@double-codeing/flow2spec 3.0.18 → 3.1.0

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

@@ -21,7 +21,7 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 | `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
 | `.Knowledge/template/` | 终稿/技术方案模板 |
 | `.Knowledge/index.md` | 人类可读索引 |
-| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`） |
+| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`） |
 | `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |
 | `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
 | `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
@@ -38,15 +38,38 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 ## 路径约束
 
 1. `.Knowledge/topics` 是知识路由主题层，允许并鼓励通过 `f2s-*` 技能维护。
-2. `f2s-ctx-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
+2. `f2s-kb-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` 会删除遗留文件）。
 
 ---
 
+## 主题元数据
+
+`manifest-routing.json.topicMetadata` 是 topic 的机读治理元数据，只用于盘点、过滤、路由审计、升级补缺和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不作为执行强制性的事实源，也不驱动 `topicId` 或文件名变化。执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。
+
+`topicMetadata` 独立于 `topicPaths`，key 必须是 `topicPaths` 中已存在的 topicId。新增 topic 时有明确证据可同步写入；仅补分类不得创建 topic、重命名 topic 或拆分 topic。
+
+| 字段 | 取值 | 说明 |
+| --- | --- | --- |
+| `primary` | `feature` / `module` / `config` / `policy` | 单值主分类。取 topic 最核心的性质，读 topic 正文后写入。 |
+| `tags` | `feature` / `module` / `config` / `policy` 数组 | 可选次要分类，不得与 `primary` 重复。 |
+| `confidence` | `manual` / `inferred` | `manual` 为人工确认；`inferred` 为有明确证据推断；证据不足时不写 metadata，并在摘要列为待确认。 |
+
+类型含义：
+
+| 类型 | 阅读预期 |
+| --- | --- |
+| `feature` | 已落地业务/产品能力背景 |
+| `module` | 目录、包、模块边界与工程结构 |
+| `config` | 配置项、开关、默认值、初始化参数 |
+| `policy` | 流程、规则、约束、门禁、禁止项、agent 编排、技能步骤 |
+
+---
+
 ## 相关文档
 
 - [使用说明](./使用说明.md)
 - [命令说明](./命令说明.md)
 - [体系与原理](./体系与原理.md)
-- [使用案例-模拟对话](./使用案例-模拟对话.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)

package/docs//350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -142,9 +142,9 @@ graph LR
 
     D1["架构文档"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
     D2["PDF/初稿"] -->|f2s-doc-final| FIN
-    FIN --> CTX["f2s-ctx-build"] --> K
+    FIN --> CTX["f2s-kb-build"] --> K
 
-    OLD["存量代码/文档"] -->|f2s-doc-add| K
+    OLD["存量代码/文档"] -->|f2s-kb-add| K
 
     NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
     BE --> IMPL["实现xxx技术方案"] -->|自动触发implement-tech-design规则| K
@@ -294,7 +294,7 @@ git log .Knowledge/
 
   a3f1c2  f2s-kb-feat: 新增退款状态机路由
   b7e9d1  f2s-kb-fix: 修正 RestTemplate 注入约定
-  c2a8f0  f2s-ctx-build: 订单服务架构说明入库
+  c2a8f0  f2s-kb-build: 订单服务架构说明入库
   d5b3e9  f2s-kb-sync: 沉淀支付重试队列设计
 
   代码变更  +  知识变更  →  同一 commit 或相邻 commit
@@ -547,7 +547,7 @@ flow2spec init cursor codex          ← 跳过 Claude
 ```
 添加主题                              删除主题
 ─────────────────────               ─────────────────────
-1. 写 topics/xxx.md                  f2s-ctx-rm stock-docs/xxx.md
+1. 写 topics/xxx.md                  f2s-kb-rm stock-docs/xxx.md
 2. 写 matchers/m-xxx.json                    ↓
 3. 在 manifest-routing 注册          自动清除 topics/ + manifest
                                      + index 引用

package/lib/init.js

@@ -21,6 +21,9 @@ const {
 } = require("./flow2specConfig");
 const { writeClaudeAgentHooks } = require("./claudeSettingsAdapter");
 
+const KNOWLEDGE_TOPIC_TYPES = ["feature", "module", "config", "policy"];
+const KNOWLEDGE_TOPIC_CONFIDENCE = ["manual", "inferred"];
+
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
@@ -175,6 +178,45 @@ function mergeTopicDependencies(templateDeps, existingDeps) {
   return out;
 }
 
