@double-codeing/flow2spec 2.2.0
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 +90 -0
- package/cli.js +62 -0
- package/docs/Flow2Spec/344/275/277/347/224/250/350/257/264/346/230/216.md +170 -0
- package/docs/README-/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md +132 -0
- package/docs/README-/345/221/275/344/273/244/350/257/264/346/230/216.md +258 -0
- 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 +119 -0
- package/docs/images//345/216/237/347/220/206/345/233/2761.png +0 -0
- package/docs/images//345/216/237/347/220/206/345/233/2762.png +0 -0
- package/docs/images//345/221/275/344/273/244/346/230/216/347/273/206/345/233/276.png +0 -0
- package/docs/images//346/227/245/345/270/270/346/223/215/344/275/234/346/265/201/347/250/213/345/233/276.png +0 -0
- package/docs/images//347/256/200/350/277/260/345/233/276.png +0 -0
- package/lib/agents.js +35 -0
- package/lib/init.js +68 -0
- package/package.json +59 -0
- package/templates/rules/implement-tech-design.mdc +177 -0
- package/templates/rules/stock-docs-vs-req-docs.mdc +14 -0
- package/templates/skills/f2s-ctx-build/SKILL.md +196 -0
- package/templates/skills/f2s-ctx-rm/SKILL.md +63 -0
- package/templates/skills/f2s-doc-arch/SKILL.md +74 -0
- package/templates/skills/f2s-doc-final/SKILL.md +85 -0
- package/templates/skills/f2s-doc-pdf/SKILL.md +63 -0
- package/templates/skills/f2s-kb-feat/SKILL.md +79 -0
- package/templates/skills/f2s-kb-fix/SKILL.md +67 -0
- package/templates/skills/f2s-kb-merge/SKILL.md +71 -0
- package/templates/skills/f2s-kb-sync/SKILL.md +88 -0
- package/templates/skills/f2s-req-backend/SKILL.md +52 -0
- package/templates/skills/f2s-req-clarify/SKILL.md +12 -0
- package/templates/skills/stock-docs-vs-req-docs/SKILL.md +27 -0
- package/templates/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md +83 -0
- package/templates/template//347/273/210/347/250/277/346/250/241/347/211/210.md +93 -0
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
# 工作流与技能说明
|
|
2
|
+
|
|
3
|
+
本文档说明 **Flow2Spec** 各 **Skill**（`skills/<标识>/SKILL.md`）的**入参、输出与行为**，并按**使用顺序**提供速查。文中 **「配置根」** 指 `flow2spec init` 所选 AI 工具目录（默认 **`.cursor/`**，亦可是 **`.claude/`**、**`.codex/`** 等）；子路径（`stock-docs/`、`rules/` 等）结构相同。目录与路径约定见 [README-目录与路径约定](./README-目录与路径约定.md)（§1 目录结构）；init 详解见 [Flow2Spec使用说明](./Flow2Spec使用说明.md#一init-做了什么)；架构见 [README-体系与原理](./README-体系与原理.md)。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 按使用顺序查找
|
|
8
|
+
|
|
9
|
+
按**推荐使用顺序**列出的技能速查，便于按流程直接跳转到对应说明。
|
|
10
|
+
|
|
11
|
+
| 阶段 | 步骤 | 技能标识（`skills/<标识>/`） | 一句话说明 | 详见 |
|
|
12
|
+
| ---------------- | --------------- | --------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------ |
|
|
13
|
+
| **项目首次使用** | — | `flow2spec init [agent ...]` | 按所选 agent 写入**配置根**模板（详见 `--help`） | [§1](#1-flow2spec-initcli) |
|
|
14
|
+
| **需求与方案** | 1 | **`f2s-req-clarify`** | 针对 PRD/需求反问直到需求完全清楚 | [§2.0.1](#201-f2s-req-clarify) |
|
|
15
|
+
| | 2 | **`f2s-req-backend`** | 根据澄清后需求基于项目知识库生成后端技术文档 | [§2.0.2](#202-f2s-req-backend) |
|
|
16
|
+
| **上下文生成** | 1 | **`f2s-doc-arch`** | 生成项目架构说明**初稿** | [§2.1](#21-f2s-doc-arch) |
|
|
17
|
+
| | 2 | **`f2s-doc-final`** | 将初稿/PDF/MD 转为《终稿模版》**终稿** | [§2.2](#22-f2s-doc-final) |
|
|
18
|
+
| | 3 | **`f2s-ctx-build`** | 根据终稿生成 **Rules、Skills、文档索引** | [§2.3](#23-f2s-ctx-build) |
|
|
19
|
+
| | 配合 | **`f2s-ctx-rm`** | 删除某文档对应的 Rules、Skills、索引 | [§2.4](#24-f2s-ctx-rm) |
|
|
20
|
+
| | 可选 | **`f2s-doc-pdf`** | 仅有 PDF 时先转成 MD | [§2.5](#25-f2s-doc-pdf) |
|
|
21
|
+
| **提问与实现** | — | **按技术方案实现** | 在对话中提供 **`配置根/req-docs/xxx.md`** 并说明按方案实现；可选先用 **`f2s-doc-pdf`** | [§3.1](#31-按技术方案实现) · [§2.5](#25-f2s-doc-pdf) |
|
|
22
|
+
| **实现后** | 按需 | **`f2s-kb-fix`** | 用户指出规则错误时：改代码并同步文档与规则 | [§3.2](#32-f2s-kb-fix--f2s-kb-feat--f2s-kb-sync) |
|
|
23
|
+
| | 按需 | **`f2s-kb-feat`** | 新增能力：补全实现与文档，或仅补文档 | [§3.2](#32-f2s-kb-fix--f2s-kb-feat--f2s-kb-sync) |
|
|
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)。
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 1. flow2spec init（CLI）
|
|
32
|
+
|
|
33
|
+
在**配置根父目录**执行，并按所选 **agent** 将模板写入对应**配置根**。
|
|
34
|
+
|
|
35
|
+
| 项目 | 说明 |
|
|
36
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
37
|
+
| **用法** | `npx @double-codeing/flow2spec init` 或 `flow2spec init [cursor \| claude \| codex ...]`（全局安装后）；省略 agent 时默认为 **cursor**（写入 **`.cursor/`**）。完整列表与示例见 **`flow2spec --help`**。 |
|
|
38
|
+
| **创建/写入** | 对每个所选 agent：在配置根下创建 `stock-docs/`、`req-docs/`、`template/`、`rules/`、`skills/` 并复制模板。详见 [Flow2Spec使用说明 - init 做了什么](./Flow2Spec使用说明.md#一init-做了什么)。 |
|
|
39
|
+
| **结果** | 配置根为 **`.cursor/`** 时，工作流在 **`skills/`** 下；由 Agent 按场景加载对应 **SKILL.md**。 |
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 2. 阶段一：需求与方案、上下文生成
|
|
44
|
+
|
|
45
|
+
### 2.0 需求与方案（可选）
|
|
46
|
+
|
|
47
|
+
当用户手头有 PRD 或需求描述、希望先澄清再产出后端技术方案时，可先使用 **`f2s-req-clarify`**，澄清完成后使用 **`f2s-req-backend`**。
|
|
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。
|
|
91
|
+
|
|
92
|
+
| 项目 | 说明 |
|
|
93
|
+
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| **入参** | 一个：**PDF 路径**或 **MD 路径**；可选第二个参数为输出路径 |
|
|
95
|
+
| **规范来源** | 优先读取 `template/终稿模版.md`；若不存在则用命令内嵌结构 |
|
|
96
|
+
| **输出位置** | PDF 首次：`stock-docs/<方案名>_初稿.md`（初稿）；MD/初稿转为规范格式：`stock-docs/<方案名>_终稿.md`（终稿）。详见 [文档产物阶段](./README-目录与路径约定.md#3-文档产物阶段原稿--初稿--终稿)。 |
|
|
97
|
+
|
|
98
|
+
传入 Markdown 时：分析并重组为「核心概念、业务规则、关键流程」等模板结构，写入终稿。传入 PDF 时：首次执行输出初稿，用户确认后再执行一次（传入初稿路径）输出终稿。完成后提示可执行 **f2s-ctx-build** 技能 并传入 `stock-docs/<方案名>_终稿.md`。
|
|
99
|
+
|
|
100
|
+
### 2.3 **f2s-ctx-build** 技能
|
|
101
|
+
|
|
102
|
+
根据文档生成 Rules、Skills、文档索引（及按需更新 main.mdc）。
|
|
103
|
+
|
|
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-文档产物阶段原稿--初稿--终稿)。 |
|
|
110
|
+
|
|
111
|
+
**注意**：同一文档多次执行会**更新**该文档对应的 Rules、Skills 及 docs-index 该行，不会重复追加行。内网 URL 可能无法访问，请先将内容保存到 `stock-docs/xxx.md` 再传路径。
|
|
112
|
+
|
|
113
|
+
### 2.4 **f2s-ctx-rm** 技能
|
|
114
|
+
|
|
115
|
+
删除某份文档对应的 Rules、Skills、索引行及 main 中的相关描述。
|
|
116
|
+
|
|
117
|
+
| 项目 | 说明 |
|
|
118
|
+
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
119
|
+
| **入参** | 一个：**文档路径**（如 `stock-docs/拼团技术方案设计.md`）或 **可匹配的片段**（如 `拼团技术方案设计.md`） |
|
|
120
|
+
| **行为** | 在 docs-index 中匹配该文档行 → 删除该行中的 Rules、Skills 文件及 Skill 空目录 → 从 docs-index 删除该行 → 更新 main.mdc（删除模块一览对应行或公共能力入口节） |
|
|
121
|
+
| **结果** | 该文档不再拥有对应 Rule/Skill，索引与 main 中相关描述被移除；**`stock-docs/`** 下的源文档不删除 |
|
|
122
|
+
|
|
123
|
+
**注意**：若匹配到多行或删除范围不明确，大模型会向用户确认后再执行。
|
|
124
|
+
|
|
125
|
+
### 2.5 **f2s-doc-pdf** 技能
|
|
126
|
+
|
|
127
|
+
将 PDF 技术方案文档转为 Markdown 并保存到项目，并可引导用户补全流程说明（流程图无法从 PDF 解析时）。
|
|
128
|
+
|
|
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，再在对话中提供该路径并说明按方案实现。 |
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 3. 阶段二：提问与实现、实现后
|
|
139
|
+
|
|
140
|
+
### 3.1 按技术方案实现
|
|
141
|
+
|
|
142
|
+
- **方式**：在对话中提供 **`配置根/req-docs/xxx.md`**（如 **`.cursor/req-docs/xxx技术方案.md`**），并明确说明「按该技术方案实现代码」。
|
|
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`**。
|
|
147
|
+
|
|
148
|
+
### 3.2 f2s-kb-fix / f2s-kb-feat / f2s-kb-sync
|
|
149
|
+
|
|
150
|
+
| 命令 | 何时用 | 说明 |
|
|
151
|
+
| -------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
152
|
+
| **`f2s-kb-fix`** | 实现后用户指出某处违反项目规则或约定 | 根据用户描述修正相关代码，并同步更新与该约定相关的文档、`rules/*.mdc` 与 `skills/*/SKILL.md`。详见 `skills/f2s-kb-fix/SKILL.md`。 |
|
|
153
|
+
| **`f2s-kb-feat`** | 用户要新增能力（功能、模块或约定） | 若尚未实现则按项目约定补全实现并补充文档、规则与 Skill；若已实现则基于现有实现与规则仅补充/对齐文档与 Rule/Skill。详见 `skills/f2s-kb-feat/SKILL.md`。 |
|
|
154
|
+
| **`f2s-kb-sync`** | 需要把会话与项目现状沉淀到知识库时 | 可**列出 Agent 已实现的能力**，也可**零输入**；零输入时由 Agent 根据当前上下文推断用户与项目关心的能力 → **输出更新大纲** → 用户确认后再写入 `rules/`、`skills/`、`docs-index.md`、`main.mdc` 等以注入上下文；可附文档路径或 `@` 文件。 |
|
|
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）
|
|
173
|
+
|
|
174
|
+
### 需求与方案（可选）
|
|
175
|
+
|
|
176
|
+
当有 PRD 或需求需先澄清再写技术方案时：
|
|
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 后**：自动合并索引/规则/技能/说明类冲突；实现与配置类仅对比与建议，待用户确认 |
|
|
202
|
+
|
|
203
|
+
完成「上下文生成」1～3 后，再按「提问与实现环节」实现代码；**f2s-kb-fix** 在实现后、用户指出某处违反规则时使用；**f2s-kb-feat** 在新增能力时使用；**f2s-kb-sync** 可按需执行。**f2s-kb-merge** 在合并分支后出现冲突标记时使用，与上述命令无固定先后顺序。
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 5. 其它
|
|
208
|
+
|
|
209
|
+
- **根据技术方案实现代码**：Rule `implement-tech-design.mdc`；在对话中提供技术方案路径（通常为 **`.cursor/req-docs/xxx.md`**），AI 按规则执行读文档、列任务、提问、实现、待完成列表与平台配置提醒。
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 6. 技能关系简图
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
flow2spec init [agent ...]
|
|
217
|
+
└── 创建 配置根/*（可多套）；写入 rules、skills、template 与预建 stock-docs、req-docs
|
|
218
|
+
|
|
219
|
+
推荐顺序（需求与方案）：需求澄清 → 后端方案
|
|
220
|
+
推荐顺序（上下文）：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
|
|
221
|
+
推荐顺序（提问与实现）：（可选 f2s-doc-pdf）→ 按 req-docs 技术方案 + implement-tech-design 实现 → f2s-kb-sync（可选：指定能力或零输入推断后注入知识库）
|
|
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 冲突 → 上下文类自动合并；实现/配置类仅对比与建议，待用户确认
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 7. 快速参考（按阶段）
|
|
240
|
+
|
|
241
|
+
| 阶段 | 想做的事 | 用哪个技能 |
|
|
242
|
+
| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
243
|
+
| **项目首次** | 在当前项目使用 Flow2Spec | `flow2spec init` 或 `flow2spec init claude` 等；见 `flow2spec --help` |
|
|
244
|
+
| **需求与方案** | 针对 PRD/需求反问直到清楚 | **f2s-req-clarify** 技能：可传 PRD 全文、需求描述或文档路径 |
|
|
245
|
+
| | 根据澄清后需求生成后端技术文档 | **f2s-req-backend** 技能：必传需求或文档路径，可附带需求条件；输出默认 `req-docs/<方案名>_技术方案.md` |
|
|
246
|
+
| **上下文生成** | 生成项目架构说明初稿 | **f2s-doc-arch** 技能：可传说明文字或文档路径；输出默认 `stock-docs/<项目名>架构说明_初稿.md` |
|
|
247
|
+
| | 把 PDF 或杂乱 MD 变成规范技术方案（终稿） | **f2s-doc-final** 技能 + `stock-docs/xxx.pdf` 或 `xxx.md`；PDF 先出初稿，再执行一次出终稿 |
|
|
248
|
+
| | 把需求/方案文档变成 AI 可用的 Rules、Skills | **f2s-ctx-build** 技能 + `stock-docs/xxx.md`（通常 `_终稿.md`） |
|
|
249
|
+
| | 不再需要某文档的上下文 | **f2s-ctx-rm** 技能 + `stock-docs/xxx.md` 或 `xxx` |
|
|
250
|
+
| | 更新某文档的 Rules、Skills | 改文档后再次 **f2s-ctx-build** 技能 + 同一路径 |
|
|
251
|
+
| **提问与实现** | 手头只有 PDF、要按方案实现代码 | 先按 **f2s-doc-pdf** 技能处理 PDF 并落到 **req-docs/**，再在对话中提供该 MD 路径并说明按方案实现 |
|
|
252
|
+
| | 按 **req-docs/** 技术方案实现代码 | 在对话中提供 **`.cursor/req-docs/xxx.md`**（或相对配置根路径）并说明按技术方案实现 |
|
|
253
|
+
| **实现后** | 用户指出规则错误：改代码并同步文档与规则 | **f2s-kb-fix** 技能 |
|
|
254
|
+
| | 新增能力（功能/模块/约定）：补全实现与文档，或已实现则仅补文档与规则 | **f2s-kb-feat** 技能 |
|
|
255
|
+
| | 指定已实现能力或零输入推断关心能力 → 大纲确认 → 写入知识库并注入上下文 | **f2s-kb-sync** 技能（可选） |
|
|
256
|
+
| | merge/rebase 后：规则/索引/技能/说明与代码同时有冲突 | **f2s-kb-merge** 技能；可 `@` 指定冲突文件 |
|
|
257
|
+
|
|
258
|
+
**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)（init 详解、典型流程、技能与工作流） | [README-目录与路径约定](./README-目录与路径约定.md)（目录结构、产物阶段、链接约定） | [README-体系与原理](./README-体系与原理.md)（架构与设计原则）
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# 目录与路径约定
|
|
2
|
+
|
|
3
|
+
本文档说明 **Flow2Spec** 在项目内使用的目录结构、文档路径与链接约定，以及版本管理字段。遵守这些约定可避免 AI 生成错误链接、便于索源与更新。
|
|
4
|
+
|
|
5
|
+
**命名一览（区分：业务项目「配置根」下的文档目录 vs Flow2Spec 包内的说明目录）**
|
|
6
|
+
|
|
7
|
+
| 目录 | 位置 | 用途 |
|
|
8
|
+
|------|------|------|
|
|
9
|
+
| **`stock-docs/`** | 如 `.cursor/stock-docs/` | **存量上下文源**：PDF/初稿/终稿/架构说明等，供 **f2s-ctx-build** 技能生成 Rules、Skills、索引 |
|
|
10
|
+
| **`req-docs/`** | 如 `.cursor/req-docs/` | **需求与技术方案**：澄清需求、后端技术方案、PDF 转 MD（实现用）等，配合 `implement-tech-design` **按方案写代码** |
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. 目录结构（配置根与配置根父目录）
|
|
16
|
+
|
|
17
|
+
**「配置根」**：`flow2spec init [agent ...]` 写入的 AI 工具配置目录。默认 **Cursor** 为 **`.cursor/`**；可选 **`.claude/`**、**`.codex/`** 等（可多选，各自一套相同子结构）。下文表格以 **`.cursor/`** 为例；若你的配置根为 `.claude/`，将路径中的 `.cursor` 替换为 `.claude` 即可。
|
|
18
|
+
|
|
19
|
+
**配置根**下为 **stock-docs/**、**req-docs/**、**rules/**、**skills/**、**template/** 及 **docs-index.md**。下表**左列**为逻辑位置，**中列**为 Cursor（配置根 `.cursor/`）时的完整路径示例；使用 **`.claude/`** 等时把中列的 `.cursor` 换成对应目录名即可。
|
|
20
|
+
|
|
21
|
+
| 逻辑位置（相对配置根或配置根父目录） | Cursor 下路径示例 | 说明 |
|
|
22
|
+
| ------------------------ | ----------------- | ---- |
|
|
23
|
+
| `stock-docs/` | `.cursor/stock-docs/` | **存量源文档**；终稿、架构初稿、从 PDF 整理的 MD 等，用于**生成 Rules、Skills、索引** |
|
|
24
|
+
| `rules/` | `.cursor/rules/` | **main.mdc**（总概述，唯一 alwaysApply）与各**专题 Rule**（*-context.mdc） |
|
|
25
|
+
| `skills/` | `.cursor/skills/` | Agent Skills：按主题分子目录，每目录下 **SKILL.md**（工作流与说明由 `flow2spec init` 写入） |
|
|
26
|
+
| `template/` | `.cursor/template/` | 《终稿模版》《后端技术模版》等 |
|
|
27
|
+
| **docs-index.md**（与 `stock-docs/` 同级） | `.cursor/docs-index.md` | 需求/文档索引表 |
|
|
28
|
+
| `req-docs/` | `.cursor/req-docs/` | **需要实现成代码的文档**（技术方案等）；对话中 **`.cursor/req-docs/xxx.md`** + implement-tech-design |
|
|
29
|
+
|
|
30
|
+
**flow2spec init 会创建**：对每个所选 agent，创建 **配置根** 及 **`stock-docs/`**、**`req-docs/`**、**`template/`**、**`rules/`**、**`skills/`** 子目录，并写入模板。
|
|
31
|
+
|
|
32
|
+
**从旧版升级**：若仍使用旧名 **`docs/`**（配置根下），可改名为 **`stock-docs/`**。若曾把 **`req-docs/` 误放在配置根父目录**（与 `.cursor` 同级而非其下），请**整体迁入**当前所用配置根下（如 `.cursor/req-docs/`），再执行 `flow2spec init` 可确保目录存在（已存在则保留其中文件）。
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. 文档路径与链接约定（必守）
|
|
37
|
+
|
|
38
|
+
生成 Rule、Skill、docs-index 时，引用 **`stock-docs/`**（配置根下）内文档的链接写法必须按下列规则，否则在编辑器里打开产物时链接会失效。
|
|
39
|
+
|
|
40
|
+
**与配置根的关系**：下表以 **Cursor**（配置根为 **`.cursor/`**）为例书写路径。若你通过 `flow2spec init claude` 等使用 **`.claude/`**、**`.codex/`** 等作为配置根，则：
|
|
41
|
+
|
|
42
|
+
- **显示路径、sourceDoc、docs-index 文档列**中的 **`.cursor`** 一律改为你的配置根目录名（例如 `sourceDoc: .claude/stock-docs/<文件名>.md`，docs-index 显示列写 `.claude/stock-docs/...`）。
|
|
43
|
+
- **相对链接**规则不变：Rule 内仍用 `../stock-docs/<文件名>.md`，Skill 内仍用 `../../stock-docs/<文件名>.md`，docs-index 的链接 href 仍仅为 `stock-docs/<文件名>.md`（均相对于**该配置根**内部的 `rules/`、`skills/`、`docs-index.md` 位置，与 **`req-docs/`** 无关）。
|
|
44
|
+
|
|
45
|
+
| 写入位置（以 `.cursor/` 为例） | 引用该文档时的写法 |
|
|
46
|
+
| -------------------------------- | ----------------------------------------------------------------------- |
|
|
47
|
+
| **`rules/*.mdc`** | 链接 href 为 `**../stock-docs/<文件名>.md**`（从 rules 到同配置根下 stock-docs 的相对路径） |
|
|
48
|
+
| **`skills/<主题>/SKILL.md`** | 链接 href 为 `**../../stock-docs/<文件名>.md**`（从 skills/xxx 到 stock-docs 的相对路径） |
|
|
49
|
+
| **`docs-index.md`** | 链接 href 为 `**stock-docs/<文件名>.md**`（docs-index 与 `stock-docs/` 同级，故 href 不含 `../`） |
|
|
50
|
+
| **frontmatter 的 sourceDoc** | **`<配置根>/stock-docs/<文件名>.md`**（与 **f2s-ctx-build** 技能入参一致，如 `.cursor/stock-docs/...` 或 `.claude/stock-docs/...`） |
|
|
51
|
+
|
|
52
|
+
**正确示例（配置根为 `.cursor/` 时）：**
|
|
53
|
+
|
|
54
|
+
- Rule 内：`[拼团技术方案设计](../stock-docs/拼团技术方案设计.md)`
|
|
55
|
+
- Skill 内：`[拼团技术方案设计](../../stock-docs/拼团技术方案设计.md)`
|
|
56
|
+
- docs-index 单元格：`[.cursor/stock-docs/拼团技术方案设计.md](stock-docs/拼团技术方案设计.md)`
|
|
57
|
+
- frontmatter：`sourceDoc: .cursor/stock-docs/拼团技术方案设计.md`
|
|
58
|
+
|
|
59
|
+
**若配置根为 `.claude/`**：docs-index 显示列与 sourceDoc 改为 `.claude/stock-docs/<文件名>.md`；链接 href 仍同上三行相对规则。
|
|
60
|
+
|
|
61
|
+
**禁止：**
|
|
62
|
+
|
|
63
|
+
- 在 Rule 内使用 `../../stock-docs/` 或把 **`req-docs/`** 下的技术方案误当作 **stock-docs** 链出目标（会 404 或链错）
|
|
64
|
+
- 在 Skill 内使用 `../stock-docs/` 或上述误链
|
|
65
|
+
- 在 docs-index 的链接 href 中使用 `../stock-docs/` 或裸路径 `.cursor/stock-docs/xxx.md`（应仅为 `stock-docs/<文件名>.md`）
|
|
66
|
+
- 在 sourceDoc 中写 `../stock-docs/xxx.md` 或 **`req-docs/xxx.md`**（生成上下文的 sourceDoc 必须为 **`<配置根>/stock-docs/<文件名>.md`**）
|
|
67
|
+
|
|
68
|
+
**记忆要点**：生成 Rules/Skills 的**源文档**只在 **`stock-docs/`** 下（勿把 **`req-docs/`** 当链出目标）；Rule 内 `../stock-docs/`，Skill 内 `../../stock-docs/`，docs-index 内 `stock-docs/`；sourceDoc 用 **实际配置根** + `/stock-docs/<文件名>.md`。
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 3. 文档产物阶段（原稿 / 初稿 / 终稿）
|
|
73
|
+
|
|
74
|
+
文档在流程中的阶段与命名约定如下，便于区分「未加工 → 待确认 → 可生成上下文」的形态。以下路径均在 **`stock-docs/`** 下（Cursor 下即 `.cursor/stock-docs/`，其他 agent 将 `.cursor` 换为对应目录名）。
|
|
75
|
+
|
|
76
|
+
| 阶段 | 含义 | 典型文件名 / 来源 |
|
|
77
|
+
|------|------|-------------------|
|
|
78
|
+
| **原稿** | 原始材料（如 PDF、未结构化的 MD），未放入本体系时的形态。 | 任意 PDF、`stock-docs/xxx.md`（未规范前） |
|
|
79
|
+
| **初稿** | **f2s-doc-final** 技能从 **PDF 首次**转出、或 **f2s-doc-arch** 技能生成的架构说明，供人工检查与修改。 | `stock-docs/<方案名>_初稿.md`、`<项目名>架构说明_初稿.md` |
|
|
80
|
+
| **终稿** | 初稿或任意 MD 经 **f2s-doc-final** 技能转为《终稿模版》规范格式后的**最终产物**，用于生成 Rules、Skills。 | `stock-docs/<方案名>_终稿.md` |
|
|
81
|
+
|
|
82
|
+
**与命令的对应关系：**
|
|
83
|
+
|
|
84
|
+
- **f2s-doc-final**：传入 PDF → 输出初稿（`_初稿.md`）；传入初稿或 MD → 输出**终稿**（`_终稿.md`）。
|
|
85
|
+
- **f2s-ctx-build**：入参为**终稿或等价存量文档路径**（如 `stock-docs/<方案名>_终稿.md`，即 `.cursor/stock-docs/...` 或 `.claude/stock-docs/...` 等），根据该文档生成 Rules、Skills、索引。生成的 **Rules、Skills 文件名与目录名不带 `_终稿` 后缀**，保持现有约定（如 `rules/<主题>-context.mdc`、`skills/<主题>-context/SKILL.md`）。
|
|
86
|
+
|
|
87
|
+
小结：**文档**可有 原稿 → 初稿（`_初稿`）→ 终稿（`_终稿`）；**Rules、Skills** 由终稿生成，命名不加 `_终稿`。
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 4. 版本管理（sourceDoc 与 generatedAt）
|
|
92
|
+
|
|
93
|
+
每条 Rule、每条 Skill 的 frontmatter 中**必须**包含：
|
|
94
|
+
|
|
95
|
+
- **sourceDoc**：源文档路径，格式 **`<配置根>/stock-docs/<文件名>.md`**（与 **f2s-ctx-build** 技能入参一致，如 `.cursor/stock-docs/xxx.md`、`.claude/stock-docs/xxx.md`）
|
|
96
|
+
- **generatedAt**：本次生成时间，东八区北京时间，ISO 8601，如 `2026-01-28T20:00:00+08:00`
|
|
97
|
+
|
|
98
|
+
用途：**从产物找文档**（看 Rule/Skill 的 `sourceDoc`）、**从文档找产物**（查该配置根下的 docs-index）、**更新**（改文档后对同一路径再执行 **f2s-ctx-build** 技能）。索源与典型用法见 [README-体系与原理 - 版本管理与索源](./README-体系与原理.md#5-版本管理与索源)。
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 5. 模版目录（`template/`）
|
|
103
|
+
|
|
104
|
+
- **包内路径**：Flow2Spec 包内模版目录 **templates/template/**（与 `templates/skills` 等同级），包含 `终稿模版.md`、`后端技术模版.md` 等。
|
|
105
|
+
- **init 注入**：`flow2spec init` 将包内 **templates/template/** 整目录复制到**每个所选配置根**下的 **`template/`**（Cursor 下即 **`.cursor/template/`**，Claude 下即 **`.claude/template/`** 等），例如 `终稿模版.md`、`后端技术模版.md` 位于 **`template/`** 内。
|
|
106
|
+
- **f2s-doc-final**：转换时优先读取 **`template/终稿模版.md`** 作为格式规范；若不存在则使用命令内嵌的模板结构。
|
|
107
|
+
- **生成后端技术文档**：结构范本为 **`template/后端技术模版.md`**；产出技术方案默认写入 **`req-docs/`**。
|
|
108
|
+
- 团队可自行修改**当前所用配置根**下 `template/` 内文件；再次 init 会**覆盖**该目录（与 rules/skills 行为一致）。
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 6. 小结
|
|
113
|
+
|
|
114
|
+
- **配置根**下：`stock-docs/`、**`req-docs/`**、`rules/`、`skills/`、`template/`，索引文件 **docs-index.md**（如 `.cursor/docs-index.md`）。
|
|
115
|
+
- **文档产物阶段**：原稿 → 初稿（`_初稿.md`）→ 终稿（`_终稿.md`）；f2s-doc-final 的最终输出为终稿；f2s-ctx-build 用终稿生成 Rules、Skills，但 Rules、Skills 命名不带 `_终稿`。
|
|
116
|
+
- 文档链接按**写入位置**使用不同相对路径：Rule 用 `../stock-docs/`，Skill 用 `../../stock-docs/`，docs-index 用 `stock-docs/`；**sourceDoc** 与显示路径用 **实际配置根** + `/stock-docs/<文件名>.md`（见 §2）。
|
|
117
|
+
- 版本管理用 **sourceDoc** + **generatedAt**，便于索源与按文档更新产物。
|
|
118
|
+
|
|
119
|
+
**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)（init、目录约定引用、典型流程） | [README-命令说明](./README-命令说明.md)（各命令入参输出、按使用顺序查找） | [README-体系与原理](./README-体系与原理.md)（main 与 docs-index、设计原则）
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/agents.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* flow2spec init 支持的 AI 工具配置目录。
|
|
3
|
+
* 模板以相同子目录结构写入各配置根：rules/、skills/、stock-docs/、req-docs/、template/
|
|
4
|
+
*/
|
|
5
|
+
const AGENTS = {
|
|
6
|
+
cursor: { root: ".cursor", label: "Cursor" },
|
|
7
|
+
claude: { root: ".claude", label: "Claude" },
|
|
8
|
+
codex: { root: ".codex", label: "Codex" },
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
const SUBDIRS = ["stock-docs", "req-docs", "template", "rules", "skills"];
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* @param {string[]} argv init 后的参数，如 []、['cursor']、['cursor','claude']
|
|
15
|
+
* @returns {string[]} 去重后的 agent id 列表
|
|
16
|
+
*/
|
|
17
|
+
function normalizeAgentIds(argv) {
|
|
18
|
+
const list = argv.length ? argv : ["cursor"];
|
|
19
|
+
const seen = new Set();
|
|
20
|
+
const out = [];
|
|
21
|
+
for (const raw of list) {
|
|
22
|
+
const id = String(raw).toLowerCase().replace(/^--/, "");
|
|
23
|
+
if (!AGENTS[id]) {
|
|
24
|
+
const keys = Object.keys(AGENTS).join(", ");
|
|
25
|
+
throw new Error(`未知 agent：${raw}。可选：${keys}`);
|
|
26
|
+
}
|
|
27
|
+
if (!seen.has(id)) {
|
|
28
|
+
seen.add(id);
|
|
29
|
+
out.push(id);
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return out;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
module.exports = { AGENTS, SUBDIRS, normalizeAgentIds };
|
package/lib/init.js
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
const path = require("path");
|
|
2
|
+
const fs = require("fs");
|
|
3
|
+
const { AGENTS, SUBDIRS, normalizeAgentIds } = require("./agents");
|
|
4
|
+
|
|
5
|
+
function ensureDirs(cwd, agentRoot) {
|
|
6
|
+
for (const sub of SUBDIRS) {
|
|
7
|
+
const full = path.join(cwd, agentRoot, sub);
|
|
8
|
+
if (!fs.existsSync(full)) fs.mkdirSync(full, { recursive: true });
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/** 递归复制目录或文件到目标，已存在则覆盖 */
|
|
13
|
+
function copyRecursive(src, dest) {
|
|
14
|
+
const stat = fs.statSync(src);
|
|
15
|
+
if (stat.isDirectory()) {
|
|
16
|
+
if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
|
|
17
|
+
for (const name of fs.readdirSync(src)) {
|
|
18
|
+
copyRecursive(path.join(src, name), path.join(dest, name));
|
|
19
|
+
}
|
|
20
|
+
} else {
|
|
21
|
+
fs.copyFileSync(src, dest);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** 将 templates 下全部内容复制到指定配置根目录（如 .cursor、.claude） */
|
|
26
|
+
function copyTemplatesToAgentRoot(cwd, agentRoot) {
|
|
27
|
+
const templatesDir = path.join(__dirname, "..", "templates");
|
|
28
|
+
const destRoot = path.join(cwd, agentRoot);
|
|
29
|
+
|
|
30
|
+
const rulesSrc = path.join(templatesDir, "rules");
|
|
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
|
+
}
|
|
37
|
+
|
|
38
|
+
const skillsSrc = path.join(templatesDir, "skills");
|
|
39
|
+
const skillsDest = path.join(destRoot, "skills");
|
|
40
|
+
if (fs.existsSync(skillsSrc)) {
|
|
41
|
+
for (const name of fs.readdirSync(skillsSrc)) {
|
|
42
|
+
copyRecursive(path.join(skillsSrc, name), path.join(skillsDest, name));
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const templateSrc = path.join(templatesDir, "template");
|
|
47
|
+
const templateDest = path.join(destRoot, "template");
|
|
48
|
+
if (fs.existsSync(templateSrc)) {
|
|
49
|
+
ensureDirs(cwd, agentRoot);
|
|
50
|
+
copyRecursive(templateSrc, templateDest);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* @param {string} cwd
|
|
56
|
+
* @param {string[]} [agentIds] 不传则仅 cursor
|
|
57
|
+
*/
|
|
58
|
+
async function run(cwd, agentIds) {
|
|
59
|
+
const ids = normalizeAgentIds(agentIds || []);
|
|
60
|
+
for (const id of ids) {
|
|
61
|
+
const root = AGENTS[id].root;
|
|
62
|
+
ensureDirs(cwd, root);
|
|
63
|
+
copyTemplatesToAgentRoot(cwd, root);
|
|
64
|
+
}
|
|
65
|
+
return ids;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
module.exports = run;
|
package/package.json
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@double-codeing/flow2spec",
|
|
3
|
+
"version": "2.2.0",
|
|
4
|
+
"description": "flow2spec init：落盘 .cursor/.claude/.codex 等配置根的 rules、skills、stock-docs/req-docs，文档驱动、f2s 可写回知识库工作流。",
|
|
5
|
+
"homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/Lands-1203/Flow2Spec.git"
|
|
9
|
+
},
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://github.com/Lands-1203/Flow2Spec/issues"
|
|
12
|
+
},
|
|
13
|
+
"main": "./cli.js",
|
|
14
|
+
"bin": {
|
|
15
|
+
"flow2spec": "cli.js"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"cli.js",
|
|
19
|
+
"lib",
|
|
20
|
+
"templates",
|
|
21
|
+
"README.md",
|
|
22
|
+
"docs"
|
|
23
|
+
],
|
|
24
|
+
"publishConfig": {
|
|
25
|
+
"access": "public",
|
|
26
|
+
"registry": "https://registry.npmjs.org/"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"test": "node cli.js --help",
|
|
30
|
+
"prepublishOnly": "node cli.js --help",
|
|
31
|
+
"pack:check": "npm pack --dry-run"
|
|
32
|
+
},
|
|
33
|
+
"keywords": [
|
|
34
|
+
"flow2spec",
|
|
35
|
+
"cursor",
|
|
36
|
+
"cursor-rules",
|
|
37
|
+
"agent-skills",
|
|
38
|
+
"claude",
|
|
39
|
+
"codex",
|
|
40
|
+
"ai-workflow",
|
|
41
|
+
"project-context",
|
|
42
|
+
"knowledge-base",
|
|
43
|
+
"documentation",
|
|
44
|
+
"rules",
|
|
45
|
+
"skills",
|
|
46
|
+
"stock-docs",
|
|
47
|
+
"req-docs",
|
|
48
|
+
"context-engineering",
|
|
49
|
+
"f2s"
|
|
50
|
+
],
|
|
51
|
+
"author": "兰大神 <550947002@qq.com>",
|
|
52
|
+
"contributors": [
|
|
53
|
+
"七七是只猫 <292761894@qq.com>"
|
|
54
|
+
],
|
|
55
|
+
"license": "ISC",
|
|
56
|
+
"engines": {
|
|
57
|
+
"node": ">=16"
|
|
58
|
+
}
|
|
59
|
+
}
|