@double-codeing/flow2spec 2.2.0

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

@@ -0,0 +1,85 @@
+---
+name: f2s-doc-final
+description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-ctx-build 生成 Rules、Skills、索引；触发：f2s-doc-final、转成概述模板、终稿模版
+---
+
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# 将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context）
+
+用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-ctx-build** 技能消费的终稿风格 Markdown 文档。
+
+**终稿模版仅作提示**：若存在项目内 **`配置根/template/终稿模版.md`**（或 Flow2Spec 包内的 `templates/template/终稿模版.md`），可读取作为**结构参考与写作提示**，**不强制套用**；输出以原文内容与逻辑为主，按需采纳模版中的章节建议。若项目内无该文件，则按本技能下方「内嵌模板结构」作为可选参考。
+
+## 内嵌模板结构（当项目内无「配置根」下 `template/终稿模版.md` 时使用）
+
+规范要求：
+
+- **一级标题**：方案名（如 `# xxx 技术方案设计`）。
+- **二级标题至少包含**：`## 核心概念`、`## 业务规则`、`## 关键流程`；其余可按需增删（如 状态与流转、接口、配置/表设计/错误码、实现位置与对接方式）。
+- **核心概念**：用表格列出术语、实体、关键 ID（列：概念、说明）。
+- **状态与流转**：若有状态机，用列表写状态及流转；若无可简述或省略。
+- **业务规则**：列表写约束、校验、配置项。
+- **关键流程**：按「用户侧或系统侧」主流程，列表写流程名、步骤简述、入口接口/方法、结果。
+- **可选章节**：接口、配置/表设计/错误码、实现位置与对接方式，按需保留并填写。
+
+---
+
+## 流程一：用户传入的是 Markdown（.md）
+
+1. **读取**用户传入的 `.md` 文件内容。
+2. **参考格式**（不强制）：若存在 `配置根/template/终稿模版.md` 或包内 `templates/template/终稿模版.md`，可读取作为结构提示；否则可参考下方内嵌模板结构。**不强制套用**，以原文信息完整、逻辑清晰为主。
+3. **分析与转换**：
+  - 理解原文主题与结构，提炼「方案名」「核心概念」「业务规则」「关键流程」及与原文相关的其他章节（如状态与流转、接口、配置/表设计/错误码、实现位置等）。
+  - 将内容重组为结构清晰的终稿风格 Markdown：一级标题为方案名；建议至少包含 核心概念、业务规则、关键流程 三个二级标题，其余按原文有无与需要增删；表格/列表格式可参考模版，不必完全一致。
+  - 若原文缺少某节，可标「（待补充）」或根据原文推断补全；若原文结构已清晰，可保留原文章节命名。
+4. **输出**：
+  - 默认写入 `**配置根/stock-docs/<方案名>_终稿.md**`（方案名由一级标题或文件名推断，做合法文件名处理；**最终产物带 `_终稿` 标识**）。
+  - 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。
+5. **回复**：告知用户已生成 `配置根/stock-docs/<方案名>_终稿.md`，并提示可按 **f2s-ctx-build** 技能、以 `配置根/stock-docs/<方案名>_终稿.md` 为入参生成 Rules、Skills。
+
+---
+
+## 流程二：用户传入的是 PDF（.pdf）
+
+分两步完成：**先 PDF → 初稿 MD，用户确认后再 初稿 MD → 模板格式 MD**。
+
+### 步骤 A：首次执行（传入 PDF 路径）
+
+1. **尝试读取 PDF**：按用户传入路径读取 PDF（可为绝对路径，或相对**配置根的父目录**；如 `配置根/stock-docs/xxx.pdf`）。
+  - 若当前环境可解析 PDF 文本：提取正文，转为 Markdown 初稿（保留标题层级、列表、段落，表格若可识别则保留）。
+  - 若无法直接读取 PDF（如仅能拿到二进制）：回复用户「当前无法直接解析 PDF，请任选其一：① 将 PDF 内容复制粘贴到项目内 `配置根/stock-docs/xxx.md`，再执行本技能并传入该路径；② 使用本地工具将 PDF 转为 .md 后，把 .md 路径传入本技能。」
+2. **生成初稿**：
+  - 将提取出的内容保存为 `**配置根/stock-docs/<方案名>_初稿.md**`（方案名可从 PDF 文件名或首标题推断）。
+  - 在回复中**展示初稿的全文或主要结构**，并明确说明：
+    - 「初稿已保存为 `配置根/stock-docs/<方案名>_初稿.md`，请检查并修改。」
+    - 「确认无误后，请执行：`**f2s-doc-final 技能 配置根/stock-docs/<方案名>_初稿.md**`，将自动转换为《终稿模版》规范格式。」
+3. **本轮不进行模板格式转换**，仅完成 PDF → 初稿 MD。
+
+### 步骤 B：用户确认后再次执行（传入初稿 .md 路径）
+
+当用户**再次执行本技能并传入初稿的 .md 路径**（如 `配置根/stock-docs/技术方案设计_初稿.md`）时：
+
+- 按 **「流程一：用户传入的是 Markdown」** 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。
+- **输出建议**：生成 `**配置根/stock-docs/<方案名>_终稿.md**`（与初稿同方案名，最终产物带 `_终稿` 标识），作为最终规范版；初稿文件可保留供对比，或在回复中提示用户可自行删除 `_初稿.md`。
+- **回复**：告知已生成规范版 `配置根/stock-docs/<方案名>_终稿.md`，并提示可按 **f2s-ctx-build** 技能、以该路径为入参生成 Rules、Skills。
+
+---
+
+## 路径与输出约定
+
+- 所有路径均相对于**配置根的父目录**；初稿/终稿等统一放在 **配置根** 下的 **`stock-docs/`** 目录内（存量上下文源，供 **f2s-ctx-build** 技能使用）。
+- **输入**：用户传入的**第一个参数**为文件路径（必填），如 `配置根/stock-docs/方案.pdf` 或 `配置根/stock-docs/方案_初稿.md`；**第二个参数**（可选）为输出路径，若提供则覆盖默认输出位置。
+- **输出**：
+  - PDF 首次：`配置根/stock-docs/<方案名>_初稿.md`
+  - MD 或初稿 MD（最终产物）：`配置根/stock-docs/<方案名>_终稿.md`（若用户传入第二参数为输出路径，则用该路径）。
+- 若 `配置根/stock-docs/` 目录不存在，先创建再写入。
+
+---
+
+## 约束与注意
+
+- 转换时**不要照抄原文**，要按模板**提炼、归纳、补全**，使核心概念、业务规则、关键流程清晰可查。
+- 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
+- 完成后用一句话总结：已生成 xxx（初稿路径或终稿路径 `配置根/stock-docs/<方案名>_终稿.md`），并说明下一步建议（确认后再次执行本技能，或按 **f2s-ctx-build** 技能以终稿路径为入参）。
+

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

