npm - @double-codeing/flow2spec - Versions diffs - 2.2.0 → 2.2.2 - Mend

@double-codeing/flow2spec 2.2.0 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/docs/README-/347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md CHANGED Viewed

@@ -1,119 +1,76 @@
 # 目录与路径约定
-本文档说明 **Flow2Spec** 在项目内使用的目录结构、文档路径与链接约定，以及版本管理字段。遵守这些约定可避免 AI 生成错误链接、便于索源与更新。
+**配置根**：`flow2spec init` 写入的目录（默认 **`.cursor/`**，亦可 **`.claude/`**、**`.codex/`**）。下文以 **`.cursor/`** 为例，其它 agent 将 `.cursor` 换成对应目录名即可。
-**命名一览（区分：业务项目「配置根」下的文档目录 vs Flow2Spec 包内的说明目录）**
+**文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) · [README-命令说明](./README-命令说明.md) · [README-体系与原理](./README-体系与原理.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
-| 目录 | 位置 | 用途 |
-|------|------|------|
-| **`stock-docs/`** | 如 `.cursor/stock-docs/` | **存量上下文源**：PDF/初稿/终稿/架构说明等，供 **f2s-ctx-build** 技能生成 Rules、Skills、索引 |
-| **`req-docs/`** | 如 `.cursor/req-docs/` | **需求与技术方案**：澄清需求、后端技术方案、PDF 转 MD（实现用）等，配合 `implement-tech-design` **按方案写代码** |
+| 路径（逻辑） | 示例（Cursor） | 说明 |
+|--------------|----------------|------|
+| **stock-docs/** | `.cursor/stock-docs/` | 存量源文档（终稿/初稿/架构等）→ **f2s-ctx-build**；**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**已落地能力、多文件聚合进上下文）的初稿/终稿亦在此，**勿**与 **req-docs** 混用 |
+| **req-docs/** | `.cursor/req-docs/` | 技术方案、澄清文档等 → **implement-tech-design** 按方案写代码 |
+| **rules/** | `.cursor/rules/` | **main.mdc**（唯一 alwaysApply）+ 专题 `*-context.mdc` |
+| **skills/** | `.cursor/skills/` | 各 `SKILL.md` |
+| **template/** | `.cursor/template/` | 终稿模版、后端技术模版 |
+| **docs-index.md** | `.cursor/docs-index.md` | 文档 ↔ Rules / Skills 索引表 |
+**init**：创建上表目录并复制模板。**升级**：旧名 `docs/` 可改名为 `stock-docs/`；`req-docs` 须在**配置根内**，勿与 `.cursor` 同级。
----
-## 1. 目录结构（配置根与配置根父目录）
-**「配置根」**：`flow2spec init [agent ...]` 写入的 AI 工具配置目录。默认 **Cursor** 为 **`.cursor/`**；可选 **`.claude/`**、**`.codex/`** 等（可多选，各自一套相同子结构）。下文表格以 **`.cursor/`** 为例；若你的配置根为 `.claude/`，将路径中的 `.cursor` 替换为 `.claude` 即可。
-**配置根**下为 **stock-docs/**、**req-docs/**、**rules/**、**skills/**、**template/** 及 **docs-index.md**。下表**左列**为逻辑位置，**中列**为 Cursor（配置根 `.cursor/`）时的完整路径示例；使用 **`.claude/`** 等时把中列的 `.cursor` 换成对应目录名即可。
+### 1.1 Cursor 与 Claude Code：`rules/` 扩展名
-| 逻辑位置（相对配置根或配置根父目录） | Cursor 下路径示例 | 说明 |
-| ------------------------ | ----------------- | ---- |
-| `stock-docs/` | `.cursor/stock-docs/` | **存量源文档**；终稿、架构初稿、从 PDF 整理的 MD 等，用于**生成 Rules、Skills、索引** |
-| `rules/` | `.cursor/rules/` | **main.mdc**（总概述，唯一 alwaysApply）与各**专题 Rule**（*-context.mdc） |
-| `skills/` | `.cursor/skills/` | Agent Skills：按主题分子目录，每目录下 **SKILL.md**（工作流与说明由 `flow2spec init` 写入） |
-| `template/` | `.cursor/template/` | 《终稿模版》《后端技术模版》等 |
-| **docs-index.md**（与 `stock-docs/` 同级） | `.cursor/docs-index.md` | 需求/文档索引表 |
-| `req-docs/` | `.cursor/req-docs/` | **需要实现成代码的文档**（技术方案等）；对话中 **`.cursor/req-docs/xxx.md`** + implement-tech-design |
+| 配置根 | 规则文件扩展名 | 路径范围（frontmatter） | 说明 |
+|--------|----------------|-------------------------|------|
+| **`.cursor/`**（Cursor） | **`.mdc`** | **`globs:`** + **`alwaysApply:`** | Cursor 约定 |
+| **`.claude/`**（Claude Code） | **`.md`** | **`paths:`**（无 `paths` 则与会话同载） | Claude Code 不识别 `.mdc`；`flow2spec init claude` 由模板自动转换 |
-**flow2spec init 会创建**：对每个所选 agent，创建 **配置根** 及 **`stock-docs/`**、**`req-docs/`**、**`template/`**、**`rules/`**、**`skills/`** 子目录，并写入模板。
-**从旧版升级**：若仍使用旧名 **`docs/`**（配置根下），可改名为 **`stock-docs/`**。若曾把 **`req-docs/` 误放在配置根父目录**（与 `.cursor` 同级而非其下），请**整体迁入**当前所用配置根下（如 `.cursor/req-docs/`），再执行 `flow2spec init` 可确保目录存在（已存在则保留其中文件）。
+在 **`.claude/`** 下手工维护规则时，请使用 **`.md`** 与 **`paths:`**；勿复制 Cursor 的 **`globs:`** / **`.mdc`** 以免不生效。Claude Code **不会**把 **`.mdx`** 当作项目规则加载；请勿用 **`.mdx`** 作为 `rules/` 内规则扩展名。
 ---
-## 2. 文档路径与链接约定（必守）
-生成 Rule、Skill、docs-index 时，引用 **`stock-docs/`**（配置根下）内文档的链接写法必须按下列规则，否则在编辑器里打开产物时链接会失效。
-**与配置根的关系**：下表以 **Cursor**（配置根为 **`.cursor/`**）为例书写路径。若你通过 `flow2spec init claude` 等使用 **`.claude/`**、**`.codex/`** 等作为配置根，则：
-- **显示路径、sourceDoc、docs-index 文档列**中的 **`.cursor`** 一律改为你的配置根目录名（例如 `sourceDoc: .claude/stock-docs/<文件名>.md`，docs-index 显示列写 `.claude/stock-docs/...`）。
-- **相对链接**规则不变：Rule 内仍用 `../stock-docs/<文件名>.md`，Skill 内仍用 `../../stock-docs/<文件名>.md`，docs-index 的链接 href 仍仅为 `stock-docs/<文件名>.md`（均相对于**该配置根**内部的 `rules/`、`skills/`、`docs-index.md` 位置，与 **`req-docs/`** 无关）。
+## 2. 链接写法（生成 Rule / Skill / docs-index 时必守）
-| 写入位置（以 `.cursor/` 为例）        | 引用该文档时的写法                                                               |
-| -------------------------------- | ----------------------------------------------------------------------- |
-| **`rules/*.mdc`**          | 链接 href 为 `**../stock-docs/<文件名>.md**`（从 rules 到同配置根下 stock-docs 的相对路径）                  |
-| **`skills/<主题>/SKILL.md`** | 链接 href 为 `**../../stock-docs/<文件名>.md**`（从 skills/xxx 到 stock-docs 的相对路径）          |
-| **`docs-index.md`**        | 链接 href 为 `**stock-docs/<文件名>.md**`（docs-index 与 `stock-docs/` 同级，故 href 不含 `../`） |
-| **frontmatter 的 sourceDoc**      | **`<配置根>/stock-docs/<文件名>.md`**（与 **f2s-ctx-build** 技能入参一致，如 `.cursor/stock-docs/...` 或 `.claude/stock-docs/...`）                           |
+从 **rules/**、**skills/**、**docs-index.md** 指向 **stock-docs/** 的 **href** 必须如下（否则链接断）：
-**正确示例（配置根为 `.cursor/` 时）：**
+| 写入位置 | 链接 href |
+|----------|-----------|
+| `rules/*.mdc` | `../stock-docs/<文件名>.md` |
+| `skills/<主题>/SKILL.md` | `../../stock-docs/<文件名>.md` |
+| `docs-index.md` | `stock-docs/<文件名>.md`（无 `../`） |
+| **sourceDoc**（frontmatter） | **`<配置根>/stock-docs/<文件名>.md`**（如 `.cursor/stock-docs/xxx.md`） |
-- Rule 内：`[拼团技术方案设计](../stock-docs/拼团技术方案设计.md)`
-- Skill 内：`[拼团技术方案设计](../../stock-docs/拼团技术方案设计.md)`
-- docs-index 单元格：`[.cursor/stock-docs/拼团技术方案设计.md](stock-docs/拼团技术方案设计.md)`
-- frontmatter：`sourceDoc: .cursor/stock-docs/拼团技术方案设计.md`
+**禁止**：Rule/Skill/docs-index 把 **req-docs** 当 stock-docs 链出；docs-index 的 href 写成 `../stock-docs/` 或裸绝对路径。
-**若配置根为 `.claude/`**：docs-index 显示列与 sourceDoc 改为 `.claude/stock-docs/<文件名>.md`；链接 href 仍同上三行相对规则。
-**禁止：**
-- 在 Rule 内使用 `../../stock-docs/` 或把 **`req-docs/`** 下的技术方案误当作 **stock-docs** 链出目标（会 404 或链错）
-- 在 Skill 内使用 `../stock-docs/` 或上述误链
-- 在 docs-index 的链接 href 中使用 `../stock-docs/` 或裸路径 `.cursor/stock-docs/xxx.md`（应仅为 `stock-docs/<文件名>.md`）
-- 在 sourceDoc 中写 `../stock-docs/xxx.md` 或 **`req-docs/xxx.md`**（生成上下文的 sourceDoc 必须为 **`<配置根>/stock-docs/<文件名>.md`**）
-**记忆要点**：生成 Rules/Skills 的**源文档**只在 **`stock-docs/`** 下（勿把 **`req-docs/`** 当链出目标）；Rule 内 `../stock-docs/`，Skill 内 `../../stock-docs/`，docs-index 内 `stock-docs/`；sourceDoc 用 **实际配置根** + `/stock-docs/<文件名>.md`。
+**记忆**：链出只认 **stock-docs**；Rule `../`，Skill `../../`，索引 `stock-docs/`；sourceDoc 用配置根全路径。
 ---
-## 3. 文档产物阶段（原稿 / 初稿 / 终稿）
-文档在流程中的阶段与命名约定如下，便于区分「未加工 → 待确认 → 可生成上下文」的形态。以下路径均在 **`stock-docs/`** 下（Cursor 下即 `.cursor/stock-docs/`，其他 agent 将 `.cursor` 换为对应目录名）。
+## 3. 文档产物阶段（均在 stock-docs/）
-| 阶段 | 含义 | 典型文件名 / 来源 |
-|------|------|-------------------|
-| **原稿** | 原始材料（如 PDF、未结构化的 MD），未放入本体系时的形态。 | 任意 PDF、`stock-docs/xxx.md`（未规范前） |
-| **初稿** | **f2s-doc-final** 技能从 **PDF 首次**转出、或 **f2s-doc-arch** 技能生成的架构说明，供人工检查与修改。 | `stock-docs/<方案名>_初稿.md`、`<项目名>架构说明_初稿.md` |
-| **终稿** | 初稿或任意 MD 经 **f2s-doc-final** 技能转为《终稿模版》规范格式后的**最终产物**，用于生成 Rules、Skills。 | `stock-docs/<方案名>_终稿.md` |
+| 阶段 | 含义 | 典型名 |
+|------|------|--------|
+| 原稿 | 未纳入体系前的材料 | 任意 PDF、杂乱 MD |
+| 初稿 | **f2s-doc-final**（PDF 首次）、**f2s-doc-arch**（架构说明），或 **f2s-doc-add**（**工作中**把**已落地能力**从多文件聚合成的初稿） | `*_初稿.md`、`*架构说明_初稿.md` 等；**f2s-doc-add** 与 **f2s-doc-arch** 分工见各自 `SKILL.md` |
+| 终稿 | **f2s-doc-final** 规范输出 | `*_终稿.md` → **f2s-ctx-build** 入参 |
-**与命令的对应关系：**
-- **f2s-doc-final**：传入 PDF → 输出初稿（`_初稿.md`）；传入初稿或 MD → 输出**终稿**（`_终稿.md`）。
-- **f2s-ctx-build**：入参为**终稿或等价存量文档路径**（如 `stock-docs/<方案名>_终稿.md`，即 `.cursor/stock-docs/...` 或 `.claude/stock-docs/...` 等），根据该文档生成 Rules、Skills、索引。生成的 **Rules、Skills 文件名与目录名不带 `_终稿` 后缀**，保持现有约定（如 `rules/<主题>-context.mdc`、`skills/<主题>-context/SKILL.md`）。
-小结：**文档**可有 原稿 → 初稿（`_初稿`）→ 终稿（`_终稿`）；**Rules、Skills** 由终稿生成，命名不加 `_终稿`。
+Rules/Skills **文件名不带 `_终稿`**。
 ---
 ## 4. 版本管理（sourceDoc 与 generatedAt）
-每条 Rule、每条 Skill 的 frontmatter 中**必须**包含：
-- **sourceDoc**：源文档路径，格式 **`<配置根>/stock-docs/<文件名>.md`**（与 **f2s-ctx-build** 技能入参一致，如 `.cursor/stock-docs/xxx.md`、`.claude/stock-docs/xxx.md`）
-- **generatedAt**：本次生成时间，东八区北京时间，ISO 8601，如 `2026-01-28T20:00:00+08:00`
-用途：**从产物找文档**（看 Rule/Skill 的 `sourceDoc`）、**从文档找产物**（查该配置根下的 docs-index）、**更新**（改文档后对同一路径再执行 **f2s-ctx-build** 技能）。索源与典型用法见 [README-体系与原理 - 版本管理与索源](./README-体系与原理.md#5-版本管理与索源)。
+每条 Rule、Skill 的 frontmatter：**sourceDoc**（同上表）、**generatedAt**（东八区 ISO 8601，如 `2026-01-28T20:00:00+08:00`）。
+**索源**：产物看 `sourceDoc`；文档看 **docs-index** 对应行；更新对同路径再跑 **f2s-ctx-build**。用法见 [README-体系与原理 §5](./README-体系与原理.md#5-版本管理与索源)。
 ---
-## 5. 模版目录（`template/`）
+## 5. template/
-- **包内路径**：Flow2Spec 包内模版目录 **templates/template/**（与 `templates/skills` 等同级），包含 `终稿模版.md`、`后端技术模版.md` 等。
-- **init 注入**：`flow2spec init` 将包内 **templates/template/** 整目录复制到**每个所选配置根**下的 **`template/`**（Cursor 下即 **`.cursor/template/`**，Claude 下即 **`.claude/template/`** 等），例如 `终稿模版.md`、`后端技术模版.md` 位于 **`template/`** 内。
-- **f2s-doc-final**：转换时优先读取 **`template/终稿模版.md`** 作为格式规范；若不存在则使用命令内嵌的模板结构。
-- **生成后端技术文档**：结构范本为 **`template/后端技术模版.md`**；产出技术方案默认写入 **`req-docs/`**。
-- 团队可自行修改**当前所用配置根**下 `template/` 内文件；再次 init 会**覆盖**该目录（与 rules/skills 行为一致）。
+包内 **templates/template/** → init 复制到 **配置根/template/**。**f2s-doc-final** 读 `template/终稿模版.md`；**f2s-req-backend** 参考 `template/后端技术模版.md`。再次 init **覆盖** `template/`。
 ---
 ## 6. 小结
-- **配置根**下：`stock-docs/`、**`req-docs/`**、`rules/`、`skills/`、`template/`，索引文件 **docs-index.md**（如 `.cursor/docs-index.md`）。
-- **文档产物阶段**：原稿 → 初稿（`_初稿.md`）→ 终稿（`_终稿.md`）；f2s-doc-final 的最终输出为终稿；f2s-ctx-build 用终稿生成 Rules、Skills，但 Rules、Skills 命名不带 `_终稿`。
-- 文档链接按**写入位置**使用不同相对路径：Rule 用 `../stock-docs/`，Skill 用 `../../stock-docs/`，docs-index 用 `stock-docs/`；**sourceDoc** 与显示路径用 **实际配置根** + `/stock-docs/<文件名>.md`（见 §2）。
-- 版本管理用 **sourceDoc** + **generatedAt**，便于索源与按文档更新产物。
+- **stock-docs** = 上下文源；**req-docs** = 实现用方案。
+- 链接层级见 §2；产物阶段见 §3；版本字段见 §4。
-**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)（init、目录约定引用、典型流程） | [README-命令说明](./README-命令说明.md)（各命令入参输出、按使用顺序查找） | [README-体系与原理](./README-体系与原理.md)（main 与 docs-index、设计原则）
+**相关文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) | [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | [README-命令说明](./README-命令说明.md) | [README-体系与原理](./README-体系与原理.md)

package/lib/claudeRulesAdapter.js ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Cursor 规则为 .mdc + frontmatter globs、alwaysApply。
+ * Claude Code 仅识别 .claude/rules 下扩展名为 .md 的规则文件，路径范围用 paths（见 Claude Code 文档：Organize rules with .claude/rules）。
+ */
+/**
+ * @param {string} mdcSource  完整 .mdc 文件正文
+ * @returns {string}         写入 `.claude/rules/*.md` 的正文
+ */
+function adaptRuleMdcToClaudeMd(mdcSource) {
+  let out = mdcSource;
+  // YAML：globs → paths（与 Cursor 语义等价）
+  out = out.replace(/^globs:/m, "paths:");
+  // Claude Code 不按 Cursor 的 alwaysApply 解析；无 paths 的规则与会话同载
+  out = out.replace(/^\s*alwaysApply:\s*(true|false)\s*\r?\n/m, "");
+  // 正文与示例中的 .mdc 引用改为 .md，与落盘扩展名一致
+  out = out.replace(/\.mdc\b/g, ".md");
+  return out;
+}
+/**
+ * @param {string} agentRoot  AGENTS[id].root，如 `.claude`
+ */
+function shouldWriteClaudeStyleRules(agentRoot) {
+  return agentRoot === ".claude";
+}
+module.exports = { adaptRuleMdcToClaudeMd, shouldWriteClaudeStyleRules };

package/lib/init.js CHANGED Viewed

@@ -1,6 +1,7 @@
 const path = require("path");
 const fs = require("fs");
 const { AGENTS, SUBDIRS, normalizeAgentIds } = require("./agents");
+const { adaptRuleMdcToClaudeMd, shouldWriteClaudeStyleRules } = require("./claudeRulesAdapter");
 function ensureDirs(cwd, agentRoot) {
   for (const sub of SUBDIRS) {
@@ -22,18 +23,46 @@ function copyRecursive(src, dest) {
   }
 }
+/** 复制 templates/rules：Cursor 保留 .mdc；Claude Code 写入 .md 并转换 frontmatter（globs→paths，去掉 alwaysApply） */
+function copyRulesTemplates(cwd, agentRoot, templatesDir) {
+  const rulesSrc = path.join(templatesDir, "rules");
+  const rulesDest = path.join(cwd, agentRoot, "rules");
+  if (!fs.existsSync(rulesSrc)) return;
+  if (!fs.existsSync(rulesDest)) fs.mkdirSync(rulesDest, { recursive: true });
+  const claudeStyle = shouldWriteClaudeStyleRules(agentRoot);
+  if (claudeStyle) {
+    for (const name of fs.readdirSync(rulesDest)) {
+      if (name.endsWith(".mdc")) {
+        fs.unlinkSync(path.join(rulesDest, name));
+      }
+    }
+  }
+  for (const name of fs.readdirSync(rulesSrc)) {
+    const srcPath = path.join(rulesSrc, name);
+    const st = fs.statSync(srcPath);
+    if (st.isDirectory()) {
+      copyRecursive(srcPath, path.join(rulesDest, name));
+      continue;
+    }
+    if (!name.endsWith(".mdc")) {
+      fs.copyFileSync(srcPath, path.join(rulesDest, name));
+      continue;
+    }
+    const raw = fs.readFileSync(srcPath, "utf8");
+    const body = claudeStyle ? adaptRuleMdcToClaudeMd(raw) : raw;
+    const destName = claudeStyle ? name.replace(/\.mdc$/i, ".md") : name;
+    fs.writeFileSync(path.join(rulesDest, destName), body, "utf8");
+  }
+}
 /** 将 templates 下全部内容复制到指定配置根目录（如 .cursor、.claude） */
 function copyTemplatesToAgentRoot(cwd, agentRoot) {
   const templatesDir = path.join(__dirname, "..", "templates");
   const destRoot = path.join(cwd, agentRoot);
-  const rulesSrc = path.join(templatesDir, "rules");
-  const rulesDest = path.join(destRoot, "rules");
-  if (fs.existsSync(rulesSrc)) {
-    for (const name of fs.readdirSync(rulesSrc)) {
-      copyRecursive(path.join(rulesSrc, name), path.join(rulesDest, name));
-    }
-  }
+  copyRulesTemplates(cwd, agentRoot, templatesDir);
   const skillsSrc = path.join(templatesDir, "skills");
   const skillsDest = path.join(destRoot, "skills");

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "flow2spec init：落盘 .cursor/.claude/.codex 等配置根的 rules、skills、stock-docs/req-docs，文档驱动、f2s 可写回知识库工作流。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

package/templates/rules/stock-docs-vs-req-docs.mdc CHANGED Viewed

@@ -8,7 +8,7 @@ alwaysApply: false
 # stock-docs 与 req-docs
-- **`配置根/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；**f2s-ctx-build**、**f2s-doc-final**、**f2s-doc-arch** 等技能的落盘（除 PDF→初稿等另有说明外）优先在此。Rule/Skill/docs-index 链出文档用 `../stock-docs/`、`../../stock-docs/`、`stock-docs/<文件名>.md`；`sourceDoc` 为 `<配置根>/stock-docs/<文件名>.md`。
+- **`配置根/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；**f2s-ctx-build**、**f2s-doc-final**、**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**将**已落地能力**从多文件解析进上下文：初稿→终稿→Rules/Skills；与 f2s-doc-arch 分工不同）等技能的落盘（除 PDF→初稿等另有说明外）优先在此。Rule/Skill/docs-index 链出文档用 `../stock-docs/`、`../../stock-docs/`、`stock-docs/<文件名>.md`；`sourceDoc` 为 `<配置根>/stock-docs/<文件名>.md`。
 - **`req-docs/`**（**配置根**下，如 `.cursor/req-docs/`）：需求澄清、**后端技术方案**、f2s-doc-pdf 输出的「按方案实现」MD；`implement-tech-design` 的 globs 为 `**/req-docs/**/*.md`。
 完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。

package/templates/skills/f2s-ctx-build/SKILL.md CHANGED Viewed

@@ -1,12 +1,13 @@
 ---
-name: f2s-ctx-build
+## name: f2s-ctx-build
 description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
----
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 `**.cursor/`**、`**.claude/**`、`**.codex/**`）。下文 `**配置根/...**` 指该目录下的相对路径。
 # 根据文档生成项目上下文（Rules、Skills、文档索引）
-用户会在本技能后附带**一个参数**：要么是一个 **URL**（如 `https://xxx.com/doc`），要么是一个**本地路径**，且路径应指向 **配置根/stock-docs/** 下的 Markdown（PDF/初稿/终稿/架构说明等**存量上下文源**，用于生成 Rules、Skills）。**不要**把 **`配置根/req-docs/`**（按方案实现代码的技术方案目录）当作本技能入参；若用户只持有该目录下的方案，应提示先将符合《终稿模版》的文档复制或整理到 **`配置根/stock-docs/`** 再执行。请按以下步骤执行，用你的**大模型能力**分析文档并生成完整架构。
+用户会在本技能后附带**一个参数**：要么是一个 **URL**（如 `https://xxx.com/doc`），要么是一个**本地路径**，且路径应指向 **配置根/stock-docs/** 下的 Markdown（PDF/初稿/终稿/架构说明等**存量上下文源**，用于生成 Rules、Skills）。**不要**把 `**配置根/req-docs/`**（按方案实现代码的技术方案目录）当作本技能入参；若用户只持有该目录下的方案，应提示先将符合《终稿模版》的文档复制或整理到 `**配置根/stock-docs/**` 再执行。请按以下步骤执行，用你的**大模型能力**分析文档并生成完整架构。
 **文档产物阶段约定**：doc 中的产物一般分为 **原稿**、**初稿**、**终稿**；本技能生成的 **Rules、Skills 文件名与目录名不带 `_终稿` 等后缀**，与现有约定一致（如 `<主题>-context.mdc`、`<主题>-context/SKILL.md`）。
@@ -15,15 +16,15 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 1. **拆解**：根据文档篇幅与领域块数量，决定是「单 Rule + 单 Skill」还是「索引入口 + 多条专题 Rule/Skill」。篇幅长或含多块独立内容（如接口约定、消息队列、配置、公共工具等）时，应拆成索引入口 + 多条按场景/主题的 Rule 与 Skill，使单条更聚焦、按需加载。
 2. **分工**：
-   - **Rules**：承担**约束、约定、作用范围**；一条 alwaysApply 的索引入口 + 若干条用 globs 限定在相关路径的专题规则；正文写「必须/禁止/约定」类内容。
-   - **Skills**：承担**领域知识、操作步骤、示例**；一个总览 skill + 若干专题 skill；description 写清触发词与使用场景，正文写概念、流程、方法表、示例。
+  - **Rules**：承担**约束、约定、作用范围**；一条 alwaysApply 的索引入口 + 若干条用 globs 限定在相关路径的专题规则；正文写「必须/禁止/约定」类内容。
+  - **Skills**：承担**领域知识、操作步骤、示例**；一个总览 skill + 若干专题 skill；description 写清触发词与使用场景，正文写概念、流程、方法表、示例。
 ---
 ## 步骤 1：获取文档内容
 - 若用户给出的是 **HTTPS/HTTP URL**：使用你可用的网络请求能力（如 web fetch）拉取该 URL 的页面内容。若你所在环境无法访问该 URL（如内网），则回复用户说明「请将页面内容复制到项目内 `配置根/stock-docs/xxx.md`，再执行本技能并传入路径 `配置根/stock-docs/xxx.md`」。
-- 若用户给出的是**本地路径**：从配置根的父目录读取该文件（须为 **`配置根/stock-docs/…`**，如 `配置根/stock-docs/功能描述.md`）。若路径落在 **`配置根/req-docs/`**（技术方案目录），应提醒用户：本技能入参须为 **stock-docs** 下的存量源文档；请先将符合《终稿模版》的内容整理到 **`stock-docs/`** 再执行。
+- 若用户给出的是**本地路径**：从配置根的父目录读取该文件（须为 `**配置根/stock-docs/…`**，如 `配置根/stock-docs/功能描述.md`）。若路径落在 `**配置根/req-docs/**`（技术方案目录），应提醒用户：本技能入参须为 **stock-docs** 下的存量源文档；请先将符合《终稿模版》的内容整理到 `**stock-docs/`** 再执行。
 得到的内容可能是 Markdown、HTML 或富文本，请先提取出**正文**（若是 HTML 可提取 body 内的文本或转成可读的 Markdown）。
@@ -33,27 +34,31 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 生成任何产物时，**必须**按下列规则写文档路径与链接。**路径写错会导致 Cursor 中链接失效、AI 无法正确打开源文档，务必严格按表执行。**
-| 写入位置 | 文档所在目录（固定） | 引用该文档时的写法 |
-|----------|----------------------|--------------------|
-| **配置根/rules/*.mdc** | 文档在 `配置根/stock-docs/<文件名>.md` | 链接 **必须** 写为 `[文档标题](../stock-docs/<文件名>.md)`，即 href 为 **`../stock-docs/<文件名>.md`**（从 配置根/rules 到 配置根/stock-docs 的相对路径）。 |
-| **配置根/skills/<主题>/SKILL.md** | 同上 | 链接 **必须** 写为 `[文档标题](../../stock-docs/<文件名>.md)`，即 href 为 **`../../stock-docs/<文件名>.md`**（从 配置根/skills/xxx 到 配置根/stock-docs 的相对路径）。 |
-| **配置根/docs-index.md** | 同上 | 文档路径列：显示可写 `配置根/stock-docs/<文件名>.md`；链接 href **必须** 为 **`stock-docs/<文件名>.md`**（因 docs-index 位于配置根下，同级的 **stock-docs** 目录即 `stock-docs/<文件名>.md`）。示例：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`。 |
-| **frontmatter 的 sourceDoc** | 同上 | **必须** 写为 **`配置根/stock-docs/<文件名>.md`**（与用户传入的本地路径一致；若用户传的是相对路径如 `配置根/stock-docs/xxx.md`，即用该值）。 |
+| 写入位置                         | 文档所在目录（固定）                    | 引用该文档时的写法                                                                                                                                                                                                |
+| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **配置根/rules/*.mdc**          | 文档在 `配置根/stock-docs/<文件名>.md` | 链接 **必须** 写为 `[文档标题](../stock-docs/<文件名>.md)`，即 href 为 `**../stock-docs/<文件名>.md`**（从 配置根/rules 到 配置根/stock-docs 的相对路径）。                                                                                 |
+| **配置根/skills/<主题>/SKILL.md** | 同上                            | 链接 **必须** 写为 `[文档标题](../../stock-docs/<文件名>.md)`，即 href 为 `**../../stock-docs/<文件名>.md`**（从 配置根/skills/xxx 到 配置根/stock-docs 的相对路径）。                                                                      |
+| **配置根/docs-index.md**        | 同上                            | 文档路径列：显示可写 `配置根/stock-docs/<文件名>.md`；链接 href **必须** 为 `**stock-docs/<文件名>.md`**（因 docs-index 位于配置根下，同级的 **stock-docs** 目录即 `stock-docs/<文件名>.md`）。示例：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`。 |
+| **frontmatter 的 sourceDoc**  | 同上                            | **必须** 写为 `**配置根/stock-docs/<文件名>.md`**（与用户传入的本地路径一致；若用户传的是相对路径如 `配置根/stock-docs/xxx.md`，即用该值）。                                                                                                          |
 **正确示例（按位置抄写格式）：**
 - Rule 内：`[技术方案设计](../stock-docs/技术方案设计.md)`
 - Skill 内：`[技术方案设计](../../stock-docs/技术方案设计.md)`
 - docs-index 表格单元格：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`
 - frontmatter：`sourceDoc: 配置根/stock-docs/技术方案设计.md`
 **常见错误（禁止）：**
 - **禁止** 在 Rule 内使用 `../../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
 - **禁止** 在 Skill 内使用 `../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
 - **禁止** 在 docs-index 内使用 `../stock-docs/` 或 `配置根/stock-docs/xxx.md` 作为链接 href —— 应仅为 `stock-docs/<文件名>.md`。
-- **禁止** 在链接或 sourceDoc 中混用目录：生成上下文的链出与 **sourceDoc** 仅指向 **`stock-docs/`**；勿把 **`配置根/req-docs/`** 下的技术方案当作本技能产物的链出目标。
-- **禁止** 在 sourceDoc 中写相对路径如 `../stock-docs/xxx.md` 或 **`配置根/req-docs/xxx.md`** —— 必须为 `配置根/stock-docs/<文件名>.md`。
+- **禁止** 在链接或 sourceDoc 中混用目录：生成上下文的链出与 **sourceDoc** 仅指向 `**stock-docs/`**；勿把 `**配置根/req-docs/**` 下的技术方案当作本技能产物的链出目标。
+- **禁止** 在 sourceDoc 中写相对路径如 `../stock-docs/xxx.md` 或 `**配置根/req-docs/xxx.md`** —— 必须为 `配置根/stock-docs/<文件名>.md`。
-**记忆要点**：默认文档目录为 **`配置根/stock-docs/`**（与项目约定一致）；Rule 内链出用 `../stock-docs/`，Skill 内链出用 `../../stock-docs/`，docs-index 内链出用 `stock-docs/`；sourceDoc 用 `配置根/stock-docs/<文件名>.md`。生成后自检所有链接与 sourceDoc，确保层级正确、与项目约定目录一致。
+**记忆要点**：默认文档目录为 `**配置根/stock-docs/`**（与项目约定一致）；Rule 内链出用 `../stock-docs/`，Skill 内链出用 `../../stock-docs/`，docs-index 内链出用 `stock-docs/`；sourceDoc 用 `配置根/stock-docs/<文件名>.md`。生成后自检所有链接与 sourceDoc，确保层级正确、与项目约定目录一致。
 ---
@@ -76,6 +81,7 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 **路径提醒**：写入 Rule/Skill/docs-index 时，文档链接 href 和 sourceDoc **必须**严格按「文档路径与链接约定」表执行——Rule 仅用 `../stock-docs/<文件名>.md`，Skill 仅用 `../../stock-docs/<文件名>.md`，docs-index 仅用 `stock-docs/<文件名>.md`，sourceDoc 仅用 `配置根/stock-docs/<文件名>.md`。勿凭印象写错层级。
 **main.mdc 与 docs-index.md 的区别**
 - **main.mdc**（`配置根/rules/main.mdc`）：**项目的总概述和索引**，固定命名 **main**，**唯一** alwaysApply 的 rule。给 AI 看的「体系结构 + 模块一览 + 公共能力入口」，让 AI 大致知道项目结构，需要时再去读各模块的 rule/skill；并在正文中**强制约定**「先查 `docs-index.md` 再下钻」（见 3.0 正文第 4 点），以落实渐进式读取。
 - **docs-index.md**（`配置根/docs-index.md`）：**需求/文档索引**，按文档列出的表格（文档路径、Rules、Skills、简要说明），供人与 AI 查「某文档对应哪些产物」。不参与 alwaysApply，**须由 main 正文显式要求 Agent 在定位文档↔产物时优先读取**，否则不会自动进入上下文。
@@ -88,9 +94,9 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
   2. **模块一览**（表格）：列「模块名」「说明」「详细约定加载方式」。每行对应一个功能模块：说明该模块用途；加载方式写「打开项目约定的该模块路径时自动加载对应 rule；或查阅 配置根/stock-docs/xxx、配置根/skills/xxx」。
   3. **公共能力入口**（若有）：接口与上下文、消息队列、配置、公共工具等入口的简短描述 + 指向对应 rule，并写实现位置（按项目约定，如 ctx 注入、MQ 辅助、配置辅助、模型、公共工具等）。
   4. **全文索引与渐进式读取（必填）**：须单独成段或小节，至少包含以下语义（可压缩措辞，不可删掉任一条）：
-     - **映射表位置**：「文档路径 ↔ Rules / Skills」的完整表在 **`配置根/docs-index.md`**（`docs-index` 非 alwaysApply，不会自动进上下文，须按需打开）。
-     - **读取顺序**：当要根据**某份 stock-docs 文档、某需求/模块名**定位应遵循的规则或应加载的技能时，**应先读取 `docs-index.md`**，在表中找到对应行，再按 **Rules**、**Skills** 列给出的路径打开 `.mdc` / `SKILL.md`；需要长文细节时再打开 **stock-docs** 链出的源文档；仍不足再下钻**业务源码**。
-     - **避免**：在未查 `docs-index.md`、未锁定相关 Rule/Skill 前，对工作区做**无范围**的大面积检索，或通读与当前问题**无关**的长文档。
+    - **映射表位置**：「文档路径 ↔ Rules / Skills」的完整表在 `**配置根/docs-index.md`**（`docs-index` 非 alwaysApply，不会自动进上下文，须按需打开）。
+    - **读取顺序**：当要根据**某份 stock-docs 文档、某需求/模块名**定位应遵循的规则或应加载的技能时，**应先读取 `docs-index.md`**，在表中找到对应行，再按 **Rules**、**Skills** 列给出的路径打开 `.mdc` / `SKILL.md`；需要长文细节时再打开 **stock-docs** 链出的源文档；仍不足再下钻**业务源码**。
+    - **避免**：在未查 `docs-index.md`、未锁定相关 Rule/Skill 前，对工作区做**无范围**的大面积检索，或通读与当前问题**无关**的长文档。
   5. 文末可再单列一行链接提示：**全文索引文件**：`配置根/docs-index.md`（与第 4 点呼应即可）。
 - **main.mdc 的更新时机**：每次执行本技能时，**可能**会更新 main.mdc，**也可能**不更新。
   - **会更新**：若本次文档属于「功能模块」或「公共模块说明」类，需在 main 的「模块一览」或「公共能力入口」中体现，则更新 main（若 main 不存在则先创建；若已存在则只更新与本次文档相关的部分，不删已有且无关的模块行）。
@@ -98,11 +104,14 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 ### 3.1 Rules（专题规则，一律非 alwaysApply）
-- **路径**：`配置根/rules/<主题>-context.mdc`（或拆解后的多条，如 common-interface-ctx.mdc）
-- **格式**：
+- **路径**：`配置根/rules/<主题>-ctx.mdc`（或拆解后的多条，如 common-interface-ctx.mdc）
+- **按配置根区分（必守）**：
+  - `**.cursor/`（Cursor）**：规则文件扩展名 `**.mdc`**；路径范围用 `**globs:**`；专题规则 `**alwaysApply: false**`；总览 `**main.mdc**` 唯一 `**alwaysApply: true**`。
+  - `**.claude/`（Claude Code）**：规则须为 `**.md`**（Claude Code 不加载 `.mdc`）；路径范围用 `**paths:**`，**不要**写 `**globs:`**；**不要**写 `**alwaysApply`**（无 `paths` 的规则与会话一并加载）。若项目同时存在 `.cursor/` 与 `.claude/`，生成或更新 `**.claude/rules/**` 时须按上表写 `**.md**` + `**paths:**`。`flow2spec init claude` 已对包内模板做自动转换，手工新增规则时请对齐官方文档。
+- **格式**（以 **Cursor `.mdc`** 为默认表述；**Claude** 将 `globs`→`paths`、扩展名 `.md` 即可）：
   - frontmatter：`description: <一句话说明本规则>`，**禁止** `alwaysApply: true`（唯一 alwaysApply 为 main.mdc）
-  - **globs（必填）**：按主题限定在相关路径，例如功能模块 → `globs: "**/functions/<模块名>/**"`；接口与 ctx → `globs: "**/functions/**/*.js"`；消息队列消费 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录；公共工具 → `globs: "**/utils/common.js"` 或项目约定的工具路径。
-  - `alwaysApply: false`
+  - **globs（必填，仅 Cursor）**：按主题限定在相关路径，例如功能模块 → `globs: "**/functions/<模块名>/**"`；接口与 ctx → `globs: "**/functions/**/*.js"`；消息队列消费 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录；公共工具 → `globs: "**/utils/common.js"` 或项目约定的工具路径。**Claude Code 下改为 `paths:`，键名同列表写法。**
+  - `alwaysApply: false`（仅 Cursor；Claude 专题规则不写此项）
   - **版本管理（必填）**：`sourceDoc: <本次命令入参，即 配置根/stock-docs/xxx.md>`，`generatedAt: "<当前时间东八区北京时间，ISO 8601 如 2026-01-28T20:00:00+08:00>"`
   - 正文：提炼的**核心概念、关键流程、规则要点**（Markdown，简洁可读）+ **文档链接**（链接 href 必须为 `../stock-docs/<文件名>.md`，见「文档路径与链接约定」）
 - **与 main.mdc 的联动**：仅当本次**会更新** main.mdc 时（见 3.0「main.mdc 的更新时机」）：若本次是功能模块，生成/更新该 rule 后**必须**在 main 的「模块一览」中增加或更新该模块行；若本次是公共模块说明，在 main 的「公共能力入口」中体现即可。若本次**不更新** main，则不改 main.mdc。
@@ -119,18 +128,16 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 - **路径**：`配置根/docs-index.md`
 - **操作**：若文件不存在，先创建表头：
   ```markdown
   # 需求/文档索引
   | 需求/模块 | 文档路径 | Rules | Skills | 简要说明 |
   | --------- | -------- | ----- | ------ | -------- |
   ```
   然后**追加一行**，且**必须填写 Rules、Skills 列**：
   - **Rules**：本次生成的 Rule 路径，多个用顿号或空格分隔，如 `配置根/rules/<主题>-context.mdc` 或 `配置根/rules/common-interface-ctx.mdc`。注意：main.mdc 不在此列逐文档列出（main 为总索引，与单文档非一对一）。
   - **Skills**：本次生成的 Skill 路径，多个用顿号或空格分隔，如 `配置根/skills/<主题>-context/SKILL.md` 或 `配置根/skills/common-modules-context/SKILL.md`、`配置根/skills/common-modules-mq-usage/SKILL.md`。
-  - **文档路径与链接（必守）**：文档路径列显示 `配置根/stock-docs/<文件名>.md`；链接 **必须** 为 `[配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md)`，即 href 只能是 **`stock-docs/<文件名>.md`**（见上文「文档路径与链接约定」）。勿写成 `../stock-docs/` 或误指 **`req-docs/`**。
+  - **文档路径与链接（必守）**：文档路径列显示 `配置根/stock-docs/<文件名>.md`；链接 **必须** 为 `[配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md)`，即 href 只能是 `**stock-docs/<文件名>.md`**（见上文「文档路径与链接约定」）。勿写成 `../stock-docs/` 或误指 `**req-docs/**`。
 - 行示例：`| <文档标题> | [配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md) | <Rules 路径> | <Skills 路径> | <一两句摘要> |`
 - 若文件已存在且表头无 Rules、Skills 列，则先补全表头再追加；追加时仍须填写 Rules、Skills 列。
 - **同一文档只占一行**：若该文档路径（或文档标题）在表中已有行，则**更新该行**（覆盖 Rules、Skills、简要说明），不要追加新行，便于日后「修改文档后重新生成」时索引保持一对一。
@@ -158,7 +165,7 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
   - 接口与 ctx 约定 → `globs: "**/functions/**/*.js"`
   - 消息队列约定 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录
   - 公共工具约定 → `globs: "**/utils/common.js"` 或项目约定路径
-- 每条 rule 的 frontmatter 中 **且必须含** `sourceDoc`、`generatedAt`（同上），正文写该主题的**核心概念、关键流程、规则要点**，可带简短示例；单条建议 &lt;50 行。生成功能模块 rule 后必须在 main.mdc 的「模块一览」中追加/更新对应行。
+- 每条 rule 的 frontmatter 中 **且必须含** `sourceDoc`、`generatedAt`（同上），正文写该主题的**核心概念、关键流程、规则要点**，可带简短示例；单条建议 <50 行。生成功能模块 rule 后必须在 main.mdc 的「模块一览」中追加/更新对应行。
 **Skills 拆分建议：**
@@ -177,20 +184,21 @@ description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触
 ## 步骤 4：若输入是 URL，保存原文到项目
-若用户提供的是 **URL**，请将你拉取到的**原始正文**保存到项目内 **`配置根/stock-docs/<主题>.md`**（或项目约定的文档目录），以便后续引用。主题名可从文档标题或 URL 路径推断，并做合法文件名处理。
+若用户提供的是 **URL**，请将你拉取到的**原始正文**保存到项目内 `**配置根/stock-docs/<主题>.md`**（或项目约定的文档目录），以便后续引用。主题名可从文档标题或 URL 路径推断，并做合法文件名处理。
 ---
 ## 约束与注意
 - 所有路径均相对于**配置根的父目录**。
-- **文档路径与链接（必守）**：一律按上文「文档路径与链接约定」执行。Rule 内链到文档 **仅允许** `../stock-docs/<文件名>.md`；Skill 内链到文档 **仅允许** `../../stock-docs/<文件名>.md`；docs-index 内链到文档 **仅允许** `stock-docs/<文件名>.md`。sourceDoc 仅允许 `配置根/stock-docs/<文件名>.md`。勿将 **`配置根/req-docs/`** 下的技术方案当作本技能产物的链出目标（链出**仅**指向 **stock-docs**）。
+- **文档路径与链接（必守）**：一律按上文「文档路径与链接约定」执行。Rule 内链到文档 **仅允许** `../stock-docs/<文件名>.md`；Skill 内链到文档 **仅允许** `../../stock-docs/<文件名>.md`；docs-index 内链到文档 **仅允许** `stock-docs/<文件名>.md`。sourceDoc 仅允许 `配置根/stock-docs/<文件名>.md`。勿将 `**配置根/req-docs/`** 下的技术方案当作本技能产物的链出目标（链出**仅**指向 **stock-docs**）。
 - **版本管理**：每条 Rule 与每条 Skill 的 frontmatter 必须含 `sourceDoc`（`配置根/stock-docs/xxx.md`）、`generatedAt`（东八区北京时间 ISO 8601 +08:00），便于更新时索源与重新生成。
 - 生成前可先确认 `配置根/rules`、`配置根/skills`、`配置根/stock-docs` 目录存在，不存在则创建。
 - **完成后自检（路径必查）**：
-  1. 每个 `.mdc` 中指向源文档的链接 href 是否为 **`../stock-docs/<文件名>.md`**（不是 `../../stock-docs/` 或误链到 `req-docs/`）。
-  2. 每个 `配置根/skills/**/SKILL.md` 中指向源文档的链接 href 是否为 **`../../stock-docs/<文件名>.md`**（不是 `../stock-docs/` 或误链到 `req-docs/`）。
-  3. `docs-index.md` 中该文档行的链接 href 是否为 **`stock-docs/<文件名>.md`**（不是 `../stock-docs/` 或裸路径）。
-  4. 所有 Rule/Skill 的 frontmatter 中 `sourceDoc` 是否为 **`配置根/stock-docs/<文件名>.md`**。
-  5. 链接目标与项目约定的文档目录一致（若约定为 `配置根/stock-docs/`，则勿用 **`配置根/req-docs/`** 作为链接目标）。
+  1. 每个 `.mdc` 中指向源文档的链接 href 是否为 `**../stock-docs/<文件名>.md`**（不是 `../../stock-docs/` 或误链到 `req-docs/`）。
+  2. 每个 `配置根/skills/**/SKILL.md` 中指向源文档的链接 href 是否为 `**../../stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或误链到 `req-docs/`）。
+  3. `docs-index.md` 中该文档行的链接 href 是否为 `**stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或裸路径）。
+  4. 所有 Rule/Skill 的 frontmatter 中 `sourceDoc` 是否为 `**配置根/stock-docs/<文件名>.md**`。
+  5. 链接目标与项目约定的文档目录一致（若约定为 `配置根/stock-docs/`，则勿用 `**配置根/req-docs/**` 作为链接目标）。
   完成后用一句话总结：已生成 Rules、Skills、文档索引及（若适用）配置根/stock-docs 下的原文备份；并确认「文档路径与链接约定」已遵守。