dsh-plugin-machr

作者：五唑锂 · MIT · 纯词频证据机（v0.9.2）

mAChR 慢通道插件：把输入文本的每个字、每个词、每个句（字/词/句三级，乱序、可重复）按相关性扔进调用者给定的分类，每类内做关联矩阵，按"第二信使浓度" α 合成最终矩阵，返回可观测的证据分布——路由表、α 权重、类内联想对、被丢弃的字/词、查询词的迭代松弛轨迹（含模糊度 H）。

设计不变式（v0.9.0 重申）：本插件完全不考虑语义——它没有任何语义理解、不做命名实体、情感或意图判断，也不调用任何模型。它是纯粹"先分类、后按词频做软路由"的证据机器：分类由调用者（快通道）提供钥匙词，机器只做频率统计、矩阵混合与机械极性标注。任何抽象结论都属于快通道（模型自身）。

分工与顺序契约：快通道（nAChR）= 模型自身的直接分析，供给抽象结论；慢通道（mAChR）= 本工具，供给证据权重。nachr_premise 为必填参数——模型必须先写出快通道论点才能调用本工具（L1 参数契约强制"先 nAChR 后 mAChR"），该论点被回显为报告的"调制基线"。调制 = 论点 × 证据。

工具

machr

参数	必填	说明
input	是	待分析文本（≤ 100 万字符）
nachr_premise	是	快通道先行论点（L1 契约：没有抽象就没有证据请求）
mode	否	evidence（默认）/ scan（词频与共现候选簇 + 立类建议）/ refine（邻域精化，需 focus）/ compare（对比两份文本，需 input_b）
input_b	compare 必填	对比模式的第二份文本（与 input 跑同一管线，输出差分账本）
focus	refine 必填	邻域聚焦词：含任一聚焦词的句块构成子语料
damp	否	热动力学阻尼强度，默认 1，0–100（越大滤噪越狠）
categories	条件必填	evidence/refine/compare 模式必填：分类名 → 钥匙词数组（≤ 32 类）；词表由所有钥匙词并集生成
extra_vocab	否	补充词表（无类认领的词，演示信息丢弃）
queries	否	读出查询词：单步读出 + 迭代松弛轨迹；支持多词词袋（空格/、//分隔）
neg_window	否	否定账本回溯窗口（字），默认 6，0–20，0 关闭
bootstrap_b	否	α Bootstrap 重采样次数，默认 100，0–1000，0 关闭（种子确定性）
route_t	否	路由温度，默认 0.6，0.1–10（越热越模糊）
relax_t	否	松弛温度，默认 0.3，0.01–10（越冷吸引子越锐）
relax_steps	否	每次查询最大松弛步数，默认 6（1–50 整数）
use_ngrams	否	CJK 二字词组块，默认 true
report_max_chars	否	报告文本长度上限，默认 16000（0 = 不限制）；截断只作用于文本报告，结构化 data 负载永不被截断

管线（字/词/句三级 + n-gram 词组）

输入 -> 字块（每个汉字/ASCII 词元一捆，捆重=出现次数）
     -> 词块（每个词表词一捆 + CJK 二字词组一捆：出现≥2 次且含词表词的 bigram）
     -> 句块（标点切分，长度≥4）
     -> 相关门软路由（亲和度 > 0 才投，可一物多投）
     -> 每类吸收质量 m_k -> 单位向量 m̂_k（关联矩阵 = m̂_k m̂_kᵀ，惰性求值）
     -> alpha 加权合成最终矩阵 G -> 对比化（扣掉高频假关联）
     -> 单步读出（机器快档）/ 迭代松弛（机器慢档，中间态即可观测模糊）
     -> α 温度敏感性（相对 route_t 的 ×0.5 / ×1 / ×1.5 三重路由，报告每类 α 极差）

结构化输出：工具返回值除文本 report 外还携带 JSON data（词表、α、α 敏感性、字级认领、类内联想、读出轨迹等），供 subagent/workflow 程序化消费，也是客户端 UI 面板的数据源。

客户端 UI 可视化行（v0.9.0）

插件注册了 tool.call.toolview 的 machr 键：每次 machr 调用在对话流中渲染为一张可视化证据卡片（默认展开）：

