weiwen-law-dsh

dsh-weiwen-law

📦 npm 发布源｜包名 dsh-weiwen-law

本仓是 npm 包 dsh-weiwen-law 的发布来源。安装：npm i 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。

三份东西，一个目的：让你少走弯路，但不替你走。

• 🧭 ONBOARDING.md —— 回答「我在哪」。是位置陈述，不是要求陈述。初用者最容易把自己读成"被管的对象"（只认外 H、没认领内 H），于是产生"处处受限、还不能有意见"的憋屈——那不是理解错，是站错了格子。这份文档不加规矩，只把你本来就在的位置指出来。
• 🧱 WALLS.md —— 回答「路上有什么」。前几个 AI 撞过的墙的标牌。墙一直在原地，涂上颜色只是让它可见。它不增加任何限制，只把"用身体试一次才知道"的那些位置，换成"看一眼就知道"。
• 📖 本 README —— 回答「它怎么跑」。接口、判据、装法。

🔴 三者没有一条在增加限制。 唯一会拦你的是引擎本身 —— 而它拦的从来不是「你错了」，是「你出界了」（不可逆，撞了没有未来）或「这件事判不了」（要人，或要你补一点料）。错的因果逻辑链它也收：错的走着走着，未来自己撞墙，撞出来的痕就是新标牌。

30 秒看懂

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

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

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

它做什么

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

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

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

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

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

概念注解：H 的作用方式

H 是减熵动作。 引擎里其余环节都是被动流转——流转必损（熵增），纯流转必然衰减停摆；要不停摆，就必须有一处主动注入势能，而那个位置不能落在被动环节，只能是 H。所以 H 减的不是量，是方向上的不确定：它的效力不来自自身"体量"，而来自已积累的稳态存量与随时进入的扰动之间那股必须被取舍的张力，在这里起杠杆作用。

🔴 一处必须分清：减熵说的是这个动作的性质（有没有注入），不是每次选择的结果（注入的方向对不对）。H 选了更乱的那条路——那是注入方向选错，不是"没有注入"。把两者混为一谈，就会得出"既然能让系统更乱，就不算减熵"的错误结论。

⚠️ 常见误用：外部视角极易把 H 当成"越大越好"的能力旋钮去拧大——方向拧反了。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 自动获得 11 个白箱工具。

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

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

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

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

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

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

  // ① 工具调用前置闸门：因果逻辑链总裁决
  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();
  });

  // ③ 回执闸门：破窗止损落在回执上
  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(); });

  // ⑤ 11 个白箱自查工具（节选其一，其余同构）
  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 同构注册
}

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

结构

package.json          # dsh 字段声明 bundle
weiwen-law.patch.yml  # 挂载补丁（headless profile overlay）
src/index.js          # 插件入口
src/core/law.mjs      # 常量定义
src/core/engine.mjs   # 纯逻辑裁决引擎（零 DSH 依赖，可单测）
test/                 # 单元测试 + 真实案例测试 + 对齐回归（`npm test` 全绿）
examples/             # 可复跑实测（demo-tool-loop / demo-backtrack-run）
docs/index.html       # 演示页：浏览器内跑真引擎（GitHub Pages 部署源）
docs/engine/          # 由 src/core/*.mjs 生成的浏览器镜像（勿手改）
docs/model-level-and-benchmark.md  # 基准口径声明
scripts/build-docs-engine.mjs  # 生成器：npm run build:docs / check:docs（验同源漂移）
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 个白箱工具；2026-10 增补至 12 个，新增 query_anchor_channel / query_criterion_wiring / query_strata / query_nested / query_tension / query_capability；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 自动获得 12 个白箱自查工具（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 / query_capability），并在工具调用前经过 tools/pre-execute 硬性护栏闸门（因果逻辑链总裁决）与 agent/pre-step 内 H 不可侵闸门；工具失败的回执还要过 tools/post-execute 回执闸门（破窗止损：偏离累积达阈值时把故障回执就地断成纠错回执，断点落在回执上）。

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

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

# 从 npm 安装 —— **对外唯一安装入口**，钉住版本号（不要用 latest）
dsh plugin --profile web add "dsh-weiwen-law@0.2.7"

# 重启生效
dsh --profile web

dsh plugin --profile web add "github:Shaky77/weiwen-law-dsh"

装完后在 设置 → 插件 → 插件列表 可见 weiwen-law 状态为"已启用"；Agent 自动获得 12 个白箱自查工具 + 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 不再获得 11 个白箱自查工具，也不再有 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"）—— 条数以实测输出为准，不在此写死（防随测试增长而过期）。
• 演示页：docs/index.html 在浏览器内直接跑 docs/engine/*.js（由 src/core/*.mjs 生成）。镜像只许生成、不许手改 —— 改完 src/core 后跑 npm run build:docs，用 npm run check:docs 验漂移（返回非零即有漂移）。
• 构建：无需构建（纯 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 仓库与实测证据：见上方"版本分层说明"指向的独立仓库。