zhoujie
3bb3528ad6
技能自己的目录里混入运行时草稿数据不太合适——如果以后要把 skill 当独立包 复用/分享,草稿数据会被一起打包进去。改为统一放到 <project-root>/output/ <skill-name>/<topic-slug>/,并按主题分子目录(topic-slug 规则和 references/ 下的归档目录一致),避免不同主题的草稿用无区分度的通用文件名互相覆盖/混堆 (这个问题在旧的 output/ 目录里已经实际发生过)。 同步更新了 SKILL.md、archive_references.py 的示例路径、已归档的 README 里 指向草稿目录的说明,以及 CLAUDE.md 里的目录结构图和相应设计原则。现有的 草稿文件已按此规则搬到 output/literature-search-verify/uav_aeromagnetic_compensation/ 下。.gitignore 里原有的 output 规则本来就不带路径前缀,新位置无需改动即可 继续被正确忽略。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
77 lines
5.1 KiB
Markdown
77 lines
5.1 KiB
Markdown
# autoPaper — 科研辅助 Claude Skill 库
|
|
|
|
本仓库不是一篇具体论文的工作区,而是一套持续维护的 Claude Code skill 库,
|
|
服务于科研工作流(文献检索 → 核实 → 归档 → 写作)。`references/` 下按主题
|
|
归档的文献是这套 skill 实际产出的样例/沉淀,不是本仓库的主体。
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
.claude/skills/ 所有 skill 的定义,每个子目录一个 skill,只放代码/说明
|
|
literature-search-verify/ 检索 + 反幻觉引用核查
|
|
SKILL.md skill 说明(frontmatter name 必须与目录名一致)
|
|
scripts/ 纯标准库 Python 脚本,无第三方依赖
|
|
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` 不一致的问题,已修正)。
|
|
|
|
## 已知薄弱环节 / 待办方向
|
|
|
|
- `scripts/search_semantic_scholar.py`、`verify_citation.py` 对 Semantic Scholar
|
|
的限流(HTTP 429)没有重试/退避,会话量大时会导致大量条目退化成只有单源验证
|
|
(已在 `references/uav_aeromagnetic_compensation/README.md` 的检索记录里实际发生过)。
|
|
- 核心正确性逻辑(`verify_citation.py` 的三档判定、`archive_references.py` 的
|
|
bib 字段解析)目前没有自动化测试兜底,只能靠人工抽查实际输出结果。
|
|
- 目前只覆盖"检索/核实"与"写作/溯源"两段,引用一致性核查(定稿里的
|
|
`\cite{}` 是否都对得上 `references.bib`、有没有归档了却从未引用的条目)、
|
|
面向具体学科的补充检索源等还没有对应 skill。
|
|
|
|
## 下一步计划(已和用户确认,尚未实施)
|
|
|
|
1. **给核心脚本补单测 + 给网络请求加限流重试**:`verify_citation.py` 的三档
|
|
判定逻辑、`archive_references.py` 的 bib 字段解析(覆盖嵌套花括号等边界
|
|
情况)补 pytest 单测;`search_semantic_scholar.py` 等对 S2/arXiv/Crossref
|
|
的请求加退避重试,避免再出现"S2 被限流导致大量条目退化成单源验证"的情况。
|
|
2. **新增"引用一致性核查" skill**:检查定稿里所有 `\cite{}` 的 key 是否都能在
|
|
对应主题的 `references/<slug>/references.bib` 里找到,以及有没有已归档
|
|
但从未被正文引用的"僵尸条目",在 literature-search-verify 和
|
|
paper-writing-grounded 之间补上这个校验环节。
|
|
|
|
## 新增 skill 时的约定
|
|
|
|
- SKILL.md 的 frontmatter `description` 要写清楚"什么场景下必须触发这个
|
|
skill",因为这是 skill 被自动选中的唯一依据。
|
|
- 正文按"为什么需要 / 工作流程 / 和其他 skill 的配合"组织,和现有两个 skill
|
|
保持同样的结构和颗粒度。
|
|
- 目录名 = frontmatter `name`,不要有拼写差异。
|