liguochuan00 · Aug 25, 2026 · Aug 19, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/.Knowledge/matchers/m-flow2spec-core-package.json b/.Knowledge/matchers/m-flow2spec-core-package.json
@@ -9,7 +9,18 @@
     "createFlow2Spec",
     "legacy shim",
     "模板真源",
-    "CLI 依赖 core"
+    "CLI 依赖 core",
+    "独立版本",
+    "Core-only",
+    "Template Version",
+    "version:set:cli",
+    "version:set:core",
+    "version:set:template",
+    "version:check",
+    "独立发布",
+    "core-v",
+    "cli-v",
+    "Core 更新检测"
   ],
   "id": "m-flow2spec-core-package",
   "version": "1.0.0",

diff --git a/.Knowledge/topics/f2s-dev-workflow-constraints.md b/.Knowledge/topics/f2s-dev-workflow-constraints.md
@@ -1,72 +1,41 @@
 ---
 id: f2s-dev-workflow-constraints
-revision: 2
-summary: "f2s-dev-workflow-constraints（路由摘要）"
+revision: 3
+summary: "Flow2Spec 本仓的模板真源、配置根、版本发布与分发边界"
 primary: policy
 confidence: inferred
 ---
 # f2s-dev-workflow-constraints（路由摘要）
 
-> **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓,**不进 `templates/`**。
+## 适用场景
 
-## 作用
+Flow2Spec 本仓开发时判断应改 Core templates、配置根、本仓知识库还是发布脚本；普通下游仓不使用本主题。
 
-约束在 Flow2Spec 本仓内开发时的写盘边界与分发口径,避免「手改配置根被 init 覆盖」「未经用户同意主动跑 init」「手改 core templates 副本」。
+## 长文规则
 
-## 长文位置(本仓配置根手写,不进 templates)
+- Claude：`.claude/rules/repo-dev-workflow-constraints.md`
+- Cursor：`.cursor/rules/repo-dev-workflow-constraints.mdc`
+- Codex：`.codex/topics/repo-dev-workflow-constraints.md`
 
-- **Cursor**:`.cursor/rules/repo-dev-workflow-constraints.mdc`
-- **Claude**:`.claude/rules/repo-dev-workflow-constraints.md`
-- **Codex**:`.codex/topics/repo-dev-workflow-constraints.md`
+三份是同源手写镜像，执行时读取当前客户端对应版本。
 
-三份为同源手写副本；执行时按当前 agent 打开对应端。
+## 核心约束
 
-## 核心约束(一句一条)
+1. 下游会使用的 Rule、Skill、Hook、AGENTS、配置与知识模板只改 `packages/core/templates/{zh-CN,en-US}/`；该目录是受 Git 管理的唯一模板真源。
+2. 配置根中有 Core template 对应源的文件属于 init 产物，不直接手改。
+3. 本仓专属 `repo-*` Rule/Skill 不进入 Core templates，直接同步三端配置根与本仓知识库。
+4. Agent 不主动运行 `flow2spec init` / `npm run sync:agents`，由用户明确触发分发。
+5. 根 `lib/`、根 `templates/` 与模板复制脚本不再使用。
 
-1. **只改 `templates/`**：所有下游会用到的规则/技能/主题/matcher/manifest 模板改动,只落 `templates/zh-CN/` 与 `templates/en-US/`(workspace 根)。
-2. **不改配置根(下游会用到的产物)**：`.claude/rules/` 等中在 `templates/` 有对应源的文件属 `init` 产物,手改会被覆盖。
-3. **本仓专属手写例外**：`f2s-dev-workflow-constraints`、`repo-dev-check` 等**只**在本仓的规则/技能,直接落配置根,**不进** `templates/`。
-4. **用户驱动分发**：Agent **不主动**跑 `flow2spec init` / `npm run sync:agents`；由用户执行。
-5. **不改 `packages/core/templates/`**：它是 `scripts/sync-core-templates.js` 从根 `templates/` 自动生成的 npm 发布物副本,已进 `.gitignore`,下次同步会被覆盖。
+## 版本与发布
 
