# dsh-approval-ai-review

[English](README.md) | 中文

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件（`dsh-plugin`）。

## 安装

```sh
dsh plugin --profile web add dsh-approval-ai-review
```

或从 GitHub 安装：`dsh plugin --profile web add github:kiiiiile/dsh-approval-ai-review`。

## 概述

使用本包可免去逐条手动确认安全工具请求。会话启用后，每个待决审批请求会在任何人工应答者介入前由一次辅助模型调用判定：安全操作自动放行；其余一切结果——升级判定、审核失败、超时、畸形输出——都会附带审核分析（该操作会做什么、有什么风险）转交其余应答者。插件默认惰性：未运行 `/auto-approve on`（或设置 `enabled: true`）时，每个请求原样委托，行为零差异。

## 目录

- [使用本包](#use-this-package)
- [理解实现](#understand-the-implementation)
- [模型体验](#model-experience)
- [已知限制与延期工作](#known-limitations-and-deferred-work)
- [开发备注](#dev-note)

-----

<a id="use-this-package"></a>
## 使用本包

在权限模式仍需询问的部署中，于 `@deepseek-ai/dsh-user-approval` 之后组合本插件：审核器消费与 Web、ACP 应答者相同的 `approval/request` waterfall，并以 `prepend` 注册，从而在任何提示出现前完成判定。插件依赖 `ctx.llm`；未显式配置路由时，审核调用复用该 agent 已路由的会话模型。

```yaml
- name: 'dsh-approval-ai-review'
  config:
    enabled: true
```

| 字段 | 默认值 | 含义 |
|---|---|---|
| `enabled` | `false` | 无 `approval/review/enabled` 覆盖时的组合默认值 |
| `reviewProvider` / `reviewModel` | 跟随会话模型 | 显式审核路由；必须成对提供 |
| `reasoningEffort` | `low` | 审核调用的思考强度（`off`/`low`/`high`/`max`） |
| `maxTokens` | `2048` | 单次审核调用的输出 token 上限 |
| `reviewTimeoutMs` | `30000` | 审核端到端截止时间 |

完整的配置面以 [`src/index.ts`](src/index.ts) 中 `Config` schema 的 JSDoc 为准。

### 按会话切换

`/auto-approve [on|off]` 将持久化的 `approval/review/enabled` 开关追加到会话日志（最后一条生效；缺失时应用组合默认值），不带参数的 `/auto-approve` 报告当前状态。该开关仅入日志：模型永远看不到它。

### 判定单个请求

审核器接收工具名、会话日志中该 `callId` 对应的精确 `tool/call` 参数，以及请求者的理由。校验通过的 `{"verdict":"approve"}` 将请求解析为 `allowed-once`。其余一切——`escalate` 判定、传输错误、超时触发、畸形输出——都会把请求委托给其余应答者，并将审核分析附加到请求理由上，使人工提示说明该操作会做什么、有什么风险。没有组合应答者时，应用 seam 自身以拒绝方式关闭的 `unavailable`。

-----

<a id="understand-the-implementation"></a>
## 理解实现

<details>
<summary>实现内部结构——点击展开</summary>

[使用本包](#use-this-package)覆盖可观察行为；本节解释分发、审核调用与日志路径。

### 源码地图

| 文件 | 职责 |
|---|---|
| [`src/index.ts`](src/index.ts) | 插件注册、`approval/request` prepend 监听器、`/auto-approve` 命令 |
| [`src/reviewer.ts`](src/reviewer.ts) | 路由解析、审核提示词、判定解析、会话日志读取 |
| [`src/types.ts`](src/types.ts) | 配置、判定词表、三个仅入日志的会话事件 |

### 分发与理由修改

`prepend` 监听器独占安全决定并委托其余一切。升级时它修改共享请求的 `reason`（waterfall 契约的 mutate-then-delegate 模式），使下游应答者展示分析；已落盘的 `approval/asked` 审计事件携带请求者的原样理由，日志不受影响。

### 审核调用

该调用是一次手工构建的 `ctx.llm.stream()` 请求，携带审核系统提示词与 JSON 框架输入；精确的路由、强度、提示词与上限在派发前追加为 `approval/review/request`，解析后的判定追加为 `approval/review/verdict`，因此辅助请求可从会话日志重建。可扩展的 finish reason 对未知种类回落为失败，且每条失败路径都升级——本插件从不以自身权限拒绝。

</details>

-----

<a id="model-experience"></a>
## 模型体验

### 审核决定

#### 模型看到什么

没有新内容。三个审核事件与切换开关仅入日志；模型看到的最终工具结果与没有本插件时完全一致，且 `approval:policy` 句子保持准确——询问仍然发生，只是更早得到回答。

#### Token 效应

零对话 transcript token。启用的每次询问消耗一次辅助模型调用，绝不进入对话 transcript。

#### KV Cache 效应

无变化。审核调用是带独立前缀的独立请求；对话的稳定请求头与缓存前缀不受影响。

## 已知限制与延期工作

<a id="known-limitations-and-deferred-work"></a>

- **审核器从不拒绝**——危险请求升级给人工而非自动拒绝；机器拒绝判定延期到有部署拥有该权限时再做。
- **子会话不继承开关**——`approval/review/enabled` 不像 `approval/policy` 那样播种给受委托的子会话；子会话审核默认值延期到委托机制拥有其一后再做。
- **审核消耗询问内的墙钟时间**——慢模型会延长待决询问；`reviewTimeoutMs` 约束它，但不会缩短调用方自身的工具超时预算。
- **强度校验依赖具体路由**——被路由模型未声明的 `reasoningEffort` 值会使审核失败（进而升级）而非启动失败；兼容集合在路由存在前不可知。

<a id="dev-note"></a>
### 开发备注

<details>
<summary>维护者的工作背景——点击展开</summary>

不发布 `./invariant` 伴随模块：本插件不拥有任何观察可能分歧的 owned 关系——审核请求/判定对在模型 JSON 边界校验，而询问/决定审计对归属 `dsh-user-approval` 的 invariant。

</details>