ln-020-codegraph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths are relative to skills repo root.

路径： 文件路径相对于技能仓库根目录。

Code Knowledge Graph

代码知识图谱

Type: Standalone Utility Category: 0XX Dev Environment

Indexes codebase into a layered graph (tree-sitter AST → SQLite) and provides dependency analysis, path tracing, references, implementations, and architecture overview via MCP tools.

类型： 独立工具 分类： 0XX 开发环境

将代码库索引为分层图谱（tree-sitter AST → SQLite），并通过MCP工具提供依赖分析、路径追踪、引用查找、实现定位和架构概览功能。

Inputs

输入

Input	Required	Source	Description
`project_path`	yes	args or CWD	Project root to index
`command`	no	args	Specific action: `index` , `search` , `symbol` , `paths` , `refs` , `arch`

输入	是否必填	来源	描述
`project_path`	是	参数或当前工作目录（CWD）	要索引的项目根目录
`command`	否	参数	具体操作： `index` 、 `search` 、 `symbol` 、 `paths` 、 `refs` 、 `arch`

When to Use

适用场景

Starting work on an unfamiliar codebase →
```
index
```
+
```
architecture
```
Before refactoring a function/class →
```
search
```
+
```
get_symbol
```
+
```
trace_paths
```
Understanding call flow →
```
trace_paths
```
Finding a symbol quickly →
```
search
```

开始接触陌生代码库 →
```
index
```
+
```
architecture
```
重构函数/类之前 →
```
search
```
+
```
get_symbol
```
+
```
trace_paths
```
梳理调用流程 →
```
trace_paths
```
快速查找符号 →
```
search
```

Workflow

工作流程

Phase 1: Index

阶段1：索引

Check if graph exists (

.hex-skills/codegraph/index.db

in project root).

If NOT exists:

Call: index_project({ path: "{project_path}" })

If exists (re-index on demand):

Call: index_project({ path: "{project_path}" })

Idempotent — skips unchanged files automatically.

检查图谱是否存在（项目根目录下的

.hex-skills/codegraph/index.db

）。

如果不存在：

Call: index_project({ path: "{project_path}" })

如果存在（按需重新索引）：

Call: index_project({ path: "{project_path}" })

幂等操作 — 会自动跳过未修改的文件。

Phase 2: Query

阶段2：查询

Route based on user intent:

User says	Tool	Parameters
"Show dependencies" / "What uses X?"	`trace_paths`	`{ name: "X", file: "...", path_kind: "mixed", direction: "reverse", path: "{project_path}" }`
"Who calls X?" / "What does X call?"	`trace_paths`	`{ name: "X", file: "...", path_kind: "calls", direction: "reverse"\|"forward", path: "{project_path}" }`
"Tell me about X" / "Context of X"	`get_symbol`	`{ name: "X", file: "...", path: "{project_path}" }`
"Project structure" / "Architecture"	`get_architecture`	`{ path: "{project_path}", scope?: "src/" }`
"Find symbol X"	`search_symbols`	`{ query: "X" }`
"Watch for changes"	`watch_project`	`{ path: "{project_path}" }`
"Find duplicate code"	`find_clones`	`{ path: "{project_path}", type: "all" }`
"Risky hotspots"	`find_hotspots`	`{ path: "{project_path}", min_callers: 2, min_complexity: 5 }`
"Unused exports"	`find_unused_exports`	`{ path: "{project_path}" }`
"Circular dependencies"	`find_cycles`	`{ path: "{project_path}" }`
"Module coupling"	`get_module_metrics`	`{ path: "{project_path}", min_coupling: 0 }`
"Implementations / overrides"	`find_implementations`	`{ name: "X", file: "...", path: "{project_path}" }`
"Dataflow / propagation"	`find_dataflows`	`{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }`

Canonical selector rule: Semantic tools accept exactly one selector:

```
symbol_id
```
```
workspace_qualified_name
```
```
qualified_name
```
```
name
```
+
```
file
```

Preferred flow: use

search_symbols

first, then feed the returned

workspace_qualified_name

into

get_symbol

trace_paths

find_references

, or

find_implementations

for exact follow-up queries.

Dataflow anchors:

find_dataflows

requires

source.anchor

and optional

sink.anchor

. Use:

```
param
```
for function parameters
```
local
```
for local variables
```
return
```
for function returns
```
property
```
with
```
access_path
```
for bounded property flow

Precision controls:

get_symbol

trace_paths

, and

find_references

support

min_confidence

(

low

inferred

exact

precise

) when the caller wants to suppress weaker parser-only facts.

根据用户意图路由到对应工具：

用户诉求	工具	参数
"展示依赖" / "哪些地方用到了X？"	`trace_paths`	`{ name: "X", file: "...", path_kind: "mixed", direction: "reverse", path: "{project_path}" }`
"谁调用了X？" / "X调用了哪些内容？"	`trace_paths`	`{ name: "X", file: "...", path_kind: "calls", direction: "reverse"\|"forward", path: "{project_path}" }`
"介绍下X" / "X的上下文"	`get_symbol`	`{ name: "X", file: "...", path: "{project_path}" }`
"项目结构" / "架构概览"	`get_architecture`	`{ path: "{project_path}", scope?: "src/" }`
"查找符号X"	`search_symbols`	`{ query: "X" }`
"监听变更"	`watch_project`	`{ path: "{project_path}" }`
"查找重复代码"	`find_clones`	`{ path: "{project_path}", type: "all" }`
"风险热点"	`find_hotspots`	`{ path: "{project_path}", min_callers: 2, min_complexity: 5 }`
"未使用导出"	`find_unused_exports`	`{ path: "{project_path}" }`
"循环依赖"	`find_cycles`	`{ path: "{project_path}" }`
"模块耦合度"	`get_module_metrics`	`{ path: "{project_path}", min_coupling: 0 }`
"实现/重写逻辑"	`find_implementations`	`{ name: "X", file: "...", path: "{project_path}" }`
"数据流/传播路径"	`find_dataflows`	`{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }`

标准选择器规则： 语义工具仅接受以下选择器中的一个：

```
symbol_id
```
```
workspace_qualified_name
```
```
qualified_name
```
```
name
```
+
```
file
```

推荐流程： 先使用

search_symbols

，再将返回的

workspace_qualified_name

传入

get_symbol

、

trace_paths

、

find_references

或

find_implementations

进行精准的后续查询。

数据流锚点：

find_dataflows

需要传入

source.anchor

，可选传入

sink.anchor

。可用值：

```
param
```
对应函数参数
```
local
```
对应局部变量
```
return
```
对应函数返回值
搭配
```
access_path
```
使用的
```
property
```
对应有限属性流

精度控制： 当调用方想要过滤掉仅靠解析器得到的可信度较低的结果时，

get_symbol

、

trace_paths

和

find_references

支持设置

min_confidence

（

low

、

inferred

、

exact

、

precise

）。

Phase 3: Present Results

阶段3：结果展示

Show MCP tool output directly (markdown tables)
For code snippets referenced in results, use
```
hex-line read_file
```
with line ranges
Suggest follow-up queries based on results:
- After
```
search_symbols
```
  → suggest
```
get_symbol
```
  with
```
workspace_qualified_name
```
  for the top exact match
- After
```
get_symbol
```
  → suggest
```
trace_paths
```
  if refactoring
- After
```
trace_paths
```
  → suggest
```
find_references
```
  or
```
find_implementations
```
  depending on symbol kind

直接展示MCP工具的输出（markdown表格）
对于结果中引用的代码片段，使用带行范围的
```
hex-line read_file
```
读取
基于结果推荐后续查询：
- 执行
```
search_symbols
```
  后 → 推荐使用匹配度最高的
```
workspace_qualified_name
```
  调用
```
get_symbol
```
- 执行
```
get_symbol
```
  后 → 如果是重构场景，推荐使用
```
trace_paths
```
- 执行
```
trace_paths
```
  后 → 根据符号类型推荐
```
find_references
```
  或
```
find_implementations
```

Supported Languages

支持的语言

Language	Extensions	Coverage
JavaScript	.js, .mjs, .cjs, .jsx	Strongest semantic coverage
TypeScript / TSX	.ts, .tsx	Strongest semantic coverage
Python	.py	Workspace-aware definitions, calls, imports, unused exports; optional precise overlay when provider is installed
C#	.cs	Workspace-aware definitions, calls, project/namespace ownership, type relations; optional precise overlay when provider is installed
PHP	.php	Workspace-aware definitions, calls, PSR-4 namespace imports, unused exports; optional precise overlay when provider is installed

语言	扩展名	支持程度
JavaScript	.js, .mjs, .cjs, .jsx	最强语义覆盖
TypeScript / TSX	.ts, .tsx	最强语义覆盖
Python	.py	支持工作区级别的定义、调用、导入、未使用导出检测；安装对应provider后可开启可选的高精度覆盖
C#	.cs	支持工作区级别的定义、调用、项目/命名空间归属、类型关系；安装对应provider后可开启可选的高精度覆盖
PHP	.php	支持工作区级别的定义、调用、PSR-4命名空间导入、未使用导出检测；安装对应provider后可开启可选的高精度覆盖

MCP Server Setup

MCP 服务端配置

Add to

.mcp.json

json

{
  "mcpServers": {
    "hex-graph": {
      "command": "node",
      "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
    }
  }
}

添加到

.mcp.json

：

json

{
  "mcpServers": {
    "hex-graph": {
      "command": "node",
      "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
    }
  }
}

Definition of Done

完成标准

Project indexed (index_project returns success)
Query results shown to user
Follow-up suggestions provided

Version: 0.1.0 Last Updated: 2026-03-20

项目索引完成（index_project返回成功）
已向用户展示查询结果
已提供后续查询建议

版本： 0.1.0 最后更新： 2026-03-20