@double-codeing/flow2spec 2.2.0 → 2.2.2

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

@@ -0,0 +1,142 @@
+---
+name: f2s-doc-add
+description: 工作中把已落地能力解析进上下文（与 f2s-doc-arch 分工不同）：多文件路径→适度深度解析→stock-docs 初稿→终稿→f2s-ctx-build 产出 Rules、Skills、docs-index；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
+---
+
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径；**路径默认相对「配置根的父目录」**（即业务仓库根），除非用户给出绝对路径。
+
+# f2s-doc-add：多文件聚合 → 初稿 → 终稿 → Rules / Skills / 索引
+
+## 使用时机（何时才用本技能）
+
+本技能面向**日常开发/维护中**这一场景：**某条能力或功能已经在代码里做好**（或已有对应说明分散在多个文件），你希望把它**系统化解析并写入 AI 可用的上下文**（`stock-docs` 终稿 + Rules + Skills + `docs-index`），便于后续对话与协作**照着知识库走**。
+
+- **典型**：补文档、做模块交接、把「已实现但只在代码里」的约定沉淀成可加载规则与技能。
+- **非典型（勿用本技能当首选）**：从零画整体架构蓝图、只要一份架构初稿——请用 **f2s-doc-arch** 及后续 **f2s-doc-final** / **f2s-ctx-build** 按步执行。
+
+---
+
+## 与 f2s-doc-arch 的分工（必读）
+
+| 技能 | 典型入口 | 产出侧重 |
+|------|----------|----------|
+| **f2s-doc-arch** | **一段说明**、**单个文档路径**，或确认后的**无参扫描** | **项目/模块架构说明初稿**（默认 `架构说明_初稿.md` 等），不写终稿、不直接跑 ctx-build |
+| **f2s-doc-add**（本技能） | **工作中**为**已做好的能力**列出 **≥1 个相关文件路径**（实现、配置、说明等），多路径聚合 | 把该能力**解析进上下文**：**`stock-docs` 初稿** → **终稿** → **f2s-ctx-build** 生成 **Rules / Skills / docs-index** |
+
+**不要混用**：仅要「架构说明初稿」、入口是文字或单文档时，用 **f2s-doc-arch**，**不要**用本技能代替。仅当用户明确要为**已存在实现的一批文件**做「进知识库 / 进上下文」的整条链时，用本技能。
+
+---
+
+本技能在流程上衔接 **f2s-doc-final** 与 **f2s-ctx-build** 的约定（**不包含** f2s-doc-arch 的架构专述步骤）：用户一次性提供**多个**本地文件路径，Agent **适度深度**阅读后先写 **`stock-docs` 初稿**，再在同一轮（或用户确认后的连续执行中）将初稿规范为 **终稿**，最后按 **`配置根/skills/f2s-ctx-build/SKILL.md`** 生成 **Rules、Skills、`docs-index.md`**（并按需更新 **`main.mdc`**）。
+
+**与 f2s-doc-final / f2s-ctx-build 的关系**：终稿形态、链接、`sourceDoc` 等**以 `f2s-doc-final`、`f2s-ctx-build` 原文为准**；本文件只规定**多源入参、读源策略、与 f2s-doc-arch 的边界**。
+
+---
+
+## 入参
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| **文件路径列表** | **是** | 一个或多个路径：空格/换行分隔，或对话中 `@` 多文件。支持 `.md`、`.txt`、常见源码与配置（`.js`、`.ts`、`.json`、`.yaml` 等）。路径相对**配置根的父目录**，或绝对路径。 |
+| **方案名**（可选） | 否 | 用于 `<方案名>_初稿.md`、`<方案名>_终稿.md` 及后续 **Rule/Skill 主题命名**；不传则从路径共性、目录名、`package.json` 的 `name` 等推断，并做**合法文件名**（去非法字符、避免空名）。 |
+| **初稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_初稿.md`**。 |
+| **终稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_终稿.md`**。 |
+
+若用户**未给出任何可读路径**，**中止**并请其至少提供一条路径。
+
+---
+
+## 与现有知识库重合时的处理（重要）
+
+执行前与读源后，应用 **`配置根/docs-index.md`**、**`配置根/rules/`**、**`配置根/skills/`** 及 **`配置根/stock-docs/`** 做一次**对照**（必要时结合对话里已加载的 Rules/Skills 摘要）：
+
+| 情况 | 做法 |
+|------|------|
+| 用户给出的路径**本身就在** `stock-docs/`、`rules/`、`skills/` 内，且与当前任务**同一主题**（同一方案、同一模块说明） | **优先在原文件上直接修改**：合并重复段落、补全缺口、统一术语与链接，使单份文档或单条 Rule/Skill **自洽、合理**；**不要**仅为走流程再新建一套并行的 `_初稿.md` / `_终稿.md`，除非用户明确要求「另存新文件」。 |
+| 知识库里**已有**描述同一能力的终稿 / Rule / Skill，而用户给的是**外围代码或其它 MD** | 以**既有知识库文件为锚点**：把新读到的信息**吸收进**对应终稿或专题 Rule/Skill（更新正文与 `generatedAt`），并同步 **`docs-index.md`** 中该行的「简要说明」等；避免 **docs-index** 出现多行指向实质重复的主题。 |
+| **无重合**或确认为**全新主题** | 按默认路径新建 **`<方案名>_初稿.md`** → **`_终稿.md`**，再执行步骤 4 **新建或追加** Rule/Skill 与索引行（仍遵守 **f2s-ctx-build** 的「同一终稿只占一行」）。 |
+
+**原则**：知识库里**已经写过**的说明，以**修订原文件**为主，保证上下文**不重复、不打架**；新建文件仅在有明确增量主题或用户指定新方案名时使用。
+
+---
+
+## 步骤 0：准备
+
+1. 确保 **`配置根/stock-docs/`** 存在（不存在则创建）。
+2. 解析路径列表：去重、展开用户 `@` 的文件；**不存在的路径**在初稿「来源与缺口」中列出，**不中断**（除非全部无效则中止）。
+3. **对照**上文「与现有知识库重合时的处理」：决定本轮产出是**更新既有路径**还是**新建** `<方案名>_初稿.md` / `_终稿.md`，并在回复中**一句话说明**本次选择理由。
+
+---
+
+## 步骤 1：适度深度解析（读源策略）
+
+对每个文件**依次**读取（可用工具分批，避免单次过大）：
+
+| 情况 | 策略 |
+|------|------|
+| 文本/Markdown/常规源码，体量 **≤ 约 500 行** | 尽量**通读**全文。 |
+| **更大** 或响应体过长 | **适度深度**：优先读 **文件头/尾**、**导出/类/接口定义**、**配置块**、**README 式章节标题**；代码可结合目录与符号性段落归纳，**禁止**假装已读未读部分。 |
+| **二进制**或无法解码 | 跳过并在初稿注明「无法解析」。 |
+| **多文件** | 归纳：**模块边界**、**重复出现的概念**、**依赖/调用关系**、与 **`配置根`** 约定相关的目录（若有）。 |
+
+解析目标：足够支撑一份**结构清楚、有主有次**的初稿，而非逐字抄录。
+
+---
+
+## 步骤 2：生成初稿
+
+1. 若已判定在**既有文件**上修订：可将「初稿」阶段体现为**该文件内的增补段落**或**同路径覆盖**（合并读源结论），不必机械新建 `_初稿.md`。否则写入 **默认** **`配置根/stock-docs/<方案名>_初稿.md`**（或用户指定的初稿路径）。
+2. 初稿**无固定版式**，建议包含：
+   - **概述**（这批文件共同说明什么）；
+   - **来源清单**（路径 + 每文件一句话作用 + 是否部分阅读）；
+   - **分文件/分模块归纳**（适度深度解析的结论）；
+   - **交叉关系**（配置、入口、数据流等）；
+   - **待确认项**（读源时未覆盖或推断处）。
+3. 文末可加一句：**「本初稿由 f2s-doc-add 根据用户所列文件聚合生成。」**
+
+---
+
+## 步骤 3：基于初稿生成终稿（对齐 f2s-doc-final）
+
+1. **读取** **`配置根/template/终稿模版.md`**（若存在）作为章节提示；**不强制逐条套用**，以初稿事实与逻辑为主。
+2. 将初稿**提炼、归纳**为终稿风格 Markdown（参见 **`配置根/skills/f2s-doc-final/SKILL.md`** 流程一）：
+   - **一级标题** = 方案名（可与 `<方案名>` 一致或略润色）；
+   - **至少**包含二级标题：**核心概念**、**业务规则**、**关键流程**；
+   - 按需补充：状态与流转、接口/API、配置与错误、实现位置与对接方式等。
+3. 写入 **默认** **`配置根/stock-docs/<方案名>_终稿.md`**（或用户指定的终稿路径）；若本轮锚定**已有终稿路径**，则在**该文件上**按终稿结构整理保存，并保证 **`sourceDoc` 仍指向该路径**（步骤 4 中 Rule/Skill 链接与 frontmatter 与之一致）。
+
+若用户要求「先审初稿再出终稿」，可在初稿保存后**暂停**并等待确认；用户确认后从**同一份初稿**继续执行步骤 3～4。
+
+---
+
+## 步骤 4：基于终稿生成 Rules、Skills 与索引（对齐 f2s-ctx-build）
+
+以 **步骤 3 产出或修订后的终稿**（单一 `stock-docs` 下的 `.md` 文件）为 **`sourceDoc` 锚定文档**，执行 **`配置根/skills/f2s-ctx-build/SKILL.md`** 中的要求，包括但不限于：
+
+- **拆解与分工**：篇幅长、多块独立内容时，拆成多条专题 Rule / 多个 Skill + 总览；否则可单 Rule + 单 Skill。
+- **文档路径与链接约定**（**必守**）：Rule 正文链向源文档用 **`../stock-docs/<终稿文件名>.md`**；Skill 用 **`../../stock-docs/<终稿文件名>.md`**；`docs-index.md` 中该文档格用 **`stock-docs/<终稿文件名>.md`** 作为 href；每条 Rule/Skill 的 frontmatter **`sourceDoc`** 为 **`配置根/stock-docs/<终稿文件名>.md`**，并带 **`generatedAt`**（东八区 ISO 8601）。
+- **`main.mdc`**：按 f2s-ctx-build「3.0」判断是否更新模块一览/公共能力入口。
+- **`docs-index.md`**：同一终稿路径**只占一行**；若已存在则**更新**该行的 Rules、Skills、简要说明。
+
+**禁止**将 **`req-docs/`** 下的文件作为本技能链最终 `sourceDoc` 指向；终稿必须在 **`stock-docs/`**。
+
+---
+
+## 输出与自检
+
+完成后向用户说明：
+
+1. **初稿**（若单独落盘）、**终稿**的磁盘路径，或写明「本轮仅在既有 `xxx.md` / 某 Rule / 某 Skill 上修订」；
+2. **新建或更新**的 Rule、Skill 路径及 **`docs-index`** 是否已更新；
+3. 提醒：若 **`main.mdc`** 已改，需扫一眼渐进式读取约定是否仍连贯。
+
+**自检**：对照 **`f2s-ctx-build`** 技能末尾「完成后自检（路径必查）」五项，核对链接与 `sourceDoc`。
+
+---
+
+## 约束与注意
+
+- **与知识库重合时**：已述内容见上文「与现有知识库重合时的处理」；**禁止**在已有同主题终稿/Rules/Skills 时仍机械新建平行文件导致重复索引。
+- **适度深度**是硬性要求：大文件不得虚构未读段落细节；不确定处写入待确认或终稿「（待补充）」。
+- **版权与敏感**：用户给出的路径可能含密钥或内网信息；写入 `stock-docs` 前**脱敏**或删去秘钥，并在初稿/终稿注明「已脱敏」若已处理。
+- 本技能**不替代**单独执行 **f2s-doc-pdf**（PDF 须先转 MD 再作为路径列表之一传入）。

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

