# dsh-herdr 产品说明书

## 1. 产品定义

`dsh-herdr` 是 DeepSeek Harness（DSH）与 Herdr 之间的安全控制适配器。它让用户在 DSH 对话中通过自然语言查询和管理 Herdr 已运行的 workspace、tab、pane 和 coding agent。

它不是：

- Herdr 的替代品或 Web 版 TUI。
- 一个通用远程 shell。
- Herdr server 的进程管理器。
- DSH 与 Herdr 之间的状态同步数据库。

## 2. 目标用户

### 主要用户

- 同时运行 DSH 和 Herdr，希望从一个对话入口协调多个 coding agent 的开发者。
- 使用 Herdr 管理多个 pane，希望让 DSH 汇总状态、派发任务和等待结果的团队负责人。
- 编写自动化工作流，需要结构化 workspace、pane 和 agent 操作的 DSH 插件开发者。

### 次要用户

- 维护插件、扩展工具和兼容新 Herdr CLI 的 coding agent。
- 排查 DSH profile 安装、Herdr socket 或 agent detection 问题的运维人员。

## 3. 核心用户任务

1. 发现当前 Herdr 布局和 agent 状态。
2. 创建隔离 workspace、tab 或 pane，但不打断用户焦点。
3. 在明确的 pane 中运行命令或启动 agent。
4. 向命名 agent 发送任务并等待稳定状态。
5. 读取 pane/agent 输出，由 DSH 汇总结果。
6. 当 Herdr 未运行、目标不存在或命令失败时得到可诊断的结构化错误。

## 4. 产品原则

### Herdr 状态权威

workspace、tab、pane、agent 的 ID、状态和生命周期由 Herdr server 决定。插件不预测 ID，不缓存状态，不从 DSH 会话推导 Herdr 状态。

### 显式目标优先

任何会改变 pane 或 agent 的工具都要求明确 pane ID 或唯一 agent 名称。插件不使用其他客户端当前聚焦对象作为隐式目标。

### 默认不打扰

创建 workspace、tab 和 pane 时固定使用 `--no-focus`。用户的 Herdr TUI 焦点不应因为后台 DSH 工作流而跳转。

### 能力白名单

每个支持的 Herdr 操作对应一个独立 DSH 工具和参数 schema。不提供任意 argv 透传工具。

### 错误可诊断

Herdr CLI 非零退出不会使 DSH 工具层崩溃，而是返回 `ok: false`、退出码和 stderr。用户应能区分 server 未运行、参数错误、目标不存在和等待超时。

## 5. 当前范围（0.3.x）

### 已支持

- Workspace：list、get、create。
- Tab：list、get、create。
- Pane：list、get、read、split、run、wait-output、send-text、layout、process-info、edges。
- Agent：list、get、read、start、wait、prompt、explain。
- 诊断：doctor（版本/socket/session/列表健康检查）。
- DSH profile bundle 安装和 GitHub 直接安装。
- 结构化成功/失败结果。

### 明确不支持

- 自动启动、停止或重启 Herdr server。
- close、move、swap、focus、send-keys 等高影响操作。
- 在 DSH Web GUI 中嵌入完整 Herdr 终端。
- 远程 Herdr session 的选择和连接配置。
- 跨会话编排状态、任务队列或长期审计存储。
- 绕过 DSH 或 Herdr 自身权限、供应链和确认机制。

## 6. 成功指标

### 可用性

- 用户可以用一句自然语言完成“创建 pane -> 启动 agent -> prompt -> wait -> read”。
- 失败结果包含足以采取下一步行动的信息。
- 安装不要求用户拥有 DSH 源码 checkout。

### 安全性

- 工具不会隐式操作未知 pane。
- 创建操作不会抢焦点。
- 命令参数不经过 shell 拼接。
- 新增破坏性能力必须经过产品确认、风险设计和 ADR。

### 可维护性

- README、工具契约和源码工具清单保持一致。
- GitHub 安装包包含可运行 `lib/`。
- 新工具具备 schema 验证、argv 映射验证和真实 Herdr 验证记录。

## 7. 典型用户旅程

### 旅程 A：只读巡检

```text
列出所有 workspace、pane 和 agent；读取工作中的 agent 最近 80 行；只读，不发送输入。
```

期望：DSH 依次调用 list/read 工具，汇总状态，不改变 Herdr 布局。

### 旅程 B：创建审查 agent

```text
把 w1:p1 向右拆分，在新 pane 启动 reviewer Codex；让它审查 Git diff，等待完成并总结。
```

期望：split 返回真实 pane ID；start 使用该 ID；prompt/wait/read 使用命名 agent；全过程不抢焦点。

### 旅程 C：运行命令并等待结果

```text
在 w1:p2 运行 just test，等待出现 test result，最多 120 秒，然后读取最近 100 行。
```

期望：pane_run 发送命令和 Enter；wait-output 有界等待；read 返回上下文。

## 8. 功能优先级框架

新增功能按以下顺序判断：

1. 是否解决高频用户任务，而不是只减少一条命令。
2. 是否能通过 Herdr 稳定公开 CLI 实现。
3. 是否需要隐式焦点、任意 shell 或破坏性动作。
4. 是否可以做成显式目标、结构化 schema 和有界等待。
5. 是否需要 host UI、持久状态或跨进程 daemon；若需要，应独立设计而不是塞入当前 toolkit。

优先级：

- P0：修复安装、工具错误、误操作风险和 Herdr CLI 不兼容。
- P1：补齐安全的高频读取、创建、等待和编排能力。
- P2：交互确认、预览、操作审计和远程 session 支持。
- P3：Web UI 面板、可视化拓扑和复杂自动化。

## 9. 发布策略

- Patch：错误处理、文档、兼容性和不改变工具契约的修复。
- Minor：新增工具、可选参数或新的安全能力。
- Major：工具重命名、返回结构不兼容、默认行为或安全边界变化。

版本更新必须同步 `package.json`、README、工具契约和编译后的 `lib/`。