# dsh-plugin-tool-guard 快速上手教程（QUICKSTART）

> 面向使用者的简单教程。想看完整接口/配置清单请看 [api.md](api.md)，想看规则细节请看 [rules.md](rules.md)。

## 1. 它是干什么的

挂在 DeepSeek Harness 上的一层**工具调用防火墙**。AI 每调用一次工具（shell 命令 / 读文件 / 写文件 / 编辑 / 删除），它先拦下来检查，再给出三种决策：

| 决策 | 含义 |
|---|---|
| ✅ 放行 | 检查通过，工具正常执行 |
| 🚫 拒绝 | 命中黑名单 / 不在白名单，工具不执行，直接告诉 AI 原因 |
| 🖐 待审批 | 风险操作，弹审批卡等**你**拍板（允许 / 拒绝 / 本次会话允许） |

挂载（`apply`）即自动生效，卸载即全部失效，零侵入，不需要改任何 Agent 业务代码。

## 2. 装好后默认是什么体验

> 重要：插件自带的参考配置 `cordis.patch.yml` 刻意选择了「日常开发免打扰」——
> **覆盖已有文件、删除文件默认不需要人工审批**（`requireApprovalForOverwrite/Delete: false`）。
> 需要审批把关时，改成 `true` 或切到 `strict` 级别即可（见第 6 节）。

默认（`standard` 级别）下你实际会遇到的拦截：

- **永远硬拦（没有审批环节）**
  - 危险命令：`rm -rf /`、磁盘格式化、`shutdown`、fork 炸弹、`curl … | bash` 等
  - 读取敏感文件：`.env`、`.ssh/`、`id_rsa`、`*.pem/*.key`、`/etc/passwd` 等
  - 操作白名单之外的路径（默认白名单 = 当前会话工作目录）
- **默认直接放行（参考配置）**：创建新文件、覆盖已有文件、删除文件、安全 shell 命令
- **打开审批后才会弹卡**：覆盖已有文件、删除任意文件，以及 `strict` 级别下的所有写入与 shell 命令

## 3. 找到控制面板

在 DSH Web GUI 侧边栏打开「工具守卫」面板，四个标签页：

- **状态** — 安全级别、是否暂停、今日拦截数、白名单路径、待审批数
- **审批** — 挂着等你的审批项（允许 / 拒绝 / 本次会话允许）
- **拦截** — 最近被拦 / 被审的记录（审计日志实时视图）
- **规则** — 四条规则的开 / 关即时开关

另外 `GET /tool-guard` 有简易状态页，完整端点清单见 [api.md](api.md) §3。

## 4. 选一个安全级别

| 级别 | 说明 | 适合 |
|---|---|---|
| `loose` 宽松 | 只拦极端破坏命令，文件操作全放行 | 完全信任 AI、想零打扰 |
| `standard` 标准 | 默认：危险命令 + 敏感文件 + 路径白名单；写入审批由配置决定 | 日常开发 |
| `strict` 严格 | 所有写文件与所有 shell 命令都要你逐个批准；**禁止暂停** | 跑不信任代码 / 重要机器 |

切换方式（三选一）：

- 面板「状态」页里点选；
- HTTP `POST /tool-guard/level?level=strict`；
- 直接让 AI 调 `guard_set_level(level="strict")`。

## 5. 审批怎么操作

当一条操作需要审批时（参考配置下主要是 `strict` 级别，或你开启了覆盖/删除审批）：

1. GUI 弹出**审批卡**（宿主有原生 approval 服务时走原生通道）；
2. 三个按钮：
   - **允许** —— 只放行这一次；
   - **拒绝** —— 这次不让做；
   - **允许本次会话** —— 同会话内同类操作（同规则 + 同工具 + 同关键入参）后续自动放行；
3. 没人点会超时（默认 120 秒），超时默认按**拒绝**处理——宁可误杀不放漏；
4. 无宿主审批服务时，审批项挂在面板「审批」标签页，也可以在那里操作；直接在聊天里回复「允许 / 拒绝」也有兜底效果。

