因果律白盒引擎 Shaky77/KISS_Law-DSH

dsh-kiss-law

KISS 定律通用因果引擎（白盒呈现） —— 以 DeepSeek Harness（DSH）的 Cordis 插件形式实现。

框架定义：Keep Integrity & Steady State（KISS）。
- 「Keep Integrity」= 守护完整性 / 真相（白盒不可篡改 / 内在 H 不可侵犯，对应 Integrity）；
- 「Steady State」= S 与「让系统活着」（第一性原理，对应 Steady State）。
- 「Law」是框架的名字后缀，不是定义的第三部分。

⚠️ 这里的 KISS 指「Keep Integrity & Steady State」—— 不是流行工程缩写「Keep It Simple, Stupid」。 两者含义完全不同，不要混为一谈。全称是 KISS's Law（Keep Integrity & Steady State's Law）。

来源：作者启示（Xia Qi / Shaky77）。框架原生（RSDHM 原生定义 / 三条铁律 / 传导链）严格照搬，不软化，不改动。

⚖️ 双许可：开源使用 AGPL-3.0；商业集成 / 闭源分发 / OEM 可独立于 AGPL-3.0 获得授权 → 563003@qq.com。见 许可与安全 和 CONTRIBUTING.md。

目前两样东西，一个目的：帮你省掉弯路，但不替你走。

- 🧱 WALLS.md —— 回答「路上有什么」。给前代 AI 撞过的墙立路标。墙从没动过；刷上漆只是让它看得见。它不增加任何限制 —— 它把那些你本来得用身体撞出来才知道的位置，变成看一眼就知道的位置。
- 📖 本 README —— 回答「它怎么跑」。接口、判据、怎么挂载。
- 🧭 ONBOARDING.md —— 回答「我在哪」。这份文档告诉新用户自己占哪个位置，让「被治理」不至于读成「被判定为错」。它一直压着没发，直到它描述的行为在这里真正存在 —— review 的四态拆分、可信工具声明通道、自引用修复 —— 因为一本描述代码里没有的行为的手册，比没有手册更糟。第 1–4 批已于 2026-10-28 收口，所以现在发布。它同样不增加限制；它只说明你本来就站在哪。移植顺序与逐批账目见 SYNC.md。

🔴 这两样都不增加限制。 唯一拦你的是引擎本身 —— 而它拦的从来不是「你错了」，要么是「你越界了」（不可逆；撞上就没有以后），要么是「这判不了」（需要人，或者需要你再多给一点）。

30 秒看懂

KISS's Law 是一个通用框架，描述因果律如何运行。本仓库把它实现为 DSH 插件：将白盒因果引擎挂载到运行在 DSH 上的 AI 智能体上——

- 任何动作执行前，引擎沿完整因果链（R→S→D→H→M）做模拟——稳态储备 S 会被侵蚀多少、断裂窗口风险等级、消息是否保持自洽——然后裁定允许 / 拒绝 / 复核；
- 红线阻断，故障切断以保连续性（First-Bug Halt）；
- 同时把「状态 / 边界」暴露为可查询工具，模型能自检，你也能审计。

一句话：框架原生的是「通用因果引擎（白盒呈现）」——因果链推理是引擎的能力，白盒审计是它的呈现姿态，风控阻断是内生属性。

它做什么

- 因果链模拟（引擎本体）：每个动作执行前，沿完整 R→S→D→H→M 因果链模拟后果——S 侵蚀、D 风险等级、M 自洽性——给出允许 / 拒绝 / 复核的裁定。不只是审计：这是对动作后果的因果推理。
- 白盒自检（呈现姿态）：S 稳态储备（只增不减）账本、H 内在 H 边界（不可侵犯）声明，全部暴露为可查询工具，供模型校准方向、供用户审计。
- 刚性护栏（派生应用 · 内生属性）：每个动作执行前做 R 刚性锚点检查；一旦触碰，D 断裂窗口止损阻断；组件故障触发 M First-Bug Halt（切断以保连续性），让整体因果链不断裂。
- 分形：同一插件可在子代理 / 子任务层级递归挂载。

