GenarrativeAI/Genarrative
10
0
Fork 0
Code Issues 22 Pull Requests 6 Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
新增十五个语义工具及中文说明和分支参数契约
复用现有API分派并支持新入口的可选创建幂等键
保留全部原工具和API并补充分派与兼容回归测试
同步工程文档及验收记录并注明本地数据库阻断的运行验证
This commit is contained in:
孔令弘
2026-09-23 05:46:12 +00:00
parent 2ab849652e
commit ecb0dc08b8
10 changed files with 1640 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+1 -1
View File
@@ -21,7 +21,7 @@
- [当前产品与工程约束](./【项目基线】当前产品与工程约束-2026-05-15.md)：现役入口、账号钱包、UI 和后端分层。
- [平台入口与玩法链路](./【玩法创作】平台入口与玩法链路-2026-05-15.md)：只描述现役平台壳与图片画布编辑器链路。
- [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
- [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：仅复用现有 External API 的 15 个候选工具、操作映射、说明和参数边界；正式工程设计参考，语义工具尚未实现。
- [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：15 个新增语义工具与全部原工具并存，复用现有 External API；包含工具说明、action、参数、幂等和兼容合同。
- [External v1 OpenAPI](./openapi/genarrative-external-v1.openapi.json)：公开 HTTP 契约唯一机器可读来源。
## AI 游戏创作与 Agent Runtime
docs/project-memory/plans/【实施计划】外部MCP语义工具并存-2026-09-23.md
+35
View File
@@ -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 和验收，不重复扩展业务实现。
docs/project-memory/plans/【里程碑】外部MCP语义工具并存-2026-09-23.md
+51
View File
@@ -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 改造。
docs/project-memory/shared-memory/document-map.md
+1 -1
View File
@@ -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：
docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md
+45 -15
View File
@@ -2,11 +2,11 @@
更新时间：`2026-09-23`
> 文档状态：`current`（正式工程设计参考；语义工具尚未实现，不能据此认定当前服务已提供这些入口）。
> 文档状态：`current`（工程实现合同；仓库已增加语义工具，线上可用性以实际部署版本为准）。
>
> 父规范：[外部 OpenAPI 与 API Key 接入方案](../【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)。
>
> 当前字段契约：[External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)。本文记录工具划分、说明和参数设计方向；最终英文工具名、完整 JSON Schema、结果投影及兼容发布方式仍需在实现前明确。
> 当前字段契约：[External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)。本文记录工具划分、说明和参数合同；英文工具名、schema 构造、结果与兼容方式见第 5 节。
## 1. 目标与范围
@@ -14,13 +14,13 @@
工具可以存在自然的功能交集：例如参考图快速变体同时属于生成图片和修改图片，读取画布同时服务于项目查找和布局编辑。不以工具数量或 API 唯一归属为目标，不把不相关任务硬合成一个工具。
本文只讨论工具说明、操作选择、关键参数和业务边界。开发者发布页、文档存储与独立发布、CLI 改造不属于本轮范围。本文不改变现有 REST 路由、DTO 和运行行为，也不直接替换现役 MCP 契约。进入工程实现时，按仓库规范驱动流程补齐对应里程碑规范、实现计划和验收条件。
本文约定工具说明、操作选择、参数和业务边界。开发者发布页、文档存储与独立发布、CLI 改造不属于本轮范围。现有 REST 路由、DTO 和运行行为保持不变，新语义工具与全部原有工具并存。
## 2. 当前实现与目标调用链
当前 [external_mcp.rs](../../server-rs/crates/api-server/src/external_mcp.rs) 从 OpenAPI 自动建立原子工具：工具名由 `operationId` 转为 snake_case；description 优先读取 operation 的 `description`，缺省读取 `summary`，附加 HTTP 方法和路径；参数 schema 来自 OpenAPI。服务级 instructions 提供通用工作流，resources 提供详细说明。
新工具拟继续部署在同一个 API server 内，复用现有分派和 External REST router：
新工具继续部署在同一个 API server 内，复用现有分派和 External REST router：
```text
Agent 调用语义工具
@@ -69,7 +69,7 @@ Agent 调用语义工具
### 3.3 共用行为
- 九类生成 POST 继续要求稳定幂等键，并返回 `202 + operationId`；工具不能把受理当成生成完成。
- 项目创建、项目资源登记、文件夹创建的 REST API 支持可选幂等键，新工具设计应保留该能力。当前 MCP bridge 主要按 required header 推导幂等参数，实现时须明确接入这些可选 header；素材记录创建 API 不在该可选幂等合同中。
- 项目创建、项目资源登记、文件夹创建的 REST API 支持可选幂等键，新语义入口提供并转发这些可选 header；原工具继续保持仅按 required header 推导幂等参数的行为。素材记录创建 API 不在该可选幂等合同中。
- 相同 API 能力出现在不同语义入口时，参数约束、底层请求和结果语义保持一致。重试或切换入口恢复同一逻辑请求时，保留原 API 操作、规范请求和幂等键，不因换工具名创建新任务。
- `projectId`、`assetFolderId`、`assetLabel`、`canvasCompletion` 等目标参数只在对应 API 支持时提供。UI 素材提取使用 `spritesheetLabel`；各生成族不共享未经核对的字段全集。
- owner 由 API Key 确定，不让 Agent 指定身份，不把 API Key 放进工具参数。
@@ -78,7 +78,7 @@ Agent 调用语义工具
## 4. 工具说明与操作映射
以下共 15 个候选工具。删除从项目管理、素材库整理中移出，统一放入 XV。action 名称是本设计的候选值，不表示已经上线。
以下共 15 个新增工具。删除从项目管理、素材库整理中移出，统一放入 XV。本节说明仓库实现合同，不表示线上已部署。
### I. 查找画布项目
@@ -111,11 +111,11 @@ Agent 调用语义工具
| --- | --- | --- |
| `list_library` | 无 | `getEditorAssetLibrary` |
| `get_project_resources` | 必填 `projectId` | `getEditorProject` |
| `get_download_url` | `objectKey`；可选 `expireSeconds` | `getExternalAssetReadUrl` |
| `get_download_url` | `objectKey` 或兼容的 `legacyPublicPath`；可选 `expireSeconds` | `getExternalAssetReadUrl` |
项目资源查询复用项目详情，不新增资源查询 API。建议仅投影其资源部分，具体输出结构在实现前固定，并保留资源身份字段。
项目资源查询复用项目详情，不新增资源查询 API。本次返回完整项目详情，资源位于其中的 resources；保持与项目读取相同的结构，不新增裁剪投影。
读取素材记录、获取文件地址与查看媒体内容是不同操作。工具不提供本地下载、关键词检索或相似素材搜索。临时签名 URL 用于访问媒体，不作为持久化生成引用。REST 还支持 `legacyPublicPath`；语义入口优先使用稳定 objectKey，是否保留该兼容查询字段在完整 schema 评审时明确，不改 REST 契约。
读取素材记录、获取文件地址与查看媒体内容是不同操作。工具不提供本地下载、关键词检索或相似素材搜索。临时签名 URL 用于访问媒体，不作为持久化生成引用。语义入口保留 REST 的 `legacyPublicPath` 可选查询字段；优先使用稳定 objectKey，至少提供一种来源，由现有 API 校验来源，不改 REST 契约。
### IV. 办理素材上传
@@ -289,20 +289,50 @@ register_resource 只登记资源，并不自动创建画布图层。正常生
不增加批量、按名称或模糊匹配删除，不用一个可伪造的 confirm 参数替代真实用户授权和后端鉴权。
## 5. 实现前仍需明确的事项
## 5. 实现合同与验收
1. 最终英文工具名与完整 action schema；条件参数如何在目标 MCP 客户端中准确展示和校验。
2. III 的项目资源投影结构及 legacyPublicPath 保留策略；各工具结果保持原样或裁剪时的精确字段。
3. 新旧工具替换、并存或迁移的具体选择。本文不预设双套目录、默认开关或 api_* 逃生入口。
4. 更新服务级 instructions、工具说明与相关使用资料，确保与实际广告的工具一致；文档存储和发布机制另行讨论。
### 5.1 工具名与兼容
实现验收围绕实际风险：操作路由和参数位置正确、缺失或错分支参数不触发副作用、原有 owner/scope 校验有效、同一逻辑生成幂等恢复、图集降级告警保留、画布 revision 冲突保留，以及重复语义入口调用同一底层能力的结果一致性。本文完成不代表这些运行时验证已经通过。
| 编号 | 工具名 |
| --- | --- |
| I | `find_canvas_projects` |
| II | `manage_canvas_projects` |
| III | `find_assets` |
| IV | `prepare_asset_upload` |
| V | `generate_image` |
| VI | `modify_image` |
| VII | `generate_icon_spritesheet` |
| VIII | `extract_ui_assets` |
| IX | `generate_character_animation` |
| X | `generate_video` |
| XI | `generate_audio` |
| XII | `edit_canvas` |
| XIII | `organize_asset_library` |
| XIV | `check_generation` |
| XV | `delete_resources` |
现有 MCP 工具和 REST API 全部保留；旧工具名称、schema、注解、调用行为和可见性不变。新工具直接追加进同一个 tools/list，不加开关、不改旧工具前缀、不设隐藏目录。更新工具说明和参数属于本轮；resources、instructions、独立 Skill、CLI、发布页与部署不属于本轮。
### 5.2 参数与结果
- 字段 schema 从对应现有 OpenAPI operation 构造，展开本地引用并保留嵌套类型、枚举、条件和字段说明。路径、查询与 body 字段平铺到单功能工具顶层或多功能工具的 input；不另写一份业务字段全集。
- 多功能工具以顶层 object 加 oneOf 表达互斥 action，每个分支含 action 常量和完整 input schema。input 必填，无业务参数时传 `{}`。idempotencyKey 仅放在工具顶层：九类生成必填，项目创建、资源登记、文件夹创建可选，其它 action 不接受。
- MCP 适配层在分派前校验 action、信封字段、所选分支允许的字段、必填参数及直接字段的类型/枚举/常量；嵌套字段值和业务组合继续由现有 REST DTO/校验处理，不创建第二套业务验证器。协议 schema 与分派校验共同限制错分支参数；未知顶层或 input 字段不能被静默丢弃。
- variation 不暴露 kind，固定注入 `quick-edit`；对象确认不暴露或接受 ownerUserId。其余公开字段全部保留。稳定 key、原 API 与规范请求保持一致，重复语义入口不新增幂等命名空间。
- 项目列表固定 summary。get_project_resources 返回完整项目响应，不裁剪；下载地址保留 objectKey、legacyPublicPath 与 expireSeconds。所有结果复用现有成功解包与结构化错误处理，不裁剪告警、revision 冲突或异步结果。
- 读取工具标记 readOnly；含删除、覆盖或移动已有状态的工具标记 destructive；生成类说明付费及异步语义，可能替换已有图层的生成工具也按潜在破坏性标记。openWorld 仅用于会访问外部服务的能力，不作为付费标志。注解不替代用户授权或后端校验。
### 5.3 验收
验证工具目录追加与旧定义一致、全部 action 路由与字段位置、必填和错分支拒绝、可选/必填幂等头、quick-edit 与普通生成入口等价、原 owner/scope 边界、结构化结果/告警和 revision 冲突透传。运行 api-server 定向测试与本地 healthz smoke；真实账号、付费 Provider 和具体 MCP 客户端尚未验证时明确记录，不能将单元测试当作线上验收。
## 6. 核对入口
- [External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)：operation、参数、请求体、响应与公开字段权威。
- [External API 路由](../../server-rs/crates/api-server/src/modules/external_api.rs)：实际路由挂载。
- [MCP 实现](../../server-rs/crates/api-server/src/external_mcp.rs)：工具生成、schema、资源和进程内分派。
- [语义工具适配](../../server-rs/crates/api-server/src/external_mcp/semantic.rs)：新增工具、action、同源 schema 与参数映射。
- [工具说明](../../server-rs/crates/api-server/prompts/external_mcp/semantic_tools.json)：新增工具的中文用途、操作和结果说明。
- [External 编辑器接口](../../server-rs/crates/api-server/src/external_editor_api.rs)：鉴权、请求处理与生成受理。
- [AGC 抠图模式与背景色透传](./【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)：去背景模式与背景色已有合同。
docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
+1 -1
View File
@@ -78,7 +78,7 @@ provider 原图已保存但透明背景处理最终失败时，worker 保留原
## 托管远程 MCP
后续语义工具的设计参考见 [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)。该文档仅规划复用现有 External API 的新工具说明、操作划分和参数；尚未实现，不替代下述现役 MCP 契约。
新增语义工具的合同见 [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)。15 个语义工具与原有 OpenAPI 自动映射工具同时可见；旧工具名称、schema、注解和行为保持不变，不删除、隐藏或加前缀。新工具按 action 选择一个既有 operation，平铺业务字段后复用下述 REST 分派；创建项目、项目资源、素材文件夹的新入口额外保留对应 API 的可选幂等键。所有结果沿用相同解包与错误处理，不裁剪告警或项目快照。resources 与 instructions 的内容更新另行处理，REST 契约不变。
`/api/external/v1/mcp` 是 Genarrative 托管的远程端点，Agent 只需配置 URL 和现有 API Key，不安装本地 MCP server。首版兼容 MCP `2025-11-25` initialize 生命周期，使用 JSON-RPC 2.0 和 Streamable HTTP，支持 `initialize`、`notifications/initialized`、`ping`、`tools/list`、`tools/call`、`resources/list`、`resources/read`。服务端使用无协议 session 的 JSON direct 模式，不依赖 sticky session，也不把 `Mcp-Session-Id` 作为业务身份。