lix-2026
1569699fbb
- 将不直接执行的 process-reference 文档迁入各域 reference 目录 - 更新 design/README、AGENTS 和总序文档，固定 process/draft/reference/done 目录语义 - 修正活跃文档中指向旧 process 位置的参考链接 验证：git diff --check；codegraph sync .
147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
# 7-28 Resource AI Tool Contract v1
|
||
|
||
状态：reference
|
||
|
||
说明（2026-05-21）：本文冻结 mindmap / office 等 Resource AI tool 合同草案；当前不是 local-first 普通 Markdown 编辑主路径，也不是 active implementation checklist。
|
||
|
||
主线：VSCode 简化版工作区 + tiptap markdown 编辑器 + Hermes / Reasonix agent + simplemindmap / office 插件 + Wolai 主题 web 壳 + 鉴权控制面。
|
||
|
||
## 目标
|
||
|
||
`simplemindmap` 与 `office` 是 Resource Tree 对象，不是 Markdown 正文的一部分。AI 操作资源时应围绕资源文件和 resource capability 工作，Markdown 正文只保留链接、嵌入引用或资源占位。
|
||
|
||
## 工具命名
|
||
|
||
长期命名使用 `mnote.<resource>.<verb>`：
|
||
|
||
- `mnote.mindmap.fetch`
|
||
- `mnote.mindmap.markdown_summary`
|
||
- `mnote.mindmap.apply_ops`
|
||
- `mnote.mindmap.move_node`
|
||
- `mnote.mindmap.export_markdown`
|
||
- `mnote.office.fetch_summary`
|
||
- `mnote.office.propose_changes`
|
||
- `mnote.office.export_change_summary`
|
||
|
||
过渡 alias：
|
||
|
||
- `mindmap_get` -> `mnote.mindmap.fetch`
|
||
- `mindmap_get_subtree` -> `mnote.mindmap.fetch`
|
||
- `mindmap_apply_ops` -> `mnote.mindmap.apply_ops`
|
||
- `mindmap_put` 只保留 compat，不作为新 AI 写入入口。
|
||
- `onlyoffice_*` 只保留服务边界工具，不暴露为资源编辑工具。
|
||
|
||
## Mindmap 工具合同
|
||
|
||
### `mnote.mindmap.fetch`
|
||
|
||
输入：
|
||
|
||
- `workspaceId`
|
||
- `documentId`
|
||
- `mindmapId`
|
||
- `rootUri`，本地 workspace 必填
|
||
- `scope`：`tree | subtree | markdown_summary`
|
||
- `nodeId`，读取 subtree 时可选
|
||
|
||
输出：
|
||
|
||
- `objectIdentity=resource:mindmap:{documentId}:{mindmapId}`
|
||
- `resourceKind=mindmap`
|
||
- `nodes`
|
||
- `edges`
|
||
- `markdownSummary`
|
||
- `revision`
|
||
|
||
### `mnote.mindmap.apply_ops`
|
||
|
||
输入：
|
||
|
||
- `workspaceId`
|
||
- `documentId`
|
||
- `mindmapId`
|
||
- `rootUri`，本地 workspace 必填
|
||
- `expectedRevision`
|
||
- `ops`：`add_node | update_node | delete_node | move_node | set_note | set_link`
|
||
|
||
约束：
|
||
|
||
- 必须校验 `allowedResourceIds` 包含 `mindmapId` 或 `resource:mindmap:{documentId}:{mindmapId}`。
|
||
- shared read scope 禁止调用。
|
||
- 写入后 changed-files 审计必须记录 mindmap 原生文件或 cloud resource mutation。
|
||
|
||
## Office 工具合同
|
||
|
||
Office 真实编辑优先交给 OnlyOffice / officecli；AI 工具不直接伪造二进制写入。
|
||
|
||
### `mnote.office.fetch_summary`
|
||
|
||
输入：
|
||
|
||
- `workspaceId`
|
||
- `documentId`
|
||
- `assetId`
|
||
- `rootUri`，本地 workspace 必填
|
||
- `extractMode`：`text | outline | metadata`
|
||
|
||
输出：
|
||
|
||
- `objectIdentity=resource:onlyoffice:{documentId}:{assetId}`
|
||
- `resourceKind=only_office`
|
||
- `fileName`
|
||
- `mimeType`
|
||
- `textSummary`
|
||
- `outline`
|
||
- `revision`
|
||
|
||
### `mnote.office.propose_changes`
|
||
|
||
输入：
|
||
|
||
- `workspaceId`
|
||
- `documentId`
|
||
- `assetId`
|
||
- `rootUri`，本地 workspace 必填
|
||
- `instructions`
|
||
- `basisRevision`
|
||
|
||
输出：
|
||
|
||
- `changeSummary`
|
||
- `suggestedEdits`
|
||
- `requiresOnlyOffice=true` 或 `requiresOfficeCli=true`
|
||
|
||
约束：
|
||
|
||
- 默认只生成建议，不直接覆盖 Office 二进制。
|
||
- 真实写入必须由 OnlyOffice callback / forcesave 或 officecli 写入链完成。
|
||
- 写入后 changed-files 审计必须记录 office 文件变更。
|
||
|
||
## 权限模型
|
||
|
||
AI resource tools 必须同时满足：
|
||
|
||
- 用户有当前 root 的 local access 或 canonical share grant。
|
||
- 当前 `AiAccessScope.permissionLevel` 允许对应读写。
|
||
- `allowedResourceIds` 包含目标资源 ID 或目标 object identity。
|
||
- 工具运行时只接收目标资源文件路径，不开放整个 workspace 之外的路径。
|
||
|
||
## 前端上下文
|
||
|
||
前端只传：
|
||
|
||
- 当前文件 / 页面引用
|
||
- `objectIdentity`
|
||
- 当前 selection，可选
|
||
|
||
前端不构造完整资源内容上下文。资源内容由 agent 通过工具读取，或由 agent 内置文件工具在授权目录内读取。
|
||
|
||
## 验证清单
|
||
|
||
- `mnote.mindmap.fetch` 可读取结构和 markdown summary。
|
||
- `mnote.mindmap.apply_ops` 在 shared read 下拒写。
|
||
- `mnote.office.fetch_summary` 可读取摘要且不写文件。
|
||
- `mnote.office.propose_changes` 只输出建议。
|
||
- `allowedResourceIds` 不包含目标资源时，所有资源工具拒绝访问。
|
||
- changed-files 审计包含 `.mindmap.json` / Office 文件。
|