mnote/design/07-ai/reference/7-28-resource-ai-tool-contract-v1.md

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 文件。