[中文](./项目里程碑.md) | [English](./en/milestones.md)

# 项目里程碑

> **范围**：整个项目  
> **更新时间**：2026-07-02

## 总览

| 阶段 | 时间 | 摘要 |
| --- | --- | --- |
| M24 · Codex 规则镜像修复 + upgrade 步骤 -1 智能预检 + 本仓开发纪律 | 2026-07-02 | 修复 writeCodexTopicMirrors filter 遗漏 .md 导致 .codex/topics 空目录；f2s-kb-upgrade 步骤 -1 改为「先探测再按需升级」（A 已 latest 跳过 / B 落后派子 agent / C 未装派子 agent）；新增本仓专属 f2s-dev-workflow-constraints 规则与 repo-dev-check 自查 skill |
| M23 · f2s-kb-distill 自动判挡 + f2s-kb-upgrade 步骤 -1 | 2026-06-30 | 砍掉 --fast 参数，内置「轻量挡 / 严格挡」四维度自动判挡；f2s-kb-upgrade 新增步骤 -1 后台子 agent 升全局 cli |
| M22 · pkgRev 顶层落盘 + init 自动升级全局 cli | 2026-06-29 | manifest 顶层 pkgRev 字段每次 init 覆盖；init 末尾检测全局已装且 latest 更高时自动 npm i -g |
| M21 · f2s-kb-upgrade templateRevision 快速路径与自更新闭环 | 2026-06-29 | 项目 vs 包模板 projectRev 相等时跳过步骤 3/3a/3b；init 后 SKILL.md 变化按新版从 2c 起重跑；feedback-closing 删除 KB 技能整体禁令并补概要要求；inferred 直接落盘 |
| M20 · init 默认值翻面 | 2026-06-29 | subAgent / switchAgentVerification / intentRecognition 三项默认值翻面为 true；新项目默认开启子 agent 编排、交叉校验、意图识别自动分流 |
| M19 · .task/ 新增 acceptance.md 验收清单 | 2026-06-24 | `.task/active/<task>/` 新增 acceptance.md（与 user-todos.md 职责分离）；task.md 全部 [x] 后、归档前必写，否则不许归档；归档目录命名统一为 `<YYYYMMDD>-<task-name>` |
| M18 · f2s-kb-distill 与规则重构 | 2026-06-14 | 新增 f2s-kb-distill 知识提取技能；feedback-closing 收口重构；Codex AGENTS.md 入口瘦身为「先做两步」导引；.codex/hooks.json SessionStart 双脚本落地；CLI 跨平台扩展名处理 |
| M17 · 中英文模板初始化 | 2026-06-08 | flow2spec init 支持 zh-CN/en-US 单选初始化；开源仓 README 默认入口切为英文；中文入口迁至 README.zh-CN.md |
| M16 · 意图识别开关与路由规则 | 2026-06-08 | 新增 intentRecognition 配置开关与 f2s-intent-routing 规则；高置信操作意图可受控自动分流到 f2s 技能 |
| M15 · 全端技术方案与普通问答收口 | 2026-06-05 | f2s-req-backend 升级为 f2s-req-tech，技术方案模板扩展为前后端/全栈通用；普通问答源码补答后增加知识库补充建议收口 |
| M14 · f2s-git-commit 快捷提交 | 2026-06-04 | f2s-git-commit 新增快捷提交模式，跳过知识库覆盖检查但保留 diff、精确 add、hooks 与提交信息展示 |
| M13 · 更新检测与三端启动提醒 | 2026-06-04 | 新增 updateCheck.enabled 配置、版本检查 hook、自然日缓存；Claude/Cursor/Codex 三端 SessionStart 注入升级提示 |
| M12 · 主题分类与 init 合并校验 | 2026-06-03 | topicMetadata 支持 primary/tags/confidence；init 支持合并校验与模板优先覆盖；多个 skill 统一重命名到 kb-/doc- 前缀 |
| M11 · 知识工程规范与 skill 骨架 | 2026-06-03 | 新增 skill-authoring 规范、f2s-kb-addRules 口述规则沉淀能力、f2s-topic-authoring 创作侧准则和大功能拆分策略 |
| M10 · 文档沉淀规则补强 | 2026-05-27 | f2s-doc-add 增加多模块检测；双仓包名规则落地；全局规则补充否定式表达禁止约束 |
| M9 · README 与任务能力外显 | 2026-05-26 | README 与英文 README 补充使用流程、命令速查、任务清单能力描述与日常开发流程 |
| M8 · 文档链路与目录去业务化 | 2026-05-21 | 重组文档目录；doc-arch 初稿必须经 doc-final 链路；明确新需求开发技能链路 |
| M7 · 四源里程碑生成能力 | 2026-05-18 | 新增 f2s-doc-milestone 技能和项目里程碑模版；规定按 req-docs/git/.task/知识库主题四源生成阶段 |
| M6 · Codex 根入口自动发现 | 2026-05-16 | flow2spec init codex 将完整规则写入仓库根 AGENTS.md；.codex/AGENTS.md 退化为指针 |
| M5 · CLI 运维命令与任务路由 | 2026-05-15 | CLI 新增 version/update 子命令；包模板 manifest 补齐 f2s-task 与 f2s-req-plan 路由和依赖 |
| M4 · 对外演示与双语资料 | 2026-05-13 | 纳入演示源文件、sync-gh-pages.sh、英文演示稿与 6 篇英文文档；README 中英切换入口与双语演示链接 |
| M3 · .Knowledge 机读路由 | 2026-05-08 | 引入 .Knowledge、manifest-routing.json、topics 与 matchers；确立 match→expand→verify→act 知识库消费链路；补齐 config 预检、KB 预检与全端编码行为准则 |
| M2 · OpenSpec 退场与 f2s 技能化 | 2026-04-23 | 删除 OpenSpec/opsx 依赖；完整转换为 f2s 自研技能路线；需求澄清、技术方案与技能模板化能力成型 |
| M1 · CLI 初始化与 OpenSpec 协作流 | 2026-02 ~ 2026-04 | Flow2Spec 作为可安装 CLI 初始化；早期围绕 OpenSpec/opsx 变更流组织 AI 协作 |

