dsh-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。为拦截/警告行为留痕。

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

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

配置（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