@double-codeing/flow2spec 2.2.2 → 3.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "2.2.2",
-  "description": "flow2spec init：落盘 .cursor/.claude/.codex 等配置根的 rules、skills、stock-docs/req-docs，文档驱动、f2s 可写回知识库工作流。",
+  "version": "3.0.7",
+  "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {
     "type": "git",

package/templates/AGENTS.md

@@ -0,0 +1,98 @@
+# Flow2Spec 项目入口
+
+本文件由 `flow2spec init` 写入 **`./.codex/AGENTS.md`**（相对仓库根）。你正在使用 Flow2Spec 的项目中工作；知识库在 **`./.Knowledge/`**，请渐进式读取，避免一次性加载大量无关文档。
+
+## ⚠️ f2s-* 技能前置强制步骤
+
+**执行任何 `f2s-*` 技能的第一个动作，必须先用 Read 工具读取仓库根目录文件 `./flow2spec.config.json`**，获取 `subAgent` 与 `switchAgentVerification` 的实际值，再决定后续编排方式。
+
+```
+必须执行：Read("flow2spec.config.json")  ← 相对仓库根；技能正文任何步骤之前
+```
+
+**禁止在未读该文件的情况下进入技能正文的任何执行步骤。**
+
+## Flow2Spec 项目开关（`./flow2spec.config.json`；缺失时由 `flow2spec init` 从 npm 包模板补齐）
+
+**`flow2spec init` 的定位**：把 Flow2Spec **包内模板**落到当前仓库——包括 **`./.Knowledge/`**（含路由结构、快照等）与 **`./.codex/`**（本文件 **`./.codex/AGENTS.md`**、**`./.codex/skills/`**、经 init 写入的 **`./.codex/topics/*.md`**），**不负责**撰写业务 **`./.Knowledge/stock-docs/`**、**`./.Knowledge/topics/`** 正文或替代 **`f2s-*` 技能**；即 **模板与目录落盘 / 形态对齐**，不是「知识库升级命令」（升级见 **`f2s-kb-upgrade`** 技能）。
+
+执行任意 **`f2s-*` 技能**前，必须读取 `./flow2spec.config.json` 中的布尔字段（缺省或文件不存在均视为 `false`）。下表由 **最近一次 `flow2spec init`** 根据当时配置写入，**以磁盘上的文件为准**。
+
+{{FLOW2SPEC_PROJECT_CONFIG}}
+
+### `subAgent` 与 `switchAgentVerification`（语义与上表一致；以磁盘配置为准）
+
+- **`subAgent`**：`f2s-*` 技能若写明某步「用子 agent 执行」，**`true`** 时按技能使用子 agent，**`false`** 时在主会话内完成。用户可说明「**仅当** `subAgent` 为 **`true`** 时，由主 agent **动态判断**哪些子任务适合交给子 agent」——**仅当配置为 `true` 时该说明有效**；为 **`false`** 时该段要求**自动失效**，不得拆子 agent。**各技能在何阶段用子 agent** 由技能正文约定，包模板**尚未**给出统一阶段清单。
+- **`switchAgentVerification`（切换 agent 校验）**：**不是**「校验一律在主会话」；**`false` 或未启用交叉规则时**：谁在会话里**落盘**，验证与复核（对照清单、diff、自检）**就在该 agent 会话内**完成（子写子验、主写主验）。**`true` 且** 当前 **`f2s-*` 技能正文**写明依赖本项时，启用**交叉校验**：**子 agent 落盘的 → 主 agent 验**；**主 agent 落盘的 → 子 agent 验**（无子 agent 时，如 **`subAgent` 为 `false`**，则「主落盘→子验」不发生，**全在主会话**验）。
+
+## 全局约束
+
+1. **必须先读机器索引**：优先读取 **`./.Knowledge/manifest-routing.json`** 做主题路由；按需依据 `taskToTopicRules[].matcherPath` 读取对应 matcher 分片（单文件，路径形如 **`./.Knowledge/matchers/<id>.json`**）取匹配词；无法命中时进入补召回阶段。
+   - 若存在 `taskToTopicRules`，优先按任务规则路由主题。
+   - 若命中主题含 `topicDependencies`，先读依赖主题再读主主题。
+   - `manifest` 仅通过 `f2s-*` 技能流程维护，不假设存在额外 CLI 命令。
+2. **人工索引按需读取**：仅在需要校验主题语义与边界时读取 **`./.Knowledge/index.md`**。
+   - `index.md` 不是机读事实源，仅承担人读导航与语义边界说明。
+3. **专题优先**：根据任务从 **`./.Knowledge/topics/*.md`** 读取**路由摘要**（主题 id、路径、下一步指针）。Flow2Spec **包级执行条令**由 **`flow2spec init`** 写入 **`./.codex/topics/f2s-*.md`**（见下文 **「专题长文」**）；需要完整条令时**按需**打开对应文件。
+4. **长文按需**：仅在需要背景时再读 **`./.Knowledge/stock-docs/*.md`**。
+5. **需求文档路径**：默认使用 **`./.Knowledge/req-docs/*.md`**。
+6. 下钻代码前先对齐知识库：若索引已覆盖，优先遵循知识库约定。
+7. **命中后补全（必须）**：执行 `match -> expand -> verify -> act`。
+   - `match`：先基于 routing + matcherPath 得到主候选。
+   - `expand`：展开 `topicDependencies`，并保留次高候选（建议 top-2/top-3）做补充校验。
+   - `verify`：执行前做缺口检查（是否缺关键主题、边界条件、上下文文档）。
+   - `act`：仅在置信度足够时执行；低置信度必须先澄清再执行。
+8. **全量补检索触发门槛（必须）**：仅在以下条件之一成立时允许做跨 matcher 全量补检索（top-k）：
+   - `taskToTopicRules` 无命中；
+   - 主候选与次候选分差过小（低置信度）；
+   - 缺口检查失败（关键主题/依赖/上下文缺失）；
+   - 用户明确要求“全量检查/不要遗漏”。
+9. **禁止项**：
+   - 禁止跳过 **`./.Knowledge/manifest-routing.json`**、按需 `matcherPath` 分片与 **`./.Knowledge/topics/`** 直接全仓检索或直接编码；**`./.Knowledge/index.md`** 按需读取，不可替代上述机读链。
+   - 同一任务线内避免重复全文读取 **`./.Knowledge/manifest-routing.json`**（除非用户说明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或手动改了 manifest；**勿将**仅执行 `flow2spec init` 当作业务知识库已更新）；禁止为枚举而遍历整个 **`./.Knowledge/matchers/`**；禁止 **`./.Knowledge/index.md`** 与 routing 交替「刷清单」。
+   - 禁止把 **`./.Knowledge/stock-docs/`** 作为“按方案实现代码”的直接输入文档。
+   - Flow2Spec 执行条令仅以 **`./.codex/AGENTS.md`**（本文件）、**`./.codex/topics/f2s-*.md`** 与 **`./.codex/skills/`** 为准；勿使用仓库内 **非上述路径** 的同名条令文件作为执行依据，以免口径分叉。
+   - 禁止把 `fallbackTopic` 当作最终命中直接实施改动；`fallbackTopic` 仅作安全兜底与澄清前置上下文。
+   - 禁止在不满足触发门槛时做跨 matcher 全量补检索。
+10. **检索与作答节奏**：在 KB 已形成可答结论时，控制 `grep`/读盘范围与轮次；优先按 topic 给出的目录做单点 `Read`。用户未要求「全仓 / 通读依赖」时，允许**先短答再按需下钻**。细则见 **`./.codex/topics/f2s-knowledge-preflight.md`** 中 **「检索体积与作答节奏」**。
+
+## 渐进式读取顺序
+
+1. `./.Knowledge/manifest-routing.json`
+2. `./.Knowledge/matchers/<matcher>.json`（按需：通过 `taskToTopicRules[].matcherPath` 定位具体文件）
+3. `./.Knowledge/index.md`（按需，用于语义校验）
+4. `./.Knowledge/topics/<topic>.md`（摘要；涉及统一入口、路由细则、`implement-tech-design` / `stock-docs-vs-req-docs` 等时，按需续读下文 **「专题长文」** 所列 `./.codex/topics/f2s-*.md`）
+5. `./.Knowledge/stock-docs/<doc>.md`（按需）
+6. 业务代码（按需；路径以仓库内实际目录为准）
+
+## 机读事实源口径（必须遵循）
+
+- 机读路由主事实以 **`./.Knowledge/manifest-routing.json`** 为准；匹配词以 `taskToTopicRules[].matcherPath` 指向的 matcher 分片文件为准。
+- **`./.Knowledge/index.md`** 仅作人读导航与语义边界校验，不承担机读字段定义。
+- `fallbackTopic` 仅用于低置信度兜底，不作为最终执行依据；进入 fallback 后必须先补召回或澄清。
+
+## 可用主题
+
+- 不在此处维护静态主题列表，避免与知识库演进漂移。
+- 每次任务均以 **`./.Knowledge/manifest-routing.json`** 的 `topicPaths`、`taskToTopicRules`、`fallbackTopic` 为唯一路由事实，并按每条规则的 `matcherPath` 读取 matcher 分片。
+- 若路由清单与 **`./.Knowledge/index.md`** 语义不一致，以路由清单为准并提示用户同步修正。
+
+## 专题长文（`./.codex/topics/`）
+
+由 **`flow2spec init`** 将 npm 包内 **`templates/rules/*.mdc`** 去 frontmatter 后写入 **`./.codex/topics/*.md`**，与本文件、**`./.codex/skills/`** 一起构成 Flow2Spec 的可执行依据。**当前包模板**对应文件（运行时路径均在仓库根下 `.codex/topics/`）：
+
+- **统一入口**：`./.codex/topics/f2s-flow2spec-unified-entry.md`
+- **implement-tech-design**：`./.codex/topics/f2s-implement-tech-design.md`
+- **stock-docs-vs-req-docs**：`./.codex/topics/f2s-stock-docs-vs-req-docs.md`
+
+同目录下另有：
+
+- **`./.codex/topics/f2s-knowledge-preflight.md`**：**普通提问**也须先 `Read` **`./.Knowledge/manifest-routing.json`** 再下钻代码；与统一入口并行时以本条「首工具调用」为准。
+- **`./.codex/topics/f2s-config-check.md`**：内容与上文「先 Read **`./flow2spec.config.json`**」一致并含 **changeTracking** 细表；**仅**在需核对细表时按需打开，不必与上列三条并列必读。
+- **`./.codex/topics/f2s-karpathy-guidelines.md`**：通用编码行为准则（先澄清、极简、手术式修改、可验证目标）；与 f2s 路由/任务条令**并行**，硬冲突时以 **f2s 条令**为准。
+
+执行 Flow2Spec 相关任务时，先读本 **`./.codex/AGENTS.md`** 与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。
+
+## 可用 Flow2Spec 技能（自动生成）
+
+{{FLOW2SPEC_CODEX_SKILLS_SUMMARY}}

