docs: add bilingual README (EN + CN) reflecting current codebase

Rewrite README.md in English and add README_CN.md in Chinese with language switcher links. Updated to cover all recent features: worktree isolation, skill auto-detection, dynamic agents, per-backend config, allowed/disallowed tools, stderr noise filtering, cross-platform support, and modular internal/ project structure. Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>
2026-02-28 09:23:05 +08:00 · 2026-02-10 23:13:06 +08:00
parent ebd795c583
commit 7cc7f50f46
2 changed files with 457 additions and 70 deletions
--- a/codeagent-wrapper/README.md
+++ b/codeagent-wrapper/README.md
@@ -1,97 +1,158 @@
 # codeagent-wrapper

-`codeagent-wrapper` 是一个用 Go 编写的“多后端 AI 代码代理”命令行包装器：用统一的 CLI 入口封装不同的 AI 工具后端（Codex / Claude / Gemini / Opencode），并提供一致的参数、配置与会话恢复体验。
+[English](README.md) | [中文](README_CN.md)

-入口：`cmd/codeagent/main.go`（生成二进制名：`codeagent`）和 `cmd/codeagent-wrapper/main.go`（生成二进制名：`codeagent-wrapper`）。两者行为一致。
+A multi-backend AI code agent CLI wrapper written in Go. Provides a unified CLI entry point wrapping different AI tool backends (Codex / Claude / Gemini / OpenCode) with consistent flags, configuration, skill injection, and session resumption.

-## 功能特性
+Entry point: `cmd/codeagent-wrapper/main.go` (binary: `codeagent-wrapper`).

- 多后端支持：`codex` / `claude` / `gemini` / `opencode`
- 统一命令行：`codeagent [flags] <task>` / `codeagent resume <session_id> <task> [workdir]`
- 自动 stdin：遇到换行/特殊字符/超长任务自动走 stdin，避免 shell quoting 地狱；也可显式使用 `-`
- 配置合并：支持配置文件与 `CODEAGENT_*` 环境变量（viper）
- Agent 预设：从 `~/.codeagent/models.json` 读取 backend/model/prompt 等预设
- 并行执行：`--parallel` 从 stdin 读取多任务配置，支持依赖拓扑并发执行
- 日志清理：`codeagent cleanup` 清理旧日志（日志写入系统临时目录）
+## Features

-## 安装
+- **Multi-backend support**: `codex` / `claude` / `gemini` / `opencode`
+- **Unified CLI**: `codeagent-wrapper [flags] <task>` / `codeagent-wrapper resume <session_id> <task> [workdir]`
+- **Auto stdin**: Automatically pipes via stdin when task contains newlines, special characters, or exceeds length; also supports explicit `-`
+- **Config merging**: Config files + `CODEAGENT_*` environment variables (viper)
+- **Agent presets**: Read backend/model/prompt/reasoning/yolo/allowed_tools from `~/.codeagent/models.json`
+- **Dynamic agents**: Place a `{name}.md` prompt file in `~/.codeagent/agents/` to use as an agent
+- **Skill auto-injection**: `--skills` for manual specification, or auto-detect from project tech stack (Go/Rust/Python/Node.js/Vue)
+- **Git worktree isolation**: `--worktree` executes tasks in an isolated git worktree with auto-generated task_id and branch
+- **Parallel execution**: `--parallel` reads multi-task config from stdin with dependency-aware topological concurrent execution and structured summary reports
+- **Backend config**: `backends` section in `models.json` supports per-backend `base_url` / `api_key` injection
+- **Claude tool control**: `allowed_tools` / `disallowed_tools` to restrict available tools for Claude backend
+- **Stderr noise filtering**: Automatically filters noisy stderr output from Gemini and Codex backends
+- **Log cleanup**: `codeagent-wrapper cleanup` cleans old logs (logs written to system temp directory)
+- **Cross-platform**: macOS / Linux / Windows

-要求：Go 1.21+。
+## Installation