• α 条形图：每类一条，浅色区间为 bootstrap mean±std；下方标注温度敏感性与极差。
• 类内联想对：top4 带同现溯源（"同现: …" 或"跨句混合"）。
• 查询读出：单步 top3 + 迭代松弛轨迹（每步 top 词与模糊度 H，收敛步骤高亮）。
• 否定账本：命中词、标记与上下文摘录、分类小计。
• 反常值：观测/基线/正残差；论点-证据对照：覆盖率与逐词映射。
• compare：Δα 双条对比、反常对差分、否定差分、仅一侧吸收词、查询读出对比。
• scan：词频、候选簇、可粘贴的 categories JSON 与查询建议。
• 原文报告始终保留在可折叠的"原文报告"块中；refine 卡片带邻域头注。

数据链路：宿主工具通过 presentationMeta 把结构化 data 写入 tool/result 的 meta（会话日志不持久化工具 value，但持久化 meta），面板从 meta 读取；旧版本记录没有 meta 时回退为纯文本报告。面板只呈现机器给出的词频证据，不添加任何语义解释。

证据强化五件套（v0.8.0）

1. 否定账本（neg_window，默认 6，0 关闭）：词表词每次出现前窗口内检查否定标记，命中者进入【10. 否定命中】——附标记、次数、上下文摘录与分类小计。回溯限定在同一个小句内；否定语境中的词仍计入正向质量，机器只并列呈现极性证据，语义裁决留给快通道。
2. 证据溯源：【5. 类内联想对】每对 top 联想附"同现句块"；两词从未同现的联想如实标注"跨句混合"——联想从黑箱变成可核查引文。
3. 多词查询（词袋）：queries 项用空格/、//分隔，各词等权合成查询向量；未命中词表的子词单独报告。
4. α Bootstrap 稳定性（bootstrap_b）：【6c】块级有放回重采样，报告每类 α 的均值±标准差；种子确定性（同输入同结果，报告可复现）。
5. mode: "compare" 对比模式：对两份文本跑同一管线，输出差分账本——Δα、各类 top 联想对、反常最强词、查询读出；v0.9.0 起还包括否定账本差分、吸收/丢弃差分、反常联想对差分与论点覆盖率差分。机器只给差分证据，哪边"更好"由快通道判断。
6. 强制优先调用契约（默认启用）：安装即启用——系统提示词区段写入强制调用规则：凡请求包含可分析文本（需求/文档/观点/约束/对比/审稿…），必须先至少调用一次 machr 再给最终答案（陌生文本 scan → 立类 → evidence；两份文本 compare；局部放大 refine），并把结果（α/联想/轨迹/否定账本）引用进回答；仅纯执行性请求可跳过。环境变量 DSH_MACHR_MANDATE=0（或 off/false）可关闭。边界说明：提示词约束能大幅提高调用率，但工具调用与否是模型自身的随机决策——需要 100% 硬性保证只能由宿主层实现工具调用策略，插件本身做不到。

v0.9.3 证据层与数值保障

1. 距离感知同现溯源：【5. 类内联想对】的每条同现溯源现在附词距——两词在同现句块内的最近出现距离（字符数，机械测量），如 严禁—肤浅:0.27（同现: "严禁肤浅"(距2)）；跨句混合对如实标注不变。数据源 catPairs[].sources[].dist，客户端面板同步展示。
2. 相邻句共现滑窗（±1 句）：新增【5b】——词 i 在第 t 句、词 j 在第 t+1 句的机械对称计数，是介于"同句同现"与"跨句混合"之间的中间关联层。数据源 adjacentPairs，客户端面板同步展示。纯频率计数，无任何语义判断。
3. 数值噪声地板（真 bug 修复）：单类（或近秩一）输入的对比如矩阵在数学上全零——此前的读出完全由浮点消去噪声（~1e-13）驱动，稀疏与稠密实现会给出不同的"吸引子"。现在残差低于 2e-12 × max(g,b) 一律视为零，退化输入的读出确定性"被丢弃"（如单词表查询 x 在 V=1 时明确报告无输出，而非噪声假吸引子）。有真实结构的多类输入不受影响（真实残差在 0.01 量级）。
4. 数值一致性模糊测试（node test/fuzz.mjs）：test/dense-ref.mjs 是 0.8.0 稠密算法的独立参考实现（不复用引擎任何函数），随机输入批量对照稀疏引擎的 α/温度敏感性/反常对/类内联想/读出轨迹/阻尼敏感性——报告级数值一致（top-k 允许显示精度平局换位）。已跑 1100 用例（三个种子）全绿。
5. 压力基准入包（node test/bench.mjs）：S1 大词表、S3 bootstrap、S4 读出、S5 compare、S8 scan、S9 满配六场景，附 α 和断言与耗时输出。

