ln-022-researchgraph

路径： 文件路径相对于此技能目录。

研究图谱

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

通过 hex-research-mcp 为规范项目研究文件建立索引并进行查询：包括假设、目标、任务、来源、来源库条目、基准测试运行清单、证据链接、派生目标指标、沿袭关系、生成的研究地图和审计缺口。

必须阅读

必须阅读： 加载 references/researchgraph_mcp_usage.md

输入

输入	必填	来源	描述
project_path	是	参数或 CWD	包含研究图谱文件的项目根目录
command	否	参数	指定操作：audit、inspect H##、goal G##、runs、evidence、lineage、progress、proposed、canvas

适用场景

当项目包含以下任意内容时，使用此技能：

• docs/hypotheses/*.md
• docs/goals/*.md
• benchmark/runs/*/manifest.yaml

当用户询问研究状态、当前或待处理假设、目标准备情况、基准测试证据、来源质量、证据深度、提案准备情况、实现缺口、偏差、字段级变更或可视化／生成的研究地图时，使用此技能。

请勿将此技能用于代码符号归属、调用图、引用或编辑影响范围。对于语义代码问题，请使用 ln-021-codegraph 或宿主的 hex-graph 策略。

MCP 可用性

如果 hex-research 可用，请使用它。如果不可用，请通过 Glob/Grep/Read 手动读取拆分的研究文件，依据直接文件证据作答，并注明置信度有所降低。

将 STALE 视为可采取行动的图谱债务或项目元数据缺失，而非工具故障。将 verify_index 返回的 INVALID 视为诊断信息，除非写入／索引操作失败。

工作流

阶段 1：检测图谱布局

检查规范布局：

• docs/hypotheses/*.md
• docs/goals/*.md
• benchmark/runs/*/manifest.yaml

如果这些内容均不存在，请停止并报告项目尚未提供研究图谱。不要臆造假设或目标。

阶段 2：验证或建立索引

先以只读方式开始：

verify_index({ path: "{project_path}" })

仅在索引缺失、已过期、用户明确要求，或任务需要当前图谱状态时，才重建索引：

index_hypotheses({ path: "{project_path}" })

本地索引存储在目标项目下的 .hex-skills/researchgraph/ 中。

阶段 3：确定意图对应的操作

用户意图	工具
当前、待处理、已拒绝、混合、尚未开始的假设	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
当前差异中的已变更研究文件及字段级差异	analyze_progress
拟议后续假设的准备情况	analyze_proposed
JSON Canvas 导出	export_canvas
生成的 docs/research-map.md 导出	export_research_map

阶段 4：呈现结果

报告：

1. 工具状态（OK、STALE、INVALID、ERROR）
2. 关键假设／目标／运行及其 ID
3. 将可采取行动的图谱债务与工具故障分开说明
4. 如果图谱指向更具体的后续问题，提供后续工具调用

对于 export_canvas 和 export_research_map，请先运行 dry-run。只有在 dry-run 输出有用且用户要求生成文件时，才写入文件。将拆分文件视为规范来源；生成的 research-map.md 并非第二个手动维护的真实来源。

手动回退

MCP 不可用时：

1. 先读取 docs/goals/*.md 和 docs/hypotheses/*.md 的 frontmatter。
2. 仅在按 H/G ID 或状态缩小范围后，读取 benchmark/runs/*/manifest.yaml。
3. 优先使用确切 ID（H04、G1），而不是广泛扫描。
4. 声明谱系、拓扑和漂移发现均为手动近似结果。

完成定义

• 已检测图布局，或已报告其不存在
• 已验证索引，或在需要时已重建
• 已将用户意图路由至最小相关工具
• 已将 STALE / 图债务与 MCP/工具故障区分开
• MCP 不可用时，已说明手动回退的可信度
• 写入画布前先执行 dry-run

---

版本： 0.1.0 最后更新： 2026-05-08