一句话定位

在 DeepSeek Harness 的每个工具调用前面立一道 YAML 写成的允许/拒绝/询问闸门，按工具名、参数、路径、Agent 身份、网络目标做匹配；叠加一个本地 HTTP/CONNECT 代理统一管控子进程出网，所有命中都写只读审计日志，但模型看不到也不被阻断以外的副作用干扰。

核心能力

• 有序规则链：按文件顺序对每条工具调用做"首匹配胜"评估，命中规则就产出 allow/deny/ask 三种动作；deny/ask 截断后续，allow 与无匹配严格 next() 放行，绝不阻断下游。
• 丰富匹配维度：工具名 glob（支持 mcp__*）、Agent 身份选择器（main/subagent/preset:<name>，未知身份永不匹配——失败兜底）、参数键值 glob 或 regex（含 !pattern 否定与 absent 缺失维度）、工作区相对路径任意嵌套、when 主机条件（环境变量 + 平台白名单）。
• 进程级网络策略：内置本地 HTTP/CONNECT 代理统一管控 shell 子进程出网，规则上可以用 match.network 的 domains/ips/ports/schemes（glob、通配、CIDR、端口范围）做目标匹配；三种网络模式自动跟随官方沙箱预设（只读→全禁、工作区写入→白名单、danger-full-access→全放）。
• 热重载与层次文件：Chokidar 监听规则文件改动，带防抖；编辑坏了保留旧规则不崩；可选 searchUp 把父目录的 .dsh/rules.yaml 一并合并（近的优先）。
• 完整只读审计：每次命中和每次放行都写入 permissionRules/decision 会话事件（带 ignorable 标记），代理拦截另写 permissionRules/network；日志不进入模型上下文，仅供事后回溯。
• 可视化设置面板：在 Web profile 增加一个"Permission Rules"设置页，展示网络模式摘要、拦截计数、最近拦截列表和规则编辑器，所有数据通过 Typert 远程接口获取。

技术实现

• 语言: TypeScript（ESM，strict 模式；客户端 React 18）
• 关键依赖: @deepseek-ai/cordis + @deepseek-ai/schemastery（插件加载与 Config 校验）、chokidar（规则文件监听）、yaml（规则文件解析）、react（Web 设置面板）
• 架构模式: 函数式 cordis 插件（name/inject/Config/apply，无默认导出）；apply 注册 tools/pre-execute 监听器、/rules 命令、设置 section、本地代理；Web 半包通过 Typert 远程接口与 host 通信。规则匹配为纯函数（无 I/O、可回放、可单测）。
• 入口文件: src/index.ts（host 入口）、src/client/index.ts（Web 设置面板入口）、src/runtime.ts（核心装配与 apply）、cordis.patch.yml（profile bundle patch）

适用场景

适合需要给 AI Agent 工具调用加上"白/黑/灰名单"的项目：比如保护 secrets/ 与 .env 不被任意编辑、限定网络出站只能命中受信任 API、要求敏感操作走二次审批。典型用户是希望在不写代码的前提下、用纯 YAML 配置文件就给一个会话乃至整个组织加一道可审计、可热更新、可追溯规则来源的安全护栏的个人或团队。

前置依赖与兼容性

安装方式

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

配置项

常见问题

Q: 安装后规则还没生效？

A: 装上只是把插件挂到 profile 里，必须重启 profile 才会出现 id: permission-rules 行；之后还要在工作目录放一份 .dsh/rules.yaml（或通过 fallbackPath 配置兜底文件），没规则就等同于"全部放行"。

Q: 跟 dsh-auto-review 是替代关系还是互补？

A: 互补。本插件产出 ask 走审批通道，dsh-auto-review 在审批通道上挂第二个 AI 模型做裁决；只装本插件时 ask 走人类或 host 默认行为，两个一起装才形成"规则筛选 + 模型复核"的闭环。

Q: 想先观察新策略会不会误伤怎么办？

A: 在 cordis.yml 把 enforce 临时设成 false 进入 dry-run：所有 deny/ask 命中只写带 dryRun 标记的审计日志，不阻断调用，事件照常流向下游；观察完再切回 true。

Q: 写错的 YAML 会怎样？

A: 默认 badFilePolicy: 'fail'，等待执行的工具调用直接报错，HMR 重载场景下保留上一次成功加载的规则、绝不崩；想要宽容一点，改成 ignore-with-warning 即可警告并按空规则继续。

Q: 网络策略默认怎么走？要怎么改？

A: 默认 network.enabled: true 且 network.mode: 'auto'，跟随官方沙箱预设（只读→全禁、工作区写入→白名单、danger-full-access→全放），host 没沙箱服务时回落到 autoFallback（默认 allow-all）。想固定就把 mode 显式写成 deny-all/whitelist/allow-all 之一。

