research-wiki

name	research-wiki
description	typed knowledge-graph 抽象层 (Wave B.3)。把分散在 evidence_graph / corpus_ledger / story_skeleton 的结构升级成 paper / idea / claim / experiment / mechanism / baseline 节点 + supports / contradicts / derives_from / cites / replicates / falsifies 边。通过 4 个 MCP tool 维护 artifacts/research_wiki.json，并用 export_to_evidence_graph 投影回 evidence_graph schema。

Research Wiki — typed knowledge graph 上层

NeXus 的研究产物原本散落在三处：

• artifacts/evidence_graph.json — claim 级证据卡
• artifacts/corpus_ledger.json — paper 级访问状态
• artifacts/story_skeleton.json — 论文骨架

这三者各自有 schema，但没有显式的关系层：claim 之间是否 supports / contradicts、idea 是否 derives_from 某 paper、experiment 是否 replicates 某 baseline，都只能从 prose 里隐式读出。

research-wiki 引入 typed knowledge graph 一层，把这些关系 first-class 起来：

节点类型	含义
paper	文献 entry（与 corpus_ledger 一一对应）
idea	hypothesis_board 上的候选 idea
claim	evidence_graph 的 claim（与 Claim.id 一一对应）
experiment	experiment_results 中的一次实验
mechanism	解释性机制 / story_skeleton 的子图
baseline	对照组 / 已发表对比方法

边类型	方向	语义
supports	A → B	A 支持 B 的论断
contradicts	A → B	A 与 B 冲突
derives_from	A → B	A 派生自 B（DAG：禁止环）
cites	A → B	A 引用 B
replicates	A → B	A 复现 B
falsifies	A → B	A 证伪 B

重要：research_wiki 是上层抽象，而不是 evidence-discipline 的替代。evidence_graph.json 的 schema 不变（那是 evidence-discipline rule 的 contract）。research-wiki 通过 export_to_evidence_graph 把 claim 子图投影回 evidence_graph。

When to Use

• 用户说**"建知识图谱"** / "做关系网络" / "connect ideas" / "看看哪些 claim 互相支持"
• 当 evidence-auditor 报告多个 claim 反复重复，需要去重 / 合并时
• idea-brainstorm 阶段，需要把候选 idea 与已有 paper / claim 关联起来
• multi-reviewer 阶段，构造 "claim → mechanism → experiment" 解释链
• 任何需要 typed traversal 的场景：给我看所有支持 X 的 claim / X 派生自哪些 paper

4 个 MCP Tool

由 pipeline-orchestrator 暴露：

research_wiki_upsert_node(project_dir, node_id, type, name, attributes?, relationships?)

创建或更新节点。type 一旦设定不可改——保证下游 projection 的稳定性。

research_wiki_upsert_node(
    project_dir=".",
    node_id="claim:c1",
    type="claim",
    name="LLMs improve with chain-of-thought",
    attributes={
        "claim_type": "result",
        "text": "Chain-of-thought prompting improves arithmetic accuracy by 27%.",
        "source_paper_id": "wei2022cot",
        "publishable": True,
        "verified": True,
    },
)

research_wiki_upsert_edge(project_dir, from_node_id, to_node_id, edge_type, evidence_refs?, attributes?, edge_id?)

创建或更新边。所有写操作都会重新跑全图不变量校验：

• 唯一 node / edge id
• 引用完整性（端点必须已存在）
• derives_from 子图为 DAG（会拒绝环）
• 拒绝自环

research_wiki_upsert_edge(
    project_dir=".",
    from_node_id="claim:c1",
    to_node_id="paper:wei2022cot",
    edge_type="derives_from",
    evidence_refs=["c1"],
)

research_wiki_query_neighbors(project_dir, node_id, edge_types?, direction?)

direction ∈ "outgoing" | "incoming" | "both"（默认 both）。

返回的每个 neighbor 形如：

{
  "neighbor_id": "paper:wei2022cot",
  "neighbor_type": "paper",
  "neighbor_name": "Chain-of-Thought Prompting Elicits Reasoning",
  "edge_id": "claim:c1--derives_from-->paper:wei2022cot",
  "edge_type": "derives_from",
  "direction": "outgoing",
  "evidence_refs": ["c1"]
}

节点不存在时返回 status="not_found"，附 available_node_ids_sample 前 10 个 id 便于 debug。

research_wiki_export_to_evidence_graph(project_dir, output_path?, write?)

把 type="claim" 的子图投影成 evidence_graph.json 形态。

• ✅ 只导出 claim 节点；idea / experiment / mechanism / baseline 默认不在 evidence_graph 出现，silently 跳过
• ✅ attributes["claim_type"] → Claim.type（缺省 observation）
• ✅ attributes["source_paper_id"] → Claim.source_paper_id；若缺省，回退到 claim --derives_from--> paper 边指向的 paper
• ✅ publishable / verified / confidence / access_state 等字段从 attributes 透传
• ⚠️ 有损投影：wiki 是 authoritative source；evidence_graph 是 publishable 投影
• ⚠️ 不修改 evidence_graph schema 本身

跳过原因会以结构化形式回传到 skipped：

{
  "claim_count": 12,
  "skipped_count": 2,
  "skipped": [
    {"node_id": "claim:x", "reason": "missing_source_paper_id"},
    {"node_id": "claim:y", "reason": "text_too_short", "text_len": 3}
  ]
}

与既有 artifact 的关系

research_wiki.json  (authoritative typed graph, Wave B.3)
        │
        ├── export_to_evidence_graph ──► evidence_graph.json   (publishable claims)
        │
        ├── paper 节点 ◄────────────── corpus_ledger.json       (access state)
        │
        └── mechanism / experiment ◄── story_skeleton.json     (narrative)

• evidence_graph.json 的 schema 由 evidence-discipline rule 锁死，research-wiki 不去碰。
• corpus_ledger 中每个 entry 都应当在 wiki 里有一个 type="paper" 节点（producer convention，非强制）。
• story_skeleton.weakness_preemption 可以表达成 mechanism → claim 的 contradicts 边。

不变量速查

检查	何时触发	失败行为
node.id 全图唯一	每次 save	ValueError 拒绝写入
edge 端点必须存在	每次 save	ValueError 拒绝写入
edge.id（合成或显式）全图唯一	每次 save	ValueError 拒绝写入
derives_from 子图为 DAG	每次 save	ValueError 拒绝写入并报路径
edge 不能自环	model_validator	ValueError 拒绝写入
node.type 不可变更	upsert_node 复写时	ValueError 拒绝写入
edge.edge_type 在 id 下不可变更	upsert_edge 复写时	ValueError 拒绝写入

输出文件

• artifacts/research_wiki.json — 主存储
• artifacts/evidence_graph.json — export_to_evidence_graph 的投影（同时也是 evidence-discipline 的契约文件）

不做的事

• ❌ clean-room 实现：仅依赖 NeXus 已有 schema, 不读任何外部 typed-KG 项目源码。
• ❌ 不修改 evidence_graph schema：那是 evidence-discipline 的 contract。
• ❌ 不自动改 SKILL.md：与 skill-self-improver 同样的"只提建议不动手"原则。
• ❌ 不替代 corpus_ledger / evidence_graph：wiki 是上层抽象，下层 artifact 仍是 publishable 真相。