wiki-enrich

Wiki Enrich：填充论文 TODO 部分（Karpathy LLM-Wiki）

目标：$ARGUMENTS

此技能的用途

ingest_paper（由 /research-lit、/arxiv、/alphaxiv、/deepxiv、/semantic-scholar、/exa-search、/firecrawl-search 调用）只会生成每篇论文的框架——frontmatter + 摘要 + 10 个可填写的 _TODO._ 占位部分（另有两个受保护的部分：## Connections 是图谱摘要；当给出 --arxiv-id 时，## Abstract (original) 会自动填充）。ARIS 中没有下游技能会填充这 10 个部分；因此，除非有人阅读每篇论文，否则知识库页面会一直留着 TODO。

这与 Karpathy 的 LLM 知识库设计（https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f）相矛盾：

“你永远（或很少）亲自编写知识库——LLM 会编写并维护其中的所有内容。……维护知识库中繁琐的部分不是阅读或思考，而是记录和整理。……LLM 不会厌倦，不会忘记更新交叉引用，一次就能处理 15 个文件。”

/wiki-enrich 是 ingest_paper 缺失的后半部分：它会读取每篇已生成框架的论文页面，通过逐级回退链从外部来源获取论文内容（完整的 5 个来源回退链见第 2.3 阶段），并将 10 个可填写的 TODO 部分改写为每部分 1～3 句话的摘要。

常量

• WIKI_ROOT = research-wiki/ — 相对于 git 根目录解析。如果不是目录，技能将硬性失败。
• TARGET_DEFAULT = missing — 未指定目标时，只补充至少有 1 个 TODO 部分的论文。其他目标：<slug>（一篇论文）或 all（每篇论文，即使已补充过也包括在内——通常与 --force 一起使用以覆盖）。
• SOURCE_DEFAULT = auto — 获取顺序：alphaxiv 概览 → alphaxiv 摘要 → deepxiv 简报 → arXiv API 摘要 → 页面摘要回退。采用第一个非空结果（完整链路见 Phase 2.3 表格）。使用 --source 可指定单一来源。
• MAX_PAPERS = 20 — 每次调用的硬性上限；大模型会处理许多文件，但 token 预算有限。使用 --max N 可覆盖。
• FORCE = false — 当值为 false（默认）时，跳过已有非 TODO 内容的部分。当值为 true 时，覆盖所有可填充部分，但绝不改动两个受保护部分：## Connections（根据 edges.jsonl 自动生成）和 ## Abstract (original)（不可变的 arXiv 获取源数据）。
• SECTIONS_TO_FILL — 10 个可填充部分 + 2 个受保护部分。ingest_paper（research_wiki.py:436-473）会无条件创建 11 个部分标题；只有当 arXiv 针对给定的 --arxiv-id 返回摘要时，才会创建第 12 个部分——## Abstract (original)（research_wiki.py:469-473）。其中 10 个部分带有 _TODO._（或 _TODO: fill in after reading._）标记，需要填充。其余 2 个——## Connections（以下枚举中的第 10 项）和 ## Abstract (original)（第 12 项，有条件创建）——从创建之初就受到保护：Connections 根据 graph/edges.jsonl 自动生成，Abstract (original) 是来自 arXiv API 的不可变源数据。此技能只会写入 10 个部分，不会写入另外 2 个。
  1. One-line thesis（标记：_TODO: fill in after reading._）
  2. Problem / Gap（标记：_TODO._）
  3. Method（标记：_TODO._）
  4. Key Results（标记：_TODO._）
  5. Assumptions（标记：_TODO._）
  6. Limitations / Failure Modes（标记：_TODO._）
  7. Reusable Ingredients（标记：_TODO._）
  8. Open Questions（标记：_TODO._）
  9. Claims（标记：_TODO._）——如果没有 claim: 边指向此论文，则填入 _No claims tracked yet._；否则列出这些边。
  10. Connections — 绝不编辑（根据 graph/edges.jsonl 自动生成）。
  11. Relevance to This Project（标记：_TODO._）——使用 RESEARCH_BRIEF.md、AGENTS.md（或旧版 CLAUDE.md）或 gap_map.md 获取项目背景。如果不存在项目背景，则保留 TODO 并报告。
  12. Abstract (original) — 保持原样（使用 --arxiv-id 时，ingest_paper 已填充此部分）。

