cgraphx 1.4.3 → 2.0.1

package/dist/.claude-template/skills/write-api-doc/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write-api-doc
-description: 在 feature 接口开发完毕后(可选环节),从 spec 的接口章节 + 实际代码反向提取,生成静态只读 HTML 接口文档,默认输出到 docs/features/<feature-id>/<文件前缀>-接口文档.html。覆盖本次 feature 新增的接口(严格新增,不含修改),支持 Node/Python/Java/Go/Rust/C#/PHP/Ruby 主流 web 框架。不依赖 cgraphx 索引、不做交互式 Swagger、不重新定义 spec。
+disable-model-invocation: true
+description: 在 feature 接口开发完毕后(可选环节),从 spec 的接口章节 + 实际代码反向提取,生成静态只读 HTML 接口文档,默认输出到 docs/features/<feature-id>/<文件前缀>-接口文档.html。覆盖本次 feature 新增的接口(严格新增,不含修改),支持 Node/Python/Java/Go/Rust/C#/PHP/Ruby 主流 web 框架。不做交互式 Swagger、不重新定义 spec。
 ---
 
 # Write API Doc
@@ -15,7 +16,7 @@ description: 在 feature 接口开发完毕后(可选环节),从 spec 的接口
 不要重新定义 spec 已锁定的接口契约、参数语义、错误码、权限边界。如果发现 spec 与代码现实不符,标注【待确认】而不是自行解释。
 不要编造未在代码或 spec 中体现的接口、参数、响应字段或错误码。
 范围严格限定"本次 feature 新增的接口",不得自行扩展到修改的老接口或全项目接口。
-不依赖 cgraphx 索引;不调用 codegraph_explore / cgraphx CLI;只用 grep + Read。
+只用 grep + Read 查代码;不依赖外部图谱或索引工具。
 </HARD-GATE>
 
 ## Trigger
@@ -29,13 +30,13 @@ description: 在 feature 接口开发完毕后(可选环节),从 spec 的接口
 不要使用此 skill 当:
 
 - 写 spec(使用 `write-spec` skill,接口文档不重新定义规格契约)
-- 写设计文档(使用 `code-impact-docgen` skill,设计文档覆盖架构/模块/决策,接口文档只覆盖接口)
-- 探索陌生项目(使用 `code-impact-init` skill)
-- 查询代码调用关系(使用 `cgraphx` skill 或 `codegraph_explore` MCP)
+- 写设计文档(使用 `write-design-doc` skill,设计文档覆盖架构/模块/决策,接口文档只覆盖接口)
+- 探索陌生项目(使用 `knowledge-init` skill)
+- 查询代码调用关系(使用 grep / Read)
 
-## 与 code-impact-docgen 的边界
+## 与 write-design-doc 的边界
 
-| 维度 | write-api-doc | code-impact-docgen |
+| 维度 | write-api-doc | write-design-doc |
 |---|---|---|
 | 主题 | 仅接口 | 整个 feature 的设计(架构/模块/决策/限制/扩展) |
 | 来源 | spec 接口章节 + 代码 | knowledge + spec + plan |