-## 模板双份关系(重要)
-
-- **根 `templates/`**：唯一手写事实源,进 git,日常改这里。
-- **`packages/core/templates/`**：npm 发布副本,不进 git,由 `scripts/sync-core-templates.js` 生成;运行时 `packages/core/index.js` 通过 `__dirname` 读它,因此 core 包必须自带这份(否则用户 `npm install` 后 `flow2spec init` 会 `ENOENT`)。
-- 自动同步触发点:`sync:agents` / `test` / `pack:check` 静默同步；`packages/core` 的 `prepack` 在 `npm pack` / `npm publish` 前同步；`sync:core-templates:check` 做纯校验。
-
-## 分发命令(用户执行)
-
-```bash
-npm run sync:agents
-# 或
-node ./cli.js init codex claude cursor
-# 或全局装了
-flow2spec init codex claude cursor
-```
-
-## 自查技能
-
-`repo-dev-check` 用于本仓提交前自查写盘边界与分发口径。触发词见该 SKILL。
-
-## 适用场景 / 触发词
-
-- 用户提到「templates vs 配置根」「模板 vs 落盘」
-- 用户说「不要改配置根 / 只改 templates / 我来跑 init / 我会自己 sync:agents」
-- Agent 打算改配置根下与 `templates/` 有对应源的文件时须先读本 topic 与对应 rules 长文
-- 用户问「根 templates 与 core templates 是什么关系」「core templates 冗余吗」
-- 分发口径澄清
+- CLI、Core、Template、Protocol 独立版本；CLI 用 caret range 约束 Core。
+- Core-only 兼容更新不升 Template Version，也不触发知识库升级。
+- `core-vX.Y.Z` 与 `cli-vX.Y.Z` 分别发布对应包。
+- 发布前执行版本、打包、tarball 安装与 README 门禁。
 
 ## 边界与禁止项
 
