完成MCP语义工具运行验收并收口文档

补充本地服务启动、MCP认证及新旧工具实际调用的验收证据记录幂等、非法字段拒绝、测试数据清理及未验证范围将已完成里程碑和实施计划归入正式技术方案并删除临时计划
2026-09-23 07:16:14 +00:00
parent e0d37edff2
commit 23b2a33257
3 changed files with 17 additions and 86 deletions
@@ -326,6 +326,23 @@ register_resource 只登记资源，并不自动创建画布图层。正常生

 验证工具目录追加与旧定义一致、全部 action 路由与字段位置、必填和错分支拒绝、可选/必填幂等头、quick-edit 与普通生成入口等价、原 owner/scope 边界、结构化结果/告警和 revision 冲突透传。运行 api-server 定向测试与本地 healthz smoke；真实账号、付费 Provider 和具体 MCP 客户端尚未验证时明确记录，不能将单元测试当作线上验收。

+### 5.4 实现与验收结果（2026-09-23）
+
+本轮实现与本地验收完成。新增 15 个语义工具与原有 29 个工具同时可见；resources/instructions 保持原样。已完成的里程碑和实施计划收口到本节。
+
+| 验证范围 | 证据与结果 |
+| --- | --- |
+| 工具与参数合同 | `cargo test --locked -p api-server external_mcp`：24 项通过，覆盖 44 个工具、31 个 action、旧定义保留、schema 展开、参数映射、错分支拒绝、必填/可选幂等和等价入口 |
+| 认证与既有 API 回归 | `cargo test --locked -p api-server external_`：155 项通过，含 MCP 内外认证、scope 拒绝、跨 owner 隔离、异步及 OpenAPI 回归 |
+| 编译与文本检查 | `cargo check --locked -p api-server`、定向 rustfmt、文档索引、编码和 diff 检查通过 |
+| 本地服务启动 | 先通过 `npm run dev:spacetime` 启动 SpacetimeDB 2.8.3 并发布隔离数据库，再通过 `npm run dev:api-server` 启动同一目标的 API 和 worker；`/v1/ping`、`/healthz`、`/readyz` 均返回 200 |
+| MCP 真实 HTTP 链路 | 未认证返回 401；使用隔离数据库中的临时测试 API Key，initialize 成功，tools/list 返回 44 个工具且包含全部 29 个旧工具，resources/list 返回原有 7 个资源 |
+| 本地数据库读写 | 新工具创建/列表/重命名/读取/删除成功；同键重复创建返回同一项目；旧工具读写与新工具互通；重复语义读取保留完整项目；ownerUserId 额外字段被拒绝且未产生写入 |
+
+运行核验使用独立测试身份和数据库，不经过真实用户登录或外部账号开通流程；测试项目已清理，临时 API Key 已撤销。最初启动未先确认数据库可用，导致连接失败；补齐数据库启动和发布后，实际 HTTP smoke 通过，无需修改业务代码。
+
+未验证：真实用户登录/发放 API Key 全流程、付费 Provider 生成、外部 MCP 客户端对 oneOf 参数的展示与使用、远端部署。本地验收不代表这些项目已通过。
+
 ## 6. 核对入口

 - [External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)：operation、参数、请求体、响应与公开字段权威。