@@ -0,0 +1,63 @@
+---
+name: f2s-doc-pdf
+description: 将 PDF 技术方案转为 Markdown 并保存到 req-docs，可补全流程说明；触发：PDF转MD、按方案实现前的 PDF
+---
+
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# 将 PDF 技术方案文档转为 Markdown（并补全流程说明）
+
+用户会在本技能后附带**一个参数**：**PDF 技术方案文档的本地路径**（如 `~/Downloads/技术方案.pdf`，或已落在 **配置根** 下的 **`req-docs/某草稿.pdf`**）。请按以下步骤执行，将 PDF 技术方案文档转为 Markdown 并保存到**配置根 `req-docs/`** 下，必要时引导用户补全流程说明。
+
+## 步骤 1：读取 PDF 并转为 Markdown
+
+1. **读取**用户传入的 PDF 文件，提取其中的**文字内容**（表格、章节、列表、代码块等尽量保留结构），整理为 Markdown 格式。
+2. **保存到配置根下** `req-docs/`，推荐路径：`**配置根/req-docs/<方案名>.md**`（如 `.cursor/req-docs/xxx.md`；技术方案用于「按方案实现代码」；**`stock-docs/`** 用于生成 Rules/Skills 的源文档，不用于实现）。文件名为原 PDF 文件名去掉 `.pdf` 后加 `.md`。
+3. 若配置根下尚无 **`req-docs/`**，可先创建再写入（`flow2spec init` 会预建该目录）。
+4. 保存后告知用户：「已将该 PDF 转为 Markdown 并保存为 `xxx.md`。」
+
+---
+
+## 步骤 2：向用户提问获取流程图（可选但推荐）
+
+PDF 内嵌的**流程图**无法被直接解析为步骤与分支，若需按图实现代码，需用户配合提供。
+
+1. 向用户说明：「文档中可能包含流程图，我无法从 PDF 中解析图中的步骤与分支。若您后续会根据技术方案实现代码（见 配置根/rules/implement-tech-design.mdc），建议补全流程说明：
+  - **方式一**：将相关流程图以**图片形式**发到本次对话中，我将解析后以文字形式写入上述 MD；  
+  - **方式二**：直接以**文字描述**每个接口/流程的步骤（如：1. 是否登录 2. 查某表 3. 判断某字段 → 返回结果），我将原样写入上述 MD。  
+   若文档无流程图或暂不提供，可回复「跳过」，我将结束本技能。」
+2. **若用户回复「跳过」或明确表示无需流程说明**：告知用户「在对话中提供上述 MD 路径，并说明要按该技术方案实现代码，我将按 **配置根/rules/implement-tech-design.mdc** 执行。」并结束。
+3. **若用户提供流程图（图片或文字）**：进入步骤 3。
+
+---
+
+## 步骤 3：将流程说明写入该 MD
+
+1. 若用户提供的是**图片**：解析图片中的步骤、判断分支与返回，整理为文字步骤。
+2. 若用户提供的是**文字**：直接采用。
+3. 在该 MD 文件末尾（或新增「流程说明」章节）**追加**流程内容，格式示例：
+
+```markdown
+## 流程说明（由用户提供 / 由流程图解析）
+
+### 示例接口 A
+1. 前端发起请求
+2. 后端：查询某表最后一条记录
+3. 判断：是否有某 ID？是 → 返回 true，否 → 返回 false
+4. 返回结果
+
+### 示例接口 B
+1. 是否登录 → 否 返回 401
+2. 是否过期 → 是 返回 403
+…
+```
+
+1. 保存后告知用户：「流程说明已写入 `xxx.md`。接下来请在对话中提供该 MD 路径并说明要按技术方案实现代码，我将按 **配置根/rules/implement-tech-design.mdc** 执行。」
+
+---
+
+## 约束与小结
+
+- **路径**：用户传入的 PDF 路径可为绝对路径或相对于配置根的父目录的路径。输出 MD 建议保存在 **`配置根/req-docs/<方案名>.md`**（如 `.cursor/req-docs/...`；**`req-docs/`** 在配置根下，放需要实现成代码的技术方案；**`stock-docs/`** 放生成 Rules/Skills 的存量源文档）。
+- **本技能仅负责**：PDF → Markdown 转换 + 可选流程说明补全；不执行代码实现。完成后可提示用户：在对话中提供生成的 MD 路径并说明按技术方案实现，AI 将按 **implement-tech-design.mdc** 执行。
+

