"bash" matches rule 1 (deny): 禁止 push 到受保护路径

Invalid JSON arguments "{not json": the arguments must parse as JSON.

# <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:；未知身份永不匹配——失败关闭）、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.md。

网络策略

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

• deny-all —— 只读沙箱预设：阻断所有出站。
• whitelist —— workspace-write 预设：放行列表目标，其余按 unlisted: ask（或 deny）。
• allow-all —— danger-full-access 预设：放行一切。
• auto（默认）—— 跟随沙箱预设；无沙箱策略服务的宿主上解析为 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 没有可用上游的情况。上游自身的主机名是运维配置而非 agent 输入，不参与这些规则的裁决。带凭据的 URL 绝不原样输出：警告、/rules network 与设置页快照都会把口令打码（http://user:@host:port）。上游不可达、超时（10 秒）或返回非 2xx 一律 502*——刻意没有静默回退直连，配置错误因此始终可见。
• 审计 —— 被拒连接向所属会话追加 permissionRules/network（同样的自适应 ignorable 门），块计数器与近期拦截在 /rules network 与设置页展示。
• 诊断 —— 被拦截的连接带 [network: …] 消息，点名被拦目标、做出裁决的模式或规则，以及处置办法。
• 设置页放行 —— 每条近期拦截都提供放行动作：它在真正裁决该连接的最近一个规则文件的最前面（索引 0）写入一条最小的 match: { network: { domains: [<主机>] } } / action: allow 规则——被拦截连接所归属工作区的项目文件（配置了绝对 rulesFile 时即该文件）；对无会话归属的宿主级拦截，则写宿主链解析出的文件（绝对 rulesFile → 已存在的 / → 配置的 fallbackPath → /，不存在则创建）。加载了多个工作区时，页面先提供工作区选择器——任何已加载的工作区链都优先于宿主链。之所以放在索引 0：规则首个匹配生效，追加在既有 deny 之后只会成为死文本。只写 domains：该维度包含子域且与端口/scheme 无关，因此同一主机在下一个端口上不会被重新拦截；既有注释与未改动规则原样保留，文本与手工编辑走同一道校验门。写入即刻生效——缓存的工作区链与无会话宿主链都会重读，无需重启、无需 /rules reload——随后重新计算裁决，因此提示报告的是真实结果，绝不在连接仍被拦截时声称成功。以下情况一律拒绝且磁盘文件分毫不动：未知工作区、不在已知规则源内的目标、只读的内置基线、无法读取或解析的文件；连接已被放行时不写入任何内容。network.allowHostAction: false 隐藏按钮并让 RPC 拒绝。

配置

所有可调项均为 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 | (none) | 按 cwd 发现无果时使用的规则文件；挂载时校验 | | badFilePolicy | fail | 坏规则文件：fail 响亮地令待处理工具调用出错；ignore-with-warning 警告并空继续 | | maxRules | 256 | 生效源链上规则总数的硬上限 | | patternMode | glob | params/paths/when.env 模式风格：glob 或 regex（工具名始终为 glob） | | watch | true | Chokidar 监听 + 变更重载 | | enforce | true | false = 试运行：deny/ask 命中带 dryRun 标记审计，每个调用都透传 | | language | en | /rules 输出语言：en、zh、es、pt、hi |

FAQ

安全边界

• 是策略，不是内核。 paths 候选只来自一组文档化的参数键（任意嵌套深度、有深度上限），且仅工作区相对路径匹配。
• 这里没有评审者。 插件绝不生成子代理或调用模型——产出 ask 决策就是其工作的终点。
• 不改沙箱。 OS 级沙箱策略属于沙箱接缝，与本插件无关。
• 响亮地拒绝错误配置。 未知 YAML 字段、未知 action 与坏模式在加载期被拒绝。
• 回溯界限。 glob 模式以 maxGlobStars 限制无界星号展开；正则模式拒绝嵌套无界量词与量化重叠字面交替。
• 关闭失败的拨号。 明文 HTTP 转发与 CONNECT 隧道只连接裁决到的地址；裁决未解析出任何地址的 allow 以 502 关闭失败，而不是按名字拨号（issue #23）。

权限与数据

• 权限：workshop 清单声明 files:read、files:watch、files:write、session:append 与 network:outbound。ask 决策走官方审批接缝——不重实现、不绕过。
• 数据：规则文件从磁盘读取；常规裁决不写任何规则数据，唯一的写面是设置页的规则编辑器与「放行」动作。无模型调用、无评审子代理。
• 会话日志：permissionRules/decision 绝不注入模型上下文，并以信封的 ignorable: true 标记追加，任何 harness 构建都能加载日志。

已知限制

