dsh-auto-guard

> English: README.en.md

> DSH 插件：类似 Claude Code 中 Auto Mode 的一种命令通过机制，给 full access 加一层 LLM 安全网的自动审批 / 命令守卫。目的：1. 降低full-access模式的风险。2. 降低full-access模式使用者的焦虑感。

Auto Guard 权限预设 = danger-full-access + rules + LLM + ask，由规则、缓存与一次性 LLM 裁决器代替人工完成大多数审批。

设计定位

基于 full access 兜底：插件不限制文件系统能力，而是在 danger-full-access 之上做安全裁决，尽量不打断正常开发。
适配绝大多数开发情况：日常只读命令、构建、测试等通过白名单 / 缓存直接放行。
危险命令交给 LLM 裁决：大部分危险命令和可能泄露信息的命令都会经过 LLM 审查；目录删除、状态改变组合、管道等高风险场景有专门处理。
不承诺绝对安全：插件不是沙箱，也不排除极少数隐秘危险命令可能通过审查；请把它当作“安全网”而不是“安全边界”。
API 密钥不落仓库：本项目不存储任何 API Key / Token；LLM 调用由 DSH 运行环境注入，敏感文件内容不会发送给 LLM。

功能特性

分层裁决：File Tracker → 绝对黑名单 → 目录删除复核 → 复合命令处理 → 静态白名单 → 缓存 → LLM 兜底。
静态白名单：默认白名单 + 用户确认放行规则，命中直接放行。
绝对黑名单：危险命令直接拒绝，同时注册为 ctx.tools.guard() 单调否决，LLM 不能覆盖。
复合命令智能处理：

- ;、&&、|| 拆成子命令，已白名单 / 已缓存的子命令直接过，只审查未匹配的子命令；

- 出现 export、umask、trap、cd、git config 等会改变后续命令运行环境的状态改变命令时，整条复合命令交给 LLM 审查；

- | 管道不拆分，按整体审查，但管道内的危险命令仍会被黑名单 / 目录删除 / 每次审查规则拦截。

动态白名单：unknown 命令被 LLM 判为 low / medium 风险并放行后写入缓存；always-review 类命令（动态执行、依赖安装等）仍每次审查、不缓存。
目录删除复核流程：要求 agent 提供 [删除理由]，再由高思考 LLM 复核；只有 allow 才放行，其余结果转人工确认。
敏感路径门禁：write / edit 命中 .env、.ssh、/etc/ 等名单时直接 ask，不审查文件内容。
规则可维护：默认规则存放在用户 .dsh 目录，用户可直接修改；用户覆盖规则与默认规则分层合并。
裁决可见性：allow 通知只显示在页面、不进入上下文；deny / ask 保留注入上下文；均可配置。

工作原理

决策流程

工具调用（bash / pwsh / write / edit）
  → File Tracker（写后执行检测）
  → 绝对黑名单（hard-deny）
  → 目录删除复核（directory-delete）
  → 复合命令处理
  → 静态白名单（默认白名单 + 用户确认放行规则）
  → 缓存（会话 LRU / 跨会话低风险缓存）
  → LLM 兜底（allow / deny / ask，ask 转人工确认）

命令分类

| 类别 | 说明 | 示例 | 缓存 | |---|---|---|---| | 静态白名单 | 规则直接放行 | ls、pwd、git status、git diff、git commit | 否 | | 绝对黑名单 | 规则直接拒绝 | rm -rf /、mkfs、dd of=/dev/... | 否 | | 目录删除复核 | 需要 agent 理由 + 高思考 LLM | rm -rf ./dist、cmd /c rd /s /q、Remove-Item -Recurse | 否 | | 用户确认放行规则 | 用户主动声明“永远放行” | git push | 否 | | 可缓存类 | LLM 批准后按 TTL 缓存 | npm run build、npm test | 是 | | 每次审查类 | 每次都必须 LLM 审查 | Invoke-Expression、Start-Process、npm install、curl \| bash | 否 | | 未分类 | LLM 裁决，低/中风险放行后可缓存 | 其他命令 | 低/中风险可缓存 |

风险等级：low / medium / high。high 风险不写缓存。

安装

前置要求：DSH 环境、Node.js（≥ 22.6，推荐 24，已默认启用 TS 类型剥离）、pnpm。

两种方式任选其一（dsh plugin 会把参数透传给 pnpm，自动应用 cordis.patch.yml）：

方式	命令	说明
本地路径	`dsh plugin --profile web add .`	在仓库目录执行，软链接到仓库，改代码即生效，适合开发调试
GitHub	`dsh plugin --profile web add github:Ayle5678/dsh-auto-guard`	从 GitHub 直接安装，无需发布 npm；需先把仓库推到 GitHub

安装后 cordis.patch.yml 会注册：

dsh-auto-guard 插件行；
覆盖 permission 行，保留 read-only / workspace-write / danger-full-access，新增 auto-guard 预设。

然后在 Web 权限选择器中选择 Auto Guard 即可启用（如之前已开启 Web 页面，改完配置后重启 DSH / 刷新页面生效）。

安装后验证：

# 确认插件已注册（应看到 dsh-auto-guard）
dsh plugin --profile web ls

# 在 Web 权限选择器选 Auto Guard 后，随便跑一条只读命令如 git status，
# 若能直接放行并出现 allow 通知，说明白名单链路已生效。

