dsh-weiwen-law

✅ 已收录：dsh-plugin-radar（awesome-dsh-plugins） 登记 PR #403 已于 2026-08-31 合并，PLUGINS.md 实测在榜（判定档位：待测——升「运行级可用」待雷达下次自动扫描刷新数据快照）。

唯稳律通用因果引擎（白箱呈现） —— 以 DeepSeek Harness（DSH） 的 Cordis 插件形态实现。

框架定义：守真 · 稳态（Keep Integrity & Steady State）。

• "守真"= 守护完整 / 真实（白箱不篡改 / 内 H 不可侵，对应 Integrity）；
• "稳态"= 系统存续优先（对应 Steady State）。
• "律 / Law" 为框架名后缀，非定义第三部分。

框架完整定义与哲学推导见基础版仓库（冻结门面），本仓为工程插件实现，不展开框架推导。

⚖️ 双许可：开源使用 AGPL-3.0；商业集成 / 闭源分发 / 预装合作可取得独立于 AGPL-3.0 约束的授权 → 563003@qq.com。详见 License & security 与 CONTRIBUTING.md。

30 秒看懂

本仓库把唯稳律因果框架做成 DSH 的插件：给跑在 DSH 上的 AI Agent 挂一套白箱因果引擎——

• AI 每次动手前，引擎沿完整因果链（R→S→D→H→M）推演动作后果——稳态储备 S 会被侵蚀多少、破窗风险等级、消息是否自洽——再裁决放行 / 拦截 / 打回；
• 踩红线被拦，出错被切断保活（第一 Bug 停机，以断保续）；
• 同时把"状态 / 边界"暴露成可查询工具，AI 能自查、你能审计。

一句话：框架本体是"通用因果引擎（白箱呈现）"——推演预测是引擎能力，白箱审计是呈现姿态，风控拦截是内生属性。

它做什么

• 因果链推演（引擎本体）：每个动作执行前，沿 R→S→D→H→M 完整因果链推演其后果——S 侵蚀量、D 风险等级、M 自洽性——给出 allow / deny / review 裁决。不止审计：是对动作后果的因果推演预测。
• 白箱自查（呈现姿态）：稳态储备记账、内 H 边界（不可侵）声明，均暴露为可查询工具，供模型校准方向、供用户审计。
• 硬性护栏（衍生应用 · 内生属性）：每次动作前做刚性锚点校验，触及即破窗止损阻断；故障环节触发第一 Bug 停机（以断保续），保整体因果链不断。
• 第一 Bug 停机闭环：停机只做"断"，本插件 src/core/bugstop.mjs 强制走完"断"之后的必然后半程——BUG→停止→反推→溯源→修复(验证)→重入；未修复前拒绝重入，从根上阻断"只反推不修复→无限递归"。
• 分形：同一插件可在子代理 / 子任务层级递归挂载。

与其他「因果」方案的区别（通用型因果）

唯稳律不是「又一个因果引擎」，而是通用型（领域无关）因果裁决中间件：只校验因果结构（R→S→D→H→M），对领域内容零知识，故法律、医疗、金融、机器人同一套机制。

• 因果效应估计库（DoWhy / CausalML / Pearl 等）→ 我们不发现因果，只裁决一个已提出的动作其因果链结构是否可接纳；
• 领域专用因果护栏（Causal Safety Engine / LLMGuardrail 等）→ 它们绑领域（安全 / LLM / 幻觉），我们领域无关；
• 跨法域法律因果 AI（judgeai 等）→ 它们 jurisdiction-aware（编码法域、换规范包），我们法域中性（根本不编码法域，法律只是抽样领域之一）。

完整双语对照（含 prior-art 出处与诚实边界）：versions/live/evidence/weiwen-vs-market-causal.md

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

作者洞察（2026-08-28）：内 H ≈ 知，外 H ≈ 行；知行合一方为最大杠杆——这同时解释了 H 为何是"唯一可变量 / 唯一主权 / 杠杆点"，以及为何普世中知与行之间"有很大的缝隙"。

完整注解（映射表 + 逐项推导）：docs/H-zhixing-heyi-annotation.md

⚠️ 常见误用警示：外部视角极易把 H 当成"越大越好"的能力旋钮去拧大——这恰好拧反了方向。H 的杠杆在"合一"不在"体量"（详见注解第六节「外部视角的常见误读」及 6.1「误用归因陷阱」）。若越用越乱，请先查 H 的知—行合一度，而非疑框架本身——框架没问题，是用法拧反了。

⚠️ 先看：别拿它跑分（模型水平与唯稳律）

