cgraphx 1.1.0 → 1.3.0

package/dist/.claude-template/skills/clarify-requirements/SKILL.md

@@ -33,11 +33,11 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 你必须为下列每一项创建一个任务,并按顺序完成:
 1. **探索上下文**
    - 按需读项目结构、文档、代码、测试、schema、路由、模型、API、UI、既有约定
-   - 项目里有这些工具可作为上下文补充:
-     - `code-impact-api skill` — 查 docs/knowledge/ 历史决策、业务概念、项目经验
-     - `db-query skill` — 查数据库、查 DDL
-     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径(MCP 优先;MCP 不可用时走 Bash CLI)
-     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史)
+   - 项目里有这些工具可作为上下文补充, 对于符合的场景,必须使用:
+     - `code-impact-api skill` — 查 历史决策、业务概念、项目经验时必须使用
+     - `db-query skill` — 查数据库、查 DDL 时必须使用
+     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径时必须使用
+     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史) 时必须使用
    - 调用前明确告诉用户"我需要先查 X 来理解背景"。收集完简要陈述发现,不要大段贴原文
    - 在假设任务形态之前,先识别当前行为和既有约束
 
@@ -360,6 +360,15 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 边界情况(任务量 2-3 个、文件 3-5 个)由主 agent 根据 plan 是否存在 + 任务独立性判断。
 
+**事后沉淀环节(可选,不在实现前)**:无论选 `/implementation` 还是 `/subagent-implement`,实现推进过程中可按需触发两个事后文档 skill:
+
+| skill | 触发时机 | 产物 | 主题 |
+|---|---|---|---|
+| `/write-api-doc` | 接口开发完毕(不必等所有自测) | `<文件前缀>-接口文档.html` | 仅本次 feature 新增的接口;从 spec 接口章节 + 代码反向提取 |
+| `/code-impact-docgen` | 自测通过后 | `<文件前缀>-设计文档.md` | 整个 feature 的设计(架构/模块/决策);从 knowledge + spec + plan 合成 |
+
+两者互不替代:同一 feature 可以同时产出接口文档和设计文档,各自服务不同读者。默认输出路径都在 `docs/features/<feature-id>/`。
+
 ## 最终输出
 
 结束时,只输出一份澄清总结:
@@ -402,10 +411,12 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 **用户控制的下一步**
 接下来你可以选择:
-- 写 PRD(`/write-prd`)
-- 起草 spec(`/write-spec`)
-- 创建实现计划(`/write-plan`)
+- 写 PRD(`/write-prd`)—— 产物 `<文件前缀>-需求文档.md`
+- 起草 spec(`/write-spec`)—— 产物 `<文件前缀>-spec.md`
+- 创建实现计划(`/write-plan`)—— 产物 `plan/<文件前缀>-index.md` 等
 - 开始实现 —— 根据任务规模选(`/implementation` 简单 / `/subagent-implement` 复杂,详见「下游实现 skill 选择」)
