权限规则 TolgaSoto/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 包，信封字段只用于读取已存储的日志），所以整个 0.2-alpha 线都预先判定为未标记，会话日志审计默认关闭 —— append 只读取 sourceEventSeqs/surfaceOp 并冻结信封，因此没有任何代码路径能打上该标记；更早的 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 级精确的命令匹配。
- 内置高风险基线 — 随包发布的 deny/ask 规则集（破坏性命令、提权、下载并执行、敏感路径），默认启用，追加在用户规则之后，因此更靠前的用户规则可以覆盖它；用 builtin.enabled 开关。
- 分层规则文件 — 可选的 searchUp 会合并从会话 cwd 到文件系统根目录的每个 .dsh/rules.yaml，最近的优先。
- 试运行上线 — enforce: false 只审计策略将会做什么，同时放行每一次调用。
- 热重载 — Chokidar 监听并防抖；改坏了会保留之前的规则，绝不崩溃。在 WSL 主机上，或规则文件位于 /mnt/<drive> 下时，监听切换为轮询，因为那里的原生变更事件不可靠。
- 大声失败 — 无效 YAML、未知动作/字段、错误的 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 预设；在未提供 sandbox-policy 服务的主机上，解析为 autoFallback（allow-all）。

- 匹配 — match.network 支持 domains / ips / ports / schemes（glob、通配符、CIDR、端口范围；接受 YAML 数字端口）。在 tools/pre-execute 热路径上，URL 候选提取会针对 web 工具参数以及 bash/pwsh 命令文本中嵌入的 URL 触发；回环目标可按 loopback 策略短路规则。IPv4 映射的 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 操作。它会在真正判定该连接的那个规则文件里，把一条最小规则 match: { network: { domains: [<host>] } } / action: allow 写到顶部（索引 0）：如果拦截归属到某个工作区，就写该工作区的项目文件（配置了绝对 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 | 重新加载的防抖窗口（ms） |
| 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 候选只来自一组有文档记录的参数键（位于