@double-codeing/flow2spec 2.2.0 → 2.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -9
- package/cli.js +1 -1
- package/docs/Flow2Spec-/344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md +231 -0
- package/docs/Flow2Spec/344/275/277/347/224/250/350/257/264/346/230/216.md +67 -114
- package/docs/README-/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md +39 -92
- package/docs/README-/345/221/275/344/273/244/350/257/264/346/230/216.md +78 -202
- package/docs/README-/347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md +41 -84
- package/lib/claudeRulesAdapter.js +28 -0
- package/lib/init.js +36 -7
- package/package.json +1 -1
- package/templates/rules/stock-docs-vs-req-docs.mdc +1 -1
- package/templates/skills/f2s-ctx-build/SKILL.md +42 -34
- package/templates/skills/f2s-doc-add/SKILL.md +142 -0
- package/templates/skills/f2s-doc-arch/SKILL.md +2 -0
- package/templates/skills/f2s-kb-fix/SKILL.md +1 -1
- package/templates/skills/stock-docs-vs-req-docs/SKILL.md +6 -4
|
@@ -1,132 +1,79 @@
|
|
|
1
1
|
# 体系与原理
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Flow2Spec 如何把**长文档**变成 **main + 专题 Rules + 专题 Skills + docs-index**，让 AI **按需加载**、控制上下文体积。**配置根**同前（默认 `.cursor/`）。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**一句话**：**stock-docs** 里文档经 **f2s-ctx-build** 落成 **main（总览）**、**globs 规则**、**description 技能** 与 **docs-index（文档↔产物表）**；实现代码用 **req-docs** + **implement-tech-design**。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) · [README-命令说明](./README-命令说明.md) · [README-目录与路径约定](./README-目录与路径约定.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## 1. 目标与价值
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
| [1. 目标与价值](#1-目标与价值) | 为什么做「按需加载」、带来什么价值 |
|
|
16
|
-
| [2. 整体架构](#2-整体架构) | 文档 → 命令 → main / Rules / Skills / docs-index 的流向 |
|
|
17
|
-
| [3. 设计原则：拆解与分工](#3-设计原则拆解与分工) | 为何拆成多条 Rule、多个 Skill；Rule 与 Skill 的职责划分 |
|
|
18
|
-
| [4. main.mdc 与 docs-index 的区别](#4-mainmdc-与-docs-index-的区别) | 何时看 main、何时看 docs-index |
|
|
19
|
-
| [5. 版本管理与索源](#5-版本管理与索源) | sourceDoc、generatedAt；从产物找文档、从文档找产物 |
|
|
20
|
-
| [6. 推荐执行顺序（概要）](#6-flow2spec-推荐执行顺序概要) | 上下文生成 → 提问与实现 → 实现后；延伸链接 |
|
|
21
|
-
| [7. 小结与延伸阅读](#7-小结与延伸阅读) | 记住这几点 + 相关文档链接 |
|
|
13
|
+
- **目标**：按路径 / 按问题加载片段，避免整篇长文塞进一轮对话。
|
|
14
|
+
- **手段**：Rule 写约束（+ globs）；Skill 写知识与步骤（+ description）；**main** 总览；**docs-index** 查某文档对应哪些产物。
|
|
22
15
|
|
|
23
16
|
---
|
|
24
17
|
|
|
25
|
-
##
|
|
18
|
+
## 2. 整体架构
|
|
26
19
|
|
|
27
|
-
|
|
28
|
-
- **价值**：
|
|
29
|
-
- 文档 → 结构化 **Rules**（约束、约定）+ **Skills**（领域知识、步骤、示例）+ **文档索引**
|
|
30
|
-
- AI 打开某目录/某文件时，通过 **globs** 自动加载对应 Rule；通过 **description** 匹配到对应 Skill
|
|
31
|
-
- 索引入口（**main.mdc**、**docs-index**）方便人与 AI 查「某文档对应哪些产物」「项目有哪些模块」
|
|
20
|
+
在**配置根**里，和 Flow2Spec 日常闭环相关的主要是**三条线**（先建立整体印象，再下看表格）：
|
|
32
21
|
|
|
33
|
-
|
|
22
|
+
| 线 | 目录 / 产物 | 在闭环里的角色 |
|
|
23
|
+
|----|----------------|----------------|
|
|
24
|
+
| **A. 文档源** | **`stock-docs/`** | 放终稿、初稿、架构长文等；是 **f2s-ctx-build** 的输入源 |
|
|
25
|
+
| **B. 可加载知识库** | **`main.mdc`**、**`rules/`**、**`skills/`**、**`docs-index.md`** | Agent **按需**读：总览 → 索引 → 专题规则/技能 → 必要时回 **`stock-docs/`** 长文 |
|
|
26
|
+
| **C. 按方案写代码** | **`req-docs/`** + **`implement-tech-design`** | 技术方案 MD 驱动改业务代码；**不**替代 A→B 那条「把长文拆进规则与技能」的链 |
|
|
34
27
|
|
|
35
|
-
|
|
28
|
+
**阶段二：用终稿跑一次 f2s-ctx-build**——入参通常是 **`stock-docs/…_终稿.md`**（或 URL 等，见 [命令说明 §2.3](./README-命令说明.md#23-f2s-ctx-build)）。**同一次执行会一并写出 / 更新下面几类文件**；它们是**并列产物**，不是「先跑完 main 再跑 rules」的串行流水线。
|
|
36
29
|
|
|
37
|
-
|
|
38
|
-
文档（`stock-docs/*.md`；Cursor 下即 `.cursor/stock-docs/*.md`）
|
|
39
|
-
│
|
|
40
|
-
├── **f2s-doc-arch** 技能 ──► 架构说明初稿（推荐顺序第 1 步）
|
|
41
|
-
├── **f2s-doc-final** 技能 ──► 规范格式 MD（初稿/终稿）
|
|
42
|
-
│
|
|
43
|
-
└── **f2s-ctx-build** 技能
|
|
44
|
-
│
|
|
45
|
-
├── main.mdc（唯一 alwaysApply：项目总概述 + 模块一览 + 公共能力入口）
|
|
46
|
-
├── 专题 Rules（`rules/*-context.mdc`，globs 限定路径）
|
|
47
|
-
├── 专题 Skills（`skills/<主题>/SKILL.md`，description 触发）
|
|
48
|
-
└── docs-index.md（文档 ↔ Rules、Skills 索引表）
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
| 产物 | 说明 |
|
|
30
|
+
| 产物 | 作用 |
|
|
52
31
|
|------|------|
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
| **专题
|
|
56
|
-
|
|
|
57
|
-
| **docs-index** | 表格：一行对应一份文档，列出处（文档路径、Rules、Skills、简要说明）；文件位于配置根下，与 `stock-docs/` 同级。 |
|
|
32
|
+
| **main.mdc** | 唯一 **alwaysApply**；总地图、模块一览、公共入口（正文应约定先读 **docs-index** 再下钻） |
|
|
33
|
+
| **专题 Rules**（`rules/*-context.mdc`） | 必须/禁止/约定；按 **globs** 命中文件时加载 |
|
|
34
|
+
| **专题 Skills**（`skills/` 下各主题的 **SKILL.md**） | 概念、流程、示例；按 **description** 匹配问题 |
|
|
35
|
+
| **docs-index.md** | 表格式：文档路径、Rules、Skills、摘要（**非** alwaysApply，须按需读） |
|
|
58
36
|
|
|
59
37
|
---
|
|
60
38
|
|
|
61
39
|
## 3. 设计原则：拆解与分工
|
|
62
40
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
- 长文档或多块独立内容（如接口约定、QMQ、配置、公共工具）应**拆成多条 Rule、多个 Skill**。
|
|
66
|
-
- 单条更聚焦、**按需加载**，避免单文件过长、alwaysApply 过多导致上下文膨胀。
|
|
67
|
-
|
|
68
|
-
### 3.2 分工
|
|
69
|
-
|
|
70
|
-
| 产物 | 职责 | 加载方式 |
|
|
71
|
-
|------|------|----------|
|
|
72
|
-
| **Rules** | 约束、约定、作用范围；「必须/禁止/约定」 | main 唯一 alwaysApply；专题 Rule 用 **globs** 限定在相关路径 |
|
|
73
|
-
| **Skills** | 领域知识、操作步骤、示例、方法表 | **description** 写清触发词与场景，Cursor 按问题匹配 |
|
|
74
|
-
|
|
75
|
-
- **main.mdc**：不写细节，只写「有什么模块、入口在哪、详见哪条 rule/skill」。
|
|
76
|
-
- **专题 Rule**：写该主题下的规则要点，正文可带简短示例。
|
|
77
|
-
- **专题 Skill**：写何时用、概念、流程、完整方法表或示例，便于 AI 回答「怎么用 QMQ」「工具方法有哪些」。
|
|
41
|
+
- **拆解**：长文档或多块独立内容 → 多条 Rule、多个 Skill，单条更短、更聚焦。
|
|
42
|
+
- **分工**：Rule = 约束与范围；Skill = 知识与操作；main = 索引不写细节；docs-index = 文档级映射。
|
|
78
43
|
|
|
79
44
|
---
|
|
80
45
|
|
|
81
|
-
## 4. main.mdc 与 docs-index
|
|
46
|
+
## 4. main.mdc 与 docs-index.md
|
|
82
47
|
|
|
83
|
-
|
|
|
84
|
-
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
| **内容** | 项目结构、模块一览、公共能力入口 | 表格：需求/模块、文档路径、Rules、Skills、简要说明 |
|
|
89
|
-
| **更新** | 仅当文档属于「功能模块」或「公共模块说明」时更新对应部分 | 每份文档占一行，生成/更新时更新该行 |
|
|
48
|
+
| | **main.mdc** | **docs-index.md** |
|
|
49
|
+
|---|--------------|-------------------|
|
|
50
|
+
| 路径 | `rules/main.mdc` | 配置根下与 stock-docs 同级 |
|
|
51
|
+
| 角色 | 项目总览、模块与公共能力入口 | 按文档列 Rules / Skills |
|
|
52
|
+
| 加载 | **唯一 alwaysApply** | 不自动进上下文；由 **main** 约定阅读顺序 |
|
|
90
53
|
|
|
91
|
-
|
|
54
|
+
**查模块/入口** → main；**查某文档生成了哪些 Rule/Skill** → docs-index。
|
|
92
55
|
|
|
93
56
|
---
|
|
94
57
|
|
|
95
58
|
## 5. 版本管理与索源
|
|
96
59
|
|
|
97
|
-
|
|
60
|
+
字段格式见 [README-目录与路径约定 §4](./README-目录与路径约定.md#4-版本管理sourcedoc-与-generatedat)。
|
|
98
61
|
|
|
99
|
-
- **sourceDoc
|
|
100
|
-
- **
|
|
101
|
-
|
|
102
|
-
| 典型问题 | 做法 |
|
|
103
|
-
|----------|------|
|
|
104
|
-
| 从产物找文档 | 看 Rule/Skill 的 **sourceDoc** |
|
|
105
|
-
| 从文档找产物 | 看 **docs-index** 中该文档行的 Rules、Skills 列 |
|
|
106
|
-
| 更新某文档的产物 | 改文档后，对同一路径再执行 **f2s-ctx-build** 技能 + `stock-docs/xxx.md`，会覆盖该文档对应的全部 Rules、Skills，并更新 docs-index 该行与 main 的相关部分 |
|
|
62
|
+
- **sourceDoc**：产物 → 源文档。
|
|
63
|
+
- **docs-index 行**：文档 → 产物列表。
|
|
64
|
+
- **更新**：改 **stock-docs** 源文后，对同路径再执行 **f2s-ctx-build**。
|
|
107
65
|
|
|
108
66
|
---
|
|
109
67
|
|
|
110
|
-
## 6.
|
|
68
|
+
## 6. 推荐顺序（概要）
|
|
111
69
|
|
|
112
|
-
|
|
113
|
-
按使用顺序查命令与各命令入参输出见 [README-命令说明](./README-命令说明.md)；init 与典型流程见 [Flow2Spec使用说明](./Flow2Spec使用说明.md)。
|
|
70
|
+
上下文链 → **req-docs** 实现 → **f2s-kb-*** 维护；冲突 **f2s-kb-merge**。详表：[README-命令说明](./README-命令说明.md#按使用顺序查找)。
|
|
114
71
|
|
|
115
72
|
---
|
|
116
73
|
|
|
117
|
-
## 7.
|
|
118
|
-
|
|
119
|
-
**记住这几点**
|
|
74
|
+
## 7. 延伸阅读
|
|
120
75
|
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
125
|
-
|
|
126
|
-
**相关文档**
|
|
127
|
-
|
|
128
|
-
| 文档 | 说明 |
|
|
129
|
-
|------|------|
|
|
130
|
-
| [README-命令说明](./README-命令说明.md) | 各命令入参、输出、按使用顺序查找 |
|
|
131
|
-
| [README-目录与路径约定](./README-目录与路径约定.md) | **`stock-docs/`** / **`req-docs/`** 结构、文档产物阶段 |
|
|
132
|
-
| [Flow2Spec使用说明](./Flow2Spec使用说明.md) | init 详解、推荐顺序、技能与工作流、常见问题 |
|
|
76
|
+
- **路径与链接**：[README-目录与路径约定](./README-目录与路径约定.md)
|
|
77
|
+
- **命令与速查**：[README-命令说明](./README-命令说明.md)
|
|
78
|
+
- **操作手册**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)
|
|
79
|
+
- **使用案例（对话版式）**：[Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
|
|
@@ -1,258 +1,134 @@
|
|
|
1
1
|
# 工作流与技能说明
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
各 Skill（`skills/<标识>/SKILL.md`）的**入参、输出、行为**与**推荐使用顺序**。**「配置根」**：`flow2spec init` 写入的目录（默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`**）。
|
|
4
|
+
|
|
5
|
+
- 目录结构：[README-目录与路径约定](./README-目录与路径约定.md)
|
|
6
|
+
- init 概要：[Flow2Spec使用说明 · 一](./Flow2Spec使用说明.md#一init-做了什么)
|
|
7
|
+
- 架构：[README-体系与原理](./README-体系与原理.md)
|
|
8
|
+
- 使用案例：[Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
|
|
4
9
|
|
|
5
10
|
---
|
|
6
11
|
|
|
7
12
|
## 按使用顺序查找
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
20
|
-
|
|
|
21
|
-
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| | 可选 | **`f2s-kb-sync`** | 可指定已实现能力或零输入推断关心能力 → **大纲确认** → 写入知识库并注入上下文 | [§3.2](#32-f2s-kb-fix--f2s-kb-feat--f2s-kb-sync) |
|
|
25
|
-
| | merge/rebase 后 | **`f2s-kb-merge`** | 解决冲突标记：索引/规则/技能等上下文自动合并；实现与配置类仅列差异待确认 | [§3.3](#33-f2s-kb-merge) |
|
|
26
|
-
|
|
27
|
-
**汇总顺序**：init → 需求与方案（需求澄清 → 后端方案）→ 上下文生成（f2s-doc-arch → f2s-doc-final → f2s-ctx-build）→ 提问与实现（可选 f2s-doc-pdf → 按 **req-docs/** 技术方案与 **implement-tech-design** 实现代码）→ 实现后（f2s-kb-fix / f2s-kb-feat / f2s-kb-sync）；**merge/rebase 出现 `<<<<<<<` 等冲突时**可用 **f2s-kb-merge**（与上述无固定先后）。详见 [§4 推荐执行顺序](#4-推荐执行顺序flow2spec)。
|
|
14
|
+
| 阶段 | 步骤 | 技能 / 命令 | 一句话 | 详见 |
|
|
15
|
+
| ------------ | ---- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
|
|
16
|
+
| 首次 | — | `flow2spec init [agent ...]` | 写入配置根模板 | [§1](#1-flow2spec-initcli) |
|
|
17
|
+
| 需求与方案 | 1 | **f2s-req-clarify** | PRD/需求反问至清楚 | [§2.0.1](#201-f2s-req-clarify) |
|
|
18
|
+
| 需求与方案 | 2 | **f2s-req-backend** | 澄清后出后端技术文档 | [§2.0.2](#202-f2s-req-backend) |
|
|
19
|
+
| 上下文生成 | 1～3 | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build** | 初稿→终稿→Rules/Skills/索引 | [§2.1～2.3](#21-f2s-doc-arch-技能) |
|
|
20
|
+
| 上下文生成 | 可选 | **f2s-doc-add** | **工作中**：**已做好的能力** + 多个相关文件路径→解析进上下文（`stock-docs` 初稿→终稿→同 **f2s-ctx-build** 产物） | [§2.1.1](#211-f2s-doc-add-技能) |
|
|
21
|
+
| 上下文生成 | 配合 | **f2s-ctx-rm** | 按文档删产物 | [§2.4](#24-f2s-ctx-rm-技能) |
|
|
22
|
+
| 上下文生成 | 可选 | **f2s-doc-pdf** | PDF→MD（req-docs） | [§2.5](#25-f2s-doc-pdf-技能) |
|
|
23
|
+
| 提问与实现 | — | **按技术方案实现** | 提供 **`req-docs/`** 下方案 MD 路径，并说明「按方案实现」 | [§3.1](#31-按技术方案实现) |
|
|
24
|
+
| 任意时机 | 按需 | **f2s-kb-fix** / **f2s-kb-feat** | 纠错 / 新能力（不限于实现后） | [§3.2](#32-f2s-kb-fix--f2s-kb-feat--f2s-kb-sync) |
|
|
25
|
+
| 实现后 | 按需 | **f2s-kb-sync** | 会话或现状沉淀写库（典型在实现后） | [§3.2](#32-f2s-kb-fix--f2s-kb-feat--f2s-kb-sync) |
|
|
26
|
+
| merge/rebase | — | **f2s-kb-merge** | 上下文类冲突合并 | [§3.3](#33-f2s-kb-merge) |
|
|
27
|
+
|
|
28
|
+
**汇总**：init →（可选需求链）→ arch → final → ctx-build →（可选 pdf）→ req-docs + implement-tech-design →（随时 **fix** / **feat**；实现后或收尾 **sync**）；冲突用 **f2s-kb-merge**。更细速查见 [§6](#6-快速参考按阶段)。
|
|
28
29
|
|
|
29
30
|
---
|
|
30
31
|
|
|
31
32
|
## 1. flow2spec init（CLI）
|
|
32
33
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
| **创建/写入** | 对每个所选 agent：在配置根下创建 `stock-docs/`、`req-docs/`、`template/`、`rules/`、`skills/` 并复制模板。详见 [Flow2Spec使用说明 - init 做了什么](./Flow2Spec使用说明.md#一init-做了什么)。 |
|
|
39
|
-
| **结果** | 配置根为 **`.cursor/`** 时，工作流在 **`skills/`** 下；由 Agent 按场景加载对应 **SKILL.md**。 |
|
|
34
|
+
| 项 | 说明 |
|
|
35
|
+
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| 用法 | `npx @ctrip/flow2spec init` 或全局安装后 `flow2spec init [cursor \| claude \| codex ...]`；默认 **cursor** |
|
|
37
|
+
| 写入 | 各配置根下 `stock-docs/`、`req-docs/`、`template/`、`rules/`、`skills/`（见 [Flow2Spec使用说明](./Flow2Spec使用说明.md#一init-做了什么)）。**`.claude/`** 下 **`rules/*.md`**（`globs`→`paths`）；**`.cursor/`** 下 **`rules/*.mdc`** |
|
|
38
|
+
| 结果 | Agent 按场景加载 `skills/*/SKILL.md` |
|
|
40
39
|
|
|
41
40
|
---
|
|
42
41
|
|
|
43
|
-
## 2.
|
|
42
|
+
## 2. 需求与方案、上下文生成
|
|
44
43
|
|
|
45
44
|
### 2.0 需求与方案（可选）
|
|
46
45
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
#### 2.0.1 **f2s-req-clarify** 技能
|
|
50
|
-
|
|
51
|
-
针对 PRD 或需求中的模糊、缺口、歧义进行反问，直到需求足够清晰。
|
|
52
|
-
|
|
53
|
-
| 项目 | 说明 |
|
|
54
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
55
|
-
| **入参** | 可选。**第一参数**：PRD 全文、需求描述，或**文档路径**（如 **`.cursor/req-docs/xxx.md`**）；不传则基于当前对话中用户已发内容进行澄清。用户可在后续回复中补充需求条件或约束。 |
|
|
56
|
-
| **行为** | 识别需求中的模糊表述、未定义概念、缺失信息、潜在矛盾及与实现强相关但未说明的点 → 分组、具体可答地反问 → 根据用户回答迭代追问，直到主要流程、边界、异常、关键概念无歧义。 |
|
|
57
|
-
| **输出** | 无固定产出；澄清结束时可以简要总结「当前需求要点」，并提示用户可使用 **`f2s-req-backend`** 生成技术文档。 |
|
|
58
|
-
|
|
59
|
-
**注意**：本技能仅做需求澄清，不在此阶段输出技术方案或接口设计。
|
|
60
|
-
|
|
61
|
-
#### 2.0.2 **f2s-req-backend** 技能
|
|
62
|
-
|
|
63
|
-
根据**已澄清的需求**（及可选需求条件），基于当前项目的**知识库、`skills/`、`rules/`**（Cursor 下即 `.cursor/skills`、`.cursor/rules`）生成针对性的**后端技术文档**。
|
|
64
|
-
|
|
65
|
-
| 项目 | 说明 |
|
|
66
|
-
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
67
|
-
| **入参** | **第一参数（必填）**：澄清后的需求描述或需求/PRD 文档路径（如 **`.cursor/req-docs/xxx.md`** 或 `stock-docs/需求_终稿.md`）。**可选**：用户补充的需求条件（范围、必须/禁止技术、与现有模块边界、性能/安全要求等）。 |
|
|
68
|
-
| **规范来源** | 优先参考 `template/后端技术模版.md`（Cursor 下即 `.cursor/template/后端技术模版.md`）；输出章节按需选用，不必全有。 |
|
|
69
|
-
| **行为** | 读取需求与条件 → 加载项目 Rules、Skills 及已有技术方案 → 对齐项目约定（接口、配置、QMQ、错误码、表设计等）→ 撰写后端技术文档。 |
|
|
70
|
-
| **输出** | 默认 **`req-docs/<方案名>_技术方案.md`**（如 `.cursor/req-docs/...`）。技术方案**供后续代码实现使用**，不用于生成 Rules/Skills。 |
|
|
71
|
-
|
|
72
|
-
**输出章节（按需选用）**：需求概述、重点问题概述、外部接口对接、配置、QMQ、接口及流程说明、关联接口调用流程、错误码、表设计。与需求无关的章节可整节省略。
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
以下技能按**推荐顺序**使用：**`f2s-doc-arch`** → **`f2s-doc-final`** → **`f2s-ctx-build`**。另有配合使用的 **`f2s-ctx-rm`**、**`f2s-doc-pdf`**。
|
|
77
|
-
|
|
78
|
-
### 2.1 **f2s-doc-arch** 技能
|
|
79
|
-
|
|
80
|
-
根据用户说明、已有文档或扫描代码，生成**项目架构说明初稿**（无固定格式，以描述清楚为准）。
|
|
81
|
-
|
|
82
|
-
| 项目 | 说明 |
|
|
83
|
-
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
-
| **入参** | 可选。**第一参数**：一段纯文字说明，或**文档路径**（如 `README.md`、`stock-docs/xxx.md`）；不传则进入「无输入」流程（扫描代码，需用户确认，不保证质量）。**第二参数**：输出路径（默认 `stock-docs/<项目名>架构说明_初稿.md`）。 |
|
|
85
|
-
| **行为** | 有输入时：读取说明或文档 → 结合项目目录与关键文件补充、归纳 → 生成架构说明初稿；若说明较宽泛则引导用户补充代码路径、模块划分、入口等。无输入时：先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。 |
|
|
86
|
-
| **输出** | 默认 `stock-docs/<项目名>架构说明_初稿.md`；可再通过 **f2s-doc-final** 技能 转为规范格式终稿，并配合 **f2s-ctx-build** 技能 生成 Rules、Skills。 |
|
|
87
|
-
|
|
88
|
-
### 2.2 **f2s-doc-final** 技能
|
|
89
|
-
|
|
90
|
-
将 PDF 或 Markdown 转为《终稿模版》规范格式的 MD。
|
|
46
|
+
**f2s-req-clarify**：入参可选（PRD/描述/路径）；反问至清晰；本阶段不输出技术方案。结束可接 **f2s-req-backend**。
|
|
91
47
|
|
|
92
|
-
|
|
93
|
-
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
-
| **入参** | 一个：**PDF 路径**或 **MD 路径**；可选第二个参数为输出路径 |
|
|
95
|
-
| **规范来源** | 优先读取 `template/终稿模版.md`；若不存在则用命令内嵌结构 |
|
|
96
|
-
| **输出位置** | PDF 首次：`stock-docs/<方案名>_初稿.md`（初稿）；MD/初稿转为规范格式：`stock-docs/<方案名>_终稿.md`（终稿）。详见 [文档产物阶段](./README-目录与路径约定.md#3-文档产物阶段原稿--初稿--终稿)。 |
|
|
48
|
+
**f2s-req-backend**：入参必填（澄清后需求或文档路径）；参考 `template/后端技术模版.md`；默认输出 **`req-docs/<方案名>_技术方案.md`**（供实现，**不**走 f2s-ctx-build）。
|
|
97
49
|
|
|
98
|
-
|
|
50
|
+
### 2.1 f2s-doc-arch
|
|
99
51
|
|
|
100
|
-
|
|
52
|
+
**定位**：**仅**「项目/模块**架构说明初稿**」；**不是** f2s-doc-add。入参可选（说明文字或文档路径；无参=扫描代码须先确认）。输出默认 **`stock-docs/<项目名>架构说明_初稿.md`**。可接 **f2s-doc-final** → **f2s-ctx-build**。
|
|
101
53
|
|
|
102
|
-
|
|
54
|
+
### 2.1.1 f2s-doc-add
|
|
103
55
|
|
|
104
|
-
|
|
105
|
-
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
-
| **入参** | 一个：**URL**（如 `https://xxx.com/doc`）或 **本地路径**（如 `stock-docs/拼团技术方案设计.md`） |
|
|
107
|
-
| **文档位置** | 本技能入参的本地文档须为 **`stock-docs/`** 下的存量源文档（与 **`req-docs/`** 中的技术方案目录分工不同） |
|
|
108
|
-
| **行为** | 大模型拉取/读取文档 → 分析（概念、状态、流程、规则）→ 按「拆解与分工」生成/更新 main.mdc（若适用）、专题 Rules、专题 Skills、docs-index 一行 |
|
|
109
|
-
| **输出** | `rules/main.mdc`（若为功能模块或公共模块）、`rules/<主题>-context.mdc`、`skills/<主题>/SKILL.md`、`docs-index.md` 中该文档对应行；若入参为 URL 还会把原文保存到 `stock-docs/<主题>.md`。**入参通常为终稿文档**（如 `stock-docs/<方案名>_终稿.md`，相对配置根），但生成的 Rules、Skills **不带 `_终稿` 后缀**，见 [文档产物阶段](./README-目录与路径约定.md#3-文档产物阶段原稿--初稿--终稿)。 |
|
|
56
|
+
**定位**：**工作中**要把**已经做好的某条能力**（实现与说明分散在多文件）**解析进 AI 上下文**时用本技能；**多文件路径**聚合→初稿→终稿→上下文产物。**独立技能**，与 **f2s-doc-arch** 分工见 **`skills/f2s-doc-add/SKILL.md`**（含「使用时机」）。入参：**多个**本地文件路径（必填，空格/换行/`@`）；可选方案名、初稿/终稿输出路径。行为：**适度深度**读源 → **`stock-docs/<方案名>_初稿.md`** → 按 **`template/终稿模版.md`** 与 **f2s-doc-final** 思路出 **`_终稿.md`** → 按 **f2s-ctx-build** 生成/更新 **Rules、Skills、`docs-index.md`**（及按需 **`main.mdc`**）。详见 **`skills/f2s-doc-add/SKILL.md`**（在对话中加载该技能后执行）。
|
|
110
57
|
|
|
111
|
-
|
|
58
|
+
### 2.2 f2s-doc-final
|
|
112
59
|
|
|
113
|
-
|
|
60
|
+
入参：PDF 或 MD 路径；可选第二参数为输出路径。规范来源：`template/终稿模版.md`。PDF：先初稿 `_初稿.md`，确认后再跑初稿路径出 `_终稿.md`；MD：可直达终稿。完成后接 **f2s-ctx-build** + `stock-docs/<方案名>_终稿.md`。
|
|
114
61
|
|
|
115
|
-
|
|
62
|
+
### 2.3 f2s-ctx-build
|
|
116
63
|
|
|
117
|
-
|
|
118
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
119
|
-
| **入参** | 一个：**文档路径**（如 `stock-docs/拼团技术方案设计.md`）或 **可匹配的片段**（如 `拼团技术方案设计.md`） |
|
|
120
|
-
| **行为** | 在 docs-index 中匹配该文档行 → 删除该行中的 Rules、Skills 文件及 Skill 空目录 → 从 docs-index 删除该行 → 更新 main.mdc（删除模块一览对应行或公共能力入口节） |
|
|
121
|
-
| **结果** | 该文档不再拥有对应 Rule/Skill，索引与 main 中相关描述被移除；**`stock-docs/`** 下的源文档不删除 |
|
|
64
|
+
入参：URL 或 **`stock-docs/`** 下本地路径（终稿常见）。产出：**main.mdc**（按需）、专题 **rules/\*.mdc**、**skills/**、**docs-index** 一行；URL 时另存 `stock-docs/`。同文档重复执行=**更新**同套产物。内网 URL 建议先落盘再传路径。
|
|
122
65
|
|
|
123
|
-
|
|
66
|
+
### 2.4 f2s-ctx-rm
|
|
124
67
|
|
|
125
|
-
|
|
68
|
+
入参：`stock-docs/` 文档路径或文件名片段。删对应 Rules、Skills、docs-index 行及 main 相关描述；**不删** stock-docs 源文件。
|
|
126
69
|
|
|
127
|
-
|
|
70
|
+
### 2.5 f2s-doc-pdf
|
|
128
71
|
|
|
129
|
-
|
|
130
|
-
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
131
|
-
| **入参** | 一个：**PDF 技术方案文档的本地路径** |
|
|
132
|
-
| **行为** | 读取 PDF → 提取文字并转为 Markdown → 保存到项目（技术方案推荐 `req-docs/<方案名>.md`；若仅作上下文源文档可放 `stock-docs/<方案名>.md`）；可选：引导用户以图片或文字提供流程图/流程说明，并追加到该 MD |
|
|
133
|
-
| **输出** | 保存后的 MD 路径；若用户补全流程说明则写入该 MD |
|
|
134
|
-
| **典型用法** | 在按技术方案实现之前，若技术方案仅为 PDF，可先按 **f2s-doc-pdf** 技能转成 **req-docs/** 下的 MD，再在对话中提供该路径并说明按方案实现。 |
|
|
72
|
+
入参：PDF 路径。转 MD，推荐 **`req-docs/<方案名>.md`**，可补流程说明。再在同对话提供该 MD 路径按方案实现。
|
|
135
73
|
|
|
136
74
|
---
|
|
137
75
|
|
|
138
|
-
## 3.
|
|
76
|
+
## 3. 提问与实现、实现后
|
|
139
77
|
|
|
140
78
|
### 3.1 按技术方案实现
|
|
141
79
|
|
|
142
|
-
|
|
143
|
-
- **行为**：AI 按 **`rules/implement-tech-design.mdc`** 读取方案、列任务、澄清缺项、按顺序实现，并输出待完成项与约定提醒。
|
|
144
|
-
- **仅有 PDF 时**：可先执行 **`f2s-doc-pdf`**，将 Markdown 保存到 **`req-docs/`**，再提供该 MD 路径。
|
|
145
|
-
|
|
146
|
-
详见 [Flow2Spec使用说明 - 典型流程](./Flow2Spec使用说明.md#四典型流程) 与配置根 **`rules/implement-tech-design.mdc`**。
|
|
80
|
+
对话中提供 **`配置根/req-docs/xxx.md`** 并说明按方案实现；AI 执行 **`rules/implement-tech-design.mdc`**。仅 PDF 时先 **f2s-doc-pdf** 再提供生成的 MD。典型流程见 [Flow2Spec使用说明 · 四](./Flow2Spec使用说明.md#四典型流程)。
|
|
147
81
|
|
|
148
82
|
### 3.2 f2s-kb-fix / f2s-kb-feat / f2s-kb-sync
|
|
149
83
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
| **`f2s-kb-merge`** | merge / rebase 后仍存在 `<<<<<<<` 等冲突标记 | 上下文类（索引、规则、技能、说明文档）自动合并；实现与对外配置等不擅自合并。详见 [§3.3](#33-f2s-kb-merge) 与 `skills/f2s-kb-merge/SKILL.md`。 |
|
|
156
|
-
|
|
157
|
-
### 3.3 f2s-kb-merge
|
|
158
|
-
|
|
159
|
-
技能名：**`f2s-kb-merge`**。在 **merge / rebase** 后仍存在 Git 冲突标记（`<<<<<<<` / `=======` / `>>>>>>>`）时使用。与 **f2s-kb-fix**（用户已指明问题后的定向修正）不同：本技能处理**合并产生的批量冲突**，并强制区分「可自动合并的编辑器上下文」与「须用户确认的实现侧」。
|
|
160
|
-
|
|
161
|
-
| 项目 | 说明 |
|
|
162
|
-
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
|
-
| **入参** | **可选**。不传：在工作区内检索仍含冲突标记的文件并分类处理。传参：指定一个或多个仍含冲突的文件（`@` 引用或路径列表），优先只处理这些文件；完成后可询问是否对工作区补充扫描。 |
|
|
164
|
-
| **可自动合并** | 文档索引（如 `docs-index.md`）、总览/模块规则（`rules/`）、技能（`skills/`）、与规则/技能配套的说明类 Markdown、索引联动的纯说明文档等；按「并集、去重、不丢任一侧独有约束」等策略合并，**必须删净冲突标记**。细则见 `skills/f2s-kb-merge/SKILL.md`。 |
|
|
165
|
-
| **禁止自动合并** | 应用/服务实现源码、会改变对外行为的配置（路由、函数注册、中间件链等）、依赖与锁文件、构建脚本，以及集中注册且两侧条目不一致的外部资源清单等；**只输出差异摘要与建议，待用户选定后再改**。 |
|
|
166
|
-
| **输出** | Markdown 摘要：已解决文件与要点；待确认文件与两侧差异及建议；确认无残留冲突标记（未全量扫描时可提示补充扫描）。 |
|
|
167
|
-
|
|
168
|
-
**典型场景**：两个分支都修改了 **docs-index、main.mdc、同一专题的 rules/skills 或 `stock-docs/` 下说明** 时，优先用 **f2s-kb-merge** 技能对齐上下文，减少漏行、漏规则。
|
|
169
|
-
|
|
170
|
-
---
|
|
171
|
-
|
|
172
|
-
## 4. 推荐执行顺序（Flow2Spec）
|
|
84
|
+
| 技能 | 何时 | 要点 |
|
|
85
|
+
| --------------- | ----------------------------------------------------- | ---------------------------------------------- |
|
|
86
|
+
| **f2s-kb-fix** | **任意**；发现违反约定或不一致即可 | 改代码 + 同步文档与 rules/skills |
|
|
87
|
+
| **f2s-kb-feat** | **任意**；新增或扩展能力时 | 未实现则补实现；已实现则对齐文档与规则 |
|
|
88
|
+
| **f2s-kb-sync** | **典型在实现后**或阶段收尾；需沉淀会话/现状到知识库时 | 可先列能力或零输入推断 → **大纲须确认** 再写库 |
|
|
173
89
|
|
|
174
|
-
|
|
90
|
+
细则见各 `skills/f2s-kb-*/SKILL.md`。
|
|
175
91
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
| 顺序 | 命令 | 作用 |
|
|
179
|
-
| ---- | ------------------------ | -------------------------------------------------------------- |
|
|
180
|
-
| 1 | **`f2s-req-clarify`** | 针对 PRD/需求反问，直到需求完全清楚 |
|
|
181
|
-
| 2 | **`f2s-req-backend`** | 根据澄清后需求（+ 可选需求条件）基于项目知识库生成后端技术文档 |
|
|
182
|
-
|
|
183
|
-
### 上下文生成
|
|
184
|
-
|
|
185
|
-
| 顺序 | 命令 | 作用 |
|
|
186
|
-
| ---- | --------------------------- | -------------------------------------------- |
|
|
187
|
-
| 1 | **`f2s-doc-arch`** | 生成项目架构说明**初稿** |
|
|
188
|
-
| 2 | **`f2s-doc-final`** | 将初稿转为《终稿模版》规范格式，得到**终稿** |
|
|
189
|
-
| 3 | **`f2s-ctx-build`** | 根据终稿生成 **Rules、Skills、文档索引** |
|
|
190
|
-
|
|
191
|
-
### 提问与实现环节
|
|
192
|
-
|
|
193
|
-
若技术方案仅为 **PDF**，可先执行 **`**f2s-doc-pdf** 技能 <PDF路径>`** 转成 MD 并保存到 **`req-docs/`**，再在对话中提供该 MD 路径并说明按技术方案实现。
|
|
194
|
-
|
|
195
|
-
| 顺序 | 命令 / 步骤 | 作用 |
|
|
196
|
-
| ---- | --------------------------- | -------------------------------------------------------------------------------------------- |
|
|
197
|
-
| 1 | **按技术方案实现**（对话） | 提供 **`req-docs/xxx.md`** 并说明按方案实现；AI 按 **implement-tech-design** 执行 |
|
|
198
|
-
| 2 | **`f2s-kb-fix`** | **实现后**用户指出规则错误时：修正代码并同步更新文档与全局 Rules/Skills |
|
|
199
|
-
| — | **`f2s-kb-feat`** | **新增能力**时：补全实现与文档，或已实现则仅补文档与规则 |
|
|
200
|
-
| 3 | **`f2s-kb-sync`** | 可指定已实现能力或零输入推断关心能力 → 大纲确认 → 写入知识库并注入上下文（可选） |
|
|
201
|
-
| — | **`f2s-kb-merge`** | **merge/rebase 后**：自动合并索引/规则/技能/说明类冲突；实现与配置类仅对比与建议，待用户确认 |
|
|
92
|
+
### 3.3 f2s-kb-merge
|
|
202
93
|
|
|
203
|
-
|
|
94
|
+
merge/rebase 后仍有 **`<<<<<<<` 等**时使用。与 **f2s-kb-fix**（单点纠错）不同：处理**批量合并冲突**。**可自动合并**：docs-index、main、rules、skills、说明类 MD 等，须去净冲突标记。**禁止自动合并**：业务源码、对外行为配置、依赖锁文件等，只出差异待你确认。详见 **`skills/f2s-kb-merge/SKILL.md`**。
|
|
204
95
|
|
|
205
96
|
---
|
|
206
97
|
|
|
207
|
-
##
|
|
98
|
+
## 4. 推荐执行顺序（简）
|
|
208
99
|
|
|
209
|
-
|
|
100
|
+
与「按使用顺序查找」表及 [§6](#6-快速参考按阶段) 一致。
|
|
210
101
|
|
|
211
102
|
---
|
|
212
103
|
|
|
213
|
-
##
|
|
104
|
+
## 5. 技能关系简图
|
|
214
105
|
|
|
215
106
|
```
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
需求澄清 └── PRD/需求 → 反问直到需求完全清楚
|
|
224
|
-
生成后端技术文档 └── 澄清后需求（+ 需求条件）→ req-docs/<方案名>_技术方案.md（基于项目知识库/Skills/Rules）
|
|
225
|
-
f2s-doc-arch └── 说明/文档（或扫描）→ stock-docs/<项目名>架构说明_初稿.md
|
|
226
|
-
f2s-doc-final └── PDF/MD → 初稿/终稿 → stock-docs/
|
|
227
|
-
f2s-ctx-build └── stock-docs/xxx.md（或 URL）→ main + Rules + Skills + docs-index
|
|
228
|
-
f2s-ctx-rm └── 文档路径/片段 → 删该文档对应的 Rules、Skills、索引行、main 相关描述
|
|
229
|
-
f2s-doc-pdf └── PDF 路径 → 转 Markdown 并保存到 req-docs/<方案名>.md，可补流程说明
|
|
230
|
-
按技术方案实现 └── 对话提供 req-docs/*.md + implement-tech-design → 代码与待办说明
|
|
231
|
-
f2s-kb-fix └── 用户指出规则错误 → 修正代码 + 更新文档与 Rules/Skills
|
|
232
|
-
f2s-kb-feat └── 新增能力 → 补全实现（若未实现）+ 文档 / Rules / Skill；已实现则仅补文档与规则
|
|
233
|
-
f2s-kb-sync └── 指定能力或零输入推断 → 大纲确认 → 更新知识库并注入上下文（可选）
|
|
234
|
-
f2s-kb-merge └── merge/rebase 冲突 → 上下文类自动合并；实现/配置类仅对比与建议，待用户确认
|
|
107
|
+
init → 配置根（rules / skills / template / stock-docs / req-docs）
|
|
108
|
+
|
|
109
|
+
需求：f2s-req-clarify → f2s-req-backend → req-docs/*_技术方案.md
|
|
110
|
+
上下文（架构）：f2s-doc-arch → f2s-doc-final → f2s-ctx-build → main + Rules + Skills + docs-index
|
|
111
|
+
上下文（已落地能力→知识库）：f2s-doc-add →（工作中多文件解析进上下文；内含终稿与 f2s-ctx-build 等价步骤，与 f2s-doc-arch 分工不同）
|
|
112
|
+
实现：（f2s-doc-pdf）→ req-docs/*.md + implement-tech-design → 代码
|
|
113
|
+
随时：f2s-kb-fix | f2s-kb-feat；实现后/收尾：f2s-kb-sync；冲突 → f2s-kb-merge
|
|
235
114
|
```
|
|
236
115
|
|
|
237
116
|
---
|
|
238
117
|
|
|
239
|
-
##
|
|
240
|
-
|
|
241
|
-
| 阶段
|
|
242
|
-
|
|
|
243
|
-
|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
247
|
-
|
|
|
248
|
-
|
|
|
249
|
-
|
|
|
250
|
-
|
|
|
251
|
-
|
|
|
252
|
-
|
|
|
253
|
-
|
|
|
254
|
-
|
|
255
|
-
|
|
|
256
|
-
| | merge/rebase 后：规则/索引/技能/说明与代码同时有冲突 | **f2s-kb-merge** 技能；可 `@` 指定冲突文件 |
|
|
257
|
-
|
|
258
|
-
**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)（init 详解、典型流程、技能与工作流） | [README-目录与路径约定](./README-目录与路径约定.md)（目录结构、产物阶段、链接约定） | [README-体系与原理](./README-体系与原理.md)（架构与设计原则）
|
|
118
|
+
## 6. 快速参考（按阶段）
|
|
119
|
+
|
|
120
|
+
| 阶段 | 想做的事 | 技能 / 步骤 |
|
|
121
|
+
| ---------- | ------------------------ | ----------- |
|
|
122
|
+
| 首次 | 初始化 | `flow2spec init` … |
|
|
123
|
+
| 上下文生成 | 架构：初稿→终稿→索引 | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build** |
|
|
124
|
+
| | 已落地能力→进上下文 | **f2s-doc-add**（`skills/f2s-doc-add/SKILL.md`：**工作中**多路径聚合，**非** f2s-doc-arch） |
|
|
125
|
+
| | 删某文档上下文 | **f2s-ctx-rm** |
|
|
126
|
+
| | 更新某文档产物 | 改文档后再 **f2s-ctx-build** 同路径 |
|
|
127
|
+
| 需求与方案 | 澄清 / 后端方案 | **f2s-req-clarify** / **f2s-req-backend** |
|
|
128
|
+
| 提问与实现 | PDF→MD | **f2s-doc-pdf** → **req-docs/xx技术方案.md** |
|
|
129
|
+
| | 写代码 | 提供 **req-docs/\*.md** + 按方案实现 |
|
|
130
|
+
| 任意时机 | 纠错 / 新能力 | **f2s-kb-fix** / **f2s-kb-feat** |
|
|
131
|
+
| 实现后 | 会话或现状写库 | **f2s-kb-sync** |
|
|
132
|
+
| 合并冲突 | 索引与规则等 | **f2s-kb-merge** |
|
|
133
|
+
|
|
134
|
+
**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) | [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | [README-目录与路径约定](./README-目录与路径约定.md) | [README-体系与原理](./README-体系与原理.md)
|