Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Manual steps: [AGENTS.md](AGENTS.md).

- **Nothing per turn.** There are no hooks and one small always-on rule (`rules/ccg-codegraph.md`). Skills (`frontend-design`, `scrapling`, `seo-page-builder`, `bt-panel`, `adsense-site-auditor`) load only when called. Output styles keep Claude Code's built-in coding instructions.
- **One main loop.** Claude plans, decides and talks to you; no router sits in front of it.
- **Other models only where they earn it:** scoped writing, or a second opinion in a fresh session. Codex-led mode (`node bin/ccg.mjs codex-mode install`) and every wrapper backend (`codex`, `claude`, `gemini`, `antigravity`, `grok`, `kimi`, `opencode`) are kept; DeepSeek Harness as a host is not.
- **Other models only where they earn it:** scoped writing, or a second opinion in a fresh session. Codex-led mode (`node bin/ccg.mjs codex-mode install`) and every wrapper backend (`codex`, `claude`, `gemini`, `antigravity`, `grok`, `kimi`, `opencode`, `pi`) are kept; Pi uses structured RPC, resumable sessions, and Pi-owned provider/context configuration ([setup](docs/pi-backend.md)); DeepSeek Harness as a host is not.

Design rules: [PRINCIPLES.md](PRINCIPLES.md).

Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ Install OpenSlime from https://github.com/Overbaker/OpenSlime. Follow AGENTS.md
- **不做每轮注入。** 没有 hook,只有一个很小的常驻规则(`rules/ccg-codegraph.md`)。技能(`frontend-design`、`scrapling`、`seo-page-builder`、`bt-panel`、`adsense-site-auditor`)只在调用时加载。输出样式保留 Claude Code 内置的编码规范。
- **单一主循环。** Claude 负责规划、决策并与你对话,前面没有路由层。
- **外部模型只用在值得的地方:** 限定范围的编写,或者在新会话里给出第二意见。
- 保留:Codex 主导模式(`node bin/ccg.mjs codex-mode install`),以及全部 wrapper 后端(`codex`、`claude`、`gemini`、`antigravity`、`grok`、`kimi`、`opencode`)。
- 保留:Codex 主导模式(`node bin/ccg.mjs codex-mode install`),以及全部 wrapper 后端(`codex`、`claude`、`gemini`、`antigravity`、`grok`、`kimi`、`opencode`、`pi`)。Pi 使用结构化 RPC 和可恢复 session;provider 与上下文窗口由 Pi 配置,[详见接入说明](docs/pi-backend.zh-CN.md)。
- 不支持:把 DeepSeek Harness 作为宿主。

设计原则见 [PRINCIPLES.md](PRINCIPLES.md)。
Expand Down
33 changes: 24 additions & 9 deletions codeagent-wrapper/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
> [根目录](../CLAUDE.md) > **codeagent-wrapper**

**Last Updated**: 2026-08-29
**Binary Version**: v5.15.0
**Binary Version**: v5.16.0
**Go Version**: 1.21+(`go.mod:1`)

---

## 模块职责

`codeagent-wrapper` 是用 Go 编写的跨平台 CLI 包装器,通过 `Backend` 接口 + `backendRegistry` 工厂将 **7 种 AI CLI 后端**(Codex / Gemini / Claude / Grok / Kimi / OpenCode / Antigravity)统一成一个标准接口。CCG 工作流系统中的 20+ 个斜杠命令通过调用它来执行多模型协作任务——Claude 作为编排层,codeagent-wrapper 负责实际派发、执行、输出解析和会话管理。
`codeagent-wrapper` 是用 Go 编写的跨平台 CLI 包装器,通过 `Backend` 接口 + `backendRegistry` 工厂将 **8 种 AI CLI 后端**(Codex / Gemini / Claude / Grok / Kimi / OpenCode / Antigravity / Pi)统一成一个标准接口。CCG 工作流系统中的 20+ 个斜杠命令通过调用它来执行多模型协作任务——Claude 作为编排层,codeagent-wrapper 负责实际派发、执行、输出解析和会话管理。

