feat(mcp): 验证有界工具目录并使陈旧契约失效

2026-09-09 01:00:02 +08:00
parent 7c7a637e38
commit 6373829243
6 changed files with 578 additions and 21 deletions
@@ -495,3 +495,15 @@ Core 的独立数据目录目前不等于已授权 Vault。Python 旧笔记写
 - 协议依据 [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)、[MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)、[MCP cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation)。此组件不是完整安装实例运行时，安装身份/在线信任/工具 schema 与授权路由、原生实例注册，以及全部沙箱资源策略仍须完成，第三方执行能力保持禁用。
 - 新增长时原生验收已显式执行：实际 tools/call 挂起 60.0015261 秒后得到 EXTENSION_TOOL_DEADLINE_EXCEEDED，服务及后代最终清空；Host 此后保存笔记并重新打开 Workspace 校验正文成功。该验收完整夹具总耗时 75.64 秒，包含握手/其他原生场景。日志 `.build/extension-mcp-sixty-seconds.log`。
 - 常规扩展回归为 60 passed / 5 ignored，其中三个 Job 辅助入口由父测试驱动，新 MCP 长时项已另行显式通过，旧底层 60 秒项本轮未重跑。desktop 全目标 Clippy -D warnings 通过。日志 `.build/extension-mcp-tests.log`、`.build/extension-mcp-clippy.log`。这些是工具期限及协议链路证据，仍不代替 C-04 中内存/scratch/CPU/进程及完整 Host 验收。
+
+
+## 增量：MCP 工具目录、离线契约与变更失效
+
+- 新增 extension_mcp_tools::Catalog / Tool；最多 100 页、500 个工具、4 MiB 目录响应总量，检测重复工具名与循环游标，只有完整目录验证成功才发布。名称按 MCP 推荐的 ASCII 字母（含大小写）、数字、点、下划线与连字符处理，大小写敏感；不再把原开发 Python 的小写限定直接套到原生 MCP。
+- 每个工具输入/输出 schema 以 Draft 2020-12 离线编译，使用线性 regex 模式，限制单 schema 64 KiB、树深 24、节点数 4096。与 Host 配置契约的有界执行策略一致，本阶段拒绝所有外部及本地/递归引用、未知 schema 方言和需要任务增强执行的工具，不进行网络或文件解析。该支持范围需在后续安装兼容性界面明确呈现。
+- Session.refresh_tools 先撤下旧目录，再在分页请求的总体 20 秒等待预算内构建新目录。未发现目录、未知工具或不满足输入 schema 的参数均在发送前拒绝；参数还限制为 256 KiB 的有界对象。远端 annotations、描述和 metadata 不产生权限，也未被转换为可免确认的工具属性。
+- 成功工具结果按已选中的输出 schema 检查 structuredContent，限制整体 256 KiB、最多 128 个内容项，并校验文本、图片/音频 base64、资源链接和嵌入资源的基础结构。isError=true 允许不带成功结构化结果。资源 URI 仅作为数据校验，不会自动抓取或打开；具体媒体渲染与资源获取仍需走各自授权路径。
+- 接收 tools/list_changed 后立即清除可调用目录；下一调用前也处理已经排队的空闲通知，避免继续使用已知失效的目录。目录建立期间发生变化不会发布混合版本。进行中的调用保留选中契约的 Arc，用原契约校验结果，新的调用必须重新发现目录；正式实例后台循环仍需持续处理空闲事件并与 UI/Agent 的目录版本同步。
+- 单元测试覆盖分页、重复、循环、总量/页数限制，必填项/类型/额外参数、结构化结果、无效 base64、所有引用类型、未知方言/不支持正则/任务要求与过深输入。真实 AppContainer 测试新增两页目录、发现前/未知名/无效参数拒绝、错误 structuredContent、调用中及空闲时工具变更；全部经实际原生 Session/Pump 运行。
+- 62 项扩展回归通过，5 项 ignored 为三个父测试驱动 Job 辅助入口及两个需显式执行的长时验收，本轮未重跑长时项；上一轮实际 MCP 60 秒验收仍为其当时提交的证据。desktop 全目标 Clippy -D warnings 通过。日志 `.build/extension-mcp-catalog-tests.log`、`.build/extension-mcp-catalog-clippy.log`。协议依据 [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)。
+- 工具发现和校验不等于用户批准执行。生产入口仍需完成实际安装实例注册、来源/活动版本/在线信任与工具目录摘要绑定、用户调用授权及 Core 路由；还需完成全部沙箱资源/并发攻击验证和其他生产化验收，第三方执行能力保持禁用。