From 2499b4f76e934ee830e9f0fe641f95224608fd64 Mon Sep 17 00:00:00 2001 From: Linghong Date: Thu, 24 Sep 2026 06:26:13 +0000 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0MCP=E6=95=B4=E4=BD=93?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 精简 instructions 为服务能力和跨工具共同约定 取消强制创建同名素材文件夹与双重落库要求 同步技术方案和共享文档索引 --- docs/project-memory/shared-memory/document-map.md | 2 +- ...术方案】外部MCP语义工具说明与参数设计-2026-09-23.md | 10 ++++++++++ server-rs/crates/api-server/src/external_mcp.rs | 10 +++++++++- 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/project-memory/shared-memory/document-map.md b/docs/project-memory/shared-memory/document-map.md index 8c7f9ec03..d5ef96116 100644 --- a/docs/project-memory/shared-memory/document-map.md +++ b/docs/project-memory/shared-memory/document-map.md @@ -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： diff --git a/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md index e3e5c1ac3..874be7e9c 100644 --- a/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md +++ b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md @@ -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、参数、请求体、响应与公开字段权威。 diff --git a/server-rs/crates/api-server/src/external_mcp.rs b/server-rs/crates/api-server/src/external_mcp.rs index 07c129681..b2d20ef1f 100644 --- a/server-rs/crates/api-server/src/external_mcp.rs +++ b/server-rs/crates/api-server/src/external_mcp.rs @@ -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 {