推进本地优先迁移与资源闭环

- 补齐共享只读页面 AI 浏览器 smoke，并回填当前优先级 checklist 的 P4/P5/P6 证据。 - 为 OnlyOffice 资源增加 /office/{documentId}/{assetId} 对象壳，固定 resource identity 与侧边栏打开路径。 - 扩展 Convex 导出脚本，支持 dry-run、manifest、冲突报告、索引刷新与 rollback，并补充 smoke。 - 补充资源 AI 工具合同与 Convex 导出 Web 入口设计。
2026-05-19 11:39:04 +08:00
parent a1b28a8e38
commit 94be1c927b
11 changed files with 1097 additions and 73 deletions
@@ -0,0 +1,144 @@
+# 7-28 Resource AI Tool Contract v1
+
+状态：process
+
+主线：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 文件。