zhangjunjesse/dsh-claude-code

dsh-plugin npm license

dsh-claude-code

一个 DeepSeek Harness 工具插件：把自包含的编码子任务委派给本地 Claude Code 订阅执行，结果回传给 DSH。DSH 是 leader，Claude Code 是 worker。

- 走官方 Claude Agent SDK，驱动 claude CLI，不提取任何 OAuth token，合规使用订阅。
- 内置 claude-code-delegation skill（Leader-Worker 委派 SOP），装好即出现在技能目录。
- 支持 resume 跨轮记忆：把上次返回的 sessionId 传回，Claude Code 会记住之前的上下文，适合多轮迭代。
- 支持 后台异步任务：run_in_background: true 立即返回 jobId，用 DSH 自带的 job_output 流式读取实时输出。
- 内置 Claude Code 监控面板：会话头「对话 / 轨迹」右边多一个 Claude Code 标签页，紧凑单行额度栏（点开看 5h/7d 进度条 + 模型专项）+ 横向滚动的任务 tab 条（ⓘ 看完整任务 / 模型 / 统计）+ 原生风格实时输出（Markdown 直接预览 / 工具卡片 / 可折叠思考）+ 一键取消（Web 端）。
- 内置 claude_code_usage 工具：读本机 Claude 订阅额度（5 小时 / 7 天窗口、重置时间、订阅档位），派活前先看一眼。
- 支持 结构化输出（outputSchema）、成本上限（maxBudgetUsd）、追加系统提示（appendSystemPrompt）与自定义 subagents。

安装（用户侧）

方式一（最简单，自动接线）：通过 dsh 插件命令安装
dsh plugin --profile web add dsh-claude-code

方式二：手动装进 profile
cd ~/.dsh/profiles
npm install dsh-claude-code
然后在 ~/.dsh/profiles//cordis.patch.yml 里加上：
- insert:
- id: claude-code
name: 'dsh-claude-code'

装完重启 dsh。插件自带 cordis.patch.yml（dsh.bundle manifest），dsh plugin add 会用它自动接线。

接线示例（带配置）：

- insert:
- id: claude-code
name: 'dsh-claude-code'
config:
model: sonnet                # sonnet | opus | haiku | 完整 id
permissionMode: acceptEdits  # default | acceptEdits | bypassPermissions | plan | dontAsk | auto
maxTurns: 100
timeoutMs: 600000
可选：claude 可执行文件路径（SDK 会自动从 PATH 探测，一般不用配）
pathToClaudeCodeExecutable: /path/to/claude
可选：成本上限与追加指令
maxBudgetUsd: 2
appendSystemPrompt: 始终用中文写提交信息；不要碰 lib/ 目录。
可选：出网 IP 是数据中心 IP 时走本机代理（Anthropic 403 的解法）
proxy: http://127.0.0.1:7897
可选：自定义 subagents（Claude Code 内可被 Agent 工具调用）
subagents:
reviewer:
description: 复核刚写完的补丁，找出 bug 与风格问题
prompt: 你是严格的代码复核者，只报真实问题，按严重度排序。
tools: [Read, Grep, Glob]
model: sonnet

配置项

