Flow2Spec
ENGitHub

使用案例（模拟对话）

以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。

前提：项目已执行 flow2spec init，flow2spec.config.json 使用默认配置（subAgent: false；changeTracking.feat/implement: true，changeTracking.fix: false）。f2s-* 技能不改动配置根 rules/、skills/ 文件。

场景一：新需求 → 澄清 → 技术方案

你

/f2s-req-clarify 产品给了一份退款需求，但没说清楚部分退款和全额退款走不走同一接口，退款成功后积分是否回撤。文档在 .Knowledge/req-docs/退款需求v1.md。

Agent

已读取需求文档，有几个点需要确认：

  1. 部分退款与全额退款是否复用同一接口，通过 amount 区分，还是拆成两个端点？
  2. 退款成功后积分是否回撤？回撤失败是否阻断退款流程？
  3. 退款申请是同步到账还是异步（T+1）？
  4. 卖家侧是否需要审核步骤？

你

  1. 同一接口用 amount 区分；2. 积分回撤，失败不阻断，异步重试；3. 异步 T+1；4. 不需要审核。

Agent

澄清完成。执行 /f2s-req-tech 输出技术方案。

你

/f2s-req-tech

Agent

已生成 .Knowledge/req-docs/退款功能_技术方案.md，包含：

  • 接口设计：POST /refunds，amount 字段区分全额/部分
  • 状态机：PENDING → SUCCESS / FAILED
  • 积分回撤：异步队列，失败进死信，告警人工处理
  • 错误码清单

下一步：说”按方案实现 .Knowledge/req-docs/退款功能_技术方案.md”触发编码。

场景二：架构说明沉淀进知识库

你

/f2s-doc-arch 帮我出一份订单服务架构初稿，重点看创建流、支付回调、幂等与消息投递；代码在 src/order、src/payment。

Agent

已扫描相关目录，生成 .Knowledge/stock-docs/订单服务架构说明_初稿.md，包含：

  • 模块边界与依赖关系
  • 创建流时序
  • 支付回调幂等机制（基于 payment_callback_log 表）
  • 消息投递重试策略

确认无误后执行 /f2s-doc-final 规范化格式。

你

/f2s-doc-final .Knowledge/stock-docs/订单服务架构说明_初稿.md

Agent

已生成 .Knowledge/stock-docs/订单服务架构说明_终稿.md，按终稿模板整理，标注了待补充项。

你

f2s-kb-build .Knowledge/stock-docs/订单服务架构说明_终稿.md

Agent

已完成知识库同步：

  • 新增 .Knowledge/topics/order-service.md
  • 更新 .Knowledge/manifest-routing.json（新增路由规则）
  • 生成 .Knowledge/matchers/order-service.json（关键词：订单创建、支付回调、幂等、消息投递）
  • 更新 .Knowledge/index.md

后续与订单服务相关的任务会自动命中此主题。

场景三：按技术方案实现

你

按方案实现：.Knowledge/req-docs/退款功能_技术方案.md，只改 src/refund/，不要动支付模块。

Agent

已读取方案。实现任务列表：

  1. 新建 RefundController，实现 POST /refunds
  2. 新建 RefundService，含状态机流转逻辑
  3. 新建 RefundRepository，对应 refund 表
  4. 新建 PointRollbackProducer，向积分队列发送回撤消息
  5. 单元测试覆盖状态机流转

实现前确认：

  • refund 表是否已存在，还是需要生成 migration？
  • 积分队列 Topic 名称是什么？

你

表已存在，不用 migration；Topic 是 point-rollback-events。

Agent

已完成以上 5 项，均在 src/refund/ 内，未触碰 src/payment/。

待完成（需人工）：

  • point-rollback-events 消费端（积分服务侧）
  • 死信监控告警规则配置

建议执行 /f2s-kb-feat 将本次新增能力同步进知识库。

场景四：实现后补录知识库

