体系与原理

Flow2Spec 的目标是把”业务知识沉淀”与”Agent 能力加载”拆开，并在仓库里用 Memory Coding（记忆编码） 把「要记住的东西」落盘为可 diff、可评审的 Git 资产。

• 知识环（.Knowledge/）：业务文档与机读路由（见下文多层结构）
• 任务环（.task/）：跨会话续作清单
• 规则环（各工具 rules / AGENTS.md）：规定 Agent 怎么读、怎么做
• 技能环（f2s-*）：维护知识、触发流程

Flow2Spec ≠ 只有知识库；上述四环同属 Memory Coding，下文「两层结构」描述的是知识环 vs 工具侧执行落点的生命周期分工。

1. Memory Coding 与仓内四环

Memory Coding：把必须长期记住的上下文编码进可提交仓库——不押在模型私有 Memory、不只在聊天里重复，也不靠全仓向量概率猜。

仓内拆成 四环（勿说成「三环」把规则与技能合并）：

与「两层结构」的关系：知识环对应「随项目走」的知识层；规则环 + 技能环落在各工具配置根，随工具升级迭代；任务环与 .Knowledge/ 并列于仓内，不属于 .Knowledge/ 目录。

2. 知识环内的多层记忆结构

.Knowledge/ 不是扁平「一堆 Markdown」，而是 横读（渐进式路由）+ 纵链（主题依赖） 的多层记忆：

L1 分片语义：includeAny 任一命中或 includeAll 全部命中，该任务规则即具备候选资格（task 精确命中豁免短语要求）；excludeAny 任一命中或 excludeAll 全部命中则整条规则否决，且否决优先于 task 精确命中。

渐进式读取（match → expand → verify → act）作用在 L0–L2（必要时再到 L3）：先收窄入口，再展开依赖与缺口检查，最后才改代码。主题级依赖挂一次、所有任务共享，避免每个任务重复声明前置约束。

人读导航：index.md 仅作语义边界校验，不替代 manifest-routing 机读链。

3. 知识层与执行层（两层结构）

4. 渐进式读取

统一建议顺序：

1. .Knowledge/manifest-routing.json
2. .Knowledge/matchers/<matcher>.json（按需：由 manifest-routing.taskToTopicRules[].matcherPath 直链定位）
3. .Knowledge/index.md
4. 命中的 stock-docs / req-docs 文档
5. 必要时下钻源码

读取后执行 match → expand → verify → act 四步流水线：命中主候选后展开依赖主题、缺口检查，置信度足够时才执行；低置信度先澄清。

同时由配置根入口（Flow2Spec 包规则：f2s-flow2spec-unified-entry.mdc / f2s-flow2spec-unified-entry.md；旧版业务仓库常见为 main.md(c)；以及 AGENTS.md）约束加载行为。
其中 Codex 不读取 rules/ 目录，统一通过 .codex/AGENTS.md + skills/ 承载执行约束。

5. 关键链路