| 字段 | 默认 | 说明 |
|---|---|---|
| model | sonnet | Claude 模型别名或完整 id |
| permissionMode | acceptEdits | Claude Code 权限模式。acceptEdits 自动放行文件编辑；auto 由分类器自动批/拒；bypassPermissions 完全免确认（需信任，且要开下面的开关） |
| maxTurns | 100 | 每次任务 Claude Code 最多跑多少轮 |
| timeoutMs | 600000 | 单次调用的协作超时（后台任务同样受它约束） |
| cwd | DSH cwd | Claude Code 工作目录 |
| allowedTools | 未设 | 允许的 Claude Code 内置工具名列表 |
| pathToClaudeCodeExecutable | 自动 | claude 可执行文件路径 |
| effort | high | 思考强度：low/medium/high/xhigh/max |
| maxThinkingTokens | 未设 | 思考 token 预算上限（旧参数，建议改用 thinkingMode） |
| thinkingMode | 未设 | 思考模式：adaptive（Claude 自己决定思考量）或 disabled（关闭扩展思考）；不设即用 SDK 默认 |
| maxBudgetUsd | 未设 | 单次任务的美元成本上限，达到即停 |
| appendSystemPrompt | 未设 | 追加到 Claude Code 默认系统提示后面的额外指令 |
| allowDangerouslySkipPermissions | false | 有意的安全开关；不开时 permissionMode: bypassPermissions 会被直接拒绝 |
| proxy | 未设 | 给 claude 子进程设置的 HTTP 代理（如 http://127.0.0.1:7897），写入其 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY；出网 IP 是数据中心 IP、Anthropic 返回 403 时用它 |
| subagents | 未设 | 自定义 subagent 表：名称 → { description, prompt, tools?, disallowedTools?, model?, maxTurns?, initialPrompt?, background? }，注册到 Claude Code 的 Agent 工具 |

工具一览（模型可见）

| 工具 | 说明 |
|---|---|
| claude_code | 把一个自包含编码任务委派给本机 Claude Code；前台返回最终文本，run_in_background: true 返回 jobId |
| claude_code_usage | 读本机 Claude 订阅额度（5 小时 / 7 天窗口百分比、重置时间、各 limit 严重度、订阅档位），纯本地读取、零 token、毫秒级 |

claude_code 参数

| 参数 | 说明 |
|---|---|
| task（必填） | 自包含任务描述（目标、文件、约束、验收） |
| cwd / model / permissionMode / maxTurns / allowedTools / effort / maxThinkingTokens | 覆盖插件配置 |
| resume | 传上次返回的 sessionId，续接那个 Claude Code 会话（记住之前的上下文） |
| run_in_background | true = 转成 DSH 后台任务，立即返回 { kind: "background", jobId } |
| thinkingMode | 本次调用的思考模式：adaptive / disabled |
| maxBudgetUsd | 本次调用的美元成本上限 |
| appendSystemPrompt | 本次调用追加到默认系统提示的额外指令 |
| outputSchema | JSON Schema 对象；给了就让 Claude Code 产出结构化结果，回到 structuredOutput |
| proxy | 本次调用用的 HTTP 代理（覆盖插件配置的 proxy） |

返回：最终结果文本 + sessionId + token 用量 + 费用 + 用到的工具 + durationMs / numTurns（有 outputSchema 时还有 structuredOutput）。

claude_code_usage 参数

| 参数 | 说明 |
|---|---|
| staleAfterMinutes | 缓存超过多少分钟就标记 maybeStale，默认 30 |
| forceRefresh | 占位参数：主动刷新要真实烧一次额度，暂不支持，传了只会多一条 warning |

返回：ok / loggedIn / subscription（type、rateLimitTier、billingType）/ fiveHour / sevenDay / limits[] / spend / extraUsage / cache（fetchedAt、ageMinutes、maybeStale）/ advice（normal / caution / blocked / unknown）/ warnings[]。

数据源是 claude CLI 自己写在 ~/.claude.json 的 cachedUsageUtilization 缓存 + claude auth status --json 的登录态。不读 ~/.claude/.credentials.json，不直连 API，输出里不含邮箱 / 账号 uuid / token 等任何账号标识。它是缓存：每次 claude_code 委派都会顺带刷新它，所以刚跑完一个任务时最新鲜；超过 staleAfterMinutes 会如实标注"N 分钟前的缓存"。CLI 升级改结构时字段会降级成 null 并给 warning，不会报错。

用法示例

// 第一轮
{ "task": "修复 src/parser.ts 里 parse() 对空输入的崩溃，并加一个单元测试", "cwd": "/path/to/repo" }
// → { "ok": true, "output": "…", "sessionId": "abc-123" }

