@double-codeing/flow2spec 3.0.14 → 3.0.15

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.
Files changed (36) hide show
  1. package/LICENSE +21 -0
  2. package/README.en.md +15 -15
  3. package/README.md +15 -15
  4. package/cli.js +2 -2
  5. package/docs/.mermaid-cache.json +49 -0
  6. package/docs/.sync-mapping.json +59 -0
  7. package/docs/en/README.md +12 -0
  8. package/docs/{architecture.en.md → en/architecture.md} +57 -20
  9. package/docs/{commands-reference.en.md → en/commands-reference.md} +14 -16
  10. package/docs/{design-principles.en.md → en/design-principles.md} +26 -7
  11. package/docs/{directory-conventions.en.md → en/directory-conventions.md} +18 -13
  12. package/docs/{usage-guide.en.md → en/usage-guide.md} +23 -35
  13. package/docs/{usage-scenarios.en.md → en/usage-scenarios.md} +8 -34
  14. package/docs/{README- → }/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md +60 -19
  15. 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 +9 -33
  16. package/docs/{Flow2Spec → }/344/275/277/347/224/250/350/257/264/346/230/216.md +24 -34
  17. package/docs/{README- → }/345/221/275/344/273/244/350/257/264/346/230/216.md +15 -15
  18. 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 +19 -12
  19. package/docs/{Flow2Spec- → }/350/256/276/350/256/241/350/257/264/346/230/216.md +69 -6
  20. package/package.json +1 -1
  21. package/templates/knowledge/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md +1 -1
  22. package/templates/knowledge/template//347/273/210/347/250/277/346/250/241/347/211/210.md +1 -2
  23. package/templates/knowledge/template//351/241/271/347/233/256/351/207/214/347/250/213/347/242/221/346/250/241/347/211/210.md +1 -1
  24. package/templates/knowledge/topics/f2s-req-plan.md +1 -1
  25. package/templates/knowledge/topics/f2s-task.md +1 -1
  26. package/templates/rules/f2s-flow2spec-unified-entry.mdc +1 -0
  27. package/templates/rules/f2s-stock-docs-vs-req-docs.mdc +1 -1
  28. package/templates/rules/f2s-task.mdc +5 -5
  29. package/templates/skills/f2s-ctx-build/SKILL.md +3 -3
  30. package/templates/skills/f2s-ctx-rm/SKILL.md +1 -1
  31. package/templates/skills/f2s-doc-add/SKILL.md +1 -1
  32. package/templates/skills/f2s-doc-milestone/SKILL.md +1 -1
  33. package/templates/skills/f2s-git-commit/SKILL.md +1 -1
  34. package/templates/skills/f2s-kb-fix/SKILL.md +1 -1
  35. package/templates/skills/f2s-kb-sync/SKILL.md +1 -1
  36. package/templates/skills/stock-docs-vs-req-docs/SKILL.md +1 -1
package/docs/{Flow2Spec- → }/350/256/276/350/256/241/350/257/264/346/230/216.md RENAMED
@@ -1,5 +1,7 @@
1
1
  # Flow2Spec 设计说明
2
2
 
3
+ [English](./en/design-principles.md)
4
+
3
5
  ## 解决的问题
4
6
 