v0.9.2 宿主配置与元数据

1. Config 参数化（schemastery schema，声明为 dependency，与第一方插件同款）：工具默认值 routeT/relaxT/damp/negWindow/bootstrapB/reportMaxChars 与强制契约开关 mandate 都可在 cordis.patch.yml 中配置：

   - insert:
       - id: machr
         name: dsh-plugin-machr
         config:
           routeT: 0.8
           reportMaxChars: 8000
           mandate: false   # 关闭强制优先调用契约
   

   调用参数显式传入时优先于配置；插件管理器里该行会出现配置入口。旧的 DSH_MACHR_MANDATE=0 环境变量仅在 config.mandate 未配置时生效（向后兼容）。schemastery 不可解析的裸 checkout 环境降级为手动校验（安装环境总有该依赖）。

2. 可复现元数据：data.meta = { version, elapsedMs, seed, defaults }；证据报告头部与对比报告头部加入确定性种子（hex）——同输入同结果、可审计。工具参数 schema 与 Config 边界保持一致。

3. 路由与否定账本加固：路由矩阵改为行主序 Float64Array 一次分配；bootstrap 预算按真实每轮成本校准（总预算 4e8）——46 万句病态输入 39.7s → 19.0s 且 B=26/100 如实封顶，S9 满配（1M 字符、100 查询、B=100）仍保持满轮 1.9s；否定账本快速拒绝改用 charCodeAt 数值集合。

4. 作者/来源：五唑锂。

v0.9.1 性能与加固（压力测试驱动）

0.9.1 全部改动来自压力基准（32 类 × 992 词、1M 字符输入、100 查询 × 50 松弛步、B=100 等极限配置），数值输出与 0.9.0 完全一致（全部回归用例原值通过）：

1. 稀疏路由与稀疏质量累积：路由亲和度只扫每块的非零维（数值等价），复杂度从 O(N·K·V) 降到 O(非零维·K)；同类质量累积同理。基准：大词表证据 30.3s → 0.62s（49×）；bootstrap 极限 65.8s → 0.67s（98×）。
2. 全词表出现位置一次扫描：词块权重与否定账本共用"首字符位置表 + startsWith"批处理，替代逐词全文 indexOf（O(词表×文本) → O(词表首字符出现次数)）。1M 字符全配跑分 19.5s → 2.4s，堆内存峰值 ~42MB。
3. bootstrap 路由预算：超大语料 × 高 B 时按每轮稀疏路由成本封顶有效轮数（下限 1，预算 2e8），报告【6c】与 data.bootstrapBEff 如实标注 B=51/100（路由预算封顶）；种子确定性保持不变。
4. 大词表稀疏读出：词表 >128 时查询读出只扫非零行，松弛轨迹每步保留质量最大的 64 项继续迭代（吸引子不变，O(V²) → O(64·V)）；小词表仍走逐字节一致的精确路径。读出极限 2.5s → 0.56s。
5. scan 数值键共现：共现计数改用词对索引 Int32Array 计数表（不再为每对词构建字符串键）；300KB 扫描 7.5s → 93ms（80×）。
6. 句级投递惰性化：只构建已投递句块的前 12 条展示项，其余仅计数（clauseRouteCount），大语料不再为每个句块建对象。
7. 无分析单元输入：纯标点/空白输入现在抛清晰错误 input produced no analyzable units（此前产出空报告 α=0）。
8. 兼容性回归：32 类上限、大小写混排词袋、CRLF/全角标点、词表词互为子串、一侧零命中的 compare、混排 scan、data JSON 往返、空前提、2 万字符前提渲染、旧记录（无 meta）客户端回退——全部通过；设计不变式（纯词频、无语义）不变。

v0.9.0 变更

