diff --git a/.claude/skills/literature-search-verify/SKILL.md b/.claude/skills/literature-search-verify/SKILL.md index c9f9d2d..beab026 100644 --- a/.claude/skills/literature-search-verify/SKILL.md +++ b/.claude/skills/literature-search-verify/SKILL.md @@ -25,12 +25,31 @@ description: Search academic literature across arXiv, Semantic Scholar, Crossref `scripts/` 目录下已经写好了能直接跑的检索脚本,不依赖任何第三方Python包,也不需要装MCP工具: ```bash +# 始终从项目根目录调用(脚本本身不关心cwd,但--bib-out等输出路径按项目根目录约定拼)。 # 一次性搞定:检索 arXiv + Semantic Scholar + Crossref,自动去重、逐条验证, # 并把通过验证的条目写成BibTeX文件——这是应该默认调用的入口 -python3 scripts/literature_search.py "UAV magnetic compensation Tolles-Lawson" \ - --max-per-source 8 --bib-out refs.bib +mkdir -p output/literature-search-verify/uav_aeromagnetic_compensation +python3 .claude/skills/literature-search-verify/scripts/literature_search.py \ + "UAV magnetic compensation Tolles-Lawson" \ + --max-per-source 8 \ + --bib-out output/literature-search-verify/uav_aeromagnetic_compensation/refs.bib ``` +草稿路径(检索报告JSON、下载的PDF、中间生成的bib)统一落在项目根目录下的 +`output/literature-search-verify/`,不要写回技能自己的目录里(`.claude/skills/` +应该只放技能代码,不放运行时产生的草稿数据)。如果项目里以后还有别的技能也 +需要草稿区,各自建 `output//` 子目录,互不混放。 + +**同一个技能内部也要按主题分开,不要所有检索会话都堆在同一层**:开始一个新 +主题的检索时,先按"和第六步归档时同样的规则"把主题名转成 slug(小写、非 +字母数字换成下划线,比如"UAV aeromagnetic compensation" → `uav_aeromagnetic_compensation`), +建 `output/literature-search-verify//` 子目录,这一整个主题下 +不管跑多少轮检索、多少条不同的query,原始JSON/bib草稿都写进这一个子目录里 +(文件名可以随意区分轮次,比如`q1.json`/`q2.json`),不要用不带主题区分的 +通用文件名散落在`output/literature-search-verify/`根下。这样同一个主题的 +草稿和第六步归档产出的`references//`目录能通过同一个slug对上号, +之后回来补充检索同一主题时也知道去哪个子目录续。 + 正常情况下**只需要跑这一条命令**,它内部会依次调用 `search_arxiv.py`、`search_semantic_scholar.py`、`search_crossref.py` 做检索,再对每条合并后的候选文献跑 `verify_citation.py` 做交叉验证,输出一份JSON报告(每条候选都带`verdict`字段)。如果只是想单独查一个来源,或者针对某一条文献单独复核,再分别调用对应的单个脚本(用法见每个脚本文件开头的docstring)。 如果这些脚本因为网络原因跑不动(比如内网/代理限制导致连不上 arxiv.org、semanticscholar.org、crossref.org),`literature_search.py` 会把每个来源的报错单独记在`search_errors`里而不是直接崩溃——这时候老实告诉用户"检索脚本连不上网络,以下是报错信息",不要退回去凭记忆编文献。如果用户这边确实连不上这几个学术API域名,才退回到 web_search 工具,并在结果里明确标注"来自通用网络搜索的补充结果,未经过脚本的交叉验证流程,置信度较低"。 @@ -66,15 +85,19 @@ MCP 检索工具覆盖的是 arXiv/Semantic Scholar/Crossref 这类有公开 API ### 第六步:归档 -`output/` 目录只是脚本运行时的草稿区——里面混着每一轮探索性检索的原始JSON(包括被过滤掉的噪声,比如"Tolles""Lawson"被当成人名匹配出的无关文献),不适合作为最终交付物,而且随着会话增多会越堆越乱、也不方便下次会话或用户直接翻阅。 +`/output/literature-search-verify/` 只是脚本运行时的草稿区——里面 +混着每一轮探索性检索的原始JSON(包括被过滤掉的噪声,比如"Tolles""Lawson"被当成 +人名匹配出的无关文献),不适合作为最终交付物,而且随着会话增多会越堆越乱、也不 +方便下次会话或用户直接翻阅。 -所以每次整理出一份**稳定可信的参考文献列表**(不管是第一轮检索还是后续多轮补充检索合并后的结果)之后,调用归档脚本把它固化到项目级目录,而不是留在技能自己的`output/`里: +所以每次整理出一份**稳定可信的参考文献列表**(不管是第一轮检索还是后续多轮补充检索合并后的结果)之后,调用归档脚本把它固化到项目级目录,而不是留在草稿区里: ```bash -python3 scripts/archive_references.py "UAV aeromagnetic compensation" \ - --bib output/uav_aeromagnetic_compensation_final.bib \ +python3 .claude/skills/literature-search-verify/scripts/archive_references.py \ + "UAV aeromagnetic compensation" \ + --bib output/literature-search-verify/uav_aeromagnetic_compensation_final.bib \ --project-root . \ - --pdfs-dir output/pdfs \ + --pdfs-dir output/literature-search-verify/pdfs \ --suspect "某条可疑文献标题|不建议引用的具体原因" \ --notes "检索覆盖了哪些方向、哪些方向搜了但没结果、中文文献缺口提醒等" ``` diff --git a/.claude/skills/literature-search-verify/scripts/archive_references.py b/.claude/skills/literature-search-verify/scripts/archive_references.py index bc5b8d0..11ee0ba 100644 --- a/.claude/skills/literature-search-verify/scripts/archive_references.py +++ b/.claude/skills/literature-search-verify/scripts/archive_references.py @@ -13,11 +13,14 @@ what's there without re-reading the conversation that produced it. No third-party dependencies; uses only the standard library. -CLI usage: - python3 archive_references.py "UAV aeromagnetic compensation" \\ - --bib output/uav_aeromagnetic_compensation_final.bib \\ +CLI usage (run from the project root; scratch input lives under +output/literature-search-verify//, matching the slug this +script derives from the topic argument): + python3 .claude/skills/literature-search-verify/scripts/archive_references.py \\ + "UAV aeromagnetic compensation" \\ + --bib output/literature-search-verify/uav_aeromagnetic_compensation/uav_aeromagnetic_compensation_final.bib \\ --project-root . \\ - --pdfs-dir output/pdfs \\ + --pdfs-dir output/literature-search-verify/uav_aeromagnetic_compensation/pdfs \\ --suspect "Some fabricated-looking title|DOI resolves but venue is topically unrelated" \\ --notes "Kalman-filter and GA/PSO angles searched, no on-topic hits found." diff --git a/CLAUDE.md b/CLAUDE.md index 1e073bf..345e1a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,15 +7,18 @@ ## 目录结构 ``` -.claude/skills/ 所有 skill 的定义,每个子目录一个 skill +.claude/skills/ 所有 skill 的定义,每个子目录一个 skill,只放代码/说明 literature-search-verify/ 检索 + 反幻觉引用核查 SKILL.md skill 说明(frontmatter name 必须与目录名一致) scripts/ 纯标准库 Python 脚本,无第三方依赖 - output/ 脚本运行时草稿区,.gitignore 掉,不进版本库 paper-writing-grounded/ 论文写作(强制数据溯源) SKILL.md git-commit/ 规范化 commit message 生成与提交 SKILL.md +output/// 各 skill 运行时的草稿区,.gitignore 掉,不进版本库; + 按 skill 分子目录、同一 skill 内再按主题分子目录 + (topic-slug 规则和 references/ 下的目录名一致), + 避免不同 skill、不同主题的草稿互相覆盖/混堆 references// literature-search-verify 归档产出的稳定文献库 references.bib 已验证文献,写作阶段 \cite{} 直接复用这里的 key README.md 人可读索引,含 suspect/unverified 条目说明 @@ -30,8 +33,11 @@ references// literature-search-verify 归档产出的稳 2. **脚本优先于临场编 API 调用**:能写成 `scripts/` 里可重复运行的脚本就不要 指望模型每次现场拼 HTTP 请求——后者不可复现、容易在细节上出错。脚本只用 标准库,不引入第三方依赖,保证任何环境下拿来就能跑。 -3. **草稿区与交付物分离**:skill 自己的 `output/` 只是运行痕迹,不是可信的最终 - 产物;确认稳定后要显式归档到 `references//` 这类项目级目录,才算数。 +3. **草稿区与交付物分离**:草稿(项目根目录下的 `output///`) + 只是运行痕迹,不是可信的最终产物,也不放在 `.claude/skills/` 里面(那里只放 + skill 代码本身);确认稳定后要显式归档到 `references//` 这类项目级 + 目录,才算数。同一 skill 下不同主题的草稿必须分子目录,不能用无区分度的 + 通用文件名(如`t1.json`)散落在同一层——这类命名冲突曾经真实发生过。 4. **skill 之间通过约定(如 bibtex key)解耦协作**,而不是互相读对方内部状态; 每个 SKILL.md 末尾应有一节说明它和其他 skill 的配合方式。 5. **目录名必须和 SKILL.md frontmatter 里的 `name:` 完全一致**——skill 发现/ diff --git a/references/uav_aeromagnetic_compensation/README.md b/references/uav_aeromagnetic_compensation/README.md index fdc93e6..a61f693 100644 --- a/references/uav_aeromagnetic_compensation/README.md +++ b/references/uav_aeromagnetic_compensation/README.md @@ -53,4 +53,4 @@ Direction covered: UAV/airborne aeromagnetic compensation (Tolles-Lawson family) Queried via arXiv + Crossref + Semantic Scholar (S2 was rate-limited (HTTP 429) for much of the session, so most entries only got single-channel verification -- arXiv ID or DOI resolution -- rather than the additional cross-source title check; this is noted per-entry as "unverified"/"skipped" in the raw JSON reports, not silently upgraded to double-verified). Searched but found no on-topic hits: Kalman-filter-based aeromagnetic compensation; genetic-algorithm/PSO-based aeromagnetic compensation. Not covered at all: CNKI/Wanfang/VIP (Chinese databases, no public API) -- use the Zotero Connector browser extension logged into a university account for these. -Raw per-query JSON search/verification reports (including filtered-out noise from ambiguous keyword matches like "Tolles"/"Lawson" as surnames) are kept in .claude/skills/literature-search-verify/output/ for audit purposes and are not part of this archive. +Raw per-query JSON search/verification reports (including filtered-out noise from ambiguous keyword matches like "Tolles"/"Lawson" as surnames) are kept in output/literature-search-verify/uav_aeromagnetic_compensation/ for audit purposes and are not part of this archive.