+function normalizeTopicMetadataEntry(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  if (!KNOWLEDGE_TOPIC_TYPES.includes(entry.primary)) return null;
+  const confidence =
+    typeof entry.confidence === "string" &&
+    KNOWLEDGE_TOPIC_CONFIDENCE.includes(entry.confidence)
+      ? entry.confidence
+      : null;
+  if (!confidence) return null;
+  const result = { primary: entry.primary, confidence };
+  if (Array.isArray(entry.tags) && entry.tags.length > 0) {
+    const validTags = dedupeStringArray(entry.tags).filter(
+      (t) =>
+        KNOWLEDGE_TOPIC_TYPES.includes(t) &&
+        t !== entry.primary,
+    );
+    if (validTags.length > 0) result.tags = validTags;
+  }
+  return result;
+}
+
+function mergeTopicMetadata(templateMetadata, existingMetadata, topicPaths) {
+  const out = {};
+  const topicIds = new Set(Object.keys(topicPaths || {}));
+  // existingMetadata 先写，templateMetadata 后写覆盖——模板优先
+  for (const metadata of [existingMetadata, templateMetadata]) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      continue;
+    }
+    for (const [topicId, entry] of Object.entries(metadata)) {
+      if (!topicIds.has(topicId)) continue;
+      const normalized = normalizeTopicMetadataEntry(entry);
+      if (!normalized) continue;
+      out[topicId] = normalized;
+    }
+  }
+  return out;
+}
+
 function buildMergedRouting(templateRouting, existingRouting) {
   const mergedTaskRules = unionByKey(
     templateRouting.taskToTopicRules,
@@ -223,6 +265,14 @@ function buildMergedRouting(templateRouting, existingRouting) {
     },
     taskToTopicRules: mergedTaskRules,
   };
+  const mergedTopicMetadata = mergeTopicMetadata(
+    templateRouting.topicMetadata,
+    existingRouting.topicMetadata,
+    knownMerged.topicPaths,
+  );
+  if (Object.keys(mergedTopicMetadata).length > 0) {
+    knownMerged.topicMetadata = mergedTopicMetadata;
+  }
 
   const knownKeys = new Set(Object.keys(knownMerged));
   const extras = {};
@@ -548,6 +598,59 @@ function validateKnowledgeRouting(cwd) {
     }
   }
 
+  if (routing.topicMetadata !== undefined) {
+    if (
+      !routing.topicMetadata ||
+      typeof routing.topicMetadata !== "object" ||
+      Array.isArray(routing.topicMetadata)
+    ) {
+      throw new Error("topicMetadata 必须是对象。");
+    }
+    for (const [topicId, metadata] of Object.entries(routing.topicMetadata)) {
+      if (!topicIds.has(topicId)) {
+        throw new Error(`topicMetadata 引用了不存在的 topic：${topicId}`);
+      }
+      if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        throw new Error(`topicMetadata.${topicId} 必须是对象。`);
+      }
+      for (const key of Object.keys(metadata)) {
+        if (!["primary", "tags", "confidence"].includes(key)) {
+          throw new Error(`topicMetadata.${topicId} 包含未知字段：${key}`);
+        }
+      }
+      if (!KNOWLEDGE_TOPIC_TYPES.includes(metadata.primary)) {
+        throw new Error(
+          `topicMetadata.${topicId}.primary 非法：${metadata.primary}`,
+        );
+      }
+      if (!KNOWLEDGE_TOPIC_CONFIDENCE.includes(metadata.confidence)) {
+        throw new Error(
+          `topicMetadata.${topicId}.confidence 非法：${metadata.confidence}`,
+        );
+      }
+      if (metadata.tags !== undefined) {
+        if (!Array.isArray(metadata.tags)) {
+          throw new Error(`topicMetadata.${topicId}.tags 必须是数组。`);
+        }
+        const seenTags = new Set();
+        for (const tag of metadata.tags) {
+          if (!KNOWLEDGE_TOPIC_TYPES.includes(tag)) {
+            throw new Error(`topicMetadata.${topicId}.tags 包含非法值：${tag}`);
+          }
+          if (tag === metadata.primary) {
+            throw new Error(
+              `topicMetadata.${topicId}.tags 不应与 primary 重复：${tag}`,
+            );
+          }
+          if (seenTags.has(tag)) {
+            throw new Error(`topicMetadata.${topicId}.tags 包含重复值：${tag}`);
+          }
+          seenTags.add(tag);
+        }
+      }
+    }
+  }
+
   const matcherMap =
     matcherData?.matchers && typeof matcherData.matchers === "object"
       ? matcherData.matchers
