# dsh-review-squad
[![author](https://img.shields.io/badge/author-luomeii-blue)](https://github.com/luomeii) ![tests](https://img.shields.io/badge/tests-70%20green-brightgreen) ![dsh](https://img.shields.io/badge/dsh-%3E%3D0.1.1--rc.2-orange)



[English](./README.md)

DeepSeek Harness 的**并行多角色代码评审小队**插件。

一条 `/review` 命令并行派出独立评审员子代理——**安全**、**正确性**、**测试**、**风格**——它们在严格只读模式下自己取证（读 diff、追调用链、查惯例），最后合并成一份按严重度分组的结构化报告。**每个评审员可以指定不同的模型**：安全用最强模型，风格用便宜快速模型。

## 为什么做这个

dsh 生态里的 git 类插件目前停在 diff 查看器和 worktree 清理这类浅工具；而"评审"是其他智能体生态用 star 反复投票选出的最热工作流（Claude Code 官方 security-review、compound-engineering、Superpowers 系）。dsh 的 subagent 体系——并行 spawn 子代理、按子代理路由模型、工具过滤——恰好是实现它的最佳原语。

## 安装

```bash
# 装进某个 profile（默认 profile 是 `web`）
dsh plugin --profile web add dsh-review-squad
```

或直接从 GitHub 源码安装：

```bash
dsh plugin --profile web add github:<owner>/dsh-review-squad
```

要求 dsh ≥ 0.1.1-rc.2（base bundle 自带 `spawn` 子代理 provider 与 `tool-str-replace-editor`）。

## 使用

### 斜杠命令（你发起）

```
/review                          # 全阵容评审未提交变更（git diff HEAD）
/review staged                   # 只评审已暂存变更
/review commit abc1234           # 评审某个提交
/review path src/lib             # 评审某个路径
/review security tests           # 只跑指定评审员
/review --style                  # 除 style 外全跑
/review stop                       # 中止本会话正在跑的评审任务（及时止损）
/review 注意重试逻辑             # 附加关注点，附给所有评审员
```

### 工具（模型发起）

模型会拿到 `code_review` 工具，可在宣布任务完成前对小队自检：

| 参数 | 含义 |
|---|---|
| `scope` | `diff`（默认）· `staged` · `commit:<sha>` · `path:<目录或文件>` |
| `focus` | 附给所有评审员的额外关注点 |
| `reviewers` | 逗号分隔的评审员 key，`--key` 表示排除 |

### 后台执行

`/review` 默认作为**后台任务**运行（`commandBackground: true`）：命令立即返回任务 id，评审期间**输入框完全可用**。任务完成时会话 agent 会收到通知，用 `job_output`（或直接对模型说“读取评审任务结果”）取报告。想改为前台等待：在 settings.yaml 的 `review-squad:` 节设 `commandBackground: false`。`code_review` 工具始终前台（模型需要内联结果）。

### 报告长什么样

```markdown
# Code review report — uncommitted changes
Reviewers: security, correctness, tests, style · findings: 5

| severity | count |
|---|---|
| CRITICAL | 1 |

## CRITICAL
- **SQL injection in user lookup — `src/db/users.ts:42` *(security)***

## Reviewer verdicts
- **security**: Would block merging: yes, because of the injection.
...
```

单个评审员失败（超时/ refusal / max-tokens）会单独成节说明（停止原因 + 诊断 + 部分输出），不会拖垮整场。报告是**确定性聚合**，不额外调一次 LLM；超过 `maxReportChars` 时按 INFO→LOW→MEDIUM 顺序降档截断。

## 工作原理

```
/review ──┐
          ├──► engine：选定评审员 ──► ctx.subagents.start("spawn", …) × N（并行）
code_review ┘                              │ 每个评审员：
                                           │  · prompt = 角色 + 取证指引 + 只读纪律 + 输出格式
                                           │  · agentOptions = 可选的按评审员模型路由
                                           │  · toolFilter.deny = str_replace_editor, write, edit, subagent, subagent_fork
                                           ▼
                              收集结果（每评审员独立超时/取消）──► 确定性合并
```

评审员是 spawn 出来的 dsh 子代理：全新上下文、有自己的工具、在你的工作区里干活。它们自己跑 `git diff`、读文件、追代码来取证——这正是评审有深度的原因（而不是拿一段 diff 套提示词）。只读约束是双保险：prompt 纪律 + toolFilter 硬 deny。

## 配置

在更晚的 patch 层（`~/.dsh/profiles/<profile>/cordis.patch.yml` 或 `--patch` 覆盖层）按 id `review-squad` 覆盖。注意 patch 行是整行替换 config——要保留的字段需要一并重写。

| 字段 | 默认值 | 含义 |
|---|---|---|
| `provider` | `spawn` | 启动评审员用的 `ctx.subagents` provider |
| `commandName` | `review` | 斜杠命令名 |
| `toolName` | `code_review` | 工具名 |
| `toolFilterDeny` | `['str_replace_editor','write','edit','subagent','subagent_fork','workflow','ralph','send_message','web_search']` | 评审员被禁用的工具——包括全部派生子代理的工具（workflow/ralph/send_message 会额外花钱）和联网搜索（成本）；未知名字会自动剔除 |
| `timeoutMs` | `600000` | 单评审员时间预算（毫秒） |
| `maxConcurrent` | `2` | 评审员按此数量分批并行（对 API 并发更友好） |
| `maxReportChars` | `24000` | 报告硬上限（字符） |
| `language` | `en` | 报告描述性文字语言（严重度/文件/行号等标记保持英文以便解析） |
| `reviewers` | 内置四人 | 小队阵容（见下） |

### 自定义阵容——"强脑弱手"玩法

```yaml
- id: review-squad
  name: dsh-review-squad
  config:
    language: zh
    reviewers:
      - key: security
        role: Security reviewer
        instructions: 查找注入、越权、提交进仓库的密钥、不安全的加密用法。
        agentOptions:
          provider: deepseek-official
          model: deepseek-v4-pro
          reasoningEffort: max
      - key: style
        role: Style reviewer
        instructions: 命名、重复、复杂度、与既有惯例的一致性。
        agentOptions:
          provider: my-cheap-gateway
          model: glm-4.6-flash
```

`agentOptions` 需要 provider 支持 subagent 的 `agentOptions` 能力（内置 `spawn` provider 五项能力全开）。

### 设置页面（Web UI）

插件自带 dsh web 设置页的 **"Review Squad"** 节：设置 → Review Squad，可直接编辑每个评审员的模型路由（provider / model / reasoning effort / max tokens）、报告语言、超时、报告预算与工具 deny 列表，保存即热生效（走 dsh 的 `settings.update` 通道写回 `settings.yaml` 的 `review-squad:` 节，无需重启）。

### 运行时覆盖 —— settings.yaml（热更新，不用重启）

除结构字段（`commandName`/`toolName`）外，所有参数都可以在 `$DSH_HOME/settings.yaml`（即 `~/.dsh/settings.yaml`）的 `review-squad:` 节里**不重启直接改**，每次调用即时生效，优先级高于 bundle 配置：

```yaml
# ~/.dsh/settings.yaml
review-squad:
  language: zh
  timeoutMs: 300000
  reviewers:
    - key: security
      role: Security reviewer
      instructions: 查找注入、越权、提交进仓库的密钥、不安全的加密用法。
      agentOptions:
        provider: deepseek-official
        model: deepseek-v4-pro
        reasoningEffort: max
    - key: style
      role: Style reviewer
      instructions: 命名、重复、复杂度、与既有惯例的一致性。
      agentOptions:
        provider: my-cheap-gateway   # 任何在 Models 页配置过的 provider
        model: glm-4.6-flash
```

省略该节即回退 bundle 配置。日常调参优先用 `settings.yaml`；patch 层的 `reviewers` 适合写死默认阵容。

### 兼容性结论（实测）

- 已在 **dsh 0.1.1-rc.2**（Windows + `deepseek-v4-flash`）上完成**真实端到端验证**：真实派出 `spawn` 评审员、按评审员 `agentOptions` 路由模型、真实模型输出的 findings 被正确解析并聚合。
- 0.1.1-rc.2 的 `spawn` provider 没有显式声明 `agentOptions` 能力（但驱动层实际生效）。插件会预检 `capabilities.agentOptions`，若运行时拒绝路由则自动回退到会话模型并在报告里说明——降级是显式的，不会跑挂。
- `toolFilterDeny` 的工具名由 dsh fail-loud 校验；默认列表里的名字在 0.1.1-rc.2 的 base bundle 中全部存在。
- 用 `--patch` 覆盖层或 profile `cordis.patch.yml` 覆盖插件行时用**直接行形式**（`- id: review-squad` + `config:`），不要再用 `- insert:`（同 id 插入两行会启动失败）。

## 开发

```bash
pnpm install
node --test            # 70 个单测/集成测试，不需要 dsh 运行时
```

不启动服务验证组合：

```bash
dsh plugin --profile dshrs-dev add ./dsh-review-squad
dsh --profile dshrs-dev --dump-config | grep review-squad
```

> 注意：已有 dsh web 实例在跑时，第二个实例可能启动挂起（共享 `$DSH_HOME`）；先停掉第一个再启动开发 profile，或把 `DSH_HOME` 指向一个临时目录做完全隔离的运行。

## 提交收录 awesome-dsh-plugin

`docs/awesome-entry.yml` 是现成的收录条目（category `git`）。填上你的 `owner`，给自己的仓库打上 `dsh-plugin` topic，然后按 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 的规则（一个 PR 一条）提交。

## 反馈与联系

发现 bug 或想要新功能？欢迎提 [issue](https://github.com/luomeii/dsh-review-squad/issues) 或在 [discussion](https://github.com/luomeii/dsh-review-squad/discussions) 讨论。想直接联系作者：luomeiy@outlook.com · https://github.com/luomeii

## 许可

MIT