@double-codeing/flow2spec 3.0.15 → 3.0.17

package/README.en.md

@@ -10,7 +10,7 @@
 🔧 **Quick start**:
 
 ```bash
-npx @ctrip/flow2spec@latest init
+npx @double-codeing/flow2spec@latest init
 ```
 
 ---
@@ -68,7 +68,7 @@ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock key
 **Minimum viable setup is an empty skeleton.**
 
 ```bash
-npx @ctrip/flow2spec@latest init
+npx @double-codeing/flow2spec@latest init
 ```
 
 1 minute generates the directory structure + routing config. Empty, ready to use. **Next requirement hits whichever area → you document that area.** No upfront investment needed.
@@ -83,6 +83,72 @@ Real data from a production repo running for 3 months:
 
 ---
 
+## Usage Flow
+
+### Step 1: Initialize (one-time)
+
+```bash
+npx @double-codeing/flow2spec@latest init
+```
+
+Follow the prompts to completion — generates the `.Knowledge/` directory structure and routing config skeleton.
+
+---
+
+### Step 2: Build the Knowledge Base (one-time)
+
+In your Agent tool (Cursor / Claude Code):
+
+1. `/f2s-doc-arch` — Scan your project architecture, generate an architecture draft, and follow the flow until topics are created
+
+> This step is done once. You won't need to repeat it for daily development.
+
+2. `/f2s-doc-add <folder path>` — Import any feature modules that haven't been added yet
+
+> Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.
+
+---
+
+### Step 3: Daily Development (every feature or fix)
+
+**Large features:**
+
+```
+/f2s-req-clarify  one-line description or paste PRD    ← clarify requirements
+/f2s-req-backend                                       ← generate technical proposal
+natural language: implement the proposal above         ← AI starts coding
+(debug and verify)
+/f2s-kb-feat  add xxx capability                       ← if something's missing
+/f2s-kb-fix   fix xxx                                  ← if there's a bug
+/f2s-kb-sync                                           ← sync knowledge base
+/f2s-git-commit                                        ← check and commit
+```
+
+**Small changes / quick fixes:**
+
+```
+/f2s-kb-feat  add xxx capability                       ← missing feature
+/f2s-kb-fix   fix xxx                                  ← bug fix
+```
+
+---
+
+## Quick Command Reference
+
+| Command | Purpose |
+|---|---|
+| `/f2s-req-clarify` | Clarify requirements |
+| `/f2s-req-backend` | Generate technical proposal |
+| `/f2s-kb-feat` | Add a new capability |
+| `/f2s-kb-fix` | Fix a bug |
+| `/f2s-kb-sync` | Sync knowledge base |
+| `/f2s-git-commit` | Commit code |
+| `/f2s-doc-add <path>` | Import API module into knowledge base |
+
+For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
+
+---
+
 ## When NOT to Use
 
 - **One-off scripts** — throwaway code is faster with a few Markdown files for AI context

package/README.md

@@ -10,7 +10,7 @@
 🔧 **快速体验**：
 
 ```bash
-npx @ctrip/flow2spec@latest init
+npx @double-codeing/flow2spec@latest init
 ```
 
 ---
@@ -69,7 +69,7 @@ topic 里，AI 不用从源码猜。
 **最小可用集是一个空骨架。**
 
 ```bash
-npx @ctrip/flow2spec@latest init
+npx @double-codeing/flow2spec@latest init
 ```
 
 1 分钟生成目录结构 + 路由配置，空的，直接跑。**下次需求命中哪块，写哪块**，不提前建设。
@@ -84,6 +84,72 @@ npx @ctrip/flow2spec@latest init
 
 ---
 