Q: 装了为什么旧 host 上看不到审计事件？

A: 0.1.0-rc.6 及之前的 host 会丢弃 ignorable 标记，导致审计事件不带标记、破坏会话在新 host 上的恢复。插件会主动降级为不开会话日志审计并打印一次性警告；想保留就把 allowUnmarkedAudit: true 设上，但旧日志可能需要跑一次 scripts/repair-session-logs.mjs repair 修一遍。

Q: 怎么查看当前生效的规则和最近决策？

A: 在会话里跑 /rules 列出全部规则与来源文件，/rules reload 强制重载当前工作区的规则链，/rules decisions [n] 看最近 n 条本会话决策（默认 10），/rules test <tool> <json> 还能不真触发工具调用就干跑一次规则比对。

Q: 怎么卸载？

A: 一行 dsh plugin --profile web remove dsh-permission-rules 即可，事务式卸载，不影响 profile 之外的其它插件或会话状态。

上手难度

入门 — 配置以纯 YAML 为主，配置文件存放在工作区根目录即可立即生效；遇到复杂匹配维度（agent 选择器、CIDR、回溯防护）再回头查文档。

已知问题与限制

• 旧 host 的审计降级：0.1.0-rc.1–0.1.0-rc.7 系列的 Session.append 不识别 ignorable 标记，插件主动降级为不写会话日志审计并打印一次性警告；保留审计需设 allowUnmarkedAudit: true，并接受旧会话在新 host 上可能需要 scripts/repair-session-logs.mjs 修复。
• 路径候选是启发式的：只有文档列举的参数键（url/path/file_path 等）参与路径匹配，且仅匹配工作区相对路径；非约定键、绝对路径之外的引用不会被规则覆盖。
• Glob 是保守子集：不支持花括号展开，需要写两条规则或切到 regex 模式；maxGlobStars（默认 2）会拒绝过多无界星号的 glob 以防回溯。
• Regex 回溯防护是结构性的而非穷举的：能挡住常见的灾难模式（嵌套无界量词、量化字面量重叠交替），但不是完整的 ReDoS 检测，不受信文件建议留在 glob 模式。
• 代理层 ask 不能进入交互式审批通道：本地代理没有会话上下文，遇到需要审批的目标只能以结构化消息拦截并写 permissionRules/network 审计，模型通过 shell 工具的错误输出看到原因；只有 Web 工具的 ask 走真正的交互审批。

---

Compatibility

What you get

dsh-permission-rules puts an ordered allow / deny / ask rule list in front of every tool call on the tools/pre-execute waterfall — deterministic, instant, auditable, and written by you in plain YAML:

• deny blocks the call; the rule's reason becomes the model-visible error.
• ask rides the official approval seam (mount dsh-auto-review for a second-model answerer, or a human answers; with neither, the harness fails closed).
• allow (and no-match) strictly delegates via next() — downstream listeners are never short-circuited.

Every hit and every passthrough is audit-logged as a permissionRules/decision session event (log-only — nothing extra is injected into the model context).

• Rich matching — tool-name globs (including mcp__*), agent-identity selectors (main / subagent / preset:*), argument key/value globs or regexes (with !pattern negation and an absent key dimension), workspace-relative path globs at any nesting depth, and when host conditions (env vars, platform).
• Hierarchical rule files — optional searchUp merges every .dsh/rules.yaml from the session cwd to the filesystem root, nearest first.
• Dry-run rollout — enforce: false audits what the policy would do while passing every call through.
• Hot reload — Chokidar watch with debounce; a broken edit keeps the previous rules, never crashes.
• Fail loud — invalid YAML, unknown actions/fields, bad globs/regexes, backtracking-prone patterns, or more than maxRules rules fail the load.

Rule syntax

# <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"