-在仓库根目录执行：
+### Recommended (interactive installer)

 ```bash
-go install ./cmd/codeagent
-go install ./cmd/codeagent-wrapper
+npx github:cexll/myclaude
 ```

-安装后确认：
+Select the `codeagent-wrapper` module to install.
+
+### Manual build
+
+Requires: Go 1.21+.

 ```bash
-codeagent version
-codeagent-wrapper version
+# Build from source
+make build
+
+# Or install to $GOPATH/bin
+make install
 ```

-## 使用示例
-
-最简单用法（默认后端：`codex`）：
+Verify installation:

 ```bash
-codeagent "分析 internal/app/cli.go 的入口逻辑，给出改进建议"
+codeagent-wrapper --version
 ```

-指定后端：
+## Usage
+
+Basic usage (default backend: `codex`):

 ```bash
-codeagent --backend claude "解释 internal/executor/parallel_config.go 的并行配置格式"
+codeagent-wrapper "analyze the entry logic of internal/app/cli.go"
 ```

-指定工作目录（第 2 个位置参数）：
+Specify backend:

 ```bash
-codeagent "在当前 repo 下搜索潜在数据竞争" .
+codeagent-wrapper --backend claude "explain the parallel config format in internal/executor/parallel_config.go"
 ```

-显式从 stdin 读取 task（使用 `-`）：
+Specify working directory (2nd positional argument):

 ```bash
-cat task.txt | codeagent -
+codeagent-wrapper "search for potential data races in this repo" .
 ```

-恢复会话：
+Explicit stdin (using `-`):

 ```bash
-codeagent resume <session_id> "继续上次任务"
+cat task.txt | codeagent-wrapper -
 ```

-并行模式（从 stdin 读取任务配置；禁止位置参数）：
+HEREDOC (recommended for multi-line tasks):

 ```bash
-codeagent --parallel <<'EOF'
+codeagent-wrapper --backend claude - <<'EOF'
+Implement user authentication:
+- JWT tokens
+- bcrypt password hashing
+- Session management
+EOF
+```
+
+Resume session:
+
+```bash
+codeagent-wrapper resume <session_id> "continue the previous task"
+```
+
+Execute in isolated git worktree:
+
+```bash
+codeagent-wrapper --worktree "refactor the auth module"
+```
+
+Manual skill injection:
+
+```bash
+codeagent-wrapper --skills golang-base-practices "optimize database queries"
+```
+
+Parallel mode (task config from stdin):
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
 ---TASK---
 id: t1
 workdir: .
 backend: codex
 ---CONTENT---
-列出本项目的主要模块以及它们的职责。
+List the main modules and their responsibilities.
 ---TASK---
 id: t2
 dependencies: t1
 backend: claude
 ---CONTENT---
-基于 t1 的结论，提出重构风险点与建议。
+Based on t1's findings, identify refactoring risks and suggestions.
 EOF
 ```

-## 配置说明
+## CLI Flags

-### 配置文件
+| Flag | Description |
+|------|-------------|
+| `--backend <name>` | Backend selection (codex/claude/gemini/opencode) |
+| `--model <name>` | Model override |
+| `--agent <name>` | Agent preset name (from models.json or ~/.codeagent/agents/) |
+| `--prompt-file <path>` | Read prompt from file |
+| `--skills <names>` | Comma-separated skill names for spec injection |
+| `--reasoning-effort <level>` | Reasoning effort (backend-specific) |
+| `--skip-permissions` | Skip permission prompts |
+| `--dangerously-skip-permissions` | Alias for `--skip-permissions` |
+| `--worktree` | Execute in a new git worktree (auto-generates task_id) |
+| `--parallel` | Parallel task mode (config from stdin) |
+| `--full-output` | Full output in parallel mode (default: summary only) |
+| `--config <path>` | Config file path (default: `$HOME/.codeagent/config.*`) |
+| `--version`, `-v` | Print version |
+| `--cleanup` | Clean up old logs |

-默认查找路径（当 `--config` 为空时）：
+## Configuration
+
+### Config File
+
+Default search path (when `--config` is empty):

 - `$HOME/.codeagent/config.(yaml|yml|json|toml|...)`

-示例（YAML）：
+Example (YAML):

 ```yaml
 backend: codex
