autoPaper/CLAUDE.md

# autoPaper — 科研辅助 Claude Skill 库

本仓库不是一篇具体论文的工作区,而是一套持续维护的 Claude Code skill 库,
服务于科研工作流(文献检索 → 核实 → 归档 → 写作)。`references/` 下按主题
归档的文献是这套 skill 实际产出的样例/沉淀,不是本仓库的主体。

## 目录结构

```
.claude/skills/                     所有 skill 的定义,每个子目录一个 skill,只放代码/说明
  literature-search-verify/         检索 + 反幻觉引用核查
    SKILL.md                        skill 说明(frontmatter name 必须与目录名一致)
    scripts/                        纯标准库 Python 脚本,无第三方依赖(含 http_utils.py 统一限流重试)
      tests/                        unittest 单测,全部mock网络请求,不发真实请求
  paper-writing-grounded/           论文写作(强制数据溯源)
    SKILL.md
  git-commit/                       规范化 commit message 生成与提交
    SKILL.md
output/<skill-name>/<topic-slug>/   各 skill 运行时的草稿区,.gitignore 掉,不进版本库;
                                     按 skill 分子目录、同一 skill 内再按主题分子目录
                                     (topic-slug 规则和 references/ 下的目录名一致),
                                     避免不同 skill、不同主题的草稿互相覆盖/混堆
references/<topic-slug>/            literature-search-verify 归档产出的稳定文献库
  references.bib                    已验证文献,写作阶段 \cite{} 直接复用这里的 key
  README.md                         人可读索引,含 suspect/unverified 条目说明
  pdfs/                             开放获取的原文 PDF(如有)
```

## 核心设计原则(新增/修改 skill 时必须保持)

1. **反幻觉是硬约束,不是建议**:任何进入正文引用或数字的内容都必须能独立核实
   或追溯到真实数据,验证不通过就必须显式标记(`suspect`/`unverified`/
   `[需要数据: ...]`),绝不能为了让输出"看起来完整"而悄悄丢弃或蒙混过关。
2. **脚本优先于临场编 API 调用**:能写成 `scripts/` 里可重复运行的脚本就不要
   指望模型每次现场拼 HTTP 请求——后者不可复现、容易在细节上出错。脚本只用
   标准库,不引入第三方依赖,保证任何环境下拿来就能跑。
3. **草稿区与交付物分离**:草稿(项目根目录下的 `output/<skill-name>/<topic-slug>/`)
   只是运行痕迹,不是可信的最终产物,也不放在 `.claude/skills/` 里面(那里只放
   skill 代码本身);确认稳定后要显式归档到 `references/<slug>/` 这类项目级
   目录,才算数。同一 skill 下不同主题的草稿必须分子目录,不能用无区分度的
   通用文件名（如`t1.json`）散落在同一层——这类命名冲突曾经真实发生过。
4. **skill 之间通过约定(如 bibtex key)解耦协作**,而不是互相读对方内部状态;
   每个 SKILL.md 末尾应有一节说明它和其他 skill 的配合方式。
5. **目录名必须和 SKILL.md frontmatter 里的 `name:` 完全一致**——skill 发现/
   调用是按目录名走的,两者不一致会导致"文档里写的名字"和"实际能唤起的名字"
   对不上(曾经出现过 `paper-wiriting-grounded` 目录名手滑打错、和 frontmatter
   里正确拼写的 `paper-writing-grounded` 不一致的问题,已修正)。

## 已知薄弱环节 / 待办方向

- 目前只覆盖"检索/核实"与"写作/溯源"两段,引用一致性核查(定稿里的
  `\cite{}` 是否都对得上 `references.bib`、有没有归档了却从未引用的条目)
  还没有对应 skill。
- `search_openalex.py` 目前只用了 OpenAlex Works API 里比较基础的字段
  (标题/作者/年份/venue/DOI/引用数/开放获取PDF),没有用它的 concept/topic
  分类字段做更细的学科过滤——如果以后要精确限定学科方向,这是可以深挖的点。

## 下一步计划

1. ~~给核心脚本补单测 + 给网络请求加限流重试~~ **已完成**:新增
   `scripts/http_utils.py` 统一封装限流重试(429/5xx指数退避,遵守
   `Retry-After`),`search_arxiv/crossref/semantic_scholar/openalex.py` 和
   `verify_citation.py` 都已接入;`verify_citation.py` 的跨源标题核查改成
   同时查 Semantic Scholar + OpenAlex 两个独立源(任一命中即通过),不再
   单点依赖 S2;新增 `search_openalex.py` 作为第四个检索源;`archive_references.py`
   的 `slugify()` 修了中文主题名被折叠成通用"references"名的问题;
   `scripts/tests/` 下补了 37 个 unittest 单测(全部mock,不发真实请求),
   覆盖上述所有改动。