+- 接口开发完毕后 —— 用 `/write-api-doc` 生成 `<文件前缀>-接口文档.html`(只覆盖新增接口,可选)
+- 自测通过后 —— 用 `/code-impact-docgen` 生成 `<文件前缀>-设计文档.md` 沉淀到 feature 目录(可选)
 ```
 
 **输出这份总结后,不再继续。** 不自动调用任何下游 skill,不写代码,不写文档。

package/dist/.claude-template/skills/code-impact-docgen/SKILL.md

@@ -1,90 +1,122 @@
 ---
 name: code-impact-docgen
-description: 从本地图谱知识库召回 AI 导向的知识文档，合成面向人类阅读的业务/技术文档。支持 HTML 和 Markdown 两种输出格式，可按文档类型（business/technical）和章节结构进行配置。
+description: 从本地图谱知识库(docs/knowledge/)和当前 feature 目录下的 spec/plan 召回素材,合成面向研发和技术负责人的"设计文档"。在 feature 自测通过后调用,默认输出到 docs/features/<feature-id>/<文件前缀>-设计文档.md。支持 HTML 和 Markdown 两种输出格式,可按章节结构进行配置。
 ---
 
 # Code Impact DocGen
 
-从本地图谱知识库中召回 AI 导向的知识文档，智能合成面向人类阅读的正式文档。
+从本地图谱知识库和当前 feature 目录下的 spec/plan 召回素材,合成**面向研发和技术负责子的设计文档**。
 
-本 skill 将 `docs/knowledge/` 中为 AI 消费而设计的结构化知识文件（YAML frontmatter + 稳定英文标题）转化为面向业务或技术读者的连贯、精炼、可读性强的文档。输出的文档不包含 YAML frontmatter，不使用 AI 导向的稳定标题，而是按照用户选择的文档类型和章节结构组织内容。
+本 skill 在 feature 实现自测通过后调用,把 `docs/knowledge/` 中的 AI 导向知识文档与当前 feature 目录下的 spec/plan 一起,合成为连贯、精炼、可读性强的设计文档。输出文档不含 YAML frontmatter,不使用 AI 导向的稳定标题,按设计文档的章节结构组织内容。
+
+**典型场景**:用户完成 feature 实现 + 自测后,说"生成设计文档"、"写设计文档"、"用 docgen 沉淀一下"——本 skill 召回 knowledge + 读取 spec/plan,合成一份设计文档落到 feature 目录。
 
 ## Trigger
 
-使用此 skill 当：
+使用此 skill 当:
 
-- 用户要求基于项目知识生成文档、报告或说明
-- 用户说"写一份文档"、"生成报告"、"整理成文档"、"写个说明"等
-- 用户要求对某个概念、领域、系统或模块生成人类可读的概述
-- 用户要求把知识库中的内容整理为可供分享或归档的文档
-- 用户要求生成 HTML 或 Markdown 格式的正式文档
+- 用户完成 feature 自测后要求"生成设计文档"、"写设计文档"、"沉淀设计文档"
+- 用户要求基于 spec/plan 和项目知识库合成一份技术文档
+- 用户说"用 docgen 生成"、"自测完了,该写设计文档了"
+- 用户要求把 spec + plan + knowledge 整理为一份可分享的设计文档
+- 用户要求生成 HTML 或 Markdown 格式的设计文档
 
-不要使用此 skill 当：
+不要使用此 skill 当:
 
-- 创建或编辑 AI 导向的知识文件（使用 `code-impact-markdown` skill）
-- 查询知识以辅助代码编辑（使用 `code-impact-api` skill）
-- 探索陌生项目（使用 `code-impact-init` skill）
+- 创建或编辑 AI 导向的知识文件(使用 `code-impact-markdown` skill)
+- 查询知识以辅助代码编辑(使用 `code-impact-api` skill)
+- 探索陌生项目(使用 `code-impact-init` skill)
+- 写 PRD(使用 `write-prd` skill,设计文档是事后沉淀,PRD 是事前业务确认)
+- 写 spec(使用 `write-spec` skill,设计文档不重新定义规格契约)
+- 写 plan(使用 `write-plan` skill)
 
 ## 依赖
 
 - cgraphx 已安装(`cgraphx --version` 可跑)
 - 项目已跑过 `cgraphx docs index`,索引中有知识文档数据(用 `cgraphx docs concepts` 验证)
-- 若索引为空:先按 `code-impact-markdown` skill 写文档到 `docs/knowledge/`,再 `cgraphx docs index`
+- 若 knowledge 索引为空:先按 `code-impact-markdown` skill 写文档到 `docs/knowledge/`,再 `cgraphx docs index`
+- 当前 feature 目录下应有 spec(`docs/features/<feature-id>/<文件前缀>-spec.md`)和/或 plan(`docs/features/<feature-id>/plan/`)
+
+## 内容来源规格
+
+设计文档的内容来源**必须包含两类**:
+
+1. **`docs/knowledge/` 中的 AI 导向知识文档** — 通过 `cgraphx docs find` 召回,提供项目级架构、决策、风险等背景
+2. **当前 feature 目录下的 spec 和 plan** — 直接 Read,提供本 feature 的目标、契约、任务拆分、技术约束
+
+**两类来源都不可缺**:若 knowledge 为空且 feature 目录无 spec/plan,skill 必须拒绝生成,提示用户先准备素材。
+
+## feature-id 与文件前缀规则
+
+**feature-id 识别(优先级从高到低)**:
+
+1. 用户调用时显式传 feature-id 或输出路径参数 → 使用用户指定
+2. skill 自动从 cwd 向上探测最近的 `docs/features/<feature-id>/` 目录 → 使用探测结果
+3. 都失败 → skill 报错并要求用户显式传 feature-id 或输出路径
+
+**文件前缀算法**:
+
+feature-id 格式:`YYYY-MM-DD-[业务ID-]<标题>`
+
+- 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
+- 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
+
+业务ID 段允许字母数字 + 连字符;标题段允许中文、英文或混合。**不得**对中文做英文 slug 转换。
 
-## 知识召回流程
+文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`;若含敏感字符,要求用户重命名,不自动替换。
 
