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。

30 秒理解

KISS 定律是一个描述因果律如何运行的通用框架。本仓库将其实现为 DSH 插件：它把白盒因果引擎挂载到运行于 DSH 上的 AI Agent 上——

- 在任何行动之前，引擎沿完整因果链（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 定律不是“又一个因果引擎”——它是一个通用（领域无关）的因果裁决中间件：它只验证因果结构（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 不可侵犯 / 首错即停 / 永不放弃任何节点）。这是“框架已挂载且模型已理解它”的最小证明。

挂载到 DSH（生产环境）

将 kiss-law.patch.yml 作为 overlay 添加到你的 DSH profile 中（确切路径取决于你的 DSH 版本；参见 DESIGN.md 中的挂载部分）。挂载后，在该 profile 下运行的任何 Agent 都会自动获得这 6 个白盒工具。

注意：确切的原生挂载 profile 路径会随 DSH 版本而变化。本仓库已通过真实运行验证：该插件可在 DSH 中加载，且全部 5 个工具均成功注册。如果官方 API 发生变化，请以当前官方文档为准进行验证。

模型如何调用它（面向 AI 工程师）

通俗版：该插件向 DSH 注册 6 个白盒工具；模型像调用普通函数一样调用它们来进行自检边界，同时由 3 个 hook 执行硬拦截。
专业版：摘自 src/index.js（完整代码见仓库），见下方代码块。

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

| 工具 | 模型用它做什么 |
|---|---|
| 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 | 查询首错即停循环状态：哪些故障环节处于已停止未修复状态、缺失步骤（回溯/追踪/修复）、白盒循环是否闭合 |

3 道硬门（hooks）

- tools/pre-execute → 返回 { kind: 'deny', reason } 以阻止该操作
- agent/pre-step → 返回 { kind: 'reject' } 以拒绝整个步骤
- tools/result → 仅观察，从不重写

完整插件入口（摘自 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();
});

// ③ 结果审计钩子：仅观察，绝不重写
ctx.on('tools/result', (res) => { if (res?.error) engine.onFailure(); });

// ④ 5 个白盒自检工具（仅摘录其一；其余同构）
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 以同构方式注册
}

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

结构

package.json          # dsh field declares bundle
kiss-law.patch.yml    # mount patch (headless profile overlay)
src/index.js          # plugin entry: hooks + 5 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 (local 123/123 passing, commit 905499f)
examples/             # runnable demos (demo-tool-loop / demo-backtrack-run)
DESIGN.md             # architecture design (mapping / risks / usage flow / mount)

部署 / 与 DeepSeek Harness 集成

本仓库是 DeepSeek Harness（dsh，命令 dsh，基于 Cordis 插件框架构建，MIT）的外部插件。KISS 定律作为因果约束层挂载，位于模型之外、执行之内——它不修改 dsh 内核，也不绑定任何特定模型。

环境要求

- Node.js ^22.19 || >=24（dsh 的硬性要求；不支持奇数版本）
- 一个 DeepSeek API Key（或任意 OpenAI 兼容端点的 Key）
- dsh 目前处于开发者预览阶段（v0.1.x）；官方声明称可能发生破坏性 API 变更——生产环境请固定具体版本
- 兼容性声明：已针对 DSH v0.1.x 验证（实测日期 2026-08-27：6 个白盒工具注册成功 + 3 道闸门正常工作）；主线迭代很快——集成前请对照当前官方文档重新核查（挂载细节见 DESIGN.md）。

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

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

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

方案二：挂载 KISS 定律插件

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

1. Get the plugin
git clone https://github.com/Shaky77/KISS_Law-DSH.git
cd KISS_Law-DSH
2. 将插件入口（src/index.js）引入 dsh 的 cordis 配置
方案 A（推荐）：通过 --patch 叠加到某个 profile 上
dsh --profile headless --patch ./kiss-law.patch.yml "your task prompt"
方案 B：将插件路径添加到 dsh 启动配置（cordis.yml）的 plugins 列表中，以实现持久化

3. 配置凭据（任选其一）
- 通过 Web UI 设置填写；或
export DEEPSEEK_API_KEY=sk-xxxx     # Linux/macOS
$env:DEEPSEEK_API_KEY="sk-xxxx" # Windows PowerShell

挂载后，在该 profile 下运行的任何 Agent 都会自动获得 6 个白盒自检工具（query_iron_laws / query_steady_state / list_rigid_anchors / query_conduction_chain / query_boundary / query_bugstop），并且每次工具调用都会经过 tools/pre-execute 硬门禁（R/D/S/H/M 总裁决）以及 agent/pre-step 内层 H 不可侵犯门禁。

日常使用与压力测试

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

卸载

- dsh plugin install：dsh plugin --profile web remove "dsh-kiss-law"，重启后生效。
- overlay 挂载：从 dsh 启动配置（cordis.yml 的 plugins 列表或 --patch）中移除 kiss-law.patch.yml 引用，重启后生效。
- 该插件不写入任何持久化状态；移除后 Agent 不再拥有白盒工具或 3 道硬门禁，且不会留下任何残留。

注意事项

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

配置

- 运行时形态：纯 ESM 插件，无构建步骤；通过 kiss-law.patch.yml overlay 或 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 显示为“已启用”。
- 挂载错误 module not found：从源码构建 dsh 时，需先运行 pnpm run build（内部包链接 + 前端产物），否则会出现 module-not-found。
- API 层拒绝非回环请求：远程部署 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"）；当前 123/123 通过（提交 905499f）。
- 构建：无需构建（纯 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