权限规则引擎 christinafernandez37/dsh-permission-rules

🛡️ dsh-permission-rules

- 1024 store channel：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-permission-rules（会计入 deepseek1024.com 的安装排行）。

dshfind

Claude Code 风格的声明式权限规则，用于 DeepSeek Harness。

规则决定已知的部分。审核模型决定未知的部分。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 40+ plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-permission-rules 是什么？

Claude Code 风格的声明式权限规则，用于 DeepSeek Harness。

规则决定已知的部分。审核模型决定未知的部分。
dsh-permission-rules 终端演示：dsh-permission-rules —— 在一个 YAML 文件里写 deny/ask 规则

dsh-permission-rules 动画终端演示

同一次运行，动画版。

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（适配于 2026-09-22，完整门控链）：它的插件配置就是实时的设置契约 —— 每个字段都声明为 .volatile()，Loader 把每个字段的实时引用交给 apply，保存的修改会提交进正在运行的引用里，无需重新挂载插件，越界值在写入任何东西之前就被 schema 拒绝。如果宿主机的 Schemastery 早于 volatile()（3.18.3 之前），这个插件照样能挂载运行 —— 字段只是保持普通值，实时配置表单不可用 —— 因为标记是通过能力探测施加的，而不是假定存在。这一线上的 Session.append 仍然无法打上 ignorable 标记（它的第三个参数是 surface-intent 包，envelope 字段只为读取已存日志而保留），所以整个 0.2-alpha 线都预先按未标记处理，会话日志审计默认关闭 —— append 只读 sourceEventSeqs/surfaceOp 并冻结 envelope，因此它没有任何代码路径能打上标记；更早的 0.1.7-alpha（适配于 2026-09-22）、0.1.5-rc.2（适配于 2026-09-09）和 0.1.3-alpha 线保持同样的 surface-only append 签名，每个 0.2 预发布版都和它们归为一类（STABLE 的 0.2.x 正式版留给 append 探测，这样一旦标记层面恢复，无需发布新插件就能采用）。这些线的日志迁移会拒绝未分类的插件事件，即使它们已标记，所以在 0.1.3-alpha 宿主机打开日志之前先 strip 掉 v1 审计行，在 0.1.5-alpha 宿主机迁移日志之前先 strip 掉 v2 审计行（原生 v3 日志只需 repair）。 |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（宿主机 + Web 设置客户端） |
| 模型 | 任意（deny/ask 的理由通过工具结果呈现） |

你能得到什么

dsh-permission-rules 在 tools/pre-execute 瀑布流上，为每次工具调用前置一份有序的 allow / deny / ask 规则列表 —— 确定、即时、可审计，由你用纯 YAML 编写：

- deny 拦截调用；规则的 reason 成为模型可见的错误。
- ask 走官方审批接缝（挂载 dsh-auto-review 由第二个模型作答，或由人来答；两者都没有时，harness 按失败关闭处理）。
- allow（以及无匹配）严格通过 next() 委托 —— 下游监听器绝不会被短路。

每次命中和每次放行都会作为 permissionRules/decision 会话事件记入审计日志（仅写日志 —— 不会向模型上下文注入任何额外内容）。
- 丰富的匹配能力 —— 工具名 glob（含 mcp__）、智能体身份选择器（main / subagent / preset:）、参数键值 glob 或正则（支持 !pattern 取反和 absent 键维度）、任意嵌套深度的工作区相对路径 glob、when 主机条件（环境变量、平台），以及shell 命令分解（argv：命令词、参数 token、管道签名），实现 token 级精确的命令匹配。
- 内置高风险基线 —— 随包附带一套 deny/ask 规则集（破坏性命令、提权、下载即执行、敏感路径），默认启用，追加在用户规则之后，因此更靠前的用户规则可以覆盖它；用 builtin.enabled 开关。
- 分层规则文件 —— 可选的 searchUp 会从会话 cwd 一路向上合并到文件系统根目录的每个 .dsh/rules.yaml，最近的优先。
- 试运行上线 —— enforce: false 只审计策略本会做什么，同时放行每一次调用。
- 热重载 —— Chokidar 监听并带防抖；改坏了会保留之前的规则，绝不崩溃。在 WSL 主机上，或规则文件位于 /mnt/<drive> 下时，监听会切换为轮询，因为那里的原生变更事件不可靠。
- 报错要响 —— 无效 YAML、未知 action/字段、错误的 glob/正则、容易回溯的模式，或规则数超过 maxRules，都会让加载失败。

