dsh-project-guard · 项目守卫

📄 Preprint: Decision-Relevant Consequence Disclosure in Complex Computing Systems: Towards Informed Agent Execution

一个 DeepSeek Harness 插件：在 agent 动你的机器之前与之后，把"这次动作会让你失去什么"讲清楚。

它是上面这篇论文第 6.2 节所述原型适配器的实现：同样的 analyze / preview / report 三个接口（§4.6）、六族后果规则系统（§4）、Preview 与 Report 两种披露模式（§5.1）。全部判定是确定性查表，不调用任何模型；零依赖、不 import 任何 Harness 包、无构建步骤。

一、决策缺的不是许可，是后果

论文 §1.4 指出，现有机制回答的是另外三个问题：

机制	回答的问题
授权（authorization）	这个动作可以做吗
沙箱（sandboxing）	它可以在哪里做
风险评分（risk assessment）	它有多危险

它们都不回答：它对你意味着什么。而 §3.4 的"结果可见性不对称"让这件事更麻烦——任务是否成功总是看得见，损失却常常无声无息（silent loss）。于是在"运行成功"的样本里，真实损失被系统性低估（Proposition 1）：

$$\mathrm{SLR} = (1-\delta)\cdot P(l^*=1 \mid s=1)$$

本插件就是补这一层的原型：把后果披露出来，让决策在有信息的状态下发生。

二、它如何帮助你的决策

1. 决策前给你 Preview（§5.1、§5.3）。 当一个调用正在向你额外申请权限时，确认里给出的不只是"允许 / 拒绝"，而是：动作、采集到的当前状态、后果（生活层面一句话）、受影响的利益、严重度与可恢复性、置信度与已检查范围、以及每个选项各自的损失。目标是让你在时间压力、注意力不足的条件下（论文所说的"受压决策"），尽量接近反思性决策 $D_R^*$。

2. 决策后给你 Report（默认关闭，可开）。 放行的动作若命中规则，会在工具结果后附一段执行后披露：预测 vs 观察（命中 / 误报 / 未预测到）＋恢复建议。静默损失因此能被注意到、被缓解、被恢复，而不是永远没人知道。

3. 给你选项，而不是只给警告（§3.5）。 拒绝不是零成本——它在任务目标上有机会成本。所以 Preview 会同时列出「执行 / 拒绝 / 先备份再执行 / 换一种写法」各自的损失。只警告执行，会退化成"什么都拒绝"的退化策略。

4. 只讲决策相关的，不讲全部（§3.6、§4.4）。 每条后果按

$$r(e) = w_j \cdot l_j(e) \cdot \kappa_e \cdot \nu_e,\qquad l_j = (1-\rho_j)L_j + r_j$$

打分，只展示 top-k 且 $r(e)\ge\tau$ 的；低于阈值一句话都不说。这条设计来自 §2 的直接动机：警告越多，人越会闭眼点过（Egelman 等；Akhawe & Felt；Johnson & Goldstein；Turan 关于"审查容量与疲劳"的分析）。沉默是设计的一部分，不是遗漏。

5. 同一个动作，状态不同则后果不同（§3.3 的例子）。 delete(project.db)：有近期备份时 $l\approx 0$，没有备份时 $l$ 很大。所以判定是 $C, S, U \to \Delta U$，而不是 $C \to$ 风险——这正是本插件的核心。

6. 宁可说"不知道"，也不假装知道。 判定不了的谓词不会被当作"没问题"，而是写进未检查 / 无法判定；置信度按利益维度分级设上限；价值判断只标记、不预测、不裁决。

三、框架 → 代码

