CodeBuddy 子代理 flg1217/dsh-subagent-codebuddy

dsh-subagent-codebuddy

CodeBuddy Code CLI 模型服务商 — DeepSeek Harness (dsh) 插件把腾讯 CodeBuddy CLI 以 ACP (Agent Client Protocol) 接入 dsh，注册为 codebuddy LLM provider：主代理可直接在模型选择器选用 CodeBuddy 模型，通用 subagent 工具也可委派 CodeBuddy 子代理。
完全遵循 dsh 官方扩展机制，零源码改动。

一、这是什么

codebuddy 是完整的模型供应商：

| 能力 | 说明 |
| 主代理模型 | 模型选择器出现 CodeBuddy 分组（模型目录 = codebuddy --help 解析 ∪ 配置默认模型），选中后该轮由 CodeBuddy CLI 全权驱动 |
| 子代理 provider | 通用 dsh subagent 工具可传 provider: codebuddy 委派（配合 subagent-model-selection 设置）；进程内 child agent、可并行、send_message 续聊 |
| 模型目录 | adapter 实现 listModels()（带缓存、永不抛错），主选择器与 list_subagent_models 共用 |
| 推理强度 | CLI --effort 档位（low / medium / high / xhigh / max / ultracode）暴露到 dsh 模型选择器；子代理可用 reasoning_effort 参数指定 |
| 图片输入/读取 | 输入：图片块读字节后以 ACP 原生 image 内容块（base64）随 prompt 发送（promptCapabilities.image，不落盘）；读取：按模型模态分流——多模态模型（CLI models.json 的 supportsImages: true）用 dsh 的 read_image，图片以 MCP image 内容块回到 CLI 侧模型、同时进 dsh 会话出图片卡片；仅文本/未登记模型用 read_image_agy（AGY 转述成文字）。历史种子与子代理转录里的图片经 CodeBuddy blob（内容寻址）双向原生转换，两侧均可预览 |
| 子代理可视化 | codebuddy 轮里的 Agent 委派镜像为 dsh 子会话（parentSession 血缘 + subagent/descriptor），侧边栏可点开完整转录（消息/工具/思考/任务），运行中近实时跟随 |
| 任务/todo | 走 dsh 原生 todo_write（工具桥一等公民，主轮与子代理会话都复用 dsh 的 TodoPanel 渲染）；CLI 侧 TaskCreate/TaskUpdate 已随内置工具禁用，todo-bridge 保留作旧会话重放兼容 |
| 工具桥（MCP / delegate） | 把本会话可见的 dsh 工具暴露给 CodeBuddy，使它的文件/命令类能力走 dsh 管线（审批/沙箱/审计/后台面板）。默认 mcp：dsh 起 HTTP MCP server，工具以 mcp__dsh__<名> 一等公民呈现（完整 JSON Schema 强约束）；delegate 为旧通道（dsh_<名> 合成 DelegateTool），保留作回退 |
| opt-in 工具 | subagent_codebuddy + list_codebuddy_models（registerSubagentTools: true 开启；默认关闭，推荐通用工具） |
| 压缩归属 | codebuddy 会话的压缩由 CLI 负责（dsh 的自动压缩被插件接管，不压镜像）；CLI 压完之后镜像成 dsh 的标准压缩卡，零 token（见 §三「压缩归属」） |

语义说明（主代理轮，重要）：ACP CLI 自带 agent 循环，但它的内置工具只放行 Read （spawn 传 --tools Read——读图必需，见下；delegate 模式为 DelegateTool,Read，见 §三「工具桥」）。
因此：

