权限规则 Rorato49012/dsh-permission-rules

🛡️ dsh-permission-rules

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

dshfind

为 DeepSeek Harness 提供 Claude Code 风格的声明式权限规则。

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

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 是什么？

为 DeepSeek Harness 提供 Claude Code 风格的声明式权限规则。

规则决定已知的部分。审核模型决定未知的部分。
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 的 append 签名，所有 0.2 预发布版都与它们归为一类（STABLE 的 0.2.x 版本交给 append 探测，这样恢复的标记 surface 无需发布新插件即可采用）。这些线的日志迁移会拒绝未分类的插件事件，即使已标记也一样，所以在 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 主机条件（环境变量、平台），以及命令行分解（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 策略短路规则。IPv4-mapped IPv6 字面量在匹配前归一化为 IPv4 形式，代理按做出决策时用的地址建立连接——绝不做第二次 DNS 解析——裁决没有解析出地址的连接直接失败关闭（502），不会去拨号主机名。
- 上游链式转发 — network.upstreamProxy（默认 off）把本代理放行的连接交给上游代理：CONNECT 向上游请求隧道（CONNECT host:port），纯 HTTP 请求以绝对形式转发给它。被拦截的目标永远到不了上游——它拿到的仍是本插件的结构化 403。即使配置了上游，两种情况也绝不链式转发：回环目标（本机之外的代理无法路由它的回环），以及任何由 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 模式和 workspace-root 比较忽略 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 list the active rules, their source files, and any last-reload error
/rules list explicit alias for the bare listing
/rules reload re-read the rule-file chain for this workspace
/rules decisions [n] show the last n permission decisions of this session (default 10)
/rules test <tool> <json> dry-evaluate the rules against a hypothetical call

/rules test 还接受前置标志：--cwd <dir>、--env KEY=VALUE（可重复）、--agent <selector>（可重复）、--platform <name>。在多文件链中（例如 searchUp），列出的每条规则行都归属到各自的源文件。

权限与数据

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

安全边界

- 是策略，不是内核。 paths 的候选值只来自一组有文档说明的参数键（位于