init: 导入团队知识库内容

2026-05-14 16:56:48 +08:00
commit acca2041f0
1681 changed files with 285734 additions and 0 deletions
@@ -0,0 +1,696 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>graphify-rs 使用手册</title>
+<style>
+:root {
+  --color-primary: #1677FF;
+  --color-primary-hover: #4096FF;
+  --color-primary-active: #0958D9;
+  --color-primary-bg: rgba(22, 119, 255, 0.1);
+  --color-success: #52C41A;
+  --color-warning: #FAAD14;
+  --color-error: #FF4D4F;
+
+  --bg: #0B0F1A;
+  --bg-secondary: #111827;
+  --bg-tertiary: #1A2235;
+  --border: #1E2A3A;
+  --border-light: #151D2E;
+  --text-primary: #E8ECF1;
+  --text-secondary: #8892A4;
+  --text-tertiary: #5A6478;
+
+  --radius-sm: 6px;
+  --radius-md: 8px;
+
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.15);
+  --shadow-md: 0 2px 4px rgba(0,0,0,0.2), 0 4px 12px -2px rgba(0,0,0,0.2);
+
+  --sidebar-w: 260px;
+  --header-h: 64px;
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+  font-family: 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, sans-serif;
+  background: var(--bg);
+  color: var(--text-primary);
+  font-size: 14px;
+  line-height: 1.57;
+}
+
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: var(--text-secondary); }
+
+/* Header */
+.header {
+  position: fixed; top: 0; left: 0; right: 0;
+  height: var(--header-h);
+  background: rgba(11, 15, 26, 0.85);
+  backdrop-filter: blur(12px);
+  border-bottom: 1px solid var(--border);
+  display: flex; align-items: center;
+  padding: 0 1.5rem;
+  z-index: 100;
+}
+.header h1 {
+  font-size: 1.05rem; font-weight: 700;
+  background: linear-gradient(135deg, var(--color-primary), #722ED1);
+  -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.header .version {
+  margin-left: auto;
+  font-size: 0.8rem; color: var(--text-secondary);
+  font-family: 'SF Mono', Monaco, monospace;
+}
+
+/* Sidebar */
+.sidebar {
+  position: fixed; top: var(--header-h); left: 0; bottom: 0;
+  width: var(--sidebar-w);
+  background: var(--bg-secondary);
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+  padding: 1rem 0;
+  z-index: 90;
+}
+.sidebar .section-label {
+  font-size: 0.7rem; font-weight: 600;
+  color: var(--text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: 0.75rem 1.25rem 0.4rem;
+}
+.sidebar a {
+  display: block;
+  padding: 0.45rem 1.25rem;
+  color: var(--text-secondary);
+  text-decoration: none;
+  font-size: 0.88rem;
+  border-left: 3px solid transparent;
+  transition: all 0.15s ease;
+}
+.sidebar a:hover {
+  color: var(--text-primary);
+  background: var(--bg-tertiary);
+}
+.sidebar a.active {
+  color: var(--color-primary);
+  background: var(--color-primary-bg);
+  border-left-color: var(--color-primary);
+  font-weight: 600;
+}
+
+/* Main Content */
+.main {
+  margin-left: var(--sidebar-w);
+  margin-top: var(--header-h);
+  padding: 2rem 2.5rem 4rem;
+  max-width: 900px;
+}
+
+/* Section */
+.section { margin-bottom: 3rem; scroll-margin-top: calc(var(--header-h) + 1rem); }
+.section-title {
+  font-size: 1.4rem; font-weight: 700;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--border);
+}
+.section-title .emoji { margin-right: 0.5rem; }
+.subsection { margin: 1.5rem 0; }
+.subsection-title {
+  font-size: 1.1rem; font-weight: 600;
+  color: var(--text-primary);
+  margin-bottom: 0.75rem;
+}
+
+/* Text */
+p { margin-bottom: 0.75rem; color: var(--text-secondary); }
+p strong { color: var(--text-primary); }
+ul, ol { margin: 0.5rem 0 1rem 1.5rem; color: var(--text-secondary); }
+li { margin-bottom: 0.35rem; }
+
+/* Code */
+code {
+  background: var(--bg-tertiary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 0.15em 0.45em;
+  font-family: 'SF Mono', 'Menlo', 'Courier New', monospace;
+  font-size: 0.88em;
+  color: #E06C75;
+}
+pre {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 1rem 1.25rem;
+  overflow-x: auto;
+  margin: 0.75rem 0 1rem;
+  position: relative;
+}
+pre code {
+  background: none; border: none; padding: 0;
+  color: var(--text-primary);
+  font-size: 0.85rem;
+  line-height: 1.65;
+}
+
+/* Tables */
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1rem 0;
+  font-size: 0.88rem;
+}
+th, td {
+  text-align: left;
+  padding: 0.6rem 1rem;
+  border-bottom: 1px solid var(--border);
+}
+th {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+  font-weight: 600;
+  font-size: 0.82rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+td { color: var(--text-secondary); }
+tr:hover td { background: var(--bg-tertiary); }
+
+/* Cards */
+.card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 1rem; margin: 1rem 0; }
+.card {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 1.25rem;
+  transition: all 0.2s ease;
+}
+.card:hover { border-color: var(--color-primary); box-shadow: var(--shadow-md); }
+.card h4 { font-size: 0.95rem; margin-bottom: 0.5rem; color: var(--text-primary); }
+.card p { font-size: 0.85rem; margin: 0; }
+
+/* Badge */
+.badge {
+  display: inline-block;
+  padding: 2px 10px;
+  border-radius: 12px;
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+.badge-blue { background: rgba(22, 119, 255, 0.15); color: #4096FF; border: 1px solid rgba(64, 150, 255, 0.3); }
+.badge-green { background: rgba(82, 196, 26, 0.15); color: #73D13D; border: 1px solid rgba(115, 209, 61, 0.3); }
+.badge-purple { background: rgba(114, 46, 209, 0.15); color: #B37FEB; border: 1px solid rgba(179, 127, 235, 0.3); }
+.badge-orange { background: rgba(250, 173, 20, 0.15); color: #FFC53D; border: 1px solid rgba(255, 197, 61, 0.3); }
+
+/* Tip / Warning */
+.callout {
+  border-radius: var(--radius-md);
+  padding: 1rem 1.25rem;
+  margin: 1rem 0;
+  border-left: 4px solid;
+}
+.callout-tip { background: rgba(22, 119, 255, 0.08); border-color: var(--color-primary); }
+.callout-tip p { color: #B0D0FF; }
+.callout-warning { background: rgba(250, 173, 20, 0.08); border-color: var(--color-warning); }
+.callout-warning p { color: #FFE08C; }
+.callout-tip code, .callout-warning code { font-size: 0.85em; }
+
+/* Flow diagram */
+.flow {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 1.25rem;
+  margin: 1rem 0;
+  font-family: 'SF Mono', 'Menlo', monospace;
+  font-size: 0.85rem;
+  line-height: 2;
+  color: var(--text-secondary);
+  white-space: pre;
+  overflow-x: auto;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .sidebar { display: none; }
+  .main { margin-left: 0; padding: 1.5rem 1rem 3rem; }
+  .card-grid { grid-template-columns: 1fr; }
+  table { font-size: 0.8rem; }
+  th, td { padding: 0.5rem 0.6rem; }
+}
+</style>
+</head>
+<body>
+
+<header class="header">
+  <h1>graphify-rs 使用手册</h1>
+  <span class="version">v1.x</span>
+</header>
+
+<nav class="sidebar" id="sidebar">
+  <div class="section-label">快速开始</div>
+  <a href="#overview" class="active">项目概述</a>
+  <a href="#install">安装方式</a>
+  <a href="#quickstart">5 分钟上手</a>
+  <div class="section-label">核心命令</div>
+  <a href="#build">build — 构建图谱</a>
+  <a href="#query">query — 查询图谱</a>
+  <a href="#watch">watch — 监听模式</a>
+  <a href="#serve">serve — MCP 服务</a>
+  <div class="section-label">进阶功能</div>
+  <a href="#config">配置系统</a>
+  <a href="#formats">输出格式</a>
+  <a href="#diff">对比差异</a>
+  <a href="#stats">统计信息</a>
+  <a href="#ingest">导入外链</a>
+  <div class="section-label">集成</div>
+  <a href="#claude-integration">Claude Code 集成</a>
+  <a href="#git-hook">Git Hook 集成</a>
+  <div class="section-label">参考</div>
+  <a href="#flags">全局参数速查</a>
+  <a href="#faq">常见问题</a>
+</nav>
+
+<main class="main">
+
+<!-- ===== 项目概述 ===== -->
+<div class="section" id="overview">
+  <h2 class="section-title"><span class="emoji">📊</span>项目概述</h2>
+  <p><strong>graphify-rs</strong> 是一个用 Rust 编写的 AI 代码知识图谱构建工具。它通过 AST 解析源码，提取函数、类、文件间的调用与依赖关系，生成结构化的 <code>graph.json</code>，并输出多种格式的报告和可视化文件。</p>
+
+  <div class="card-grid">
+    <div class="card">
+      <h4>AST 解析，无需编译</h4>
+      <p>基于 treesitter 进行语法分析，支持 50+ 语言，不需要编译或运行代码即可构建依赖图。</p>
+    </div>
+    <div class="card">
+      <h4>增量构建</h4>
+      <p><code>--update</code> 模式只重新解析新增或修改的文件，大型项目构建仅需 2~5 秒。</p>
+    </div>
+    <div class="card">
+      <h4>多格式输出</h4>
+      <p>支持 JSON、HTML 可视化、GraphML、Cypher、Wiki、Obsidian、SVG 等 8 种格式。</p>
+    </div>
+    <div class="card">
+      <h4>AI 集成</h4>
+      <p>原生支持 Claude Code、Codex、OpenClaw、Trae 等编辑器，也可作为 MCP Server 运行。</p>
+    </div>
+  </div>
+
+  <h3 class="subsection-title">支持的编程语言</h3>
+  <table>
+    <thead><tr><th>语言</th><th>文件扩展名</th><th>解析器</th></tr></thead>
+    <tbody>
+      <tr><td>Java</td><td><code>.java</code></td><td>treesitter-java</td></tr>
+      <tr><td>Python</td><td><code>.py</code></td><td>treesitter-python</td></tr>
+      <tr><td>JavaScript / TypeScript</td><td><code>.js</code> <code>.ts</code> <code>.tsx</code></td><td>treesitter-typescript</td></tr>
+      <tr><td>Go</td><td><code>.go</code></td><td>treesitter-go</td></tr>
+      <tr><td>Rust</td><td><code>.rs</code></td><td>treesitter-rust</td></tr>
+      <tr><td>C / C++</td><td><code>.c</code> <code>.cpp</code> <code>.h</code></td><td>treesitter-c / cpp</td></tr>
+      <tr><td>Ruby</td><td><code>.rb</code></td><td>treesitter-ruby</td></tr>
+      <tr><td>PHP</td><td><code>.php</code></td><td>treesitter-php</td></tr>
+      <tr><td>其他</td><td>Markdown / TOML / JSON / YAML 等</td><td>通用解析</td></tr>
+    </tbody>
+  </table>
+</div>
+
+<!-- ===== 安装方式 ===== -->
+<div class="section" id="install">
+  <h2 class="section-title"><span class="emoji">📦</span>安装方式</h2>
+
+  <h3 class="subsection-title">方式一：Cargo 安装（推荐）</h3>
+  <pre><code>cargo install graphify-rs</code></pre>
+
+  <h3 class="subsection-title">方式二：从源码构建</h3>
+  <pre><code>git clone https://github.com/nicbarker/graphify.git
+cd graphify
+cargo build --release
+# 产物在 target/release/graphify-rs</code></pre>
+
+  <h3 class="subsection-title">方式三：预编译二进制</h3>
+  <p>从 GitHub Releases 下载对应平台的二进制文件，放入 <code>PATH</code> 即可。</p>
+
+  <div class="callout callout-tip">
+    <p>验证安装是否成功：</p>
+    <pre><code>graphify-rs --version</code></pre>
+  </div>
+</div>
+
+<!-- ===== 5 分钟上手 ===== -->
+<div class="section" id="quickstart">
+  <h2 class="section-title"><span class="emoji">🚀</span>5 分钟上手</h2>
+
+  <div class="flow">步骤 1：初始化配置（可选）
+  graphify-rs init
+
+步骤 2：构建知识图谱
+  cd /path/to/your-project
+  graphify-rs build --path . --output graphify-out
+
+步骤 3：查看输出
+  ls graphify-out/
+  ├── graph.json          # 图谱数据（核心产物）
+  ├── index.html           # 交互式可视化页面
+  ├── GRAPH_REPORT.md      # 架构深度报告
+  └── wiki/index.md        # Wiki 导航索引
+
+步骤 4：在 Claude Code 中使用
+  graphify-rs install --platform claude</div>
+
+  <div class="callout callout-tip">
+    <p>首次构建时 <code>--no-llm</code> 会跳过 LLM 摘要生成，速度更快。需要 AI 增强报告时去掉此标志。</p>
+  </div>
+</div>
+
+<!-- ===== build ===== -->
+<div class="section" id="build">
+  <h2 class="section-title"><span class="emoji">🔨</span>build — 构建知识图谱</h2>
+  <p><code>build</code> 是核心命令，解析源代码并生成图谱数据。</p>
+
+  <h3 class="subsection-title">基础用法</h3>
+  <pre><code># 构建当前目录
+graphify-rs build
+
+# 构建指定目录，输出到自定义路径
+graphify-rs build --path /path/to/project --output my-graph
+
+# 增量构建（只解析变更文件）
+graphify-rs build --path . --output graphify-out --update</code></pre>
+
+  <h3 class="subsection-title">常用参数</h3>
+  <table>
+    <thead><tr><th>参数</th><th>默认值</th><th>说明</th></tr></thead>
+    <tbody>
+      <tr><td><code>-p, --path</code></td><td><code>.</code></td><td>要扫描的项目目录</td></tr>
+      <tr><td><code>-o, --output</code></td><td><code>graphify-out</code></td><td>输出目录路径</td></tr>
+      <tr><td><code>--update</code></td><td>—</td><td>增量模式，仅重新解析新/修改的文件</td></tr>
+      <tr><td><code>--no-llm</code></td><td>—</td><td>跳过 LLM 增强，纯 AST 解析（更快）</td></tr>
+      <tr><td><code>--code-only</code></td><td>—</td><td>只解析代码文件，忽略文档/配置</td></tr>
+      <tr><td><code>--format</code></td><td><code>all</code></td><td>指定输出格式，逗号分隔</td></tr>
+      <tr><td><code>--max-viz-nodes</code></td><td><code>2000</code></td><td>HTML 可视化节点上限，超出会卡顿</td></tr>
+      <tr><td><code>-j, --jobs</code></td><td>CPU 核数</td><td>并行任务数</td></tr>
+      <tr><td><code>-v, --verbose</code></td><td>—</td><td>输出 debug 级别日志</td></tr>
+      <tr><td><code>-q, --quiet</code></td><td>—</td><td>静默模式，只输出错误</td></tr>
+    </tbody>
+  </table>
+
+  <h3 class="subsection-title">实用场景</h3>
+
+  <p><strong>大型 Java 项目首次构建：</strong></p>
+  <pre><code>graphify-rs build --path ./crmeb-mer --output graphify-out --max-viz-nodes 5000</code></pre>
+
+  <p><strong>日常开发增量更新：</strong></p>
+  <pre><code># 修改代码后快速更新图谱
+graphify-rs build --path . --output graphify-out --no-llm --update</code></pre>
+
+  <p><strong>只生成 JSON 数据（不生成 HTML/Wiki 等）：</strong></p>
+  <pre><code>graphify-rs build --path . --output graphify-out --format json</code></pre>
+
+  <p><strong>指定多种输出格式：</strong></p>
+  <pre><code>graphify-rs build --path . --output graphify-out --format json,wiki,report</code></pre>
+
+  <div class="callout callout-warning">
+    <p><code>--max-viz-nodes</code> 设置过高会导致浏览器渲染卡顿，建议 2000 以下。超过 5000 仅适合在高性能机器上查看。</p>
+  </div>
+</div>
+
+<!-- ===== query ===== -->
+<div class="section" id="query">
+  <h2 class="section-title"><span class="emoji">🔍</span>query — 查询知识图谱</h2>
+  <p>基于自然语言提问，工具会在图谱数据中进行图遍历和语义匹配，返回相关节点和关系。</p>
+
+  <h3 class="subsection-title">基础用法</h3>
+  <pre><code>graphify-rs query "项目中有哪些 Controller 类？"
+graphify-rs query "UserService 依赖了哪些模块？"
+graphify-rs query "支付相关的方法有哪些？"</code></pre>
+
+  <h3 class="subsection-title">参数</h3>
+  <table>
+    <thead><tr><th>参数</th><th>默认值</th><th>说明</th></tr></thead>
+    <tbody>
+      <tr><td><code>&lt;QUESTION&gt;</code></td><td>必填</td><td>自然语言查询问题</td></tr>
+      <tr><td><code>--graph</code></td><td><code>graphify-out/graph.json</code></td><td>图谱数据路径</td></tr>
+      <tr><td><code>--budget</code></td><td><code>2000</code></td><td>图遍历预算（步数）</td></tr>
+      <tr><td><code>--dfs</code></td><td>—</td><td>使用深度优先搜索策略</td></tr>
+    </tbody>
+  </table>
+
+  <div class="callout callout-tip">
+    <p>查询问题越具体，返回结果越精准。"入口方法有哪些" 比 "结构是什么" 效果好得多。</p>
+  </div>
+</div>
+
+<!-- ===== watch ===== -->
+<div class="section" id="watch">
+  <h2 class="section-title"><span class="emoji">👁️</span>watch — 监听模式</h2>
+  <p>监听项目文件变化，自动触发增量重建图谱，适合开发过程中持续保持图谱最新。</p>
+
+  <pre><code># 监听当前目录
+graphify-rs watch
+
+# 监听指定目录
+graphify-rs watch --path ./crmeb-mer --output graphify-out</code></pre>
+
+  <p>运行后会保持后台监听进程，每次检测到文件变动自动执行 <code>build --update</code>。</p>
+
+  <div class="callout callout-warning">
+    <p>监听模式对大型目录可能会频繁触发构建，建议配合 <code>--update</code> 使用（默认行为）。</p>
+  </div>
+</div>
+
+<!-- ===== serve ===== -->
+<div class="section" id="serve">
+  <h2 class="section-title"><span class="emoji">🖥️</span>serve — MCP Server</h2>
+  <p>以 MCP（Model Context Protocol）服务形式暴露图谱查询能力，供 AI 编辑器远程调用。</p>
+
+  <pre><code># 启动 MCP 服务
+graphify-rs serve
+
+# 指定图谱数据
+graphify-rs serve --graph graphify-out/graph.json</code></pre>
+
+  <p>启动后支持 SSE / stdio 传输协议，可在 Claude Code 的 MCP 配置中注册为远程工具。</p>
+</div>
+
+<!-- ===== 配置系统 ===== -->
+<div class="section" id="config">
+  <h2 class="section-title"><span class="emoji">⚙️</span>配置系统</h2>
+
+  <h3 class="subsection-title">初始化配置</h3>
+  <pre><code>graphify-rs init</code></pre>
+  <p>在项目根目录生成 <code>graphify.toml</code> 配置文件，可自定义：</p>
+  <ul>
+    <li><strong>include / exclude 规则</strong> — 控制哪些文件/目录被扫描</li>
+    <li><strong>LLM 提供商和模型</strong> — 配置增强摘要使用的 AI 模型</li>
+    <li><strong>输出格式默认值</strong> — 设置 <code>--format</code> 的默认行为</li>
+  </ul>
+
+  <h3 class="subsection-title">示例配置</h3>
+  <pre><code># graphify.toml
+[build]
+path = "."
+output = "graphify-out"
+
+[exclude]
+paths = ["node_modules", "target", "dist", ".git"]
+
+[llm]
+enabled = true
+model = "claude-sonnet-4-6"</code></pre>
+
+  <p>有配置文件后，<code>build</code> 命令会自动读取，命令行参数会覆盖配置文件中的值。</p>
+</div>
+
+<!-- ===== 输出格式 ===== -->
+<div class="section" id="formats">
+  <h2 class="section-title"><span class="emoji">📋</span>输出格式速查</h2>
+  <p>通过 <code>--format</code> 参数控制输出产物，默认 <code>all</code> 生成全部格式。</p>
+
+  <table>
+    <thead><tr><th>格式</th><th>说明</th><th>典型用途</th></tr></thead>
+    <tbody>
+      <tr><td><code>json</code></td><td>结构化图谱数据 <code>graph.json</code></td><td>查询、MCP 服务、二次开发</td></tr>
+      <tr><td><code>html</code></td><td>交互式可视化页面 <code>index.html</code></td><td>浏览器中浏览代码关系</td></tr>
+      <tr><td><code>report</code></td><td>架构深度分析报告 <code>GRAPH_REPORT.md</code></td><td>架构评审、文档沉淀</td></tr>
+      <tr><td><code>wiki</code></td><td>Wiki 格式文档 <code>wiki/index.md</code></td><td>AI 编辑器导航</td></tr>
+      <tr><td><code>obsidian</code></td><td>Obsidian 双向链接笔记</td><td>个人知识管理</td></tr>
+      <tr><td><code>graphml</code></td><td>GraphML 格式图</td><td>导入 Gephi 等图分析工具</td></tr>
+      <tr><td><code>cypher</code></td><td>Neo4j Cypher 导入脚本</td><td>导入 Neo4j 图数据库</td></tr>
+      <tr><td><code>svg</code></td><td>静态 SVG 依赖图</td><td>文档嵌入、打印</td></tr>
+    </tbody>
+  </table>
+</div>
+
+<!-- ===== diff ===== -->
+<div class="section" id="diff">
+  <h2 class="section-title"><span class="emoji">🔄</span>diff — 对比图谱差异</h2>
+  <p>比较两次构建之间的图谱变化，查看新增/删除/修改的节点和关系。</p>
+
+  <pre><code>graphify-rs diff old-graph.json new-graph.json
+graphify-rs diff graphify-out/graph.json graphify-out-v2/graph.json --output json</code></pre>
+
+  <table>
+    <thead><tr><th>参数</th><th>默认值</th><th>说明</th></tr></thead>
+    <tbody>
+      <tr><td><code>&lt;OLD&gt;</code></td><td>必填</td><td>旧版 graph.json 路径</td></tr>
+      <tr><td><code>&lt;NEW&gt;</code></td><td>必填</td><td>新版 graph.json 路径</td></tr>
+      <tr><td><code>--output</code></td><td><code>text</code></td><td>输出格式：<code>text</code> 或 <code>json</code></td></tr>
+    </tbody>
+  </table>
+
+  <div class="callout callout-tip">
+    <p>典型用法：重构前后对比架构变化，或者验证某个模块的依赖是否被正确删除。</p>
+  </div>
+</div>
+
+<!-- ===== stats ===== -->
+<div class="section" id="stats">
+  <h2 class="section-title"><span class="emoji">📈</span>stats — 统计信息</h2>
+  <p>不重新构建，直接读取已有的 <code>graph.json</code> 并输出统计摘要。</p>
+
+  <pre><code>graphify-rs stats
+graphify-rs stats graphify-out/graph.json</code></pre>
+
+  <p>输出内容包括：节点数、边数、文件数、语言分布、拓扑指标等。</p>
+</div>
+
+<!-- ===== ingest ===== -->
+<div class="section" id="ingest">
+  <h2 class="section-title"><span class="emoji">🌐</span>ingest — 导入外链内容</h2>
+  <p>抓取指定 URL 的内容并纳入图谱分析范围，适合分析在线文档或远程代码。</p>
+
+  <pre><code>graphify-rs ingest https://example.com/api-docs</code></pre>
+
+  <p>内容会被保存到输出目录，后续 <code>build</code> 时一并分析。</p>
+</div>
+
+<!-- ===== Claude Code 集成 ===== -->
+<div class="section" id="claude-integration">
+  <h2 class="section-title"><span class="emoji">🤖</span>Claude Code 集成</h2>
+
+  <h3 class="subsection-title">安装技能</h3>
+  <pre><code>graphify-rs install --platform claude</code></pre>
+  <p>自动将 graphify 技能注册到 Claude Code，注册后可在对话中使用 <code>/graphify</code> 命令。</p>
+
+  <h3 class="subsection-title">卸载</h3>
+  <pre><code>graphify-rs claude uninstall</code></pre>
+
+  <div class="callout callout-tip">
+    <p>也可以在 CLAUDE.md 中手动配置图谱使用规则，例如：</p>
+    <pre><code># 回答架构问题前先读取图谱
+- 先读取 graphify-out/GRAPH_REPORT.md 了解核心节点和社区结构
+- 如果 graphify-out/wiki/index.md 存在，优先导航该索引</code></pre>
+  </div>
+</div>
+
+<!-- ===== Git Hook 集成 ===== -->
+<div class="section" id="git-hook">
+  <h2 class="section-title"><span class="emoji">🪝</span>Git Hook 集成</h2>
+  <p>将图谱构建绑定到 Git 事件（如 commit 后自动构建），保持图谱始终与代码同步。</p>
+
+  <h3 class="subsection-title">安装 Hook</h3>
+  <pre><code>graphify-rs hook install</code></pre>
+
+  <h3 class="subsection-title">查看状态</h3>
+  <pre><code>graphify-rs hook status</code></pre>
+
+  <h3 class="subsection-title">卸载 Hook</h3>
+  <pre><code>graphify-rs hook uninstall</code></pre>
+
+  <p>默认在 <code>post-commit</code> 阶段触发增量构建，等价于每次提交后自动运行 <code>build --update</code>。</p>
+</div>
+
+<!-- ===== 全局参数速查 ===== -->
+<div class="section" id="flags">
+  <h2 class="section-title"><span class="emoji">📌</span>全局参数速查</h2>
+  <p>以下参数对所有子命令生效：</p>
+
+  <table>
+    <thead><tr><th>参数</th><th>说明</th></tr></thead>
+    <tbody>
+      <tr><td><code>-q, --quiet</code></td><td>静默模式，抑制非必要输出</td></tr>
+      <tr><td><code>-v, --verbose</code></td><td>调试模式，输出 debug 级日志</td></tr>
+      <tr><td><code>-j, --jobs</code></td><td>并行任务数，默认等于 CPU 核数</td></tr>
+      <tr><td><code>-h, --help</code></td><td>打印帮助信息</td></tr>
+      <tr><td><code>-V, --version</code></td><td>打印版本号</td></tr>
+    </tbody>
+  </table>
+</div>
+
+<!-- ===== 常见问题 ===== -->
+<div class="section" id="faq">
+  <h2 class="section-title"><span class="emoji">💡</span>常见问题</h2>
+
+  <h3 class="subsection-title">构建太慢了怎么办？</h3>
+  <p>首次构建对大型项目可能需要十几秒。优化方案：</p>
+  <ul>
+    <li>使用 <code>--update</code> 增量构建（通常 2~5 秒）</li>
+    <li>使用 <code>--no-llm</code> 跳过 LLM 增强</li>
+    <li>在 <code>graphify.toml</code> 中排除不需要的目录（如 <code>node_modules</code>、<code>vendor</code>）</li>
+  </ul>
+
+  <h3 class="subsection-title">HTML 可视化页面卡顿？</h3>
+  <p>节点过多会导致浏览器渲染性能下降。通过 <code>--max-viz-nodes 1000</code> 限制节点数量。</p>
+
+  <h3 class="subsection-title">如何排除某些文件/目录？</h3>
+  <p>在项目根目录创建 <code>graphify.toml</code>，在 <code>[exclude]</code> 中配置路径列表，或运行 <code>graphify-rs init</code> 生成模板后修改。</p>
+
+  <h3 class="subsection-title">图谱数据在哪个目录？</h3>
+  <p>默认输出到 <code>graphify-out/</code>，核心产物是 <code>graph.json</code>，所有查询、MCP 服务、diff 对比都基于此文件。</p>
+
+  <h3 class="subsection-title">如何在团队中共享图谱？</h3>
+  <ul>
+    <li>将 <code>graphify-out/</code> 提交到 Git，团队成员可直接查看报告</li>
+    <li>使用 <code>graphify-rs serve</code> 启动 MCP Server 共享查询能力</li>
+    <li>生成 GraphML 格式导入 Gephi 进行深度图分析</li>
+  </ul>
+
+  <h3 class="subsection-title">日常开发工作流建议</h3>
+  <div class="flow">开发中:    graphify-rs watch              # 后台监听，自动更新
+提交前:    graphify-rs stats               # 快速检查图谱状态
+提交后:    git hook 自动 build --update    # 保持图谱同步
+需要分析:  graphify-rs query "..."         # 自然语言查询图谱
+归档:      git commit graphify-out/         # 将图谱随代码一起版本管理</div>
+</div>
+
+</main>
+
+<script>
+// Sidebar scroll spy
+const links = document.querySelectorAll('.sidebar a');
+const sections = [...links].map(a => document.querySelector(a.getAttribute('href')));
+
+function onScroll() {
+  let idx = 0;
+  for (let i = sections.length - 1; i >= 0; i--) {
+    if (sections[i] && sections[i].getBoundingClientRect().top <= 120) { idx = i; break; }
+  }
+  links.forEach((a, i) => a.classList.toggle('active', i === idx));
+}
+
+window.addEventListener('scroll', onScroll, { passive: true });
+onScroll();
+
+// Smooth scroll
+links.forEach(a => {
+  a.addEventListener('click', e => {
+    e.preventDefault();
+    const target = document.querySelector(a.getAttribute('href'));
+    if (target) target.scrollIntoView({ behavior: 'smooth' });
+  });
+});
+</script>
+
+</body>
+</html>