@double-codeing/flow2spec 2.2.3 → 3.0.8

package/README.md

@@ -1,93 +1,117 @@
 # Flow2Spec
 
-Flow2Spec 把**配置根里的知识库**（`rules/`、`skills/`、`docs-index.md`、`stock-docs/` 等）与**业务代码**串成一条**可日复一日的闭环**：先落盘可加载的约定与索引 → 日常提问与实现都**优先就着知识库走** → 随时可用 **f2s-kb-feat** / **f2s-kb-fix** 扩展或纠错并**写回**规则与技能；**实现后**（或阶段收尾）再用 **f2s-kb-sync** 将会话/现状沉淀进知识库，下一轮对话立刻继承，少在聊天与零散文档里重复对齐口径。
+Flow2Spec 用于在业务仓库初始化一套可持续的 AI 协作结构：
 
-**闭环为什么省事**：能力拆成一组 **f2s-*** 技能（`skills/<标识>/SKILL.md`），按「当前在闭环的哪一环」选用即可；init 一次把目录与模版备好，后续主要是**对话里触发技能 + 确认大纲/路径**，不必自己拼一套文档治理流程。
+- **业务知识文档**统一在 `.Knowledge/`
+- **规则与技能能力**保留在各 agent 配置根（`.cursor/`、`.claude/`、`.codex/`）
 