• 前标记宿主与拒绝型宿主上的审计标记。 permissionRules/decision 以 ignorable: true 追加；Session.append 早于该标记的宿主（0.1.0-rc.1–rc.7 与 0.1.1-rc.1–rc.7 线）静默丢弃它，0.1.2-rc 线沿用 alpha.5 表面（append 无任何选项能写该标记），0.1.2-alpha 线在读取时连已标记的插件事件也拒绝，0.1.3-alpha 与 0.1.5-alpha 线同样沿用 surface-only 追加签名（已在已发布的 0.1.3-alpha.1/0.1.5-alpha.1 包上核验）——运行时在首次追加前即预检这些线并以一次性警告禁用会话日志审计。跨代迁移同样拒绝已标记的审计行：0.1.3-alpha 的 v1→v2 门拒绝未知 v1 事件，0.1.5-alpha 的 v2→v3 门拒绝一切未分类事件（其清单冻结为已发布 v2 词汇），故在 0.1.3 宿主打开日志前 strip v1 行、在升级到 0.1.5 宿主前 strip v2 行。v3 原生日志接受已标记的插件行，只需 repair。设 allowUnmarkedAudit: true 重新启用；用 scripts/repair-session-logs.mjs 修复已写日志（标记无济于事的宿主用其 strip 模式移除审计行）。
• 路径候选是启发式的。 只有文档化的参数键参与路径匹配，且工作区相对匹配仅在 caseInsensitivePaths 开启时忽略 ASCII 大小写。
• glob 是保守子集。 无花括号展开——写两个模式，或用正则模式。
• 正则回溯守卫是结构性的、非穷尽的。 对不可信文件优先用 glob 模式。
• 宿主自身的出站请求不经过本代理。 注入的代理环境覆盖派生的 shell 子进程（这正是注入的用途），以及在请求时读取代理变量名的消费者；它不覆盖宿主进程自身基于 fetch 的流量——launcher 在第一个插件挂载之前就用启动环境装好了 undici 的全局 dispatcher，该 dispatcher 按策略而非按环境路由，且 Node 在启动时采样代理环境，因此后挂载的插件无法改变它。结论：供应商端点不需要允许规则，network.injectEnv: false 也不会把宿主进程移出任何东西。2026-09-10 实测于 Node 22；用 scripts/host-egress-probe.mjs 可复现。
• 链式只覆盖到达本代理的流量。 在 dsh-v0.1.7-alpha.1 及之后的宿主上，harness 自身的启动期代理策略与其子进程环境覆盖可能优先于本插件注入的代理名，因此 network.upstreamProxy 描述的是本代理所处理连接的去向——它不是关于宿主进程每一条出站路径的断言。

与其他 DSH 插件的互操作性

已对照 DSH 0.2.0-rc.2（本 README 面向的运行时）与 2026-10-05 实测的高星插件集验证。

本插件不干扰其他插件，包括广泛安装的高星插件：

• 无工具名冲突。 所有工具都带命名空间，不占用任何已被内置工具或其他插件持有的裸名。
• 无服务键冲突。 只提供 permissionRules, permissionRulesRuntime；该键既不是内置 seam，也没有被任何已调研的高星插件提供。
• 无 slot 冲突。 不注册客户端 slot key，因此不参与 shadows-shipped-ui 座位争抢。
• 无 HTTP 路由冲突。 不注册任何 webServer 前缀。
• 无 patch 层冲突。 组合包 patch 只 insert 自己那一行，从不覆写内置行的 config。
• 无全局改写。 不改原型、不改写 process.env、不替换全局 fetch dispatcher。

• tools/post-execute — also used by cc-safety-net (1576★).
• tools/pre-execute — also used by cc-safety-net (1576★).

与 dsh-auto-review 协作

• dsh-permission-rules 产出 ask；dsh-auto-review 在 approval/request waterfall 上以只读第二模型裁决作答（或委托给人）。两者都挂载即得完整闭环。
• 集成测试：permissionRules/decision → approval/asked → autoReview/verdict → approval/decided，评审者以脚本化 mock 替换。
• 官方 harness 的 never 审批策略与每个失败关闭保证保持不变。

会话日志修复

在 ignorable 标记出现之前写入的会话日志可能被较新 harness 构建拒绝（SessionFormatUnsupportedError）。随附的 scripts/repair-session-logs.mjs 仅重写目标审计行以携带 ignorable: true，保帧、带备份：

node scripts/repair-session-logs.mjs scan [--home DIR]      # 报告外来行，不改任何内容
node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
node scripts/repair-session-logs.mjs strip [--home DIR] [--dry-run]

--home 默认 $DSH_HOME/sessions（或 ~/.dsh/sessions）。工具按规范基名发现每一代日志——session.jsonl、session.v2.jsonl、session.v3.jsonl，各自可选 .zstd 压缩——请按世代选择模式：

