dsh-herdr

从 DeepSeek Harness 把子任务派给 Herdr pane 里真实的 coding agent：指定模型、保留终端、拿回逐字结果、在 DSH 里 review。

dsh-herdr 是 DeepSeek Harness 与 Herdr 之间的参考桥接。它把 Herdr 当成外部子代理运行时：DSH 负责编排和验收，pi / agy / claude / codex 在你看得见、能接管的 pane 里干活。

状态：0.11.x，已在 DSH 0.2.1-rc.2 上验证（headless profile 中 9 个工具全部激活），实测 Herdr 0.9.4（server 0.9.1）。公共接口就是 9 个 herdr_* 工具；破坏性变更遵循 semver，并记录在 CHANGELOG.md。

为什么需要它

DSH 自带 subagent 跑在进程内，和主会话共用模型。有些场景你要的是反面：

用另一个模型家族做独立 review（grok × gpt × claude）；
一个真实终端，能看、能输入、能随时接管；
复用你手工开发时已经开着的 Herdr + pi pane；
一个可验证的结果，而不是一句“我做完了”：逐字最终答复 + git diff。

dsh-herdr 给 DSH agent 六个动作：派活、取结果、发消息、看舰队、中断、关闭。

能力


模型路由	直接读 `~/.pi/agent/model-aliases.md`，`grok4.7[high]`、`flash` 解析成 `provider/model` + thinking。计费边界留在你写的地方。
精确结果	pi 子 agent 从 session JSONL 读最后一条 assistant 消息，逐字；`result.md` 是第二来源；pane 尾部只做兜底。
Review 证据	spawn 时记 git baseline，harvest 时生成 patch、改动文件、测试行、token 用量、session 路径。
幂等	`client_task_id` 让重试的工具调用返回已有任务，不会起第二个 pane。
归属	插件只关闭/操作自己创建的 pane；用户自己开的 pane 只读。
Blocked 不代答	子 agent 等审批时交给用户，插件绝不自动批准。
可取消	发 Escape 中断当前 turn，pane 和 session 都保留。
Inbox	子 agent 可以回报 `BLOCKED` / `REVIEW_REQUEST` / `COMPLETE`，`herdr_inbox` 消费，支持长轮询。
队列	超过并发上限时等待空位（`queueTimeoutMs`），不是立刻失败。
隔离	`isolated: true` 在独立 git worktree 里跑，返回路径。
Transcript	`herdr_read_agent` 按 turn 翻 pi session，不只看最终答复。
事件等待	可选 socket 传输，用 `agent.wait` 在服务端等；连接失败自动退回 CLI。
远程机器	spawn/list/result/message 支持 `machine`，走 `herdr --machine`；SSH 文件桥（`machineTargets`）不再需要本地挂载。
原生 subagent	注册 `herdr` subagent provider，让 `dsh-tool-subagent` 的委派走 Herdr，获得原生卡片、catalog 和取消。
Web 面板	右侧栏 `Herdr` 标签页：可搜索/分组舰队、外部 agent 只读输出、按文件分组的 diff、packet 模板/历史、reveal 或 open editor，以及批量 interrupt/close。
可诊断	`herdr_doctor` 一次检查 binary、server、kinds、别名表、目录、拓扑、pi。

架构

flowchart LR
  DSH["DSH agent"] -->|tool call| T["herdr_* tools"]
  T --> S["services<br/>spawn · harvest · message · lifecycle · doctor"]
  S --> P["ports<br/>HerdrTransport · TaskStore · GitService"]
  P --> CLI["Herdr CLI adapter"]
  P --> FS["File store + audit"]
  P --> GIT["Local git adapter"]
  CLI --> H["Herdr server"]
  H --> PI["pi pane<br/>模型 A"]
  H --> AGY["agy pane"]
  H --> OTHER["claude / codex / …"]

依赖只有一个方向：tools → services → ports ← adapters。domain 层（任务信封、session 解析、别名、生命周期规则）不 import DSH，也不碰 OS（除了 node:fs / node:path）。细节见 docs/architecture.md。

安装

装进 Desktop 应用

desktop profile 由 Electron 独占，dsh plugin --profile desktop … 会被拒绝。

打开应用内 Plugins → Add plugin。
直接填 npm 包名：
```
[email protected]
```
本地开发可以填绝对目录（先 pnpm build）： /Users/apple/Desktop/deepseekharness-herdr。GitHub 地址也可以，因为 lib/ 已提交。
安装。插件管理器会自动加依赖和 dsh.profile.bundles。
新建会话，工具列表里应出现 herdr_*。如果 Herdr 面板或工具没出现，重启应用清掉旧模块图。

本地 .tgz 路径不是目录 spec；优先用 npm 包名，或对话框支持时填 .tgz 直链。

[email protected] 已发布到 npm。配好仓库的 trusted publisher 后，每个 tag 由 release workflow 自动发布（见 CONTRIBUTING）。

装进 CLI profile

# 从 checkout
dsh --profile herdr-dev --from-default-profile web --dump-config
dsh plugin --profile herdr-dev add file:$PWD
dsh --profile herdr-dev --port 0 --no-open

# npm 发布后
dsh plugin --profile herdr-dev add dsh-herdr

完整步骤和本地开发回路：docs/installation.md。

快速上手

