ln-020-codegraph

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

代码知识图谱

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

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

输入

输入	必需	来源	描述
project_path	是	args 或 CWD	要索引的项目根目录
command	否	args	具体操作：index、search、symbol、paths、refs、arch

适用场景

• 开始处理不熟悉的代码库 → index + architecture
• 重构函数或类之前 → find_symbols + inspect_symbol + trace_paths
• 理解调用流程 → trace_paths
• 快速查找符号 → search

MCP 可用性

必须阅读： 加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md

当任务依赖于符号身份、引用、实现、架构、数据流或编辑影响时，优先使用 hex-graph。如果可用，针对性地读取本地代码时优先使用 hex-line。如果 MCP 不可用、不受支持或尚未建立索引，请继续使用内置的 Glob/Grep/Read/Bash，依据人工收集的证据作答，并明确说明置信度有所降低，而不要因此阻断此技能。

工作流

阶段 1：索引

检查图谱是否存在（项目根目录中的 .hex-skills/codegraph/index.db）。

如果不存在：

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

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

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

幂等——自动跳过未更改的文件。

如果 hex-graph 不可用： 使用 Glob 和有针对性的 Grep/Read 手动构建项目映射，然后继续执行最接近的查询工作流，无需建立索引。

阶段 2：查询

根据用户意图进行路由：

用户说	工具	参数
“显示依赖项” / “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）。

阶段 3：呈现结果

1. 有 MCP 工具输出时直接展示；否则呈现手动查找结果，并标明这是回退推理
2. 对结果中引用的代码片段，如果可用，请使用 hex-line read_file 指定行范围；否则使用内置的 Read
3. 根据结果建议后续查询：

• 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，而不是断定没有依赖项

支持的语言

语言	扩展名	覆盖范围
JavaScript	.js, .mjs, .cjs, .jsx	语义覆盖最全面
TypeScript / TSX	.ts, .tsx	语义覆盖最全面
Python	.py	支持工作区感知的定义、调用、导入、未使用的导出；安装提供程序后可选用精准覆盖层
C#	.cs	支持工作区感知的定义、调用、项目/命名空间归属、类型关系；安装提供程序后可选用精准覆盖层
PHP	.php	支持工作区感知的定义、调用、PSR-4 命名空间导入、未使用的导出；安装提供程序后可选用精准覆盖层

MCP 服务设置

添加到 .mcp.json：

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

完成标准

• 已为项目建立索引，或已构建手动回退映射
• 已向用户展示查询结果
• 已提供后续建议
• MCP 不可用时已说明回退路径

---

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