• Match dimensions — tools (globs, incl. mcp__*), agents (main / subagent / preset:<name>; unknown identity never matches — fail closed), params (key/value globs or regexes, !pattern negation, absent key dimension), paths (workspace-relative globs extracted at any nesting depth), when (env var globs/regexes + a closed platform list), and network (domains / ips / ports / schemes — globs, wildcards, CIDRs, port ranges).
• Actions — allow / deny / ask, evaluated in file order, first match wins.
• Rule metadata — enabled: false (visible but inert), description, tags; unknown fields fail the load.
• Schema — a JSON Schema ships at docs/rules-format.schema.json (editor completion via # yaml-language-server: $schema=...); the full vocabulary and a 5-rule security baseline live in docs/rules-format.en.md.

Network policy

A Codex-style process-level network policy: shell subprocess traffic flows through a built-in local HTTP/CONNECT proxy, and every connection is decided by ordered network rules or by three modes mapped onto the official sandbox presets:

• deny-all — the read-only sandbox preset: block all outbound.

• whitelist — the workspace-write preset: allow listed targets, unlisted: ask (or deny) for the rest.

• allow-all — the danger-full-access preset: allow everything.

• auto (default) — follows the sandbox preset; on hosts without the sandbox-policy service it resolves to autoFallback (allow-all).

• Matching — match.network with domains / ips / ports / schemes (globs, wildcards, CIDRs, port ranges; numeric YAML ports are accepted). URL-candidate extraction on the tools/pre-execute hot path fires on web-tool arguments and URLs embedded in bash/pwsh command text; loopback targets can short-circuit rules per loopback policy.

• Audit — denied connections append permissionRules/network to the owning session (same adaptive ignorable gate), with block counters and recent interceptions in /rules network and the settings page.

Quick start

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

# 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'

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main" — the prepare script builds with production dependencies only.
• npm channel (published releases): dsh plugin --profile web add dsh-permission-rules.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-permission-rules-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-permission-rules.

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need.

Tools & surfaces

/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 also accepts leading flags: --cwd <dir>, --env KEY=VALUE (repeatable), --agent <selector> (repeatable), and --platform <name>. In multi-file chains (e.g. searchUp), every listed rule line is attributed to its own source file.

Permissions & data

• Permissions: declares files:read, files:watch, files:write, session:append, and network:outbound in its workshop manifest. ask decisions ride the official approval seam — nothing is re-implemented or bypassed.
• Data: rule files are read from disk; no rule data is written. No model calls, no reviewer subagents.
• Session log: permissionRules/decision is never injected into the model context and is appended with the envelope's ignorable: true marker so any harness build loads the log.

Security boundaries

• Policy, not a kernel. paths candidates come only from a documented set of argument keys (at any nesting depth, depth-capped), and only workspace-relative paths match.
• No reviewer here. The plugin never spawns subagents or calls models — producing an ask decision is the end of its work.
• No sandbox changes. OS-level sandbox policy belongs to the sandbox seam, not this plugin.
• Loud misconfiguration. Unknown YAML fields, unknown actions, and bad patterns are rejected at load.
• Backtracking bounds. Glob patterns are capped at maxGlobStars unbounded star expansions; regex-mode patterns reject nested unbounded quantifiers and quantified overlapping literal alternations.

Known limitations

• Audit marker on pre-marker hosts. permissionRules/decision is appended with ignorable: true; hosts whose Session.append predates the marker (the 0.1.0-rc.6 line) silently drop it, so the runtime disables session-log audit with a one-time warning. Set allowUnmarkedAudit: true to opt back in; repair already-written logs with scripts/repair-session-logs.mjs.
• Path candidates are heuristic. Only the documented argument keys feed path matching, and workspace-relative matching is ASCII-case-insensitive only when caseInsensitivePaths is on.
• Globs are a conservative subset. No brace expansion — write two patterns, or use regex mode.
• The regex backtracking guard is structural, not exhaustive. Prefer glob mode for untrusted files.

Collaborating with dsh-auto-review

• dsh-permission-rules produces ask; dsh-auto-review answers on the approval/request waterfall with a read-only second-model verdict (or delegates to humans). Mount both for the full closed loop.
• Integration-tested: permissionRules/decision → approval/asked → autoReview/verdict → approval/decided, with the reviewer replaced by a scripted mock.
• The never approval policy and every fail-closed guarantee of the official harness stay untouched.

Session log repair

Session logs written before the ignorable marker existed can be refused by newer harness builds (SessionFormatUnsupportedError). The shipped scripts/repair-session-logs.mjs rewrites only the targeted audit rows to carry ignorable: true, frame-preserving, with backups:

node scripts/repair-session-logs.mjs scan [--home DIR]      # report foreign rows, change nothing
node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]

--home defaults to $DSH_HOME/sessions (or ~/.dsh/sessions).

Development

pnpm install            # node ^22.19 || >=24
pnpm run typecheck      # tsc, src + tests
pnpm run lint           # eslint, src + tests + scripts
pnpm test               # vitest: 139 tests, 9 suites
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   # five-language README sync gate (also in CI)

See VERIFICATION.md for the headless end-to-end verification record.

Topics

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

Contributors

• @PerryLink — creator and maintainer: rule vocabulary and evaluation, runtime, HMR watch, session-log audit, network policy + proxy, and the five-language docs.
• @22xuan — the detailed report on rc.6 hosts silently dropping the audit event's ignorable marker (#2) and the upstream harness discussion; the v0.4.1 runtime host-capability detection and the documentation correction drew directly from that analysis.

PerryLink DSH Plugin Family

This project is one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0 © 2026 dsh-permission-rules contributors