💡 示例：

• /wiki-enrich — 补充所有至少有 1 个 TODO 部分的论文（最常见的用法）
• /wiki-enrich vllm — 按 slug 补充单篇论文
• /wiki-enrich all --force — 从头重写每篇论文（采用新风格时使用）
• /wiki-enrich --source alphaxiv --max 5 — 只使用 alphaxiv，只处理 5 篇论文
• /wiki-enrich missing --max 50 — 批量处理更多论文（注意 token 预算）

预检

解析 $WIKI_ROOT 和 $WIKI_SCRIPT（规范解析链——参见 shared-references/wiki-helper-resolution.md）：

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
[ -d research-wiki/ ] || { echo "ERROR: research-wiki/ not found. Run /research-wiki init first." >&2; exit 1; }

ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null)}"
WIKI_SCRIPT=""
[ -n "$ARIS_REPO" ] && [ -f "$ARIS_REPO/tools/research_wiki.py" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"
[ -z "$WIKI_SCRIPT" ] && [ -f tools/research_wiki.py ] && WIKI_SCRIPT="tools/research_wiki.py"
[ -z "$WIKI_SCRIPT" ] && [ -f ~/.codex/skills/research-wiki/research_wiki.py ] && WIKI_SCRIPT="$HOME/.codex/skills/research-wiki/research_wiki.py"
[ -n "$WIKI_SCRIPT" ] || { echo "ERROR: research_wiki.py not found." >&2; exit 1; }

如果任一项解析失败，则硬性失败——此技能会操作知识库状态，不得在未确认状态的情况下运行。

工作流

阶段 1：解析目标并发现候选项

解析 $ARGUMENTS 中的第一个位置参数（目标）和标志（--source、--force、--max）。

构建候选论文列表：

case "$TARGET" in
  all)
    PAPERS=( research-wiki/papers/*.md )
    ;;
  missing|"")
    # only papers with at least one TODO marker line
    PAPERS=( $(grep -lE "^_TODO(\._?|: fill in after reading\._?)$" research-wiki/papers/*.md 2>/dev/null) )
    ;;
  *)
    P="research-wiki/papers/${TARGET}.md"
    [ -f "$P" ] || { echo "ERROR: paper not found: $P" >&2; exit 1; }
    PAPERS=( "$P" )
    ;;
esac
echo "Candidate papers: ${#PAPERS[@]} (cap ${MAX_PAPERS})"
PAPERS=( "${PAPERS[@]:0:${MAX_PAPERS}}" )

如果候选列表为空，打印 "✓ Nothing to enrich." 并以状态码 0 退出。不要报错。

阶段 2：逐篇论文读取、获取并填充

一次处理一篇论文。针对 $PAPERS 中的每个 $PAPER： 步骤 2.1 — 阅读页面和项目背景。 使用 Read 工具读取完整论文文件。从 YAML frontmatter 中提取：

• node_id（例如 paper:vllm）——slug = paper: 后面的部分
• external_ids.arxiv 中的 arxiv——若不存在，则为空字符串
• title
• 现有的 ## Abstract (original) 引用块（若存在）——备用内容来源

此外，在本批次的第一篇论文中（其余论文沿用缓存），读取 Claims 和 Relevance to This Project 部分所需的项目背景文件：

• research-wiki/graph/edges.jsonl — 查找指向当前论文 node_id 的 claim: 边
• RESEARCH_BRIEF.md（项目根目录）——若存在，则作为项目目标的来源
• AGENTS.md（项目根目录，Codex CLI 为主要文件）或旧版 CLAUDE.md——若存在，则作为项目背景的备用来源
• research-wiki/gap_map.md——若非空，则作为差距分析的来源

如果这些项目背景文件均不存在，Relevance to This Project 部分将填入字面文本 "context not yet set"（见步骤 2.4 表格）。

步骤 2.2 — 确定哪些部分为 TODO。

根据标记匹配各部分标题：

• 标题后紧跟 _TODO._ → 填写
• 标题后紧跟 _TODO: fill in after reading._ → 填写（One-line thesis）
• 标题后为任何其他内容 → 跳过（除非使用 --force）
• ## Connections → 始终跳过（自动生成）
• ## Abstract (original) → 始终跳过（不可变源数据）

如果没有剩余的可填写部分，记录 "skip: <slug> (already enriched)" 并继续。

步骤 2.3 — 获取源内容。

按顺序尝试获取内容，直到某个来源返回可用内容（超过 200 个字符）：

顺序	来源	方式
1	alphaxiv overview（默认 auto；使用 --source alphaxiv 可固定来源）	WebFetch https://www.alphaxiv.org/overview/<arxiv_id>.md — 面向 LLM 优化的摘要，通常最适合用于填写各部分
2	alphaxiv abs（alphaxiv 内的备用来源）	WebFetch https://www.alphaxiv.org/abs/<arxiv_id>.md
3	deepxiv brief（使用 --source deepxiv 可固定来源）	如果能解析出辅助程序，则运行 python3 "$DEEPXIV_FETCHER" paper-brief <arxiv_id>
4	arXiv API 摘要——实时获取（使用 --source arxiv 可固定来源）	curl http://export.arxiv.org/api/query?id_list=<arxiv_id> — 日志标签：arxiv-api-abstract
5	页面摘要——备用（最后手段）	复用此前 ingest_paper 运行时已添加到页面正文中的 ## Abstract (original) 引用块 — 日志标签：page-abstract-fallback
—	无 arxiv ID，且无页面摘要	跳过此论文，记录 "skip: <slug> (no arxiv id, no abstract)"，然后继续

尝试 alphaxiv 时：如果 WebFetch 返回 404、“Paper not found”或重定向到主页，则视为未找到并尝试下一个来源。

尝试 deepxiv 时：根据 shared-references/integration-contract.md 解析 $DEEPXIV_FETCHER。如果辅助程序或 deepxiv CLI 缺失，则静默尝试下一个来源。

将获取的内容保存为 $SOURCE_TEXT。记录成功的来源，以便写入日志条目。

步骤 2.4 — 生成各部分的内容。

你（执行 Agent）是负责具体工作的 LLM。根据以下内容：

• $SOURCE_TEXT（获取的概览、简报或摘要）
• $TITLE
• 可填写部分标题列表

按照以下规则编写每个 TODO 部分的正文：

部分	长度	风格	提取内容
一句话论点	1 句，≤25 个词	陈述句	用一句话概括论文的核心贡献——构建、证明或改进了什么
问题 / 缺口	1-2 句	陈述句	该领域面临什么问题，以及以往工作为何不足
方法	2-4 句	技术性，点明技术名称	核心机制——算法名称 + 关键思路 + 与基线方法的差异
关键结果	1-3 个项目符号，或 2-3 句	定量	摘要 / 概述中的关键数据（提升 X%、加速 Y 倍等）。单位保持原样。
假设	1-3 个项目符号	陈述句	论文默认成立的条件（工作负载类型、硬件、模型类别、分布形状）
局限性 / 失效模式	1-3 个项目符号	客观	论文明确承认的内容，或结构上缺失的内容（例如“没有多节点评估”“假设请求长度均匀”）
可复用要素	1-3 个项目符号	具体	可迁移到其他场景的技术 / 数据集 / 论文见解。对 /idea-creator 最有价值——请认真撰写。
未解问题	1-2 个项目符号	疑问句	论文尚未回答、但由此引出的问题
论断	1 行	固定格式	如果 graph/edges.jsonl 中没有 claim: 边引用本文，写入以下字面斜体行：_No claims tracked yet — populate via /proof-checker._。否则列出论断节点 ID。
与本项目的关联	1-2 句	联系项目背景	使用 RESEARCH_BRIEF.md / AGENTS.md（或旧版 CLAUDE.md）/ gap_map.md 来表述关联。如果没有项目背景，写入以下字面斜体行：_Project context not yet set — populate RESEARCH_BRIEF.md or gap_map.md to enable this section._ 并报告。

规则（忠实于 Karpathy）：

• 忠实于原文。 论文未提及的内容，不要臆造。宁可写 _Not stated in source._，也不要产生幻觉。
• 不写填充内容。 不要写“本文提出了一种……方法”。直接从名词开始。
• 技术术语保留英文。 vLLM、KV cache、prefill、decode、TTFT 等均保持原样。
• 尽可能使用定量数据。 如果摘要中有数字，就使用这些数字；不要改写成“显著”。
• 双语支持。 如果项目的 AGENTS.md 声明了语言偏好（language: zh 或 language: bilingual），请遵循。否则默认使用英文（或遵循 shared-references/output-language.md）。

步骤 2.5 — 编辑文件。

对每个可填写部分，使用 Edit 工具将 TODO 标记替换为生成的正文。匹配准确的章节标题 + 标记组合，确保编辑目标唯一，例如：

## Problem / Gap
_TODO._

→

## Problem / Gap
<generated body>

切勿修改 YAML frontmatter、## Connections 或 ## Abstract (original)。

步骤 2.6 — 追加日志条目。

python3 "$WIKI_SCRIPT" log research-wiki/ "wiki-enrich: enriched paper:<slug> from <source> (filled N/M sections)"

记录内容来源（alphaxiv-overview、alphaxiv-abs、deepxiv-brief、arxiv-api-abstract 或 page-abstract-fallback），确保审计记录如实反映来源。

阶段 3：最终报告

处理完所有候选项后，打印：

✓ wiki-enrich complete

Processed:  N
Enriched:   X (sections filled: total)
Skipped:    Y  (reasons: already enriched / no arxiv id / fetch failed)
Failed:     Z  (with paper + reason)

Source breakdown:
  alphaxiv-overview: A
  alphaxiv-abs:      B
  deepxiv-brief:     C
  arxiv-api-abstract:     D
  page-abstract-fallback: E

Re-ideation suggestion: <if ≥5 papers were enriched, recommend `/idea-creator "topic"` so the freshly-filled `Reusable Ingredients` and `Limitations` feed brainstorming. `query_pack.md` is already rebuilt below — the user does NOT need to call `/research-wiki query` manually.>

最后也要重建一次 query_pack.md（只调用一次 python3 "$WIKI_SCRIPT" rebuild_query_pack research-wiki/），这样 /idea-creator 下次运行时就能看到新正文。

输出协议

遵循共享协议：

• 不要添加 MANIFEST.md 条目。 此技能会直接编辑已有的脚手架页面，而不是生成新产物。审计记录保存在 research-wiki/log.md（步骤 2.6）中，并按论文记录来源。将 wiki-enrich 阶段添加到 shared-references/output-manifest.md 不在本 PR 的范围内。
• 输出语言协议 — 遵循项目的语言设置。

核心规则

• 默认保持幂等。 不带 --force 重新运行时，只处理仍标记为 TODO 的章节。可安全地通过 cron 调用。
• 绝不触碰 frontmatter、## Connections 或 ## Abstract (original)。 frontmatter 是元数据，Connections 由图谱生成，Abstract 是不可变的源数据。
• 缺少 wiki / 辅助工具时直接报错。 不要默默创建 research-wiki/ ——如果该目录缺失，说明用户的当前工作目录不正确，或尚未运行 /research-wiki init。
• 记录来源。 每条日志都记录实际填充正文的来源。若今后审计发现某篇论文的内容是 alphaxiv 幻觉出来的，就能查到该来源涉及的所有页面。
• 不要自动触发 /idea-creator。 此技能负责搭建基础；由用户决定何时继续头脑风暴。只在最终报告中建议重新构思。
• 优雅降级。 如果 WebFetch 遇到速率限制，则转到下一个来源。如果所有来源都没有结果，就跳过该论文并继续，不要中止整个批次。
• 忠实于 Karpathy 的原则高于内容完整性。 与其产生幻觉，不如将章节留为 _Not stated in source._。wiki 的价值就在于不说谎。

与其他技能组合使用

/research-lit "topic"               ← ingests papers as scaffolds (Step 6)
/wiki-enrich                        ← THIS — fills paper bodies (you are here)
/research-wiki lint                 ← health-check (orphans, contradictions, dead ideas)
/idea-creator "direction"           ← reads query_pack, ideates on top of enriched wiki
/research-wiki query "topic"        ← rebuild query_pack after big wiki changes

在全新运行 /research-pipeline 后，若 Stage 1 Phase 1 已完成但 Phase 2 尚未开始（这正是促使开发此技能的故障模式），恢复步骤如下：

/wiki-enrich              # fill the paper TODOs ingest_paper left behind
/idea-creator "..."        # now ideate with a wiki that actually has content