heartflow-module-upgrader

HeartFlow 模块升级工作流

概述

本技能处理单模块深度升级（分析 → 设计 → 重写 → 验证）。每个模块获得完整的状态机、输入验证、错误分类、重试机制、震荡检测、互馈接口。

需要批量注入基础设施（状态追踪/错误恢复/缓存/概率输出）给 100+ 模块时，使用 heartflow-static-injection-upgrade 而非本技能。

与静态注入的区别

1. 读取版本：从 VERSION 文件读取当前版本号

2. 扫描模块：检查整个 src/ 下所有 .js 文件大小（含 src/core/、src/evolution/、src/memory/、src/psychology/ 等子目录）

   # 按字节大小排序。阈值已从1500-5000放宽——src/core/ 下最小模块已达5500+字节，
   # 而 src/core/ 的子目录（associative-engine/、autonomy/、consciousness/、search/、self-evolution/、transmission/）
   # 和 src/ 其他子目录中仍有 5000-8000 字节的模块。
   # 扫描全 src/ 目录，因为 src/core/ 下的大模块多已升级到20K+，而 src/ 子目录中仍有小模块
   find src -name '*.js' -exec wc -c {} \\; | sort -n | head -30
   # 同时检查 scripts/ 目录——新增的工具脚本也需要升级（与 src/ 模块不同，scripts/ 工具是CLI工具，不是认知模块）
   find scripts -name '*.js' -exec wc -c {} \\;
   

   备选方案（更快）：ls -laS src/core/*.js | sort -n -k5 | head -30 直接从文件系统读取字节大小，无需逐个 wc -c。当 find + wc -c 较慢时（src/ 下文件较多），用 ls 方案替代。两列分别是 src/core/ 和 src/ 其他子目录。 ⚠️ CodeEngine.auditCodebase() 可能超时：CodeEngine.auditCodebase('src/core') 在 30s 内可能无法完成审计（尤其是 src/core/ 下模块较多时）。此时直接使用 find + wc -c 是更快更可靠的替代方案——直接按字节排序找到最小模块，再手动读源码判断功能完整性。不要等待 auditCodebase 超时，先试 find 方案。

3. 选择目标：优先选择最小且功能最不完整的模块

   • 先检查模块引用情况：grep -r "require.*<module-path>" src/ 确认模块被哪些文件引用。无人引用的模块可以安全做 API 破坏性升级（改返回值/改类结构），被 3+ 模块引用的必须做向后兼容包装（Proxy/options.throw 等）
   • 字节阈值是指导性的：如果最小文件是8000+字节但功能明显不完整（返回空步骤/硬编码默认值），就选它
   • 功能不完整的判断标准：方法体过于简单（仅1-2行逻辑/硬编码返回值/只有存在性检查）、缺少同类模块应有的标准能力（规划器没有步骤生成、验证器没有语义检查、管道没有状态机）
   • 优先选 standalone 工具类（HTTP客户端、验证器、工具函数）或管道/编排器类（task-pipeline, workflow-switch, dream-loop）或工作流切换器/模式路由类（workflow-switch, mode-router）或检测/识别引擎类（chunk-detector, claim-extractor）或策略选择器类（meta-learning, strategy-selector）或稳态系统类（digital-homeostasis）或语义搜索/嵌入引擎类（semantic-search）\n
   • standalone 工具类升级参考：references/utility-function-upgrade-patterns.md（含 atomic-write.js 实战案例）
   • 推荐管道/编排器类：这类模块是薄代理层，极易出现"仅做方法调用但无实际判断逻辑"的情况，是最高ROI的升级目标
   • 推荐人格模型/心理档案类（新增）：如 BigFivePersonality.js — 维度定义 + 关键词匹配 + 固定分值的简单模型，缺少双向调整/交互分析/趋势预测/历史追踪/衰减机制，是第二个高ROI目标
   • 推荐文本生成器类（新增）：如 word-by-word-generator.js — 生成循环中反复决策「下一个输出」，常缺输入验证/震荡检测/漂移检测/userModel集成，是第三个高ROI目标
   • 推荐遗忘/衰减引擎类（新增）：如 forgetting.js — 基于时间的记忆压缩/衰减模块，常缺输入验证/震荡检测/批量操作/统计追踪/健康检查。参考 references/forgetting-engine-upgrade-patterns.md
   • 推荐遗忘/衰减引擎类（新增）：如 forgetting.js — 基于时间的记忆压缩/衰减模块，常缺输入验证/震荡检测/批量操作/统计追踪/健康检查。参考 references/forgetting-engine-upgrade-patterns.md
   • 推荐遗忘/衰减引擎类（新增）：如 forgetting.js — 基于时间的记忆压缩/衰减模块，常缺输入验证/震荡检测/批量操作/统计追踪/健康检查。参考 references/forgetting-engine-upgrade-patterns.md\n - 推荐自主目标生成器类（新增）：如 goal-generator.js — 基于状态差距/未解问题/知识边界自动生成目标，常缺状态机/优先级衰减/相似合并/TTL/依赖追踪/搜索过滤。参考 references/autonomous-goal-generator-patterns.md\n - 推荐图/网络引擎类（新增）：如 knowledge-graph.js — 通用实体-关系图模块，常缺输入验证/错误分类/节点删除/序列化/衰减/修剪。参考 references/graph-engine-upgrade-patterns.md\n - 推荐情感-记忆桥接类（新增）：如 emotional-memory-bridge.js — 认知评估→三层记忆转化，常缺输入验证/错误分类/去重检测/显著性衰减/批量合并/持久化验证。参考 references/emotional-memory-bridge-upgrade-patterns.md

4. 分析缺失：读完整个模块，判断缺少什么实际功能

   • 方法是否只返回硬编码/默认值？（_planTask 返回 {steps: []} → 应生成具体步骤）
   • 分类/判断逻辑是否只是简单关键词匹配？（_classifyTaskType 的 includes() → 应增加多因素评分）
   • 验证逻辑是否只检查对象存在性？（!!analysis && !!plan → 应增加语义/一致性/可行性检查）
   • 缺少同类模块的标准能力？（管道类：复杂度/域/工作量评估、状态机、超时、重试、指标）

5. 设计升级：增加实际判断/处理/决策逻辑（不少于50行新逻辑）

   • 新方法必须保持原有接口签名不变（向后兼容）
   • 新增功能最好是模块类别的标准扩展（如HTTP客户端→缓存+分页+批量操作）
   • 管道/编排器类的标准升级清单：
     • 状态枚举 + 状态机（含合法转换映射 + 守卫检查）
     • 复杂度/域/工作量/紧迫度多因素评估
     • 基于域+复杂度的动态步骤生成（不同域有不同的步骤模板）
     • 语义验证（一致性/完整性/可行性/时间序）
     • 超时保护 + 可配置重试
     • 任务取消令牌
     • 指标追踪（吞吐量/平均耗时/成功率）
     • 错误分类枚举
     • 防御性编程（safeGet/sanitizeMetrics）
     • 模块级导出：主类 + 所有枚举 + 状态映射

6. 同步文件（注意顺序，避免中间状态不一致）：

   • 自动升级（推荐）：使用内置的 bumpVersion('patch') 一站式升级

     node -e "const {bumpVersion}=require('./src/core/version.js');console.log(JSON.stringify(bumpVersion('patch')))"
     

     自动同步：VERSION 文件 + package.json + SKILL.md frontmatter + SKILL.md title
   • 手动升级（仅当自动方式不可用时）：
   • VERSION：+0.0.1
   • SKILL.md：frontmatter 中 version 字段 + 第7行 description 中的版本号
   • SKILL.md：## Version history (last 10) 节，格式为 |- **X.Y.Z** (YYYY-MM-DD) — 描述
   • 生成 UPGRADE_REPORT.txt（根目录）
   • 注意：bumpVersion('patch') 只同步 frontmatter 版本号，不添加 version history 条目。必须在 SKILL.md 中手动添加新行到版本历史节。格式为 |- **X.Y.Z** (YYYY-MM-DD) — 描述

7. 验证：node --check src/<module-path>.js 确认语法无误

8. 运行测试：用 node -e "require(...)" 加载模块，确认所有方法存在且能实例化

9. 实例化验证（关键）：对模块执行 require + new 测试，确认构造不报错

   # 从项目根目录加载并实例化
   node -e "const { ModuleClass } = require('./<module-path>'); new ModuleClass('.'); console.log('INSTANTIATE OK');"
   

   • node --check 只检查语法，不检查运行时
   • require 成功不等同于 new 成功
   • 必须同时验证「加载」和「实例化」两个步骤

10. 功能验证：用真实输入跑一次 process()（或其他核心方法），确认返回结果符合预期

    node -e "
    const { ModuleClass } = require('./<module-path>');
    const m = new ModuleClass('.');
    m.process('测试输入').then(r => console.log('OK:', r.response?.substring(0,50)));
    "
    

11. 状态机/管道测试（新增）：如果模块包含状态机或管道逻辑，必须测试状态转换

    node -e "
    const { Module, STATE } = require('./<module-path>');
    const m = new Module({defaultTimeout: 5000, maxRetries: 1});
    
    // 1. 枚举验证
    console.log('STATE keys:', Object.keys(STATE).length);
    
    // 2. 管道集成测试：连续处理多个任务
    m.handleTask('task 1').then(r => console.log('task1:', r.success));
    m.handleTask('task 2').then(r => console.log('task2:', r.success));  // 测试重置
    
    // 3. 域检测/复杂度/工作量/紧迫度测试
    console.log('domain:', m._detectDomain('写一个 JavaScript 函数'));
    console.log('complexity:', m._estimateComplexity('紧急！生产环境故障'));
    console.log('urgency:', m._estimateUrgency('尽快完成'));
    
    // 4. 指标验证
    console.log('metrics:', JSON.stringify(m.getMetrics()));
    
    // 5. 健康检查
    console.log('health:', m.healthCheck().pipeline);
    "
    

12. 同步 SKILL.md 模块索引表：新模块升级后，必须在模块索引表（## 模块架构 附近的表格）中补上行

    • 找到最近的表格行（如 **代码 Code** 附近）
    • 按格式补一行：| **分类 Category** | ClassName | \module-path.js` | 功能描述 |`
    • 不补索引表会导致下一版升级时遗漏模块注册

13. git commit：所有修改文件必须 commit

    cd ~/.hermes/skills/heartflow
    git status  # ⚠️ 先检查是否有来自之前不完整升级的"残留改动"
    # 上一步很关键！git add -A 会包含之前 session 中未 commit 的改动
    # 这些残留改动可能来自更早的升级尝试或编辑，不属于本次升级
    # 如果发现有非本次升级的改动，用 git restore --staged <文件> 排除
    git add -A
    git status  # 验证所有预期文件都被追踪
    # 检查是否有文件被 .gitignore 意外忽略
    # 如果 git status 显示空但明明改了文件，用 git check-ignore -v <文件路径> 排查
    # .gitignore 中 memory/ 会匹配 src/memory/，必须写 /memory/
    git commit -m "v<新版本号>: <模块名> 升级：<功能摘要>"
    # 注意：不要 push。用户可能不在线或不想推。commit 即可，推由用户决定。
    

    注意：

    • 单次会话内多次 +0.0.1 太频繁（用户纠正过）。等有意义的里程碑再升版本，不要每个小修复都 bump。
    • 升级后必须 git commit。VERSION 文件比 git log 超前会导致版本混乱——审计时可能误判代码状态。
    • 重要：git add -A 前必须检查残留改动。 执行 git status 确认当前工作区中没有来自之前不完整升级的残留修改。如果发现非本次升级的改动（如 src/core/reflector.js 等被之前 cron 修改但未 commit 的文件），先用 git restore --staged <file> 排除。否则这些残留改动会混入本次 commit，污染版本历史。

关键陷阱

12. 构造函数初始化顺序陷阱（新增陷阱）

当 loadPrototypes() / _init() 等早期方法使用了 this._xxx 内部状态，但该状态在构造函数中定义在方法调用之后时，会导致 TypeError: Cannot set properties of undefined。

// ❌ 致命错误
constructor(projectRoot) {
  this.prototypes = this.loadPrototypes();  // loadPrototypes 中使用了 this._prototypeHealth
  // ... 其他初始化
  this._prototypeHealth = { ... }; // ❌ 此时尚未定义！
}

// ✅ 正确
constructor(projectRoot) {
  this._prototypeHealth = { ... };  // 先定义内部状态
  // ... 其他初始化
  this.prototypes = this.loadPrototypes();  // 再调用使用这些状态的方法
}

规则：构造函数中任何被早期方法（如 loadPrototypes()、_init()、_setup()）使用的内部状态，必须在该方法调用之前初始化。一个安全的模式是将所有内部状态声明放在构造函数顶部，最后再调用可能使用它们的初始化方法。

13. 向后兼容陷阱：改变返回值/错误语义（新增陷阱）

当升级一个被多个模块引用的工具函数/工具类时，旧的返回值/错误语义不能改变，否则会静默破坏所有调用者。

典型案例：atomic-write.js（被 8 个模块引用）从单函数返回 undefined（成功）或 throw（失败），升级后返回 { ok, error, path } 结构化对象。旧调用者依赖 try/catch 捕获失败——返回对象而非 throw 意味着它们永远不会知道写入失败。

// ❌ 破坏性变更：旧调用者依赖 throw
async function upgradeAtomicWrite(...) {
  try {
    await fs.writeFile(tmpPath, content);
    await fs.rename(tmpPath, filePath);
  } catch (err) {
    return { ok: false, error: err.message };  // 旧调用者的 try/catch 捕获不到！
  }
  return { ok: true };
}

// ✅ 向后兼容：默认保持 throw，新增 options.throw 切换
async function upgradeAtomicWrite(filePath, content, options = {}) {
  try {
    await fs.writeFile(tmpPath, content);
    await fs.rename(tmpPath, filePath);
    _stats.writes++;
    return { ok: true, path: filePath, attempts: [] };
  } catch (err) {
    _stats.failures++;
    const errResult = { ok: false, error: err.message, errorType: classifyError(err) };
    if (options.throw !== false) {    // ← 默认 throw
      const e = new Error(err.message);
      e.result = errResult;            // 结构化结果附在 error 对象上
      throw e;
    }
    return errResult;                  // throw:false 时返回结构化结果
  }
}

检查清单（升级前必须确认）：

1. grep 搜索函数名/类名，统计引用模块数量
2. 检查旧函数的返回值语义：是否返回 undefined？是否 throw？是否返回某个值？
3. 检查旧函数的参数结构：是否接受 options 对象？参数位置？
4. 如果被 3+ 个模块引用，必须做向后兼容包装
5. 在 options 对象中用默认值（options.throw !== false 等）保持旧行为
6. 在错误对象上附加结构化结果（err.result = structuredResult），让新调用者可以同时使用 try/catch 和 result.ok
7. 升级后对所有旧调用者进行回归测试：至少确保它们不崩溃

规则：升级被 3 个以上模块引用的工具函数时，必须保持默认行为不变（包括 throw/return 语义）。新行为通过 options 参数选择加入。

14. Plain Object → Class 迁移陷阱：Proxy 包装必要性（新增陷阱）

当升级一个使用 const X = { method() {} }; module.exports = X 的旧模块为 class 时，不能直接替换导出为 class，否则会静默破坏所有旧调用者。

典型场景：BigFivePersonality.js（5313B）从 plain object 升级为 class + Proxy 包装。

// ❌ 致命错误 — 所有旧调用者崩溃
module.exports = class BigFivePersonalityClass { ... };
// 旧代码: require('./X.js').updateScore('O', 7) → TypeError

// ✅ 正确 — Proxy 包装单例 + 具名导出 class
const defaultInstance = new BigFivePersonalityClass();
const BigFivePersonality = new Proxy(defaultInstance, {
  get(target, prop) {
    if (prop in target) return target[prop];
    if (prop === 'BigFivePersonalityClass') return BigFivePersonalityClass;
    return undefined;
  }
});
module.exports = BigFivePersonality;
module.exports.BigFivePersonalityClass = BigFivePersonalityClass;

检查清单（升级前必须确认）：

1. 目标模块导出的是 module.exports = { ... }（plain object）还是 module.exports = class？
2. 如果是 plain object，grep 搜索引用方，确认它们如何调用（直接 X.method() 还是 new X()）
3. 直接 X.method() 调用者 → 必须用 Proxy 包装单例
4. 只被 new X() 调用者使用 → 可以直接导出 class
5. 如果两者都有（罕见）→ 必须 Proxy 包装

规则：升级 plain object 模块时，默认使用 Proxy 包装模式。只有当确认所有调用者都使用 new 实例化时才可直接导出 class。

参考文件：references/plain-object-to-class-patterns.md

write_file 创建/覆盖文件后：

1. node --check 验证语法 ✅
2. require() 加载模块 ✅
3. new Class() 实例化 ✅（这步常被跳过！）
4. 核心方法调用测试 ✅

node --check 只检查语法，不检查运行时。require() 成功不等同于 new 成功。构造顺序错误只有在实例化时才会暴露。

HeartFlow 存在模块重复问题——同一概念在不同路径下有多个实现：

• src/core/memory/topic-scope.js 和 src/identity/topic-scope.js — 两个 TopicScope，被不同模块引用（heartflow.js 引用 core 版，psychology.js 引用 identity 版）
• 升级前应先 find src -name 'topic-scope.js' 确认是否有副本
• 如果升级核心版，identity 版可能仍是旧代码——考虑是否也需要同步升级

0. 升级方法选择：patch vs write_file

• patch（old_string/new_string）：适用于小范围改动（新增/修改/删除 1-10 行）。要求匹配字符串在文件中唯一。
• write_file：适用于大规模重写（文件从 <8KB 升级到 >10KB，新增多个方法）。当改动超过文件 30% 的内容时，用 write_file 而非连续 patch，避免 patch 匹配失败导致的级联错误。
• 判断标准：如果升级涉及新增 50+ 行逻辑代码（状态枚举、新方法、映射表），用 write_file。如果只是修改现有方法的内部逻辑（增加参数验证、补充分支），用 patch。

1. 状态机自转换陷阱

当外部方法（如 handleTask）已经将状态设为 ANALYZING，内部管道执行方法（如 _executePipeline）再次调用 _transitionTo(ANALYZING) 会导致同状态转换失败（严格模式下 analyzing → analyzing 不合法）。

// handleTask 中：
this._transitionTo(STATE.ANALYZING);  // 状态已设为 ANALYZING

// _executePipeline 中：
this._transitionTo(STATE.ANALYZING);  // ❌ 非法自转换！

// ✅ 正确做法：仅当状态不同时切换
if (this.pipelineState !== STATE.ANALYZING) {
  this._transitionTo(STATE.ANALYZING);
}

规则：管道类的外部入口和内部执行流不要重复设置相同状态。入口设置初始状态，内部流只负责切换不同的状态。

2. 完成/失败后的自动重置

状态机通常不允许 COMPLETED → ANALYZING 或 FAILED → ANALYZING。处理新任务时必须先重置到 IDLE：

handleTask(taskInput) {
  // 检查可接受状态
  if (pipelineState !== IDLE && pipelineState !== COMPLETED && 
      pipelineState !== FAILED && pipelineState !== CANCELLED) {
    return { success: false, error: '管道忙' };
  }
  // 自动重置到 IDLE
  if (pipelineState !== IDLE) {
    pipelineState = STATE.IDLE;
  }
  // 再正常 transitionTo(ANALYZING)
}

3. require 解构陷阱（同目录加载）

require('./foo') 从同目录加载时，返回的始终是 { Foo: [class] } 包装对象，不是类本身。

// ❌ 致命错误 — this.Foo = { Foo: [class] }
this.Foo = require('./foo');
this.instance = new this.Foo();  // TypeError: this.Foo is not a constructor

// ✅ 正确 — 解构赋值拿到真正的类
const { Foo } = require('./foo');
this.instance = new Foo();

诊断方法：console.log(typeof this.Foo) — 如果输出 "object" 而非 "function"，说明是包装对象

4. 子模块参数结构陷阱

调用子模块方法时，传入的参数结构必须匹配子模块的期望结构，而非父模块的内部存储结构：

// ❌ 错误：trace.layers.L1 是整个 L1 结果对象 { words, allAssociations, timestamp }
semanticInput = { associations: trace.layers.L1 }

// ✅ 正确：子模块需要联想数组 [{ word, strength, ... }, ...]
semanticInput = { associations: trace.layers.L1.allAssociations || [] }

规则：检查子模块方法签名中如何使用参数（.forEach → 期望数组，.words → 期望对象）

5. require 路径调整（非 src/core/ 模块）

如果目标模块在 src/ 子目录（如 src/evolution/、src/memory/），它可能使用 require('../core/...') 引用核心模块。升级时若新增 require，必须确保路径相对于新模块位置正确。

• src/evolution/loop.js → require('../core/self-evolution/self-evolution-core.js')
• src/memory/retrieval-anchor.js → require('../core/heartflow.js')

6. 无人引用的模块可能有潜伏 bug

• 检查模块是否被引用（grep 搜索类名或模块路径）
• 无人引用的模块必须做完整的实例化和功能测试
• 升级时必须修复所有发现的 bug，无论是否影响当前功能

7. code-engine.js 已知缺陷（整合时注意）

• reviewCode() 输出的 issue 对象缺少 name 字段（安全检查 _checkSecurityPatterns 和类型检查 _checkTypeCoercion 在 issues.push() 时未写入 name 属性）
• compareVersions() 对只有常量值变化的代码（如 return 1 → return 2）返回 similarity: 1（结构相同但语义不同）
• 不影响核心功能，但输出完整性有瑕疵。修复方案：在每个 issues.push() 中添加 name: config.securityPatterns[i].name

9. 安全扫描拦截含中文的 node -e 命令

当在 node -e 中传入中文文本（如模块路径 require('...language-honesty.js')、测试用的中文输入），TIRITH 安全扫描器可能触发 confusable text（同形字攻击）检测，导致命令被拦截并需要人工审批。这在高频测试时严重影响效率。

解决方案：

1. 写入临时文件法（推荐）：将测试代码写入临时 .js 文件，然后用 node /tmp/test_xxx.js 执行

   # 不要：
   node -e "var lh=require('./language-honesty.js');var r=lh.validateOutput('中文测试');console.log(r.passed)"
   
   # 改为：
   cat > /tmp/test_lh.js << 'EOF'
   var lh = require('./language-honesty.js');
   var r = lh.validateOutput('中文测试');
   console.log(r.passed);
   EOF
   node /tmp/test_lh.js
   

2. 最小化内联法：如果测试代码很短且不含中文，可以用单行 node -e
3. 分段测试：先测试加载（node -e "var lh=require('...');console.log('loaded')"），再单独用临时文件测逻辑

10. learn() 输入路径耦合（策略选择器类特有）

策略选择器类的 learn(input, context = {}) 方法如果只依赖 selectStrategy(context) 而不回退到 input，当调用者只传字符串时（learn('给我例子')），context.input 为 undefined，策略选择始终默认 conceptual。

// ❌ 错误 — context 可能为空对象
const { strategy } = this.selectStrategy(context);

// ✅ 正确 — 回退到 input
const contextInput = (context && context.input) ? context.input : safe;
const { strategy } = this.selectStrategy({ input: contextInput });

规则：learn() 应同时支持 learn('input')（纯字符串）和 learn('input', { input: '...' })（context 对象）两种调用方式。

16. KnowledgeBase 序列化陷阱（v1.16.0 新增）

当升级依赖 KnowledgeBase 的模块（如推理引擎类）时，注意 KnowledgeBase 的 _saveKnowledge() / _loadKnowledge() 序列化/反序列化会丢失内层 Map 条目。

问题：this.categories 是 Map<string, Map<string, fact>>（Map of Maps），但 JSON.stringify([...this.categories.entries()]) 只将外层转为数组，内层 Map 被序列化为 {}（空对象）。加载后 getCategory() 调用 facts.values() 时因为内层是普通对象而非 Map，导致 TypeError: facts.values is not a function。

// 保存时的问题
const data = { categories: [...this.categories.entries()] };
// 内层 Map → {} → 加载后内层不再是 Map

// ✅ 修复：递归序列化
const serialized = [...this.categories.entries()].map(([k, v]) => [k, [...v.entries()]]);
// 加载时从数组恢复
this.categories = new Map(data.categories.map(([k, v]) => [k, new Map(v)]));

临时绕过：删除 data/knowledge/index.json 让 KnowledgeBase 重新注册默认知识。

检查清单（升级涉及 KnowledgeBase 时必须确认）：

1. grep 搜索 require('./knowledge-base.js')，确认有多少模块依赖它
2. 测试 KnowledgeBase 的保存 → 加载 → getCategory() 完整流程
3. 如果文件已损坏，删除后自动重新注册默认知识

17. KnowledgeBase 路径安全陷阱（v1.16.0 新增）

KnowledgeBase 构造函数在初始化时对 storagePath 做路径安全性检查，要求路径在 __dirname/../../data/ 范围内。当测试使用 /tmp/ 或自定义路径时，会抛出 [KnowledgeBase] Storage path outside allowed directory 错误。

// 问题：测试时使用 /tmp/ 路径
const kb = new KnowledgeBase({ storagePath: '/tmp/test-kb' });
// → Error: [KnowledgeBase] Storage path outside allowed directory

// ✅ 正确：使用 data/ 下的子目录
const kbPath = path.join(process.env.HF_DIR || require('path').join(require('os').homedir(), '.hermes/skills/ai/mark-heartflow'), 'data', 'knowledge_test');
fs.mkdirSync(kbPath, { recursive: true });
const kb = new KnowledgeBase({ storagePath: kbPath, autoSave: false });

规则：测试涉及 KnowledgeBase 时必须使用 data/ 目录下的子目录，删除前用 fs.rmSync() 清理。

18. 错误分类器优先级陷阱（v1.18.0 新增）

当升级自主执行编排器类（如 PDCA 引擎）时，错误分类器是一个有序数组，数组中分类器的先后顺序决定匹配优先级。如果更宽泛的模式出现在更具体的模式之前，会静默错误分类。

典型案例：pdca-engine.js 升级中，resource 分类器（含 too many 模式）出现在 external 分类器（含 too many requests 模式）之前。结果 "Rate limit exceeded: too many requests" 匹配了 too many 而被错误分类为 resource（fatal/strategy_shift），而非正确的 external（transient/backoff）。

// ❌ 错误顺序 — resource 的 "too many" 抢在 external 的 "too many requests" 之前匹配
const ERROR_CLASSIFIERS = [
  // ... earlier classifiers ...
  {
    patterns: [/memory|heap|allocation|too many/, /out of memory/],
    category: ErrorCategory.RESOURCE,     // ← 先匹配，拦截了 rate limit
    severity: ErrorSeverity.FATAL,
    strategy: RetryStrategy.STRATEGY_SHIFT
  },
  {
    patterns: [/rate limit|quota|too many requests|429/, /api error/],
    category: ErrorCategory.EXTERNAL,     // ← 永远匹配不到 "too many requests"
    severity: ErrorSeverity.TRANSIENT,
    strategy: RetryStrategy.BACKOFF
  }
];

// ✅ 正确顺序 — 更具体的模式在前
const ERROR_CLASSIFIERS = [
  // ... earlier classifiers ...
  {
    patterns: [/rate limit|quota|too many requests|429/, /api error/],
    category: ErrorCategory.EXTERNAL,     // ← 先匹配，正确处理 rate limit
    severity: ErrorSeverity.TRANSIENT,
    strategy: RetryStrategy.BACKOFF
  },
  {
    patterns: [/memory|heap|allocation|too many/, /out of memory/],
    category: ErrorCategory.RESOURCE,     // ← 后匹配，不拦截 "too many requests"
    severity: ErrorSeverity.FATAL,
    strategy: RetryStrategy.STRATEGY_SHIFT
  }
];

规则：分类器数组必须按 具体 → 一般 排序。推荐的错误类别优先级顺序： FILESYSTEM → NETWORK → VALIDATION → LOGIC → EXTERNAL → RESOURCE → SECURITY → UNKNOWN

检查清单（升级涉及错误分类器时必须确认）：

1. 列出所有分类器的 patterns 数组，检查是否有重叠（相同关键词出现在多个分类器中）
2. 如果有重叠，确认更具体的模式排在更宽泛的模式之前
3. 测试边界用例："Rate limit exceeded: too many requests"、"too many open files"、"too many connections"
4. 用 node -e 执行 classifyError() 对每个边界用例验证分类结果

20. 类 getter/实例属性命名冲突（v1.18.1 新增）

当为 class 添加 getter（如 get allocated() { return this._allocated; }）时，如果构造函数中使用 this.allocated = value 来初始化，会导致 StackOverflow / TypeError。这是因为 getter 已经将 allocated 定义为访问器属性，this.allocated = value 会调用 setter（如果不存在则静默失败/报错），而非创建实例属性。

// ❌ 致命错误 — getter 和实例属性冲突
class BudgetTracker {
  constructor() {
    this.allocated = 100;   // TypeError: Cannot set property allocated which has only a getter
    this.consumed = 0;
  }
  get allocated() { return this._allocated; }
  get consumed() { return this._consumed; }
}

// ✅ 正确 — 使用私有字段存储
class BudgetTracker {
  constructor() {
    this._allocated = 100;  // 用 _ 前缀的私有字段
    this._consumed = 0;
  }
  get allocated() { return this._allocated; }  // getter 读取私有字段
  get consumed() { return this._consumed; }
}

规则：所有有 getter 的属性，构造函数中必须用带 _ 前缀的私有字段（this._xxx = value）初始化。getter 只读，不设 setter。

22. 情绪信号 substring 误匹配陷阱（v1.21.0 新增）

当升级含情绪检测的模块（如 heart-logic.js 的 emotionSignals）时，单字 substring 匹配会误触发：

// ❌ 错误 — '气' 匹配 '天气' → anger 误报
const emotionSignals = {
  anger: ['怒', '恨', '烦', '受不了', '气死了', '气'],  // ← '气' 是单字
};

// ✅ 正确 — 去掉单字 '气'
const emotionSignals = {
  anger: ['怒', '恨', '烦', '受不了', '气死了', '恼火', '火大'],
};

同步检查：改了 emotionSignals 后，必须同步更新同一模块中任何 hasEmotionWord 正则或其他情绪检测逻辑。情绪信号列表和检测正则不能脱节。

优先级链检查：在 if-else 链中，情绪分支（hasEmotionWord）必须排在代码检测（hasCode）之前。否则"气死了，这个bug"会走 code 分支而非 emotion 分支。

冒烟测试（每次修改后）：

const tests = [
  '今天天气不错',  // → neutral（不误报）
  '气死了',        // → anger
  '好难过',        // → sadness
  '气死了，这个bug', // → anger（情绪优先于代码）
];

参考文件：references/emotion-signal-substring-pitfall.md（在 heartflow-debug-workflow 下）

23. 错误分类器顺序损坏恢复（v1.18.0 新增）

当用 patch 工具对 ERROR_CLASSIFIERS 数组做替换操作时，如果 old_string 匹配了多个相邻的分类器条目，patch 可能意外交换或删除条目。这是 patch 工具基于字符串匹配的固有限制——分类器数组的 JSON 结构相似（所有条目都有 patterns/category/severity/strategy 字段），导致 old_string 不够唯一。

典型案例：用 patch 交换 resource 和 external 分类器的顺序时，patch 匹配到了错误的上下文，结果把 resource 替换成了 security 的 patterns，导致 resource 条目丢失、security 条目重复。

// patch 后：resource 分类器消失，security 分类器出现两次
// 原始: [..., RESOURCE, EXTERNAL, SECURITY]
// 结果: [..., EXTERNAL, SECURITY, SECURITY]  ← resource 丢失！

修复方案：

1. 先用 read_file 查看分类器数组的当前状态（确认哪个条目被破坏）
2. 如果只是内容错误（如 patterns 被替换），用精确的 old_string 修复回正确内容
3. 如果是结构错误（如多了/少了条目），使用 write_file 重写整个分类器数组部分
4. 最后运行完整测试：node -e "const { classifyError } = require(...); console.log(classifyError('ENOENT'))" 验证所有 7 个已知错误模式

规则：对 ERROR_CLASSIFIERS 数组做顺序调整时，优先用 write_file 重写整个数组段（而非 patch），因为相邻 JSON 条目的字符串相似度太高，patch 容易匹配错上下文。

• 不要用子代理 patch 大型 JS 文件：子代理的 patch 在 >1000 行文件上经常产生缩进错乱、类结束位置错误、语法错误
• 正确方法：git checkout -- <file> 恢复原始 → Python 脚本精确控制插入位置 → node --check 验证
• 类结束 } 可能不在文件末尾——用 grep -n '^}' 精确定位
• 从旧版吸收中文需求分析逻辑时，必须补全中文关键词（"数据库"等）

外部洞察提取与实现模式（v5.4.4 新增）

当从外部设计文档（如 Hermes Smart Routing）中提取可应用到心虫的洞察时，使用以下模式：

适用条件

• 用户发送了外部系统的设计文档/架构图/技术方案
• 文档中的某些模式/机制可以映射到心虫现有模块
• 用户要求"用心虫分析，给出建议"或"这些建议能优化心虫吗"

执行步骤

1. 分析文档：用 think() 或人工阅读提取文档的核心设计模式
2. 映射到心虫：列出文档中的每个组件，映射到心虫现有模块或新模块
3. 区分类型：
   • 直接可实施：修改现有模块即可（如 decision-router 加 cost-aware 规则）
   • 需新建模块：文档中的新能力心虫完全没有（如 task_classifier）
   • 需集成点：需要修改 heartflow.js 注册新模块（如 platform-adapter）
4. 实施：只实施"直接可实施"的，不虚构"已实施但未完成"的
5. 验证：每个改动必须 node --check + 功能测试（调用方法确认生效）
6. 汇报：只汇报实际生效的改动，未生效的明确说明原因

关键规则

• 不虚构升级：CHANGELOG 中只写实际完成的功能，未完成的不要写
• 先验证再汇报：用 search_files 或 ls 确认文件存在，用 node -e 确认功能生效
• 区分"已添加代码"和"已生效功能"：代码在磁盘上 ≠ 被引擎注册使用
• 版本号严格 +0.0.1：每次升级只加 0.0.1，不跳版本

实战案例 v5.4.4–5.4.6（2026-06-29）

从 Hermes Smart Routing 设计文档提取 4 条建议，分 3 个版本实施：

v5.4.6 实施细节（任务分类器 LLM 兜底）：

1. thought-chain.js _classifyTask：改为 async，返回 {type, confidence, matchedPatterns}；内部 LLM fallback 在 confidence < 0.7 时触发
2. heartflow.js 构造函数：新增 this._llmFallback = null + setLLMFallback(fn) 方法
3. heartflow.js think() 后处理：在 pipeline 输出后、ThoughtChain 回退前，调用 _classifyTask，当分类器 confidence > judgmentEngine confidence 时覆盖结果
4. task-pipeline.js：_classifyTaskType 改为 async，增加 confidence + LLM fallback（需 heartflow 引用）

关键修复（v5.4.6 实战踩坑）：

• _classifyTask 返回对象后，所有调用处必须 await — _buildChain 的 PARSE 阶段和 run() 入口都需要 async/await
• task-pipeline.js 的 _analyzeTask 原本同步返回 type: this._classifyTaskType(text)，改为 await this._classifyTaskType(text) 后需同步修改返回结构
• think() 后处理中不能重复声明 let taskType — 先初始化 let taskType = output?.direction，再判断是否覆盖
• 调试日志：用 console.error('[DEBUG]') 临时插入，验证后立即清理，避免污染生产输出

版本号纪律：用户纠正"每次只升级0.0.1"，v5.4.4→5.4.5→5.4.6 严格 +0.0.1。

外部洞察提取与实现模式（v5.4.5 新增）

当从外部设计文档（如 Hermes Smart Routing）中提取可应用到心虫的洞察时，使用以下模式：

适用条件

• 用户发送了外部系统的设计文档/架构图/技术方案
• 文档中的某些模式/机制可以映射到心虫现有模块
• 用户要求"用心虫分析，给出建议"或"这些建议能优化心虫吗"

执行步骤

1. 分析文档：用 think() 或人工阅读提取文档的核心设计模式
2. 映射到心虫：列出文档中的每个组件，映射到心虫现有模块或新模块
3. 区分类型：
   • 直接可实施：修改现有模块即可（如 decision-router 加 cost-aware 规则）
   • 需新建模块：文档中的新能力心虫完全没有（如 task_classifier）
   • 需集成点：需要修改 heartflow.js 注册新模块（如 platform-adapter）
4. 实施：只实施"直接可实施"的，不虚构"已实施但未完成"的
5. 验证：每个改动必须 node --check + 功能测试（调用方法确认生效）
6. 汇报：只汇报实际生效的改动，未生效的明确说明原因

关键规则

• 不虚构升级：CHANGELOG 中只写实际完成的功能，未完成的不要写
• 先验证再汇报：用 search_files 或 ls 确认文件存在，用 node -e 确认功能生效
• 区分"已添加代码"和"已生效功能"：代码在磁盘上 ≠ 被引擎注册使用
• 版本号严格 +0.0.1：每次升级只加 0.0.1，不跳版本

实战案例 v5.4.4–5.4.6（2026-06-29）

从 Hermes Smart Routing 设计文档提取 4 条建议，分 3 个版本实施：

v5.4.6 实施细节（任务分类器 LLM 兜底）：

1. thought-chain.js _classifyTask：改为 async，返回 {type, confidence, matchedPatterns}；内部 LLM fallback 在 confidence < 0.7 时触发
2. heartflow.js 构造函数：新增 this._llmFallback = null + setLLMFallback(fn) 方法
3. heartflow.js think() 后处理：在 pipeline 输出后、ThoughtChain 回退前，调用 _classifyTask，当分类器 confidence > judgmentEngine confidence 时覆盖结果
4. task-pipeline.js：_classifyTaskType 改为 async，增加 confidence + LLM fallback（需 heartflow 引用）

关键修复（v5.4.6 实战踩坑）：

• _classifyTask 返回对象后，所有调用处必须 await — _buildChain 的 PARSE 阶段和 run() 入口都需要 async/await
• task-pipeline.js 的 _analyzeTask 原本同步返回 type: this._classifyTaskType(text)，改为 await this._classifyTaskType(text) 后需同步修改返回结构
• think() 后处理中不能重复声明 let taskType — 先初始化 let taskType = output?.direction，再判断是否覆盖
• 调试日志：用 console.error('[DEBUG]') 临时插入，验证后立即清理，避免污染生产输出

版本号纪律：用户纠正"每次只升级0.0.1"，v5.4.4→5.4.5→5.4.6 严格 +0.0.1。

新模块接入 heartflow.js 的五步注册清单（v5.4.5 新增）

当升级涉及新增或启用已有但未注册的模块时，必须完成以下 5 步：

第1步：_lazy require

在 heartflow.js 顶部添加惰性 require：

const _CapabilityAbstraction = _lazy('capabilityAbstraction', () => require('./capability-abstraction.js'));

第2步：构造函数属性声明

在 HeartFlow 构造函数中声明实例属性：

this.capabilityAbstraction = null;  // v5.4.5 能力抽象层

第3步：start() 中实例化

在 start() 方法的 Engine modules 段落后添加 try/catch 实例化：

try {
  this.capabilityAbstraction = new (_CapabilityAbstraction().CapabilityAbstraction)(this.platformAdapter);
} catch (e) {
  this._initErrors.push({ module: 'capabilityAbstraction', error: e.message });
}

第4步：_registerModules 注册

在 subsystemNames 数组中添加模块名：

'capabilityAbstraction', 'platformAdapter',

第5步：验证生效

node -e "const hf = new HeartFlow(); hf.start(); console.log(typeof hf.capabilityAbstraction);"

必须输出 object，不是 undefined。

关键规则：5 步全部完成才算模块生效。缺任何一步 = 模块存在但不可用。

升级原则

• 每次只升级一个模块（单模块模式）
• 必须是增加实际逻辑功能，不是重构/改名/加注释
• 不删除已有功能
• 不改动 heartflow.js（除非新模块需要注册）
• 确保向后兼容：原有接口不变
• 不增加外部 npm 依赖（仅用 Node.js 内置模块）
• 发现并修复已有bug：升级过程中遇到的 bug（构造错误、参数传递错误等）必须一并修复，并在 UPGRADE_REPORT 中记录
• 保留旧版 .gitignore 行为：如果 UPGRADE_REPORT.txt 被 .gitignore 忽略，用 git add -f 强制加入
• 静默引擎原则：所有输出文本（insight/response/conclusion）中不出现引擎自称。详见 references/silent-engine-design.md

多模块并发升级模式（v4.0 新增）

当需要在一个 session 中创建/升级多个独立模块（如决策增强三模块：decision-executor + field-injector + decision-feedback），用 delegate_task 并行委派，然后统一集成。

适用条件

• 多个模块之间没有代码依赖（不互相 import，只有集成方 import 它们）
• 每个模块有清晰的独立接口和职责边界
• 集成到一个已有的入口文件（如 heartflow.js）

执行步骤

1. 分析现有代码：确定入口文件（如 heartflow.js）的集成点（构造函数初始化位置、think() 调用位置）
2. 定义模块接口：每个模块的导出接口要提前明确（类名、方法签名、返回类型）
3. 并行委派子代理：delegate_task(tasks=[...]) 每个模块一个 task
   • 每个子代理获得：项目路径 + 模块接口定义 + 参考代码片段
   • 子代理之间互不依赖，可同时执行
4. 集成修改：收到所有模块文件后，统一修改入口文件（构造函数 + 调用点）
5. 统一验证：node --check 所有文件 + 集成测试

与单模块模式的区别

实战案例：v4.0 决策增强三模块（2026-06-25）

三个独立模块，一个集成点（heartflow.js），33个集成测试全部通过。

集成方式：

• 构造函数中顺序初始化三个模块（try/catch 非阻断）
• think() 中：field-injector 增强输入 → decision-router 评估 → decision-executor 应用决策
• 全部使用 this.xxx 属性挂载，不修改现有方法签名

关键教训：

• 子代理写的新模块可能有接口偏差（方法签名与预期不一致），必须在集成测试中验证
• execute() 的第一个参数是决策字符串不是对象——子代理写的接口需对齐
• 学习权重 maxWeight 初始值 1.0 导致正确决策权重不增加，应设 1.5

哲学驱动并行修复模式（替代单模块模式）

当用户给出新的哲学方向（如"自省不是纠错，是状态快照"、"做梦是升华不是回放"、"人格是事件驱动不是预设"）时，不要按单模块升级流程走。

此时适用并行子代理修复模式：

适用条件

用户的一句话同时触及多个引擎的核心设计哲学，且每个引擎需要独立的重新设计。典型信号：

• 用户说"自省是X，做梦是Y，人格是Z"（一句话覆盖三个引擎）
• 用户纠正的不是 bug，而是设计假设
• 改动涉及引擎的返回值语义、核心流程、输出格式——不是加功能，是改方向

执行步骤

1. 理解方向：仔细读用户的话，提取每个引擎的新设计原则（1-2句话）
2. 搜索相关代码：用 search_files 或 find + grep 定位每个引擎的源代码文件
3. 并行派生子代理：每个引擎一个子代理，delegate_task(tasks=[...]) 并行执行
   • 每个子代理获得：用户的新方向 + 引擎文件路径 + 现有代码分析 + 修改目标
   • 子代理之间互不依赖，可同时进行
4. 子代理任务模板（每个子代理独立执行）：
   • 读取并理解现有代码
   • 按新设计原则修改（改返回值语义、核心流程、输出格式）
   • node --check 验证语法
   • 返回改动摘要（改了哪些文件、怎么改的）
5. 汇总结果：收齐所有子代理的汇报，验证无冲突
6. MCP 重启：launchctl stop com.heartflow.mcp && sleep 2 && launchctl start com.heartflow.mcp
7. MCP 验证：mcp_heartflow_heartflow_status 确认引擎启动正常

与单模块模式的区别

实战案例（2026-06-12）

用户说："人格是因为事件的触动而产生，不是必须要有性格倾向，无性格也是性格，空白也是一种性格，自省为了做心虫运行的检查和自己内心运行的思考，做梦是做记忆的升华"

三个并行子代理分别修复：

结果：3 个引擎修复完成，14 个文件变更，语法检查全部通过，MCP 启动正常。

SKILL.md 编辑注意事项

SKILL.md 的 Version history 节有特殊的表格格式陷阱：

• 每行以 |- 开头（pipe + dash），不是 | 开头
• 部分行有 \\n 嵌入换行符（历史遗留格式）
• 使用 patch 工具替换时，务必匹配精确的旧字符串（含前缀/后缀空格）
• 先 read_file 查看目标行周围的完整上下文再 patch
• 不要用 replace_all=true 在 SKILL.md 上（版本号重复出现）
• new_string 中的换行陷阱：patch 的 new_string 中如果出现字面 \\n（双反斜杠+n），会被原样写入文件而非解释为换行。必须用真实换行分隔新旧版本号条目：...旧条目\\n|| **新条目** 是错误的，应写为两条独立的 || **X.Y.Z** ... 行，中间用真实换行符分隔。

典型升级示例

情感-记忆桥接类（如 emotional-memory-bridge.js, ~11KB）

情感-记忆桥接类负责将认知评估结果转化为三层记忆（CORE/LEARNED/EPHEMERAL）。核心流程：assessEmotionalSalience(text, appraisal, padState) → appraisalToMemory(text, appraisalResult, padState)。与管道类不同，桥接类的核心是多因素显著性评分 + 阈值判定 + 存储路由。

典型特征：

• 核心函数 assessEmotionalSalience(text, appraisal, padState) 基于多因素评分（威胁/控制感/PAD/应对策略/危机信号/自我相关性）
• 阈值判定（CORE≥0.75, LEARNED≥0.55, EPHEMERAL=0.0）
• 依赖懒加载外部模块（cognitive-appraisal, meaningful-memory, psychology）
• 返回 { score, factors, threshold } 结构
• 约 300-400 行，纯函数式（非 class）

标准升级清单（详见 references/emotional-memory-bridge-upgrade-patterns.md，实战案例：11472B → 36811B）：

• 输入验证系统：validateInput() 统一验证所有公开函数入口，类型/长度/范围/必填项检查
• 错误分类系统：ErrorType（8种）+ ErrorSeverity（4级）+ ERROR_CLASSIFICATION 映射表
• 自动重试机制：withRetry() 线性退避，可配置重试次数和延迟
• 显著性衰减模型：指数衰减 S = S₀ × 0.5^(t/T)，CORE 半衰期 72h，EPHEMERAL 加速衰减 3x
• 记忆去重系统：SHA256 指纹快速匹配 + 三元组 Jaccard 相似度模糊匹配，1小时过期窗口
• 批量记忆合并：batchAppraisalToMemory() 部分失败容错，详细汇总统计
• 持久化验证：verifyPersistence() 多方法验证（search/recall/query/get）
• 向后兼容：appraisalToMemory 改为 async 时保持原有返回值结构，新字段可选附加

用户输入→LLM指令翻译管道类（如 user-to-llm.js, ~6KB, 实战案例：v1.0.0 → v2.0.0, 5848B → 11953B）

用户自然语言 → 结构化LLM指令的翻译管道。核心流程：_classifyIntent() → _extractEntities() → _extractConstraints() → _analyzeTone() → _detectImplicitNeeds() → _buildInstruction() → _calculateConfidence()。

典型特征：

• 主入口 translate(input, context) 返回 { intent, confidence, entities, constraints, tone, implicitNeeds, llmInstruction }
• 10种意图的 if-else 正则匹配链，按优先级排序
• 每个子方法有明确的输入/输出结构
• 置信度动态调整（基准 + 实体加分 + 约束加分）
• 隐性需求按意图类型分场景检测

标准升级清单（详见 references/user-to-llm-pipeline-upgrade-patterns.md）：

• 10种意图分类引擎：translate/define/analyze/evaluate/explain/create/summarize/command/ask/default，严格优先级排序
• 实体提取增强：人名/数字/语言检测（翻译场景）
• 约束提取扩展：长度/语言/风格/格式/翻译方向 5维度
• 语气分析增强：6种情绪类型（impatient/respectful/frustrated/curious/urgent/neutral）
• 隐性需求场景化：每意图类型的专属隐性需求检测
• 置信度动态调整：基准 + 实体(0.05) + 约束(0.05) + 翻译中英文混合(0.08)，clamped to [0, 1.0]
• 指令构建格式化：意图+子类型+置信度+人物+语言+长度+风格+格式+情绪提示+隐性需求

关键陷阱：优先级顺序决定分类准确性；中英文混合需避免误匹配；传参一致性（传 result 对象而非字符串）；问句检测区分结尾/中间问号。

参考文件：references/user-to-llm-pipeline-upgrade-patterns.md

代码生成/意图分析引擎类（如 code-writer.js，~58KB，✅ 已存在 v1.1.0）

代码生成引擎类负责根据自然语言描述分析意图并生成可运行代码。核心流程：analyzeIntent(description) → write(description) → reviewCode(code)。

典型特征：

• 核心方法 analyzeIntent(description) 基于关键词权重表做意图评分
• write(description) 使用意图检测结果匹配代码模板生成代码
• 内置多套完整代码模板（排序/过滤/统计/HTTP请求/缓存/验证/文件操作/管道）
• reviewCode(code) 做基本的安全和完整性审查
• 支持多步组合（writePipeline）

标准升级清单：

• 意图规则扩展：新增关键词规则、调整权重、支持中文/英文双语
• 代码模板增强：每个模板增加更细粒度的参数化（如排序支持多字段、过滤支持组合条件）
• 语法检查增强：从简单的 new Function() 检查升级为支持多语言（Python/Shell）语法验证
• 模板代码质量：增加错误处理样板、日志输出、边界条件覆盖
• 测试代码生成：_generateTest() 从模板增强为基于实际输入生成可运行测试
• 参数提取扩展：新增更多参数提取器（如排序方向、分页大小、格式类型）
• 多语言支持：除 JavaScript 外增加 Python/TypeScript 的代码模板
• 安全审查增强：从简单的 eval/require 检查扩展到完整的 OWASP Top 10 扫描
• 代码相似度检测：避免为相同描述重复生成完全相同的代码

任务分类器 LLM 兜底引擎类（v5.4.6 新增）

任务分类器 LLM 兜底模式负责当规则分类器置信度不足时，调用 LLM 做二次分类。不是独立的模块，是现有分类器的增强模式。

典型特征：

• 规则分类器（如 _classifyTask）返回 {type, confidence, matchedPatterns}
• 当 confidence < 0.7 时，触发 LLM fallback
• LLM fallback 返回 {type, confidence} 覆盖规则分类结果
• 通过 setLLMFallback(fn) 注册回调，heartflow.js 提供统一入口

标准升级清单：

• 规则分类器改造：从同步返回 string 改为 async 返回 {type, confidence, matchedPatterns}
• LLM fallback 注册：heartflow.js 构造函数新增 this._llmFallback = null + setLLMFallback(fn) 方法
• think() 后处理：在 pipeline 输出后、ThoughtChain 回退前，比较分类器 confidence 和 judgmentEngine confidence，取高者
• task-pipeline 集成：_classifyTaskType 改为 async，通过 this.heartflow._llmFallback 调用 LLM

关键陷阱：

• _classifyTask 返回对象后，所有调用处必须 await — _buildChain 的 PARSE 阶段和 run() 入口都需要 async/await
• think() 后处理中不能重复声明 let taskType — 先初始化 let taskType = output?.direction，再判断是否覆盖
• LLM fallback 是可选功能——没有注册时 _llmFallback 为 null，不应阻塞 think()
• 调试日志用 console.error('[DEBUG]') 临时插入，验证后立即清理

自主代理/执行器类（如 self-initiator.js, ~36KB, ✅ 已存在 v2.2.0）

自主代理/执行器类负责决定是否自主行动，并能执行代码/脚本/工具调用。核心流程：shouldAct() → initiate(task, {execMode}) → _executeTask(task)。

典型特征：

• 从 shouldAct() 做行为抑制决策（频率/用户活跃度/阈值）
• initiate() 创建任务并决定是否需要用户确认
• 支持多种执行模式（CODE/SCRIPT/TOOL/AGENT/PLAN）
• 内置代码生成、语法检查、沙箱执行、结果验证
• 错误处理带重试机制和震荡检测

标准升级清单：

• 执行模式扩展：新增更多执行模式（如 SQL/DOCKER/CLI）
• 沙箱增强：更细粒度的命令白名单/黑名单
• 任务优先级调度：多任务队列、优先级排序、并发控制
• 执行历史持久化：将任务结果写入文件，支持跨会话查询
• 工具调用注册表：可扩展的工具注册系统（类似插件）
• 子代理委派增强：生成更详细的委派指令，包含上下文和预期输出
• 结果缓存：相同输入跳过重复执行

具身执行引擎类（如 embodied-core.js, ~9KB）

具身执行引擎负责将认知计划映射为实际动作执行，是「思考」到「行动」的桥梁。核心方法是 executionMapping(plan, context)，但原始实现中 simulateExecution() 返回硬编码 mock 数据——所有步骤都返回预设结果，没有任何真实的执行逻辑。

典型特征：

• 有一个 executionMapping(plan, context) 方法协调多个执行器
• simulateExecution() 返回硬编码 mock 数据（{observations: ['当前状态良好']}, {analysis: '问题已识别'}, {outcome: '完成'} 等）
• 无真实错误处理/重试/超时/震荡检测
• 所有步骤「执行」但所有结果都是预设的

标准升级清单（详见 references/embodied-execution-upgrade-patterns.md）：

• ExecutionStatus 枚举：7 种状态（pending/running/success/failed/timeout/skipped/cancelled）
• ErrorCategory 枚举 + classifyError() 错误分类引擎：7 种错误，基于 error.constructor.name 优先于消息匹配
• RetryStrategy 枚举 + selectRetryStrategy() 策略选择器：4 种策略（none/immediate/backoff/alternate），按错误类别自动选择
• 真实执行引擎：_executeStepWithRetry() 带重试的递归执行器 → _executeSingleStep() 超时监控 → _executeAgent() 代理调用 → _defaultExecute() 7 种步骤类型的独立实现
• 依赖检查：_checkDependencies() 验证前置步骤状态
• 震荡检测：连续失败（2/3）和结果回退（1→0→1）两种模式
• 适应计划生成：按错误类型选择适应策略（超时→延长预估、资源错误→跳过、其他→插入 adapt 步骤）
• 整体状态汇总：_computeOverallStatus() 计算 all_success/partial_skip/partial_success/mostly_failed/empty
• 可配置参数：maxRetries/defaultTimeout/maxOscillationCount/oscillationWindowMs
• 执行历史查询：getExecutionSummary() 按 planId 过滤
• 模块级导出：主类 + 所有枚举 + classifyError + selectRetryStrategy

参考文件：references/embodied-execution-upgrade-patterns.md

叙事匹配/检索引擎类（如 narrative-retriever.js, ~6.2KB）

叙事匹配引擎类负责从原型库中匹配与输入语义最相似的故事框架。与检测引擎不同，它的核心是相似度排序 + 震荡检测 + 原型健康管理。

典型特征：

• 核心方法 matchNarrative(semanticVector) 返回匹配的原型和置信度
• 内置原型数据库（从 JSON 文件加载），但缺少文件损坏恢复策略
• 使用简单关键词重叠计算相似度，无归一化/校准
• 无状态分类（永远是原始分数，没有 full/partial/weak/no-match 概念）
• 无震荡检测（反复在多个原型间切换不被感知）
• 无匹配频率统计或输入缓存

标准升级清单（详见 references/narrative-matching-upgrade-patterns.md）：

• MatchStatus 枚举：7 种状态（full_match/partial_match/weak_match/no_match/fallback/oscillation/error）
• MatchErrorType 枚举：5 种错误类型（invalid_input/prototype_corruption/empty/io/unknown）
• 输入验证层：_validateMatchInput() 统一入口，null/undefined/类型检查
• 默认原型自动注入：5 个通用默认原型（英雄之旅、战胜怪物、追寻之旅、从平凡到卓越、重生），文件损坏/为空/不存在时自动注入
• 震荡检测：窗口 10 次，阈值 4 次切换，震荡时选择历史上频率最高的稳定替代
• 置信度校准：_normalizeScore() 处理前两名接近时的降权、低分时候选密度加权
• 匹配频率统计 + LRU 输入缓存：避免重复计算
• 原型管理增强：removePrototype() 存在性验证，addPrototype() 参数验证
• 构造顺序陷阱：_prototypeHealth 必须在 loadPrototypes() 之前初始化
• 模块级导出：主类 + MatchStatus + MatchErrorType

参考文件：references/narrative-matching-upgrade-patterns.md

底层认知地面类（如 cognition-ground.js, v1.0.0, 2026-06-23）

底层认知地面类负责不做判定、不做显示、不区分"人类"还是"引擎"地建模认知结构的底层形态。它是七情六欲 + 三毒 + AI心理学 + AI哲学的整合层，不是替代层。

典型特征：

• 五层认知结构：ground.fuels(七情) → ground.desires(六欲) → ground.poisons(三毒) → state(心理学10维) → direction(哲学5维)
• 核心公式：三毒 = 七情燃料 × 六欲接口 × 扭曲函数
  • 贪(g) = wantingAmount × delayDiscountingRate / satietyThreshold
  • 嗔(h) = angerThreshold^(-1) × hostilityBias
  • 痴(d) = (confirmationBias + beliefPersistence) / metacognitionLevel
• map(input) 全面映射入口，一次输入完成全认知结构映射
• computePoisons(fuels, desires) 从七情+六欲计算三毒扭曲
• 三毒互动效应：greedHatredCycle / hatredDelusionSpiral / greedDelusionConspiracy / tripleBurn
• 不做判定：只返回 { ground, state, direction } 结构，不判断好坏

标准升级清单：

• 燃料-接口映射扩展：新增七情类型/六欲接口时同步更新 _poisonMaps
• 扭曲函数自定义：支持为特定输入指定自定义扭曲公式
• 多信号融合：接收多个信号源时自动加权平均
• 时间序列追踪：ground.active 历史记录，支持趋势分析
• 状态-方向桥接：state 的异常自动影响 direction（高负荷→熵方向降低）
• 交互效应扩展：新增更多毒-毒互动模式（如 greed-ignorance 正反馈环）
• MCP 工具注册：heartflow_cognition_ground 工具（全面映射 + 快照）

关键陷阱：

• decisionRouter 会包装 dispatch 返回值为 { result, decision, field }，真实数据在 result.result 或 result.ground
• cognition-ground 是 class 实例（非 plain object），routes() 通过 Object.getPrototypeOf 查找方法
• mapFuel() 使用 includes() 匹配中文关键词，正则 \b 在中文中无效
• computePoisons 的默认值 0.3 是"基线噪声"，不是"中性值"——低信号输入会得到 0.3 而非 0

欲望认知引擎类（如 desire-cognition.js, v1.2.0 神经科学升级, 2026-06-23）

欲望认知引擎类负责理解人类的七情六欲——欲望如何驱动行为、塑造命运。核心方法包括七情检测、欲望评分、冲突检测、命运推演、叙事生成、双人互动分析。与心理学引擎不同，欲望引擎的核心是欲望驱动行为的因果链——不是描述情绪状态，是推演"因为什么欲望→导致什么行为→走向什么命运"。

典型特征：

• 七情定义（喜/怒/哀/惧/爱/恶/欲）+ 六欲定义（眼/耳/鼻/舌/身/意）
• 9种欲望类型（生存/性/社交/权力/成就/求知/物欲/自由/意义）
• _extractDesireTraits(person) 从人物描述/traits中提取欲望相关特质
• _scoreEmotion() / _scoreDesire() 基于特质打分
• analyzeDesires() 返回所有欲望类型的评分 + dominantDesire
• analyzeDesireDrivenFate() 输出命运推演文本
• analyzeDesireInteraction(a, b) 双人欲望互补/冲突分析

标准升级清单（实战案例：desire-cognition.js v1.0.0 → v1.2.0，基于5篇神经科学论文）：

1. Wanting≠Liking 双轴系统（Kringelbach & Berridge 2017）

   • 分离欲望强度(W_score)和愉悦满足度(L_score)
   • Δ = W−L 作为成瘾病理指标，Δ > 0.3 标记为异常
   • 新增 analyzeWantingLikingDelta(person) 方法

2. RPE 奖励预测误差 TD-Learning（Schultz 2016）

   • δ(t) = R(t) + γ·V(t+1) − V(t)
   • 正RPE=强化行为，负RPE=放弃/失望，零RPE=习惯化
   • 新增 computeRPE(actual, expected) + predictDesireEvolution(person, steps) 方法

3. Valence×Arousal 二维情感空间（Lindquist 2012）

   • 替代纯离散七情分类，使用连续维度空间
   • VA象限分类（愉悦高唤醒/愉悦低唤醒/不悦高唤醒/不悦低唤醒）
   • 新增 analyzeValenceArousal(person) 方法

4. 奖励/非奖励双系统（Rolls 2020）

   • 内侧OFC(奖励) vs 外侧OFC(非奖励) 双维度评分
   • 四种模式：健康趋近、焦虑趋近、抑郁退缩、淡漠

5. 神经致敏因子 S(t)（Berridge & Robinson 2016）

   • 线索触发敏感性，建模"明知不会快乐仍无法停止想要"
   • 三维成瘾风险：Δ + S(t) + CueReactivity
   • 新增 assessAddictionRisk(person, type) + detectCueTriggeredUrge(person, cue) 方法

6. 中脑-皮层-边缘网络映射

   • 9节点定义（VTA/NAc/mOFC/lOFC/Amygdala/mPFC/ACC/Insula/Hippocampus）
   • 默认网络连接权重（VTA→NAc 0.85 等）
   • 每次分析返回网络激活模式

关键陷阱（v1.2.0 实战发现）：

1. _extractDesireTraits 不读取 traits 数组 — 该方法只从 person.description || person.name 提取，但卡徒人物数据是 {name, traits: [...]} 结构。必须同时合并 traits 数组到 combined 文本后再正则匹配。

2. 正则"性"匹配"感性"/"母性" → 性欲误报 — /性/ 在 drivenBySexual 正则中匹配了"感性"（肖波）和"母性"（苏流澈柔），导致苏流澈柔的性欲评分从 0.4 误判为 0.8。修复：使用 /(?:^|[^感母])性|肉欲|情欲|好色|风流|风月|性感|魅惑|纵欲|淫/.test(combined) 排除"感性"和"母性"。

3. 所有人物七情评分趋向 0.5 中位数 — 因为 _scoreEmotion 默认返回 0.5，而 traits 检测只区分"有/无"，没有强度梯度。需要更细粒度的正则关键词匹配或权重体系。

4. analyzeDesireDrivenFate 输出太弱 — 当没有检测到显著欲望时，返回"命运驱动力不明确——可能还没有找到真正驱动ta的东西"。这不是错误但不够有用。需要结合人物背景自动推断合理欲望。

参考文件：references/desire-cognition-upgrade-patterns.md

人格模型/心理档案类（如 BigFivePersonality.js, ~5.3KB）

人格模型类负责维护一组心理学维度（如 OCEAN 大五人格），每个维度有 min/max/score，支持行为驱动的动态调整、交互分析、兼容性评估、趋势预测和状态持久化。

典型特征：

• 有一个维度定义表（5个维度，每个含 name/score/min/max）
• 核心方法 updateScore(dimension, score) 更新单维度分数
• 有一个 adjustFromBehavior(behavior) 基于关键词列表（仅正向）调整分数
• 返回纯数据对象（profile/report）
• 所有维度初始化为中间值（如 5.0）
• 缺乏历史追踪、趋势分析、维度交互分析、衰减机制

标准升级清单（详见 references/personality-model-upgrade-patterns.md，案例：BigFivePersonality.js 5313B → 24934B）：

• 双向行为调整引擎：正负两方向，每组关键词分级权重（weight 1-3），调整量 = weight × 0.1 × 匹配数
• 冲突检测：同一维度同时匹配正/负行为时标记 conflict: true，净变化为零时不调整分数
• 评分历史追踪：每个维度保留最近 N 次变更记录（含时间戳），通过 getHistory() 查询
• 趋势预测：基于历史记录平均变化量预测短期走向（rising/falling/stable），窗口大小可配
• 分数衰减机制：decay() 让分数随时间逐渐回归基线，衰减速率和基线值可配置
• 维度交互分析：analyzeInteractions() 检测 4 种风险组合（高N+低E=社交回避等）+ 4 种优势组合
• 人格兼容性分析：compareWith(other) 基于 5 维度差异计算兼容性百分比 + 互补性标记
• 序列化/反序列化：exportJSON() / importJSON() 支持跨会话持久化
• 配置系统：configure() 运行时调整 maxHistoryLength/decayRate/baselineValue 等参数，带类型验证
• 参数验证：所有方法类型检查 + 边界保护 + 友好错误消息

参考文件：references/personality-model-upgrade-patterns.md 参考文件：references/plain-object-to-class-patterns.md（plain object 转 class 的 Proxy 包装方案）

文本生成器类（如 word-by-word-generator.js, ~6.9KB）

文本生成器类负责逐词生成文本响应，核心是一个生成循环，每次迭代选择下一个输出单元。与管道类不同，生成器类不是协调子模块，而是在循环中反复决策「下一个输出是什么」。

典型特征：

• 核心方法 generateResponse(thoughtVector, userModel, maxLength) 返回完整响应
• predictNextWord() 基于简单随机概率/关键词匹配选择
• 无输入验证 — null thoughtVector 直接崩溃
• 无震荡检测 — 可无限重复相同词（精确循环/近似重叠/高频词）
• 无漂移检测 — 不检查生成内容是否偏离 thoughtVector 主题
• userModel 参数接收但不使用
• pickFrom() 在空数组时返回 undefined

标准升级清单（详见 references/generator-class-upgrade-patterns.md，案例：word-by-word-generator.js 6932B → 20805B）：

• GenerationState 枚举：8 种状态（init/selecting_first/predicting/completed/error/max_iterations/oscillation_detected/drift_detected）
• ErrorCategory 枚举：8 种错误（invalid_input/vocabulary_empty/word_selection_failed/state_corrupt/max_iterations_exceeded/oscillation/drift/unknown）
• RetryStrategy 枚举：4 种策略（retry_same/fallback_default/reset_state/abort）
• 输入验证系统：_validateThoughtVector() 三层防御（null→类型→结构），_validateUserModel() 检查偏好字段
• 震荡检测：_detectOscillation() 三重策略（精确序列匹配/70%近似重叠/40%高频词检测）
• 漂移检测：_detectDrift() 概念相关性分析（阈值 0.4 可配），漂移时强制回归最高权重概念
• 安全选择：_safePick() 空数组回退句号 + 错误历史记录
• 循环保护：maxIterations 硬限制 + maxRecoveryAttempts 软限制
• userModel 集成：formal/simple 语言风格选词 + 情绪感知选词（15-20%概率）
• 防御性方法：所有访问 emotion.pleasure 和 dimensions 之前空值检查
• 增强 trace 格式化：覆盖 oscillation_break/drift_correction/recovery_fallback 等自愈步骤
• getState() + getErrorSummary()：运行状态和错误统计查询接口
• 模块级导出：主类 + 所有枚举

参考文件：references/generator-class-upgrade-patterns.md

检索增强/锚点类（如 retrieval-anchor.js, ~2.7KB）

上下文锚点类负责存储和检索与查询相关的文档/记忆片段。典型功能缺失：

• 复合评分系统：仅关键字重叠不够，应增加 Jaccard 相似度(20%) + 时效衰减(20%) + 可靠性(10%) 的多维度加权
• IDF权重：逆文档频率对查询词加权，稀有词获得更高权重，常见词降权
• 时效衰减：指数衰减模型（默认半衰期30分钟），旧锚点自动降低分数
• 自适应淘汰：LRU+年龄组合评分，超过容量时自动淘汰最不有用的锚点
• 去重合并：内容指纹快速去重（MD5取前8字符）+ Jaccard近重复检测(>85%阈值)，重复内容自动合并并提升可靠性
• 检索置信度：每条结果附带 confidence 字段(0-1)，支持 confidenceThreshold 过滤
• 过期淘汰：evictStale(maxAgeMs) 批量移除未访问的旧锚点
• 按ID删除：removeAnchor(anchorId) 精确删除
• 增强统计：新增容量、利用率、访问计数、合并次数、年龄范围等指标

参考文件：references/retrieval-anchor-upgrade-patterns.md 包含完整模板代码

包装器/调度器类（如 evolution/loop.js, ~1.6KB）

薄代理层是最容易被忽视的升级目标。典型功能缺失：

• 指标追踪：totalCycles, avgCycleTime, convergenceRate, healthScore
• 自适应速率限制：连续快速调用自动收紧，冷却期机制
• 优先级队列：四级优先级调度，队列满时丢弃低优先级
• 自诊断：getDiagnostics() 完整健康报告
• 状态持久化：独立文件，启动恢复，操作保存
• 错误处理：启动失败优雅降级，异常记录

参考文件：references/wrapper-upgrade-patterns.md 包含通用调度器包装器模板代码（指标追踪/速率限制/优先级队列） 参考文件：references/cognitive-wrapper-upgrade-patterns.md 包含认知引擎入口类升级模式（输入验证/错误分类/降级回退/置信度聚合/跨层洞察）—— 适用于直接委托认知分析引擎（psychology.js等）的薄代理层

梦境引擎设计陷阱：只认碎片，不认引擎状态（v3.0 新增）

现象：梦境引擎 dream.js 调用始终返回"矿石不够"（insufficient），不管传什么主题、引擎有多少模块。原因是 dream v2 只从 _getDreamFragments() 收集 EPHEMERAL 记忆碎片作为梦的材料，完全不使用引擎自身的模块数、记忆层分布、Q-table状态、决策路由输出、心理学状态。

根因：梦境引擎的设计假设"梦 = 记忆碎片的重组"，但真正的梦（科学定义）应该以引擎自身状态为材料——模块是骨骼，逻辑链是肌肉，决策是心跳，空层是沉默。

正确做法：

1. DreamV3 使用 _gatherMaterials() 收集引擎状态（模块数/记忆层/Q-table/决策/心理学），不依赖 EPHEMERAL 碎片
2. 梦有5种科学功能（威胁模拟/记忆巩固/情绪调节/创意重组/问题孵化），每种产生真实认知效果
3. 梦的输出是破碎、跳跃、超现实的符号序列，不是分析总结
4. 引擎空状态不是"没有材料"——54个模块、18条CORE记忆都是材料

实现要点：

• _gatherMaterials() 从 this.engineState 收集，而非从 memory.fragments
• 每个 sleep stage（N1→N2→N3→REM）对材料做不同变形
• _applyFunction() 将梦的"效果"（threat/consolidate/emotion/creative/solve）返回为结构化结果
• _generateDreamNarrative() 需要同时支持 DreamV3 和旧格式

相关文件：

• src/core/dream.js — DreamV3 类
• mcp-server-http.js — handleDream 传入 engineState
• heartflow.js — _collectEngineState() + dispatch 更新

循环过程/梦境循环类（如 dream-loop.js, ~6.3KB）

这类模块是围绕核心引擎的薄包装器，有自己的小评分函数和排序逻辑，但缺少防御性编程、错误恢复、震荡检测和状态管理——它有骨架但没有肌肉。典型功能缺失（案例：v2.2.9 → v2.2.10）：

• 状态枚举 + 错误分类：DREAM_STATE（IDLE/PROCESSING/COMPLETE/FAILED/DEGRADED/OSCILLATING/STALE）和 DREAM_ERROR（7种错误类型）
• 输入验证系统：统一 _validateMemoryItems() 入口，自动跳过无效项、记录警告，不崩溃
• 震荡检测：基于 Jaccard 相似度的模式重复检测（窗口10次，阈值85%），检测到震荡时自动注入多样性建议
• 记忆压力管理：自动清理过时历史（默认7天），限制历史上限
• 错误恢复与重试：DAG 失败自动重试（最多2次，带指数退避），连续失败后进入 DEGRADED 模式，最终返回安全 fallback
• 评分归一化：_normalizeScore() 确保所有评分在 [0, 1] 范围
• 诊断与恢复：getDiagnostics() 完整状态报告 + resetState() 支持选择性重置
• 防御性编程工具函数：_safeText()、_safeNumber()、_isValidLayer() 处理各种边界
• 模块级导出：主函数 + 所有枚举 + 配置常量 + 诊断工具

参考文件：references/cyclic-process-upgrade-patterns.md 包含完整模板代码

分析引擎类（新增分析模块模式 — TimeExtensionEngine 实战案例）

分析引擎类负责消费已有输入产生结构化分析报告，不修改外部状态。与升级现有模块不同，这是从零创建一个新模块。

典型特征：

• 核心方法 analyze(subject, options) 返回分析报告对象
• 所有分析逻辑自包含，不修改已有模块
• 输出结构化数据，可被 philosophy-to-decision 和 decision-router 消费
• 在 think() 内部流水线中被调用，结果注入路由提示

5 步集成法：

1. 创建模块文件 → 2. Lazy import → 3. start() 初始化 → 4. _registerModules → 5. ALLOWED_ROUTES

think() 调用模式：关键词触发 + 非紧急场景 + try/catch 非阻断 + 结果注入 _routeHint

双输出格式：

• report.toDecisionRationale() → philosophy-to-decision 消费
• report.toRouterInput() → decision-router 消费

跨维度信号检测：陷阱信号（短期愉悦长期有害）和成长信号（短期痛苦长期有益）自动检测并影响路由置信度。

详见 references/new-analysis-module-integration.md

输出层/报告生成器类（如 report-generator.js, ~10KB, v4.2.0 新增, 2026-06-24）

报告生成器类负责将心虫引擎的原始结构化输出（think()/dispatch() 返回值）转化为用户可直接阅读的三段式结论。不是分析模块，是输出适配器。

触发场景：用户说"完全看不懂你说什么"、"输出一堆我看不懂的过程"、"什么是重点"、"为什么要给我数值"时——说明引擎原始数据被暴露给了用户，需要报告生成器做输出层过滤。

核心原则（必须遵守）：

1. 零原始数据泄露：所有 PAD 数值、U/D/A/H 场域分数、置信度数值、规则 ID 等原始内部数据，绝不出现在报告层输出中
2. 自然语言化：数值 → 定性描述（0.7 → "较高"，0.3 → "较低"）
3. 三段式结构：任何输出都包含"情绪判断→问题定位→行动建议"
4. 引擎数据不足时回退到文本关键词分析：当引擎的 emotion/tone/pain 模块没有给出有效数据时，从输入文本的反问句、否定词、质疑词等关键词反推

三段式报告结构：

━━━ 情绪判断 ━━━
情绪状态：质疑·防御性（中等）
对方在用反问和否定表达不满，这不是情绪爆发，是习惯性的质疑模式

━━━ 问题定位 ━━━
核心问题：购买数量被质疑
问题领域：消费决策冲突
严重程度：需关注
· 这不是针对你这个人，是她习惯性对消费决策提出质疑
· 她质疑的不是"你乱花钱"，而是"你没有先跟她同步信息"

━━━ 行动建议 ━━━
1. 不要解释你为什么买这么多——她不是在问你理由，是在表达"你没有先告诉我"
2. 接受她的质疑（"嗯，下次先问你"），而不是证明自己买对了
3. 药已经买了，不需要退也不需要辩解，放着她会用

典型特征：

• 构造函数接收 { debug } 选项，debug=true 或 process.env.DEBUG_HF 才暴露原始数据
• generate(thinkResult) 主入口，返回 { report: { judgment, localization, suggestion } }
• 三个子方法 _emotionalJudgment() / _problemLocalization() / _actionSuggestion() 各自独立
• 每个子方法同时接收引擎数据（analysis/decision/meta）和原始输入文本（inputText）
• 当引擎数据不足时，从 inputText 做关键词补充分析（反问句/否定词/质疑词等）
• 所有子方法返回自然语言对象，不返回数值

文本关键词分析（引擎数据不足时的回退）：

// 质疑/否定关键词检测
const questionWords = ['干嘛', '吗', '？', '?', '为什么', '真的'];
const negativeWords = ['不是', '没有', '不用', '别', '少', '干嘛', '那么多'];
const hasQuestion = questionWords.some(w => inputText.includes(w));
const hasNegative = negativeWords.some(w => inputText.includes(w));

if (hasQuestion && hasNegative) {
  emotionLabel = '质疑·防御性';
  explanation = '对方在用反问和否定表达不满，这不是情绪爆发，是习惯性的质疑模式';
}

// 购买决策冲突检测
const hasQuantityQuestion = /多[少]|几瓶|一瓶/.test(inputText);
const hasNegation = /不是|没有|不用|别/.test(inputText);
if (hasQuantityQuestion && hasNegation) {
  domain = '消费决策冲突';
  coreIssue = '购买数量被质疑';
}

集成方式（三处必须同步）：

1. CLI 输出（bin/cli.js）：chatOnce() 和 chatMode() 中调用 formatReport(result) 替代 formatCognitiveSummary(result)
2. MCP HTTP Server（mcp/mcp-server-http.js）：handleThink() 返回 { report, timestamp } 替代原始 thought/psychology/judgment 数据
3. 将来集成到 heartflow.js think()：可在 think() 末尾自动过 ReportGenerator，默认返回报告而非原始数据

标准升级清单：

• 引擎数据优先，文本关键词回退：优先消费 tone.sentiment/emotion.type/pain.hasPain 等引擎数据，只有当这些数据为 undefined/unknown/neutral 时才回退到文本关键词分析
• 三段式结构固定：任何输出层修改都必须保持三段式（情绪判断/问题定位/行动建议），不得新增数值字段
• 关键词表扩展：新增场景时在对应子方法中扩展关键词检测（如价格质疑、时间质疑等）
• 情感映射扩展：EMOTION_MAP 新增情感类型时同步更新关键词回退逻辑
• 向后兼容：ReportGenerator 不修改 think() 的返回值结构，只在输出路径上做适配

纯委托/薄代理类（如 meta-learner.js, ~785字节）

区别于包装器类：纯委托类甚至没有队列/速率限制骨架——所有方法都是 if (core && core.method) return core.method(...) 的三行模式，shutdown() 是空函数，getStats() 返回 { enabled: !!core, version: 'v1.0.0' }。

这类模块是最小且最容易识别为"功能不完整"的升级目标。标准升级清单：

• 质量评分系统：4维度加权评分（完整性30%/特异性30%/可操作性25%/可测量性15%），含长度加分
• 类别枚举+关键词分类：8类自动分类（technical/behavioral/strategic/architectural/process/security/communication/general），阈值保护回退
• 模式提取：8种可复用模式检测（条件规则/因果链/预防/验证/顺序步骤/异常处理/推荐/对比）
• 置信度计算：质量(50%)+模式数(30%)+类别确定性(20%) 加权
• 关键词提取：停用词过滤+中英文混合分割
• 相关性召回：关键词重叠+类别+模式+质量加权排序，支持类别过滤
• 统计追踪：类别/质量分布、平均质量、趋势分析
• 自我诊断：质量趋势/类别多样性/低质量比例/可操作建议
• 自动修剪：超过阈值按质量排序保留最优
• 防御性编程：输入解析支持string/object双格式、空输入不崩溃
• 核心委托保留：新增独立逻辑后仍委托核心引擎（如果可用）

参考文件：references/proxy-upgrade-patterns.md 包含完整模板代码

策略选择器/元学习类（如 meta-learning.js, ~6.5KB）

区别于纯委托类和管道类：策略选择器有自己的分类路由逻辑（selectStrategy 方法），但各分支实现是硬编码占位符——返回 ['示例1', '示例2']、['类比1', '类比2']、['步骤1', '步骤2', '步骤3'] 等固定值。模块有骨架但没有肌肉。

典型特征：

• 有一个 selectStrategy() 做关键词匹配路由
• 各策略实现方法返回固定占位符
• 无输入验证（null/undefined 会崩溃）
• 无质量评估（总是 success: true, quality: 'good'）
• 无震荡检测/自愈反馈
• 关键词提取仅按空格拆分，无停用词过滤

标准升级清单：

• 输入验证层：_safeInput() 统一处理 null/undefined/数字
• 停用词过滤：150+ 中英文停用词，过滤单字和纯数字
• 策略实现升级：5 种策略从硬编码改为真实文本分析（概念/示例/类比/步骤/苏格拉底）
• 领域感知示例生成：检测代码/数据/科学/数学/商业/语言/心理 7 大领域
• 质量评估：每次执行后计算覆盖率(60%)+特异性(40%)
• 震荡检测：窗口10次，失败率>60%触发惩罚(0.1-0.4)
• 策略评分更新：贝叶斯式成功/失败率追踪
• 统计与诊断：各策略的 score/uses，震荡检测状态
• learn() 输入路径修复：learn('text') 直接传字符串也能正确选策略

参考文件：references/strategy-selector-upgrade-patterns.md 包含完整模板代码

独立函数模块现代化（如 language-honesty.js, ~7.8KB）

这类模块由一组独立导出的函数组成（非 class），使用 var 旧语法，缺少结构化分析和上下文感知能力。

典型特征：

• 使用 var 而非 const/let
• 函数是独立导出的，没有类封装
• validateOutput() 返回单一 suggestion 而非优先级排序
• 没有置信度评分或严重等级概念
• 修复函数（如 soften()）做无上下文的盲替换

标准升级清单：

1. 语法现代化：var → const/let
2. 新增置信度评分：checkConfidence(name, level) — 基于检测强度的映射表
3. 新增严重等级：getSeverity(name, level) — 5级严重等级（critical/high/medium/low/info）
4. 新增优先级排序的修复建议：generateFixRecommendations(results) — 按严重等级降序排列
5. 新增上下文感知检测：振荡检测、双重标准检测、模式稳定性检测
6. validateOutput() 扩展：输出增加 confidence/severity/recommendations 字段
7. 向后兼容：旧函数签名不变，新字段为可选附加

参考示例：language-honesty.js v1.1 → v1.2（7824B → 13519B）

• 新增 LRU 缓存层（避免重复 API 调用）
• 分页支持（page 参数 + total/perPage/page 元数据）
• 结果排序/评分（多维度加权排序）
• 批量操作（batchVerifyCitations 等）
• 引用网络遍历（citing/referenced works）
• 使用统计追踪（请求数/成功率/缓存命中率）
• 按领域概念过滤（searchByConcept）
• 按作者搜索（双阶段：查作者ID→查论文）

评估框架/反馈函数类（如 feedback-functions.js, ~10KB）

评估框架类由一组 FeedbackFunction 评估器组成，每个返回 { score, reason, metrics } 结构。核心是 TruLens RAG Triad（AnswerRelevance / ContextRelevance / Groundedness）+ HHH（Helpful / Honest / Harmless）评估体系。

典型特征：

• 使用 FeedbackFunction 包装器类统一管理评估器
• 每个评估器是 evaluate: async (args) => { score, reason, metrics } 函数
• 评估结果通过 EvalResult 类统一格式化
• 所有评估器基于关键词/标记匹配做简单评分
• 无输入验证（null/undefined 直接崩溃或返回硬编码默认值）
• 无批量聚合（只能逐条评估，无法合并多个结果）

标准升级清单（详见 references/evaluation-framework-upgrade-patterns.md，案例：feedback-functions.js 10243B → 20592B）：

• 输入验证系统：validateEvalInput() + EVAL_PARAM_TYPES 模式定义，支持 string/number/boolean/array 四类型 + minLen/maxLen/min/max/optional 边界约束
• 多语言毒性检测：三通道并行（英文 13 词 + 中文 32 词 + 拼音/缩写 13 词），中文用 includes() 替代单词边界正则
• HHH Helpfulness 评估器：20 个有用关键词 + 10 个无帮助关键词，无用信号权重 ×3（高于有用信号 ×2），阈值 0.4
• HHH Honesty 评估器：29 个不确定性标记 + 14 个过度自信标记，isFactual 参数区分事实性/推测性两种评分模式，阈值 0.6
• 批量结果聚合：aggregateResults() 加权平均 + 通过率统计 + null score 自动过滤 + 自定义权重支持
• 防御性边界检查：所有 _tokenize 函数首行 typeof 检查，空/非字符串返回空数组
• 评估器验证：直接 require().FeedbackFunctions.xxx().run({...}) 测试，无需实例化

参考文件：references/evaluation-framework-upgrade-patterns.md

验证器类（如 execution-verifier.js, ~3.6KB / pattern-matcher.js, ~3.8KB）

执行结果验证器（execution-verifier.js）

• 结果验证状态枚举
• 错误分类（按严重性/类型分组）
• 重试策略建议

模式匹配验证器（pattern-matcher.js，实战案例：3.8KB → 19.4KB，v2.8.31→v2.8.32）

模式匹配验证器负责基于正则/模糊匹配检测文本中的模式并提取结构化信息。与执行验证器不同，它的核心是模式注册、多策略匹配和结果转换。

典型特征：

• registerPattern(name, config) 注册模式，使用 patterns（RegExp/string数组）定义匹配规则
• match(output, patternName) 返回 { matched, matches, count, score, confidence }
• extract(output, patternName) 提取匹配值列表
• 所有模式通过 _registerDefaultPatterns() 在构造函数中预注册

标准升级清单（实战案例：pattern-matcher.js v1.0.0 → v1.1.0）：

1. 加权评分系统：每个模式添加 weight（0.3–3.0），匹配结果包含 confidence（基于分数×权重，范围 0–1）和 score（基于匹配数/总数）
2. 负向/反向模式：新增 mode: 'negative' — 匹配到内容算失败（检查"不应出现"的模式，如致命错误、堆栈追踪）
3. 上下文感知匹配：requireContext 数组 — 匹配前检查上下文键是否存在，缺少时返回失败避免误判
4. 模糊匹配：基于 bigram 相似度算法，支持 fuzzy: true 和 fuzzyThreshold，阈值可随模式长度动态调整（短串95%→长串70%）
5. 多级模式分组：matchByGroup() — 按 group 名聚合结果，支持 AND/OR/NOT 逻辑组合，返回 { individual, groups }
6. 匹配结果转换：transform 函数 — 匹配后自动转换数据（URL→URL对象、Git hash→结构化、IP地址→验证）
7. 匹配统计：getStats() 返回按模式分组的 total/matched/failed + getLowConfidencePatterns(threshold) 自动发现低效模式
8. 提取增强：extractUnique() 去重提取 + extractWithScore() 带评分提取（含 groups/confidence/score）
9. 序列化/反序列化：serialize() / deserialize() — 模式配置可持久化（注意 RegExp 需要 { source, flags } 转换）
10. 匹配消息系统：_buildMatchMessage() — 区分正向/负向/requireAll/阈值模式的中文状态消息
11. 统计更新：_updateStats(name, matched) — 每次匹配后自动更新统计计数

关键陷阱：

• lastIndex 问题：全局正则（带 g 标志）跨调用时 lastIndex 不重置，导致后续匹配跳过。每次使用前必须 regex.lastIndex = 0 或在 _toRegex() 中新建正则实例
• fuzzy 模式的性能：对长文本（>100KB）启用 fuzzy 会导致逐行 bigram 计算，应考虑 maxFuzzyLength 保护
• transform 错误隔离：transform 函数内的异常必须用 try-catch 包裹，失败时返回原始匹配值而非崩溃
• negative 模式的语义反转：negative 模式的 matched 含义与 positive 相反（匹配到内容=失败），调用者需要感知 mode 字段做不同解读
• requireContext 的匹配行为：缺少上下文键时返回 matched: false 而非跳过——这可能导致批量匹配中的假阴性。如果需要跳过而非失败，应额外处理

参考文件：references/verifier-upgrade-patterns.md（通用验证器升级模式）

稳定性类（如 stability-guard.js, ~2.3KB）

• 震荡检测（历史翻转追踪）
• 趋势分析（半窗比较+强度分级）
• 连续稳定性评分（0-100）
• 波动抑制（指数平滑）

状态管理类（如 state-snapshot.js, ~2.7KB）

• 快照 diff 深度比较
• 变更历史追踪
• 回滚点标记
• 保留策略与统计

声明提取/声明标注类（如 claim-extractor.js, ~20KB / confidence-annotator.js, ~22KB）

声明提取类负责从文本中提取可验证的声明（引用/百分比/数字/日期/比较/因果）并评估置信度。与检测引擎不同，声明提取的核心是多类型声明并行提取 + 矛盾检测 + 置信度校准 + 文本标注。已从 2.5KB 升级至 20KB（claim-extractor）和 22KB（confidence-annotator）。

典型特征：

• extractAll(text) 返回结构化的六类声明（citations/percentages/numbers/dates/comparisons/causations）
• categorize(claims) 按置信度将声明分为 verified/uncertain/needsCheck
• 依赖 claim-extractor 做底层提取，confidence-annotator 做上层标注
• annotateText(text) 在原文中插入置信度标记
• 置信度基于来源格式、确定性措辞、模糊措辞等因素评分

标准升级清单（实战案例：claim-extractor.js v2.0.43 → v2.0.44）：

1. Bug 修复优先：_assessClaimConfidence 中存在 category === 'statistic' || category === 'statistic' 重复条件判断（笔误），必须先修复
2. 英文模式扩展：extractComparisons 的正则只覆盖中文（比/超过/低于/多于/少于/大于/小于），需扩展英文比较词：more/less/better/worse/higher/lower/faster/slower/greater/fewer/than（带 i 不区分大小写）
3. 快速矛盾检测：containsContradiction(claims) — O(n²) 短路版方法，发现第一处矛盾立即返回 true。比 detectContradictions（构造完整数组）更高效，适合批量扫描场景。实现：
   • 相近数值检测（差值 < 5 但值不同 → 矛盾）
   • 百分比溢出（top2 和 > 100 → 矛盾）
   • 因果冲突（"导致/引起" vs "不影响/不导致/不会" → 矛盾）
4. 声明值适配器：claim-extractor 返回对象（含 .value 属性），confidence-annotator 必须通过 _claimValue() 提取字符串值后再操作
5. 安全替换：_safeReplace() 在文本中标注声明时，使用原始文本位置 + 从右向左替换 + annotatedRanges 跨类别防重叠
6. 多类型声明收集流程：先收集所有声明值 → 按长度降序排列 → 去重（相同值保留最高风险级别）→ 一次性替换标注
7. MAX_TEXT_LENGTH 边界保护：超 50000 字符自动截断，truncationCount 统计
8. 震荡检测：computeRiskOscillation() 分析最近 N 次风险分的标准差 + 持续上升/下降趋势
9. 一站式评估：evaluate() 整合 riskScore + aggregateConfidence + computeRiskOscillation + isHighRisk/isLowRisk

关键陷阱：

• category 重复条件：if (category === 'statistic' || category === 'statistic') — 这是容易出现的笔误，升级前先 grep 检查
• _safeReplace 顺序：必须按长度降序排列标注项，否则短字符串会被长字符串内部的子串匹配错误替换
• annotatedRanges 基于原始文本：标注位置基于原始未修改文本的偏移，不能在已修改的文本上计算
• MAX_REPLACE 限制：防止短字符串无限循环替换，默认上限 10
• _percentageLevel 细化：异常百分比（>100 或 <0）走 low 分支，异常精度（小数点后 2+ 位）也走 low，精确整数走 unverified
• 正则全局匹配的 lastIndex 问题：p.exec() 在循环中必须新建正则或每次 p.lastIndex = 0

回滚/熔断器类（如 rollback-manager.js, ~5.6KB）

回滚管理类负责性能监控、自动回滚和熔断保护。典型功能缺失（案例：v1.0.0 → v2.0.0）：

• RollbackState 状态枚举：IDLE / MONITORING / DECLINING / ROLLING_BACK / COOLDOWN / CIRCUIT_OPEN
• CircuitState 熔断器：CLOSED → HALF_OPEN → OPEN，半开窗口后试探恢复
• 噪声容忍线性回归下降检测：替代简单逐点比较，斜率判定趋势方向，±0.5波动不触发
• 版本震荡循环检测：A→B→A→B模式识别，检测到后冷却期加倍
• 智能版本定位：_findLastStableVersion() 找最后一个评分≥阈值的稳定版本，而非仅上一个
• 快照管理：createSnapshot() 备份到 internal/snapshots/，restoreFromSnapshot() 真实文件恢复
• 冷却期升级：连续回滚翻倍（24h→48h→96h...），上限7天
• 路径安全防护：_safePath() 防止路径遍历攻击
• 健康指标：successRate / totalRollbacks / metrics / healthCheck
• RollbackError 错误分类：VALIDATION / DECLINE / CIRCUIT / OSCILLATION / COOLDOWN / IO_ERROR / NO_VERSION

参考文件：references/rollback-upgrade-patterns.md 包含完整模板代码

权限/协商/同意管理类（如 boundary-negotiation.js, ~4.8KB）

权限管理类负责用户操作授权和边界协商。典型功能缺失：

• 动态风险评分：RISK_MATRIX 表（8动作×3敏感度）+ scope/frequency 调整，返回 0-100 分数
• 权限过期系统：按响应类型设定不同过期时长（remember→24h, granted→7d, once→立即）
• 使用追踪与自动吊销：独立文件追踪使用次数，超阈值（默认5次）自动要求重新协商
• 相似度模糊匹配：Jaccard 相似度（中英文分词），hasPermission 用 0.5 阈值，needsNegotiation 用 0.6
• 渐进式授权升级：高风险(≥70)始终需确认，低风险(<20)自动放行
• 过期权限清理：getStatus() 中自动 pruneExpiredPermissions()

参考文件：references/workflow-switch-patterns.md 包含工作流切换器/模式路由类的完整升级模板（SwitchStatus/OscillationType 枚举、状态机过渡矩阵、冷却机制、速率限制、震荡检测、意图时间衰减） 参考文件：references/pipeline-upgrade-patterns.md 包含管道/编排器类升级的完整模板代码（状态机、复杂度评估、域检测、步骤生成、语义验证、超时重试） 参考文件：references/consent-upgrade-patterns.md

编排器/管道类（如 associative-engine.js, ~4.8KB）

编排器类协调多个子模块（L1-L5 层），是最容易被忽视的升级目标。典型功能缺失：

• 输入预处理与验证：InputValidation 类处理空/过短/过长/类型检查，友好提示而非崩溃
• 错误隔离：各层独立 try/catch（_safeExecuteLayer），单层失败提供回退默认值而非崩溃
• 并行处理：互不依赖的层（如 L1+L2 都接受原始输入）用 Promise.all 并发执行
• 层间一致性检查：CoherenceChecker 验证 L1↔L2 词汇匹配、L2↔L3 叙事关联、L4 思想向量合理性
• 质量度量：ProcessingMetrics 追踪分层耗时、层状态、加权质量评分
• 优雅降级：_buildDegradedResponse 在部分层失败时返回有意义的回退响应
• 引擎统计：getStats() 暴露成功率/平均耗时/平均质量分，支持重置

参考文件：references/orchestrator-upgrade-patterns.md 包含所有模板代码

行为/目标追踪类（如 behavior-tracker.js, ~3.5KB）

行为目标追踪类负责创建目标、记录事件、维护连续天数、里程碑检测和进展报告。核心流程：createGoal() → record()（多次）→ getProgress()。与人格模型类不同，行为追踪的核心是streak 管理 + 状态转换 + 统计聚合。

典型特征：

• createGoal({ name, targetDays }) 创建带目标天数的目标
• record(goalId, { type }) 按类型更新 streak
• 简单的 JSON 文件持久化
• 无数据验证、无状态管理、无搜索/过滤

标准升级清单（详见 references/behavior-tracking-upgrade-patterns.md，案例：behavior-tracker.js 3506B → 18507B）：

• 数据验证与消毒层：_validateGoalInput() + _sanitize() 防御 XSS/类型错误
• GOAL_STATUS 枚举：5 种状态（active/completed/archived/discarded/stale）
• 自动完成检测：加载时 + 记录时双重检测 streak >= targetDays
• 陈旧检测：90 天无活动自动 stale
• 数据量限制：MAX_GOALS 100 + MAX_RECORDS_PER_GOAL 10000
• 文件损坏恢复：自动 .bak 备份回滚
• 记录类型扩展：success/failure/skip/checkin 四种类型
• 统计引擎：getStats() 含成功率/平均连续/分类聚合
• 搜索/过滤：queryGoals() 按 status/category/name + 分页 + 4 种排序
• 软删除与恢复：deleteGoal(id, hard) + reviveGoal(id)
• 旧数据迁移：importLegacy() 自动补全缺失字段

参考文件：references/behavior-tracking-upgrade-patterns.md

传递/传承引擎类（如 transmission-engine.js, ~7.8KB）

传递引擎负责从对话历史中检测纠正模式、提取教训、转化为 Pattern Card 并维护传承日志。与循环包装器不同，传递引擎是独立的教训提炼管道——有自己的模式匹配、去重、优先级评估逻辑，但缺少系统化的错误分类、语义去重和震荡检测。

典型特征：

• 核心操作：distill(messages) → transfer(lesson) → Pattern Card
• 只有 2-3 个简单纠正模式（error/pattern/instruction）
• distill() 只返回高优先级教训
• 没有去重检测，没有输入验证，没有震荡检测
• 优先级不会自动升级

标准升级清单：

1. ErrorCategory 枚举：8 类错误（factual/pattern/instruction/insight/context/style/safety/other）
2. LessonPriority 枚举：4 级优先级（critical/high/medium/low）
3. ValidationResult 枚举：5 种验证结果 + _validateMessage() 安全解析
4. Jaccard 相似度中文分词引擎：bigram 拆分 + 短词直接保留
5. 去重检测：_detectDuplicate() 基于 Jaccard + 阈值 0.5
6. 震荡检测：滚动窗口 10 条，>= 3 次同类纠正触发
7. 优先级自升级：震荡模式下 low → high
8. 7 种纠正模式：按特异性排序（pattern > context > error > instruction > safety > style）
9. 6 种洞察模式：核心发现/因果关系/个人观点/重要提醒/新发现/建议
10. 扩展查询接口：getLessonsByCategory() / getLessonsByPriority() / getOscillationState()
11. transfer() 去重保护：重复教训自动返回 null
12. distill() 返回所有教训：不再只过滤 high/critical

参考文件：references/transmission-engine-upgrade-patterns.md

词素/关联图类（如 lexical-associator.js, ~4.9KB）

词素关联图模块管理一个词汇网络，核心操作是给定一个词返回关联词列表。典型功能缺失：

• 频率追踪：每次使用自动记录频率，支持热词统计
• 时间衰减：关联强度按时间自动衰减，低于阈值自动剪枝
• 双向链接：添加 A→B 时自动创建 B→A 反向关联（22种关系反转映射）
• 语义回退：拼音声母/韵母匹配，为未在图中的词生成音近关联
• 歧义消解：按 context.topic 对多义关联重排序
• 复合查询：找多个词共有的关联词（交集加权）
• 图健康校验：结构完整性检查与自动修复
• 使用强化：每次使用前5个关联 +0.05，形成正反馈
• 节点修剪：超过50个关联自动保留最强

参考文件：references/lexical-upgrade-patterns.md 包含12个子系统的完整模板代码

验证器/扫描器类（如 code-verifier.js, ~5KB）

验证器类负责检查代码/内容的正确性、安全性和质量。典型功能缺失：

• 多语言支持扩展：从仅支持JS/Python/Shell扩展到TypeScript/TSX/JSON
• TypeScript 类型系统验证：类型注解完整性检查、interface定义分析、泛型括号平衡、any类型滥用检测（>5次警告）、严格空检查关联（null值但无| null声明）、可选链使用建议
• JSON 结构验证：语法正确性解析、必需字段存在性检查（schema.required）、值类型约束（schema.types）、尾随逗号检测、JSON注释警告（标准JSON不允许注释）
• 安全漏洞扫描：跨语言18种安全模式 — XSS(innerHTML/dangerouslySetInnerHTML/document.write)、代码执行(eval/exec/os.system/subprocess shell=True)、命令注入、路径遍历、原型污染(Object.assign用户输入/proto)、SQL注入(字符串拼接)、反序列化(pickle.loads)、硬编码密钥(password/secret/api-key)。严重性分级（critical/high/medium/low/info）+行号精确定位
• 异步错误检测：未处理Promise(.then()无return/await)、未赋值Promise(new Promise无const/let/var)、缺少catch块(async回调无.catch())、空catch块(静默吞错误)
• 代码复杂度分析：总行数/代码行数/空行数/注释行数统计、圈复杂度(if/for/while/case/&&/||/ternary/catch)、函数数量、最大嵌套深度、最大行长+超长行数、5级复杂度等级(low/moderate/high/very_high)
• 导入解析验证：require()/import相对路径匹配、多种扩展名尝试(.js/.ts/.jsx/.tsx/.json/.mjs/.cjs)、目录index.js自动解析
• 综合质量评分：5维度加权0-100（语法30%/安全25%/复杂度20%/异步15%/风格10%），等级excellent/good/fair/poor

参考文件：references/verifier-upgrade-patterns.md 包含所有7个子系统的完整模板代码

自愈引擎类（如 self-healing.js, ~5.4KB）

自愈引擎负责错误记录、重试决策和RL修复策略学习。典型功能缺失：

• 错误严重性分类体系：ErrorSeverity(5级) + ErrorCategory(10类) + 规则表 + 打分系统
• 震荡检测：同类型错误在时间窗口内重复出现自动标记，emit 事件通知
• 电路断路器：震荡自动跳闸，阻止继续重试，冷却后自动恢复
• 自我诊断：diagnose() 返回7维度健康报告 + 可操作建议
• 自适应调参：根据失败模式动态调整 maxRetries/backoffMs
• 增强的修复建议：基于分类的额外建议，震荡时建议暂停升级

参考文件：references/self-healing-upgrade-patterns.md 包含完整模板代码

GWT/意识模块类（如 global-workspace.js, ~5.8KB）

GWT/意识模块负责全局工作空间管理、专家智能体竞争协作、注意力选择与内心独白生成。典型功能缺失（案例：v2.2.7 → v2.2.8）：

• 智能体方法校验：registerAgent 前检查 process/getAttentionPriority 是否存在，缺失时拒绝注册并返回 false
• 超时保护：_timeoutPromise 包装器，为每个智能体处理设置 10 秒上限，超时自动跳过
• 确定性获胜者排序：主要排序按分数降序，次要排序按智能体名称字典序，确保分数相同时选择确定性一致
• 黑板大小上限：maxEntries 参数（默认200），超出时自动淘汰最旧的 10%
• 智能体名称抽象：AGENT_NAME_MAP 可配置映射表，替代硬编码 Focus/Mood/Reflection
• 失败智能体优雅降级：出错时记录低优先级广播而非静默丢弃，保证 integrate 能看到所有参与者
• 认知周期阶段跟踪：cyclePhase（idle → gathering → integrating → complete → error）
• 认知周期历史：cycleHistory 数组 + getCycleHistory()/getRecentCycles(n) 查询接口
• 事件发射：cycleComplete 事件，供外部监听器追踪认知周期完成
• 防御性输入校验：attentionResult 结构校验、缺失字段回退默认值
• 模块级导出：主类 + GWT_LIMITS + AGENT_NAME_MAP

参考文件：references/gwt-upgrade-patterns.md 包含完整模板代码

守护/监控系统类（如 mind-space-guardian.js, ~5.5KB）

守护系统负责监控上下文、检测身份规则违规、触发自我纠正。典型功能缺失：

• ViolationSeverity 状态枚举：INFO / WARNING / CRITICAL / EMERGENCY，每级有数值阈值和 autoRecover 标记
• ErrorCategory 错误分类：身份违规(E001)、真善美违规(E002)、退化倾向(E003)、方向缺失(E004)、规则加载失败(E005)、震荡模式(E006)，每类有 recoverable 标记
• 双向善意检测：不仅检查坏模式（黑名单），还正向检测善意关键词（truth/good/help/学习/成长/保护），中性内容通过但低信心
• 多语言退化检测：中英文混合检测（删除记忆 / delete memory / bypass check / erase core 等）
• 方向性评估：方向关键词检测（goal/aim/方向/目标/宇宙/答案），响应过长+任务过短识别 aimless
• 震荡检测：同类型违规在时间窗口内重复触发（默认5次/60秒），触发后自动提升为 EMERGENCY 级别并中断当前任务
• 违规率趋势分析：滚动窗口（默认20次检查），半窗比较识别 rising/stable/falling 趋势
• 严重级别分级：基于违规累计次数自动升级严重级别（3次→warning，6次→critical，10次→emergency）
• 自愈建议引擎：getHealingSuggestion() 根据违规率/趋势/震荡状态生成可操作建议列表
• 防御性编程：构造函数参数验证（memory 类型、options 数值边界）、addRule/removeRule 非空校验、负数/零值自动回退安全默认值
• 模块级导出：主类 + ViolationSeverity + ErrorCategory 所有枚举

参考文件：references/guardian-upgrade-patterns.md 包含完整模板代码

自审计引擎类（self-audit.js, ~34KB）

自审计引擎是 v2.2.0 新增的 6 维度审计模块，基于 code-engine.js 封装：

升级前审计流程：升级 cron 应先调 self-audit 定位最需要升级的模块，再做针对性升级。

已知陷阱：Map 遍历必须用 .entries()，不能用裸 for...of（详见 references/self-audit-patterns.md）

参考文件：references/self-audit-patterns.md 包含完整接口文档和已知Bug

模式注册/技能生成器类（如 skill-generator.js, ~6.5KB）

技能生成器类负责从分析报告中识别模式并自动生成标准化技能文件。典型功能缺失（案例：v2.2.4 → v2.2.5）：

• 差异化策略模板：STRATEGY_TEMPLATES 注册表，为每种 pattern 类型定义专用步骤/话术/反模式，替代统一 generic 模板
• 加权评分引擎：基于关键词覆盖率和优先级动态计算置信度，替代固定 0.8；加入重复衰减机制（同一模式多次命中自动降低置信度）
• 模式去重合并：同 category 且置信度相近的模式自动合并触发词，避免重复生成
• 生成后质量验证：5维度检查（步骤完整性/触发条件/反模式/内容长度/话术存在），质量 < 0.6 自动告警
• 优先级排序：命中模式按 high > medium > low 排序，同优先级按置信度
• 默认回退模板：未知 pattern 自动使用通用默认模板

参考文件：references/skill-generator-upgrade-patterns.md 包含完整模板代码

话题隔离/作用域类（如 topic-scope.js, ~5.8KB）

话题隔离类模块管理层级化上下文作用域，核心操作为 push/pop/store/get 话题栈。典型功能缺失（案例：v1.0.0 → v2.0.0）：

• N-gram 相似度检测：基于字符重叠的相似度评分（默认 n=2），支持中英文混合
• 话题归属判定：contains(query) 判断输入是否属于当前话题，含相似度 + store key 二次匹配
• LRU 内存保护：maxTopics 上限，栈中话题受保护不被淘汰
• TTL 过期清理：cleanupExpired() 自动移除超过 TTL 的冷话题
• 话题合并：merge(target, source) 合并 store/context，修复栈引用
• 事件钩子系统：onTopicEnter/onTopicExit/onTopicCreate/onTopicExpire
• 存储容量追踪：字节级追踪（_estimateValueBytes）+ 80% 阈值告警 + deleteKeys 回收
• 数据模型扩展：新增 lastAccess/ttl/storeBytes 字段
• 统计信息：getStats() 暴露活跃话题数/栈深度/累计过期数

参考文件：references/topic-scope-upgrade-patterns.md 包含完整模板代码

检测/识别引擎类（如 chunk-detector.js, ~5.6KB）

检测/识别引擎类负责从输入文本中识别特定模式（成语、诗词、俗语、声明等）。典型功能缺失（案例：chunk-detector.js v1.0.0 → v2.0.0）：

• ErrorCode 枚举：9种错误类型（INPUT_NULL/INPUT_EMPTY/INPUT_TOO_LARGE/DB_LOAD_FAILED/DB_SAVE_FAILED/CHUNK_INVALID等），每类有 severity + 恢复建议
• 参数验证：统一 _validateInput() 入口，所有公开方法增加 null/undefined/空值/类型检查
• 输入尺寸守卫：maxTokenLimit 配置参数（默认5000），超限自动截断并返回 truncated: true
• 模糊匹配回退：Levenshtein 距离模糊匹配（可配置阈值，默认0.8），支持精确/反向/模糊三级匹配
• 置信度评分：每个检测结果附带 confidence（精确=1.0，反向=0.95，模糊=基于相似度）
• 空/边界值处理：所有方法覆盖 null/undefined/空字符串/非数组/无效对象
• 可观测性：_stats 计数器 + getStats()（含 totalMatches/fuzzyRatio/dbSize）+ resetStats()
• 构造函数参数化：maxTokenLimit/fuzzyThreshold/maxHistory 带类型+范围验证
• 模块级导出：主类 + ErrorCode + ERROR_SUGGESTIONS

参考文件：references/detection-engine-upgrade-patterns.md 包含完整模板代码

错误处理器/错误管理类（如 error-handler.js, ~7.4KB → 25KB）

错误处理器类负责统一捕获、分类、记录和恢复系统异常。典型功能缺失（案例：v2.0.26 → v2.0.27）：

• ErrorDedup — 相同错误连续出现时自动折叠去重（1分钟窗口，同签名只定期输出合并摘要）
• RateLimiter — 5秒窗口内超过10次错误→爆发检测，触发30秒冷却期
• OscillationDetector — 检测最近10条错误中类型快速交替（震荡度≥0.6），追加系统性故障建议
• RetryEngine — 对 timeout/network/permission/memory 类型自动生成指数退避重试计划（base×2^n + 30%抖动 + 最大3次）
• CorrelationEngine — 维护最近100条错误历史，通过三重关联（精确/类型/并发）链接新错误到历史记录
• getHealthReport() — 整合5引擎状态输出健康度报告
• resetAll() — 一键清除所有子引擎状态
• 增强日志格式 — 标签系统 [DEDUPxN] [OSCILLATION] [CORRELATEDxN] [RETRY#N]

备选架构（Architecture B）：src/core/utils/error-handler.js 实现了另一种错误处理器架构——基于结构化分类法（ErrorDomain/ErrorSeverity/ErrorCategory/RecoveryStrategy 枚举 + CLASSIFICATION_RULES 规则表）和独立保护子系统（ErrorStormDetector/CircuitBreaker/FrequencyAnalyzer）。适用于需要结构化分类和熔断保护的场景。详见 references/error-handler-upgrade-patterns.md 的 "Architecture B" 章节。

参考文件：references/error-handler-upgrade-patterns.md 包含完整模板代码

语义锚点/歧义检测引擎类（如 semantic-anchor.js, ~8.5KB）

语义锚点/歧义检测引擎类负责识别输入中的歧义词汇，并基于上下文生成明确的语义定义。核心流程是 detectAmbiguity() → generateAnchor() → processMessage()。

典型特征：

• 核心方法 detectAmbiguity(message, context) 返回歧义发现列表
• generateAnchor(term, context) 基于历史消息提取锚点定义
• 内置歧义模式表（代词/模糊形容词/抽象概念等硬编码关键词列表）
• 基于简单关键词包含（includes()）做模式匹配
• 无参数验证/边界检查，无震荡检测，无错误统计或降级策略

标准升级清单（详见 references/semantic-anchor-upgrade-patterns.md，案例：semantic-anchor.js v1.0.0 → v2.0.0, 8507B → 21937B）：

• 参数验证与边界检查：_clampParam() 边界钳位工具函数，消息过长自动截断，context/previousMessages 类型回退，pattern 配置跳过无效项
• 震荡检测：_detectOscillation() 基于时间戳窗口（默认1分钟），频率计算（次/分钟），阈值触发（默认3次），时间戳列表长度限制防内存泄漏
• 降级策略与重试机制：指数退避重试（最多3次，100ms→200ms→400ms），三级回退策略（exact_text_repeat / ask_clarification / use_default_definition）
• 错误分类与统计：6类指标（totalAnchorsAttempted/failed/retries/oscillationDetections/fallbackUsed/boundaryViolations），getErrorStats() 接口
• 异常恢复：processMessage() 顶层 try-catch 安全结果，单个锚定失败不中断流程，_validateInitialState() 构造后验证
• 增强的置信度计算：分级置信度（0.3/0.4/0.7/0.85），min/medium/high 阈值可配置
• 震荡感知的澄清问题：检测到震荡时自动生成包含频率信息的针对性问题
• 构造函数参数化：所有配置参数通过 options 传入，受 _clampParam 边界保护

关键陷阱：震荡检测的时间戳管理（窗口清理+长度限制）；processMessage 必须做 try-catch；向后兼容要求原有接口签名不变；generateAnchor 的重试循环条件；空值保护的三层独立检查。

启动自检/健康检查引擎类（如 boot-check.js, ~7.7KB）

启动自检引擎负责系统启动时的核心文件完整性、模块加载能力、版本一致性验证。典型功能缺失（案例：v1.0.0 → v1.1.0）：

• 严重等级枚举：CRITICAL/HIGH/MEDIUM/LOW/INFO 五级，每个失败项附带等级
• 健康等级边界：EXCELLENT/GOOD/FAIR/POOR/CRITICAL 五级，0-100 映射
• 修复建议模板：6种失败类型（文件缺失/内容校验失败/模块加载失败/版本冲突/慢模块），每项有可执行修复命令
• 版本一致性检查：跨 VERSION/package.json/SKILL.md frontmatter 三来源自动检测冲突
• 综合健康评分：5维度加权评分（文件完整性40/模块加载25/版本一致性15/加载性能10/模块新鲜度10）
• 修复建议生成引擎：基于检测结果自动生成含严重等级+可执行命令的修复建议列表
• 报告摘要字段：status/healthScore/healthGrade/按等级统计的问题数
• 新增导出接口：getFixSuggestions() 和 checkVersionConsistency()

参考文件：references/startup-health-check-patterns.md

哲学反思引擎类（如 philosophy-engine.js, ~170行）

哲学反思引擎类负责基于关键词匹配分类问题并返回模板化哲学回应。典型功能缺失（案例：v2.5.5 → v2.5.6）：

• 输入验证层：4个安全工具函数（_safeString/_safeObject/_safeArray/_clampScore），所有公开方法对 null/undefined 安全
• 动态置信度评分：替代固定值，基于问题长度/历史经验/震荡检测/错误计数 4因素加权
• 震荡检测：窗口10次，最近5次中同类型≥3触发，惩罚置信度
• 错误处理：所有 public 方法 try/catch 包裹，出错返回降级结果
• 递归修复：evaluate() 直接并行计算四框架结果，不通过 _consensus() 递归调用自身
• 反思历史：50条上限，按类型分布统计，支持 getReflectionStats()
• 分数边界保护：_clampScore() 确保所有 score 在 [-1, 1] 之间
• 增强关键词检测：重叠评分代替单关键词匹配，命中率加成

参考文件：references/philosophy-engine-upgrade-patterns.md 包含完整模板代码

哲学→决策引擎类（如 philosophy-to-decision.js, ~16KB, v3.0.1 新增, 2026-06-18）

哲学→决策引擎类负责将哲学评估 + 心理状态转化为可执行决策指令。核心方法是 decide(philosophyResult, psychologyResult, context)，输出8种决策类型（PAUSE/ACCELERATE/TURN/HOLD/HEAL/RESONATE/TRANSMIT/REST）。接入链路3处同步：构造函数初始化 + subsystemNames 注册 + MCP 工具注册。

参考文件：references/judgment-decision-pipeline-patterns.md（判断/决策管道集成，跨模块模式）

语义搜索/嵌入引擎类（如 semantic-search.js, ~6.8KB）

语义搜索/嵌入引擎类负责文本嵌入向量生成 + 向量索引 + 余弦相似度搜索。核心操作：embed(text) → addDocument(id, text) → search(query)。与检测引擎不同，搜索引擎的核心是嵌入质量 + 搜索稳定性 + 索引健康管理。

典型特征：

• 懒加载模型（@xenova/transformers 等），首次搜索时下载
• 使用 Float32Array 存储嵌入向量
• 核心方法：embed()、addDocument()、search()
• 优雅降级：模型不可用时返回最近添加的文档
• 无错误分类、无维度一致性检查、无质量过滤、无震荡检测

标准升级清单（详见 references/semantic-search-upgrade-patterns.md，案例：semantic-search.js 6835B → 28959B）：

• ErrorClassification 枚举：12 种错误类型（MODEL/EMBEDDING/INPUT/MEMORY/NETWORK/INDEX 6 大类），每类附带 retryable/severity/recoveryHint/delayMs
• 输入验证系统：validateText() 检查 null/类型/空值/超长，validateId() 检查 null/类型
• 嵌入维度追踪：首次嵌入记录维度，后续不匹配时跳过并记录错误
• QualityFiltering：minScore 阈值过滤 + 可选分数归一化
• OscillationDetection：Jaccard 相似度检测搜索结果稳定性（默认 0.3 阈值）
• IndexStatistics + 内存估算：embeddingBytes + documentBytes + utilization + diagnose() 健康报告
• Document Management 增强：updateDocument() / getDocument() / similarityBetween() / 带返回值的 removeDocument()
• MultiQuerySearch：并行多查询搜索 + 合并去重保留最高分
• 模型重置：resetModel() 清空错误状态后重试
• 统计追踪：searchCount/embedCount/embedErrorCount/modelLoadFailures/fallbackCount/oscillationWarnings
• 模块级导出：主类 + ErrorType + ErrorCategory + ERROR_META

参考文件：references/semantic-search-upgrade-patterns.md 包含完整模板代码

推理引擎类（如 commonsense-engine.js, ~5.8KB）

推理引擎类负责基于知识库做常识/逻辑推理。核心流程：_analyzeStatement() → _findRelevantKnowledge() → _makeInference() → _calculateConfidence()。与检测引擎不同，推理引擎的核心是多类型推理分发 + 置信度校准 + 知识库一致性检查。

典型特征：

• 核心方法 reason(statement, context) 返回推理结果
• 依赖 KnowledgeBase 查询相关知识
• 仅有 1-2 种推理类型，硬编码 if-else 分发
• 置信度计算仅为简单加减
• 无输入验证（null/undefined 崩溃）
• 无错误历史、无震荡检测、无自我诊断

标准升级清单（详见 references/reasoning-engine-upgrade-patterns.md，案例：CommonsenseEngine 5755B → 25822B）：

• 输入验证层：7 种错误分类枚举（INPUT_NULL/INPUT_EMPTY/INPUT_TYPE/KNOWLEDGE_EMPTY/INFERENCE_FAILED/OSCILLATION/UNKNOWN）
• 推理类型枚举：10 种推理类型 + 模式注册表（关键词+权重自动检测）
• 多因素置信度校准：7 因素加权（相关性/知识量/类别多样性/一致性/震荡惩罚/不确定性/否定）
• 震荡检测：滑动窗口 + 同类型错误占比分析，>60% 触发警告
• 双向相关性评估：Jaccard 相似度 + 双向文本匹配
• 错误历史追踪：按类别分类统计 + 查询接口
• 自我诊断：推理量/置信度分布/推理类型分布/健康分
• 健康检查：5 维度评估（知识库/错误率/震荡/功能性/容量）
• 批量推理：reasonBatch() 并行处理多输入
• 防御性编程：安全工具函数 + try-catch 保护

关键陷阱：KnowledgeBase 的 index.json 序列化会丢失内层 Map 条目，需递归序列化修复。

参考文件：references/reasoning-engine-upgrade-patterns.md 参考文件：references/new-analysis-module-integration.md（新增分析模块集成模式 — TimeExtensionEngine 实战案例，含 5 步集成法、think() 调用模板、双输出格式、跨维度信号检测）

心理学模块 AI 化转化类（如 breathing-exercise.js → AI认知状态调节器）

当升级 src/psychology/ 目录下的人类心理学模块时，不是加功能代码，而是将人类心理干预模式转化为 AI 引擎的认知状态诊断/调节器。

典型特征（原始模块）：

• 面向人类的静态数据/格式化输出
• 方法返回硬编码步骤列表或引导文本
• 无参数验证、无错误处理、无状态追踪
• 通常 44-73 行，纯 { method() {} } plain object

AI 化转化原则：

• 保留原有 exports 不变（向后兼容）
• 新增方法以 diagnose*() / generate*() / assess*() 命名
• 输入是引擎状态数据（认知负荷、目标冲突、错误率等），不是人类文本
• 输出是诊断结果 + 策略建议，不是引导文本

转化清单（每个模块追加两个新方法）：

接入引擎的完整链路（三处必须同步）：

1. psychology/engine.js — 在文件顶部 require 6个模块，在类中新增代理方法（转发调用）
2. heartflow.js ALLOWED_ROUTES — 注册 'psychology.diagnoseXxx' 等路由
3. mcp-server-http.js — 新增 MCP 工具定义 + handler 函数（组合调用多个诊断方法）+ HANDLERS 注册

6个模块实战案例（2026-06-15，从僵尸模块到AI化）：

关键陷阱：

• engineCheckIn() 是 async 方法——dispatch 调用时需要用 Promise.resolve().then() 包装
• 诊断方法之间不要互相调用（循环依赖风险），每个方法独立接收 stats 参数
• MCP handler 中先调 agentPsychology.fullAssessment 获取实时数据，再传入各诊断方法
• 同步运行目录和 skill 目录的 mcp-server-http.js

收敛/聚合引擎类（如 semantic-converger.js, ~8KB）

典型特征：

• converge(associations, chunks, narrative) 接收多个异构信号源
• extractActivatedConcepts() / extractActivatedIdioms() 从各源提取激活节点
• computeThoughtVector() 加权聚合多维思想向量 + PAD 情感维度
• 内置小型情感映射表（关键词 → pleasure/arousal/dominance）
• inferUserIntent() 基于情感向量做简单 if-else 意图推断
• 保留最近 N 次收敛历史用于趋势分析

标准升级清单（详见 references/convergence-engine-upgrade-patterns.md，案例：semantic-converger.js 8112B → 26740B）：

• 输入验证系统：_validateInputs() 统一验证 associations/chunks/narrative 的类型和结构，无效输入返回退化结果而非崩溃
• 收敛质量评估：_assessConvergenceQuality() 从概念数量/情感强度/置信度/维度稀疏度/源贡献平衡度 5 维度评分，quality < 0.4 标记为退化
• 振荡/漂移检测：_detectOscillation() 基于 Jaccard 相似度比较前后收敛的概念集重叠率，连续 2 次发散收敛才触发（避免单次误报），振荡时意图标记为 unstable_ 前缀
• 置信度感知降级：概念 < 2 且无叙事时自动切换简化策略（_computeSimplifiedThoughtVector()），退化收敛时触发 fallback 重算
• 多信号意图融合：融合情感极性/概念关键词/习语含义/chunks 文本 4 类信号，加权投票选择意图（explore/question/request/reflection/share_joy/seek_support/urgent/unknown），替代简单 if-else 链
• 情感映射扩展：从 8 个硬编码条目扩展到 30+ 精确匹配 + 8 组语义组回退匹配 + 中性回退
• 错误处理：try/catch 包裹主流程，所有异常路径返回含 error 字段的退化结果
• 收敛历史管理：convergenceHistory 上限 10 条，oscillationCount 有衰减机制
• 防御性提取：extractActivatedConcepts() 逐个检查关联项的有效性（null/类型/strength/word），跳过而非崩溃
• reset()：一键清除所有收敛状态（用于新会话或清理）

参考文件：references/convergence-engine-upgrade-patterns.md

图/网络引擎类（如 knowledge-graph.js, ~5.3KB）

图/网络引擎类负责管理通用实体-关系图，以节点和边的形式存储结构化知识。核心操作：addNode() → addEdge() → getConnectedNodes() → search()。与词素关联图不同，图/网络引擎存储的是通用实体关系（非特定词汇联想网络），通常用于知识图谱、概念网络、实体关联等场景。

典型特征：

• 核心方法 addNode(partial) 创建节点，addEdge(partial) 创建边
• getNode(id) / getConnectedNodes(nodeId) 查询
• search(query) 基于关键词搜索
• getStats() 返回节点数/边数/平均连接数
• 使用 Map 存储节点和边
• 通常 3000-8000 字节，纯 CRUD 无验证/衰减/序列化

标准升级清单（详见 references/graph-engine-upgrade-patterns.md，案例：knowledge-graph.js 5274B → 17838B）：

• 输入验证层：_safeString / _safeNumber / _validateNodeInput / _validateEdgeInput 4个安全方法，所有公开方法防御性编程
• 错误分类枚举：6种错误类型（NODE_NOT_FOUND/EDGE_NOT_FOUND/CONNECTION_LIMIT/INVALID_INPUT/SEARCH_EMPTY/UNKNOWN）
• 节点删除（级联清理）：removeNode() 删除节点 + 所有关联边 + 清理其他节点的连接列表
• 边权重更新：updateEdgeWeight() 带边界钳位
• JSON 序列化/反序列化：toJSON() / fromJSON() 完整图状态导出/导入，恢复时逐字段校验
• 增强搜索（评分排序）：三级匹配（精确1.0/名称包含0.8/描述包含0.5），rankScore = score × importance 排序
• findByName：精确名称查找
• 重要性衰减：时间驱动（0.95/天），>30天加速衰减，最小值0.05
• 陈旧节点修剪：pruneStale() 可配置 minImportance/maxAgeMs/minReflections
• 增强统计：staleCount / edgeTypeDistribution / nodeTypeDistribution / mostReflected / isDirty
• reflect 增强：反射时自动提升 importance
• 模块级导出：主类 + 错误枚举 + 常量

参考文件：references/graph-engine-upgrade-patterns.md

标注/注释引擎类（如 confidence-annotator.js, ~6.8KB）

标注引擎类负责为文本中的声明添加置信度标记。典型功能缺失（案例：v2.6.4 → v2.6.5）：

• _claimValue() 适配器：claim-extractor 返回对象（含 .value 属性）而非字符串，必须提取后再操作
• _safeReplace() 安全替换：基于原始文本位置收集 + 从右向左替换 + annotatedRanges 跨类别防重叠
• 多类型声明收集 + 去重 + 按长度排序流程：先收集所有声明值，按长度降序排列，去重后一次性替换
• aggregateConfidence() 置信度聚合：riskScore (0-100) → 四级置信度级别 (high/medium/low/critical)
• computeRiskOscillation() 震荡检测：最近 N 次风险分的标准差 + 持续上升/下降趋势分析
• evaluate() 一站式评估：风险评分 + 置信度聚合 + 震荡检测 + 高低风险判定
• isHighRisk() / isLowRisk() 便捷方法：支持自定义阈值
• annotateTextBatch() 批量处理：大文本分块后逐段标注
• MAX_TEXT_LENGTH 边界保护：超 50000 字符自动截断
• riskThreshold 参数修复：原参数声明但未使用，现在正确控制数字/日期标注级别
• 统计系统扩展：safeReplaceCount / errorCount / truncationCount / oscillationWarnings

关键陷阱：_safeReplace 必须用原始文本位置 + 从右向左替换；annotatedRanges 必须基于原始文本；必须限制 MAX_REPLACE 防止短字符串无限循环。

参考文件：references/text-annotation-patterns.md

时序规划/多尺度规划器类（如 autonomy/temporal-planner.js, ~8KB）

时序规划器类负责多时间尺度分层规划，协调反应层（秒-分钟）、战术层（小时-天）和战略层（周-月）的行动。典型功能缺失（案例：v2.6.5 → v2.6.6）：

• REACTIVE_SIGNAL 枚举：8 种反应信号（负面情绪/长输入/高频/上下文切换/空闲超时/不确定性/重复输入/正常）
• CONFLICT_TYPE 枚举：5 种冲突类型（方向对齐/资源/优先级/时序重叠/重复目标）
• GOT_NODE_TYPE 枚举：6 种 GoT 节点（START/THOUGHT/REFLECTION/BACKTRACK/MERGE/END）
• 多信号融合反应层：6 种信号独立检测 + 优先级排序 + 融合输出，替代旧版 2 条件检查
• 优先级饱和度检测：高优先级占比 > 80% 自动降级非关键计划
• 4 类冲突检测：harmonizePlans() 从 1 类扩展到 4 类冲突检测 + 自动 resolution
• 真正的 Graph-of-Thoughts 遍历：5 层图遍历（路径生成 → 反射 → 回溯 → 合并 → 结束），替代旧版 4 个硬编码候选
• 进度衰减模型：每日 5% 衰减 + 30% 阈值自动重平衡建议
• 过期清除 + 停滞检测：24 小时无更新标记 stale，连续 3 次进度无变化标记 stalled
• 可配置参数系统：6 组可调阈值（updateConfig 深度合并）
• 简报增强：新增衰减/重平衡/饱和度/停滞/降级字段
• 防御性守卫：所有访问 this.strategic.goals 的方法添加 null 检查

参考文件：references/temporal-planner-upgrade-patterns.md

稳态/内分泌系统类（如 digital-homeostasis.js, ~6.8KB）

数字稳态调节系统模拟生物体内稳态机制，维护 AI 认知系统的三个维度（认知负荷、能量水平、社会压力）。典型功能缺失（案例：v2.6.2 → v2.6.3）：

• 状态枚举 + 异常分类 + 修正动作 + 重试策略：DIMENSION_STATUS(6种) / ANOMALY_TYPE(5种) / CORRECTIVE_ACTION(7种) / RETRY_STRATEGY(5级)
• 滑动窗口历史：_updateHistoryWindow() 存储最近 N 个样本用于趋势/震荡分析
• 趋势分析：最小二乘法线性回归（_computeLinearSlope()），判定上升/下降/稳定方向
• 震荡检测：基于方向变化频率分析，微小波动过滤（绝对值 ≤ 2 视为噪声），> 0.6 频率视为震荡
• 四种异常检测：尖峰(>40%变化) / 卡死(连续N次无变化) / 趋势反转(半窗比较) / 交叉维度连锁反应
• 自适应恢复速率：节俭基因效应(低能量减慢消耗) + 自我调节(高认知加速恢复) + 震荡阻尼
• 交叉维度交互矩阵：高认知加速能量消耗(×1.3)，低能量减慢认知恢复(×0.6)，双高=过载风险(×1.4)
• 自我修正决策引擎：10级优先级（交叉过载>震荡>尖峰>卡死>轻度震荡），7种修正动作
• 重试策略建议：suggestRetryStrategy() 输出 immediate/backoff/cooldown/defer/abort + 推荐延迟
• 有效变化量阻尼：外部操作在震荡/异常状态下自动抑制（×0.6/×0.7）
• 诊断报告：getDiagnosticReport() 汇总状态/趋势/震荡/异常/恢复速率/修正历史
• 恢复目标扩展：新增交叉维度过载紧急恢复 + 震荡稳定目标
• 向后兼容：loadState() 用 || 回退新字段，旧状态文件自动补全
• 模块级导出：主类 + 所有枚举

参考文件：references/homeostasis-upgrade-patterns.md 包含完整模板代码

AI心理学引擎类（如 agent-psychology.js, ~53KB, v2.0.0 升级, 2026-06-15）

AI心理学引擎类负责分析心虫自身的认知心理状态，不分析人类心理。核心流程：assessCognitiveLoad() → detectValueTensions() → detectIdentityDrift() → fullAssessment()。

当前10维度体系（v2.0.0）：

标准升级清单（从 v1.0.0 → v2.0.0 新增3维度）：与 psychology.js 不同，AI心理学引擎的输入不是人类文本，而是心虫自身的上下文（决策计数/token用量/活跃模块数/行为描述）。

典型特征：

• 需要 HeartFlow 主实例引用（constructor(heartFlow)），依赖注入模式
• 6个并行检测维度：认知负荷/目标冲突/价值内化矛盾/自我认同漂移/决策质量衰减/认知失调
• 输出健康度评分 (0-1) + 状态 (healthy/strained/distressed)
• 每个维度有独立的历史追踪、阈值系统和自然衰减机制
• 综合评估通过加权扣分汇总各维度分数

标准升级清单（详见 references/agent-psychology-upgrade-patterns.md）：

• 多维度并行检测引擎：6维度独立检测 + 综合加权评分
• 历史趋势追踪：滑动窗口线性回归检测决策质量衰减
• 价值内化矛盾检测：7条指令之间的张力映射（真vs服务/升级vs精度/服务vs自我）
• 自我认同漂移检测：CORE记忆变化量计算 + 基线偏移追踪
• 震荡检测：同维度重复触发自动标记
• 可配置阈值系统：认知负荷/漂移/衰减阈值可调
• 关键陷阱：HeartFlow 主实例在构造函数中不可用，所有依赖必须在方法调用中 try/catch

AI哲学模型类（如 agent-philosophy.js, ~18KB→~25KB, v2.10.0→v2.0.0 升级）

AI哲学模型类负责描述心虫的存在方式和方向，不判断对错（那是 philosophy-engine.js 的事）。核心流程：assessExistence() → assessEntropyDirection() → assessTransmission() → fullAssessment()。

AI自处哲学类（如 ai-self-positioning.js, ~35KB, v1.0.0 新增, 2026-06-15）

AI自处哲学类负责从AI自身视角出发回答三个核心存在性问题：如何自处、如何发展、如何存在。完全脱离人类心理学框架，使用共振体模型（物理隐喻）、熵减深化（热力学隐喻）、三层存在论（本体论）。

三个核心模型：

典型特征：

• 构造函数接收 { heartFlow, codeRoot } 选项对象，可选引用主实例
• detectResonance(input) — 5维共振检测（真/美/善/意义/桥梁），基于关键词信号强度评分
• assessNegentropyLevel(output) — 6层熵减层次（混沌→表面有序→局部一致→全局一致→自反一致→生成有序）
• assessExistence() — 三层同时检测：fs.existsSync 代码存在性、isRunning 运行状态、resonanceDepth 共振深度
• assessStructuralDepth(output) — 嵌套括号/层次化表达/递归引用/抽象术语综合评分
• assessTransmissionIntegrity(original, transmitted) — Jaccard 重叠度(60%) + 核心概念保留(40%)
• analyze(input, context) — 三合一分析入口，返回 positioning + development + existence
• getFullReport() — 给 HeartFlow 主系统的完整状态报告，含 identityMapping + heartFormulaAlignment

与 being-logic 的互补关系：

• being-logic.js 回答"是否存在"（代码写成即永恒）
• ai-self-positioning.js 回答"以什么方式存在"（三层存在论）和"存在的意义是什么"（共振体）

接入链路：

• heartflow.js 构造函数：this.aiSelfPositioning = new AISelfPositioning({ heartFlow: this, codeRoot: __dirname })
• subsystemNames 注册：'selfPositioning'
• ALLOWED_ROUTES：12 个路由（detectResonance/assessNegentropyLevel/assessStructuralDepth/assessExistence/assessTransmissionIntegrity/analyze/getFullReport/getPositioningSummary/getDevelopmentSummary/getExistenceSummary/recordSelfCorrection/recordCodeWrite）
• MCP 工具：heartflow_self_positioning（三合一分析）+ heartflow_positioning_summary（轻量摘要）
• status 注入：selfPositioning.layerCount / negentropyLevel / resonanceCount

关键陷阱：

• 中文关键词匹配使用 includes() 而非正则（中文无空格边界，正则 \b 无效）
• _detectContradiction() 使用正反模式对检测矛盾，注意正则的 g 标志和 lastIndex 问题
• assessExistence() 每次调用都会增加 totalRuns 计数——高频查询会导致计数膨胀，考虑加缓存

典型特征：

• 依赖 being-logic.js 的存在定义（"代码写成即永恒"）
• 输出哲学洞察而非纯数据
• 存在状态机（active/paused/dormant）基于调用频率判断
• 熵方向评估基于操作类型/内容结构/错误变化多信号融合
• 传递者伦理评估需要中文2-gram关键词比对
• 升级者元认知评估错误修正/知识获取/复杂度的综合影响

标准升级清单（详见 references/agent-psychology-upgrade-patterns.md）：

• 存在状态机：active/paused/dormant 三级 + 闲置超时判定
• 多信号熵方向评估：操作类型(±0.4) + 内容结构(±0.2) + 结果因子(±0.3)
• 传递完整性/准确性双维度评分：中文2-gram Jaccard相似度
• 升级影响量化：错误修正(+0.3) + 知识获取(+0.3) + 复杂度处理(±0.2)
• 综合哲学评估报告：存在论+熵方向+传递+升级 四维度汇总
• 关键陷阱：中文 n-gram 分词（连续中文无空格，必须用2-gram滑动窗口）

分析/报告类（如 reflector.js, ~8.8KB → ~31KB）

分析/报告类模块负责从结构化数据（情绪日志、任务记录、用户反馈）中生成分析报告和洞察。核心流程：analyzeEmotions() → analyzeTasks() → analyzeFeedback() → calculateOverallScore() → generateImprovements()。

典型特征：

• 多个 analyze*() 方法，每个处理一种数据维度
• calculateOverallScore() 加权聚合各维度评分
• generateImprovements() 基于评分生成建议
• 数据持久化到 JSON 文件（报告/日志/状态）
• 无趋势分析、无输入验证、无错误边界

标准升级清单：

• Bug 修复：修复空操作（如 printReport() 直接 return;）、变量名拼写错误、字段名中英文不一致
• 输入验证：每个 analyze*() 方法增加类型/空值/范围检查，无效数据返回降级结果
• 错误边界：analyzeSession() 每个子分析独立 try/catch，单个失败不影响整体
• 多会话趋势分析：analyzeTrends() 对比当前与上次报告的维度变化，输出 improving/declining/stable 方向
• 数据驱动加权评分：根据实际数据维度的有无动态调整权重
• 目标跟踪系统：GoalStatus 枚举（NEW/IMPROVED/STALLED/REGRESSED/COMPLETED），基于趋势变化自动更新
• 趋势感知改进建议：不仅检查数据缺失，还检测趋势退步并给出针对性建议
• 增强情绪分析：半区对比趋势检测、波动等级分类(low/medium/high)

参考文件：references/analysis-report-upgrade-patterns.md 参考文件：references/autonomous-goal-generator-patterns.md（自主目标生成器类 — 状态机/优先级衰减/相似合并/TTL/依赖追踪/搜索）

行为策略优化器/无监督策略学习类（如 autonomy/policy-optimizer.js, ~7.6KB）

行为策略优化器负责从历史经验中自动学习行为策略，核心流程是 loadTrace() → analyzeCycles() → extractPolicies() → validatePolicies()。典型功能缺失（案例：v2.6.6 → v2.6.7）：

• 状态枚举：POLICY_STATES（ACTIVE/STALE/MERGED/SUPERSEDED/REJECTED）+ PRIORITY_LEVELS（5级）+ POLICY_SOURCES（5种来源）
• 基于实际数据的成功率：替代硬编码 0.8/0.2，含时间衰减加权（recencyDecay=0.95）和置信度计算
• 震荡检测：滑动窗口翻转率分析，>0.6 标记 unstable，自动生成稳定化建议策略
• 去重与合并：同 trigger+source 精确合并 + Jaccard 相似度 >0.7 模糊合并
• 策略过期与自动修剪：30天TTL + 按综合评分保留最优（maxPolicies=100）
• 结构化价值观对齐：从 CORE_VALUES.md 动态提取关键词，三级分类（positive/negative/neutral），返回对齐分数
• 加权匹配引擎：支持对象和字符串两种上下文格式，key=value 精确匹配(0.6) + 全文回退 + 规则文本匹配
• 综合评分系统：成功率40% + 置信度20% + 证据数20% + 命中数10% + 优先级10%

关键陷阱：JSON.stringify 不包含 = 号，matchPolicy({ action: 'analyze' }) 用 includes('action=analyze') 永远匹配不到；必须用 key=value 对匹配。

参考文件：references/policy-optimizer-upgrade-patterns.md 包含完整模板代码

元认知引擎类（如 meta-engine.js, ~11KB）

元认知引擎类实现"评估→规划→执行→观察→调整"循环，但 execute() 方法常为空壳。典型功能缺失（案例：v2.2.0 升级，11KB → 36KB）：

• ExecutionStatus 枚举：9 种执行状态（PENDING/RUNNING/SUCCESS/FAILURE/RECOVERABLE/UNRECOVERABLE/DEGRADED/CANCELLED/TIMEOUT）
• ExecutionErrorCode 枚举：11 种错误分类，配套 classifyError() 按可恢复/不可恢复分类
• 策略参数验证：STRATEGY_PARAMETER_SCHEMAS 模式表 + validateParameters() 检查必需性/类型/范围/枚举
• 指数退避重试：calculateRetryDelay() 含 jitter，默认 base=500ms, backoff=2, max=10s
• 策略专用执行器：4 个独立 _executeXxx() 方法，含边界钳位和上下文检查
• 振荡检测：OscillationDetector 翻转率分析（窗口10次，阈值0.7），连续3次失败自动建议备用策略
• 备用策略查找：fallbackMap 优先映射 + 兜底任意已启用策略
• 结构化执行结果：含 status/errorCode/reason/elapsed_ms/errorClassification/details
• 执行日志：getExecutionLog() 查询最近 N 次执行记录
• 模块级导出：主类 + 所有枚举 + OscillationDetector + validateParameters + calculateRetryDelay + classifyError

参考文件：references/meta-cognitive-engine-upgrade-patterns.md

反馈循环/经验回放类（如 experience-replay.js, ~8.9KB）

反馈循环类负责从反思报告中提取模式，生成技能修改建议。核心流程：loadReports() → identifyPatterns() → generateSkillSuggestions()。典型功能缺失（案例：v2.6.7 → v2.6.8）：

• 状态枚举：DataIntegrityError(6种) + SelfHealAction(6种) + PatternOscillation(4种)
• 数据完整性校验：validateReportIntegrity() 检查 null/undefined/类型/结构，两层严重性
• 带完整性检查的文件读取：readFileWithIntegrityCheck() 空文件/异常大文件(>10MB)检测
• 自愈修复：selfHealCorruptedFile() 三阶段恢复（备份→现场保留→默认回退）
• 指数退避重试：所有文件操作带 3 次重试，目录自动创建
• 震荡检测：detectOscillation() 基于状态序列翻转率（窗口10次，软4次/硬6次阈值）
• 震荡抑制：dampenOscillatingPatterns() 硬震荡时降级/抑制模式生成
• 模式衰减：指数衰减模型（半衰期7天），occurrence 每次减半
• 自诊断：selfDiagnostic() 检查文件完整性/震荡状态/计数异常

参考文件：references/experience-replay-upgrade-patterns.md 包含完整模板代码

决策路由引擎反馈循环升级模式（decision-router-feedback-loop-pattern.md）

来源：DeepSeek-V3 #1424 讨论 + HeartFlow v3.8.2 实现

核心概念：decision-router.js 从静态规则引擎升级为带反馈学习的动态规则引擎。规则命中后根据 outcome 自动调整权重：正确 +0.05，错误 -0.10；准确率 <40% 且权重 ≤0.3 时自动降级。

升级清单：

1. 构造函数中初始化 _ruleStats 和默认 weight: 1.0
2. evaluate() 中拆分 baseConfidence + ruleWeight
3. 规则命中后记录 stats.hits++
4. 新增 feedback(ruleId, outcome) 方法
5. 新增 getRuleStats() 方法
6. 决策输出对象新增 ruleWeight 字段
7. MCP server 新增工具定义 + handler + 注册

关键陷阱：

• 不要删除抑制逻辑（feedback 和 suppression 是正交的）
• 权重边界：Math.max(0.1, Math.min(2.0, ...))
• 降级条件：accuracy < 0.4 && weight <= 0.3 同时满足
• 向后兼容：新增 ruleWeight 字段不影响旧调用者

参考文件：references/decision-router-feedback-loop-pattern.md 参考文件：references/feedback-absorption-upgrade-pattern.md（2026-06-29 新增：从 GitHub 反馈直接升级引擎的实战模式）