From 8bae66108af8951a28b890bdc922256fb3ae478a Mon Sep 17 00:00:00 2001 From: Linghong Date: Mon, 31 Aug 2026 09:40:09 +0000 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=20DirectProject=20=E5=AE=A2?= =?UTF-8?q?=E6=88=B7=E7=AB=AF=E6=89=A9=E5=B1=95=E5=AF=BC=E5=85=A5=E6=96=B9?= =?UTF-8?q?=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增客户端 Skill 与 MCP 扩展导入技术方案。 记录独立扩展拆分、统一原生命名、默认启用和 Plugin 边界。 同步文档总览、文档地图和长期决策记录。 --- docs/README.md | 1 + .../shared-memory/decision-log.md | 11 + .../shared-memory/document-map.md | 13 +- ...roject客户端Skill与MCP扩展导入方案-2026-08-31.md | 474 ++++++++++++++++++ 4 files changed, 493 insertions(+), 6 deletions(-) create mode 100644 docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md diff --git a/docs/README.md b/docs/README.md index f937a964d..00c032ebf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,7 @@ ## AI 游戏创作与 Agent Runtime - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。 +- [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。 - [项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)：当前工作台页面和验收边界。 - [立项策划 Agent（Fast GDD）](<./technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md>)：当前策划入口、审批和恢复合同。 - [GameAgent 资源自由画板与快速编辑](./technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 5e0ee27db..a34ea37ae 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -15,6 +15,17 @@ - 关联文档：相关 PRD、技术文档、提交或 Issue ``` +## 2026-08-31 DirectProject 客户端扩展按独立 Skill/MCP 导入 + +- 背景：DirectProject 需要使用用户在 AGC 客户端导入的市面原生 Skill、MCP 和 Plugin 内容，但第三方内容不应直接安装到运行时 Codex，也不应要求用户转换为 AGC 自定义格式。 +- 决策：客户端提供一个全局“扩展”入口，统一接受文件、目录、zip 和标准 Plugin；目录、zip、Plugin 只是导入来源，发现出的每个 Skill 和每个 MCP Server 分别成为独立扩展项，分别列表、重命名、启用、禁用和删除。已识别项导入后默认启用，下次 DirectProject Codex 启动时按原生 Skill root 和 MCP 配置注入。 +- 命名：客户端列表名称与 Codex 运行时名称使用同一个原生标识，不维护 display/runtime 两套名称；重复或同名项保留为新的独立项并自动追加 `-2`、`-3`。Skill 重命名只修改客户端运行时副本中的有效名称，原始导入内容不修改。 +- Plugin 边界：Plugin 只作为导入容器提取 Skill/MCP；当前 DirectProject 关闭的 hooks、apps、remote plugin 和完整 Plugin Runtime 不接入。单个可执行文件或脚本不提供手动指定为 MCP 入口的功能。 +- 信任边界：不审核第三方 Skill 文案、脚本、二进制、MCP tool 或网络行为；导入阶段不执行内容。客户端只做标准结构识别、必要配置解析和 zip staging 路径边界处理，且不向第三方扩展注入 AGC 凭据或内部路径。 +- 影响范围：AGC 客户端扩展设置 UI、客户端本地扩展存储、DirectProject Codex app-server 启动准备和 pool fingerprint；不新增 HTTP 服务、SpacetimeDB schema、公开 API 或独立 Plugin Runtime。 +- 验证方式：分三阶段验收：先验证导入拆分和完整列表，再验证 Skill 运行时发现和重命名，最后验证 MCP 配置合并、Plugin 提取和失败隔离；只增加对应的定向测试、`npm run check:encoding` 和 `git diff --check`。 +- 关联文档：`docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`、`apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs`。 + ## 2026-08-30 批准 GDD 直接进入做游戏链路 - 背景：立项策划 GDD 批准后需要给用户一个进入做游戏的自然出口，产品决策改为点击按钮后直接开始建造。 diff --git a/docs/project-memory/shared-memory/document-map.md b/docs/project-memory/shared-memory/document-map.md index 5fbb8fe37..15c219955 100644 --- a/docs/project-memory/shared-memory/document-map.md +++ b/docs/project-memory/shared-memory/document-map.md @@ -1,6 +1,6 @@ # 文档地图与阅读索引 -更新时间：`2026-08-25` +更新时间：`2026-08-31` ## 阅读顺序 @@ -22,11 +22,12 @@ AI 游戏创作 / DirectProject / UI workflow： 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` -2. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` -3. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md` -4. `docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md` -5. `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` -6. UI 编辑器、宿主壳和当前测试专题文档 +2. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md` +3. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` +4. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md` +5. `docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md` +6. `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` +7. UI 编辑器、宿主壳和当前测试专题文档 图片画布 / 媒体生成： diff --git a/docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md b/docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md new file mode 100644 index 000000000..440f8cb0f --- /dev/null +++ b/docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md @@ -0,0 +1,474 @@ +# DirectProject 客户端 Skill 与 MCP 扩展导入方案 + +更新时间：`2026-08-31` + +## 1. 文档定位 + +本方案是 DirectProject 客户端第三方 Skill、MCP 和 Plugin 导入能力的当前实现依据。它描述客户端侧的导入、拆分、命名、启用和 DirectProject 启动注入边界，不改变 AGC 内置 Skill Pack、`agc_tools` MCP、项目文件工具和现有 Runtime 权威。 + +本方案只覆盖客户端安装和下一次 Codex 启动时接入。第三方扩展不是安装到全局运行时 Codex，也不要求用户把市面上的扩展重新打包为 AGC 自定义格式。 + +## 2. 一句话交付结果 + +客户端提供一个全局“扩展”入口，直接接受文件、目录、zip 和标准 Plugin；导入后把其中发现的每个 Skill 和每个 MCP Server 拆成独立扩展项，用户可以分别重命名、启用、禁用和删除；DirectProject 启动 Codex 时只注入已启用的独立项。 + +## 3. 已确定的产品边界 + +### 3.1 客户端安装、运行时注入 + +- 扩展内容保存在 AGC 客户端的扩展仓库。 +- 不把扩展永久安装到用户的全局 `CODEX_HOME`。 +- DirectProject 创建或复用 app-server 时，读取客户端当前已启用的扩展并生成本次运行的临时 Skill root 与 MCP 配置。 +- 导入、启用、禁用和重命名不热更新正在运行的 Codex；变更从下一次 DirectProject 启动生效。 +- 扩展默认对客户端内所有 DirectProject 生效，不做项目级启用映射。 + +### 3.2 用户信任和最小处理 + +用户自行负责第三方扩展的信任判断。客户端不审核 Skill 文案、脚本、二进制、MCP tool description、网络域名或扩展行为。 + +客户端只做导入流程正常运行所需的最小结构处理： + +- 识别标准 Skill、MCP 和 Plugin 结构； +- 读取必要的 TOML/JSON 配置； +- 生成运行时名称和临时配置； +- 解压时防止路径穿越到 staging 目录外。 + +导入阶段不执行脚本、不启动 MCP、不调用第三方网络服务。 + +即使不审核第三方行为，也不得向第三方扩展注入 AGC provider key、Codex 登录态、Cookie、bridge token、内部服务令牌或客户端内部路径。 + +### 3.3 明确不支持 + +- 单个 `.exe`、`.py`、`.js` 或其它可执行文件/脚本由用户手动指定为 MCP 入口； +- 根据 README 或文件后缀猜测如何启动普通程序； +- 完整 Codex Plugin Runtime； +- Plugin hooks、apps、remote plugin 和依赖这些能力的运行时行为； +- 自定义扩展 manifest、审核清单或自定义安装包格式； +- Skill/MCP 行为安全扫描、脚本沙箱和网络白名单； +- 项目级扩展配置； +- 热更新、后台扩展服务、在线市场、版本历史、回滚和自动升级。 + +## 4. 导入与拆分模型 + +目录、zip 和 Plugin 是“导入来源”，不是管理对象。一个来源中识别出的每个 Skill 和每个 MCP Server 都独立成为客户端扩展项。 + +```text +导入来源 + ↓ +保存原始内容 + ↓ +发现标准结构 + ↓ +拆成独立 Skill/MCP 扩展项 + ↓ +分别列表显示、命名、启用和删除 +``` + +### 4.1 Skill 发现 + +以下内容分别导入为独立 Skill： + +- 根目录的 `SKILL.md`； +- 标准 Skill root 中的每个 `*/SKILL.md`； +- Plugin 中包含的标准 Skill 目录。 + +例如： + +```text +my-package/ +└── skills/ + ├── art-skill/SKILL.md + └── code-skill/SKILL.md +``` + +导入结果是两个独立项： + +```text +art-skill +code-skill +``` + +### 4.2 MCP 发现 + +以下配置中的每个 Server 分别导入为独立 MCP 项： + +- Codex 原生 `config.toml` 的 `[mcp_servers.]`； +- 兼容的 `.mcp.json` 顶层 `mcpServers.`； +- 标准 Plugin 中能够解析出的 MCP 配置。 + +例如一个配置包含： + +```toml +[mcp_servers.search] +command = "..." + +[mcp_servers.filesystem] +command = "..." +``` + +导入结果是两个独立项： + +```text +search +filesystem +``` + +`.mcp.json` 只作为兼容输入读取，不作为新的 AGC 配置格式；只支持能直接转换为 MCP Server 连接描述的字段，不为各客户端的私有扩展建立独立系统。 + +### 4.3 Plugin 处理 + +存在 `.codex-plugin/plugin.json` 时，将目录或 zip 识别为标准 Plugin 导入来源。 + +本期只提取其中可识别的 Skill 和 MCP，并分别创建独立扩展项： + +```text +Plugin +├── Skill A → 独立 Skill 项 +├── Skill B → 独立 Skill 项 +└── MCP C → 独立 MCP 项 +``` + +Plugin 自身不生成父级列表项，也不提供 Plugin 级开关。hooks、apps、remote plugin 以及依赖完整 Plugin Runtime 的内容忽略；如果没有任何可支持的 Skill/MCP，则来源保留为未知内容。 + +### 4.4 未知输入 + +- 单个无关文件或二进制：保存为一个 `unknown` 项，不执行。 +- 完全无法发现标准内容的目录或 zip：保存一个 `unknown` 项。 +- 含有已识别 Skill/MCP 的来源中其它普通文件：不把每个普通文件都变成独立项，但保留原始来源用于溯源。 + +未知项可以展示和删除，但没有有效的启动入口。 + +## 5. 命名规则 + +### 5.1 一个名称同时用于 UI 和 Codex + +每个独立 Skill/MCP 项使用一个有效名称： + +```text +name 当前名称，前端和 Codex 运行时使用 +original_name 原始名称，用于溯源，不随用户改名变化 +``` + +不维护 `display_name` 和 `runtime_name` 两套可见名称。 + +用户把 Skill 从 `art-skill` 改为 `pixel-art-skill` 后： + +- 前端列表显示 `pixel-art-skill`； +- Codex 的 Skill 列表也使用 `pixel-art-skill`； +- 客户端只在运行时副本中修改 Skill 的有效名称； +- 原始 `SKILL.md` 不修改。 + +MCP 重命名同理：客户端列表名称和运行时生成配置中的 Server key 使用同一个名称，原始 TOML/JSON 不修改。 + +### 5.2 自动重命名 + +每次重复导入都保留为新的独立项，不覆盖旧项、不去重。 + +名称冲突统一使用原生标识形式追加后缀： + +```text +art-skill +art-skill-2 +art-skill-3 +``` + +不使用 `art-skill (2)` 这一类仅适用于 UI 的第二套名称。 + +同一类型内名称需要唯一： + +- Skill 与 Skill 之间避免重复； +- MCP 与 MCP 之间避免重复； +- Skill 和 MCP 可以同名，因为属于不同的运行时命名空间。 + +如果名称相同但内容不同，视为名称冲突；如果内容指纹相同，视为重复导入。两种情况都保留新项并使用同一套后缀分配逻辑。 + +提示合并为一次普通通知，例如： + +```text +检测到重复或同名扩展，已自动命名为“art-skill-2”。 +``` + +内容指纹只用于识别重复导入，不用于安全审核。 + +### 5.3 手动重命名 + +前端允许用户直接编辑独立扩展项的 `name`： + +- 名称不能为空； +- 使用对应 Skill/MCP 的原生标识格式； +- 保存时检查同类型名称冲突； +- 冲突时自动分配 `-2`、`-3` 后缀并提示用户。 + +Skill 的手动重命名必须反映到 Codex 运行时名称。客户端保留原始内容，在临时运行副本中修改标准名称字段，不修改用户导入的源文件。 + +目录或 Plugin 中的多个 Skill 已经在导入时拆成独立项，因此用户可以分别重命名每个 Skill，不存在“重命名整个多 Skill 包”的操作。 + +## 6. 客户端存储 + +扩展仓库使用客户端本地存储和内部元数据，不对用户要求任何自定义包结构。 + +```text +ImportedSource +├── id +├── original_name +├── storage_path +└── fingerprint + +ExtensionItem +├── id +├── source_id +├── type: skill | mcp | unknown +├── name +├── original_name +├── source_relative_path +├── enabled +├── fingerprint +└── last_error +``` + +`source_id` 只用于来源溯源和清理，不形成可操作的父级扩展项，也不产生父子级联启用状态。 + +对于目录或 zip： + +- 原始来源保存一次； +- 每个发现的 Skill/MCP 保存独立元数据； +- 删除某个子项不影响其它子项； +- 原始来源不因删除一个子项而立即删除。 + +重复导入同一来源时创建新的来源和新的子项，名称按规则追加后缀。 + +## 7. 前端设计 + +### 7.1 入口 + +复用现有 [RuntimeConfigDialog.tsx](../../apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx) 的设置弹窗，在设置导航中增加“扩展”分区。 + +不在项目聊天区新增入口，不按项目创建扩展页面。 + +### 7.2 页面 + +页面只包含： + +- “导入扩展”按钮； +- 独立扩展项列表； +- 每项的名称、类型、来源摘要和当前状态； +- 启用/禁用开关； +- 重命名操作； +- 删除操作； +- 必要时的一行启动错误。 + +一个目录、zip 或 Plugin 中的多个内容直接平铺显示，不显示父级包和父级开关： + +```text +art-skill +Skill · 来自 my-plugin.zip 已启用 + +code-skill +Skill · 来自 my-plugin.zip 已禁用 + +search +MCP · 来自 my-plugin.zip 启动失败 +``` + +完整列表包括： + +- 已启用； +- 已禁用； +- 未识别； +- 当前不可用； +- 启动失败。 + +“完整列表”指所有用户导入的独立扩展项，不指 zip 内每个普通文件或每个 MCP tool。 + +### 7.3 导入后的默认状态 + +已识别的 Skill/MCP 导入后默认启用，下一次 DirectProject 启动时加载。 + +未识别内容保留在列表中，但没有有效启动能力。 + +导入和状态变化不需要和 Agent 模型配置共用“保存”按钮，扩展操作可以单项即时保存。 + +## 8. DirectProject 运行时接入 + +### 8.1 Skill + +启动准备阶段： + +```text +读取 enabled=true 的 Skill 项 + ↓ +创建本次运行的临时 Skill root + ↓ +为重命名 Skill 生成运行时副本 + ↓ +调用 skills/extraRoots/set + ↓ +调用 skills/list 复核 +``` + +每个独立 Skill 的启用状态单独生效。Skill 内容中的脚本、二进制和引用资源不做行为扫描。 + +### 8.2 MCP + +启动准备阶段： + +```text +读取 enabled=true 的 MCP 项 + ↓ +为每个项生成 mcp_servers 配置 + ↓ +处理同类型 Server key 冲突 + ↓ +与 AGC 内置 agc_tools 合并 + ↓ +启动 Codex +``` + +每个 MCP Server 独立启用和禁用。相对路径按来源目录解析，原始 command、args、cwd、env 或 URL 按原生配置保留。 + +`agc_tools` 为 AGC 内部保留名称，第三方扩展不得覆盖。第三方 MCP 的工具调用继续继承 DirectProject 当前既有运行策略；本功能不新增逐工具审核系统。 + +### 8.3 失败处理 + +第三方扩展的解析或启动失败时： + +- 记录对应独立项的 `last_error`； +- 列表显示“启动失败”或“当前不可用”； +- 尽量跳过失败项，保留 AGC 内置 Skill 和 `agc_tools`； +- 不自动重试、不启动后台修复服务、不删除原始内容。 + +扩展集合的 fingerprint 纳入现有 DirectProject app-server pool key，扩展集合变化后不复用不匹配的旧运行实例。 + +## 9. 客户端接口 + +Skill 和 MCP 共用客户端扩展接口： + +```text +list_client_extensions() +import_client_extension(path) +set_client_extension_enabled(id, enabled) +rename_client_extension(id, name) +remove_client_extension(id) +``` + +不新增按类型分开的安装接口。导入接口返回拆分后的多个独立项： + +```text +{ + imported: [ + { id, type: "skill", name: "art-skill" }, + { id, type: "skill", name: "code-skill" }, + { id, type: "mcp", name: "search" } + ], + unknown: false +} +``` + +前端不直接处理 Skill root 路径、MCP command 或 zip staging 路径；这些属于客户端后端和 DirectProject 启动适配层。 + +## 10. 分阶段实施与验收 + +不采用一次性大改动。按垂直闭环分三阶段，每阶段完成后验收再进入下一阶段。 + +### 阶段 0：冻结契约和样例 + +确认： + +- 导入来源与独立扩展项的关系； +- 名称统一使用原生标识； +- 重复导入自动追加后缀； +- 已识别内容默认启用； +- Plugin 只作为导入容器； +- 单个可执行文件/脚本不作为 MCP 入口； +- 客户端全局生效。 + +准备最小样例并确认每个样例的预期拆分结果。 + +### 阶段 1：客户端导入和列表 + +完成： + +- 客户端存储； +- 文件、目录、zip 导入； +- Skill/MCP/Plugin 结构发现； +- 多内容拆分为独立项； +- 未知项保留； +- 默认启用； +- 原生名称自动追加后缀； +- 手动重命名； +- 独立启用、禁用、删除； +- 设置弹窗中的完整列表。 + +验收： + +- 一个来源包含多个 Skill/MCP 时，列表出现多个独立项； +- 相同来源重复导入时不覆盖旧项； +- 同名和重复内容均自动使用 `-2`、`-3`； +- 单个二进制不会被启动； +- 原始来源内容未被改写。 + +### 阶段 2：Skill 运行时闭环 + +完成： + +- 读取客户端已启用 Skill； +- 临时 Skill root 生成； +- Skill 重命名同步到运行时副本； +- `skills/extraRoots/set` 和 `skills/list` 接入； +- 扩展 fingerprint 纳入 app-server pool key。 + +验收： + +- 多个 Skill 可以独立发现； +- 重命名后的 Skill 在 `skills/list` 中使用新名称； +- 单独禁用一个 Skill 不影响其它 Skill； +- 当前 Codex 不热更新； +- AGC 内置 Skill 不受影响。 + +### 阶段 3：MCP 和 Plugin 部分闭环 + +完成： + +- `config.toml` 每个 Server 独立导入； +- `.mcp.json` 每个 Server 独立导入； +- Plugin 中 Skill/MCP 独立导入； +- MCP Server 重名自动追加原生后缀； +- MCP 运行时配置合并； +- 单项错误记录和内置能力保留。 + +验收： + +- 一个 MCP 配置包含多个 Server 时，列表出现多个独立项； +- 每个 MCP 可以单独启用、禁用和重命名； +- 重名 Server 能生成稳定的唯一 key； +- Plugin 不会开启 hooks、apps 或完整 Plugin Runtime； +- 单个可执行文件/脚本仍不会自动作为 MCP 入口。 + +## 11. 最小验证范围 + +只增加和本功能直接相关的定向验证： + +- 多 Skill/MCP 来源拆分； +- 原生名称自动重命名和手动重命名； +- 重复导入保留多个独立项； +- Skill 运行时名称复核； +- MCP Server key 冲突； +- 未知文件不执行； +- zip 解压路径边界。 + +不新增完整第三方扩展行为测试、安全扫描框架、在线测试服务或大规模 E2E 基础设施。 + +## 12. 非目标和后续议题 + +以下内容不属于本方案的交付判据： + +- 完整 Codex Plugin Runtime； +- Plugin hooks/apps/remote plugin； +- 单文件 MCP 入口配置； +- 项目级扩展开关； +- MCP 工具逐项权限管理； +- OAuth/密钥管理中心； +- 在线市场和自动更新； +- 第三方扩展安全评级和行为沙箱。 + +后续如果要支持这些能力，必须另立技术方案，不在本方案中预留复杂抽象或隐藏开关。