@@ -99,59 +160,113 @@ model: gpt-4.1
 skip-permissions: false
 ```

-也可以通过 `--config /path/to/config.yaml` 显式指定。
+Can also be specified explicitly via `--config /path/to/config.yaml`.

-### 环境变量（`CODEAGENT_*`）
+### Environment Variables (`CODEAGENT_*`)

-通过 viper 读取并自动映射 `-` 为 `_`，常用项：
+Read via viper with automatic `-` to `_` mapping:

- `CODEAGENT_BACKEND`（`codex|claude|gemini|opencode`）
- `CODEAGENT_MODEL`
- `CODEAGENT_AGENT`
- `CODEAGENT_PROMPT_FILE`
- `CODEAGENT_REASONING_EFFORT`
- `CODEAGENT_SKIP_PERMISSIONS`
- `CODEAGENT_FULL_OUTPUT`（并行模式 legacy 输出）
- `CODEAGENT_MAX_PARALLEL_WORKERS`（0 表示不限制，上限 100）
+| Variable | Description |
+|----------|-------------|
+| `CODEAGENT_BACKEND` | Backend name (codex/claude/gemini/opencode) |
+| `CODEAGENT_MODEL` | Model name |
+| `CODEAGENT_AGENT` | Agent preset name |
+| `CODEAGENT_PROMPT_FILE` | Prompt file path |
+| `CODEAGENT_REASONING_EFFORT` | Reasoning effort |
+| `CODEAGENT_SKIP_PERMISSIONS` | Skip permission prompts (default true; set `false` to disable) |
+| `CODEAGENT_FULL_OUTPUT` | Full output in parallel mode |
+| `CODEAGENT_MAX_PARALLEL_WORKERS` | Parallel worker count (0=unlimited, max 100) |
+| `CODEAGENT_TMPDIR` | Custom temp directory (for macOS permission issues) |
+| `CODEX_TIMEOUT` | Timeout in ms (default 7200000 = 2 hours) |
+| `CODEX_BYPASS_SANDBOX` | Codex sandbox bypass (default true; set `false` to disable) |
+| `DO_WORKTREE_DIR` | Reuse existing worktree directory (set by /do workflow) |

-### Agent 预设（`~/.codeagent/models.json`）
-
-可在 `~/.codeagent/models.json` 定义 agent → backend/model/prompt 等映射，用 `--agent <name>` 选择：
+### Agent Presets (`~/.codeagent/models.json`)

 ```json
 {
-  "default_backend": "opencode",
-  "default_model": "opencode/grok-code",
+  "default_backend": "codex",
+  "default_model": "gpt-4.1",
+  "backends": {
+    "codex": { "api_key": "..." },
+    "claude": { "base_url": "http://localhost:23001", "api_key": "..." }
+  },
  "agents": {
    "develop": {
      "backend": "codex",
      "model": "gpt-4.1",
      "prompt_file": "~/.codeagent/prompts/develop.md",
-      "description": "Code development"
+      "reasoning": "high",
+      "yolo": true,
+      "allowed_tools": ["Read", "Write", "Bash"],
+      "disallowed_tools": ["WebFetch"]
    }
  }
 }
 ```

-## 支持的后端
+Use `--agent <name>` to select a preset. Agents inherit `base_url` / `api_key` from the corresponding `backends` entry.

-该项目本身不内置模型能力，依赖你本机安装并可在 `PATH` 中找到对应 CLI：
+### Dynamic Agents

- `codex`：执行 `codex e ...`（默认会添加 `--dangerously-bypass-approvals-and-sandbox`；如需关闭请设置 `CODEX_BYPASS_SANDBOX=false`）
- `claude`：执行 `claude -p ... --output-format stream-json`（默认会跳过权限提示；如需开启请设置 `CODEAGENT_SKIP_PERMISSIONS=false`）
- `gemini`：执行 `gemini ... -o stream-json`（可从 `~/.gemini/.env` 加载环境变量）
- `opencode`：执行 `opencode run --format json`
+Place a `{name}.md` file in `~/.codeagent/agents/` to use it via `--agent {name}`. The Markdown file is read as the prompt, using `default_backend` and `default_model`.

-## 开发
+### Skill Auto-Detection

-```bash
-make build
-make test
-make lint
-make clean
+When no skills are specified via `--skills`, codeagent-wrapper auto-detects the tech stack from files in the working directory:
+
+| Detected Files | Injected Skills |
+|----------------|-----------------|
+| `go.mod` / `go.sum` | `golang-base-practices` |
+| `Cargo.toml` | `rust-best-practices` |
+| `pyproject.toml` / `setup.py` / `requirements.txt` | `python-best-practices` |
+| `package.json` | `vercel-react-best-practices`, `frontend-design` |
+| `vue.config.js` / `vite.config.ts` / `nuxt.config.ts` | `vue-web-app` |
+
+Skill specs are read from `~/.claude/skills/{name}/SKILL.md`, subject to a 16000-character budget.
+
+## Supported Backends
+
+This project does not embed model capabilities. It requires the corresponding CLI tools installed and available in `PATH`:
+
+| Backend | Command | Notes |
+|---------|---------|-------|
+| `codex` | `codex e ...` | Adds `--dangerously-bypass-approvals-and-sandbox` by default; set `CODEX_BYPASS_SANDBOX=false` to disable |
+| `claude` | `claude -p ... --output-format stream-json` | Skips permissions and disables setting-sources to prevent recursion; set `CODEAGENT_SKIP_PERMISSIONS=false` to enable prompts; auto-reads env and model from `~/.claude/settings.json` |
+| `gemini` | `gemini -o stream-json -y ...` | Auto-loads env vars from `~/.gemini/.env` (GEMINI_API_KEY, GEMINI_MODEL, etc.) |
+| `opencode` | `opencode run --format json` | — |
+
+## Project Structure
+
+```
+cmd/codeagent-wrapper/main.go   # CLI entry point
+internal/
+  app/          # CLI command definitions, argument parsing, main orchestration
+  backend/      # Backend abstraction and implementations (codex/claude/gemini/opencode)
+  config/       # Config loading, agent resolution, viper bindings
+  executor/     # Task execution engine: single/parallel/worktree/skill injection
+  logger/       # Structured logging system
+  parser/       # JSON stream parser
+  utils/        # Common utility functions
+  worktree/     # Git worktree management
 ```

