ln-021-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`	是	参数或当前工作目录	要索引的项目根目录
`command`	否	参数	具体操作： `index` , `search` , `symbol` , `paths` , `refs` , `arch`

When to Use

使用场景

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

接手陌生代码库时 →
```
index
```
+
```
architecture
```
对函数/类进行重构前 →
```
find_symbols
```
+
```
inspect_symbol
```
+
```
trace_paths
```
理解调用流程时 →
```
trace_paths
```
快速查找符号时 →
```
search
```

MCP Availability

MCP 可用性

Tool policy: follow host AGENTS.md MCP preferences; load

references/mcp_tool_preferences.md

and

references/mcp_integration_patterns.md

only when host policy is absent or MCP behavior is unclear.

Use

hex-graph

first when the task depends on symbol identity, references, implementations, architecture, dataflow, or edit impact. Use

hex-line

first for targeted local code reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in

Glob/Grep/Read/Bash

, answer with manual evidence, and explicitly note the degraded confidence instead of blocking the skill.

工具策略：遵循宿主AGENTS.md中的MCP偏好；仅当宿主策略缺失或MCP行为不明确时，才加载

references/mcp_tool_preferences.md

和

references/mcp_integration_patterns.md

。

当任务依赖符号标识、引用、实现、架构、数据流或编辑影响时，优先使用

hex-graph

；如果有可用的针对性本地代码读取工具，优先使用

hex-line

。若MCP不可用、不支持或未完成索引，则继续使用内置的

Glob/Grep/Read/Bash

，手动提供证据并明确标注置信度降低，而非阻塞技能执行。

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.

If
hex-graph
is unavailable: build a manual project map with

Glob

and targeted

Grep/Read

, then continue to the closest matching query workflow without indexing.

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

.hex-skills/codegraph/index.db

）。

若不存在：

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

若存在（按需重新索引）：

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

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

若
hex-graph
不可用：使用

Glob

和针对性的

Grep/Read

构建手动项目映射，然后继续执行最匹配的查询工作流，无需索引。

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"	`inspect_symbol`	`{ name: "X", file: "...", path: "{project_path}" }`
"Project structure" / "Architecture"	`analyze_architecture`	`{ path: "{project_path}", scope?: "src/" }`
"Find symbol X"	`find_symbols`	`{ path: "{project_path}", query: "X" }`
"Find `app.get(...)` / `router.use(...)` / `server.registerTool(...)` pattern"	`grep_search`	`{ path: "{project_path}", pattern: "app\.get\(
"Find duplicate code / hotspots / unused exports"	`audit_workspace`	`{ path: "{project_path}", scope?: "src/", verbosity: "minimal", limit: 5, clone_member_limit: 3 }`
"Circular dependencies / module coupling"	`analyze_architecture`	`{ path: "{project_path}", verbosity: "full" }`
"Implementations / overrides"	`find_implementations`	`{ name: "X", file: "...", path: "{project_path}" }`
"Dataflow / propagation"	`trace_dataflow`	`{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }`
"Review a diff / worktree"	`analyze_changes`	`{ path: "{project_path}", base_ref: "origin/main" }`
"Check what editing this range affects"	`analyze_edit_region`	`{ path: "{project_path}", file: "src/file.ts", line_start: 10, line_end: 40 }`

Canonical selector rule: Semantic tools accept exactly one selector:

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

Preferred flow: use

find_symbols

only after narrowing

path

as much as practical, then feed the returned

workspace_qualified_name

into

inspect_symbol

trace_paths

find_references

, or

find_implementations

for exact follow-up queries.

Query boundary rule:

find_symbols

is name-based discovery only. For code fragments like

export function

or unresolved member-call patterns like

app.get(...)

, use

grep_search

instead of treating them as symbols.

Ambiguity rule: if

find_symbols

returns

partial ... truncated=1

or shows more total results than returned rows, refine with

path

, then

name + file

workspace_qualified_name

instead of widening the graph query.

Path rule:

path

may be the indexed project root or any file/subdirectory inside that indexed project.

Dataflow anchors:

trace_dataflow

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:

inspect_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的上下文"	`inspect_symbol`	`{ name: "X", file: "...", path: "{project_path}" }`
"项目结构" / "架构"	`analyze_architecture`	`{ path: "{project_path}", scope?: "src/" }`
"查找符号X"	`find_symbols`	`{ path: "{project_path}", query: "X" }`
"查找 `app.get(...)` / `router.use(...)` / `server.registerTool(...)` 模式"	`grep_search`	`{ path: "{project_path}", pattern: "app\.get\(
"查找重复代码 / 热点代码 / 未使用的导出"	`audit_workspace`	`{ path: "{project_path}", scope?: "src/", verbosity: "minimal", limit: 5, clone_member_limit: 3 }`
"循环依赖 / 模块耦合"	`analyze_architecture`	`{ path: "{project_path}", verbosity: "full" }`
"实现 / 重写"	`find_implementations`	`{ name: "X", file: "...", path: "{project_path}" }`
"数据流 / 传播路径"	`trace_dataflow`	`{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }`
"审查差异 / 工作区"	`analyze_changes`	`{ path: "{project_path}", base_ref: "origin/main" }`
"检查编辑此范围会影响哪些内容"	`analyze_edit_region`	`{ path: "{project_path}", file: "src/file.ts", line_start: 10, line_end: 40 }`

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

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

推荐流程： 仅在尽可能缩小

path

范围后使用

find_symbols

，然后将返回的

workspace_qualified_name

传入

inspect_symbol

、

trace_paths

、

find_references

或

find_implementations

进行精确的后续查询。

查询边界规则：

find_symbols

仅基于名称进行发现。对于

export function

等代码片段或

app.get(...)

这类未解析的成员调用模式，请使用

grep_search

而非将其视为符号。

歧义处理规则： 如果

find_symbols

partial ... truncated=1

或显示的总结果数多于返回行数，请通过

path

缩小范围，然后使用

name + file

或

workspace_qualified_name

进行查询，而非扩大图谱查询范围。

路径规则：

path

可以是已索引的项目根目录，也可以是该索引项目内的任意文件/子目录。

数据流锚点：

trace_dataflow

需要

source.anchor

，可选

sink.anchor

。可使用：

```
param
```
表示函数参数
```
local
```
表示局部变量
```
return
```
表示函数返回值
```
property
```
搭配
```
access_path
```
表示有界属性流

精度控制： 当调用者希望屏蔽较弱的仅解析器生成的结果时，

inspect_symbol

、

trace_paths

和

find_references

支持

min_confidence

参数（可选值：

low

inferred

exact

precise

）。

Phase 3: Present Results

阶段3：结果呈现

Show MCP tool output directly when available; otherwise present manual findings and mark them as fallback reasoning
For code snippets referenced in results, use
```
hex-line read_file
```
with line ranges when available; otherwise use built-in
```
Read
```
Suggest follow-up queries based on results:

After

find_symbols

with a clean top match → suggest

inspect_symbol

with

workspace_qualified_name

After
```
find_symbols
```
with
```
partial ... truncated=1
```
→ suggest narrowing
```
path
```
or switching to
```
name + file
```
before any deeper graph tool
After
```
inspect_symbol
```
→ suggest
```
trace_paths
```
if refactoring

After

trace_paths

→ suggest

find_references

find_implementations

depending on symbol kind

After empty
```
trace_paths
```
from a broad or module-level selector → suggest
```
inspect_symbol
```
or
```
analyze_architecture
```
instead of assuming there are no dependencies

若有可用的MCP工具输出，直接展示；否则呈现手动查找结果并标记为 fallback 推理
对于结果中引用的代码片段，若有可用的
```
hex-line read_file
```
工具，使用行范围读取；否则使用内置的
```
Read
```
工具
根据结果提供后续查询建议：

若
```
find_symbols
```
返回清晰的顶级匹配结果 → 建议使用
```
workspace_qualified_name
```
调用
```
inspect_symbol
```
若
```
find_symbols
```
返回
```
partial ... truncated=1
```
→ 建议先缩小
```
path
```
范围或切换为
```
name + file
```
，再进行更深层的图谱工具查询
若完成
```
inspect_symbol
```
查询 → 若涉及重构，建议调用
```
trace_paths
```
若完成
```
trace_paths
```
查询 → 根据符号类型，建议调用
```
find_references
```
或
```
find_implementations
```
若从宽泛或模块级选择器执行
```
trace_paths
```
返回空结果 → 建议调用
```
inspect_symbol
```
或
```
analyze_architecture
```
，而非假设不存在依赖关系

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	支持工作区感知的定义、调用、导入、未使用导出；若安装了提供者，可启用可选的精确覆盖
C#	.cs	支持工作区感知的定义、调用、项目/命名空间归属、类型关系；若安装了提供者，可启用可选的精确覆盖
PHP	.php	支持工作区感知的定义、调用、PSR-4命名空间导入、未使用导出；若安装了提供者，可启用可选的精确覆盖

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 or manual fallback map built
Query results shown to user
Follow-up suggestions provided
Fallback path stated when MCP was unavailable

Version: 0.1.0 Last Updated: 2026-03-20

已完成项目索引或构建手动 fallback 映射
已向用户展示查询结果
已提供后续查询建议
当MCP不可用时，已说明 fallback 路径

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