-**渐进式读取带来的开发体验**：**`main.mdc`**（唯一 **alwaysApply**）先给总览与入口；**`docs-index.md`** 虽不进自动上下文，但 **`main` 生成时会写入「先打开 docs-index 再按表找 Rule/Skill」的必读约定`**，从而先索引、再专题规则/技能、再 **`stock-docs/`** 长文、**必要时才下钻业务代码**；上下文**层层加深**而非整仓硬塞，**更省 token、更少噪声**，回答更贴已写进知识库的约定与模块边界。
+集中管理项目知识，同时不破坏各工具原生的 rules/skills 加载机制。
 
-在**配置根的父目录**执行 **`flow2spec init`** 写入所选 AI 工具目录（默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`** 等）。命令与顺序见 [README-命令说明](./docs/README-命令说明.md#按使用顺序查找)，目录分工见 [目录与路径约定](./docs/README-目录与路径约定.md)，对话示例见 [Flow2Spec-使用案例-模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)。
+> 🎬 **在线演示**：组内分享用的 13 页 HTML PPT（脱敏版）——**<https://lands-1203.github.io/Flow2Spec/>**
+> `←` `→` 翻页，`S` 打开演讲者模式。源文件见 [presentations/flow2spec-intro-public/](./presentations/flow2spec-intro-public/)。
 
 ---
 
 ## 快速开始
 
 ```bash
-# 在目标代码仓库（配置根的父目录）执行（默认仅写入 .cursor/）
-npx @double-codeing/flow2spec init
-# 指定 AI 工具配置目录（可多选）
-npx @double-codeing/flow2spec init claude
-npx @double-codeing/flow2spec init cursor claude codex
-# 或全局安装后
-npm install -g @double-codeing/flow2spec
-flow2spec init
+npx @double-codeing/flow2spec@latest init
+npx @double-codeing/flow2spec@latest init cursor claude codex
 ```
 
-- 模板按所选 **agent** 写入对应**配置根**（如 **`.cursor/`**、**`.claude/`**、**`.codex/`**）下的 `rules/`、`skills/`、`template/` 与预建 **`stock-docs/`**（存量上下文源）、**`req-docs/`**（需求与技术方案，按代码实现）。目录分工见 [目录与路径约定](./docs/README-目录与路径约定.md)。
-- 工作流说明在 **`skills/<标识>/SKILL.md`**；在 Cursor 中由 Agent 按场景加载对应 Skill。
-- 可用 **`flow2spec --help`** 查看全部 agent 名称与示例。
+可选：全局安装 CLI 后，可在仓库根直接使用 `flow2spec init …`（与上文等价）：
 
-**init 详解**：[Flow2Spec使用说明 - init 做了什么](./docs/Flow2Spec使用说明.md#一init-做了什么)。
+```bash
+npm install -g @double-codeing/flow2spec@latest
+```
 
----
+`init` 完成后的目录结构：
 
-## 能力与入口（速览）
+| 路径                                             | 用途                                                                                             |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `.Knowledge/stock-docs/`                         | 架构说明、终稿等沉淀文档                                                                         |
+| `.Knowledge/req-docs/`                           | 需求澄清与技术方案                                                                               |
+| `.Knowledge/topics/`                             | 主题路由摘要                                                                                     |
+| `.Knowledge/template/`                           | 终稿与技术方案模板                                                                               |
+| `.Knowledge/manifest-routing.json` + `matchers/` | 机器可读路由与关键词索引                                                                         |
+| `配置根/rules/` + `配置根/skills/`               | 各工具规则与技能入口                                                                             |
+| `flow2spec.config.json`                          | 控制 `subAgent`、`switchAgentVerification`、`changeTracking`（各技能独立子项），默认均为 `false` |
 
-| 环节 | 典型技能 / 用法 |
-|------|----------------|
-| **沉淀知识库（架构说明）** | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build**：架构初稿→终稿→Rules、Skills、索引（终稿在 `stock-docs/`） |
-| **沉淀知识库（已落地能力→上下文）** | **f2s-doc-add**：**工作中**某能力**已做好**，用**一批相关文件路径**把它解析进知识库（初稿→终稿→Rules/Skills/索引）；**与**「架构说明」**那条技能链不同** |
-| **按方案写代码** | **`req-docs/`** 下技术方案 MD + **`implement-tech-design`**；仅有 PDF 时可用 **f2s-doc-pdf** |
-| **纠错与扩展** | **f2s-kb-feat**、**f2s-kb-fix**（任意时机） |
-| **实现后写库** | **f2s-kb-sync**（会话/现状 → 大纲确认后写库） |
+> `init` 只做结构与模板补齐，业务文档内容由 `f2s-*` 技能维护。详见 [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)。
 
-更细的入参、输出与顺序：[README-命令说明](./docs/README-命令说明.md) · 使用手册：[Flow2Spec使用说明](./docs/Flow2Spec使用说明.md) · 使用案例：[Flow2Spec-使用案例-模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)。
+包升级后可在业务仓库用 **`/f2s-kb-upgrade`** 对齐知识库模板与路由；细则见 [使用说明](./docs/Flow2Spec使用说明.md)。
 
 ---
 
-## 原理与流程图解
+## 工作流全景
 
-下图与「闭环日常流」「渐进式读取」一一对应；技能标识以 **f2s-*** 为准，与图不一致处以 [README-命令说明](./docs/README-命令说明.md) 为准。
+所有技能均以 `f2s-*` 前缀或主题名在 Agent 内触发。以下按**业务场景**分组，标明推荐执行链路与前置条件。
 
-### 命令明细（名称、作用、使用时机与频率）
+> **前置要求**：涉及「旧库迁移」或「包模板对齐」时，需先在本地安装最新 CLI：
+>
+> ```bash
+> npm install -g @double-codeing/flow2spec@latest
+> ```
+>
+> 其余场景以仓库内已初始化的规则与技能为准。
 
-![命令明细图：f2s 技能一览与使用频率](./docs/images/命令明细图.png)
+### 一、需求交付链路
 
-### 日常操作与项目仓库（知识库与业务代码）
+从 PRD 到代码落地的完整路径。
 
-![日常操作流程图：各技能与知识库、业务代码的关系](./docs/images/日常操作流程图.png)
+> **任务清单控制**：`f2s-req-plan` **强制**创建任务清单；`f2s-implement-tech-design` 是否使用任务清单取决于 `changeTracking.implement` 配置。
 
-### init 与配置根结构（以 `.cursor` 为例）
+| 场景                           | 执行链                                                                              | 产出                              |
+| ------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------- |
+| 有 PRD，需澄清后出方案并落地   | `f2s-req-clarify` → `f2s-req-backend` → `f2s-implement-tech-design` → `f2s-kb-feat` | 澄清纪要 → 技术方案 → 实现+知识库 |
+| 已有方案，需强制任务清单后实现 | `f2s-req-plan`                                     
+                                 | 可确认任务清单与实现编排          |
 
-![原理图1：flow2spec init 与配置根内知识库、技能与模版](./docs/images/原理图1.png)
+### 二、知识沉淀链路
 
-### main.mdc 与 docs-index.md
+将非结构化信息（口述、草稿、外部文档、代码）转化为可检索的知识资产。
 
-![原理图2：规则总入口与文档索引](./docs/images/原理图2.png)
+| 场景              | 执行链                                             | 产出                           |
+| ----------------- | -------------------------------------------------- | ------------------------------ |
+| 从口述/草稿到终稿 | `f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build` | 架构初稿 → 规范终稿 → 主题路由 |
+| 外部文档转知识库  | `f2s-doc-final` → `f2s-ctx-build`                  | 可检索 Markdown + 路由索引     |
+| 存量代码/散稿补录 | `f2s-doc-add` 或 `f2s-kb-sync`                     | 自动提取能力 → 主题索引        |
 
-### 简述：知识库与代码闭环
+### 三、日常协作
 
-![简述图：生成知识库 → 基于知识库实现 → 基于实现反哺知识库](./docs/images/简述图.png)
+缺陷修复、迭代与上下文同步。
 
----
+| 场景           | 技能           |
+| -------------- | -------------- |
+| 修复缺陷       | `f2s-kb-fix`   |
+| 新增功能       | `f2s-kb-feat`  |
+| 同步已实现能力 | `f2s-kb-sync`  |
+| 解决合并冲突   | `f2s-kb-merge` |
 
-## 文档导航
+### 四、仓库治理
 
-| 文档 | 说明 |
-|------|------|
-| [**Flow2Spec使用说明**](./docs/Flow2Spec使用说明.md) | **使用手册**：init、目录约定、推荐顺序、典型流程、技能与工作流、常见问题 |
-| [**Flow2Spec-使用案例-模拟对话**](./docs/Flow2Spec-使用案例-模拟对话.md) | **对话版式与场景**：真实输入、命令解释、渐进读取与 **f2s-*** 示例 |
-| [README-命令说明](./docs/README-命令说明.md) | 各命令入参/输出、**按使用顺序查找**、快速参考 |
-| [README-目录与路径约定](./docs/README-目录与路径约定.md) | **配置根**下 `stock-docs/`、`req-docs/` 等结构、路径与链接约定、文档产物阶段 |
-| [README-体系与原理](./docs/README-体系与原理.md) | 架构、设计原则、main 与 docs-index 区别 |
+一次性或周期性的结构化维护。
+
+| 场景                                         | 技能             | 注意事项           |
+| -------------------------------------------- | ---------------- | ------------------ |
+| 旧版迁移（rules/skills 散稿 → `.Knowledge`） | `f2s-kb-migrate` | 一次性；执行前备份 |
+| 模板对齐（包升级后同步）                     | `f2s-kb-upgrade` | 可重复执行         |
 
 ---
 
-## CLI
+## 关键原则
+
+1. `.Knowledge/` 只放业务文档与索引，不放规则执行文件。
+2. `rules/` `skills/` 始终在配置根，保证 Claude/Cursor/Codex 按各自方式加载。
+3. Codex 不读取 `rules/` 目录，通过 `.codex/AGENTS.md` + `skills/ + .codex/topics/*.md`承载约束入口。
 
-| 命令 | 说明 |
-|------|------|
-| `flow2spec init [agent ...]` | 将模板写入所选配置根（默认 `cursor` → `.cursor/`）；详见 **`flow2spec --help`** |
-| `flow2spec --help` | 查看用法、可选 agent（cursor / claude / codex）与示例 |
+---
+
+## 文档导航
 
-技能列表与速查见 [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)。
+- [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)
+- [README-命令说明](./docs/README-命令说明.md)
+- [README-目录与路径约定](./docs/README-目录与路径约定.md)
+- [README-体系与原理](./docs/README-体系与原理.md)
+- [Flow2Spec-使用案例-模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
+- [Flow2Spec-设计说明](./docs/Flow2Spec-设计说明.md)

package/cli.js

@@ -1,33 +1,56 @@
 #!/usr/bin/env node
 
+const path = require("path");
+const fs = require("fs");
+const readline = require("readline");
 const runInit = require("./lib/init");
 const { AGENTS } = require("./lib/agents");
+const {
+  loadFlow2specConfig,
+  CONFIG_FILENAME,
+  CONFIG_FIELDS,
+  getMissingConfigFields,
+} = require("./lib/flow2specConfig");
 
 const args = process.argv.slice(2);
 const sub = args[0];
 
 const agentList = Object.entries(AGENTS)
-  .map(([id, { label }]) => `${id}（${label}）`)
-  .join("，");
+  .map(([id, { label }]) => `${id}(${label})`)
+  .join(", ");
 
 const help = `
-Flow2Spec - 文档前置工作流（AI 配置模板）
+Flow2Spec - 统一知识库工作流（AI 配置入口）
 
 用法:
-  flow2spec init [agent ...]    在当前项目初始化：将模板写入所选 AI 工具配置目录
+  flow2spec init [agent ...] [--reset-knowledge] [--yes]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
+  flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
   flow2spec --help              显示本说明
 
-agent（可多个，空格分隔；省略时默认为 cursor）：
+agent（可多个，空格分隔；省略时交互选择）：
   ${agentList}
 
 示例:
-  flow2spec init                  # 仅写入 .cursor/（Cursor）
-  flow2spec init claude           # 仅写入 .claude/
+  flow2spec init                  # 交互选择工具和配置
+  flow2spec init claude           # 直接写入 .claude/，跳过工具选择
   flow2spec init cursor claude    # 同时写入 .cursor/ 与 .claude/
+  flow2spec init --yes            # 跳过所有问答，使用默认值（适合 CI）
+  flow2spec init --reset-knowledge  # 强制用模板覆盖 .Knowledge（谨慎）
 
 init 会:
-  1. 将 templates/ 下内容复制到各所选 agent 的配置根目录下的 rules、skills、template（及预建 stock-docs/、req-docs/）。Claude Code（.claude/）下规则为 .md，frontmatter 路径键为 paths（由模板 .mdc 的 globs 自动转换）；Cursor（.cursor/）下仍为 .mdc 与 globs。
-  2. 工作流说明位于 skills 各子目录的 SKILL.md；写入 .claude/.codex 时主要为统一存放规则、技能与模版，供对应工具按各自方式加载
+  1. 交互询问要初始化的 AI 工具（cursor / claude / codex，可多选）；已通过参数指定则跳过。
+     传 --yes 或非 TTY 环境时跳过问答，使用默认值。
+  2. 对 ${CONFIG_FILENAME} 中缺失的配置字段逐项提问（已有字段不覆盖）。
+     传 --yes 时所有缺失字段使用默认值（均为 false）。
+  3. 默认仅补齐 .Knowledge 缺失模板，并对路由清单做包级/结构增量对齐（manifest-routing + matcherPath 分片；关键词仅写在 matchers/*.json）；不替代 f2s-* 对业务文档与路由内容的写入。
+     传 --reset-knowledge 时才会强制用模板覆盖 .Knowledge 中模板承载部分。
+  4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 生成 AGENTS.md 汇总）。
+     Claude 额外写入 .claude/hooks/f2s-config-inject.js 与 .claude/settings.json（PreToolUse hook），
+     在调用 f2s-* Skill 时注入配置摘要；配置缺失、JSON 无效或 hook 异常时也会注入默认语义说明，避免静默。
+     Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件。
+     Codex 的 AGENTS.md 顶部包含强制前置步骤说明。
+  5. 每次 init 将包内 templates/knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。）
+  6. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。
 
 更多说明见 README.md 或 docs/Flow2Spec使用说明.md
 `;
@@ -37,19 +60,236 @@ if (sub === "--help" || sub === "-h" || !sub) {
   process.exit(0);
 }
 
+if (sub === "config") {
+  const cwd = process.cwd();
+  const abs = path.join(cwd, CONFIG_FILENAME);
+  try {
+    const cfg = loadFlow2specConfig(cwd);
+    console.log(JSON.stringify({ configPath: abs, ...cfg }, null, 2));
+  } catch (e) {
+    console.error(e.message || e);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (sub === "init") {
-  const agentArgs = args.slice(1);
-  runInit(process.cwd(), agentArgs)
-    .then((ids) => {
+  const rawArgs = args.slice(1);
+  const overwriteKnowledge = rawArgs.includes("--reset-knowledge");
+  const skipPrompts = rawArgs.includes("--yes") || rawArgs.includes("-y");
+  const agentArgs = rawArgs.filter(
+    (a) => a !== "--reset-knowledge" && a !== "--yes" && a !== "-y",
+  );
+
+  const cwd = process.cwd();
+
+  // ── 清除已输出的 n 行（用于多选 UI 重绘）
+  function clearLines(n) {
+    if (n <= 0) return;
+    process.stdout.write(`\x1b[${n}A\x1b[0J`);
+  }
+
+  /**
+   * 多选 UI（raw mode）：箭头键移动，空格选/取消，回车确认。
+   * 非 TTY 环境直接返回默认选中项。
+   */
+  async function promptMultiSelect(title, items, defaultSelected = []) {
+    if (!process.stdin.isTTY || skipPrompts) {
+      return defaultSelected.length ? defaultSelected : [items[0].value];
+    }
+
+    const selected = new Set(defaultSelected.length ? defaultSelected : [items[0].value]);
+    let cursor = 0;
+    let rendered = 0;
+
+    function render() {
+      if (rendered > 0) clearLines(rendered);
+      const lines = [];
+      lines.push(`  ${title}`);
+      for (let i = 0; i < items.length; i++) {
+        const sel = selected.has(items[i].value);
+        const check = sel ? "\x1b[32m◉\x1b[0m" : "○";
+        const arr = i === cursor ? "\x1b[36m›\x1b[0m" : " ";
+        const label = items[i].label.padEnd(10);
+        const desc = items[i].desc ? `  \x1b[2m${items[i].desc}\x1b[0m` : "";
+        lines.push(`  ${arr} ${check}  ${label}${desc}`);
+      }
+      lines.push("");
+      lines.push("  \x1b[2m↑↓ 移动  空格 选/取消  回车 确认\x1b[0m");
+      rendered = lines.length;
+      process.stdout.write(lines.join("\n") + "\n");
+    }
+
+    render();
+
+    return new Promise((resolve) => {
+      function onKey(str, key) {
+        if (!key) return;
+        if (key.ctrl && key.name === "c") process.exit(0);
+
+        if (key.name === "up") {
+          cursor = (cursor - 1 + items.length) % items.length;
+          render();
+        } else if (key.name === "down") {
+          cursor = (cursor + 1) % items.length;
+          render();
+        } else if (key.name === "space") {
+          const val = items[cursor].value;
+          if (selected.has(val)) selected.delete(val);
+          else selected.add(val);
+          render();
+        } else if (key.name === "return") {
+          process.stdin.removeListener("keypress", onKey);
+          const result = selected.size ? [...selected] : [items[0].value];
+          if (rendered > 0) clearLines(rendered);
+          const labels = result
+            .map((v) => items.find((i) => i.value === v)?.value)
+            .join(", ");
+          process.stdout.write(`  ${title}  \x1b[32m${labels}\x1b[0m\n`);
+          resolve(result);
+        }
+      }
+      process.stdin.on("keypress", onKey);
+    });
+  }
+
+  /**
+   * 单键 y/n 问答（raw mode）。
+   * 非 TTY 或 skipPrompts 时直接返回默认值。
+   */
+  async function promptBooleanKey(question, defaultValue = false) {
+    if (!process.stdin.isTTY || skipPrompts) return defaultValue;
+
+    const hint = defaultValue
+      ? "\x1b[2m[Y/n]\x1b[0m"
+      : "\x1b[2m[y/N]\x1b[0m";
+    process.stdout.write(`  ${question} ${hint} `);
+
+    return new Promise((resolve) => {
+      process.stdin.once("keypress", function (str, key) {
+        if (key && key.ctrl && key.name === "c") process.exit(0);
+        let result;
+        if (!str || str.trim() === "" || key?.name === "return") {
+          result = defaultValue;
+        } else {
+          result = str.trim().toLowerCase() === "y";
+        }
+        process.stdout.write((result ? "\x1b[32my\x1b[0m" : "n") + "\n");
+        resolve(result);
+      });
+    });
+  }
+
+  async function collectInitOptions() {
+    const needAgentPrompt = agentArgs.length === 0 && !skipPrompts;
+    const missingFields = getMissingConfigFields(cwd);
+    const needConfigPrompt = missingFields.length > 0;
+
+    // 没有任何需要处理的事情
+    if (!needAgentPrompt && !needConfigPrompt) {
+      return { configValues: undefined, chosenAgents: agentArgs };
+    }
+
+    // --yes 模式：缺失字段直接用默认值，不弹交互
+    if (skipPrompts) {
+      const configValues = needConfigPrompt
+        ? Object.fromEntries(missingFields.map((f) => [f.key, f.default]))
+        : undefined;
+      return { configValues, chosenAgents: agentArgs };
+    }
+
+    const isInteractive = process.stdin.isTTY;
+    if (isInteractive) {
+      readline.emitKeypressEvents(process.stdin);
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+    }
+
+    let chosenAgents = agentArgs;
+    let configValues;
+
+    try {
+      process.stdout.write("\n");
+
+      if (needAgentPrompt) {
+        const agentItems = Object.entries(AGENTS).map(([id, { label }]) => ({
+          value: id,
+          label: id,
+          desc: label,
+        }));
+        chosenAgents = await promptMultiSelect(
+          "选择要初始化的 AI 工具（可多选）",
+          agentItems,
+          ["cursor"],
+        );
+      }
+
+      if (needConfigPrompt) {
+        if (needAgentPrompt) process.stdout.write("\n");
+        const isFirstTime = missingFields.length === CONFIG_FIELDS.length;
+        process.stdout.write(
+          `  配置 ${CONFIG_FILENAME}${isFirstTime ? "（首次创建）" : "（补充新增字段）"}：\n\n`,
+        );
+        const values = {};
+        for (const field of missingFields) {
+          values[field.key] = await promptBooleanKey(
+            field.question,
+            field.default,
+          );
+        }
+        configValues = values;
+      }
+    } finally {
+      if (isInteractive) {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+      }
+    }
+
+    process.stdout.write("\n");
+    return { configValues, chosenAgents };
+  }
+
+  collectInitOptions()
+    .then(({ configValues, chosenAgents }) =>
+      runInit(cwd, chosenAgents, { overwriteKnowledge, configValues }),
+    )
+    .then(({ ids, knowledgeResult, routingUpgrade, indexSnapshot, projectConfig, claudeHooksResult }) => {
       const lines = ids.map((id) => {
         const { root, label } = AGENTS[id];
-        return `  - ${root}/：（${label}）rules、skills、template、stock-docs、req-docs（预建）`;
+        if (id === "codex")
+          return `  - ${root}/：（${label}）AGENTS.md、skills/`;
+        if (id === "claude") {
+          const hookLine = claudeHooksResult?.settingsChanged
+            ? "rules/、skills/、hooks/f2s-config-inject.js、settings.json（已写入 f2s PreToolUse hook）"
+            : "rules/、skills/（settings.json 中 f2s hook 已存在，跳过）";
+          return `  - ${root}/：（${label}）${hookLine}`;
+        }
+        return `  - ${root}/：（${label}）rules/、skills/`;
       });
+      const knowledgeLine = overwriteKnowledge
+        ? "  - .Knowledge/：已按 --reset-knowledge 强制覆盖模板"
+        : `  - .Knowledge/：保留已有内容，补齐缺失模板（新增 ${knowledgeResult?.written || 0}，跳过 ${knowledgeResult?.skipped || 0}）`;
+      const routingLine = overwriteKnowledge
+        ? "  - .Knowledge/manifest-routing.json + .Knowledge/matchers/*：已随 reset 覆盖到模板版本（不再写入 manifest-matchers.json）"
+        : routingUpgrade?.upgraded
+          ? "  - 路由清单已与模板增量对齐"
+          : "  - 路由清单已是最新能力路由，无需变更";
+      const indexLine =
+        indexSnapshot?.written === false
+          ? `  - .Knowledge/template/index.template.md：未复制（${indexSnapshot?.reason || "skip"}）`
+          : "  - .Knowledge/template/index.template.md：已从包内 templates/knowledge/index.md 复制（与 .Knowledge/index.md 对照见 f2s-kb-upgrade 技能）";
+      const pc = projectConfig || {};
+      const configLine = `  - ${CONFIG_FILENAME}：subAgent=${Boolean(pc.subAgent)}, switchAgentVerification=${Boolean(pc.switchAgentVerification)}`;
       console.log(`
 ✓ Flow2Spec init 完成
+${knowledgeLine}
+${routingLine}
+${indexLine}
+${configLine}
 ${lines.join("\n")}
 
-在 Cursor 中可通过 Agent Skills 加载 skills/ 目录下工作流（配置根为 .cursor 时）。建议阅读 README 或 docs/Flow2Spec使用说明.md。
+建议阅读 README 或 docs/Flow2Spec使用说明.md，按「规则在配置根、文档在 .Knowledge」的方式使用。
 `);
     })
     .catch((e) => {