@double-codeing/flow2spec 2.2.0

package/README.md

@@ -0,0 +1,90 @@
+# Flow2Spec
+
+Flow2Spec 把**配置根里的知识库**（`rules/`、`skills/`、`docs-index.md`、`stock-docs/` 等）与**业务代码**串成一条**可日复一日的闭环**：先落盘可加载的约定与索引 → 日常提问与实现都**优先就着知识库走** → 代码与约定演进后再用 **f2s-kb-feat** / **f2s-kb-sync** / **f2s-kb-fix** 等**写回**规则与技能，下一轮对话立刻继承，少在聊天与零散文档里重复对齐口径。
+
+**闭环为什么省事**：能力拆成一组 **f2s-*** 技能（`skills/<标识>/SKILL.md`），按「当前在闭环的哪一环」选用即可；init 一次把目录与模版备好，后续主要是**对话里触发技能 + 确认大纲/路径**，不必自己拼一套文档治理流程。
+
+**渐进式读取带来的开发体验**：**`main.mdc`**（唯一 **alwaysApply**）先给总览与入口；**`docs-index.md`** 虽不进自动上下文，但 **`main` 生成时会写入「先打开 docs-index 再按表找 Rule/Skill」的必读约定`**，从而先索引、再专题规则/技能、再 **`stock-docs/`** 长文、**必要时才下钻业务代码**；上下文**层层加深**而非整仓硬塞，**更省 token、更少噪声**，回答更贴已写进知识库的约定与模块边界。
+
+在**配置根的父目录**执行 **`flow2spec init`** 写入所选 AI 工具目录（默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`** 等）。命令与顺序见 [README-命令说明](./docs/README-命令说明.md#按使用顺序查找)，目录分工见 [目录与路径约定](./docs/README-目录与路径约定.md)。
+
+---
+
+## 快速开始
+
+```bash
+# 在目标代码仓库（配置根的父目录）执行（默认仅写入 .cursor/）
+npx @double-codeing/flow2spec init
+# 指定 AI 工具配置目录（可多选）
+npx @double-codeing/flow2spec init claude
+npx @double-codeing/flow2spec init cursor claude codex
+# 或全局安装后
+npm install -g @double-codeing/flow2spec
+flow2spec init
+```
+
+- 模板按所选 **agent** 写入对应**配置根**（如 **`.cursor/`**、**`.claude/`**、**`.codex/`**）下的 `rules/`、`skills/`、`template/` 与预建 **`stock-docs/`**（存量上下文源）、**`req-docs/`**（需求与技术方案，按代码实现）。目录分工见 [目录与路径约定](./docs/README-目录与路径约定.md)。
+- 工作流说明在 **`skills/<标识>/SKILL.md`**；在 Cursor 中由 Agent 按场景加载对应 Skill。
+- 可用 **`flow2spec --help`** 查看全部 agent 名称与示例。
+
+**init 详解**：[Flow2Spec使用说明 - init 做了什么](./docs/Flow2Spec使用说明.md#一init-做了什么)。
+
+---
+
+## 能力与入口（速览）
+
+| 环节 | 典型技能 / 用法 |
+|------|----------------|
+| **沉淀知识库** | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build**（终稿进 `stock-docs/`，产出 Rules、Skills、索引） |
+| **按方案写代码** | **`req-docs/`** 下技术方案 MD + **`implement-tech-design`**；仅有 PDF 时可用 **f2s-doc-pdf** |
+| **实现后反哺** | **f2s-kb-feat**（新能力）、**f2s-kb-sync**（会话/已实现能力 → 大纲确认后写库）、**f2s-kb-fix**（纠错并同步规则） |
+
+更细的入参、输出与顺序：[README-命令说明](./docs/README-命令说明.md) · 使用手册：[Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)。
+
+---
+
+## 原理与流程图解
+
+下图与「闭环日常流」「渐进式读取」一一对应；技能标识以 **f2s-*** 为准，与图不一致处以 [README-命令说明](./docs/README-命令说明.md) 为准。
+
+### 命令明细（名称、作用、使用时机与频率）
+
+![命令明细图：f2s 技能一览与使用频率](./docs/images/命令明细图.png)
+
+### 日常操作与项目仓库（知识库与业务代码）
+
+![日常操作流程图：各技能与知识库、业务代码的关系](./docs/images/日常操作流程图.png)
+
+### init 与配置根结构（以 `.cursor` 为例）
+
+![原理图1：flow2spec init 与配置根内知识库、技能与模版](./docs/images/原理图1.png)
+
+### main.mdc 与 docs-index.md
+
+![原理图2：规则总入口与文档索引](./docs/images/原理图2.png)
+
+### 简述：知识库与代码闭环
+
+![简述图：生成知识库 → 基于知识库实现 → 基于实现反哺知识库](./docs/images/简述图.png)
+
+---
+
+## 文档导航
+
+| 文档 | 说明 |
+|------|------|
+| [**Flow2Spec使用说明**](./docs/Flow2Spec使用说明.md) | **使用手册**：init、目录约定、推荐顺序、典型流程、技能与工作流、常见问题 |
+| [README-命令说明](./docs/README-命令说明.md) | 各命令入参/输出、**按使用顺序查找**、快速参考 |
+| [README-目录与路径约定](./docs/README-目录与路径约定.md) | **配置根**下 `stock-docs/`、`req-docs/` 等结构、路径与链接约定、文档产物阶段 |
+| [README-体系与原理](./docs/README-体系与原理.md) | 架构、设计原则、main 与 docs-index 区别 |
+
+---
+
+## CLI
+
+| 命令 | 说明 |
+|------|------|
+| `flow2spec init [agent ...]` | 将模板写入所选配置根（默认 `cursor` → `.cursor/`）；详见 **`flow2spec --help`** |
+| `flow2spec --help` | 查看用法、可选 agent（cursor / claude / codex）与示例 |
+
+技能列表与速查见 [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)。

package/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const runInit = require("./lib/init");
+const { AGENTS } = require("./lib/agents");
+
+const args = process.argv.slice(2);
+const sub = args[0];
+
+const agentList = Object.entries(AGENTS)
+  .map(([id, { label }]) => `${id}（${label}）`)
+  .join("，");
+
+const help = `
+Flow2Spec - 文档前置工作流（AI 配置模板）
+
+用法:
+  flow2spec init [agent ...]    在当前项目初始化：将模板写入所选 AI 工具配置目录
+  flow2spec --help              显示本说明
+
+agent（可多个，空格分隔；省略时默认为 cursor）：
+  ${agentList}
+
+示例:
+  flow2spec init                  # 仅写入 .cursor/（Cursor）
+  flow2spec init claude           # 仅写入 .claude/
+  flow2spec init cursor claude    # 同时写入 .cursor/ 与 .claude/
+
+init 会:
+  1. 将 templates/ 下内容复制到各所选 agent 的配置根目录下的 rules、skills、template（及预建 stock-docs/、req-docs/）
+  2. 工作流说明位于 skills 各子目录的 SKILL.md；写入 .claude/.codex 时主要为统一存放规则、技能与模版，供对应工具按各自方式加载
+
+更多说明见 README.md 或 docs/Flow2Spec使用说明.md
+`;
+
+if (sub === "--help" || sub === "-h" || !sub) {
+  console.log(help.trim());
+  process.exit(0);
+}
+
+if (sub === "init") {
+  const agentArgs = args.slice(1);
+  runInit(process.cwd(), agentArgs)
+    .then((ids) => {
+      const lines = ids.map((id) => {
+        const { root, label } = AGENTS[id];
+        return `  - ${root}/：（${label}）rules、skills、template、stock-docs、req-docs（预建）`;
+      });
+      console.log(`
+✓ Flow2Spec init 完成
+${lines.join("\n")}
+
+在 Cursor 中可通过 Agent Skills 加载 skills/ 目录下工作流（配置根为 .cursor 时）。建议阅读 README 或 docs/Flow2Spec使用说明.md。
+`);
+    })
+    .catch((e) => {
+      console.error(e.message || e);
+      process.exit(1);
+    });
+} else {
+  console.log(help.trim());
+  process.exit(1);
+}

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

@@ -0,0 +1,170 @@
+# Flow2Spec 使用说明
+
+本文档是 **Flow2Spec 的使用手册**：面向已安装或准备使用 Flow2Spec 的读者，说明 init 后日常如何使用、目录与产物约定、推荐顺序、典型流程、**skills** 工作流标识与常见问题。  
+**项目概览与快速开始** 见仓库根目录 [README.md](../README.md)。
+
+---
+
+## 文档结构一览
+
+| 章节 | 内容 |
+|------|------|
+| [一、init 做了什么](#一init-做了什么) | 执行 init 后写入哪些目录与模板 |
+| [二、文档目录约定](#二文档目录约定重要) | 配置根（如 `.cursor/`）下 **`stock-docs/`** 与 **`req-docs/`** 的分工；完整结构见 [目录与路径约定](./README-目录与路径约定.md) |
+| [三、推荐执行顺序](#三推荐执行顺序) | 上下文生成 → 提问与实现 → 实现后；[按顺序查找](./README-命令说明.md#按使用顺序查找) |
+| [四、典型流程](#四典型流程) | 架构说明、文档→上下文、技术方案→代码、全局工作流 |
+| [五、implement-tech-design 可改造](#五implement-tech-designmdc-可自行改造) | 如何按项目定制「按技术方案实现」规则 |
+| [六、技能与工作流标识](#六技能与工作流标识) | 各 SKILL 目录名与用途速览 |
+| [七、速查与相关文档](#七速查与相关文档) | 想做的事→技能 见 [命令说明 §7](./README-命令说明.md#7-快速参考按阶段)；常见问题与延伸阅读 |
+
+---
+
+## 一、init 做了什么
+
+在**配置根父目录**执行 **`flow2spec init [agent ...]`**（未全局安装时可使用 `npx @double-codeing/flow2spec init`）。**agent** 可省略，省略时默认为 **`cursor`**（写入 **`.cursor/`**）。可选 **`claude`**、**`codex`** 等，空格分隔多个时会**分别**写入多套目录（如 `.cursor/` 与 `.claude/` 各一份相同模板结构）。详见 **`flow2spec --help`**。
+
+1. **模板写入「配置根」**（来自 Flow2Spec 的 `templates/`）：对每个所选 agent，在**配置根父目录**下创建对应目录（如 **`.cursor/`**、**`.claude/`**、**`.codex/`**），并写入下列子路径（结构相同）：
+
+   | 子目录 | 内容 |
+   |--------|------|
+   | **skills/** | **Agent Skills**（`skills/<标识>/SKILL.md`）：含 **f2s-doc-arch**、**f2s-doc-final**、**f2s-ctx-build**、**f2s-ctx-rm**、**f2s-doc-pdf**、**f2s-req-clarify**、**f2s-req-backend**、**f2s-kb-sync**、**f2s-kb-fix**、**f2s-kb-feat**、**f2s-kb-merge**、**stock-docs-vs-req-docs** 等工作流说明 |
+   | **rules/** | 如 **implement-tech-design.mdc**（按技术方案实现代码的通用规则） |
+   | **template/** | 终稿模版、后端技术模版等 |
+   | **stock-docs/** | 预建空目录；你用来生成 Rules/Skills 的**存量源文档**（终稿、架构说明等）也放此处 |
+   | **req-docs/** | 预建空目录；**需求澄清、技术方案、PDF 转实现用 MD** 等放在此处（如 `.cursor/req-docs/`） |
+
+   **说明**：在 **Cursor** 中由 Agent 按需加载 **Skills**（`SKILL.md` 的 `description` 便于匹配）；写入 **`.claude/`**、**`.codex/`** 时主要为在统一目录结构下存放规则、技能与模版，供对应工具按各自方式加载。
+
+**覆盖策略**：对已存在的模板文件为**覆盖写入**（刷新 `rules/`、`skills/`、`template/` 等）。请勿依赖「跳过已存在文件」来保留本地对模板的手工修改——如需定制，建议在业务仓库中改备份或使用自有分支管理。
+
+---
+
+## 二、文档目录约定（重要）
+
+下文 **「配置根」** 表示 `flow2spec init` 所选工具对应目录（Cursor 默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`** 等）。**`stock-docs/`** 与 **`req-docs/`** 均在配置根下，是**两个并列子目录**，职责不同。
+
+| 目录 | 用途 |
+|------|------|
+| **`stock-docs/`**（如 `.cursor/stock-docs/`） | 放**用于生成 Rules、Skills、索引**的**存量源文档**（终稿、架构说明、从 PDF 整理的领域说明等）。执行 **f2s-ctx-build** 技能时传入 **`stock-docs/xxx.md`**（Cursor 下多为 `.cursor/stock-docs/xxx.md`）。 |
+| **`req-docs/`**（如 `.cursor/req-docs/`） | 放**需要实现成代码的文档**（如技术方案、接口设计、表设计）。在对话中提供 **`.cursor/req-docs/xxx.md`**（或 **`req-docs/xxx.md`**，相对配置根）并说明「按该技术方案实现代码」时，AI 按 implement-tech-design 规则执行。 |
+
+- 技术方案（含 PDF 转出的 MD）建议放在 **`req-docs/`**；仅用于给 AI 做上下文、不直接落代码的文档放在 **`stock-docs/`**（如 `.cursor/stock-docs/`）。
+- 完整目录结构、文档路径与链接约定、**文档产物阶段**（原稿→初稿→终稿）见 [README-目录与路径约定](./README-目录与路径约定.md)。
+
+---
+
+## 三、推荐执行顺序
+
+### 上下文生成
+
+| 顺序 | 技能 | 作用 |
+|------|------|------|
+| 1 | **`f2s-doc-arch`** | 生成项目架构说明**初稿** |
+| 2 | **`f2s-doc-final`** | 将初稿转为《终稿模版》规范格式，得到**终稿** |
+| 3 | **`f2s-ctx-build`** | 根据终稿生成 **Rules、Skills、文档索引**（项目上下文） |
+
+### 提问与实现环节
+
+若技术方案仅为 **PDF**，可先按 **f2s-doc-pdf** 技能处理（用户提供 PDF 路径），将 Markdown 保存到 **`req-docs/`**（如 `.cursor/req-docs/`），再在对话中提供该 MD 路径并说明按技术方案实现代码。
+
+| 顺序 | 步骤 / 技能 | 作用 |
+|------|-------------|------|
+| 1 | **按技术方案实现**（对话 + **implement-tech-design**） | 提供 **`req-docs/xxx.md`**（或 `.cursor/req-docs/...`）并说明按方案实现；AI 按 **`rules/implement-tech-design.mdc`** 读文档、列任务、提问缺项、实现代码 |
+| 2 | **`f2s-kb-fix`** | **实现后**用户指出规则错误时：修正代码并同步更新文档与全局 Rules/Skills |
+| — | **`f2s-kb-feat`** | **新增能力**时：补全实现与文档，或已实现则仅补文档与规则 |
+| 3 | **`f2s-kb-sync`** | 可指定已实现能力或零输入推断关心能力 → **大纲确认** → 写入知识库并注入上下文（可选） |
+| — | **`f2s-kb-merge`** | **merge/rebase 后**仍存在冲突标记时：上下文类（索引、规则、技能、说明文档）自动合并；实现与配置类仅列差异待确认 |
+
+完成「上下文生成」1～3 后，再按「提问与实现环节」实现代码；**f2s-kb-fix** 在实现后、用户指出某处违反规则时使用；**f2s-kb-feat** 在新增能力时使用；**f2s-kb-sync** 可按需执行。**f2s-kb-merge** 在合并分支后出现 `<<<<<<<` 等冲突时使用，与上述无固定先后。更细的按使用顺序查找见 [README-命令说明](./README-命令说明.md#按使用顺序查找)。
+
+---
+
+## 四、典型流程
+
+### 生成项目架构说明（初稿）
+
+- 使用 **`f2s-doc-arch`** 技能：根据**用户说明**（纯文字）、**已有文档路径**（如 README、设计 doc），或在不提供时**扫描代码**（不推荐），生成**项目架构说明初稿**。
+- **入参**：可选。第一参数 = 一段说明文字 或 文档路径；第二参数 = 输出路径（默认 `stock-docs/<项目名>架构说明_初稿.md`，Cursor 下多为 `.cursor/stock-docs/...`）。
+- **特点**：无固定格式，以描述清楚为准；用户说明较宽泛时会引导补充代码路径、模块划分、入口等；不推荐无输入直接扫描，若确需则先提醒再执行。
+- 生成初稿后，可再执行 **f2s-doc-final** 技能转为规范格式终稿，并配合 **f2s-ctx-build** 技能生成 Rules、Skills。
+
+### 文档 → 上下文（生成 Rules/Skills）
+
+- 将需求/模块/领域说明放到 **`stock-docs/`**（Cursor 下即 `.cursor/stock-docs/`）。
+- 使用 **`f2s-doc-final`** 将 PDF 或杂乱 MD 转为《终稿模版》规范格式：PDF 先出**初稿**（`<方案名>_初稿.md`），再执行一次出**终稿**（`<方案名>_终稿.md`）；MD 直接出终稿。
+- 使用 **`f2s-ctx-build`** 并传入 `stock-docs/<方案名>_终稿.md`（如 `.cursor/stock-docs/...`）根据终稿生成 Rules、Skills、索引（Rules、Skills 命名不带 `_终稿`，见上文「文档产物阶段」）。
+- 使用 **`f2s-kb-sync`**：可把**用户指定的「Agent 已实现的能力」**写入计划，也可**不输入任何内容**由 Agent 根据**当前上下文**推断**用户与项目关心的能力**；再汇总用户描述、Agent 描述与项目侧信息，**先输出更新大纲并经确认**，再写入 **`rules/`**、**`skills/`**、**`docs-index.md`**、**`main.mdc`** 等以**注入可加载上下文**。可附带文档路径或 `@` 文件作为素材。
+- **merge / rebase 后**：若 **docs-index.md**、**main.mdc**、专题 **rules/skills** 或 **`stock-docs/`** 下说明出现 Git 冲突标记（Cursor 下路径多在 `.cursor/`），可按 **f2s-kb-merge** 技能自动合并「上下文类」文件，实现与配置类冲突则只列差异待你确认。详见 [README-命令说明 §3.3](./README-命令说明.md#33-f2s-kb-merge)。
+
+### 技术方案 → 代码（实现用文档在配置根 req-docs/）
+
+- 在对话中**提供技术方案文档路径**（通常为 **`.cursor/req-docs/xxx.md`** 或 **`req-docs/xxx.md`**（相对配置根），或 PDF 路径），并说明「按该技术方案实现代码」。
+- AI 会按 **`rules/implement-tech-design.mdc`**（Cursor 下 `.cursor/rules/implement-tech-design.mdc`）执行：读文档、列任务、提问缺项、按顺序实现、输出待完成列表与平台配置提醒。
+- **手头只有 PDF 时**：可先按 **f2s-doc-pdf** 技能将 PDF 转成 Markdown 并保存到 **`req-docs/<方案名>.md`**（可补全流程说明），再在对话中提供该 MD 路径；或直接提供 PDF 路径，规则会先按 **f2s-doc-pdf** 技能转 MD 再继续。
+
+### 全局工作流
+
+| 技能 | 何时用 |
+|------|--------|
+| **`f2s-kb-sync`** | 可指定已实现能力或零输入推断关心能力 → 大纲确认 → 写入知识库并注入上下文（可选） |
+| **`f2s-kb-fix`** | 实现后用户指出某处违反规则时，修正代码并同步更新相关文档与全局 Rules/Skills |
+| **`f2s-kb-feat`** | 新增能力时：补全实现与文档，或已实现则仅补文档与规则 |
+| **`f2s-kb-merge`** | merge/rebase 后：自动处理 **docs-index、rules、skills、说明类 MD** 等冲突；源码与对外配置等**不擅自合并**，只对比并等用户确认 |
+
+详见 [README-命令说明](./README-命令说明.md)（含 [§3.3 f2s-kb-merge](./README-命令说明.md#33-f2s-kb-merge)）。
+
+---
+
+## 五、implement-tech-design.mdc 可自行改造
+
+**`rules/implement-tech-design.mdc`**（Cursor 下路径为 `.cursor/rules/implement-tech-design.mdc`）是通用模板，约定的是「读文档 → 列任务 → 实现前提问 → 按顺序实现 → 待完成列表与提醒」的整体流程。
+
+**你可以按自己项目的技术栈与业务对该文件做改造**，例如：
+
+- **目录与约定**：把「项目约定的配置注册处」「接口/路由目录」「MQ 定义处」「错误码定义处」等改成你们项目真实路径与命名（如 `src/config/`、`src/api/`、`src/mq/` 等）。
+- **步骤与检查项**：增加或删减步骤（如代码规范检查、内部 Code Review、发布流程提醒）。
+- **术语与示例**：把示例中的表名、接口名、错误码换成你们业务相关示例，便于 AI 与成员理解。
+- **触发条件**：调整 frontmatter 里的 `globs`，使规则在你们放「要实现成代码」的文档路径下自动加载（默认含 `**/req-docs/**/*.md`；技术方案应在 **`req-docs/`**，见 [二、文档目录约定](#二文档目录约定重要)）。
+
+改造后文件保留在项目 **`rules/`** 下即可（Cursor 下多为 `.cursor/rules/`）。注意：当前 **`flow2spec init` 对模板为覆盖写入**，再次 init 会用包内模板刷新 `rules/`、`skills/`、`template/` 等；定制规则请在业务仓库用分支或备份管理，或避免对 init 下发的文件做长期手工修改。
+
+---
+
+## 六、技能与工作流标识
+
+工作流写在 **`skills/<标识>/SKILL.md`**。Agent 主要依据各文件 **YAML frontmatter** 中的 **`name`** 与 **`description`**（触发场景）匹配；可按项目需要编辑 `description` 以增加触发词。
+
+| `name`（与目录一致） | 路径示例（配置根 `.cursor/`） | 用途摘要 |
+|----------------------|------------------------------|----------|
+| `f2s-doc-arch` | `.cursor/skills/f2s-doc-arch/SKILL.md` | 架构说明初稿 |
+| `f2s-doc-final` | `.cursor/skills/f2s-doc-final/SKILL.md` | PDF/MD → 终稿模版 |
+| `f2s-ctx-build` | `.cursor/skills/f2s-ctx-build/SKILL.md` | 终稿 → Rules/Skills/索引 |
+| `f2s-ctx-rm` | `.cursor/skills/f2s-ctx-rm/SKILL.md` | 按文档删除上下文产物 |
+| `f2s-doc-pdf` | `.cursor/skills/f2s-doc-pdf/SKILL.md` | PDF → `req-docs/` MD |
+| `f2s-req-clarify` | `.cursor/skills/f2s-req-clarify/SKILL.md` | 需求澄清 |
+| `f2s-req-backend` | `.cursor/skills/f2s-req-backend/SKILL.md` | 后端技术方案 |
+| `f2s-kb-sync` | `.cursor/skills/f2s-kb-sync/SKILL.md` | 指定已实现能力或零输入推断 → 知识库（先大纲确认）→ 注入上下文 |
+| `f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-merge` | `.cursor/skills/f2s-kb-fix/SKILL.md` 等 | 全局维护与合并冲突 |
+
+---
+
+## 七、速查与相关文档
+
+**想做的事 → 用哪个技能**（按阶段速查）：见 [README-命令说明 - 快速参考](./README-命令说明.md#7-快速参考按阶段)。  
+**按使用顺序查找**：见 [README-命令说明 - 按使用顺序查找](./README-命令说明.md#按使用顺序查找)。
+
+---
+
+### 常见问题
+
+- **希望「实现技术方案」更贴合业务**：直接编辑 **`rules/implement-tech-design.mdc`**（Cursor 下 `.cursor/rules/...`），按 [五、implement-tech-design 可改造](#五implement-tech-designmdc-可自行改造) 改造即可。
+- **技能未生效**：确认已在**配置根父目录**执行过 `flow2spec init`，且 **`skills/`** 下存在对应 **`SKILL.md`**；在对话中明确提及技能名或 `description` 中的触发词。
+- **想按使用顺序查找**：打开 [README-命令说明](./README-命令说明.md)，看开头的「按使用顺序查找」表。
+
+**相关文档**
+
+| 文档 | 说明 |
+|------|------|
+| [README-命令说明](./README-命令说明.md) | 各技能入参、输出、**按使用顺序查找** |
+| [README-体系与原理](./README-体系与原理.md) | 文档与上下文的架构、main 与 docs-index 区别 |
+| [README-目录与路径约定](./README-目录与路径约定.md) | **`stock-docs/`** / **`req-docs/`** 结构、文档产物阶段 |

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

@@ -0,0 +1,132 @@
+# 体系与原理
+
+本文档面向团队讲解 **Flow2Spec** 中「文档与上下文」的整体架构、设计原则，以及 Rules、Skills、文档索引之间的关系。适合想理解「为什么这样设计」「main 和 docs-index 有什么区别」的读者。
+
+**配置根**：`flow2spec init [agent ...]` 写入的 AI 工具目录（默认 **`.cursor/`**，亦可是 **`.claude/`**、**`.codex/`** 等）。下文图示与表格以 **`.cursor/`** 为例；若你的配置根不同，将路径中的 `.cursor` 替换为实际目录名即可。
+
+**一句话**：文档通过命令生成 **main（总地图）+ 专题 Rules（按路径加载）+ 专题 Skills（按触发词匹配）+ docs-index（文档↔产物索引）**，使 AI 能按需加载上下文，避免长文档一次性塞入。
+
+---
+
+## 文档结构一览
+
+| 章节 | 内容 |
+|------|------|
+| [1. 目标与价值](#1-目标与价值) | 为什么做「按需加载」、带来什么价值 |
+| [2. 整体架构](#2-整体架构) | 文档 → 命令 → main / Rules / Skills / docs-index 的流向 |
+| [3. 设计原则：拆解与分工](#3-设计原则拆解与分工) | 为何拆成多条 Rule、多个 Skill；Rule 与 Skill 的职责划分 |
+| [4. main.mdc 与 docs-index 的区别](#4-mainmdc-与-docs-index-的区别) | 何时看 main、何时看 docs-index |
+| [5. 版本管理与索源](#5-版本管理与索源) | sourceDoc、generatedAt；从产物找文档、从文档找产物 |
+| [6. 推荐执行顺序（概要）](#6-flow2spec-推荐执行顺序概要) | 上下文生成 → 提问与实现 → 实现后；延伸链接 |
+| [7. 小结与延伸阅读](#7-小结与延伸阅读) | 记住这几点 + 相关文档链接 |
+
+---
+
+## 1. 目标与价值
+
+- **目标**：让 Cursor 里的 AI **按需**加载项目上下文，而不是一次性塞入整份长文档。
+- **价值**：
+  - 文档 → 结构化 **Rules**（约束、约定）+ **Skills**（领域知识、步骤、示例）+ **文档索引**
+  - AI 打开某目录/某文件时，通过 **globs** 自动加载对应 Rule；通过 **description** 匹配到对应 Skill
+  - 索引入口（**main.mdc**、**docs-index**）方便人与 AI 查「某文档对应哪些产物」「项目有哪些模块」
+
+---
+
+## 2. 整体架构
+
+```
+文档（`stock-docs/*.md`；Cursor 下即 `.cursor/stock-docs/*.md`）
+        │
+        ├── **f2s-doc-arch** 技能 ──► 架构说明初稿（推荐顺序第 1 步）
+        ├── **f2s-doc-final** 技能 ──► 规范格式 MD（初稿/终稿）
+        │
+        └── **f2s-ctx-build** 技能
+                    │
+                    ├── main.mdc（唯一 alwaysApply：项目总概述 + 模块一览 + 公共能力入口）
+                    ├── 专题 Rules（`rules/*-context.mdc`，globs 限定路径）
+                    ├── 专题 Skills（`skills/<主题>/SKILL.md`，description 触发）
+                    └── docs-index.md（文档 ↔ Rules、Skills 索引表）
+```
+
+| 产物 | 说明 |
+|------|------|
+| **文档** | 生成 Rules/Skills 的源真相在 **`stock-docs/`**（如 `.cursor/stock-docs/`）；需实现成代码的技术方案在 **`req-docs/`**（如 `.cursor/req-docs/`）。 |
+| **main.mdc** | 给 AI 的「总地图」，**唯一**始终加载的 Rule；列出项目结构、模块一览、公共能力入口。 |
+| **专题 Rules** | 按主题/路径（**globs**）加载，写「必须/禁止/约定」；与 main 同在 **`rules/`**。 |
+| **专题 Skills** | 按问题/触发词（**description**）匹配，写概念、流程、方法表、示例。 |
+| **docs-index** | 表格：一行对应一份文档，列出处（文档路径、Rules、Skills、简要说明）；文件位于配置根下，与 `stock-docs/` 同级。 |
+
+---
+
+## 3. 设计原则：拆解与分工
+
+### 3.1 拆解
+
+- 长文档或多块独立内容（如接口约定、QMQ、配置、公共工具）应**拆成多条 Rule、多个 Skill**。
+- 单条更聚焦、**按需加载**，避免单文件过长、alwaysApply 过多导致上下文膨胀。
+
+### 3.2 分工
+
+| 产物 | 职责 | 加载方式 |
+|------|------|----------|
+| **Rules** | 约束、约定、作用范围；「必须/禁止/约定」 | main 唯一 alwaysApply；专题 Rule 用 **globs** 限定在相关路径 |
+| **Skills** | 领域知识、操作步骤、示例、方法表 | **description** 写清触发词与场景，Cursor 按问题匹配 |
+
+- **main.mdc**：不写细节，只写「有什么模块、入口在哪、详见哪条 rule/skill」。
+- **专题 Rule**：写该主题下的规则要点，正文可带简短示例。
+- **专题 Skill**：写何时用、概念、流程、完整方法表或示例，便于 AI 回答「怎么用 QMQ」「工具方法有哪些」。
+
+---
+
+## 4. main.mdc 与 docs-index 的区别
+
+| 项目 | main.mdc | docs-index.md |
+|------|----------|---------------|
+| **路径** | `rules/main.mdc`（Cursor：`.cursor/rules/main.mdc`） | `docs-index.md`（Cursor：`.cursor/docs-index.md`） |
+| **用途** | 项目总概述与索引，给 AI 的「总地图」 | 需求/文档索引，**按文档**列产物 |
+| **加载** | **唯一** alwaysApply 的 Rule | 不参与 alwaysApply，仅供查阅 |
+| **内容** | 项目结构、模块一览、公共能力入口 | 表格：需求/模块、文档路径、Rules、Skills、简要说明 |
+| **更新** | 仅当文档属于「功能模块」或「公共模块说明」时更新对应部分 | 每份文档占一行，生成/更新时更新该行 |
+
+**何时看哪个**：查「项目有哪些模块、公共能力在哪」→ **main.mdc**；查「某份文档生成了哪些 Rules、Skills」→ **docs-index**。
+
+---
+
+## 5. 版本管理与索源
+
+路径与字段格式（sourceDoc、generatedAt）约定见 [README-目录与路径约定 §4](./README-目录与路径约定.md#4-版本管理sourcedoc-与-generatedat)。此处侧重用法：
+
+- **sourceDoc**：每条 Rule/Skill 的 frontmatter 中写 `sourceDoc: <配置根>/stock-docs/xxx.md`（如 `.cursor/stock-docs/xxx.md`），表示「由哪份文档生成」。
+- **generatedAt**：同一 frontmatter 中写 `generatedAt: 2026-01-28T20:00:00+08:00`（东八区 ISO 8601）。
+
+| 典型问题 | 做法 |
+|----------|------|
+| 从产物找文档 | 看 Rule/Skill 的 **sourceDoc** |
+| 从文档找产物 | 看 **docs-index** 中该文档行的 Rules、Skills 列 |
+| 更新某文档的产物 | 改文档后，对同一路径再执行 **f2s-ctx-build** 技能 + `stock-docs/xxx.md`，会覆盖该文档对应的全部 Rules、Skills，并更新 docs-index 该行与 main 的相关部分 |
+
+---
+
+## 6. Flow2Spec 推荐执行顺序（概要）
+
+**上下文生成** → **提问与实现** → **实现后**（f2s-kb-fix / f2s-kb-feat / f2s-kb-sync）；**合并分支后**若**配置根**下索引、规则、技能等出现冲突标记（Cursor 下多在 `.cursor/`），可用 **f2s-kb-merge** 与实现侧冲突分流处理（见 [命令说明 §3.3](./README-命令说明.md#33-f2s-kb-merge)）。日常在 Cursor 中时 AI 自动加载 main，按路径加载 Rule、按提问匹配 Skill。  
+按使用顺序查命令与各命令入参输出见 [README-命令说明](./README-命令说明.md)；init 与典型流程见 [Flow2Spec使用说明](./Flow2Spec使用说明.md)。
+
+---
+
+## 7. 小结与延伸阅读
+
+**记住这几点**
+
+- 文档在 **`stock-docs/`**（生成上下文用；如 `.cursor/stock-docs/`），技术方案需实现成代码的在 **`req-docs/`**（如 `.cursor/req-docs/`）；产物在 **`rules/`**、**`skills/`**，索引在 **`docs-index.md`**，总入口在 **main.mdc**。
+- **拆解**：长文档拆成多条 Rule、多个 Skill，按需加载。
+- **分工**：Rule 管约束与约定，Skill 管知识与步骤；main 管总览，docs-index 管文档与产物对应关系。
+- **路径与链接**：统一按 [README-目录与路径约定](./README-目录与路径约定.md) 执行，避免引用错误。
+
+**相关文档**
+
+| 文档 | 说明 |
+|------|------|
+| [README-命令说明](./README-命令说明.md) | 各命令入参、输出、按使用顺序查找 |
+| [README-目录与路径约定](./README-目录与路径约定.md) | **`stock-docs/`** / **`req-docs/`** 结构、文档产物阶段 |
+| [Flow2Spec使用说明](./Flow2Spec使用说明.md) | init 详解、推荐顺序、技能与工作流、常见问题 |