规则语法

<project>/.dsh/rules.yaml
rules:
- match: { tools: [bash, pwsh], params: { command: "git push" }, paths: ["/secrets/"] }
action: deny
reason: "No pushes from protected paths"

- match: { tools: [edit, write] }
action: ask
reason: "File writes need confirmation"

- 匹配维度 —— tools（glob，含 mcp__）、agents（main / subagent / preset:<name>；未知身份永不匹配 —— 失败即关闭）、params（键值 glob 或正则，!pattern 取反，absent 键维度）、paths（工作区相对 glob，在任意嵌套深度提取）、when（env 变量 glob/正则 + 封闭的 platform 列表），以及 network（domains / ips / ports / schemes —— glob、通配符、CIDR、端口范围）。
- 动作 —— allow / deny / ask，按文件顺序求值，先匹配者胜。
- 规则元数据 —— enabled: false（可见但不生效）、description、tags；未知字段会让加载失败。
- Schema —— JSON Schema 随包附在 docs/rules-format.schema.json（编辑器补全用 # yaml-language-server: $schema=...）；完整词汇表和一套 5 条规则的安全基线在 docs/rules-format.en.md。

网络策略

Codex 风格的进程级网络策略：shell 子进程流量走内置的本地 HTTP/CONNECT 代理，每个连接由有序的网络规则决定，或由映射到官方沙箱预设的三种模式决定：

- deny-all —— 只读沙箱预设：阻断所有出站。
- whitelist —— workspace-write 预设：放行列表中的目标，其余目标走 unlisted: ask（或 deny）。
- allow-all —— danger-full-access 预设：全部放行。
- auto（默认）—— 跟随沙箱预设；在没有 sandbox-policy 服务的主机上，解析为 autoFallback（allow-all）。

- 匹配 —— match.network 支持 domains / ips / ports / schemes（glob、通配符、CIDR、端口范围；YAML 里写成数字的端口也接受）。tools/pre-execute 热路径上的 URL 候选提取，会针对 web 工具的入参、以及 bash/pwsh 命令文本里内嵌的 URL 触发；loopback 目标可以按 loopback 策略短路规则。IPv4-mapped IPv6 字面量在匹配前会归一化成 IPv4 形式，代理连接的地址就是做决策时用的地址 —— 绝不二次 DNS 解析 —— 如果一次裁决没有解析出任何地址，连接直接失败关闭（502），而不是去拨号那个域名。
- 上游链式转发 —— network.upstreamProxy（默认 off）把本代理放行的连接送到上游代理：CONNECT 向上游请求隧道（CONNECT host:port），纯 HTTP 请求则以绝对形式转发过去。被拦截的目标永远不会到达上游 —— 它拿到的仍是本插件的结构化 403。有两种情况即使配了上游也不会链式转发：loopback 目标（本机之外的代理无法路由它的 loopback），以及任何由 ips 作用域规则产生的裁决（链式转发会把主机名交给上游，「连接落在规则看到的地址上」—— issue #21 —— 就会恰好在规则关心地址的地方失效；这类裁决继续直接拨号裁决出的地址），另外还有 scheme 没有可用上游的目标。上游自己的主机名属于运维配置，不是智能体输入，不受这些规则裁决。带凭据的 URL 绝不原样输出：警告、/rules network 和设置快照都会把密码打码（http://user:@host:port）。上游不可达、超时（10 s）、或返回非 2xx，一律得到 502* —— 这里刻意不做静默回退到直连，好让配置错误一直可见。
- 审计 —— 被拒绝的连接会往所属会话追加 permissionRules/network（同样走自适应 ignorable 门控），/rules network 和设置页里能看到拦截计数和最近的拦截记录。
- 诊断 —— 被拦截的连接会带一条 [network: …] 消息，写明被拦截的目标、做出裁决的模式或规则，以及补救办法。
- 在设置页面允许 — 每次近期拦截都提供 Allow 操作。它会在真正判定该连接、且距离最近的规则文件顶部（索引 0）写入一条最小规则 match: { network: { domains: [<host>] } } / action: allow：如果该拦截归属于某个工作区，就写该工作区的项目文件（配置了绝对 rulesFile 时写该文件）；如果是无会话的主机级拦截，就写主机链解析出的文件（绝对 rulesFile → 已存在的 <processCwd>/<rulesFile> → 配置的 fallbackPath → <processCwd>/<rulesFile>，不存在则创建）—— 加载了多个工作区时，页面会先弹出选择器，因为任何已加载工作区链的优先级都高于主机链。之所以放在索引 0，是因为规则采用首个匹配生效：追加到已有的 deny 之后，这条规则就成了死文本。只写 domains，是因为这个维度包含子域名，且与端口、协议无关，所以主机在下一个端口上不会被重新拦截；已有注释和未改动的规则都会保留，文本也要经过与手动编辑相同的校验关卡。改动立即生效 —— 缓存的各工作区链和无会话主机链都会重新读取，无需重启，也无需 /rules reload —— 并且会重新计算判定结果，所以通知报告的是真实结果，绝不会在连接仍被拦截时声称成功。以下情况会拒绝写入并保持文件不变：未知工作区、目标不在已知规则来源内、只读的内置基线、以及无法读取或解析的文件；已经允许的连接不会写入任何内容。network.allowHostAction: false 会隐藏按钮，并让 RPC 拒绝执行。