- 模型的工具面 = dsh 侧工具（MCP 模式下是 mcp__dsh__bash / mcp__dsh__edit / mcp__dsh__read_image …，delegate 模式下是 dsh_bash / dsh_edit …）+ CLI 原生 Read。dsh 工具调用 在 dsh 侧执行，受 dsh 的沙箱与审批约束，并进会话日志、审计与后台任务面板。
- 读图片走 CLI 原生 Read：CLI 的内置读图管线对任意模型适配（实测纯文本模型经 Read 读图也能看到图片内容），而 MCP 工具结果里的图片会被 CLI 按模型能力过滤 （function_call_result → [Image content filtered - current model does not support images]）。dsh 的 read_image 仍可用（对支持图片的模型更直接：图片经 MCP image 内容块回传，与 CLI 原生读图落点相同）；read_image_agy（AGY 转述）作为兜底与用户显式要求的选项保留。指路由尾注与 system 位下发。
模型目录（主选择器 / list_subagent_models / 设置卡「获取所有模型」）带 · 支持图片输入 / · 仅文本 后缀。
- 文本/思考/工具卡片仍以会话事件实时回传 dsh 界面。

为什么几乎全禁而不是白名单（2026-09-18）：CLI 原生工具要进 dsh 会话，必须在会话 scope 注册「回放镜像」承接；镜像注册一旦丢失，该会话的原生调用就永久报 unknown tool "cli_read" （偶发、不可复现）。全禁后这条路径不再被触发；Read 是唯一例外（读图通道，见上）。
逃生口：extraArgs 排在 --tools 之后，可用 extraArgs: ['--tools', 'default'] 覆盖本策略。
历史注记：更早的版本让 CLI 用自己的工具链、dsh 沙箱不参与——安全模型以本节为准。

二、快速开始

系统要求

- dsh >= 0.1.3-alpha.2（验证于 0.1.3-alpha.2）
- CodeBuddy CLI 已安装并登录（子进程继承登录态）
- 需运行在带 webServer 服务的 profile（如 web）：bridgeMode: mcp 依赖它挂 MCP 端点；拿不到该服务时端点不注册，--mcp-config 不注入（不会报错，但工具桥不可用）

安装插件

node scripts/link-profile.mjs # 默认装配进 web profile
或等价于:dsh plugin --profile web add <本仓库目录>

插件行由插件自带的 cordis.patch.yml（bundle patch）自动注入，默认配置开箱即用。
需要覆盖默认值时，在 profile 的 cordis.patch.yml 用同 id 覆盖：

- id: subagent-codebuddy
config:
model: <其他模型> # 默认 deepseek-v4-flash registerSubagentTools: true # 需要 opt-in 工具时开启 bridgeMode: delegate # 工具桥回退到旧通道（默认 mcp）

设置面板（设置 → 插件 → CodeBuddy）也可改模型与工具桥开关，表单值优先于本文件。

重启 dsh web 后：模型选择器出现 CodeBuddy 分组。

主代理使用

新会话 → 模型选择器 → 选中 CodeBuddy 的某个模型（如 deepseek-v4-flash）→ 正常对话。
该轮由 CodeBuddy 驱动；它的文件/命令类工具经工具桥回到 dsh 执行（见 §一「语义说明」），步骤/文本实时回传 dsh 界面。

子代理委派（通用工具）

1. 设置 → 子代理模型选择，把 codebuddy 路由加入允许列表（新顶层会话生效）： subagent-model-selection: enabled: true allowedModels:
- provider: codebuddy
model: deepseek-v4-flash

2. 主代理调 subagent 工具，传 provider: codebuddy、model: <id>（model 为精确 id，目录见 list_subagent_models 或主模型选择器）。

动态模型选择

- adapter listModels()：从 codebuddy --help 实时解析支持列表（成功缓存 10 分钟），配置默认模型始终并入目录，CLI 不可用时回退配置模型、provider 仍可选择。
- opt-in 的 list_codebuddy_models 工具提供同样数据的文本视图。

配置项

