Flow2Spec
ENGitHub

Flow2Spec 升级指南

当前更新策略（CLI 3.6.5 起）

CLI 对 Core 使用 caret 兼容范围（如 ^3.8.2），兼容 Core 更新可以独立发布。旧 CLI 的依赖声明不会被新 Core 改写，需先更新一次 CLI。

  • flow2spec update --core：保留当前 CLI 版本，刷新其兼容范围内的 Core，并验证实际加载版本。
  • flow2spec update --cli：更新 latest CLI，并刷新它兼容范围内的 Core；用于升级 CLI 或进入新的兼容范围。
  • 安装后的依赖不会自动变化；锁文件仍保留解析版本。更新模板后执行 flow2spec init <agents...>，再按 projectRev / pkgRev 判断知识库升级。

历史迁移案例（CLI 3.6.2 / Core 3.7.2 / Template 3.6.2）

本次版本核心能力：路由初筛 summary 召回锚。manifest-routing.json 的每条路由规则新增 summary 语义摘要（由 topic frontmatter 自动同步），大幅提升自然问法（如「原型放在哪」「流程图在哪个目录」）的知识库命中率；kb check 同步新增 summary 质量校验。

版本对照

维度案例版本说明
CLI（@double-coding/flow2spec）3.6.2历史发布版本；现行更新策略见上文
Core（@double-coding/flow2spec-core）3.7.2随 CLI 自动安装，无需单独操作
Template Version3.6.2模板含主题层变更（projectRev 3）
Qoder 插件3.7.2自行构建（npm run build:qoder-plugin），随 Core 版本号命名

新用户（首次接入）

方式一：CLI（Codex / Cursor / Claude / DSH）

npm install -g @double-coding/flow2spec
flow2spec init <codex|cursor|claude|dsh>   # 可多选，按提示回答

安装 CLI 会自动带上其依赖范围内的 Core，无需单独安装。init 完成后可使用随包知识库模板和 summary 初筛能力。

方式二：Qoder 插件（自行构建安装）

Qoder 插件市场为官方插件，Flow2Spec 插件需自行构建后本地安装：

  1. 克隆仓库并构建插件包：

    git clone https://github.com/double-coding-lab/Flow2Spec.git
cd Flow2Spec && npm install && npm run build:qoder-plugin
# 产出 output/flow2spec-3.7.2.zip

  2. 在 Qoder 插件管理中选择本地安装，导入该 zip；

  3. 首次在项目中使用时按提示执行 flow2spec init plugin（插件模式：仅初始化知识库与配置，不写任何客户端目录）。

初始化后按需对 agent 说「f2s-kb-build / f2s-kb-add」等开始沉淀知识库。

老用户（已有 .Knowledge 项目）

本次 Template 3.5.0 → 3.6.0 包含主题层变更（projectRev 2 → 3），因此不能只更新包，需要走一次知识库升级。分三步：

第 1 步：更新包

更新到最新 CLI 及其兼容 Core：

npm install -g @double-coding/flow2spec@latest
flow2spec version   # 确认 CLI 3.6.2 / Core 3.7.2

已在 3.6.2 及以上的后续升级，也可直接用 flow2spec update --cli（自带生效校验，检测到依赖树异常会自动重装修复）。

Qoder 插件用户：拉取最新代码重新构建插件包（npm run build:qoder-plugin，产出 output/flow2spec-3.7.2.zip），在 Qoder 插件管理中重新导入即可，无需操作 npm 全局包。

第 2 步：知识库升级（关键，交给 agent 做）

在项目会话中对 agent 说：

f2s-kb-upgrade

agent 会代跑完整流程，其中与本次版本直接相关的是：

  1. 代跑 flow2spec init 对齐路由清单与模板（增量落盘，不覆盖你已沉淀的业务知识）；
  2. kb build --fix-topics 为存量 topic 补齐 frontmatter 骨架；
  3. summary 补写（本版新增）：kb check --strict 会列出所有缺失 / 占位的 topic 摘要，agent 逐个阅读 topic 正文、按创作规范补写一句话语义摘要，再 kb build 同步进路由清单——这一步完成后，你的存量知识库才真正获得初筛召回增强；
  4. 回写 projectRev，输出升级摘要。

全程无需手动改任何 .Knowledge 文件。

第 3 步：验证

flow2spec version          # CLI 3.6.2 / Core 3.7.2 / Template 3.6.2
flow2spec kb check --strict   # 期望：knowledge check: ok，无 summary warning

再用一句自然问法试试路由（例如问「这个项目的原型 / 需求文档放在哪」），确认 agent 能命中对应 topic。

常见问题

Q：Core 更新需要 CLI 同时发版吗？ 兼容范围内不需要。CLI 3.6.5 起使用 caret 范围；已有用户运行 flow2spec update --core 获取兼容 Core，跨兼容范围则先更新支持它的 CLI。

Q：旧版跑 flow2spec update --core 显示「已更新」但 flow2spec version 版本没变？ CLI ≤ 3.6.1 的已知缺陷：那条命令把 Core 装到了全局顶级位置，CLI 实际加载的是包内嵌套副本。修复方式：重装一次 CLI（npm uninstall -g @double-coding/flow2spec && npm install -g @double-coding/flow2spec@latest）。现行更新命令刷新 CLI 的依赖树并校验实际生效版本，失败时返回错误。

Q：升级会覆盖我已经写好的知识库吗？ 不会。f2s-kb-upgrade 代跑的 init 是增量对齐，只更新模板承载的路由结构与规则；stock-docs / req-docs / topic 正文的业务内容不受影响。只有明确要求「覆盖重置」时才会带 --reset-knowledge。

Q：不跑 f2s-kb-upgrade，只更新包行不行？ 引擎能力（summary 同步、校验）会生效，但你的存量 topic 没有摘要，初筛命中率不会提升；且首次 kb check 会持续报占位 / 缺失 warning。建议升级包后尽快跑一次。

Q：我的项目还是很老的 V1 布局（无 .Knowledge/manifest-routing.json 分片结构）怎么办？ V1 自动迁移已随包移除。先用历史版本 @double-coding/flow2spec@3.4.x 完成一次性迁移（或手动迁入 .Knowledge 形态），再回到最新版本跑 f2s-kb-upgrade。

Q：对 agent 说 f2s-kb-upgrade，它回复「版本均为最新」就停了，什么都没做？ 这是旧版技能（Template ≤ 3.6.0）的已知误判：它只比对了「本机包 vs npm」，没检查「项目知识库 vs 包模板」——刚升完包的老项目恰好命中。Template 3.6.1 起已修复（停止前强制项目侧对齐检查）。老项目首次升级时若遇到，说得更明确即可绕过：

f2s-kb-upgrade，强制走完整流程：先代跑 flow2spec init，再 kb build --fix-topics 和 kb check --strict，按 3a.8 补写 summary

Q：升级后 git 里 .cursor/、.codex/ 出现大量文件变化，正常吗？ 正常。这些是新模板的规则与技能正文真实更新（含已移除的 f2s-kb-migrate 整文件删除），不是空改动；可用 git diff -w 验证实质变更占比。升级只会动 .Knowledge/、各 agent 配置根（.cursor/ .codex/ 等）、AGENTS.md、flow2spec.config.json，不碰业务源码；建议把升级改动与业务改动分开提交。另外 manifest 的 version 是 Template Version（升级后为 3.6.2），不会等于 Core 版本号，属正常现象。

Q：升级后提交代码被 kb check 拦住报 routing drift？ 说明 manifest 与 topic 不同步（常见于手改过 manifest）。让 agent 跑一次 flow2spec kb build（幂等）即可自愈。