dsh-auto-review-jev

简体中文 | English

DeepSeek Harness 的审批守护者：权限请求先由 reviewer 模型裁决，再决定要不要打扰你。

安装 · 快速开始 · 工作方式 · 配置 · System One · 策略 · 信任边界 · 验证

[!NOTE] 本项目 fork 自 gbthui/dsh-auto-review（Apache-2.0）。审查接缝、证据流水线、熔断器与审计落盘是上游工作；本 fork 增加 System One 决策 API 协议、onLowConfidence 策略、allowRules 免审白名单，以及两者的设置页编辑器。

为什么有这个 fork

	上游 dsh-auto-review	本 fork
审查协议	chat completion（/chat/completions）	chat completion 或 System One 决策 API（POST {baseURL}/systemone，一次调用并行问两个 choice 问题）
后端	任意 OpenAI 兼容端点	另加 TypeSafe Jev、硅基流动 systemone、自部署 Laya（回环地址免 key）
审查器犹豫时	一律拒绝	policy.onLowConfidence: deny | defer，defer 把请求交回人工，而不是静默拒绝
重复请求	每次都问审查器	policy.allowRules 按「工具 + 操作前缀」精确预批，越权放行由 policy.allowDangerFullAccessRules 单独把关
设置页	只有 reviewer	reviewer 与 policy（置信度阈值、低置信度动作、免审白名单）

安装

插件装在 web profile，三种来源任选：

# 1) 发行包（预构建，免构建步骤，也不需要放行构建脚本）
npx @deepseek-ai/dsh plugin --profile web add \
  https://github.com/xlennart/dsh-auto-review-jev/releases/download/v0.2.0-jev.0/dsh-auto-review-jev-0.2.0-jev.0.tgz

# 2) 直接从 git 安装
npx @deepseek-ai/dsh plugin --profile web add https://github.com/xlennart/dsh-auto-review-jev.git

# 3) 本地目录（开发用）
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-auto-review-jev

bundle 在 profile 进程启动时读取，所以装完要重启 profile（桌面端：托盘退出后重新启动；CLI：停掉再执行 npx @deepseek-ai/dsh web）——正在运行的宿主不会自动加载新装或重新构建的插件。

在会话里确认：

/auto-review status

它会输出守护者是否已武装、由哪个端点/模型裁决、审计文件在哪里。

快速开始

插件默认启用；未配置 reviewer 时跟随当前会话模型，无需任何设置。若要指定 System One 后端：

# ~/.dsh/settings.yaml
dsh-auto-review:
  reviewer:
    protocol: systemone              # chat（默认）| systemone
    baseURL: https://api.typesafe.ai/v1
    model: jev-latest
    apiKeyFile: ~/.dsh/reviewer.env  # KEY=VALUE 文件；也支持 apiKey / apiKeyEnv
    systemone:
      confidenceThreshold: 0.8       # 决策答案低于此值即不予采信
  policy:
    onLowConfidence: defer           # deny（默认）| defer 交人工

Web UI 的 设置 → dsh-auto-review 里同样可以改。

工作方式

flowchart TD
  A[agent 请求沙箱不允许的操作] --> B{守护者已武装?}
  B -- 否 --> H[交互式审批：交给人]
  B -- 是 --> C[证据：工具调用、沙箱状态、只读事实、有界上下文]
  C --> R{命中 policy.allowRules?}
  R -- 是 --> P[放行一次]
  R -- 否 --> D[审查器：systemone 决策 API 或 chat completion]
  D --> V{严格裁决解析}
  V -- allow --> P
  V -- deny --> X[拒绝 + 注入拒绝通知给 agent]
  V -- 低置信度 --> W{policy.onLowConfidence}
  W -- deny --> X
  W -- defer --> H
  V -- critical 风险 --> X
  P --> Z[该操作重试一次]

• 审查器只替代审批提示。插件不改沙箱配置、也不会自行放宽沙箱：它只回答宿主已经抛出的请求。
• critical 风险一律拒绝，不受 decision 答案影响。
• 审查器出错时失败关闭（policy.denyOnReviewerError: true）。
• 熔断器能拦住反复试探被拒操作的 agent。
• 拒绝会以通知形式注入会话，来源使用生产方自有 kind（plugin:dsh-auto-review），因此 transcript 始终满足 v4 会话格式。

配置

设置段：dsh-auto-review。完整参考见 docs/configuration.md。

reviewer

键	默认值	说明
protocol	chat	chat = OpenAI 兼容补全，systemone = System One 决策 API
baseURL	''	空 + chat = 当前会话模型；空 + systemone = 硅基流动
model	''	空 + systemone = Kev-4b（硅基流动暂定默认）
apiKey / apiKeyEnv / apiKeyFile	''	三选一；回环端点不需要
timeoutMs	24000	单次审查调用超时
thinking	default	对不接受 thinking 的后端设 off
systemone.confidenceThreshold	0.6	低于此值的决策答案不予采信（0.5–1）
factFinding.enabled / maxRounds / maxFacts	true / 2 / 3	审查器可调用的只读事实工具
factFinding.content.enabled / maxBytes	false / 4096	是否允许把文件内容附进请求

policy

键	默认值	说明
enabled	true	总开关（/auto-review on │ off）
tools	[]	限定守护者审查哪些工具
allowRules	[]	免审白名单：{ tool, operations[], escalationTarget }
allowDangerFullAccessRules	false	必须显式打开，规则才允许授予 danger-full-access
onLowConfidence	deny	deny（失败关闭）或 defer（交人工）
denyOnReviewerError	true	审查器崩溃/超时 ⇒ 拒绝
context.enabled / maxMessages / maxChars	true / 10 / 6000	交给审查器的有界会话上下文
breaker.consecutiveDenyLimit / windowDenyLimit	3 / 10	连续拒绝达阈值即熔断
audit.enabled / path / includeToolInput	true / ~/.dsh/auto-review-audit.jsonl / false	每次裁决一行 JSON