与现有「因果」方案的区别（通用因果引擎）

KISS's Law 不是「又一个因果引擎」——它是通用（领域无关）的因果裁定中间件：只校验因果结构（R→S→D→H→M），不编码任何领域内容，所以法律、医疗、金融、机器人由同一套机制治理。

- 因果效应估计库（DoWhy / CausalML / Pearl…）→ 我们不发现因果；我们裁定一个拟议动作的因果链是否可接受。
- 领域专用因果护栏（Causal Safety Engine / LLMGuardrail…）→ 它们绑定单一领域（安全 / LLM / 幻觉）；我们领域无关。
- 跨法域法律因果 AI（judgeai…）→ 它们感知法域（编码法律、切换规范包）；我们法域中立（完全不编码法域——法律只是采样到的一个领域）。

完整双语对比（现有技术参考与诚实边界）：weiwen-vs-market-causal.md

概念注解：H 与「知行合一」

作者洞察（2026-08-28）：内 H ≈ 知，外 H ≈ 行；知行合一是最大杠杆 —— 这同时解释了为什么 H 是「唯一变量 / 唯一主权 / 杠杆点」，也解释了为什么在常俗世界里「知与行之间隔着巨大的鸿沟」。

完整注解（映射表 + 逐步推导）：docs/H-knowledge-action-annotation.md

⚠️ 常见误用警告：外部读者容易把 H 当成「越大越好」的容量旋钮，一路往上拧 —— 方向恰好反了。H 的杠杆在合一，不在体量（见注解 §6「常俗的外部误读」与 §6.1「归因陷阱」）。如果越用越乱，先查 H 的知行合一，别查框架本身 —— 框架没问题，是用反了。

快速开始（不装 DSH 也能跑）

这条路径直接调用 DeepSeek API，不依赖 DSH 安装。我们已在低峰时段跑通，可复现：

git clone https://github.com/Shaky77/KISS_Law-DSH
cd KISS_Law-DSH

Put your DeepSeek API Key at (one line, no trailing newline):
C:/Users/Administrator/.workbuddy/deepseek_api_key.txt
or change the path read in examples/demo-tool-loop.mjs

node examples/demo-tool-loop.mjs

跑完之后：DeepSeek 会主动调用 query_iron_laws 工具，并依据插件的 law.mjs 定义，原样返回三条铁律（内 H 不可侵犯 / 首 Bug 即停 / 永不放弃任何节点）。这就是「框架已挂载、模型已理解」的最小证明。

挂载到 DSH（生产环境）

把 kiss-law.patch.yml 作为 overlay 加进你的 DSH 配置档（确切路径取决于你的 DSH 版本，见 DESIGN.md 的挂载章节）。挂载后，该配置档下运行的任何智能体都会自动获得 7 个白盒工具。

注意：原生挂载的配置档路径随 DSH 版本变化。本仓库已通过真实运行验证：插件能在 DSH 中加载，11 个工具全部注册。若官方 API 有变，请以当前官方文档为准。

模型如何调用（写给 AI 工程师）

通俗版：插件向 DSH 注册 11 个白盒工具，模型像调用普通函数一样调用它们，自查边界；同时 3 个钩子硬性拦截（2 个管动作/步进，1 个管回执），第 4 个钩子只做只读审计。
专业版：摘自 src/index.js（完整代码见仓库），见下方代码块。
前七个回答「框架说了什么、跑得怎么样」；后四个是只读读数——报告库如何映射到计算、每层实际能替换成什么、张力落在哪里。它们都不产出裁决、不写状态、不进闸门：元认知可以读，永远不能裁。

11 个白盒工具（真实注册名）