package/templates/flow2spec.config.json

@@ -0,0 +1,9 @@
+{
+  "subAgent": false,
+  "switchAgentVerification": false,
+  "changeTracking": {
+    "feat": false,
+    "fix": false,
+    "implement": false
+  }
+}

package/templates/hooks/f2s-config-inject.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * flow2spec PreToolUse hook — 在任何 f2s-* Skill 执行前自动注入 flow2spec.config.json。
+ * 由 flow2spec init --claude 写入 .claude/hooks/f2s-config-inject.js。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CFG = {
+  subAgent: false,
+  switchAgentVerification: false,
+  changeTracking: { feat: false, fix: false, implement: false },
+};
+
+/** 与 lib/flow2specConfig.js 一致，避免 hook 依赖包内路径 */
+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;
+}
+
+function emitAdditionalContext(lines) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: lines.join('\n'),
+      },
+    }),
+  );
+}
+
+function normalizeCfg(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
+  }
+  const ct = raw.changeTracking;
+  let changeTracking = { ...DEFAULT_CFG.changeTracking };
+  if (typeof ct === 'boolean') {
+    changeTracking = {
+      feat: normalizeBool(ct, DEFAULT_CFG.changeTracking.feat),
+      fix: normalizeBool(ct, DEFAULT_CFG.changeTracking.fix),
+      implement: normalizeBool(ct, DEFAULT_CFG.changeTracking.implement),
+    };
+  } else if (ct && typeof ct === 'object' && !Array.isArray(ct)) {
+    changeTracking = {
+      feat: normalizeBool(ct.feat, DEFAULT_CFG.changeTracking.feat),
+      fix: normalizeBool(ct.fix, DEFAULT_CFG.changeTracking.fix),
+      implement: normalizeBool(ct.implement, DEFAULT_CFG.changeTracking.implement),
+    };
+  }
+  const switchRaw = Object.prototype.hasOwnProperty.call(raw, 'switchAgentVerification')
+    ? raw.switchAgentVerification
+    : raw.subAgentVerification;
+  return {
+    subAgent: normalizeBool(raw.subAgent, DEFAULT_CFG.subAgent),
+    switchAgentVerification: normalizeBool(
+      switchRaw,
+      DEFAULT_CFG.switchAgentVerification,
+    ),
+    changeTracking,
+  };
+}
+
+function buildChangeTrackingLines(skillName, cfg) {
+  const lines = [];
+  const ctKeyMap = {
+    'f2s-kb-feat': 'feat',
+    'f2s-kb-fix': 'fix',
+    'f2s-implement-tech-design': 'implement',
+  };
+  const ctKey = ctKeyMap[skillName];
+  if (ctKey === undefined) return lines;
+  const ctValue = normalizeBool(
+    (cfg.changeTracking ?? {})[ctKey],
+    DEFAULT_CFG.changeTracking[ctKey],
+  );
+  lines.push('');
+  if (ctValue) {
+    const stepMap = {
+      feat: '步骤 0',
+      fix: '步骤 0',
+      implement: '步骤 2.5（写入任务清单）、2.6（随步打钩 task.md）、步骤 5（归档门禁后归档）',
+    };
+    lines.push(
+      `changeTracking.${ctKey}=true → 本技能变更追踪【必须执行】：在 ${stepMap[ctKey]} 创建或续作 .task/active/ 任务，禁止跳过。`,
+    );
+  } else {
+    lines.push(
+      `changeTracking.${ctKey}=false → 本技能变更追踪步骤跳过，不得创建 .task/ 目录。`,
+    );
+  }
+  return lines;
+}
+
+function buildCoreLines(cfg, sourceLabel) {
+  const lines = [
+    `[flow2spec] ${sourceLabel}`,
+    `  subAgent = ${cfg.subAgent}`,
+    `  switchAgentVerification = ${cfg.switchAgentVerification}`,
+    `  changeTracking = ${JSON.stringify(cfg.changeTracking)}`,
+    '',
+    'subAgent=true  → 按技能 SKILL.md 中 B/C 模式派子 agent 并行扫描，主 agent 合并落盘。',
+    'subAgent=false → 全部在主 agent 内完成，不派子 agent。',
+    'switchAgentVerification=true → 子 agent 落盘的由主 agent 校验；主 agent 落盘的由子 agent 校验（须 subAgent=true 且实际拆出子任务）。',
+  ];
+  return lines;
+}
+
+const chunks = [];
+process.stdin.on('data', (d) => chunks.push(d));
+process.stdin.on('end', () => {
+  let skillName = '';
+  try {
+    const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    skillName = String(input?.tool_input?.skill || '');
+  } catch (_err) {
+    process.exit(0);
+    return;
+  }
+
+  if (!/^f2s-/.test(skillName)) {
+    process.exit(0);
+    return;
+  }
+
+  const configPath = path.resolve(process.cwd(), 'flow2spec.config.json');
+
+  try {
+    if (!fs.existsSync(configPath)) {
+      const cfg = { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
+      const lines = [
+        '[flow2spec] 项目根不存在 flow2spec.config.json；按统一入口约定，缺失字段均视为 false。',
+        '',
+        ...buildCoreLines(cfg, '等价配置预览（建议随后 Read 或 flow2spec init 补齐该文件）：'),
+        '',
+        '可执行：flow2spec init（或从包模板复制 flow2spec.config.json 到项目根）。',
+        ...buildChangeTrackingLines(skillName, cfg),
+      ];
+      emitAdditionalContext(lines);
+      process.exit(0);
+      return;
+    }
+
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (parseErr) {
+      const cfg = { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
+      const lines = [
+        `[flow2spec] flow2spec.config.json 存在但 JSON 解析失败：${parseErr.message || String(parseErr)}`,
+        '在修复文件前，请按以下默认安全语义执行本技能（与「文件不存在」一致）：',
+        '',
+        ...buildCoreLines(cfg, '等价配置（解析失败回退）'),
+        ...buildChangeTrackingLines(skillName, cfg),
+      ];
+      emitAdditionalContext(lines);
+      process.exit(0);
+      return;
+    }
+
+    const cfg = normalizeCfg(raw);
+    const lines = [
+      ...buildCoreLines(cfg, 'flow2spec.config.json 已自动注入，执行本 f2s-* 技能前必须遵守以下配置：'),
+      '',
+      '仍建议用 Read(flow2spec.config.json) 与磁盘核对，尤其在刚编辑过该文件时。',
+      ...buildChangeTrackingLines(skillName, cfg),
+    ];
+    emitAdditionalContext(lines);
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    emitAdditionalContext([
+      `[flow2spec] f2s-config-inject hook 未预期异常：${msg}`,
+      '请手动 Read("flow2spec.config.json") 后再执行本技能；若持续失败请检查 hook 脚本与项目根路径。',
+    ]);
+  }
+  process.exit(0);
+});

package/templates/knowledge/index.md

@@ -0,0 +1,68 @@
+# Flow2Spec Knowledge Index
+
+> **路径约定**：下文 **`.Knowledge/`**、**`manifest-routing.json`** 等路径均相对于**本仓库根目录**（即已运行 `flow2spec init` 的当前项目）。
+
+本文件是 **人读导航**：主题说明、关联文档摘要、语义边界。  
+**机读事实源** 以 `.Knowledge/manifest-routing.json` + `taskToTopicRules[].matcherPath` 指向的 `.Knowledge/matchers/*.json` 分片为准（不再使用 `.Knowledge/manifest-matchers.json`）。
+
+---
+
+## 推荐阅读顺序
+
+1. `.Knowledge/manifest-routing.json`（任务路由、`topicPaths`、`topicDependencies`、`fallbackTopic`）
+2. 按需：由 `matcherPath` 读取 `.Knowledge/matchers/<id>.json`（`includeAny` 关键词）
+3. 按需：本 `index.md`（主题语义与边界）
+4. `.Knowledge/topics/<topic>.md`（执行约束与流程）
+5. 按需：`.Knowledge/stock-docs/`、`.Knowledge/req-docs/`
+6. 仍不足再下钻业务代码
+
+---
+
+## 主题一览
+
+| 主题 | 路径 | 适用场景 | 关联文档（摘要） |
+| --- | --- | --- | --- |
+| implement-tech-design | `.Knowledge/topics/f2s-implement-tech-design.md` | 按技术方案实现代码 | req：[技术方案](.Knowledge/req-docs/<技术方案>.md)（必填） |
+| stock-docs-vs-req-docs | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock：[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)（可选） |
+| fallback-triage | `.Knowledge/topics/f2s-fallback-triage.md` | 未命中或低置信度：分诊与澄清 | stock：[路由分诊说明](.Knowledge/stock-docs/<分诊说明>.md)（可选） |
+| config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关 | Codex 长文：仓库根 `.codex/topics/f2s-config-check.md`；[路由摘要](topics/f2s-config-precheck.md) |
+
+每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
+其中 **`implement-tech-design`**、**`stock-docs-vs-req-docs`**、**`config-precheck`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。
+
+---
+
+## 命中与执行（与统一入口一致）
+
+- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片的 `includeAny`。
+- **依赖**：命中主主题前，按 `topicDependencies` 先读依赖主题。
+- **兜底**：`fallbackTopic` 指向分诊主题（如 `fallback-triage`），仅低置信度上下文，**不得**当作最终命中直接改代码。
+- **执行链**：`match → expand → verify → act`；`expand` 须含依赖展开，并保留次高候选做校验。
+- **全量补检索**：仅当无命中、候选分差过小、缺口检查失败，或用户明确要求「全量检查」时允许跨 matcher 补检索。
+
+---
+
+## 目录职责
+
+| 目录 | 职责 |
+| --- | --- |
+| `topics/` | 专题规则与执行流程 |
+| `matchers/` | matcher 分片（`matcherPath` 指向） |
+| `stock-docs/` | 存量沉淀（架构、终稿等） |
+| `req-docs/` | 需求与技术方案（驱动实现） |
+| `template/` | 终稿与方案模版 |
+
+路由清单由 `f2s-*` 技能链路维护，不依赖额外 CLI 子命令。
+
+---
+
+## 常见缺口怎么处理（与统一入口一致）
+
+| 情况 | 你怎么做 |
+| --- | --- |
+| 有文档但没配到（1a） | 维护侧：`f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
+| 配到了但不够（1b） | 走依赖与次高候选 → `verify` 点名缺哪篇文档；仍缺则向用户要路径或补 `req-docs`。 |
+| 库里没有（2） | 承认缺口 → 代码下钻或请用户补需求/方案文档。 |
+| 反复读 manifest 费 token（2a） | 同一任务线内 routing 只当快照；只读命中项的单个 matcher；不遍历整个 `matchers/` 目录枚举；`index.md` 勿与 routing 循环互刷。 |
+
+**说明**：「路由/知识已更新」指 `f2s-*`（如 `f2s-ctx-build`、`f2s-kb-sync`、`f2s-doc-add`、`f2s-kb-fix` 等）产出或手改 `manifest-routing` / `matchers` 分片；**`flow2spec init` 不撰写业务文档**，以模板补齐与配置根落盘为主，勿与知识库内容更新混为一谈。

package/templates/knowledge/manifest-matchers.json

@@ -0,0 +1,35 @@
+{
+  "version": "1.0.0",
+  "generatedFrom": ".Knowledge/manifest-routing.json",
+  "matcherKey": "matcherId",
+  "sourceOfTruth": ".Knowledge/manifest-routing.json",
+  "matchers": {
+    "m-implement-from-spec": {
+      "includeAny": [
+        "按技术方案实现",
+        "实现接口",
+        "需求文档开发"
+      ]
+    },
+    "m-doc-routing": {
+      "includeAny": [
+        "文档放哪",
+        "stock-docs",
+        "req-docs",
+        "目录约定"
+      ]
+    },
+    "m-f2s-config-precheck": {
+      "includeAny": [
+        "flow2spec.config.json",
+        "subAgent",
+        "switchAgentVerification",
+        "切换 agent 校验",
+        "技能前置",
+        "f2s-config-check",
+        "f2s-config-inject",
+        "changeTracking"
+      ]
+    }
+  }
+}

package/templates/knowledge/manifest-routing.json

@@ -0,0 +1,45 @@
+{
+  "version": "2.0.0",
+  "knowledgeRoot": ".Knowledge",
+  "matcherKey": "matcherId",
+  "sourceOfTruth": ".Knowledge/manifest-routing.json",
+  "fallbackTopic": "fallback-triage",
+  "topicDependencies": {
+    "implement-tech-design": [
+      "stock-docs-vs-req-docs"
+    ]
+  },
+  "topicPaths": {
+    "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md",
+    "stock-docs-vs-req-docs": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md",
+    "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md",
+    "config-precheck": ".Knowledge/topics/f2s-config-precheck.md"
+  },
+  "taskToTopicRules": [
+    {
+      "task": "f2s-config-precheck",
+      "matcherId": "m-f2s-config-precheck",
+      "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json",
+      "topics": [
+        "config-precheck"
+      ]
+    },
+    {
+      "task": "implement-from-spec",
+      "matcherId": "m-implement-from-spec",
+      "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json",
+      "topics": [
+        "stock-docs-vs-req-docs",
+        "implement-tech-design"
+      ]
+    },
+    {
+      "task": "doc-routing",
+      "matcherId": "m-doc-routing",
+      "matcherPath": ".Knowledge/matchers/m-doc-routing.json",
+      "topics": [
+        "stock-docs-vs-req-docs"
+      ]
+    }
+  ]
+}

package/templates/knowledge/matchers/m-doc-routing.json

@@ -0,0 +1,11 @@
+{
+  "id": "m-doc-routing",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1",
+  "includeAny": [
+    "文档放哪",
+    "stock-docs",
+    "req-docs",
+    "目录约定"
+  ]
+}

package/templates/knowledge/matchers/m-f2s-config-precheck.json

@@ -0,0 +1,15 @@
+{
+  "includeAny": [
+    "flow2spec.config.json",
+    "subAgent",
+    "switchAgentVerification",
+    "切换 agent 校验",
+    "技能前置",
+    "f2s-config-check",
+    "f2s-config-inject",
+    "changeTracking"
+  ],
+  "id": "m-f2s-config-precheck",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1"
+}

package/templates/knowledge/matchers/m-implement-from-spec.json

@@ -0,0 +1,10 @@
+{
+  "id": "m-implement-from-spec",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1",
+  "includeAny": [
+    "按技术方案实现",
+    "实现接口",
+    "需求文档开发"
+  ]
+}

package/templates/{template → knowledge/template}//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md

@@ -1,8 +1,9 @@
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> **主口径（统一知识库）**：技术方案模板与产物统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/req-docs/`。
+> 本模板唯一来源为 `templates/knowledge/template/后端技术模版.md`。
 
 # 后端技术方案模版
 
-> 供 **f2s-req-backend** 技能使用。本模版在 Flow2Spec 中位于 **templates/template/**（与 docs 同级），init 时会将整目录复制到项目的 **`配置根/template/`**，本文件即 `配置根/template/后端技术模版.md`。生成 Markdown 时一级、二级标题顺序固定如下，与需求无关的整节可省略。**接口与处理流程写在同一处**，不拆章重复。
+> 供 **f2s-req-backend** 技能使用。主模板路径为 `.Knowledge/template/后端技术模版.md`；配置根不再写入 `template/` 副本。生成 Markdown 时一级、二级标题顺序固定如下，与需求无关的整节可省略。**接口与处理流程写在同一处**，不拆章重复。
 
 ---
 

package/templates/{template → knowledge/template}//347/273/210/347/250/277/346/250/241/347/211/210.md

@@ -1,10 +1,11 @@
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/stock-docs/`。
+> 本模板唯一来源为 `templates/knowledge/template/终稿模版.md`。
 
 # 终稿概述模版
 
-> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-ctx-build** 技能生成 Rules、Skills 与文档索引。  
+> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-ctx-build** 技能更新 `.Knowledge/topics`、`.Knowledge/index.md` 与（按需）路由清单（`manifest-routing` + `matchers/*.json`）。  
 > 适用：后端服务、前端/客户端、全栈、产品与设计说明等，按需保留或省略章节。  
-> **在 Flow2Spec 中**：本模版位于 **templates/template/**（与 docs 同级），init 时会将整目录复制到项目的 **`配置根/template/`**，本文件即 `配置根/template/终稿模版.md`。  
+> **在 Flow2Spec 中**：主模板路径为 `.Knowledge/template/终稿模版.md`；配置根不再写入 `template/` 副本。  
 > **执行 f2s-doc-final 技能时**：本模版仅作为**结构参考与写作提示**，不强制套用；转换以原文内容与逻辑为主，按需采纳章节建议。
 
 ---
@@ -90,4 +91,4 @@
 
 - 将上述括号内的占位替换为实际内容；与文档类型无关的章节可整节删除或标「（不适用）」。
 - 至少保留 **核心概念、业务规则、关键流程** 三个二级标题，其余按需增删。
-- 保存为 `配置根/stock-docs/<方案名>_终稿.md` 后，按 **f2s-ctx-build** 技能、以该路径为入参即可生成 Rules、Skills、文档索引。
+- 保存为 `.Knowledge/stock-docs/<方案名>_终稿.md` 后，按 **f2s-ctx-build** 技能、以该路径为入参即可更新 `.Knowledge/topics`、`.Knowledge/index.md`，并在需要时更新路由清单。

package/templates/knowledge/topics/f2s-config-precheck.md

@@ -0,0 +1,24 @@
+# config-precheck（路由摘要）
+
+## 本主题作用
+
+- 供 `manifest-routing.topicPaths` 锚定主题 id **`config-precheck`**。
+- 与执行任意 **`f2s-*` 技能**前读取项目根 **`flow2spec.config.json`**（`subAgent`、`switchAgentVerification`、`changeTracking`）相关；语义与 **`.codex/AGENTS.md`** 顶部、「统一入口」一致。
+
+## 完整条令（按需，勿在 `.Knowledge` 再维护第二份正文）
+
+| 侧 | 路径 |
+| --- | --- |
+| Codex（init 镜像，与模板同源） | [f2s-config-check.md](../../.codex/topics/f2s-config-check.md) |
+| Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） |
+| Claude | `.claude/rules/f2s-config-check.md`；PreToolUse：`templates/hooks/f2s-config-inject.js` |
+| 包模板 | `templates/rules/f2s-config-check.mdc` |
+
+## 必备步骤
+
+1. 用 **Read** 打开项目根 **`flow2spec.config.json`**（须在 `f2s-*` 技能正文任何步骤之前）。
+2. **`.codex/AGENTS.md`** 中 `{{FLOW2SPEC_PROJECT_CONFIG}}` 表为 **init 时刻快照**；与磁盘不一致时以 **Read** 结果为准。
+
+## 禁止项
+
+- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。

package/templates/knowledge/topics/f2s-fallback-triage.md

@@ -0,0 +1,60 @@
+# fallback-triage
+
+## 触发条件
+
+以下任一成立时进入本主题：
+
+- `taskToTopicRules` 无命中
+- 无法确定路由到哪个主题（多个候选相近，关键词均为通用词，无领域词命中）
+- 缺口检查失败（依赖主题或上下文文档缺失）
+
+> **进入本主题时**：`manifest-routing.json` 已在本任务线读取过，视为稳定快照，不再重读。直接基于已有路由结果分诊。
+>
+> **本主题仅用于分诊，不作为最终命中依据，不直接实施业务改动。**
+
+---
+
+## 分诊流程
+
+### 第一步：判断路由是否命中
+
+**已命中主题，但上下文不足**：
+
+1. 读取 `topicDependencies` 中的依赖主题，保留次高候选做补充校验
+2. 点名缺少哪份文档或哪段 topic
+3. 向用户要具体文档路径，补齐后继续执行
+4. **不进行无门槛的跨 matcher 全量检索**
+
+**未命中任何主题**：进入第二步。
+
+---
+
+### 第二步：向用户确认领域覆盖情况
+
+不由 Agent 自行推断，直接问用户：
+
+> 当前任务未命中路由。请确认：**这个领域的文档是否已录入知识库？**
+> - 是 → 可能是路由词条缺失，建议执行 `f2s-ctx-build` / `f2s-kb-sync` 补充路由后重试
+> - 否 → 知识库当前无此覆盖，可选择：下钻业务源码 / 补充 `req-docs` 后按方案实现
+> - 不确定 → 请检查 `.Knowledge/stock-docs/` 是否有相关文档，再告知
+
+根据用户回答走对应出口，**不在无答案时自行猜测**。
+
+---
+
+## 出口路径
+
+| 分诊结论 | 下一步 |
+|----------|--------|
+| 已命中主题，补齐上下文后 | 跳转至该 topic，按 `match → expand → verify → act` 执行 |
+| 用户确认文档已录入，路由词条缺失 | 提示执行 `f2s-ctx-build` / `f2s-kb-sync` 补路由，本次暂停或下钻源码 |
+| 用户确认库中无覆盖 | 提供两条路：下钻源码 / 补充 `req-docs` 后实现 |
+| 用户不确定，仍无法定位 | 停止执行，向用户说明原因，等待明确指令 |
+
+---
+
+## 禁止项
+
+- 禁止将本主题作为最终命中依据直接实施改动
+- 禁止跳过向用户确认，自行推断领域覆盖情况
+- 禁止在上下文不足时进行跨 matcher 全量补检索

package/templates/knowledge/topics/f2s-implement-tech-design.md

@@ -0,0 +1,21 @@
+# implement-tech-design（路由摘要）
+
+> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。  
+> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-implement-tech-design.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。
+
+## 本文件作用
+
+- 供 `manifest-routing.topicPaths` 与 `index.md` 锚定主题 id **`implement-tech-design`**。
+- 仅保留**路径与角色**记忆点，避免与 `rules/` 双份维护长文。
+
+## 路径与角色（须与规则一致）
+
+- 技术方案输入：`.Knowledge/req-docs/*.md`（及 PDF 经 `f2s-doc-pdf` 落入同目录的 MD）。
+- 存量沉淀：`.Knowledge/stock-docs/` — **不**作为「按方案写代码」的直接输入。
+
+## 下一步读什么
+
+| 环境 | 下一步 |
+| --- | --- |
+| Cursor / Claude | 打开或 @ **`rules/f2s-implement-tech-design`**，按其中步骤执行。 |
+| Codex | 读 **`.codex/topics/f2s-implement-tech-design.md`**。 |