@@ -666,9 +769,21 @@ function copySkills(cwd, agentRoot, templatesDir) {
   if (fs.existsSync(skillsSrc)) {
     const skillsDest = path.join(destRoot, "skills");
     ensureDir(skillsDest);
-    for (const name of fs.readdirSync(skillsSrc)) {
+    const templateNames = new Set(fs.readdirSync(skillsSrc));
+    for (const name of templateNames) {
       copyRecursive(path.join(skillsSrc, name), path.join(skillsDest, name));
     }
+    // 删除配置根中以 f2s- 开头、但已不存在于 templates/skills/ 的旧 skill 目录
+    // 只清理 Flow2Spec 管理的 skill，不触碰用户自定义 skill
+    // LEGACY_SKILLS：非 f2s- 开头的历史旧名，也需一并清理
+    const LEGACY_SKILLS = new Set(["stock-docs-vs-req-docs"]);
+    if (fs.existsSync(skillsDest)) {
+      for (const name of fs.readdirSync(skillsDest)) {
+        if ((name.startsWith("f2s-") || LEGACY_SKILLS.has(name)) && !templateNames.has(name)) {
+          fs.rmSync(path.join(skillsDest, name), { recursive: true, force: true });
+        }
+      }
+    }
   }
 }
 

package/package.json

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

package/templates/AGENTS.md

@@ -30,6 +30,7 @@
 1. **必须先读机器索引**：优先读取 **`./.Knowledge/manifest-routing.json`** 做主题路由；按需依据 `taskToTopicRules[].matcherPath` 读取对应 matcher 分片（单文件，路径形如 **`./.Knowledge/matchers/<id>.json`**）取匹配词；无法命中时进入补召回阶段。
    - 若存在 `taskToTopicRules`，优先按任务规则路由主题。
    - 若命中主题含 `topicDependencies`，先读依赖主题再读主主题。
+   - 若存在 `topicMetadata`，仅将其中 `primary` / `tags` 作为阅读预期：`config` 关注配置项 / 开关 / 默认值；`policy` 关注正文中的必须 / 禁止 / 门禁 / 流程约束；`feature` 作为已落地能力背景；`module` 作为目录 / 包 / 模块边界背景。`topicMetadata` 不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性；无明确分类证据时不写 metadata，并在摘要列为待确认。
    - `manifest` 仅通过 `f2s-*` 技能流程维护，不假设存在额外 CLI 命令。
 2. **人工索引按需读取**：仅在需要校验主题语义与边界时读取 **`./.Knowledge/index.md`**。
    - `index.md` 不是机读事实源，仅承担人读导航与语义边界说明。
@@ -49,7 +50,7 @@
    - 用户明确要求“全量检查/不要遗漏”。
 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/manifest-routing.json`**（除非用户说明已通过 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 等更新路由或知识、或手动改了 manifest；**勿将**仅执行 `flow2spec init` 当作业务知识库已更新）；禁止为枚举而遍历整个 **`./.Knowledge/matchers/`**；禁止 **`./.Knowledge/index.md`** 与 routing 交替「刷清单」。
    - 禁止把 **`./.Knowledge/stock-docs/`** 作为“按方案实现代码”的直接输入文档。
    - Flow2Spec 执行条令以 **`./AGENTS.md`**（完整）、**`./.codex/topics/f2s-*.md`** 与 **`./.codex/skills/`** 为准；**`.codex/AGENTS.md`** 仅为目录指针，不可替代根 `AGENTS.md`；勿使用仓库内 **非上述路径** 的同名条令文件作为执行依据，以免口径分叉。
    - 禁止把 `fallbackTopic` 当作最终命中直接实施改动；`fallbackTopic` 仅作安全兜底与澄清前置上下文。
@@ -61,7 +62,7 @@
 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`）
+4. `./.Knowledge/topics/<topic>.md`（摘要；涉及统一入口、路由细则、`implement-tech-design` / `f2s-doc-routing` 等时，按需续读下文 **「专题长文」** 所列 `./.codex/topics/f2s-*.md`）
 5. `./.Knowledge/stock-docs/<doc>.md`（按需）
 6. 业务代码（按需；路径以仓库内实际目录为准）
 
@@ -74,7 +75,7 @@
 ## 可用主题
 
 - 不在此处维护静态主题列表，避免与知识库演进漂移。
-- 每次任务均以 **`./.Knowledge/manifest-routing.json`** 的 `topicPaths`、`taskToTopicRules`、`fallbackTopic` 为唯一路由事实，并按每条规则的 `matcherPath` 读取 matcher 分片。
+- 每次任务均以 **`./.Knowledge/manifest-routing.json`** 的 `topicPaths`、`taskToTopicRules`、`fallbackTopic` 为唯一路由事实，并按每条规则的 `matcherPath` 读取 matcher 分片；`topicMetadata` 只作治理与阅读预期，不是路由事实源。
 - 若路由清单与 **`./.Knowledge/index.md`** 语义不一致，以路由清单为准并提示用户同步修正。
 
 ## 专题长文（`./.codex/topics/`）
@@ -83,13 +84,12 @@
 
 - **统一入口**：`./.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`
+- **f2s-doc-routing**：`./.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 相关任务时，先读本文件（**`./AGENTS.md`**）与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。
 

package/templates/knowledge/index.md

@@ -23,14 +23,14 @@
 | 主题 | 路径 | 适用场景 | 关联文档（摘要） |
 | --- | --- | --- | --- |
 | 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)（可选） |
+| f2s-doc-routing | `.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) |
 | f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话续作 | 长文：配置根 `rules/f2s-task.*`；Codex：`.codex/topics/f2s-task.md` |
 | f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现；始终维护 `.task/` | 技能：`skills/f2s-req-plan/SKILL.md`；依赖 `f2s-task` |
 
 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
