Skip to content

docs: rewrite README against verified code behavior - #2

Merged
keros68 merged 1 commit into
mainfrom
docs/readme-rewrite
Aug 1, 2026
Merged

docs: rewrite README against verified code behavior#2
keros68 merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@keros68

@keros68 keros68 commented Aug 1, 2026

Copy link
Copy Markdown
Owner

每条保留下来的事实都在这个仓库里找到了出处。核实手段:读 scripts/ 全部模块、直接查询 assets/sci_select_journals.sqlite、跑 77 项 unittest、跑索引审计、实跑一次单刊查询。

README 长度 12903 → 10530 字符(-18.4%),392 → 256 行。

与代码不符、已修正

「IF、JCR Q 区和收录类型……在线获取」 — 仓库里没有任何在线源产出 jcr_quartile。唯一生产者是 build_journal_index.py,也就是自建索引。内置库没有这个字段,letpub_client.py 不解析它,OpenAlex 分支也不写它。改为明确写出:JCR Q 区没有在线来源,只有自建索引才有。

「IF、收录类型或审稿速度缺失时才访问 LetPub」journal_metrics._selection_core_available 要求 ISSN + 收录类型 + 层级三者齐全才跳过 LetPub。内置库既无 ISSN 也无收录类型,OpenAlex 候选带 ISSN 但不带收录类型,所以选刊模式实际每个候选都会查 LetPub。

示例输出 SCIE | IF=7.2 | ... — 2026-08-01 实跑 get_journal_metrics("Environmental Pollution") 得到 SCIE | 实时IF≈7.2(非JIF) | NI=2026 | 2025中科院=2区 | 2026新锐=2区。LetPub 只给了 real_time_ifformat_metrics_line 因此走 实时IF≈ 分支。已换成实跑结果并标注日期和条件。

专家标注 适合 / 勉强 / 不适合benchmark_score.FIT_RELEVANCE 只认 suitable / borderline / unsuitable,标注表写中文会被判为不完整。

期刊层级「主要依据当前分区和 JCR」_journal_level 还有第三档:分区和 JCR Q 都缺时按 IF 判(>=8 高位、>=4 中位、>0 常规)。

「聚合站、个人页面和搜索摘要不能标成官网已核验」scope_evidence.py 实际强制的是:HTTPS、正文 >=120 字符、调用者显式确认域名,以及一份固定聚合站黑名单(openalex.org、letpub.com.cn、wikipedia.org、scansci.com/.cn)。它识别不了个人页面和搜索摘要。已按代码实际约束改写。

Python 3.10+ 徽章 — 仓库没有 pyproject.tomlsetup.pypython_requires,3.10 这个下界没有出处。CI 固定 3.12。徽章改成 Python 3.12 tested 并链到 workflow。

新增(都已核实)

  • 内置库 22657 本期刊、Nature Index 178 本(直接查 SQLite 得到;与 references/data-sources.md 的「177 期刊 + 1 会议录」一致)。
  • OPENALEX_MAILTOsimilar_works.py:52)和 XINRUI_API_KEYjournal_metrics.py:113)此前只出现在 references 里,README 的回退链没写。
  • 审计实跑结果 external_identity_gate_applicable: false,替代原文含糊的「显示为不适用」。
  • 硬筛选的坑_passes_selection_constraints 按字段值过滤,字段为空即淘汰。内置库没有 JCR Q 区,所以配内置库传 jcr_quartiles 会把结果清空;impact_low / impact_high 同样会剔除 IF 未获取的候选。这是真实行为,写进了「已知限制」。
  • agents/openai.yaml 存在但 README 从未提及,补进项目结构。
  • 测试数 77(实跑 python -m unittest discover -s tests,全绿)。

