| 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 真相。