-生成文档前，必须通过以下流程收集源材料。不要凭空编写内容——所有内容必须基于图谱中已有的知识文档。
+**默认输出路径**:`docs/features/<feature-id>/<文件前缀>-设计文档.md`(或 `.html`)
 
-### 第一步：确认需求
+用户可显式参数覆盖默认路径。
 
-向用户确认（如果未明确指定）：
+## 召回与生成流程
 
-1. **主题范围** — 一个 concept 名称、一个 domain、一个系统/模块名称，或一个自由描述
-2. **文档类型** — `business`（面向业务读者）或 `technical`（面向技术人员）
-3. **输出格式** — `html` 或 `md`
-4. **可选：目标章节** — 用户可以选择包含或排除哪些章节（见章节菜单）
+生成设计文档前,必须通过以下流程收集源材料。不要凭空编写内容——所有事实性内容必须来自上述两类来源。
 
-如果用户未指定文档类型，根据主题范围自动判断：
+### 第一步:确认需求与识别 feature-id
 
-- 主题涉及业务流程、产品功能、项目规划 → 默认 `business`
-- 主题涉及代码架构、模块设计、技术实现 → 默认 `technical`
-- 不确定时向用户确认
+向用户确认(如果未明确指定):
 
-### 第二步：召回知识文档
+1. **feature-id / 输出路径** — 默认按上方规则识别,用户可覆盖
+2. **输出格式** — `html` 或 `md`
+3. **可选:目标章节** — 用户可以选择包含或排除哪些章节(见章节菜单)
+4. **可选:主题范围补充** — 若 feature spec/plan 之外还有特定主题需要覆盖,用户可补充
 
-根据主题范围选择召回方式（用 `cgraphx docs` CLI）：
+### 第二步:召回 knowledge 文档
 
-**按概念精确过滤（推荐，召回最精准）：**
+用 `cgraphx docs find` 按 concept/domain/keyword/tag 过滤(见下方命令)。
+
+**按概念精确过滤(推荐,召回最精准)**:
 
 ```bash
 cgraphx docs find --concept=<concept-name> --limit=20
 ```
 
-**按 domain 过滤（覆盖整个业务领域）：**
+**按 domain 过滤(覆盖整个业务领域)**:
 
 ```bash
 cgraphx docs find --domain=<domain-name> --limit=20
 ```
 
-**按关键词子串匹配（适合模糊探索；LIKE on title + Summary）：**
+**按关键词子串匹配(适合模糊探索;LIKE on title + Summary)**:
 
 ```bash
 cgraphx docs find --q=<关键词> --limit=20
 ```
 
-**按 tag 过滤（横向主题分组）：**
+**按 tag 过滤(横向主题分组)**:
 
 ```bash
 cgraphx docs find --tag=<tag-name> --limit=20
 ```
 
-**组合多维过滤（交集）：**
+**组合多维过滤(交集)**:
 
 ```bash
 cgraphx docs find --concept=X --domain=Y --status=active --type=decision
 ```
 