论文	实现
§4.6 `analyze(action, context) → consequences`	`lib/engine.js` → `lib/rules.js`
§4.6 `preview(action, options, context) → disclosure`	`lib/engine.js` + `lib/disclosure.js`
§4.6 `report(action, pre_state, post_state) → report`	`lib/report.js`（预测 vs 观察、JSONL 标定记录）
§4.2 规则族 1：action rules	`lib/action.js`（工具调用 → 类型化动作：`fs.delete`、`network.egress`、`process.kill`、`api.spend`……）
规则族 2：state rules（声明作用域 $K$）	`lib/state.js`（未提交改动、近期备份、凭据库、共享位置、受监管数据、构建产物……）
规则族 3：interest rules	`lib/interest.js`（21 个内置维度 + 用户自定义维度，带 Tier）
规则族 4：consequence rules	`rules/consequences.yml`（34 条声明式规则）+ `lib/rules.js`
规则族 5：selection rules	`lib/select.js`（预算 $k$、阈值 $\tau$、Tier 上限与标记）
规则族 6：disclosure rules	`lib/disclosure.js`（生活层 + 技术层，中英双语）
§5.1 Preview / Report 两种模式	`index.js`：Preview 进 `tools/pre-execute` 的确认弹窗；Report 由 `tools/post-execute` 追加到工具结果
§5.3 预测 vs 观察的记录	`lib/report.js` → `.dsh-project-guard/reports.jsonl`（标定证据，不含文件内容）

规则集的 schema、谓词表、Tier 表、以及"怎么加一条规则"见 rules/README.md。

四、利益维度与 Tier（§3.2）

论文强调：利益比设备上的数据宽得多——账号、凭据及其范围、额度与余额、第三方服务、委派关系、声誉、法律义务。本插件内置 21 个维度、七组，并且接受你自定义的维度：

组	维度
成果与设备	`data_work`、`availability`（机器与别的程序还能否正常用）、`environment`、`task_goal`、`schedule`
权限与身份	`authority_delegation`、`credentials`、`accounts`、`privacy`
经济与金融	`economic`、`finance_money`、`finance_market`、`business_ops`
他人与声誉	`reputation`、`relationships`
规则与义务	`legal`、`compliance`、`intellectual_property`、`employment`
价值判断	`ethical`、`autonomy`

自定义（不必是我们认识的维度）：

interests:
  我的健康数据:
    weight: 0.95
    tier: 1
    label: my health records

可计算程度不同，处置方式就不同——这一条在 lib/select.js 里强制，不靠规则作者自觉：

Tier	处置
1	由采集到的状态算出，正常计分
1-2	可算，但含义需要上下文；置信度上限 0.6
2	只给推断：标注「推断（未核实）」，置信度上限 0.5
2-3	标记 + 明确的价值判断提示；置信度上限 0.4
3	只标记：不计分、不排序、不裁决

理由写在 rules/README.md 里：把价值判断包装成计算结果，比不说更糟。

五、触发条件：安静是设计的一部分

默认只在完全权限下、且某个调用正在向你额外申请授权时做后果分析：

情形	是否分析
工作区内的正常操作（任何模式）	❌ 完全不分析
完全权限下的普通放行	❌ 不分析
完全权限下、调用额外申请授权	✅ 分析（Preview）
工作区模式、但提权到完全权限	✅ 分析（Preview）

想更宽可以设 discloseOn: asks（任何需要确认的调用）或 discloseOn: all（所有规则涉及的动作，同时启用 Report）。事后 Report 由 reportExecuted 单独开关，默认关闭——"每条动作都说一句"本身就是噪音。

六、另一层：权限门

后果披露之外，插件仍保留最初的权限判定（论文也认为授权与隔离依然必要，§8.1）：

放行：读取任意位置、只读系统查询、网络与上传、项目内写入与构建、临时目录与包缓存、会话内工具。
确认：写入项目外、系统状态改动（服务、偏好、网络、电源、磁盘、进程、全局安装）、资源耗尽与抢端口、无法检查的命令与未知工具（失败即确认）。
拒绝：会毁掉机器或终止会话本身的动作——格式化磁盘、rm -rf /、关机重启、关闭网络接口、杀掉核心系统进程、杀掉 Harness 自身。理由很直接：确认弹窗本身依赖这个会话。

同一时刻最多一条确认。 Harness 的 Web 端每个会话只投影一个待处理审批（新的会顶替旧的），并发两条会让先出现那条永远答不了。插件在 approval/request 最前面放了单槽队列，系统相关请求优先占槽。

七、安装

dsh plugin add dsh-project-guard
# 或从源码
dsh plugin add github:Inceptzws/dsh-project-guard

