research-wiki

研究 Wiki：持久化研究知识库

子命令：$ARGUMENTS

概述

研究 Wiki 是一个持久化的项目级知识库，会在整个 ARIS 研究生命周期中不断积累结构化知识。与用过即忘的一次性文献综述不同，Wiki 会不断复利增长——每读一篇论文、测试一个想法、开展一次实验、收到一份评审，都会让 Wiki 变得更智能。

灵感来自 Karpathy 的 LLM Wiki 模式：只需编纂一次知识，持续更新，而非每次查询都重新推导。

核心概念

四种实体类型

实体	目录	节点 ID 格式	代表内容
论文	papers/	paper:<slug>	已发表或预印本研究论文
想法	ideas/	idea:<id>	研究想法（已提出、测试或失败）
实验	experiments/	exp:<id>	已开展并有结果的具体实验
主张	claims/	claim:<id>	具有如实 PROOF 状态的定理／标题——通过 /proof-checker 创建（见 Hook 4）

带类型的关系（graph/edges.jsonl）

边类型	起点 → 终点	含义
extends	论文 → 论文	基于先前工作构建
contradicts	论文 → 论文	对结果／主张持不同意见
addresses_gap	论文|想法 → gap	针对已知领域空白
inspired_by	想法 → 论文	想法源自这篇论文
tested_by	想法|主张 → exp	在此实验中进行了测试
supports	exp → 主张|想法	实验证实了主张
invalidates	exp → 主张|想法	实验推翻了主张
supersedes	论文 → 论文	较新的工作取代较早的工作

关系仅存储在 graph/edges.jsonl 中。每个页面上的 ## Connections 部分均由关系图自动生成——切勿手动编辑。

记录卫生（防止自我污染）

在持久化想法／主张／实验记录之前，先筛查可能固化为自引错误结论的操作性噪声（见 shared-references/capture-antipatterns.md）。 按规范链解析辅助工具（integration-contract §2）： .aris/tools/capture_filter.py → tools/capture_filter.py → $ARIS_REPO/tools/capture_filter.py（无法解析时警告并跳过）。对记录文本运行 python3 <capture_filter> -；如果标记为 env-failure / transient-error / negative-tool-claim，则不要将其存储为持久节点—— 将其改写为修复方法／缺失配置／变通方案，或直接丢弃。切勿存储 “codex/gemini/评审者无法执行 X”——这类内容会载入每个后续 会话，并在实际原因消失很久之后仍被用来指责 Agent。（Wiki 中的 “失败想法 → 防止重复记忆”是正确的反向做法：这是类别层面的研究 发现，而非操作性噪声。）

Wiki 目录结构

research-wiki/
  index.md               # categorical index (auto-generated)
  log.md                 # append-only timeline
  gap_map.md             # field gaps with stable IDs (G1, G2, ...)
  query_pack.md          # compressed summary for /idea-creator (auto-generated, max 8000 chars)
  papers/
    <slug>.md            # one page per paper
  ideas/
    <idea_id>.md         # one page per idea
  experiments/
    <exp_id>.md          # one page per experiment
  claims/
    <claim_id>.md        # one page per testable claim
  graph/
    edges.jsonl          # materialized current relationship graph

子命令

辅助工具解析（在运行下方任一子命令前执行）

除纯目录初始化外，所有 Wiki 操作都通过单一规范辅助工具 tools/research_wiki.py 执行。操作 Wiki 的技能 必须按下方链解析 $WIKI_SCRIPT——切勿硬编码 python3 tools/research_wiki.py …。如果项目中没有 tools/ 目录（install_aris.sh 安装后的 默认状态），硬编码会悄然失败；这正是导致真实用户的 research-wiki/ 空了一周的故障模式。

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
  ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