| 键 | 默认 | 含义 |
| command | codebuddy | 可执行文件（Windows 自动解析 npm cmd-shim → node <真实CLI>） |
| model | deepseek-v4-flash | 默认 CodeBuddy 模型 ID（子代理委派缺省值；主代理选择器另选） |
| permissionMode | bypassPermissions | --permission-mode：CodeBuddy 工具调用自动放行 |
| extraArgs | [] | 追加的 CodeBuddy 参数 |
| providerName | codebuddy | LLM provider 路由名 |
| toolName | subagent_codebuddy | opt-in 工具名 |
| registerSubagentTools | false | 是否注册 opt-in 委派工具（推荐用通用 subagent） |
| bridgeMode | mcp | 工具桥模式：mcp = dsh 起 HTTP MCP server、工具以 mcp__dsh__<名> 呈现（完整 schema，推荐）；delegate = 旧 DelegateTool 通道（dsh_<名>，回退用）。设置面板有同名开关，切换对新回合生效 |
| longToolCapMinutes | 30 | 静默长工具硬顶（分钟，0 = 关闭）：只影响发起后零事件的工具段（任何中间进展都会重置计时）；超顶中止本次调用并自动续跑——防止 CLI 卡死时进程泄漏、子会话回合悬空 |
| tailQuietSeconds | 5 | 尾巴窗口静默阈值（秒，0 = 关闭）：干净收尾后继续抽流，等 CLI 后台任务完成后的自发续跑 |
| tailBgQuietMinutes | 10 | 起了后台任务的回合的静默阈值（分钟） |
| tailCapMinutes | 30 | 尾巴窗口硬顶（分钟）：后台任务最长可拖着回合不闭合的时长 |

三、工作原理

主代理轮: 会话模型选择器 → codebuddy/<id> → CodebuddyLlmAdapter └─ spawn codebuddy --acp --tools Read [--mcp-config <会话专属配置>] → initialize → session/new|load → session/prompt └─ session/update(思考/文本/工具)→ 写入调用方已打开的 step └─ 工具调用回流:CLI 调 mcp__dsh__<名> ──HTTP JSON-RPC──▶ dsh MCP 端点 └─ 伪装成工具调用块灌进 dsh loop → 原生执行(审批/沙箱/事件/UI 卡片) └─ tool/result 回填 MCP 响应 ──▶ CLI 拿到结果继续子代理轮: 通用 subagent(provider: spawn) → child agent → 同一 adapter

工具桥（MCP / delegate）

CLI 内置工具只放行 Read（--tools Read，读图通道，见 §一「语义说明」），其余全部禁用，模型的能力面 = dsh 工具 + 原生 Read。
插件把当前会话可见的 dsh 工具暴露给 CLI，两条通道：

| | mcp（默认） | delegate（回退） |
| 呈现 | mcp__dsh__bash / mcp__dsh__edit … | dsh_bash / dsh_edit …（合成 DelegateTool） |
| 参数约束 | 各工具完整 JSON Schema（协议下发，强约束） | 无结构 input: object（模型端几乎零约束） |
| 传输 | dsh 起 HTTP MCP server，CLI 每回合以 --mcp-config 连接 | ACP session/request 反向调用 |
| 工具集 | tools/list 每次现取会话可见工具（不缓存） | 回合开始前批量注册 |

MCP 端点的安全约束：仅 loopback 来源 + URL 携带每进程随机 key（双重校验），挂在 dsh 自带 webserver 上（与 Web UI 同端口），不额外开监听；tools/call 另按 tools/list 的同一份工具面校验可见性。会话专属配置写在系统临时目录，权限 0600，超龄自动清扫。

客户端放弃后的结果补投（交互式工具的关键路径）：CLI 侧一旦按超时/断连放弃一次 tools/call，它的模型就永远看不到结果，而 dsh 侧不会因此中止已经注入 loop 的调用。
对交互式工具这是致命的：用户在 ask_user_question / exit_plan_mode 上作答之后，回答送达的是一个已经消失的调用——界面上「提问结束就完了」，不会有任何后续。所以端点把这类结果补投进会话：客户端确实断连过（响应未写完就 close）且调用最终完成时，把结果作为一条 notice 投进会话；会话空闲就唤起一轮（CLI 被重新 prompt，模型据此继续），忙则排队等下一步。只在客户端确实断连时才投递——那时 CLI 一定没收到响应，所以这不是重复上报。同理，转发兜底超时那句「不要盲目重跑同一命令」也会补投：它正是防止同一副作用跑两遍的关键，丢在一个已经消失的响应里等于没说。

