## DSH 插件 README 写作规范

> 给 coding agent 写 DeepSeek Harness 插件 README 时照做的章节模板与写作规则。
> 提炼自 `dsh-agent-teams` 成品 README 的多轮迭代（功能/原理/UI/工具/安装/配置/使用/验证/限制全结构），并对照 DSH 仓库内包 README 的风格（`packages/preset`、`packages/bundle`、`packages/client/ui-workflow-run`：精炼、表格化）。

### 0. 语言与篇幅策略

- **独立插件项目**（面向安装用户，如 `dsh-agent-teams`）：中文为主，命令、工具名、标识符、字段名保留英文；解释性句子用中文。
- **DSH 仓库内包**（`packages/*/README.md`）：英文为主，一段话简介 + 分节 + 表格，每节不超过几段；仓库内 README 是给维护者/协作者的，不需要"安装/使用"教程。
- 本文模板两种场景同构：结构顺序不变，语言与详略按读者切换。
- 篇幅：独立插件 README 200–400 行封顶；超过说明某节在堆砌实现细节（见 §2 避免清单）。

### 1. 结构模板（一级标题顺序）

| 顺序 | 章节 | 写什么 | 不写什么 |
|---|---|---|---|
| 1 | 简介（标题下一段） | 一句话价值（安装后用户能做什么）+ 3–5 条核心特性（黑体关键词） | 版本历史、Roadmap、致谢 |
| 2 | `## 工作原理` | 能力接缝表格 + 数据流一句话 + 状态机一句话（见 §2） | 架构图、贴源码、实现细节堆砌 |
| 3 | `## Web UI`（如有） | 面板形态、挂载位置、交互要点、数据链路 | 每个 CSS 类、动画参数逐条 |
| 4 | `## 工具一览` | 表格：工具名 | 作用（一句话，含关键语义/边界） | 工具参数 schema 全量 |
| 5 | `## 安装` | 命令 + 生效时机（重启/HMR）+ 备选方式 | 构建链内部原理 |
| 6 | `## 配置` | 配置项表格 + 一段 YAML 示例 | 每个配置的源码出处 |
| 7 | `## 使用` | 一段话 + 1 条可直接复制的示例指令 | 完整对话脚本 |
| 8 | `## 验证` | 三层：0 真实已验记录 / 1 离线 / 2 端到端（见 §4） | 把"未验证"写成"已验证" |
| 9 | `## 已知限制` | 每条 = 现象 + 原因/影响 + 缓解（见 §5） | 自我批评、无缓解的抱怨 |
| 10 | `## License` | 许可证名 | — |

### 2. 工作原理怎么写

**开篇用能力接缝表格**（这是 DSH 插件的架构语言——一切皆插件、能力即接缝）：

```markdown
`<插件名>` 复用了 DSH 的能力接缝（capability seam）而不是重新发明：

| DSH 能力 | 插件用法 |
|---|---|
| `ctx.tools` 注册表 | 注册 N 个 `xxx_*` 工具（与 `tool-workflow` 同一注册路径） |
| `ctx.subagents.startContinuable()` | 创建成员：durable 可续聊子代理 |
| `ctx.systemPrompt.section()` | 注册使用策略提示段 |
| `ctx.httpServer.register()` | 提供面板数据路由 `/plugins/xxx/state` |
| 文件系统 | 状态持久化在 `<workspace>/.xxx/<id>/` |
```

- 表格列出**真正用到的能力**，每行"DSH 能力 → 插件用途"一句话；这是读者判断"这个插件怎么融入 DSH"的最快路径。
- 表格后补**数据流一句话**："工具执行 → 磁盘状态（真相源）→ host 快照路由 → 浮层轮询渲染。会话日志事件继续写入（重放/审计）。"（一个方向链，不要画 ASCII 大图。）
- **状态机一句话**："任务状态机：`pending → claimed → in_progress → completed | failed | cancelled`，状态迁移在白名单内校验。"（能一句话压缩的状态机绝不用多段。）
- 需要引用文件时只给**入口路径**（如 `src/snapshot.ts`），不贴代码。
- **避免**：架构图（ASCII/plantuml）、实现细节堆砌（锁、队列、重试策略）、重复仓库 AGENTS.md 已有的通用机制解释。

### 3. 安装与配置

**安装命令必须可复制**（绝对路径/明确 cd）：

```markdown
```sh
cd /path/to/<plugin>
pnpm build            # 产出 lib/
dsh plugin --profile web add /absolute/path/to/<plugin>
```
```

- 一句话说明安装后发生什么（`dsh plugin` 安装进 profile 并加入 `dsh.profile.bundles` 层列表；bundle patch 挂载主机组合行）。
- **必须写生效时机**："> 注意：`dsh plugin` 修改的是该 profile 的 `package.json`/manifest；**重启 dsh 服务后**插件才会加载。"
- 配置节用**表格 + 一段 YAML 示例**：