-**列出全部 concept / domain / tag（找主题入口）：**
+**列出全部 concept / domain / tag(找主题入口)**:
 
 ```bash
 cgraphx docs concepts     # 跨文档去重的 concept + 各自关联文档数 + 所属 domain
@@ -94,9 +126,19 @@ cgraphx docs tags
 
 `find` 输出每条结果包含 `title` / `document_type` / `status` / `updated` / `summary`(Summary 章节文本) / `path`(项目根相对,供 Read)。
 
-### 第三步：读取文档详情
+### 第三步:读取 feature 目录下的 spec 和 plan
+
+Read 以下文件(若存在):
+
+- `docs/features/<feature-id>/<文件前缀>-spec.md` — 拿到目标、范围、业务规则、技术约束、不可留实现期决策
+- `docs/features/<feature-id>/plan/<文件前缀>-index.md` — 拿到任务拆分、依赖图、改动范围
+- `docs/features/<feature-id>/plan/<文件前缀>-01-schema.md` 等按需子文件 — 拿到具体 schema/接口/前端任务细节
 
-`find` 返回的 `summary` 是 `## Summary` 章节内容,通常是文档的核心结论。**如果 Summary 不够,**用 `path` 字段直接 Read 原文件:
+如果 feature 目录下还没有 spec/plan(比如 plan 不存在),如实标注"无 plan 文件,任务拆分章节缺失",不要凭空补。
+
+### 第四步:读取 knowledge 详情
+
+`find` 返回的 `summary` 是 `## Summary` 章节内容,通常是文档的核心结论。**如果 Summary 不够**,用 `path` 字段直接 Read 原文件:
 
 ```bash
 cgraphx docs show <doc-id-or-path>     # 输出 frontmatter 元数据 + Summary
@@ -106,9 +148,9 @@ Read <path>                              # 拿到完整原文(含 Context / Deci
 
 **重要**:**只有 `## Summary` 进 cgraphx 索引**,其他章节(Context / Decisions / Findings / Steps / ...)留在文件里。生成文档时,这些章节的内容来源是 **Read 文件原文**,不是图谱字段。
 
-### 第四步：探索关联知识（可选，按需）
+### 第五步:探索关联知识(可选,按需)
 
