dsh-guardrail

@jypjypjypjyp/dsh-guardrail

工具调用规范守卫：对 agent 工具调用输入参数做字符串匹配，命中危险行为则拦截（deny）并注入原因给模型，或放行但注入警告（warn）。附规则管理面板（配置/启停/增删/试跑/审计全部可在 UI 完成）。

能力

• 挂 tools/pre-execute（waterfall）：deny → 工具不执行 + 原因注入模型可见错误；warn → 放行 + tools/post-execute 注入独立警告消息
• 内置 11 条高风险规则（删根/提权/管道执行远程代码/强推主分支/fork bomb 等），可启停、可覆盖动作（deny/warn）
• 用户规则存 ~/.dsh/guardrail-rules.json，面板编辑即热加载
• 面板（React 注册为会话视图 guardrail 标签页）：规则列表/启停/增删/动作切换、测试匹配器、添加规则、审计视图
• 经 webServer 暴露 /guardrail/api/*（rules 增删改查、test 试跑、audit、config）
• 审计：内存环形缓冲（默认 200）+ 可选文件日志
• 匹配/加载异常一律放行（fail-open），不阻断正常流程
• 正则支持 lookbehind（需 Node/浏览器 V8），可写「必须 uv pip」这类约束规则
• 面板样式只使用 DSH 系统主题 token（--dsw-alias-* / --ds-*），无自定义硬编码颜色；随亮/暗主题自动切换，与整站统一

安装

注意：仓库 .gitignore 排除 lib/（构建产物不提交）。克隆或下载后必须构建才能被 DSH 装配。

git clone <repo-url> dsh-guardrail
cd dsh-guardrail
bash scripts/build.sh        # 链接 DSH 安装依赖 + tsc(host) + tsdown(client)

构建产物：lib/index.js（host）、lib/client.js（browser bundle）、lib/types/index.d.ts。

装配进 web profile（持久化，重启自动加载）

本地做以下两步即装配（免重启可用注入器，重启后仍生效）：

1. package.json 加 dsh.bundle.patch（已内置 cordis.patch.yml）。
2. 在 profile 的 dsh.profile.bundles 数组追加 dsh-guardrail（并建 node_modules 的 link: 指向本仓库）。

或使用 dsh-super-injector 的 dev_inject_plugin / dev_install_package 热装配。启动后浏览器进入任一会话，右上标签页出现 guardrail 即加载成功。

使用说明（图文）

1. 找到面板

打开 DSH 网页（如 http://127.0.0.1:3080），进入任意会话，在顶部标签栏点击 guardrail（位于「对话 / 轨迹」右侧）。

2. 配置区（顶部卡片，见图「面板-配置与规则」上部）

• 启用守卫：总开关，关闭后所有规则不再拦截/警告
• 规则文件：用户规则 JSON 路径（只读展示），默认 ~/.dsh/guardrail-rules.json
• 启用内置规则：是否启用 11 条内置规则
• 审计上限：内存环形缓冲条数（如 200）
• 日志文件：可选，把审计写入该文件

3. 规则管理

每条规则一行，含：

• 图标：📦=内置规则、📝=用户规则
• 动作徽章：🟥 deny 拦截 / 🟨 warn 警告
• 目标工具 + 正则（截断显示）
• 停用 / 启用：切换启停；停用后整行加划线，更醒目
• deny / warn 下拉：切换动作——内置规则经 builtins.overrides 保存，用户规则直接改记录
• 删除：仅用户规则有（内置规则不可删，删需 API 403）

所有修改即时持久化到 ~/.dsh/guardrail-config.json 与 ~/.dsh/guardrail-rules.json。

4. 测试匹配器与添加规则

• 测试 / 添加规则：填「工具名」（如 bash）+「参数 JSON」（如 {"command":"rm -rf /"}），点 试跑，下方显示命中的规则与片段：
  • ✅ 命中 rm-root · 片段: rm -rf / → 该输入会被对应规则拦截/警告
  • 未命中 → 匹配不到任何启用规则

• 添加规则：填 id（必填）、正则 pattern（必填）、动作 deny/warn、reason（可用 {tool} / {pattern} 占位）、tools（逗号分隔，空=全部）、field（可选参数路径，如 command），点 添加规则 即热加载。

5. 审计

面板底部「审计（最近 30 条）」实时展示：[时间] action tool → ruleId reason。为拦截/警告行为留痕。

规则字段

id · tools?（目标工具，空=全部）· pattern（正则）· field?（可选参数路径，如 command）· action（deny|warn）· reason（支持 {tool}/{pattern}）· enabled

内置规则 builtin: true：不可删除、不可改 pattern，可经 builtins.overrides 启停/覆盖动作。

用命令锚定约束「必须走 uv」

例：pip 必须用 uv pip、python 必须走 uv run：

• deny (?:^|[;&|]\s*|"command":")(?:[^\s"]*/)?pip3?\b —— 禁止直接 pip 执行
• deny (?:^|[;&|]\s*|"command":")(?:[^\s"]*/)?python3?\b —— 禁止直接 python 执行

pattern 锚定命令起点：字符串开头（或 JSON 参数 "command":" 前缀）、;/&&/| 之后，且允许路径前缀（如 /usr/bin/python）。这样只拦「真正执行的命令」，不会误伤 echo python、grep -rn python src/、cd python 这类只是提到这个词的命令。

⚠️ 语义说明：(?<!uv[\s-])\bpip3?\b 这类裸 \b 词边界版本，会命中任意出现的 pip/python（含 echo python、grep pip），误报严重；且它只豁免紧跟 uv 的 uv pip，不会豁免 uv run pip（run 隔在中间）。如果你确实想拦截上述误报空窗，请用上面的命令锚定版。

配置（profile cordis.patch.yml）

- id: guardrail
  disabled: false
  config:
    rulesFile: ~/.dsh/guardrail-rules.json
    builtins:
      enabled: true
      overrides:
        - id: git-reset-hard
          action: deny   # 示例：把内置 warn 规则升级为 deny
    audit:
      maxEntries: 500
      logFile: ~/.dsh/guardrail-audit.log

API

GET /guardrail/api/rules · POST /guardrail/api/rules · PUT /guardrail/api/rules/:id · DELETE /guardrail/api/rules/:id · POST /guardrail/api/test · GET /guardrail/api/audit（可 ?action=warn|deny|error） · GET /guardrail/api/config · PUT /guardrail/api/config

错误码：400（非法输入/JSON）。内置规则不可删除（403）、未知路由 404。

POST /rules 只要求 id/pattern/action（服务端校验），reason/enabled 走默认值，tools/field 可选透传。

构建

bash scripts/build.sh    # 链接 DSH 安装依赖 + tsc（host） + tsdown（client）

注：源文件相对 import 使用 .js 扩展（NodeNext ESM 规范），测试文件使用 .ts（vitest 转译，且被排除出 host tsc）。测试运行用本地 node_modules/.bin/vitest。