-其中 **`implement-tech-design`**、**`stock-docs-vs-req-docs`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。
+其中 **`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` 前置同源，按需打开）。
 
 ---
 
@@ -62,9 +62,9 @@
 
 | 情况 | 你怎么做 |
 | --- | --- |
-| 有文档但没配到（1a） | 维护侧：`f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
+| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-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` 不撰写业务文档**，以模板补齐与配置根落盘为主，勿与知识库内容更新混为一谈。
+**说明**：「路由/知识已更新」指 `f2s-*`（如 `f2s-kb-build`、`f2s-kb-sync`、`f2s-kb-add`、`f2s-kb-fix` 等）产出或手改 `manifest-routing` / `matchers` 分片；**`flow2spec init` 不撰写业务文档**，以模板补齐与配置根落盘为主，勿与知识库内容更新混为一谈。

package/templates/knowledge/manifest-routing.json

@@ -6,15 +6,44 @@
   "fallbackTopic": "fallback-triage",
   "topicDependencies": {
     "implement-tech-design": [
-      "stock-docs-vs-req-docs"
+      "f2s-doc-routing"
     ],
     "f2s-req-plan": [
       "f2s-task"
     ]
   },
+  "topicMetadata": {
+    "implement-tech-design": {
+      "primary": "policy",
+      "confidence": "manual"
+    },
+    "f2s-doc-routing": {
+      "primary": "policy",
+      "confidence": "manual"
+    },
+    "fallback-triage": {
+      "primary": "policy",
+      "confidence": "manual"
+    },
+    "config-precheck": {
+      "primary": "config",
+      "tags": [
+        "policy"
+      ],
+      "confidence": "manual"
+    },
+    "f2s-task": {
+      "primary": "policy",
+      "confidence": "manual"
+    },
+    "f2s-req-plan": {
+      "primary": "policy",
+      "confidence": "manual"
+    }
+  },
   "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",
+    "f2s-doc-routing": ".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",
     "f2s-task": ".Knowledge/topics/f2s-task.md",
@@ -34,7 +63,7 @@
       "matcherId": "m-implement-from-spec",
       "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json",
       "topics": [
-        "stock-docs-vs-req-docs",
+        "f2s-doc-routing",
         "implement-tech-design"
       ]
     },
@@ -43,7 +72,7 @@
       "matcherId": "m-doc-routing",
       "matcherPath": ".Knowledge/matchers/m-doc-routing.json",
       "topics": [
-        "stock-docs-vs-req-docs"
+        "f2s-doc-routing"
       ]
     },
     {
@@ -63,4 +92,4 @@
       ]
     }
   ]
-}
+}

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

@@ -2,7 +2,7 @@
 
 # 终稿概述模版
 
-> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-ctx-build** 技能更新 `.Knowledge/topics`、`.Knowledge/index.md` 与（按需）路由清单（`manifest-routing` + `matchers/*.json`）。  
+> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-kb-build** 技能更新 `.Knowledge/topics`、`.Knowledge/index.md` 与（按需）路由清单（`manifest-routing` + `matchers/*.json`）。  
 > 适用：后端服务、前端/客户端、全栈、产品与设计说明等，按需保留或省略章节。  
 > **在 Flow2Spec 中**：主模板路径为 `.Knowledge/template/终稿模版.md`；配置根不再写入 `template/` 副本。  
 > **执行 f2s-doc-final 技能时**：本模版仅作为**结构参考与写作提示**，不强制套用；转换以原文内容与逻辑为主，按需采纳章节建议。
@@ -99,4 +99,4 @@
 
 - 将上述括号内的占位替换为实际内容；与文档类型无关的章节可整节删除或标「（不适用）」。
 - 至少保留 **核心概念、业务规则、关键流程** 三个二级标题，其余按需增删。
-- 保存为 `.Knowledge/stock-docs/<方案名>_终稿.md` 后，按 **f2s-ctx-build** 技能、以该路径为入参即可更新 `.Knowledge/topics`、`.Knowledge/index.md`，并在需要时更新路由清单。
+- 保存为 `.Knowledge/stock-docs/<方案名>_终稿.md` 后，按 **f2s-kb-build** 技能、以该路径为入参即可更新 `.Knowledge/topics`、`.Knowledge/index.md`，并在需要时更新路由清单。

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

@@ -34,7 +34,7 @@
 不由 Agent 自行推断，直接问用户：
 
 > 当前任务未命中路由。请确认：**这个领域的文档是否已录入知识库？**
-> - 是 → 可能是路由词条缺失，建议执行 `f2s-ctx-build` / `f2s-kb-sync` 补充路由后重试
+> - 是 → 可能是路由词条缺失，建议执行 `f2s-kb-build` / `f2s-kb-sync` 补充路由后重试
 > - 否 → 知识库当前无此覆盖，可选择：下钻业务源码 / 补充 `req-docs` 后按方案实现
 > - 不确定 → 请检查 `.Knowledge/stock-docs/` 是否有相关文档，再告知
 
@@ -47,7 +47,7 @@
 | 分诊结论 | 下一步 |
 |----------|--------|
 | 已命中主题，补齐上下文后 | 跳转至该 topic，按 `match → expand → verify → act` 执行 |
-| 用户确认文档已录入，路由词条缺失 | 提示执行 `f2s-ctx-build` / `f2s-kb-sync` 补路由，本次暂停或下钻源码 |
+| 用户确认文档已录入，路由词条缺失 | 提示执行 `f2s-kb-build` / `f2s-kb-sync` 补路由，本次暂停或下钻源码 |
 | 用户确认库中无覆盖 | 提供两条路：下钻源码 / 补充 `req-docs` 后实现 |
 | 用户不确定，仍无法定位 | 停止执行，向用户说明原因，等待明确指令 |
 

package/templates/knowledge/topics/f2s-stock-docs-vs-req-docs.md

@@ -1,18 +1,18 @@
-# stock-docs-vs-req-docs（路由摘要）
+# f2s-doc-routing（路由摘要）
 
 > **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。  
 > **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。
 
 ## 本文件作用
 
-- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`stock-docs-vs-req-docs`**。
+- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。
 - 仅保留**目录分工**记忆点。
 
 ## 目录分工（须与规则一致）
 
 | 目录 | 用途 |
 | --- | --- |
-| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-ctx-build` / `f2s-doc-final` 等优先落盘。 |
+| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 |
 | `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 |
 
 **原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。

package/templates/rules/f2s-flow2spec-unified-entry.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
    - 若命中主题在 `topicDependencies` 中存在依赖，先读依赖主题，再读主主题。
    - 路由清单仅通过 `f2s-*` 技能流程维护，不依赖额外 CLI 子命令。
 2. `.Knowledge/index.md` 按需读取，仅用于确认主题语义与边界。
