更新MCP整体使用说明

精简 instructions 为服务能力和跨工具共同约定取消强制创建同名素材文件夹与双重落库要求同步技术方案和共享文档索引
2026-09-24 06:26:13 +00:00
parent 991183fb2f
commit 2499b4f76e
3 changed files with 20 additions and 2 deletions
@@ -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)：15 个语义工具与全部旧工具并存，复用现有 API 分派和 schema；多功能入口使用 action/input，结果不裁剪，可选幂等只扩展新入口。resources/instructions 仍沿用原内容，线上状态按实际部署核对。
+2. [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：15 个语义工具与全部旧工具并存，复用现有 API 分派和 schema；多功能入口使用 action/input，结果不裁剪，可选幂等只扩展新入口。instructions 与 usage resource 已更新为服务能力和跨工具共同约定，其它 resources 保持原样；线上状态按实际部署核对。

 AI 游戏创作 / DirectProject / UI workflow：

@@ -343,6 +343,16 @@ register_resource 只登记资源，并不自动创建画布图层。正常生

 未验证：真实用户登录/发放 API Key 全流程、付费 Provider 生成、外部 MCP 客户端对 oneOf 参数的展示与使用、远端部署。本地验收不代表这些项目已通过。

+### 5.5 instructions 更新（2026-09-24）
+
+初始化响应的 instructions 只描述服务能力和跨工具共同约定，不引入“语义工具 / 原有工具”分类，也不重复单个工具的参数分支。具体参数以工具 schema 和说明为准，详细流程由 resources 提供。
+
+当前说明覆盖：按任务需要创建项目和素材文件夹、通过生成目标字段落画布或素材库且避免重复登记、付费异步提交与稳定幂等键、使用 `check_generation` 按返回间隔轮询、本地文件上传票据与实际传输分工、稳定媒体引用、按真实结果和告警判断完成情况。
+
+不再要求所有任务先创建同名素材文件夹或同时写入画布与素材库。查询超时不代表生成失败，不应因此重新提交或更换幂等键。
+
+权威文案位于 `external_mcp.rs` 的 `MCP_INSTRUCTIONS`，初始化响应与 `genarrative://external-editor/usage` 共用同一内容。本次仅更新该说明；其它 resources、工具、API 和独立 Skill 保持不变。
+
 ## 6. 核对入口

 - [External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)：operation、参数、请求体、响应与公开字段权威。
@@ -56,7 +56,15 @@ const SKILL_REQUESTS_AND_OUTPUTS_URI: &str =
    "genarrative://external-editor/skill/references/requests-and-outputs.md";
 const MAX_MCP_REST_RESPONSE_BYTES: usize = 4 * 1024 * 1024;

-const MCP_INSTRUCTIONS: &str = r#"陶泥儿外部编辑器工具。先创建或复用画布项目，并创建与画布同名的素材文件夹；生成结果应同时写入画布和素材库。参考本地文件时先走上传票据和对象确认，不要把 Data URL、Blob URL 或临时签名 URL写入生成参数。所有生成工具都是异步提交：必须提供 idempotencyKey，提交后按 pollAfterMs 调用 get_external_editor_generation_job，只有 status=completed 时消费 result；查询超时不能重新提交。图集生成必须显式声明 sliceMode，没有默认值：需求要求等分网格、固定槽位或指定行列数时用 grid 并提供来自需求的 gridX/gridY，自由排布或数量不定时用 connected-components（可用 sliceCount 约束张数），connected-components 不接受 gridX/gridY；缺失、越界或自相矛盾在计费前返回 400。warning 表示主结果可用但存在降级，sliceWarning 表示完整透明图集可用但切片未完成。详细说明、OpenAPI、Skill 主入口和分主题 references 见 resources/list；需要本地文件编排或不支持 MCP 时再下载 skill.zip。"#;
+const MCP_INSTRUCTIONS: &str = r#"陶泥儿提供画布项目管理、素材库管理，以及图片、角色动画、视频和音频生成能力。
+
+按用户任务需要创建或复用项目、素材文件夹，不默认创建。生成结果需要进入画布或素材库时，使用对应生成工具支持的目标字段；已有落库结果不要重复登记。
+
+生成操作会产生费用，采用异步提交。每次独立生成使用稳定的 idempotencyKey；取得任务 ID 后，使用 check_generation 按 pollAfterMs 查询，直到 completed 或 failed。查询超时不代表生成失败，不要因此重新提交或更换幂等键。
+
+本地参考文件通过 prepare_asset_upload 获取上传票据，由调用方实际上传后确认对象。后续引用遵循各工具要求，使用稳定的对象键或资源、素材 ID；不要把临时下载 URL 当作持久引用。
+
+以实际返回的结果和告警判断完成情况，部分产物成功不代表所有处理步骤成功。具体参数以工具 schema 和说明为准；需要详细流程、示例或 API 契约时，通过 resources/list 查找相关文档。"#;

 #[derive(Clone, Debug)]
 struct McpOperation {