-## 故障排查
+## Development

- macOS 下如果看到临时目录相关的 `permission denied`（例如临时可执行文件无法在 `/var/folders/.../T` 执行），可设置一个可执行的临时目录：`CODEAGENT_TMPDIR=$HOME/.codeagent/tmp`。
- `claude` 后端的 `base_url/api_key`（来自 `~/.codeagent/models.json`）会注入到子进程环境变量：`ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY`。若 `base_url` 指向本地代理（如 `localhost:23001`），请确认代理进程在运行。
+```bash
+make build    # Build binary
+make test     # Run tests
+make lint     # golangci-lint + staticcheck
+make clean    # Clean build artifacts
+make install  # Install to $GOPATH/bin
+```
+
+CI uses GitHub Actions with Go 1.21 / 1.22 matrix testing.
+
+## Troubleshooting
+
+- On macOS, if you see `permission denied` related to temp directories, set: `CODEAGENT_TMPDIR=$HOME/.codeagent/tmp`
+- `claude` backend's `base_url` / `api_key` (from `~/.codeagent/models.json` `backends.claude`) are injected as `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY` env vars
+- `gemini` backend's API key is loaded from `~/.gemini/.env`, injected as `GEMINI_API_KEY` with `GEMINI_API_KEY_AUTH_MECHANISM=bearer` auto-set
+- Exit codes: 127 = backend not found, 124 = timeout, 130 = interrupted
+- Parallel mode outputs structured summary by default; use `--full-output` for complete output when debugging