/multi-agent-orchestration

codebuddy CLI（codebuddy）Worker 可行性研究

本文档为 SKILL.md 的补充参考文档，记录 CodeBuddy CLI 作为 worker backend 的可行性研究。 研究日期：2026-06-20 复测日期：2026-06-21（CodeBuddy CLI --model kimi-k2.6，书稿 worker 三轮评测场景）

⚠️ v1.18.0 变更（DEC-044，2026-07-07）：codebuddy 的 headless / -p --output-format stream-json 模式已从本 skill 移除（render-runtime-profile.sh --mode batch / --prompt-file 调用即报错）。所有 codebuddy worker 一律走交互式 codebuddy … -y + tmux send-keys。理由：tmux 的价值是交互式监控可纠偏，headless 一发跑完等于放弃监控；headless 适合的短任务本就该用同宿主 Subagent。下文凡涉及 batch -p 的段落（含 DEC-040 的 batch flag 修正、bypassPermissions 默认值等）均保留作历史参考，交互式默认 --permission-mode acceptEdits -y。

1. 概述

CodeBuddy 桌面端内置了 codebuddy CLI 二进制，功能对标 Claude Code，可以作为 multi-agent orchestration 的 worker backend 使用。核心价值是利用 CodeBuddy 桌面端的登录态和 token 额度，无需额外配置 API Key，CLI 自动复用 GUI 的认证和额度池。2026-06-21 已用 --model kimi-k2.6 跑通 writing-reviewer 书稿 worker 三轮评测。

v1.20.3 模型偏好（2026-08-05 用户实战沉淀）：

• 首选：hy3（WorkBuddy 平台自定义模型）
• 次选：deepseek-v4-flash（平台批量模型）
• 回退：deepseek-v4-pro（仅作回退，不用作主）

spawn-worker.sh 派 codebuddy worker 时按 --model hy3 → deepseek-v4-flash → deepseek-v4-pro 顺序选 model。详见 config/orchestration-personal.example.json 的 backend_model_routing.codebuddy.default_models 字段 + SKILL.md §9。

与 Claude Code 的关系：CodeBuddy 的 CLI 参数体系与 Claude Code 高度兼容（-p、--print、--output-format、--settings、--permission-mode、--worktree、--mcp-config 等），可直接沿用 SKILL.md 中对 Claude Code worker 的大部分模板。

2. 二进制位置与安装边界

默认只使用已存在的 app bundle 绝对路径。本节不授权 worker 安装桌面端、写 ~/.zshrc、创建 symlink 或修改机器环境；这些动作必须由用户明确批准精确命令。

2.1 版本验证

"/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" --version

二进制随 CodeBuddy 桌面端自动更新，无需手动升级。

2.2 PATH-less 检测（实测盲区）

which codebuddy 在 CodeBuddy 桌面端已装但未建 symlink 时会报 not found，导致 PM 误判 worker CLI 不可用。scripts/check-dependencies.sh --backend codebuddy 现有多源检测：先查 PATH，再查已知 .app bundle 路径 /Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy。检测到时直接把绝对路径交给 spawn；不得为了消除 PATH WARN 自行写 alias 或创建 symlink。

不只 CI/构建环境依赖这段检测，PM 在新机器派 worker 前也应该跑：

bash scripts/check-dependencies.sh --backend codebuddy --strict

2.3 PM 第一次跑 codebuddy worker 必读（踩坑 1 + 踩坑 3）

这两个坑在 2026-07-08 PM 派 worker A/B 时各浪费约 5 分钟，已沉淀于此，下次直接照做。

踩坑 1：codebuddy CLI 不在 PATH（Electron app 内嵌）

• 现象：which codebuddy → not found，PM 第一反应会以为没装。
• 真相：CodeBuddy 是 Electron app，CLI 嵌在 app bundle 里，路径为 /Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy。
• 已有兜底：scripts/render-runtime-profile.sh --backend codebuddy 已默认 fallback 到该绝对路径；check-dependencies.sh 也会多源检测出这个路径并给 fix 提示。
• PM 第一次该做：
  1. 先跑 bash scripts/check-dependencies.sh --backend codebuddy --strict，确认探测到绝对路径而非 not found。
  2. 只有用户明确批准修改 shell 配置时，才可把 alias 加进 ~/.zshrc： alias cbc='"/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy"'

踩坑 3：codebuddy trust dialog 偶尔卡住（auto-accept 不可靠）

• 现象：worker 启动后 30–60s 弹出 trust dialog： 1. Trust folder only / 2. Trust parent folder / 3. Trust folder and all subdirectories / 4. No, exit。

• 现状：spawn-worker.sh 标 "trust dialog detected"，但实测 30s 超时后打印 no trust dialog seen within 30s, continuing —— 实际 dialog 还在，worker 卡死在等待输入。

• 解决（PM 手动兜底）：

  # 选默认 option 1 = Trust folder only
  tmux send-keys -t <session> Enter

  或在 worker 启动前预设：

  echo y | codebuddy -p "..."   # 部分版本可用，优先手动 Enter 兜底

• PM 第一次该做：spawn 后立刻 tmux attach -t <session> 盯 30–60s，看到 dialog 直接 tmux send-keys -t <session> Enter，不要等脚本的 30s 超时。

2.4 Permission Dialog 必按 2（踩坑 5）

2026-07-08 PM 派 worker 时实测：acceptEdits + -y 并不等于完全 bypass，每个工具调用仍弹确认框，不处理 worker 直接卡死。

