@double-codeing/flow2spec 2.2.1 → 2.2.3
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 +2 -1
- package/cli.js +1 -1
- package/docs/Flow2Spec/344/275/277/347/224/250/350/257/264/346/230/216.md +48 -42
- package/docs/README-/345/221/275/344/273/244/350/257/264/346/230/216.md +35 -28
- 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 +11 -2
- 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/f2s-req-clarify/SKILL.md +3 -23
- package/templates/skills/stock-docs-vs-req-docs/SKILL.md +6 -4
package/README.md
CHANGED
|
@@ -35,7 +35,8 @@ flow2spec init
|
|
|
35
35
|
|
|
36
36
|
| 环节 | 典型技能 / 用法 |
|
|
37
37
|
|------|----------------|
|
|
38
|
-
|
|
|
38
|
+
| **沉淀知识库（架构说明）** | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build**：架构初稿→终稿→Rules、Skills、索引（终稿在 `stock-docs/`） |
|
|
39
|
+
| **沉淀知识库（已落地能力→上下文）** | **f2s-doc-add**：**工作中**某能力**已做好**，用**一批相关文件路径**把它解析进知识库（初稿→终稿→Rules/Skills/索引）；**与**「架构说明」**那条技能链不同** |
|
|
39
40
|
| **按方案写代码** | **`req-docs/`** 下技术方案 MD + **`implement-tech-design`**；仅有 PDF 时可用 **f2s-doc-pdf** |
|
|
40
41
|
| **纠错与扩展** | **f2s-kb-feat**、**f2s-kb-fix**（任意时机） |
|
|
41
42
|
| **实现后写库** | **f2s-kb-sync**（会话/现状 → 大纲确认后写库） |
|
package/cli.js
CHANGED
|
@@ -26,7 +26,7 @@ agent（可多个，空格分隔；省略时默认为 cursor）：
|
|
|
26
26
|
flow2spec init cursor claude # 同时写入 .cursor/ 与 .claude/
|
|
27
27
|
|
|
28
28
|
init 会:
|
|
29
|
-
1. 将 templates/ 下内容复制到各所选 agent 的配置根目录下的 rules、skills、template（及预建 stock-docs/、req-docs
|
|
29
|
+
1. 将 templates/ 下内容复制到各所选 agent 的配置根目录下的 rules、skills、template（及预建 stock-docs/、req-docs/）。Claude Code（.claude/）下规则为 .md，frontmatter 路径键为 paths（由模板 .mdc 的 globs 自动转换）；Cursor（.cursor/）下仍为 .mdc 与 globs。
|
|
30
30
|
2. 工作流说明位于 skills 各子目录的 SKILL.md；写入 .claude/.codex 时主要为统一存放规则、技能与模版，供对应工具按各自方式加载
|
|
31
31
|
|
|
32
32
|
更多说明见 README.md 或 docs/Flow2Spec使用说明.md
|
|
@@ -4,16 +4,16 @@
|
|
|
4
4
|
|
|
5
5
|
**文档**：[README-命令说明](./README-命令说明.md) · [README-目录与路径约定](./README-目录与路径约定.md) · [README-体系与原理](./README-体系与原理.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
|
|
6
6
|
|
|
7
|
-
| 章节
|
|
8
|
-
|
|
9
|
-
| [一、init](#一init-做了什么)
|
|
10
|
-
| [二、目录约定](#二文档目录约定)
|
|
11
|
-
| [三、推荐顺序](#三推荐执行顺序)
|
|
12
|
-
| [四、典型流程](#四典型流程)
|
|
13
|
-
| [五、改造 implement-tech-design](#五implement-tech-designmdc-可自行改造) | 按项目改「按方案实现」规则
|
|
14
|
-
| [六、技能标识](#六技能与工作流标识)
|
|
15
|
-
| [七、延伸](#七速查与相关文档)
|
|
16
|
-
| [使用案例（另文）](./Flow2Spec-使用案例-模拟对话.md)
|
|
7
|
+
| 章节 | 内容 |
|
|
8
|
+
| ---------- | ----------------------- |
|
|
9
|
+
| [一、init](#一init-做了什么) | 写入目录与模板 |
|
|
10
|
+
| [二、目录约定](#二文档目录约定) | `stock-docs/` vs `req-docs/`；完整结构见 [目录与路径约定](./README-目录与路径约定.md) |
|
|
11
|
+
| [三、推荐顺序](#三推荐执行顺序) | 链到 [命令说明 · 按使用顺序查找](./README-命令说明.md#按使用顺序查找) |
|
|
12
|
+
| [四、典型流程](#四典型流程) | 架构 / 上下文 / 按方案实现 / 全局技能 |
|
|
13
|
+
| [五、改造 implement-tech-design](#五implement-tech-designmdc-可自行改造) | 按项目改「按方案实现」规则 |
|
|
14
|
+
| [六、技能标识](#六技能与工作流标识) | `skills/<name>/SKILL.md` 速览 |
|
|
15
|
+
| [七、延伸](#七速查与相关文档) | 速查与 FAQ |
|
|
16
|
+
| [使用案例（另文）](./Flow2Spec-使用案例-模拟对话.md) | 真实输入、命令解释、场景与速查 |
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -23,13 +23,15 @@
|
|
|
23
23
|
|
|
24
24
|
对每个所选配置根：**覆盖写入** `templates/` 中的 `rules/`、`skills/`、`template/`，并预建 **`stock-docs/`**、**`req-docs/`**。Cursor 下 Agent 按场景加载 **`skills/<标识>/SKILL.md`**。
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
| **
|
|
31
|
-
| **
|
|
32
|
-
| **
|
|
26
|
+
**规则文件与工具差异**：**Cursor** 的 `rules/` 使用 **`.mdc`**，frontmatter 用 **`globs:`**、**`alwaysApply:`**。**Claude Code** 仅加载 **`.claude/rules/`** 下 **`.md`**（官方文档「Organize rules with .claude/rules」）；`flow2spec init claude` 会把模板 **`.mdc`** 转为 **`.md`**，并将 **`globs:`** 改为 **`paths:`**、去掉 **`alwaysApply`**（无 `paths` 的规则与会话一并加载，等价于总览类 always 规则）。
|
|
27
|
+
|
|
28
|
+
| 子目录 | 用途 |
|
|
29
|
+
| --------------- | ------------------------------------------ |
|
|
30
|
+
| **skills/** | f2s-\* 工作流 + **stock-docs-vs-req-docs** |
|
|
31
|
+
| **rules/** | Cursor：**\*.mdc**（如 **implement-tech-design.mdc**）；Claude Code：**\*.md**（如 **implement-tech-design.md**） |
|
|
32
|
+
| **template/** | 终稿模版、后端技术模版 |
|
|
33
|
+
| **stock-docs/** | 生成 Rules/Skills 的**存量源文档** |
|
|
34
|
+
| **req-docs/** | 需求澄清、技术方案、**按方案实现**用 MD |
|
|
33
35
|
|
|
34
36
|
**注意**：再次 init 会覆盖模板；本地对模板的长期修改请用分支或备份。
|
|
35
37
|
|
|
@@ -39,10 +41,10 @@
|
|
|
39
41
|
|
|
40
42
|
**配置根**：如 `.cursor/`、`.claude/`。
|
|
41
43
|
|
|
42
|
-
| 目录
|
|
43
|
-
|
|
44
|
-
| **stock-docs/** | 终稿、架构说明等 → **f2s-ctx-build** 入参
|
|
45
|
-
| **req-docs/**
|
|
44
|
+
| 目录 | 用途 |
|
|
45
|
+
| --------------- | ------------------------------------------------------------ |
|
|
46
|
+
| **stock-docs/** | 终稿、架构说明等 → **f2s-ctx-build** 入参 |
|
|
47
|
+
| **req-docs/** | 技术方案等 → 对话提供路径 + **implement-tech-design** 写代码 |
|
|
46
48
|
|
|
47
49
|
细则、链接写法、原稿/初稿/终稿：[README-目录与路径约定](./README-目录与路径约定.md)。
|
|
48
50
|
|
|
@@ -50,13 +52,14 @@
|
|
|
50
52
|
|
|
51
53
|
## 三、推荐执行顺序
|
|
52
54
|
|
|
53
|
-
**需求（可选）**：f2s-req-clarify → f2s-req-backend
|
|
55
|
+
**需求（可选）**：f2s-req-clarify → f2s-req-backend
|
|
54
56
|
|
|
55
|
-
|
|
57
|
+
**上下文（架构说明）**：**f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build**
|
|
58
|
+
**上下文（已落地能力→知识库）**：**f2s-doc-add**——**工作中**要把**已经做好的能力**从多份源码/说明里**解析进上下文**时用；独立技能，**不要**与「仅要架构初稿」的 f2s-doc-arch 混用（见 `skills/f2s-doc-add/SKILL.md`「使用时机」与分工表）
|
|
56
59
|
|
|
57
|
-
**实现**：可选 f2s-doc-pdf → **req-docs/** 下 MD + 说明「按方案实现」→ **implement-tech-design**
|
|
60
|
+
**实现**：可选 f2s-doc-pdf → **req-docs/** 下 MD + 说明「按方案实现」→ **implement-tech-design**
|
|
58
61
|
|
|
59
|
-
**知识库维护**：任意时机 **f2s-kb-fix** / **f2s-kb-feat**；**实现后**（或收尾）沉淀写库 → **f2s-kb-sync**；合并冲突 → **f2s-kb-merge**
|
|
62
|
+
**知识库维护**：任意时机 **f2s-kb-fix** / **f2s-kb-feat**；**实现后**（或收尾）沉淀写库 → **f2s-kb-sync**；合并冲突 → **f2s-kb-merge**
|
|
60
63
|
|
|
61
64
|
完整表与入参/输出：[README-命令说明 · 按使用顺序查找](./README-命令说明.md#按使用顺序查找)。
|
|
62
65
|
|
|
@@ -66,6 +69,8 @@
|
|
|
66
69
|
|
|
67
70
|
**架构初稿**：**f2s-doc-arch**（说明或文档路径；无参扫描需用户确认）→ 可选 **f2s-doc-final** → **f2s-ctx-build**。
|
|
68
71
|
|
|
72
|
+
**已落地能力 → 上下文**：在日常开发中，某能力**已实现**且材料分散在多文件时，加载 **f2s-doc-add**，给出**多个相关路径**：适度深度解析 → **`stock-docs/<方案名>_初稿.md`** → 终稿 → **f2s-ctx-build** 等价产物。
|
|
73
|
+
|
|
69
74
|
**文档 → 上下文**：材料放 **stock-docs/**；PDF/杂乱 MD 用 **f2s-doc-final**（PDF 常先初稿再终稿）；终稿路径交给 **f2s-ctx-build**。会话沉淀、大纲确认写库：**f2s-kb-sync**。冲突标记：**f2s-kb-merge**（见 [命令说明 §3.3](./README-命令说明.md#33-f2s-kb-merge)）。
|
|
70
75
|
|
|
71
76
|
**技术方案 → 代码**：提供 **req-docs/xxx.md**（或 PDF，规则会先走 **f2s-doc-pdf**），说明按方案实现；行为见 **rules/implement-tech-design.mdc**。
|
|
@@ -84,16 +89,17 @@
|
|
|
84
89
|
|
|
85
90
|
工作流在 **`skills/<标识>/SKILL.md`**；Agent 依 **frontmatter** 的 `name`、`description` 匹配。
|
|
86
91
|
|
|
87
|
-
| name
|
|
88
|
-
|
|
89
|
-
| f2s-doc-arch
|
|
90
|
-
| f2s-doc-
|
|
91
|
-
| f2s-
|
|
92
|
-
| f2s-ctx-
|
|
93
|
-
| f2s-
|
|
94
|
-
| f2s-
|
|
95
|
-
| f2s-
|
|
96
|
-
|
|
|
92
|
+
| name | 用途 |
|
|
93
|
+
| ----------------------------------------------------- | ---------------------------------------------------- |
|
|
94
|
+
| f2s-doc-arch | **仅**架构说明类初稿（文字/单文档/扫描）；**不**内含终稿与 ctx-build |
|
|
95
|
+
| f2s-doc-add | **工作中**：**已做好的能力** + 多文件路径→解析进上下文（初稿→终稿→Rules/Skills/索引）；勿与 f2s-doc-arch 混用 |
|
|
96
|
+
| f2s-doc-final | PDF/MD → 终稿模版 |
|
|
97
|
+
| f2s-ctx-build | 终稿 → Rules / Skills / docs-index |
|
|
98
|
+
| f2s-ctx-rm | 按文档删上下文 |
|
|
99
|
+
| f2s-doc-pdf | PDF → req-docs MD |
|
|
100
|
+
| f2s-req-clarify / f2s-req-backend | 需求澄清 / 后端技术方案 |
|
|
101
|
+
| f2s-kb-fix / f2s-kb-feat / f2s-kb-sync / f2s-kb-merge | 任意：纠错、新能力；典型实现后：写库；冲突：合并 |
|
|
102
|
+
| stock-docs-vs-req-docs | 两目录分工说明 |
|
|
97
103
|
|
|
98
104
|
入参与输出细节仍以各 **SKILL.md** 与 [README-命令说明](./README-命令说明.md) 为准。
|
|
99
105
|
|
|
@@ -105,13 +111,13 @@
|
|
|
105
111
|
|
|
106
112
|
**常见问题**
|
|
107
113
|
|
|
108
|
-
- **按方案实现要改行为**：改 **implement-tech-design.mdc**（见上文第五节）。
|
|
109
|
-
- **技能不触发**：确认已 init；对话里点名技能名或 `description` 里的词。
|
|
114
|
+
- **按方案实现要改行为**：改 **implement-tech-design.mdc**（见上文第五节）。
|
|
115
|
+
- **技能不触发**：确认已 init；对话里点名技能名或 `description` 里的词。
|
|
110
116
|
- **顺序搞不清**：看 [README-命令说明](./README-命令说明.md) 开头总表。
|
|
111
117
|
|
|
112
|
-
| 文档
|
|
113
|
-
|
|
118
|
+
| 文档 | 说明 |
|
|
119
|
+
| - | -------------------------------------------- |
|
|
114
120
|
| [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | 真实输入 + 命令解释 + Agent 示意，全文同版式 |
|
|
115
|
-
| [README-命令说明](./README-命令说明.md)
|
|
116
|
-
| [README-目录与路径约定](./README-目录与路径约定.md)
|
|
117
|
-
| [README-体系与原理](./README-体系与原理.md)
|
|
121
|
+
| [README-命令说明](./README-命令说明.md) | 入参、输出、顺序、§6 速查 |
|
|
122
|
+
| [README-目录与路径约定](./README-目录与路径约定.md) | 路径、链接、产物阶段 |
|
|
123
|
+
| [README-体系与原理](./README-体系与原理.md) | main、docs-index、拆解原则 |
|
|
@@ -11,18 +11,19 @@
|
|
|
11
11
|
|
|
12
12
|
## 按使用顺序查找
|
|
13
13
|
|
|
14
|
-
| 阶段 | 步骤 | 技能 / 命令 | 一句话
|
|
15
|
-
| ------------ | ---- | -------------------------------------------------------- |
|
|
16
|
-
| 首次 | — | `flow2spec init [agent ...]` | 写入配置根模板
|
|
17
|
-
| 需求与方案 | 1 | **f2s-req-clarify** | PRD/需求反问至清楚
|
|
18
|
-
| 需求与方案 | 2 | **f2s-req-backend** | 澄清后出后端技术文档
|
|
19
|
-
| 上下文生成 | 1～3 | **f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build** | 初稿→终稿→Rules/Skills/索引
|
|
20
|
-
| 上下文生成 |
|
|
21
|
-
| 上下文生成 |
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
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) |
|
|
26
27
|
|
|
27
28
|
**汇总**：init →（可选需求链）→ arch → final → ctx-build →（可选 pdf）→ req-docs + implement-tech-design →（随时 **fix** / **feat**；实现后或收尾 **sync**）；冲突用 **f2s-kb-merge**。更细速查见 [§6](#6-快速参考按阶段)。
|
|
28
29
|
|
|
@@ -32,8 +33,8 @@
|
|
|
32
33
|
|
|
33
34
|
| 项 | 说明 |
|
|
34
35
|
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
35
|
-
| 用法 | `npx @double-codeing/flow2spec init` 或全局安装后 `flow2spec init [cursor \| claude \| codex ...]`；默认 **cursor**
|
|
36
|
-
| 写入 | 各配置根下 `stock-docs/`、`req-docs/`、`template/`、`rules/`、`skills/`（见 [Flow2Spec使用说明](./Flow2Spec使用说明.md#一init-做了什么)
|
|
36
|
+
| 用法 | `npx @double-codeing/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`** |
|
|
37
38
|
| 结果 | Agent 按场景加载 `skills/*/SKILL.md` |
|
|
38
39
|
|
|
39
40
|
---
|
|
@@ -48,7 +49,11 @@
|
|
|
48
49
|
|
|
49
50
|
### 2.1 f2s-doc-arch
|
|
50
51
|
|
|
51
|
-
|
|
52
|
+
**定位**：**仅**「项目/模块**架构说明初稿**」；**不是** f2s-doc-add。入参可选（说明文字或文档路径；无参=扫描代码须先确认）。输出默认 **`stock-docs/<项目名>架构说明_初稿.md`**。可接 **f2s-doc-final** → **f2s-ctx-build**。
|
|
53
|
+
|
|
54
|
+
### 2.1.1 f2s-doc-add
|
|
55
|
+
|
|
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`**（在对话中加载该技能后执行）。
|
|
52
57
|
|
|
53
58
|
### 2.2 f2s-doc-final
|
|
54
59
|
|
|
@@ -102,7 +107,8 @@ merge/rebase 后仍有 **`<<<<<<<` 等**时使用。与 **f2s-kb-fix**（单点
|
|
|
102
107
|
init → 配置根（rules / skills / template / stock-docs / req-docs）
|
|
103
108
|
|
|
104
109
|
需求：f2s-req-clarify → f2s-req-backend → req-docs/*_技术方案.md
|
|
105
|
-
|
|
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 分工不同）
|
|
106
112
|
实现：（f2s-doc-pdf）→ req-docs/*.md + implement-tech-design → 代码
|
|
107
113
|
随时：f2s-kb-fix | f2s-kb-feat；实现后/收尾：f2s-kb-sync；冲突 → f2s-kb-merge
|
|
108
114
|
```
|
|
@@ -111,17 +117,18 @@ init → 配置根（rules / skills / template / stock-docs / req-docs）
|
|
|
111
117
|
|
|
112
118
|
## 6. 快速参考（按阶段）
|
|
113
119
|
|
|
114
|
-
| 阶段 | 想做的事 | 技能 / 步骤
|
|
115
|
-
| ---------- | ------------------------ |
|
|
116
|
-
| 首次 | 初始化 | `flow2spec init` …
|
|
117
|
-
| 上下文生成 |
|
|
118
|
-
| |
|
|
119
|
-
| |
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
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** |
|
|
126
133
|
|
|
127
134
|
**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) | [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | [README-目录与路径约定](./README-目录与路径约定.md) | [README-体系与原理](./README-体系与原理.md)
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
| 路径（逻辑） | 示例（Cursor） | 说明 |
|
|
8
8
|
|--------------|----------------|------|
|
|
9
|
-
| **stock-docs/** | `.cursor/stock-docs/` | 存量源文档（终稿/初稿/架构等）→ **f2s-ctx-build** |
|
|
9
|
+
| **stock-docs/** | `.cursor/stock-docs/` | 存量源文档（终稿/初稿/架构等）→ **f2s-ctx-build**；**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**已落地能力、多文件聚合进上下文）的初稿/终稿亦在此，**勿**与 **req-docs** 混用 |
|
|
10
10
|
| **req-docs/** | `.cursor/req-docs/` | 技术方案、澄清文档等 → **implement-tech-design** 按方案写代码 |
|
|
11
11
|
| **rules/** | `.cursor/rules/` | **main.mdc**（唯一 alwaysApply）+ 专题 `*-context.mdc` |
|
|
12
12
|
| **skills/** | `.cursor/skills/` | 各 `SKILL.md` |
|
|
@@ -15,6 +15,15 @@
|
|
|
15
15
|
|
|
16
16
|
**init**：创建上表目录并复制模板。**升级**：旧名 `docs/` 可改名为 `stock-docs/`；`req-docs` 须在**配置根内**，勿与 `.cursor` 同级。
|
|
17
17
|
|
|
18
|
+
### 1.1 Cursor 与 Claude Code：`rules/` 扩展名
|
|
19
|
+
|
|
20
|
+
| 配置根 | 规则文件扩展名 | 路径范围（frontmatter） | 说明 |
|
|
21
|
+
|--------|----------------|-------------------------|------|
|
|
22
|
+
| **`.cursor/`**（Cursor） | **`.mdc`** | **`globs:`** + **`alwaysApply:`** | Cursor 约定 |
|
|
23
|
+
| **`.claude/`**（Claude Code） | **`.md`** | **`paths:`**（无 `paths` 则与会话同载） | Claude Code 不识别 `.mdc`；`flow2spec init claude` 由模板自动转换 |
|
|
24
|
+
|
|
25
|
+
在 **`.claude/`** 下手工维护规则时，请使用 **`.md`** 与 **`paths:`**；勿复制 Cursor 的 **`globs:`** / **`.mdc`** 以免不生效。Claude Code **不会**把 **`.mdx`** 当作项目规则加载；请勿用 **`.mdx`** 作为 `rules/` 内规则扩展名。
|
|
26
|
+
|
|
18
27
|
---
|
|
19
28
|
|
|
20
29
|
## 2. 链接写法（生成 Rule / Skill / docs-index 时必守）
|
|
@@ -39,7 +48,7 @@
|
|
|
39
48
|
| 阶段 | 含义 | 典型名 |
|
|
40
49
|
|------|------|--------|
|
|
41
50
|
| 原稿 | 未纳入体系前的材料 | 任意 PDF、杂乱 MD |
|
|
42
|
-
| 初稿 | **f2s-doc-final**（PDF
|
|
51
|
+
| 初稿 | **f2s-doc-final**（PDF 首次）、**f2s-doc-arch**（架构说明），或 **f2s-doc-add**（**工作中**把**已落地能力**从多文件聚合成的初稿） | `*_初稿.md`、`*架构说明_初稿.md` 等；**f2s-doc-add** 与 **f2s-doc-arch** 分工见各自 `SKILL.md` |
|
|
43
52
|
| 终稿 | **f2s-doc-final** 规范输出 | `*_终稿.md` → **f2s-ctx-build** 入参 |
|
|
44
53
|
|
|
45
54
|
Rules/Skills **文件名不带 `_终稿`**。
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cursor 规则为 .mdc + frontmatter globs、alwaysApply。
|
|
3
|
+
* Claude Code 仅识别 .claude/rules 下扩展名为 .md 的规则文件，路径范围用 paths（见 Claude Code 文档：Organize rules with .claude/rules）。
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* @param {string} mdcSource 完整 .mdc 文件正文
|
|
8
|
+
* @returns {string} 写入 `.claude/rules/*.md` 的正文
|
|
9
|
+
*/
|
|
10
|
+
function adaptRuleMdcToClaudeMd(mdcSource) {
|
|
11
|
+
let out = mdcSource;
|
|
12
|
+
// YAML：globs → paths（与 Cursor 语义等价）
|
|
13
|
+
out = out.replace(/^globs:/m, "paths:");
|
|
14
|
+
// Claude Code 不按 Cursor 的 alwaysApply 解析；无 paths 的规则与会话同载
|
|
15
|
+
out = out.replace(/^\s*alwaysApply:\s*(true|false)\s*\r?\n/m, "");
|
|
16
|
+
// 正文与示例中的 .mdc 引用改为 .md，与落盘扩展名一致
|
|
17
|
+
out = out.replace(/\.mdc\b/g, ".md");
|
|
18
|
+
return out;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @param {string} agentRoot AGENTS[id].root，如 `.claude`
|
|
23
|
+
*/
|
|
24
|
+
function shouldWriteClaudeStyleRules(agentRoot) {
|
|
25
|
+
return agentRoot === ".claude";
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
module.exports = { adaptRuleMdcToClaudeMd, shouldWriteClaudeStyleRules };
|
package/lib/init.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
const path = require("path");
|
|
2
2
|
const fs = require("fs");
|
|
3
3
|
const { AGENTS, SUBDIRS, normalizeAgentIds } = require("./agents");
|
|
4
|
+
const { adaptRuleMdcToClaudeMd, shouldWriteClaudeStyleRules } = require("./claudeRulesAdapter");
|
|
4
5
|
|
|
5
6
|
function ensureDirs(cwd, agentRoot) {
|
|
6
7
|
for (const sub of SUBDIRS) {
|
|
@@ -22,18 +23,46 @@ function copyRecursive(src, dest) {
|
|
|
22
23
|
}
|
|
23
24
|
}
|
|
24
25
|
|
|
26
|
+
/** 复制 templates/rules：Cursor 保留 .mdc；Claude Code 写入 .md 并转换 frontmatter（globs→paths，去掉 alwaysApply） */
|
|
27
|
+
function copyRulesTemplates(cwd, agentRoot, templatesDir) {
|
|
28
|
+
const rulesSrc = path.join(templatesDir, "rules");
|
|
29
|
+
const rulesDest = path.join(cwd, agentRoot, "rules");
|
|
30
|
+
if (!fs.existsSync(rulesSrc)) return;
|
|
31
|
+
if (!fs.existsSync(rulesDest)) fs.mkdirSync(rulesDest, { recursive: true });
|
|
32
|
+
|
|
33
|
+
const claudeStyle = shouldWriteClaudeStyleRules(agentRoot);
|
|
34
|
+
if (claudeStyle) {
|
|
35
|
+
for (const name of fs.readdirSync(rulesDest)) {
|
|
36
|
+
if (name.endsWith(".mdc")) {
|
|
37
|
+
fs.unlinkSync(path.join(rulesDest, name));
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
for (const name of fs.readdirSync(rulesSrc)) {
|
|
43
|
+
const srcPath = path.join(rulesSrc, name);
|
|
44
|
+
const st = fs.statSync(srcPath);
|
|
45
|
+
if (st.isDirectory()) {
|
|
46
|
+
copyRecursive(srcPath, path.join(rulesDest, name));
|
|
47
|
+
continue;
|
|
48
|
+
}
|
|
49
|
+
if (!name.endsWith(".mdc")) {
|
|
50
|
+
fs.copyFileSync(srcPath, path.join(rulesDest, name));
|
|
51
|
+
continue;
|
|
52
|
+
}
|
|
53
|
+
const raw = fs.readFileSync(srcPath, "utf8");
|
|
54
|
+
const body = claudeStyle ? adaptRuleMdcToClaudeMd(raw) : raw;
|
|
55
|
+
const destName = claudeStyle ? name.replace(/\.mdc$/i, ".md") : name;
|
|
56
|
+
fs.writeFileSync(path.join(rulesDest, destName), body, "utf8");
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
25
60
|
/** 将 templates 下全部内容复制到指定配置根目录（如 .cursor、.claude） */
|
|
26
61
|
function copyTemplatesToAgentRoot(cwd, agentRoot) {
|
|
27
62
|
const templatesDir = path.join(__dirname, "..", "templates");
|
|
28
63
|
const destRoot = path.join(cwd, agentRoot);
|
|
29
64
|
|
|
30
|
-
|
|
31
|
-
const rulesDest = path.join(destRoot, "rules");
|
|
32
|
-
if (fs.existsSync(rulesSrc)) {
|
|
33
|
-
for (const name of fs.readdirSync(rulesSrc)) {
|
|
34
|
-
copyRecursive(path.join(rulesSrc, name), path.join(rulesDest, name));
|
|
35
|
-
}
|
|
36
|
-
}
|
|
65
|
+
copyRulesTemplates(cwd, agentRoot, templatesDir);
|
|
37
66
|
|
|
38
67
|
const skillsSrc = path.join(templatesDir, "skills");
|
|
39
68
|
const skillsDest = path.join(destRoot, "skills");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@double-codeing/flow2spec",
|
|
3
|
-
"version": "2.2.
|
|
3
|
+
"version": "2.2.3",
|
|
4
4
|
"description": "flow2spec init：落盘 .cursor/.claude/.codex 等配置根的 rules、skills、stock-docs/req-docs，文档驱动、f2s 可写回知识库工作流。",
|
|
5
5
|
"homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
|
|
6
6
|
"repository": {
|
|
@@ -8,7 +8,7 @@ alwaysApply: false
|
|
|
8
8
|
|
|
9
9
|
# stock-docs 与 req-docs
|
|
10
10
|
|
|
11
|
-
- **`配置根/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；**f2s-ctx-build**、**f2s-doc-final**、**f2s-doc-arch
|
|
11
|
+
- **`配置根/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；**f2s-ctx-build**、**f2s-doc-final**、**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**将**已落地能力**从多文件解析进上下文：初稿→终稿→Rules/Skills；与 f2s-doc-arch 分工不同）等技能的落盘（除 PDF→初稿等另有说明外）优先在此。Rule/Skill/docs-index 链出文档用 `../stock-docs/`、`../../stock-docs/`、`stock-docs/<文件名>.md`；`sourceDoc` 为 `<配置根>/stock-docs/<文件名>.md`。
|
|
12
12
|
- **`req-docs/`**（**配置根**下，如 `.cursor/req-docs/`）：需求澄清、**后端技术方案**、f2s-doc-pdf 输出的「按方案实现」MD；`implement-tech-design` 的 globs 为 `**/req-docs/**/*.md`。
|
|
13
13
|
|
|
14
14
|
完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
2
|
+
|
|
3
|
+
## name: f2s-ctx-build
|
|
3
4
|
description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
|
|
4
|
-
|
|
5
|
-
> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见
|
|
5
|
+
|
|
6
|
+
> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 `**.cursor/`**、`**.claude/**`、`**.codex/**`）。下文 `**配置根/...**` 指该目录下的相对路径。
|
|
6
7
|
|
|
7
8
|
# 根据文档生成项目上下文（Rules、Skills、文档索引）
|
|
8
9
|
|
|
9
|
-
用户会在本技能后附带**一个参数**：要么是一个 **URL**（如 `https://xxx.com/doc`），要么是一个**本地路径**，且路径应指向 **配置根/stock-docs/** 下的 Markdown（PDF/初稿/终稿/架构说明等**存量上下文源**，用于生成 Rules、Skills）。**不要**把
|
|
10
|
+
用户会在本技能后附带**一个参数**：要么是一个 **URL**（如 `https://xxx.com/doc`），要么是一个**本地路径**，且路径应指向 **配置根/stock-docs/** 下的 Markdown（PDF/初稿/终稿/架构说明等**存量上下文源**，用于生成 Rules、Skills）。**不要**把 `**配置根/req-docs/`**（按方案实现代码的技术方案目录）当作本技能入参；若用户只持有该目录下的方案，应提示先将符合《终稿模版》的文档复制或整理到 `**配置根/stock-docs/**` 再执行。请按以下步骤执行，用你的**大模型能力**分析文档并生成完整架构。
|
|
10
11
|
|
|
11
12
|
**文档产物阶段约定**：doc 中的产物一般分为 **原稿**、**初稿**、**终稿**；本技能生成的 **Rules、Skills 文件名与目录名不带 `_终稿` 等后缀**，与现有约定一致（如 `<主题>-context.mdc`、`<主题>-context/SKILL.md`）。
|
|
12
13
|
|
|
@@ -15,15 +16,15 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
15
16
|
|
|
16
17
|
1. **拆解**：根据文档篇幅与领域块数量，决定是「单 Rule + 单 Skill」还是「索引入口 + 多条专题 Rule/Skill」。篇幅长或含多块独立内容（如接口约定、消息队列、配置、公共工具等）时，应拆成索引入口 + 多条按场景/主题的 Rule 与 Skill，使单条更聚焦、按需加载。
|
|
17
18
|
2. **分工**：
|
|
18
|
-
|
|
19
|
-
|
|
19
|
+
- **Rules**：承担**约束、约定、作用范围**；一条 alwaysApply 的索引入口 + 若干条用 globs 限定在相关路径的专题规则；正文写「必须/禁止/约定」类内容。
|
|
20
|
+
- **Skills**：承担**领域知识、操作步骤、示例**；一个总览 skill + 若干专题 skill；description 写清触发词与使用场景，正文写概念、流程、方法表、示例。
|
|
20
21
|
|
|
21
22
|
---
|
|
22
23
|
|
|
23
24
|
## 步骤 1：获取文档内容
|
|
24
25
|
|
|
25
26
|
- 若用户给出的是 **HTTPS/HTTP URL**：使用你可用的网络请求能力（如 web fetch）拉取该 URL 的页面内容。若你所在环境无法访问该 URL（如内网），则回复用户说明「请将页面内容复制到项目内 `配置根/stock-docs/xxx.md`，再执行本技能并传入路径 `配置根/stock-docs/xxx.md`」。
|
|
26
|
-
- 若用户给出的是**本地路径**：从配置根的父目录读取该文件（须为
|
|
27
|
+
- 若用户给出的是**本地路径**：从配置根的父目录读取该文件（须为 `**配置根/stock-docs/…`**，如 `配置根/stock-docs/功能描述.md`）。若路径落在 `**配置根/req-docs/**`（技术方案目录），应提醒用户：本技能入参须为 **stock-docs** 下的存量源文档；请先将符合《终稿模版》的内容整理到 `**stock-docs/`** 再执行。
|
|
27
28
|
|
|
28
29
|
得到的内容可能是 Markdown、HTML 或富文本，请先提取出**正文**（若是 HTML 可提取 body 内的文本或转成可读的 Markdown）。
|
|
29
30
|
|
|
@@ -33,27 +34,31 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
33
34
|
|
|
34
35
|
生成任何产物时，**必须**按下列规则写文档路径与链接。**路径写错会导致 Cursor 中链接失效、AI 无法正确打开源文档，务必严格按表执行。**
|
|
35
36
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
|
39
|
-
| **配置根/
|
|
40
|
-
| **配置根/
|
|
41
|
-
| **
|
|
37
|
+
|
|
38
|
+
| 写入位置 | 文档所在目录（固定） | 引用该文档时的写法 |
|
|
39
|
+
| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| **配置根/rules/*.mdc** | 文档在 `配置根/stock-docs/<文件名>.md` | 链接 **必须** 写为 `[文档标题](../stock-docs/<文件名>.md)`，即 href 为 `**../stock-docs/<文件名>.md`**（从 配置根/rules 到 配置根/stock-docs 的相对路径）。 |
|
|
41
|
+
| **配置根/skills/<主题>/SKILL.md** | 同上 | 链接 **必须** 写为 `[文档标题](../../stock-docs/<文件名>.md)`，即 href 为 `**../../stock-docs/<文件名>.md`**（从 配置根/skills/xxx 到 配置根/stock-docs 的相对路径）。 |
|
|
42
|
+
| **配置根/docs-index.md** | 同上 | 文档路径列：显示可写 `配置根/stock-docs/<文件名>.md`；链接 href **必须** 为 `**stock-docs/<文件名>.md`**（因 docs-index 位于配置根下，同级的 **stock-docs** 目录即 `stock-docs/<文件名>.md`）。示例：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`。 |
|
|
43
|
+
| **frontmatter 的 sourceDoc** | 同上 | **必须** 写为 `**配置根/stock-docs/<文件名>.md`**（与用户传入的本地路径一致；若用户传的是相对路径如 `配置根/stock-docs/xxx.md`，即用该值）。 |
|
|
44
|
+
|
|
42
45
|
|
|
43
46
|
**正确示例（按位置抄写格式）：**
|
|
47
|
+
|
|
44
48
|
- Rule 内：`[技术方案设计](../stock-docs/技术方案设计.md)`
|
|
45
49
|
- Skill 内：`[技术方案设计](../../stock-docs/技术方案设计.md)`
|
|
46
50
|
- docs-index 表格单元格：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`
|
|
47
51
|
- frontmatter：`sourceDoc: 配置根/stock-docs/技术方案设计.md`
|
|
48
52
|
|
|
49
53
|
**常见错误（禁止）：**
|
|
54
|
+
|
|
50
55
|
- **禁止** 在 Rule 内使用 `../../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
|
|
51
56
|
- **禁止** 在 Skill 内使用 `../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
|
|
52
57
|
- **禁止** 在 docs-index 内使用 `../stock-docs/` 或 `配置根/stock-docs/xxx.md` 作为链接 href —— 应仅为 `stock-docs/<文件名>.md`。
|
|
53
|
-
- **禁止** 在链接或 sourceDoc 中混用目录：生成上下文的链出与 **sourceDoc** 仅指向
|
|
54
|
-
- **禁止** 在 sourceDoc 中写相对路径如 `../stock-docs/xxx.md` 或
|
|
58
|
+
- **禁止** 在链接或 sourceDoc 中混用目录：生成上下文的链出与 **sourceDoc** 仅指向 `**stock-docs/`**；勿把 `**配置根/req-docs/**` 下的技术方案当作本技能产物的链出目标。
|
|
59
|
+
- **禁止** 在 sourceDoc 中写相对路径如 `../stock-docs/xxx.md` 或 `**配置根/req-docs/xxx.md`** —— 必须为 `配置根/stock-docs/<文件名>.md`。
|
|
55
60
|
|
|
56
|
-
**记忆要点**：默认文档目录为
|
|
61
|
+
**记忆要点**：默认文档目录为 `**配置根/stock-docs/`**（与项目约定一致）；Rule 内链出用 `../stock-docs/`，Skill 内链出用 `../../stock-docs/`，docs-index 内链出用 `stock-docs/`；sourceDoc 用 `配置根/stock-docs/<文件名>.md`。生成后自检所有链接与 sourceDoc，确保层级正确、与项目约定目录一致。
|
|
57
62
|
|
|
58
63
|
---
|
|
59
64
|
|
|
@@ -76,6 +81,7 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
76
81
|
**路径提醒**：写入 Rule/Skill/docs-index 时，文档链接 href 和 sourceDoc **必须**严格按「文档路径与链接约定」表执行——Rule 仅用 `../stock-docs/<文件名>.md`，Skill 仅用 `../../stock-docs/<文件名>.md`，docs-index 仅用 `stock-docs/<文件名>.md`，sourceDoc 仅用 `配置根/stock-docs/<文件名>.md`。勿凭印象写错层级。
|
|
77
82
|
|
|
78
83
|
**main.mdc 与 docs-index.md 的区别**
|
|
84
|
+
|
|
79
85
|
- **main.mdc**（`配置根/rules/main.mdc`）：**项目的总概述和索引**，固定命名 **main**，**唯一** alwaysApply 的 rule。给 AI 看的「体系结构 + 模块一览 + 公共能力入口」，让 AI 大致知道项目结构，需要时再去读各模块的 rule/skill；并在正文中**强制约定**「先查 `docs-index.md` 再下钻」（见 3.0 正文第 4 点），以落实渐进式读取。
|
|
80
86
|
- **docs-index.md**（`配置根/docs-index.md`）：**需求/文档索引**，按文档列出的表格（文档路径、Rules、Skills、简要说明），供人与 AI 查「某文档对应哪些产物」。不参与 alwaysApply，**须由 main 正文显式要求 Agent 在定位文档↔产物时优先读取**，否则不会自动进入上下文。
|
|
81
87
|
|
|
@@ -88,9 +94,9 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
88
94
|
2. **模块一览**（表格）：列「模块名」「说明」「详细约定加载方式」。每行对应一个功能模块：说明该模块用途；加载方式写「打开项目约定的该模块路径时自动加载对应 rule；或查阅 配置根/stock-docs/xxx、配置根/skills/xxx」。
|
|
89
95
|
3. **公共能力入口**（若有）：接口与上下文、消息队列、配置、公共工具等入口的简短描述 + 指向对应 rule，并写实现位置（按项目约定，如 ctx 注入、MQ 辅助、配置辅助、模型、公共工具等）。
|
|
90
96
|
4. **全文索引与渐进式读取（必填）**：须单独成段或小节，至少包含以下语义（可压缩措辞，不可删掉任一条）：
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
97
|
+
- **映射表位置**：「文档路径 ↔ Rules / Skills」的完整表在 `**配置根/docs-index.md`**（`docs-index` 非 alwaysApply，不会自动进上下文，须按需打开）。
|
|
98
|
+
- **读取顺序**：当要根据**某份 stock-docs 文档、某需求/模块名**定位应遵循的规则或应加载的技能时，**应先读取 `docs-index.md`**，在表中找到对应行，再按 **Rules**、**Skills** 列给出的路径打开 `.mdc` / `SKILL.md`；需要长文细节时再打开 **stock-docs** 链出的源文档；仍不足再下钻**业务源码**。
|
|
99
|
+
- **避免**：在未查 `docs-index.md`、未锁定相关 Rule/Skill 前，对工作区做**无范围**的大面积检索，或通读与当前问题**无关**的长文档。
|
|
94
100
|
5. 文末可再单列一行链接提示：**全文索引文件**：`配置根/docs-index.md`（与第 4 点呼应即可）。
|
|
95
101
|
- **main.mdc 的更新时机**：每次执行本技能时，**可能**会更新 main.mdc，**也可能**不更新。
|
|
96
102
|
- **会更新**：若本次文档属于「功能模块」或「公共模块说明」类，需在 main 的「模块一览」或「公共能力入口」中体现，则更新 main（若 main 不存在则先创建；若已存在则只更新与本次文档相关的部分，不删已有且无关的模块行）。
|
|
@@ -98,11 +104,14 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
98
104
|
|
|
99
105
|
### 3.1 Rules（专题规则，一律非 alwaysApply）
|
|
100
106
|
|
|
101
|
-
- **路径**：`配置根/rules/<主题>-
|
|
102
|
-
-
|
|
107
|
+
- **路径**：`配置根/rules/<主题>-ctx.mdc`（或拆解后的多条，如 common-interface-ctx.mdc）
|
|
108
|
+
- **按配置根区分（必守）**：
|
|
109
|
+
- `**.cursor/`（Cursor）**：规则文件扩展名 `**.mdc`**；路径范围用 `**globs:**`；专题规则 `**alwaysApply: false**`；总览 `**main.mdc**` 唯一 `**alwaysApply: true**`。
|
|
110
|
+
- `**.claude/`（Claude Code）**：规则须为 `**.md`**（Claude Code 不加载 `.mdc`）；路径范围用 `**paths:**`，**不要**写 `**globs:`**；**不要**写 `**alwaysApply`**（无 `paths` 的规则与会话一并加载）。若项目同时存在 `.cursor/` 与 `.claude/`，生成或更新 `**.claude/rules/**` 时须按上表写 `**.md**` + `**paths:**`。`flow2spec init claude` 已对包内模板做自动转换，手工新增规则时请对齐官方文档。
|
|
111
|
+
- **格式**（以 **Cursor `.mdc`** 为默认表述；**Claude** 将 `globs`→`paths`、扩展名 `.md` 即可）：
|
|
103
112
|
- frontmatter：`description: <一句话说明本规则>`，**禁止** `alwaysApply: true`（唯一 alwaysApply 为 main.mdc）
|
|
104
|
-
- **globs
|
|
105
|
-
- `alwaysApply: false
|
|
113
|
+
- **globs（必填，仅 Cursor）**：按主题限定在相关路径，例如功能模块 → `globs: "**/functions/<模块名>/**"`；接口与 ctx → `globs: "**/functions/**/*.js"`；消息队列消费 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录；公共工具 → `globs: "**/utils/common.js"` 或项目约定的工具路径。**Claude Code 下改为 `paths:`，键名同列表写法。**
|
|
114
|
+
- `alwaysApply: false`（仅 Cursor；Claude 专题规则不写此项）
|
|
106
115
|
- **版本管理（必填）**：`sourceDoc: <本次命令入参，即 配置根/stock-docs/xxx.md>`，`generatedAt: "<当前时间东八区北京时间，ISO 8601 如 2026-01-28T20:00:00+08:00>"`
|
|
107
116
|
- 正文：提炼的**核心概念、关键流程、规则要点**（Markdown，简洁可读）+ **文档链接**（链接 href 必须为 `../stock-docs/<文件名>.md`，见「文档路径与链接约定」）
|
|
108
117
|
- **与 main.mdc 的联动**：仅当本次**会更新** main.mdc 时（见 3.0「main.mdc 的更新时机」）：若本次是功能模块，生成/更新该 rule 后**必须**在 main 的「模块一览」中增加或更新该模块行；若本次是公共模块说明，在 main 的「公共能力入口」中体现即可。若本次**不更新** main，则不改 main.mdc。
|
|
@@ -119,18 +128,16 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
119
128
|
|
|
120
129
|
- **路径**：`配置根/docs-index.md`
|
|
121
130
|
- **操作**：若文件不存在，先创建表头：
|
|
122
|
-
|
|
123
131
|
```markdown
|
|
124
132
|
# 需求/文档索引
|
|
125
133
|
|
|
126
134
|
| 需求/模块 | 文档路径 | Rules | Skills | 简要说明 |
|
|
127
135
|
| --------- | -------- | ----- | ------ | -------- |
|
|
128
136
|
```
|
|
129
|
-
|
|
130
137
|
然后**追加一行**，且**必须填写 Rules、Skills 列**：
|
|
131
138
|
- **Rules**：本次生成的 Rule 路径，多个用顿号或空格分隔，如 `配置根/rules/<主题>-context.mdc` 或 `配置根/rules/common-interface-ctx.mdc`。注意：main.mdc 不在此列逐文档列出（main 为总索引，与单文档非一对一）。
|
|
132
139
|
- **Skills**：本次生成的 Skill 路径，多个用顿号或空格分隔，如 `配置根/skills/<主题>-context/SKILL.md` 或 `配置根/skills/common-modules-context/SKILL.md`、`配置根/skills/common-modules-mq-usage/SKILL.md`。
|
|
133
|
-
- **文档路径与链接（必守）**：文档路径列显示 `配置根/stock-docs/<文件名>.md`；链接 **必须** 为 `[配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md)`，即 href 只能是
|
|
140
|
+
- **文档路径与链接（必守）**：文档路径列显示 `配置根/stock-docs/<文件名>.md`；链接 **必须** 为 `[配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md)`，即 href 只能是 `**stock-docs/<文件名>.md`**（见上文「文档路径与链接约定」）。勿写成 `../stock-docs/` 或误指 `**req-docs/**`。
|
|
134
141
|
- 行示例：`| <文档标题> | [配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md) | <Rules 路径> | <Skills 路径> | <一两句摘要> |`
|
|
135
142
|
- 若文件已存在且表头无 Rules、Skills 列，则先补全表头再追加；追加时仍须填写 Rules、Skills 列。
|
|
136
143
|
- **同一文档只占一行**：若该文档路径（或文档标题）在表中已有行，则**更新该行**（覆盖 Rules、Skills、简要说明），不要追加新行，便于日后「修改文档后重新生成」时索引保持一对一。
|
|
@@ -158,7 +165,7 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
158
165
|
- 接口与 ctx 约定 → `globs: "**/functions/**/*.js"`
|
|
159
166
|
- 消息队列约定 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录
|
|
160
167
|
- 公共工具约定 → `globs: "**/utils/common.js"` 或项目约定路径
|
|
161
|
-
- 每条 rule 的 frontmatter 中 **且必须含** `sourceDoc`、`generatedAt`（同上），正文写该主题的**核心概念、关键流程、规则要点**，可带简短示例；单条建议
|
|
168
|
+
- 每条 rule 的 frontmatter 中 **且必须含** `sourceDoc`、`generatedAt`（同上），正文写该主题的**核心概念、关键流程、规则要点**，可带简短示例；单条建议 <50 行。生成功能模块 rule 后必须在 main.mdc 的「模块一览」中追加/更新对应行。
|
|
162
169
|
|
|
163
170
|
**Skills 拆分建议：**
|
|
164
171
|
|
|
@@ -177,20 +184,21 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
|
|
|
177
184
|
|
|
178
185
|
## 步骤 4：若输入是 URL，保存原文到项目
|
|
179
186
|
|
|
180
|
-
若用户提供的是 **URL**，请将你拉取到的**原始正文**保存到项目内
|
|
187
|
+
若用户提供的是 **URL**，请将你拉取到的**原始正文**保存到项目内 `**配置根/stock-docs/<主题>.md`**（或项目约定的文档目录），以便后续引用。主题名可从文档标题或 URL 路径推断，并做合法文件名处理。
|
|
181
188
|
|
|
182
189
|
---
|
|
183
190
|
|
|
184
191
|
## 约束与注意
|
|
185
192
|
|
|
186
193
|
- 所有路径均相对于**配置根的父目录**。
|
|
187
|
-
- **文档路径与链接（必守）**：一律按上文「文档路径与链接约定」执行。Rule 内链到文档 **仅允许** `../stock-docs/<文件名>.md`；Skill 内链到文档 **仅允许** `../../stock-docs/<文件名>.md`；docs-index 内链到文档 **仅允许** `stock-docs/<文件名>.md`。sourceDoc 仅允许 `配置根/stock-docs/<文件名>.md`。勿将
|
|
194
|
+
- **文档路径与链接（必守）**：一律按上文「文档路径与链接约定」执行。Rule 内链到文档 **仅允许** `../stock-docs/<文件名>.md`；Skill 内链到文档 **仅允许** `../../stock-docs/<文件名>.md`；docs-index 内链到文档 **仅允许** `stock-docs/<文件名>.md`。sourceDoc 仅允许 `配置根/stock-docs/<文件名>.md`。勿将 `**配置根/req-docs/`** 下的技术方案当作本技能产物的链出目标（链出**仅**指向 **stock-docs**）。
|
|
188
195
|
- **版本管理**：每条 Rule 与每条 Skill 的 frontmatter 必须含 `sourceDoc`（`配置根/stock-docs/xxx.md`）、`generatedAt`（东八区北京时间 ISO 8601 +08:00），便于更新时索源与重新生成。
|
|
189
196
|
- 生成前可先确认 `配置根/rules`、`配置根/skills`、`配置根/stock-docs` 目录存在，不存在则创建。
|
|
190
197
|
- **完成后自检（路径必查）**：
|
|
191
|
-
1. 每个 `.mdc` 中指向源文档的链接 href 是否为
|
|
192
|
-
2. 每个 `配置根/skills/**/SKILL.md` 中指向源文档的链接 href 是否为
|
|
193
|
-
3. `docs-index.md` 中该文档行的链接 href 是否为
|
|
194
|
-
4. 所有 Rule/Skill 的 frontmatter 中 `sourceDoc` 是否为
|
|
195
|
-
5. 链接目标与项目约定的文档目录一致（若约定为 `配置根/stock-docs/`，则勿用
|
|
198
|
+
1. 每个 `.mdc` 中指向源文档的链接 href 是否为 `**../stock-docs/<文件名>.md`**（不是 `../../stock-docs/` 或误链到 `req-docs/`）。
|
|
199
|
+
2. 每个 `配置根/skills/**/SKILL.md` 中指向源文档的链接 href 是否为 `**../../stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或误链到 `req-docs/`）。
|
|
200
|
+
3. `docs-index.md` 中该文档行的链接 href 是否为 `**stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或裸路径）。
|
|
201
|
+
4. 所有 Rule/Skill 的 frontmatter 中 `sourceDoc` 是否为 `**配置根/stock-docs/<文件名>.md**`。
|
|
202
|
+
5. 链接目标与项目约定的文档目录一致（若约定为 `配置根/stock-docs/`，则勿用 `**配置根/req-docs/**` 作为链接目标）。
|
|
196
203
|
完成后用一句话总结：已生成 Rules、Skills、文档索引及（若适用）配置根/stock-docs 下的原文备份；并确认「文档路径与链接约定」已遵守。
|
|
204
|
+
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: f2s-doc-add
|
|
3
|
+
description: 工作中把已落地能力解析进上下文（与 f2s-doc-arch 分工不同）：多文件路径→适度深度解析→stock-docs 初稿→终稿→f2s-ctx-build 产出 Rules、Skills、docs-index；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径；**路径默认相对「配置根的父目录」**（即业务仓库根），除非用户给出绝对路径。
|
|
7
|
+
|
|
8
|
+
# f2s-doc-add：多文件聚合 → 初稿 → 终稿 → Rules / Skills / 索引
|
|
9
|
+
|
|
10
|
+
## 使用时机（何时才用本技能）
|
|
11
|
+
|
|
12
|
+
本技能面向**日常开发/维护中**这一场景：**某条能力或功能已经在代码里做好**（或已有对应说明分散在多个文件），你希望把它**系统化解析并写入 AI 可用的上下文**（`stock-docs` 终稿 + Rules + Skills + `docs-index`），便于后续对话与协作**照着知识库走**。
|
|
13
|
+
|
|
14
|
+
- **典型**：补文档、做模块交接、把「已实现但只在代码里」的约定沉淀成可加载规则与技能。
|
|
15
|
+
- **非典型（勿用本技能当首选）**：从零画整体架构蓝图、只要一份架构初稿——请用 **f2s-doc-arch** 及后续 **f2s-doc-final** / **f2s-ctx-build** 按步执行。
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 与 f2s-doc-arch 的分工（必读）
|
|
20
|
+
|
|
21
|
+
| 技能 | 典型入口 | 产出侧重 |
|
|
22
|
+
|------|----------|----------|
|
|
23
|
+
| **f2s-doc-arch** | **一段说明**、**单个文档路径**，或确认后的**无参扫描** | **项目/模块架构说明初稿**（默认 `架构说明_初稿.md` 等），不写终稿、不直接跑 ctx-build |
|
|
24
|
+
| **f2s-doc-add**（本技能） | **工作中**为**已做好的能力**列出 **≥1 个相关文件路径**（实现、配置、说明等），多路径聚合 | 把该能力**解析进上下文**：**`stock-docs` 初稿** → **终稿** → **f2s-ctx-build** 生成 **Rules / Skills / docs-index** |
|
|
25
|
+
|
|
26
|
+
**不要混用**：仅要「架构说明初稿」、入口是文字或单文档时，用 **f2s-doc-arch**，**不要**用本技能代替。仅当用户明确要为**已存在实现的一批文件**做「进知识库 / 进上下文」的整条链时，用本技能。
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
本技能在流程上衔接 **f2s-doc-final** 与 **f2s-ctx-build** 的约定（**不包含** f2s-doc-arch 的架构专述步骤）：用户一次性提供**多个**本地文件路径，Agent **适度深度**阅读后先写 **`stock-docs` 初稿**，再在同一轮（或用户确认后的连续执行中）将初稿规范为 **终稿**，最后按 **`配置根/skills/f2s-ctx-build/SKILL.md`** 生成 **Rules、Skills、`docs-index.md`**（并按需更新 **`main.mdc`**）。
|
|
31
|
+
|
|
32
|
+
**与 f2s-doc-final / f2s-ctx-build 的关系**：终稿形态、链接、`sourceDoc` 等**以 `f2s-doc-final`、`f2s-ctx-build` 原文为准**；本文件只规定**多源入参、读源策略、与 f2s-doc-arch 的边界**。
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 入参
|
|
37
|
+
|
|
38
|
+
| 参数 | 必填 | 说明 |
|
|
39
|
+
|------|------|------|
|
|
40
|
+
| **文件路径列表** | **是** | 一个或多个路径：空格/换行分隔，或对话中 `@` 多文件。支持 `.md`、`.txt`、常见源码与配置（`.js`、`.ts`、`.json`、`.yaml` 等）。路径相对**配置根的父目录**，或绝对路径。 |
|
|
41
|
+
| **方案名**（可选） | 否 | 用于 `<方案名>_初稿.md`、`<方案名>_终稿.md` 及后续 **Rule/Skill 主题命名**；不传则从路径共性、目录名、`package.json` 的 `name` 等推断，并做**合法文件名**（去非法字符、避免空名）。 |
|
|
42
|
+
| **初稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_初稿.md`**。 |
|
|
43
|
+
| **终稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_终稿.md`**。 |
|
|
44
|
+
|
|
45
|
+
若用户**未给出任何可读路径**，**中止**并请其至少提供一条路径。
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 与现有知识库重合时的处理（重要）
|
|
50
|
+
|
|
51
|
+
执行前与读源后，应用 **`配置根/docs-index.md`**、**`配置根/rules/`**、**`配置根/skills/`** 及 **`配置根/stock-docs/`** 做一次**对照**（必要时结合对话里已加载的 Rules/Skills 摘要）：
|
|
52
|
+
|
|
53
|
+
| 情况 | 做法 |
|
|
54
|
+
|------|------|
|
|
55
|
+
| 用户给出的路径**本身就在** `stock-docs/`、`rules/`、`skills/` 内，且与当前任务**同一主题**（同一方案、同一模块说明） | **优先在原文件上直接修改**：合并重复段落、补全缺口、统一术语与链接，使单份文档或单条 Rule/Skill **自洽、合理**；**不要**仅为走流程再新建一套并行的 `_初稿.md` / `_终稿.md`，除非用户明确要求「另存新文件」。 |
|
|
56
|
+
| 知识库里**已有**描述同一能力的终稿 / Rule / Skill，而用户给的是**外围代码或其它 MD** | 以**既有知识库文件为锚点**：把新读到的信息**吸收进**对应终稿或专题 Rule/Skill（更新正文与 `generatedAt`），并同步 **`docs-index.md`** 中该行的「简要说明」等；避免 **docs-index** 出现多行指向实质重复的主题。 |
|
|
57
|
+
| **无重合**或确认为**全新主题** | 按默认路径新建 **`<方案名>_初稿.md`** → **`_终稿.md`**，再执行步骤 4 **新建或追加** Rule/Skill 与索引行（仍遵守 **f2s-ctx-build** 的「同一终稿只占一行」）。 |
|
|
58
|
+
|
|
59
|
+
**原则**：知识库里**已经写过**的说明，以**修订原文件**为主，保证上下文**不重复、不打架**；新建文件仅在有明确增量主题或用户指定新方案名时使用。
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 步骤 0：准备
|
|
64
|
+
|
|
65
|
+
1. 确保 **`配置根/stock-docs/`** 存在（不存在则创建）。
|
|
66
|
+
2. 解析路径列表：去重、展开用户 `@` 的文件；**不存在的路径**在初稿「来源与缺口」中列出，**不中断**（除非全部无效则中止）。
|
|
67
|
+
3. **对照**上文「与现有知识库重合时的处理」：决定本轮产出是**更新既有路径**还是**新建** `<方案名>_初稿.md` / `_终稿.md`，并在回复中**一句话说明**本次选择理由。
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 步骤 1：适度深度解析（读源策略）
|
|
72
|
+
|
|
73
|
+
对每个文件**依次**读取（可用工具分批，避免单次过大）：
|
|
74
|
+
|
|
75
|
+
| 情况 | 策略 |
|
|
76
|
+
|------|------|
|
|
77
|
+
| 文本/Markdown/常规源码，体量 **≤ 约 500 行** | 尽量**通读**全文。 |
|
|
78
|
+
| **更大** 或响应体过长 | **适度深度**：优先读 **文件头/尾**、**导出/类/接口定义**、**配置块**、**README 式章节标题**；代码可结合目录与符号性段落归纳，**禁止**假装已读未读部分。 |
|
|
79
|
+
| **二进制**或无法解码 | 跳过并在初稿注明「无法解析」。 |
|
|
80
|
+
| **多文件** | 归纳：**模块边界**、**重复出现的概念**、**依赖/调用关系**、与 **`配置根`** 约定相关的目录（若有）。 |
|
|
81
|
+
|
|
82
|
+
解析目标：足够支撑一份**结构清楚、有主有次**的初稿，而非逐字抄录。
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 步骤 2：生成初稿
|
|
87
|
+
|
|
88
|
+
1. 若已判定在**既有文件**上修订：可将「初稿」阶段体现为**该文件内的增补段落**或**同路径覆盖**（合并读源结论），不必机械新建 `_初稿.md`。否则写入 **默认** **`配置根/stock-docs/<方案名>_初稿.md`**（或用户指定的初稿路径）。
|
|
89
|
+
2. 初稿**无固定版式**，建议包含：
|
|
90
|
+
- **概述**（这批文件共同说明什么）；
|
|
91
|
+
- **来源清单**（路径 + 每文件一句话作用 + 是否部分阅读）；
|
|
92
|
+
- **分文件/分模块归纳**（适度深度解析的结论）；
|
|
93
|
+
- **交叉关系**（配置、入口、数据流等）；
|
|
94
|
+
- **待确认项**（读源时未覆盖或推断处）。
|
|
95
|
+
3. 文末可加一句：**「本初稿由 f2s-doc-add 根据用户所列文件聚合生成。」**
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 步骤 3：基于初稿生成终稿（对齐 f2s-doc-final）
|
|
100
|
+
|
|
101
|
+
1. **读取** **`配置根/template/终稿模版.md`**（若存在）作为章节提示；**不强制逐条套用**，以初稿事实与逻辑为主。
|
|
102
|
+
2. 将初稿**提炼、归纳**为终稿风格 Markdown（参见 **`配置根/skills/f2s-doc-final/SKILL.md`** 流程一）：
|
|
103
|
+
- **一级标题** = 方案名（可与 `<方案名>` 一致或略润色）；
|
|
104
|
+
- **至少**包含二级标题：**核心概念**、**业务规则**、**关键流程**；
|
|
105
|
+
- 按需补充：状态与流转、接口/API、配置与错误、实现位置与对接方式等。
|
|
106
|
+
3. 写入 **默认** **`配置根/stock-docs/<方案名>_终稿.md`**（或用户指定的终稿路径）；若本轮锚定**已有终稿路径**，则在**该文件上**按终稿结构整理保存，并保证 **`sourceDoc` 仍指向该路径**（步骤 4 中 Rule/Skill 链接与 frontmatter 与之一致）。
|
|
107
|
+
|
|
108
|
+
若用户要求「先审初稿再出终稿」，可在初稿保存后**暂停**并等待确认；用户确认后从**同一份初稿**继续执行步骤 3～4。
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 步骤 4：基于终稿生成 Rules、Skills 与索引（对齐 f2s-ctx-build）
|
|
113
|
+
|
|
114
|
+
以 **步骤 3 产出或修订后的终稿**（单一 `stock-docs` 下的 `.md` 文件）为 **`sourceDoc` 锚定文档**，执行 **`配置根/skills/f2s-ctx-build/SKILL.md`** 中的要求，包括但不限于：
|
|
115
|
+
|
|
116
|
+
- **拆解与分工**：篇幅长、多块独立内容时，拆成多条专题 Rule / 多个 Skill + 总览；否则可单 Rule + 单 Skill。
|
|
117
|
+
- **文档路径与链接约定**（**必守**）：Rule 正文链向源文档用 **`../stock-docs/<终稿文件名>.md`**；Skill 用 **`../../stock-docs/<终稿文件名>.md`**；`docs-index.md` 中该文档格用 **`stock-docs/<终稿文件名>.md`** 作为 href；每条 Rule/Skill 的 frontmatter **`sourceDoc`** 为 **`配置根/stock-docs/<终稿文件名>.md`**，并带 **`generatedAt`**（东八区 ISO 8601）。
|
|
118
|
+
- **`main.mdc`**：按 f2s-ctx-build「3.0」判断是否更新模块一览/公共能力入口。
|
|
119
|
+
- **`docs-index.md`**：同一终稿路径**只占一行**；若已存在则**更新**该行的 Rules、Skills、简要说明。
|
|
120
|
+
|
|
121
|
+
**禁止**将 **`req-docs/`** 下的文件作为本技能链最终 `sourceDoc` 指向；终稿必须在 **`stock-docs/`**。
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 输出与自检
|
|
126
|
+
|
|
127
|
+
完成后向用户说明：
|
|
128
|
+
|
|
129
|
+
1. **初稿**（若单独落盘）、**终稿**的磁盘路径，或写明「本轮仅在既有 `xxx.md` / 某 Rule / 某 Skill 上修订」；
|
|
130
|
+
2. **新建或更新**的 Rule、Skill 路径及 **`docs-index`** 是否已更新；
|
|
131
|
+
3. 提醒：若 **`main.mdc`** 已改，需扫一眼渐进式读取约定是否仍连贯。
|
|
132
|
+
|
|
133
|
+
**自检**：对照 **`f2s-ctx-build`** 技能末尾「完成后自检（路径必查）」五项，核对链接与 `sourceDoc`。
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 约束与注意
|
|
138
|
+
|
|
139
|
+
- **与知识库重合时**：已述内容见上文「与现有知识库重合时的处理」；**禁止**在已有同主题终稿/Rules/Skills 时仍机械新建平行文件导致重复索引。
|
|
140
|
+
- **适度深度**是硬性要求：大文件不得虚构未读段落细节；不确定处写入待确认或终稿「（待补充）」。
|
|
141
|
+
- **版权与敏感**：用户给出的路径可能含密钥或内网信息；写入 `stock-docs` 前**脱敏**或删去秘钥，并在初稿/终稿注明「已脱敏」若已处理。
|
|
142
|
+
- 本技能**不替代**单独执行 **f2s-doc-pdf**（PDF 须先转 MD 再作为路径列表之一传入）。
|
|
@@ -8,6 +8,8 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
|
|
|
8
8
|
|
|
9
9
|
本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。
|
|
10
10
|
|
|
11
|
+
**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进上下文（初稿→终稿→Rules/Skills/索引），应使用 **`配置根/skills/f2s-doc-add/SKILL.md`**，**勿用本技能冒充该流程**。
|
|
12
|
+
|
|
11
13
|
---
|
|
12
14
|
|
|
13
15
|
## 入参（均可选）
|
|
@@ -30,7 +30,7 @@ description: 根据用户指出的实现规则错误，修正代码并同步更
|
|
|
30
30
|
|
|
31
31
|
4. **更新全局规则与 Skill**
|
|
32
32
|
- 若该约定为项目级或模块级：
|
|
33
|
-
- 在项目约定的规则目录（如 `配置根/rules
|
|
33
|
+
- 在项目约定的规则目录（如 `配置根/rules/`）下新增或更新一条规则，写清「必须/禁止」及适用范围（**Cursor**：`globs` + **`.mdc`**；**Claude Code** 的 **`.claude/rules/`**：**`.md`** + **`paths:`**，勿写 **`.mdc`** / **`globs:`**）。
|
|
34
34
|
- 在项目约定的技能目录（如 `配置根/skills/`）下新增或更新一个 Skill，写清触发词与正确/错误示例，便于后续实现与 AI 按规则执行。
|
|
35
35
|
- 规则与 Skill 中可引用文档作为约定出处。
|
|
36
36
|
|
|
@@ -1,32 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: f2s-req-clarify
|
|
3
|
-
description: 针对 PRD
|
|
3
|
+
description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出技术方案；触发：需求澄清、PRD 澄清
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 需求澄清
|
|
7
7
|
|
|
8
8
|
**入参**：可选。PRD 全文、需求描述或文档路径（如 **`.cursor/req-docs/xxx.md`**）；不传则按当前对话内容澄清。后续回复可补需求条件。
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
**行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- 阅读 PRD/描述后，找出模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点。
|
|
15
|
-
- **必须把分组、具体可答的反问输出在对话中**（用户可见的回复正文），便于用户逐条答复。**禁止**在本阶段写入 `.cursor/req-docs/` 或输出一份完整的「需求澄清文档」正文（不要一上来就甩整篇 MD）。
|
|
16
|
-
- 根据用户回答**迭代追问**，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。
|
|
17
|
-
|
|
18
|
-
### 阶段二：澄清文档（仅在信息已足够清晰后）
|
|
19
|
-
|
|
20
|
-
- **仅当**流程、边界、异常、关键概念已无歧义（或用户明确表示「可以定稿 / 先按当前理解出文档」）时，再输出一份可直接落盘的「需求澄清文档」（Markdown）。
|
|
21
|
-
- 文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（若有）。
|
|
22
|
-
- 建议保存路径：**`.cursor/req-docs/`**（由用户或 Agent 在定稿后落盘）。
|
|
23
|
-
- 输出完文档后，再提示使用 **f2s-req-backend**（可附带已定稿要点）生成技术方案。**本技能阶段不输出**技术方案或接口设计。
|
|
24
|
-
|
|
25
|
-
## 禁止
|
|
26
|
-
|
|
27
|
-
- **禁止**在首次处理需求时直接输出完整澄清文档或创建 `req-docs` 澄清终稿（除非用户明确要求跳过反问、直接根据已有材料生成文档）。
|
|
28
|
-
- **禁止**用「仅附件/仅工具写入」代替在对话中展示问题：阶段一反问须出现在**对话框**中。
|
|
29
|
-
|
|
30
|
-
## 与用户协作提示（可写在阶段二末尾）
|
|
31
|
-
|
|
32
|
-
- 若用户希望保留反问记录，可在定稿文档中增加「澄清过程摘要」小节，概括对话中已确认的结论（非必须）。
|
|
12
|
+
**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 **`.cursor/req-docs/`**。输出完文档后，再提示使用 **f2s-req-backend 技能**（可附带需求条件）生成技术方案，供后续代码实现。不在此阶段输出技术方案或接口设计。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: stock-docs-vs-req-docs
|
|
3
|
-
description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs
|
|
3
|
+
description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、f2s-ctx-build、f2s-doc-arch、f2s-doc-add、已落地能力、技术方案放哪、PDF 终稿
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# stock-docs 与 req-docs（技能）
|
|
@@ -9,19 +9,21 @@ description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-doc
|
|
|
9
9
|
|
|
10
10
|
- 用户问「文档放哪」「PDF 转完放哪」「生成 Rules 用哪个目录」「技术方案目录」等。
|
|
11
11
|
- 实现或命令执行时需要选择 **`配置根/stock-docs/`** 还是 **`配置根/req-docs/`**。
|
|
12
|
+
- 区分 **f2s-doc-arch**（架构说明**初稿**）与 **f2s-doc-add**（**工作中**把**已落地能力**从多文件解析进上下文）：二者产物都落在 **stock-docs/**，与 **req-docs** 无关；分工见 **`skills/f2s-doc-arch/SKILL.md`**、**`skills/f2s-doc-add/SKILL.md`**。
|
|
12
13
|
|
|
13
14
|
## 核心对照
|
|
14
15
|
|
|
15
16
|
| 目录 | 位置 | 用途 |
|
|
16
17
|
|------|------|------|
|
|
17
|
-
| **stock-docs** | 配置根下 |
|
|
18
|
-
| **req-docs** | 配置根下（如 `.cursor/req-docs/`） | 需求与技术方案 → 按 `implement-tech-design`
|
|
18
|
+
| **stock-docs** | 配置根下 | **存量上下文源** → **f2s-ctx-build** 入参；**f2s-doc-final** 的初稿/终稿；**f2s-doc-arch** 的架构初稿；**f2s-doc-add** 聚合读源后的初稿与终稿（与 f2s-doc-arch 分工不同，见该 SKILL「使用时机」） |
|
|
19
|
+
| **req-docs** | 配置根下（如 `.cursor/req-docs/`） | 需求与技术方案 → 按 `implement-tech-design` **写代码**、**f2s-doc-pdf** 输出 |
|
|
19
20
|
|
|
20
21
|
## 常见错误
|
|
21
22
|
|
|
22
23
|
- 把 **仅用于实现代码** 的 **`配置根/req-docs/xxx.md`** 当作 **f2s-ctx-build** 技能的入参（应先把符合终稿范式的内容放到 **stock-docs** 再生成上下文）。
|
|
23
24
|
- 在 Rule 内链到 **`req-docs/`**（应链到 **stock-docs** 中的源文档）。
|
|
25
|
+
- 把 **f2s-doc-add** / **f2s-doc-arch** 产出的初稿、终稿误存到 **req-docs**（应始终在 **stock-docs/**）。
|
|
24
26
|
|
|
25
27
|
## 详细约定
|
|
26
28
|
|
|
27
|
-
见 Flow2Spec 包内
|
|
29
|
+
见 Flow2Spec 包内 **`docs/README-目录与路径约定.md`**；技能顺序与 **f2s-doc-arch** / **f2s-doc-add** 见 **`docs/README-命令说明.md`**。具体步骤以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**）为准。
|