5
7
  ```
@@ -19,6 +21,67 @@
19
21
 
20
22
  ## 核心设计
21
23
 
24
+ ### 0. Memory Coding 与仓内四环
25
+
26
+ **Memory Coding**：把必须长期记住的上下文**编码进可提交仓库**（可 PR、可 review），而不是押在模型 Memory 或聊天里。
27
+
28
+ 仓内 **四环**（规则环与技能环分列，勿合并为「规则+技能」）：
29
+
30
+ | 环 | 落点 | 职责 |
31
+ | --- | --- | --- |
32
+ | 知识环 | `.Knowledge/` | 路由 + 主题 + 存量/需求文档 |
33
+ | 任务环 | `.task/` | 跨会话续作、用户代办 |
34
+ | 规则环 | 各工具 `rules` / `AGENTS.md` | 怎么读、怎么做（缺口闸门、路由顺序） |
35
+ | 技能环 | `f2s-*` / `skills/` | 维护知识、触发 feat/fix/sync 等 |
36
+
37
+ ```mermaid
38
+ graph TB
39
+ subgraph MC["Memory Coding · 仓内四环"]
40
+ KR["知识环 .Knowledge/"]
41
+ TR["任务环 .task/"]
42
+ RR["规则环 rules"]
43
+ SR["技能环 f2s-*"]
44
+ end
45
+ SR -->|"维护 ↑"| KR
46
+ RR -->|"读与做 ↓"| KR
47
+ TR -.->|"并列，不在 .Knowledge 内"| KR
48
+ ```
49
+
50
+ Flow2Spec 提供的是 **Memory Coding 的落盘与维护闭环**，不是「又一个 RAG 知识库」。
51
+
52
+ ### 0.1 知识环：多层记忆结构
53
+
54
+ 知识环内部是 **横读 + 纵链** 的多层结构（与下文「渐进式路由」「topicDependencies」对应）：
55
+
56
+ ```mermaid
57
+ graph TB
58
+ subgraph H["横读 · 渐进式收窄"]
59
+ L0["L0 manifest-routing"]
60
+ L1["L1 matchers 分片"]
61
+ L2["L2 topics 摘要"]
62
+ L3["L3 stock-docs / req-docs"]
63
+ L0 --> L1 --> L2 --> L3
64
+ end
65
+ subgraph V["纵链 · topicDependencies"]
66
+ T1["通用约定"]
67
+ T2["子域边界"]
68
+ T3["端上白名单"]
69
+ T4["本域细则"]
70
+ T1 --> T2 --> T3 --> T4
71
+ end
72
+ L2 --- V
73
+ ```
74
+
75
+ | 层级 | 路径 | 作用 |
76
+ | --- | --- | --- |
77
+ | L0 | `manifest-routing.json` | 机读路由、依赖声明 |
78
+ | L1 | `matchers/*.json` | 关键词命中，**match** 只读一片 |
79
+ | L2 | `topics/*.md` | 硬约束摘要；**expand** 拉依赖 |
80
+ | L3 | `stock-docs/`、`req-docs/` | 长文档，按需下钻 |
81
+ | 纵链 | `topicDependencies` | 主题级前置，所有任务共享 |
82
+
83
+ 读取流水线：`match → expand → verify → act`（详见 [体系与原理 §4](./体系与原理.md)）。
84
+
22
85
  ### 1. 知识与规则分离
23
86
 
24
87
  ```mermaid
@@ -78,7 +141,7 @@ graph LR
78
141
  CMT -->|"未入库则提醒\n-> kb-sync/kb-feat"| K
79
142
 
80
143
  D1["架构文档"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
81
- D2["PDF 方案"] -->|f2s-doc-pdf| FIN
144
+ D2["PDF/初稿"] -->|f2s-doc-final| FIN
82
145
  FIN --> CTX["f2s-ctx-build"] --> K
83
146
 
84
147
  OLD["存量代码/文档"] -->|f2s-doc-add| K
@@ -446,7 +509,7 @@ f2s-kb-sync 三种输入方式
446
509
  | **Codex `AGENTS.md` + `renderProjectConfigBlock`** | 顶部 **Read** 硬约束 + **init 快照表**（与磁盘不一致时以 Read 为准）。 |
447
510
  | **知识库 `config-precheck` 主题** | 路由命中时只提供**摘要**与链向 Codex 长文，**不**替代 Read JSON。 |
448
511
 
449
- **权威仍为**项目根 JSON 的 **Read** 结果；各层为提示而非第二份真值源。操作侧完整表格与路径见 **[Flow2Spec使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./Flow2Spec使用说明.md)**；口述节奏见 **[Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)**。
512
+ **权威仍为**项目根 JSON 的 **Read** 结果；各层为提示而非第二份真值源。操作侧完整表格与路径见 **[使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./使用说明.md)**；口述节奏见 **[Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)**。
450
513
 
451
514
  #### 6. 技能不复述统一入口规则，只引用
452
515
 
@@ -573,9 +636,9 @@ flow2spec.config.json
573
636
 
574
637
  ## 相关文档
575
638
 
576
- - [Flow2Spec使用说明](./Flow2Spec使用说明.md)
577
- - [README-命令说明](./README-命令说明.md)
578
- - [README-体系与原理](./README-体系与原理.md)
579
- - [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
639
+ - [使用说明](./使用说明.md)
640
+ - [命令说明](./命令说明.md)
641
+ - [体系与原理](./体系与原理.md)
642
+ - [使用案例-模拟对话](./使用案例-模拟对话.md)
580
643
  - [Flow2Spec-演讲稿](./Flow2Spec-演讲稿.md)
581
644
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@double-codeing/flow2spec",
3
- "version": "3.0.14",
3
+ "version": "3.0.15",
4
4
  "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
5
5
  "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
6
6
  "repository": {
package/templates/knowledge/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md CHANGED
@@ -30,7 +30,7 @@
30
30
  ## 4. 外部对接和内部调用
31
31
 
32
32
  - 二级标题：`## 外部对接和内部调用`
33
- - 简要列出：依赖的外部 HTTP/RPC/券台/订单等；本服务内部会调用的模块或方法（不必展开到每个参数）。
33
+ - 简要列出：依赖的外部 HTTP/RPC/消息队列等；本服务内部会调用的模块或方法（不必展开到每个参数）。
34
34
 
35
35
  ---
36
36
 
package/templates/knowledge/template//347/273/210/347/250/277/346/250/241/347/211/210.md CHANGED
@@ -1,5 +1,4 @@
1
- > **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/stock-docs/`。
2
- > 本模板唯一来源为 `templates/knowledge/template/终稿模版.md`。
1
+ > **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `.Knowledge/template/` 与 `.Knowledge/stock-docs/`。
3
2
 
4
3
  # 终稿概述模版
5
4
 
package/templates/knowledge/template//351/241/271/347/233/256/351/207/214/347/250/213/347/242/221/346/250/241/347/211/210.md CHANGED
@@ -1,4 +1,4 @@
1
- > **主口径**：模板在 `templates/knowledge/template/项目里程碑模版.md`；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。
1
+ > **主口径**：模板在 `.Knowledge/template/项目里程碑模版.md`（由 `flow2spec init` 落地）；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。
2
2
  > **执行 `f2s-doc-milestone`**：结构以本模版为准；内容仅来自 **req-docs、git log、.task** 与知识库主题，禁止臆造。
3
3
  > **阶段**：Mx **仅**功能/能力变更；**不得**单独成阶段的联调、测试、验收或纯环境运维；工程性改动并入对应功能阶段。
4
4
 
package/templates/knowledge/topics/f2s-req-plan.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。
4
4
  > **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。
5
- > 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/<任务清单说明>.md)（可选）。
5
+ > 设计背景（可选）：[任务清单与变更追踪](../stock-docs/<任务清单说明>.md)。
6
6
 
7
7
  ## 依赖
8
8
 
package/templates/knowledge/topics/f2s-task.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # f2s-task（路由摘要）
2
2
 
3
3
  > 长文见配置根 **`rules/f2s-task.*`**。
4
- > 体系化设计说明（两种模式、目录、`todo.json`）：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。
4
+ > 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。
5
5
 
6
6
  ## 作用
7
7
 
package/templates/rules/f2s-flow2spec-unified-entry.mdc CHANGED
@@ -81,6 +81,7 @@ alwaysApply: true
81
81
 
82
82
  ## 禁止项
83
83
 
84
+ - **`templates/` 可下发约束**（经 `init` 会克隆到任意业务仓）：技能/规则/知识模板正文中的示例须**中性**——勿写特定业务域名称、单一组织 npm 包名、仅 Flow2Spec 产品仓存在的 `docs/` 路径；用 `<能力>`、`src/<模块>/` 等占位。
84
85
  - 使用 `git worktree` 或隔离目录跑子任务后，**禁止**在未 `git worktree remove` / 未交接删除命令的情况下结束会话（见上文「Git worktree 与子任务工作目录卫生」）。
85
86
  - 未查看 `.Knowledge/manifest-routing.json` 前，禁止进行全仓无范围扫描；`.Knowledge/index.md` 在需确认主题语义时再读，禁止与 manifest 交替重复读取以代替决策。
86
87
  - 禁止把 `stock-docs` 作为直接编码输入文档；按方案实现应使用 `req-docs`。
package/templates/rules/f2s-stock-docs-vs-req-docs.mdc CHANGED
@@ -13,4 +13,4 @@ alwaysApply: false
13
13
  - **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-ctx-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-doc-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。
14
14
  - **`.Knowledge/req-docs/`**：需求澄清、技术方案（前后端/数据/任务等）、`f2s-doc-pdf` 输出的「按方案实现」MD；`implement-tech-design` 的触发范围为 `.Knowledge/req-docs/**/*.md`。
15
15
 
16
- 完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。
16
+ 完整约定见本规则与 **`skills/stock-docs-vs-req-docs/SKILL.md`**；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。
package/templates/rules/f2s-task.mdc CHANGED
@@ -138,12 +138,12 @@ alwaysApply: true
138
138
  # <任务名> 上下文
139
139
 
140
140
  ## 涉及文件
141
- - `src/payment/callback.js`
142
- - `src/payment/retry.js`
141
+ - `src/<模块>/callback.js`
142
+ - `src/<模块>/retry.js`
143
143
 
144
144
  ## 相关资料
145
- - `.Knowledge/req-docs/payment-spec.md`
146
- - `.Knowledge/stock-docs/payment-arch.md`
145
+ - `.Knowledge/req-docs/<能力>-spec.md`
146
+ - `.Knowledge/stock-docs/<能力>-arch.md`
147
147
 
148
148
  ## 用户代办清单
149
149
  - 见同目录 `user-todos.md`（须用户执行的项统一写在该文件，勿仅在对话中罗列）
@@ -175,7 +175,7 @@ alwaysApply: true
175
175
 
176
176
  ## 2026-05-09
177
177
 
178
- - [ ] 在预发 MySQL 执行：`.Knowledge/req-docs/xxx.sql`（先备份）
178
+ - [ ] 在目标环境执行：`.Knowledge/req-docs/xxx.sql`（先备份）
179
179
  - [ ] 在配置中心打开功能开关 `feature.foo.enabled`
180
180
 
181
181
  ## 2026-05-10
package/templates/skills/f2s-ctx-build/SKILL.md CHANGED
@@ -89,10 +89,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
89
89
 
90
90
  ## 复杂场景示例
91
91
 
92
- 用户输入：`f2s-ctx-build .Knowledge/stock-docs/支付回调改造_终稿.md`，且现有 `topics/payment.md` 已存在。
92
+ 用户输入：`f2s-ctx-build .Knowledge/stock-docs/回调改造_终稿.md`，且现有 `topics/callback.md` 已存在。
93
93
 
94
- - 若新文档与现有 `payment` 主题高度重合：原位更新 `topics/payment.md`，不要新建 `payment-v2.md`。
95
- - 若新文档新增“重试补偿”子能力：可新增 `topics/payment-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `payment-retry -> payment`。
94
+ - 若新文档与现有 `callback` 主题高度重合：原位更新 `topics/callback.md`，不要新建 `callback-v2.md`。
95
+ - 若新文档新增「重试补偿」子能力：可新增 `topics/callback-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `callback-retry -> callback`。
96
96
  - 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
97
97
 
98
98
  ## 完成后自检
package/templates/skills/f2s-ctx-rm/SKILL.md CHANGED
@@ -39,7 +39,7 @@ description: 删除某 stock-docs 文档对应的知识主题与索引映射；
39
39
 
40
40
  ## 复杂场景示例
41
41
 
42
- 用户输入文件名片段“支付”，匹配到 2 个主题文档。
42
+ 用户输入文件名片段「回调」，匹配到 2 个主题文档。
43
43
 
44
44
  - 先列出两个候选并要求用户确认删除范围，避免误删。
45
45
  - 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。
package/templates/skills/f2s-doc-add/SKILL.md CHANGED
@@ -88,7 +88,7 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
88
88
  用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。
89
89
 
90
90
  - 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
91
- - 若发现已有 `.Knowledge/stock-docs/支付能力_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
91
+ - 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
92
92
  - 用户要求“先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