package/templates/skills/f2s-kb-feat/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: f2s-kb-feat
+description: 新增能力时补全实现与文档；已实现则仅基于实现与规则补充文档；触发：f2s-kb-feat、新增能力
+---
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# /新增能力（f2s-kb-feat）
+
+当用户需要新增一个能力（功能、模块或约定）时，补全实现与文档；若该能力已实现，则基于现有实现与项目规则补充、对齐文档，使能力可被复用、可被 AI 与后续开发遵循。
+
+**输入**：用户描述「要新增什么能力」。例如：
+
+- 「新增一个 XX 能力，需要…」
+- 「加一个 Y 模块，用来…」
+- 「支持 Z 场景，需要…」
+
+用户可附带**范围**（如目录、模块、路径）或设计文档路径。
+
+**步骤**
+
+1. **理解需求与现状**
+   - 明确要新增的**能力**（功能点、入口、约定等）。
+   - 判断是否已有**部分或全部实现**：搜索相关代码与文档。
+   - 若需求不清或与现有实现冲突，可先询问用户再继续。
+
+2. **补全实现（若尚未实现或未完成）**
+   - 按项目既有目录与约定实现，遵循现有规则（rules）与技能（skills）；实现后与规则、技能保持一致。
+
+3. **补充/对齐文档**
+   - **项目文档**：在约定的文档目录中新增或修订与能力相关的小节，写清能力说明与使用方式；若有主文档索引则引用。
+   - **规则（Rules）**：若该能力引入新的项目级或模块级约定，在 `配置根/rules/` 下新增或更新规则，写清适用范围（目录/globs）与必须/禁止项。
+   - **技能（Skills）**：若该能力需要被 AI 或后续开发频繁引用，在 `配置根/skills/` 下新增或更新 Skill，写清触发词、能力摘要与使用方式，便于检索与遵循。
+
+4. **（若已实现）基于实现反推文档**
+   - 梳理现有代码与调用关系，归纳能力入口与行为；将结果写入文档、规则与 Skill，与现有风格一致。不修改已有实现，只补文档与规则。
+
+5. **输出摘要**
+   - **能力**：新增/补全了哪些能力点。
+   - **实现**：涉及的文件与改动（若未改动实现则说明「实现已存在，未改代码」）。
+   - **文档**：新增/修订了哪些文档路径与小节。
+   - **规则 / Skill**：新增或更新了哪条 rule、哪个 skill。
+
+**输出格式示例**
+
+```markdown
+## 新增能力：<能力简述>
+
+### 能力说明
+
+- <要点 1>
+- <要点 2>
+- …
+
+### 实现
+
+- <路径>：<说明>（若未改代码：实现已存在，仅补充文档）
+- …
+
+### 文档
+
+- <文档路径>：新增/修订「…」小节
+- …
+
+### 规则 / Skill
+
+- <规则路径>：新增/更新 — …
+- <Skill 路径>：新增/更新 — 触发词：…
+```
+
+**约束**
+
+- 实现须符合项目既有规则与技能；有冲突时以项目规则为准，必要时在文档中注明。
+- 至少补充文档；能力为项目级或会复用时，建议同时更新规则与 Skill。
+- 已实现的能力：只补文档与规则，不改代码；实现与约定不符时可单独指出或走修正规则流程。
+
+**何时使用**
+
+- 用户表达要「新增能力」「加功能/模块」或「支持某场景」时。
+- 能力已实现但文档不全，用户希望按实现与现有规则补全文档时。