诊断落盘：桥的关键诊断（客户端等待时长、兜底超时、回落直执、补投失败）除 console.error 外还会追加到 ~/.dsh/codebuddy/mcp-bridge.log。控制台日志会随终端滚掉，而「CLI 到底有没有放弃这次调用」必须可事后核对——其中打印的客户端等待时长就是 CLI 侧工具超时 T_client。pump.ts 的 MCP_CALL_TIMEOUT_MS 若要收紧必须以这个值为据， 不要拿尾注里那句未经验证的 30s 反推（曾这样推成 25s 并造成回归，有回归用例钉住）。

- 事件写入：adapter 检测调用方（agent-loop）已打开的 turn/step，把 ACP 的思考/文本/工具事件直写进该 step（tool/call 前先以 assistant/message 广告，严格满足 dsh 会话格式 v2 关系校验）；辅助调用（压缩/标题，带 purpose）或没有打开 step 时退化为纯 chunk 流，不写会话。
- 历史原生转换：已有对话切换到 codebuddy 时，折叠后的 dsh 历史由转换器写成 CodeBuddy 原生会话文件（~/.codebuddy/projects/<slug>/<sessionId>.jsonl： user/assistant 消息 + function_call/result 记录），再 session/load 载入——历史以原生消息进入 CodeBuddy，而不是压成一段提示词文本。载入失败自动回退「新会话 + 全量提示词」。单条消息的新会话（如子代理首次委派）直接走 session/new。
- 会话续跑：同一 dsh 会话映射到同一 ACP sessionId（session/load 回放复用，映射持久化在 ~/.dsh/codebuddy/conversations.json，服务重启可恢复）；可重试失败（静默空跑/进程退出/超时）自动恢复续跑，用尽才显式报错；切换其他模型期间的缺失轮次在续聊时自动补发。
- 假死防御：进展性 update 重置动态空闲阈值；工具在途期间暂停计时 （ACP 工具无心跳，完成即重新起算）；静默超阈值先 session/cancel、5s 后 kill。
- CodeBuddy 的模型、网络与配额由 CodeBuddy 侧负责，插件只做桥接。

压缩归属（重要）

codebuddy 会话的压缩由 CLI 负责，dsh 不参与。 这不是可选项，是架构约束：dsh 只是渲染层，真实上下文在 CLI 自己的会话文件里；而 dsh 的压力测量以 CLI 上报的 usage 为基线，它唯一能压的却是 dsh 侧的镜像消息面 —— 压完压力不降 → 下一个 step 再触发；compaction-basic 的收缩闸门（summary is not smaller than the shadowed content）在镜像面只剩旧摘要时必然拒绝，于是变成 压缩风暴（短时间内连打 20+ 次 compaction/start → compaction/end(error)），偶发成功的那几次还会把镜像面替换成摘要、把模型带偏。

实现方式（零 dsh 源码改动）：

| 路径 | 行为 |
| 自动压缩（agent/pre-step 的 pressure / agent/request-error 的 context-overflow） | 插件在 ctx.compaction 服务实例上接管 compactIfNeeded；codebuddy 路由的会话一律返回 null |
| 手动 /compact | per-agent 命令覆盖 → 转发给 CLI（跑在 runMaintenance 相位里，压缩期间消息按原生行为排队） |
| compactNow 兜底 | per-agent 覆盖没挂上时全局命令会走到它 → 同样接管，不压镜像 |
| CLI 自己压完之后 | compact-mirror 把这次压缩镜像成 dsh 的一次压缩事务 → 界面出现标准压缩卡。零 token：照抄 CLI 的摘要原文，不调用任何模型，只有本地文件读取 + 日志写入 |