## M24 · Codex 规则镜像修复 + upgrade 步骤 -1 智能预检 + 本仓开发纪律

- 修复 `writeCodexTopicMirrors` filter：原 `endsWith(".mdc")` 遗漏所有 `.md` 规则文件，导致 `flow2spec init codex` 后 `.codex/topics/` 目录始终为空；扩展匹配 `.md` 与 `.mdc` 并统一转成 `.codex/topics/*.md`
- f2s-kb-upgrade 步骤 -1 从「无条件后台派子 agent 跑 `npm i -g`」改为**先探测再按需处理**：主 agent 顺序前台跑 `flow2spec --version` + `npm view ... version` + `command -v npx`，按 A/B/C 分支决定
  - A 已装且是 latest → 完全跳过升级；步骤 2 首选 `flow2spec init`
  - B 已装但落后 → 派独立子 agent 后台跑 `npm i -g ...@latest`（fire-and-forget）；步骤 2 用 `npx @latest init`
  - C 未装 / latest 未知 → 按 B 处理；探测全失败可整体跳过步骤 -1
- 步骤 2 命令清单默认形态随步骤 -1 分支选定；补「手动 override」条款与「辅助命令」小节（`flow2spec --version` / `flow2spec update`）
- 新增 **`f2s-dev-workflow-constraints`** 规则长文（Cursor / Claude / Codex 三端）：Flow2Spec 双仓自身开发的写盘边界与分发口径——只改 templates、不改配置根、用户驱动分发、双仓一致；**本规则只存本仓、不进 templates**，下游拿不到
- 新增 **`repo-dev-check`** 自查 skill：本仓提交前逐份改动套「templates vs 配置根」判定表 + 双仓 diff + 分发建议；触发词包括「双仓漂移」「写盘边界」「templates vs 配置根」
- `.Knowledge/topics/f2s-dev-workflow-constraints.md` 打薄成路由摘要，指向配置根 rules 长文；matcher 补新触发词（`sync:agents` / `写盘边界` / `双仓漂移`）；index.md 主题一览同步更新关联文档列
- 本仓专属规则 / skill 的双仓同步义务：内容含双仓包名对照表（`@double-codeing` / `@ctrip`），双仓采用**逐字节一致**同步策略，不做包名替换