package/templates/skills/f2s-kb-fix/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: f2s-kb-fix
+description: 根据用户指出的实现规则错误，修正代码并同步更新文档与全局规则；触发：f2s-kb-fix、修正实现规则
+---
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+在代码实现后，若用户指出某处违反了项目规则或约定，则修正实现并同步更新相关文档与全局规则，使该约定被明确记录、后续实现与 AI 可遵循。
+
+**输入**：用户描述「哪里错了、应遵循什么规则」。例如：
+- 「某处违反了 XX 规则，请改掉并补充到规则里」
+- 「Y 模块下所有 Z 的写法错了，应该是…」
+- 「只改某目录 / 某类文件」
+
+用户可附带**范围**（如具体目录、文件或「全项目同类写法」）。
+
+**步骤**
+
+1. **解析用户指出的问题**
+   - 明确违反的**规则或约定**（正确写法 vs 当前错误写法）。
+   - 明确**范围**：具体文件、目录或「全项目同类写法」。
+   - 若范围不清，可询问用户后再继续。
+
+2. **修正代码**
+   - 在范围内按正确写法修改所有相关位置（编辑文件）。
+   - 若用户表达为「所有这类」或规则为全局性，可搜索代码库中同类错误写法并一并修正。
+
+3. **更新相关文档**
+   - 判断与该约定相关的文档（项目约定的文档目录，如 `配置根/stock-docs`、`req-docs` 等）。
+   - 在文档中新增或修订一小节，写清该约定，必要时注明对应 rule/skill。
+
+4. **更新全局规则与 Skill**
+   - 若该约定为项目级或模块级：
+     - 在项目约定的规则目录（如 `配置根/rules/`）下新增或更新一条规则，写清「必须/禁止」及适用范围（globs 等）。
+     - 在项目约定的技能目录（如 `配置根/skills/`）下新增或更新一个 Skill，写清触发词与正确/错误示例，便于后续实现与 AI 按规则执行。
+   - 规则与 Skill 中可引用文档作为约定出处。
+
+5. **输出摘要**
+   - **代码**：修改了哪些文件、改了什么。
+   - **文档**：更新了哪些路径、新增/修订了哪一节。
+   - **规则/Skill**：新增或更新了哪条 rule、哪个 skill。
+
+**输出格式示例**
+
+```markdown
+## 修正：<规则简述>
+
+### 代码
+- <路径>：<具体修改说明>
+- …
+
+### 文档
+- <文档路径>：新增/修订「…」小节
+- …
+
+### 规则 / Skill
+- <规则路径>：新增/更新 — …
+- <Skill 路径>：新增/更新 — 触发词：…
+```
+
+**约束**
+- 范围不明时：按最可能范围（如用户提到的模块或近期改动的文件）修正，并说明「若其他位置也有同类写法，可再说，我一起改」。
+- 至少更新「文档、规则、Skill」中的一类，使约定被书面化。
+- 一条约定优先对应一条规则 + 一个 Skill；若已有合适 rule/skill 文件，在其上增补即可。
+
+**何时使用**
+- 实现完成后，用户指出「这里违反规则」「写错了」「应该按 XX 约定来」时。
+- 用户希望既改代码，又把规则沉淀到文档与 Cursor（rules/skills）以便以后统一遵循时。