+## 使用流程
+
+### 第一步：初始化（一次性）
+
+```bash
+npx @double-codeing/flow2spec@latest init
+```
+
+跟着提示走完，生成 `.Knowledge/` 目录结构和路由配置骨架。
+
+---
+
+### 第二步：建知识库（一次性）
+
+在 Agent 工具（Cursor / Claude Code）中执行：
+
+1. `/f2s-doc-arch` — 扫描项目架构，生成架构说明初稿，跟着流程走直到生成主题（topics）
+
+> 这一步只做一次，之后日常开发不需要重复。
+
+2. `/f2s-doc-add <文件夹路径>` — 把还没入库的功能模块路径补进来
+
+> 这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做
+
+---
+
+### 第三步：日常开发（每次需求）
+
+**大需求：**
+
+```
+/f2s-req-clarify  一句话需求或粘贴 PRD    ← 需求澄清
+/f2s-req-backend                          ← 生成技术方案
+自然语言：实现上面的技术方案              ← AI 开始实现
+（调试验证）
+/f2s-kb-feat  新增 xxx 能力               ← 功能缺失时补能力
+/f2s-kb-fix   修复 xxx                    ← 有 BUG 时修复
+/f2s-kb-sync                              ← 同步知识库
+/f2s-git-commit                           ← 检查并提交
+```
+
+**小需求 / 日常改动：**
+
+```
+/f2s-kb-feat  新增 xxx 能力               ← 功能缺失
+/f2s-kb-fix   修复 xxx                    ← 改 BUG
+```
+
+---
+
+## 常用命令速查
+
+| 命令 | 用途 |
+|---|---|
+| `/f2s-req-clarify` | 需求澄清 |
+| `/f2s-req-backend` | 生成技术方案 |
+| `/f2s-kb-feat` | 新增小功能 |
+| `/f2s-kb-fix` | 改 BUG |
+| `/f2s-kb-sync` | 同步知识库 |
+| `/f2s-git-commit` | 提交代码 |
+| `/f2s-doc-add <路径>` | 接口模块入知识库 |
+
+更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)
+
+---
+
 ## 什么时候别用
 
 - **一次性脚本** — 写完就删的东西，直接丢几个 Markdown 给 AI 更快

package/docs/en/architecture.md

@@ -81,6 +81,15 @@ Codex does not read the `rules/` directory; execution constraints are carried th
 - Change tracking chain: `changeTracking.*` config -> `f2s-task` rules (automatic) -> `.task/` task checklist -> cross-session continuation
 - Package template/routing shape alignment with config root: `f2s-kb-upgrade` (**do not** equate running `flow2spec init` alone with "knowledge base upgrade"); migrate legacy repo structure into `.Knowledge`: `f2s-kb-migrate`
 
+The documentation curation chain produces two document types:
+
+| | Draft (初稿) | Final (终稿) |
+|--|------|------|
+| Nature | Raw extraction from source files | Structured knowledge for AI/knowledge base consumption |
+| Structure | Source list, per-module summary, pending items | Core concepts, business rules, key flows, interfaces |
+| Perspective | "What I read" | "What the AI needs to know" |
+| Uncertain content | Retained, explicitly marked "pending" | Cleaned up or absorbed after confirmation |
+
 ---
 
 ## 6. Agent Execution Model

package/docs/en/commands-reference.md

@@ -2,6 +2,29 @@
 
 # Workflow and Skill Reference
 
+## Command Quick Reference
+
+| Command | Purpose | Category |
+|---|---|---|
+| `/f2s-doc-arch` | Scan project, generate architecture draft | Doc Curation |
+| `/f2s-doc-final` | Convert PDF / draft to standardized final-draft format | Doc Curation |
+| `/f2s-ctx-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
+| `/f2s-doc-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
+| `/f2s-ctx-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
+| `/f2s-doc-pdf` | Convert PDF technical proposal to Markdown, save to req-docs | Doc Curation |
+| `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |
+| `/f2s-req-backend` | Generate backend technical proposal from clarified requirements | Requirements |
+| `/f2s-req-plan` | Break a technical proposal into a task checklist and implement (always creates tasks, regardless of `changeTracking.*` config) | Requirements |
+| `/f2s-git-commit` | Commit code with automatic knowledge base coverage check | Commit |
+| `/f2s-kb-feat` | Add new capability + sync knowledge base | KB Maintenance |
+| `/f2s-kb-fix` | Fix a bug + auto-sync knowledge base | KB Maintenance |
+| `/f2s-kb-sync` | Sink implemented capabilities from the conversation into the knowledge base | KB Maintenance |
+| `/f2s-kb-merge` | Resolve knowledge base conflicts after a Git merge | KB Maintenance |
+| `/f2s-kb-migrate` | One-time migration of a legacy knowledge base to `.Knowledge/` | KB Maintenance |
+| `/f2s-kb-upgrade` | Upgrade knowledge base template, align manifest + matchers shards | KB Maintenance |
+
+---
+
 ## 1) Document Curation (stock-docs Pipeline)
 
 ### `f2s-doc-arch`
