新增 AGC 模型 Agent 模式与 Claude Agent SDK sidecar

后台模型目录增加 codex/cc 执行模式绑定，旧目录缺省兼容 Codex AGC 客户端按模型绑定路由 Codex app-server 或 Claude Agent SDK sidecar 随包携带 Node runtime、Claude Agent SDK 与匹配平台 Claude runtime 补充模型配置、客户端选择、运行时适配、MCP 取消和定向测试同步 AGC 模型配置规范、里程碑计划与共享决策记录
2026-09-30 13:49:09 +08:00
parent 5e2d47919e
commit fb130d1847
38 changed files with 3417 additions and 118 deletions
@@ -0,0 +1,47 @@
+# 【实施计划】AGC模型Agent模式绑定与Claude Code执行器
+
+| 字段      | 值 |
+| --------- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC模型Agent模式绑定与Claude Code执行器-2026-09-30.md` |
+| Status    | ready |
+| Owner     | Codex |
+
+## 修改边界
+
+- 允许修改：
+  - `server-rs/crates/module-runtime`、`shared-contracts`、`api-server`、SpacetimeDB JSON 目录读写相关测试。
+  - `apps/admin-web` AGC 模型目录页面、类型和测试。
+  - `apps/ai-game-creator-shell` 客户端模型目录/选择、Tauri 配置、Agent Runtime 与 Claude Agent SDK sidecar/adapter、测试。
+  - 当前 AGC 模型目录/Runtime 权威文档和共享记忆（仅写入最终稳定结论）。
+- 明确不修改：
+  - 现有 Codex app-server 协议实现的行为与私有凭据。
+  - SpacetimeDB 表结构、migration、生成绑定（目录 JSON 载荷兼容即可）。
+  - 与本功能无关的工作树已有修改。
+
+## 实现顺序
+
+1. 先补齐目录领域字段、默认/兼容反序列化、后台 DTO/API/admin-web 编辑与测试。
+2. 扩展公开模型摘要和客户端缓存/选择，将后台 `codex`/`cc` 映射为内部执行模式并修复设置保存覆盖问题。
+3. 新增 Claude Agent SDK sidecar 执行器：隔离环境、stream-json 输入输出、模型/Anthropic 配置、MCP 配置、文本与工具事件、超时取消和进程回收；不修改 Codex 执行器。
+4. 在 Runtime/DirectProject 分发处按模型绑定路由；补齐 cc 的配置检查、错误分类、客户端状态展示和回归测试。
+5. 运行定向验证、隔离真实 smoke，回写文档证据；若发现合同变化，先回到主规范再继续。
+
+## 验证命令
+
+1. `npm run check:encoding`
+2. `git diff --check`
+3. `npm --prefix apps/admin-web run test -- --run src/pages/AdminAgcModelsPage.test.tsx`
+4. `npm --prefix apps/admin-web run typecheck`（以仓库实际 script 为准）
+5. `cargo test -p module-runtime agc_models`
+6. `cargo test -p api-server agc_model`
+7. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 的配置/Claude/Direct 定向测试
+8. `npm --prefix apps/ai-game-creator-shell run test -- --run` 与类型检查（按实际 script 收窄）
+9. 隔离临时项目运行 Claude Code 文本、受控 MCP、取消/回收 smoke
+
+## 风险与回滚点
+
+- Claude Agent SDK sidecar 的 stream-json 事件或输入格式变化：adapter 只接受白名单事件，失败关闭；可将模型绑定回 `codex`，不影响现有链路。
+- 后台目录新增字段与旧 JSON：使用缺省 `codex`，保存时写回字段；若兼容测试失败，保留目录载荷原格式并只在读投影填默认。
+- 客户端模型选择与 Agent 模式不同步：选择命令以模型目录快照的 `agentMode` 为输入并做枚举校验；同步失败不得切换活动回合。
+- Claude 原生工具越权：默认只接入受控 MCP，禁止原生 Bash/写文件；任何未经宿主确认的工具请求转失败。
+- 取消/进程归属不确定：保持失败关闭，不复用旧 cc 进程；Codex 模式继续走原有执行器。
@@ -0,0 +1,51 @@
+# 【里程碑】AGC模型Agent模式绑定与Claude Code执行器
+
+| 字段        | 值 |
+| ----------- | --- |
+| Version     | 1.0 |
+| Status      | completed |
+| Date        | 2026-09-30 |
+| Parent Spec | `docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md` |
+
+## 目标
+
+让后台维护的每个 AGC 模型同时决定执行 Agent：默认使用 Codex，显式绑定 `cc` 时由 AGC 客户端调用 Claude Code，并保持宿主工具与回合边界。
+
+## 范围
+
+- AGC 模型目录、后台完整 DTO、客户端公开模型摘要增加 `agentMode`。
+- `codex` / `cc` 的绑定校验、旧目录兼容和客户端模型选择同步。
+- AGC 客户端新增 Claude Code 执行器，使用 Anthropic 接入、Claude Code stream-json 和受控 MCP。
+- 文本回复、受控只读/项目工具调用、流式活动、取消/超时、进程回收和错误分类。
+- Codex 原有模式、provider 模式、自定义模型和后台 revision/权限合同保持兼容。
+
+## 不在范围内
+
+- 删除或改写现有 Codex app-server。
+- 将本机 `cc`（可能是 C 编译器别名）覆盖为 Claude Code 命令。
+- 放开 Claude Code 原生 Bash、任意文件写入、编辑器执行、试玩、付费工具或未登记 MCP。
+- SpacetimeDB 表结构字段变更；目录继续存储在现有 JSON 载荷中。
+- 为 Claude Code 增加新的公开 API 或把 Anthropic 协议伪装为 OpenAI Responses。
+
+## 依赖与前置条件
+
+- Claude Agent SDK sidecar 在开发/运行环境可发现，并支持 `--print --input-format stream-json --output-format stream-json`。
+- 中转可处理 Claude Code 使用的 Anthropic Messages 请求，模型 ID 与后台目录一致。
+- AGC 现有 DirectProject MCP loopback、项目身份、权限、预算和执行租约可复用。
+- 先完成本里程碑的主规范与实施计划评审，再进入代码实现。
+
+## 验收标准
+
+- [x] 后台新增模型默认 `codex`，可选择 `cc`，非法值和缺失值分别按约定拒绝/兼容。
+- [x] 后台 GET/PUT、公开模型目录和客户端选择保持 `agentMode` 一致，旧目录/旧客户端兼容为 Codex。
+- [ ] 选择 `codex` 模型仍启动现有 Codex app-server；选择 `cc` 模型启动 Claude Agent SDK sidecar，不发送 Codex JSON-RPC。
+- [x] `cc` 文本回合成功，模型 ID、Anthropic 地址和凭据不出现在用户提示、日志和错误正文。
+- [x] `cc` 只能通过 AGC 受控 MCP 使用已登记工具；拒绝越界根目录、未授权工具、原生 Bash/写文件和付费工具。
+- [x] `cc` 超时、取消、sidecar 缺失、非零退出、坏 JSON、MCP 断连都能回收进程并释放回合/租约。
+- [x] Codex、provider、自定义 LLM 和模型选择回归通过。
+
+## 证据要求
+
+- 自动化：module-runtime/API/admin-web/AGC Tauri 定向测试；前端类型检查；Rust 编译与测试。
+- 运行时：隔离临时项目的 Claude Code 中转 smoke，至少文本 + 一次受控 MCP 工具 + 取消/进程退出。
+- 边界：旧目录反序列化、非法 agentMode、模型切换绑定、配置保存不覆盖模式、无 `claude`、Anthropic 地址缺失、Codex 回归。
@@ -9171,3 +9171,9 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（弹窗层级）：个人中心的独立弹窗（`SquareImageCropModal`、`PlatformProfileModalShell` 两个壳层）改回 `UnifiedModal` 默认的页面级 portal（挂到 `document.body`），不再用 `portal={false}` 内联渲染；层级由现有 `z-[80]` 决定，仍在鉴权 / 法务 / 预览等 `z-[110]` 以上弹窗之下。`PlatformStatusDialog` 保持内联（承载运行态内嵌遮罩，不在本次范围）。
 - 影响范围：`src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`src/components/creation-home/ClientDownloadEntry.tsx`、`src/components/common/SquareImageCropModal.tsx`、`src/components/platform-entry/PlatformProfileModalShell.tsx`、`src/index.css`。
 - 验证：本地 Vite + Chromium 真机尺寸复核（320/360/375/390/414/480/639/640/768/1024）：顶栏在 320–768 全部单行、右侧留白 16px；弹窗内「上传 / 保存」`elementFromPoint` 命中自身而非底部菜单，overlay 父节点为 `BODY`。定向 Vitest（`ClientDownloadEntry`、`PlatformProfileModalShell`、`PlatformActiveProfileView`、`PlatformEntryActiveFlowShell`、`UnifiedModalPortalTheme`）与 `prettier --check`、`eslint`、`tsc`、`check:encoding` 通过。