-如果需要更全面的背景（文档间引用关系）:
+如果需要更全面的背景(文档间引用关系):
 
 ```bash
 cgraphx docs refs <doc-id-or-path>
@@ -119,127 +161,94 @@ cgraphx docs refs <doc-id-or-path>
 
 适合"这个决策被哪些文档引用了"、"还有哪些相关文档"的扩展召回。
 
-### 第五步：合成文档
+### 第六步:合成设计文档
 
-基于召回的全部源材料，按照用户选择的文档类型和章节结构生成文档。见后续章节。
+基于 knowledge + spec/plan 两类来源,按章节菜单重组内容,生成设计文档。见后续章节。
 
-## 文档类型
+## 设计文档定位
 
-用户选择 `business` 或 `technical`，决定文档的读者定位、语气和结构。
+- **读者**:研发工程师、架构师、技术负责人、后续维护者
+- **语气**:精确、专业,包含技术细节
+- **结构重点**:架构设计、核心模块、数据流、技术决策、已知限制、扩展方向
+- **典型场景**:feature 实现自测通过后,作为事后技术沉淀归档
+- **与 spec 的区别**:spec 是事前契约,设计文档是事后沉淀;设计文档不得重新定义 spec 的契约
 
-### business（面向业务读者）
+## 章节菜单
 
-- **读者**：项目经理、产品经理、业务决策者、新成员
-- **语气**：非技术性，侧重价值、流程、决策理由
-- **结构重点**：背景与目标、业务流程、关键决策、影响与价值
-- **技术细节处理**：将技术概念转化为业务可理解的描述，必要时放在附录中
-- **默认章节**：背景与目标、核心能力、业务流程、关键决策、现状与展望
+用户可以选择包含哪些章节。以下为完整章节库。
 
-### technical（面向技术读者）
+### 默认章节(用户未指定时全部包含)
 
-- **读者**：开发工程师、架构师、技术负责人
-- **语气**：精确、专业，包含技术细节
-- **结构重点**：架构设计、数据流、技术决策、已知问题、扩展方向
-- **默认章节**：概述、架构设计、核心模块、技术决策、已知限制、扩展方向
+| 章节名 | 用途 | 主来源 |
+|--------|------|--------|
+| 概述 / Overview | 设计文档覆盖的主题、目标和定位 | spec 目标与范围 + knowledge Summary |
+| 架构设计 / Architecture | 系统架构和数据流 | spec 系统行为 + knowledge Summary + Read 原文 |
+| 核心模块 / Core Modules | 各模块职责和交互 | plan 任务拆分 + knowledge Summary |
+| 技术决策 / Key Decisions | 重要技术决策及理由 | spec 不可留实现期决策 + knowledge Decisions |
+| 已知限制 / Known Limits | 技术约束和已知问题 | spec 待确认项 + knowledge Findings/Risks |
+| 扩展方向 / Extension Points | 可扩展点和改进方向 | knowledge Outlook |
 
-## 章节菜单
+### 可选章节(按需添加)
 
-用户可以选择包含哪些章节。以下为完整章节库，按文档类型标记适用范围。
-
-### 通用章节（business + technical）
-
-| 章节名 | 用途 | business | technical |
-|--------|------|----------|-----------|
-| 背景与目标 / Overview | 文档覆盖的主题和目标 | 默认 | 默认（概述） |
-| 核心能力 / Key Capabilities | 系统或模块的主要能力 | 默认 | 默认 |
-| 关键决策 / Key Decisions | 重要技术或业务决策及理由 | 默认 | 默认 |
-| 现状与展望 / Status & Outlook | 当前状态、已知限制、未来方向 | 默认 | 默认 |
-| 术语表 / Glossary | 关键术语和定义 | 可选 | 可选 |
-| 相关资源 / References | 相关文档和代码链接 | 可选 | 可选 |
-
-### business 专属章节
-
-| 章节名 | 用途 |
-|--------|------|
-| 业务流程 / Business Flow | 业务操作流程和规则 |
-| 用户场景 / Use Cases | 典型使用场景描述 |
-| 价值与影响 / Value & Impact | 对业务的价值和影响 |
-| 风险与注意事项 / Risks | 已知风险和注意事项 |
-| 常见问题 / FAQ | 业务层面的常见问题 |
-
-### technical 专属章节
-
-| 章节名 | 用途 |
-|--------|------|
-| 架构设计 / Architecture | 系统架构和数据流 |
-| 核心模块 / Core Modules | 各模块职责和交互 |
-| 数据模型 / Data Model | 数据结构和存储方案 |
-| API 参考 / API Reference | 接口和端点说明 |
-| 性能特征 / Performance | 性能瓶颈和优化方向 |
-| 已知限制 / Known Limits | 技术约束和已知问题 |
-| 扩展方向 / Extension Points | 可扩展点和改进方向 |
-| 运维指南 / Operations | 部署、监控、故障排除 |
+| 章节名 | 用途 | 主来源 |
+|--------|------|--------|
+| 数据模型 / Data Model | 数据结构和存储方案 | plan schema 任务 + spec 数据口径 |
+| API 参考 / API Reference | 接口和端点说明 | spec 接口边界 + plan backend 任务 |
+| 性能特征 / Performance | 性能瓶颈和优化方向 | knowledge Findings |
+| 运维指南 / Operations | 部署、监控、故障排除 | knowledge Operations |
+| 术语表 / Glossary | 关键术语和定义 | spec 术语章节 + knowledge 各字段术语 |
+| 相关资源 / References | 相关文档和代码链接 | spec / plan / knowledge 引用 |
 
 ### 章节选择规则
 
 - 用户可以明确指定要包含的章节
 - 用户可以从默认章节中排除不需要的章节
-- 如果用户未指定，使用对应文档类型的默认章节
+- 如果用户未指定,使用上述全部默认章节
 - 按照上述表格顺序排列章节
 
 ## 输出格式
 
 ### HTML 格式
 
-生成单文件独立 HTML 文档，特点：
-
-- **内联 CSS**：不依赖外部样式表，所有样式写在 `<style>` 标签内
-- **响应式布局**：使用 CSS 变量控制主题，支持不同屏幕宽度
-- **打印友好**：包含 `@media print` 样式
-- **浅色阅读主题**：白色背景，高对比度，适合长时间阅读
-- **字体**：`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`
-- **代码块**：等宽字体，浅灰背景，圆角边框
-- **表格**：斑马纹行，边框分隔
-- **目录**：文档开头自动生成可点击目录（锚点链接）
+生成单文件独立 HTML 文档,特点:
 
-生成前阅读对应模板文件获取完整 CSS 和结构参考：
+- **内联 CSS**:不依赖外部样式表,所有样式写在 `<style>` 标签内
+- **响应式布局**:使用 CSS 变量控制主题,支持不同屏幕宽度
+- **打印友好**:包含 `@media print` 样式
+- **浅色阅读主题**:白色背景,高对比度,适合长时间阅读
+- **字体**:`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`
+- **代码块**:等宽字体,浅灰背景,圆角边框
+- **表格**:斑马纹行,边框分隔
+- **目录**:文档开头自动生成可点击目录(锚点链接)
 
-| 文档类型 | 模板文件 |
-|----------|----------|
-| business | [template-business-html.md](template-business-html.md) |
-| technical | [template-technical-html.md](template-technical-html.md) |
+生成前阅读对应模板文件获取完整 CSS 和结构参考:[template-design-html.md](template-design-html.md)
 
 ### Markdown 格式
 
-生成干净的 Markdown 文档，特点：
-
-- **无 YAML frontmatter**：与 `docs/knowledge/` 中的 AI 导向文档不同
-- **层级标题**：`#`（文档标题）、`##`（章节）、`###`（子章节）
-- **代码块**：三个反引号围栏代码块，标注语言
-- **表格**：标准 Markdown 表格
-- **链接**：`[文本](url)` 格式，优先使用相对路径
-- **目录**：文档开头用标题列表作为目录
-- **元信息**：文档开头用引用块注明生成日期和主题范围
+生成干净的 Markdown 文档,特点:
 
