🐛 fix(kb): 非主题版本更新直接代跑 init，移除 f2s-kb-migrate (#40)

.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`**。

.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"
     }
   }
 }

.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"
+}

.Knowledge/stock-docs/flow2spec架构说明_终稿.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`）
 

.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.<name>`，仅保留拆包前旧引用路径的兼容。
+- 普通用户只装 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`）。

.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');
 }
 

.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/<topic>.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/<topic>.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 该条全文。
 
 ## 禁止项
 

.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` |

.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 命名