package/templates/skills/f2s-kb-merge/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: f2s-kb-merge
+description: 解决 Git 合并后编辑器上下文冲突；可选传入冲突文件；实现侧冲突仅罗列待用户确认；触发：合并上下文冲突、f2s-kb-merge
+---
+
+# /合并上下文冲突（f2s-kb-merge）
+
+在 **rebase / merge** 后出现 `<<<<<<<` / `=======` / `>>>>>>>` 时，优先**自动合并「AI 与开发者上下文」相关文件**，保证索引、规则、技能与说明文档互相对齐；**涉及可执行实现、部署或依赖声明的冲突不擅自合并**，需**向用户展示双方差异并等待确认**后再改。
+
+## 传参（可选）
+
+- **不传参**：在工作区内**自行检索**仍存在冲突标记的文件，再按本技能分类与策略处理（含全量扫描后的摘要）。
+- **传参**：用户可指定**一个或多个仍含冲突的文件**（随消息 @ 文件或列出路径均可）。助手**优先只处理这些文件**中的冲突；若其中含「禁止自动合并」类别，仍只罗列差异与建议，**不擅自写入**。指定文件处理完毕后，可询问用户是否需要对工作区做**补充扫描**。
+
+## 适用范围（可自动合并）
+
+以下**类别**内的冲突，按本技能**合并策略**处理，**无需**逐行征求确认（除非两侧表述**互斥**且无法判断应以何为准）：
+
+| 类别                 | 说明                                                                 |
+| -------------------- | -------------------------------------------------------------------- |
+| 文档索引             | 承载「文档 ↔ 规则 / 技能」映射的索引表文件                           |
+| 项目总览规则         | 规则目录中的总入口文件                                               |
+| 模块规则             | 同套规则目录下的其余规则片段                                         |
+| 技能                 | 技能目录下的 SKILL 说明文件                                          |
+| 上下文说明文档       | 与规则、技能配套的说明类 Markdown                                    |
+| 索引联动的纯说明文档 | 由项目约定存放、仅被索引或规则引用、**不含可执行实现语义**的说明文档 |
+
+## 禁止自动合并（须用户确认）
+
+以下冲突**不得**在未获用户明确选择前合并：
+
+- **应用或服务实现源码**（业务逻辑、接口实现、数据访问等）
+- **会改变对外暴露行为**的配置（路由、函数注册、中间件链、运行入口等）
+- **依赖与构建元数据**（依赖声明、锁文件、构建与部署脚本等）
+- **集中维护外部资源清单的实现模块**：若两侧**条目集合或注册内容不同**，属运行行为差异，须用户确认保留范围（助手可建议「并集 + 去重」，**待用户同意**后再写入）
+
+**处理方式**：列出冲突文件、简述两侧意图，给出推荐方案，**请用户选定**后再改上述范围中的文件。
+
+## 合并策略（上下文类）
+
+1. **删除所有** Git 冲突标记（`<<<<<<<` / `=======` / `>>>>>>>`），不得残留。
+2. **索引表**
+   - 同一索引行的 **Rules / Skills / 链接列**：做**并集**，路径去重、空格分隔。
+   - 仅在一侧出现的**独立索引行**：合并后**保留**，避免丢失条目。
+3. **总览规则**
+   - 同一主题下多条 bullet：合并为**信息完整的单条或并列多条**，**不丢弃**任一侧独有的约束或引用。
+4. **长文档中的表格**
+   - 描述**不同维度能力**的行：**并集保留**。
+   - 描述**同一主题**的重复行：合并为**一条**连贯表述，涵盖两侧要点。
+5. **rules / skills**
+   - 优先保留**更具体、约束更清晰**的表述；另一侧独有的**必须 / 禁止**条款**并入**，避免规则回退。
+6. **链接与路径**
+   - 统一为仓库内可解析的相对路径，并与总览规则中的索引入口一致。
+
+## 执行步骤
+
+1. **确定范围**：若用户已指定冲突文件，仅以这些文件为范围；否则全工作区检索冲突标记（或结合 IDE 冲突列表）。再按**适用范围**分类。
+2. **上下文类**：按合并策略直接修改并保存。
+3. **实现类**：只输出对比摘要与建议，**不修改文件**直至用户确认。
+4. **输出摘要**（Markdown）：已解决文件 + 要点；待确认文件 + 两侧差异 + 建议。
+5. 对**已处理文件**再次确认**无**冲突标记残留；若未做全量扫描，可提示用户是否补充扫描。
+
+## 与相关命令的关系
+
+- **`/修正实现规则`（f2s-kb-fix）**：用户已指明问题点后的**定向修正**与文档/规则同步。
+- **本技能**：合并产生的**批量冲突**，侧重**编辑器上下文与说明文档**同**实现侧**分离处理。
+
+## 何时使用
+
+- merge / rebase 后，**规则 / 技能 / 索引 / 配套说明文档**出现冲突（可全量处理，也可只处理用户指定的冲突文件）。
+- 需要一次性对齐「索引 ↔ 规则 ↔ 技能 ↔ 说明文档」，且**避免误合并实现或部署相关改动**时。