93
93
 
94
94
  ## 约束
package/templates/skills/f2s-doc-milestone/SKILL.md CHANGED
@@ -70,7 +70,7 @@ description: 据 req-docs、git log、.task 与知识库主题语义生成里程
70
70
  | 用户意图 | 示例 | 落盘文件名 |
71
71
  | --- | --- | --- |
72
72
  | 整个项目（默认） | 不传 / `整个项目` / `全项目` | `项目里程碑.md` |
73
- | 某一需求或能力 | `支付回调改造` / `登录模块` | `<简述>里程碑.md` |
73
+ | 某一需求或能力 | `回调改造` / `登录模块` | `<简述>里程碑.md` |
74
74
 
75
75
  **文件名规则**：后缀 `里程碑.md`；整个项目 → 前缀 `项目`；单一需求 → 语义或 req 标题简述（≤ 20 字）。
76
76
 
package/templates/skills/f2s-git-commit/SKILL.md CHANGED
@@ -46,7 +46,7 @@ git diff HEAD
46
46
 
47
47
  **存在时执行覆盖检查：**
48
48
 
49
- 1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（如：支付、订单、用户认证等）。
49
+ 1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（以仓库内目录/包名为准，勿臆测未出现的业务名）。
50
50
  2. 读取 `.Knowledge/topics/` 目录列表与 `.Knowledge/stock-docs/` 目录列表。