@@ -8,6 +8,8 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。
 
+**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进上下文（初稿→终稿→Rules/Skills/索引），应使用 **`配置根/skills/f2s-doc-add/SKILL.md`**，**勿用本技能冒充该流程**。
+
 ---
 
 ## 入参（均可选）

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

@@ -30,7 +30,7 @@ description: 根据用户指出的实现规则错误，修正代码并同步更
 
 4. **更新全局规则与 Skill**
    - 若该约定为项目级或模块级：
-     - 在项目约定的规则目录（如 `配置根/rules/`）下新增或更新一条规则，写清「必须/禁止」及适用范围（globs 等）。
+     - 在项目约定的规则目录（如 `配置根/rules/`）下新增或更新一条规则，写清「必须/禁止」及适用范围（**Cursor**：`globs` + **`.mdc`**；**Claude Code** 的 **`.claude/rules/`**：**`.md`** + **`paths:`**，勿写 **`.mdc`** / **`globs:`**）。
      - 在项目约定的技能目录（如 `配置根/skills/`）下新增或更新一个 Skill，写清触发词与正确/错误示例，便于后续实现与 AI 按规则执行。
    - 规则与 Skill 中可引用文档作为约定出处。
 

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

@@ -1,6 +1,6 @@
 ---
 name: stock-docs-vs-req-docs