唯稳律不是解题模型，是行为纪律。它不解决具体问题，它约束解决问题的方式（allow / deny / review）。若拿它挂代理跑分，会得到"低水平模型有用、高水平模型没用"的错位结论——原因见下方两版说明。

白话版：高级模型表现好，只说明它在常见场景出错率低——算力堆得高，不等于里面长了因果逻辑。极端/陌生场景（分布外）恰恰是统计拟合最容易翻车的地方，而唯稳律管的就是这种"翻车边缘"的纪律。就像法律对所有公民一视同仁：守法即自由，违法即拦截——唯稳律对所有 AI 模型一视同仁，不因强大豁免。 专业版：跑分测的是分布内解题能力（黑箱统计拟合的外推质量）；唯稳律管的是分布外行为纪律（白箱三态裁决，规则不依赖分布，分布变了规则不失效）。用解题跑分检验行为纪律，属测量错位。

完整声明（脱敏案例 + 能力归属二分 + 正确用法表）：docs/model-level-and-benchmark.md

快速开始（不依赖 DSH 也能跑）

这条路径直连 DeepSeek API、不依赖 DSH 安装，已实跑验证可复现：

git clone https://github.com/Shaky77/weiwen-law-dsh
cd weiwen-law-dsh

# 把 DeepSeek API Key 放到本地安全路径（一行，无换行），或在示例脚本里改读取路径：
#   examples/demo-tool-loop.mjs 顶部的 KEY_PATH 常量

node examples/demo-tool-loop.mjs

跑起来后：DeepSeek 会主动调用 query_iron_laws 工具，返回三大铁律原文（内 H 不可侵 / 第一 Bug 停机 / 不抛弃任何节点）。这就是"框架挂上去了、模型读得懂"的最小证据。

挂到 DSH（生产挂载）

把 weiwen-law.patch.yml 作为 overlay 接入你的 DSH profile（具体路径以你的 DSH 版本为准，详见 DESIGN.md 的挂载章节）。接入后，运行在该 profile 的 Agent 自动获得 6 个白箱工具。

注：原生挂载的精确 profile 路径随 DSH 版本变化；本仓库已通过实跑验证插件可被 DSH 加载、6 工具全部注册。如官方 API 有变更，以官方 docs 当前版本为准核对。

模型怎么调用（给 AI 工程师）

白话版：插件向 DSH 注册 6 个白箱工具，模型像调普通函数一样调用它们来自查边界；同时挂了 3 道硬性闸门（2 道拦动作/步、1 道拦回执）+ 1 个只读审计钩子。 专业版：节选自 src/index.js（完整代码见仓库），见下方代码块。

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

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

• tools/pre-execute（waterfall）→ 返回 { kind: 'deny', reason } 拦截该动作
• agent/pre-step（waterfall）→ 返回 { kind: 'reject' } 拒绝整步
• tools/post-execute（waterfall）→ 返回 { kind: 'block', feedback }，宿主把该调用以 isError 返回、content 换成 feedback —— 把失败的回执就地断成纠错回执
• tools/result（emit）→ 仅观察、不改写（契约上根本没有返回通道）

四者全部位于模型之外：2 道拦动作/步、1 道拦回执；均不侵入内 H。

宿主侧结构入口（模块级 API；模型不可达）