## M23 · f2s-kb-distill 自动判挡 + f2s-kb-upgrade 步骤 -1

- f2s-kb-distill 砍掉 `--fast` 参数，内置「轻量挡 / 严格挡」自动判挡：按上游 case、业务源码 Read 数、函数引用数、用户否定信号 4 维度由 agent 选挡
- 轻量挡跳过下钻量化打分、既有 topic 描述程度评估、决策矩阵与风格对齐；步骤 5 路由 / 步骤 6 落盘永不省略
- f2s-kb-upgrade 新增「步骤 -1」：进入步骤 0 前派独立子 agent 后台执行 `npm i -g <pkg>@latest`，不等待完成，主流程立即继续；不受 subAgent 配置约束
- 步骤 -1 与 cli.js `maybeAutoUpdateGlobalInstall` 形成互补：升级技能内强制触发，init 末尾兜底触发
- feedback-closing case 1/2/3 收口块回滚为单命令（去掉 `--fast` 提示）
- 命令说明与 commands-reference 增加「执行挡位」节，说明轻量 / 严格两挡触发条件

## M22 · pkgRev 顶层落盘 + init 自动升级全局 cli

- `lib/init.js` 新增 `finalizePkgRev`：把包模板 projectRev 写入项目侧 manifest 顶层 `pkgRev` 字段，每次 init 覆盖
- init 同时覆盖 `manifest.version` 为当前包版本，保证项目 manifest 与所用 CLI 版本一致
- `cli.js` 新增 `maybeAutoUpdateGlobalInstall`：init 末尾检测全局已装且 npm latest 更高时自动执行 `npm i -g <pkg>`；npx-only 用户静默跳过
- f2s-kb-upgrade 步骤 2c 取 pkgRev 改为直接 `Read` manifest 顶层 `pkgRev`，不再回退扫描其他位置
- 全局术语统一为 `projectRev`（包模板侧）/ `pkgRev`（项目落地侧）

## M21 · f2s-kb-upgrade templateRevision 快速路径与自更新闭环

- f2s-kb-upgrade 引入 `templateRevision`（后改名 `projectRev`）快速路径：项目修订号与包模板修订号相等时跳过步骤 3、3a、3b
- 自更新闭环修正：init 后重读 SKILL.md 发现版本变化，按新版从步骤 2c 起重跑，不再二次执行 `flow2spec init`
- `f2s-kb-feedback-closing` 重构：删除「KB 技能内整体禁止贴收口块」的一刀切禁令，改为 distill 自身禁贴 + 其它 KB 技能按四 case 正常判定
- feedback-closing 落地「概要要求」：case 1~3 必须一句话写明"这次跑 distill 会把什么入库"
- topicMetadata 准则补充：`inferred` 不需用户事先同意即可直接落盘，纠正"必须人工确认"的误读

## M20 · init 默认值翻面

- `flow2spec.config.json` 三项布尔字段默认值翻面为 `true`：`subAgent` / `switchAgentVerification` / `intentRecognition`
- 新项目执行 `flow2spec init` 后默认开启：子 agent 编排、落盘交叉校验、意图识别自动分流
- 老项目已显式写过这三项不受影响；升级时仍缺该字段的老项目按新默认 `true` 补齐
- 默认翻面后 `f2s-*` 技能的拆子前提与跨 agent 校验由"opt-in"转为"opt-out"

## M19 · .task/ 新增 acceptance.md 验收清单

- `.task/active/<task>/` 新增 `acceptance.md` 文件，与 `user-todos.md` 职责分离：前者管「用户验收」，后者管「用户代办」
- 新增归档门禁：`task.md` 全部 `[x]` 后、目录移入 `completed/` 前必写 `acceptance.md`，仍为占位说明或缺失则禁止归档
- 创建任务步骤 3.e 同步创建 `acceptance.md` 占位；执行中原则上不写，task.md 完工后由 Agent 整理为正式验收清单
- 归档目录命名统一为 `<YYYYMMDD>-<task-name>`（本地日历日期 8 位在前），便于按时间排序
- `f2s-task` 规则、`f2s-req-plan` 技能、各 `f2s-kb-*` 技能内变更追踪相关步骤同步更新
- 版本号 bump 至 3.2.1