-description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、配置根文档、PDF 终稿、技术方案放哪、f2s-ctx-build 路径
+description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、f2s-ctx-build、f2s-doc-arch、f2s-doc-add、已落地能力、技术方案放哪、PDF 终稿
 ---
 
 # stock-docs 与 req-docs（技能）
@@ -9,19 +9,21 @@ description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-doc
 
 - 用户问「文档放哪」「PDF 转完放哪」「生成 Rules 用哪个目录」「技术方案目录」等。
 - 实现或命令执行时需要选择 **`配置根/stock-docs/`** 还是 **`配置根/req-docs/`**。
+- 区分 **f2s-doc-arch**（架构说明**初稿**）与 **f2s-doc-add**（**工作中**把**已落地能力**从多文件解析进上下文）：二者产物都落在 **stock-docs/**，与 **req-docs** 无关；分工见 **`skills/f2s-doc-arch/SKILL.md`**、**`skills/f2s-doc-add/SKILL.md`**。
 
 ## 核心对照
 
 | 目录 | 位置 | 用途 |
 |------|------|------|
-| **stock-docs** | 配置根下 | 存量上下文源 → **f2s-ctx-build** 技能、终稿/初稿/架构说明 |
-| **req-docs** | 配置根下（如 `.cursor/req-docs/`） | 需求与技术方案 → 按 `implement-tech-design` **写代码**、f2s-doc-pdf 输出 |
+| **stock-docs** | 配置根下 | **存量上下文源** → **f2s-ctx-build** 入参；**f2s-doc-final** 的初稿/终稿；**f2s-doc-arch** 的架构初稿；**f2s-doc-add** 聚合读源后的初稿与终稿（与 f2s-doc-arch 分工不同，见该 SKILL「使用时机」） |
+| **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** 中的源文档）。
+- 把 **f2s-doc-add** / **f2s-doc-arch** 产出的初稿、终稿误存到 **req-docs**（应始终在 **stock-docs/**）。
 
 ## 详细约定
 
-见 Flow2Spec 包内 `docs/README-目录与路径约定.md`；工作流以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**）为准。
+见 Flow2Spec 包内 **`docs/README-目录与路径约定.md`**；技能顺序与 **f2s-doc-arch** / **f2s-doc-add** 见 **`docs/README-命令说明.md`**。具体步骤以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**）为准。