cgraphx 1.1.0

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

@@ -0,0 +1,366 @@
+---
+name: code-impact-docgen
+description: 从本地图谱知识库召回 AI 导向的知识文档，合成面向人类阅读的业务/技术文档。支持 HTML 和 Markdown 两种输出格式，可按文档类型（business/technical）和章节结构进行配置。
+---
+
+# Code Impact DocGen
+
+从本地图谱知识库中召回 AI 导向的知识文档，智能合成面向人类阅读的正式文档。
+
+本 skill 将 `docs/knowledge/` 中为 AI 消费而设计的结构化知识文件（YAML frontmatter + 稳定英文标题）转化为面向业务或技术读者的连贯、精炼、可读性强的文档。输出的文档不包含 YAML frontmatter，不使用 AI 导向的稳定标题，而是按照用户选择的文档类型和章节结构组织内容。
+
+## Trigger
+
+使用此 skill 当：
+
+- 用户要求基于项目知识生成文档、报告或说明
+- 用户说"写一份文档"、"生成报告"、"整理成文档"、"写个说明"等
+- 用户要求对某个概念、领域、系统或模块生成人类可读的概述
+- 用户要求把知识库中的内容整理为可供分享或归档的文档
+- 用户要求生成 HTML 或 Markdown 格式的正式文档
+
+不要使用此 skill 当：
+
+- 创建或编辑 AI 导向的知识文件（使用 `code-impact-markdown` skill）
+- 查询知识以辅助代码编辑（使用 `code-impact-api` skill）
+- 探索陌生项目（使用 `code-impact-init` skill）
+
+## 依赖
+
+- cgraphx 已安装(`cgraphx --version` 可跑)
+- 项目已跑过 `cgraphx docs index`,索引中有知识文档数据(用 `cgraphx docs concepts` 验证)
+- 若索引为空:先按 `code-impact-markdown` skill 写文档到 `docs/knowledge/`,再 `cgraphx docs index`
+
+## 知识召回流程
+
+生成文档前，必须通过以下流程收集源材料。不要凭空编写内容——所有内容必须基于图谱中已有的知识文档。
+
+### 第一步：确认需求
+
+向用户确认（如果未明确指定）：
+
+1. **主题范围** — 一个 concept 名称、一个 domain、一个系统/模块名称，或一个自由描述
+2. **文档类型** — `business`（面向业务读者）或 `technical`（面向技术人员）
+3. **输出格式** — `html` 或 `md`
+4. **可选：目标章节** — 用户可以选择包含或排除哪些章节（见章节菜单）
+
+如果用户未指定文档类型，根据主题范围自动判断：
+
+- 主题涉及业务流程、产品功能、项目规划 → 默认 `business`
+- 主题涉及代码架构、模块设计、技术实现 → 默认 `technical`
+- 不确定时向用户确认
+
+### 第二步：召回知识文档
+
+根据主题范围选择召回方式（用 `cgraphx docs` CLI）：
+
+**按概念精确过滤（推荐，召回最精准）：**
+
+```bash
+cgraphx docs find --concept=<concept-name> --limit=20
+```
+
+**按 domain 过滤（覆盖整个业务领域）：**
+
+```bash
+cgraphx docs find --domain=<domain-name> --limit=20
+```
+
+**按关键词子串匹配（适合模糊探索；LIKE on title + Summary）：**
+
+```bash
+cgraphx docs find --q=<关键词> --limit=20
+```
+
+**按 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（找主题入口）：**
+
+```bash
+cgraphx docs concepts     # 跨文档去重的 concept + 各自关联文档数 + 所属 domain
+cgraphx docs domains
+cgraphx docs tags
+```
+
+`find` 输出每条结果包含 `title` / `document_type` / `status` / `updated` / `summary`(Summary 章节文本) / `path`(项目根相对,供 Read)。
+
+### 第三步：读取文档详情
+
+`find` 返回的 `summary` 是 `## Summary` 章节内容,通常是文档的核心结论。**如果 Summary 不够,**用 `path` 字段直接 Read 原文件:
+
+```bash
+cgraphx docs show <doc-id-or-path>     # 输出 frontmatter 元数据 + Summary
+# 或直接:
+Read <path>                              # 拿到完整原文(含 Context / Decisions / Steps 等其他章节)
+```
+
+**重要**:**只有 `## Summary` 进 cgraphx 索引**,其他章节(Context / Decisions / Findings / Steps / ...)留在文件里。生成文档时,这些章节的内容来源是 **Read 文件原文**,不是图谱字段。
+
+### 第四步：探索关联知识（可选，按需）
+
+如果需要更全面的背景（文档间引用关系）:
+
+```bash
+cgraphx docs refs <doc-id-or-path>
+# 输出双向引用:
+#   Outgoing: 这份文档引用了哪些
+#   Incoming: 哪些文档引用了这份
+```
+
+适合"这个决策被哪些文档引用了"、"还有哪些相关文档"的扩展召回。
+
+### 第五步：合成文档
+
+基于召回的全部源材料，按照用户选择的文档类型和章节结构生成文档。见后续章节。
+
+## 文档类型
+
+用户选择 `business` 或 `technical`，决定文档的读者定位、语气和结构。
+
+### business（面向业务读者）
+
+- **读者**：项目经理、产品经理、业务决策者、新成员
+- **语气**：非技术性，侧重价值、流程、决策理由
+- **结构重点**：背景与目标、业务流程、关键决策、影响与价值
+- **技术细节处理**：将技术概念转化为业务可理解的描述，必要时放在附录中
+- **默认章节**：背景与目标、核心能力、业务流程、关键决策、现状与展望
+
+### technical（面向技术读者）
+
+- **读者**：开发工程师、架构师、技术负责人
+- **语气**：精确、专业，包含技术细节
+- **结构重点**：架构设计、数据流、技术决策、已知问题、扩展方向
+- **默认章节**：概述、架构设计、核心模块、技术决策、已知限制、扩展方向
+
+## 章节菜单
+
+用户可以选择包含哪些章节。以下为完整章节库，按文档类型标记适用范围。
+
+### 通用章节（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 | 部署、监控、故障排除 |
+
+### 章节选择规则
+
+- 用户可以明确指定要包含的章节
+- 用户可以从默认章节中排除不需要的章节
+- 如果用户未指定，使用对应文档类型的默认章节
+- 按照上述表格顺序排列章节
+
+## 输出格式
+
+### HTML 格式
+
+生成单文件独立 HTML 文档，特点：
+
+- **内联 CSS**：不依赖外部样式表，所有样式写在 `<style>` 标签内
+- **响应式布局**：使用 CSS 变量控制主题，支持不同屏幕宽度
+- **打印友好**：包含 `@media print` 样式
+- **浅色阅读主题**：白色背景，高对比度，适合长时间阅读
+- **字体**：`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`
+- **代码块**：等宽字体，浅灰背景，圆角边框
+- **表格**：斑马纹行，边框分隔
+- **目录**：文档开头自动生成可点击目录（锚点链接）
+
+生成前阅读对应模板文件获取完整 CSS 和结构参考：
+
+| 文档类型 | 模板文件 |
+|----------|----------|
+| business | [template-business-html.md](template-business-html.md) |
+| technical | [template-technical-html.md](template-technical-html.md) |
+
+### Markdown 格式
+
+生成干净的 Markdown 文档，特点：
+
+- **无 YAML frontmatter**：与 `docs/knowledge/` 中的 AI 导向文档不同
+- **层级标题**：`#`（文档标题）、`##`（章节）、`###`（子章节）
+- **代码块**：三个反引号围栏代码块，标注语言
+- **表格**：标准 Markdown 表格
+- **链接**：`[文本](url)` 格式，优先使用相对路径
+- **目录**：文档开头用标题列表作为目录
+- **元信息**：文档开头用引用块注明生成日期和主题范围
+
+生成前阅读对应模板文件：
+
+| 文档类型 | 模板文件 |
+|----------|----------|
+| business | [template-business-md.md](template-business-md.md) |
+| technical | [template-technical-md.md](template-technical-md.md) |
+
+## 图表绘制
+
+当文档中需要使用图表（流程图、时序图、架构图、状态图等）来辅助说明时，遵循以下规则：
+
+- **优先使用 Mermaid**：在保证表达效果的前提下，优先使用 Mermaid 语法绘制图表，以确保文档的纯文本可维护性和跨平台渲染一致性
+- 适用的图表类型包括但不限于：`flowchart`（流程图）、`sequenceDiagram`（时序图）、`classDiagram`（类图）、`stateDiagram`（状态图）、`erDiagram`（ER 图）、`gantt`（甘特图）
+- 图表应放在相关的章节中，紧跟在解释性文字之后
+- 每张图表前应有简短的文字说明其用途
+- 图表内容应精简，避免过于复杂；如果信息量过大，拆分为多张图表
+- 仅当 Mermaid 无法表达所需的视觉效果时（如复杂的手绘风格、特殊布局），才使用外部图片或 SVG
+
+Markdown 格式中使用 Mermaid 代码块：
+
+````markdown
+```mermaid
+flowchart TD
+    A[开始] --> B{判断}
+    B -->|是| C[执行]
+    B -->|否| D[结束]
+```
+````
+
+HTML 格式中使用 Mermaid 代码块（依赖 Mermaid.js CDN 渲染），模板中需引入 Mermaid 脚本：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+<script>mermaid.initialize({startOnLoad:true});</script>
+<pre class="mermaid">
+flowchart TD
+    A --> B
+</pre>
+```
+
+## 合成规则
+
+生成文档时遵循以下规则，确保从多个 AI 知识文档合成出连贯的人类文档。
+
+### 内容来源
+
+- 所有事实性内容必须来自图谱中召回的知识文档
+- 不要编造不存在的细节、数据或结论
+- 如果某个方面的知识缺失，在文档中如实标注"待补充"或省略该部分
+- 可以基于多个文档的内容进行归纳和总结，但归纳必须忠实于原文
+
+### 结构重组
+
+- AI 知识文档使用稳定英文标题（Summary、Findings、Decisions 等）按分析目的组织
+- 人类文档按阅读目的组织（背景、流程、决策等）
+- **必须重新组织内容结构**，不要照搬 AI 文档的标题和章节
+- 相关信息应合并到同一章节，避免内容分散
+- 去除重复信息：多个 AI 文档可能包含相同的背景信息，只需出现一次
+
+### 语气转换
+
+- AI 知识文档的语气是"分析记录"（记录观察、证据、影响）
+- 人类文档的语气是"知识传递"（解释、说明、指导）
+- 将被动描述转为主动解释
+- 将技术分析转为可操作的指导（technical 类型）或可理解的概述（business 类型）
+
+### 引用和溯源
+
+- 不要在人类文档中引用 AI 文档的路径或文件名
+- 如需引用代码文件，使用相对路径
+- 如需引用外部文档，使用 URL 或文档标题
+
+## 语言和风格规则
+
+### 语言
+
+- 文档正文用**中文**编写
+- 技术术语、代码标识符、文件路径、函数名、类名保留原始英文
+- 章节标题可使用中英双语格式："架构设计 / Architecture"（英文部分用于 HTML 锚点兼容性）
+- 代码示例中的注释使用中文
+- 专有名词（如 Neo4j、pgvector、BM25、RRF）保留英文原名
+
+### 排版
+
+- 段落之间空一行
+- 每个章节以 `##` 标题开始
+- 重要概念第一次出现时加粗
+- 代码块标注语言类型
+- 表格使用标准格式
+- 列表项以动词或名词开头，保持一致
+- 避免过长的段落（超过 5 行应考虑拆分）
+
+### 风格
+
+- 精炼、直接、避免冗余
+- 每句话传递信息，不写废话
+- 使用主动语态
+- 避免模糊措辞（如"可能"、"也许"），除非表达不确定性
+- 不确定性用明确标注："当前不确定"、"待验证"
+
+## 保存位置
+
+生成的人类文档**必须**保存到 `docs/published/` 目录中，**不要**直接保存到 `docs/` 根目录，也**不要**保存到 `docs/knowledge/`（该目录专用于 AI 导向的知识文件）。
+
+`docs/published/` 目录不存在时创建。
+
+### 文件命名
+
+```text
+# 格式：主题关键词.格式
+hybrid-search-architecture.md
+knowledge-pipeline-overview.html
+project-status-report.md
+```
+
+- 使用英文短横线分隔
+- 文件名使用英文（便于 URL 兼容和跨平台）
+- 文件名应反映文档内容而非日期
+
+### 生成后
+
+保存文件后：
+
+1. 告知用户文件保存位置
+2. 简要说明文档覆盖的内容范围
+3. 如有知识缺失（图谱中未覆盖的重要方面），列出"可能需要补充的知识"
+4. 不触发分析（本 skill 只读取知识，不写入 `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. **质量检查** — 检查文档是否满足以下条件：
+   - 所有事实性内容有知识来源
+   - 章节结构完整、逻辑连贯
+   - 语言风格符合文档类型定位
+   - 格式正确、排版整洁
+8. **保存文件** — 写入 `docs/published/` 目录
+9. **反馈** — 告知用户保存位置和内容范围，列出知识缺失（如有）

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

@@ -0,0 +1,242 @@
+# Business 文档 HTML 模板
+
+适用于面向业务读者的 HTML 格式文档。
+
+生成前阅读此文件获取完整的 CSS 样式和章节结构参考。
+
+## 完整 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;
+    }
+
+    @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 | 主题范围：{范围描述}</p>
+
+    <nav class="toc">
+      <h3>目录</h3>
+      <ul>
+        <li><a href="#背景与目标">背景与目标</a></li>
+        <li><a href="#核心能力">核心能力</a></li>
+        <li><a href="#业务流程">业务流程</a></li>
+        <li><a href="#关键决策">关键决策</a></li>
+        <li><a href="#现状与展望">现状与展望</a></li>
+      </ul>
+    </nav>
+
+    <article>
+      <section id="背景与目标">
+        <h2>背景与目标</h2>
+        <p>说明项目或系统的定位、目标和解决的问题。</p>
+      </section>
+
+      <section id="核心能力">
+        <h2>核心能力</h2>
+        <p>描述系统提供的主要能力和价值。</p>
+      </section>
+
+      <section id="业务流程">
+        <h2>业务流程</h2>
+        <p>说明核心业务流程和操作步骤。</p>
+      </section>
+
+      <section id="关键决策">
+        <h2>关键决策</h2>
+        <p>列出重要的技术和业务决策及其理由。</p>
+      </section>
+
+      <section id="现状与展望">
+        <h2>现状与展望</h2>
+        <p>说明当前状态和未来方向。</p>
+      </section>
+    </article>
+  </div>
+</body>
+</html>
+```
+
+## Business HTML 章节内容指南
+
+每个章节应按照以下指引从 AI 知识文档中提取、转换和改写内容。
+
+| 章节 | 内容来源 | 改写方向 |
+|------|------------------------|----------|
+| 背景与目标 | Summary 文本 | 从"为什么分析"转为"项目/系统的目标和定位" |
+| 核心能力 | Summary 文本 | 从"发现"转为"能力描述"，面向非技术读者 |
+| 业务流程 | Read 文件原文（该章节 cgraphx 不提取） | 从"操作步骤"转为"业务流程说明"，去除技术细节 |
+| 关键决策 | Read 文件原文（该章节 cgraphx 不提取） | 从"决策记录"转为"决策解释"，说明决策的业务原因 |
+| 价值与影响 | Read 文件原文（该章节 cgraphx 不提取） | 从"对未来变更的影响"转为"对业务的价值和影响" |
+| 现状与展望 | Read 文件原文（该章节 cgraphx 不提取） | 从"发现和后续"转为"当前状态和未来规划" |
+| 风险与注意事项 | Read 文件原文（该章节 cgraphx 不提取） | 从"故障排除"转为"风险提示和应对措施" |
+| 常见问题 | Read 文件原文（该章节 cgraphx 不提取） | 从"分析记录"转为"Q&A 格式" |
+| 术语表 | 各文本字段中的术语 | 提取关键术语，给出简洁的业务定义 |
+| 相关资源 | — | 列出相关的代码文件（相对路径）或外部文档 |
+
+## HTML 格式要点
+
+- 所有 CSS 内联在 `<style>` 标签中，不引用外部样式表
+- `<title>` 包含文档标题和项目名称
+- 使用 `<nav class="toc">` 作为目录容器
+- 每个章节使用 `<section id="章节锚点">` 包裹
+- 章节锚点使用中文 ID（如 `id="背景与目标"`）
+- 重要提示或注意事项使用 `<div class="callout">` 样式
+- 代码示例使用 `<pre><code>` 标签
+- 表格使用 `<thead>` + `<tbody>` 结构