快速开始

dsh plugin --profile web add github:PerryLink/dsh-permission-rules

1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-permission-rules

or from npm (published releases)
dsh plugin --profile web add dsh-permission-rules

2. restart and verify the row
dsh --profile web --dump-config | grep -A4 'id: permission-rules'

安装与卸载

- git 渠道（最新的 main）：dsh plugin --profile web add github:PerryLink/dsh-permission-rules —— prepare 脚本只用生产依赖构建。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-permission-rules。
- tarball 渠道：在本仓库执行 pnpm pack，然后 dsh plugin --profile web add ./dsh-permission-rules-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-permission-rules。

配置

所有可调项都是 Schemastery Config 字段，可在 cordis.yml 中修改。按 id 定向的覆盖会替换整行——你需要把每个键都重新写一遍。在 0.1.7-alpha 宿主机上，每个字段都声明为 .volatile()，所以也能在 Plugins 设置页里就地编辑：编辑结果会提交到运行中的引用，不会重新挂载插件，运行时下次用到时读取新值；改动 network.proxyPort、proxyBind、injectEnv 或 noProxy 会立即重新绑定本地代理。数值边界写在 schema 里，配置编辑器在持久化之前会按该 schema 解析合并后的配置，所以超出范围的值在写入时就会被拒绝。如果宿主机的 Schemastery 早于 volatile()，这些字段就只能改 cordis.yml。