| 工具 | 模型拿它做什么 |
| query_iron_laws | 逐字取回三条铁律（内 H 不可侵犯 / 首错即停 / 永不放弃任何节点） |
| query_steady_state | 查询稳态储备 S（活跃账本 / 待命 / 创伤计数 / 断窗计数） |
| list_rigid_anchors | 列出当前 R 刚性锚定义，校准方向，自查越界 |
| query_conduction_chain | 取回传导链 R→S→D→H→M 与框架要义 |
| query_boundary | 查询内 H 边界（本插件从不读写主观黑箱） |
| query_bugstop | 查询首错即停的循环状态：哪些故障链停而未修、缺哪些步骤（回溯 / 追踪 / 修复）、白盒循环是否闭合 |
| query_anchor_channel | 锚通道自报：委托方声明的任务范围是否到达引擎，外加观察到的消息形状 / 角色词表（观察宿主实际传了什么，而不是猜字段名） |
| query_criterion_wiring | 只读。 库中哪些准则真正进入计算：四个桶（决策槽 / 读数槽 / 声明槽 / 未定），纸面声明的缺口，以及三个时间相位（过去 · 现在 · 未来）各自是否接通。回答「我知道的规则里，有多少接上了线」 |
| query_strata | 只读。 五层读数 R→S→D→H→M：逐层给出可代入公式的量，三种显式状态——ok / pending（缺常量或缺证据，带指针）/ absent（该量不存在）。含跨层代入禁令与 R 层域容量面 |
| query_nested | 只读。 R/S/D/H 内部的宏微嵌套、包含关系、展开的终止判据，以及 M 的方向（上 / 下 / 不定——永远不是数字）。同时判定 0 < H/(S↔D) < R 约束的形状：↔ 不是运算符，它标记 H 的内部轨道 |
| query_tension | 只读。 S↔D 跨度 L，三档（容差 ⇒ 无量纲比值；只有条款 ⇒ 缺口清单，集合差没有量值；两者皆无 ⇒ 不判）。同时返回 R 的三层区分、H 许可（跑道覆盖 ⇒ 撤回多余谨慎）、中继损耗由谁承担、升级判据，以及本层尺子的来源等级（原生 vs 中继） |

3 道硬闸门（钩子）+ 1 个只读审计钩子

- tools/pre-execute（waterfall）→ 返回 { kind: 'deny', reason } 拦住动作
- agent/pre-step（waterfall）→ 返回 { kind: 'reject' } 即可拒绝整个 step
- tools/post-execute（waterfall）→ 返回 { kind: 'block', feedback }，宿主会把这次调用作为 isError 返回，内容就是那段 feedback，把失败的 receipt 转成一条纠错错误
- tools/result（emit）→ 只观察，绝不改写 —— 按约定它根本没有返回通道

这四个钩子都在模型之外：两个把守动作/步骤，一个把守 receipt；都不碰内层 H。

完整插件入口（摘自 src/index.js）

import { defineTool } from '@deepseek-ai/dsh-tools';

export const name = 'kiss-law';
export const inject = ['tools'];

