From 6d34f9cdc5200ef526993b4c5d358ed28d622aa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Mon, 24 Aug 2026 15:55:12 +0800 Subject: [PATCH 1/5] =?UTF-8?q?=E6=9C=AC=E5=9C=B0=E7=9F=A5=E8=AF=86?= =?UTF-8?q?=E5=BA=93=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/hooks/f2s-update-check.js | 8 +- .claude/rules/f2s-flow2spec-unified-entry.md | 8 +- .claude/rules/f2s-intent-routing.md | 1 - .claude/rules/f2s-topic-authoring.md | 2 +- .claude/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .claude/skills/f2s-kb-upgrade/SKILL.md | 37 +- .claude/skills/f2s-req-plan/SKILL.md | 12 +- .codex/hooks/f2s-update-check.js | 8 +- .codex/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .codex/skills/f2s-kb-upgrade/SKILL.md | 37 +- .codex/skills/f2s-req-plan/SKILL.md | 12 +- .codex/topics/f2s-flow2spec-unified-entry.md | 8 +- .codex/topics/f2s-intent-routing.md | 1 - .codex/topics/f2s-topic-authoring.md | 2 +- .cursor/hooks/f2s-update-check.js | 8 +- .cursor/rules/f2s-flow2spec-unified-entry.mdc | 8 +- .cursor/rules/f2s-intent-routing.mdc | 1 - .cursor/rules/f2s-topic-authoring.mdc | 2 +- .cursor/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .cursor/skills/f2s-kb-upgrade/SKILL.md | 37 +- .cursor/skills/f2s-req-plan/SKILL.md | 12 +- .../en-US/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .../zh-CN/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .../en-US/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ .../zh-CN/skills/f2s-kb-migrate/SKILL.md | 358 ------------------ 25 files changed, 102 insertions(+), 2608 deletions(-) delete mode 100644 .claude/skills/f2s-kb-migrate/SKILL.md delete mode 100644 .codex/skills/f2s-kb-migrate/SKILL.md delete mode 100644 .cursor/skills/f2s-kb-migrate/SKILL.md delete mode 100644 packages/core/templates/en-US/skills/f2s-kb-migrate/SKILL.md delete mode 100644 packages/core/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md delete mode 100644 templates/en-US/skills/f2s-kb-migrate/SKILL.md delete mode 100644 templates/zh-CN/skills/f2s-kb-migrate/SKILL.md diff --git a/.claude/hooks/f2s-update-check.js b/.claude/hooks/f2s-update-check.js index 2fac2c2..ad5436f 100644 --- a/.claude/hooks/f2s-update-check.js +++ b/.claude/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。 * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本： * - 一致或本地更新 → 静默退出 - * - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade） + * - 落后 → 向 Agent 上下文注入提示（agent 可直接代跑 flow2spec init；主题层变更再走 f2s-kb-upgrade） * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。 * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。 */ @@ -16,7 +16,7 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_DIR = path.join(process.cwd(), '.Knowledge'); const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; -const PACKAGE_NAME = '@double-coding/flow2spec'; +const PACKAGE_NAME = '@double-coding/flow2spec-core'; // ── 缓存 ──────────────────────────────────────────────────────────────────── @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。我可以直接代跑 flow2spec init 完成更新；若本次更新包含主题层变更，再走 f2s-kb-upgrade 完整流程。`; return [ `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] 转告后可直接替用户执行 \`flow2spec init <已初始化的 agents，如 claude cursor codex>\` 完成更新，无需用户手动执行 f2s-kb-upgrade。init 成功后读取 .Knowledge/manifest-routing.json：若 projectRev 与 pkgRev 相等（非主题版本更新），更新已完成，删除 .Knowledge/update-check.json；若两者不等（包含主题层变更），继续执行 f2s-kb-upgrade skill 完整流程（可从其步骤 2c 起，不必重复 init）。`, ].join('\n'); } diff --git a/.claude/rules/f2s-flow2spec-unified-entry.md b/.claude/rules/f2s-flow2spec-unified-entry.md index 2b76efb..c22960f 100644 --- a/.claude/rules/f2s-flow2spec-unified-entry.md +++ b/.claude/rules/f2s-flow2spec-unified-entry.md @@ -91,20 +91,20 @@ description: Flow2Spec 统一知识库入口，按 .Knowledge 渐进式读取 ## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时） -三端均在 SessionStart 注册版本检查脚本：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件同时注册配置摘要脚本 `node .codex/hooks/f2s-config-session.js` 与版本检查脚本 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`**，注册配置摘要、版本检查与 `PreToolUse Skill` 守门。版本检查脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。 +各已初始化客户端在支持时使用自身的启动 / 更新机制，具体以生成的客户端入口为准。不提供 hooks 的客户端继续通过生成的 rules、skills、`AGENTS.md` 或 topics 镜像工作。版本检查脚本在客户端支持时完成版本比对并注入升级提示；项目级技能发现客户端通过 `flow2spec init dsh` 使用 `.dsh/skills/` 与 `.dsh/topics/`。 **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.md`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.md`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/.claude/rules/f2s-intent-routing.md b/.claude/rules/f2s-intent-routing.md index 75d99d5..fa4e29e 100644 --- a/.claude/rules/f2s-intent-routing.md +++ b/.claude/rules/f2s-intent-routing.md @@ -38,7 +38,6 @@ description: 意图识别：高置信操作意图自动进入对应 f2s-* Skill | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/.claude/rules/f2s-topic-authoring.md b/.claude/rules/f2s-topic-authoring.md index 59f30be..49e4a21 100644 --- a/.claude/rules/f2s-topic-authoring.md +++ b/.claude/rules/f2s-topic-authoring.md @@ -14,7 +14,7 @@ description: Flow2Spec 主题创作准则：topic 命名 / 骨架 / topicMetadat - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 diff --git a/.claude/skills/f2s-kb-migrate/SKILL.md b/.claude/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/.claude/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/.claude/skills/f2s-kb-upgrade/SKILL.md b/.claude/skills/f2s-kb-upgrade/SKILL.md index 9b74ffc..8b94ed1 100644 --- a/.claude/skills/f2s-kb-upgrade/SKILL.md +++ b/.claude/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,18 +52,23 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 -**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？** -各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 + +**为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** +各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 ## 目标 @@ -73,7 +78,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V 1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。 2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。 -3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。 +3. 优先写入用户指定的 agent；未指定时使用包的默认客户端选择。 ## init 与技能自更新（必须） @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 diff --git a/.claude/skills/f2s-req-plan/SKILL.md b/.claude/skills/f2s-req-plan/SKILL.md index 1bc3577..0232fd5 100644 --- a/.claude/skills/f2s-req-plan/SKILL.md +++ b/.claude/skills/f2s-req-plan/SKILL.md @@ -18,13 +18,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 | **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 | | **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 | -**三端读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**： - -| 端 | 路径 | -| --- | --- | -| **Cursor** | 配置根 `rules/f2s-task.mdc`；或已 init 的 `.cursor/rules/f2s-task.mdc` | -| **Claude Code** | `.claude/rules/f2s-task.md` | -| **Codex** | `.codex/topics/f2s-task.md` | +**所有已为项目初始化的客户端都必须读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**。请从当前客户端生成的 rules、`AGENTS.md` 或 topics 入口读取，不得用本技能摘要代替全文。 ## 编排（主 / 子 agent） @@ -46,7 +40,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ### 步骤 0：前置（强制，任何步骤之前） 1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。 -2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 +2. **`Read` 当前客户端生成入口中的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。 ### 步骤 1：续作分诊 + 解析输入 @@ -140,7 +134,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ## 约束 -- **步骤 0**：必须先 `Read` `flow2spec.config.json` + **`f2s-task` 全文**（三端路径见上表） +- **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** - **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 - 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） - 步骤 2 必须主 agent；未确认禁止落盘 diff --git a/.codex/hooks/f2s-update-check.js b/.codex/hooks/f2s-update-check.js index 2fac2c2..ad5436f 100644 --- a/.codex/hooks/f2s-update-check.js +++ b/.codex/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。 * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本： * - 一致或本地更新 → 静默退出 - * - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade） + * - 落后 → 向 Agent 上下文注入提示（agent 可直接代跑 flow2spec init；主题层变更再走 f2s-kb-upgrade） * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。 * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。 */ @@ -16,7 +16,7 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_DIR = path.join(process.cwd(), '.Knowledge'); const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; -const PACKAGE_NAME = '@double-coding/flow2spec'; +const PACKAGE_NAME = '@double-coding/flow2spec-core'; // ── 缓存 ──────────────────────────────────────────────────────────────────── @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。我可以直接代跑 flow2spec init 完成更新；若本次更新包含主题层变更，再走 f2s-kb-upgrade 完整流程。`; return [ `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] 转告后可直接替用户执行 \`flow2spec init <已初始化的 agents，如 claude cursor codex>\` 完成更新，无需用户手动执行 f2s-kb-upgrade。init 成功后读取 .Knowledge/manifest-routing.json：若 projectRev 与 pkgRev 相等（非主题版本更新），更新已完成，删除 .Knowledge/update-check.json；若两者不等（包含主题层变更），继续执行 f2s-kb-upgrade skill 完整流程（可从其步骤 2c 起，不必重复 init）。`, ].join('\n'); } diff --git a/.codex/skills/f2s-kb-migrate/SKILL.md b/.codex/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/.codex/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/.codex/skills/f2s-kb-upgrade/SKILL.md b/.codex/skills/f2s-kb-upgrade/SKILL.md index 9b74ffc..8b94ed1 100644 --- a/.codex/skills/f2s-kb-upgrade/SKILL.md +++ b/.codex/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,18 +52,23 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 -**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？** -各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 + +**为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** +各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 ## 目标 @@ -73,7 +78,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V 1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。 2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。 -3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。 +3. 优先写入用户指定的 agent；未指定时使用包的默认客户端选择。 ## init 与技能自更新（必须） @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 diff --git a/.codex/skills/f2s-req-plan/SKILL.md b/.codex/skills/f2s-req-plan/SKILL.md index 1bc3577..0232fd5 100644 --- a/.codex/skills/f2s-req-plan/SKILL.md +++ b/.codex/skills/f2s-req-plan/SKILL.md @@ -18,13 +18,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 | **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 | | **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 | -**三端读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**： - -| 端 | 路径 | -| --- | --- | -| **Cursor** | 配置根 `rules/f2s-task.mdc`；或已 init 的 `.cursor/rules/f2s-task.mdc` | -| **Claude Code** | `.claude/rules/f2s-task.md` | -| **Codex** | `.codex/topics/f2s-task.md` | +**所有已为项目初始化的客户端都必须读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**。请从当前客户端生成的 rules、`AGENTS.md` 或 topics 入口读取，不得用本技能摘要代替全文。 ## 编排（主 / 子 agent） @@ -46,7 +40,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ### 步骤 0：前置（强制，任何步骤之前） 1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。 -2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 +2. **`Read` 当前客户端生成入口中的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。 ### 步骤 1：续作分诊 + 解析输入 @@ -140,7 +134,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ## 约束 -- **步骤 0**：必须先 `Read` `flow2spec.config.json` + **`f2s-task` 全文**（三端路径见上表） +- **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** - **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 - 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） - 步骤 2 必须主 agent；未确认禁止落盘 diff --git a/.codex/topics/f2s-flow2spec-unified-entry.md b/.codex/topics/f2s-flow2spec-unified-entry.md index 935a2ca..dd99d27 100644 --- a/.codex/topics/f2s-flow2spec-unified-entry.md +++ b/.codex/topics/f2s-flow2spec-unified-entry.md @@ -87,20 +87,20 @@ ## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时） -三端均在 SessionStart 注册版本检查脚本：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件同时注册配置摘要脚本 `node .codex/hooks/f2s-config-session.js` 与版本检查脚本 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`**，注册配置摘要、版本检查与 `PreToolUse Skill` 守门。版本检查脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。 +各已初始化客户端在支持时使用自身的启动 / 更新机制，具体以生成的客户端入口为准。不提供 hooks 的客户端继续通过生成的 rules、skills、`AGENTS.md` 或 topics 镜像工作。版本检查脚本在客户端支持时完成版本比对并注入升级提示；项目级技能发现客户端通过 `flow2spec init dsh` 使用 `.dsh/skills/` 与 `.dsh/topics/`。 **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/.codex/topics/f2s-intent-routing.md b/.codex/topics/f2s-intent-routing.md index c343435..345a6e7 100644 --- a/.codex/topics/f2s-intent-routing.md +++ b/.codex/topics/f2s-intent-routing.md @@ -34,7 +34,6 @@ | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/.codex/topics/f2s-topic-authoring.md b/.codex/topics/f2s-topic-authoring.md index 8aab8f6..665f88d 100644 --- a/.codex/topics/f2s-topic-authoring.md +++ b/.codex/topics/f2s-topic-authoring.md @@ -11,7 +11,7 @@ - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 diff --git a/.cursor/hooks/f2s-update-check.js b/.cursor/hooks/f2s-update-check.js index 2fac2c2..ad5436f 100644 --- a/.cursor/hooks/f2s-update-check.js +++ b/.cursor/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。 * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本： * - 一致或本地更新 → 静默退出 - * - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade） + * - 落后 → 向 Agent 上下文注入提示（agent 可直接代跑 flow2spec init；主题层变更再走 f2s-kb-upgrade） * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。 * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。 */ @@ -16,7 +16,7 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_DIR = path.join(process.cwd(), '.Knowledge'); const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; -const PACKAGE_NAME = '@double-coding/flow2spec'; +const PACKAGE_NAME = '@double-coding/flow2spec-core'; // ── 缓存 ──────────────────────────────────────────────────────────────────── @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。我可以直接代跑 flow2spec init 完成更新；若本次更新包含主题层变更，再走 f2s-kb-upgrade 完整流程。`; return [ `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] 转告后可直接替用户执行 \`flow2spec init <已初始化的 agents，如 claude cursor codex>\` 完成更新，无需用户手动执行 f2s-kb-upgrade。init 成功后读取 .Knowledge/manifest-routing.json：若 projectRev 与 pkgRev 相等（非主题版本更新），更新已完成，删除 .Knowledge/update-check.json；若两者不等（包含主题层变更），继续执行 f2s-kb-upgrade skill 完整流程（可从其步骤 2c 起，不必重复 init）。`, ].join('\n'); } diff --git a/.cursor/rules/f2s-flow2spec-unified-entry.mdc b/.cursor/rules/f2s-flow2spec-unified-entry.mdc index 799483f..f28b98a 100644 --- a/.cursor/rules/f2s-flow2spec-unified-entry.mdc +++ b/.cursor/rules/f2s-flow2spec-unified-entry.mdc @@ -92,20 +92,20 @@ alwaysApply: true ## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时） -三端均在 SessionStart 注册版本检查脚本：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件同时注册配置摘要脚本 `node .codex/hooks/f2s-config-session.js` 与版本检查脚本 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`**，注册配置摘要、版本检查与 `PreToolUse Skill` 守门。版本检查脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。 +各已初始化客户端在支持时使用自身的启动 / 更新机制，具体以生成的客户端入口为准。不提供 hooks 的客户端继续通过生成的 rules、skills、`AGENTS.md` 或 topics 镜像工作。版本检查脚本在客户端支持时完成版本比对并注入升级提示；项目级技能发现客户端通过 `flow2spec init dsh` 使用 `.dsh/skills/` 与 `.dsh/topics/`。 **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/.cursor/rules/f2s-intent-routing.mdc b/.cursor/rules/f2s-intent-routing.mdc index 869ef6a..7cb4fea 100644 --- a/.cursor/rules/f2s-intent-routing.mdc +++ b/.cursor/rules/f2s-intent-routing.mdc @@ -39,7 +39,6 @@ alwaysApply: true | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/.cursor/rules/f2s-topic-authoring.mdc b/.cursor/rules/f2s-topic-authoring.mdc index b2ac24b..e454ec9 100644 --- a/.cursor/rules/f2s-topic-authoring.mdc +++ b/.cursor/rules/f2s-topic-authoring.mdc @@ -15,7 +15,7 @@ alwaysApply: false - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 diff --git a/.cursor/skills/f2s-kb-migrate/SKILL.md b/.cursor/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/.cursor/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/.cursor/skills/f2s-kb-upgrade/SKILL.md b/.cursor/skills/f2s-kb-upgrade/SKILL.md index 9b74ffc..8b94ed1 100644 --- a/.cursor/skills/f2s-kb-upgrade/SKILL.md +++ b/.cursor/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,18 +52,23 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 -**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？** -各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 + +**为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** +各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 ## 目标 @@ -73,7 +78,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V 1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。 2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。 -3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。 +3. 优先写入用户指定的 agent；未指定时使用包的默认客户端选择。 ## init 与技能自更新（必须） @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 diff --git a/.cursor/skills/f2s-req-plan/SKILL.md b/.cursor/skills/f2s-req-plan/SKILL.md index 1bc3577..0232fd5 100644 --- a/.cursor/skills/f2s-req-plan/SKILL.md +++ b/.cursor/skills/f2s-req-plan/SKILL.md @@ -18,13 +18,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 | **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 | | **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 | -**三端读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**： - -| 端 | 路径 | -| --- | --- | -| **Cursor** | 配置根 `rules/f2s-task.mdc`；或已 init 的 `.cursor/rules/f2s-task.mdc` | -| **Claude Code** | `.claude/rules/f2s-task.md` | -| **Codex** | `.codex/topics/f2s-task.md` | +**所有已为项目初始化的客户端都必须读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**。请从当前客户端生成的 rules、`AGENTS.md` 或 topics 入口读取，不得用本技能摘要代替全文。 ## 编排（主 / 子 agent） @@ -46,7 +40,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ### 步骤 0：前置（强制，任何步骤之前） 1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。 -2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 +2. **`Read` 当前客户端生成入口中的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。 ### 步骤 1：续作分诊 + 解析输入 @@ -140,7 +134,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ## 约束 -- **步骤 0**：必须先 `Read` `flow2spec.config.json` + **`f2s-task` 全文**（三端路径见上表） +- **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** - **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 - 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） - 步骤 2 必须主 agent；未确认禁止落盘 diff --git a/packages/core/templates/en-US/skills/f2s-kb-migrate/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 209d827..0000000 --- a/packages/core/templates/en-US/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: Migrate a legacy knowledge base to `.Knowledge` in one pass: use the configuration-root `docs-index.md` plus the unified rule entry (legacy `rules/main.md(c)` or current package `rules/f2s-flow2spec-unified-entry.md(c)`) as primary index clues; fully process business `rules/` and business `skills/` (excluding `f2s-*` package skills), and fully migrate `stock-docs`/`req-docs`; **after migration acceptance, must write** `.Knowledge/migration-report.md` (migration mapping table + proposed deletion path list); **closing must delete** migrated legacy `rules/`, migrated business `skills/`, and legacy `docs-index.md`/`index-doc.md`; the user only **reviews/revises the deletion list (exclusions)**; triggers: f2s-kb-migrate、知识库迁移、旧版迁移、knowledge-base migration、legacy migration ---- - -> Execution scope: this is an `f2s-*` skill workflow, not a CLI subcommand. Migration targets include: -> 1) Structure layer: `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` -> 2) Document layer: `.Knowledge/stock-docs`, `.Knowledge/req-docs` -> -> **Hard boundary**: `skills/f2s-*` (under each agent configuration root) are Flow2Spec package skills / execution-layer capabilities. They **must not** be written into `.Knowledge` (including `topics/stock-docs/req-docs`) and must not be used as sources for "business skill migration". They also **must not** be deleted in this workflow (version alignment is handled by `flow2spec init` / package upgrade). -> -> **Baseline rule keep-list (must not delete)**: `rules/f2s-flow2spec-unified-entry.md(c)`, `rules/f2s-implement-tech-design.md(c)`, `rules/f2s-stock-docs-vs-req-docs.md(c)`. - -## Orchestration (main / sub-agent) - -- The meaning of `subAgent` / `switchAgentVerification` uses the unified entry as the only source of truth: **Cursor/Claude** read the configuration-root `rules/f2s-flow2spec-unified-entry.*`; **Codex** reads `.codex/topics/f2s-flow2spec-unified-entry.md` (same source, mirrored by `flow2spec init`). This section does not repeat those definitions. -- **Sub-agent responsibility** (only when `subAgent=true`): under the main agent's given inventory, perform moving work and generate **draft fragments** for `migration-report.md`; all outputs are submitted as patches and merged/written by the main agent. -- **Main agent must control**: - - `.Knowledge/.migrate-state.json` **write authority belongs to main** (state-machine source of truth; concurrent main/sub writes can misalign queues). - - The **"Deletion execution record"** section of `migration-report.md` is always appended by the main agent. - - **Deletion-list confirmation** and closed-loop cleanup must be completed by the main agent. -- **Write-authority hard rule**: `manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / the migration report "Deletion execution record" are always written by the main agent. -- By default, the writing side verifies its own work; this SKILL does not bind cross-agent verification. - -# f2s-kb-migrate (Legacy Knowledge Base -> New Knowledge Base) - -## Why this coexists with `f2s-kb-upgrade` - -| Skill | Problem solved | -| --- | --- | -| **This skill `f2s-kb-migrate`** | **One-time structural move**: legacy indexes (`docs-index.md` / `index-doc.md`), `rules/main.md(c)`, business `skills/`, scattered `stock-docs`/`req-docs` -> **`.Knowledge`**, plus deletion list and `migration-report.md`. | -| **`f2s-kb-upgrade`** | **Knowledge-base template upgrade skill (the only "upgrade" meaning)**: execute the full **`skills/f2s-kb-upgrade/SKILL.md`** workflow. It runs **`flow2spec init`** inside the process to align **`manifest-routing` + `matchers/`** and each agent's **`rules`/`skills`**. It includes **V1 / current repository (V2+)** branching (legacy projects must **migrate first, then run this skill**; **V2+ includes npm v3.x and other projects already using `.Knowledge`**, see `f2s-kb-upgrade` step 0). | - -- **After migration acceptance and deletion-list confirmation are complete**: remind the user to execute, or execute for them, the **full `f2s-kb-upgrade` skill** (whose **step 2** runs **`flow2spec init`**) to align the Flow2Spec package version, routing shards, and configuration-root artifacts to the current package. **Do not** let the user think that running `init` alone completes knowledge-base template upgrade. -- **Projects already stably using `.Knowledge` with no legacy-index burden**: do not run this skill again; daily package/template alignment uses **`f2s-kb-upgrade`** only (not just `init`). - -**Why does each agent directory have a same-named `SKILL.md`?** Each tool reads only its own configuration-root `skills/`; `flow2spec init` **syncs** the current-language skill content into the selected agent directories. - -## What This Command Does (External Wording) - -Move the legacy "scattered configuration-root document index + rules + business skills + stock/req document trees" **as a whole into the new `.Knowledge`**, then perform **legacy entry and legacy business-artifact cleanup**, cutting over from the old knowledge-base organization. - -Objects that must be covered: - -1. **Index entry**: business docs and rule clues declared/mapped in configuration-root `docs-index.md` (compatible with `index-doc.md`). -2. **Rule entry**: the rule set declared/referenced in `rules/main.md` / `rules/main.mdc` (common legacy form) or `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc` (compatible with historical `rules/flow2spec-unified-entry.md(c)`), plus other business rule files under `rules/`. -3. **Business skills**: business skill directories under each agent configuration-root `skills/`, excluding `f2s-*` (full inventory). -4. **Document trees**: legacy `stock-docs/`, `req-docs/` (or synonymous directories) fully migrated into the corresponding `.Knowledge` directories. - -For objects **not covered by the index**: - -- First output a candidate list (path + inferred reason: naming/directory/reference relationship). -- **By default, user confirmation is required** before including them in migration. Only when evidence is very strong (for example explicitly referenced by `rules/main` / `f2s-flow2spec-unified-entry`, or clearly referenced by an indexed document) may the Agent decide to include them, and the basis must be written in the migration summary. - -Cleanup after migration (mandatory closing; only when migration has no failures and no pending confirmations; **`skills/f2s-*` are never deleted**): - -- **Must execute**: delete migrated business rule files in legacy **`rules/`** (including `main.md(c)` if it is only a legacy entry), but **must not delete** the three `f2s-*` root rule files in the baseline keep-list. -- **Must execute**: delete migrated **business** subdirectories under legacy **`skills/`** (**excluding** `f2s-*`; if a directory still has unmigrated items, do not delete it until completed or removed from the list). -- **Must execute**: delete legacy entry **`docs-index.md`** (compatible with **`index-doc.md`**) to avoid dual entry points with `.Knowledge/index.md`. -- **Default optional deletion sub-list** (the user may exclude): legacy **`stock-docs/`** and **`req-docs/`** source directories, only when the corresponding document-layer migration has passed acceptance with no failures and no pending confirmations. - -**Meaning of user confirmation (important)**: - -- This is **not** asking "whether to clean up"; cleanup is part of the workflow. -- Instead, output the default-selected **"deletion path list"** (rule files one by one, business skill directories one by one, index filenames, and optional legacy document root directories) and ask the user to **review**. The user can only: - - Reply "**确认清单**" to delete according to the current list; or - - Reply "**排除：<路径…>**" to remove specified items from the list before deletion (removed items must be written to `.migrate-state.json` `notes[]` with reasons). -- If the user asks to **defer deleting a path**, keep that item in the list, end the cleanup round with `status=paused`, and **do not** pretend migration closure is complete. - -## Applicable Scenarios - -- The project still uses legacy knowledge organization (`docs-index.md` / `index-doc.md` + `rules/main.md(c)` or `rules/f2s-flow2spec-unified-entry.md(c)` (compatible with old `flow2spec-unified-entry.md(c)`) + business `skills/` + scattered `stock-docs`/`req-docs`). -- The user wants to migrate to the new `.Knowledge` format and confirm topic by topic to avoid one-shot large changes. -- The user needs **all req-docs / stock-docs** migrated into `.Knowledge` and wants to cut over from legacy knowledge-base directories/wording (paths, index, topic text unified to the new architecture). - -## Input - -- Optional inputs: - - Legacy unified rule entry path: `rules/main.md` / `rules/main.mdc` and/or `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc` (compatible with old `rules/flow2spec-unified-entry.md(c)`) - - Legacy `index-doc.md` (or `docs-index.md`) path - - Legacy stock document directory (for example `stock-docs/`, `docs/stock/`) - - Legacy requirement document directory (for example `req-docs/`, `docs/req/`) - - Migration scope (all topics / specified topics) -- If not provided, locate the above files in the repository first and ask the user to confirm. - -## Resumable Migration State File (Required) - -- State file path: `.Knowledge/.migrate-state.json` -- Purpose: record migration progress and support recovery after session interruption without migrating completed items again. -- Initialization timing: create immediately after the user confirms "start migration". -- Ending timing: - - All migration complete and user confirms completion: delete the state file. - - User actively says "stop": keep the state file for later recovery. -- `.migrate-state.json` is written only by the main agent; sub-agents submit patch fragments for the main agent to merge (write-authority hard rule). - -Recommended fields (minimal set): - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -Update rules (required): - -1. After completing each topic, business skill directory, business rule file, or document file, immediately write the state-file update. -2. When receiving "重试 ", roll back that item's state before retrying. -3. When receiving "继续", read the state file first and continue from unfinished queues. -4. When receiving "停止", write `status=paused` and end this round. -5. When receiving a resume request, first show a state summary (current stage, remaining counts, failed/pending items) and wait for user confirmation to continue. - -## Mandatory Flow (Phased Execution) - -### Step 1: Read Legacy Mappings - -1. Read `docs-index.md` (compatible with `index-doc.md`) and extract "business document -> rule/topic" mappings (**primary index**). -2. Read **`rules/main.md` (compatible with `main.mdc`)** or **`rules/f2s-flow2spec-unified-entry.md` (compatible with `f2s-flow2spec-unified-entry.mdc`; compatible with old `flow2spec-unified-entry.md(c)`)** (usually only one exists), and extract module/topic directory clues (**cross-check with the index**). -3. **Full inventory of business rule files**: scan files under `rules/` except the following, and build `bizRuleQueue` (deduped): - - Unified entry: `main.md(c)`, `f2s-flow2spec-unified-entry.md(c)`, `flow2spec-unified-entry.md(c)` (compatible with old name) - - Baseline keep: `f2s-implement-tech-design.md(c)`, `f2s-stock-docs-vs-req-docs.md(c)` -4. **Full inventory of business skills**: scan each agent configuration-root `skills/` directory; **exclude** `f2s-*`; all other directories enter `bizSkillQueue` (deduped). -5. Scan legacy `stock-docs` and `req-docs` candidate source directories if they exist. -6. Generate the migration inventory and show it to the user for confirmation: - - Topic list (deduped, sorted) - - Business rule file list (`bizRuleQueue`) - - Business skill directory list (`bizSkillQueue`) - - `stock-docs` file list - - `req-docs` file list -7. Document classification rules (must be explicit): - - Source path matches `stock-docs` (including synonyms such as `docs/stock`) -> migrate to `.Knowledge/stock-docs` - - Source path matches `req-docs` (including synonyms such as `docs/req`) -> migrate to `.Knowledge/req-docs` - - Unclassifiable files -> put into "manual confirmation list"; do not migrate before confirmation -8. Compute "out-of-index candidates" (`orphans`): - - Files in `bizRuleQueue` not covered by `docs-index` / unified entry (`rules/main` or `f2s-flow2spec-unified-entry`) - - Directories in `bizSkillQueue` not covered by index mappings - - By default, require user confirmation for every item; only in high-confidence reference scenarios may the Agent include it autonomously, and the basis must be appended to state-file `notes[]` (without breaking JSON parseability). -9. After the user confirms the inventory, initialize the state file and write queues (inventory/orphans/topics/stock/req). - -### Step 2: Migrate Topic by Topic (Structure-Layer Core) - -For each topic, execute in this order: - -1. Collect legacy materials for the topic: - - Related `rules/*.md(c)` (business rules) - - Related **business** `skills/` (merge their content into the topic narrative/workflow; do not copy them as skill files under `.Knowledge`) - - **Business document** paths in index mappings - - **Must not** include any file under `skills/f2s-*` -2. Generate or update `.Knowledge/topics/.md`: - - Body text uses the new architecture vocabulary (`.Knowledge` layering, `manifest` routing, `stock-docs`/`req-docs` responsibilities). - - Remove legacy-only paths/terms (such as old `docs-index` root paths or scattered legacy directory names) and replace them with `.Knowledge/...` or stable paths relative to `.Knowledge`. - - **Authoring-side guideline**: if this step generates/rewrites a topic or adjusts `topicMetadata` / `topicDependencies`, first Read the full `rules/f2s-topic-authoring.*` (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`) before writing. -3. Update the topic index row in `.Knowledge/index.md`, and maintain the "Associated documents (summary)" column (1-3 key `stock-docs/req-docs` **clickable Markdown links** per topic, format: `[title](relative path)`). -4. Update the routing manifest as needed: - - `.Knowledge/manifest-routing.json`: `topicPaths`, `taskToTopicRules[]`, `topicDependencies`, `topicMetadata`, `fallbackTopic` - - `.Knowledge/matchers/.json`: `includeAny` (consistent with `manifest-routing.taskToTopicRules[].matcherPath`) -5. Output this topic's migration summary and **pause**, prompting the user: - - Reply "继续" to migrate the next topic - - Or reply "停止" to stop this round - - Or reply "重试 " to redo the current topic - -> Before receiving "继续", do not migrate the next topic. -> After completing each topic, update the state file before waiting. - -### Step 3: Migrate `stock-docs` (Document Layer) - -After step 2 completes, execute: - -1. Migrate into `.Knowledge/stock-docs/` according to "source-directory relative path"; do not flatten. -2. Default scenario is first migration from a legacy repo into the new knowledge base, so target paths are treated as "not existing". -3. After each file migration, output a result and pause, waiting for "继续 / 停止 / 重试 <文件>". -4. After all files complete, output a `stock-docs` sub-summary (success/failure/pending confirmation). - -> Before receiving "继续", do not migrate the next file. -> After completing each file, update the state file before waiting. - -### Step 4: Migrate `req-docs` (Document Layer) - -After the `stock-docs` phase completes, execute: - -1. Migrate into `.Knowledge/req-docs/` according to "source-directory relative path"; do not flatten. -2. Default scenario is first migration from a legacy repo into the new knowledge base, so target paths are treated as "not existing". -3. After each file migration, output a result and pause, waiting for "继续 / 停止 / 重试 <文件>". -4. After all files complete, output a `req-docs` sub-summary (success/failure/pending confirmation). - -> Before receiving "继续", do not migrate the next file. -> After completing each file, update the state file before waiting. - -### Step 5: Closing After All Migration Completes (Required: Migration Report + Deletion-List Confirmation) - -When topic migration (step 2) and document-layer `stock-docs` / `req-docs` migration (steps 3-4) have **all passed acceptance** (no failures and no blocking pending confirmations, or pending items are separately listed in the report), execute the following substeps in order. - -#### 5.0 Migration Report (Required: Write Project Markdown) - -1. **Must** create or overwrite this file in the project repository: **`.Knowledge/migration-report.md`** (relative to project root; same repo as `.Knowledge`, convenient for review and traceability). -2. The report body must contain at least two major blocks (tables or nested lists are allowed; all paths use POSIX style relative to project root): - - **"Migration mapping table"**: - - **Topics**: each migrated `topic` -> legacy sources (corresponding `rules/*.md(c)`, business `skills/`, `docs-index` mapping-line summary) -> new path `.Knowledge/topics/.md`; also indicate whether `.Knowledge/index.md` / routing-manifest fields were modified. - - **`stock-docs`**: every **source path -> `.Knowledge/stock-docs/...` target path** (include skipped files and reasons; write "none" if none). - - **`req-docs`**: same as above. - - **"Proposed deletion path list"**: exactly consistent with the **default-selected deletion list** shown to the user in step 5.2 (each file under `rules/`, each business `skills/` directory to delete, `docs-index`/`index-doc`, and optionally legacy `stock-docs/`/`req-docs/` roots). Prefer `- [ ] ` for each item so humans can review/check. -3. If the user later sends **"排除：<路径…>"** in step 5.2, update the same file **before physical deletion**: append or write in a "User exclusions" section the excluded paths and reasons, and sync the "Proposed deletion path list" checkbox state or list so the report on disk matches the final deletion set. -4. After physical deletion is executed according to the final list in step 5.2 step 3, append a **`## Deletion Execution Record`** section at the **end of the same file** (include execution time and actual deleted paths; for undeleted items, state reason and `status=paused`, etc.). Do not leave this only in the conversation. -5. The migration report "Deletion execution record" section is always appended by the main agent; sub-agents must not write it directly (write-authority hard rule). - -> **Forbidden**: entering physical deletion or ending the migration closure before `.Knowledge/migration-report.md` is written. - -#### 5.1 Overall Summary (In Conversation, May Match Report Summary) - -- Migrated topic list -- New/updated `.Knowledge` files -- Migrated `stock-docs` files -- Migrated `req-docs` files -- Unmigrated or failed items - -#### 5.2 Required Cleanup Phase (Deletion-List Confirmation; Must Not Skip) - -1. Output the default-selected **"deletion path list"** (same source as the "Proposed deletion path list" in `migration-report.md`), including at least: - - Every **business rule** file path under legacy **`rules/`** to delete (may include `main.md(c)`; **must not include** the baseline `f2s-*` root rules) - - Every subdirectory path under legacy **business** `skills/` to delete (**excluding** `f2s-*`) - - Legacy **`docs-index.md` / `index-doc.md`** - - (Optional sub-list) legacy **`stock-docs/`** and **`req-docs/`** root directories, only when document migration has passed acceptance and no pending items remain; the user may exclude them. -2. Wait for the user to reply **"确认清单"** or **"排除：<路径…>"** to update the list. **Do not** ask a binary "whether to clean up" question. -3. Delete according to the **final list**; **do not** delete paths outside the list; **do not** delete **`skills/f2s-*`**. -4. After closing is complete, handle the state file: - - Fully completed round: delete `.Knowledge/.migrate-state.json` - - Paused/aborted round: keep `.Knowledge/.migrate-state.json` (`status=paused`) and record undeleted paths and reasons - -## Output Summary Format (Recommended) - -```markdown -## Topic Migration Complete: - -### Sources -- rules: -- business docs: -- mapping: - -### Written -- .Knowledge/topics/.md -- .Knowledge/index.md (updated rows) -- .Knowledge/manifest-routing.json (updated fields: ...) -- .Knowledge/matchers/.json (updated `includeAny`, etc.: ...) - -### Next Step -- Reply "继续" to migrate the next topic -- Reply "停止" to stop migration -``` - -```markdown -## Document Migration Complete: / - -### Source -- source: - -### Written -- .Knowledge// - -### Next Step -- Reply "继续" to migrate the next file -- Reply "停止" to stop migration -``` - -## Constraints - -- Must confirm topic by topic; do not skip confirmation and migrate everything in batch. -- `stock-docs` / `req-docs` must confirm file by file; do not batch-migrate without confirmation. -- Document migration must preserve source-directory relative paths; do not flatten to single-layer filenames. -- **`f2s-*` skills must not enter `.Knowledge` and must not be merged into topics during topic migration.** -- **Business** `skills/` (non-`f2s-*`) must be fully inventoried; out-of-index items require user confirmation by default before migration. -- Before all topics complete, do not delete legacy business `rules/` or old business `skills/` that are **non-`f2s-*`**; the baseline `f2s-*` root rule files are never deleted. -- Before document migration completes, do not delete legacy document directories. -- Before deleting legacy directories, complete **"deletion path list"** review (exclusions allowed); **do not** replace list confirmation with "whether to clean up". -- During migration, modify only `.Knowledge` and (after **final deletion-list** confirmation) deletion of old paths in the list; do not modify business code. -- Must maintain `.Knowledge/.migrate-state.json`; do not keep migration progress only in memory. -- After topic and document-layer migration acceptance, **first** write `.Knowledge/migration-report.md` (including migration mapping table and proposed deletion path list), then enter physical deletion; report and in-conversation deletion list must share a traceable source. -- `.migrate-state.json` / `migration-report.md` deletion execution record / `manifest-routing.json` / `.Knowledge/index.md` are always written by the main agent. - -## Migration Report Template (Recommended Structure for `migration-report.md`) - -The following skeleton may be copied and filled; all paths are relative to project root. - -```markdown -# Knowledge-Base Migration Report - -- **Generated at (ISO-8601)**: <...> -- **Configuration root (for example `.cursor/`)**: <...> - -## Migration Mapping Table - -### Topics (legacy sources -> new path) - -| topic ID | legacy rules / legacy business skills / index clues | new path | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs (source -> target) - -| source path | target path | note | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | success / skip reason | - -### req-docs (source -> target) - -| source path | target path | note | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | success / skip reason | - -## Proposed Deletion Path List (default selected; same as in-conversation list) - -- [ ] `` (each file under `rules/`) -- [ ] `` (business `skills/`, excluding `f2s-*`) -- [ ] `.cursor/docs-index.md` (or actual path) -- [ ] (optional) legacy `stock-docs/` / `req-docs/` root directories - -## User Exclusions (if any) - -- (write "none" if none) - -## Failed or Unmigrated Items (if any) - -- (write "none" if none) - -## Deletion Execution Record - -(Append only after physical deletion: time, deleted list, undeleted items and reasons) -``` - -## Completion Self-Check - -1. Topic count aligns with the legacy mapping count (unless the user explicitly skipped items). -2. Every `manifest.topics[].path` exists. -3. `index` can locate every migrated topic. -4. `topicMetadata` only references topicIds that exist in `topicPaths`; `primary` / `tags` / `confidence` are valid. -5. `.Knowledge/stock-docs` and `.Knowledge/req-docs` match the confirmed migration lists. -6. Manual confirmation list is empty; if not, deleting legacy document directories is forbidden. -7. Legacy business `rules/`, old business `skills/` that are **non-`f2s-*`**, legacy indexes, and legacy document directories (if listed) were deleted according to the **final deletion list**; the three `f2s-*` root rules in the baseline keep-list are still kept. -8. Legacy entries `docs-index.md` / `index-doc.md` and `rules/main.md(c)` were deleted according to the list (and `.Knowledge` can replace their responsibilities), or explicitly kept due to user exclusion and written to `notes[]`. -9. State file matches migration result (delete if complete; keep with `status=paused` if paused). -10. `.Knowledge/index.md` has synced the "Associated documents (summary)" column for every topic (may write "none", but not blank). -11. `skills/f2s-*` were not accidentally deleted and were not written into `.Knowledge`. -12. `.Knowledge/migration-report.md` is written and contains the **migration mapping table** and **proposed deletion path list**; if deletion was executed, **`## Deletion Execution Record`** was appended and matches actual disk state. -13. State-machine file and deletion execution record were not written by sub-agents without authority; manifest / index were written by the main agent only. diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/packages/core/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/templates/en-US/skills/f2s-kb-migrate/SKILL.md b/templates/en-US/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 209d827..0000000 --- a/templates/en-US/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: Migrate a legacy knowledge base to `.Knowledge` in one pass: use the configuration-root `docs-index.md` plus the unified rule entry (legacy `rules/main.md(c)` or current package `rules/f2s-flow2spec-unified-entry.md(c)`) as primary index clues; fully process business `rules/` and business `skills/` (excluding `f2s-*` package skills), and fully migrate `stock-docs`/`req-docs`; **after migration acceptance, must write** `.Knowledge/migration-report.md` (migration mapping table + proposed deletion path list); **closing must delete** migrated legacy `rules/`, migrated business `skills/`, and legacy `docs-index.md`/`index-doc.md`; the user only **reviews/revises the deletion list (exclusions)**; triggers: f2s-kb-migrate、知识库迁移、旧版迁移、knowledge-base migration、legacy migration ---- - -> Execution scope: this is an `f2s-*` skill workflow, not a CLI subcommand. Migration targets include: -> 1) Structure layer: `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` -> 2) Document layer: `.Knowledge/stock-docs`, `.Knowledge/req-docs` -> -> **Hard boundary**: `skills/f2s-*` (under each agent configuration root) are Flow2Spec package skills / execution-layer capabilities. They **must not** be written into `.Knowledge` (including `topics/stock-docs/req-docs`) and must not be used as sources for "business skill migration". They also **must not** be deleted in this workflow (version alignment is handled by `flow2spec init` / package upgrade). -> -> **Baseline rule keep-list (must not delete)**: `rules/f2s-flow2spec-unified-entry.md(c)`, `rules/f2s-implement-tech-design.md(c)`, `rules/f2s-stock-docs-vs-req-docs.md(c)`. - -## Orchestration (main / sub-agent) - -- The meaning of `subAgent` / `switchAgentVerification` uses the unified entry as the only source of truth: **Cursor/Claude** read the configuration-root `rules/f2s-flow2spec-unified-entry.*`; **Codex** reads `.codex/topics/f2s-flow2spec-unified-entry.md` (same source, mirrored by `flow2spec init`). This section does not repeat those definitions. -- **Sub-agent responsibility** (only when `subAgent=true`): under the main agent's given inventory, perform moving work and generate **draft fragments** for `migration-report.md`; all outputs are submitted as patches and merged/written by the main agent. -- **Main agent must control**: - - `.Knowledge/.migrate-state.json` **write authority belongs to main** (state-machine source of truth; concurrent main/sub writes can misalign queues). - - The **"Deletion execution record"** section of `migration-report.md` is always appended by the main agent. - - **Deletion-list confirmation** and closed-loop cleanup must be completed by the main agent. -- **Write-authority hard rule**: `manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / the migration report "Deletion execution record" are always written by the main agent. -- By default, the writing side verifies its own work; this SKILL does not bind cross-agent verification. - -# f2s-kb-migrate (Legacy Knowledge Base -> New Knowledge Base) - -## Why this coexists with `f2s-kb-upgrade` - -| Skill | Problem solved | -| --- | --- | -| **This skill `f2s-kb-migrate`** | **One-time structural move**: legacy indexes (`docs-index.md` / `index-doc.md`), `rules/main.md(c)`, business `skills/`, scattered `stock-docs`/`req-docs` -> **`.Knowledge`**, plus deletion list and `migration-report.md`. | -| **`f2s-kb-upgrade`** | **Knowledge-base template upgrade skill (the only "upgrade" meaning)**: execute the full **`skills/f2s-kb-upgrade/SKILL.md`** workflow. It runs **`flow2spec init`** inside the process to align **`manifest-routing` + `matchers/`** and each agent's **`rules`/`skills`**. It includes **V1 / current repository (V2+)** branching (legacy projects must **migrate first, then run this skill**; **V2+ includes npm v3.x and other projects already using `.Knowledge`**, see `f2s-kb-upgrade` step 0). | - -- **After migration acceptance and deletion-list confirmation are complete**: remind the user to execute, or execute for them, the **full `f2s-kb-upgrade` skill** (whose **step 2** runs **`flow2spec init`**) to align the Flow2Spec package version, routing shards, and configuration-root artifacts to the current package. **Do not** let the user think that running `init` alone completes knowledge-base template upgrade. -- **Projects already stably using `.Knowledge` with no legacy-index burden**: do not run this skill again; daily package/template alignment uses **`f2s-kb-upgrade`** only (not just `init`). - -**Why does each agent directory have a same-named `SKILL.md`?** Each tool reads only its own configuration-root `skills/`; `flow2spec init` **syncs** the current-language skill content into the selected agent directories. - -## What This Command Does (External Wording) - -Move the legacy "scattered configuration-root document index + rules + business skills + stock/req document trees" **as a whole into the new `.Knowledge`**, then perform **legacy entry and legacy business-artifact cleanup**, cutting over from the old knowledge-base organization. - -Objects that must be covered: - -1. **Index entry**: business docs and rule clues declared/mapped in configuration-root `docs-index.md` (compatible with `index-doc.md`). -2. **Rule entry**: the rule set declared/referenced in `rules/main.md` / `rules/main.mdc` (common legacy form) or `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc` (compatible with historical `rules/flow2spec-unified-entry.md(c)`), plus other business rule files under `rules/`. -3. **Business skills**: business skill directories under each agent configuration-root `skills/`, excluding `f2s-*` (full inventory). -4. **Document trees**: legacy `stock-docs/`, `req-docs/` (or synonymous directories) fully migrated into the corresponding `.Knowledge` directories. - -For objects **not covered by the index**: - -- First output a candidate list (path + inferred reason: naming/directory/reference relationship). -- **By default, user confirmation is required** before including them in migration. Only when evidence is very strong (for example explicitly referenced by `rules/main` / `f2s-flow2spec-unified-entry`, or clearly referenced by an indexed document) may the Agent decide to include them, and the basis must be written in the migration summary. - -Cleanup after migration (mandatory closing; only when migration has no failures and no pending confirmations; **`skills/f2s-*` are never deleted**): - -- **Must execute**: delete migrated business rule files in legacy **`rules/`** (including `main.md(c)` if it is only a legacy entry), but **must not delete** the three `f2s-*` root rule files in the baseline keep-list. -- **Must execute**: delete migrated **business** subdirectories under legacy **`skills/`** (**excluding** `f2s-*`; if a directory still has unmigrated items, do not delete it until completed or removed from the list). -- **Must execute**: delete legacy entry **`docs-index.md`** (compatible with **`index-doc.md`**) to avoid dual entry points with `.Knowledge/index.md`. -- **Default optional deletion sub-list** (the user may exclude): legacy **`stock-docs/`** and **`req-docs/`** source directories, only when the corresponding document-layer migration has passed acceptance with no failures and no pending confirmations. - -**Meaning of user confirmation (important)**: - -- This is **not** asking "whether to clean up"; cleanup is part of the workflow. -- Instead, output the default-selected **"deletion path list"** (rule files one by one, business skill directories one by one, index filenames, and optional legacy document root directories) and ask the user to **review**. The user can only: - - Reply "**确认清单**" to delete according to the current list; or - - Reply "**排除：<路径…>**" to remove specified items from the list before deletion (removed items must be written to `.migrate-state.json` `notes[]` with reasons). -- If the user asks to **defer deleting a path**, keep that item in the list, end the cleanup round with `status=paused`, and **do not** pretend migration closure is complete. - -## Applicable Scenarios - -- The project still uses legacy knowledge organization (`docs-index.md` / `index-doc.md` + `rules/main.md(c)` or `rules/f2s-flow2spec-unified-entry.md(c)` (compatible with old `flow2spec-unified-entry.md(c)`) + business `skills/` + scattered `stock-docs`/`req-docs`). -- The user wants to migrate to the new `.Knowledge` format and confirm topic by topic to avoid one-shot large changes. -- The user needs **all req-docs / stock-docs** migrated into `.Knowledge` and wants to cut over from legacy knowledge-base directories/wording (paths, index, topic text unified to the new architecture). - -## Input - -- Optional inputs: - - Legacy unified rule entry path: `rules/main.md` / `rules/main.mdc` and/or `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc` (compatible with old `rules/flow2spec-unified-entry.md(c)`) - - Legacy `index-doc.md` (or `docs-index.md`) path - - Legacy stock document directory (for example `stock-docs/`, `docs/stock/`) - - Legacy requirement document directory (for example `req-docs/`, `docs/req/`) - - Migration scope (all topics / specified topics) -- If not provided, locate the above files in the repository first and ask the user to confirm. - -## Resumable Migration State File (Required) - -- State file path: `.Knowledge/.migrate-state.json` -- Purpose: record migration progress and support recovery after session interruption without migrating completed items again. -- Initialization timing: create immediately after the user confirms "start migration". -- Ending timing: - - All migration complete and user confirms completion: delete the state file. - - User actively says "stop": keep the state file for later recovery. -- `.migrate-state.json` is written only by the main agent; sub-agents submit patch fragments for the main agent to merge (write-authority hard rule). - -Recommended fields (minimal set): - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -Update rules (required): - -1. After completing each topic, business skill directory, business rule file, or document file, immediately write the state-file update. -2. When receiving "重试 ", roll back that item's state before retrying. -3. When receiving "继续", read the state file first and continue from unfinished queues. -4. When receiving "停止", write `status=paused` and end this round. -5. When receiving a resume request, first show a state summary (current stage, remaining counts, failed/pending items) and wait for user confirmation to continue. - -## Mandatory Flow (Phased Execution) - -### Step 1: Read Legacy Mappings - -1. Read `docs-index.md` (compatible with `index-doc.md`) and extract "business document -> rule/topic" mappings (**primary index**). -2. Read **`rules/main.md` (compatible with `main.mdc`)** or **`rules/f2s-flow2spec-unified-entry.md` (compatible with `f2s-flow2spec-unified-entry.mdc`; compatible with old `flow2spec-unified-entry.md(c)`)** (usually only one exists), and extract module/topic directory clues (**cross-check with the index**). -3. **Full inventory of business rule files**: scan files under `rules/` except the following, and build `bizRuleQueue` (deduped): - - Unified entry: `main.md(c)`, `f2s-flow2spec-unified-entry.md(c)`, `flow2spec-unified-entry.md(c)` (compatible with old name) - - Baseline keep: `f2s-implement-tech-design.md(c)`, `f2s-stock-docs-vs-req-docs.md(c)` -4. **Full inventory of business skills**: scan each agent configuration-root `skills/` directory; **exclude** `f2s-*`; all other directories enter `bizSkillQueue` (deduped). -5. Scan legacy `stock-docs` and `req-docs` candidate source directories if they exist. -6. Generate the migration inventory and show it to the user for confirmation: - - Topic list (deduped, sorted) - - Business rule file list (`bizRuleQueue`) - - Business skill directory list (`bizSkillQueue`) - - `stock-docs` file list - - `req-docs` file list -7. Document classification rules (must be explicit): - - Source path matches `stock-docs` (including synonyms such as `docs/stock`) -> migrate to `.Knowledge/stock-docs` - - Source path matches `req-docs` (including synonyms such as `docs/req`) -> migrate to `.Knowledge/req-docs` - - Unclassifiable files -> put into "manual confirmation list"; do not migrate before confirmation -8. Compute "out-of-index candidates" (`orphans`): - - Files in `bizRuleQueue` not covered by `docs-index` / unified entry (`rules/main` or `f2s-flow2spec-unified-entry`) - - Directories in `bizSkillQueue` not covered by index mappings - - By default, require user confirmation for every item; only in high-confidence reference scenarios may the Agent include it autonomously, and the basis must be appended to state-file `notes[]` (without breaking JSON parseability). -9. After the user confirms the inventory, initialize the state file and write queues (inventory/orphans/topics/stock/req). - -### Step 2: Migrate Topic by Topic (Structure-Layer Core) - -For each topic, execute in this order: - -1. Collect legacy materials for the topic: - - Related `rules/*.md(c)` (business rules) - - Related **business** `skills/` (merge their content into the topic narrative/workflow; do not copy them as skill files under `.Knowledge`) - - **Business document** paths in index mappings - - **Must not** include any file under `skills/f2s-*` -2. Generate or update `.Knowledge/topics/.md`: - - Body text uses the new architecture vocabulary (`.Knowledge` layering, `manifest` routing, `stock-docs`/`req-docs` responsibilities). - - Remove legacy-only paths/terms (such as old `docs-index` root paths or scattered legacy directory names) and replace them with `.Knowledge/...` or stable paths relative to `.Knowledge`. - - **Authoring-side guideline**: if this step generates/rewrites a topic or adjusts `topicMetadata` / `topicDependencies`, first Read the full `rules/f2s-topic-authoring.*` (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`) before writing. -3. Update the topic index row in `.Knowledge/index.md`, and maintain the "Associated documents (summary)" column (1-3 key `stock-docs/req-docs` **clickable Markdown links** per topic, format: `[title](relative path)`). -4. Update the routing manifest as needed: - - `.Knowledge/manifest-routing.json`: `topicPaths`, `taskToTopicRules[]`, `topicDependencies`, `topicMetadata`, `fallbackTopic` - - `.Knowledge/matchers/.json`: `includeAny` (consistent with `manifest-routing.taskToTopicRules[].matcherPath`) -5. Output this topic's migration summary and **pause**, prompting the user: - - Reply "继续" to migrate the next topic - - Or reply "停止" to stop this round - - Or reply "重试 " to redo the current topic - -> Before receiving "继续", do not migrate the next topic. -> After completing each topic, update the state file before waiting. - -### Step 3: Migrate `stock-docs` (Document Layer) - -After step 2 completes, execute: - -1. Migrate into `.Knowledge/stock-docs/` according to "source-directory relative path"; do not flatten. -2. Default scenario is first migration from a legacy repo into the new knowledge base, so target paths are treated as "not existing". -3. After each file migration, output a result and pause, waiting for "继续 / 停止 / 重试 <文件>". -4. After all files complete, output a `stock-docs` sub-summary (success/failure/pending confirmation). - -> Before receiving "继续", do not migrate the next file. -> After completing each file, update the state file before waiting. - -### Step 4: Migrate `req-docs` (Document Layer) - -After the `stock-docs` phase completes, execute: - -1. Migrate into `.Knowledge/req-docs/` according to "source-directory relative path"; do not flatten. -2. Default scenario is first migration from a legacy repo into the new knowledge base, so target paths are treated as "not existing". -3. After each file migration, output a result and pause, waiting for "继续 / 停止 / 重试 <文件>". -4. After all files complete, output a `req-docs` sub-summary (success/failure/pending confirmation). - -> Before receiving "继续", do not migrate the next file. -> After completing each file, update the state file before waiting. - -### Step 5: Closing After All Migration Completes (Required: Migration Report + Deletion-List Confirmation) - -When topic migration (step 2) and document-layer `stock-docs` / `req-docs` migration (steps 3-4) have **all passed acceptance** (no failures and no blocking pending confirmations, or pending items are separately listed in the report), execute the following substeps in order. - -#### 5.0 Migration Report (Required: Write Project Markdown) - -1. **Must** create or overwrite this file in the project repository: **`.Knowledge/migration-report.md`** (relative to project root; same repo as `.Knowledge`, convenient for review and traceability). -2. The report body must contain at least two major blocks (tables or nested lists are allowed; all paths use POSIX style relative to project root): - - **"Migration mapping table"**: - - **Topics**: each migrated `topic` -> legacy sources (corresponding `rules/*.md(c)`, business `skills/`, `docs-index` mapping-line summary) -> new path `.Knowledge/topics/.md`; also indicate whether `.Knowledge/index.md` / routing-manifest fields were modified. - - **`stock-docs`**: every **source path -> `.Knowledge/stock-docs/...` target path** (include skipped files and reasons; write "none" if none). - - **`req-docs`**: same as above. - - **"Proposed deletion path list"**: exactly consistent with the **default-selected deletion list** shown to the user in step 5.2 (each file under `rules/`, each business `skills/` directory to delete, `docs-index`/`index-doc`, and optionally legacy `stock-docs/`/`req-docs/` roots). Prefer `- [ ] ` for each item so humans can review/check. -3. If the user later sends **"排除：<路径…>"** in step 5.2, update the same file **before physical deletion**: append or write in a "User exclusions" section the excluded paths and reasons, and sync the "Proposed deletion path list" checkbox state or list so the report on disk matches the final deletion set. -4. After physical deletion is executed according to the final list in step 5.2 step 3, append a **`## Deletion Execution Record`** section at the **end of the same file** (include execution time and actual deleted paths; for undeleted items, state reason and `status=paused`, etc.). Do not leave this only in the conversation. -5. The migration report "Deletion execution record" section is always appended by the main agent; sub-agents must not write it directly (write-authority hard rule). - -> **Forbidden**: entering physical deletion or ending the migration closure before `.Knowledge/migration-report.md` is written. - -#### 5.1 Overall Summary (In Conversation, May Match Report Summary) - -- Migrated topic list -- New/updated `.Knowledge` files -- Migrated `stock-docs` files -- Migrated `req-docs` files -- Unmigrated or failed items - -#### 5.2 Required Cleanup Phase (Deletion-List Confirmation; Must Not Skip) - -1. Output the default-selected **"deletion path list"** (same source as the "Proposed deletion path list" in `migration-report.md`), including at least: - - Every **business rule** file path under legacy **`rules/`** to delete (may include `main.md(c)`; **must not include** the baseline `f2s-*` root rules) - - Every subdirectory path under legacy **business** `skills/` to delete (**excluding** `f2s-*`) - - Legacy **`docs-index.md` / `index-doc.md`** - - (Optional sub-list) legacy **`stock-docs/`** and **`req-docs/`** root directories, only when document migration has passed acceptance and no pending items remain; the user may exclude them. -2. Wait for the user to reply **"确认清单"** or **"排除：<路径…>"** to update the list. **Do not** ask a binary "whether to clean up" question. -3. Delete according to the **final list**; **do not** delete paths outside the list; **do not** delete **`skills/f2s-*`**. -4. After closing is complete, handle the state file: - - Fully completed round: delete `.Knowledge/.migrate-state.json` - - Paused/aborted round: keep `.Knowledge/.migrate-state.json` (`status=paused`) and record undeleted paths and reasons - -## Output Summary Format (Recommended) - -```markdown -## Topic Migration Complete: - -### Sources -- rules: -- business docs: -- mapping: - -### Written -- .Knowledge/topics/.md -- .Knowledge/index.md (updated rows) -- .Knowledge/manifest-routing.json (updated fields: ...) -- .Knowledge/matchers/.json (updated `includeAny`, etc.: ...) - -### Next Step -- Reply "继续" to migrate the next topic -- Reply "停止" to stop migration -``` - -```markdown -## Document Migration Complete: / - -### Source -- source: - -### Written -- .Knowledge// - -### Next Step -- Reply "继续" to migrate the next file -- Reply "停止" to stop migration -``` - -## Constraints - -- Must confirm topic by topic; do not skip confirmation and migrate everything in batch. -- `stock-docs` / `req-docs` must confirm file by file; do not batch-migrate without confirmation. -- Document migration must preserve source-directory relative paths; do not flatten to single-layer filenames. -- **`f2s-*` skills must not enter `.Knowledge` and must not be merged into topics during topic migration.** -- **Business** `skills/` (non-`f2s-*`) must be fully inventoried; out-of-index items require user confirmation by default before migration. -- Before all topics complete, do not delete legacy business `rules/` or old business `skills/` that are **non-`f2s-*`**; the baseline `f2s-*` root rule files are never deleted. -- Before document migration completes, do not delete legacy document directories. -- Before deleting legacy directories, complete **"deletion path list"** review (exclusions allowed); **do not** replace list confirmation with "whether to clean up". -- During migration, modify only `.Knowledge` and (after **final deletion-list** confirmation) deletion of old paths in the list; do not modify business code. -- Must maintain `.Knowledge/.migrate-state.json`; do not keep migration progress only in memory. -- After topic and document-layer migration acceptance, **first** write `.Knowledge/migration-report.md` (including migration mapping table and proposed deletion path list), then enter physical deletion; report and in-conversation deletion list must share a traceable source. -- `.migrate-state.json` / `migration-report.md` deletion execution record / `manifest-routing.json` / `.Knowledge/index.md` are always written by the main agent. - -## Migration Report Template (Recommended Structure for `migration-report.md`) - -The following skeleton may be copied and filled; all paths are relative to project root. - -```markdown -# Knowledge-Base Migration Report - -- **Generated at (ISO-8601)**: <...> -- **Configuration root (for example `.cursor/`)**: <...> - -## Migration Mapping Table - -### Topics (legacy sources -> new path) - -| topic ID | legacy rules / legacy business skills / index clues | new path | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs (source -> target) - -| source path | target path | note | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | success / skip reason | - -### req-docs (source -> target) - -| source path | target path | note | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | success / skip reason | - -## Proposed Deletion Path List (default selected; same as in-conversation list) - -- [ ] `` (each file under `rules/`) -- [ ] `` (business `skills/`, excluding `f2s-*`) -- [ ] `.cursor/docs-index.md` (or actual path) -- [ ] (optional) legacy `stock-docs/` / `req-docs/` root directories - -## User Exclusions (if any) - -- (write "none" if none) - -## Failed or Unmigrated Items (if any) - -- (write "none" if none) - -## Deletion Execution Record - -(Append only after physical deletion: time, deleted list, undeleted items and reasons) -``` - -## Completion Self-Check - -1. Topic count aligns with the legacy mapping count (unless the user explicitly skipped items). -2. Every `manifest.topics[].path` exists. -3. `index` can locate every migrated topic. -4. `topicMetadata` only references topicIds that exist in `topicPaths`; `primary` / `tags` / `confidence` are valid. -5. `.Knowledge/stock-docs` and `.Knowledge/req-docs` match the confirmed migration lists. -6. Manual confirmation list is empty; if not, deleting legacy document directories is forbidden. -7. Legacy business `rules/`, old business `skills/` that are **non-`f2s-*`**, legacy indexes, and legacy document directories (if listed) were deleted according to the **final deletion list**; the three `f2s-*` root rules in the baseline keep-list are still kept. -8. Legacy entries `docs-index.md` / `index-doc.md` and `rules/main.md(c)` were deleted according to the list (and `.Knowledge` can replace their responsibilities), or explicitly kept due to user exclusion and written to `notes[]`. -9. State file matches migration result (delete if complete; keep with `status=paused` if paused). -10. `.Knowledge/index.md` has synced the "Associated documents (summary)" column for every topic (may write "none", but not blank). -11. `skills/f2s-*` were not accidentally deleted and were not written into `.Knowledge`. -12. `.Knowledge/migration-report.md` is written and contains the **migration mapping table** and **proposed deletion path list**; if deletion was executed, **`## Deletion Execution Record`** was appended and matches actual disk state. -13. State-machine file and deletion execution record were not written by sub-agents without authority; manifest / index were written by the main agent only. diff --git a/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md b/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/templates/zh-CN/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 From 52f00329080f9e04f85cd21bf64d745aa205df83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Mon, 24 Aug 2026 15:58:32 +0800 Subject: [PATCH 2/5] ~ --- .dsh/skills/f2s-kb-migrate/SKILL.md | 358 --------------------- .dsh/skills/f2s-kb-upgrade/SKILL.md | 31 +- .dsh/topics/f2s-flow2spec-unified-entry.md | 6 +- .dsh/topics/f2s-intent-routing.md | 1 - .dsh/topics/f2s-topic-authoring.md | 2 +- 5 files changed, 22 insertions(+), 376 deletions(-) delete mode 100644 .dsh/skills/f2s-kb-migrate/SKILL.md diff --git a/.dsh/skills/f2s-kb-migrate/SKILL.md b/.dsh/skills/f2s-kb-migrate/SKILL.md deleted file mode 100644 index 72ba035..0000000 --- a/.dsh/skills/f2s-kb-migrate/SKILL.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -name: f2s-kb-migrate -description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 ---- - -> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： -> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` -> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` -> -> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 -> -> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 - -## 编排（主 / 子 agent） - -- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 -- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 -- **主必控**： - - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； - - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； - - **删除清单确认**与闭环收尾必主完成。 -- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 -- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 - -# f2s-kb-migrate（旧版知识库 -> 新版知识库） - -## 与 `f2s-kb-upgrade` 为何并存 - -| 技能 | 解决的问题 | -| --- | --- | -| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | -| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | - -- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 -- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 - -**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 - -## 本命令做什么（对外口径） - -把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 - -必须覆盖的对象： - -1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 -2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 -3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 -4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 - -对“索引未覆盖”的对象： - -- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 -- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 - -迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： - -- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 -- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 -- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 -- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 - -**用户确认的含义（重要）**： - -- **不是**询问「要不要做清理」；清理是流程的一部分。 -- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： - - 回复「**确认清单**」按当前清单执行删除；或 - - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 -- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 - -## 适用场景 - -- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 -- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 -- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 - -## 输入 - -- 可选输入： - - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） - - 旧版 `index-doc.md`（或 `docs-index.md`）路径 - - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） - - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） - - 迁移范围（全部主题 / 指定主题） -- 不提供时，先在仓库中定位上述文件并向用户确认。 - -## 断点续迁状态文件（必须启用） - -- 状态文件路径：`.Knowledge/.migrate-state.json` -- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 -- 初始化时机：用户确认“开始迁移”后立即创建。 -- 结束时机： - - 全部迁移完成且用户确认结束：删除状态文件。 - - 用户主动“停止”：保留状态文件，等待下次恢复。 -- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 - -建议字段（最小集）： - -```json -{ - "version": "1", - "status": "running", - "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", - "topicQueue": [], - "topicDone": [], - "bizRuleQueue": [], - "bizRuleDone": [], - "bizSkillQueue": [], - "bizSkillDone": [], - "stockQueue": [], - "stockDone": [], - "reqQueue": [], - "reqDone": [], - "pendingManual": [], - "failed": [], - "notes": [], - "updatedAt": "ISO-8601" -} -``` - -更新规则（必须执行）： - -1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 -2. 收到“重试 ”时，先回滚该项状态，再执行重试。 -3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 -4. 收到“停止”时，写入 `status=paused` 并结束本轮。 -5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 - -## 强制流程（分阶段执行） - -### 步骤 1：读取旧版映射 - -1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 -2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 -3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： - - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） - - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` -4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 -5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 -6. 生成待迁移清单并展示给用户确认： - - 主题清单（去重、排序） - - 业务规则文件清单（`bizRuleQueue`） - - 业务技能目录清单（`bizSkillQueue`） - - `stock-docs` 文件清单 - - `req-docs` 文件清单 -7. 文档分类口径（必须明确）： - - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` - - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` - - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 -8. 计算“索引外候选”（`orphans`）： - - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 - - `bizSkillQueue` 中未被索引映射覆盖的目录 - - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 -9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 - -### 步骤 2：逐主题迁移（结构层核心） - -对每个主题按以下顺序执行： - -1. 汇总该主题旧资料： - - 相关 `rules/*.md(c)`（业务规则） - - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） - - 索引映射中的**业务文档**路径 - - **不得**包含 `skills/f2s-*` 下任何文件 -2. 生成或更新 `.Knowledge/topics/.md`： - - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 - - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 - - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 -3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 -4. 按需更新路由清单： - - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` - - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） -5. 输出本主题迁移摘要并**暂停**，提示用户： - - 回复“继续”迁移下一个主题 - - 或回复“停止”终止本轮 - - 或回复“重试 ”重做当前主题 - -> 未收到“继续”前，不得迁移下一个主题。 -> 每完成一个主题，必须先更新状态文件再进入等待。 - -### 步骤 3：迁移 `stock-docs`（文档层） - -当步骤 2 全部完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 4：迁移 `req-docs`（文档层） - -当 `stock-docs` 阶段完成后，执行： - -1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 -2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 -3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 -4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 - -> 未收到“继续”前，不得迁移下一个文件。 -> 每完成一个文件，必须先更新状态文件再进入等待。 - -### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） - -当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 - -#### 5.0 迁移报告（必选：写入项目 Markdown） - -1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 -2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： - - **「迁移对照表」**： - - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 - - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 - - **`req-docs`**：同上。 - - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 -3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 -4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 -5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 - -> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 - -#### 5.1 总摘要（对话内，可与报告摘要一致） - -- 已迁移主题列表 -- 新增/更新的 `.Knowledge` 文件 -- 已迁移 `stock-docs` 文件 -- 已迁移 `req-docs` 文件 -- 未迁移或失败项 - -#### 5.2 必选清理阶段（删除清单确认，不得跳过） - -1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： - - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） - - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） - - 旧版 **`docs-index.md` / `index-doc.md`** - - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 -2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 -3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 -4. 收尾完成后处理状态文件： - - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` - - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 - -## 输出摘要格式（建议） - -```markdown -## 主题迁移完成： - -### 来源 -- rules: <旧路径...> -- 业务文档: <索引映射中的文档路径...> -- 映射: - -### 已写入 -- .Knowledge/topics/.md -- .Knowledge/index.md（更新 行） -- .Knowledge/manifest-routing.json（更新字段：...） -- .Knowledge/matchers/.json（更新 `includeAny` 等：...） - -### 下一步 -- 回复“继续”迁移下一个主题 -- 回复“停止”结束迁移 -``` - -```markdown -## 文档迁移完成：/ - -### 来源 -- source: <旧路径...> - -### 已写入 -- .Knowledge// - -### 下一步 -- 回复“继续”迁移下一个文件 -- 回复“停止”结束迁移 -``` - -## 约束 - -- 必须逐主题确认，不可批量跳过确认直接全量迁移。 -- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 -- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 -- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** -- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 -- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 -- 未完成文档迁移前，禁止删除旧文档目录。 -- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 -- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 -- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 -- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 -- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 - -## 迁移报告模板（落盘 `migration-report.md` 时建议结构） - -以下骨架可直接复制后填空；路径均为相对项目根。 - -```markdown -# 知识库迁移报告 - -- **生成时间（ISO-8601）**：<...> -- **配置根（如 `.cursor/`）**：<...> - -## 迁移对照表 - -### 主题（旧来源 → 新路径） - -| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | -| --- | --- | --- | -| | <...> | `.Knowledge/topics/.md` | - -### stock-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | - -### req-docs（源 → 目标） - -| 源路径 | 目标路径 | 备注 | -| --- | --- | --- | -| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | - -## 拟删除路径清单（默认全选；与对话内清单一致） - -- [ ] `<路径>`（`rules/` 下逐文件） -- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） -- [ ] `.cursor/docs-index.md`（或实际路径） -- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 - -## 用户排除项（如有） - -- （无则写「无」） - -## 失败或未迁移项（如有） - -- （无则写「无」） - -## 删除执行记录 - -（仅在执行物理删除后追加：时间、已删列表、未删及原因） -``` - -## 完成后自检 - -1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 -2. `manifest.topics[].path` 是否都存在。 -3. `index` 是否可定位到每个已迁移主题。 -4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 -5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 -6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 -7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 -8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 -9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 -10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 -11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 -12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 -13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/.dsh/skills/f2s-kb-upgrade/SKILL.md b/.dsh/skills/f2s-kb-upgrade/SKILL.md index 3cc064d..8b94ed1 100644 --- a/.dsh/skills/f2s-kb-upgrade/SKILL.md +++ b/.dsh/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,15 +52,20 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 + +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 **为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** 各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 diff --git a/.dsh/topics/f2s-flow2spec-unified-entry.md b/.dsh/topics/f2s-flow2spec-unified-entry.md index 7a7c33e..dd99d27 100644 --- a/.dsh/topics/f2s-flow2spec-unified-entry.md +++ b/.dsh/topics/f2s-flow2spec-unified-entry.md @@ -92,15 +92,15 @@ **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/.dsh/topics/f2s-intent-routing.md b/.dsh/topics/f2s-intent-routing.md index c343435..345a6e7 100644 --- a/.dsh/topics/f2s-intent-routing.md +++ b/.dsh/topics/f2s-intent-routing.md @@ -34,7 +34,6 @@ | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/.dsh/topics/f2s-topic-authoring.md b/.dsh/topics/f2s-topic-authoring.md index 8aab8f6..665f88d 100644 --- a/.dsh/topics/f2s-topic-authoring.md +++ b/.dsh/topics/f2s-topic-authoring.md @@ -11,7 +11,7 @@ - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 From 83fac8b76f1d2dfe96f7b3bdfa48804039c79a42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Mon, 24 Aug 2026 16:15:32 +0800 Subject: [PATCH 3/5] =?UTF-8?q?[tech]=20chore:=20=E5=9B=BA=E5=8C=96=20unia?= =?UTF-8?q?i=20=E9=A1=B9=E7=9B=AE=E7=B1=BB=E5=9E=8B=E6=A0=87=E8=AE=B0?= =?UTF-8?q?=E4=B8=BA=20tech?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .uniai-project.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .uniai-project.json diff --git a/.uniai-project.json b/.uniai-project.json new file mode 100644 index 0000000..6a89424 --- /dev/null +++ b/.uniai-project.json @@ -0,0 +1,3 @@ +{ + "mode": "tech" +} From ae7729df8aab7554e85a10953f10a88f10b44610 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Mon, 24 Aug 2026 16:15:48 +0800 Subject: [PATCH 4/5] =?UTF-8?q?[tech]=20fix(kb):=20=E9=9D=9E=E4=B8=BB?= =?UTF-8?q?=E9=A2=98=E7=89=88=E6=9C=AC=E6=9B=B4=E6=96=B0=E7=9B=B4=E6=8E=A5?= =?UTF-8?q?=E4=BB=A3=E8=B7=91=20init=EF=BC=8C=E7=A7=BB=E9=99=A4=20f2s-kb-m?= =?UTF-8?q?igrate=EF=BC=88#40=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [摘要] 升级提示改为 agent 直接代跑 flow2spec init，按 projectRev/pkgRev 判定是否再走完整升级；下线旧版迁移技能。 - hook 与统一入口新增 agent-instruction：init 后 projectRev == pkgRev（非主题更新）即完成，不等再走 f2s-kb-upgrade（从步骤 2c 起） - f2s-kb-upgrade：V1 旧版布局不再内置迁移，命中即停止并告知处理方式（历史版本包一次性迁移 / 手动迁入 .Knowledge） - 移除 intent-routing / topic-authoring / 统一入口中对 f2s-kb-migrate 的引用（模板目录删除已随配置根分发提交） - packages/core/lib/updateCheck.js buildNotice 同口径更新 Closes #40 Co-Authored-By: Claude Fable 5 --- AGENTS.md | 3 +- packages/cli/cli.js | 0 packages/core/lib/updateCheck.js | 4 +-- .../templates/en-US/hooks/f2s-update-check.js | 6 ++-- .../rules/f2s-flow2spec-unified-entry.md | 6 ++-- .../en-US/rules/f2s-intent-routing.md | 1 - .../en-US/rules/f2s-topic-authoring.md | 2 +- .../en-US/skills/f2s-kb-upgrade/SKILL.md | 31 +++++++++++-------- .../templates/zh-CN/hooks/f2s-update-check.js | 6 ++-- .../rules/f2s-flow2spec-unified-entry.md | 6 ++-- .../zh-CN/rules/f2s-intent-routing.md | 1 - .../zh-CN/rules/f2s-topic-authoring.md | 2 +- .../zh-CN/skills/f2s-kb-upgrade/SKILL.md | 31 +++++++++++-------- templates/en-US/hooks/f2s-update-check.js | 6 ++-- .../rules/f2s-flow2spec-unified-entry.md | 6 ++-- templates/en-US/rules/f2s-intent-routing.md | 1 - templates/en-US/rules/f2s-topic-authoring.md | 2 +- .../en-US/skills/f2s-kb-upgrade/SKILL.md | 31 +++++++++++-------- templates/zh-CN/hooks/f2s-update-check.js | 6 ++-- .../rules/f2s-flow2spec-unified-entry.md | 6 ++-- templates/zh-CN/rules/f2s-intent-routing.md | 1 - templates/zh-CN/rules/f2s-topic-authoring.md | 2 +- .../zh-CN/skills/f2s-kb-upgrade/SKILL.md | 31 +++++++++++-------- 23 files changed, 107 insertions(+), 84 deletions(-) mode change 100644 => 100755 packages/cli/cli.js diff --git a/AGENTS.md b/AGENTS.md index c20b31c..122252e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,10 +106,9 @@ - `f2s-kb-feat`：新增能力时补全实现与知识库；已实现则仅同步知识库；触发：f2s-kb-feat、新增能力 - `f2s-kb-fix`：根据用户指出的实现或规则错误修正代码，并默认同步知识库；触发：f2s-kb-fix、修正实现规则 - `f2s-kb-merge`：解决 Git 合并后编辑器上下文冲突；可选传入冲突文件；实现侧冲突仅罗列待用户确认；触发：合并上下文冲突、f2s-kb-merge -- `f2s-kb-migrate`：旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 - `f2s-kb-rm`：删除某 stock-docs 文档对应的知识主题与索引映射；触发：删除项目上下文、f2s-kb-rm - `f2s-kb-sync`：可显式给出能力或零输入推断；先输出知识库更新大纲，确认后写入 topics/index/manifest；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力 -- `f2s-kb-upgrade`：知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +- `f2s-kb-upgrade`：知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 - `f2s-req-clarify`：针对 PRD/需求反问直到清楚，再可用 f2s-req-tech 出技术方案；触发：需求澄清、PRD 澄清 - `f2s-req-plan`：根据技术方案/需求描述/变更描述规划并实现任务；始终按 f2s-task 维护 .task/；支持子 agent 并行实现；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单 - `f2s-req-tech`：根据澄清后的需求基于项目知识库/Skills/Rules 生成技术方案文档；触发：生成技术方案、技术方案、f2s-req-tech diff --git a/packages/cli/cli.js b/packages/cli/cli.js old mode 100644 new mode 100755 diff --git a/packages/core/lib/updateCheck.js b/packages/core/lib/updateCheck.js index f012de6..cc4fe87 100644 --- a/packages/core/lib/updateCheck.js +++ b/packages/core/lib/updateCheck.js @@ -60,9 +60,9 @@ function projectName(cwd) { function buildNotice({ cwd, locale, manifestVersion, latestVersion }) { if (locale === "en-US") { - return `[flow2spec] The project "${projectName(cwd)}" knowledge version is v${manifestVersion}; Core v${latestVersion} is available. Run the f2s-kb-upgrade skill to align templates and routing.`; + return `[flow2spec] The project "${projectName(cwd)}" knowledge version is v${manifestVersion}; Core v${latestVersion} is available. The agent may run flow2spec init directly to complete the update; run the f2s-kb-upgrade skill only when the update includes topic-layer changes (projectRev != pkgRev after init).`; } - return `[flow2spec] 当前项目「${projectName(cwd)}」知识版本为 v${manifestVersion}，Core 最新版本为 v${latestVersion}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + return `[flow2spec] 当前项目「${projectName(cwd)}」知识版本为 v${manifestVersion}，Core 最新版本为 v${latestVersion}。可由 agent 直接代跑 flow2spec init 完成更新；仅当更新包含主题层变更（init 后 projectRev 与 pkgRev 不等）时再执行 f2s-kb-upgrade skill。`; } function queryLatestVersion(packageName, options = {}) { diff --git a/packages/core/templates/en-US/hooks/f2s-update-check.js b/packages/core/templates/en-US/hooks/f2s-update-check.js index 3f390a3..9b6960e 100644 --- a/packages/core/templates/en-US/hooks/f2s-update-check.js +++ b/packages/core/templates/en-US/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — checks for version updates on the first conversation each day. * Compares the local knowledge-base manifest-routing.json version with the latest npm version: * - Same or local is newer -> exit silently - * - Behind -> inject one notice into Agent context (suggest running f2s-kb-upgrade) + * - Behind -> inject a notice into Agent context (the agent may run flow2spec init directly; use f2s-kb-upgrade only for topic-layer changes) * If already checked and no upgrade is needed, stay silent; if already checked and an upgrade is still needed, keep injecting the reminder in each new session. * Written by flow2spec init to the corresponding agent's hooks/f2s-update-check.js. */ @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] The current project "${getProjectName()}" knowledge-base version is v${manifestVersion}, which is lower than the latest package version v${latestNpm}. You can run the f2s-kb-upgrade skill to align templates and routing.`; + const userMsg = `📦 [flow2spec] The current project "${getProjectName()}" knowledge-base version is v${manifestVersion}, which is lower than the latest package version v${latestNpm}. I can run flow2spec init on your behalf to complete the update; if this update includes topic-layer changes, run the full f2s-kb-upgrade flow afterwards.`; return [ `[flow2spec/agent-instruction] At the start of this response, you must relay the following upgrade notice to the user verbatim. Do not omit it or skip it after only internal judgment:`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] After relaying, you may directly run \`flow2spec init \` on the user's behalf to complete the update; the user does not need to run f2s-kb-upgrade manually. After init succeeds, read .Knowledge/manifest-routing.json: if projectRev equals pkgRev (a non-topic version update), the update is complete — delete .Knowledge/update-check.json; if they differ (the update includes topic-layer changes), continue with the full f2s-kb-upgrade skill flow (you may start from its step 2c without re-running init).`, ].join('\n'); } diff --git a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md index 0d01fa3..928bdeb 100644 --- a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md @@ -97,15 +97,15 @@ Each initialized client uses its own startup/update mechanism when supported; th **Rule-layer fallback check** (backup for script cache): 1. Read `flow2spec.config.json` -> if `updateCheck.enabled` is not `true`, skip and show no notice. -2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is the same local calendar day as today (`new Date(checkedAt).toDateString() === new Date().toDateString()`), do not check npm again. However, if `needsUpgrade=true` or `latestNpm > manifestVersion`, the first user reply in this session must still remind the user to run `f2s-kb-upgrade`; if the current `.Knowledge/manifest-routing.json.version` is already no lower than `latestNpm`, delete that cache and stop reminding. +2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is the same local calendar day as today (`new Date(checkedAt).toDateString() === new Date().toDateString()`), do not check npm again. However, if `needsUpgrade=true` or `latestNpm > manifestVersion`, the first user reply in this session must still relay the upgrade notice, and the agent may **directly run** `flow2spec init ` on the user's behalf to complete the update — after init, read `.Knowledge/manifest-routing.json`: if `projectRev` equals `pkgRev` (a non-topic version update), the update is complete, delete the cache; if they differ (topic-layer changes included), run the full `f2s-kb-upgrade` flow (starting from its step 2c, without re-running init). If the current `.Knowledge/manifest-routing.json.version` is already no lower than `latestNpm`, delete that cache and stop reminding. 3. If neither of the two steps above skipped the check: run the update-check script under the current agent configuration root (Claude: `node .claude/hooks/f2s-update-check.js`; Cursor: `node .cursor/hooks/f2s-update-check.js`; Codex: `node .codex/hooks/f2s-update-check.js`) and parse JSON from stdout: - - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content (suggest running the `f2s-kb-upgrade` skill). + - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content and follow its agent-instruction (for non-topic version updates the agent may run `flow2spec init` directly; run the `f2s-kb-upgrade` skill only for topic-layer changes). - If there is no output or parsing fails: stay silent. 4. If any step errors, silently skip it and do not affect normal conversation. ## Topic Authoring Pointer -When adding or modifying `.Knowledge/topics/.md`, adjusting `manifest-routing.topicDependencies`, or deleting / migrating topics, the **authoring-side** guideline uses **`rules/f2s-topic-authoring.*`** as the single source of truth (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`). This entry is the **consumption side** (how to route / read / fall back using existing topics), and both coexist; in hard conflicts, this unified entry wins. `f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` must Read that full rule before any topic write. +When adding or modifying `.Knowledge/topics/.md`, adjusting `manifest-routing.topicDependencies`, or deleting / migrating topics, the **authoring-side** guideline uses **`rules/f2s-topic-authoring.*`** as the single source of truth (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`). This entry is the **consumption side** (how to route / read / fall back using existing topics), and both coexist; in hard conflicts, this unified entry wins. `f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` must Read that full rule before any topic write. ## Prohibited diff --git a/packages/core/templates/en-US/rules/f2s-intent-routing.md b/packages/core/templates/en-US/rules/f2s-intent-routing.md index 9704f97..229871d 100644 --- a/packages/core/templates/en-US/rules/f2s-intent-routing.md +++ b/packages/core/templates/en-US/rules/f2s-intent-routing.md @@ -39,7 +39,6 @@ When the user input **clearly triggers** one of the following operational intent | 新增规则、口述规则、把这条记到知识库; add rule, spoken rule, record this in the KB | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文; generate project context, generate context from final draft | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突; merge context conflict, resolve KB conflict | `f2s-kb-merge` | -| 知识库迁移、旧版迁移; knowledge-base migration, legacy migration | `f2s-kb-migrate` | | 删除项目上下文; delete project context | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移; KB template upgrade, KB upgrade, one-click upgrade migration | `f2s-kb-upgrade` | | 项目架构说明、架构初稿; project architecture description, architecture draft | `f2s-doc-arch` | diff --git a/packages/core/templates/en-US/rules/f2s-topic-authoring.md b/packages/core/templates/en-US/rules/f2s-topic-authoring.md index b55d726..61ecb62 100644 --- a/packages/core/templates/en-US/rules/f2s-topic-authoring.md +++ b/packages/core/templates/en-US/rules/f2s-topic-authoring.md @@ -16,7 +16,7 @@ This rule is touched when any of the following is true: - Add, delete, or adjust `manifest-routing.topicMetadata`; - Add, delete, or adjust dependency edges in `manifest-routing.topicDependencies`; - Add a reference to a topic id in `taskToTopicRules[].topics`; -- Delete or migrate a topic (`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`). +- Delete or migrate a topic (`f2s-kb-rm` / `f2s-kb-upgrade`). ## 1. Topic Naming diff --git a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md index 9133c8d..6a0f366 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow branch** must run f2s-kb-migrate first, then run flow2spec init inside the workflow; **current repositories (flow branch V2+, including Flow2Spec npm v3.x projects already using .Knowledge)** run init to align manifest-routing + matcher shards (package `manifest-matchers.json` is only an init merge seed and is not written into .Knowledge). Triggers: f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级、upgrade knowledge base、template upgrade. Note: do not call standalone flow2spec init an "upgrade command"; **V1/V2+ are flow-branch labels inside this skill, not npm package major versions**. +description: Knowledge-base template upgrade skill (this SKILL only): **current repositories (flow branch V2+, including Flow2Spec npm v3.x projects already using .Knowledge)** run init to align manifest-routing + matcher shards (package `manifest-matchers.json` is only an init merge seed and is not written into .Knowledge); **non-topic version updates** (projectRev == pkgRev after init) can be completed by the agent directly running flow2spec init, without entering this skill's full flow; **legacy layouts (flow branch V1) no longer have built-in migration support** (f2s-kb-migrate has been removed from the package). Triggers: f2s-kb-upgrade、旧项目升级、知识库模板升级、upgrade knowledge base、template upgrade. Note: do not call standalone flow2spec init an "upgrade command"; **V1/V2+ are flow-branch labels inside this skill, not npm package major versions**. --- > Execution scope: this skill is used to "run shell for the user" to complete Flow2Spec **template and configuration-root alignment as defined by this SKILL**. One step runs **`flow2spec init`**, but **`init` is not an "upgrade command"**. **Upgrade command / knowledge-base upgrade** refers only to the **full `f2s-kb-upgrade` workflow**. @@ -44,7 +44,7 @@ description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow - The meaning of `subAgent` / `switchAgentVerification` uses the unified entry as the only source of truth: **Cursor/Claude** read the configuration-root `rules/f2s-flow2spec-unified-entry.*`; **Codex** reads `.codex/topics/f2s-flow2spec-unified-entry.md` (same source, mirrored by `flow2spec init`). This section does not repeat those definitions. - **Sub-agent responsibility** (only when `subAgent=true`): run shell commands such as `flow2spec init`; only command execution is delegated, not knowledge-base body writing. - **Main agent must control** (must not delegate): - 1. **Version branching**: **V1** runs `f2s-kb-migrate` first, then enters this skill; **current repositories (V2+)** directly enter the `init` flow (including Flow2Spec **npm v3.x** etc.; as long as step 0 "current repository" conditions are met, use this branch. **Do not** create a separate flow just because the package major version is 3). + 1. **Version branching**: **V1 (legacy layout)** no longer supports automatic migration — on a hit, stop this skill and tell the user how to proceed (see step 0); **current repositories (V2+)** directly enter the `init` flow (including Flow2Spec **npm v3.x** etc.; as long as step 0 "current repository" conditions are met, use this branch. **Do not** create a separate flow just because the package major version is 3). 2. **Re-read after `init`**: re-read `f2s-kb-upgrade/SKILL.md` from disk and compare whether the identifier changed. 3. **Rerun the whole skill**: when SKILL changed, rerun from the beginning according to the new literal text until two consecutive rounds show no changes. 4. **Step 3b merge**: preserve the maintained section of `.Knowledge/index.md` and merge with the package version; main agent performs this. @@ -52,15 +52,20 @@ description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow - **Write-authority hard rule**: `.Knowledge/index.md` is **written only by the main agent**; sub-agents **must not touch it**. `manifest-routing.json` is also written by main. - This SKILL does not bind cross-agent verification; the writing side verifies its own work. -## Why this coexists with `f2s-kb-migrate` +## Non-topic version updates: the agent may run `init` directly (no need to enter this skill) -| Skill | Problem solved | -| --- | --- | -| **`f2s-kb-migrate`** | **Structural move**: `docs-index.md` / `index-doc.md`, `rules/main.md(c)`, business `skills/`, scattered `stock-docs`/`req-docs` -> **migrate into `.Knowledge`**, write `migration-report.md`, and confirm deletion list with the user. It does not run npm package upgrade. | -| **This skill `f2s-kb-upgrade`** | **Package and template alignment**: run **`flow2spec init`**, merge **`manifest-routing.json`** with **`matchers/*.json`**, refresh each agent's **`rules`/`skills`** (or Codex **`AGENTS.md`**); `init` also copies the current-language **`index.md` -> `.Knowledge/template/index.template.md`** as a comparison snapshot. **`.Knowledge/index.md`** is diff-aligned in step 3b; init **does not** automatically change its body. | +When the version check reports "knowledge-base version is lower than the latest package version", the agent may **directly run** `flow2spec init ` on the user's behalf to complete the update: -- **One-click closure for old projects**: **first `f2s-kb-migrate`** -> **then this skill** (`init`). Do not use only `init` as a substitute for full migration. -- **Projects already using new `.Knowledge`**: **run only this skill**; do not repeat migrate. +- After `init`, read the project-side `.Knowledge/manifest-routing.json`: if `projectRev` **equals** `pkgRev` (a non-topic version update) -> the update is complete, delete `.Knowledge/update-check.json`, **no need to enter this skill**; +- If they **differ** (topic-layer changes included) -> enter this skill's full flow (judge from step 2c, without re-running `init`). +- This path uses the same judgment as this skill's step 2c "fast path"; when the user explicitly asks for a "full flow / reset", still execute this skill in full. + +## Legacy layouts (V1) no longer have built-in migration + +`f2s-kb-migrate` has been removed from the package; automatic migration of legacy knowledge organization is no longer supported. When step 0's V1 signals hit, this skill **stops** and tells the user two ways to proceed: + +1. Use a historical package version that still ships `f2s-kb-migrate` (npm `@double-coding/flow2spec@3.4.x` or earlier) to perform the one-time migration, then come back to the latest version and run this skill; +2. Manually move legacy rules, business skills, and scattered `stock-docs` / `req-docs` into the `.Knowledge` shape, then run this skill. **Why does each configured client directory have a same-named `SKILL.md`?** Each client only loads `skills/` under **its own configuration root**. `flow2spec init` writes the current-language skill content into the selected agent directories. @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **Naming note**: **"V1"** and **"current repository (V2+)"** below are **flow-branch labels inside this skill**. If the **npm package is v3.x, v4.x, ...** and the repository is already in `.Knowledge` + `manifest-routing` shape, still use the **"current repository (V2+)"** branch (only `init` alignment). **Do not** interpret the npm major version number as the literal "V2" here. -**V1 - Legacy knowledge organization (must migrate before init)** +**V1 - Legacy knowledge organization (built-in migration no longer available)** Hit **any** strong signal: - The configuration root still has **`docs-index.md` or `index-doc.md`**, and mostly still closes through **`rules/main.md` / `rules/main.mdc`**; or - Business **`stock-docs` / `req-docs`, rules, and business skills** are still mainly in the old configuration-root tree and are **not** stably under `.Knowledge`. -**Action**: first execute the full **`f2s-kb-migrate`** workflow (including `migration-report` and deletion-list confirmation), **then** enter steps 1-5 to execute `flow2spec init`. +**Action**: **stop this skill** and tell the user the two ways to proceed per "Legacy layouts (V1) no longer have built-in migration" above (one-time migration with a historical package version / manual move into `.Knowledge`); **do not** continue steps 1-5 on a V1 layout. **Current repository (V2+) - Already on `.Knowledge` + new routing (package/shape alignment only)** Both conditions are met: @@ -146,7 +151,7 @@ Both conditions are met: **Historical wording**: if the repository still has legacy single-file **`manifest.json`**, **do not** use it as the machine-readable source of truth; machine reading uses **`manifest-routing.json` + `matchers/*.json` pointed to by `matcherPath`**. `init` handles merge/backfill of shards with the template. -**Action**: directly enter steps 1-5; **no** migrate is needed unless the user explicitly asks to redo migration. +**Action**: directly enter steps 1-5. ### Step 1: Confirm `init` Mode Inside This Skill (Required) @@ -347,7 +352,7 @@ Output: ## Completion Self-Check 1. **Step -1** was performed: before entering step 0, **3 foreground probes** were run sequentially (`flow2spec --version` / `npm view ... version` / `npx` availability) and one of the A/B/C branches was determined. Only under B/C did an **independent sub-agent** get dispatched to run `npm i -g @double-coding/flow2spec@latest` in the background (fire-and-forget); under A **no upgrade action** was dispatched. Step 2's default command form was chosen accordingly (A → `flow2spec init`, B/C → `npx @latest init`); the summary clearly states the branch and version comparison. -2. **Step 0** was performed: V1 did not skip migrate, and **current repositories (V2+)** did not incorrectly run migrate. +2. **Step 0** was performed: on V1 the skill stopped and told the user how to proceed, and **current repositories (V2+)** entered the `init` flow normally. 3. **Before step 2** recorded the project-side `projectRev` (`projectRev`), and **after step 2 `init`** re-read `pkgRev` and executed **step 2c** judgment. 4. After **step 2 `init`**, **`f2s-kb-upgrade/SKILL.md`** was re-read: on full flow, a change must trigger **a rerun from step 2c per the new literal text** (**no second `init`**); on fast path, the loop can be skipped (see "init and skill self-update" / "fast-path exception"). 5. A shell command was actually executed, not only suggested. diff --git a/packages/core/templates/zh-CN/hooks/f2s-update-check.js b/packages/core/templates/zh-CN/hooks/f2s-update-check.js index 61785b8..2f6f4ed 100644 --- a/packages/core/templates/zh-CN/hooks/f2s-update-check.js +++ b/packages/core/templates/zh-CN/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。 * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本： * - 一致或本地更新 → 静默退出 - * - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade） + * - 落后 → 向 Agent 上下文注入提示（agent 可直接代跑 flow2spec init；主题层变更再走 f2s-kb-upgrade） * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。 * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。 */ @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。我可以直接代跑 flow2spec init 完成更新；若本次更新包含主题层变更，再走 f2s-kb-upgrade 完整流程。`; return [ `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] 转告后可直接替用户执行 \`flow2spec init <已初始化的 agents，如 claude cursor codex>\` 完成更新，无需用户手动执行 f2s-kb-upgrade。init 成功后读取 .Knowledge/manifest-routing.json：若 projectRev 与 pkgRev 相等（非主题版本更新），更新已完成，删除 .Knowledge/update-check.json；若两者不等（包含主题层变更），继续执行 f2s-kb-upgrade skill 完整流程（可从其步骤 2c 起，不必重复 init）。`, ].join('\n'); } diff --git a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md index 1d0e9b5..f28b98a 100644 --- a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md @@ -97,15 +97,15 @@ alwaysApply: true **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/packages/core/templates/zh-CN/rules/f2s-intent-routing.md b/packages/core/templates/zh-CN/rules/f2s-intent-routing.md index 869ef6a..7cb4fea 100644 --- a/packages/core/templates/zh-CN/rules/f2s-intent-routing.md +++ b/packages/core/templates/zh-CN/rules/f2s-intent-routing.md @@ -39,7 +39,6 @@ alwaysApply: true | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md b/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md index b2ac24b..e454ec9 100644 --- a/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md +++ b/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md @@ -15,7 +15,7 @@ alwaysApply: false - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md index 3cc064d..8b94ed1 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,15 +52,20 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 + +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 **为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** 各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 diff --git a/templates/en-US/hooks/f2s-update-check.js b/templates/en-US/hooks/f2s-update-check.js index 3f390a3..9b6960e 100644 --- a/templates/en-US/hooks/f2s-update-check.js +++ b/templates/en-US/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — checks for version updates on the first conversation each day. * Compares the local knowledge-base manifest-routing.json version with the latest npm version: * - Same or local is newer -> exit silently - * - Behind -> inject one notice into Agent context (suggest running f2s-kb-upgrade) + * - Behind -> inject a notice into Agent context (the agent may run flow2spec init directly; use f2s-kb-upgrade only for topic-layer changes) * If already checked and no upgrade is needed, stay silent; if already checked and an upgrade is still needed, keep injecting the reminder in each new session. * Written by flow2spec init to the corresponding agent's hooks/f2s-update-check.js. */ @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] The current project "${getProjectName()}" knowledge-base version is v${manifestVersion}, which is lower than the latest package version v${latestNpm}. You can run the f2s-kb-upgrade skill to align templates and routing.`; + const userMsg = `📦 [flow2spec] The current project "${getProjectName()}" knowledge-base version is v${manifestVersion}, which is lower than the latest package version v${latestNpm}. I can run flow2spec init on your behalf to complete the update; if this update includes topic-layer changes, run the full f2s-kb-upgrade flow afterwards.`; return [ `[flow2spec/agent-instruction] At the start of this response, you must relay the following upgrade notice to the user verbatim. Do not omit it or skip it after only internal judgment:`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] After relaying, you may directly run \`flow2spec init \` on the user's behalf to complete the update; the user does not need to run f2s-kb-upgrade manually. After init succeeds, read .Knowledge/manifest-routing.json: if projectRev equals pkgRev (a non-topic version update), the update is complete — delete .Knowledge/update-check.json; if they differ (the update includes topic-layer changes), continue with the full f2s-kb-upgrade skill flow (you may start from its step 2c without re-running init).`, ].join('\n'); } diff --git a/templates/en-US/rules/f2s-flow2spec-unified-entry.md b/templates/en-US/rules/f2s-flow2spec-unified-entry.md index 0d01fa3..928bdeb 100644 --- a/templates/en-US/rules/f2s-flow2spec-unified-entry.md +++ b/templates/en-US/rules/f2s-flow2spec-unified-entry.md @@ -97,15 +97,15 @@ Each initialized client uses its own startup/update mechanism when supported; th **Rule-layer fallback check** (backup for script cache): 1. Read `flow2spec.config.json` -> if `updateCheck.enabled` is not `true`, skip and show no notice. -2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is the same local calendar day as today (`new Date(checkedAt).toDateString() === new Date().toDateString()`), do not check npm again. However, if `needsUpgrade=true` or `latestNpm > manifestVersion`, the first user reply in this session must still remind the user to run `f2s-kb-upgrade`; if the current `.Knowledge/manifest-routing.json.version` is already no lower than `latestNpm`, delete that cache and stop reminding. +2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is the same local calendar day as today (`new Date(checkedAt).toDateString() === new Date().toDateString()`), do not check npm again. However, if `needsUpgrade=true` or `latestNpm > manifestVersion`, the first user reply in this session must still relay the upgrade notice, and the agent may **directly run** `flow2spec init ` on the user's behalf to complete the update — after init, read `.Knowledge/manifest-routing.json`: if `projectRev` equals `pkgRev` (a non-topic version update), the update is complete, delete the cache; if they differ (topic-layer changes included), run the full `f2s-kb-upgrade` flow (starting from its step 2c, without re-running init). If the current `.Knowledge/manifest-routing.json.version` is already no lower than `latestNpm`, delete that cache and stop reminding. 3. If neither of the two steps above skipped the check: run the update-check script under the current agent configuration root (Claude: `node .claude/hooks/f2s-update-check.js`; Cursor: `node .cursor/hooks/f2s-update-check.js`; Codex: `node .codex/hooks/f2s-update-check.js`) and parse JSON from stdout: - - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content (suggest running the `f2s-kb-upgrade` skill). + - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content and follow its agent-instruction (for non-topic version updates the agent may run `flow2spec init` directly; run the `f2s-kb-upgrade` skill only for topic-layer changes). - If there is no output or parsing fails: stay silent. 4. If any step errors, silently skip it and do not affect normal conversation. ## Topic Authoring Pointer -When adding or modifying `.Knowledge/topics/.md`, adjusting `manifest-routing.topicDependencies`, or deleting / migrating topics, the **authoring-side** guideline uses **`rules/f2s-topic-authoring.*`** as the single source of truth (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`). This entry is the **consumption side** (how to route / read / fall back using existing topics), and both coexist; in hard conflicts, this unified entry wins. `f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` must Read that full rule before any topic write. +When adding or modifying `.Knowledge/topics/.md`, adjusting `manifest-routing.topicDependencies`, or deleting / migrating topics, the **authoring-side** guideline uses **`rules/f2s-topic-authoring.*`** as the single source of truth (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`). This entry is the **consumption side** (how to route / read / fall back using existing topics), and both coexist; in hard conflicts, this unified entry wins. `f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` must Read that full rule before any topic write. ## Prohibited diff --git a/templates/en-US/rules/f2s-intent-routing.md b/templates/en-US/rules/f2s-intent-routing.md index 9704f97..229871d 100644 --- a/templates/en-US/rules/f2s-intent-routing.md +++ b/templates/en-US/rules/f2s-intent-routing.md @@ -39,7 +39,6 @@ When the user input **clearly triggers** one of the following operational intent | 新增规则、口述规则、把这条记到知识库; add rule, spoken rule, record this in the KB | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文; generate project context, generate context from final draft | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突; merge context conflict, resolve KB conflict | `f2s-kb-merge` | -| 知识库迁移、旧版迁移; knowledge-base migration, legacy migration | `f2s-kb-migrate` | | 删除项目上下文; delete project context | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移; KB template upgrade, KB upgrade, one-click upgrade migration | `f2s-kb-upgrade` | | 项目架构说明、架构初稿; project architecture description, architecture draft | `f2s-doc-arch` | diff --git a/templates/en-US/rules/f2s-topic-authoring.md b/templates/en-US/rules/f2s-topic-authoring.md index b55d726..61ecb62 100644 --- a/templates/en-US/rules/f2s-topic-authoring.md +++ b/templates/en-US/rules/f2s-topic-authoring.md @@ -16,7 +16,7 @@ This rule is touched when any of the following is true: - Add, delete, or adjust `manifest-routing.topicMetadata`; - Add, delete, or adjust dependency edges in `manifest-routing.topicDependencies`; - Add a reference to a topic id in `taskToTopicRules[].topics`; -- Delete or migrate a topic (`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`). +- Delete or migrate a topic (`f2s-kb-rm` / `f2s-kb-upgrade`). ## 1. Topic Naming diff --git a/templates/en-US/skills/f2s-kb-upgrade/SKILL.md b/templates/en-US/skills/f2s-kb-upgrade/SKILL.md index 9133c8d..6a0f366 100644 --- a/templates/en-US/skills/f2s-kb-upgrade/SKILL.md +++ b/templates/en-US/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow branch** must run f2s-kb-migrate first, then run flow2spec init inside the workflow; **current repositories (flow branch V2+, including Flow2Spec npm v3.x projects already using .Knowledge)** run init to align manifest-routing + matcher shards (package `manifest-matchers.json` is only an init merge seed and is not written into .Knowledge). Triggers: f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级、upgrade knowledge base、template upgrade. Note: do not call standalone flow2spec init an "upgrade command"; **V1/V2+ are flow-branch labels inside this skill, not npm package major versions**. +description: Knowledge-base template upgrade skill (this SKILL only): **current repositories (flow branch V2+, including Flow2Spec npm v3.x projects already using .Knowledge)** run init to align manifest-routing + matcher shards (package `manifest-matchers.json` is only an init merge seed and is not written into .Knowledge); **non-topic version updates** (projectRev == pkgRev after init) can be completed by the agent directly running flow2spec init, without entering this skill's full flow; **legacy layouts (flow branch V1) no longer have built-in migration support** (f2s-kb-migrate has been removed from the package). Triggers: f2s-kb-upgrade、旧项目升级、知识库模板升级、upgrade knowledge base、template upgrade. Note: do not call standalone flow2spec init an "upgrade command"; **V1/V2+ are flow-branch labels inside this skill, not npm package major versions**. --- > Execution scope: this skill is used to "run shell for the user" to complete Flow2Spec **template and configuration-root alignment as defined by this SKILL**. One step runs **`flow2spec init`**, but **`init` is not an "upgrade command"**. **Upgrade command / knowledge-base upgrade** refers only to the **full `f2s-kb-upgrade` workflow**. @@ -44,7 +44,7 @@ description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow - The meaning of `subAgent` / `switchAgentVerification` uses the unified entry as the only source of truth: **Cursor/Claude** read the configuration-root `rules/f2s-flow2spec-unified-entry.*`; **Codex** reads `.codex/topics/f2s-flow2spec-unified-entry.md` (same source, mirrored by `flow2spec init`). This section does not repeat those definitions. - **Sub-agent responsibility** (only when `subAgent=true`): run shell commands such as `flow2spec init`; only command execution is delegated, not knowledge-base body writing. - **Main agent must control** (must not delegate): - 1. **Version branching**: **V1** runs `f2s-kb-migrate` first, then enters this skill; **current repositories (V2+)** directly enter the `init` flow (including Flow2Spec **npm v3.x** etc.; as long as step 0 "current repository" conditions are met, use this branch. **Do not** create a separate flow just because the package major version is 3). + 1. **Version branching**: **V1 (legacy layout)** no longer supports automatic migration — on a hit, stop this skill and tell the user how to proceed (see step 0); **current repositories (V2+)** directly enter the `init` flow (including Flow2Spec **npm v3.x** etc.; as long as step 0 "current repository" conditions are met, use this branch. **Do not** create a separate flow just because the package major version is 3). 2. **Re-read after `init`**: re-read `f2s-kb-upgrade/SKILL.md` from disk and compare whether the identifier changed. 3. **Rerun the whole skill**: when SKILL changed, rerun from the beginning according to the new literal text until two consecutive rounds show no changes. 4. **Step 3b merge**: preserve the maintained section of `.Knowledge/index.md` and merge with the package version; main agent performs this. @@ -52,15 +52,20 @@ description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow - **Write-authority hard rule**: `.Knowledge/index.md` is **written only by the main agent**; sub-agents **must not touch it**. `manifest-routing.json` is also written by main. - This SKILL does not bind cross-agent verification; the writing side verifies its own work. -## Why this coexists with `f2s-kb-migrate` +## Non-topic version updates: the agent may run `init` directly (no need to enter this skill) -| Skill | Problem solved | -| --- | --- | -| **`f2s-kb-migrate`** | **Structural move**: `docs-index.md` / `index-doc.md`, `rules/main.md(c)`, business `skills/`, scattered `stock-docs`/`req-docs` -> **migrate into `.Knowledge`**, write `migration-report.md`, and confirm deletion list with the user. It does not run npm package upgrade. | -| **This skill `f2s-kb-upgrade`** | **Package and template alignment**: run **`flow2spec init`**, merge **`manifest-routing.json`** with **`matchers/*.json`**, refresh each agent's **`rules`/`skills`** (or Codex **`AGENTS.md`**); `init` also copies the current-language **`index.md` -> `.Knowledge/template/index.template.md`** as a comparison snapshot. **`.Knowledge/index.md`** is diff-aligned in step 3b; init **does not** automatically change its body. | +When the version check reports "knowledge-base version is lower than the latest package version", the agent may **directly run** `flow2spec init ` on the user's behalf to complete the update: -- **One-click closure for old projects**: **first `f2s-kb-migrate`** -> **then this skill** (`init`). Do not use only `init` as a substitute for full migration. -- **Projects already using new `.Knowledge`**: **run only this skill**; do not repeat migrate. +- After `init`, read the project-side `.Knowledge/manifest-routing.json`: if `projectRev` **equals** `pkgRev` (a non-topic version update) -> the update is complete, delete `.Knowledge/update-check.json`, **no need to enter this skill**; +- If they **differ** (topic-layer changes included) -> enter this skill's full flow (judge from step 2c, without re-running `init`). +- This path uses the same judgment as this skill's step 2c "fast path"; when the user explicitly asks for a "full flow / reset", still execute this skill in full. + +## Legacy layouts (V1) no longer have built-in migration + +`f2s-kb-migrate` has been removed from the package; automatic migration of legacy knowledge organization is no longer supported. When step 0's V1 signals hit, this skill **stops** and tells the user two ways to proceed: + +1. Use a historical package version that still ships `f2s-kb-migrate` (npm `@double-coding/flow2spec@3.4.x` or earlier) to perform the one-time migration, then come back to the latest version and run this skill; +2. Manually move legacy rules, business skills, and scattered `stock-docs` / `req-docs` into the `.Knowledge` shape, then run this skill. **Why does each configured client directory have a same-named `SKILL.md`?** Each client only loads `skills/` under **its own configuration root**. `flow2spec init` writes the current-language skill content into the selected agent directories. @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **Naming note**: **"V1"** and **"current repository (V2+)"** below are **flow-branch labels inside this skill**. If the **npm package is v3.x, v4.x, ...** and the repository is already in `.Knowledge` + `manifest-routing` shape, still use the **"current repository (V2+)"** branch (only `init` alignment). **Do not** interpret the npm major version number as the literal "V2" here. -**V1 - Legacy knowledge organization (must migrate before init)** +**V1 - Legacy knowledge organization (built-in migration no longer available)** Hit **any** strong signal: - The configuration root still has **`docs-index.md` or `index-doc.md`**, and mostly still closes through **`rules/main.md` / `rules/main.mdc`**; or - Business **`stock-docs` / `req-docs`, rules, and business skills** are still mainly in the old configuration-root tree and are **not** stably under `.Knowledge`. -**Action**: first execute the full **`f2s-kb-migrate`** workflow (including `migration-report` and deletion-list confirmation), **then** enter steps 1-5 to execute `flow2spec init`. +**Action**: **stop this skill** and tell the user the two ways to proceed per "Legacy layouts (V1) no longer have built-in migration" above (one-time migration with a historical package version / manual move into `.Knowledge`); **do not** continue steps 1-5 on a V1 layout. **Current repository (V2+) - Already on `.Knowledge` + new routing (package/shape alignment only)** Both conditions are met: @@ -146,7 +151,7 @@ Both conditions are met: **Historical wording**: if the repository still has legacy single-file **`manifest.json`**, **do not** use it as the machine-readable source of truth; machine reading uses **`manifest-routing.json` + `matchers/*.json` pointed to by `matcherPath`**. `init` handles merge/backfill of shards with the template. -**Action**: directly enter steps 1-5; **no** migrate is needed unless the user explicitly asks to redo migration. +**Action**: directly enter steps 1-5. ### Step 1: Confirm `init` Mode Inside This Skill (Required) @@ -347,7 +352,7 @@ Output: ## Completion Self-Check 1. **Step -1** was performed: before entering step 0, **3 foreground probes** were run sequentially (`flow2spec --version` / `npm view ... version` / `npx` availability) and one of the A/B/C branches was determined. Only under B/C did an **independent sub-agent** get dispatched to run `npm i -g @double-coding/flow2spec@latest` in the background (fire-and-forget); under A **no upgrade action** was dispatched. Step 2's default command form was chosen accordingly (A → `flow2spec init`, B/C → `npx @latest init`); the summary clearly states the branch and version comparison. -2. **Step 0** was performed: V1 did not skip migrate, and **current repositories (V2+)** did not incorrectly run migrate. +2. **Step 0** was performed: on V1 the skill stopped and told the user how to proceed, and **current repositories (V2+)** entered the `init` flow normally. 3. **Before step 2** recorded the project-side `projectRev` (`projectRev`), and **after step 2 `init`** re-read `pkgRev` and executed **step 2c** judgment. 4. After **step 2 `init`**, **`f2s-kb-upgrade/SKILL.md`** was re-read: on full flow, a change must trigger **a rerun from step 2c per the new literal text** (**no second `init`**); on fast path, the loop can be skipped (see "init and skill self-update" / "fast-path exception"). 5. A shell command was actually executed, not only suggested. diff --git a/templates/zh-CN/hooks/f2s-update-check.js b/templates/zh-CN/hooks/f2s-update-check.js index 61785b8..2f6f4ed 100644 --- a/templates/zh-CN/hooks/f2s-update-check.js +++ b/templates/zh-CN/hooks/f2s-update-check.js @@ -4,7 +4,7 @@ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。 * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本： * - 一致或本地更新 → 静默退出 - * - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade） + * - 落后 → 向 Agent 上下文注入提示（agent 可直接代跑 flow2spec init；主题层变更再走 f2s-kb-upgrade） * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。 * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。 */ @@ -41,11 +41,13 @@ function getProjectName() { } function buildNotice(latestNpm, manifestVersion) { - const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`; + const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。我可以直接代跑 flow2spec init 完成更新；若本次更新包含主题层变更，再走 f2s-kb-upgrade 完整流程。`; return [ `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`, ``, userMsg, + ``, + `[flow2spec/agent-instruction] 转告后可直接替用户执行 \`flow2spec init <已初始化的 agents，如 claude cursor codex>\` 完成更新，无需用户手动执行 f2s-kb-upgrade。init 成功后读取 .Knowledge/manifest-routing.json：若 projectRev 与 pkgRev 相等（非主题版本更新），更新已完成，删除 .Knowledge/update-check.json；若两者不等（包含主题层变更），继续执行 f2s-kb-upgrade skill 完整流程（可从其步骤 2c 起，不必重复 init）。`, ].join('\n'); } diff --git a/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md b/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md index 1d0e9b5..f28b98a 100644 --- a/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md +++ b/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md @@ -97,15 +97,15 @@ alwaysApply: true **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须转告升级提示，并可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新——init 后读 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` 相等（非主题版本更新）即完成并删除该缓存；不等（含主题层变更）再执行 `f2s-kb-upgrade` 完整流程（可从其步骤 2c 起，不重复 init）；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： - - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容，并按其中 agent-instruction 执行（非主题版本更新可直接代跑 `flow2spec init`；主题层变更再执行 `f2s-kb-upgrade` skill）。 - 无输出或解析失败：静默，不提示。 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 ## 主题创作（Topic Authoring）指针 -新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 ## 禁止项 diff --git a/templates/zh-CN/rules/f2s-intent-routing.md b/templates/zh-CN/rules/f2s-intent-routing.md index 869ef6a..7cb4fea 100644 --- a/templates/zh-CN/rules/f2s-intent-routing.md +++ b/templates/zh-CN/rules/f2s-intent-routing.md @@ -39,7 +39,6 @@ alwaysApply: true | 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | | 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | | 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | -| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | | 删除项目上下文 | `f2s-kb-rm` | | 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | | 项目架构说明、架构初稿 | `f2s-doc-arch` | diff --git a/templates/zh-CN/rules/f2s-topic-authoring.md b/templates/zh-CN/rules/f2s-topic-authoring.md index b2ac24b..e454ec9 100644 --- a/templates/zh-CN/rules/f2s-topic-authoring.md +++ b/templates/zh-CN/rules/f2s-topic-authoring.md @@ -15,7 +15,7 @@ alwaysApply: false - 新增、删除或调整 `manifest-routing.topicMetadata`； - 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； - 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； -- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-upgrade`）。 ## 1. topic 命名 diff --git a/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md b/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md index 3cc064d..8b94ed1 100644 --- a/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md +++ b/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: f2s-kb-upgrade -description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +description: 知识库模板升级技能（仅指本 SKILL）：**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）；**非主题版本更新**（init 后 projectRev == pkgRev）可由 agent 直接代跑 flow2spec init 完成，无需进入本技能完整流程；**旧版布局（流程分流 V1）已不再内置迁移支持**（f2s-kb-migrate 已随包移除）。触发：f2s-kb-upgrade、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 --- > 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 @@ -44,7 +44,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 - **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 - **主必控**（主 agent 不可下放）： - 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 1. **版本分流**：**V1（旧版布局）** 已不再支持自动迁移，命中即停止本技能并告知用户处理方式（见步骤 0）；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 @@ -52,15 +52,20 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 - 本 SKILL 不绑定交叉校验；落盘侧自验。 -## 与 `f2s-kb-migrate` 为何并存 +## 非主题版本更新：agent 可直接代跑 `init`（无需进入本技能） -| 技能 | 解决的问题 | -| --- | --- | -| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | -| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | +版本检查提示「知识库版本低于最新包版本」时，agent 可**直接替用户执行** `flow2spec init <已初始化的 agents>` 完成更新： -- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 -- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 +- `init` 后读项目侧 `.Knowledge/manifest-routing.json`：`projectRev` 与 `pkgRev` **相等**（非主题版本更新）→ 更新完成，删除 `.Knowledge/update-check.json`，**无需进入本技能**； +- 两者**不等**（包含主题层变更）→ 进入本技能完整流程（从步骤 2c 起判定，不重复 `init`）。 +- 该路径与本技能步骤 2c「快速路径」同一判定口径；用户显式要求「完整流程 / 覆盖重置」时仍按本技能全文执行。 + +## 旧版布局（V1）不再内置迁移 + +`f2s-kb-migrate` 已随包移除，旧版知识组织的自动迁移不再兼容。命中步骤 0 的 V1 信号时，本技能**停止执行**并告知用户两种处理方式： + +1. 使用仍内置 `f2s-kb-migrate` 的历史版本包（npm `@double-coding/flow2spec@3.4.x` 及更早）完成一次性迁移，再回到最新版本跑本技能； +2. 手动将旧版规则、业务 skills、散落的 `stock-docs` / `req-docs` 迁入 `.Knowledge` 形态后，再跑本技能。 **为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** 各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 @@ -130,13 +135,13 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 -**V1 — 旧版知识组织（须先迁移再 init）** +**V1 — 旧版知识组织（不再内置迁移）** 命中**任一**强信号则按 V1： - 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 - 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 -**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 +**动作**：**停止本技能**，按上文「旧版布局（V1）不再内置迁移」告知用户两种处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`）；**不得**在 V1 布局上继续步骤 1–5。 **现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** 同时满足： @@ -146,7 +151,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ **历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 -**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 +**动作**：直接进入步骤 1–5。 ### 步骤 1：确认本技能内 `init` 模式（必须） @@ -347,7 +352,7 @@ command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ ## 完成后自检 1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 -2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 5. 是否已实际执行 shell 命令（而非只给建议）。 From 2dea8df77a118a0c5181e6a512dedc15e34621f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Mon, 24 Aug 2026 16:23:34 +0800 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=94=A7=20chore(release):=20bump=20to?= =?UTF-8?q?=203.5.0=EF=BC=8C=E5=90=8C=E6=AD=A5=20docs=20=E4=B8=8E=20KB=20c?= =?UTF-8?q?ore-package=20topic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - workspace / core / cli / manifest 版本 3.4.1 → 3.5.0（含 lockfile 与四处 manifest-routing） - docs zh/en 各 4 份：删除 f2s-kb-migrate 章节与速查表行，upgrade 章节改写为「非主题更新直 init / V1 停技能」新口径；.Knowledge/stock-docs 终稿同步 - KB 新增 topic flow2spec-core-package（含 matcher / manifest / index 路由），记录 core 包三层职责与 CLI/legacy shim 消费关系 Co-Authored-By: Claude Fable 5 --- .Knowledge/index.md | 1 + .Knowledge/manifest-routing.json | 17 ++++++- .../matchers/m-flow2spec-core-package.json | 17 +++++++ ...4\346\230\216_\347\273\210\347\250\277.md" | 4 +- .Knowledge/topics/flow2spec-core-package.md | 27 ++++++++++ docs/en/architecture.md | 2 +- docs/en/commands-reference.md | 43 ++-------------- docs/en/directory-conventions.md | 2 +- docs/en/usage-guide.md | 7 +-- ...73\344\270\216\345\216\237\347\220\206.md" | 2 +- ...77\347\224\250\350\257\264\346\230\216.md" | 7 +-- ...75\344\273\244\350\257\264\346\230\216.md" | 50 ++----------------- ...57\345\276\204\347\272\246\345\256\232.md" | 2 +- package-lock.json | 13 +++-- package.json | 5 +- packages/cli/package.json | 4 +- packages/core/package.json | 2 +- .../en-US/knowledge/manifest-routing.json | 2 +- .../zh-CN/knowledge/manifest-routing.json | 2 +- .../en-US/knowledge/manifest-routing.json | 2 +- .../zh-CN/knowledge/manifest-routing.json | 2 +- 21 files changed, 99 insertions(+), 114 deletions(-) create mode 100644 .Knowledge/matchers/m-flow2spec-core-package.json create mode 100644 .Knowledge/topics/flow2spec-core-package.md diff --git a/.Knowledge/index.md b/.Knowledge/index.md index a4a9f01..f96a46f 100644 --- a/.Knowledge/index.md +++ b/.Knowledge/index.md @@ -39,6 +39,7 @@ | flow2spec-init-defaults | `.Knowledge/topics/f2s-init-defaults.md` | `flow2spec init` 字段默认值、四处落点一致性、老项目缺字段补写、`init` 不动 stock/req/topics/matchers、manifest 两个版本字段（`projectRev` / `pkgRev`）对照 | 包源码：`lib/flow2specConfig.js` `DEFAULTS` / `CONFIG_FIELDS`；模板：`templates/{locale}/flow2spec.config.json` | | flow2spec-doctor | `.Knowledge/topics/flow2spec-doctor.md` | `flow2spec doctor` 只读检查环境、项目初始化、协作上下文与知识库健康 | stock：[Doctor 诊断命令](stock-docs/Flow2Spec-doctor诊断命令.md)；中英文命令文档：`docs/命令说明.md` / `docs/en/commands-reference.md` | | flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh`、DeepSeek Harness 项目技能发现与 `.dsh/` 目录适配 | 用户文档：`docs/使用说明.md` / `docs/en/usage-guide.md`；实现：`lib/dshAgentsAdapter.js` | +| flow2spec-core-package | `.Knowledge/topics/flow2spec-core-package.md` | `@double-coding/flow2spec-core` 职责边界：核心实现、发包模板真源、原生插件 API 与 CLI/legacy shim 消费关系 | 开发者文档：`packages/core/README.md`；入口：`packages/core/index.js` | 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`；**`f2s-kb-feedback-closing`** 在 cases 1–3 建议执行 **`f2s-kb-distill`**。 diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index 37f3cdf..98b9452 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.4.1", + "version": "3.5.0", "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", "sourceOfTruth": ".Knowledge/manifest-routing.json", @@ -32,7 +32,8 @@ "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md", - "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md" + "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md", + "flow2spec-core-package": ".Knowledge/topics/flow2spec-core-package.md" }, "taskToTopicRules": [ { @@ -163,6 +164,14 @@ "topics": [ "flow2spec-doctor" ] + }, + { + "task": "flow2spec-core-package", + "matcherId": "m-flow2spec-core-package", + "matcherPath": ".Knowledge/matchers/m-flow2spec-core-package.json", + "topics": [ + "flow2spec-core-package" + ] } ], "projectRev": 2, @@ -250,6 +259,10 @@ "tags": [ "module" ] + }, + "flow2spec-core-package": { + "primary": "module", + "confidence": "inferred" } } } diff --git a/.Knowledge/matchers/m-flow2spec-core-package.json b/.Knowledge/matchers/m-flow2spec-core-package.json new file mode 100644 index 0000000..f279b76 --- /dev/null +++ b/.Knowledge/matchers/m-flow2spec-core-package.json @@ -0,0 +1,17 @@ +{ + "includeAny": [ + "flow2spec-core", + "core 包", + "包结构", + "workspace 包", + "包拆分", + "原生插件 API", + "createFlow2Spec", + "legacy shim", + "模板真源", + "CLI 依赖 core" + ], + "id": "m-flow2spec-core-package", + "version": "1.0.0", + "schema": "flow2spec.matcher.v1" +} diff --git "a/.Knowledge/stock-docs/flow2spec\346\236\266\346\236\204\350\257\264\346\230\216_\347\273\210\347\250\277.md" "b/.Knowledge/stock-docs/flow2spec\346\236\266\346\236\204\350\257\264\346\230\216_\347\273\210\347\250\277.md" index 29b7179..b1695fe 100644 --- "a/.Knowledge/stock-docs/flow2spec\346\236\266\346\236\204\350\257\264\346\230\216_\347\273\210\347\250\277.md" +++ "b/.Knowledge/stock-docs/flow2spec\346\236\266\346\236\204\350\257\264\346\230\216_\347\273\210\347\250\277.md" @@ -87,8 +87,8 @@ | 全局同步已实现能力 | `f2s-kb-sync` | | 从 stock-docs 生成主题路由（含拆分评估） | `f2s-kb-build`（stock-doc > 300–500 行或覆盖 3+ 职责域时提示拆分） | | 解决合并后上下文冲突 | `f2s-kb-merge` | -| 知识库模板升级 | `f2s-kb-upgrade`（其中一步代跑 `npx @double-coding/flow2spec@latest init`，或已全局安装时的 `flow2spec init`） | -| 旧版一次性迁移 | `f2s-kb-migrate` | +| 知识库模板升级 | `f2s-kb-upgrade`（其中一步代跑 `npx @double-coding/flow2spec@latest init`，或已全局安装时的 `flow2spec init`）；非主题版本更新（init 后 `projectRev == pkgRev`）可由 agent 直接代跑 `flow2spec init` 完成，无需进入该技能完整流程 | +| 旧版一次性迁移 | 不再内置（`f2s-kb-migrate` 已随包移除）；用历史版本包（`@3.4.x` 及更早）一次性迁移或手动迁入 `.Knowledge` | ### 流程五：任务路由与执行（`match → expand → verify → act`） diff --git a/.Knowledge/topics/flow2spec-core-package.md b/.Knowledge/topics/flow2spec-core-package.md new file mode 100644 index 0000000..381872a --- /dev/null +++ b/.Knowledge/topics/flow2spec-core-package.md @@ -0,0 +1,27 @@ +--- +id: flow2spec-core-package +revision: 0 +summary: "@double-coding/flow2spec-core 的职责边界：核心实现、发包模板真源与原生插件 API" +primary: module +confidence: inferred +--- +# Flow2Spec Core 包（@double-coding/flow2spec-core） + +## 适用场景 + +回答或维护 npm workspace 包结构、`flow2spec-core` 的职责、CLI 与 core 的依赖关系、原生插件 API、发包模板真源位置、根目录 legacy shim。 + +## 核心事实 + +- workspace 三层：根 `flow2spec-workspace`（private）+ `packages/core`（`@double-coding/flow2spec-core`）+ `packages/cli`（`@double-coding/flow2spec`）；三者版本保持一致，CLI 对 core 的依赖固定为同一版本。 +- **core 承载全部核心实现**（`packages/core/lib/`）：`init` 落盘引擎、各端适配器（`claudeRulesAdapter` / `claudeSettingsAdapter` / `codexAgentsAdapter` / `dshAgentsAdapter`）、知识库引擎与路由（`knowledgeEngine` / `routing`）、`updateCheck`、`doctor`、`developerId`、`flow2specConfig`、`resources`。 +- **npm 发布的模板真源**在 `packages/core/templates/{zh-CN,en-US}/`（`package.json` 的 `files` 含 `templates`）；根 `templates/` 是本仓同步副本，模板改动须双根同步（写盘边界见 `f2s-dev-workflow-constraints`）。 +- **原生插件 API**：`createFlow2Spec({ cwd })` 暴露 `resources.skillCatalog()`（宿主适配的结构化 Skill 清单）、`resources.unifiedEntry()`（宿主适配的统一入口）、`update.check()`（复用 `.Knowledge/update-check.json` 每日缓存）；`capabilities.json` 的 `protocolVersion` 供插件启动时做兼容校验；`index.d.ts` 导出完整公共契约类型。 +- **CLI 是薄壳**：`packages/cli/cli.js` 只做命令行解析并转调 core；根 `cli.js` 一行转发 `require("./packages/cli/cli.js")`。 +- **根 `lib/*.js` 为 legacy shim**：逐文件 `module.exports = require("@double-coding/flow2spec-core").legacy.`，仅保留拆包前旧引用路径的兼容。 +- 普通用户只装 CLI 或原生插件（如 DeepSeek Harness 的 `@double-coding/flow2spec-deepseek-harness`），core 作为依赖按锁定版本自动带上。 + +## 边界与注意 + +- 本仓开发态下 `packages/cli` → core 的模块解析依赖根 `node_modules/@double-coding/` 的 workspace 软链；fresh clone 或拆包合入后未执行 `npm install` 时会报 `Cannot find module '@double-coding/flow2spec-core'`。下游 npm 安装不受影响（`scripts/test-package-install.js` 从 tarball 真装验证）。 +- `packages/core/README.md` 面向 CLI 与原生插件开发者独立维护；`packages/cli/README.md` 必须与根 `README.md` 完全一致（发布门禁见 `f2s-dev-workflow-constraints`）。 diff --git a/docs/en/architecture.md b/docs/en/architecture.md index 77996ae..732d8ca 100644 --- a/docs/en/architecture.md +++ b/docs/en/architecture.md @@ -79,7 +79,7 @@ Codex does not read the `rules/` directory; execution constraints are carried th - Maintenance chain: `f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge` - Requirements planning chain: `f2s-req-plan` (planning + implementation, always creates task checklist) - Change tracking chain: `changeTracking.*` config -> `f2s-task` rules (automatic) -> `.task/` task checklist -> cross-session continuation -- Package template/routing shape alignment with config root: `f2s-kb-upgrade` (**do not** equate running `flow2spec init` alone with "knowledge base upgrade"); migrate legacy repo structure into `.Knowledge`: `f2s-kb-migrate` +- Package template/routing shape alignment with config root: `f2s-kb-upgrade` (**do not** equate running `flow2spec init` alone with "knowledge base upgrade"; for non-topic version updates the agent may directly run `flow2spec init` to complete the alignment) The documentation curation chain produces two document types: diff --git a/docs/en/commands-reference.md b/docs/en/commands-reference.md index 05e197d..5152cbc 100644 --- a/docs/en/commands-reference.md +++ b/docs/en/commands-reference.md @@ -21,7 +21,6 @@ | `/f2s-kb-distill` | Extract reusable knowledge facts from Q&A and auto-commit to knowledge base | KB Maintenance | | `/f2s-kb-sync` | Sink implemented capabilities from the conversation into the knowledge base | KB Maintenance | | `/f2s-kb-merge` | Resolve knowledge base conflicts after a Git merge | KB Maintenance | -| `/f2s-kb-migrate` | One-time migration of a legacy knowledge base to `.Knowledge/` | KB Maintenance | | `/f2s-kb-upgrade` | Upgrade knowledge base template, align manifest + matchers shards | KB Maintenance | The table above lists conversation-triggered `/f2s-*` skills. The repository also provides shell commands: `flow2spec kb status / check / plan / apply / build` handles collaborative knowledge merges (see [§ 7](#7-flow2spec-kb-cli-for-collaborative-merges)), while `flow2spec doctor` performs a read-only project health check (see [§ 8](#8-flow2spec-doctor-project-health-check)). @@ -502,47 +501,11 @@ The table above lists conversation-triggered `/f2s-*` skills. The repository als --- -### `f2s-kb-migrate` - -**Purpose**: Migrates an old-format knowledge base (`docs-index.md` + `rules/` pattern) into the `.Knowledge/` structure organized by topic. - -**How It Works**: Uses the legacy `docs-index.md` and `rules/main.md(c)` as index clues, recursively finds all referenced business rules and skill files, and reorganizes by topic into `.Knowledge/` (`topics` / `stock-docs` / `req-docs`). After migration, persist `migration-report.md` (mapping table + proposed deletion paths), then clean up old files after user confirmation. A one-time structural merge of scattered rules/docs into one knowledge base. - -**Use Cases**: -- Upgrading an old project to the new Flow2Spec version -- An existing knowledge base needs structured reorganization - -**Relationships**: -- **Prerequisite**: Old-format knowledge base (`docs-index.md`, `rules/`, `skills/`) -- **Next Step**: `f2s-kb-upgrade` (**Flow V1**: old knowledge base must migrate first, then upgrade; **Current V2+ knowledge base** (including npm v3.x): see the upgrade skill Step 0) -- **Flow**: - 1. Use `docs-index.md` + `rules/main.md(c)` as the primary index - 2. Process all business `rules/` and business `skills/` in full (excluding `f2s-*` package skills) - 3. Migrate all `stock-docs`/`req-docs` - 4. Persist `.Knowledge/migration-report.md` - 5. Delete migrated old files after user confirmation - -**Sub-Agent Invocation**: -- `subAgent: false` (default): The main agent migrates topic by topic -- `subAgent: true`: Sub-agents only handle migration + draft migration-report fragments (delivered as patches); status files (migration-report.md, deletion execution records) are exclusively persisted by the main agent; the main agent leads the deletion confirmation and closure - -**Responsibility Matrix**: -| Role | Responsibilities | -|------|-----------------| -| Main Agent | Creates migration plan, consolidates migration results, persists migration-report, leads deletion confirmation and execution closure | -| Sub-Agent | Handles topic migration and draft fragment generation (patch format) for designated topics; does not write status files or deletion execution records | - -**Cross-Verification (when `switchAgentVerification: true`)**: -- Topics migrated and persisted by sub-agents -> Main agent verifies migration completeness (whether old paths are fully covered, whether topic boundaries overlap) -- Only effective when `subAgent: true` and sub-tasks are actually dispatched; otherwise all verification happens within the main agent - ---- - ### `f2s-kb-upgrade` **Purpose**: Knowledge base template upgrade. Aligns manifest-routing and matchers shards. -**How It Works**: Uses "version branching + delegated init" — detect whether the current knowledge base is V1 (legacy structure, migrate first) or V2+ (already has `.Knowledge`): V1 runs migrate then init; V2+ runs `flow2spec init` directly for incremental package alignment (new templates, manifest schema upgrades, matcher shard format alignment). After upgrade, re-read SKILL.md to see if certain steps must be re-run. Unlike a standalone `init`, `kb-upgrade` includes version routing and re-run logic; `init` alone is a one-shot structural fill-in. +**How It Works**: Uses "version branching + delegated init" — detect whether the current knowledge base is V1 (legacy structure) or V2+ (already has `.Knowledge`): V1 no longer has built-in migration support — the skill stops and tells the user how to proceed (one-time migration with a historical package version, or manual move into `.Knowledge`); V2+ runs `flow2spec init` directly for incremental package alignment (new templates, manifest schema upgrades, matcher shard format alignment). After upgrade, re-read SKILL.md to see if certain steps must be re-run. Unlike a standalone `init`, `kb-upgrade` includes version routing and re-run logic; `init` alone is a one-shot structural fill-in. For **non-topic version updates** (`projectRev == pkgRev` after init), the agent may directly run `flow2spec init` on the user's behalf without entering this skill's full flow. **Use Cases**: - After a `flow2spec` package version upgrade, upgrade the project knowledge base template @@ -552,12 +515,12 @@ The table above lists conversation-triggered `/f2s-*` skills. The repository als - When Codex detects an older knowledge-base version through `.codex/hooks.json` on `SessionStart`, it prompts you to execute this skill (new or changed hooks must be trusted through `/hooks` first) **Relationships**: -- **Prerequisite**: `f2s-kb-migrate` (V1 flow) or an existing `.Knowledge/` +- **Prerequisite**: an existing `.Knowledge/` (legacy V1 structures no longer have automatic migration support) - **Includes**: Internally invokes `flow2spec init` for structural alignment - **Note**: A standalone `flow2spec init` is **not** an upgrade command **Flow Differences (in-skill routing codes, **not** equivalent to npm major versions)**: -- **V1**: First `f2s-kb-migrate`, then runs `flow2spec init` +- **V1**: Built-in migration is no longer available; the skill stops and tells the user how to proceed (one-time migration with a historical package version / manual move into `.Knowledge`) - **Current Knowledge Base (V2+)**: When `.Knowledge` + `manifest-routing` are already stable, runs `flow2spec init` to align manifest-routing + matchers shards (**includes Flow2Spec npm v3.x, etc.**; see `skills/f2s-kb-upgrade/SKILL.md` Step 0 for details) **Sub-Agent Invocation**: diff --git a/docs/en/directory-conventions.md b/docs/en/directory-conventions.md index 9899a14..7657a48 100644 --- a/docs/en/directory-conventions.md +++ b/docs/en/directory-conventions.md @@ -23,7 +23,7 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings. | `.Knowledge/index.md` | Human-readable index | | `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`/`topicMetadata`) | | `.Knowledge/matchers/*.json` | **L1** Keyword fragments (`id/includeAny`); **match** reads one shard via `matcherPath` | -| `.Knowledge/migration-report.md` | Migration comparison table and deletion path list written by `f2s-kb-migrate` | +| `.Knowledge/migration-report.md` | Migration comparison table and deletion path list written by the historical `f2s-kb-migrate` skill (removed from the package; existing files may be kept) | | `.task/` | Local change-tracking state, ignored by Git by default. In collaboration mode it has an extra `/` layer; see “The two `.task/` layouts” below. It is created only when `changeTracking.*` is `true` or `f2s-req-plan` is explicitly invoked. | | `Config Root/rules/` | Rule files (Cursor `.mdc`, Claude `.md`) | | `Config Root/skills/` | Skill definitions (`SKILL.md`) | diff --git a/docs/en/usage-guide.md b/docs/en/usage-guide.md index 9fb8f53..47bc4c5 100644 --- a/docs/en/usage-guide.md +++ b/docs/en/usage-guide.md @@ -130,11 +130,12 @@ f2s-kb-merge # Resolve context conflicts after Git merges ### Cross-Version Knowledge Base Upgrade ``` -f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade -f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0) +Non-topic version update (projectRev == pkgRev after init): the agent runs flow2spec init directly — done +Topic-layer changes (projectRev != pkgRev): full f2s-kb-upgrade flow (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0) +Legacy layout (V1): built-in migration removed; use a historical package version (@3.4.x or earlier) for a one-time migration, or move into .Knowledge manually ``` -In interactive terminals, the Flow2Spec CLI checks the latest npm version with a cache when running `flow2spec version` / `flow2spec init`. If a newer version exists, it prompts you to run `flow2spec update`, then execute `f2s-kb-upgrade` in the Agent conversation to align the project knowledge templates, manifest/matchers, and agent config roots. Failed update checks are skipped silently and do not affect the current command; checks are disabled in `CI`, non-TTY sessions, or when `FLOW2SPEC_SKIP_UPDATE_CHECK=1` is set. +In interactive terminals, the Flow2Spec CLI checks the latest npm version with a cache when running `flow2spec version` / `flow2spec init`. If a newer version exists, it prompts you to run `flow2spec update`; for non-topic version updates the agent may directly run `flow2spec init` to complete the alignment, and only when the update includes topic-layer changes execute `f2s-kb-upgrade` in the Agent conversation to align the project knowledge templates, manifest/matchers, and agent config roots. Failed update checks are skipped silently and do not affect the current command; checks are disabled in `CI`, non-TTY sessions, or when `FLOW2SPEC_SKIP_UPDATE_CHECK=1` is set. After `flow2spec init codex`, Codex projects include `.codex/hooks.json`, `.codex/hooks/f2s-config-session.js`, and `.codex/hooks/f2s-update-check.js`. On Codex `SessionStart` for `startup|resume`, the first script injects one configuration summary and the second checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through `/hooks` in Codex. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip only the version check. diff --git "a/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" "b/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" index 927a398..10d75e4 100644 --- "a/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" +++ "b/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" @@ -81,7 +81,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并 - 维护链：`f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge` - 需求规划链：`f2s-req-plan`（规划 + 实现，始终创建任务清单） - 变更追踪链：`changeTracking.*` 配置 → `f2s-task` 规则（自动）→ `.task/` 任务清单 → 跨会话续作 -- 包模板/路由形态与配置根对齐：`f2s-kb-upgrade`（**勿**将单独 `flow2spec init` 等同于「知识库升级」）；旧库结构迁入 `.Knowledge`：`f2s-kb-migrate` +- 包模板/路由形态与配置根对齐：`f2s-kb-upgrade`（**勿**将单独 `flow2spec init` 等同于「知识库升级」；非主题版本更新可由 agent 直接代跑 `flow2spec init` 完成对齐） 文档沉淀链产出两类文档： diff --git "a/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" "b/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" index aa95884..e0b5c3d 100644 --- "a/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" +++ "b/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" @@ -117,11 +117,12 @@ f2s-kb-merge # Git 合并后解决上下文冲突 ### 知识库跨版本升级 ``` -f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade -f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0） +非主题版本更新（init 后 projectRev == pkgRev）：agent 直接代跑 flow2spec init 即完成 +主题层变更（projectRev != pkgRev）：f2s-kb-upgrade 完整流程（现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0） +旧版布局（流程 V1）：不再内置迁移；用历史版本包（@3.4.x 及更早）一次性迁移或手动迁入 .Knowledge ``` -Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会按缓存检查 npm 最新版本；若发现新版本，会提示先执行 `flow2spec update`，随后在 Agent 对话中执行 `f2s-kb-upgrade`，用于对齐项目知识库模板、manifest/matchers 与配置根产物。更新检查失败会静默跳过，不影响当前命令；`CI`、非 TTY 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时不检查。 +Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会按缓存检查 npm 最新版本；若发现新版本，会提示先执行 `flow2spec update`；非主题版本更新可由 agent 直接代跑 `flow2spec init` 完成对齐，仅当更新包含主题层变更时再在 Agent 对话中执行 `f2s-kb-upgrade`，用于对齐项目知识库模板、manifest/matchers 与配置根产物。更新检查失败会静默跳过，不影响当前命令；`CI`、非 TTY 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时不检查。 Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json`、`.codex/hooks/f2s-config-session.js` 与 `.codex/hooks/f2s-update-check.js`：前者在 Codex `SessionStart` 的 `startup|resume` 事件注入一次配置摘要，后者自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时仅跳过版本检查，不影响配置摘要注入。 diff --git "a/docs/\345\221\275\344\273\244\350\257\264\346\230\216.md" "b/docs/\345\221\275\344\273\244\350\257\264\346\230\216.md" index 07ef89a..749a052 100644 --- "a/docs/\345\221\275\344\273\244\350\257\264\346\230\216.md" +++ "b/docs/\345\221\275\344\273\244\350\257\264\346\230\216.md" @@ -21,7 +21,6 @@ | `/f2s-kb-distill` | 从问答过程中提取可复用知识事实并自动入库 | 知识库维护 | | `/f2s-kb-sync` | 将会话中已实现能力沉淀回知识库 | 知识库维护 | | `/f2s-kb-merge` | 解决 Git 合并后的知识库冲突 | 知识库维护 | -| `/f2s-kb-migrate` | 旧版知识库一次性迁移到 `.Knowledge/` | 知识库维护 | | `/f2s-kb-upgrade` | 知识库模板升级，对齐 manifest + matchers 分片 | 知识库维护 | 上表是聊天里触发的 `/f2s-*` 技能。仓库还带 shell CLI：`flow2spec kb status / check / plan / apply / build` 用于协作合库，见 [§ 7](#7-flow2spec-kb-cli协作合库)；`flow2spec doctor` 用于只读项目体检，见 [§ 8](#8-flow2spec-doctor项目体检)。 @@ -582,56 +581,13 @@ | 子 agent | 仅做冲突扫描与分类，按五字段 schema 交付对照表，不自行合并文件 | ---- - -### `f2s-kb-migrate` - -**作用**：将旧版知识库（`docs-index.md` + `rules/` 模式）按主题迁移到 `.Knowledge/` 结构。 - -**工作原理**：以旧版 `docs-index.md` 和 `rules/main.md(c)` 为「索引线索」，递归识别所有被引用的业务规则和技能文件，按主题粒度重新组织到 `.Knowledge/` 的 `topics/stock-docs/req-docs` 三层结构中。迁移完成后落盘 `migration-report.md`（对照表 + 拟删路径），待用户确认后清理旧文件。本质是一次性的结构重组，将分散的规则/文档归并为统一知识库。 - -**使用场景**： - -- 旧项目升级到 Flow2Spec 新版 -- 存量知识库需要结构化整理 - -**关联关系**： - -- **前置**：旧版知识库（`docs-index.md`、`rules/`、`skills/`） -- **后续**：`f2s-kb-upgrade`（**流程 V1** 旧库须先 migrate 再 upgrade；**现行库 V2+**（含 npm v3.x）见 upgrade 技能步骤 0） -- **流程**： - 1. 以 `docs-index.md` + `rules/main.md(c)` 为主索引 - 2. 全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-`* 包技能） - 3. 全量迁移 `stock-docs`/`req-docs` - 4. 落盘 `.Knowledge/migration-report.md` - 5. 用户确认后删除已迁旧的文件 - -**子 agent 调用**： - -- `subAgent: false`（默认）：主 agent 内逐主题迁移 -- `subAgent: true`：子只做搬运 + migration-report 草案片段（以 patch 形式交付）；状态文件（migration-report.md、删除执行记录）由主 agent 唯一落盘；主 agent 主导删除清单确认与删除闭环 - -**职责划分**： - - -| 角色 | 职责 | -| ------- | --------------------------------------------- | -| 主 agent | 制定迁移规划、合并迁移结果、落盘 migration-report、主导删除确认与执行闭环 | -| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录 | - - -**交叉验证（`switchAgentVerification: true` 时）**： - -- 子 agent 迁移落盘的主题 → 主 agent 校验迁移完整性（旧路径是否全量覆盖、主题边界是否重叠） -- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证 - --- ### `f2s-kb-upgrade` **作用**：知识库模板升级。对齐 manifest-routing + matchers 分片。 -**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构，需先 migrate）还是 V2+（已有 `.Knowledge`），V1 走 migrate 后再 init，V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐。 +**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构）还是 V2+（已有 `.Knowledge`）：V1 已不再内置迁移支持，技能停止并告知用户处理方式（用历史版本包一次性迁移，或手动迁入 `.Knowledge`）；V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐；**非主题版本更新**（init 后 `projectRev == pkgRev`）可由 agent 直接代跑 `flow2spec init` 完成，无需进入本技能完整流程。 **使用场景**： @@ -644,13 +600,13 @@ **关联关系**： -- **前置**：`f2s-kb-migrate`（V1 流程）或已存在的 `.Knowledge/` +- **前置**：已存在的 `.Knowledge/`（V1 旧结构不再支持自动迁移） - **包含**：内部会调用 `flow2spec init` 进行结构对齐 - **注意**：单独的 `flow2spec init` **不是**升级命令 **流程差异**（技能内分流代号，**不等于** npm 包主版本号）： -- **V1**：先 `f2s-kb-migrate` 再代跑 `flow2spec init` +- **V1**：不再内置迁移支持；技能停止并告知用户处理方式（历史版本包一次性迁移 / 手动迁入 `.Knowledge`） - **现行库（V2+）**：已稳定 `.Knowledge` + `manifest-routing` 时，代跑 `flow2spec init` 以对齐 manifest-routing + matchers 分片（**含 Flow2Spec npm v3.x 等**，详见 `skills/f2s-kb-upgrade/SKILL.md` 步骤 0） **子 agent 调用**： diff --git "a/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" "b/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" index 8553a8e..3440eed 100644 --- "a/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" +++ "b/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" @@ -23,7 +23,7 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。 | `.Knowledge/index.md` | 人类可读索引 | | `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`） | | `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 | -| `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 | +| `.Knowledge/migration-report.md` | 历史版本 `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表（该技能已移除，存量文件可保留） | | `.task/` | 变更追踪任务清单目录，本地运行态、默认进 `.gitignore`。多人协作时按 `/` 再分一层，两种形态见下文 §`.task/` 的两种形态。仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 | | `配置根/rules/` | 规则文件（Cursor `.mdc`，Claude `.md`） | | `配置根/skills/` | 技能定义（`SKILL.md`） | diff --git a/package-lock.json b/package-lock.json index b33acda..8bdf277 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,16 +1,19 @@ { "name": "flow2spec-workspace", - "version": "3.4.1", + "version": "3.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "flow2spec-workspace", - "version": "3.4.1", + "version": "3.5.0", "workspaces": [ "packages/core", "packages/cli" ], + "dependencies": { + "@double-coding/flow2spec-core": "^3.5.0" + }, "engines": { "node": ">=16" } @@ -25,10 +28,10 @@ }, "packages/cli": { "name": "@double-coding/flow2spec", - "version": "3.4.1", + "version": "3.5.0", "license": "ISC", "dependencies": { - "@double-coding/flow2spec-core": "3.4.1" + "@double-coding/flow2spec-core": "3.5.0" }, "bin": { "flow2spec": "cli.js" @@ -39,7 +42,7 @@ }, "packages/core": { "name": "@double-coding/flow2spec-core", - "version": "3.4.1", + "version": "3.5.0", "license": "ISC", "engines": { "node": ">=16" diff --git a/package.json b/package.json index e61ecd4..4cd9ca8 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "flow2spec-workspace", "private": true, - "version": "3.4.1", + "version": "3.5.0", "description": "Flow2Spec workspace for the Core library and CLI packages", "workspaces": [ "packages/core", @@ -18,5 +18,8 @@ "sync:package-readme": "node scripts/sync-package-readme.js", "pack:check": "node scripts/sync-package-readme.js --check && npm pack --workspace @double-coding/flow2spec-core --dry-run && npm pack --workspace @double-coding/flow2spec --dry-run", "tag:version": "node scripts/git-tag-version.js" + }, + "dependencies": { + "@double-coding/flow2spec-core": "^3.5.0" } } diff --git a/packages/cli/package.json b/packages/cli/package.json index cf2bfa2..758ae18 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@double-coding/flow2spec", - "version": "3.4.1", + "version": "3.5.0", "description": "在业务仓库初始化文档驱动、可写回知识库的 AI 协作骨架", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { @@ -20,7 +20,7 @@ "README.md" ], "dependencies": { - "@double-coding/flow2spec-core": "3.4.1" + "@double-coding/flow2spec-core": "3.5.0" }, "publishConfig": { "access": "public", diff --git a/packages/core/package.json b/packages/core/package.json index a866608..f2d7b64 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@double-coding/flow2spec-core", - "version": "3.4.1", + "version": "3.5.0", "description": "Flow2Spec Core APIs, knowledge engine, project initialization and shared resources", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { diff --git a/packages/core/templates/en-US/knowledge/manifest-routing.json b/packages/core/templates/en-US/knowledge/manifest-routing.json index b50c683..b2e80e3 100644 --- a/packages/core/templates/en-US/knowledge/manifest-routing.json +++ b/packages/core/templates/en-US/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.4.1", + "version": "3.5.0", "projectRev": 2, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", diff --git a/packages/core/templates/zh-CN/knowledge/manifest-routing.json b/packages/core/templates/zh-CN/knowledge/manifest-routing.json index b50c683..b2e80e3 100644 --- a/packages/core/templates/zh-CN/knowledge/manifest-routing.json +++ b/packages/core/templates/zh-CN/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.4.1", + "version": "3.5.0", "projectRev": 2, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", diff --git a/templates/en-US/knowledge/manifest-routing.json b/templates/en-US/knowledge/manifest-routing.json index b50c683..b2e80e3 100644 --- a/templates/en-US/knowledge/manifest-routing.json +++ b/templates/en-US/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.4.1", + "version": "3.5.0", "projectRev": 2, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", diff --git a/templates/zh-CN/knowledge/manifest-routing.json b/templates/zh-CN/knowledge/manifest-routing.json index b50c683..b2e80e3 100644 --- a/templates/zh-CN/knowledge/manifest-routing.json +++ b/templates/zh-CN/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.4.1", + "version": "3.5.0", "projectRev": 2, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId",