Lit Search

时间窗受限的高召回文献检索

驱动 literature-search/ 这条流水线。核心前提：召回率不是提示词问题，是检索工程问题。 反复 WebSearch 得到的是"相关度排序的前若干条"，既不可复现，也无法说明漏了什么。

工具位置与产物去向（第一步，别跳过）

CLI 就装在本 skill 目录里（src/litsearch/ + pyproject.toml）。 所有命令都要在这个目录下执行——它是 uv 找得到项目的地方：

SKILL_DIR=~/.claude/skills/lit-search     # 本 SKILL.md 所在目录
cd "$SKILL_DIR" && uv run lit --help      # 跑不通就先跑一次 ./install.sh

$LITSEARCH_HOME 若已设置则优先用它（把工具装在别处的人靠这个覆盖）。 两处都找不到 src/litsearch/cli.py → 问用户，不要猜。

产物必须写到用户的项目里，不是 skill 目录里。 --runs-root 默认是相对路径 runs/，而命令的工作目录是 skill 目录—— 不显式指定的话，几百 MB 的采集结果会堆进 ~/.claude/skills/lit-search/runs/， 用户既找不到，也想不到要去那里清理。每一条命令都要带上绝对路径：

PROJ=/abs/path/to/用户的项目            # 开工前先跟用户确认这个位置
cd "$SKILL_DIR" && uv run lit harvest --topic "$PROJ/topics/<id>.yaml" \
                                      --runs-root "$PROJ/runs" --depth standard

协议 YAML 同理——写在用户项目的 topics/ 下，不要写进 skill 目录。 本目录的 examples/ 有两份真实协议（生物医学、纯 CS 各一份）可以照抄。 下文命令块为了可读省略了这两个路径参数，实际执行时必须补上。

判断要不要用

用：系统综述、开题报告的文献检索部分、挑战赛调研——需要说得清召回边界的场合。 （开题报告的写作由 research-proposal skill 负责——它消费本 skill 的 dois.md/references.bib，不要在这里写正文。） 不用：用户只想快速看几篇代表作。那种情况直接 WebSearch 更快，别拖他走完整条流水线。

契约

输入：一句话研究主题 + 可选时间范围（不给就默认近 5 年）。 输出：

全量交付，分层只决定顺序，不决定去留。

两份参考文件，按需读，不要预先读： references/topic-template.yaml（写协议用）、 references/evidence.md（下面每条规则背后的实测数字，用户追问或排查时才需要）。

阶段 0｜写协议（这一步是模型的核心工作）

没有 lit init 命令——把主题变成协议需要判断力，不是代码。模板在 references/topic-template.yaml，复制到 topics/<id>.yaml 后按四步填。

① 拆概念块。 3–5 块，标出哪些 required。

第一个 required 块会成为无布尔检索能力源（CVF/OpenReview/Zenodo）的锚点短语。 把区分度最高的概念放第一位——通常是疾病/对象/材料。放成 "segmentation" 这类泛词， 会把整届 CVPR（约 9,200 篇）拉回本地过滤。

② 提名金标准——5–10 篇，DOI 必须先验证再写入。

gold_set 是整条流水线里唯一能证伪的东西。所以：

curl -sI -o /dev/null -w "%{http_code}\n" -L "https://doi.org/<doi>"   # 200 才许写进协议

走 doi.org，不要走 Crossref。 arXiv 的 10.48550/arXiv.* 注册在 DataCite， api.crossref.org 对它一律 404——用 Crossref 验证会把真实存在的预印本当成编造的 DOI 拒掉， 而 CS/AI 主题的金标准几乎全是 arXiv。

编一个格式合法但不存在的 DOI，代价不是"少一篇文献"，是验证链条整个失效—— 你会看到 8/9 的召回，然后花半天排查一个根本不存在的漏检。

数量不能凑合。 少于 5 条时 coverage_report.md 会自己标注"证据偏弱"： 3/3 和 9/9 印出来一模一样，但前者能证伪的检索缺陷少得多。

同时提名 1–2 篇窗口外的真实论文当 out_of_window_controls，验证日期过滤真的生效。

③ 干跑校准量级。

uv run lit strategies --topic topics/<id>.yaml    # 只看检索式，不发请求
uv run lit plan       --topic topics/<id>.yaml    # 各源预计命中数

这是唯一允许调参的窗口。 一旦开始采集，改术语会变更语义指纹，作废整轮。

④ 领域判断。 生物医学之外的主题（纯 CS / 工程 / 材料）要主动提醒用户两件事：

1. 摘要覆盖会下降。 这条流水线对闭源出版商的摘要覆盖实质上是 PubMed 撑起来的 （实测 Elsevier 95.6%、Springer 80.4%，而 Crossref 上这些条目根本没有摘要）。 PubMed 用不上时初筛退化成只看标题。Semantic Scholar 本该补这个位，但当前版本尚未实现 ——协议里写 semantic_scholar: enabled 会被丢弃（CLI 会红字提示）。不要向用户 声称补上了覆盖面。
2. 捕获-再捕获会结构性不可得。 它需要 PubMed × OpenAlex 两个源同时在场。 关掉 PubMed 后，召回证据就只剩金标准一个点位——所以这类主题的 gold_set 更要提满 5–10 条。

阶段 1–7｜流水线

每一步跑完都要把数字念给用户听，不要静默推进。

先让用户选深度——代价必须先于执行可见：

uv run lit depths     # 三档的规模、耗时、成本对照

三档的差别只在跑多少源、滚几轮雪球。判定规则、去重、时间窗、召回率证据 三档完全一致——降档降的是覆盖面，不是严谨度。 systematic 必须显式指定并等用户确认。

<run> 从哪来：lit harvest 跑完第一行会打印 run 目录，那就是它。 后续命令也接受 <topic>/<run_id>，或只给协议里的 topic id 自动取最新一次—— 后者最省事。忘了跑到哪一步用 lit show <run>。

# 1 采集
uv run lit harvest    --topic topics/<id>.yaml --depth standard
uv run lit proceedings <run> --topic ...   # 仅 MICCAI/LNCS 类主题；语料里没有 LNCS 会自动跳过

# 2 筛选（三级放量，见下）
uv run lit screen      <run> --topic ... --limit 4
uv run lit screen      <run> --topic ... --limit 100
uv run lit screen      <run> --topic ...
# 在 human_queue.csv 填 decision/reviewer/reason 后导回（可分批）
uv run lit adjudicate  <run> --topic ... --kind screening --input human_queue.csv
# 在 boundary_cases.csv 填 decision/reviewer/reason 后导回
uv run lit adjudicate  <run> --topic ... --kind date --input boundary_cases.csv

# 3 引文闭包（必须在筛选之后）
uv run lit snowball    <run> --topic ... --seeds included
uv run lit screen      <run> --topic ... --resume     # 只补新增记录，不重判已判过的

# 4 证据与报告
uv run lit validate    <run> --topic ...
uv run lit report      <run> --topic ...
uv run lit verify      <run> --strict

# 5 分层与交付（--ccf 可选，先问用户要目录路径）
uv run lit rank        <run> --ccf CCF.pdf --included
uv run lit deliver     <run> --topic ... --ccf CCF.pdf --style gbt7714 --bibtex

滚雪球循环怎么收。 snowball → screen --resume → snowball → …，交替进行。 三种终止，只有第一种能宣称闭包完成：

--depth quick 不跑滚雪球，standard 只滚 1 轮；要滚到饱和用 systematic 或显式 --max-rounds。不要照全量重跑 screen——那会把几千条已判定的再判一遍， 钱翻倍，还可能触发"新一轮判定数少于上一轮"的护栏而拒绝写入。

补源不能靠续跑。 harvest --resume 只重跑上一轮未完成的检索式，它没有能力 覆盖一个从没跑过的源。先跑了 quick、之后想补顶会源，用：

uv run lit harvest --topic ... --into <run> --phase stage3 --sources cvf,openreview,grey

放量前必须先冒烟、再校准

不要直接对上万条跑筛选。三级放量，每级只花上一级十倍的钱，发现的却是完全不同的问题：

• --limit 4（约 $0.003）验 API 契约。 假客户端测得了你的代码，测不了服务端约束。 实测就是在这一步撞到 Thinking mode does not support this tool_choice。

• --limit 100（约 $0.02）验任务设计。 两根轴都要看，缺一根都会放过问题：

  成因——大量 unclear 且理由雷同 = 把全文阶段的标准用在了标题摘要阶段， 该改提示词而不是改协议（改协议会变更语义指纹，挡住后续滚雪球并入）。 健康的队列应以"通道分歧"和"低置信度"为主。

  体量——队列占比超过 15% 就要停下来改标准，不管成因分布多"健康"。 实测一次 4,000 条的运行队列率 24.6%（973 条），成因分布完全正常， 但 973 条没有人会真去看。lit adjudicate 能把裁定结果导回， 可它是给几十条用的；上千条时正确动作是回来改判定标准，不是把队列丢给用户。 在裁定导回之前，这些记录不进 included，也不进交付物。

• 放量。

判定 API 后端同样三级：--limit 4（约 $0.0002）验服务端约束，--limit 100 （约 $0.005）验任务设计，再放量。这一步不能省——假客户端测得了你的代码， 测不了服务端，也测不了运行时：十项 CLI 测试用 respx 全绿，真跑第一次就抛了 Event loop is closed（httpx 的连接池绑在创建它的事件循环上，而 respx 在传输层 拦截、根本不建真实连接）。

--limit 的结果写 screening_trial.json 和 human_queue_trial.csv（判定 API 则写 jev_scores_trial.jsonl），不占正式轮次——否则一次校准会盖掉全量结果。 校准时打开的是这三个 *_trial 文件，不是 human_queue.csv / jev_scores.jsonl。

⚠️ --limit N 取的是语料前 N 条，不是随机抽样。 前缀里几乎全是最先被采集、 也最典型的记录，而撑爆人工队列的永远是后面那些边缘记录。实测一次：前缀样本 100/100 含锚点关键词、仅 12% 无摘要，报出队列率 9%；而全语料是 22.9% 和 75.7%， 换同分布随机样本重测真实值 18%，超红线。

跑过 lit proceedings 或滚过雪球之后差距最大——那两步追加的记录全排在语料尾部。 校准前先核样本构成（关键词命中率、无摘要占比与全语料是否相当）； 不相当就把 run 复制到临时目录、把 corpus.jsonl 换成随机 N 条再跑，别改原 run。

不能跳过的顺序

筛选必须在滚雪球之前。 实测：从未筛选的 13,920 条种子出发，后向候选是 134,317 条； 而最终会纳入的只有几百条。跳过筛选去滚雪球 = 把噪声放大一个数量级，还要为此付十倍筛选费。 用户催的时候也不要改成 --seeds in_window——先把成本讲清楚，让他自己决定。

滚雪球与筛选必须交替。 种子是"已纳入"，不筛就没有种子。 实测饱和曲线 34.7% → 4.1% → 0.4%，而 snowball 独有贡献占 92%—— 这是纯关键词检索会漏成什么样的直接证据。

成本必须先于执行可见。 lit screen --dry-run 给出 token 数与美元金额。 无凭据时是字符粗估并明确标注。不要替用户跳过这一步。

分层与交付

只标注与排序，绝不过滤。 阈值会把"没被评价过"和"质量低"变成同一个动作—— 实测以 4.0 切，1,487 条只剩 390 条，其中被删的 340 条是没有指标而非指标低。

分层取所有可用尺子里最好的那个：

四条必须讲清楚的事：

1. CCF 与影响力指标测的不是同一件事，取较优。 实测 Medical Image Analysis 是 CCF-C，而它的 OpenAlex 指标 10.14 全语料最高。
2. OpenAlex 2yr_mean_citedness 不是 JIF。 JIF 分母只算 citable items， OpenAlex 分母算全部条目；发大量学会年会摘要的刊被系统性低估三到五倍 （实测 Stroke 1.81、Neurology 1.11）。阈值不能跨标度搬运。
3. 排行榜数据由用户提供，不随仓库分发。 CCF 目录是公开文档但仍走 --ccf 槽位； JCR / 中科院分区是商业授权数据，绝对不能打包进仓库。
4. 没有目录就不猜等级。 目录里没有的会议标"未评级"。 编出来的 CCF-A 和真的长得一模一样，这是最危险的地方。

引文格式化免 key：lit deliver 走 doi.org 内容协商，支持 apa / ieee / gbt7714 / nature / ama / bibtex。

（期刊匹配走 ISSN 而非刊名、样式名发请求前先校验——这两条是 lit rank / lit deliver 内部的护栏，你没有对应操作。想知道为什么见 references/evidence.md。）