package/dist/.claude-template/skills/write-design-doc/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: write-design-doc
+disable-model-invocation: true
+description: 功能发布后(或自测通过后)按需执行——从本地图谱知识库(docs/knowledge/)和当前 feature 目录下的 spec/plan 召回素材,合成面向研发和技术负责人的"设计文档"。默认输出到 docs/features/<feature-id>/<文件前缀>-设计文档.md。支持 HTML 和 Markdown 两种输出格式,可按章节结构进行配置。不在开发主链上,不参与流程门禁,纯事后文档合成。
+---
+
+# 生成设计文档 (Write Design Doc)
+
+## 定位
+
+- **发布后的事后文档,不在开发主链上**:功能发布后(或自测通过后)按需执行,从 `docs/knowledge/` 召回项目级背景(cgraphx docs),读 feature 目录的 spec/plan,合成给研发/技术负责人/维护者读的设计文档("生成设计文档"、"沉淀一下设计文档"时触发)。
+- **两类来源缺一不可**:knowledge 给项目级架构/决策/风险;spec/plan 给本 feature 的目标/契约/任务拆分。knowledge 为空且无 spec/plan → **拒绝生成**,提示先备素材。
+- **事后沉淀,不是契约**:不得重新定义 spec 已锁定的契约;发现 spec 与代码现实不符,标【待确认】,不自行解释。
+- **边界**:写知识文件 → `knowledge-write`;查知识辅助编码 → `knowledge-api`;探索陌生项目 → `knowledge-init`;PRD/spec/plan → 各自 skill。
+
+## 依赖
+
+- cgraphx 已装、`docs index` 已跑(用 `docs concepts` 验证;索引为空 → 先按 `knowledge-write` 沉淀再 index)。
+- feature 目录下有 spec(`<文件前缀>-spec.md`)和/或 plan(`plan/`)。
+
+## 流程
+
+1. **确认**:feature-id/输出路径(默认按下方规则,用户可覆盖)、输出格式(html/md)、目标章节(默认全含默认章节)、可选的主题范围补充。
+2. **召回 knowledge**:`cgraphx docs find` —— 推荐 `--concept=<名>`(最精准);或 `--domain=` / `--q=<词>`(整串 LIKE title+Summary)/ `--tag=`,多维组合取交集;用 `docs concepts/domains/tags` 找主题入口。每条结果含 title/document_type/status/updated/summary/path。
+3. **读 feature 目录**:spec(目标/规则/约束/不可留实现期决策)+ `plan/<前缀>-index.md`(任务/依赖/范围)+ 按需子文件。plan 不存在 → 如实标注"无 plan,任务拆分章节缺失",不凭空补。
+4. **读 knowledge 详情**:Summary 不够 → `docs show <id>` 或直接 `Read <path>`(只有 Summary 进索引,其余章节靠 Read 原文);需扩展召回 → `docs refs` 看双向引用。
+5. **评估覆盖度**:两类来源不足以覆盖所计划章节 → 告知用户缺什么。
+6. **合成 + 格式化**:按章节菜单重组(见「合成规则」),按所选格式读模板生成:[template-design-html.md](template-design-html.md) / [template-design-md.md](template-design-md.md)。
+7. **质量检查**:所有事实有来源 · 章节连贯 · 未重定义 spec 契约 · 格式排版。
+8. **保存 + 反馈**:写入路径;告知位置 + 覆盖范围;列出"可能需要补充的知识"(如有)。本 skill 只读,不写 `docs/knowledge/`。
+
+## 章节菜单
+
+**默认章节**(未指定时全含,按此顺序):
+
+| 章节 | 用途 | 主来源 |
+|---|---|---|
+| 概述 / 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 |
+
+**可选章节**(按需):数据模型 / Data Model(plan schema + spec 口径)· API 参考 / API Reference(spec 接口边界 + plan backend)· 性能特征 / Performance(knowledge Findings)· 运维指南 / Operations(knowledge Operations)· 术语表 / Glossary(spec 术语 + knowledge 术语)· 相关资源 / References(spec/plan/knowledge 引用)。
+
+用户可指定包含/排除;未指定 → 全部默认章节。
+
+## 合成规则
+
+- **来源**:所有事实性内容来自 knowledge 或 spec/plan,不编造;缺失 → 如实标"待补充"或省略;可归纳但必须忠实原文。
+- **结构重组**:设计文档按"知识传递"组织(概述/架构/模块/决策/限制/扩展);**不照搬** knowledge 的标题或 spec/plan 的章节;相关信息进同一章节;重复信息合并只出现一次。
+- **语气转换**:knowledge 是分析记录、spec/plan 是契约/清单 → 设计文档是知识传递:被动描述转主动解释,技术分析转可操作指导。
+- **引用溯源**:不引用 knowledge 文档路径、不引用 spec/plan 路径(读者已在 feature 目录);引代码用相对路径,引外部文档用 URL/标题。
+
+## 语言与风格
+
+- 正文中文;技术术语/标识符/路径/专有名词(Neo4j、pgvector、BM25)保留英文;章节标题可中英双语(HTML 锚点兼容);代码注释用中文。
+- 排版:段落间空行;`##` 起章节;重要概念首次出现加粗;代码块标语言;超 5 行段落考虑拆分。
+- 风格:精炼直接,主动语态,避免"可能/也许"式模糊;不确定性明确标注("当前不确定"、"待验证")。
+
+## 图表
+
+- **优先 Mermaid**(flowchart / sequenceDiagram / classDiagram / stateDiagram / erDiagram / gantt)——纯文本可维护、跨平台一致;仅 Mermaid 无法表达时(手绘风、特殊布局)用外部图片/SVG。
+- 图表放相关章节、紧跟解释文字;每张图前一句用途说明;过复杂的拆多张。
+- md 用 ```mermaid 代码块;html 引入 Mermaid CDN + `<pre class="mermaid">`(见模板)。
+
+## 输出格式
+
+- **HTML**:单文件自包含(内联 CSS,不依赖外部样式表)、响应式 + `@media print`、浅色高对比阅读主题、文档开头自动生成可点击目录;完整 CSS 与结构见模板。
+- **Markdown**:无 YAML frontmatter(区别于 knowledge 文件)、层级标题、围栏代码块标语言、开头标题列表作目录、引用块注明生成日期/主题范围/feature-id。
+
+## 保存位置与命名
+
+- 路径:`docs/features/<feature-id>/<文件前缀>-设计文档.md`(或 `.html`);用户参数可覆盖。
+- **feature-id 识别**:用户显式指定 > 从 cwd 向上探测最近的 `docs/features/<feature-id>/` > 都失败 → 报错要求用户指定。
+- **feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`;前缀:有业务ID = `<业务ID>-<标题>`,无 = `<标题>`;标题允许中文,**不得中文转英文 slug**;敏感字符(`/ \ : * ? " < > |`)拒绝,要求用户重命名,不自动替换。
+
+## 红线(绝对不能做)
+
+1. ❌ **不编造**无来源的细节/数据/结论——缺失标"待补充"或省略。
+2. ❌ **不重新定义 spec 已锁定的契约**;spec 与代码现实不符 → 标【待确认】。
+3. ❌ **不写 `docs/knowledge/`**——本 skill 只读。
+4. ❌ **正文不引用 knowledge/spec/plan 的内部路径**。
+5. ❌ **不照搬来源章节结构**——必须按知识传递目的重组。
+6. ❌ **不中文转英文 slug**——命名按规则。