---

Expand All @@ -25,10 +25,10 @@

```bash
# 单任务模式(新会话)
codeagent-wrapper [--backend <codex|gemini|claude>] "任务文本" [工作目录]
codeagent-wrapper [--backend <codex|gemini|claude|pi>] "任务文本" [工作目录]

# stdin 模式(处理含换行/特殊字符的任务)
codeagent-wrapper [--backend <codex|gemini|claude>] - [工作目录] <<'EOF'
codeagent-wrapper [--backend <codex|gemini|claude|pi>] - [工作目录] <<'EOF'
任务文本
EOF

Expand All @@ -48,7 +48,8 @@ codeagent-wrapper --cleanup

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--backend <name>` | 指定后端:`codex`、`gemini`、`claude` | `codex` |
| `--backend <name>` | 指定后端:`codex`、`gemini`、`claude`、`antigravity`、`grok`、`kimi`、`opencode`、`pi` | `codex` |
| `--pi-model <name>` | Pi 的 `provider/model` 或唯一模型 ID;也可用 `PI_MODEL`。长上下文/provider 配置由 Pi 管理 | 空(Pi 默认) |
| `--gemini-model <name>` | Gemini 型号(仅 gemini 后端有效) | 空(后端默认) |
| `--progress` | 向 stderr 输出紧凑进度行 | 关 |
| `--with-mcp` | 让子代理加载 MCP servers。默认跳过:grok/kimi 走影子 HOME(v3.3.0),codex 注入 `-c mcp_servers={}`、gemini 注入哨兵 allowlist(v5.15.0)。⚠ **见下方「谁必须开这个 flag」** | 关 |
Expand Down Expand Up @@ -90,6 +91,8 @@ diff、明令禁改文件)与修正调用(按 file:line 改)**不开**,
| `CODEAGENT_POST_MESSAGE_DELAY` | agent_message 后等待秒数(0-60) | 5s |
| `CODEAGENT_MAX_PARALLEL_WORKERS` | 并行 worker 上限(0=不限) | 0 |
| `GEMINI_MODEL` | Gemini 型号(低优先级,CLI 参数覆盖) | 空 |
| `PI_MODEL` | Pi 模型,CLI `--pi-model` 优先;并行模式通过此变量选择 | 空 |
| `CODEAGENT_PI_COMMAND` | 覆盖 Pi 可执行文件(测试/自定义安装) | `pi` |

### 退出码