• 现象：即使 codebuddy --permission-mode acceptEdits -y，每个 Read / Edit / Bash 工具调用都会弹 Do you want to proceed? dialog，选项为 1. Yes / 2. Yes, don't ask again for this session (shift+tab) 等。

• 关键区别：

  • 按 1 (Yes) 只放行当前这一次 call，下一个工具调用又弹，worker 永远跑不动。
  • 按 2 (Yes, don't ask again for this session) 一次性放行整个 session，后续调用不再询问。

• 解决（PM spawn 后必做兜底）：

  # worker 启动后立刻连发 2，选"本次会话不再询问"
  tmux send-keys -t <session> 2 Enter

  如果已误按 1 卡住，再补一发 tmux send-keys -t <session> 2 Enter 即可解卡。

• PM 第一次该做：spawn 完 worker 必须立即 tmux send-keys -t <session> 2 兜底，不要等第一个工具调用卡住再处理。-y 不能替你省掉这一步。

2.5 Hooks / ping-island-bridge 冻死（踩坑 6，2026-07-10 排查确认）

⚠️ 这是 codebuddy CLI 在所有语境下全局冻死的直接根因（非 DEC-107 的"云端重定向环"非 DEC-109 的"本地认证握手"）。症状：codebuddy 任何子命令（--version、-p、doctor、交互模式）均无响应、pane 全空白、进程存活但 TUI 永不渲染。

根因:~/.codebuddy/settings.json 中 hooks 字段全部调用 ping-island-bridge → PingIslandBridge 二进制 → 连接 Unix socket /tmp/island.sock。若 Ping Island app 未在本机运行（socket 不存在），bridge 挂死 → codebuddy 启动期 SessionStart hook 触发 → 全局冻。

诊断命令:

# 1. 检查 hooks 是否存在
python3 -c "import json; d=json.load(open('~/.codebuddy/settings.json')); print(list(d.get('hooks',{}).keys()))"
# 2. 检查 Ping Island 是否运行
ls -la /tmp/island.sock  # 不存在 → 冻死根因
ps aux | grep -i "Ping.*Island"
# 3. 快速验证（去 hooks 后跑 --version）
# 如果返回版本号且不冻 → 确认是 hooks 问题

修复（永久,2026-07-10 验证生效）:

# 1. 切除 hooks（一次性操作）
python3 -c "
import json
with open('$HOME/.codebuddy/settings.json') as f:
    d = json.load(f)
d.pop('hooks', None)
with open('$HOME/.codebuddy/settings.json','w') as f:
    json.dump(d, f, indent=2, ensure_ascii=False)
"

# 2. 用干净环境启动 codebuddy（去掉 CodeBuddy 会话的干扰变量）
#    这是 spawn-worker / -p headless 的关键开关：
env -i HOME="$HOME" PATH="$PATH" LANG="zh_CN.UTF-8" TERM="$TERM" \
  codebuddy --model hy3 -p "prompt" -y

为什么需要 env -i:CodeBuddy 桌面端从子进程启动 codebuddy 时会遗传 __CFBundleIdentifier、ACC_PRODUCT_CONFIG_V3 等变量,导致 codebuddy 误判自身已在 CodeBuddy 语境、走 IPC 认证路径而挂死。env -i 摘掉所有继承变量(仅保留 HOME/PATH/LANG/TERM),让 codebuddy 按独立 CLI 模式走 cli-external-link 浏览器认证 → 首次完成浏览器授权后 token 缓存 → 后续直接复用。

2026-07-10 实测：

• hy3 -p：2 ✅
• deepseek-v4-flash -p：通过 ✅
• 前提：hooks 已切除 + env -i 隔离 + 用户已通过一次交互认证(token 缓存在 ~/.codebuddy/local_storage/)

2.6 spawn-worker 集成

注意:去 hooks 后 --version / 交互模式不冻,但 headless -p 仍需要一次交互认证缓存 token（因 auth 类型是 cli-external-link,需浏览器）。在真正的 Terminal.app 跑一次交互模式完成授权即可。

跨后端 hooks 对比（2026-07-10，DEC-111）：qoderwork（国际版，~/.qoderwork/settings.json）同样含 ping-island-bridge hooks 会冻；qoderwork-cn（国内版，~/.qoderworkcn/ 无 settings.json）不受影响、健康可用。详见 DEC-111。

3. 命令行用法

用法: codebuddy [options] [query...]

交互模式:     codebuddy                                              # 启动 REPL
             codebuddy "初始提示词"                                   # 带 prompt 启动 REPL
批处理模式:   codebuddy -p "prompt"                                  # 打印后退出
             cat task.md | codebuddy -p "分析"                        # 管道输入
继续会话:     codebuddy -c                                           # 继续最近会话
             codebuddy -c -p "prompt"                                # SDK 模式继续
恢复会话:     codebuddy -r <session-id> "prompt"                     # 恢复指定会话

3.1 关键参数速查

3.2 子命令速查

4. 模型指定方式

4.1 CodeBuddy 平台内置模型（零配置，用平台额度）

CodeBuddy 平台内置多种模型，CLI 默认继承桌面端的模型配置和额度。直接通过 --model 指定即可，无需设置任何环境变量。

已知可用模型标识

# 默认推荐：DeepSeek V4 Flash（低倍率、经济实惠）
codebuddy --model deepseek-v4-flash -p "检索相关案例" -y

# 书稿评测：Kimi K2.6
codebuddy --model kimi-k2.6 -p "审稿并修订指定章节" -y

# 复杂法律分析：DeepSeek V4 Pro
codebuddy --model deepseek-v4-pro -p "分析判决书争议焦点" -y

# 多模态任务：MiniMax M3（支持图片输入）
codebuddy --model minimax-m3 -p "分析这份合同扫描件中的风险条款" -y

# 腾讯混元带思考主力（Hy3，2026-07-08 升级为首选；codebuddy 内部路由含思考能力）
codebuddy --model hy3 -p "分析这 5 份判决书的争议焦点演化规律" -y

# 腾讯混元 agent preview（⚠️ 实测有消耗额度，不默认派发；用户特定场景才调）
codebuddy --model hy3-preview-agent -p "按模板生成 N 份合同审查意见" -y

# 自动路由（偷懒用）
codebuddy --model auto -p "分析这个法律问题" -y

腾讯混元（Hunyuan）档位速记（2026-07-08 smoke test + 用户路由推断确认）：

档位	--model	状态	适用
带思考主力	hy3	✅ 可用，codebuddy 内部路由	2026-07-08 升级为主力；通用对话 + 文书辅助 + 长逻辑链思考（用户推断 hy3 内部已统一路由到思考能力，对外显示 Hy3）；PM 直接 --model hy3 即可
Agent 预览	hy3-preview-agent	⚠️ 有消耗额度（2026-07-08 用户复核）	不默认派发；用户特定场景可 ad-hoc 调

codebuddy --help 只列出 hy3（不列 hy3-preview-agent），但 --model 实际接受 hy3 与 hy3-preview-agent。用前可短 smoke test 确认路由。

⚠️ 2026-07-22 复核提醒：hy3-preview-agent 在 2026-07-06 → 2026-07-22 期间曾被误判为"限时免费档"，用户已于 2026-07-08 复核确认实际有消耗额度。到期当天仍建议重跑 smoke test 确认新可用模型清单（可能含新档或恢复档）。

常用策略（2026-07-08 校正）：Worker 首选 hy3（codebuddy 内置带思考的主力路由，对外统一显示 Hy3，含思考能力），覆盖通用对话 / 文书辅助 / 长逻辑链推理 / 简单任务。次选：deepseek-v4-pro（深度推理）/ deepseek-v4-flash（经济快）/ kimi-k2.7（深度推理补充）；kimi-k2.6（写作审稿已验证）、minimax-m3（多模态）作场景专用。hy3-preview-agent 实测有消耗额度（用户复核），不默认派发；用户特定场景才 ad-hoc 调。具体可用模型取决于你的 CodeBuddy 订阅套餐，可在桌面端底部模型选择器或 /model 命令查看完整列表；默认选哪个见 personal config。

4.2 可选：对接自有 API Key（降本兜底，非主要场景）

设计原则：使用 CodeBuddy/QoderWork 这类平台 CLI 的核心价值是零配置吃平台额度。如果你有自己的 API Key（如 DeepSeek、Anthropic），直接用 Claude Code + 环境变量更直接，不需要绕 CodeBuddy CLI 这一层。以下仅作为极端降本或平台额度耗尽时的兜底参考。

# 如有自有 DeepSeek Key（通常不需要，直接用 Claude Code 即可）
export CODEBUDDY_BASE_URL="https://api.deepseek.com"
export CODEBUDDY_API_KEY="<your-key>"
codebuddy --model deepseek-v4-pro -p "任务" -y

4.3 环境变量速查

4.4 文生图模型

如需使用图片生成功能（worker 一般不需要）：

codebuddy --text-to-image-model your-image-model -p "任务" -y

环境变量控制：CODEBUDDY_IMAGE_GEN_ENABLED（设为 false 禁用）。

5. MCP 工具链集成

CodeBuddy CLI 支持通过 --mcp-config 加载 MCP 服务器：

# 从文件加载
codebuddy --mcp-config /path/to/mcp-servers.json -p "任务" -y

# 内联 JSON（仅通过 --settings 传入）
codebuddy --settings '{"mcpServers":{...}}' -p "任务" -y

MCP 配置也支持写入 ~/.codebuddy/mcp.json，CLI 和桌面端共用。

注意：CodeBuddy 桌面端的 MCP 连接器（飞书、腾讯文档、元典法律检索等）需要通过 GUI 授权启用。CLI 模式下，需要在 mcp.json 中预先配置和 Trust 这些连接器后才能使用。

⚠️ 2026-06-26 修正（用户澄清）：CodeBuddy CLI 接入的 MCP（华宇元典法律检索、企查查等）不是平台免费连接器，而是用户自己在外部配置的付费 API（与其它 CLI 共用同一套 key/额度）。因此：

• 这些 MCP 调用消耗用户付费 API 额度，不是 CodeBuddy 平台免费额度。
• 不需要 MCP 的 worker（如纯正文修订）务必 --strict-mcp-config --mcp-config <empty> 关掉 MCP，避免误触发付费 API（codebuddy-spawn.sh 已默认关；见 §5 + DEC-037）。
• 只有明确要用法律检索 / 工商查询的 worker 才开 MCP，且要知道在花付费额度。

5.1 MCP 相关环境变量

6. 关键限制与注意事项

6.1 SDK 环境变量冲突（类似 QoderWork）

CodeBuddy 桌面端运行时注入的 hooks 和 permission 环境变量不影响 CLI 独立运行。CLI 直接从命令行启动时不会走 SDK 模式，无需像 QoderWork 那样清除环境变量。已验证 CLI 在独立终端中可直接运行。

但如果从 CodeBuddy 桌面端的"内置终端"或 SDK 模式下启动，可能会遇到类似问题。建议始终在干净终端/tmux session 中运行 CLI worker。

6.2 权限与安全

无头模式（-p）执行涉及文件读写、命令执行、网络请求等操作时，必须加 -y（--dangerously-skip-permissions），否则操作会被阻止。

# ❌ 不加 -y 可能被阻止
codebuddy -p "写一个文件到 /tmp/test.txt"

# ✅ 正确用法
codebuddy -p -y "写一个文件到 /tmp/test.txt"

安全提示：只在受信任的环境和明确的任务中使用 -y。建议配合 --sandbox 或 worktree 隔离使用。

6.3 额度共享

CLI 和 CodeBuddy 桌面端共用 ~/.codebuddy/ 下的认证和额度池。CLI 消耗的 token 额度从同一账户扣除，不会独立计费。

6.4 会话管理

• CLI 的会话数据存储在 ~/.codebuddy/projects/{projectDir}/{sessionId}/
• 可通过 --session-id 指定固定 session ID，方便 PM 追踪
• 支持 --continue 和 --resume 恢复历史会话
• 后台 worker 通过 --bg --name <name> 启动，用 ps / logs / kill 管理

6.5 多 Worker 并发额度

多个 CLI 实例共享同一账户额度，需注意并发控制和配额分配。建议通过 SKILL.md 的 Wave-Based Orchestration 管理 provider slot。

2026-06-26 并发实测（v0.10.7 cross-model eval，历史观察）： 5 个 codebuddy worker 同时并发抢 CodeBuddy 共享额度时，hy3-preview-agent 单 run 耗时曾显著拉长（preview 模型对共享额度竞争敏感）。其余模型（kimi/deepseek/glm-5.1/glm-5v-turbo）也有不同程度的变慢。

2026-07-08 校正：早期把 hy3-preview-agent 当"限时免费档"+ "取消 ≤3 并发限制" 是基于错误假设（用户复核确认该档有消耗额度）。已从 default_models 移除，不再享受特殊待遇；本段硬约束（≤3 并发）按通用建议适用所有 codebuddy 模型。若未来再开放为真免费档，再单独评估并发策略。

通用建议（适用所有 codebuddy 模型与跨 backend）：

• codebuddy 同账户并发建议 ≤ 3（保守基线，跨模型通用）；超过时优先跨 provider 分流（一部分走 codebuddy 平台额度，一部分走 claude-code 第三方 provider 或 qoderwork 免费 Qwen 额度），而不是硬压在单一 CodeBuddy 账户上。
• 高倍率模型（opus / sonnet 等）单独给一个低并发 slot，避免被其它 worker 拖垮。
• 评测 fan-out 场景尤其要遵守：12 模型同 backend 并发会把共享额度打满，导致批数/耗时失真，污染 cross-model 经济性对比（见 eval-harness cross-model 评测方法论的"经济性对比要在额度不竞争时测"）。

6.6 历史实测归档说明

§6.6/6.7 原"2026-06-21 书稿 worker 实测"和"2026-06-26 复测更新"两段（kimi-k2.6 三轮评测、snapshot-copy-into-worktree pattern、render-runtime-profile 支持情况）已精简：

• snapshot-copy-into-worktree 已固化为通用规则，见 SKILL.md §9 + DEC-037。
• render-runtime-profile 对 codebuddy/qoderwork-cn 的支持 见 scripts/render-runtime-profile.sh --help。
• spawn 实战踩坑（权限/Enter/session 断流等）已合并到 §10。

7. tmux Worker 启动示例

7.1 非交互批处理模式（推荐）

# 基本批处理
"/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" \
  -p "$(cat /tmp/task.prompt.md)" \
  --output-format json \
  -y

# tmux 批处理（隔离执行）
tmux new-session -d \
  -s worker-workbuddy \
  -c /path/to/worktree \
  "bash -lc '/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy \
   --model deepseek-v4-flash \
   --permission-mode acceptEdits \
   -p \"\$(cat /tmp/task.prompt.md)\" \
   -y'"

7.2 交互式模式（可人工接管）

tmux new-session -d \
  -s worker-workbuddy \
  -c /path/to/worktree \
  'codebuddy --model deepseek-v4-flash --permission-mode acceptEdits'

7.3 使用 worktree 隔离（原生支持）

# CodeBuddy 原生支持 --worktree（自动创建 git worktree + 可选 tmux）
codebuddy --worktree feature/legal-research --tmux -p "任务描述" -y

7.4 后台 Worker 模式

# 启动后台 worker
codebuddy --bg --name legal-research -p "检索相关案例" -y

# 查看状态
codebuddy ps
codebuddy logs legal-research

# 附加到 worker
codebuddy attach legal-research

# 终止 worker
codebuddy kill legal-research

7.5 多模型/多 provider 路由（Worker 隔离）

# Worker A：书稿评测 / 写作审稿（Kimi K2.6）
tmux new-session -d -s worker-wb-kimi -c /path/to/worktree-A \
  'codebuddy --model kimi-k2.6 --permission-mode bypassPermissions'

# Worker B：深度推理型（V4 Pro）
tmux new-session -d -s worker-wb-pro -c /path/to/worktree-B \
  'codebuddy --model deepseek-v4-pro --permission-mode acceptEdits'

# Worker C：多模态型（MiniMax M3，处理图片/扫描件）
tmux new-session -d -s worker-mm-img -c /path/to/worktree-C \
  'codebuddy --model minimax-m3 --permission-mode acceptEdits'

# Worker D：腾讯混元带思考主力（Hy3，codebuddy 内部路由含思考能力，对外统一显示 Hy3）
tmux new-session -d -s worker-wb-hy3 -c /path/to/worktree-D \
  'codebuddy --model hy3 --permission-mode bypassPermissions'

# Worker E：腾讯混元 Agent 预览档（hy3-preview-agent，⚠️ 有消耗额度，不默认派发；用户特定场景才用）
tmux new-session -d -s worker-wb-hy3-preview -c /path/to/worktree-E \
  'codebuddy --model hy3-preview-agent --permission-mode bypassPermissions'

7.6 与 spawn-worker.sh 集成

使用正式 codebuddy backend 通过 spawn-worker.sh 启动：

bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch feature/legal-research \
  --session wb-legal-research \
  --worker-backend codebuddy \
  --runtime-profile codebuddy-kimi-k26 \
  --api-provider workbuddy \
  --model kimi-k2.6 \
  --provider-slot workbuddy-kimi-k26-1 \
  --command "bash -lc 'exec \"/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy\" --model kimi-k2.6 --permission-mode bypassPermissions --session-id wb-legal-research'"

7.7 HTTP 服务模式（REST API + Web UI）

CodeBuddy CLI 支持启动 HTTP 服务，适合需要 REST API 集成的场景：

# 启动 HTTP 服务（含 Web UI、REST API、ACP 协议）
codebuddy --serve --port 8080

# 指定监听地址
env SERVER__HOST=0.0.0.0 SERVER__PORT=8080 codebuddy --serve

8. 适用场景

9. 与现有 Skill 框架的集成建议

• backend 标识：建议写具体执行面，例如 codebuddy；profile 标识可写 codebuddy-kimi-k26 / workbuddy-deepseek / workbuddy-custom
• spawn 集成：只使用正式 --worker-backend codebuddy；backend 与真实 codebuddy 可执行命令必须一致，custom 不在当前白名单
• 权限模式：必须 --permission-mode bypassPermissions（acceptEdits 仍卡权限，-y 被覆盖；参考 §10.1）；tmux 交互式按自动化强度用 bypassPermissions
• 必加参数：无头模式下 -y 是必须的（等同 Claude Code 的 --dangerously-skip-permissions）
• checkpoint 兼容：codebuddy 本身不产生 STATUS.json，需要在 worker prompt 中明确要求 worker 自行写入 checkpoint 三件套，或靠 git status + 文件系统巡检兜底
• 额度监控：目前没有 CLI 方式查询剩余额度，需要登录 CodeBuddy 桌面端查看
• 参数相似度：与 Claude Code 的参数体系高度兼容，SKILL.md 中 Claude Code worker 的大部分模板可直接迁移，仅需将 claude 替换为 codebuddy 并调整少量参数名（如 --allowed-tools → --allowedTools、--disallowed-tools → --disallowedTools）

9.1 Worker Prompt 模板

你是 CodeBuddy CLI worker，运行在无头批处理模式。
你的任务是：[具体任务描述]

## 工作规范
- 工作完成后必须将结果写入 [输出文件路径]
- 如有 checkpoint 要求，写入 .claude/agent-sessions/ 下的 STATUS.json / RESULT.md / PATCH_SUMMARY.md
- 操作前检查 git 状态，完成后 git add + commit
- 遇到无法继续的问题时，在 RESULT.md 中记录 BLOCKED 状态和原因

## 运行约束
- 工作目录：[worktree 路径]
- 最大轮次限制已设置，请在限制内完成
- 收到权限确认提示时自动通过（已配置 --permission-mode）

9.2 与 Claude Code Worker 的关键差异

9.3 成本优化策略

1. 小额任务用轻量模型：通过 CODEBUDDY_SMALL_FAST_MODEL 指定小型模型处理翻译、格式化等轻任务
2. 复杂推理用大模型：通过 CODEBUDDY_BIG_SLOW_MODEL 指定大型模型处理法律分析、代码重构等重任务
3. 对接第三方 API 降本：将高频轻度任务路由到 DeepSeek 等低成本的第三方 API
4. 控制 max-turns：通过 --max-turns 限制 worker 最大轮次，防止跑飞浪费额度

10. codebuddy spawn 实战坑点

基于 2026-07-05 五轮 + 2026-07-08 三轮 spawn 实战（多步文本 / SVG / CLI 调研）提炼。所有派 codebuddy worker 的 PM 必读。原 §14（2026-07-08 三轮验证）内容已合并入本节。

10.1 权限机制：多步任务必须 bypassPermissions

acceptEdits 字面上只 accept edits，对读类操作（Read/Bash）和特殊路径访问的权限对话框不跳；-y（--dangerously-skip-permissions）在 acceptEdits mode 下被覆盖，不真正跳过读权限。acceptEdits 与 -y 不是叠加关系——acceptEdits 把权限策略收紧到"只放行 edit 类操作"。

• 现象：codebuddy --permission-mode acceptEdits -y 组合下，每次 bash 命令（git status / ls 等）、读 worktree 外路径（PM 投递的 worker-prompts 目录、外部素材）、特殊路径（tmux socket、跨 worktree 符链接目标）都弹权限对话框。
• --add-dir <项目根> 预授权不足：即使把项目根加进 --add-dir，只预授权文件目录访问，不覆盖工具调用层，读非文件系统路径仍问。
• 后果：多步任务（一次跑要 Read 多文件 + Bash 多次）权限循环卡死，headless worker 无人应答；单步文本任务（路径少）勉强过，路径一多即回卡死。

修复：多步任务一律 --permission-mode bypassPermissions，不要寄希望于 acceptEdits -y 或 --add-dir。acceptEdits 只适合单步 / 少路径任务（"读这一个文件改一处"）。

render-runtime-profile 不直接支持 bypassPermissions，走 launch.sh 模式（避免 inline JSON 引号被吞）：

cat > /tmp/codebuddy-bypass-launch.sh << 'EOF'
#!/bin/bash
MODEL="$1"
exec "/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" \
  --model "$MODEL" --permission-mode bypassPermissions \
  --strict-mcp-config --mcp-config '{"mcpServers":{}}' -y
EOF
chmod +x /tmp/codebuddy-bypass-launch.sh

# spawn-worker 用 launch.sh
bash scripts/spawn-worker.sh --project "$PROJECT" --branch "$BRANCH" \
  --session "$SESSION" --worker-backend codebuddy --model "$MODEL" \
  --command "bash /tmp/codebuddy-bypass-launch.sh deepseek-v4-pro" --with-sentinel

验证：tmux pane 底部应显示 ⏵⏵ bypass permissions on (shift+tab to cycle)（不是 accept edits on）。

10.2 Enter 提交：send-keys 后 Enter 被吞，需单独再发

tmux send-keys -t <session> "prompt" Enter 的 Enter 没提交 prompt——pane 显示 prompt 文本完整出现在 > 输入框里但没执行（STATUS.json 没写、git status 空、pane 仍停输入态）。这是 codebuddy 交互式 TUI 的稳定行为（三轮 spawn 全中，与 Claude Code glm worker 同坑）。

标准投递配方：

# 1) 投递 prompt 文本（用 -l 避免特殊字符被 tmux 解释）
tmux send-keys -t <session> -l "$(cat /path/to/prompt.md)"
# 2) 单独发 Enter 提交（关键：不要指望上一条命令里的 Enter）
tmux send-keys -t <session> Enter
sleep 12-15  # codebuddy TUI 启动慢，等 agent loop 起来
# 3) 兜底：再补一发 Enter（部分环境第一次 Enter 被吞）
tmux send-keys -t <session> Enter

• 用 C-m（tmux send-keys -t <session> C-m）比 Enter 更稳（绕过某些终端 keymap 差异）。
• 验证提交成功：ls <worktree>/.claude/agent-sessions/<session>/STATUS.json 出现 + pane 显示 worker 已进 agent loop（thinking / tool_use 文本出现）。
• 若补发仍卡，codebuddy session 状态混乱——TaskStop + tmux kill-session + 重 spawn。

10.3 worker 漏 commit（PM 替 commit + 记录）

实测多次：worker STATUS done + pane 回到 >，但 git log main..HEAD 空、git diff --stat 空——worker 改了文件但没 commit。违反 §5.1 Commit Cadence 硬约束（"commit 是强制的收尾步骤"）。

PM 验收补救：

cd <worktree>
git status --short  # R/RM rename + modify
git add <skill-dir>/  # stage 改动（不含 .claude/agent-sessions/）
git commit -m "feat(<skill>): v0.X.Y <任务>" \
           -m "<worker>(codebuddy) done 但漏 commit, PM 替 commit"

预防：worker prompt 必须强调"commit 是强制收尾"+ worker 完成后先 git diff --check main...HEAD 自检非空 + commit。另：worker 可能在提交后再次更新 metadata.json 完成态字段，导致未提交尾巴——若只剩本轮报告目录下的 metadata，补一个 chore(eval): finalize codebuddy metadata 提交。

10.4 PingIslandBridge hook warning（非致命）

worker 调用 TaskUpdate / TaskCreate 时报：

⚠ Hook PreToolUse [warning]
    PingIslandBridge error: The operation couldn't be completed.
    (PingIslandBridge.(unknown context at $XXX).BridgeError error 1.)

非致命——worker 后续工具调用可能继续（hook warning 不阻塞）。但导致 STATUS 更新不及时（worker 跳过 TaskUpdate 后直接 Write）。

修复：worker prompt 提醒"遇到 PingIslandBridge hook warning 时跳过 TaskUpdate，直接 Write/Edit + 用其他方式更新 STATUS"。

10.5 push origin 失败（多人并发，origin 领先）

多人 session 并发环境（如本项目 lse-v5 + fiveq-iter + lsa-rename 同期跑），worker commit 后 git push origin main 经常失败：

hint: Updates were rejected because the tip of your current branch is behind
      its remote counterpart.

PM 收口策略（不强行 push）：

1. 本地 git merge --ff-only 或 git rebase main 合到 main
2. 不 push origin（避免与别人 session 冲突）
3. 本地 main 已生效（symlink），skill 可用
4. push 待所有人 session 闲下来后协调

10.6 session 断流：权限框处理后 worker 空等不续跑

worker 执行中弹权限确认对话框，PM 选 don't-ask（option 2，session-allow）放行后，prompt 流程被打断——codebuddy 回到 > 空等，不会自动续跑原 prompt。这与 §10.2 的"Enter 不提交"叠加：PM 处理完权限框、以为 worker 会接着跑，实际 worker 在空等下一个输入。

顺跑配置：

• 权限打断后重发 prompt（最简单）：处理完权限框（tmux send-keys -t <session> 2 Enter 选 session-allow）后，按 §10.2 投递配方重发一次原 prompt。
• 或用 codebuddy -c resume：kill 当前 tmux session 后用 codebuddy -c 继续最近会话（codebuddy 会话状态存在 ~/.codebuddy/projects/{projectDir}/{sessionId}/，不随 tmux session 消失）。但 -c resume 后仍需重新投递 prompt（resume 恢复上下文，不恢复中断的执行）。
• 最佳策略：绕开权限框——用 bypassPermissions（§10.1）从根上消除权限打断，session 不会断流。

10.7 原生 --worktree --tmux 对比测方向（long-term）

CodeBuddy CLI 原生支持 --worktree --tmux（§7.3），可替代"spawn-worker.sh tmux + launch.sh"手工组合。建议对比测，未测前不替换 spawn-worker.sh：

• 现有路径（spawn-worker.sh + launch.sh + bypassPermissions）：PM 控制力强（worktree 路径 / branch / base ref / METADATA 全自定义），但步骤多（写 launch.sh + spawn + trust-auto + permission_auto + 投递 prompt + 重发 Enter）。
• 原生路径（codebuddy --worktree <name> --tmux）：codebuddy 自建 worktree + tmux session，理论上省 trust / permission 两道手工框；但 PM 对 worktree 路径 / branch 命名 / session 命名控制力弱，METADATA.json / STATUS.json 还得 PM 自己补。
• 待测项：(a) 原生是否自动跳过 §10.1 权限框（bypassPermissions 能否透传）；(b) 原生 session 命名能否被 pm-monitor.sh / wait-worker.sh 识别；(c) 原生 worktree 的 commit / branch 能否被 PM 直接收口。仅作 long-term 优化方向记录。

10.8 实战速查表

11. --add-dir 跨目录访问与 permission_auto 兜底

11.1 问题背景

codebuddy 有两层安全门：

1. 工具权限层（tool permission）：由 -y / --dangerously-skip-permissions 控制
2. 跨目录访问层（directory access）：独立的 runtime prompt，-y 不覆盖

即使带了 -y，codebuddy 读取 worktree 外文件时仍弹：

Do you want to proceed?
  1. Yes
> 2. Yes, and don't ask again for session (shift + tab)
  3. No, and tell CodeBuddy what to do differently (escape)

headless worker 无人应答，卡住。

11.2 推荐策略：任务文件放 worktree 内

最干净的解：任务文件/素材放在 worktree 内，worker 用相对路径读，不触发跨目录安全门。

# spawn 前把任务文件拷进 worktree
cp /tmp/task.prompt.md <worktree>/_task.prompt.md
# spawn 后用 worktree 内路径
tmux send-keys -t <session> -l "read ./_task.prompt.md"

11.3 若必须跨目录：--add-dir

当任务文件/素材必须留在 worktree 外时，用 --add-dir 声明允许访问的额外目录：

# render-runtime-profile 生成含 --add-dir 的命令
eval "$(bash scripts/render-runtime-profile.sh \
  --backend codebuddy \
  --model deepseek-v4-pro \
  --add-dir /tmp \
  --add-dir /Users/Shared/project-assets \
  --output shell)"

# spawn 时也传 --add-dir（写入 METADATA.json 记录）
bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch docs/ch01-agent-intro \
  --session legal-ch01 \
  --add-dir /tmp \
  --add-dir /Users/Shared/project-assets \
  --command "$WORKER_COMMAND"

render-runtime-profile.sh 会将 --add-dir 追加到 codebuddy 的 --add-dir flag；spawn-worker.sh 会将 --add-dir 写入 METADATA.json 的 add_dirs 字段供 PM 审计。

11.4 兜底：permission_auto

即使配了 --add-dir，首次访问这些目录时仍可能弹 "Do you want to proceed" prompt。spawn-worker.sh 的 permission_auto() 函数会在启动后轮询 tmux pane（最长 60s，2s 间隔），匹配该文本后自动选 option 2（session-allow）。

• 只选 session-allow，不选 bypass——session-allow 仍记录权限，且只对当前 session 有效
• 与 trust_auto 共用 --no-trust-auto opt-out 开关
• 超时后静默退出，不阻塞 worker 启动

11.5 推荐工作流总结

12. 权限与 scope 控制（settings.json，2026-07-05 补充）

来源：codebuddy 官方 settings 文档 https://www.codebuddy.cn/docs/cli/settings 用途：scope-guard fix（防 worker 越界改 docs/manuscript 等；2026-07-05 PR#209 density worker 删 manuscript 图7-7 + Wave3 codebuddy worker 改 docs/manuscript 两起越界触发）

12.1 关键字段（permissions + hooks）

配置层级：~/.codebuddy/settings.json(全局) < .codebuddy/settings.json(团队) < .codebuddy/settings.local.json(本地 gitignore) < CLI 参数。spawn 时在 worktree 写 settings.local.json。

12.2 -y 与 deny 的权衡（关键）

文档明确：disableBypassPermissionsMode: "disable" 会禁用 -y。意味着——-y（bypassPermissions）模式下 deny rules 可能不生效（bypass 跳权限检查）。要让 deny 硬拦越界，必须禁 -y。但禁 -y 后 headless worker 对非 allow 的操作弹 prompt（需 permission_auto 兜底，已有 fix）。

→ 这跟 fix1（-y 默认加，headless 零 prompt）直接冲突。不能用 deny rules + 禁 -y 的方案做 scope-guard。

12.3 PreToolUse hook（优先于 -y，scope-guard 最优方案）

hooks.PreToolUse 在工具执行前跑脚本，返回 permissionDecision: deny 可短路权限管线。

qoder 文档明确（见 07 §9）：hook permission decisions have higher priority than permission modes — even in bypass_permissions mode, a PreToolUse hook returning deny will still block execution（unbypassable）。codebuddy 作为 Claude Code fork，hooks.PreToolUse 语义一致 —— ✅ 2026-07-05 PM 实测确认：codebuddy（--permission-mode bypassPermissions/-y）与 qoder（--yolo）下 PreToolUse hook 返回 deny 都硬拦越界（unbypassable 实测确认，与 qoder 官方文档一致）。⚠️ stdin 传递坑：codebuddy/qoder 调 python3 scope-guard.py 时 stdin 不直接传（实测丢失 → scope-guard no-op → 越界不拦），必须用 scope-guard-hook.sh wrapper（cat 中转 stdin → pipe scope-guard.py），spawn-worker 已自动配 wrapper。

→ scope-guard fix 的权威方案：PreToolUse hook 检查路径白名单，不管 -y 与否都拦越界，不用禁 -y（保持 headless 零 prompt）。

12.4 scope-guard 应用（spawn-worker.sh 待实现）

spawn 时在 worktree 写 .codebuddy/settings.local.json：

{
  "trustAll": true,
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write|NotebookEdit",
      "hooks": [{
        "type": "command",
        "command": "python <skill>/scripts/scope-guard.py"
      }]
    }]
  }
}