-3. 再读 `.Knowledge/topics/<topic>.md`（**路由摘要**：主题 id、路径约定、下一步指针）；若主题为 **`implement-tech-design`** 或 **`stock-docs-vs-req-docs`**，**必须继续读取**配置根 **`rules/f2s-implement-tech-design.*` / `rules/f2s-stock-docs-vs-req-docs.*` 全文**作为执行依据（`.Knowledge/topics` 内同名文件不重复长文）。
+3. 再读 `.Knowledge/topics/<topic>.md`（**路由摘要**：主题 id、路径约定、下一步指针）；若主题为 **`implement-tech-design`** 或 **`f2s-doc-routing`**，**必须继续读取**配置根 **`rules/f2s-implement-tech-design.*` / `rules/f2s-stock-docs-vs-req-docs.*` 全文**作为执行依据（`.Knowledge/topics` 内同名文件不重复长文）。
 4. 若需要背景，再读 `.Knowledge/stock-docs/<doc>.md`。
 5. 仅在前四步不足时下钻业务源码。
 6. 命中后必须执行 `match -> expand -> verify -> act`：
@@ -58,6 +58,7 @@ alwaysApply: true
 - `taskToTopicRules[].matcherPath`：匹配词分片直链路径，按需读取单个 matcher 文件。
 - `taskToTopicRules[].matcherId`：matcher 的稳定标识，需与 matcher 分片内 `id` 一致。
 - `topicDependencies`：主主题命中后先加载依赖主题。
+- `topicMetadata`：主题治理元数据，只影响阅读预期，不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性；执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。读到 `topicMetadata[topicId].primary` / `tags` 时：`config` 关注配置项、开关、默认值、初始化参数；`policy` 优先检查正文中的必须/禁止/门禁/流程约束；`feature` 作为已落地业务/产品能力背景；`module` 作为目录、包、模块边界与工程结构背景。`confidence` 仅允许 `manual` / `inferred`；无明确分类证据时不写 metadata。
 - `matcherPath(includeAny)`：任务关键词匹配词表。
 - `fallbackTopic`：任务与关键词都未命中时必须读取，但仅作低置信度兜底，不是最终执行依据。
 - `.Knowledge/manifest-routing.json + matcherPath 分片文件` 是机读事实源（关键词仅在 `matchers/*.json`）。
@@ -68,10 +69,10 @@ alwaysApply: true
 
 | 情况 | 对策 |
 | --- | --- |
-| **1a 库里有文档但未配路由** | 用 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补 `taskToTopicRules`、`matcherPath` 分片、`topicPaths`；扩充 `includeAny` 覆盖用户常用说法。Agent 侧：走 `fallbackTopic` 分诊并提示「需补路由」，**不**靠全仓扫文件代替配置。 |
+| **1a 库里有文档但未配路由** | 用 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补 `taskToTopicRules`、`matcherPath` 分片、`topicPaths`；扩充 `includeAny` 覆盖用户常用说法。Agent 侧：走 `fallbackTopic` 分诊并提示「需补路由」，**不**靠全仓扫文件代替配置。 |
 | **1b 命中了但上下文不够** | 先 `expand`（`topicDependencies` + 次高候选），再 `verify` 点名缺哪份 `stock-docs`/`req-docs` 或哪段 topic；仍不足则 **向用户要文档或路径**，不要无门槛跨 matcher 全量补检索。**Agent 若需下钻源码**：须先对用户做**可见的缺口说明**（已读 KB、缺什么、拟读哪 1～2 个文件），见 **`f2s-knowledge-preflight`**「缺口闸门」；**禁止**无说明地连续 `Grep`/乱序探源。 |
 | **2 库里没有对应文档** | 一次读完 routing + 已命中 matcher + 相关 topic 后，在回复中 **明确承认知识库无覆盖**，再选：下钻业务代码 / 请用户补充 `req-docs` 或 PRD。**禁止**用反复读清单假装「再找一遍就会有」。**下钻源码前**同样须满足 **`f2s-knowledge-preflight`**「缺口闸门」的可见说明。 |
