扩展MCP的完整Skill资源
拆分外部编辑器Skill为四篇渐进式参考文档 MCP资源列表支持逐篇发现和读取Skill内容 Skill归档和manifest同步七文件清单及SHA校验 同步OpenAPI、架构文档和项目决策记录
This commit is contained in:
@@ -146,7 +146,7 @@
|
||||
],
|
||||
"operationId": "callExternalEditorMcp",
|
||||
"summary": "调用托管式远程 MCP",
|
||||
"description": "MCP 2025-11-25 Streamable HTTP JSON 端点。使用与 REST API 相同的 Bearer API Key；生成工具立即返回异步 operation。",
|
||||
"description": "MCP 2025-11-25 Streamable HTTP JSON 端点。使用与 REST API 相同的 Bearer API Key；生成工具立即返回异步 operation。resources/list 和 resources/read 提供 usage、OpenAPI、Skill 主入口以及 capability routing、API operations、authentication and safety、requests and outputs 四篇渐进式 reference；本地脚本仍只通过完整 Skill ZIP 提供。",
|
||||
"security": [
|
||||
{
|
||||
"ExternalApiKey": []
|
||||
|
||||
@@ -5891,7 +5891,7 @@
|
||||
|
||||
- 异步契约：External v1 的图片生成、图片编辑、图标图集、UI 素材提取、角色动画、视频、音效和背景音乐八类 POST 固定持久化入 `external_generation_job` 并返回 HTTP `202 + operationId/statusUrl/pollAfterMs`；不受站内 `GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 影响。每次逻辑生成必须携带稳定 `Idempotency-Key`，网络结果未知或调用方轮询超时时复用原键和原 operationId，不得换键重提。
|
||||
- 查询与结果：新增 owner-safe `GET /api/external/v1/generations/{operationId}`。`queued/running` 返回 phase/progress，`completed` 返回 compact 稳定 artifact 引用，`failed` 返回脱敏错误，跨 owner 按不存在处理。compact result 允许 objectKey、resource/asset ID、assetObjectId、尺寸、媒体类型、taskId 和告警；禁止完整 project/canvas、Data URL、Blob URL、临时 signed URL、内部 provider 原文和 lease/fencing 控制字段。
|
||||
- MCP：新增托管 `/api/external/v1/mcp`，使用现有 External API Key Bearer 鉴权和无协议 session 的 Streamable HTTP JSON direct 模式。MCP tools 从同一 OpenAPI operation 形成并复用 External REST router；生成 tool 显式要求 `idempotencyKey`，另有统一任务查询 tool。MCP resources 提供使用说明、OpenAPI 和 Skill 入口。禁止开放内部 SpacetimeDB MCP、worker procedure、controller 或队列控制面。
|
||||
- Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、API 选择参考、stdlib Python helper 和 `agents/openai.yaml`，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。不支持 MCP 或需要本地文件上传编排的 Agent 使用该 Skill 包。
|
||||
- MCP：新增托管 `/api/external/v1/mcp`，使用现有 External API Key Bearer 鉴权和无协议 session 的 Streamable HTTP JSON direct 模式。MCP tools 从同一 OpenAPI operation 形成并复用 External REST router；生成 tool 显式要求 `idempotencyKey`，另有统一任务查询 tool。MCP resources 提供使用说明、OpenAPI、Skill 入口 `SKILL.md` 和 `references/capability-routing.md`、`references/api-operations.md`、`references/authentication-and-safety.md`、`references/requests-and-outputs.md` 四篇稳定 reference；日后新增 reference 时必须同步新增独立 resource。MCP Agent 直接调用托管 tools，不安装 CLI，也不将脚本、测试或 workflow 暴露为 MCP resources。禁止开放内部 SpacetimeDB MCP、worker procedure、controller 或队列控制面。
|
||||
- Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
|
||||
- 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
|
||||
- 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
|
||||
|
||||
@@ -45,7 +45,7 @@ v1 只开放以下能力：
|
||||
- `GET /api/external/v1/agent-integration.json`：公开导出 Agent 集成发现 manifest，声明 MCP、OpenAPI、Skill 入口、完整 Skill archive、archive SHA-256 和包内文件清单。
|
||||
- `GET /api/external/v1/skill/SKILL.md`：公开读取 Skill 原始入口。
|
||||
- `GET /api/external/v1/skill.zip`：公开下载完整 Skill 包。
|
||||
- `POST /api/external/v1/mcp`：使用相同 Bearer API Key 的托管式 Streamable HTTP MCP；对外暴露本节 OpenAPI operation tools 以及使用说明、OpenAPI、Skill 三类资源，不开放内部 SpacetimeDB MCP。
|
||||
- `POST /api/external/v1/mcp`：使用相同 Bearer API Key 的托管式 Streamable HTTP MCP；对外暴露本节 OpenAPI operation tools 以及使用说明、OpenAPI、Skill 入口 `SKILL.md` 和逐个 Skill reference 文档，不开放内部 SpacetimeDB MCP。
|
||||
|
||||
八类生成 POST 全部要求 `Idempotency-Key`，成功只返回 HTTP `202 Accepted`、`operationId`、`kind`、`status`、`statusUrl`、`pollAfterMs` 和 `updatedAtMicros`。调用方不得把 `202` 当作媒体生成完成，也不得在网络结果不确定时换一个幂等键重新提交。
|
||||
|
||||
@@ -79,26 +79,35 @@ provider 原图已保存但透明背景处理最终失败时，worker 保留原
|
||||
|
||||
MCP tools 从同一份 OpenAPI operation 自动形成 snake_case 名称，并在进程内复用 External REST router，因此鉴权、scope、owner、入参、幂等、计费和结果查询契约只有一份。生成 tools 把 `idempotencyKey` 显式放进参数，因为 MCP transport 的 Authorization 头不能代替逐次业务幂等键。工具结果使用 `structuredContent`；业务失败使用 `isError=true` 的结构化安全错误，协议不可路由时才返回 JSON-RPC error。
|
||||
|
||||
MCP 暴露三个稳定资源：
|
||||
MCP 暴露下列稳定文本资源：
|
||||
|
||||
- `genarrative://external-editor/usage`：关键工作流和异步轮询规则。
|
||||
- `genarrative://external-editor/openapi`：完整 External v1 OpenAPI。
|
||||
- `genarrative://external-editor/skill`：Skill 入口正文与完整 Skill 包下载地址。
|
||||
- `genarrative://external-editor/skill`：Skill 入口原文；保留首版已声明的稳定 URI。
|
||||
- `genarrative://external-editor/skill/references/capability-routing.md`：能力选路与场景边界。
|
||||
- `genarrative://external-editor/skill/references/api-operations.md`：公开 API 操作、必填字段与调用顺序。
|
||||
- `genarrative://external-editor/skill/references/authentication-and-safety.md`：API Key 鉴权、幂等与安全边界。
|
||||
- `genarrative://external-editor/skill/references/requests-and-outputs.md`：异步提交、状态轮询与 compact 结果语义。
|
||||
|
||||
Skill 日后新增 `references/` 文档时，MCP 必须按包内相对路径逐个增加 `genarrative://external-editor/skill/references/<name>` resource，不得只暴露 `SKILL.md` 而让 Agent 无法读取其引用。当前稳定 reference 精确为上述四篇，不得声明不存在的 reference。MCP Agent 直接调用托管 tools，不下载或安装 Python CLI；`scripts/`、`tests/` 和 `.github/workflows/` 不作为 MCP resources。
|
||||
|
||||
MCP 必须始终复用 `require_external_api_key`，owner 从 `ExternalApiPrincipal` 获取，不接受请求参数伪造 owner。禁止透传内部 `external_generation_job` procedure、worker controller、SpacetimeDB MCP 或 lease/fencing 控制面。
|
||||
|
||||
## Agent 集成发现与完整 Skill 包
|
||||
|
||||
`agent-integration.json` 是机器可读的统一发现入口。支持远程 MCP 的 Agent 读取其中 `mcp.transport/url/authentication`；不支持 MCP 的 Agent 下载 `skill.archive`，核对 `archiveSha256`，解压后从 `genarrative-external-editor-api/SKILL.md` 进入。
|
||||
`agent-integration.json` 是机器可读的统一发现入口。支持远程 MCP 的 Agent 读取其中 `mcp.transport/url/authentication`，通过 MCP resources 读取 Skill 入口和所需 references，直接调用 MCP tools，不安装 CLI。仅不支持 MCP，或需要在 Agent 所在机器上编排本地文件上传的调用方下载 `skill.archive`，核对 `archiveSha256`，解压后从 `genarrative-external-editor-api/SKILL.md` 进入。
|
||||
|
||||
Skill archive 必须至少包含：
|
||||
|
||||
- `SKILL.md`
|
||||
- `references/api-selection.md`
|
||||
- `references/capability-routing.md`
|
||||
- `references/api-operations.md`
|
||||
- `references/authentication-and-safety.md`
|
||||
- `references/requests-and-outputs.md`
|
||||
- `scripts/genarrative_external_api.py`
|
||||
- `agents/openai.yaml`
|
||||
|
||||
包由 api-server 直接从仓库同源文件构建，不能只返回光秃秃的 OpenAPI JSON，也不能把个人 API Key、环境配置或本机路径写入包。Python helper 对上层保持便利的同步函数外观，但内部必须执行“异步提交 → 保存 operationId → 按 pollAfterMs 查询 → completed 返回 result”，查询超时应保留 operationId 供后续继续，不得换键重提。
|
||||
包由 api-server 直接从仓库同源文件构建，不能只返回光秃秃的 OpenAPI JSON，也不能把个人 API Key、环境配置或本机路径写入包。完整 `skill.zip` 只服务不支持 MCP 或需要本地文件编排的 Agent，不是 MCP resource catalog 的压缩包镜像。Python helper 对上层保持便利的同步函数外观，但内部必须执行“异步提交 → 保存 operationId → 按 pollAfterMs 查询 → completed 返回 result”，查询超时应保留 operationId 供后续继续，不得换键重提。
|
||||
|
||||
api-server 使用 `include_str!` 嵌入 OpenAPI 与 Skill 源文件；容器构建阶段必须同时复制 `docs/openapi/` 和 `.codex/skills/genarrative-external-editor-api/`，不能只复制 `server-rs/`，否则本地 Cargo 验证虽可通过，隔离镜像构建会在编译期找不到同源资源。
|
||||
|
||||
@@ -243,8 +252,8 @@ docs/openapi/genarrative-external-v1.openapi.json
|
||||
- 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
|
||||
- OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
|
||||
- OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。
|
||||
- `agent-integration.json` 能发现 MCP、OpenAPI、Skill entry/archive；下载 archive 的 SHA-256 与 manifest 一致，ZIP 包含四个声明文件且不含凭据。
|
||||
- MCP 在无 Bearer 时返回 `401`，合法 Key 可完成 initialize、tools/list、resources/list/read 和生成提交/查询；多实例不依赖 sticky session，不暴露内部 SpacetimeDB MCP 或 worker 控制面。
|
||||
- `agent-integration.json` 能发现 MCP、OpenAPI、Skill entry/archive；下载 archive 的 SHA-256 与 manifest 一致，ZIP 包含 `SKILL.md`、四篇 references、Python helper 和 `agents/openai.yaml` 七个声明文件且不含凭据。
|
||||
- MCP 在无 Bearer 时返回 `401`，合法 Key 可完成 initialize、tools/list、resources/list/read 和生成提交/查询；resource catalog 必须包含 usage、OpenAPI、`skill` 主入口和当前全部 Skill references，当前精确为 `skill/references/capability-routing.md`、`skill/references/api-operations.md`、`skill/references/authentication-and-safety.md` 与 `skill/references/requests-and-outputs.md`，且不包含 CLI 脚本、测试或 workflow；多实例不依赖 sticky session，不暴露内部 SpacetimeDB MCP 或 worker 控制面。
|
||||
- 外部素材库接口覆盖当前已有素材操作：直传凭证、素材对象确认、签名读取、读取素材库、创建 / 更新 / 删除文件夹、创建 / 更新 / 删除素材、创建项目画布资源。
|
||||
- 外部项目接口覆盖当前已有项目管理操作：项目列表、最近项目、创建、读取、重命名、删除和默认画布保存。
|
||||
- 外部素材生成接口覆盖当前已有编辑器素材操作：生图、重绘 / 调整、规范图生成、宣发素材生成、图标素材生成与拆分、UI 设计图生成与拆分、角色动画、视频、音效和背景音乐。
|
||||
|
||||
Reference in New Issue
Block a user