```markdown
| 字段 | 默认值 | 说明 |
|---|---|---|
| `stateDir` | `.agent-teams` | 状态目录名（工作区下） |
| `memberProvider` | `spawn` | 成员子代理 provider |
| `memberMaxDepth` | `1` | 成员再委派深度上限（`0` = 禁止） |
```

- **兼容性/部署差异放引用注释块**（可复用模式④），但必须基于目标部署源码：

```markdown
> 兼容性说明：本插件面向的 DSH checkout 通过 package.json `dsh.client` 与
> `exports["./client"]` 发现浏览器 bundle；若部署版本不同，请先核对其 client-modules 实现。
```

### 4. 验证章节规范（三层）

验证章节是插件 README 信任度的核心，必须**分层 + 诚实标注"已验/待验"**：

| 层 | 标题 | 内容 | 前置条件 |
|---|---|---|---|
| 0 | `### 0. 已在独立实例上真实验证` | 已真实跑通的验证清单（模型名、命令、产物证据），**每项都是发生过的事实** | 已实际执行过 |
| 1 | `### 1. 离线验证（不需要启动任何服务）` | 可复制的构建/冒烟/组合验证命令 | 无 |
| 2 | `### 2. 端到端验证（需要重启服务，请自行安排在合适时机）` | 给用户的 GUI/headless 验证步骤 | 用户安排时机 |

- **0 层记录清单模板**（照此粒度记录）：
  - headless profile 端到端：`dsh --profile headless "…"`（真实 LLM 跑通全流程）
  - 落盘/日志验证：会话日志含完整事件流（列出事件名与次数，如 `team-created ×1, member-added ×2…`）
  - UI 加载链路：浏览器名册含插件、`GET /plugins/xxx/client.js → 200`、数据路由返回形状
  - GUI 端到端：驱动真实浏览器后的面板行为（自动展开、状态更新、收起），附截图路径
- **命令规范**：全部可直接复制（`cd /path/…` 开头、注释标注预期输出如"应看到 xxx 行"）；声明"不会触碰正在运行的 profile / 不 boot 服务"的验证要写明。
- **原则**：0 层只写真实发生过的；1 层是开发者的自检入口；2 层留给用户在自己实例上复现——三个层次缺一不可，混写会毁掉信任。

### 5. 已知限制怎么写

- 每条限制 = **现象 + 原因/影响 + 缓解**，一条 bullet 内说完。例：
  - "成员只有在收到消息（被唤醒）后才行动，没有常驻轮询；……队长离线时消息留在邮箱、待队长下次操作时投递。"（现象 → 影响 → 缓解路径）
  - "成员（模型）不总是严格走工具'仪式'（如完成时不调 `update_task`）——面板如实反映事件流，可能与磁盘真相有短暂偏差；队长以 `agent_teams_status`/文件为准汇总。"
- **为什么重要**：限制节是"行为契约的负空间"——它提前回答用户必然遇到的问题（"为什么任务显示还没完成？"），防止把设计取舍误读成 bug；也是后续迭代的 TODO 清单来源。
- 写**真实限制**而非套话：设计取舍（文件级持久化、单队长单团队）、环境依赖（全局角落无 slot 时 portal 自管几何；宽屏让位、窄屏 overlay）、模型行为（不守仪式）、边界（旧会话无历史事件）。
- 每条给**缓解或指引**（"以 status 为准""待队长下次操作投递"），不写无解的抱怨。

### 6. 五条可复用模式（自 `dsh-agent-teams` 提炼）

1. **能力接缝表开篇**：架构解释永远从"DSH 能力 | 插件用法"表格开始——比任何叙述都快地建立"它怎么融入 DSH"的心智模型。
2. **验证命令全部可复制**：`cd /path/to/…` + 绝对路径 + 注释标注预期输出；用户可以直接粘贴执行，而不是"看图理解"。
3. **兼容性/部署差异用引用注释块**（`> 兼容性说明：…`）：把“目标版本怎样发现 client bundle”“哪些改动需要重启”这类一次性背景从正文隔离，正文保持干净。
4. **状态机与数据流用一句话压缩**：状态流转一行写完、数据链路一个箭头链写完——能一句话表达的状态机绝不用多段，需要展开的细节放代码/文件引用。
5. **"真实已验"放在验证章节最前并诚实分级**：0 层（我已验证，带证据）→ 1 层（离线自检）→ 2 层（你来自测）——信任来自分清"我跑过"与"你去跑"。

### 7. 完成检查清单

- [ ] 简介一句话回答了"装了这个插件用户能做什么"
- [ ] 工作原理以能力接缝表格开头，数据流/状态机各一句话
- [ ] 安装命令可直接复制，且写明了生效时机（重启）
- [ ] 配置有字段/默认值/说明表格
- [ ] 验证分三层，0 层只含真实发生过的验证（带命令与证据）
- [ ] 已知限制每条含缓解路径
- [ ] 没有贴源码、没有架构大图、没有把实现细节当卖点