@double-codeing/flow2spec 2.2.3 → 3.0.8

package/docs/README-/347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md

@@ -1,76 +1,47 @@
 # 目录与路径约定
 
-**配置根**：`flow2spec init` 写入的目录（默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`**）。下文以 **`.cursor/`** 为例，其它 agent 将 `.cursor` 换成对应目录名即可。
+## 核心边界
 
-**文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) · [README-命令说明](./README-命令说明.md) · [README-体系与原理](./README-体系与原理.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
-
-| 路径（逻辑） | 示例（Cursor） | 说明 |
-|--------------|----------------|------|
-| **stock-docs/** | `.cursor/stock-docs/` | 存量源文档（终稿/初稿/架构等）→ **f2s-ctx-build**；**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**已落地能力、多文件聚合进上下文）的初稿/终稿亦在此，**勿**与 **req-docs** 混用 |
-| **req-docs/** | `.cursor/req-docs/` | 技术方案、澄清文档等 → **implement-tech-design** 按方案写代码 |
-| **rules/** | `.cursor/rules/` | **main.mdc**（唯一 alwaysApply）+ 专题 `*-context.mdc` |
-| **skills/** | `.cursor/skills/` | 各 `SKILL.md` |
-| **template/** | `.cursor/template/` | 终稿模版、后端技术模版 |
-| **docs-index.md** | `.cursor/docs-index.md` | 文档 ↔ Rules / Skills 索引表 |
-
-**init**：创建上表目录并复制模板。**升级**：旧名 `docs/` 可改名为 `stock-docs/`；`req-docs` 须在**配置根内**，勿与 `.cursor` 同级。
-
-### 1.1 Cursor 与 Claude Code：`rules/` 扩展名
-
-| 配置根 | 规则文件扩展名 | 路径范围（frontmatter） | 说明 |
-|--------|----------------|-------------------------|------|
-| **`.cursor/`**（Cursor） | **`.mdc`** | **`globs:`** + **`alwaysApply:`** | Cursor 约定 |
-| **`.claude/`**（Claude Code） | **`.md`** | **`paths:`**（无 `paths` 则与会话同载） | Claude Code 不识别 `.mdc`；`flow2spec init claude` 由模板自动转换 |
-
-在 **`.claude/`** 下手工维护规则时，请使用 **`.md`** 与 **`paths:`**；勿复制 Cursor 的 **`globs:`** / **`.mdc`** 以免不生效。Claude Code **不会**把 **`.mdx`** 当作项目规则加载；请勿用 **`.mdx`** 作为 `rules/` 内规则扩展名。
+- `.Knowledge/`：只放业务知识文档与索引
+- `配置根`（`.cursor/.claude/.codex`）：放规则与技能入口
 
 ---
 
-## 2. 链接写法（生成 Rule / Skill / docs-index 时必守）
-
-从 **rules/**、**skills/**、**docs-index.md** 指向 **stock-docs/** 的 **href** 必须如下（否则链接断）：
-
-| 写入位置 | 链接 href |
-|----------|-----------|
-| `rules/*.mdc` | `../stock-docs/<文件名>.md` |
-| `skills/<主题>/SKILL.md` | `../../stock-docs/<文件名>.md` |
-| `docs-index.md` | `stock-docs/<文件名>.md`（无 `../`） |
-| **sourceDoc**（frontmatter） | **`<配置根>/stock-docs/<文件名>.md`**（如 `.cursor/stock-docs/xxx.md`） |
-
-**禁止**：Rule/Skill/docs-index 把 **req-docs** 当 stock-docs 链出；docs-index 的 href 写成 `../stock-docs/` 或裸绝对路径。
-
-**记忆**：链出只认 **stock-docs**；Rule `../`，Skill `../../`，索引 `stock-docs/`；sourceDoc 用配置根全路径。
+## 目录职责
+
+| 路径 | 职责 |
+| --- | --- |
+| `.Knowledge/stock-docs/` | 架构、终稿、沉淀文档 |
+| `.Knowledge/req-docs/` | 需求澄清、技术方案 |
+| `.Knowledge/topics/` | 主题路由文档（用于规则与流程执行） |
+| `.Knowledge/template/` | 终稿/技术方案模板 |
+| `.Knowledge/index.md` | 人类可读索引 |
+| `.Knowledge/manifest-routing.json` | 机器可读路由骨架（task/topic/dependencies） |
+| `.Knowledge/matchers/*.json` | 关键词分片（`id/includeAny`），由 `manifest-routing.taskToTopicRules[].matcherPath` 直链指向 |
+| `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
+| `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
+| `配置根/rules/` | 规则文件（Cursor `.mdc`，Claude `.md`） |
+| `配置根/skills/` | 技能定义（`SKILL.md`） |
+| `配置根/template/` | （废弃）不再写入；历史目录可清理 |
+| `.codex/AGENTS.md` | Codex 统一入口与加载说明 |
+| `flow2spec.config.json` | 项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项） |
+
+> 多端提示与路径表见 [Flow2Spec使用说明 § 一](./Flow2Spec使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。
 
 ---
 
-## 3. 文档产物阶段（均在 stock-docs/）
-
-| 阶段 | 含义 | 典型名 |
-|------|------|--------|
-| 原稿 | 未纳入体系前的材料 | 任意 PDF、杂乱 MD |
-| 初稿 | **f2s-doc-final**（PDF 首次）、**f2s-doc-arch**（架构说明），或 **f2s-doc-add**（**工作中**把**已落地能力**从多文件聚合成的初稿） | `*_初稿.md`、`*架构说明_初稿.md` 等；**f2s-doc-add** 与 **f2s-doc-arch** 分工见各自 `SKILL.md` |
-| 终稿 | **f2s-doc-final** 规范输出 | `*_终稿.md` → **f2s-ctx-build** 入参 |
+## 路径约束
 
-Rules/Skills **文件名不带 `_终稿`**。
+1. `.Knowledge/topics` 是知识路由主题层，允许并鼓励通过 `f2s-*` 技能维护。
+2. `f2s-ctx-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
+3. 实现类任务统一读取 `.Knowledge/req-docs/*.md`。
+4. `manifest-routing.json` 与 `matchers/*.json` 由 `f2s-*` 技能流程维护；不再使用 `.Knowledge/manifest-matchers.json`（`flow2spec init` 会删除遗留文件）。
 
 ---
 
-## 4. 版本管理（sourceDoc 与 generatedAt）
-
-每条 Rule、Skill 的 frontmatter：**sourceDoc**（同上表）、**generatedAt**（东八区 ISO 8601，如 `2026-01-28T20:00:00+08:00`）。  
-**索源**：产物看 `sourceDoc`；文档看 **docs-index** 对应行；更新对同路径再跑 **f2s-ctx-build**。用法见 [README-体系与原理 §5](./README-体系与原理.md#5-版本管理与索源)。
-
----
-
-## 5. template/
-
-包内 **templates/template/** → init 复制到 **配置根/template/**。**f2s-doc-final** 读 `template/终稿模版.md`；**f2s-req-backend** 参考 `template/后端技术模版.md`。再次 init **覆盖** `template/`。
-
----
-
-## 6. 小结
-
-- **stock-docs** = 上下文源；**req-docs** = 实现用方案。  
-- 链接层级见 §2；产物阶段见 §3；版本字段见 §4。
+## 相关文档
 
-**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) | [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | [README-命令说明](./README-命令说明.md) | [README-体系与原理](./README-体系与原理.md)
+- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
+- [README-命令说明](./README-命令说明.md)
+- [README-体系与原理](./README-体系与原理.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)

package/lib/agents.js

@@ -1,6 +1,6 @@
 /**
  * flow2spec init 支持的 AI 工具配置目录。
- * 模板以相同子目录结构写入各配置根：rules/、skills/、stock-docs/、req-docs/、template/
+ * 知识库统一写入项目根 `.Knowledge/`（含 template），rules/skills 保留在各配置根。
  */
 const AGENTS = {
   cursor: { root: ".cursor", label: "Cursor" },
@@ -8,7 +8,13 @@ const AGENTS = {
   codex: { root: ".codex", label: "Codex" },
 };
 
-const SUBDIRS = ["stock-docs", "req-docs", "template", "rules", "skills"];
+const KNOWLEDGE_ROOT = ".Knowledge";
+const KNOWLEDGE_SUBDIRS = ["stock-docs", "req-docs", "matchers"];
+const AGENT_SUBDIRS = {
+  cursor: ["rules", "skills"],
+  claude: ["rules", "skills"],
+  codex: ["skills"],
+};
 
 /**
  * @param {string[]} argv  init 后的参数，如 []、['cursor']、['cursor','claude']
@@ -32,4 +38,10 @@ function normalizeAgentIds(argv) {
   return out;
 }
 
-module.exports = { AGENTS, SUBDIRS, normalizeAgentIds };
+module.exports = {
+  AGENTS,
+  KNOWLEDGE_ROOT,
+  KNOWLEDGE_SUBDIRS,
+  AGENT_SUBDIRS,
+  normalizeAgentIds,
+};

package/lib/claudeSettingsAdapter.js

@@ -0,0 +1,114 @@
+'use strict';
+/**
+ * 负责合并 flow2spec hook 配置到 .claude/settings.json。
+ * 仅在 init --claude 时调用。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_COMMAND = 'node .claude/hooks/f2s-config-inject.js';
+
+/**
+ * 判断 PreToolUse 数组里是否已存在 f2s-config-inject hook。
+ * @param {Array} preToolUseArr
+ * @returns {boolean}
+ */
+function hasF2sHook(preToolUseArr) {
+  if (!Array.isArray(preToolUseArr)) return false;
+  for (const group of preToolUseArr) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const h of group.hooks) {
+      if (h && h.type === 'command' && String(h.command || '').includes('f2s-config-inject')) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 将 f2s PreToolUse hook 合并进现有 settings，返回新对象（不修改原对象）。
+ * @param {object} existing  现有 settings（可为 {}）
+ * @returns {object}
+ */
+function mergeF2sHook(existing) {
+  const next = JSON.parse(JSON.stringify(existing || {}));
+  if (!next.hooks) next.hooks = {};
+  if (!next.hooks.PreToolUse) next.hooks.PreToolUse = [];
+
+  if (hasF2sHook(next.hooks.PreToolUse)) {
+    return { settings: next, changed: false };
+  }
+
+  next.hooks.PreToolUse.push({
+    matcher: 'Skill',
+    hooks: [{ type: 'command', command: HOOK_COMMAND }],
+  });
+
+  return { settings: next, changed: true };
+}
+
+/**
+ * 读取 .claude/settings.json（不存在则返回 {}）。
+ * @param {string} claudeRoot  .claude 目录绝对路径
+ * @returns {object}
+ */
+function readSettings(claudeRoot) {
+  const settingsPath = path.join(claudeRoot, 'settings.json');
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (_err) {
+    return {};
+  }
+}
+
+/**
+ * 写入 .claude/settings.json。
+ * @param {string} claudeRoot
+ * @param {object} settings
+ */
+function writeSettings(claudeRoot, settings) {
+  const settingsPath = path.join(claudeRoot, 'settings.json');
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * 将 templates/hooks/f2s-config-inject.js 复制到 .claude/hooks/。
+ * @param {string} claudeRoot
+ * @param {string} templatesDir
+ */
+function copyHookScript(claudeRoot, templatesDir) {
+  const src = path.join(templatesDir, 'hooks', 'f2s-config-inject.js');
+  if (!fs.existsSync(src)) return { written: false, reason: 'missing-template' };
+
+  const hooksDir = path.join(claudeRoot, 'hooks');
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+  const dest = path.join(hooksDir, 'f2s-config-inject.js');
+  fs.copyFileSync(src, dest);
+  return { written: true };
+}
+
+/**
+ * 主入口：为 claude agent 配置 f2s PreToolUse hook。
+ * @param {string} cwd        项目根目录
+ * @param {string} templatesDir  flow2spec 包 templates 目录
+ * @returns {{ hookScriptResult, settingsChanged }}
+ */
+function writeClaudeAgentHooks(cwd, templatesDir) {
+  const claudeRoot = path.join(cwd, '.claude');
+  if (!fs.existsSync(claudeRoot)) fs.mkdirSync(claudeRoot, { recursive: true });
+
+  const hookScriptResult = copyHookScript(claudeRoot, templatesDir);
+
+  const existing = readSettings(claudeRoot);
+  const { settings, changed } = mergeF2sHook(existing);
+  if (changed) {
+    writeSettings(claudeRoot, settings);
+  }
+
+  return { hookScriptResult, settingsChanged: changed };
+}
+
+module.exports = { writeClaudeAgentHooks, mergeF2sHook };

package/lib/codexAgentsAdapter.js

@@ -0,0 +1,70 @@
+const fs = require("fs");
+const path = require("path");
+
+function readSkillSummary(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(skillsDir)) {
+    const skillFile = path.join(skillsDir, name, "SKILL.md");
+    if (!fs.existsSync(skillFile)) continue;
+    const raw = fs.readFileSync(skillFile, "utf8");
+    const frontmatter = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const body = frontmatter ? frontmatter[1] : "";
+    const skillName = (body.match(/^\s*name:\s*(.+)\s*$/m) || [])[1] || name;
+    const desc = (body.match(/^\s*description:\s*(.+)\s*$/m) || [])[1] || "暂无描述";
+    out.push(`- \`${skillName.trim()}\`：${desc.trim()}`);
+  }
+  return out.sort((a, b) => a.localeCompare(b, "zh-Hans-CN"));
+}
+
+function renderProjectConfigBlock(projectConfig) {
+  const c = projectConfig || {};
+  const subAgent = Boolean(c.subAgent);
+  const switchAgentVerification = Boolean(c.switchAgentVerification);
+  const ct = c.changeTracking || {};
+  const feat = Boolean(ct.feat);
+  const fix = Boolean(ct.fix);
+  const implement = Boolean(ct.implement);
+  return [
+    "| 配置项 | 当前值 | 说明 |",
+    "| --- | --- | --- |",
+    "| `subAgent` | " +
+      String(subAgent) +
+      " | 技能规定用子 agent 的步骤：`true` 执行，`false` 全在主会话。用户「动态判断谁用子 agent」**仅当本项为 true** 时有效，否则该说明失效。各 f2s 阶段细则见技能正文（模板未统一写死）。 |",
+    "| `switchAgentVerification` | " +
+      String(switchAgentVerification) +
+      " | **切换 agent 校验**：`false` 时落盘侧同会话内验（子写子验、主写主验）。`true` 且技能写明依赖本项时交叉验：子落盘→主验，主落盘→子验；无子 agent（如 `subAgent` false）则主落盘→子验不发生、全主验。旧键 `subAgentVerification` 仍可被解析。 |",
+    "| `changeTracking.feat` | " +
+      String(feat) +
+      " | `true` → `f2s-kb-feat` **步骤 0** 必须创建/续作 `.task/active/` 变更追踪任务；`false` → 跳过，不创建 `.task/` 目录。 |",
+    "| `changeTracking.fix` | " +
+      String(fix) +
+      " | `true` → `f2s-kb-fix` **步骤 0** 必须创建/续作 `.task/active/` 变更追踪任务；`false` → 跳过。 |",
+    "| `changeTracking.implement` | " +
+      String(implement) +
+      " | `true` → `f2s-implement-tech-design` **步骤 2.5** 写入任务清单、**步骤 5** 归档完成；`false` → 跳过。 |",
+  ].join("\n");
+}
+
+function renderCodexAgents(templateBody, skillsSummaryLines, projectConfig) {
+  const summary =
+    skillsSummaryLines.length > 0
+      ? skillsSummaryLines.join("\n")
+      : "- 当前未发现可用技能。";
+  let body = templateBody.replace("{{FLOW2SPEC_CODEX_SKILLS_SUMMARY}}", summary);
+  body = body.replace(
+    "{{FLOW2SPEC_PROJECT_CONFIG}}",
+    renderProjectConfigBlock(projectConfig),
+  );
+  return body;
+}
+
+function buildCodexAgentsMd(templatesDir, projectConfig) {
+  const templatePath = path.join(templatesDir, "AGENTS.md");
+  const skillsDir = path.join(templatesDir, "skills");
+  const templateBody = fs.readFileSync(templatePath, "utf8");
+  const skillLines = readSkillSummary(skillsDir);
+  return renderCodexAgents(templateBody, skillLines, projectConfig);
+}
+
+module.exports = { buildCodexAgentsMd, renderProjectConfigBlock };

package/lib/flow2specConfig.js

@@ -0,0 +1,229 @@
+const path = require("path");
+const fs = require("fs");
+
+const CONFIG_FILENAME = "flow2spec.config.json";
+
+const DEFAULTS = {
+  subAgent: false,
+  // switchAgentVerification：false=落盘侧同会话内验；true+技能绑定=交叉验（子落盘主验/主落盘子验）
+  switchAgentVerification: false,
+  changeTracking: {
+    feat: false,
+    fix: false,
+    implement: false,
+  },
+};
+
+/**
+ * 所有已知配置字段描述，供 init 交互提示使用。
+ * 新增字段在此追加，cli.js 会自动对缺失字段发起提问。
+ * 支持点号分隔的嵌套键，如 "changeTracking.feat"（对应 { changeTracking: { feat: ... } }）。
+ */
+const CONFIG_FIELDS = [
+  {
+    key: "subAgent",
+    type: "boolean",
+    default: false,
+    question: "启用子 Agent 并行执行？（适合大型项目；小项目建议默认 N）",
+  },
+  {
+    key: "switchAgentVerification",
+    type: "boolean",
+    default: false,
+    question: "启用交叉验证（子 agent 落盘 → 主 agent 验；需配合技能使用）",
+  },
+  {
+    key: "changeTracking.feat",
+    type: "boolean",
+    default: false,
+    question: "启用变更追踪 - f2s-kb-feat（新增能力时创建可续作的任务清单）？",
+  },
+  {
+    key: "changeTracking.fix",
+    type: "boolean",
+    default: false,
+    question: "启用变更追踪 - f2s-kb-fix（修正能力时创建可续作的任务清单）？",
+  },
+  {
+    key: "changeTracking.implement",
+    type: "boolean",
+    default: false,
+    question: "启用变更追踪 - f2s-implement-tech-design（实现技术方案时创建可续作的任务清单）？",
+  },
+];
+
+function normalizeBool(value, fallback) {
+  if (value === true || value === "true" || value === 1 || value === "1")
+    return true;
+  if (value === false || value === "false" || value === 0 || value === "0")
+    return false;
+  return fallback;
+}
+
+/**
+ * 读取点号分隔键对应的嵌套值，如 "changeTracking.feat" → raw.changeTracking?.feat
+ */
+function getNestedValue(obj, dottedKey) {
+  const parts = dottedKey.split(".");
+  let cur = obj;
+  for (const p of parts) {
+    if (!cur || typeof cur !== "object") return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+/**
+ * 读取项目根 flow2spec.config.json，与 DEFAULTS 合并。
+ * 文件不存在时返回默认副本（不自动创建文件）。
+ * changeTracking 兼容旧版布尔值（true/false → 全部子项同值）。
+ */
+function loadFlow2specConfig(cwd) {
+  const abs = path.join(cwd, CONFIG_FILENAME);
+  const out = {
+    ...DEFAULTS,
+    changeTracking: { ...DEFAULTS.changeTracking },
+  };
+  if (!fs.existsSync(abs)) {
+    return out;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch (e) {
+    throw new Error(
+      `${CONFIG_FILENAME} JSON 解析失败：${e.message || String(e)}`,
+    );
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return out;
+  }
+  if (Object.prototype.hasOwnProperty.call(raw, "subAgent")) {
+    out.subAgent = normalizeBool(raw.subAgent, DEFAULTS.subAgent);
+  }
+  if (Object.prototype.hasOwnProperty.call(raw, "switchAgentVerification")) {
+    out.switchAgentVerification = normalizeBool(
+      raw.switchAgentVerification,
+      DEFAULTS.switchAgentVerification,
+    );
+  } else if (Object.prototype.hasOwnProperty.call(raw, "subAgentVerification")) {
+    // 旧键名，仍读取；新落盘请用 switchAgentVerification
+    out.switchAgentVerification = normalizeBool(
+      raw.subAgentVerification,
+      DEFAULTS.switchAgentVerification,
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(raw, "changeTracking")) {
+    const ct = raw.changeTracking;
+    if (typeof ct === "boolean") {
+      // 旧版布尔值：统一应用到全部子项
+      out.changeTracking = { feat: ct, fix: ct, implement: ct };
+    } else if (ct && typeof ct === "object" && !Array.isArray(ct)) {
+      out.changeTracking = {
+        feat: normalizeBool(ct.feat, DEFAULTS.changeTracking.feat),
+        fix: normalizeBool(ct.fix, DEFAULTS.changeTracking.fix),
+        implement: normalizeBool(ct.implement, DEFAULTS.changeTracking.implement),
+      };
+    }
+  }
+  return out;
+}
+
+/**
+ * 返回配置文件中尚未存在的字段列表（用于 init 时只提示新增字段）。
+ * 文件不存在时返回全部字段。支持点号嵌套键。
+ */
+function getMissingConfigFields(cwd) {
+  const abs = path.join(cwd, CONFIG_FILENAME);
+  if (!fs.existsSync(abs)) return CONFIG_FIELDS;
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return [];
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return CONFIG_FIELDS;
+  return CONFIG_FIELDS.filter((f) => {
+    const parts = f.key.split(".");
+    if (parts.length === 2) {
+      const parent = raw[parts[0]];
+      // 旧版布尔值视为已配置，不再重复询问
+      if (typeof parent === "boolean") return false;
+      return !parent || !Object.prototype.hasOwnProperty.call(parent, parts[1]);
+    }
+    return !Object.prototype.hasOwnProperty.call(raw, f.key);
+  });
+}
+
+/**
+ * 将点号嵌套键的 values 对象合并入 target，支持一层嵌套。
+ * 例如 { "changeTracking.feat": true } → target.changeTracking.feat = true
+ */
+function mergeValues(target, values) {
+  const result = { ...target };
+  for (const [key, val] of Object.entries(values)) {
+    const parts = key.split(".");
+    if (parts.length === 2) {
+      result[parts[0]] = {
+        ...(result[parts[0]] && typeof result[parts[0]] === "object"
+          ? result[parts[0]]
+          : {}),
+        [parts[1]]: val,
+      };
+    } else {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+/**
+ * 若项目根不存在配置文件，则写入配置（优先用 values，其次包模板，再次 DEFAULTS）。
+ * 已存在时：若 values 中有缺失字段，则补写这些字段；否则不覆盖。
+ * @param {object} [options.values]  用户交互收集到的字段值，优先级高于模板文件
+ */
+function ensureFlow2specProjectConfig(cwd, templatesDir, options = {}) {
+  const { overwrite = false, values } = options;
+  const dest = path.join(cwd, CONFIG_FILENAME);
+  const src = path.join(templatesDir, CONFIG_FILENAME);
+
+  if (fs.existsSync(dest) && !overwrite) {
+    if (values && typeof values === "object" && Object.keys(values).length > 0) {
+      let existing;
+      try {
+        existing = JSON.parse(fs.readFileSync(dest, "utf8"));
+      } catch {
+        existing = {};
+      }
+      const merged = mergeValues(existing, values);
+      if (JSON.stringify(merged) !== JSON.stringify(existing)) {
+        fs.writeFileSync(dest, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+        return { created: false, updated: true, path: dest };
+      }
+    }
+    return { created: false, path: dest };
+  }
+
+  let base;
+  if (fs.existsSync(src)) {
+    try {
+      base = JSON.parse(fs.readFileSync(src, "utf8"));
+    } catch {
+      base = { ...DEFAULTS, changeTracking: { ...DEFAULTS.changeTracking } };
+    }
+  } else {
+    base = { ...DEFAULTS, changeTracking: { ...DEFAULTS.changeTracking } };
+  }
+  const merged = values && typeof values === "object" ? mergeValues(base, values) : base;
+  fs.writeFileSync(dest, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  return { created: true, path: dest };
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  DEFAULTS,
+  CONFIG_FIELDS,
+  loadFlow2specConfig,
+  getMissingConfigFields,
+  ensureFlow2specProjectConfig,
+};