@@ -17,7 +40,7 @@
 
 **Relationships**:
 - **Prerequisite**: None
-- **Next Step**: `f2s-doc-final` (normalized final draft) or direct use with `f2s-ctx-build`
+- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-ctx-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
 - **Output**: `.Knowledge/stock-docs/<Architecture Overview>_draft.md`
 
 **Sub-Agent Invocation**:
@@ -234,6 +257,8 @@
 
 **Purpose**: Starting from a technical proposal or requirement description, **always creates a task checklist**, then implements the code accordingly. Does not depend on the `changeTracking` configuration; represents the user's explicit need for traceable task management.
 
+> **About task checklists**: Task checklists are not exclusive to `/f2s-req-plan`. `/f2s-kb-feat`, `/f2s-kb-fix`, and `implement-tech-design` also create task checklists automatically when the corresponding `changeTracking.*` field is set to `true` in `flow2spec.config.json`. The distinction of `/f2s-req-plan` is that it **always creates a checklist regardless of any config** — suited for large features where the user explicitly wants to track progress across sessions.
+
 **How It Works**: Runs a five-phase closed loop: parse → plan → confirm → implement → archive. (1) Parse the technical proposal for implementation points; (2) split into executable tasks at module/feature granularity and write to `.task/`; (3) show the draft to the user, lock the checklist after confirmation; (4) implement item by item, checking off `task.md` immediately when each item completes; (5) archive when all are done. Unlike the `implement-tech-design` rule, `req-plan` always carries task tracking and can parallelize implementation with sub-agents for large work; the rule path is lightweight, single-threaded coding.
 
 **Use Cases**:

package/docs/en/directory-conventions.md

@@ -16,8 +16,6 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings.
 
 | Path | Responsibility |
 | --- | --- |
-| `docs/` | Product docs (**Chinese**): usage guide, commands reference, design principles, etc. |
-| `docs/en/` | Product docs (**English**): six paired documents; see [README.md](./README.md) |
 | `.Knowledge/stock-docs/` | **L3** Architecture, final drafts, reference documents |
 | `.Knowledge/req-docs/` | **L3** Requirement clarification, technical proposals |
 | `.Knowledge/topics/` | **L2** Topic summaries (hard constraints, boundaries, pointers) |

package/docs/en/usage-guide.md

@@ -67,7 +67,11 @@ If **`changeTracking` is off** but you still need a `.task/` checklist temporari
 ### New Feature Development
 
 ```
-f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+f2s-req-clarify (one-line requirement or doc) → f2s-req-backend → implement <technical design> (strictly follows implement-tech-design rule)
+After implementation, new capability → f2s-kb-feat
+After implementation, bug fix → f2s-kb-fix
+After debugging → f2s-kb-sync
+Finally → f2s-git-commit
 ```
 
 When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.

package/docs//344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -83,6 +83,15 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并
 - 变更追踪链：`changeTracking.*` 配置 → `f2s-task` 规则（自动）→ `.task/` 任务清单 → 跨会话续作
 - 包模板/路由形态与配置根对齐：`f2s-kb-upgrade`（**勿**将单独 `flow2spec init` 等同于「知识库升级」）；旧库结构迁入 `.Knowledge`：`f2s-kb-migrate`
 
