用途
ln-020-codegraph 是一个独立的代码知识图谱工具，用于将代码库索引为分层图谱（tree-sitter AST → SQLite），并通过 MCP 工具提供依赖分析、路径追踪、引用查找、实现查找和架构概览。它适合在以下场景使用：开始接触不熟悉的代码库时进行索引和架构分析；重构函数或类之前查找符号、检查符号并追踪路径；理解调用流程；快速查找某个符号。
主要能力
该工具通过 MCP 提供多种查询能力，按用户意图路由到不同工具：
- 依赖分析 / “什么使用了 X”：使用 trace_paths，参数 path_kind 为 mixed，direction 为 reverse。
- 调用关系 / “谁调用了 X”或“X 调用了什么”：使用 trace_paths，path_kind 为 calls，direction 为 reverse 或 forward。
- 符号上下文 / “告诉我关于 X 的信息”：使用 inspect_symbol。
- 项目结构 / 架构：使用 analyze_architecture，可指定 scope。
- 查找符号：使用 find_symbols。
- 查找代码模式（如 app.get(...)、router.use(...)、server.registerTool(...)）：使用 grep_search。
- 查找重复代码 / 热点 / 未使用导出：使用 audit_workspace。
- 循环依赖 / 模块耦合：使用 analyze_architecture，verbosity 为 full。
- 实现 / 覆盖：使用 find_implementations。
- 数据流 / 传播：使用 trace_dataflow，需要 source.anchor 和可选的 sink.anchor。
- 审查 diff / worktree：使用 analyze_changes，指定 base_ref。
- 检查编辑某范围的影响：使用 analyze_edit_region，指定 file、line_start、line_end。
语义工具接受恰好一个选择器：symbol_id、workspace_qualified_name、qualified_name 或 name + file。推荐流程是先用 find_symbols 缩小路径，再将返回的 workspace_qualified_name 用于 inspect_symbol、trace_paths、find_references 或 find_implementations。find_symbols 仅用于基于名称的发现；对于代码片段或未解析的成员调用模式，应使用 grep_search。若 find_symbols 返回部分结果（truncated=1）或总数多于返回行数，应先用 path 细化，再用 name + file 或 workspace_qualified_name，而不是扩大图谱查询。path 可以是已索引的项目根目录或其中的任何文件/子目录。trace_dataflow 的锚点类型包括 param（函数参数）、local（局部变量）、return（函数返回）、property（配合 access_path 用于有界属性流）。inspect_symbol、trace_paths 和 find_references 支持 min_confidence（low、inferred、exact、precise）以抑制较弱的仅解析器事实。
使用方式
工作流分为三个阶段：
-
索引：检查项目根目录下是否存在 .hex-skills/codegraph/index.db。若不存在，调用 index_project({ path: "{project_path}" })；若存在，也可按需重新索引，该操作是幂等的，会自动跳过未更改的文件。若 hex-graph 不可用，则用 Glob 和有针对性的 Grep/Read 构建手动项目地图，然后继续到最接近的查询工作流，不进行索引。
-
查询：根据用户意图路由到上述工具。
-
呈现结果：直接显示 MCP 工具输出；否则呈现手动发现并标记为回退推理。对于结果中引用的代码片段，若可用则使用 hex-line 的 read_file 并指定行范围，否则使用内置 Read。根据结果建议后续查询，例如：find_symbols 得到干净的首个匹配后建议用 workspace_qualified_name 调用 inspect_symbol；find_symbols 返回部分结果时建议先缩小路径或改用 name + file；inspect_symbol 后若涉及重构建议 trace_paths；trace_paths 后根据符号类型建议 find_references 或 find_implementations；从宽泛或模块级选择器得到空 trace_paths 时，建议改用 inspect_symbol 或 analyze_architecture，而不是假定没有依赖。
MCP 服务器设置：在 .mcp.json 中添加：
{ "mcpServers": { "hex-graph": { "command": "node", "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"] } } }
适用场景
- 开始接触不熟悉的代码库：索引 + 架构分析。
- 重构函数/类之前：find_symbols + inspect_symbol + trace_paths。
- 理解调用流程：trace_paths。
- 快速查找符号：search。
限制
- 支持的语言及覆盖：JavaScript（.js、.mjs、.cjs、.jsx）语义覆盖最强；TypeScript/TSX（.ts、.tsx）语义覆盖最强；Python（.py）支持工作区感知的定义、调用、导入、未使用导出，安装 provider 时可选的精确覆盖；C#（.cs）支持工作区感知的定义、调用、项目/命名空间归属、类型关系，安装 provider 时可选的精确覆盖；PHP（.php）支持工作区感知的定义、调用、PSR-4 命名空间导入、未使用导出，安装 provider 时可选的精确覆盖。
- 若 MCP 不可用、不支持或未索引，则继续使用内置 Glob/Grep/Read/Bash，以手动证据回答，并明确标注置信度下降，而不是阻塞技能。
- find_symbols 仅基于名称发现，不适用于代码片段或未解析的成员调用模式。
- 语义工具需要恰好一个选择器。
- 数据流追踪需要 source.anchor，sink.anchor 可选。
版本：0.1.0；最后更新：2026-03-20。