# 审查流程与 Web UI

[English](review-flow.en.md) · [返回 README](../README.md)

## 流程

1. 插件只在当前 preset 为 `auto-review` 时认领审批。
2. `tools/pre-execute` 先等待其他策略。下游 `deny` 原样保留；下游 `ask` 仍保持审批边界。
3. 可证明位于 workspace 内的保守只读 Shell 可豁免。其他 Shell、已知网络工具和 `mcp__*` 默认主动审查。
4. 主动请求用 `session + callId + live signal identity` 保存一次性精确 target，并向标准审批链提供受限的可读 reason。复制 reason、signal 不匹配或已消费 marker 的重放请求返回 `unavailable`。
5. Guardian 在无工具、温度 `0`、有超时和输出上限的独立流中判断。
6. Guardian 未批准且 `manualOverride` 允许时，插件调用当前 `approval/request` listener 的 `next()`，复用 DSH 原生 Reject / Allow once 面板；不会克隆请求，也不会递归进入 Auto Review。
7. 最终 JSONL 审计完成后才可能返回 `allowed-once`。

## 最近 Review 生命周期

Host 在内存中发布 `start → status → end`，并为有界数量的 Session 保留最近一份 Review 快照。Web 通过 Typert Remote 打开当前 Session 的 watcher，并约每 250 ms 轮询；当前 permission preset 是 `auto-review` 时，watcher 会先回放最近快照，再接收增量更新。

刷新页面、切换 Session 或 Client 插件重载会重新打开 watcher 并恢复最近状态。Host 重启后，Remote 会从当前审计 JSONL 或其 `.1` 备份查找该 Session 最近一条已持久化 final record，转换为脱敏的 `start + end` 快照；关闭审计或审计失败的结果仅在当前 Host 生命周期内保留。同一 Session 的新 `start` 替换旧卡片，只有匹配当前 `reviewId` 的 `status/end` 才会生效，迟到更新不会覆盖新结果。队列、watcher 数量、闲置时间和内存快照数量均有上限。

插件当前不会向 Session 追加 `auto-review/start`、`auto-review/status` 或 `auto-review/end`。旧的 durable Session 写入以及 Chat/Tool View/Trajectory 投影代码仍保留并标注 `TODO(dsh-session-events)`，但生产入口已禁用。只有 DSH 正式支持第三方 log-only 事件，并能在 JSONL/SQLite、cold load 与 Client replay 中端到端持久化 `ignorable: true` 后，才应恢复该路径。

## 实时卡片

`conversation.input.dock` 在输入框上方显示一个默认折叠的 **Guardian Review** 卡片。header 显示受限 target summary，以及 Reviewing / Awaiting approval / Approved / Allowed once / Denied / Cancelled / Unavailable。

展开后显示工具、target kind、Guardian status、简短判断原因、risk、authorization、manual approval、audit 和 duration；不重复显示 Status 行。不会显示完整命令、URL 参数或证据。Guardian 判断原因最多 240 字符，并遮盖常见凭据和 URL query values。

## Trajectory 兼容路径

`trajectoryEnabled` 仍由 Host schema、环境变量和旧配置接受，以避免破坏已有组合；当前 Web Settings 隐藏该字段，生产 Client 也不会注册 Trajectory 投影，所以它现在不产生 UI 效果。旧实现及测试保留，待 DSH 支持可安全回放的第三方 Session 事件后恢复。

## 取消和故障

请求取消或插件 graceful disposal 会终止 Reviewer，并发布尽力而为的取消终态。传输、卡片、watcher 或历史恢复故障不会改变授权结果；Guardian 策略与 JSONL audit-before-allow 仍是安全边界。Host 硬崩溃不会留下新的自定义 Session 事件；重启后只能恢复崩溃前已经完成并成功写入审计的结果。