新增外部MCP语义工具并保留原有入口

新增十五个语义工具及中文说明和分支参数契约复用现有API分派并支持新入口的可选创建幂等键保留全部原工具和API并补充分派与兼容回归测试同步工程文档及验收记录并注明本地数据库阻断的运行验证
2026-09-23 05:46:12 +00:00
parent 2ab849652e
commit ecb0dc08b8
10 changed files with 1640 additions and 55 deletions
@@ -0,0 +1,35 @@
+# 外部 MCP 语义工具并存实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [外部 MCP 语义工具并存](./【里程碑】外部MCP语义工具并存-2026-09-23.md) |
+| Status | awaiting-runtime-verification |
+| Owner | Agent |
+
+## 修改边界
+
+MCP 模块、所属工具提示词、定向测试、主规范及文档索引。REST DTO/路由/OpenAPI、resources/instructions、数据库和 CLI 保持原样。
+
+## 实现顺序
+
+1. 评审主规范和里程碑，收口剩余技术歧义。
+2. 在 MCP 内增加语义注册与 schema 构造；提示词置于所属 prompts 目录。
+3. 新工具转换为现有 operation 参数后复用分派；可选幂等只影响新入口。
+4. 验证各 action 映射、旧目录兼容、错误与权限边界；同步文档状态。
+
+## 验证命令
+
+- `cargo test --locked -p api-server external_mcp`
+- `cargo test --locked -p api-server external_api_auth`
+- `cargo test --locked -p api-server external_`（覆盖认证及相关 External API 回归）
+- 对修改的 Rust 文件运行 `rustfmt --check`。
+- `npm run dev:api-server` 与实际端口 `/healthz`；只启动/停止本任务进程。
+- `npm run check:doc-index`、`npm run check:encoding`、`git diff --check`。
+
+## 风险与回滚点
+
+schema 条件保真、幂等键可选分支和新增目录体积是重点。只增加 MCP 适配，不复制业务处理；异常时可回滚新增语义注册而不迁移数据。不得将内存 router 测试作为真实 Provider/账号验收。
+
+## 当前状态
+
+实现与自动化回归完成；155 项 External 相关测试通过。运行时启动因本地 SpacetimeDB 连接拒绝而未完成健康检查，详情见里程碑证据表。恢复可用的本地数据库配置后只需补跑 smoke 和验收，不重复扩展业务实现。
@@ -0,0 +1,51 @@
+# 外部 MCP 语义工具并存
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | awaiting-runtime-verification |
+| Date | 2026-09-23 |
+| Parent Spec | [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md) |
+
+## 目标与范围
+
+同一托管 MCP 增加主规范的 15 个语义工具及完整输入说明；复用现有 External API，实现 action 分派、参数位置转换及同源业务结果。
+
+## 非目标
+
+不删除、隐藏、重命名或改变任何旧工具/API；不新增 REST 能力，不修改 SpacetimeDB，不改 resources、instructions、CLI、独立 Skill 或发布页，不部署。
+
+## 依赖与前置条件
+
+主规范第 5 节固定工具名、schema、结果、可选幂等与新旧并存方式；开发前完成独立评审。
+
+独立评审结论：范围、兼容、失败语义与验收无阻塞项；分支 schema 与运行时均须拒绝错分支字段，可选幂等不得改变旧入口行为。
+
+## 验收标准
+
+- [x] 15 个新工具和原目录同时可见，原工具定义保持一致。
+- [x] 每个 action 只调用一个已有 operation；路径、查询、body 与幂等头正确。
+- [x] 错 action、缺字段、跨分支字段和 ownerUserId 注入在分派前拒绝。
+- [x] 必填及可选幂等键转发正确，重复语义入口不改变规范请求。
+- [x] 成功结果、告警和结构化业务错误沿用既有处理，无额外投影。
+- [x] API Key/owner/scope 边界继续在现有 router 生效。
+- [x] 定向 Rust 测试、格式、编码和文档检查通过。
+- [ ] 本地 healthz smoke 通过。
+
+## 证据要求
+
+自动化覆盖目录、分派、参数、幂等、传输和认证；运行时执行本地 API smoke。真实账号/Provider/客户端未验证项单独记录，不自动触发付费生成。
+
+## 验收证据
+
+| 条款 | 验证 | 结果与边界 |
+| --- | --- | --- |
+| 工具目录与字段合同 | `cargo test --locked -p api-server external_mcp` | 24 项通过；44 个工具可见，31 个 action 路由覆盖，原工具序列化定义保留，全部 schema 无外部引用且满足既有体积上限 |
+| 错分支、请求映射、幂等 | 同上 | 错分支/owner 注入拒绝，路径编码和查询/body 分离，可选/必填 key，两个 quick-edit 入口的规范请求一致 |
+| 权限、异步与旧 REST | `cargo test --locked -p api-server external_` | 155 项通过；含上述 24 项、MCP 内外两次认证和 scope 403、既有跨 owner 不可见、幂等、参数校验、OpenAPI 与 Skill 回归 |
+| 编译与文本 | `cargo check --locked -p api-server`、定向 rustfmt、文档索引、编码和 diff 检查 | 通过 |
+| 运行时 | `npm run dev:api-server` 与本地 healthz | 可执行文件编译成功、BgFilter worker 启动；API 启动被本地 SpacetimeDB 连接拒绝阻断，healthz 与未认证 MCP initialize 超时。本次使用隔离测试数据库名，未发布数据库或调用付费生成，启动进程已清理 |
+
+未验证：真实账号下的端到端数据库读写、付费 Provider 生成、外部 MCP 客户端对 oneOf 参数的展示与使用、远端部署。内存 router 和同源请求映射证明适配链路，不替代这些真实运行环境验收。
+
+剩余工作仅为在可用的本地数据库配置下重跑启动 smoke，并取得本里程碑验收结论；不自动扩大为开发环境修复或 resources/instructions 改造。
@@ -24,7 +24,7 @@
 外部 MCP 语义工具设计：

 1. [外部 OpenAPI 与 API Key 接入方案](../../【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)：现役托管 MCP 与 External API 合同。
-2. [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：正式工程参考，记录仅复用现有 API 的 15 个候选工具与参数设计；工具尚未实现，不作为已上线能力说明。
+2. [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：15 个语义工具与全部旧工具并存，复用现有 API 分派和 schema；多功能入口使用 action/input，结果不裁剪，可选幂等只扩展新入口。resources/instructions 仍沿用原内容，线上状态按实际部署核对。

 AI 游戏创作 / DirectProject / UI workflow：