+
+## 2026-09-30 AGC 模型绑定 Agent 执行模式
+
+- 后台 AGC 模型目录新增 `agentMode`，只允许 `codex` / `cc`，缺失的历史目录按 `codex` 兼容；模型选择返回的公开摘要同步携带该绑定。
+- 客户端把后台 `codex` 映射到现有 Codex app-server，把 `cc` 映射到独立 Claude Code CLI adapter；不通过替换 Codex JSON-RPC 可执行文件实现。
+- Claude Code 只使用隔离环境和 AGC loopback MCP，禁用原生工具；取消通过独立 Direct 回合进程树回收处理。Codex、provider 和自定义 Responses 链路保持原路径。
@@ -52,6 +52,16 @@
 - 项目右侧对话的模型选择器在对话进行中保持可交互：切换模型只写回客户端配置并作用于下一轮，当前回合不受影响；发送按钮仍由 `controlBusy` / `modelReady` 把关。
 - 自定义开关关闭时，设置页不包含模型管理或模型选择，使用官方代理锁定。

+
+## 模型绑定 Agent 执行模式
+
+- 后台 AGC 模型目录每项新增 `agentMode`，只接受 `codex` 与 `cc`；缺少该字段的历史目录按 `codex` 解释，后台新增模型默认 `codex`。
+- `codex` 仍表示现有 AGC Codex app-server 执行链路；`cc` 表示 AGC 客户端启动随包的 Claude Agent SDK sidecar，模型的 `modelId` 原样作为 Claude Agent SDK 的模型标识，不把 Claude 协议伪装成 OpenAI Responses。sidecar 随 AGC 安装包携带 SDK 及匹配平台的 Claude Code runtime，用户不需要预先安装 `claude` 命令。
+- `/api/llm/models` 的启用模型摘要返回 `agentMode`，后台完整目录、管理 DTO 和客户端目录保持同一绑定快照。客户端在选择模型时同时持久化模型 ID 与执行模式；默认模型变化、模型被停用或目录刷新回退时一并更新执行模式。
+- 客户端设置保存不得把后台模型绑定覆盖回 Codex。旧客户端配置缺少执行模式时继续按 Codex 运行；旧后台响应缺少 `agentMode` 时客户端按 Codex 兼容。
+- `cc` 执行器必须使用 Claude Agent SDK 的 Anthropic 接入方式，通过隔离的 sidecar 运行环境和受控 MCP 桥接 AGC 工具；不得开放 Claude Code 原生 Bash、任意写文件、付费或编辑器执行能力绕过 AGC 宿主门禁。当前 Codex 模式、provider 模式和自定义 LLM 行为不因新增绑定改变。
+- `cc` 模式的进程失败、超时、取消、MCP 断连和无效输出均按失败关闭，不能留下活动回合、执行租约或未确认的子进程；无法找到或启动 Claude Code 时给出可行动错误。
+
 ## 验收

 - 空目录 + 上游可达：启动后目录自动生成（`id` 为模型名 slug、`alias`/`modelId` 为上游原名、`enabled` 全为真、默认项为排序后第一项），`revision` 自增一次，`GET /api/llm/models` 的 `displayName` 就是上游原名，界面不出现任何内置模型名。