@double-codeing/flow2spec 3.0.13 → 3.0.14

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

@@ -61,16 +61,21 @@ graph LR
 
 ### 3. 技能维护闭环
 
+<p><img src="./images/flow-1.png" alt="技能维护闭环" style="max-width:100%;" /></p>
+
+<details>
+<summary>Mermaid 源码</summary>
+
 ```mermaid
 graph LR
     K[".Knowledge/"] --> AI["下次会话\n的 AI"]
-    AI --> C["代码\n变更"]
+    AI --> C["功能迭代"]
 
     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
+    CMT -->|"未入库则提醒\n-> kb-sync/kb-feat"| K
 
     D1["架构文档"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
     D2["PDF 方案"] -->|f2s-doc-pdf| FIN
@@ -79,11 +84,13 @@ graph LR
     OLD["存量代码/文档"] -->|f2s-doc-add| K
 
     NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
-    BE --> IMPL["implement-tech-design"] -->|f2s-kb-feat| K
+    BE --> IMPL["实现xxx技术方案"] -->|自动触发implement-tech-design规则| K
 
     GIT["Git 合并后"] -->|f2s-kb-merge| K
 ```
 
+</details>
+
 七条入口  ·  `f2s-git-commit` 是提交时的知识纪律收口  ·  `.Knowledge/` 是唯一汇聚点  ·  知识驱动 AI，AI 驱动下轮开发
 
 

package/docs/design-principles.en.md

@@ -63,16 +63,21 @@ graph LR
 
 ### 3. Skill Maintenance Loop
 
+<p><img src="./images/process-1.png" alt="Skill maintenance loop" style="max-width:100%;" /></p>
+
+<details>
+<summary>Mermaid source</summary>
+
 ```mermaid
 graph LR
     K[".Knowledge/"] --> AI["Next Session\nAI"]
-    AI --> C["Code\nChanges"]
+    AI --> C["Feature iteration"]
 
     C -->|"Fix Bug"| FIX["f2s-kb-fix"] --> K
     C -->|"New Capability"| FEAT["f2s-kb-feat"] --> K
     C -->|"Session End"| SYNC["f2s-kb-sync"] --> K
     C -->|"Commit Code"| CMT["f2s-git-commit\nGate Check"]
-    CMT -->|"Not in KB, remind\n→ kb-sync/kb-feat"| K
+    CMT -->|"Not in KB, remind\n-> kb-sync/kb-feat"| K
 
     D1["Architecture Docs"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
     D2["PDF Proposal"] -->|f2s-doc-pdf| FIN
@@ -81,11 +86,13 @@ graph LR
     OLD["Existing Code/Docs"] -->|f2s-doc-add| K
 
     NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
-    BE --> IMPL["implement-tech-design"] -->|f2s-kb-feat| K
+    BE --> IMPL["Implement xxx technical design"] -->|auto-trigger implement-tech-design rule| K
 
     GIT["After Git Merge"] -->|f2s-kb-merge| K
 ```
 
+</details>
+
 Seven entry points  ·  `f2s-git-commit` is the knowledge discipline gate at commit time  ·  `.Knowledge/` is the single convergence point  ·  Knowledge drives AI, AI drives the next development cycle
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.0.13",
+  "version": "3.0.14",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

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

@@ -0,0 +1,29 @@
+> **主口径**：模板在 `templates/knowledge/template/项目里程碑模版.md`；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。  
+> **执行 `f2s-doc-milestone`**：结构以本模版为准；内容仅来自 **req-docs、git log、.task** 与知识库主题，禁止臆造。  
+> **阶段**：Mx **仅**功能/能力变更；**不得**单独成阶段的联调、测试、验收或纯环境运维；工程性改动并入对应功能阶段。
+
+# （范围名）里程碑
+
+> **范围**：（用户语义说明；未指定时写「整个项目」）  
+> **生成时间**：`YYYY-MM-DD`  
+> **索源**：req-docs · git 命令/tag · `.task` 路径 · 知识库主题（`manifest-routing` / `index.md` 主题一览及本轮所读 `topics/*.md`）
+
+## 总览
+
+| 阶段 | 时间 | 一句话 |
+| --- | --- | --- |
+| M1 （功能变更摘要） | YYYY-MM | （可验证的功能交付，须可被索源支撑；非联调/测试/验收） |
+| M2 … | … | … |
+
+## M1 · （阶段标题）
+
+- **交付**：（列表，可验证）
+- **依据**：（可选）req `…` · commit `hash` · task `…`
+
+## M2 · …
+
+（结构同 M1；总览表中每一行 Mx 须有对应二级标题。）
+
+## 待确认
+
+- （三源不一致或缺记录时列出；无则写「无」）