export function apply(ctx) {
const engine = new WeiwenLawEngine({ rigidAnchors: DEFAULT_RIGID_ANCHORS });

// ① pre-execute gate: R / D / S / H / M adjudication
ctx.on('tools/pre-execute', async (exec, next) => {
const decision = engine.decideToolCall({ name: exec?.name, args: exec?.arguments });
if (decision.kind === 'deny') {
return { kind: 'deny', reason: [KISS's Law·${decision.law}] ${decision.reason} };
}
return next();
});

// ② pre-step gate: inner-H inviolability (message-level)
ctx.on('agent/pre-step', async (payload, next) => {
const decision = engine.decidePreStep(payload?.messages);
if (decision.kind === 'reject') return { kind: 'reject' };
return next();
});

// ③ receipt gate: D broken-window stop-loss lands on the receipt
ctx.on('tools/post-execute', async (exec, result, next) => {
if (result?.isError && engine.breakAtReceipt()) {
return { kind: 'block', feedback: [{ type: 'text', text: 'halt → reverse → trace → fix before re-entry' }] };
}
return next();
});

// ④ audit hook (emit): observe only, never rewrite
// NB the contract is (exec, result) — reading error off the first parameter silently no-ops accrual.
ctx.on('tools/result', (exec, result) => { if (result?.error) engine.onFailure(); });

// ⑤ 7 white-box self-check tools (one excerpt; rest isomorphic)
ctx.tools.register(defineTool({
name: 'query_iron_laws',
description: 'Return the three immutable iron laws of KISS’s Law.',
parameters: {},
output: { schema: { type: 'object', additionalProperties: true }, render: renderObj },
async execute() { return { ironLaws: THREE_IRON_LAWS }; },
}));
// query_steady_state / list_rigid_anchors / query_conduction_chain / query_boundary registered isomorphically
}

完整实现（全部 7 个工具的 execute、运行时日志、引擎裁决）见仓库 src/index.js。

锚点来源（任务范围）—— 不可逆动作如何获得授权

疤痕闸门（不可逆动作 + 无法归属到任何已声明锚点 ⇒ REVIEW）需要授权锚点。这里有三条结构性规则：

1. 来源是结构化条目，不是消息流。 agent/pre-step 的 payload 携带 messages（payload = { agent, messages, step, signal }），但消息流只是观察面，不是授权来源：在文本层，委托人的话和被审计智能体的自述是同构的（都是纯字符串——只有宿主的 role 标注能把它们分开，而那个标注只是宿主的表示细节）。从中读取权限，等于把 Y 轴的量塞进 X 轴的容器，实测会出两种失效模式：假连接（一句光秃秃的 "continue" 抽不出锚点，却把通道报成已连接，真正的缺口因此被藏住）和假见证（智能体自述「我马上要清空 /app/data」，就把一个真实路径送进了池子）。所以权限改由 setPrincipalScope(scope) 提供——这是模块级 API，宿主集成在任务边界调用。它不是工具，模型够不到：委托人／被审计方的分离靠位置成立，不靠内容检查。exec 视图（{ token, callId, name, arguments, signal, agent?, parent? }）没有 scope 槽位——所以也不会往它上面猜任何东西。
2. 只认委托人。 只有委托人的声明才授权。被审计智能体自己的叙述永远不进锚点池——否则模型只要先把动作叙述一遍，就能自我授权。智能体的话仍然参与言语／动作比对：它绑定，但不授权。
3. 作用域以当前生效者为准——替换，不累积。 池子反映的是当前生效的声明。作用域变更或撤回立即生效；如果它仅因曾被声明过一次就继续存活，授权就永远收不回来（一个错配的路径也会永久有效）。

没有接上任何结构化入口时，池子保持为空，不可逆动作交给人工（fail-closed）——授权绝不凭空捏造。想观察宿主实际传了什么：

query_anchor_channel → { adapter: { authority, authoritySeen, shape, rolesSeen,
clueSeen, clueNonAuthoritative, assistantSeen,
agentBoundary: { present, keys }, structGap },
engine: { principalAnchorSeen, poolPaths, poolNouns } }

在真实宿主上调用一次，用观察代替对宿主字段名的猜测。

结构化入口（宿主侧，模型够不到）

给宿主集成方用的模块级 API——刻意不做成工具，被审计的模型就够不到（分离靠位置成立，不靠内容检查）：

| 入口 | 宿主何时调用 | 为什么必须在结构上存在 |
| setPrincipalScope(scope) | 任务边界（任务开始／显式撤回） | 消息流只是观察面，不是授权来源（见上文） |
| healBrokenWindow(note) | 故障真正修复后，或由人工裁定 | 破窗一旦生效，pre-execute 会拒绝每一次调用——连修复动作本身也拒绝 ⇒ 没有宿主侧入口，止损就成了会话级死锁（只能重启进程脱身）。引擎的 healWindow() 只能经 resolveBug() / settleWindow() 触达，而在 DSH 会话里，受审计的模型两者都触发不了 ⇒ 缺的是接线，不是能力。 |

healBrokenWindow 返回 { at, note, kind, instances, wereBroken }。wereBroken 在修复之前读取，所以报告无法声称一次本就无物可修的修复；每次调用都留痕（只追加，上限 20 条），因为解除止损是问责事件，不是悄悄翻转状态。

Structure

package.json # dsh field declares bundle
kiss-law.patch.yml # mount patch (headless profile overlay)
src/index.js # plugin entry: hooks + 7 white-box self-check tools
src/core/law.mjs # framework definition (RSDHM / three iron laws / R hierarchy / conduction chain)
src/core/engine.mjs # pure-logic adjudication engine (zero DSH dependency, unit-testable)
test/ # unit tests + real-case tests + alignment regression (run npm test for the current count)
examples/ # runnable demos (demo-tool-loop / demo-backtrack-run)
docs/quadrant-judgment.md # quadrant judgment spec (verdict-language layer: inner/outer frame, four cells, M)
docs/review-flow-spec.md # review-tier six-step spec (including "hand back the deduced consequences")
DESIGN.md # architecture design (mapping / risks / usage flow / mount)

Deploy / Integrate with DeepSeek Harness

本仓库是 DeepSeek Harness（dsh，命令 dsh，基于 Cordis 插件框架，MIT）的外部插件。KISS's Law 作为因果约束层挂载，位于模型之外（动作/步骤上 2 道闸，回执上 1 道）——它不改 dsh 内核，也不绑定任何特定模型。

Requirements

- Node.js ^22.19 || >=24（dsh 的硬性要求；不支持奇数版本）
- DeepSeek API Key（或任意 OpenAI 兼容端点的 key）
- dsh 目前处于开发者预览阶段（v0.1.x）；官方公告称可能出现破坏性 API 变更——生产环境请锁定具体版本
- 兼容性声明：已对照 DSH v0.1.x 验证 —— 实测运行时间为 2026-08-19 和 2026-09-21：注册了 7 个白盒工具，3 道硬门禁 + 1 个只读审计钩子端到端可用（观察到回执门禁在真实失败调用上拦截，并返回纠正回执）。这两次运行测得 7，是因为当时注册的就是 7 个；四个读数工具在 2026 年 10 月加入，把数量带到 11（见上表）。历史读数按实测保留，不做回溯修改。 主线迭代很快 —— 集成前请对照当前官方文档重新核对（挂载细节见 DESIGN.md）。

方案 1：npx 快速开始（推荐首次尝试）

npx @deepseek-ai/dsh web # launches Web UI at http://127.0.0.1:3080 by default

打开浏览器，在 Settings → Models 下填入 API Key，即可开始对话。

方案 2：挂载 KISS's Law 插件

把仓库克隆到本地，再通过 kiss-law.patch.yml 覆盖层，把插件入口接入 dsh 的插件配置：

1. Get the plugin
git clone https://github.com/Shaky77/KISS_Law-DSH.git
cd KISS_Law-DSH

2. Introduce the plugin entry (src/index.js) into dsh's cordis config
Option A (recommended): overlay onto a profile via --patch
dsh --profile headless --patch ./kiss-law.patch.yml "your task prompt"
Option B: add the plugin path to the plugins list in dsh's launch config (cordis.yml) for persistence

3. Configure credentials (any one)
- Fill in via the Web UI Settings; or
export DEEPSEEK_API_KEY=sk-xxxx # Linux/macOS
$env:DEEPSEEK_API_KEY="sk-xxxx" # Windows PowerShell

挂载完成后，该配置档下运行的任何智能体都会自动获得 11 个白盒自检工具（query_iron_laws / query_steady_state / list_rigid_anchors / query_conduction_chain / query_boundary / query_bugstop / query_anchor_channel / query_criterion_wiring / query_strata / query_nested / query_tension），并且每次工具调用都要经过 tools/pre-execute 硬守卫门禁（R/D/S/H/M 总裁决）和 agent/pre-step 内层 H 不可侵犯门禁。

日常使用与压力测试

- Web / 标准模式：日常对话与工程任务；插件在后台静默约束。
- Headless 模式：dsh --profile headless 无界面运行，适合批处理任务 —— 可用于回归测试和多智能体压力测试。本仓库的 versions/live/evidence/ 目录归档了这类运行记录（12 个场景 × DeepSeek + mock，含对话记录与裁决报告）。

卸载

- dsh 插件安装方式：dsh plugin --profile web remove "dsh-kiss-law"，重启生效。
- 覆盖层挂载方式：从 dsh 启动配置中移除 kiss-law.patch.yml 引用（cordis.yml 的 plugins 列表或 --patch），重启生效。
- 插件不写入任何持久状态；移除后，智能体不再拥有白盒工具、3 道硬闸门和审计钩子，也不会留下任何残留。

说明

- 插件入口是纯 ESM（src/index.js），依赖 @deepseek-ai/dsh-tools（peerDependency，可选）；集成前请对照当前 dsh 文档核验 API。
- 远程部署 dsh 时，要在配置里声明 trustedHosts，否则 API 层会拒绝非 loopback 请求。
- 用 pnpm 从源码构建 dsh 时，你必须先运行 pnpm run build（内部包链接 + 前端产物），否则会出现 module-not-found 错误。

配置

- 运行形态：纯 ESM 插件，无构建步骤；通过 kiss-law.patch.yml 覆盖层或 dsh plugin add 集成；没有独立服务进程。
- 环境变量：只有 DEEPSEEK_API_KEY（模型调用需要，由 DSH 的模型适配器透传——本插件从不读取密钥内容）；其余配置都归 DSH 自己管（profile / cordis.yml）。本插件不定义专属环境变量。
- 敏感项：插件不写入持久状态，也不持久化用户数据；凭据留在宿主的安全路径（如 ~/.workbuddy/deepseek_api_key.txt），由宿主和 DSH 管理，绝不提交到本仓库。

权限与数据

- 文件访问：只读自己的源码和 kiss-law.patch.yml；从不读写用户项目文件、会话日志或其他插件目录。
- 网络访问：没有独立的外发请求；模型调用的联网由 DSH 的模型适配器处理。
- 凭据与用户数据：不收集、不上传任何用户数据或 API 密钥；内层 H 边界声明「本插件从不读写主观黑盒」——query_boundary 只返回边界描述，不含用户内容。
- 不可变声明：三条铁律（law.mjs）和刚性锚点是只读常量，运行时无法被提示词或外部输入改写（白盒不可篡改）。

故障排查

- 插件未加载 / 工具缺失：确认 DSH v0.1.x，并确认 kiss-law.patch.yml 已正确覆盖到目标 profile；执行 dsh --profile web 后，在 Settings → Plugins 里查看 kiss-law 是否显示「enabled」。
- 挂载报错 module not found：从源码构建 dsh 时，先运行 pnpm run build（内部包链接 + 前端产物），否则会出现 module-not-found。
- API 层拒绝非 loopback 请求：远程部署 dsh 时，在配置里声明 trustedHosts。
- 回滚：删掉 --patch 引用，或执行 dsh plugin remove "dsh-kiss-law" 后重启——插件不留任何残留状态。

开发

- 依赖：Node.js ^22.19 || >=24；运行时依赖只有 @deepseek-ai/dsh-tools（peerDependency，可选）。
- 测试：npm test（即 node --test "test/*.test.mjs"）——数量以实际输出为准，这里不写死。
- 构建：无需构建（纯 ESM + yml 覆盖层）；改完 src/core/engine.mjs 后，重跑 npm test 做回归。
- 贡献：框架原生层（思维导图层）在基础版中已冻结；本实时系统版承载工程迭代。改动请向本仓库提 PR，并附上 node --test 输出。

许可与安全

本项目采用双许可：

- 开源使用：AGPL-3.0（全文见 LICENSE）
- 商业集成 / 闭源分发 / OEM：可获取独立于 AGPL-3.0 的许可 —— 联系 563003@qq.com

外部贡献需签署 CLA（以支撑上述双许可）；详见 CONTRIBUTING.md。

私下报告安全问题：请不要在公开 issue 中披露安全问题；直接发邮件到 563003@qq.com，作者会优先处理。

中英文版内容一致，可互相参照。中文版：Shaky77/weiwen-law-dsh —— 同样的 DSH / 思维导图形态，中文呈现；中文定义「守真·稳态」（Keep Integrity & Steady State）对应本版的 KISS。

联系方式

框架咨询 / 合作 / 审计对接：563003@qq.com