// 第二轮（迭代同一任务，带记忆）
{ "task": "上一步的修复里你漏了边界情况 X，补上并重跑测试", "resume": "abc-123" }

后台异步任务

长任务不必阻塞当前这轮对话：传 run_in_background: true，工具立刻返回 jobId，任务在 DSH 的后台任务系统里跑。

// 1) 派后台任务
{ "task": "把 src/ 全量迁移到新的 logger API，跑通 npm run build", "run_in_background": true }
// → { "kind": "background", "jobId": "claude-code-1" }

// 2) 增量读实时输出（每次只返回上次之后的新内容）
job_output { "jobId": "claude-code-1" }

// 3) 看在跑的任务 / 取消
job_list {}
job_kill { "jobId": "claude-code-1" }

- 实时输出来自 SDK 的 includePartialMessages，包含 Claude Code 的增量文本和 [tool] Name 调用标记。
- 任务结束时 DSH 自动推送完成通知，不用轮询；结束状态为 completed / failed / killed。
- 后台任务同样受 timeoutMs 约束，超时自动中止并以 failed 收尾（已产生的实时输出会保留）。
- job_output / job_list / job_kill 与完成通知由 DSH 的 dsh-tool-jobs 提供；没装它时后台模式会直接报 background jobs unavailable: load @deepseek-ai/dsh-tool-jobs。

Claude Code 监控面板（Web 端）

装好后重启 DSH，会话顶部「对话 / 轨迹」右边会多一个 Claude Code 标签页，点开整个会话体变成监控面板：

- 顶部额度栏（紧凑单行）：默认只占一行 —— 订阅档位（如 Claude Max · 20x）+ 5h 2% · 7d 3% 百分比 + 正常 / 注意 / 已阻塞状态徽标 + 刷新按钮；点这一行展开，才显示 5 小时 / 7 天两条进度条（重置时间，≥50% 转黄、≥80% 转红）、模型专项徽标（如 Fable 0%）和缓存年龄。数据来自 claude CLI 自己的本地缓存（和 claude_code_usage 工具同源），刷新只是重读缓存、不会消耗额度；挂载时读一次，之后每 5 分钟一次。
- 上方任务 tab 条：本会话的全部 claude-code 委派，一个任务一个 tab（状态色点 —— 运行中蓝色呼吸、已完成绿、已失败红、已取消灰 —— 加单行截断标题）；运行中在前（按开始时间），已结束按新到旧；任务多到放不下时 tab 条横向滚动。状态由 DSH 自带的任务推送驱动，不轮询。
- 任务详情弹框：每个 tab 上的 ⓘ 打开弹框（ESC / 点遮罩 / 关闭按钮都能关），里面是完整任务全文、模型、状态、开始 / 结束时间、耗时、费用、轮数、Claude 会话 id（可复制）和失败原因；缺省字段显示 -。点 ⓘ 不会切换选中的任务。
- 下方 Claude Code 窗口：统计条（jobId / 状态 / 轮数 / 费用 / 耗时）+ 原生风格输出——助手文本直接按 Markdown 预览（标题 / 粗体斜体 / 行内代码 / 代码块 / 有序无序列表 / 引用 / 分隔线 / 链接，每块右下角可切「原文 / 预览」；零依赖手写渲染器，全部走 React 文本节点、不用 innerHTML，链接只放行 http(s): 且 target=_blank rel=noopener noreferrer），思考块默认折叠成一行 💭（点开看全文），每次工具调用是一张卡片（工具名徽标按名字着色 + 参数 JSON 单行、点开展开为格式化全文），工具结果缩进挂在这张卡片下面（长结果截断 + 展开），任务结束是一条 ✅ 完成 · $0.13 · 12 turns · 3m20s 摘要；贴底自动滚动、上滚即暂停并给「↓ 回到底部」。没有结构化事件的任务（例如首个块之前就失败）回落到等宽文本流。
- 操作：取消（二次确认）、复制输出、复制 Claude 会话 id（可直接当 resume 用）。
- 实时输出只在「面板打开 + 选中任务还在跑」时每秒拉一次增量（结构化事件与文本流各自一个绝对游标），任务进终态后补拉一次收尾。
- 面板的读取走绝对 offset，和模型侧 job_output 的游标完全独立——你在面板里看输出不会偷走模型的字节。面板取消走插件自己的中止通道，任务照常以 killed 结算，模型仍然会收到完成通知。
- 任务只存在于当前 DSH 进程内（每会话保留最近 20 条），重启后列表为空；历史结果看对话里的工具卡片。
- 标签页在 tab 条里的位置由插件加载顺序决定（不是 order），一般就在「轨迹」右边。
- 给已装好的插件补上这个 Web 半边后必须重启 DSH：包元数据的"非 client 包"判定会被永久缓存。