WIKI_SCRIPT=".aris/tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
[ -f "$WIKI_SCRIPT" ] || {
  echo "ERROR: research_wiki.py not found at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
  echo "       Fix one of:" >&2
  echo "         1. rerun 'bash tools/install_aris.sh' from the ARIS repo (creates .aris/tools symlink, refreshes ~/.aris/repo)" >&2
  echo "         2. rerun 'bash tools/smart_update.sh' (refreshes ~/.aris/repo)" >&2
  echo "         3. export ARIS_REPO=<path-to-ARIS-repo>" >&2
  echo "         4. cp <ARIS-repo>/tools/research_wiki.py tools/" >&2
  exit 1
}

/research-wiki 本身就是 Wiki 工具——如果缺少辅助工具，该技能会直接失败。作为副作用更新 Wiki 的调用技能（/idea-creator、/result-to-claim、/research-lit、/arxiv、 /alphaxiv、/deepxiv、/semantic-scholar、/exa-search、 /firecrawl-search）使用相同的解析链，但会警告并跳过，而非直接失败——必须仍向用户交付其主要输出（想法列表、主张判定、论文摘要）。

/research-wiki init

为当前项目初始化 wiki。根据上述规则解析 $WIKI_SCRIPT 后：

python3 "$WIKI_SCRIPT" init research-wiki/

此辅助程序会创建 research-wiki/{papers,ideas,experiments,claims,graph}/ 以及 index.md、log.md、gap_map.md、query_pack.md 和 graph/edges.jsonl，随后将 "Wiki initialized" 追加到 log.md。

（此技能的早期版本描述了一种仅生成散文的初始化方式，遗漏了 query_pack.md——这与辅助程序的行为不一致，导致 /idea-creator 的 Phase 0 查询包检查会转而调用 rebuild_query_pack；在旧的硬编码路径下，该调用会静默失败。将初始化工作委托给辅助程序，是确保 wiki 架构只有一个真实来源的做法。）

/research-wiki ingest "<paper title>" — arxiv: <id>

将论文添加到 wiki。此子命令只是对 python3 "$WIKI_SCRIPT" ingest_paper … 的薄封装；在 ARIS 中，这是论文导入的唯一实现（依据 shared-references/integration-contract.md ——一个辅助程序，不存在副本）。此辅助程序会完成以下所有操作：

1. 获取元数据——指定 --arxiv-id 时，查询 arXiv Atom API
2. 生成 slug——<first_author_last_name><year>_<keyword>
3. 检查重复项——除非指定 --update-on-exist，否则跳过已有页面
4. 创建页面——根据下方架构创建 papers/<slug>.md
5. 重建 index.md 和 query_pack.md
6. 追加 log.md

旧手动流程中的边关系提取（第 5/8 步）不属于 ingest_paper；请针对识别出的每种关系，后续使用 add_edge 完成：

# arXiv-known paper
python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
    --arxiv-id 2501.12345 --thesis "One-line claim from abstract."

# Venue paper with no arXiv mirror
python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
    --title "Attention Is All You Need" \
    --authors "Ashish Vaswani, Noam Shazeer, …" --year 2017 --venue "NeurIPS"

# Manual edge after ingest
python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
    --from "paper:vaswani2017_attention_all_you" \
    --to "paper:chen2025_factorized_gap" \
    --type "extends" --evidence "Section 3.2: adapts the encoder block …"

其他技能（/research-lit、/arxiv、/alphaxiv、/deepxiv、 /semantic-scholar、/exa-search、/firecrawl-search）会在各自的最后一步直接调用同一个辅助程序——它们不会通过 /research-wiki ingest 子命令转交，因此无需经过 LLM 往返。

/research-wiki sync — arxiv-ids <id1>,<id2>,...

批量回填：导入一个或多个先前已阅读但尚未导入的 arXiv ID （例如，research-wiki/ 是在阅读完成后才设置的，或者某个钩子未触发）。

# Explicit list
python3 "$WIKI_SCRIPT" sync research-wiki/ \
    --arxiv-ids 2310.06770,1706.03762

# From a file (one id per line, # comments ok)
python3 "$WIKI_SCRIPT" sync research-wiki/ --from-file ids.txt

系统会逐个 ID 检查重复项；已导入的论文会被静默跳过。 这是建议使用的手动修复步骤（参见集成契约 §5 回填）。sync 不会扫描会话追踪记录——调用方需明确指定 ID。

论文页面架构（与 ingest_paper 完全一致——请勿 手写其他字段；lint 会标记不一致之处）：

---
type: paper
node_id: paper:<slug>
title: "<full title>"
authors: ["First A. Author", "Second B. Author"]
year: 2025
venue: "arXiv"
external_ids:
  arxiv: "2501.12345"
  doi: null
  s2: null
tags: ["tag1", "tag2"]
added: 2026-04-07T10:12:00Z
---

# <full title>

## One-line thesis

[Single sentence capturing the paper's core contribution]

## Problem / Gap

## Method

## Key Results

## Assumptions

## Limitations / Failure Modes

## Reusable Ingredients

[Techniques, datasets, or insights that could be repurposed]

## Open Questions

## Claims

[Reference claim pages: claim:C1, claim:C2, etc.]

## Connections

[AUTO-GENERATED from graph/edges.jsonl — do not edit manually]

## Relevance to This Project

[Why this paper matters for our specific research direction]

此外，如果论文是通过 --arxiv-id 导入，且 arXiv API 返回了摘要，辅助程序会在 Relevance to This Project 之后追加一个 ## Abstract (original) 章节，其中以引用块形式包含原始摘要文本。手动导入（未指定 --arxiv-id）不会包含此章节。

/research-wiki query "<topic>"

生成 query_pack.md——一份经过压缩、适合放入上下文窗口的摘要：

固定预算（最多 8000 个字符 / 约 2000 个 token）：

部分	预算	内容
项目方向	完整章节	按 ## 标题从 RESEARCH_BRIEF.md 中结构化提取（Problem / Constraints / Direction / Background / Non-Goals / Domain Knowledge / Existing Results），按优先级排序。每个字段没有字符数上限——唯一的安全保障是 8000 字符的组装循环。如果简报没有使用已知标题，则回退为截取前 600 个字符。
前 5 个缺口	1200 个字符	来自 gap_map.md，按以下标准排序：未解决 + 关联的想法 + 失败的实验
论文集群	1600 个字符	按标签重叠度划分为 3-5 个集群，每个集群用 2-3 句话描述
失败的想法	1400 个字符	始终包含——最能避免重复
重点论文	1800 个字符	8-12 篇论文，按以下标准排序：关联的缺口、关联的想法、中心性、相关性标记
活跃链条	900 个字符	局限 → 机会的关系链
未解决的问题	500 个字符	Wiki 中尚未解决的问题

删减优先级（超出预算时）：排名靠后的论文 > 集群详情 > 链条详情。切勿优先删减失败的想法或重点缺口。

**关键规则：**只读取短字段（frontmatter、单行论点、缺口摘要、失败记录）。不要每次都总结完整的页面正文。

/research-wiki update <node_id> — <field>: <value>

更新特定实体：

/research-wiki update paper:chen2025 — relevance: core
/research-wiki update idea:001 — outcome: negative
/research-wiki update claim:C1 — status: refuted

每次更新后：重建 query_pack.md，更新 log.md。

/research-wiki lint

检查 Wiki 健康状况：

1. 孤立页面——没有任何边的实体
2. 过时声明——status: drafted 或 status: unproven 且超过 14 天的声明
3. 矛盾——同时具有 supports 和 invalidates 边的声明
4. 缺少关联——具有 2 个或更多相同标签但没有明确关系的论文
5. 无效想法——从未经过测试的 stage: proposed 想法
6. 内容稀疏的页面——有 3 个或更多空章节的页面

输出一份 LINT_REPORT.md，其中包含建议的修复措施。

/research-wiki stats

快速概览：

📚 Research Wiki Stats
Papers: 28 (12 core, 10 related, 6 peripheral)
Ideas: 7 (2 active, 3 failed, 1 partial, 1 succeeded)
Experiments: 12
Claims: 15 (8 verified, 4 unproven, 2 refuted, 1 sound-modulo-imports)
Edges: 64
Gaps: 8 (3 unresolved)
Last updated: 2026-04-07T10:12:00Z

与现有工作流集成

所有论文阅读技能都遵循相同的集成约定（参见 shared-references/integration-contract.md）：

• 单一谓词 — [ -d research-wiki/ ]
• 单一规范助手 — 通过本 SKILL 顶部的调用链解析 $WIKI_SCRIPT 后，执行 python3 "$WIKI_SCRIPT" ingest_paper …
• 具体产物 — papers/<slug>.md + log.md 条目
• 回填 — sync --arxiv-ids …
• 诊断 — verify_wiki_coverage.sh（Policy E；根据 integration-contract §2 解析）

Hook 1：/research-lit 找到论文后

# At end of research-lit, after synthesis:
if research-wiki/ exists AND $WIKI_SCRIPT resolved (chain at top of this SKILL):
    for paper in top_relevant_papers (limit 8-12):
        python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
            --arxiv-id <id> [--thesis "..."] [--tags "..."]
        for each explicit relation to existing wiki paper:
            python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
                --from "paper:<slug>" --to "<target>" \
                --type <extends|contradicts|addresses_gap|...> \
                --evidence "..."
    log "research-lit ingested N papers"
elif research-wiki/ exists but $WIKI_SCRIPT did not resolve:
    warn "wiki update skipped — research_wiki.py unreachable; rerun install_aris.sh"

每项论文阅读技能都会包含自己的步骤“更新 Research Wiki（如果已启用）”，对其处理的每篇论文调用一次同一个助手。不会重复业务逻辑——只有遍历该技能特定结果集的循环不同。

Hook 2：/idea-creator 读取并写入 Wiki

构思前：

if research-wiki/query_pack.md exists (and < 7 days old):
    prepend query_pack to landscape context
    treat failed ideas as banlist
    treat top gaps as search seeds
    still run fresh literature search for last 3-6 months

构思后（关键——否则 ideas/ 会一直为空；每次生成都会运行，包括使用更新后的约束重新运行）：页面写入是一个确定性的助手命令，而不是模型可以跳过的自由发挥步骤：

for idea in all_generated_ideas (recommended + killed):
    python3 "$WIKI_SCRIPT" upsert_idea research-wiki/ \
      --slug <stable-id> --title <title> --stage <proposed|archived> --outcome pending \
      --thesis <...> --risks <...> --based-on <paper:slug,...> --target-gaps <G2,...>
    # one call: writes ideas/<slug>.md, wires inspired_by/addresses_gap edges,
    # rebuilds index + query_pack, logs. Default skip-on-exist (won't clobber an
    # existing idea enriched by /result-to-claim). `outcome` ∈ {unknown, pending,
    # negative, mixed, positive} — the experiment verdict is set later by
    # /result-to-claim, never guessed at ideation.
log "idea-creator wrote N ideas to wiki"

Hook 3：/result-to-claim 给出判定后

# Create/refresh the experiment node FIRST via the deterministic helper (verdict owner
# → --update-on-exist). This is the experiment BIRTH point. add_edge does NOT verify
# node existence, so GATE the supports/invalidates edges below on the node having been
# born (EXP_NODE_OK) — else they'd dangle off a missing exp node.
EXP_NODE_OK = (python3 "$WIKI_SCRIPT" add_experiment research-wiki/ --slug <exp_id> \
  --idea idea:<active_idea> --verdict <yes|partial|no> --confidence <high|medium|low> \
  --metrics <...> --reasoning <...> --provenance <run dir> --update-on-exist) succeeded
  # writes page + idea--tested_by-->exp edge + rebuilds index/query_pack

# Record empirical support as EDGES ONLY, and ONLY if EXP_NODE_OK — never overwrite the
# claim's `status`. A claim's `status` is the PROOF axis (verified / sound-modulo-imports
# / refuted / unproven / drafted / retracted), owned by /proof-checker (the claim birth
# point). Experiment support is a SEPARATE axis carried entirely by supports/invalidates
# edges; writing "supported"/"invalidated" into status is rejected by the validator.
if EXP_NODE_OK:
    for claim_id in resolved_claims:
        if verdict == "yes":
            add_edge(exp_id, claim_id, "supports")
        elif verdict == "partial":
            add_edge(exp_id, claim_id, "supports")   # partial — qualify in --evidence
        else:
            add_edge(exp_id, claim_id, "invalidates")

# Update idea outcome
update_idea(active_idea_id, outcome=verdict)

# If failed, record WHY for future ideation
if verdict in ("no", "partial"):
    update_idea failure_notes with specific metrics and reasons

rebuild query_pack
log "result-to-claim: exp_id updated, verdict=..."

Hook 4：声明诞生——来自 /proof-checker（唯一的诞生入口）

Wiki 声明节点在这里诞生。 /proof-checker 的 Phase 5.5 会在写入 PROOF_AUDIT.json 后，为每个顶层定理／标题调用 add_claim，写入真实的 PROOF 轴 status，并添加指向审计跟踪的 provenance 指针。没有其他技能会创建声明节点：/result-to-claim（Hook 3）只会为已诞生的声明添加经验性的 supports／invalidates 边，绝不会编辑其 status。

# (run by /proof-checker; shown here for the wiki's record)
python3 "$WIKI_SCRIPT" add_claim research-wiki/ --slug thm-main-ub \
  --name "Main upper bound" --status verified \
  --provenance ".aris/traces/proof-checker/<run>/" --statement "..." --update-on-exist

声明的 status ∈ {drafted, unproven, sound-modulo-imports, verified, refuted, retracted} —— 仅表示证明轴。经验性支持是独立的轴，完全由边承载（Hook 3），绝不会写入 status。

重新构思触发条件

Wiki 有重大更新后，建议重新运行 /idea-creator：

• 自上次构思以来摄入 ≥5 篇新论文
• 自上次构思以来新增 ≥3 个失败／部分成功的想法
• 图中发现新的矛盾
• 发现现有想法都未涉及的新缺口

系统只会提出建议，不会自动触发。由用户决定。

关键规则

• 关系的唯一事实来源：graph/edges.jsonl。页面的 Connections 部分是自动生成的视图。
• 各处均使用规范节点 ID：paper:<slug>、idea:<id>、exp:<id>、claim:<id>、gap:<id>。绝不使用原始标题或不一致的简称。
• 失败的想法是最宝贵的记忆。 绝不要从 query_pack 中清除它们。
• query_pack.md 有严格的 8000 字符限制。 采用确定性生成，而非开放式摘要。
• 每次变更都要追加到 log.md。 日志就是审计跟踪。
• 评审者独立性同样适用。 跨模型评审技能读取 Wiki 时，只传递文件路径——不要为评审者总结 Wiki 内容。
• Wiki 使用 UTF-8。 所有 Wiki 文件都以 UTF-8 读写，确保 research-wiki/ 可在不同平台和协作者之间移植。由旧版 ARIS 在非 UTF-8 区域设置（例如中国 Windows 上的 cp936）中创建的 Wiki，必须转换为 UTF-8 一次——请先备份；该辅助工具会按名称报告存在问题的文件，而不会猜测。

致谢

灵感来自 Karpathy's LLM Wiki ——“一次性编译知识，保持内容更新，不要在每次查询时重新推导。”