• v3（session.v3.jsonl，0.1.5-alpha 线原生写出） —— 读取路径接受已标记的插件行，repair 即可。
• v2（session.v2.jsonl，0.1.3-alpha 线写出） —— repair 可让写出它的宿主打开日志，但 0.1.5-alpha 的 v2→v3 迁移连已标记的未分类事件也拒绝：请在升级到 0.1.5-alpha 宿主之前对 v2 日志执行 strip。
• v1（session.jsonl） —— 0.1.3-alpha 的 v1→v2 迁移连已标记的未知 v1 事件也拒绝：请在 0.1.3 或更新宿主首次打开日志前执行 strip。

兼容性

| 维度 | 状态 | |---|---| | Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（2026-09-22 已适配，完整门禁链）：其插件配置即新的 live settings 契约——每个字段都以 .volatile() 声明，Loader 向 apply 逐个交付活引用，保存的编辑直接写入运行中的引用、不重挂插件，越界值在写入前即被 schema 拒绝。Schemastery 早于 volatile()（3.18.3 之前）的宿主仍能挂载并运行本插件——字段退化为普通值、live 配置表单不可用——因为该标记是能力探测而非假定存在。本线的 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-only 追加签名，且每个 0.2 预发布版都与它们同类（0.2.x 的稳定版交由追加探测判定，因此恢复盖章能力无需本插件再发版）。这些线的日志迁移连已标记的未分类插件事件也拒绝：在 0.1.3-alpha 宿主打开日志前 strip 掉 v1 审计行，在 0.1.5-alpha 宿主迁移前 strip 掉 v2 审计行（v3 原生日志只需 repair）。 | | Node | ^22.19.0 || >=24.9.0 | | Platforms | 全部（host + Web 设置客户端） | | Model | 任意（deny/ask 原因经工具结果呈现） |

生态与质量

• Gitee 镜像（同步镜像，以 GitHub 为准）
• dshfind 插件页（安装量与排名）
• OpenSSF Scorecard 报告（由 .github/workflows/scorecard.yml 驱动）
• dsh-plugin-doctor 验证报告（K10–K13 全 pass）
• DSH Market（已上架）
• 1024 商店渠道：先 npm i -g dsh1024，再 dsh1024 plugin --profile web add dsh-permission-rules（计入 deepseek1024.com 安装排行）
• 生态实测知识库：插件开发指南 · 选型实测数据 · 维护取舍判据

开发

pnpm install            # node ^22.19 || >=24.9
pnpm run typecheck      # tsc, src + tests
pnpm run lint           # eslint, src + tests + scripts
pnpm test               # vitest: 24 spec files
pnpm run test:coverage  # coverage gate (90/80/90/90)
pnpm run build          # tsc declarations + tsdown bundles (lib/)
pnpm run pack:check     # build + pack (the published artifact)
node scripts/check-readme-sync.mjs   # 五语 README 一致性门（CI 同款）

无头端到端验证记录见 VERIFICATION.md。README 配图由 scripts/gen-readme-assets.py 程序化生成（Pillow 绘制 1440×576 中英深浅双版 hero，手写 1100×660 双通道结构 SVG），可重复执行。

Topics：dsh, dsh-plugin, deepseek-harness, permission, policy, allow-deny-ask, approval, safety, network, network-policy, proxy

家族与致谢

本项目是 PerryLink 维护的 DeepSeek Harness 插件家族成员（全部 Apache-2.0）。如果这个插件帮到了你，给个 star——它不解锁任何功能，但会让下一个人更容易找到它。

• @PerryLink —— 创建者与维护者：规则词汇与求值、运行时、HMR 监听、会话日志审计、网络策略 + 代理，以及五语文档。
• @am-i-dead —— 把客户端安全的 allow-host helper 从 host-only 模块中拆出（#24）。
• @22xuan —— 关于 rc.6 宿主静默丢弃审计事件 ignorable 标记的详细报告（#2）与上游 harness 讨论；v0.4.1 的运行时宿主能力检测与文档更正直接源自该分析。
• @sjh9714 —— 提出共享规则语法测试向量语料（#4、#5），已于 v0.5.1 以 docs/rule-test-vectors/ 落地，并在方案讨论中补充了 AST 分解的边界用例。
• @weipeng1999 —— 提出基于 AST 的命令分解功能（#8），促成该方案讨论。
• @alexchenzl —— DSH 目录收录请求（#7）。
• @zl190 —— 报告并验证了 0.1.0-rc.7 harness 兼容性缺口（PR #9）。
• @cuohua —— 报告版本门仅覆盖 0.1.0 线后，0.1.1-rc 线仍静默丢弃 ignorable 标记（#11）；加宽后的版本门直接源自该分析。

License

LICENSE（Apache License 2.0）© 2026 dsh-permission-rules contributors

_{Apache-2.0 · 社区插件，与 DeepSeek 无关。}

_{工具链：dsh-plugin-guide · dsh-standards · dsh-plugin-start}