-| **2a 反复读清单耗 token** | **同一任务线内** `manifest-routing.json` 视为稳定快照：再次全文读取须说明理由（例如用户声明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或**手动编辑**了 manifest/matcher）。**勿将**仅执行 **`flow2spec init`** 等同于「业务知识库已更新」：`init` 以模板补齐、配置根落盘与包级路由结构对齐为主；**stock-docs / req-docs、topics 路由摘要、matchers 词条**由 **`f2s-*` 技能流程**维护；**包模板 `templates/rules/*.mdc`** 为 Flow2Spec 规则事实源，`init` 同步到配置根 **`rules/*.mdc`**（或等价扩展名）并镜像 **`.codex/topics/*.md`**（条数与包模板一致，含统一入口与专题长文）。只读 **当前规则对应的单个** `matcherPath`；不要为枚举而遍历整个 `matchers/` 目录。`index.md` 仅在需核对主题语义时打开，禁止与 manifest 交替「刷清单」。 |
+| **2a 反复读清单耗 token** | **同一任务线内** `manifest-routing.json` 视为稳定快照：再次全文读取须说明理由（例如用户声明已通过 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 等更新路由或知识、或**手动编辑**了 manifest/matcher）。**勿将**仅执行 **`flow2spec init`** 等同于「业务知识库已更新」：`init` 以模板补齐、配置根落盘与包级路由结构对齐为主；**stock-docs / req-docs、topics 路由摘要、matchers 词条**由 **`f2s-*` 技能流程**维护；**包模板 `templates/rules/*.mdc`** 为 Flow2Spec 规则事实源，`init` 同步到配置根 **`rules/*.mdc`**（或等价扩展名）并镜像 **`.codex/topics/*.md`**（条数与包模板一致，含统一入口与专题长文）。只读 **当前规则对应的单个** `matcherPath`；不要为枚举而遍历整个 `matchers/` 目录。`index.md` 仅在需核对主题语义时打开，禁止与 manifest 交替「刷清单」。 |
 
 ### 知识缺口的执行层要点（避免「表里有写、行为没做」）
 
@@ -88,6 +89,10 @@ alwaysApply: true
 
 **例外（应显式否定）**：A、B 两种做法在逻辑上均正确，但项目已做出**排他性选择**时，须写出「不用 B」——不说清楚，读者无法判断 B 是否仍可选。
 
+## 主题创作（Topic Authoring）指针
+
+新增或修改 `.Knowledge/topics/<topic>.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**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 该条全文。
+
 ## 禁止项
 
 - **`templates/` 可下发约束**（经 `init` 会克隆到任意业务仓）：技能/规则/知识模板正文中的示例须**中性**——勿写特定业务域名称、单一组织 npm 包名、仅 Flow2Spec 产品仓存在的 `docs/` 路径；用 `<能力>`、`src/<模块>/` 等占位。

package/templates/rules/f2s-implement-tech-design.mdc

@@ -129,7 +129,7 @@ alwaysApply: false
 
 - 若方案命名不明确，可先给出命名建议并请用户确认；
 - 若方案跨度大，可按“最小可用版本 -> 增量迭代”拆分阶段交付；
-- 若用户希望沉淀知识库，可提醒后续用 `f2s-ctx-build` 同步主题与路由。
+- 若用户希望沉淀知识库，可提醒后续用 `f2s-kb-build` 同步主题与路由。
 
 ---
 

package/templates/rules/f2s-karpathy-guidelines.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # Karpathy 式编码行为准则
 
-> 来源与同步：[forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)（MIT），思想来自 [Andrej Karpathy 对 LLM 写代码常见问题的观察](https://x.com/karpathy/status/2015883857489522876)。与项目内 Flow2Spec / `f2s-*` 规则**并行**；若某条与 f2s 强制步骤冲突，**以 f2s 与项目约定为准**。
+> 与项目内 Flow2Spec / `f2s-*` 规则**并行**；若某条与 f2s 强制步骤冲突，**以 f2s 与项目约定为准**。
 
 用于减少常见「模型写代码」失误的行为约定。
 

package/templates/rules/f2s-stock-docs-vs-req-docs.mdc

@@ -6,11 +6,11 @@ globs:
 alwaysApply: false
 ---
 
-> **唯一长文**：本文件为 **stock-docs-vs-req-docs** 的完整约定。`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-stock-docs-vs-req-docs.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。
+> **唯一长文**：本文件为 **f2s-doc-routing** 的完整约定。`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-stock-docs-vs-req-docs.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。
 
 # stock-docs 与 req-docs
 
-- **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-ctx-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-doc-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。
+- **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-kb-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-kb-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。
 - **`.Knowledge/req-docs/`**：需求澄清、技术方案（前后端/数据/任务等）、`f2s-doc-pdf` 输出的「按方案实现」MD；`implement-tech-design` 的触发范围为 `.Knowledge/req-docs/**/*.md`。
 
-完整约定见本规则与 **`skills/stock-docs-vs-req-docs/SKILL.md`**；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。
+完整约定见本规则与 **`skills/f2s-doc-routing/SKILL.md`**；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。