Expand Down Expand Up @@ -129,15 +132,25 @@ type Backend interface {
| `kimi` | `kimi` | `buildKimiArgs()` |
| `opencode` | `opencode` | `buildOpencodeArgs()` |
| `antigravity` / `agy` | `agy` | `buildAntigravityArgs()` |
| `pi` | `pi` | `PiBackend.BuildArgs()` |

**加一个后端**:主路径干净 —— 在 `backend.go` 写个 struct 实现 `Backend` 三方法 + 在 `config.go` 的 `backendRegistry` 注册一行即可。此外需手动碰约 12 处后端字符串特判:`server.go`(SSE 输出格式,~4 处)、`executor.go`(stdin/prompt 传递方式 `line 877-878`、`case "codex"` `line 1018`,~4 处)、`main.go`(flag 校验,~4 处)。`parser.go` 已统一(靠 JSON 事件形状识别后端,0 处特判)。若加后端变频繁,可给 `Backend` 接口加 `PromptMode()` / `SSEFormat()` 把这 12 处也收编——半天~1 天渐进重构,非大工程。
**加一个后端**:主路径干净 —— 在 `backend.go` 写个 struct 实现 `Backend` 三方法 + 在 `config.go` 的 `backendRegistry` 注册一行即可。此外需手动碰约 12 处后端字符串特判:`server.go`(SSE 输出格式,~4 处)、`executor.go`(stdin/prompt 传递方式 `line 877-878`、`case "codex"` `line 1018`,~4 处)、`main.go`(flag 校验,~4 处)。Pi 使用独立 `pi_parser.go` 解析 RPC,其余后端的 `parser.go` 靠 JSON 事件形状识别(0 处特判)。若加后端变频繁,可给 `Backend` 接口加 `PromptMode()` / `SSEFormat()` 把这 12 处也收编——半天~1 天渐进重构,非大工程。

### stdin 传递协议

当任务文本包含以下特殊字符时自动切换 stdin 模式(`main.go:22`):
- 换行 `\n`、反斜杠 `\`、双引号 `"`、单引号 `'`、反引号 `` ` ``、`$`
- 或任务文本长度 > 800 字符

Pi 始终使用 JSONL RPC stdin 发送 `get_state` 和 `prompt`,任务不会作为 argv 传给 Pi,
所以 multiline、`@` 前缀和 shell 符号均按字面量处理。`get_state` 用于发现 session ID,
`prompt` 的 response 仅表示已接收;以 `agent_settled` 为完成信号,再关闭 stdin。
assistant `text_delta` 持续流式返回,最终 assistant message 提供完整结果。RPC 拒绝、
provider 错误、重试耗尽、`error`/`aborted` stop reason 和读取错误均使任务退出非零。
resume 通过 `--session <id>` 恢复。启动时默认禁用 extensions、skills、prompt templates
和 MCP,RPC 是本地子进程(provider 可以本地或远程),并非远程 Pi server transport。
完整用户说明见 [Pi RPC 后端](../docs/pi-backend.zh-CN.md)。

Gemini 平台差异(`executor.go:864`):
- **macOS/Linux**:`-p "<任务文本>"` 直接传参(execve 保留多行 argv)
- **Windows**:omit `-p`,通过 stdin pipe 传入(cmd.exe 会截断多行参数,Issue #129)
Expand Down Expand Up @@ -185,7 +198,7 @@ id: task-b

| 文件 | 职责 |
|------|------|
| `backend.go` | `Backend` 接口;7 个实现 `CodexBackend` / `GeminiBackend` / `ClaudeBackend` / `GrokBackend` / `KimiBackend` / `OpencodeBackend` / `AntigravityBackend`;各自 `buildXxxArgs()`;`loadMinimalEnvSettings()` 读取 `~/.claude/settings.json` 注入环境变量 |
| `backend.go` | `Backend` 接口;7 个原有实现 `CodexBackend` / `GeminiBackend` / `ClaudeBackend` / `GrokBackend` / `KimiBackend` / `OpencodeBackend` / `AntigravityBackend`;各自 `buildXxxArgs()`;`loadMinimalEnvSettings()` 读取 `~/.claude/settings.json` 注入环境变量 |

### 执行层

Expand All @@ -204,6 +217,8 @@ id: task-b

| 文件 | 职责 |
|------|------|
| `pi.go` | 第 8 个 `PiBackend`;严格 RPC 参数,包含 `--session`、`--model` 和确定性隔离 flags;`buildPiRPCInput()` 序列化 stdin |
| `pi_parser.go` | `parsePiRPCStream()`——RPC 状态、错误、token/工具进度和 settled 完成协议 |
| `parser.go` | `parseJSONStreamInternal()`——流式解析 Codex / Claude / Gemini JSON 事件;提取 `agent_message`、`session_id`;支持进度回调 `onProgressCallback`、session 回调 `onSessionStartedCallback` |
| `filter.go` | `filteringWriter`——过滤 stderr 噪声行(`[STARTUP]`、`YOLO mode`、Node.js warning 等) |

Expand Down Expand Up @@ -297,8 +312,8 @@ bash build-all.sh

| 文件 | 位置 | 当前值 |
|------|------|--------|
| `codeagent-wrapper/main.go` | `version = "..."` (`main.go:17`) | `5.15.0` |
| `src/utils/installer.ts` | `EXPECTED_BINARY_VERSION = '...'` | `5.15.0` |
| `codeagent-wrapper/main.go` | `version = "..."` (`main.go:17`) | `5.16.0` |
| `src/utils/installer.ts` | `EXPECTED_BINARY_VERSION = '...'` | `5.16.0` |

两边不一致的后果:用户运行 `npx ccg-workflow update` 时无法触发 binary 重新下载,继续使用旧版 binary。

Expand Down
28 changes: 27 additions & 1 deletion codeagent-wrapper/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ type Config struct {
GrokModel string // Grok model name (empty = use default)
KimiModel string // Kimi model alias (empty = use default)
OpencodeModel string // Opencode model as provider/model (empty = use default)
PiModel string // Pi model as provider/model or unique model ID (empty = use default)
Progress bool // Emit compact progress lines to stderr
WithMCP bool // Let the sub-agent load Claude's MCP servers (slow; off by default)
}
Expand All @@ -49,6 +50,7 @@ type TaskSpec struct {
GrokModel string `json:"-"`
KimiModel string `json:"-"`
OpencodeModel string `json:"-"`
PiModel string `json:"-"`
WithMCP bool `json:"-"`
Context context.Context `json:"-"`
}
Expand Down Expand Up @@ -81,6 +83,7 @@ var backendRegistry = map[string]Backend{
"grok": GrokBackend{},
"kimi": KimiBackend{},
"opencode": OpencodeBackend{},
"pi": PiBackend{},
}

func selectBackend(name string) (Backend, error) {
Expand Down Expand Up @@ -219,6 +222,7 @@ func parseArgs() (*Config, error) {
grokModel := strings.TrimSpace(os.Getenv("GROK_MODEL"))
kimiModel := strings.TrimSpace(os.Getenv("KIMI_MODEL"))
opencodeModel := strings.TrimSpace(os.Getenv("OPENCODE_MODEL"))
piModel := strings.TrimSpace(os.Getenv("PI_MODEL"))
withMCP := envFlagEnabled("CODEAGENT_WITH_MCP")

backendName := defaultBackendName
Expand Down Expand Up @@ -310,6 +314,24 @@ func parseArgs() (*Config, error) {
}
opencodeModel = value
continue
case arg == "--pi-model":
if i+1 >= len(args) {
return nil, fmt.Errorf("--pi-model flag requires a non-empty model name")
}
value := strings.TrimSpace(args[i+1])
if value == "" {
return nil, fmt.Errorf("--pi-model flag requires a non-empty model name")
}
piModel = value
i++
continue
case strings.HasPrefix(arg, "--pi-model="):
value := strings.TrimSpace(strings.TrimPrefix(arg, "--pi-model="))
if value == "" {
return nil, fmt.Errorf("--pi-model flag requires a non-empty model name")
}
piModel = value
continue
case arg == "--with-mcp":
withMCP = true
continue
Expand Down Expand Up @@ -341,7 +363,11 @@ func parseArgs() (*Config, error) {
}
args = filtered

cfg := &Config{WorkDir: defaultWorkdir, Backend: backendName, SkipPermissions: skipPermissions, GeminiModel: geminiModel, GrokModel: grokModel, KimiModel: kimiModel, OpencodeModel: opencodeModel, Progress: progress, WithMCP: withMCP}
if backendName == "pi" && strings.HasPrefix(piModel, "-") {
return nil, fmt.Errorf("--pi-model requires a model name that does not start with '-'")
}

cfg := &Config{WorkDir: defaultWorkdir, Backend: backendName, SkipPermissions: skipPermissions, GeminiModel: geminiModel, GrokModel: grokModel, KimiModel: kimiModel, OpencodeModel: opencodeModel, PiModel: piModel, Progress: progress, WithMCP: withMCP}
cfg.MaxParallelWorkers = resolveMaxParallelWorkers()

if args[0] == "resume" {
Expand Down
Loading
Loading