@double-codeing/flow2spec 2.2.2 → 3.0.7

package/docs/Flow2Spec-/350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -0,0 +1,574 @@
+# Flow2Spec 设计说明
+
+## 解决的问题
+
+```
+❌ 现状                          ✅ Flow2Spec 之后
+
+架构约定  ──┐                    .Knowledge/
+技术方案  ──┼──► 散落            ├── manifest-routing.json
+模块边界  ──┤    无结构           ├── matchers/
+团队经验  ──┘    每次重新解释     ├── topics/
+                                 ├── stock-docs/
+                                 └── req-docs/
+
+                                 AI 随时能读懂项目
+```
+
+---
+
+## 核心设计
+
+### 1. 知识与规则分离
+
+```mermaid
+graph LR
+    subgraph K[".Knowledge/  知识层"]
+        K1[架构说明]
+        K2[技术方案]
+        K3[路由索引]
+    end
+
+    subgraph R["配置根  执行层"]
+        R1[.cursor/rules/]
+        R2[.claude/rules/]
+        R3[.codex/AGENTS.md]
+    end
+
+    K -->|知识输入| AI[AI 工具]
+    R -->|规则约束| AI
+
+    note1["知识随项目迭代"] -.-> K
+    note2["规则随工具升级"] -.-> R
+```
+
+
+
+### 2. 渐进式路由
+
+```mermaid
+graph LR
+    T[任务] --> M[manifest-routing\n读路由表]
+    M -->|关键词匹配| MT[matchers/xxx.json\n只读这一个分片]
+    MT -->|命中| TP[topics/xxx.md]
+    TP --> V{缺口检查}
+    V -->|通过| ACT[执行]
+    V -->|不足| Q[向用户澄清]
+    M -->|未命中| FB[fallback-triage\n结构化分诊]
+```
+
+
+
+### 3. 技能维护闭环
+
+```mermaid
+graph LR
+    K[".Knowledge/"] --> AI["下次会话\n的 AI"]
+    AI --> C["代码\n变更"]
+
+    C -->|"修复 Bug"| FIX["f2s-kb-fix"] --> K
+    C -->|"新增能力"| FEAT["f2s-kb-feat"] --> K
+    C -->|"会话结束"| SYNC["f2s-kb-sync"] --> K
+    C -->|"提交代码"| CMT["f2s-git-commit\n收口检查"]
+    CMT -->|"未入库则提醒\n→ kb-sync/kb-feat"| K
+
+    D1["架构文档"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
+    D2["PDF 方案"] -->|f2s-doc-pdf| FIN
+    FIN --> CTX["f2s-ctx-build"] --> K
+
+    OLD["存量代码/文档"] -->|f2s-doc-add| K
+
+    NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
+    BE --> IMPL["implement-tech-design"] -->|f2s-kb-feat| K
+
+    GIT["Git 合并后"] -->|f2s-kb-merge| K
+```
+
+七条入口  ·  `f2s-git-commit` 是提交时的知识纪律收口  ·  `.Knowledge/` 是唯一汇聚点  ·  知识驱动 AI，AI 驱动下轮开发
+
+
+
+### 4. 任务清单与跨会话续作
+
+```mermaid
+graph LR
+    SKILL["f2s-kb-feat / f2s-kb-fix\nimplement-tech-design"] -->|"changeTracking: true"| TJ[".task/active/\ntask.md · todo.json"]
+    RP["f2s-req-plan\n（始终创建）"] --> TJ
+
+    TJ --> NS[新会话首条消息]
+    NS -->|关键词匹配| LD["加载剩余 checklist\n+ linkedSkill 上下文"]
+    LD --> RS[按原技能约束继续]
+```
+
+任务不因会话结束丢失  ·  关键词自动续作，无需重新说明上下文  ·  技能约束完整恢复
+
+---
+
+## 设计亮点
+
+### 一、路由与上下文加载
+
+#### 1. matchers 分片，不嵌入 manifest
+
+```
+❌ 嵌入 manifest                  ✅ 独立分片
+
+manifest.json (每次全读)          manifest-routing.json
+├── task1: keywords:[...]    →    ├── task1 → m-order.json ──► 只读这一个
+├── task2: keywords:[...]         ├── task2 → m-payment.json
+└── task3: keywords:[...]         └── task3 → m-refund.json
+
+                                  更新关键词不动路由结构
+                                  每次路由 token 成本固定
+```
+
+#### 2. topicDependencies：依赖挂在主题上
+
+```
+❌ 挂在任务级                     ✅ 挂在主题级
+
+taskA → [dep, main]               topicDependencies:
+taskB → [main]      ← 漏写了        main: [dep]
+taskC → [main]      ← 漏写了
+                                  任何路径加载 main
+新增任务时漏写 → 静默失效          都自动带上前置依赖
+```
+
+#### 3. topic 只存摘要，规则文件存全文
+
+```
+.Knowledge/topics/implement-tech-design.md     ← 轻量，路由时加载
+┌──────────────────────────────────────────┐
+│ 主题 id、路径约定、下一步指针             │
+│ ~100 行                                   │
+└──────────────────────────────────────────┘
+             ↓ 命中后才读
+.claude/rules/f2s-implement-tech-design.md     ← 全文，执行时加载
+┌──────────────────────────────────────────┐
+│ 完整执行约束、强制步骤、禁止项、边界说明  │
+│ ~500 行                                   │
+└──────────────────────────────────────────┘
+```
+
+路由层保持轻量  ·  执行细节按需加载  ·  两者独立更新
+
+#### 4. 禁止全量扫描是硬约束
+
+```
+读取顺序（必须）
+
+  1. manifest-routing.json   ← 先看路由表
+  2. matchers/xxx.json       ← 只读命中分片
+  3. index.md                ← 按需，确认语义
+  4. stock-docs / req-docs   ← 按需，补充背景
+  5. 业务源码                ← 最后手段
+
+  ❌ 未读 manifest 前，禁止全仓无范围扫描
+  ❌ 同一任务线内，manifest 已读则不重复全文读取
+  ❌ index.md 禁止与 manifest 交替"刷清单"代替决策
+```
+
+#### 5. 技能触发词写在 description 字段
+
+```yaml
+name: f2s-kb-sync
+description: >
+  同步已实现能力到知识库。
+  触发词：f2s-kb-sync、全局同步、知识库同步、已实现能力
+```
+
+```
+用户输入 → Agent 扫 description 做语义匹配 → 触发对应技能
+```
+
+触发词在 description 里  ·  不在正文里  ·  命中率更高  ·  双语覆盖减少漏触发
+
+---
+
+### 二、知识结构
+
+#### 1. stock-docs vs req-docs 语义禁止
+
+```
+stock-docs/                        req-docs/
+架构说明 / 终稿                     需求 / 技术方案
+
+     ↓ 用于                              ↓ 用于
+知识路由 / 背景参考              驱动编码实现
+
+     ✅ 可以读                           ✅ 可以读
+     ❌ 不能作为编码输入                  ✅ implement-tech-design 的输入
+```
+
+防止：用过期参考文档驱动实现 → 代码与最新方案脱节
+
+#### 2. init 幂等
+
+```
+flow2spec init  可以安全重跑
+
+        ✅  做                         ❌  不做
+┌─────────────────────┐      ┌─────────────────────┐
+│ 补齐缺失目录和模板   │      │ 写业务文档内容       │
+│ 落盘 rules/skills   │      │ 更新路由关键词       │
+│ 包级结构对齐        │      │ 覆盖已有知识内容     │
+└─────────────────────┘      └─────────────────────┘
+
+结构操作  ≠  业务语义         两者职责不交叉
+```
+
+#### 3. 知识版本化
+
+```
+git log .Knowledge/
+
+  a3f1c2  f2s-kb-feat: 新增退款状态机路由
+  b7e9d1  f2s-kb-fix: 修正 RestTemplate 注入约定
+  c2a8f0  f2s-ctx-build: 订单服务架构说明入库
+  d5b3e9  f2s-kb-sync: 沉淀支付重试队列设计
+
+  代码变更  +  知识变更  →  同一 commit 或相邻 commit
+```
+
+知识有版本  ·  可 review  ·  可回溯  ·  可 blame
+
+#### 4. 禁止历史否定堆砌
+
+```
+❌ 错误写法（知识库越来越臃肿）        ✅ 正确写法（只保留当前成立的表述）
+
+  RestTemplate 约定（更新于 2026-05）    RestTemplate 必须通过 Bean 注入
+  ~~原错误地使用 new RestTemplate()~~    禁止直接 new RestTemplate()
+  → 不再与直接实例化有关
+  → 原写法已废弃，现改为 Bean 注入
+```
+
+每次修复原位改写  ·  不叠加历史  ·  知识库永远只描述现在
+
+---
+
+### 三、执行约束
+
+#### 1. 强制步骤是约束，不是建议
+
+```
+implement-tech-design 执行流
+
+  输入标准化
+       ↓
+  读取方案与上下文
+       ↓
+  ★ 输出实现任务列表    ← 不可跳过
+       ↓
+  ★ 实现前提问确认      ← 不可跳过
+       ↓
+  按任务列表实现
+       ↓
+  输出待完成清单与提醒   ← 不可跳过
+```
+
+建议 → 可以被跳过  ·  约束 → 必须明确处理才能继续
+
+#### 2. fallback 本身是有程序的 topic
+
+```mermaid
+graph TD
+    F[进入 fallback-triage] --> S1{路由是否命中?}
+    S1 -->|已命中但上下文不足| EXP[展开依赖主题\n补齐后继续]
+    S1 -->|未命中| Q[询问用户:\n这个领域文档是否已录入?]
+    Q -->|是| HINT[路由词条缺失\n建议补路由]
+    Q -->|否| CHOICE[下钻源码\n或补充 req-docs]
+    Q -->|不确定| STOP[停止执行\n等待明确指令]
+```
+
+
+
+未命中 ≠ 静默失败  ·  降级本身有明确程序
+
+#### 3. manifest / index 写权硬约束
+
+```
+子 agent 可以落盘的               子 agent 不得触碰
+────────────────────             ────────────────────
+代码实现文件                      manifest-routing.json  ← 恒主 agent 落盘
+stock-docs 内容文件               .Knowledge/index.md    ← 恒主 agent 落盘
+topics 内容文件（diff 模式）
+matchers/*.json（diff 模式）
+```
+
+多个子 agent 并行时，共享状态文件由主 agent 单点写入，防止并发冲突
+
+#### 4. 文档改动 vs 代码改动，拆分策略不同
+
+```
+代码子包                          文档子包
+────────────────────             ────────────────────
+✅ 可下放子 agent 执行            ❌ 默认不拆，主 agent 直接写
+✅ 子 agent 直接落盘              若确需外包 →
+                                  子侧只输出 before/after diff 片段
+                                  主 agent 审核后合并落盘
+                                  ❌ 整文件重写严格禁止
+```
+
+原因：文档需要保证「现行真值覆盖 / 文风一致 / 禁历史否定堆砌」  ·  要求写的人看到全文上下文
+
+#### 5. 任务清单与跨会话续作
+
+```
+关键词自动续作示例
+
+  新会话第一句："支付回调还有个问题"
+       ↓
+  匹配 todo.json 各条目 keywords
+       ↓
+  命中 { name: "payment_callback_fix", keywords: ["支付", "回调"] }
+       ↓
+  加载 task.md（展示剩余步骤）
+  linkedSkill = "f2s-kb-fix" → 加载 SKILL.md
+       ↓
+  技能的落盘规则 / 文风要求 / 自检清单全部恢复
+  用户无需重新描述上下文，直接继续
+
+  ✅ 不需要说"继续上次任务"
+  ✅ 技能约束完整恢复，与首次调用一致
+```
+
+```
+todo.json 写权约束
+
+  主 agent ── 读 / 写 todo.json   ✅
+  子 agent ── 读 todo.json        ✅
+  子 agent ── 写 todo.json        ❌
+
+  原因：多子 agent 并行落盘时，并发写会导致条目互相覆盖
+```
+
+生命周期由技能驱动  ·  关键词路由实现跨会话自动续作  ·  linkedSkill 保证技能约束完整恢复
+
+---
+
+### 四、Agent 编排
+
+#### 1. subAgent × switchAgentVerification 正交
+
+```
+                    switchAgentVerification
+                   false            true
+     subAgent  ┌────────────┬─────────────────┐
+     true →    │ 并行执行    │ 并行执行         │
+               │ 落盘侧自验  │ 子落盘→主验      │
+               │            │ 主落盘→子验      │
+               ├────────────┼─────────────────┤
+     false →   │ 顺序执行   │ 顺序执行         │
+               │ 主 agent   │ 主 agent 自验    │
+               │ 自验       │（无子侧可交叉）   │
+               └────────────┴─────────────────┘
+```
+
+两个维度正交  ·  独立配置  ·  默认左下角
+
+#### 2. 确认权不可下放子 agent
+
+```mermaid
+graph LR
+    S1[步骤1: 素材汇总] -->|subAgent=true 可并行| SUB[子 agent]
+    SUB -->|只读，不落盘| S2
+
+    S2[步骤2: 输出大纲\n用户确认] -->|必须主 agent| USER[用户]
+    USER -->|确认| S3
+
+    S3[步骤3: 落盘] -->|subAgent=true 可并行| SUB2[子 agent]
+```
+
+
+
+用户对话只经过主 agent  ·  确认决策不可绕过用户  ·  子 agent 只做执行不做决策
+
+#### 3. 技能可覆盖全局 subAgent 配置
+
+```
+flow2spec.config.json        f2s-req-clarify SKILL.md
+subAgent: true               本技能默认不拆子：
+                             无论 subAgent 真值，
+                             澄清流程全程在主会话
+
+原因：需求澄清强依赖连续同会话追问
+     拆子会断上下文，导致澄清质量下降
+```
+
+全局配置是允许拆的上限  ·  技能自己判断是否适合拆  ·  配置 true 不等于一定拆
+
+#### 4. f2s-kb-sync 先出大纲，确认后再写
+
+```mermaid
+graph LR
+    T[触发 f2s-kb-sync] --> O[输出更新大纲]
+    O --> U{用户确认}
+    U -->|确认| W[写入 .Knowledge/]
+    U -->|修改| O
+    U -->|取消| STOP[不写入]
+```
+
+
+
+写入是破坏性操作  ·  大纲是用户唯一的纠错机会  ·  确认前不落盘
+
+#### 5. 零输入推断
+
+```
+f2s-kb-sync 三种输入方式
+
+  方式 1：用户显式给出能力列表    "帮我把退款状态机同步进知识库"
+  方式 2：用户给辅助材料          @src/refund/ @docs/方案.md
+  方式 3：零输入                  "f2s-kb-sync"（仅此一句）
+                                       ↓
+                                  Agent 基于会话上下文推断
+                                  本次实现了什么、有什么值得沉淀
+```
+
+会话上下文本身就是信息源  ·  不需要用户整理再输入
+
+#### 5.1 执行开关如何进入 Agent（多端提示）
+
+`flow2spec.config.json` 决定 **`subAgent` / `switchAgentVerification` / `changeTracking`**，但各 AI 产品**不保证**会话启动即自动打开该文件。设计上用 **多条弱约束叠加** 降低「未读配置就开跑 `f2s-*`」的概率，同时避免在 `.Knowledge` 再维护一份与 `.codex/topics/f2s-config-check.md` 逐字重复的长文：
+
+| 机制 | 设计意图 |
+| --- | --- |
+| **Cursor `f2s-config-check.mdc`** | 规则层强制「技能正文前先 Read」。 |
+| **Claude `f2s-config-inject` PreToolUse** | 在调用 **`f2s-*` Skill** 时注入解析结果；**缺文件 / 坏 JSON / hook 异常**仍输出说明与默认语义，避免静默。 |
+| **Codex `AGENTS.md` + `renderProjectConfigBlock`** | 顶部 **Read** 硬约束 + **init 快照表**（与磁盘不一致时以 Read 为准）。 |
+| **知识库 `config-precheck` 主题** | 路由命中时只提供**摘要**与链向 Codex 长文，**不**替代 Read JSON。 |
+
+**权威仍为**项目根 JSON 的 **Read** 结果；各层为提示而非第二份真值源。操作侧完整表格与路径见 **[Flow2Spec使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./Flow2Spec使用说明.md)**；口述节奏见 **[Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)**。
+
+#### 6. 技能不复述统一入口规则，只引用
+
+```
+每个 SKILL.md 的编排部分写法：
+
+  subAgent / switchAgentVerification 语义
+  以统一入口为唯一事实源，本处不复述。
+  ↓
+  Cursor/Claude → rules/f2s-flow2spec-unified-entry.*
+  Codex         → .codex/topics/f2s-flow2spec-unified-entry.md
+
+15 个技能，每个只写自己特有的编排约束
+公共规则统一在一处定义，修改一处全部生效
+```
+
+---
+
+### 五、可插拔架构
+
+#### 1. 工具可插拔：一份知识，任意组合工具
+
+```
+flow2spec init cursor claude codex   ← 三工具全装
+flow2spec init claude                ← 只装 Claude
+flow2spec init cursor codex          ← 跳过 Claude
+
+.Knowledge/ 始终不变，工具随时加减
+```
+
+同一份 `.Knowledge/` 驱动所有工具  ·  加减工具不影响知识内容  ·  新工具接入零重建
+
+#### 2. 知识主题可插拔：增删不连带
+
+```
+添加主题                              删除主题
+─────────────────────               ─────────────────────
+1. 写 topics/xxx.md                  f2s-ctx-rm stock-docs/xxx.md
+2. 写 matchers/m-xxx.json                    ↓
+3. 在 manifest-routing 注册          自动清除 topics/ + manifest
+                                     + index 引用
+
+其他主题完全不受影响
+```
+
+新主题只需在 `topicDependencies` 里声明依赖  ·  不声明则彼此独立  ·  删除无副作用
+
+#### 3. 技能可插拔：自包含单元，项目级可覆盖包级
+
+```
+包级技能（随 flow2spec init 分发）     项目级技能（放 配置根/skills/）
+
+f2s-kb-sync/SKILL.md                  my-domain-skill/SKILL.md
+f2s-doc-arch/SKILL.md                 my-review-skill/SKILL.md
+...
+
+名字不冲突则共存  ·  同名则项目级覆盖包级  ·  互不感知
+```
+
+技能靠 `description` 字段自描述触发词  ·  不需要注册表  ·  不需要改全局配置  ·  上线即生效
+
+#### 4. 路由词表可插拔：分片隔离，局部更新
+
+词条变更只改对应 `matchers/m-xxx.json`，其他路由 diff 为零；结构见「[一、路由与上下文加载 → matchers 分片](#matchers-分片不嵌入-manifest)」。
+
+词条变更局部化  ·  合并冲突最小化  ·  新增路由不影响存量
+
+#### 5. 执行模型可插拔：config 按项目切换
+
+```
+flow2spec.config.json
+
+  subAgent: false               → 全程主 agent，低开销，适合小项目
+  subAgent: true                → 允许拆子并行，适合大规模改动
+
+  switchAgentVerification: false → 落盘侧自验，日常使用
+  switchAgentVerification: true  → 交叉校验，高置信度关键场景
+
+  changeTracking.feat/fix/implement: false → 不创建任务清单
+  changeTracking.feat/fix/implement: true  → 对应技能执行时自动创建任务清单，支持跨会话续作
+
+  三个维度正交 · 各技能可进一步细化覆盖全局配置
+```
+
+改一行配置切换执行策略  ·  不修改任何技能文件  ·  新项目开箱即用，老项目按需升级
+
+---
+
+## 优势与劣势
+
+```
+✅ 优势                              ⚠️  局限
+
+上下文精准                           前期投入：知识要靠技能建起来
+└─ 路由只加载相关文档                 规模门槛：小项目开销 > 收益
+
+跨工具共享                           需要团队纪律
+└─ 知识写一份，三工具都用             └─ 技能只降低摩擦，不消灭摩擦
+
+工具无关                             学习曲线
+└─ 换工具不重建知识                   └─ stock/req 边界、路由结构不直觉
+
+可持续
+└─ 维护绑定开发动作
+```
+
+---
+
+## 适合谁
+
+```
+                      项目规模
+                 小 ◄──────────► 大
+          ┌──────────┬────────────┐
+    短期   │  不需要   │   可以用    │
+          ├──────────┼────────────┤
+    长期   │  可以用   │  强烈推荐   │
+          └──────────┴────────────┘
+
+同时满足：有规模 · 长期迭代 · 多工具或多人 AI 协作
+```
+
+---
+
+## 相关文档
+
+- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
+- [README-命令说明](./README-命令说明.md)
+- [README-体系与原理](./README-体系与原理.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [Flow2Spec-演讲稿](./Flow2Spec-演讲稿.md)
+