用途
ln-022-researchgraph 是一个独立实用工具（Standalone Utility），归类于开发环境相关类别。它通过 hex-research MCP 对项目中的规范研究文件进行索引与查询，覆盖假设（hypotheses）、目标（goals）、任务、来源、来源库条目、基准运行清单（benchmark run manifests）、证据链接、派生目标指标、血缘关系、生成的研究地图以及审计缺口。
主要能力
该技能可处理以下研究图谱对象：假设、目标、任务、来源、来源库条目、基准运行清单、证据链接、派生目标指标、血缘、生成的研究地图、审计缺口。
根据用户意图，技能会路由到相应工具：
- 查找假设（live、pending、rejected、mixed、not-started）：find_hypotheses
- 检查单个假设 H##：inspect_hypothesis
- 检查目标 G## 或目标状态：inspect_goal
- 查找证据、来源、基准证明：find_evidence
- 查找定向或全面基准运行：find_runs
- 追踪父/子假设链：trace_lineage
- 分析图谱枢纽、断连节点、形状：analyze_topology
- 审计缺失目标、来源、任务缺口、漂移：audit_orphans
- 追踪目标树：trace_goal_tree
- 目标就绪度、派生指标与指标覆盖：inspect_goal、audit_goal_alignment
- 来源质量或证据深度：inspect_hypothesis、find_evidence、analyze_proposed
- 当前 diff 中变更的研究文件与字段级增量：analyze_progress
- 拟议下一步假设的就绪度：analyze_proposed
- JSON Canvas 导出：export_canvas
- 生成 docs/research-map.md 导出：export_research_map
使用方式
输入
- project_path（必填）：来源为 args 或 CWD，指包含研究图谱文件的项目根目录。
- command（可选）：来源为 args，指定具体动作，如 audit、inspect H##、goal G##、runs、evidence、lineage、progress、proposed、canvas。
强制阅读
必须加载 references/researchgraph_mcp_usage.md。
工作流程
第一阶段：检测图谱布局。检查规范布局是否存在：docs/hypotheses/.md、docs/goals/.md、benchmark/runs/*/manifest.yaml。若均不存在，则停止并报告项目尚未暴露研究图谱，不得虚构假设或目标。
第二阶段：校验或索引。先以只读方式运行 verify_index({ path: "{project_path}" })。仅当索引缺失、过期、被明确要求，或任务需要当前图谱状态时，才重建：index_hypotheses({ path: "{project_path}" })。本地索引存放于目标项目的 .hex-skills/researchgraph/ 下。
第三阶段：路由意图。按上表将用户意图映射到最小相关工具。
第四阶段：呈现结果。报告工具状态（OK、STALE、INVALID、ERROR）；列出带 ID 的关键假设/目标/运行；将可操作的图谱债务与工具故障分开；当图谱指向更窄的下一问题时给出后续工具调用建议。对于 export_canvas 和 export_research_map，先运行 dry-run，仅在 dry-run 输出有用且用户请求文件后才写入。拆分文件为规范来源，生成的 research-map.md 不是第二份手动事实来源。
MCP 可用性
优先使用 hex-research。若不可用，则用 Glob/Grep/Read 手动读取拆分的研究文件，基于直接文件证据作答，并将置信度标记为 degraded。STALE 应视为可操作的图谱债务或缺失项目元数据，而非工具故障。verify_index 返回的 INVALID 应视为诊断信息，除非写入/索引操作失败。
手动回退
当 MCP 不可用时：先读取 docs/goals/.md 与 docs/hypotheses/.md 的 frontmatter；仅在按 H/G ID 或状态缩小范围后，再读取 benchmark/runs/*/manifest.yaml；优先使用精确 ID（如 H04、G1）而非宽泛扫描；说明血缘、拓扑与漂移发现为手动近似结果。
适用场景
当项目存在以下任一情况时使用：docs/hypotheses/.md、docs/goals/.md、benchmark/runs/*/manifest.yaml。当用户询问研究状态、活跃或待定假设、目标就绪度、基准证据、来源质量、证据深度、提案就绪度、实现缺口、漂移、字段级变更，或可视化/生成的研究地图时使用。
限制
不适用于代码符号归属、调用图、引用或编辑影响范围。此类语义代码问题应使用 ln-021-codegraph 或宿主 hex-graph 策略。若项目未暴露研究图谱，不得虚构假设或目标。MCP 不可用时需标记置信度为 degraded，血缘、拓扑与漂移发现为手动近似。
完成定义
- 检测到图谱布局或报告其缺失
- 在需要时校验或重建索引
- 将用户意图路由到最小相关工具
- 将 STALE / 图谱债务与 MCP/工具故障分开
- MCP 不可用时说明手动回退置信度
- Canvas 写入前使用 dry-run
版本：0.1.0；最后更新：2026-05-08。