Agent Skills
返回列表
🤖

HeartFlow 模块升级工作流

AI Agent 更新于 2026.08.29

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

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

技能介绍

要解决什么问题

HeartFlow 这类多模块 Agent 代码库里,大量 src/ 下的 .js 模块仍是薄封装:硬编码返回值、缺少状态机、验证只做存在性检查、管道没有重试与超时。若要对某一个模块做实质性补强(通常需新增不少于约 50 行真实判断逻辑),同时保持接口向后兼容,就需要可重复的工程流程,而不是零散改几处。

本技能与 heartflow-static-injection-upgrade 分工明确:本技能面向单模块深度升级(分析 → 设计 → 重写 → 验证);批量给 100+ 模块注入统一基础设施骨架时,应换用静态注入技能,勿混用。

工作流如何运作

流程从读取 VERSION、按字节扫描 src/(含 core、evolution、memory、psychology 等)选型开始。选型前会用 grep 统计引用:无人引用可走破坏性 API 调整;被 3+ 模块引用则必须兼容包装(如 options.throw、Proxy)。

分析阶段对照同类模块的「标准能力」找缺口(例如规划器应生成步骤、验证器应有语义检查)。设计阶段为管道/编排器类补齐状态枚举与合法转换、多因素复杂度评估、动态步骤模板、语义验证、超时重试、取消令牌与指标追踪等。

交付后执行 node --check、require + new 实例化(不仅语法检查)、核心 process() 试跑,含状态机则需测状态转换;同步 bumpVersion('patch') 或手动改 VERSION/package.json/SKILL frontmatter,并在 模块索引表补行,最后 git commit 且提交前用 git status 排除历史残留改动。

边界与陷阱

文档内整理了构造函数初始化顺序、工具函数返回值语义变更、Plain Object → Class 的 Proxy 包装、ERROR_CLASSIFIERS 数组 patch 顺序、KnowledgeBase 序列化等陷阱。同概念多路径实现(如两个 topic-scope.js)升级前需先 find 确认副本,避免只改一半。

使用场景

  • HeartFlow 仓库里某个管道类只有透传调用、没有状态转换,需要按技能清单补状态机与重试后再发版
  • 选中 `src/core` 里体积最小但返回空步骤的规划器模块,要一次性补上步骤生成与语义验证逻辑
  • `atomic-write.js` 被 8 个模块引用,需在保持默认 throw 语义前提下增加结构化返回的可选行为
  • 单次升级完成后要在 SKILL.md 模块架构表里补一行注册,并 bump 版本且 commit,避免 VERSION 超前于 git

适合人员

  • 维护 HeartFlow 或多子目录 Agent 单体仓库、需要按 ROI 逐个加厚核心模块的 Node.js 维护者
  • 负责编排器/管道类(task-pipeline、workflow-switch)升级、又不敢破坏多文件 `require` 链路的集成工程师
  • 写过批量静态注入但发现单个模块仍缺业务判断逻辑、想走「扫描—分析—重写—验证」闭环的 Agent 框架贡献者
  • 升级共享工具函数前需要对照 grep 引用数与返回值语义、避免静默破坏调用方的代码审查者