package/templates/skills/f2s-kb-sync/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: f2s-kb-sync
+description: 可将「Agent 已实现的能力」写清传入，也可零输入；零输入时由 Agent 根据当前上下文推断用户与项目关心的能力，先输出知识库更新大纲、确认后写入 Rules/Skills/索引以注入上下文；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力
+---
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# f2s-kb-sync（知识库同步 · 先大纲后写入）
+
+在用户要执行 **f2s-kb-sync** 时：把**用户本次描述**、**当前 Agent / 会话角色相关描述**、**与项目相关的功能与约定**、以及**要注入上下文的「能力」集合**（见下文「输入」）整理为对**知识库**的更新方案；**必须先输出「更新大纲」并征得用户明确确认**，再写入 **`rules/`**、**`skills/`**（在既有结构上**增补或修订**，不无故整目录删除模板技能）、**`docs-index.md`**、**`main.mdc`** 等，使这些能力在后续对话中可被 **Rule / Skill / 索引** 加载，即**注入到 Agent 可用上下文**。可选在 **`stock-docs/`** 增加简短摘录类 MD 作为索源（若需要且大纲已列明）。
+
+**知识库**在本技能中指：供 AI 持续使用的**项目侧上下文产物**——主要是 **`rules/*.mdc`**、**`skills/*/SKILL.md`**（项目自增的 skill 或既有 skill 的正文补丁）、**`docs-index.md`**、**`rules/main.mdc`**，以及为索源服务的 **`stock-docs/*.md`**（按需）。
+
+---
+
+## 输入（均可选；能力来源二选一或组合）
+
+### 1）用户指定「Agent 已实现的能力」（可选）
+
+- 用户可在消息中**明确列出**当前 Agent（或本会话）**已经具备 / 已经实现**的能力：例如条目列表、模块名、命令或技能名、可回答的问题类型、已接好的 MCP/工具等。
+- 若用户写了这部分：将其视为**高优先级事实**，写入大纲中的 **「用户指定的能力清单」**，与下文推断结果**对齐、合并、去重**；冲突时以**用户本次明确文字**为准。
+
+### 2）零输入或仅少量补充（可选）
+
+- 用户**可以不输入任何内容**（或只 `@` 个别文件、只说一句「同步一下」等）。
+- 此时 **Agent 必须自行判断**：在当前上下文（**本轮对话**、**用户已打开或引用的文件**、**工作区与项目结构**、**已有 `docs-index` / `main` / rules / skills**）下，**用户与项目最关心、最常被依赖的能力**是哪些。
+- 推断要求：
+  - 给出**简短依据**（例如：来自哪几条用户原话、哪个目录、哪份文档标题），写进大纲的 **「Agent 推断：关心的能力」** 小节，便于用户核对。
+  - **宁缺毋滥**：只纳入与后续协作强相关、可写成可维护规则/技能条目的能力；忌泛泛「会写代码」类空话。
+  - 若上下文极薄、无法合理推断：在大纲中如实写「推断受限」，并列出**为完成同步请用户补充的最少信息**（一两问即可），仍**先出大纲再请确认**，不要无确认写库。
+
+### 3）其它常见输入（仍可选）
+
+- **用户自然语言**：本次想同步什么、强调哪些模块或约定、对 Agent 的期望等。
+- **路径/附件**：如 **`配置根/req-docs/xxx.md`**、**`配置根/stock-docs/xxx.md`**、README、架构说明等；用户也可用 `@` 引用文件。
+
+---
+
+## 执行步骤（顺序不可颠倒）
+
+### 步骤 1：收集素材（只读与归纳，不写知识库）
+
+1. **能力集合**（本步核心）  
+   - 若用户**已指定**「Agent 已实现的能力」：逐条收录，并标为 **「用户指定」**。  
+   - 若用户**未指定**或指定不全：**由 Agent 根据当前上下文推断**「用户与项目关心的能力」，标为 **「Agent 推断」**，每条附**一句依据**（对话原句 / 路径 / 文件角色）。  
+   - 合并为本次要注入知识库的 **「目标能力列表」**（去重；用户指定与推断冲突时以用户指定为准）。
+2. **用户侧**：整理用户消息中的目标、范围、术语、约束、验收或优先级；若用户声明了「当前 Agent 身份/模式/回答风格」等，单独摘录为「Agent 描述」小节素材。
+3. **项目侧**（在合理范围内浏览/检索，避免全仓无目的扫描）：例如 **`README`**、**`package.json`**、顶层目录、与对话相关的源码路径；读取 **`配置根/docs-index.md`**、**`配置根/rules/main.mdc`**（若存在）以了解现有知识库结构，避免重复或冲突。
+4. **功能与约定**：围绕 **「目标能力列表」**，归纳**业务能力、模块边界、接口/MQ/配置习惯**等（只写从文档与代码中可支撑的结论；不确定处在大纲标「待确认」，不写进最终落库正文，除非用户在大纲确认中一并认可）。
+
+### 步骤 2：输出「更新大纲」（必须；此步结束前禁止写任何知识库文件）
+
+向用户输出一份清晰的 **Markdown《知识库更新大纲》**，建议包含：
+
+1. **同步目标**：一两句话说明本次更新解决什么问题（含：要把哪些**能力**注入可加载上下文）。
+2. **能力清单**（必填小节）：  
+   - **用户指定的能力**（若无则写「无」）；  
+   - **Agent 推断：用户与项目关心的能力**（若无则写「无」或「推断受限」+ 需补充的问题）；  
+   - **合并后的目标能力列表**（最终将以知识库条目支撑的能力）。
+3. **信息来源**：列出已依据的用户原话要点、Agent 描述要点、项目文件/路径（不必贴全文）。
+4. **拟变更清单**（逐项、可到路径级）：
+   - **rules**：拟新建或修改的 `.mdc` 路径 + 每处「改什么 / 为什么」。
+   - **skills**：拟新建子目录与 `SKILL.md` 或拟修改的现有 `SKILL.md` + 每处「改什么 / 为什么」。
+   - **docs-index / main**：是否增删行、是否更新模块一览等。
+   - **stock-docs**（可选）：是否新增摘录类 MD、文件名建议、是否后续再走 **f2s-ctx-build**（若需从终稿生成大套 Rules/Skills，应在大纲中单独列为可选阶段）。
+5. **不做的事**：明确写出本次**不会**改动的范围（如业务源码、依赖版本、未在大纲中的文件），避免用户误解。
+6. **确认提示**：用单独一段请求用户回复，例如：「请回复 **确认** 按大纲执行」「或回复修改意见（指出要删/要改的条目）」。
+
+**禁止**：在用户确认前创建、覆盖或删除 **`配置根/rules/`**、**`配置根/skills/`** 下任何文件，以及 **`docs-index.md`**、**`main.mdc`**（本步骤仅输出大纲）。
+
+### 步骤 3：用户确认后再写入（注入上下文）
+
+- 仅当用户**明确确认**大纲（或确认经用户要求修订后的新版大纲）后，再按大纲**逐项**实施写入。
+- **注入的含义**：通过新增/更新 **`rules/`**、**`skills/`**、**`docs-index.md`**、**`main.mdc`**（及按需 **`stock-docs/`**），使 **「目标能力列表」** 在后续会话中以 **globs / description / 索引** 等形式被 Cursor（或当前工具）加载，而不是只在当轮对话记忆里存在。
+- 写入 **`rules/`**、**`skills/`** 时遵守项目既有风格与 frontmatter；若涉及从 **`stock-docs/`** 链出或写 **sourceDoc**，遵守 **`f2s-ctx-build`** 技能中的「文档路径与链接约定」（参见 `配置根/skills/f2s-ctx-build/SKILL.md`）。
+- 若大纲列有「先 **f2s-doc-final** / **f2s-ctx-build**」等后续技能：在本技能完成**已确认**的写入后，再引导用户按需触发对应技能，**不要**在本技能内跳过确认擅自执行长链路。
+
+### 步骤 4：收尾摘要
+
+- 列出已写入/修改的文件路径与一句话说明。
+- 若有大纲中未执行项（如用户缩小范围），说明原因。
+
+---
+
+## 约束与注意
+
+- **先大纲、后写入**：无确认则无写库；用户仅说「继续」而未确认大纲时，须再次展示大纲要点并请其明确确认。
+- **克制修改**：优先**小步增补**；避免一次性重写 `main.mdc` 或整表 `docs-index`；与 Flow2Spec 模板自带的 **`skills/`** 工作流文件冲突时，优先**新增**项目专用 rule/skill 文件，而非覆盖模板包名同名文件——除非大纲已写明且用户确认。
+- **与 f2s-kb-fix / f2s-kb-feat 区分**：本技能侧重「会话与项目现状 → 知识库对齐」；针对**已指明的规则违反**用 **f2s-kb-fix**；针对**新增能力**用 **f2s-kb-feat**。