+文档沉淀链产出两类文档：
+
+| | 初稿 | 终稿 |
+|--|------|------|
+| 本质 | 从源文件提取的原始记录 | 供 AI/知识库消费的结构化知识 |
+| 结构 | 来源清单、分模块归纳、待确认项 | 核心概念、业务规则、关键流程、接口 |
+| 视角 | "我读到了什么" | "AI 需要知道什么" |
+| 不确定内容 | 保留，显式标注"待确认" | 清洗掉或已确认后吸收 |
+
 ---
 
 ## 6. Agent 执行模型

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -12,25 +12,29 @@ flow2spec init [cursor|claude|codex ...]
 flow2spec init [cursor|claude|codex ...] --reset-knowledge
 ```
 
-| init 做 | init 不做 |
-|---------|----------|
-| 补齐缺失的目录与模板文件 | 撰写或更新业务文档内容 |
-| 落盘各 agent 配置根 `rules/` `skills/` | 更新 `includeAny` 业务词条 |
-| `manifest-routing` + `matchers/` 包级结构对齐 | 替代 `f2s-*` 技能对业务语义的书写 |
+
+| init 做                                      | init 不做                      |
+| ------------------------------------------- | ---------------------------- |
+| 补齐缺失的目录与模板文件                                | 撰写或更新业务文档内容                  |
+| 落盘各 agent 配置根 `rules/` `skills/`            | 更新 `includeAny` 业务词条         |
+| `manifest-routing` + `matchers/` 包级结构对齐     | 替代 `f2s-*` 技能对业务语义的书写        |
 | `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |
 
+
 > **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
 
 ### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）
 
 执行任意 **`f2s-*` 技能**前，需要让 Agent 拿到 **`subAgent` / `switchAgentVerification` / `changeTracking`** 等实际值。Flow2Spec 在 **不同客户端** 用 **不同机制** 强化这一点；它们彼此**补充**，**不**互相替代，**权威始终**是项目根 **`flow2spec.config.json`**（须用 **Read** 与磁盘一致后再进技能正文）。
 
-| 端 | `init` 落盘与行为 | 说明 |
-| --- | --- | --- |
-| **Cursor** | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`） | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。 |
-| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。 |
-| **Codex** | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
-| **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 |
+
+| 端               | `init` 落盘与行为                                                                          | 说明                                                                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。                                                                                                                                         |
+| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。                                                                |
+| **Codex**       | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表                        | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
+| **知识库（可选）**     | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时                              | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。                                                                      |
+
 
 字段语义与默认值规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。设计视角见 [设计说明 § 四、5.1](./设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
 
@@ -67,7 +71,11 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 ### 新需求开发
 
 ```
-f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+f2s-req-clarify 一句话需求或文档 → f2s-req-backend → 实现xx技术方案 （会严格按照implement-tech-design规则走）
+实现完成后需新增能力→ f2s-kb-feat
+实现完成后需修bug→ f2s-kb-fix
+调试完成后-> f2s-kb-sync
+最后->f2s-git-commit
 ```
 
 需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-backend` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
@@ -151,3 +159,4 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 - [目录与路径约定](./目录与路径约定.md)
 - [体系与原理](./体系与原理.md)
 - [使用案例-模拟对话](./使用案例-模拟对话.md)
+

package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -2,6 +2,29 @@
 
 [English](./en/commands-reference.md)
 
+## 命令速查表
+
+| 命令 | 用途 | 分类 |
+|---|---|---|
+| `/f2s-doc-arch` | 扫描项目，生成架构说明初稿 | 文档沉淀 |
+| `/f2s-doc-final` | PDF / 初稿转《终稿模版》规范格式 | 文档沉淀 |
+| `/f2s-ctx-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
+| `/f2s-doc-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
+| `/f2s-ctx-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
+| `/f2s-doc-pdf` | PDF 技术方案转 Markdown，保存到 req-docs | 文档沉淀 |
+| `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |
+| `/f2s-req-backend` | 基于澄清结果生成后端技术方案文档 | 需求与方案 |
+| `/f2s-req-plan` | 按技术方案拆任务清单，支持并行实现 （不依赖 `changeTracking.*` 配置） | 需求与方案 |
+| `/f2s-git-commit` | 提交代码，自动检查知识库覆盖情况 | 提交 |
+| `/f2s-kb-feat` | 新增能力，补全实现 + 同步知识库 | 知识库维护 |
+| `/f2s-kb-fix` | 修复 BUG + 自动同步知识库 | 知识库维护 |
+| `/f2s-kb-sync` | 将会话中已实现能力沉淀回知识库 | 知识库维护 |
+| `/f2s-kb-merge` | 解决 Git 合并后的知识库冲突 | 知识库维护 |
+| `/f2s-kb-migrate` | 旧版知识库一次性迁移到 `.Knowledge/` | 知识库维护 |
+| `/f2s-kb-upgrade` | 知识库模板升级，对齐 manifest + matchers 分片 | 知识库维护 |
+
+---
+
 ## 1) 文档沉淀（stock-docs 链路）
 
 ### `f2s-doc-arch`
