dsh-cybernetics — 控制论内核 v4 运行时（DeepSeek Harness 插件）

由存档 dsh-cybernetics插件源码存档.md（v4.1，2026-08-16 卸载前）与 dsh-cybernetics插件开发与自进化经验.md 重建。 对照《工程控制论》（钱学森/宋健·第三版）实现的机制级 Cordis 插件（ESM）。

一、文件清单

文件	说明
index.js	主插件（v4.2，808 行）
core.mjs	纯函数控制律内核（EMA/滞环/发散/振荡/hash/熵/健康评分），供单元测试与外部复用
test/cybernetics.test.mjs	单元测试（node:test，10 用例全绿）
cordis.patch.yml	插件自身 bundle patch（默认配置）
package.json	包声明（dependencies 为空——依赖软链到全局宿主）

二、机制（v4.2）

经典控制回路：

• 观测器：内存状态（按 session 分区）+ JSONL 持久化（~/.dsh/cybernetics/state_log.ndjson）
• 前馈控制：tools/pre-execute 规则表拦截（工具名白名单 + 参数正则）+ 本轮调用计数
• 反馈校正：tools/result → delta → EMA 滤波（pHat）→ 控制律（档位自适应 + 发散/振荡检测）
• 执行器：cybernetics_snap / cybernetics_status / cybernetics_check / cybernetics_sandbox_mode
• 能控性自检：目标 + 所需工具 vs 当前可用工具（插件工具 ∪ 观测记忆）

v4.2 完善项（2026-08-19，对照 v4.1 实测反馈）

项	内容
A1	修复冗余 hash 假误报：rc.6 下 exec.args 恒 undefined → 改用参数文本（execArgsText，arguments 优先）
A2	观测完整率钳制 ≤1（孤儿 result 不再把分子顶破）
A3	boot 日志回放恢复：pHat/档位跨重启续算（boot-recover 事件），消除系统失忆
B4	信息熵告警：工具单一化（<1.0 且窗口 ≥8 次）注入警告，熵 ≥1.5 恢复（滞环防抖）
B5	工具耗时观测：result 记 dtMs，status/snap 输出最慢 TOP3
B6	agent/disposed 会话汇总：session-summary 事件（pHat 起止/档位/冗余/慢工具），供周检 automation
B7	按 session 分区状态：并发会话 pHat/档位/计数互不污染，无 session 路径归 global 兜底
C8	冗余事件聚合：每 10 次记一条 redundant-burst，不再逐条刷日志
C9	status 内存态与日志回放态交叉校验，漂移 >0.1 标注
C10	版本常量 VERSION 统一（core.mjs）
C11	警告注入失败留痕（dropped-warn 事件）
C12	纯函数下沉 core.mjs + node:test 单元测试
C13	健康评分 healthScore（0-100：成功率×100 − 观测缺口×20 − 冗余率×10 − 发散/振荡各 10）
C14	失败归因观测（2026-08-19，方案 B）：result 事件失败时记 errorType（FsError code 优先，如 FS_EDIT_NOT_FOUND/FS_AMBIGUOUS_EDIT；无 code 按消息模式归类）+ errMsg（截断 120 字符）——供周检第④项做失败根因分布

核心参数（control，均可经 patch 配置）：

参数	默认	含义
alpha	0.2	EMA 滤波系数
escalateAt / deescalateAt	0.6 / 0.15	升档 / 降档失败率阈值
deescalateStreak	5	降档防抖连续次数（滞环）
divergenceStreak	3	连续失败判定发散
oscillationWindow / oscillationRatio	10 / 0.7	振荡检测窗口 / 翻转率
redundantWindow	20	冗余 / 熵窗口
entropyWarnAt / entropyRecoverAt	1.0 / 1.5	B4 低熵告警 / 恢复阈值（滞环）

档位 → 稳定阀阈值：fast: 5 / deep: 4 / conservative: 3（档位越高越收紧）。

三、挂载方式

标准安装（bundle，推荐）——本目录即 bundle 形态，含自身 cordis.patch.yml：

dsh plugin --profile web add /home/boom/Deepseek/dsh-cybernetics

或手工方式（旧版本兼容）：把 dsh-cybernetics 加入 profile 的 dsh.profile.bundles， 或直接追加到 profile 的 cordis.patch.yml：

# 追加到 ~/.dsh/profiles/web/cordis.patch.yml 或 headless
- insert:
    - id: cybernetics
      name: '/home/boom/.dsh/plugins/dsh-cybernetics/index.js'

关键：插件 node_modules 必须软链到全局宿主（ln -s $DSH_NODE_MODULES node_modules）， 绝不自己 pnpm 装依赖——否则 TOOL_RUNTIME_SCHEDULER Symbol 不匹配，所有工具调度崩溃。

四、开发教训（来自经验文档）

1. 依赖副本冲突（最大坑）：插件自装 @deepseek-ai/dsh-tools → 宿主出现两个副本 → TOOL_RUNTIME_SCHEDULER（module-level Symbol）不同 → 所有工具调度崩。解法：软链到全局宿主。
2. waterfall 监听器必须 return next()：光调 next() 返回 undefined → 断链 → 后续工具全崩。
3. rc.6 defineTool 签名：execute(args, exec) + output:{schema, render}；工具列表用 ctx.tools.schemas()。
4. HMR 副作用回滚：改插件后 cordis HMR 只重载配置，ctx.tools.register 副作用被回滚 → 需重启 dsh web。
5. 稳定阀三缺陷（积分饱和教训）：计数器跨轮累计不重置 → 锁死（改滑动窗口）； 一票否决无恢复路径（降级为警告注入）；全部工具一视同仁（交互/观测工具豁免）。
6. TRANSPORT 报错根因：tools/pre-execute（工具执行期）注入消息破坏角色交替约束 → 移到 agent/pre-step（请求组装期）用 createUserMessage 构造完整消息。
7. 控制律要自适应：档位切换 + 滞环防抖；反馈要滤波（EMA 估计失败率）。
8. 能控性判定防冷启动误报：观测记忆持久化（observed_tools.json）+ 未观测 ≠ 缺失的语义分层。
9. rc.6 参数字段是 arguments 不是 args：所有 exec 参数读取必须走 execArgsText， 否则 exec.args 恒 undefined（A1 假冗余根因）。

五、验证

# 语法检查
node --check index.js && node --check core.mjs
# 单元测试（10 用例）
node --test test/cybernetics.test.mjs
# 导入冒烟测试（需先软链 node_modules）
node -e "import('./index.js').then(m => console.log(m.name, m.inject))"
# 运行时验证（重启 dsh web 后）
cybernetics_status   # 应含 healthScore / boot 恢复 / 最慢工具
# A3 生效标志：重启后日志出现 event:"boot-recover"
grep boot-recover ~/.dsh/cybernetics/state_log.ndjson | tail -1
# A1 生效标志：重启后冗余计数骤降（不再每调一次 bash 都算冗余）
grep redundant-burst ~/.dsh/cybernetics/state_log.ndjson | tail -1