结构与文风

  • 开头从名词短语(「AI agent 用的……skill」)改成完整定义句。
  • 删掉「旧流程的主要问题不是……」那段设计沿革,属于 changelog 不属于 README。
  • 工作流原本讲了三遍(候选如何生成 编号步骤、工作流 ASCII 图、English 段),只留编号步骤。
  • 候选波动的原因 并入 已知限制项目定位 引用块与 边界 高度重复,合并。
  • ## English 小节里原本夹着大段中文示例(追加筛选条件、硬约束 API),已移回中文小节,English 只留摘要。
  • 加粗从 30 余处降到 6 处。

保留未动:所有承诺性表述(不打包原始 Excel、ShowJCR jcr.db、缓存)、边界条款、环境变量名、路径、命令。这些都逐条核实过。

我没能核实的(照实说明)

  1. 安装路径~/.claude/skills/~/.codex/skills/~/.agents/skills/ 都是外部工具约定,仓库里没有出处。改成「clone 到所用工具的 skills 目录」加一个 Claude Code 的具体例子,删掉了最没根据的「通用 agent 目录 ~/.agents/skills」。若确认 Codex 路径无误,可以加回去。
  2. $sci-select 触发语法同理,属于宿主工具约定,按原样保留。
  3. benchmarks/corpus_manifest.json 的 60 篇是否来自 60 本不同期刊。manifest 只存 DOI 和主题层(60 条、20 层、每层 3 篇,这三项已核实),刊名不在文件里。不同刊源是采样器 benchmark_dataset.pyused_journals 约束,所以措辞改成「采样器保证 60 篇来自不同期刊」。
  4. 同系列仓库链接指向外部仓库,未逐个访问。
  5. 内置库里还有 cas_top_2025(1789 条为 true)、open_access(5954 条)、xinrui_subject 三个字段,但 journal_index_client._to_metrics 不映射它们,运行时永远读不到。没有写进 README,写了等于承诺一个取不到的能力。要不要在 _to_metrics 里补上,是另一个 issue。

建议的仓库简介(未改动,请你决定)

中文:

面向 AI agent 的 SCI/SCIE/ESCI/SSCI 选刊 skill:查期刊公开指标,从摘要发现带证据的候选期刊

英文:

An AI-agent skill for SCI/SCIE/ESCI/SSCI journal lookup and evidence-backed candidate-journal discovery

验证

  • python -m unittest discover -s tests → Ran 77 tests, OK
  • python -m scripts.audit_journal_index assets/sci_select_journals.sqlite --sample-size 20 --max-severe-mismatch-rate 0.02 → 0 structural / 0 provenance errors, exit 0
  • Get-ChildItem scripts -Filter *.py | ForEach-Object { python -m py_compile $_.FullName } → exit 0(README 里的 PowerShell 命令逐字跑过)

README 里所有相对链接都检查过,全部存在。本 PR 只改 README.md

🤖 Generated with Claude Code

Every claim was re-checked against the code, the bundled SQLite index, and
actual runs (77 unittests, the index audit, a live single-journal lookup).
Length went from 12903 to 10530 characters.

Corrections where the README did not match the code:

- JCR Q 区 was listed as an online-fetched field. No source in this repo
  produces `jcr_quartile`: it comes only from build_journal_index.py, i.e.
  a user-built index. The bundled DB has none, LetPub does not parse one,
  and OpenAlex does not supply one.
- "IF、收录类型或审稿速度缺失时才访问 LetPub" was wrong. The skip gate in
  journal_metrics._selection_core_available needs ISSN + coverage type +
  standing all present; the bundled index carries neither ISSN nor coverage
  type, so selection mode queries LetPub for every candidate.
- The example metrics output showed `IF=7.2`. A real run prints
  `实时IF≈7.2(非JIF)` because LetPub returned only real_time_if. Replaced
  with the verified line and dated it.
- Expert labels were documented as `适合 / 勉强 / 不适合`. benchmark_score.py
  only accepts `suitable` / `borderline` / `unsuitable`.
- 期刊层级 was said to follow "分区和 JCR". _journal_level also falls back
  to raw IF when both are missing.