@@ -19,7 +42,7 @@
 **关联关系**：
 
 - **前置**：无
-- **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`
+- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-ctx-build`（**须终稿入参**；初稿不可直驱 build）
 - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
 
 **子 agent 调用**：
@@ -277,6 +300,8 @@
 
 **作用**：从技术方案或需求描述出发，**始终创建任务清单**，然后按清单实现代码。不依赖 `changeTracking` 配置，代表用户明确需要可追溯的任务管理。
 
+> **关于任务清单**：任务清单不是 `/f2s-req-plan` 专属。`/f2s-kb-feat`、`/f2s-kb-fix` 和 `implement-tech-design` 在 `flow2spec.config.json` 中对应 `changeTracking.*` 字段为 `true` 时同样会自动创建任务清单。`/f2s-req-plan` 的区别是**不依赖任何配置、始终创建清单**，适合用户明确希望追踪进度的大型需求。
+
 **工作原理**：执行「解析→规划→确认→实现→归档」五阶段闭环。① 解析技术方案文档提取实现要点；② 按模块/功能粒度拆分为可执行任务清单并写入 `.task/`；③ 展示草稿给用户确认后锁定清单；④ 按清单逐项实现代码，每完成一项立即打钩 `task.md`；⑤ 全部完成后归档。与 `implement-tech-design` 规则的区别：`req-plan` 始终带任务追踪且支持并行子 agent 实现，适合大型需求；后者是轻量规则驱动的单线程编码。
 
 **使用场景**：

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

@@ -16,8 +16,6 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 
 | 路径 | 职责 |
 | --- | --- |
-| `docs/` | 产品说明（**中文**）：使用说明、命令说明、设计说明等 |
-| `docs/en/` | 产品说明（**英文**）：与上表一一对应的 6 篇文档，见 [en/README.md](./en/README.md) |
 | `.Knowledge/stock-docs/` | **L3** 架构、终稿、沉淀长文档 |
 | `.Knowledge/req-docs/` | **L3** 需求澄清、技术方案长文档 |
 | `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.0.15",
+  "version": "3.0.17",
   "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": {

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

@@ -86,6 +86,15 @@
 
 ---
 
+## 来源文件
+
+> 生成本终稿时实际读取的原始路径，便于溯源与后续更新。
+
+- `<路径1>`
+- `<路径2>`
+
+---
+
 ### 使用说明
 
 - 将上述括号内的占位替换为实际内容；与文档类型无关的章节可整节删除或标「（不适用）」。

package/templates/skills/f2s-ctx-build/SKILL.md

@@ -25,6 +25,8 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 - 接收一个参数：URL 或本地路径。
 - 本地路径必须位于 `.Knowledge/stock-docs/`。
+- **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。
+- 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。
 - 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
 
 ## 生成原则
@@ -89,10 +91,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 ## 复杂场景示例
 
-用户输入：`f2s-ctx-build .Knowledge/stock-docs/回调改造_终稿.md`，且现有 `topics/callback.md` 已存在。
+用户输入：`f2s-ctx-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
 