错误诊断

调用前会做一次同步预检，常见问题给的是可直接照做的提示：

| 现象 | 处理 |
|---|---|
| claude executable not found | 本机没装 CLI：npm install -g @anthropic-ai/claude-code；或把 pathToClaudeCodeExecutable 指到正确路径 |
| cwd does not exist or is not a directory | cwd 写错或目录不存在，改成存在的绝对路径 |
| 认证失败 | 在终端手动跑一次 claude 完成登录，再回来调用 |
| 计费错误 | 检查 Claude 订阅状态 |
| 限流 / 过载 | 稍后重试；必要时降 effort 或拆小任务 |
| 403（出网 IP 是数据中心 IP） | 在插件配置里设 proxy（如 http://127.0.0.1:7897，指向本机 Clash 等代理），或给 DSH 进程设置 HTTPS_PROXY / HTTP_PROXY 后重启 dsh 再调用 |
| bypassPermissions 被拒 | 这是有意的安全开关：在插件配置里显式设 allowDangerouslySkipPermissions: true，或改用 acceptEdits / auto |
| 达到 maxBudgetUsd | 调高预算或缩小任务范围 |
| resume 的会话已被清理 | 去掉 resume 重新发起一次 |

合规说明

- ✅ 走 Claude Code 官方 CLI / Agent SDK，符合 Anthropic 认证与订阅政策。
- ❌ 本插件不是「把 Claude 当 DSH 的裸模型适配器」——那需要提取 Claude Code 的 OAuth token 直连 api.anthropic.com，已被 Anthropic 明令禁止、会导致封号。

开发
bash
npm install --legacy-peer-deps
npm run build       # node 半边 tsc → lib/，client 半边 esbuild → lib/client.js，再断言产物齐全
npm run typecheck   # 两个 tsconfig 都查（node + client）
两个半边：

| 半边 | 入口 | 产物 | 构建 |
|---|---|---|---|
| node（Host） | src/index.ts（+ tracker.ts / remote.ts / usage.ts） | lib/.js + lib/types/* | tsc -p tsconfig.json |
| client（Web） | src/client/index.ts | lib/client.js（单文件 CJS，外层包 window.__ModuleLoader__.load({ id: "dsh-claude-code", … })） | tsc -p tsconfig.client.json（只出 d.ts）+ scripts/build-client.mjs（esbuild） |

client bundle 只允许 require DSH shell 的 seed 白名单（react、react/jsx-runtime、@deepseek-ai/dsh-client-ui-primitives 等），构建脚本会断言这一点，其余依赖必须打进 bundle。

发布
bash
npm login
npm publish         # publishConfig.access 已设 public

发布后建议：GitHub 建仓库并给仓库打 dsh-plugin topic，即可出现在 github.com/topics/dsh-plugin。

注意

- 每次调用约 10 秒起步、按订阅计费（小任务实测约 0.1~0.2 美元），只适合"完整子任务"。
- Claude Code 自己执行工具，DSH 的沙箱/权限不套在它的工具调用上——请把 cwd 与 permissionMode 收敛到信任范围。