- Scope evidence rules were stated more broadly than the code enforces.
  scope_evidence.py requires HTTPS, >=120 chars, caller-confirmed domain,
  and rejects a fixed aggregator list; it does not detect personal pages
  or search snippets.
- The Python 3.10+ badge had no source in the repo. CI pins 3.12.

Added, all verified: bundled index size (22657 journals, 178 Nature Index
venues), OPENALEX_MAILTO, XINRUI_API_KEY on the fallback chain, the audit's
`external_identity_gate_applicable: false` result, test count, and the
hard-filter gotcha (missing fields drop candidates, so `jcr_quartiles` with
the bundled index returns nothing).

Structural cleanup: opened with a definition sentence instead of a noun
phrase, dropped the design-history paragraph and the duplicate workflow
diagram, merged 候选波动的原因 into 已知限制, and moved the Chinese examples
that were sitting under "## English" back into the Chinese sections.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings August 1, 2026 02:09

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR rewrites README.md to align the documentation with behavior verified from the repository’s actual scripts, bundled SQLite index, and CI validation workflow.

Changes:

  • Reorganized and tightened the README structure (installation, workflow, known limitations, and English summary).
  • Updated claims about data sources and fallbacks (LetPub/OpenAlex/local index), and refreshed example output to reflect observed runtime formatting.
  • Added/clarified operational details (environment variables, audit/test workflow link, and project structure overview).
Suppressed comments (1)

README.md:202

  • 同一段里这两行将部分脚本文件漏写了 scripts/ 前缀(audit_journal_index.py / benchmark_run.py / benchmark_score.py),与实际路径不符,读者按 README 可能找不到对应文件。
- `scripts/build_journal_index.py` / `audit_journal_index.py` — 索引构建与发布前审计。
- `scripts/benchmark_dataset.py` / `benchmark_run.py` / `benchmark_score.py` — 盲测数据、执行与评分。

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread README.md

print(format_finder_checklist(checklist))
```
`verify_official_scope` 要求 HTTPS 链接和至少 120 字符的正文,并由调用者显式确认域名属于期刊或出版社;openalex.org、letpub.com.cn、wikipedia.org、scansci 会被直接拒绝。程序本身不抓取出版社网站,不自动登录,也不绕过验证码。
Comment thread README.md
- `examples/demo-report.md` - 示例报告。
- `tests/` - 行为测试。
- `SKILL.md` — skill 主说明和触发规则;`agents/openai.yaml` — OpenAI 侧 agent 清单。
- `scripts/select_journals.py` — 主题识别、候选检索、排序和报告生成;`similar_works.py` — OpenAlex 相似论文召回;`scope_evidence.py` — 官网 scope 核验;`journal_metrics.py` — 单刊指标聚合;`profile_consistency.py` — 画像校验与跨模型一致性。
Comment thread README.md
| `tags` | 分区和 Nature Index 标签 |

内置库按标准化刊名匹配。为避免第三方表格的 ISSN 错位把一本期刊的 JIF/JCR 字段挂到另一本期刊,内置版本不再打包未经逐条核验的 ISSN、JIF、JCR Q 区和收录类型;这些字段在线获取,失败时明确显示未获取。用户自建且已核验的 SQLite/JSON 仍可提供完整字段
内置库不打包 ISSN、JIF、JCR Q 区和收录类型:第三方表格的 ISSN 错位会把一本期刊的 JCR 字段挂到另一本上,未逐条核验的字段一律不入库。ISSN、IF、收录类型和审稿速度由 LetPub 在线补充,缺失时显式标为未获取;**JCR Q 区没有在线来源,只有自建索引才会有这个字段**。仓库同样不打包原始 Excel、ShowJCR 的 `jcr.db` 或源码、运行缓存
@keros68
keros68 merged commit 2a4bd0e into main Aug 1, 2026
3 checks passed
@keros68
keros68 deleted the docs/readme-rewrite branch August 1, 2026 02:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants