index-references

目的

每个 references/<project>/ 下的工作 (论文 PDF + 从 GitHub clone 的代码) 都生成一份固定结构的 NOTES.md 摘要,使未来 Claude 会话只需读摘要即可定位,避免每次 grep 几十万行代码 / 几百页论文。同时维护根 CLAUDE.md 中的"references 读取约定"块,把摘要的存在和读法显式写进 project memory。

用户给 <name> 时若 references/<name>/ 还不存在, skill 负责自动搜出官方 repo 并 clone, 再下载论文 PDF 放进同目录 — 用户不需要手动 clone / 下载。

边界: NOTES.md 管实现, LEDGER.md 管论文

项目里若存在 references/LEDGER.md (由 research-lit-survey 维护), 它是论文级的唯一真相源, NOTES.md 不得与之竞争。两者回答不同的问题:

操作规则:

• 索引前先看 references/LEDGER.md 是否已有该工作的行。 有 → 把 ledger 的 key 写进 NOTES.md 顶部, 并回填该行的 repo path 列为 references/<name>/; NOTES 里不再重复 tier / 新颖性 / 领域地位这类论文级判断。
• 没有 LEDGER.md (项目没跑过 survey) → NOTES 照常写, 但它只是实现索引: 其中任何论文级内容都标 <unverified — no survey>, 不得用于对外主张或 baseline 决策。 真要拿它支撑结论, 先跑 research-lit-survey。
• 复现达标线 (论文报告的绝对值) 属于 NOTES 的正当内容 —— 复现就是拿它对表。但它只在这个角色里有效: 要把这些数字用于跨方法比较 / 调研结论 / 论文, 必须走 LEDGER + 论文全文, 那里才有指标口径、 n、seed、budget 对齐的审计。

目标布局

<project_root>/
└── references/
    └── <name>/              # ← 这本身就是 git 仓库 (clone 的源码)
        ├── .git/
        ├── README.md        # ← 上游 README
        ├── <title>.pdf      # ← 论文 PDF, 放在仓库根
        ├── NOTES.md         # ← 本 skill 生成的摘要
        └── ... (其它源码)

参数解析

接收到本 skill 调用后,先解析 $ARGUMENTS:

未识别参数 → 打印用法后停止。

工作目录约定

• 当前工作目录 = 项目根。references/ 不存在时, 若调用涉及 acquire/index 单个具体 name, 自动 mkdir references/; 但 --all / --sync-claudemd 这类需要现有内容的命令仍直接报错停止。
• 根 CLAUDE.md 可能不存在 → 视情况新建(只有在确认要写 references 约定时);若已存在,只编辑被本 skill 标记的块,不要触碰其它内容。

Auto-acquire 阶段 (代码 + 论文自动获取)

当 <name> 的目录在 references/ 下不存在(或用户用 --add 显式触发), 先 acquire, 再 (默认) 接 index。多个 name 顺序处理, 单个失败不阻断后续。

1. 找官方代码仓库 (GitHub URL)

按以下优先级搜索, 至少看 2-3 个候选确认是"官方"实现, 不要满足于第一个:

1. WebSearch: query 形如 "<name>" github code, "<name>" paper official implementation, 含 paper 主题词更稳
2. arxiv abs 页 / 项目主页: arxiv 页面常有 "Code" 字段指向 github
3. paperswithcode: paperswithcode.com/paper/<slug> 上有 "Code" → official 标记
4. GitHub 搜索: WebFetch https://github.com/search?q=<name>&type=repositories (有 gh CLI 时优先 gh search repos "<name>")

判定"官方":

• repo owner 是论文一作 / 知名实验室 / 公司账号 (非 fork)
• README 标题 ≈ 论文标题, 或明确写 "official implementation / code"
• star 数与论文影响力大致匹配 (新论文星少不能单凭这个判)

≥ 2 个高置信候选 → 列出来一句话描述 (owner / star / README 首行) 让用户挑; 唯一明确 → 直接进 step 2; 完全找不到 → 报错, 提示用户 /index-references <name> --repo <url> 手动给。

2. Clone 仓库

mkdir -p references
GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 <url> references/<name>

默认:

• --depth 1 浅 clone, 节省时间和磁盘;用户传 --full-history 才完整 clone
• GIT_LFS_SKIP_SMUDGE=1 跳过 LFS 大文件 (有些 repo 把 ckpt 当 LFS 推, 可能几十 GB); 需要时让用户自行 git lfs pull

clone 失败 (网络/权限/目录非空) → 报错并指出原因, 不要静默跳过; 不要在已有内容的目录上强制 clone。

3. 下载论文 PDF

优先从刚 clone 的 README 抓 arxiv 链接 (最可靠, 因为 repo 通常自带正确的论文链接):

1. 读 references/<name>/README.md, grep arxiv.org/abs/(\d+\.\d+) 或 arxiv.org/pdf/(\d+\.\d+)
2. 找不到 → WebSearch "<paper 标题或 name> arxiv", 或看 README 的 project page 链接
3. 拿到 arxiv ID 后:

   curl -sL "https://arxiv.org/pdf/<id>.pdf" -o "references/<name>/<title>.pdf"

4. 无 arxiv → 用 openreview / 项目主页 / 直接 PDF 链接 curl -L -o

PDF 文件名约定: 跟现有 references 一致, 形如 <论文短标题>, <一作> et al., <year>, v<n>.pdf 或简化的 <短标题>.pdf 均可。不要用 arxiv ID 当文件名 (无语义)。标题里有冒号 / 斜杠等 shell 不友好字符要去掉或换 -。

校验: 下载后 file references/<name>/*.pdf 检查 magic 为 PDF, 且 wc -c 大小 > 50 KB (常见 fail mode 是拿到 HTML 错误页, 几 KB)。

4. 进入 index 阶段

acquire 全部完成且非 --add 模式时, 自动接 "单个 reference 的索引流程"。--add 模式则停在这里, 打印 acquire 结果汇总。

单个 reference 的索引流程

对每个待索引的 references/<name>/:

1. 盘点输入:
   • 先查 references/LEDGER.md 有无该工作的行 (见上"边界"节): 有 → 记下 key, 写进 NOTES 顶部 并回填该行 repo path; 无 → NOTES 顶部写 none — implementation index only。
   • 找 PDF: references/<name>/*.pdf (通常一份论文)。可能为 0 或 1+。
   • 找 README: references/<name>/README.md (或 Readme* / *.rst 兜底)。
   • 顶层目录列表 (一层即可,不要递归)。
   • 配置文件入口 (configs/, *.yaml, requirements.txt, setup.py, pyproject.toml)。
2. 读取顺序 (从信息密度高到低,边读边写,够用即止):
   1. README.md (整体读) — 多半已经包含定位/方法/数据/超参/复现命令。
   2. PDF 摘要 + 引言 + 方法节标题 (用 Read tool 的 pages 参数控前 ~10 页)。如果 README 已经讲清楚方法,就跳过 PDF 的方法细节,只在必要节点再回查。
   3. 实验节必读 — 不因"README 已讲清楚"而跳过。 用 pages 翻到 Experiments/Results 章 (通常紧接方法节之后), 抄下主结果表的绝对值与实验设置(环境/依赖/指标口径)。 README 几乎从不写全这两样, 而它们决定了别人的数能不能和自己的比 —— 跳过这一步是本 skill 最常见、代价最大的失败模式。
   4. 顶层目录与入口脚本 (train.py / main.py / scripts/*.sh 的开头几十行) → 推断代码地图。
   5. 默认配置文件 (configs/default.yaml 之类) → 抓关键超参。
3. 写 NOTES.md (中英混合,模板见下)。
   • 不要瞎编。任何不确定的字段写 <unknown — see {file}> 并附查找指引,留给后续按需补。
   • 区分两种不可靠:<unknown> = 没找到; <derived> = 这是概括/换算过的二手值,原始值在别处 (例如只抄到相对增益、只记了"大致相当"、把多个数取了平均)。<derived> 的危险在于它看起来 像事实,读者会直接引用 —— 必须同时写明原始值在哪 (see paper Table N)。
   • 引用源码时用 path/to/file.py:LINE 或 path/to/file.py:func_name,可点击跳转。
   • 控制总长度在 ~200 行内。摘要不是文档,过长就失去意义。
4. token 预算: 单个 reference 不要无限读。如果项目代码超过 ~5k 文件,顶层目录扫一遍后,只读 README + 默认 config + 1-2 个入口脚本即可,其余字段留 <unknown>。

NOTES.md 模板

写入 references/<name>/NOTES.md,严格按以下结构(标题英文,正文中文,术语保留原文):

# <Project Name> — NOTES

> Indexed: <YYYY-MM-DD> · Paper: `<pdf filename or "n/a">` · Repo origin: `<github url if found in README, else "n/a">`
> Ledger: `<LEDGER.md 中的 key, 若无 ledger 则写 "none — implementation index only">`

## TL;DR (定位用)
<1-2 句: 这个工作做什么,与当前 host 项目可能的连接点。host 项目的方向若未知,就只写"做什么"。
这是**路由标签**,用来认出该找哪份代码,不是可引用的论文概括。>

## Core Method (核心方法 — 仅为读懂代码所需)
<写到"能看懂 Code Map 里各模块在干什么"为止, 通常 2-3 句: 输入/输出、关键模块、训练目标。
术语保留英文(如 diffusion, cross-attention, RoPE)。
**不写方法的动机、贡献、与他人方法的优劣比较** —— 那些属于论文层, 走 LEDGER + 论文全文。
已有 ledger 行时, 此节可直接写 `see ledger <key>` 再补代码相关的实现要点。>

## Training Data (训练数据)
- **Source**: <数据集名 + 来源链接 / 论文引用>
- **Scale**: <#samples / #hours / #frames 等>
- **Preprocessing**: <切片/分辨率/归一化等关键操作; 指向 `datasets/...py` 等>

## Key Hyperparameters (关键超参数)
| Param        | Value | Source                  |
| ------------ | ----- | ----------------------- |
| optimizer    |       | `configs/xxx.yaml`      |
| lr           |       |                         |
| batch size   |       |                         |
| #steps/epoch |       |                         |
| warmup       |       |                         |
| loss weights |       |                         |
| precision    |       |                         |

## Experiment Setup (实验设置)
- **Benchmarks**: <eval set 名 + split; 若不确定清单是否完整, 标 `<partial>`>
- **Metrics**: <该工作实际报告的指标口径, 精确到变体 (如 word-F1 vs EM vs SubEM)>
- **Baselines**: <对比方法清单>
- **Setup dependencies (可比性关键)**: <凡是**改动后会使自己的复现结果与论文不可比**的设置。
  按本工作的实际情况列, 没有就写 none。判据是"若我换掉它, 还能不能拿自己的数对他们的数"。
  举例仅作提示, 不是固定清单: 外部服务/付费 API、数据或语料的具体版本、base checkpoint、
  eval harness 及其版本、采样/随机性协议、与硬件绑定的数值行为。>
- **Repro command**: `<bash 命令, 来自 README / scripts/>`

## Reported Results (复现达标线)
<抄主结果表的**绝对值**, 附出处表号。这是复现的达标线, 也是判断"我的实现对不对"的唯一锚点。
**角色限定**: 这些数只用于"我跑出来的和它对不对得上"。要拿去做跨方法比较、写进调研结论或论文,
必须走 LEDGER + 论文全文, 在那里补齐指标口径 / n / baseline / seed / budget 对齐的审计。

规则:
- **必须是绝对值。只写相对增益 (如 "+42.8% over X") 不合格** —— 相对值无法当达标线,
  且会让读者误以为必须自己跑基线才能对齐。若原文只给相对值, 找到基线绝对值一并记, 否则标 `<derived>`。
- 每个数附出处: `paper Table N` / `Fig. N` / README 表格。
- 只记与本项目相关的行列 + 该工作自己的最优行; 有消融表且消融揭示了组件贡献时一并记。
- 规模/变体不止一个时 (如 3B/7B), 记与本项目规模最接近的那个, 并注明另一个的量级。>

| Setting | <bench1> | <bench2> | ... | Avg | Source |
| ------- | -------: | -------: | --- | --: | ------ |
|         |          |          |     |     | `paper Table N` |

## Code Map (代码地图)
顶层目录 / 关键入口,一行说明:
- `train.py` — <入口, 简述>
- `configs/` — <配置组织方式>
- `models/` — <核心网络定义所在>
- `datasets/` — <数据加载>
- `scripts/` — <复现脚本>
- ... (按实际填,无关的不列)

## Reusable Modules (可复用模块)
对当前项目可能直接复用的具体单元,精确到文件/函数:
- `models/foo.py:Bar` — <什么场景下能复用, 注意事项>
- `utils/bar.py:fn_xyz` — <...>
- (若一时找不到明确点,留 `TBD — 待具体复用需求出现时再深挖`)

## Differences & Applicability (差异 / 适用边界)
<相对当前 host 项目可能的关键差异: 输入模态、规模、假设。哪些设置能直接搬,哪些需要改造。>

## Open Questions (待查)
<标记 NOTES 中所有 `<unknown>` 字段的去向, 例如: "lr schedule: 查 main/trainer.py:configure_optimizers">

根 CLAUDE.md 约定块

在根 CLAUDE.md 中维护一个用注释包裹的、可被本 skill 重写的块,内容随当前已索引项变化。

块的边界标记必须精确如下:

<!-- BEGIN: references-convention (managed by /index-references) -->
## References (相关工作)

`references/` 存放相关工作的论文 + 从 GitHub clone 的源码。**读取策略**:

1. **永远先读 `references/<project>/NOTES.md`** — 预先生成的摘要 (TL;DR / 方法 / 数据 / 超参 / 实验 / 代码地图 / 可复用模块 / 差异)。不要直接 grep 源码。
2. NOTES.md 不存在或字段为 `<unknown>` 时,运行 `/index-references <project>` (或 `--refresh <project>`) 生成 / 更新。
3. 只有当 NOTES.md 指向具体文件 (`Code Map` / `Reusable Modules` 段) 之后,才进入源文件读取对应片段。
4. 复用代码优先看 NOTES.md 的 `Reusable Modules` 段。
5. **NOTES 是导航,不是引用源。** 上面 1/3 两条约束的是**代码定位**,不适用于**事实性主张**。
   凡是要进入*决策 / 对外文档 / 算力承诺*的事实 —— 论文报告的数值、官方超参、实验环境与依赖、
   基线设置 —— 必须回论文 PDF 或官方代码核实后再用;标 `<derived>` / `<partial>` / `<unknown>`
   的字段一律视为「待核」而非「已知」。**核到的当场回写 NOTES 并标出处**(表号 / `file:line`),
   让索引单调变好、同一个坑不踩第二次。
6. **NOTES 管实现, `references/LEDGER.md` 管论文。** 问"这份代码怎么跑"→ NOTES;
   问"这个工作是什么 / 可不可信 / 能不能当 baseline"→ LEDGER 行 + 重读论文全文。
   NOTES 里不含 tier 与领域判断;LEDGER 不存在时, NOTES 中的论文级内容一律视为未经验证。

### 当前已索引的 references
- `<name1>` — <TL;DR 第一句, 截断到 ~80 字>
- `<name2>` — ...
<!-- END: references-convention -->

更新规则:

• 块内完全由 skill 重写,不保留任何人工编辑 → 若发现块内有非本 skill 写入的痕迹,先在终端提醒用户冲突,询问是否覆盖。
• CLAUDE.md 不存在 → 创建一个,顶部只放本块。
• 已有 CLAUDE.md 但无该块 → 追加到文件末尾。
• "当前已索引的 references" 列表从扫描 references/*/NOTES.md 现存情况生成 (而非记忆里的); 每条的描述取 NOTES.md 中 ## TL;DR 段第一句。

输出与汇报

每次运行结束后,简短打印:

• Acquire 阶段: 每个 name 的 clone URL + commit / PDF 文件名 + 大小; 失败原因 (若有)
• Index 阶段: 新生成 NOTES.md 路径; 跳过 / 已存在的列表; 留下的 <unknown> 字段数 (单项 > 5 个就提示用户)
• 是否更新了 CLAUDE.md

不要把 NOTES.md 全文回显进对话。

不要做的事

• 不要修改 references 子项目里的任何源文件 (它们是上游 clone, 保持干净)。
• 不要在 references 根之外创建额外 NOTES (例如 references/NOTES.md 总览)。摘要只放在每个子项目里。
• 不要把摘要写得像论文 reading note — 它是给未来 Claude 看的索引,不是给人精读的。
• 不要为了填满表格而瞎编超参,宁可留 <unknown> + 查找指引。
• 不要只记相对增益当主结果 ("比 X 高 42.8%")。它不能当复现达标线,且看起来像事实。 要绝对值 + 表号;确实只有相对值就标 <derived> 并写明原始表在哪。
• 不要因为 README 讲清楚了方法就跳过论文实验节。 环境依赖与主结果表几乎只在论文里, 而它们决定别人的数能不能和自己的比。
• 不要在 NOTES 里写 tier / 新颖性 / 领域地位, 也不要写"这个方法比 X 好"这类论文级判断。 项目有 references/LEDGER.md 时它们归 ledger; 没有时它们尚未经过验证, 写下来只会被下游当事实引用。
• 不要在没有 --refresh 的情况下覆盖已有 NOTES.md。
• 不要在 references/<name>/ 已经非空时强行 git clone (会报 fatal); 先检查目录状态, 给用户选项: 删除重 clone / git pull 更新 / 跳过。
• 不要为了"省事"用第一个 GitHub 搜索结果, fork / 复现 / 第三方实现 ≠ official, 拿错的 repo 会污染整个 NOTES。