## M18 · f2s-kb-distill 与规则重构

- 新增 f2s-kb-distill 技能：从问答过程提取可复用知识事实，自动判断创建新 topic 或追加到既有 topic
- 重构 f2s-kb-feedback-closing：建议出口统一为 f2s-kb-distill，替换原有 f2s-kb-add/f2s-kb-sync 双入口
- Codex 根入口 AGENTS.md 瘦身：去掉大段内嵌规则，改为「先做两步」简短导引
- Codex hooks 落地：.codex/hooks.json 新增 SessionStart 配置摘要与版本检查双脚本
- CLI 跨平台扩展名处理：Cursor 规则保留 .mdc，Claude/Codex 规则统一切换为 .md，codexAgentsAdapter 兼容 .mdc 读取
- intentRecognition 默认在内部仓启用
- 里程碑skill规则重构

## M17 · 中英文模板初始化

- templates/ 拆分为 zh-CN/ 与 en-US/ 两套模板目录
- flow2spec init 新增语言单选初始化，默认中文
- 英文模板覆盖 rules、skills、knowledge、AGENTS.md 与 flow2spec.config.json；模板文件名使用英文命名
- 开源仓 README 默认入口切为英文；中文入口迁至 README.zh-CN.md；README.en.md 保留兼容

## M16 · 意图识别开关与路由规则

- flow2spec.config.json 新增 intentRecognition 布尔字段
- 新增 f2s-intent-routing 规则：高置信操作意图按映射表自动进入对应 f2s 技能
- 低置信、讨论、评估或需求不完整场景保持普通对话或先走澄清流程
- 禁止在 intentRecognition 未读取或为 false 时自动调用 Skill

## M15 · 全端技术方案与普通问答收口

- f2s-req-backend 重命名为 f2s-req-tech
- 技术方案模板从后端专用升级为前端/后端/全栈通用
- 新增 f2s-kb-feedback-closing 规则：普通问答下钻源码后的知识库补充建议四 case 收口
- 普通问答源码补答后明确收口提示逻辑，减少不必要的 f2s-kb-add/sync 提示

## M14 · f2s-git-commit 快捷提交

- f2s-git-commit 支持快捷提交模式，跳过知识库覆盖检查步骤
- 保留 diff 读取、冲突检查、精确 add、git hooks 与提交信息首行展示
- 禁止自动 push / pull，保留用户确认环节

## M13 · 更新检测与三端启动提醒

- flow2spec.config.json 新增 updateCheck.enabled 配置
- 版本检查 hook 落地:manifest version 与 npm latest 比对;自然日缓存到 .Knowledge/update-check.json
- Claude 端写入 .claude/settings.json SessionStart 版本检查脚本
- Cursor 端写入 .cursor/hooks.json SessionStart 版本检查脚本
- Codex 端写入 .codex/hooks.json SessionStart 配置摘要与版本检查双脚本
- 规则层双保险：脚本缓存与规则层 updateCheck 互为备份

## M12 · 主题分类与 init 合并校验

- manifest-routing.json 新增 topicMetadata 字段，支持 primary/tags/confidence 三字段
- f2s-topic-authoring 规则补充 topicMetadata 判定准则（4 种 primary 类型、confidence 取值规则）
- init copySkills 自动删除旧 skill 目录，不误删用户自定义 skill
- init 支持模板优先覆盖与合并校验
- 6 个 skill 统一重命名到 kb-/doc- 前缀规范
- 冗余 skill（f2s-coding-guide、f2s-doc-routing）删除

## M11 · 知识工程规范与 skill 骨架

