@dsh-audit-missing/plugin

Readme

# @dsh-audit-missing/plugin —— 任务遗漏审核

一个**独立于 DSH 核心包**的审核插件：提交前扫描**当前工作空间的未提交改动**，对照**设计文档**，派 DSH 的 **subagent（默认模型）** 做「**设计文档承诺 vs 实际实现**」的差集比对，找出**遗漏的点**。

> 核心价值：审核的不只是"代码质量"，而是"**该做的有没有做全**"——设计文档/M1 迭代里承诺的点，开发完有没有条漏。

---

## 一、它解决什么问题

你之前说的痛点：
> 我们做了设计文档、规划了 M1 迭代要做哪些东西。开发完之后，**可能遗漏了一些点**——设计文档里承诺的、需求清单里列的，实际没全做到。

本插件做的是**差集审核**：
- **预期清单**（应该做）= 设计文档 / 需求清单里的承诺点。
- **实际证据**（做了）= 当前工作空间未提交的改动（git diff + 改动文件）。
- 模型逐点判断：`✅ 已实现` / `⚠️ 部分实现` / `❌ 缺失`，输出遗漏清单。

> 注意：它**不审核代码质量**（那是 `adversarial-review` 的事）；它审核的是**任务/设计的遗漏**。

---

## 二、怎么用

在 DSH 会话里输入（自然语言友好）：

```
/audit-missing <设计文档相对路径> [自然语言意图]
```

**用法示例**：
```
/audit-missing docs\欠费催缴机器人-开发计划文档.md
/audit-missing docs\欠费催缴机器人-开发计划文档.md M0
/audit-missing docs\欠费催缴机器人-开发计划文档.md 帮我检查这一节是否做完
/audit-missing --list            # 跨会话查看审核结果历史（最近 20 条）
/audit-missing --cost 1000 500 100  # token 成本分析（手动喂 input output cacheRead cacheWrite）
/audit-missing --review-code     # 提交前审代码质量（adversarial-review 审当前工作区未提交改动）
```

| 部分 | 说明 |
|---|---|
| `<设计文档相对路径>` | 必填（`--list`/`--cost`/`--review-code` 除外）。相对**当前工作区**的设计文档（如 `docs\xxx.md`），agent 会读它。 |
| `[自然语言意图]` | 可选。如 `M0`、`看下是否完成`——agent 会据此聚焦要审的迭代/部分。 |
| `--list` | 查看**跨会话**的审核结果历史（无需文档、不派模型）。 |
| `--cost <input> <output> [cacheRead] [cacheWrite]` | **token 成本分析**：算成本、缓存命中率、优化建议（手动喂 token 或读累计 usage）。 |
| `--review-code` | **提交前审代码质量**（与任务遗漏审核互补）：调 adversarial-review 审当前工作区未提交改动；DeepSeek 受 strict json_schema 限制时会回退输出审核 prompt。 |

**审核方式**：agent **读设计文档** + **读当前工作区（项目根）的实际代码/文件**，逐点核对文档承诺的点是否真的实现了，报告 `❌ 缺失` / `⚠️ 部分实现`。**不是**只看 git diff，而是看项目真实状态。

**输出（详细版）**：一份核对报告，含**审核范围**（读了文档哪些节、读了哪些文件）、**结论汇总**、逐条**出处/依据/建议**：
```
## 任务遗漏审核（对照文档读项目）
设计文档：docs\xxx.md
项目根目录：D:\proj

### 审核范围
- 设计文档：docs\xxx.md（核对了 M0 的 A/B/C 三节）
- 我读的项目文件：src/a.ts、src/b.js

### 结论
共核对 3 个承诺点：已实现 1，部分实现 1，缺失 1。

### ❌ 缺失（未实现）
- 做点击穿透 —— 出处：M0 第 2 节 —— 依据：读了 src/a.ts 没看到该实现 —— 建议：补上
### ⚠️ 部分实现
- 支持飞书分享 —— 出处：M0 第 3 节 —— 依据：只做了文档读取 —— 建议：补分享
```

**跨会话**：每次审核结果会持久化到工作区根 `.dsh-audit-results.json`，换会话用 `/audit-missing --list` 也能看到历史。

---

## 三、安装 / 挂载（同款 DSH 插件方式）