镜像的两个时机与一条去重规则：
- 时机：挂在 agent/pre-step（CLI 在 step 之间压的）和 agent/turn-stopping（CLI 在回合收尾压的，最常见）。只挂前者的话，回合收尾那一次本轮再没有下一个 step，压缩卡与上下文容量都要等到下一个大轮才出现。两个时机都在 turn/end 之前，turn 归属天然正确。
- 去重：dsh 自己发起的那次压缩（手动 /compact 转发）不再镜像——命令回执已经报过它，再补一张压缩卡就是同一次压缩的两条消息。判定按时间线而不是「第几条摘要」：CLI 的摘要是惰性落盘的（手动压缩的摘要可能十几分钟后才写出），期间镜像层会先看到一条更早的、与本次无关的摘要，而它恰恰会落在手动压缩回执的旁边——用户看到的两条正是这一对。30 分钟 TTL 兜底，转发没有产出时不会永久静音镜像。

判据是会话最新一次请求的路由 provider（不是持久化的会话映射）——把 codebuddy 会话切回别的 provider 后，dsh 会恢复正常压缩。

已知限制：镜像时机与容量刷新

- 压缩卡必然出现在一轮对话的尾部。ACP 协议不报压缩事件（session/update 只有 agent_message_chunk / agent_thought_chunk / tool_call / usage_update 等类型，没有 compact 或 summary）。CLI 的压缩发生在 ACP run 内部（收到 prompt → 检查压力 → 压缩 → 落盘 → 处理 → 流式返回），对 dsh 完全不可见。镜像层只能 tail CLI 的会话文件（~/.codebuddy/projects/<slug>/<acpId>.jsonl 里的 {"type":"summary","providerData":{"source":"periodic"}} 记录），而该记录的落盘是惰性的。所以卡片最早只能在 turn-stopping（turn 收尾）弹出——这是 dsh 能读到新摘要的最早时机。除非 CLI 在 ACP 协议里增加压缩通知，否则无法更早。
- 上下文容量环（ContextMeter）不会在压缩时立即下降。容量环显示的是 contextPressure 投影的 projectedTokens，而 pressureTokens 只在 CLI 上报 usage chunk 时更新。压缩镜像是纯逻辑写（零模型调用、零 usage 事件），不产生 usage → 容量环停在最后一次请求的值，直到下一轮请求上报 usage 才降到新值。这是设计后果，不是 bug。

压缩卡不会隐藏或删除任何历史消息：被遮蔽的消息照常渲染，dsh 的历史接口不做过滤。压缩改的是 dsh 的 surface（上下文压力表，以及插件需要重建 CLI 上下文时的素材 buildPrompt / 原生 seed）。

启动自检与告警（不会再静默失效）：插件装载时自检接管是否真的落到实例上，dsh 升级若改了压缩入口，控制台会出现 [subagent-codebuddy/compact] …未生效/未安装 的 warn；正常接管时每个 codebuddy 会话播报一次 已接管 <sessionId> 的 dsh 压缩；镜像成功时播报 [subagent-codebuddy/mirror] 已把 CodeBuddy CLI 的压缩镜像到 dsh 会话 <id>…。

四、参与开发

pnpm install # 安装 typescript + vitest（PowerShell）
pnpm build # tsc 编译 → lib/（产物随仓库提交，免构建安装）
pnpm test # vitest 单元测试
pnpm typecheck # tsc --noEmit

本仓库的 pnpm install 只在开发机上可用：package.json 的 devDependencies 用了 link:<绝对路径> 形式指向 dsh 源码树（本地联调需要）。换机器前需把它们改成正常的版本号（如 >=0.1.3-alpha.2）或 workspace:*。仅使用插件（不构建）的人不受影响——运行时 lib/ 只依赖相对路径与 peerDependencies。

分发与发布

分发走 git（不做 npm publish）：使用者把本仓库目录加进 profile 即可，lib/ 已随仓库提交。

发布前检查：

1. pnpm typecheck && pnpm test 全绿；
2. pnpm build 且 lib/ 与 src/ 同步（git status 里 lib/ 的改动应与 src/ 一致——否则使用者拿到的是旧产物）；
3. README 的配置项表/能力表与实际 Config 一致；
4. git status 无遗留文件；
5. git add -A && git commit -m "..." && git push origin master。

五、许可证

MIT