package/templates/skills/f2s-req-backend/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: f2s-req-backend
+description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成后端技术文档；触发：生成后端技术文档、后端技术方案
+---
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# 根据需求生成后端技术文档
+
+用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、优先级等）。你需要**基于当前项目的知识库、配置根/skills、配置根/rules** 理解项目约定与能力，针对该需求输出一份**后端技术文档**。
+
+**用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不用于生成 Rules/Skills。
+
+**结构范本**：技术方案按 `配置根/template/后端技术模版.md` 的章节顺序与书写要求输出。**接口与处理流程写在同一处**：每个接口小节内同时给出契约（请求/返回）与**处理流程**（分步说明、分支与错误码引用），**不要**再单独拆「接口及流程说明」「关联接口调用流程」「流程说明」等大章重复描述同一接口。
+
+---
+
+## 输入
+
+- **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 **`.cursor/req-docs/xxx.md`**、`配置根/stock-docs/需求_终稿.md`）。
+- **后续参数或用户补充（可选）**：需求条件与约束，例如：
+  - 范围（只做某模块、某端）
+  - 必须/禁止使用的中间件、接口风格
+  - 与现有某模块的边界
+  - 性能、安全、合规要求
+
+---
+
+## 输出结构
+
+生成文档时，**按 `配置根/template/后端技术模版.md` 中的章节顺序与书写要求**输出；与需求无关的整节可省略。执行本技能时请**先读取该模版**作为结构与表述参考。
+
+---
+
+## 步骤
+
+1. **读取需求**：从用户提供的路径或正文获取需求内容；若有需求条件，一并纳入。
+2. **加载项目上下文**：主动读取并运用：
+   - `配置根/rules/` 下与接口、配置、MQ、数据等相关的规则；
+   - `配置根/skills/` 下与公共模块、接口约定、QMQ、配置、工具等相关的 Skill；
+   - 项目内已有技术方案；**结构对照 `配置根/template/后端技术模版.md`**。
+3. **对齐项目约定**：接口命名、目录结构、配置中心、QMQ、错误码、表命名等与现有项目一致。
+4. **撰写文档**：按 `配置根/template/后端技术模版.md` 书写；**每个接口下写全处理流程**，避免接口与流程两张皮。
+5. **输出位置**：默认 **`配置根/req-docs/<方案名>_技术方案.md`**（如 `.cursor/req-docs/...`；方案名由需求主题推断）；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。
+
+---
+
+## 约束
+
+- 所有路径相对于**配置根的父目录**。
+- 生成的是**后端技术文档**，不写前端 UI 细节（接口契约与入参出参除外）。
+- 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。
+- **原则**：接口小节 = 契约 + 处理流程，二者不拆章重复；结构以 `配置根/template/后端技术模版.md` 为准。

package/templates/skills/f2s-req-clarify/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: f2s-req-clarify
+description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出技术方案；触发：需求澄清、PRD 澄清
+---
+
+# 需求澄清
+
+**入参**：可选。PRD 全文、需求描述或文档路径（如 **`.cursor/req-docs/xxx.md`**）；不传则按当前对话内容澄清。后续回复可补需求条件。
+
+**行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。
+
+**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 **`.cursor/req-docs/`**。输出完文档后，再提示使用 **f2s-req-backend 技能**（可附带需求条件）生成技术方案，供后续代码实现。不在此阶段输出技术方案或接口设计。