-- **仅本仓适用**：下游项目不承担本 topic 约束,不 `Read` 也不生效。
-- **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。
-- `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件,不视为配置根。
-- **禁止手改 `packages/core/templates/`**——它由脚本从根 templates 生成,下次同步会覆盖。
-
-## npm workspace 发布门禁
-
-- 主 CLI 包 `@double-coding/flow2spec` 的 `packages/cli/README.md` 与根 `README.md` 保持完全一致；Core 包维护面向程序化调用的独立 README。
-- Core、CLI 与 workspace 根版本保持一致,CLI 固定依赖同版本 Core。
-- 发布前运行 `npm run pack:check` 与 `node scripts/test-package-install.js`,并从 CLI tarball 校验 README,确保 npm 页面保留完整产品文档。
-- `packages/core/templates/` 由 `scripts/sync-core-templates.js` 生成,`prepack` 自动触发,tarball 内始终包含最新模板；CI/pre-release 建议跑 `npm run sync:core-templates:check` 做漂移检查。
+- 本主题和长文规则只服务 Flow2Spec 本仓，不进入下游模板。
+- 禁止恢复双模板根或版本锁步模型。
+- 禁止用 Core Version 覆盖 `manifest-routing.json.version`；该字段表示 Template Version。
diff --git a/.Knowledge/topics/f2s-init-defaults.md b/.Knowledge/topics/f2s-init-defaults.md
@@ -1,6 +1,6 @@
 ---
 id: flow2spec-init-defaults
-revision: 0
+revision: 1
 summary: "flow2spec-init-defaults（路由摘要）"
 primary: config
 confidence: inferred
@@ -18,10 +18,10 @@ tags: [policy]
 
 | 落点 | 角色 | 路径 |
 | --- | --- | --- |
-| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `lib/flow2specConfig.js` |
-| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `lib/flow2specConfig.js` |
-| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `templates/{zh-CN,en-US}/flow2spec.config.json` |
-| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `lib/codexAgentsAdapter.js` |
+| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `packages/core/lib/flow2specConfig.js` |
+| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `packages/core/lib/flow2specConfig.js` |
+| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `packages/core/templates/{zh-CN,en-US}/flow2spec.config.json` |
+| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `packages/core/lib/codexAgentsAdapter.js` |
 
 不一致的后果：
 
@@ -35,7 +35,7 @@ tags: [policy]
 
 | 字段 | 类型 | 当前默认值 | 语义 |
 | --- | --- | --- | --- |
-| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 `templates/<locale>/` |
+| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 Core package template |
 | `subAgent` | boolean | `true` | 是否允许技能拆子 agent；`false` 时主 agent 全流程；详见 `f2s-flow2spec-unified-entry` |
 | `switchAgentVerification` | boolean | `true` | 切换 agent 校验；`true` 且技能正文绑定时启用交叉校验；旧键 `subAgentVerification` 仍兼容 |
 | `intentRecognition` | boolean | `true` | 高置信操作意图是否按 `f2s-intent-routing` 自动进入对应 `f2s-*` 技能 |
@@ -44,7 +44,7 @@ tags: [policy]
 | `changeTracking.implement` | boolean | `true` | `f2s-implement-tech-design` 是否走 `.task/` 变更追踪 |
 | `updateCheck.enabled` | boolean | `true` | 是否启用每日版本更新提示 |
 
-「当前默认值」一栏以包模板 `templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。
+「当前默认值」一栏以包模板 `packages/core/templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。
 
 ### 默认值变更记录
 
@@ -69,20 +69,14 @@ tags: [policy]
 
 含义：升级 npm 包后新增的字段，会以「当前 `CONFIG_FIELDS` 默认值」补齐到老项目；如新版本默认值翻面（例如某字段由 `false` 改为 `true`），**只影响**升级时**仍缺该字段**的老项目，已写过该字段的项目不变。
 
-### 跑 `f2s-kb-upgrade` 时怎么让全局 flow2spec 保持最新
+### 跑 `f2s-kb-upgrade` 时的版本预检
 
-`f2s-kb-upgrade` SKILL 的「步骤 -1」（先于一切）**先做前台探测再决定是否升级**：主 agent 顺序跑 `flow2spec --version` + `npm view @double-coding/flow2spec version` + `command -v npx`，按 3 分支处理：
+步骤 -1 执行 `flow2spec version` 与 `flow2spec update --check`，分别读取 CLI、Core、Core Range、Template、Protocol 和 npm 最新 Core/Template：
 
-- **A. 已装且是 latest** → **完全跳过**升级；步骤 2 命令首选 `flow2spec init <agents...>`。
-- **B. 已装但落后** → 派**独立子 agent** 后台跑 `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；步骤 2 命令用 `npx @double-coding/flow2spec@latest init <agents...>` 保证本次拿到 latest 模板。
-- **C. 未装 / latest 未知** → 同 B 处理；探测全部失败时可放弃步骤 -1，由 cli.js 兜底。
-
-口径：
-
-- **仅** B/C 时才派子 agent；派子**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）；
-- 派子是 fire-and-forget，结果不进入 SKILL 结论摘要——失败也只是"下次再升一次"；
-- 与 `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 不冲突：前者是 SKILL 入口按需异步派工，后者是 `init` 收尾兜底；两次都成功就是 no-op。
-- 用户自查用 `flow2spec --version`（当前全局版本）和 `flow2spec update`（CLI 内置自更新）。
+- Core-only 更新：`flow2spec update --core` 后幂等 init 刷新 Hook，不进入完整知识库升级。
+- Template 更新且 Core 兼容：更新 Core 后继续 init 与 `projectRev` / `pkgRev` 分流。
+- 本地版本不可用或 Core 超出范围：显式组合 latest CLI/Core 执行 init，避免 npx 复用旧 Core。
+- `manifest-routing.json.version` 表示 Template Version，不能与 Core Version 混用。
 
 ## init 不动哪些目录
 

diff --git a/.Knowledge/topics/flow2spec-core-package.md b/.Knowledge/topics/flow2spec-core-package.md
@@ -1,27 +1,55 @@
 ---
 id: flow2spec-core-package
-revision: 0
-summary: "@double-coding/flow2spec-core 的职责边界：核心实现、发包模板真源与原生插件 API"
+revision: 2
+summary: "Core/CLI 所有权、公共 API、独立版本、独立发布与更新兼容契约"
 primary: module
 confidence: inferred
 ---
 # Flow2Spec Core 包（@double-coding/flow2spec-core）
 
 ## 适用场景
 
-回答或维护 npm workspace 包结构、`flow2spec-core` 的职责、CLI 与 core 的依赖关系、原生插件 API、发包模板真源位置、根目录 legacy shim。
+维护 npm workspace 包结构、Core 公共 API、CLI/Core 依赖、模板真源、独立版本、发布 tag、更新检测与兼容范围。
 
-## 核心事实
+## 所有权
 
-- 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 作为依赖按锁定版本自动带上。
+- 根 private workspace 只负责开发编排，不作为 Core 运行时依赖声明位置。
+- `packages/core/lib/` 承载核心实现；`packages/core/templates/{zh-CN,en-US}/` 是受 Git 管理的唯一模板真源并随 Core tarball 发布。
+- 根 `lib/`、根 `templates/` 与 `scripts/sync-core-templates.js` 均不存在。
+- CLI 是薄壳，只通过 `@double-coding/flow2spec-core` 的公共 API 工作；当前运行时范围为 `^3.5.0`。
 
-## 边界与注意
+## 公共 API
 
-- 本仓开发态下 `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`）。
+- `createFlow2Spec({ cwd })` 暴露项目初始化、配置、路由、知识库、协作、doctor、resources 与 update API。
+- `getVersions()` 返回 `coreVersion`、`templateVersion`、`protocolVersion`。
+- `capabilities.json.protocolVersion` 表示公共协议兼容级别，不表示包版本或模板版本。
+- `legacy` 暂时保留 Core 包内的旧消费兼容面；CLI 和仓库测试不再依赖根 shim。
+
+## 独立版本
+
+```text
+CLI Version       packages/cli/package.json
+Core Version      packages/core/package.json
+Template Version  packages/core/package.json.templateVersion
+Protocol Version  packages/core/capabilities.json.protocolVersion
+```
+
+- `version:set:cli` 只更新 CLI，可显式提高 `--core-range`。
+- `version:set:core` 只更新 Core，并拒绝落到当前 CLI 范围之外。
+- `version:set:template` 更新 Core 元数据及中英文 `manifest-routing.json.version`。
+- `version:check` 校验 semver range、lockfile、双语 Template Version、Protocol Version 与 release tag。
+
+## 发布与更新
+
+- `core-vX.Y.Z` 只发布 Core；`cli-vX.Y.Z` 只发布 CLI。同时发布时先 Core 后 CLI。
+- `flow2spec version` 展示 CLI/Core/Core Range/Template/Protocol。
+- `flow2spec update --check|--cli|--core` 分别检查、更新 CLI、更新兼容 Core。
+- Hook 与 `update.check()` 同时返回 Core 与 Template 状态。
+- Core-only 更新：更新 Core 后幂等 init 刷新 Hook，不进入 `f2s-kb-upgrade`。
+- Template 更新：更新 Core、执行 init，再由 `projectRev` / `pkgRev` 决定是否进入完整知识库升级。
+
+## 边界
+
+- Core 新版必须落在 CLI caret range 内；超出范围先升级 CLI。
+- `.Knowledge/manifest-routing.json.version` 表示 Template Version，不能与 Core Version 混用。
+- 包安装验收使用两包 tarball，并验证 Core templates、类型声明、CLI README 与启动行为。