- 新增 skill-authoring topic + matcher：统一 templates/skills/f2s-*/SKILL.md 骨架、命名与小节顺序
- 新增 f2s-kb-addRules 技能（原 f2s-kb-capture 重命名）：口述规则沉淀，自动判断新建 topic 或并入存量
- 新增 f2s-topic-authoring 规则：topic 创作侧准则，覆盖命名、骨架、topicDependencies 判定与大功能拆分
- 大功能拆分策略落地：主 topic + 子 topic 结构建议，含拆分阈值与反向排除规则

## M10 · 文档沉淀规则补强

- f2s-doc-add（f2s-kb-add 前身）增加多模块检测，避免多模块材料被合并进单一输出文档
- 双仓里程碑 stock-doc 补充包名规则（公开仓 @double-codeing/flow2spec，私有仓路径区分）
- 全局规则新增否定式表达约束：禁止用"非 X / 不是 X"传达正确信息，须改为肯定式陈述

## M9 · README 与任务能力外显

- README 补充使用流程与命令速查表
- README 补充任务清单能力与日常开发流程说明
- 英文 README 同步补充能力描述，移除 f2s-req-plan 误导引用

## M8 · 文档链路与目录去业务化

- 文档目录重组，去除产品仓 docs 路径耦合
- 确立 doc-arch（架构初稿）→ doc-final（终稿模板）→ kb-build 的文档链路，禁止初稿直接驱动 kb-build
- 更新新需求开发典型技能链路，明确各技能在需求→实现→知识库闭环中的位置
- .Knowledge/stock-docs、req-docs 目录约定与路径表去业务化

## M7 · 四源里程碑生成能力

- 新增 f2s-doc-milestone 技能：按 req-docs、git log、.task、知识库主题四源生成项目里程碑
- 新增项目里程碑模版：确定阶段结构、字段规范与禁止写联调/测试/验收的约束
- 里程碑阶段仅记录功能/能力变更，工程性改动并入对应功能阶段

## M6 · Codex 根入口自动发现

- flow2spec init codex 将完整规则写入仓库根 AGENTS.md
- .codex/AGENTS.md 退化为指针，降低 Codex 自动发现规则缺失风险
- 确立 Codex 三端（Claude/Cursor/Codex）规则注入各自配置根的统一模式

## M5 · CLI 运维命令与任务路由

- CLI 新增 version 子命令：读取 package.json 输出当前版本
- CLI 新增 update 子命令：执行包自更新
- 包模板 manifest 补齐 f2s-task 与 f2s-req-plan 路由条目和 topicDependencies 依赖声明

## M4 · 对外演示与双语资料

- 纳入 presentations/flow2spec-intro-public 演示源文件
- 新增 sync-gh-pages.sh 同步脚本与 GitHub Pages 部署能力
- 新增英文演示稿与 6 篇英文文档
- README 增加中英切换入口与双语演示链接

## M3 · .Knowledge 机读路由

- 引入 .Knowledge/ 目录：manifest-routing.json、topics/、matchers/ 标准结构落地
- 确立 match→expand→verify→act 知识库消费链路
- 新增 f2s-knowledge-preflight 规则：强制首读 manifest-routing.json 与缺口闸门约束
- 新增 f2s-config-check 规则：f2s-* 技能前置读取 flow2spec.config.json
- 补齐 Karpathy 全端编码行为准则（f2s-karpathy-guidelines）

## M2 · OpenSpec 退场与 f2s 技能化

- 删除 OpenSpec/opsx 依赖与变更流组织方式
- 完整转换为 f2s 自研技能路线（skills/ 目录体系成型）
- f2s-req-clarify（需求澄清）、f2s-req-tech（技术方案）技能初始化
- 确立 f2s-* 技能为后续知识库与需求链路的基础执行单元

## M1 · CLI 初始化与 OpenSpec 协作流

- Flow2Spec 作为可安装 CLI 工具完成初始化
- 早期通过 OpenSpec/opsx 变更流组织需求、变更和 AI 执行
- 基础 init 命令支持 Cursor/Claude/Codex 配置根写入

## 待确认

- `.task/active/lazy_loading_rule_optimization/` 在途任务（创建于 2026-06-03，规则瘦身/懒加载优化）仍未闭环，步骤未全部完成，本轮不形成已交付阶段
- 无其它缺口