dsh-superagent Policy 静态校验器
把
settings.json粘进面板之前,离线看清:这份 Policy 会让谁获得授权、哪些规则会静默失效、策略版本一变哪些 Mandate 会失守。
作者:吴昭睿 · 2026-11-05 · v0.1.0 · Node ≥ 20 · 85 tests passing
English abstract. An offline, zero-dependency linter for dsh-superagent policies. Upstream zod already rejects malformed settings at save time; this tool targets the semantic failures it cannot see — mode=off making rules inert, an explicit admission cell disabling the allow-list, an admission cell the Source row never offers, and a policy-version change that invalidates live Mandates. It also projects the admission matrix and reproduces the upstream policy hash.
目录
它解决什么问题
dsh-superagent 是 DeepSeek 的常驻编码 Agent。它的 settings.json 决定三件事:谁能让它开工(admission)、它能主动接什么活(rules + eval mode)、活怎么跑(executor)。上游用 zod 校验形状,形状错误在保存时就会被拒绝——但下面这些配置形状完全合法:
| 你以为 | 实际 |
|---|---|
| 写了 3 条规则,Agent 会主动接活 | eval.mode="off",inferred 候选永不产生,规则全是摆设 |
| 只允许白名单里的人 | 某行 unlistedAddressed="explicit",任何人 @ 一下就能开工 |
| 这个群只收 @ 消息,但配了未 @ 的准入格 | 该行根本不提供那个格子,配了等于没配 |
行名写成 issue |
GitHub Source 产生的是 issues,这一行永远不会出现 |
禁掉 gh 更安全 |
上游直接拒绝整份配置——worker 没 gh 就跑不了 Ticket |
| 改一条规则文案没关系 | policyVersion 变了,所有 inferred Mandate 在 resume 时要重新过 auto + 规则启用检查 |
这个工具就盯这些。结构校验只做兜底,不跟 zod 抢活。
快速开始
需要 Node ≥ 20(本机实测 24.18)。
# 1) 合法配置:0 条 error,退出码 0
node src/cli.js check --settings examples/valid/settings.json --deployment examples/valid/deployment.json
# 2) 含错配置:1 条 error + 3 条 warning,退出码 1
node src/cli.js check --settings examples/invalid/settings.json --deployment examples/invalid/deployment.json
# 3) 准入矩阵:谁会被放行
node src/cli.js matrix --settings examples/valid/settings.json
第 3 条会列出 GitHub 的 issues / pulls / comments / ci 四行、<default> 行,以及每格是配置值还是默认值;x 表示该行不提供这一格。
一分钟演示
npm run demo
会依次跑:合法配置(exit 0)→ 含错配置(exit 1)→ 准入矩阵 → 策略版本对比 → 目录统计。作品的一页式说明见 docs/PORTFOLIO.md。
作为 DSH Skill 安装
git clone https://github.com/huanlin-labs/dsh-policy-validator.git ~/.dsh/skills/dsh-policy-validator
之后在 DSH 里让 Agent 用 dsh-policy-validator 技能校验 dsh-superagent 的 settings.json / deployment.json。技能说明见 SKILL.md,完整操作指南见 docs/GUIDE.md。
命令
| 命令 | 作用 | 参数 |
|---|---|---|
check |
校验 settings(可选 deployment),输出诊断 | --settings(必填)、--deployment、--format text|json、--strict、--max-warnings N、--expect <hash> |
matrix |
展开每个 source 的准入行与三格有效值 | --settings、--format |
version |
打印 mandate-v3 内容哈希;--compare 比较两份配置的授权影响 |
--settings、--compare、--expect |
rules |
列出 62 条诊断码 | --format |
退出码:
0:没有 error;warning / info 不阻断1:有 error;--strict下 warning 也算;--max-warnings超预算也算;--expect哈希不符也算2:参数错误、文件不存在、JSON 解析失败、--format非法
check --format json 的 stdout 是纯 JSON,诊断与错误信息只走 stderr。报告里的 inputs.settings 是解析后的绝对路径,同一文件在不同 cwd 下得到同一份 JSON。
--expect 的正确用法:
node src/cli.js check --settings settings.json --deployment deployment.json \
--format json --expect d54ad3d321d6995db10cd73992427aa2
不匹配时报告里 expectation.match=false、ok=false,退出码 1。
诊断码
共 62 条:51 条结构(DEP 12 / POL 9 / SRC 10 / EVAL 5 / EXE 8 / X 7)+ 11 条语义(SEM001–SEM011)。完整目录见 docs/RULES.md,每条的上游文件与行号见 docs/UPSTREAM.md。
所有诊断的 source 都以 upstream: 开头,指向上游仓库的 src/(例如 upstream:src/policy.ts:197);本仓库没有 src/policy.ts,不要把 upstream: 后面的路径当成本仓库文件。
语义检查是最有价值的部分:
| 码 | 级别 | 触发条件 | 后果 |
|---|---|---|---|
| SEM001 | warning | mode=off 且有启用规则 |
inferred 永不产生,规则全是摆设 |
| SEM002 | warning | mode=auto 但无启用规则 |
admitsInferred 要求至少一条规则,auto 等同 observe |
| SEM003 | warning | 任一 unlistedAddressed=explicit |
该 scope 的白名单失效,任何人 @ 即开工 |
| SEM004 | warning | 配了该行不提供的准入格 | 值再合法也不影响任何 Trigger |
| SEM005 | error | blockedCommands 含 gh/git/lark-cli(精确匹配) |
上游直接拒绝整份配置 |
| SEM006 | warning | paused=true |
服务暂停,其余 Policy 全部闲置 |
| SEM007 | warning | Policy 指向未知 kind,或实例 enabled=false |
整块 Policy 不可达 |
| SEM008 | info | 有 admission 行但 allowed 为空 |
只剩 unlisted 路径,listed 快捷方式永不生效 |
| SEM009 | warning | 规则 name 重复(忽略大小写) | 面板与提示词按 name 展示,审计困难 |
| SEM010 | warning | 所有规则都 disabled | accept 永远 noRuleMatched |
| SEM011 | warning | admission 行名不是该 Source kind 产生的 id | 该行永远不会成为 Trigger |
准入矩阵
matrix 不是把 admission 原样打印,而是按 Source kind 投影:
- GitHub:
issues、pulls、comments、ci四行。observeIssues/Pulls/Comments/Ci决定该行是否提供未 @ 的两格;ci只提供unlistedUnaddressed。 - Feishu:
config.chats里每个chatId一行,外加other与direct。listen="all"的群提供未 @ 两格;otherChats="mentions"决定other行;directMessages决定direct行。 <default>:始终显示三格的全局默认(inferred / ignore / ignore)。
一个列在 allowed 里的人直接 @ Agent,永远是 explicit,不读任何格子(src/policy.ts:197)。
策略版本与影响面
version 复刻上游 src/policy.ts:116-118:
key(POLICY_REVISION, JSON.stringify({ rules, mode, sources }))
= sha256(JSON.stringify([...])).slice(0, 32)
因此 paused、模型、maxWorkers 变化不会改哈希;rules / eval.mode / policy.sources 任一变化会。--compare 额外给出影响面:
- 离开
auto⇒INFERRED_MANDATES_LOSE_AUTO(所有 inferred Mandate 失守) - 删/禁规则 ⇒
MANDATES_LOSE_RULE(匹配它的 Mandate 失守) - 删 source ⇒
MANDATES_LOSE_SOURCE(该来源的 Mandate 无法重验证)
deployment 与 settings 的分工
这是最容易配错的地方,本工具按上游实际读取位置校验:
| 内容 | 位置 |
|---|---|
插件 Config(deployment.json) |
只有 stateDir、promptMaxChars、admissionContextMaxPages、admissionContextTimeoutMs |
| GitHub 仓库与 CLI | settings.sources.github.config.repository / .cli |
| Feishu CLI 与群 | settings.sources.feishu.config.* |
上游 src/app/setup.ts:76-85 把 settings.sources.github?.config 传给 resolveDeployment;把 github 写进插件 Config 会被 machineOf 以 "configuration has keys it does not use" 拒绝(src/deployment.ts:38-42)。DEP002 会明确提示迁移到 Source。
fixtures 与测试
fixtures/cases/:47 个用例,每个含settings.json、deployment.json、expected.json。expected.json记录退出码、码集合,以及 每条诊断的 code/severity/path 快照;测试逐条deepEqual,不是只比码集合。- 覆盖:每个 catalog 码至少被一个用例触发;
test/fixtures.test.js强制检查。 node --test:85 个测试(规则单测、47 个 fixture 快照、API 冒烟、Node 20 兼容守卫、CLI 端到端与 demo)。node scripts/check-fixtures.mjs:单独核对全部 fixtures。node scripts/gen-fixtures.mjs:重建 fixtures(改规则后先跑这个,再核对expected.json的意图)。node scripts/gen-docs.mjs:从src/catalog.js重建docs/UPSTREAM.md与docs/RULES.md。
目录
src/
model.js 上游常量、默认展开
kinds.js GitHub/Feishu 的准入行投影
report.js 诊断模型、稳定排序、退出码
matrix.js 准入矩阵
version.js key() / policyVersion / comparePolicies
catalog.js 62 条诊断码目录
checks/semantic.js SEM001–SEM011
checks/structure.js DEP/POL/SRC/EVAL/EXE/X
index.js 对外 API(validate)
cli.js CLI
SKILL.md DSH Skill 入口
fixtures/cases/ 47 个用例
test/ 85 个测试
docs/ UPSTREAM / RULES / ARCHITECTURE / PRIOR-ART
scripts/ 生成与核对脚本
架构图见 docs/ARCHITECTURE.md。
设计取舍
- 语义优先,schema 兜底:形状错误上游 zod 已经拦;本工具的价值在“形状合法但语义不符预期”。
- 零依赖:只用 Node 标准库,CI 里
node src/cli.js即可跑,不需要npm install。 - 稳定输出:诊断按 severity → path → code 排序,去重键为 code+path+message;比较用 code unit,不用受 locale 影响的
localeCompare。 - 不猜运行态:不联网、不调用
gh/lark-cli、不启动服务;所有结论只来自两份 JSON。 - 快照明确:所有上游引用都是相对仓库的
src/...:行号,并锁定mandate-v3。
它不做什么
- 不验证登录态:本工具不执行
gh auth status或lark-cli auth status;凭据问题只在运行时暴露。 - 不替代 zod:结构校验是兜底,不是逐字节等价;保存时的最后一道门仍是上游。
- 不判断运行时行为:Eval 超时、投递、重试、面板交互都不在范围内。
- 不做自动修复:只给
hint,不擅自改配置。
快照与许可
- 上游:
deepseek-ai/dsh-superagent-prototype,2026-10-31 发布,POLICY_REVISION="mandate-v3"。 - 先例调查:2026-11-05,公开可检索范围内未发现同类的离线 Policy 校验器;检索式与盲区见
docs/PRIOR-ART.md。 - 许可证:MIT(见
LICENSE)。复用上游常量与默认规则文本的部分在NOTICE中注明上游 MIT 与快照日期。 - 变更记录:
CHANGELOG.md。提交前审查:docs/REVIEW.md(三路独立审查与复核结论)。
上游日更。升级快照时按这个顺序复核:src/policy.ts 的 schema 与常量 → src/deployment.ts → src/sources/github.ts / feishu.ts 的 policy.rows() → docs/UPSTREAM.md 的映射 → scripts/gen-docs.mjs 的 SOURCES。
No comments yet. Be the first to write one.