-- 若新文档与现有 `callback` 主题高度重合：原位更新 `topics/callback.md`，不要新建 `callback-v2.md`。
-- 若新文档新增「重试补偿」子能力：可新增 `topics/callback-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `callback-retry -> callback`。
+- 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
+- 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
 - 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
 
 ## 完成后自检

package/templates/skills/f2s-doc-add/SKILL.md

@@ -46,11 +46,24 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 
 若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。
 
+## 步骤 0.5：多模块检测（输入路径 ≥ 2 时必须执行）
+
+1. **目录聚合**：按路径中的功能层目录（如 `src/<模块名>/`、顶层目录名）对文件分组。
+2. **判定规则**（满足任一即判定为「多模块」）：
+   - 文件分属 ≥ 2 个不同顶层功能目录（如 `auth/`、`payment/`）；
+   - 用户在输入中明确提及「多个功能 / 不同模块 / 分别处理」等；
+   - 文件名前缀明显不同且无共同父目录。
+3. **单模块（未触发判定）**：不中断，继续步骤 1，按现有单输出逻辑生成 `<方案名>_初稿.md`。
+4. **多模块（触发判定）**：**暂停**，向用户展示分组结果，并询问：
+   - **方案 A（推荐）**：按模块分别生成知识文件 → 每组独立走步骤 1→2→3→4，各自产出 `<模块名>_初稿.md` / `<模块名>_终稿.md`；
+   - **方案 B（合并）**：忽略模块边界，合并生成一份 `<方案名>_初稿.md`（原有行为）。
+   - **禁止**在未获用户明确选择前默认走方案 B 继续执行。
+
 ## 步骤 1：适度深度解析
 
 - 小文件通读；
 - 大文件优先结构与关键片段（导出、接口、配置、流程）；
-- 不确定内容显式标注“待确认”，禁止编造。
+- 不确定内容显式标注”待确认”，禁止编造。
 - 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。**
 
 ## 步骤 2：生成初稿
@@ -67,7 +80,8 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 
 - 参考 `.Knowledge/template/终稿模版.md`
 - 输出：`.Knowledge/stock-docs/<方案名>_终稿.md`
-- 若用户要求“先审初稿”，则停在初稿并等待确认
+- **必须填写 `## 来源文件` 小节**，列出步骤 1 实际读取的原始源文件路径
+- 若用户要求”先审初稿”，则停在初稿并等待确认
 
 ## 步骤 4：同步知识路由
 
@@ -89,7 +103,14 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 
 - 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
 - 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
-- 用户要求“先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
+- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
+
+用户输入 3 个文件：`src/auth/login.ts`、`src/payment/checkout.ts`、`src/notification/email.ts`。
+
+- 步骤 0.5 检测到文件分属 `auth/`、`payment/`、`notification/` 三个不同顶层功能目录，判定为「多模块」。
+- 向用户展示分组：`auth` 组 1 个文件、`payment` 组 1 个文件、`notification` 组 1 个文件；询问方案 A（分别生成）或方案 B（合并）。
+- 用户选方案 A：按 `auth`、`payment`、`notification` 三组各走步骤 1→2→3→4，分别产出 `auth_初稿.md`、`payment_初稿.md`、`notification_初稿.md`。
+- **禁止**在用户选择前直接合并三个模块生成 `综合_初稿.md`。
 
 ## 约束
 
@@ -103,3 +124,4 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
 2. 同主题是否避免重复新建。
 3. topic/index/manifest 是否与终稿语义一致。
+4. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。

package/templates/skills/f2s-doc-arch/SKILL.md

@@ -25,7 +25,7 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 ## 入参（均可选）
 
 | 参数           | 说明                                                                                                                                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -------------- | -------------------------- |
 | **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
 | **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |
 
@@ -68,7 +68,20 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 ## 引导与迭代
 
 - 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
-- 生成初稿后，可提示用户：可根据需要修改 `.Knowledge/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能，以该路径为入参得到终稿，再按 **f2s-ctx-build** 同步知识路由主题与索引。
+
+## 完成后的下一步（硬约束）
+
+本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-ctx-build`：
+
+1. 告知初稿路径，建议用户先审阅、补充内容。
+2. **下一步必须为 `f2s-doc-final`**：以初稿路径为入参，产出 `.Knowledge/stock-docs/<方案名>_终稿.md`（《终稿模版》规范格式）。
+3. **仅在终稿落盘后**再引导 **`f2s-ctx-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。
+4. **禁止**在完成回复中单独写「请执行 `f2s-ctx-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-ctx-build` 与 `f2s-doc-final` 并列成「二选一」。
+5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-ctx-build`。
+
+**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-ctx-build`，且 ctx-build 在终稿之后）：
+
+> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-ctx-build <终稿路径>`** 同步知识路由主题与索引。
 
 ---
 
@@ -84,4 +97,4 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 - **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
 - **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
-- 完成后用一句话总结：已生成架构说明初稿的路径，并视情况提示可补充的内容或下一步（如 f2s-doc-final、f2s-ctx-build）。
+- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-ctx-build`**；不得仅推荐 build。