-生成前阅读对应模板文件：
+- **无 YAML frontmatter**:与 `docs/knowledge/` 中的 AI 导向文档不同
+- **层级标题**:`#`(文档标题)、`##`(章节)、`###`(子章节)
+- **代码块**:三个反引号围栏代码块,标注语言
+- **表格**:标准 Markdown 表格
+- **链接**:`[文本](url)` 格式,优先使用相对路径
+- **目录**:文档开头用标题列表作为目录
+- **元信息**:文档开头用引用块注明生成日期、主题范围、feature-id
 
-| 文档类型 | 模板文件 |
-|----------|----------|
-| business | [template-business-md.md](template-business-md.md) |
-| technical | [template-technical-md.md](template-technical-md.md) |
+生成前阅读对应模板文件:[template-design-md.md](template-design-md.md)
 
 ## 图表绘制
 
-当文档中需要使用图表（流程图、时序图、架构图、状态图等）来辅助说明时，遵循以下规则：
+当文档中需要使用图表(流程图、时序图、架构图、状态图等)来辅助说明时,遵循以下规则:
 
-- **优先使用 Mermaid**：在保证表达效果的前提下，优先使用 Mermaid 语法绘制图表，以确保文档的纯文本可维护性和跨平台渲染一致性
-- 适用的图表类型包括但不限于：`flowchart`（流程图）、`sequenceDiagram`（时序图）、`classDiagram`（类图）、`stateDiagram`（状态图）、`erDiagram`（ER 图）、`gantt`（甘特图）
-- 图表应放在相关的章节中，紧跟在解释性文字之后
+- **优先使用 Mermaid**:在保证表达效果的前提下,优先使用 Mermaid 语法绘制图表,以确保文档的纯文本可维护性和跨平台渲染一致性
+- 适用的图表类型包括但不限于:`flowchart`(流程图)、`sequenceDiagram`(时序图)、`classDiagram`(类图)、`stateDiagram`(状态图)、`erDiagram`(ER 图)、`gantt`(甘特图)
+- 图表应放在相关的章节中,紧跟在解释性文字之后
 - 每张图表前应有简短的文字说明其用途
-- 图表内容应精简，避免过于复杂；如果信息量过大，拆分为多张图表
-- 仅当 Mermaid 无法表达所需的视觉效果时（如复杂的手绘风格、特殊布局），才使用外部图片或 SVG
+- 图表内容应精简,避免过于复杂;如果信息量过大,拆分为多张图表
+- 仅当 Mermaid 无法表达所需的视觉效果时(如复杂的手绘风格、特殊布局),才使用外部图片或 SVG
 
-Markdown 格式中使用 Mermaid 代码块：
+Markdown 格式中使用 Mermaid 代码块:
 
 ````markdown
 ```mermaid
@@ -250,7 +259,7 @@ flowchart TD
 ```
 ````
 
-HTML 格式中使用 Mermaid 代码块（依赖 Mermaid.js CDN 渲染），模板中需引入 Mermaid 脚本：
+HTML 格式中使用 Mermaid 代码块(依赖 Mermaid.js CDN 渲染),模板中需引入 Mermaid 脚本:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
@@ -263,35 +272,39 @@ flowchart TD
 
 ## 合成规则
 
-生成文档时遵循以下规则，确保从多个 AI 知识文档合成出连贯的人类文档。
+生成设计文档时遵循以下规则,确保从 knowledge + spec/plan 合成出连贯的人类文档。
 
 ### 内容来源
 