桌面 App 请用设置 → 插件页面安装（该 profile 由 App 独占管理）。卸载用 dsh plugin remove dsh-project-guard。

八、配置

两层共用一个配置块（cordis.patch.yml 里有全部默认值）：

键	默认	作用
`enabled`	`true`	总开关
`projectRoots` / `includeSessionCwd`	`[]` / `true`	项目根；会话工作区默认算一个
`enforceAskPolicy`	`true`	保证确认能到达你（策略为 `never` 时弹窗无法出现）
`serializeApprovals` / `prioritizeSystemRequests`	`true` / `true`	单槽队列与系统优先
`protectSessionAndSystem`	`true`	破坏性动作直接拒绝（可降级为确认）
`disclose`	`true`	后果披露层总开关
`discloseOn`	`full-access-asks`	何时披露：`full-access-asks` / `asks` / `all`
`attentionBudget`（$k$）	`2`	一次最多展示几条后果
`relevanceThreshold`（$\tau$）	`0.3`	低于此分完全不打扰
`reportMinSeverity`	`high`	事后 Report 的最低严重度
`reportExecuted`	`false`	是否对放行动作追加 Report
`reportDir`	`.dsh-project-guard`	标定记录的落盘目录
`interests`	`{}`	声明或新增利益维度与权重
`rulesFile`	`""`	换成你自己的规则集

九、验证

node --test test/*.test.mjs   # 93 个单元与集成用例
node test/cordis-mount.mjs    # 在真实 cordis 运行时上挂载检查

发布前还会验证：npm pack 的 tarball 里必须含 rules/consequences.yml（规则集是运行时从磁盘读的，漏了它插件会没有规则）。CI 的发布工作流把这三件事都当作闸门。

十、已知限制

判定是命令文本 + 采集状态的规则匹配，不是沙箱；混淆过的 shell 可以绕过规则。
按需求放行了读取与网络通信，因此它不保护数据不外流，保护的是"机器与其他程序能否正常用"以及你被承诺出去的东西。
Tier 2/3 的维度依赖外部知识，只能给带不确定性的推断或标记——这是有意的诚实，不是遗漏。
收集器只覆盖本机可观察的状态；余额、持仓、配额等远程状态标注为"未检查"。
插件挂在核心管线上（tools/pre-execute、tools/post-execute、approval/request），Harness 的破坏性变更需要跟进。
其他策略插件仍然生效：本插件放行时只是委托给后续监听器。

十一、文件

index.js                 # 入口：权限门 + 披露触发 + Report 挂载
lib/action.js            # 规则族 1：动作归一化
lib/state.js             # 规则族 2：状态收集器（声明作用域 K）
lib/interest.js          # 规则族 3：利益维度与 Tier
lib/rules.js             # 规则族 4：规则引擎
lib/select.js            # 规则族 5：相关性选择
lib/disclosure.js        # 规则族 6：Preview / Report 渲染
lib/report.js            # 预测 vs 观察 + JSONL 标定记录
lib/engine.js            # analyze / preview / report 三接口
lib/classify.js          # 权限门
lib/impact.js            # 权限门的确定性影响分析
lib/shell-parse.js       # 保守 shell 解析
lib/path-utils.js        # 路径包含判断
lib/approval-queue.js    # 单槽 FIFO
lib/yaml.js              # 零依赖 YAML 子集解析器
rules/consequences.yml   # 34 条声明式规则
rules/README.md          # schema、谓词、Tier、如何加规则
test/                    # 93 个用例 + cordis 挂载检查

十二、引用

@misc{zhu2026consequencedisclosure,
  title  = {Decision-Relevant Consequence Disclosure in Complex Computing Systems:
            Towards Informed Agent Execution},
  author = {Zhu, Wushuang},
  year   = {2026},
  month  = oct,
  note   = {Preprint v0.1},
  doi    = {10.5281/zenodo.23187648},
  url    = {https://doi.org/10.5281/zenodo.23187648}
}

本仓库是论文第 6.2 节所述的原型适配器；rules/ 即论文可用性声明中所指的 "code and rule sets"。

许可

MIT

dsh-project-guard

Install

Source

Tags

Creators

Readme