@double-codeing/flow2spec 3.0.16 → 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`
@@ -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//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//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`
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.0.16",
+  "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-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 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。