• 文档沉淀链：f2s-doc-arch → f2s-doc-final → f2s-kb-build
• 实现链：.Knowledge/req-docs/*.md → implement-tech-design → 代码
• 维护链：f2s-kb-fix / f2s-kb-feat / f2s-kb-sync / f2s-kb-merge
• 需求规划链：f2s-req-plan（规划 + 实现，始终创建任务清单）
• 变更追踪链：changeTracking.* 配置 → f2s-task 规则（自动）→ .task/ 任务清单 → 跨会话续作
• 包模板/路由形态与配置根对齐：f2s-kb-upgrade（勿将单独 flow2spec init 等同于「知识库升级」；非主题版本更新可由 agent 直接代跑 flow2spec init 完成对齐）

文档沉淀链产出两类文档：

6. 多人协作的两条隔离线

Flow2Spec 假设团队场景是「一份知识库、多个人一起写」。围绕这个假设，仓内两条环走了相反的策略：任务环切开、知识环合并。

• 任务环：.task/ 不进 Git、按 <developerId>/ 分层，是个人过程草稿。
• 知识环：.Knowledge/ 完整走 Git，配合 topic frontmatter 里的整数 revision 做磁盘乐观锁，多人并写靠 kb-delta.json 结构化提交自动合并。

两条线共同用一个前提——Git 是团队的共享通道。凡是团队要看的东西都进 Git，凡是个人过程状态都不进。

6.1 任务环：按 developerId 本地隔离

.task/ 记的是「这一轮 AI 会话在做什么」——checklist、user-todos、跨会话续作的中间态。这些内容对别人来说是噪声，所以：

• .task/ 默认写进 .gitignore，不跨机器同步；
• collaboration.enabled: true（默认）时，.task/ 内部再按 <developerId>/ 分层，兜底同机多账号、共享构建机等场景；
• developerId 从 collaboration.developerId → git email → git name 逐档降级；解析不出（或 enabled: false）时回落到 legacy 单根 .task/，与旧版行为一致。

看到 .task/<developerId>/ 是隔离模式，看到 .task/todo.json 直接躺根下是 legacy——两种形态并存。详细路径与 developerId 解析规则见 目录与路径约定 §.task/ 的两种形态。

这条切法的副作用：manager 视角看团队进度不能靠 .task/completed/（它不在 Git 里），要走 git log、PR、里程碑文档。这是刻意的取舍——.task/ 是过程草稿，.Knowledge/、commit message 与 milestone 才是团队产出。

6.2 知识环：磁盘乐观锁 + 结构化 delta

.Knowledge/ 是团队沉淀，必须共享，也必须扛得住多人并写。做法：

关键判断在 plan 阶段：delta 里的 baseRevisions 对得上磁盘现状就 mergeable，apply 写盘并把 revision +1、刷路由；对不上就报 mergeable: false 附具体 topic 与差值，交给人做语义合并。

冲突不是靠拦截并发写，而是让第二个人 git pull 到最新磁盘 revision 之后再重新 plan——这跟平时 Git 分支要先 pull main 再 merge 的思路一致。乐观锁只覆盖走 delta 通道的改动；任何绕开 delta 的直接文件编辑仍然需要人肉解冲突，所以 f2s-kb-* 技能强制走 delta。

6.3 两条线为什么这样切

一个反问：既然 .task/ 不进 Git，为什么还要 <developerId>/ 这一层？在 目录与路径约定 §.task/ 的两种形态 里列了三个具体边界，简言之是「本地磁盘隔离不能覆盖所有场景」（同机多账号、AI 越界扫描、未来 completed/ 白名单进 Git 的可能性）。

反过来 .Knowledge/ 也可以走「按 developerId 拆知识库」的路线——但那会导致每个人看到的知识库版本不一样，团队协作的语义直接崩掉。所以知识库必须共享，冲突必须解决，只是解决方式换成了「自动合并 + 冲突时人工介入」。

7. Agent 执行模型

Flow2Spec 通过项目根 flow2spec.config.json 的 subAgent、switchAgentVerification 两个字段控制执行行为。

Agent 如何读到上述真值：多端提示 + Read 权威，见 使用说明 § 一（唯一详表）；设计归纳见 设计说明 § 四、5.1。

7.1 主/子 Agent 职责划分原则

subAgent: false（默认）：全部 f2s-* 技能在主 agent 内顺序完成，无并行拆分。

subAgent: true：达到技能正文约定的规模门槛时，允许拆分子 agent 并行处理。职责边界如下：

子 agent 的拆分边界由各 f2s-* 技能正文逐步约定（如模块数、文档数、代码行数等门槛），当前尚未在模板层给出统一阶段表，以技能正文为准。

7.2 验证归属原则

默认（谁落盘谁验）：落盘或变更后的验证在落盘侧 agent 内完成。子 agent 落盘则子 agent 自验，主 agent 落盘则主 agent 自验。

交叉验证（switchAgentVerification: true）：由对方 agent 承担验证，适用于需要更高置信度的场景。启用条件必须同时满足：

1. 配置 switchAgentVerification: true
2. 当前执行的 f2s-* 技能正文明确写出该步骤依赖本项

交叉验证规则：

设计意图：交叉验证引入外部视角，降低落盘侧的自验盲区，但增加执行开销，因此设为显式 opt-in 而非默认行为。

7.3 变更追踪（changeTracking）

changeTracking 是独立于 subAgent / switchAgentVerification 的第三个维度，控制技能执行时是否自动创建可跨会话续作的任务清单。

{
  "changeTracking": {
    "feat": true,
    "fix": false,
    "implement": true
  }
}

• 各技能子项独立控制，互不影响
• 开启后：技能执行前自动检查 .task/todo.json，创建或续接任务；完成后自动归档
• 跨会话：新会话描述相关内容，f2s-task 规则（alwaysApply）关键词匹配命中后自动加载剩余清单和对应技能上下文
• f2s-req-plan 不受此配置约束，始终创建任务清单

8. 设计收益

1. 跨工具共享同一业务知识源
2. 不破坏各客户端原有的规则加载习惯
3. 通过 manifest-routing + matcherPath 分片（matchers/*.json）控制任务路由与依赖，减少误读与全量扫描
4. 主/子 agent 职责边界清晰，主 agent 始终持有全局视图，子 agent 专注单元处理，汇总一致性由主 agent 保证
5. 验证归属可配置：默认落盘侧自验保持低开销，交叉验证按需启用提升关键场景置信度
6. 多人协作分两条线各自解决：任务环靠本地隔离避免串戏，知识环靠磁盘乐观锁 + 结构化 delta 自动合并

9. 相关文档

• Flow2Spec 基础介绍
• 使用说明
• 命令说明
• 目录与路径约定
• 使用案例-模拟对话
• 项目里程碑