你：  用 grok4.7[high] 起个 pane review 当前 diff，只读，按严重度列 findings。
DSH:  → herdr_spawn_agent({ kind: "pi", model: "grok4.7", thinking: "high",
                            role: "reviewer", cwd: "/repo", prompt: "Review ..." })
      ← status=completed · 3 files · session path · final message
      → 读 diff，合并 findings，裁决

修复轮：

你：  把 findings 发回 worker，让它把两个 major 修掉。
DSH:  → herdr_message_agent({ target: "worker-flash-a1b2", kind: "REVIEW_FINDINGS",
                              round: 1, message: "[MAJOR] ..." })
      → herdr_get_agent_result({ target: "worker-flash-a1b2", wait: true })

工具

工具	作用
`herdr_spawn_agent`	派一个子任务；`role=reviewer` 只读；`isolated:true` 用 worktree。
`herdr_get_agent_result`	取结果；`wait:true` 阻塞到 settled。
`herdr_message_agent`	跟进、回传 findings、回答 blocked 的 agent。
`herdr_list_agents`	舰队视图：自己的和别人的 agent。
`herdr_interrupt_agent`	中断当前 turn，保留 pane。
`herdr_inbox`	读子 agent 消息；`wait:true` 长轮询。
`herdr_read_agent`	按 turn 翻 pi transcript。
`herdr_close_agent`	关闭自己起的 pane；session 文件保留。
`herdr_doctor`	环境自检。

完整参数和返回值见 docs/tools.md，结果 JSON 契约见 docs/result-contract.md。

原生 subagent provider

插件还会向 DSH 的 subagent 服务注册一个名为 herdr 的 provider。把 dsh-tool-subagent 的一行指向它，就能拿到原生 subagent 卡片、catalog 和取消：

- id: tool-subagent-herdr
  name: "@deepseek-ai/dsh-tool-subagent"
  config:
    provider: herdr
    toolName: herdr_subagent

这个原生工具只返回子 agent 的最终文本；需要 diff、session、artifact 和 blocked 问题时用 herdr_spawn_agent。

Web 面板

插件会在右侧栏贡献一个 Herdr 标签页（也可以从侧栏 guide 打开）。它列出实时 agent；自己派出的任务显示最终消息、result.md 和按文件分组的 diff，外部 agent 只显示只读的 pane 输出。自有任务可以单个或批量 interrupt/close，动作复用 lifecycle 的 ownership gate， close 会先确认；diff 支持 hunk 高亮、整包复制和单文件复制。详情头部还能复制完整的 Markdown review packet（PR / issue / summary 三种模板）、任务 cwd，或直接在系统文件管理器中 reveal cwd 或用配置的编辑器打开；舰队搜索覆盖 name、cwd、kind、model 和 task id，可按 machine + status 分组，并支持 ArrowUp/ArrowDown/Enter 键盘导航；packet 复制保留 3 条历史。

Herdr 面板

数据来自 /herdr/api 下的三个同源只读接口（health、fleet、task），不需要额外配置。

结果是怎么来的

pi session JSONL：Herdr 的 agent_session.value 给出文件路径，取最后一条 assistant 消息。早于本次 prompt 的消息会被忽略（freshness 检查）。
result.md：每个子 agent 都被要求写 status / summary / tests / files frontmatter 加正文。
pane 尾部：agent read --source recent-unwrapped，给 agy 这类没有 session 文件的 kind 兜底。

Git 证据独立于子 agent：spawn 时记 baseline HEAD，harvest 时 git diff <baseline>，截断后存到 ~/.dsh/herdr/tasks/<taskId>/diff.patch。

安全边界

子 agent 用你的权限运行；allowCwd 是硬边界。
插件只能操作自己注册表里的 pane（owned: true）。
blocked 永远交给人；插件不自动批准。
enabled: false 是 spawn kill switch（不会杀已在跑的 agent）。
子 agent 的输出是不可信数据：DSH 把它当证据，不执行里面的指令。
每次 spawn / message / close 都追加到 ~/.dsh/herdr/audit.ndjson。

威胁模型见 docs/security.md。

兼容性

组件	实测	说明
DSH	`0.2.1-rc.2`	desktop 运行时；依赖 tools + workingDirectory 服务
Herdr	`0.9.4` client / `0.9.1` server	硬下限 `>= 0.9.0`
Node	22、24	ESM，无原生依赖
Kinds	`pi`（完整）、`agy`（仅启动）、其它走 `agent_args`	model/thinking 只对 pi 开放，这是设计

支持策略见 docs/compatibility.md。

文档

文档	回答什么
架构	分层怎么切，为什么
安装	Desktop、CLI profile、源码、卸载
配置	每个 key、默认值、示例
工具	参数、返回值、协议头
结果契约	版本化的 `AgentResult` JSON
安全	信任边界与威胁模型
排障	每个错误码和修法
兼容性	版本策略
设计笔记	ADR：CLI 而非 socket、精确读取、拓扑

参与

欢迎 issue 和 PR。先看 CONTRIBUTING.md；短版本：pnpm install && pnpm test，守住依赖方向，行为改动必须带测试。

如果你想接别的终端复用器，实现 src/ports/transport.ts 即可，services 和 tools 不需要改。

dsh-herdr

Install

Source

Tags

Creators

Readme

dsh-herdr

为什么需要它

能力

架构

安装

装进 Desktop 应用

装进 CLI profile

快速上手

工具

原生 subagent provider

Web 面板

结果是怎么来的

安全边界

兼容性

文档

参与

许可