### 1. 包装进 profile
确保本插件目录 `D:\liaodoDownload\搞钱\dsh-audit-missing\` 作为一个依赖装进 DSH profile。例如：
```powershell
pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" add "D:\liaodoDownload\搞钱\dsh-audit-missing"
```

### 2. 挂载进 Loader（新增 insert）
在 `~/.dsh/profiles/web/cordis.patch.yml` 里追加：
```yaml
- insert:
    - id: dsh-audit-missing
      name: "@dsh-audit-missing/plugin"
```

### 3. 重启 `dsh --profile web`
让 DSH 重新加载 patch layer、扫描到本插件、注册 `/audit-missing` 命令。

---

## 四、结构说明

```
dsh-audit-missing/
├─ package.json        # DSH 插件声明（dsh.client + export ./client + 命令 peer deps）
├─ lib/
│  ├─ core.js          # 纯逻辑：git 状态归纳 / diff 收集 / 文档候选提取 / prompt 组装 / 结果解析（无 DSH 依赖）
│  ├─ index.js         # 宿主命令层：ctx.commands 注册 /audit-missing + 跑 git + 派 subagent
│  └─ client.js        # 前端 bundle：shell.overlay 渲染「审核结果」视图 + 侧边栏入口（独立自洽可视化，不依赖第三方任务面板）
├─ test-core.mjs       # 核心纯逻辑单测（24 项）
├─ test-plugin-contract.mjs # 插件加载契约测试（含 client bundle，30 项）
└─ README.md           # 本文档
```

---

## 五、可视化：审核结果怎么展示（B 方案）

`/audit-missing` 作为 DSH 命令，结果会**自动渲染在会话对话流里**（DSH 对 slash 命令的通用展示）。此外本插件提供了**独立的全屏审核结果视图**：

- 侧边栏底部多一个「审核」入口（`sidebar.footer.action`，与原生方式并排、不顶掉任何东西）。
- 点它打开**全屏审核报告视图**（`shell.overlay`），把 `❌ 缺失` / `⚠️ 部分实现` 分节、逐条展示遗漏点和补做建议。
- **独立自洽**：不依赖 shengsheng 或任何第三方任务面板；数据来自当前会话里 `/audit-missing` 命令的 `CommandNode` 结果，复用 DSH 原生命令数据流。

---

## 六、本插件已验证 vs 需真机实测

| | 状态 |
|---|---|
| 语法检查 | ✅ 通过（core.js / index.js / client.js） |
| 核心逻辑单测 | ✅ 24/24 通过 |
| 插件加载契约（含 client bundle） | ✅ 30/30 通过（命令注册、slot 注册、locale 注册全正常） |
| 挂载/加进 patch | ✅ 按上文可装 |
| **subagent 派模型做差集比对** | ⚠️ **需在 DSH 会话实测** —— 这步真实调用 LLM，我这边无法真机验证，需你装了后跑 `/audit-missing` 看结果 |
| **client 视图真机渲染** | ⚠️ 需真机看侧边栏「审核」入口和全屏报告是否正常显示 |

**诚实说明**：本插件"收集改动 + 组装 prompt + 解析结果"、"打包成可加载的 host+client 插件"已可靠验证；但"派 subagent 用默认模型比对"和"client 视图在浏览器里的实际渲染"，都需在**宿主 DSH 会话 + 浏览器**里实测。若报错（subagent 无输出、model 不识别、视图空白），按报错排查。

---

## 七、一个关键配置：审核用哪个模型

- **默认**：用 DSH 默认模型（本插件 `delegateAudit` 里 `provider: "default"`，未覆盖 `agentOptions.model`）。
- **想用"另一个模型"**（避免主编码模型自审）：在 `lib/index.js` 的 `delegateAudit` 里，给 `ctx.subagents.start` 加 `agentOptions: { provider, model }`，指定另一个模型即可（DSH 支持）。

---

## 八、后续 / 待优化

- **adversarial-review（代码质量审核）**：已装入工作时区，但因 DeepSeek 输出过不了它的 strict json_schema，记为待优化 —— 见 `doc/dsh-todo-backlog.md`。
- **真机实测反馈**：subagent 差集比对、client 视图浏览器渲染，需在 DSH 会话 + 浏览器实测后反馈。

---

*本插件为第三方、独立于 @deepseek-ai/dsh 的用户扩展，遵循 DSH Cordis 插件 + 命令契约。*