| 键 | 默认值 | 含义 |
| rulesFile | .dsh/rules.yaml | 规则文件位置；相对路径按调用会话的 cwd 解析，绝对路径为全局路径，挂载时校验 |
| fallbackPath | （无） | 按 cwd 查找无果时使用的规则文件；挂载时校验 |
| badFilePolicy | fail | 规则文件损坏时的行为：fail 让待处理的工具调用大声报错；ignore-with-warning 发出警告并以空规则继续 |
| maxRules | 256 | 有效来源链上规则数量的硬上限 |
| maxCachedWorkspaces | 512 | 按工作区缓存的规则加载数量硬上限（LRU 淘汰） |
| patternMode | glob | params/paths/when.env 的模式风格：glob 或 regex（工具名始终是 glob） |
| watch | true | Chokidar 监听 + 变更时重载 |
| watchStabilityThresholdMs | 200 | 重载防抖窗口（毫秒） |
| language | en | /rules 输出语言：en、zh、es、pt、hi |
| caseInsensitivePaths | （win32） | paths 模式与工作区根目录比较忽略 ASCII 大小写；Windows 上为 true |
| audit | all | 审计粒度：all 记录每次命中以及放行；hits 跳过放行事件 |
| searchUp | false | 从会话 cwd 向上遍历父目录，合并找到的每个规则文件，最近的优先 |
| maxGlobStars | 2 | 每个 glob 模式中无界 / 量词的硬上限 |
| enforce | true | false = 演练模式：deny/ask 命中会带 dryRun 标记写入审计日志，每次调用都放行 |
| allowUnmarkedAudit | false | 早于标记机制的宿主机缺少 ignorable 标记；插件会禁用会话日志审计并发出警告。设为 true 可重新启用 |
| network.enabled | true | 代理、环境变量注入和 web 工具模式默认值的总开关 |
| network.mode | auto | 策略模式：auto 跟随沙箱预设，也可用 deny-all / whitelist / allow-all |
| network.autoFallback | allow-all | auto 找不到沙箱策略服务时使用的模式 |
| network.unlisted | ask | 白名单模式下没有规则匹配的目标如何处理：ask 或 deny |
| network.proxyBind | 127.0.0.1 | 本地代理绑定地址（仅限回环） |
| network.proxyPort | 0 | 本地代理端口；0 表示自动挑一个空闲的临时端口 |
| network.proxyMaxRecent | 100 | 设置页保留的最近拦截记录条数上限 |
| network.loopback | allow | 回环地址目标：allow（与 Codex 行为一致）或 policy |
| network.injectEnv | true | 是否为子进程注入代理环境变量 |
| network.noProxy | clear | 子进程的 NO_PROXY 处理方式：clear 强制执行策略，preserve 则保留原值 |
| network.upstreamProxy | off | 本插件放行的连接走哪个上游代理：off 直连，inherit 复用启动环境里的代理名，也可以直接写 http(s):// 代理 URL |
| network.allowHostAction | true | 设置页里针对单条拦截的「允许此主机」操作：false 会隐藏 Allow 按钮，并让 permissionRules/allowHost RPC 拒绝执行（规则编辑器不受影响） |
| builtin.enabled | true | 内置高风险基线：false 会彻底禁用随包附带的 deny/ask 规则集 |
| builtin.path | （随包附带）* | 替换用的基线文件（绝对路径，或相对于 process.cwd()）；挂载时校验 |

工具与界面

| 界面 | 类型 | 说明 |
| tools/pre-execute | 监听器 | 首个匹配生效的 allow/deny/ask 规则 + 网络 URL 候选提取 |
| /rules | 命令 | list · reload · decisions [n] · test <tool> <json> |
| permissionRules/decision | 事件 | 只写日志的审计，覆盖每次命中与放行 |
| permissionRules/network | 事件 | 代理层的审计，记录被拦截的连接 |
| HTTP/CONNECT 代理 | 服务 | 内置本地代理，管控 shell 子进程流量 |
| 设置页 | 客户端 | 网络模式编辑器、规则编辑器、拦截计数、最近拦截记录，每条都带「允许」操作 |

/rules 列出生效的规则、来源文件，以及最近一次重载的错误 /rules list 裸列出的显式别名 /rules reload 重新读取当前工作区的规则文件链 /rules decisions [n] 显示本会话最近 n 条权限决策（默认 10） /rules test <tool> <json> 对一次假想调用做规则试算

/rules test 还接受前置标志：--cwd <dir>、--env KEY=VALUE（可重复）、--agent <selector>（可重复）、--platform <name>。在多文件链里（例如 searchUp），列出的每一行规则都会标注它自己的来源文件。

权限与数据

- 权限：在 workshop manifest 里声明 files:read、files:watch、files:write、session:append、network:outbound。ask 决策走官方审批通道——没有重新实现，也没有绕过。
- 数据：规则文件只从磁盘读取，不写入任何规则数据。不调用模型，不使用审查子代理。
- 会话日志：permissionRules/decision 永远不会注入模型上下文，追加时带上信封的 ignorable: true 标记，因此任何 harness 构建都能加载这份日志。

安全边界

- 是策略，不是内核。 paths 候选只来自一组有文档记录的参数键（at