2. **新增"引用一致性核查" skill**(`citation-consistency-check`):检查定稿里
   所有 `\cite{}` 的 key 是否都能在对应主题的 `references/<slug>/references.bib`
   里找到,以及有没有已归档但从未被正文引用的"僵尸条目",在
   literature-search-verify 和 paper-writing-grounded 之间补上这个校验环节。
3. **新增"图表生成" skill**(`figure-from-data`,独立 skill,不并入
   paper-writing-grounded):把全局 dataviz skill 的画图能力和本项目"数据不
   能编"的红线结合起来——图上出现的每一个数字/误差棒/显著性标注都必须能
   追溯到用户提供的真实数据,追溯不到就必须显式标记,不能为了图好看而插值/
   编造。用户目前"才刚开始"做实验,这个和 reproducibility-checklist 一起
   算当前阶段实际用得上的。
4. **新增"实验可复现性自查" skill**(`reproducibility-checklist`):检查一个
   实验结果和"跑出这个结果的环境/随机种子/超参数/代码版本"之间是否可追溯,
   在博士研究早期建立这个记录习惯,比后期(投稿前)才补收益更大。具体检查
   项和触发时机(每次跑完实验?还是准备写进论文前?)还需要进一步讨论确定。
5. **新增"投稿格式合规检查" skill**(`submission-checklist`):投稿前检查页数
   限制、双盲匿名化处理、模板合规、supplementary材料要求等——失败代价直接
   (格式不合规可能直接被拒),但用户目前还没到投稿周期,优先级低于上面几项,
   先记录设想,不着急做。
6. **新增"审稿意见回复" skill**(`rebuttal-writing-grounded`):和
   paper-writing-grounded 共享同一条红线——不能为了让回复显得更有说服力,
   而承诺做不到的新实验或编造补充结果;但写作场景(逐条对应审稿人意见、
   语气要求"礼貌但坚定")不同,应该做成姊妹 skill 而不是塞进
   paper-writing-grounded 里。用户目前还没进入投稿/答辩周期,优先级最低,
   先记录设想。
7. **新增"实验设计常见陷阱清单" skill**(`experimental-design-checklist`,
   优先级低、置信度低):不强制流程,只是一份"容易漏掉的检查项"提醒(有没有
   设基线/消融、统计检验方法选得对不对、有没有偷偷用测试集调过参),因为
   "实验设计得好不好"本质是统计学/领域判断力,skill 只能提醒别漏掉常见坑,
   不能替用户判断设计是否合理——做的时候要非常克制,避免让用户误以为"清单
   过了=设计没问题"。
8. **新增"组会/答辩/会议报告大纲" skill**(`presentation-outline`,优先级低、
   价值存疑):把已有的真实结果整理成报告大纲,同样要遵守"不编内容"的红线。
   价值有限,因为这类大纲高度依赖听众和场合,通用流程能提供的帮助有限;暂
   不确定要不要做,先记录设想。
9. **新增"导师进展汇报" skill**(`advisor-progress-report`,优先级低、价值
   存疑):从 git log / 实验记录整理成给导师的周报。风险是"总结不当会歪曲
   实际进度"——如果做,必须严格限定为"只整理已确认的事实,不做主观进度
   评估",且这类沟通策略本身因人而异,通用 skill 能提供的价值可能不大。
10. **讨论过但决定不做**:
    - "新颖性/查重式文献扫描"(检索这个想法是否已被做过)。结论是它和
      literature-search-verify 的检索底层高度重合,而"够不够新颖"本质是
      判断力问题,skill 顶多能帮忙把相关已有工作找全,这部分
      literature-search-verify 已经能覆盖大半,边际价值不足以单独立项。
    - "研究问题提出/创新点判断"。这是纯判断力/领域洞察力问题,不适合
      productize——skill 最多能辅助"检索现有工作看有没有人做过"(即上一条
      讨论过的新颖性扫描),但"这个问题值不值得做"必须是人的判断,做成
      强流程 skill 反而有"流程走完=判断没问题"的误导风险。
    - 以上两条如果以后发现实际需求很明确,可以重新评估这些决定。

## 新增 skill 时的约定

- SKILL.md 的 frontmatter `description` 要写清楚"什么场景下必须触发这个
  skill",因为这是 skill 被自动选中的唯一依据。
- 正文按"为什么需要 / 工作流程 / 和其他 skill 的配合"组织,和现有两个 skill
  保持同样的结构和颗粒度。
- 目录名 = frontmatter `name`,不要有拼写差异。