package/templates/skills/stock-docs-vs-req-docs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: stock-docs-vs-req-docs
+description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、配置根文档、PDF 终稿、技术方案放哪、f2s-ctx-build 路径
+---
+
+# stock-docs 与 req-docs（技能）
+
+## 何时使用
+
+- 用户问「文档放哪」「PDF 转完放哪」「生成 Rules 用哪个目录」「技术方案目录」等。
+- 实现或命令执行时需要选择 **`配置根/stock-docs/`** 还是 **`配置根/req-docs/`**。
+
+## 核心对照
+
+| 目录 | 位置 | 用途 |
+|------|------|------|
+| **stock-docs** | 配置根下 | 存量上下文源 → **f2s-ctx-build** 技能、终稿/初稿/架构说明 |
+| **req-docs** | 配置根下（如 `.cursor/req-docs/`） | 需求与技术方案 → 按 `implement-tech-design` **写代码**、f2s-doc-pdf 输出 |
+
+## 常见错误
+
+- 把 **仅用于实现代码** 的 **`配置根/req-docs/xxx.md`** 当作 **f2s-ctx-build** 技能的入参（应先把符合终稿范式的内容放到 **stock-docs** 再生成上下文）。
+- 在 Rule 内链到 **`req-docs/`**（应链到 **stock-docs** 中的源文档）。
+
+## 详细约定
+
+见 Flow2Spec 包内 `docs/README-目录与路径约定.md`；工作流以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**）为准。

package/templates/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md

@@ -0,0 +1,83 @@
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+
+# 后端技术方案模版
+
+> 供 **f2s-req-backend** 技能使用。本模版在 Flow2Spec 中位于 **templates/template/**（与 docs 同级），init 时会将整目录复制到项目的 **`配置根/template/`**，本文件即 `配置根/template/后端技术模版.md`。生成 Markdown 时一级、二级标题顺序固定如下，与需求无关的整节可省略。**接口与处理流程写在同一处**，不拆章重复。
+
+---
+
+## 1. 文档标题
+
+- 一级标题：`# <活动/需求名> 后端技术方案`
+
+---
+
+## 2. 需求概述
+
+- 二级标题：`## 需求概述`
+- 用无序列表或短段落写清：背景、目标、范围、**明确不做什么**。
+
+---
+
+## 3. 重点问题概述
+
+- 二级标题：`## 重点问题概述`
+- 技术难点、库存/并发/一致性、与现有模块边界、风险与取舍（列表即可）。
+
+---
+
+## 4. 外部对接和内部调用
+
+- 二级标题：`## 外部对接和内部调用`
+- 简要列出：依赖的外部 HTTP/RPC/券台/订单等；本服务内部会调用的模块或方法（不必展开到每个参数）。
+
+---
+
+## 5. 配置
+
+- 二级标题：`## 配置`
+- 按配置来源分子节，例如 `### xxx.json`，内嵌 JSON 示例（可用注释说明字段含义）。
+- 若有拼团等，可另起 `### groupon-setting 片段` 等。
+
+---
+
+## 6. QMQ（如有）
+
+- 二级标题：`## QMQ`
+- 按场景分子节，如 `### xxx 流程`，用编号步骤说明生产/消费、落库字段等。
+
+---
+
+## 7. 接口（接口 + 流程合一）
+
+- 二级标题：`## 接口`
+- **每个接口一个三级标题**：`### <接口中文名>`（可括号注明 serverless 名或路径）。
+- **同一小节内必须包含**（按需取舍，顺序建议）：
+  1. **业务说明**（可选）：一两句或列表，如前置条件、是否仅主态调用。
+  2. **请求体**：`json` 代码块；参数说明可用列表或表格。
+  3. **返回体**：`json` 代码块。
+  4. **data 字段说明**（可选）：表格 `| 字段 | 说明 |`。
+  5. **处理流程**（必选）：编号步骤 `1. 2. 3.`，含分支（**是/否** → 下一步或错误码）、DB/Redis/下游调用、与项目约定的 `responseData`/错误码。复杂接口流程可写多步，步骤粒度适中、便于实现对照。
+- **复用通用能力**的接口（如直接透传拼团）：写清请求体示例 +「详情见《拼团技术方案设计》」即可，**处理流程**可简写为「同公共拼团接口逻辑」。
+- **禁止**：单独再开一章「接口及流程说明」罗列所有接口流程；禁止在文末再整段重复每个接口的逐步流程（除非是全链路**一页级**串联，见下条）。
+
+---
+
+## 8. 关联接口调用流程（可选、仅全景）
+
+- 二级标题：`## 关联接口调用流程`
+- **仅**写用户/页面维度的**调用顺序**（如：进页先调 A 再调 B），**不**重复各接口内部步骤（内部步骤已在「接口」各小节「处理流程」中写完）。若无多接口串联必要，可整节省略。
+
+---
+
+## 9. 错误码
+
+- 二级标题：`## 错误码`
+- 表格：`| 错误码 | 说明 |`（或 resultCode 与项目枚举一致）。
+
+---
+
+## 10. 表设计
+
+- 二级标题：`## 表设计`
+- 每个表：`### 表中文名 表名`，内嵌 `CREATE TABLE` 或字段说明+索引说明。