## 6. 配置文件：自定义规则 / 白名单 / 开启审批

参考配置 `cordis.patch.yml`（bundle patch，安装即生效）：

```yaml
securityLevel: standard          # loose / standard / strict
rules:
  dangerousCommands:
    patterns: []                 # 危险命令正则，空 = 内置列表
  pathWhitelist:
    paths: []                    # 允许操作目录，空 = 仅当前工作目录
  sensitiveFiles:
    patterns: []                 # 敏感文件 glob，空 = 内置列表
  writeProtection:
    # 想要覆盖/删除弹审批卡，把下面两个改成 true：
    requireApprovalForOverwrite: true
    requireApprovalForDelete: true
approval:
  timeoutSeconds: 120            # 审批超时（秒）
  defaultOnTimeout: deny         # 超时默认 deny（安全优先）
pause:
  autoResumeMinutes: 10          # 暂停自动恢复分钟数
audit:
  keepAfterUnload: false         # true = 卸载时把审计日志归档成 JSON
  maxRecordsPerSession: 200      # 每会话最多保留条数（滚动覆盖最旧）
```

> 面板「规则」页的开关是**运行时即时生效**的，但重启后还原为配置文件的值。

## 7. 管理指令（让 AI 调 `guard_*` 工具即可）

| 工具 | 作用 |
|---|---|
| `guard_status` | 当前级别 / 是否暂停 / 白名单 / 待审批 |
| `guard_stats` | 统计：总检查数、放行 / 拦截 / 审批数、今日拦截 |
| `guard_recent_blocks` | 最近被拦 / 被审的记录（审计查询） |
| `guard_set_level` | 切换安全级别 |
| `guard_pause` | 临时暂停防护（`0` = 手动恢复；严格级别禁止暂停） |
| `guard_resume` | 恢复防护 |
| `guard_whitelist_add` / `remove` | 运行时增删路径白名单目录 |

## 8. 审计记录去哪看

- **实时**：面板「拦截」页 / `guard_recent_blocks` / `GET /tool-guard/recent?sessionId=…`
- **归档**：仅当 `audit.keepAfterUnload: true`，插件卸载时把全部日志写入
  `~/.deepseek-harness/audit/tool-guard-<时间戳>.json`（Windows 下即
  `C:\Users\<用户名>\.deepseek-harness\audit\`），否则卸载即清空
- 审计日志含：时间、会话、轮次、工具名、**脱敏后**入参、决策、命中规则、原因

## 9. 5 步验证它真的在工作

1. 打开面板「状态」——级别 `standard`、未暂停；
2. 让 AI 读 `.env` 或执行 `rm -rf C:\` → 应立即被拒并给出原因；
3. （开了写入审批后）让 AI 覆盖一个已存在文件 → 应弹出审批卡；
4. 点「允许本次会话」→ 再让它改同一个文件 → 应直接放行不再弹；
5. 调 `guard_stats` / 面板「拦截」页 → 能看到上面两次操作的审计记录。

## 10. 常见问题

- **审批卡没弹出来？** 先确认参考配置里 `requireApprovalForOverwrite / Delete` 是否为 `true`——默认是关闭的（免打扰设计）。覆盖/删除审批未开时只有 `strict` 级别会强制弹卡。
- **想临时全放行？** `guard_pause`（默认 10 分钟后自动恢复；严格级别下不可暂停）。
- **路径被白名单拦了？** 把目录加进白名单：`guard_whitelist_add(path="D:/my-work")`，或在配置文件 `rules.pathWhitelist.paths` 里加。
- **怎么关掉某个规则？** 面板「规则」页即时开关；持久化改配置 `rules.*.enabled`。
- **被拦的操作我能手动补执行吗？** 插件只做决策，不代替你执行——工具根本没运行，你完全可以自己在终端里做（风险自担）。

---

更多细节见 `docs/api.md`（接口）、`docs/rules.md`（规则与级别矩阵）、`docs/PRD.md`（权威规格）。