-- 所有事实性内容必须来自图谱中召回的知识文档
+- 所有事实性内容必须来自 knowledge 文档或 feature 目录下的 spec/plan
 - 不要编造不存在的细节、数据或结论
-- 如果某个方面的知识缺失，在文档中如实标注"待补充"或省略该部分
-- 可以基于多个文档的内容进行归纳和总结，但归纳必须忠实于原文
+- 如果某个方面的知识缺失,在文档中如实标注"待补充"或省略该部分
+- 可以基于多个来源进行归纳和总结,但归纳必须忠实于原文
+- 设计文档**不得**重新定义 spec 已锁定的契约;若发现 spec 与代码现实不符,标注【待确认】而不是自行解释
 
 ### 结构重组
 
-- AI 知识文档使用稳定英文标题（Summary、Findings、Decisions 等）按分析目的组织
-- 人类文档按阅读目的组织（背景、流程、决策等）
-- **必须重新组织内容结构**，不要照搬 AI 文档的标题和章节
-- 相关信息应合并到同一章节，避免内容分散
-- 去除重复信息：多个 AI 文档可能包含相同的背景信息，只需出现一次
+- knowledge 用稳定英文标题(Summary、Findings、Decisions 等)按分析目的组织
+- spec/plan 用研发视角章节(目标、范围、任务、约束等)按交付目的组织
+- 设计文档按"知识传递"目的组织(概述、架构、模块、决策、限制、扩展)
+- **必须重新组织内容结构**,不要照搬 knowledge 的标题或 spec/plan 的章节
+- 相关信息应合并到同一章节,避免内容分散
+- 去除重复信息:knowledge 和 spec/plan 可能包含相同的背景信息,只需出现一次
 
 ### 语气转换
 
-- AI 知识文档的语气是"分析记录"（记录观察、证据、影响）
-- 人类文档的语气是"知识传递"（解释、说明、指导）
+- knowledge 的语气是"分析记录"(记录观察、证据、影响)
+- spec/plan 的语气是"契约 / 任务清单"(规则、约束、步骤)
+- 设计文档的语气是"知识传递"(解释、说明、指导)
 - 将被动描述转为主动解释
-- 将技术分析转为可操作的指导（technical 类型）或可理解的概述（business 类型）
+- 将技术分析转为可操作的指导
 
 ### 引用和溯源
 
-- 不要在人类文档中引用 AI 文档的路径或文件名
-- 如需引用代码文件，使用相对路径
-- 如需引用外部文档，使用 URL 或文档标题
+- 不要在设计文档中引用 knowledge 文档的路径或文件名
+- 不要在文档中引用 spec/plan 的文件路径(读者已经在 feature 目录里)
+- 如需引用代码文件,使用相对路径
+- 如需引用外部文档,使用 URL 或文档标题
 
 ## 语言和风格规则
 
@@ -299,9 +312,9 @@ flowchart TD
 
 - 文档正文用**中文**编写
 - 技术术语、代码标识符、文件路径、函数名、类名保留原始英文
-- 章节标题可使用中英双语格式："架构设计 / Architecture"（英文部分用于 HTML 锚点兼容性）
+- 章节标题可使用中英双语格式:"架构设计 / Architecture"(英文部分用于 HTML 锚点兼容性)
 - 代码示例中的注释使用中文
-- 专有名词（如 Neo4j、pgvector、BM25、RRF）保留英文原名
+- 专有名词(如 Neo4j、pgvector、BM25、RRF)保留英文原名
 
 ### 排版
 
@@ -310,57 +323,54 @@ flowchart TD
 - 重要概念第一次出现时加粗
 - 代码块标注语言类型
 - 表格使用标准格式
-- 列表项以动词或名词开头，保持一致
-- 避免过长的段落（超过 5 行应考虑拆分）
+- 列表项以动词或名词开头,保持一致
+- 避免过长的段落(超过 5 行应考虑拆分)
 
 ### 风格
 
 - 精炼、直接、避免冗余
-- 每句话传递信息，不写废话
+- 每句话传递信息,不写废话
 - 使用主动语态
-- 避免模糊措辞（如"可能"、"也许"），除非表达不确定性
-- 不确定性用明确标注："当前不确定"、"待验证"
+- 避免模糊措辞(如"可能"、"也许"),除非表达不确定性
+- 不确定性用明确标注:"当前不确定"、"待验证"
 
 ## 保存位置
 