51
51
  3. 对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。
52
52
  4. 得出结论：**已覆盖 / 部分覆盖 / 未覆盖**。
package/templates/skills/f2s-kb-fix/SKILL.md CHANGED
@@ -59,7 +59,7 @@ description: 根据用户指出的实现或规则错误修正代码，并默认
59
59
 
60
60
  ## 复杂场景示例
61
61
 
62
- 用户指出"订单回调幂等实现错误"，但未给明确文件范围。
62
+ 用户指出「某回调接口幂等实现错误」，但未给明确文件范围。
63
63
 
64
64
  - 先按最小可行范围修复已定位的回调处理链路，并在摘要中说明"可继续扩展全仓同类修复"。
65
65
  - 同步更新 `topics` 中幂等规则段落，避免后续再次生成错误实现。
package/templates/skills/f2s-kb-sync/SKILL.md CHANGED
@@ -88,7 +88,7 @@ description: 可显式给出能力或零输入推断；先输出知识库更新
88
88
 
89
89
  用户仅说“/f2s-kb-sync 同步一下”，未给能力清单。
90
90
 
91
- - 步骤 1 先做最小推断（例如支付、订单两个高频能力），并给出推断依据。
91
+ - 步骤 1 先做最小推断（例如从 `git diff` / 目录名归纳 1～2 个能力域），并给出推断依据。
92
92
  - 步骤 2 必须输出大纲并等待“确认”；未确认前禁止写入任何 `.Knowledge` 文件。
93
93
  - 用户确认后只执行大纲内条目；若用户中途缩小范围，未执行项写入收尾摘要。
94
94
 
package/templates/skills/stock-docs-vs-req-docs/SKILL.md CHANGED
@@ -32,4 +32,4 @@ description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-doc
32
32
 
33
33
  ## 详细约定
34
34
 
35
- 见 Flow2Spec 包内 **`docs/README-目录与路径约定.md`**；技能顺序与 **f2s-doc-arch** / **f2s-doc-add** 见 **`docs/README-命令说明.md`**。具体步骤以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**）为准。
35
+ 以本技能对照表与配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**、**f2s-doc-arch**）为准；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。