# dsh-herdr 项目导航

本文是开发者和智能体接手项目时的第一入口。阅读目标是先理解产品边界，再定位代码和验证方式，避免直接在 `src/index.ts` 中堆叠工具。

## 推荐阅读顺序

1. [01-产品说明书](./01-产品说明书.md)：产品目标、用户、范围和路线图。
2. [02-架构说明书](./02-架构说明书.md)：运行链路、模块职责、安全边界和故障模型。
3. [03-工具契约](./03-工具契约.md)：24 个工具的输入、行为和风险分级。
4. [04-功能扩展指南](./04-功能扩展指南.md)：如何判断、设计和添加新功能。
5. [05-测试与发布](./05-测试与发布.md)：构建、验证、安装、版本和发布检查。
6. [06-运维与故障排查](./06-运维与故障排查.md)：`server_not_running`、pnpm 策略、peer warning 等问题。
7. [路线图](./ROADMAP.md)：后续版本方向和明确的非目标。
8. [ADR](./decisions/)：关键架构决策及其原因。

## 架构图

- [可交互 HTML 架构图](./architecture/dsh-herdr-architecture.html)
- [Archify 架构规格](./architecture/dsh-herdr.architecture.json)

HTML 是可直接在浏览器打开的独立工件，支持视图聚焦、搜索和源码证据跳转。JSON 是可维护的图源。

## 目录职责

| 路径 | 职责 | 修改时需要同步 |
| --- | --- | --- |
| `src/index.ts` | 插件入口、工具注册、schema 定义 | `lib/`、工具契约、README |
| `src/runtime.ts` | `runHerdr` 子进程封装、错误归一化、可选 CLI 超时 | `lib/runtime.js`、测试 |
| `src/argv.ts` | 每个工具到 `herdr` argv 的确定性映射 | `lib/argv.js`、argv 测试 |
| `test/` | runtime / argv / 注册的 Node 测试 | `package.json` 的 `test` 脚本 |
| `lib/` | 提交到 Git 的编译产物，供 GitHub 安装直接运行 | 必须由构建生成，不手改 |
| `package.json` | 包版本、入口、peer、DSH bundle 声明 | README 兼容性、发布记录 |
| `cordis.patch.yml` | 把插件装配进 DSH profile | 仅在插件 ID/入口变化时修改 |
| `scripts/build.sh` | 复用 DSH checkout 的 TypeScript 和类型依赖构建 | 开发环境文档 |
| `docs/` | 产品、架构、契约、测试、运维和决策 | README 导航 |
| `README.md` | 面向用户的安装、使用和安全说明 | 保持简洁，细节链接到 docs |

## 当前实现概览

项目是一个 DSH host-side toolkit 插件，不包含 Web client UI，也不持有 Herdr 状态。

```text
用户自然语言
  -> DSH 智能体选择工具
  -> DSH tools registry 校验参数
  -> dsh-herdr 构造白名单 argv
  -> Node.js execFile("herdr", args)
  -> Herdr CLI 连接本地 socket server
  -> Herdr 管理 workspace / tab / pane / agent
```

Herdr 是运行状态的唯一权威来源。插件只负责安全适配，不缓存 workspace、pane 或 agent 状态。

## 修改前检查

```bash
pwd
git status --short --branch
git log -5 --oneline
```

必须确认：

- 当前目录是 `dsh-herdr`，不是 Herdr 源码仓库。
- 工作区已有改动归属清楚，不覆盖用户改动。
- 要增加的能力在 [ROADMAP](./ROADMAP.md) 或产品范围内；若改变安全边界，先写 ADR。
- 已从当前 Herdr 源码或安装版 `herdr <group> help` 核对 CLI 契约。

## 最小验证集合

```bash
# 编译并打包
DSH_CHECKOUT=/path/to/deepseek-harness bash scripts/build.sh
npm pack --dry-run --json

# 检查 diff
git diff --check
git status --short
```

还应执行：

- 注册所有工具，检查数量和名称唯一。
- 对新增工具使用 mock `herdr` 验证 argv 映射。
- 在隔离 Herdr named session 中验证真实成功路径；不能从默认会话做破坏性测试。
- 通过 DSH profile 安装后检查插件版本和 peer dependency。

详细步骤见 [05-测试与发布](./05-测试与发布.md)。