ln-021-codegraph

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

代码知识图谱

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

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

输入

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

适用场景

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

MCP 可用性

工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 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}" }
“API 路由 / 响应契约影响”	api_impact	{ path: "{project_path}", route: "/api/users", limit: 10 }
“图谱健康状况 / 缺失的叠加层事实”	diagnose_graph	{ 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，不要据此断定不存在依赖
• api_impact 未返回路由或缺少覆盖层事实后 → 建议调用 diagnose_graph

支持的语言

语言	扩展名	覆盖范围
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