Agent Skills
返回列表
💻

HeartFlow 源码清理与死代码检测

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_fdb96f95/heartflow-source-cleanup。

技能介绍

要解决什么问题

大型 Node/HeartFlow 类代码库在反复「并发优化」后,表面能靠 try/catch 兜底启动,却常出现静默功能降级:整套 formula/ 被整目录删掉、self-healing-rl.js 从惰性链上消失,静态扫描还以为「无引用」。另一类问题是清理过猛留下的结构性残骸——只删了 _lazy() 定义却保留构造函数里的 _Xxx() 调用,或留下 // DELETED 旁的顶层 require(),MCP 一加载就级联崩溃。

本技能把清理工作约束在可验证的轨道上:死代码判定靠主入口 require 链追踪;高价值孤儿(有 class/function 导出)与真死代码(仅 wrapper/配置)分开处理;删除前必须做交叉验证,删除后必须做语法与加载实测。

技能如何工作

判定表是起点:被引用文件保留;未引用但有完整导出保留作未来模块;未引用且无导出归档;空目录删除;含大量维护性注释的极小文件不动。

配套思路与脚本角色包括:

  • scripts/find-orphans.py:递归追踪 require 链,输出孤儿文件清单
  • scripts/cleanup-empty-dirs.sh:清理无 JS 的空目录
  • scripts/merge-small-files.py:在合规前提下合并碎片文件

实战章节覆盖两类启动级故障的最小修复模板:

  1. 惰性双层加载(const _X = _lazy(...) + 构造内 _X()):定义与调用点必须同时处理
  2. 孤儿顶层 require:批量将失效 require 改为 null fallback,或在对应用 try/catch

与 heartflow-core-optimizer 分工明确:本技能负责找孤儿 + 验证 require 链;后者负责存活模块价值评估与批量归档。

适用边界与注意点

静态 require 链抓不到 _lazy()、函数体内 try/catch require、HF_DIR + '/src/...' 拼接路径和 globalThis 注入——删模块前必须 grep -rn 全库字符串搜索与链追踪并用。铁律是用户强制的 「宁愿冗余,也不要缺少」:清理优先归档而非不可逆删除;误删优先 git 恢复,禁止用 null/空对象糊弄仍在用的消费者。删除目录前要 ls 逐文件确认消费者;恢复后要 node --check 全库并通过 require 主入口验证,必要时配合 think() 与运行时告警 grep。另:产品 src/ 不得写入个人 API 厂商、密钥或本机路径;构造函数顶层裸调 getCognitiveBridge() 等在独立 require 时会崩,需 fallback 或延迟到已注入上下文。

使用场景

  • HeartFlow 大版本「删源文件」前,要用 require 链 + 全库 grep 确认 lazy/runtime 引用再决定是否归档
  • MCP 启动因 // DELETED 旁顶层 require 崩溃时,按技能模板批量改 null fallback 并做 node --check
  • 清理后功能悄悄变差,需要对照 _lazy() 调用点与 formula-bridge 等运行时路径排查误删
  • 例行仓库瘦身:用 find-orphans 出清单,把无导出孤儿移入 archive 而非直接 git 删除

适合人员

  • 维护 HeartFlow 分叉或 MCP 扩展的工程师,需要在不误删 formula/自愈模块前提下做源码瘦身
  • 负责 Node 单体拆模块的 Tech Lead,要区分「孤儿但可复用」与「真死 wrapper」并写进团队规范
  • 做过 v6.3.x 级联启动事故的事后修复者,要系统性扫 _lazy 与 DELETED require 残留
  • CI/发布同学在 push 前自查:产品代码无个人 API 路径,且删文件后主入口 require 实测通过