# codegraph-viz

**Repository Path**: haijiun/codegraph-viz

## Basic Information

- **Project Name**: codegraph-viz
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codegraph-viz

> 把 [Codegraph](https://github.com/) 的代码知识图谱索引 `.codegraph/codegraph.db`，渲染成**可离线打开**的交互式图：调用图 / 依赖图 / 类继承体系，支持搜索、过滤、双击跳转源码。

[English](./README.md)

这是一个 [Claude Code](https://claude.com/claude-code) **Agent Skill**。它读取
Codegraph 为仓库构建的 SQLite 知识图谱，把一个**带范围限定的子图**渲染成自包含的
交互式 HTML 页面（或导出 GraphML 供 Gephi / Cytoscape 使用）。它是**只读**的——
绝不会重新索引或修改数据库。

## 它能干什么

Codegraph 已经能用文字回答"X 是怎么工作的"。这个 skill 解决的是你想**直接看到**
结构的场景：

- 某个函数周围的**调用图**（"谁调用它、它调用谁"）；
- 一个模块的**内部接线** / 依赖图；
- **类继承体系**（`extends` 边）；
- 改动前先看**影响面（blast radius）**。

整张图（动辄上千节点）一次画出来就是一团乱麻，所以每次渲染都必须**限定范围**——
按根符号 + BFS 深度、按目录、按边类型、按节点类型，或只保留度数最高的枢纽节点。

## 功能特性

- **完全离线** —— vis-network 已内置并内联进 HTML，无需 CDN、无需联网、HTML 输出
  无需 pip 安装。文件可随意拷贝/分享。
- **搜索框** —— 实时高亮匹配节点；按 Enter 缩放定位到第一个命中。
- **可点击图例** —— 切换任意节点类型的显隐（例如隐藏 `import` 噪声，露出底下的
  调用结构）。
- **双击跳源码** —— 在 VS Code 中按精确行号打开该符号（`--editor idea` 走
  JetBrains，或自定义 URL 模板）。
- **悬停提示** —— 显示类型、全限定名、文件:行号、签名。
- **GraphML 导出** —— 在 Gephi / Cytoscape 里做重量级图分析。

## 前置要求

- 仓库已被 **Codegraph 索引**（存在 `.codegraph/codegraph.db`）。本 skill 不负责
  建索引——请先运行 Codegraph 索引器。
- **Python 3.9+**。HTML 输出无需任何第三方包；GraphML 导出额外需要 `networkx`
  （`pip install networkx`）。

## 安装

这是标准的 Claude Code skill——把文件夹放进 skills 目录即可：

```bash
# 个人级（对你所有项目生效）：
git clone https://github.com/<you>/codegraph-viz ~/.claude/skills/codegraph-viz

# …或项目级（随仓库一起提交）：
git clone https://github.com/<you>/codegraph-viz <repo>/.claude/skills/codegraph-viz
```

Claude Code 会通过 `SKILL.md` 的 frontmatter 自动发现它。若不经 Claude、直接用
命令行，clone 到任意位置运行脚本即可（见下）。

## 使用方法

直接用自然语言让 Claude 做即可——例如 *"把 `run_trace_phases` 的调用图画出来"*
或 *"画一下 training 模块的类继承体系"*，skill 会自动触发。

也可以自己跑脚本（DB 会从当前目录向上自动查找）：

```bash
# 从某函数向外扩 2 跳的调用图：
python scripts/codegraph_viz.py --root run_trace_phases --depth 2 \
    --edge-kinds calls,instantiates,extends --out rtp.html

# 某个包的内部接线：
python scripts/codegraph_viz.py --dir src/server --out server.html

# 全仓库的类继承体系：
python scripts/codegraph_viz.py --edge-kinds extends --node-kinds class \
    --max-nodes 800 --out classes.html

# 导出给 Gephi / Cytoscape：
python scripts/codegraph_viz.py --dir src/server --format graphml --out server.graphml
```

然后用任意浏览器打开 `.html`。

### 便捷封装

`wrappers/` 里有转发全部参数的封装脚本，会自动挑对解释器（Windows 上优先用 `py`
启动器，因为系统自带的 `python.exe` 是个坏掉的 Store 占位 stub）：

```bash
./wrappers/codegraph-viz --root main --depth 2 --out main.html      # bash
.\wrappers\codegraph-viz.cmd --root main --depth 2 --out main.html  # cmd / PowerShell
```

## 参数说明

| 参数 | 含义 |
|---|---|
| `--db PATH` | DB 路径（默认：向上查找 `.codegraph/`） |
| `--root NAME` | BFS 起点符号（先精确匹配 name/qualified_name，否则子串匹配） |
| `--depth N` | 从 `--root` 出发的 BFS 跳数（默认 2） |
| `--dir PREFIX` | 只保留 `file_path` 以此开头的节点 |
| `--edge-kinds` | `calls,contains,instantiates,imports,extends,references` |
| `--node-kinds` | `function,method,class,file,variable,…` |
| `--max-nodes N` | 上限（默认 400）；超出时保留度数最高的节点 |
| `--format` | `html`（默认）或 `graphml` |
| `--out PATH` | 输出文件 |
| `--cdn` | 从 CDN 加载 vis-network 而非内联（文件更小，但需联网） |
| `--editor` | `vscode`（默认）、`idea`，或 `{file}/{line}/{col}` URL 模板 |

## 工作原理

Codegraph 的 DB 把每个符号存为 `nodes` 表的一行（`id, kind, name,
qualified_name, file_path, start_line, signature, …`），每条关系存为 `edges`
表的一行（`source, target, kind` ∈ `calls/contains/instantiates/imports/
extends/references`）。脚本会：

1. 定位 `.codegraph/codegraph.db`（只读打开）；
2. 加载节点 + 边，应用范围过滤，给定 `--root` 时跑 BFS，并把结果裁剪到度数最高的
   节点；
3. 生成 HTML 页面——子图以 JSON 内嵌、vis-network 内联；或经 networkx 导出
   GraphML。

## 常见问题

- **结果为空** → 过滤太紧：放宽 `--depth`、去掉 `--node-kinds`、或扩大 `--dir`。
- **`--root` 找不到** → 依次尝试精确 name、qualified_name、子串匹配；检查拼写或
  改用 `--dir`。
- **默认离线**：约 640 KB 的 vis-network 被内联，因此每个 HTML 较大但完全可移植。
  联网时可用 `--cdn` 生成小文件。若内置的库文件缺失，脚本会自动下载一次到
  `scripts/vendor/`，只有下载也失败时才回退到 CDN。
- **Windows 上 `python` 指向坏掉的 Store stub**：改用 `py` 启动器
  （`.cmd`/`.ps1` 封装已默认优先用它）。
- DB 以**只读**（`mode=ro`）打开，可在 Codegraph 守护进程实时索引时安全运行。

## 许可证

MIT —— 见 `LICENSE`（发布前请补上你选择的许可证）。