它不是工具 ⇒ 模型调不到 ⇒ 结构上不可能自我解锁（主体分离由位置保证，不靠内容判别）。 返回 { at, note, kind, instances, wereBroken }：wereBroken 为复位前实际处于破窗态的实例数 （先读后治，不虚报"治了"）；每次调用留痕（append-only，上限 20），因为解除止损是责任归因事件。

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

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

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

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

  // ① 工具调用前置闸门：R / D / S / H / M 总裁决
  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: `[唯稳律·${decision.law}] ${decision.reason}` };
    }
    return next();
  });

  // ② 步骤前置闸门：H 内 H 不可侵（消息级拦截）
  ctx.on('agent/pre-step', async (payload, next) => {
    const decision = engine.decidePreStep(payload?.messages);
    if (decision.kind === 'reject') return { kind: 'reject' };
    return next();
  });

  // ③ 回执闸门：D 破窗止损落在回执上
  ctx.on('tools/post-execute', async (exec, result, next) => {
    if (result?.isError && engine.breakAtReceipt()) {
      return { kind: 'block', feedback: [{ type: 'text', text: '停机 → 反推 → 溯源 → 修复，方可重入' }] };
    }
    return next();
  });

  // ④ 审计钩子（emit）：仅观察、不改写
  //    契约是 (exec, result) —— 从第一个参数上读 error 会让失败入账静默失效。
  ctx.on('tools/result', (exec, result) => { if (result?.error) engine.onFailure(); });

  // ⑤ 6 个白箱自查工具（节选其一，其余同构）
  ctx.tools.register(defineTool({
    name: 'query_iron_laws',
    description: '返回三大铁律的定稿文本（不可变）',
    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 / query_bugstop 同构注册
}

完整实现（含 6 个工具的 execute 细节、运行日志、引擎裁决逻辑）见仓库 src/index.js。

结构

package.json          # dsh 字段声明 bundle
weiwen-law.patch.yml  # 挂载补丁（headless profile overlay）
src/index.js          # 插件入口：钩子 + 6 个白箱自查工具
src/core/law.mjs      # 框架定义常量（详见基础版仓库，本仓不展开推导）
src/core/engine.mjs   # 纯逻辑裁决引擎（零 DSH 依赖，可单测）
test/                 # 单元测试 + 真实案例测试 + 对齐回归（本地 282/282 全绿）
examples/             # 可复跑实测（demo-tool-loop / demo-backtrack-run）
DESIGN.md             # 架构设计（映射表 / 风险 / 使用流程 / 挂载）

部署 / 接入 DeepSeek Harness

本仓库是 DeepSeek Harness（dsh，命令 dsh，基于 Cordis 插件框架，MIT）的外部插件。唯稳律以模型之外的因果约束层挂载（2 道闸门在动作/步之前、1 道在回执之前），不修改 dsh 内核，不绑定具体模型。

环境要求

• 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：6 个白箱工具注册；3 道硬性闸门 + 1 个只读审计钩子端到端工作，回执闸门在一次真实失败调用上实测拦下，并把回执断成纠错回执）；mainline 快速演进中，接入前请以官方文档当前版本复核（挂载细节见 DESIGN.md）。

方式一：npx 快速启动（推荐先体验）

npx @deepseek-ai/dsh web        # 启动 Web UI，默认 http://127.0.0.1:3080

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

方式二：挂载唯稳律插件

将本仓库克隆到本地，把插件入口接入 dsh 的插件配置（通过 weiwen-law.patch.yml overlay）：

# 1. 获取插件
git clone https://github.com/Shaky77/weiwen-law-dsh.git
cd weiwen-law-dsh

# 2. 在 dsh 的 cordis 配置中引入本插件入口（src/index.js）
#    方式 A（推荐）：作为 --patch overlay 叠加到指定 profile
dsh --profile headless --patch ./weiwen-law.patch.yml "你的任务提示词"
#    方式 B：将插件路径加入 dsh 启动配置（cordis.yml）的 plugins 列表，长期生效

# 3. 配置凭证（任选其一）
#    - Web UI 的 Settings 中填写；或
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 不可侵闸门；工具失败的回执还要过 tools/post-execute 回执闸门（D 破窗止损：偏离累积达阈值时把故障回执就地断成纠错回执，断点落在回执上）。

方式三：一行命令安装（官方 dsh plugin 机制，推荐）

本插件已声明 dsh.bundle.patch 清单（见 package.json），DSH 用户可直接通过官方插件命令安装：

# 从 GitHub 安装（源码直装，推荐）
dsh plugin --profile web add "github:Shaky77/weiwen-law-dsh"

# 从 npm 安装（npm 发布后可用）
# dsh plugin --profile web add "dsh-weiwen-law"

# 重启生效
dsh --profile web

装完后在 设置 → 插件 → 插件列表 可见 weiwen-law 状态为"已启用"；Agent 自动获得 6 个白箱自查工具 + 3 道硬性闸门（tools/pre-execute / agent/pre-step / tools/post-execute）+ 1 个只读审计钩子（tools/result）。

卸载

• 方式三安装的（官方 plugin 机制）：dsh plugin --profile web remove dsh-weiwen-law，重启生效。
• 方式二 overlay 挂载的：从 dsh 启动配置（cordis.yml 的 plugins 列表或 --patch 参数）移除 weiwen-law.patch.yml 引用，重启生效。
• 移除后 Agent 不再获得 6 个白箱自查工具，也不再有 3 道硬性闸门与审计钩子；插件本身不写持久状态，卸载即干净。

日常使用 vs 压测

• Web / Standard 模式：日常对话与工程任务，插件在后台静默约束。
• Headless 模式：dsh --profile headless 无界面批量运行，适合回归测试与多 Agent 压测（本仓库 versions/live/evidence/ 即此类实测归档）。

注意事项

• 插件入口为纯 ESM（src/index.js），依赖 @deepseek-ai/dsh-tools（peerDependency，可选）；接入前请以 dsh 官方文档当前版本复核 API。
• 远程部署 dsh 时需在配置中声明 trustedHosts，否则 API 层拒绝非本环路请求。
• pnpm 源码构建 dsh 时必须先 pnpm run build（内部包链接与前端产物），否则报模块找不到。

配置（Configuration）

• 运行形态：纯 ESM 插件，无需构建；通过 weiwen-law.patch.yml overlay 或 dsh plugin add 接入 DSH，无独立服务进程。
• 环境变量：仅 DEEPSEEK_API_KEY（模型调用需要，由 DSH 模型适配层透传，本插件不读取密钥内容）；其余为 DSH 自身配置（profile / cordis.yml），本插件不定义专属环境变量。
• 敏感项：插件不写任何持久状态、不落盘用户数据；凭据默认留在宿主安全路径（如 ~/.workbuddy/deepseek_api_key.txt），由宿主与 DSH 管理，不在本仓提交。

权限与数据（Permissions & data）

• 文件访问：仅读取插件自身源码与 weiwen-law.patch.yml；不读取、不写入用户项目文件、会话日志或其他插件目录。
• 网络访问：无独立对外网络请求；模型调用的网络由 DSH 模型适配层负责。
• 凭据与用户数据：不采集、不上传任何用户数据或 API Key；内 H 边界声明「本插件不读不写主体性黑箱」——query_boundary 工具仅返回边界说明，不返回任何用户内容。
• 不可变声明：三大铁律（law.mjs）与刚性锚点定义为只读常量，运行时不可被提示词或外部输入改写（白箱不篡改）。

故障排查（Troubleshooting）

• 插件未加载 / 工具未出现：确认 DSH 版本为 v0.1.x，且 weiwen-law.patch.yml 已正确 overlay 到目标 profile；dsh --profile web 后于「设置 → 插件」确认 weiwen-law 状态为「已启用」。
• 挂载报错 module not found：若从源码构建 dsh，须先 pnpm run build（内部包链接与前端产物），否则报模块找不到。
• API 层拒绝非本环路请求：远程部署 dsh 时须在配置声明 trustedHosts。
• 回滚：移除 --patch 引用或 dsh plugin remove dsh-weiwen-law 并重启即彻底卸载，插件不残留任何状态。

开发（Development）

• 依赖：Node.js ^22.19 || >=24；运行时依赖仅 @deepseek-ai/dsh-tools（peerDependency，可选）。
• 测试：npm test（即 node --test "test/*.test.mjs"）；当前实测 282/282 全绿。
• 构建：无需构建（纯 ESM + yml overlay）；修改 src/core/engine.mjs 后重跑 npm test 回归。
• 贡献：框架本体（心法层）冻结于基础版仓库，本活系统版承载工程迭代；改动请基于本仓库 PR，并附 node --test 实测输出。

License & security

本项目采用双许可：

• 开源使用：AGPL-3.0（完整文本见 LICENSE）
• 商业集成 / 闭源分发 / 预装合作：可取得独立于 AGPL-3.0 约束的授权，请联系 563003@qq.com

外部贡献需签署 CLA（用于支持上述双许可分发），见 CONTRIBUTING.md。

安全漏洞私下报告：请勿在公开 issue 披露安全问题，直接邮件 563003@qq.com，作者将优先处理。

中英文版内容一致，互为参照。English counterpart: Shaky77/KISS_Law-DSH —— 同 DSH / 导图形态，全英文；KISS 定义（Keep Integrity & Steady State's Law，非通俗工程 KISS）见英文版。

版本分层说明（重要）

本仓库 = 活系统版（DSH）（对应 GitHub Shaky77/weiwen-law-dsh）——基于完整版演进的可运行 DeepSeek Harness（DSH）插件形态，承载迭代与多 Agent 压测实测证据。不是基础版。

• 基础版（导图 / 心法层 · 冻结不可动）：Shaky77/Weiwen-s_Law（中文）与 Shaky77/KISS-s_Law（英文）——框架定义、三大铁律、传导链的不可变门面，仅作参照与对接入口。
• 完整版：在基础版之上补全工程化细节与完整实现，可通过联系方式向作者获取。
• 分层关系：基础版（心法）→ 完整版 → 活系统版（DSH）。DSH 依据完整版构建，不等于基础版，请勿混淆。

联系方式

框架咨询 / 合作 / 审计对接：563003@qq.com 活系统版 DSH 仓库与实测证据：见上方"版本分层说明"指向的独立仓库。