package/templates/skills/f2s-doc-milestone/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: f2s-doc-milestone
+description: 据 req-docs、git log、.task 与知识库主题语义生成里程碑（《项目里程碑模版》）；触发：f2s-doc-milestone、生成项目里程碑、里程碑。命令后可附语义化范围。本技能固定子 agent 生成、主 agent 验证，不受 flow2spec.config 编排开关影响
+---
+
+> 执行口径：读 `.Knowledge/template/项目里程碑模版.md`；落盘 **仅** `.Knowledge/stock-docs/<范围名>里程碑.md`（无第二路径参数）。
+
+## 编排（固定，不受项目配置影响）
+
+**本技能不受** `flow2spec.config.json` 中 **`subAgent`**、**`switchAgentVerification`**（及旧键 `subAgentVerification`）**影响**：无论其为 `true` 或 `false`，**一律**按下述分工执行，**禁止**因配置改为「全主会话」或「子 agent 自验即结束」。
+
+| 角色 | 步骤 | 职责 |
+| --- | --- | --- |
+| **主 agent** | 0、3、4 | 读模版与知识库主题索引、解析范围、派子、**验证**、必要时修订、回复用户 |
+| **子 agent** | 1、2 | 采集四源、套模版、**Write 初稿** |
+
+1. **主 agent**：步骤 0 → 下发「采集契约」→ 子 agent 步骤 1–2 落盘初稿。
+2. **主 agent**：步骤 3 对照四源与「重要节点清单」验证（不全文重写；补缺、纠偏、「待确认」）→ 步骤 4 回复。
+3. 子 agent **禁止**宣称「里程碑已验收完成」；终稿以主 agent 验证后为准。
+
+> 步骤 0 仍 **`Read("flow2spec.config.json")`**（满足 `f2s-config-check` 前置），但**不得**用其中的 `subAgent` / `switchAgentVerification` 改变本技能编排。
+
+**子 agent 采集契约（主 agent 派子前写入 prompt）**
+
+| 字段 | 内容 |
+| --- | --- |
+| `scope` | 用户语义范围一句 |
+| `outputPath` | `stock-docs/<范围名>里程碑.md` |
+| `sources` | 见下文「四源」；**须含知识库主题语义** |
+| `template` | `.Knowledge/template/项目里程碑模版.md`（不写模版顶部说明 blockquote） |
+| `delivery` | 完整 Markdown，可直接 `Write` 至 `outputPath` |
+| `stagePolicy` | 见下文「阶段粒度」；契约中须复述一句 |
+
+## 阶段粒度（必须，写入契约）
+
+里程碑 **Mx 仅记录功能/能力变更**：当前仓库（或用户指定范围内）**已落地或可核验**的交付，例如模块/接口/数据模型/领域行为/知识库路由等，且须在四源中有依据。
+
+**不得**单独占一行总览或独立 `## Mx ·` 的阶段类型（无四源交付支撑时禁止臆造；有交付也不得拆成「纯测试/纯联调」阶段）：
+
+- 联调、集成测试、UAT、回归、验收、提测、上线检查（仅过程、无功能 diff）
+- 仅环境/运维动作（执行 DDL、填配置、发版窗口、跨仓排期）且**无**本范围功能交付
+- 以「稳定化 / 工程化 / 收尾」为名、实质仅为上述过程性工作的阶段
+
+**合并规则**：同一次能力迭代内的工程性改动（如 id 类型对齐、分页格式、锁与并发）**并入**对应功能阶段正文，不另起「联调 / 测试 / 验收」阶段。
+
+**缺口处理**：四源仅提及待联调、待验收、环境待补齐而无本范围功能交付 → **不写**对应 Mx；可在 **待确认** 列一句，**禁止**用「计划项」填充总览表。
+
+## 四源（采集与验证均须覆盖）
+
+| 源 | 读什么 | 里程碑里怎么用 |
+| --- | --- | --- |
+| **req-docs** | 范围内 `.Knowledge/req-docs/*.md` | 需求/方案节点、交付摘要 |
+| **git** | `git log --no-merges`、`git tag -l`、`package.json` 版本 | 时间线、大版本/tag、提交锚点 |
+| **`.task`** | `todo.json`、`active/`、`completed/` 下 `task.md` 等 | 任务闭环、已交付步骤 |
+| **知识库主题（语义）** | 见下「主题索源」 | 与 index/manifest 已登记能力对齐，避免漏写「库里已有语义」的阶段 |
+
+### 主题索源（知识库语义，主 agent 步骤 0 须读；子 agent 步骤 1 须读）
+
+1. **`Read(".Knowledge/manifest-routing.json")`**：提取 `topicPaths`、`taskToTopicRules`（及与范围相关的 `topicDependencies`）。
+2. **`Read(".Knowledge/index.md")`**：至少「**主题一览**」表（主题 id、适用场景、关联文档摘要）。
+3. **按需 `Read` `.Knowledge/topics/<topic>.md`**：与范围或 manifest 命中相关的摘要（**禁止**为枚举遍历整个 `topics/`；仅读 manifest/index 已点名的主题，通常 ≤ 全表行数）。
+4. 将主题语义归纳为「能力/场景节点」列表，供子 agent 写入契约；里程碑阶段须能覆盖或于「待确认」说明与某主题相关的缺口。
+
+文首 **「索源」** 一行须写明：本轮读了哪些 topic（id 或 `topics/*.md` 路径），或「无 `.Knowledge` 路由」。
+
+## 入参（仅一个，可选）
+
+命令名之后可跟**一段语义化范围**（自然语言）：
+
+| 用户意图 | 示例 | 落盘文件名 |
+| --- | --- | --- |
+| 整个项目（默认） | 不传 / `整个项目` / `全项目` | `项目里程碑.md` |
+| 某一需求或能力 | `支付回调改造` / `登录模块` | `<简述>里程碑.md` |
+
+**文件名规则**：后缀 `里程碑.md`；整个项目 → 前缀 `项目`；单一需求 → 语义或 req 标题简述（≤ 20 字）。
+
+**范围收窄**：在四源上按关键词、路径、日期过滤；未传范围则四源全量可追溯（主题索源读 index 全表 + manifest，topics 按需展开）。
+
+## 步骤 0：前置（主 agent）
+
+1. **`Read("flow2spec.config.json")`**（不采纳其 `subAgent` / `switchAgentVerification` 编排本技能）
+2. **`Read(".Knowledge/template/项目里程碑模版.md")`**
+3. **主题索源**（见上：manifest → index 主题一览 → 按需 topics 摘要）
+4. 解析范围 → 确定默认路径 **`stock-docs/<范围名>里程碑.md`**。
+5. **相似文件检查（落盘前必做）**：列出 `.Knowledge/stock-docs/` 下已有 `*里程碑*.md`（含 `*里程碑.md`）。若存在与本次**目标路径相同**或**语义相近**的文件（例如同为「整个项目」的 `项目里程碑.md` 与另一份全项目里程碑、或前缀/范围关键词高度重叠），**须先询问用户**，**禁止**静默覆盖或擅自另存：
+   - **覆盖**：沿用原路径，子 agent 写入时覆盖该文件（验证后仍以该路径为终稿）。
+   - **另生成一份**：改用新路径（建议：范围简述 + `_YYYYMMDD` + `里程碑.md`，或用户指定的 `<简述>里程碑.md`），并在契约中更新 `outputPath`。
+   - 无相似文件，或仅有一个且与目标路径完全一致且用户本轮已明确要「重新生成/覆盖」→ 可不再追问，按默认路径继续。
+6. 向用户复述：范围、**最终** `outputPath`、已读主题数量；若做了相似文件询问，待用户选择后再继续。
+7. 组装「采集契约」（含最终 `outputPath`、主题节点列表）并 **派子 agent** 执行步骤 1–2
+
+## 步骤 1：采集索源（子 agent）
+
+- 按契约完成 **四源** 采集；git **须** 对照 tag 与主版本/semver 跃迁（以本仓库 `git tag` / `package.json` 为准）。
+- 主题语义：核对 manifest/index 中能力与 git/req/task 是否同窗出现；暂无法对齐的记入内部备注供「待确认」。
+
+索源为空：仍生成文档，「待确认」说明缺口；**禁止**训练数据填交付。
+
+## 步骤 2：套模版并落盘（子 agent）
+
+1. `# （范围名）里程碑`；文首范围、时间、**索源（含本轮 topics）**。
+2. 时间升序 **M1、M2…**；总览表与各 `## Mx ·` 一一对应；**每阶段标题与一句话须体现功能变更**，不得用「联调 / 测试 / 验收」作阶段名（见「阶段粒度」）。
+3. 不写模版顶部说明 blockquote。
+4. **`Write`** 至 `outputPath`。
+
+## 步骤 3：验证（主 agent，须执行）
+
+子 agent 落盘后 **必须**验证：**重要节点**是否错误、遗漏或合并过度。
+
+1. **重读四源要点**：git tag/commit、req/task、**index 主题一览 + 已读 topics** 与文稿对照。
+2. **对照「重要节点清单」**：
+
+| 类别 | 检查什么 |
+| --- | --- |
+| 版本 / tag | 四源中的 major tag、`package.json` 版本跃迁是否在总览或 Mx 中体现 |
+| 路线/架构转折 | 四源中出现的目录重组、技术路线替换等重大变更是否单独或合并体现 |
+| 功能交付 | req/git/task 中可核验的能力是否在 Mx 中有对应阶段 |
+| **知识库主题** | 若存在 manifest/index：与范围相关的主题是否覆盖或列入「待确认」 |
+| 任务闭环 | 若存在 `.task/`：已归档任务是否在相关 Mx 中体现 |
+| 依据可追溯 | 每 Mx 交付能否在四源中找到 |
+| 时间线 | 先后合理；同窗多版本是否需拆分 |
+| **阶段粒度** | 是否存在仅联调/测试/验收/环境而无功能交付的 Mx；若有 **删除或并入** 相邻功能阶段 |
+
+3. 遗漏 → 补 Mx（**须为功能变更**）；错误 → 按四源修正；无法确认 → 「待确认」（**禁止**用假 Mx 代替）。
+4. 验证或修订完成后方可步骤 4。
+
+## 步骤 4：回复（主 agent）
+
+落盘路径、阶段数、验证结论（一句）、「待确认」摘要。
+
+## 禁止项
+
+- 禁止用 `subAgent` / `switchAgentVerification` 跳过子生成或跳过主验证。
+- 禁止在 `stock-docs/` 已存在**相似里程碑**且用户未选择「覆盖 / 另生成一份」前派子 agent 或 `Write`。
+- 禁止第二参数改输出路径（路径由范围 + 相似文件询问结果确定）；禁止写入 `req-docs`。
+- 禁止未读四源写交付；禁止子 agent 未经验证即宣称完成。
+- 禁止遍历整个 `matchers/` 或全仓 topics 代替「manifest + index + 按需 topics」。
+- 禁止用训练数据或其它项目的里程碑结构替代**当前仓库**四源；禁止代写与本次 `outputPath` 无关的其它 `stock-docs` 文档。
+- 禁止单独设立联调 / 集成测试 / UAT / 验收 / 纯环境运维类 Mx；禁止在无四源功能交付时写「计划项」阶段。