scope-guard.py 读 stdin（tool_name + tool_input），检查 tool_input.file_path 是否匹配 scope 白名单（PM 传入的 --allow-paths），越界返回：

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "out of scope: 仅允许 <allow-paths>"}}

验收：spawn 一个 codebuddy worker（带 -y），让它改 manuscript/** → 应被 hook 硬拦（permission denied by hook），而非靠 prompt 自觉。

13. Worker 跑 captcha 任务必读：复用 sibling captcha-auto/ skill（踩坑 6）

2026-07-08 PM 实战最大瓶颈：gov-info-query 三站（共用 VL 验证码识别）频繁撞 429 Too Many Requests，自写 VL 调用既重复又易踩限流。已沉淀 sibling skill ../captcha-auto/，future worker 必须复用而非自写。

• 现象：gov-info-query 三站共用同一 VL 验证码识别通道，并发或连续请求时撞 429 too many requests，是当前最卡脖子的环节。
• 已有能力：HANDOFF.md §1 列出 sibling skill ../captcha-auto/，内含 buildVisionRequestBody 封装 + 统一的 retry / backoff 逻辑。
• Worker 纪律（强制）：
  1. 用 gov-info-query skill 遇到 captcha，先看 sibling captcha-auto/，不要自写 VL 调用、不要重复造轮子。
  2. 脚本应失败 ≤ 3 次 + 指数退避（exponential backoff）后，仍失败则降级为 JSON 输出，交 PM 人工重跑，而不是无限重试或静默卡死。
• 期望的失败处理骨架：

  # 伪代码：≤3 次重试 + 指数退避，失败则降级 JSON 让 PM 接手
  for attempt in 1 2 3; do
    resp=$(buildVisionRequestBody ... | call_vl)   # 来自 captcha-auto/
    [ "$resp" != "429" ] && break
    sleep $((2 ** attempt))   # 2s, 4s, 8s
  done
  [ "$resp" = "429" ] && echo '{"status":"captcha_failed","action":"pm_retry"}' > result.json

• PM 第一次该做：派 captcha 类 worker 时，在 prompt 里点名 ../captcha-auto/，并明确"失败 ≤3 次 + 退避 + 降级 JSON"，避免 worker 自写 VL 又撞 429。

版本记录：

• 2026-08-05：① 全文拼写校正 qodebuddy → CodeBuddy（产品名，腾讯旗下）；② 结构精简——合并旧 §10（2026-07-05 五轮）与旧 §14（2026-07-08 三轮）为新 §10「spawn 实战坑点」（按坑点类型组织，双速查表合一）；删除旧 §6.6/§6.7 历史实测段（snapshot-copy pattern 已固化为 SKILL.md §9 + DEC-037，render-runtime-profile 支持情况见 --help），保留 §6.6 指针；版本记录区由 12 条压缩为关键节点。
• 2026-07-08：腾讯混元（Hunyuan）模型支持落地——hy3 升为带思考主力首选（内部路由含思考能力，对外统一显示 Hy3），hy3-preview-agent 实测有消耗额度移出 default_models，hy3-r1 实测 400 不可用移除；default_models 收敛为 hy3 / deepseek-v4-flash / deepseek-v4-pro（§4.1）；§3.1 加 --effort 行；§7.5 多模型路由示例补 Worker D（Hy3）；spawn 投递配方补强（见新 §10.1/10.2/10.6）。
• 2026-07-05：新增 §12 权限与 scope 控制（PreToolUse hook unbypassable）；§11 --add-dir 跨目录访问与 permission_auto 兜底；§10 spawn 实战坑点首版。
• 2026-06-21：补充 kimi-k2.6 三轮书稿 worker 评测实践、CodeBuddy checkpoint/path 偏差和 metadata finalize 收口规则。
• 2026-06-20：初版，基于 CodeBuddy v2.103.3 CLI 实测编写。