@@ -0,0 +1,309 @@
# 外部 MCP 语义工具说明与参数设计
更新时间：`2026-09-23`
> 文档状态：`current`（正式工程设计参考；语义工具尚未实现，不能据此认定当前服务已提供这些入口）。
>
> 父规范：[外部 OpenAPI 与 API Key 接入方案](../【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)。
>
> 当前字段契约：[External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)。本文记录工具划分、说明和参数设计方向；最终英文工具名、完整 JSON Schema、结果投影及兼容发布方式仍需在实现前明确。
## 1. 目标与范围
在现有 API server 的托管 MCP 层增加按用户任务组织的工具。仅使用现有 External v1 已开放的能力，不直接接入尚未公开的画布功能。
工具可以存在自然的功能交集：例如参考图快速变体同时属于生成图片和修改图片，读取画布同时服务于项目查找和布局编辑。不以工具数量或 API 唯一归属为目标，不把不相关任务硬合成一个工具。
本文只讨论工具说明、操作选择、关键参数和业务边界。开发者发布页、文档存储与独立发布、CLI 改造不属于本轮范围。本文不改变现有 REST 路由、DTO 和运行行为，也不直接替换现役 MCP 契约。进入工程实现时，按仓库规范驱动流程补齐对应里程碑规范、实现计划和验收条件。
## 2. 当前实现与目标调用链
当前 [external_mcp.rs ](../../server-rs/crates/api-server/src/external_mcp.rs ) 从 OpenAPI 自动建立原子工具：工具名由 `operationId` 转为 snake_case； `description` ，缺省读取 `summary` ，附加 HTTP 方法和路径；参数 schema 来自 OpenAPI。服务级 instructions 提供通用工作流，resources 提供详细说明。
新工具拟继续部署在同一个 API server 内，复用现有分派和 External REST router：
``` text
Agent 调用语义工具
→ MCP 层选择对应 operation，并转换参数位置
→ 进程内调用现有 External REST router
→ 复用鉴权、scope、owner、校验、幂等、计费和业务处理
→ MCP 返回业务结果或结构化错误
```
多功能工具的一次调用只选择一个操作。工具聚合不意味着批量执行、自动连续写入或新增跨操作事务。文件上传仍由调用方完成二进制传输。
## 3. 说明与参数的共同设计
### 3.1 工具说明
每份说明包含：
1. 用途：用户希望完成什么任务时选择本工具。
2. 操作选择：多功能工具列出各 action 的用途，解释容易混淆的选择。
3. 结果：立即返回业务结果，还是返回异步任务 ID；有哪些重要的降级或结果边界。
字段格式、枚举、必填关系放入参数 schema 和字段说明，避免把全部接口校验细节堆进工具 description。付费、删除等重要影响应明确表达，但 description 和风险注解不替代后端权限校验；宿主负责结合用户已给出的授权作调用决策。
### 3.2 多功能与单功能工具
多功能工具采用 `action + input` ，
示意调用（示例 ID 仅为说明）：
``` json
{
"action" : "edit" ,
"input" : {
"sourceReferenceId" : "<resourceId-or-assetId>" ,
"prompt" : "把衣服改成红色" ,
"projectId" : "<projectId>"
} ,
"idempotencyKey" : "<stable-logical-request-key>"
}
```
单功能工具直接声明业务字段，不强行添加 action 或 input 包装。`kind` 、`sliceMode` 、视频 `mode` 等原有业务选择保留原名，它们与工具级 action 职责不同。
工具参数中的 ID 由 MCP 层放入 REST 路径或查询，业务输入放入请求体，`idempotencyKey` 转为 `Idempotency-Key` header。具体参数保留现有命名、类型和条件；下表列的是关键字段，并非完整 schema 或排他白名单。未逐项列出的可选字段按对应 OpenAPI operation 核对，不把站内 DTO 的内部字段顺带开放。
### 3.3 共用行为
- 九类生成 POST 继续要求稳定幂等键，并返回 `202 + operationId` ；工具不能把受理当成生成完成。
- 项目创建、项目资源登记、文件夹创建的 REST API 支持可选幂等键，新工具设计应保留该能力。当前 MCP bridge 主要按 required header 推导幂等参数，实现时须明确接入这些可选 header；素材记录创建 API 不在该可选幂等合同中。
- 相同 API 能力出现在不同语义入口时，参数约束、底层请求和结果语义保持一致。重试或切换入口恢复同一逻辑请求时，保留原 API 操作、规范请求和幂等键，不因换工具名创建新任务。
- `projectId` 、`assetFolderId` 、`assetLabel` 、`canvasCompletion` 等目标参数只在对应 API 支持时提供。UI 素材提取使用 `spritesheetLabel` ；各生成族不共享未经核对的字段全集。
- owner 由 API Key 确定，不让 Agent 指定身份，不把 API Key 放进工具参数。
- 业务结果继续使用结构化返回；业务失败沿用安全错误语义，不把失败包装成成功。生成成功、素材登记、画布落位、切片成功分别按实际结果判断。
- 读取、写入、付费与删除应在说明和注解中准确表达。注解作用于整个工具，因此将删除独立成工具；`openWorldHint` 不等同于付费标记。
## 4. 工具说明与操作映射
以下共 15 个候选工具。删除从项目管理、素材库整理中移出，统一放入 XV。action 名称是本设计的候选值，不表示已经上线。
### I. 查找画布项目
**说明： ** 查找已有画布项目，或读取指定项目的完整内容。先通过列表或最近项目确定目标，再读取详情获取画布、图层和资源。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `list` | 无 | `listEditorProjects` ，固定 `view=summary` |
| `recent` | 无 | `loadRecentEditorProject` |
| `get` | 必填 `projectId` | `getEditorProject` |
列表使用既有摘要视图，不能退回全量项目快照。当前接口没有分页、limit 或名称搜索参数，工具不虚构这些字段。名称匹配基于读取结果；有歧义时向用户明确候选，不静默创建替代项目。
### II. 管理画布项目
**说明： ** 创建新的画布项目，或修改已有项目的名称。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `create` | 可选 `title` ；可选幂等键 | `createEditorProject` |
| `rename` | 必填 `projectId` 、`title` | `renameEditorProject` |
一次创建仅创建项目，不默认追加创建同名素材文件夹。删除使用 XV。
### III. 查找与读取素材
**说明： ** 查看账号素材库或指定项目中的资源，并为已有素材获取临时下载地址。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `list_library` | 无 | `getEditorAssetLibrary` |
| `get_project_resources` | 必填 `projectId` | `getEditorProject` |
| `get_download_url` | `objectKey` ；可选 `expireSeconds` | `getExternalAssetReadUrl` |
项目资源查询复用项目详情，不新增资源查询 API。建议仅投影其资源部分，具体输出结构在实现前固定，并保留资源身份字段。
读取素材记录、获取文件地址与查看媒体内容是不同操作。工具不提供本地下载、关键词检索或相似素材搜索。临时签名 URL 用于访问媒体，不作为持久化生成引用。REST 还支持 `legacyPublicPath` ；语义入口优先使用稳定 objectKey，是否保留该兼容查询字段在完整 schema 评审时明确，不改 REST 契约。
### IV. 办理素材上传
**说明： ** 获取文件直传凭证，并在调用方完成上传后确认素材对象。文件传输由调用方执行。
| action | 必填参数 | 常用可选参数 | 现有 operationId |
| --- | --- | --- | --- |
| `create_upload_ticket` | `legacyPrefix` 、`fileName` | `contentType` 、`pathSegments` 、`maxSizeBytes` 等 | `createExternalDirectUploadTicket` |
| `confirm_upload` | `objectKey` 、`assetKind` | `bucket` 、`contentType` 、`contentLength` 、`contentHash` 等 | `confirmExternalAssetObject` |
流程为“申请凭证 → 调用方按返回的 OSS 表单直传参数上传 → 确认对象”。不把上传协议笼统写成固定 PUT。工具不接受本地路径或 base64，不代上传。对象确认后若需要项目资源或素材库记录，再调用相应登记操作；确认对象不等于完成这些登记。
`ownerUserId` 由后端账号身份决定，不作为 Agent 可选参数。
### V. 生成图片
**说明： ** 根据文字和可选参考图生成图片，支持普通图片、视觉规范、角色、UI 设计、宣发素材和快速参考变体。提交后通过任务 ID 查询结果。
映射 `generateExternalEditorImage` ，无需 action。
| 参数 | 约束与用途 |
| --- | --- |
| `prompt` | 必填，生成内容描述 |
| `kind` | 可选；省略表示普通图，其他用途为 `spec` 、`character` 、`quick-edit` 、`ui-design` 、`publication-material` |
| `referenceImageSrcs` | 可选参考图；具体引用和组合约束沿用 API |
| `model` 、`aspectRatio` 、`imageSize` 、`size` | 可选输出配置，枚举及组合以当前 schema 为准 |
| `style` | 可选风格；适用范围沿用对应 kind 的现有处理 |
| `screenColor` | 可选纯色抠像背景色，见下文 |
| 目标与落位字段 | 按当前接口支持提供项目、素材库和画布目标 |
**背景色已经通过 API 开放。 ** screenColor 可传画布支持的颜色 hex，例如 `#CFEFFF` ；传 `"auto"` 、null 或省略，由服务端自动选择。它描述生成及后续抠图流程的纯色背景，不保证最终产物保留该底色；不能据此承诺“最终图片指定底色”或通用背景替换能力。
不额外引入与 kind 重复的 action；不添加未开放的 `scene` 生成入口。
### VI. 修改图片
**说明： ** 对已有图片做定向修改、生成参考变体或移除背景。定向修改使用已登记资源；快速变体通过参考图生成新版本。提交后通过任务 ID 查询结果。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `edit` | 必填 `sourceReferenceId` 、`prompt` ；其余为编辑 API 的可选字段 | `editExternalEditorImage` |
| `variation` | 必填 `prompt` ；参考输入使用 `referenceImageSrcs` ；其他字段复用图片生成 | `generateExternalEditorImage` ，适配层固定 `kind=quick-edit` |
| `remove_background` | 必填 `sourceImageSrc` ；可选 `backgroundMode` 、条件允许的 `screenColor` 及目标字段 | `removeExternalEditorImageBackground` |
来源参数保留真实差异：
- edit 的 sourceReferenceId 只接受当前账号已登记的项目资源 ID 或素材 ID，不能用 objectKey 或 URL 代替。
- 去背景的 sourceImageSrc 支持当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID，只处理允许的静态图片。
- 变体的参考来源沿用生成 API；不新造含糊的统一 source 字段。其参考输入必填性、有效引用等条件沿用 quick-edit 的现有契约，不从图片生成 schema 只有 prompt 必填就推断所有用途无需前置条件。
去背景 backgroundMode 省略或 null 时默认为 `complex` 。complex 做语义分割；`flat` 用于纯色背景。screenColor 仅在 flat 下可传非 null 值，支持 `auto` 、`#RRGGBB` ，省略或 null 自动检测；complex 下传非 null screenColor 会被拒绝。不能直接照搬图片生成的全部背景色组合规则。
需要原位替换时，编辑和去背景沿用各自 API 的 `projectId + targetLayerId` 来源绑定要求；不能用目标图层 ID 绕过账号归属与对象一致性校验。变体入口不额外承诺原位替换。
variation 与 V 的 kind=quick-edit 是合理交集，复用同一输入定义、底层请求和结果语义，不让调用方重复提供固定 kind。
### VII. 生成图标图集
**说明： ** 根据已登记的参考规范和图标清单生成图集，并按指定方式尝试拆分独立图标。
映射 `generateExternalEditorIconSpritesheet` ，无需 action。
- 必填：`referenceId` 、`iconDescriptions` 、`sliceMode` 。
- referenceId 为当前账号已登记为 `icon-spec` 的项目资源或素材 ID，不接受 objectKey 或 URL 代替。
- `sliceMode=grid` ：提供需求对应的 `gridX` 、`gridY` ，各为 1–
- `sliceMode=connected-components` ：可用 `sliceCount` （1–256）约束张数，不提供 gridX/gridY。
- 可选：`referenceImageSrcs` 、`screenColor` 、`style` 、模型、比例、尺寸及目标字段。
sliceMode 没有默认值。主规范引用使用 referenceId，不用辅助 referenceImageSrcs 替代。此工具包含生成步骤，不是任意已有图片的通用裁切工具。切片未完成时可能仍有完整图集，结果必须保留 sliceWarning。
### VIII. 提取 UI 素材
**说明： ** 以已有 UI 设计图为参考，生成组件素材图集并尝试拆分，供后续界面制作使用。
映射 `extractExternalEditorUiDesignAssets` ，无需 action。
- 必填：`sourceImageSrc` 、`aspectRatio` 、`imageSize` 。
- 可选：`model` 、`referenceImageSrcs` 、`screenColor` 、`spritesheetLabel` 和对应目标字段。
- 结果命名沿用 spritesheetLabel，不强行改成其他生成接口的 assetLabel。
接口包含生成过程，不保证把原图中的组件逐像素原样裁出。与 VII 的区别是：VII 以规范和明确图标清单生成，VIII 以已有 UI 设计图提取组件语义。两者都须分别判断图集与切片结果。
### IX. 生成角色动画
**说明： ** 根据角色源图和动作描述，生成角色动画预览与帧序列。
映射 `generateExternalEditorCharacterAnimation` ，无需 action。
- 来源必填：`sourceLayerId` 、`sourceImageSrc` 、`sourceWidth` 、`sourceHeight` 。
- 动作必填：`promptText` 。
- 输出必填：`resolution` 、`ratio` 、`frameCount` 、`durationSeconds` 、`model` 。
- 可选：`screenColor` 、`sourceResourceId` 、目标与落位字段等。
来源与尺寸先从真实资源中取得，不为简化调用伪造图层 ID 或源图尺寸。此工具不提供已有动画文件编辑。正式动画结果按现有帧序列合同消费，不重复用第一帧手工登记一份动画。
### X. 生成视频
**说明： ** 根据文字和模型支持的参考图片、视频或音频生成视频片段。
映射 `generateExternalEditorVideo` ，无需 action。
- 必填：`prompt` 、`model` 、`aspectRatio` 、`durationSeconds` 、`resolution` 、`mode` 、`sound` 。
- 可选参考：`referenceImageSrcs` 、`referenceVideoSrcs` 、`referenceAudioSrcs` 。
- 其他可选项：当前 API 支持的 `webSearchEnabled` 、目标与落位字段等。
保留 mode 作为视频业务模式，与工具级 action 无关。参考媒体、时长、分辨率、声音和其他选项的组合以所选模型的当前契约为准，不暗示每个模型支持所有组合。
### XI. 生成音频
**说明： ** 生成音效或背景音乐。短声音、环境声和交互反馈选择音效；配乐选择背景音乐。
| action | 必填参数 | 常用可选参数 | 现有 operationId |
| --- | --- | --- | --- |
| `sound_effect` | `prompt` | `duration` 、`loop` 、`model` 、目标字段 | `generateExternalEditorSoundEffect` |
| `background_music` | `gptDescriptionPrompt` 、`makeInstrumental` | 目标与落位字段 | `generateExternalEditorBackgroundMusic` |
当前音效 duration 是可选字段，省略或 null 表示自动，手动时长范围为 0.5–30 秒。不沿用“必须填写时长”的过期说法。两个分支保留各自提示词字段，不另外实现一套提示词翻译协议。两者均异步受理。
### XII. 编辑画布
**说明： ** 读取画布、保存完整布局，或登记供图层引用的项目资源。保存布局需要基于最新画布版本。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `get` | 必填 `projectId` | `getEditorProject` |
| `save_layout` | 必填 `projectId` 、`viewport` 、`layers` 、`expectedRevision` | `saveEditorProjectCanvas` |
| `register_resource` | 必填 `projectId` 、`imageSrc` 、`width` 、`height` 、`sourceType` ；支持可选幂等键 | `createEditorProjectResource` |
save_layout 保存完整默认画布布局，不提供只传一个图层的局部 patch 语义；expectedRevision 来自最新读取，版本冲突按现有 API 处理。
register_resource 只登记资源，并不自动创建画布图层。正常生成结果落画布优先使用生成接口的 canvasCompletion。可选 objectKey、assetObjectId、assetKind、帧序列等字段按资源登记 schema 提供，不从临时 UI 状态推导正式来源。
### XIII. 整理素材库
**说明： ** 管理素材文件夹和素材记录，包括新建、改名、移动以及登记已有媒体。
| action | 关键参数 | 现有 operationId |
| --- | --- | --- |
| `create_folder` | 必填 `label` ；可选 `sortOrder` 、幂等键 | `createEditorAssetFolder` |
| `update_folder` | 必填 `folderId` ；可选 `label` 、`collapsed` | `updateEditorAssetFolder` |
| `create_asset` | 必填 `folderId` 、`label` 、`imageSrc` 、`width` 、`height` 、`sourceType` | `createEditorAsset` |
| `update_asset` | 必填 `assetId` ；可选 `label` 、`folderId` | `updateEditorAsset` |
移动素材复用 update_asset 的 folderId，不额外拆一个重复操作。可选更新字段的有效性按现有 API 处理。create_asset 只登记元数据，不上传文件、不触发生成；生成接口已经完成入库时不重复登记。删除使用 XV。
### XIV. 查看生成进度与结果
**说明： ** 查询一次已提交生成任务的当前状态。完成时返回结果，失败时返回错误；尚未完成时按建议间隔再次查询。
映射 `getExternalEditorGenerationJob` ，无需 action；必填 `operationId` 。
- 每次调用只查询一次，不在 MCP 服务端长时间阻塞到任务完成。
- `queued/running` ：读取进度和 pollAfterMs，继续等待。
- `completed` ：消费 result，并保留 warning 与 sliceWarning 等真实降级信息。
- `failed` ：返回已有脱敏错误。
- 跨账号任务与不存在任务沿用同一不可见语义。
收到 operationId 后优先直接查询。若提交响应丢失、尚未取得 operationId，不能靠查询工具凭空恢复：按现有幂等合同，复用原 API 操作、原请求和原幂等键重试以取得受理结果；不能换键重提。查询超时不改变服务端任务状态。
### XV. 删除资源
**说明： ** 删除指定项目、素材文件夹或素材记录。按精确 ID 操作，调用前明确目标及删除范围，并取得对应用户授权。
| action | 必填参数 | 现有 operationId |
| --- | --- | --- |
| `delete_project` | `projectId` | `deleteEditorProject` |
| `delete_folder` | `folderId` | `deleteEditorAssetFolder` |
| `delete_asset` | `assetId` | `deleteEditorAsset` |
工具统一标记删除风险。项目删除沿用默认画布与项目资源元数据级联清理语义。文件夹删除将其素材记录移到默认文件夹，默认文件夹不能删除；素材删除删除记录并处理关联精选审核状态。文件夹和素材记录删除不等于删除底层 OSS 媒体。
不增加批量、按名称或模糊匹配删除，不用一个可伪造的 confirm 参数替代真实用户授权和后端鉴权。
## 5. 实现前仍需明确的事项
1. 最终英文工具名与完整 action schema；条件参数如何在目标 MCP 客户端中准确展示和校验。
2. III 的项目资源投影结构及 legacyPublicPath 保留策略；各工具结果保持原样或裁剪时的精确字段。
3. 新旧工具替换、并存或迁移的具体选择。本文不预设双套目录、默认开关或 api_* 逃生入口。
4. 更新服务级 instructions、工具说明与相关使用资料，确保与实际广告的工具一致；文档存储和发布机制另行讨论。
实现验收围绕实际风险：操作路由和参数位置正确、缺失或错分支参数不触发副作用、原有 owner/scope 校验有效、同一逻辑生成幂等恢复、图集降级告警保留、画布 revision 冲突保留，以及重复语义入口调用同一底层能力的结果一致性。本文完成不代表这些运行时验证已经通过。
## 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、资源和进程内分派。
- [External 编辑器接口 ](../../server-rs/crates/api-server/src/external_editor_api.rs )：鉴权、请求处理与生成受理。
- [AGC 抠图模式与背景色透传 ](./【技术方案】AGC抠图模式与背景色透传-2026-09-16.md )：去背景模式与背景色已有合同。
当前参数事实按 2026-09-23 的仓库内容核对；后续实现时再次以代码与 OpenAPI 为准，发现变动同步修订本文，不维护第二份脱离 API 的字段真相。
