dsh-claude-code

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/<你的profile>/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

配置项

工具一览（模型可见）

claude_code 参数

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

claude_code_usage 参数

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

开发

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

两个半边：

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

发布

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 收敛到信任范围。