内容
# 副手
一个**本地编码代理协调器**。给它一个高级别的任务，它会：
1. 将任务分解为**子任务的有向无环图（DAG）**，
2. 扩展一个**自动批准的无头 Claude Code 会话**，每个子任务一个，每个会话都在自己的**git 工作树/分支**上隔离，
3. 显示**实时进度** — 既有终端 `rich` 表格，也有实时 `progress.md` 文档，在 **VSCode** 中打开并自动重新加载，
4. 运行每个子任务的**验收检查**（失败后重试一次），
5. **合并**绿色分支，并在 VSCode 中打开更改的文件，
6. 报告**可衡量的速度/精度目标**的表格。
端到端验证：串行基线 **35.7s → 协调 6.6s**（5.40 倍加速），100% 验收率，0 次合并冲突，0 次人工等待 — 参见 [RESULTS.md](RESULTS.md)。
它在单个计划批准后完全自主构建，并在出现重大偏差时重新提示。
## 设计血统
| 来源 | 副手继承的内容 |
|--------|---------------------------|
| **Nous Hermes-Agent** | 技能/记忆学习循环，可插拔执行后端（此处为 git 工作树），隔离的子代理委托以实现并行工作流 |
| **Raschka, "The Six Components of a Coding Agent"** | （1）实时仓库上下文，（2）缓存形状提示，（3）有界/结构化工具使用，（4）上下文膨胀控制，（5）结构化会话记忆，（6）有界子代理委托 |
### 组件映射
| 模块 | 角色 | 血统 |
|--------|------|---------|
| `repo_context.py` | 工作空间摘要（分支、树、文档） | Raschka #1 |
| `prompts/` | 稳定系统前缀 + 动态后缀以重用缓存 | Raschka #2 |
| `agent_session.py` + `approval.py` | 无头 `claude -p` 包装器，自动批准策略 | Raschka #3 |
| `context_budget.py` | 输出剪裁 + 分层转录减少 | Raschka #4 |
| `memory.py` | 转录 + 工作内存作为磁盘上的 JSON | Raschka #5 |
| `orchestrator.py` | DAG 波浪，有界并行代理，合并 | Raschka #6 / Hermes |
| `worktree.py` | 每个代理的 git 工作树 + 分支 | Hermes 后端 |
| `skills.py` | 蒸馏 + 回忆可重用技能 | Hermes 学习循环 |
| `dashboard.py` | 实时 `rich` 表格 + 实时 `progress.md` | — |
| `vscode.py` | 在 VSCode 中打开进度文档 + 更改的文件 | — |
| `metrics.py` | 目标计算 + 门控 | OBJECTIVES.md |
## 自动批准的工作原理
副手驱动 Claude Code **原生二进制文件**（`$CLAUDE_CODE_EXECPATH`）以无头模式运行：
```bash
claude -p "<prompt>" --output-format stream-json --verbose \
--permission-mode acceptEdits \
--allowedTools "Edit Write Read Grep Glob Bash(uv *) Bash(pytest *) …" \
--session-id <uuid> --max-turns N
```
`acceptEdits` + 显式 `--allowedTools` 允许列表自动批准编辑和范围内的构建/测试/检查/vcs 命令，同时拒绝未列出的或危险的操作 — 零人工提示（目标 **S4 = 0**），无需打开 shell 授权。
每个会话都在自己的工作树中运行，因此并行代理永远不会冲突。
三个批准级别（`--approval`）：`accept_edits_allowlist`（默认），`bypass`（`--allow-dangerously-skip-permissions`），`edits_no_bash`。
## 在 VSCode 中显示进度
生成的代理是**无头** Claude Code 子进程 — 这使得自动批准和并行扩展成为可能，并且意味着它们不会在 VSCode 边栏中显示为交互式会话（该边栏会话是用于**驱动**副手的）。进度在编辑器中显示：
- 仪表板写入实时 **`progress.md`** （`.sidekick/runs/<id>/progress.md`）— 每个代理的状态/当前操作/编辑/回合/令牌/已用时间的表格，加上结果页脚。副手使用 `code -r` 打开它；VSCode 在每次更新时自动重新加载选项卡，因此您可以从一个编辑器窗格中查看整个扩展。
- 完成后，每个已接受的子任务的**更改文件**将被打开以供审查。
- 检测是自动的（`code` CLI 在 PATH 上）；强制使用 `--vscode` / `--no-vscode` 或 `SIDEKICK_VSCODE=1|0`。相同的 `progress.md` 适用于任何编辑器或 `tail`。
您可以从 VSCode 的集成终端（或其 Claude Code 扩展终端）运行副手，并在其旁边保持 `progress.md` 打开。
## 使副手成为 VSCode 中的默认编码工作流
**首先，将副手放在 PATH 上**，以便 VSCode 任务和终端可以调用它：
```bash
cd /path/to/sidekick && uv tool install --editable . # 或：pipx install -e .
```
**一个限制：**Claude Code **边栏会话无法透明地通过副手重定向** — 扩展程序在进程中运行代理并暴露出没有重定向钩子，因此没有任何东西可以悄悄地运行在它下面。副手**驱动**无头代理；您继续使用边栏来驱动副手。了解这一点后，有三种使用模式：
### 模式 A — 自动启动 `sidekick repl` 在文件夹打开时（“默认工作流”）
复制 [`examples/vscode/tasks.json`](examples/vscode/tasks.json) → `.vscode/tasks.json` 在任何仓库中。打开文件夹会自动在专用终端中启动 **`sidekick repl`**（VSCode 询问一次以“允许自动任务”）。然后，每次：
```
sidekick> 为上传处理程序添加输入验证
```
→ 副手计划 → 扩展自动批准的代理到工作树 → 合并绿色分支，并在您旁边的编辑器选项卡中实时显示 `progress.md`。这是最接近“VSCode 始终通过副手运行”的功能。
### 模式 B — 从边栏会话驱动副手
正常使用交互式 Claude Code 边栏；当任务需要并行扩展时，告诉它运行副手，例如 *"运行 `sidekick run "在这些 4 个模块中重构 X" --yes`"*。边栏仍然是您的控制界面；副手负责并行执行并通过 `progress.md` + 打开的差异报告。
### 模式 C — 终端一行命令 / 热键
- 集成终端别名（添加到 `~/.bashrc`）：
```bash
cc() { sidekick run "$@" --yes; } # 然后： cc "为 parser.py 添加单元测试"
```
递归安全 — 副手调用 Claude 二进制文件通过其绝对 `$CLAUDE_CODE_EXECPATH`，而非 shell `claude`。
- 热键：[`examples/vscode/keybindings.json`](examples/vscode/keybindings.json) 将 `Ctrl+Alt+L` 绑定到“运行任务”提示（使用 `tasks.json` 中的第二个任务）。
### 您在编辑器中看到的内容
| 界面 | 何时 | 在哪里 |
|---------|------|-------|
| 实时 `progress.md`（每个代理的表格） | 运行期间 | 编辑器选项卡，自动重新加载 |
| `rich` 仪表板 | 运行期间 | `sidekick` 终端 |
| 每个已接受的子任务的更改文件 | 完成后 | 打开审查 |
| 目标表格（S1–S4 / A1–A4 / E1–E2） | 完成后 | `sidekick` 终端 |
使用 `--vscode` / `--no-vscode` 或 `SIDEKICK_VSCODE=1|0` 切换编辑器集成（自动从 `code` CLI 检测）。默认情况下，不为每个代理打开单独的 VSCode **窗口** — 如果需要，可以使用 `code <worktree>` 步骤设置。
## 语音输入
在 VSCode 集成终端中说出一个任务而不是输入它（它使用 `ffmpeg`/`arecord` 通过终端进程访问操作系统麦克风）。
```bash
sidekick voice # 按 Enter，说话，副手计划 → 扩展 → 合并
sidekick voice --transcribe-only # 只打印它听到的内容
sidekick repl --voice # 语音驱动的交互式循环（适用于 VSCode 任务）
```
语音转文本通过 **OpenAI 兼容的 `/audio/transcriptions`** 端点进行，因此它与编码模型（由 `claude`、`kimi`… 分支共享）无关：
| 变量 | 默认值 |
|-----|---------|
| `SIDEKICK_STT_BASE_URL` | `$OPENAI_BASE_URL` 或 `https://api.openai.com/v1` |
| `SIDEKICK_STT_API_KEY` | `$OPENAI_API_KEY` |
| `SIDEKICK_STT_MODEL` | `whisper-1` |
| `SIDEKICK_AUDIO_INPUT` | 自动（`pulse:default` / `alsa:default`） |
| `SIDEKICK_AUDIO_SECONDS` | `8` |
需要 `ffmpeg` 或 `arecord` 加上 STT 密钥；如果缺少任何一个，则会优雅地降级并显示清晰的消息。
## 用法
```bash
just setup # uv venv + 可编辑安装
sidekick plan "添加输入验证" # 查看子任务 DAG
sidekick run "添加输入验证" --yes # 扩展，自动批准，合并，报告
sidekick repl # 交互式任务循环（VSCode 自动启动）
sidekick voice # 说出一个任务；副手运行它
sidekick repl --voice # 语音驱动的循环
sidekick metrics # 目标表格来自 .sidekick/metrics.jsonl
sidekick status # 上次运行的工作内存
sidekick bench # 串行基线与协调（证明 S2）
sidekick run "..." --vscode # 强制在 VSCode 中打开进度 + 差异
sidekick run "..." --no-vscode # 仅限终端仪表板
sidekick run "..." --concurrency 5 # 更宽的扩展
```
在目标 git 仓库内运行 `sidekick`（更改会提交到该仓库的分支并合并到其当前分支）。
## 可衡量的目标
参见 [OBJECTIVES.md](OBJECTIVES.md)。`sidekick bench` 和 `sidekick metrics` 从 `metrics.jsonl` 计算 S1–S4（速度），A1–A4（准确率），E1–E2（效率）。每个优化（提示形状，上下文预算，并发量，批准策略）都通过其对该表格的影响来判断。
## 要求
- PATH 上或 `$CLAUDE_CODE_EXECPATH`（在 Claude Code 中设置）上的 Claude Code 原生二进制文件。
- `git`，Python ≥ 3.12。`rich`（声明的依赖项）用于实时仪表板。
- 通过正在运行的 Claude Code 会话的凭据（或 `ANTHROPIC_API_KEY`）进行身份验证。
- *可选：* 用于编辑器内进度文档 + 差异的 VSCode `code` CLI（自动检测；副手无需它即可正常运行）。
## 另一个 Claude Code 会话的委托
`sidekick` 可以**从另一个 Claude Code 会话中调用**，以便父会话永远不会在其工作上花费自己的上下文。两个部分：
1. **一次性全局安装**:
```bash
uv tool install /mnt/backup/projects/sidekick
```
这将 `sidekick` 放在 `PATH` 上，适用于每个 shell — 每个 Claude Code 会话（当前或未来）都可以调用它。
2. `~/.claude/skills/delegate-to-sidekick/SKILL.md` 处的**用户级技能**（也存在于此分支 — 参见 `examples/delegate-to-sidekick.SKILL.md` 获取规范副本）告诉任何 Claude Code 会话如何以及何时调用。技能由 Claude Code 自动发现；会话在可用技能列表中看到 `delegate-to-sidekick` 并可以通过 `Skill` 工具调用它。
合约是一条命令：
```bash
sidekick --repo /abs/path/to/repo run "<task>" --json --no-vscode
```
`--json` 发出 stdout 上的单个信封（架构在 SKILL.md 中记录）；`--no-vscode` 阻止实时进度文档在父会话的 IDE 中弹出窗口。信封携带 `ok`、`n_accepted/n_total`、`n_merged`、每个子任务的 `branch` 以及最近 2 KB 的每个验收检查的转录 — 足够让父会话总结并决定是否跟进。
SKILL.md 严格规则涵盖了陷阱（`--repo` 必须是绝对路径，绝不能在源代码树内调用 `uv run sidekick` 等）。
要升级此分支上拉取新更改后的全局安装：
```bash
uv tool install --reinstall /mnt/backup/projects/sidekick
```
连接信息
猜你喜欢
暂无推荐服务器