yueqian-ai
697 lines
26 KiB
HTML
697 lines
26 KiB
HTML
<!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><QUESTION></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><OLD></code></td><td>必填</td><td>旧版 graph.json 路径</td></tr>
|
||
<tr><td><code><NEW></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>
|