你

/f2s-kb-sync 退款功能上线了，帮我把支付失败重试队列命名、死信表字段、监控告警口径沉淀进知识库，先给大纲我确认再写。

Agent

知识库更新大纲（待确认）：

更新主题：order-service（已有）

  • 新增「支付失败重试机制」：队列名 payment-retry-queue，最大重试 3 次，间隔 30s / 120s / 300s
  • 新增「死信表」：表名 payment_dead_letter，字段 order_id / error_code / retry_count / created_at
  • 新增「监控口径」：告警阈值 retry_count >= 3，通知渠道 DingTalk

确认后写入，或告诉我需要修改的地方。

你

确认写入。

Agent

已形成当前任务的 kb-delta.json：

  • 目标主题：order-service
  • 基线版本：revision: 6
  • 变更类型：appendBody

提交时会由 f2s-git-commit 自动执行 plan → apply → build → check；若磁盘 revision 已变化，会停止并报告冲突，不会覆盖队友的新内容。

场景五：发现违规实现，修复并同步知识库

你

/f2s-kb-fix RefundService 里直接 new RestTemplate() 了，违反 Spring Bean 注入约定。

Agent

已修复：RefundService.java 第 34 行改为构造注入，RefundConfig 补充 @Bean 声明。

已把「RestTemplate 必须通过 Bean 注入，禁止直接实例化」整理为知识变更 delta，并记录修复证据。提交前会先做 revision 预检，再合入对应 topic。

场景六：Git 合并后知识库冲突

你

/f2s-kb-merge .Knowledge/index.md 和 .Knowledge/stock-docs/订单服务架构说明_终稿.md 合并后有冲突标记，业务代码我已手动合完。

Agent

已扫描两个文件的冲突标记：

  • index.md：2 处冲突，均为主题描述字段，取 HEAD 版本（内容较新），已自动处理。
  • 订单服务架构说明_终稿.md：1 处冲突，「监控告警阈值」两个分支不同（3 次 vs 5 次），需你确认。

你

用 3 次。

Agent

已按确认结果清理全部冲突标记，文件可提交。

场景七：两个人修改同一个 topic

背景

Alice 和 Bob 都从 order-service revision: 6 开始工作。Alice 补充退款到账时限，Bob 补充退款重试规则；两份改动落在同一个 topic。

Alice

f2s-kb-sync 把“退款审核通过后 3 个工作日内原路退回”补进订单服务知识，确认大纲后生成 delta。

Agent（Alice）

已生成 .task/alice/active/refund_arrival/kb-delta.json，baseRevisions.order-service = 6。kb plan 通过，apply 后 order-service 已更新为 revision 7。

Alice 随后提交并推送了代码与 .Knowledge/ 变更。

Bob

我已经拉取 Alice 的最新提交。继续检查我的退款重试 delta。

Agent（Bob）

kb plan 未通过：

order-service: revision mismatch 6 -> 7

Alice 新增的是到账时限；你的 delta 新增失败重试，两条规则不互斥，但都修改同一个 topic。需要以 revision 7 的正文为基线重新整理 change，不能只把 baseRevisions 数字改成 7。

Bob

保留 Alice 的到账时限，把我的“最多重试 3 次，间隔 30s / 120s / 300s”放到退款失败处理下面，再试一次。

Agent（Bob）

已重读 revision 7，按当前结构重写 delta：

  • 保留到账时限原文
  • 在「退款失败处理」下追加重试次数与间隔
  • baseRevisions.order-service 更新为 7

第二次 kb plan 通过，apply 后 topic 进入 revision 8；kb build 与 kb check 均通过。现在可以查看 .Knowledge/ diff 后提交。

这里处理的是 revision 冲突：拉取最新 topic、重读语义、重写 delta。只有文件已经出现 <<<<<<< 等标记时，才属于 Git 冲突并进入 f2s-kb-merge。

相关文档