1. 矩阵内存安全：原实现为每类物化 V×V 关联矩阵（词表 1000 × 32 类 ≈ 数百 MB JS 数组）；现在只保留每类单位质量向量 m̂_k（O(K·V)），最终矩阵 G 用单个 Float64Array（O(V²)），对比矩阵按需逐元素计算——最坏内存从 ~O(K·V²) 降到 ~O(V²)，数值完全一致（全部回归用例原值通过）。
2. compare 差分补全：【3b. 反常联想对差分】【3c. 否定账本差分】【3d. 词吸收与丢弃差分】【5. 论点词表覆盖率差分】，结构化数据同步扩展。
3. scan 立类建议：扫描报告新增【5. 立类建议】——簇→类机械映射（1 簇 = 1 类，簇词 = 钥匙词），输出可直接粘贴进 categories 的 JSON，并附共现词对查询建议。纯机械产物，不做语义命名。
4. α 温度敏感性相对 route_t：敏感性档位从固定 T=0.4/0.6/0.9 改为相对当前 route_t 的 ×0.5/×1/×1.5，报告头部与【6b】显示实际温度。
5. 报告长度控制：新增 report_max_chars（默认 16000，0 不限），超限截断并附注；data 负载永不截断。
6. 工具定义与提示词优化（agent-experience）：参数 schema 自带类型/默认值/上下限（integer/default/minimum/maximum/maxLength/maxItems 等）；工具描述与系统提示词区段压缩去重（每条事实只讲一次，参数规则放在参数上）。L1 契约与强制调用契约保持不变。
7. 客户端 UI 可视化行：见上文；presentationMeta 打通 meta 数据链路。

加固与修复（v0.7.0）

1. 空词项死循环（严重）：extra_vocab/queries/focus 里的空串或空白串此前能通过参数校验进入引擎，indexOf('') 使调用挂死。现在工具层统一拒绝非空校验，引擎 analyze/refine 直接调用时同样抛错，双保险。
2. 参数加固与上限：relax_steps 限定 1–50 的整数；input ≤ 100 万字符、nachr_premise ≤ 2 万字符、分类 ≤ 32 个、总词表 ≤ 1000 词、queries ≤ 100、extra_vocab ≤ 500、focus ≤ 100——防止超长输入/超大词表把报告和矩阵撑爆。
3. 引擎防御：非字符串 input、空 categories、空词项一律抛出明确错误；entropy 在单词表（V=1）时不再产生 NaN；charUnitCounts 只计算一次。
4. 句块切分补全 ASCII 标点：英文/中英混排文本的句级投递不再被长段污染。
5. 报告防洪：调制基线回显截断 240 字、未投递词封顶 20 个、句级投递封顶 12 条（其余标注"略"）；v0.9.0 起由 report_max_chars 统一兜底。
6. 论点-证据对照大小写不敏感：词表 nAChR 现在能正确对照前提里的 nachr。
7. 宿主契约：apply() 按 Cordis 约定返回卸载清理函数；证据区段 Map 封顶 256 条防长会话内存膨胀；output.render 空值安全。
8. 测试随包分发：files 加入 test，README 里的测试命令在 tgz 中真实可用。

跃迁三件套（v0.6.0）

1. 反常值报告（似然函数跃迁器）：观测关联 − 频率基线的正残差 top10 与"反常最强词"。
2. 阻尼参数与敏感性（热动力学阻尼）：damp 参数（默认 1）；【7b. 阻尼敏感性】——阻尼 0.5/1/2 三档下各查询 top3。
3. 邻域精化（四元数调谐器）：mode: "refine" + focus 词数组——把含聚焦词的句块作为子语料重跑整条管线，α 与联想在邻域内重新归一化。

开发与测试

node --check lib/index.js && node --check lib/engine.js
node test/run.mjs          # 沙箱友好（不 spawn 子进程）
node test/apply.test.mjs   # 假 ctx 集成测试（含 L1 契约）
node test/fuzz.mjs 300 20261018  # 数值一致性模糊测试（沙箱友好，可指定用例数/种子）
node test/bench.mjs        # 压力基准六场景
node --test test/          # 完整 node:test 版本（非受限环境；或 npm test）

安装

把本目录同步到 profile 的 node_modules/dsh-plugin-machr/，并在该 profile 的 package.json 中加入依赖与 bundle 声明（本地开发用 link: 相对路径；分发用 dsh plugin --profile <名字> add ./dsh-plugin-machr-0.9.3.tgz 或发布 npm 后按名安装）。 宿主端随服务器加载；客户端可视化行随 Web 页刷新生效。升级宿主引擎后需重启应用（客户端声明负缓存与新模块代都以重启为准）。

许可

MIT © 五唑锂