-生成的人类文档**必须**保存到 `docs/published/` 目录中，**不要**直接保存到 `docs/` 根目录，也**不要**保存到 `docs/knowledge/`（该目录专用于 AI 导向的知识文件）。
+**默认保存路径**:`docs/features/<feature-id>/<文件前缀>-设计文档.md`(或 `.html`)
 
-`docs/published/` 目录不存在时创建。
+feature-id 和文件前缀规则见上方"feature-id 与文件前缀规则"章节。用户可显式参数覆盖默认路径。
 
 ### 文件命名
 
-```text
-# 格式：主题关键词.格式
-hybrid-search-architecture.md
-knowledge-pipeline-overview.html
-project-status-report.md
-```
-
-- 使用英文短横线分隔
-- 文件名使用英文（便于 URL 兼容和跨平台）
-- 文件名应反映文档内容而非日期
+- 使用 `<文件前缀>-设计文档.md` 或 `<文件前缀>-设计文档.html` 命名
+- 文件前缀算法:有业务ID 时为 `<业务ID>-<标题>`,无业务ID 时为 `<标题>`
+- 文件前缀允许中文(如 `features目录结构调整-设计文档.md`)
+- 不做中文 → 英文 slug 转换
+- 文件名不得包含敏感字符 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
 
 ### 生成后
 
-保存文件后：
+保存文件后:
 
-1. 告知用户文件保存位置
+1. 告知用户文件保存位置(默认 feature 目录路径)
 2. 简要说明文档覆盖的内容范围
-3. 如有知识缺失（图谱中未覆盖的重要方面），列出"可能需要补充的知识"
-4. 不触发分析（本 skill 只读取知识，不写入 `docs/knowledge/`）
+3. 如有知识缺失(knowledge 和 spec/plan 都未覆盖的重要方面),列出"可能需要补充的知识"
+4. 不触发分析(本 skill 只读取 knowledge + spec/plan,不写入 `docs/knowledge/`)
 
 ## 完整生成流程
 
-1. **确认需求** — 与用户确认主题范围、文档类型（business/technical）、输出格式（html/md）、章节选择
-2. **召回知识** — 用 `cgraphx docs find` 按概念/领域/关键词过滤,收集相关文档(Summary + path)
-3. **读取详情** — Summary 不够时,用 `cgraphx docs show` 或直接 `Read <path>` 拿完整原文
-4. **评估覆盖度** — 检查召回的知识是否足够覆盖用户请求的主题，如果不足告知用户
-5. **合成内容** — 按照选定的文档类型和章节结构，重组和改写知识内容
-6. **格式化输出** — 按照 HTML 或 Markdown 的格式规则生成完整文档
-7. **质量检查** — 检查文档是否满足以下条件：
-   - 所有事实性内容有知识来源
+1. **确认需求与识别 feature-id** — 与用户确认输出格式、章节选择;按规则识别 feature-id 和文件前缀
+2. **召回 knowledge** — 用 `cgraphx docs find` 按概念/领域/关键词过滤,收集相关文档(Summary + path)
+3. **读取 feature 目录** — Read spec、plan/index、plan/子文件,拿到本 feature 的契约和任务
+4. **读取 knowledge 详情** — Summary 不够时,用 `cgraphx docs show` 或直接 `Read <path>` 拿完整原文
+5. **评估覆盖度** — 检查 knowledge + spec/plan 是否足够覆盖设计文档的章节;如果不足告知用户
+6. **合成内容** — 按照章节菜单,从 knowledge 和 spec/plan 重组、改写、整合内容
+7. **格式化输出** — 按照 HTML 或 Markdown 的格式规则生成完整文档
+8. **质量检查** — 检查文档是否满足以下条件:
+   - 所有事实性内容有 knowledge 或 spec/plan 来源
    - 章节结构完整、逻辑连贯
-   - 语言风格符合文档类型定位
+   - 语言风格符合设计文档定位
    - 格式正确、排版整洁
-8. **保存文件** — 写入 `docs/published/` 目录
-9. **反馈** — 告知用户保存位置和内容范围，列出知识缺失（如有）
+   - 没有重新定义 spec 已锁定的契约
+9. **保存文件** — 写入 `docs/features/<feature-id>/<文件前缀>-设计文档.md`(或 `.html`)
+10. **反馈** — 告知用户保存位置和内容范围,列出知识缺失(如有)