package/dist/.claude-template/skills/write-design-doc/template-design-html.md

@@ -0,0 +1,357 @@
+# 设计文档 HTML 模板
+
+适用于 feature 发布后按需沉淀的设计文档,面向研发、技术负责人和后续维护者。由 `write-design-doc` skill 在发布后(或自测通过后)按需生成,默认输出到 `docs/features/<feature-id>/<文件前缀>-设计文档.md`(HTML 内容嵌入 markdown 文件,或直接 `.html`)。
+
+内容来源:`docs/knowledge/` 中与主题相关的 AI 知识文档 + 当前 feature 目录下的 spec/plan。
+
+## 完整 HTML 结构
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{文档标题} — {项目名称}</title>
+  <style>
+    :root {
+      --bg: #ffffff;
+      --surface: #f8f9fa;
+      --text: #1d1d1f;
+      --text-secondary: #6e6e73;
+      --accent: #0071e3;
+      --accent-light: #e8f0fe;
+      --border: #d2d2d7;
+      --code-bg: #f5f5f7;
+      --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+      --font-mono: "SF Mono", "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
+      --max-width: 800px;
+    }
+
+    *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      font-family: var(--font-sans);
+      font-size: 16px;
+      line-height: 1.7;
+      color: var(--text);
+      background: var(--bg);
+    }
+
+    .container {
+      max-width: var(--max-width);
+      margin: 0 auto;
+      padding: 2rem 1.5rem;
+    }
+
+    h1 {
+      font-size: 2rem;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      margin-bottom: 0.5em;
+      padding-bottom: 0.5em;
+      border-bottom: 2px solid var(--border);
+    }
+
+    .meta {
+      color: var(--text-secondary);
+      font-size: 0.875rem;
+      margin-bottom: 2em;
+    }
+
+    h2 {
+      font-size: 1.5rem;
+      font-weight: 600;
+      margin-top: 2.5em;
+      margin-bottom: 0.75em;
+      padding-bottom: 0.3em;
+      border-bottom: 1px solid var(--border);
+    }
+
+    h3 {
+      font-size: 1.2rem;
+      font-weight: 600;
+      margin-top: 1.5em;
+      margin-bottom: 0.5em;
+    }
+
+    p { margin-bottom: 1em; }
+
+    ul, ol {
+      margin-bottom: 1em;
+      padding-left: 1.5em;
+    }
+
+    li { margin-bottom: 0.3em; }
+
+    strong { font-weight: 600; }
+
+    code {
+      font-family: var(--font-mono);
+      background: var(--code-bg);
+      padding: 0.15em 0.4em;
+      border-radius: 4px;
+      font-size: 0.9em;
+    }
+
+    pre {
+      background: var(--code-bg);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1em;
+      margin-bottom: 1em;
+      overflow-x: auto;
+    }
+
+    pre code {
+      background: none;
+      padding: 0;
+      font-size: 0.875em;
+    }
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin-bottom: 1em;
+      font-size: 0.95em;
+    }
+
+    th, td {
+      padding: 0.6em 1em;
+      text-align: left;
+      border-bottom: 1px solid var(--border);
+    }
+
+    thead th {
+      font-weight: 600;
+      color: var(--accent);
+      background: var(--surface);
+    }
+
+    tbody tr:nth-child(even) { background: var(--surface); }
+
+    .toc {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1em 1.5em;
+      margin-bottom: 2em;
+    }
+
+    .toc h3 {
+      margin-top: 0;
+      margin-bottom: 0.5em;
+      font-size: 1rem;
+    }
+
+    .toc ul { list-style: none; padding-left: 0; }
+    .toc li { margin-bottom: 0.25em; }
+    .toc a { color: var(--accent); text-decoration: none; }
+    .toc a:hover { text-decoration: underline; }
+    .toc ul ul { padding-left: 1.5em; margin-top: 0.25em; }
+
+    .callout {
+      background: var(--accent-light);
+      border-left: 4px solid var(--accent);
+      padding: 0.75em 1em;
+      border-radius: 0 8px 8px 0;
+      margin-bottom: 1em;
+    }
+
+    .diagram {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1.5em;
+      margin-bottom: 1em;
+      font-family: var(--font-mono);
+      font-size: 0.875em;
+      white-space: pre;
+      overflow-x: auto;
+      line-height: 1.5;
+    }
+
+    .tag {
+      display: inline-block;
+      font-size: 0.8em;
+      background: var(--accent-light);
+      color: var(--accent);
+      border: 1px solid rgba(0, 113, 227, 0.2);
+      padding: 0.15em 0.6em;
+      border-radius: 12px;
+    }
+
+    .api-method {
+      font-family: var(--font-mono);
+      font-weight: 600;
+    }
+
+    .decision-block {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1em 1.5em;
+      margin-bottom: 1em;
+    }
+
+    .decision-block h4 {
+      margin-top: 0;
+      margin-bottom: 0.5em;
+      color: var(--accent);
+    }
+
+    .decision-block dl {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      gap: 0.3em 1em;
+      font-size: 0.95em;
+    }
+
+    .decision-block dt {
+      font-weight: 600;
+      color: var(--text-secondary);
+    }
+
+    .decision-block dd {
+      margin: 0;
+    }
+
+    .limit-table td:first-child {
+      white-space: nowrap;
+      font-weight: 600;
+      color: var(--text-secondary);
+    }
+
+    @media print {
+      body { font-size: 12pt; }
+      .container { max-width: 100%; padding: 0; }
+      .toc { break-after: page; }
+      h2 { break-after: avoid; }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>{文档标题}</h1>
+    <p class="meta">生成日期：YYYY-MM-DD | 主题范围：{范围描述} | feature-id: {feature-id}</p>
+
+    <nav class="toc">
+      <h3>目录</h3>
+      <ul>
+        <li><a href="#概述">概述</a></li>
+        <li><a href="#架构设计">架构设计</a></li>
+        <li><a href="#核心模块">核心模块</a>
+          <ul>
+            <li><a href="#模块A">模块 A</a></li>
+            <li><a href="#模块B">模块 B</a></li>
+          </ul>
+        </li>
+        <li><a href="#技术决策">技术决策</a></li>
+        <li><a href="#已知限制">已知限制</a></li>
+        <li><a href="#扩展方向">扩展方向</a></li>
+      </ul>
+    </nav>
+
+    <article>
+      <section id="概述">
+        <h2>概述</h2>
+        <p>系统概述和技术定位。来源:spec 目标与范围 + knowledge Summary。</p>
+      </section>
+
+      <section id="架构设计">
+        <h2>架构设计</h2>
+        <p>系统架构和数据流描述。来源:spec 系统行为/接口边界 + knowledge Summary + Read 原文。</p>
+        <pre class="diagram">组件 A ──→ 组件 B ──→ 组件 C
+              │
+              ↕
+           外部服务</pre>
+      </section>
+
+      <section id="核心模块">
+        <h2>核心模块</h2>
+
+        <section id="模块A">
+          <h3>模块 A</h3>
+          <p>职责描述和关键接口。来源:plan 任务拆分 + knowledge Summary。</p>
+        </section>
+
+        <section id="模块B">
+          <h3>模块 B</h3>
+          <p>职责描述和关键接口。</p>
+        </section>
+      </section>
+
+      <section id="技术决策">
+        <h2>技术决策</h2>
+        <div class="decision-block">
+          <h4>决策标题</h4>
+          <dl>
+            <dt>选择</dt>
+            <dd>xxx</dd>
+            <dt>原因</dt>
+            <dd>xxx</dd>
+            <dt>替代方案</dt>
+            <dd>xxx</dd>
+          </dl>
+        </div>
+        <p>来源:spec 不可留实现期决策 + knowledge Decisions。</p>
+      </section>
+
+      <section id="已知限制">
+        <h2>已知限制</h2>
+        <table class="limit-table">
+          <thead>
+            <tr><th>限制</th><th>影响范围</th><th>应对措施</th></tr>
+          </thead>
+          <tbody>
+            <tr><td>限制描述</td><td>影响范围</td><td>应对措施</td></tr>
+          </tbody>
+        </table>
+        <p>来源:spec 待确认项 + knowledge Findings/Risks。</p>
+      </section>
+
+      <section id="扩展方向">
+        <h2>扩展方向</h2>
+        <ol>
+          <li><strong>方向 A</strong> — 描述和优先级</li>
+          <li><strong>方向 B</strong> — 描述和优先级</li>
+        </ol>
+        <p>来源:knowledge Outlook。</p>
+      </section>
+    </article>
+  </div>
+</body>
+</html>
+```
+
+## 设计文档 HTML 章节内容指南
+
+| 章节 | 主来源 | 辅来源 | 改写方向 |
+|------|------------------------|----------|----------|
+| 概述 | spec 目标与范围 | knowledge Summary | 保留技术精确度,增加架构上下文 |
+| 架构设计 | spec 系统行为/接口边界 | knowledge Summary + Read 原文 | 补充系统级架构图(文本框图)、数据流描述 |
+| 核心模块 | plan 任务拆分 | knowledge Summary | 按模块分组,说明职责和交互关系 |
+| 数据模型 | plan schema 任务 | spec 数据口径 + Read 原文 | 用表格展示节点类型、属性、关系 |
+| 技术决策 | spec 不可留实现期决策 | knowledge Decisions + Read 原文 | 保留决策理由,补充替代方案对比 |
+| API 参考 | spec 接口边界 | plan backend 任务 + Read 原文 | 按 endpoint 分组,包含请求/响应示例 |
+| 性能特征 | knowledge Findings | Read 原文 | 用表格展示瓶颈和优化方向 |
+| 已知限制 | spec 待确认项 | knowledge Findings/Risks + Read 原文 | 按严重程度排序,说明影响范围 |
+| 扩展方向 | knowledge Outlook | Read 原文 | 按优先级排序,说明实现复杂度 |
+| 运维指南 | knowledge Operations | Read 原文 | 按"部署 / 监控 / 排障"分组 |
+
+## HTML 格式要点
+
+- 所有 CSS 内联在 `<style>` 标签中,不引用外部样式表
+- `<title>` 包含文档标题和项目名称
+- 使用 `<nav class="toc">` 作为目录容器
+- 每个章节使用 `<section id="章节锚点">` 包裹
+- 章节锚点使用中文 ID(如 `id="架构设计"`)
+- 重要提示或注意事项使用 `<div class="callout">` 样式
+- 代码示例使用 `<pre><code>` 标签
+- 表格使用 `<thead>` + `<tbody>` 结构
+- 架构图使用 `<pre class="diagram">` 包裹 ASCII 文本框图
+- 技术决策使用 `<div class="decision-block">` 结构,包含 `<dl>` 列表
+- 已知限制使用表格,按严重程度降序排列
+- 模块描述使用 `<section id="模块名">` + `<h3>` 子标题
+- API 端点使用 `<span class="api-method">GET</span>` 标注 HTTP 方法
+- 技术标签使用 `<span class="tag">标签名</span>` 样式

package/dist/.claude-template/skills/write-design-doc/template-design-md.md

@@ -0,0 +1,164 @@
+# 设计文档 Markdown 模板
+
+适用于 feature 发布后按需沉淀的设计文档,面向研发、技术负责人和后续维护者。由 `write-design-doc` skill 在发布后(或自测通过后)按需生成,默认输出到 `docs/features/<feature-id>/<文件前缀>-设计文档.md`。
+
+内容来源:`docs/knowledge/` 中与主题相关的 AI 知识文档 + 当前 feature 目录下的 spec/plan。
+
+## 文档结构
+
+```markdown
+# {文档标题}
+
+> 生成日期：YYYY-MM-DD | 主题范围：{范围描述} | feature-id: {feature-id}
+
+## 目录
+
+- [概述](#概述)
+- [架构设计](#架构设计)
+- [核心模块](#核心模块)
+  - [模块 A](#模块-a)
+  - [模块 B](#模块-b)
+- [技术决策](#技术决策)
+- [已知限制](#已知限制)
+- [扩展方向](#扩展方向)
+
+## 概述
+
+系统概述和技术定位。来源:spec 的目标与范围 + knowledge Summary。
+
+## 架构设计
+
+系统架构和数据流描述。来源:spec 的系统行为/接口边界 + knowledge Summary + Read 文件原文。
+
+```
+组件 A ──→ 组件 B ──→ 组件 C
+      │
+      ↕
+   外部服务
+```
+
+## 核心模块
+
+### 模块 A
+
+职责描述、关键接口和依赖关系。来源:plan 的任务拆分 + knowledge Summary。
+
+### 模块 B
+
+职责描述、关键接口和依赖关系。
+
+## 技术决策
+
+### 决策标题
+
+- **选择**：xxx
+- **原因**：xxx
+- **替代方案**：xxx
+
+来源:spec 的"不可留到实现期的决策" + knowledge 中的 Decisions 章节。
+
+## 已知限制
+
+| 限制 | 影响范围 | 应对措施 |
+|------|----------|----------|
+| 限制描述 | 影响范围 | 应对措施 |
+
+来源:spec 的"待确认项" + knowledge 中的 Findings / Risks 章节。
+
+## 扩展方向
+
+1. **方向 A** — 描述和优先级
+2. **方向 B** — 描述和优先级
+```
+
+## 可选章节（按需插入）
+
+```markdown
+## 数据模型
+
+| 类型 | 属性 | 关系 |
+|------|------|------|
+| 节点类型 A | 属性列表 | 关系列表 |
+
+来源:spec 的"数据、状态与口径" + plan 的 schema 任务 + knowledge 的 Data Model 章节。
+
+## API 参考
+
+### 端点名称
+
+`POST /api/path`
+
+**请求参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| param | string | 说明 |
+
+**响应示例**：
+
+```json
+{
+  "key": "value"
+}
+```
+
+## 性能特征
+
+| 瓶颈 | 影响 | 优化方向 |
+|------|------|----------|
+| 描述 | 影响范围 | 优化方案 |
+
+## 运维指南
+
+### 部署
+
+部署步骤和注意事项。
+
+### 监控
+
+关键指标和告警规则。
+
+### 故障排除
+
+按"症状 → 原因 → 修复"格式记录。
+
+## 术语表
+
+| 术语 | 定义 |
+|------|------|
+| 术语 A | 技术定义 |
+| 术语 B | 技术定义 |
+
+## 相关资源
+
+- spec: `docs/features/<feature-id>/<文件前缀>-spec.md`
+- plan: `docs/features/<feature-id>/plan/<文件前缀>-index.md`
+- 相关代码: 相对路径
+- 外部文档: URL
+```
+
+## 设计文档 Markdown 章节内容指南
+
+| 章节 | 主来源 | 辅来源 | 改写方向 |
+|------|------------------------|----------|----------|
+| 概述 | spec 目标与范围 | knowledge Summary | 保留技术精确度,补充架构上下文 |
+| 架构设计 | spec 系统行为/接口边界 | knowledge Summary + Read 原文 | 补充系统级架构图(ASCII 文本框图)、数据流描述 |
+| 核心模块 | plan 任务拆分 | knowledge Summary | 按模块分组,说明职责和交互关系 |
+| 数据模型 | plan schema 任务 | spec 数据口径 + Read 原文 | 用表格展示节点类型、属性、关系 |
+| 技术决策 | spec 不可留实现期决策 | knowledge Decisions + Read 原文 | 保留决策理由,补充替代方案对比,按"选择/原因/替代方案"格式 |
+| API 参考 | spec 接口边界 | plan backend 任务 + Read 原文 | 按 endpoint 分组,包含请求参数表格和响应示例 |
+| 性能特征 | knowledge Findings | Read 原文 | 用表格展示瓶颈和优化方向 |
+| 已知限制 | spec 待确认项 | knowledge Findings/Risks + Read 原文 | 按严重程度排序,用表格说明影响范围和应对措施 |
+| 扩展方向 | knowledge Outlook | Read 原文 | 按优先级排序,用编号列表说明实现复杂度 |
+| 运维指南 | knowledge Operations | Read 原文 | 按"部署 / 监控 / 故障排除"分子章节 |
+
+## 格式规则
+
+- 架构图使用代码块中的 ASCII 文本框图,不标注语言类型
+- 技术决策按"选择 / 原因 / 替代方案"列表格式
+- 代码示例标注语言类型(`rust`、`bash`、`json` 等)
+- 文件路径使用行内代码包裹:`src/main.rs`
+- HTTP 方法使用行内代码包裹:`POST /api/search/hybrid`
+- 模块描述使用 `###` 子标题
+- 表格优先用于结构化信息(限制、API 参数、性能瓶颈)
+- 不要在文档中引用 AI 知识文档的路径或文件名;如需引用代码用相对路径