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

新增十五个语义工具及中文说明和分支参数契约
复用现有API分派并支持新入口的可选创建幂等键
保留全部原工具和API并补充分派与兼容回归测试
同步工程文档及验收记录并注明本地数据库阻断的运行验证

docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md

@@ -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)：去背景模式与背景色已有合同。