System One 决策 API 审查器

protocol: systemone 把一次审查变成一次决策 API 调用：

POST {baseURL}/systemone
{ "model": "<model>", "state": { "policy": "...", "request": "..." },
  "questions": { "decision": {...}, "risk": {...} } }

两个 choice 问题（decision、risk）并行提出，返回的结构化答案被确定性地合成为与 chat 路径完全相同的裁决 JSON，并走同一套严格解析（critical 风险拒绝、未知选项判为格式错误、低置信度交由 policy.onLowConfidence）。置信度按 |p(allow) − 0.5| × 2 计算，所以 p(allow)=0.500 得到置信度 0.000——这是「无法判断」，而不是悄悄放行。

后端	baseURL	model	密钥
TypeSafe Jev（推荐）	https://api.typesafe.ai/v1	jev-latest	TypeSafe key（审计里记录裁决模型，如 jev-1.13.0）
硅基流动	（空） → https://api.siliconflow.cn/v1	（空） → Kev-4b	硅基流动 key
自部署 Laya	你的 Laya 端点	你的模型	回环地址免 key

来自真实使用的标定结论：面对 escalation 类请求，Jev 常常刻意保持不表态（置信度接近 0.000）。此时 onLowConfidence: deny 等于「不批」，defer 等于「问人」——想少被打扰就提高 allowRules 覆盖率或下调 confidenceThreshold。

免审白名单与低置信度

与其让审查器揣摩你的习惯，不如把窄而重复的形态显式预批：

dsh-auto-review:
  policy:
    onLowConfidence: defer
    allowRules:
      - tool: write                       # 工具名精确匹配
        operations: ['C:\work\notes\']    # 操作前缀（路径/命令）
      - tool: bash
        operations: ['git status', 'git log']
        escalationTarget: workspace-write # "" | workspace-write | danger-full-access
    allowDangerFullAccessRules: false     # 无沙箱放行保持默认关闭

命中规则会跳过审查器并直接放行一次，所以规则必须保守：escalation 规则至少钉住一个操作前缀；未打开 allowDangerFullAccessRules 时，配置校验会直接拒绝 escalationTarget: danger-full-access。

onLowConfidence 决定「不可采信的审查结论」意味着什么：

取值	行为
deny（默认）	失败关闭——审查器不表态即拒绝，并告知 agent 原因
defer	该请求落回人工审批；审计行记 source=reviewer-low-confidence

信任边界

• 外发内容：待批工具调用、沙箱状态、审查器主动索取的只读事实，以及一段有界上下文（默认 10 条消息 / 6000 字符；文件内容默认关闭）。没有别的——不导出环境变量、不发送完整 transcript、不含凭据。
• 密钥不外流：API key 来自 apiKey、apiKeyEnv 或 KEY=VALUE 文件，并在审查请求、审计行与 trace 中被抹除。
• 回环特殊处理：自部署端点在 127.0.0.1/localhost/[::1] 上可免 key；其他地址缺 key 时拒绝启动。
• 本地产物：~/.dsh/auto-review-audit.jsonl（每次裁决一行，includeToolInput 默认关闭）与 ~/.dsh/auto-review-trace.jsonl（每次请求为何如此处理：谁裁决、端点、模型、置信度）。都是纯本地文件，随时可删。
• 插件无法给自己授权：它只回答宿主已抛出的请求，且从不修改沙箱配置。

验证

npm run build      # tsc → lib/
npm test           # 对构建产物跑零依赖的冒烟套件
npm run test:systemone   # 针对本地 mock System One 决策 API 的集成测试

npm test 包含五个冒烟套件（模块与导出、答案裁决、消息来源准入、trace 落盘、前端契约）。test:systemone 会拉起一个本地 mock 决策 API，断言整条链路：请求形状、密钥处理、置信度到策略的映射，以及解析器的失败关闭行为。它直接引用 TypeScript 源码，因此需要能解析到 harness 包（在 checkout 或已装 harness 的 profile 内运行）。

排查

现象	原因 / 处理
dsh plugin add 或重新构建后没有任何变化	bundle 在进程启动时读取——重启 profile。
/auto-review status 提示没有 settings provider	在 profile patch 里设 dsh-auto-review.enabled，或用 Web 设置页。
安装报 ERESOLVE	改用发行包（预构建）而非 git spec，或加 --legacy-peer-deps。
所有请求都落回人工	审查器结论低于 confidenceThreshold 且 policy.onLowConfidence: defer。提高 allowRules 覆盖率，或改为 deny。
审查器一律拒绝	看 audit.path——每行带 p(allow)、confidence、risk 以及裁决模型。
拒绝后会话损坏	0.2.0-jev.0 起不应再出现；注入使用生产方自有 source kind。若见到 format v4 message requires a producer-owned source kind，说明该构建早于修复。

兼容性

DeepSeek Harness 0.2.0-rc.x（声明为 engines.dsh: >=0.2.0-0 <0.3.0），Node.js ≥ 22。官方 @deepseek-ai/* 包由 profile 在运行时提供，因此刻意不声明为依赖（避免 profile 内出现重复运行时）。

文档

• docs/configuration.md —— 全部设置项与默认值
• docs/deployment.md —— 多 profile、文件/registry 安装、手工接入
• docs/terminology.yaml —— 文档用词表
• CHANGELOG.md —— 本 fork 相对上游的变更

许可证

Apache-2.0。上游：gbthui/dsh-auto-review（Apache-2.0），本 fork 建立在其审查接缝、证据流水线、熔断器与审计落盘之上。