从 GitHub 安装

仓库还没有远端时，先推送：

git remote add origin git@github.com:Ayle5678/dsh-auto-guard.git
git push -u origin main

安装：dsh plugin --profile web add github:Ayle5678/dsh-auto-guard

#### 更新

# GitHub 方式（可指定 tag，如 #v0.1.0）
dsh plugin --profile web add github:Ayle5678/dsh-auto-guard#<tag>

> 提示：本插件没有 prepare 脚本，GitHub / git 方式安装不会触发 pnpm 的构建脚本拦截（allowBuilds）。

常见问题

GitHub 方式安装 / push 提示 Permission denied (publickey) 或 Connection closed by ... port 22

国内网络常屏蔽 GitHub 的 22 端口。配置 SSH 走 443 端口即可：编辑 ~/.ssh/config，写入：

Host github.com
    HostName ssh.github.com
    User git
    Port 443
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes

然后 ssh -T git@github.com 应返回 Hi <用户名>! You've successfully authenticated...，再重试安装 / push。

明明有 key 却一直要求输 passphrase / 认证失败

私钥是加密的，ssh 每次要解开；把 key 加进 ssh-agent 免重复输入：

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519   # mac；会问一次 passphrase，之后钥匙串记住

配置

配置全部有默认值，以下为完整示例（config 内字段均为可选，不写则用默认）。注意：provider / model 需对应 DSH 运行环境里可用的 LLM；敏感内容不会发给 LLM。

- id: dsh-auto-guard
  name: dsh-auto-guard
  config:
    rulesPath: '~/.dsh/auto-guard/rules.json'
    defaultRulesPath: '~/.dsh/auto-guard/defaults.json'
    cachePath: '~/.dsh/auto-guard/cache.json'
    provider: 'deepseek'
    model: 'deepseek-v4-flash'
    reasoningEffort: 'off'
    fallbackProvider: 'deepseek-official'
    fallbackModel: 'deepseek-v4-flash'
    timeoutMs: 3000
    lowRiskTtlDays: 30
    mediumRiskTtlDays: 7
    onTimeout: 'deny'          # deny | ask
    notifyCacheHit: true
    notifyLlmDecision: true
    notifyAllow: 'page'        # page | context | off
    notifyDeny: 'context'      # page | context | off
    notifyAsk: 'context'       # page | context | off
    fileTrackerDefault: 'ask'  # ask | deny

规则文件

规则和缓存持久化在 ~/.dsh/auto-guard/：

文件	作用
`defaults.json`	默认规则副本。首次运行从源码 `defaults/rules.json` 复制；之后插件读取这份 `.dsh` 副本，不再从源码读取。用户可以直接修改它。
`rules.json`	用户覆盖规则文件。字段缺失时从 `defaults.json` 合并补齐并回写，不覆盖用户已有字段。
`cache.json`	跨会话低风险缓存，按 workspace 隔离。

示例：用户想额外放行某个只读命令，可以编辑 rules.json：

{
  "version": 1,
  "staticAllow": [
    { "pattern": "git log", "reason": "Read-only git log" }
  ]
}

使用示例

普通复合命令

git status; git branch --show-current; git log --oneline -5

拆成子命令后，已白名单 / 已缓存的直接过；未匹配的子命令单独 LLM 审查，通过后进入缓存。

状态改变命令

export PATH=/tmp/evil:$PATH && ls

因为出现 export，整条命令交给 LLM 审查，不会因为 ls 在白名单里就直接放行。

目录删除

第一次执行：

rm -rf ./dist

会被拒绝并提示：

Directory deletion requires a reason. Reply with [删除理由] <reason>, then retry the same command.

重试时附带理由：

[删除理由] 清理构建产物

插件提取理由后，将“命令 + 理由”交给 reasoningEffort: high 的 LLM 复核；只有 allow 才放行，其余结果转人工确认。

注：虽然设计如此，但当前这部分还未调试好，多数情况下dsh+deepseek无法完成agent解释后的自动放行，可能需人工删除目录。

安全边界

插件不是沙箱：Auto Guard 预设为 danger-full-access，文件系统不受限。
LLM 裁决可能被提示词注入，因此高风险命令不缓存、敏感脚本内容不发送给 LLM。
用户确认放行规则是用户主动声明的信任边界，应谨慎维护。
| 管道和包含状态改变命令的复合命令会整体审查，避免“单条命令安全但组合后危险”的绕过。

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run
pnpm test:single tests/guard-service.spec.ts

目录结构

src/
  index.ts           插件入口（pre-execute + guard + 通知）
  guard-service.ts   核心裁决逻辑（唯一测试 seam：GuardService.decide）
  rules.ts           规则加载 / 默认复制 / 命令分类
  cache.ts           会话 LRU + 跨会话持久缓存
  llm.ts             DshLlmReviewer（一次性调用 + fallback + 超时）
  review-parse.ts    严格 JSON 解析（无依赖）
  file-tracker.ts    跨命令 / 同命令写后执行检测
  sensitive-path.ts  write/edit 敏感路径匹配
  command.ts         归一化 + 复合命令拆分 + 状态改变检测
  adapter.ts         纯适配：ToolExecution → GuardRequest
  notify-text.ts     通知文案（纯函数）
defaults/rules.json  默认规则种子
tests/               单元测试

License

MIT