cn-literature：中文文献检索与题录整理工作流

目的

把中文文献纳入与英文文献同一套 PaperDocument 产物体系。核心设计原则是 诚实设计：各中文数据库的能力边界差异很大，本技能对每个来源如实说明 "能做什么、不能做什么"，不假装有接口、不绕过平台限制。

各来源能力边界（必须先读再执行）：

• CNKI（知网）：无公开 API。本技能不绕过验证码、不批量抓取。 推荐工作流是"人工检索 + 题录导出 + 脚本解析"：用户在 CNKI 官网检索， 导出 Refworks 或 EndNote 格式题录文件，再用 scripts/parse_refworks.py 解析为 PaperDocument。
• 万方：有官方开放平台（api.wanfangdata.com.cn，按点计费）。 已配置 WANFANG_TOKEN 环境变量时，可用 scripts/wanfang_search.py 直接检索；未配置时走与 CNKI 相同的 人工导出流程。
• 维普 / 超星：无可用接口，请用户人工检索后把题录粘贴到会话中， 由你手工整理为 PaperDocument。

前置检查

1. 网络可用与否决定不了 CNKI 流程（其核心是本地解析），但万方直接 检索需要网络；离线时只做解析类工作。
2. 明确用户手里有什么：是"还没检索"（→ 引导官网检索）、"已有导出 文件"（→ 解析）、还是"已粘贴题录"（→ 手工整理）。
3. 检查 scripts/parse_refworks.py 与 scripts/wanfang_search.py 存在；python 可用。
4. 计算 slug：检索主题规范化（Unicode NFKC 规范化、转小写、去首尾空白、 连续空白折叠为单个空格）后取 sha1 十六进制摘要前 8 位。

操作规程

1. 按来源选择工作流

2. CNKI 人工导出引导（未检索时给用户的话术要点）

1. 在 CNKI 官网用检索主题完成检索并勾选目标文献；
2. 选择"导出与分析"→ 导出格式选 Refworks（次选 EndNote）；
3. 保存为 UTF-8 编码的 .txt 文件，放到工作区；
4. 把文件路径交给本技能。

如实告知：CNKI 导出的题录是仅元数据（metadata-only），不含全文； 全文需用户凭机构权限自行下载，本技能不代为获取。

3. 解析题录文件

python scripts/parse_refworks.py --input <题录.txt> --format json --origin CNKI

• --origin 填来源名（CNKI / 万方 / 维普 / 超星），写入每条的 source 字段，供下游按 guardrail 第 1 条标注 [CNKI]、[万方]。
• 脚本容错：未知标签跳过、缺字段留 null；解析结果逐条检查 title 是否 为空，空 title 的条目挑出来交用户核对，不静默丢弃。
• EndNote 格式（%0/%T/%A 标签）与 Refworks 格式（RT/T1/A1 标签）结构 类似；本脚本按 Refworks 标签解析，EndNote 导出文件请用户重新导出为 Refworks，或由你手工整理。

4. 万方直接检索（仅已配置 token 时）

python scripts/wanfang_search.py --query "<检索主题>" --limit 20 --format json

• token 从环境变量 WANFANG_TOKEN 读取；未配置时脚本输出 {"error": {"type": "auth_missing", ...}}，此时回到人工导出流程， 并把配置指引转告用户。
• 接口字段以万方开放平台官方文档为准；上游变更时脚本输出 upstream_changed 错误，如实转告用户，不自行猜字段修补结果。

5. 统一 PaperDocument 与标注规则

• 全部来源统一为： {id, title, authors, year, venue, doi, url, abstract, source, retrieved_at} （source 为字符串数组）。
• source 字段记录来源列表（如 ["CNKI"]、["万方"]）；写入任何 产物时按包根 CLAUDE.md guardrail 第 1 条在同句标注 [CNKI] / [万方]。
• 仅有元数据、无全文/无摘要的条目，在落盘 JSON 之外给用户的汇总中 明确标注 metadata-only，下游 literature-survey 引用时不得把 metadata-only 条目当作"已读原文"。
• 中文文献常缺 DOI：id 用 来源:sha1(标题+首作者)前8位 形式生成， 保证同批去重稳定。

6. 与英文检索结果合并（可选）

• 若同主题已有 literature-search 的 papers.json，按同一去重规则合并： ① DOI（统一小写、去 https://doi.org/ 前缀）；② 标题模糊匹配 （小写、去标点、折叠空白）。
• 中英文重复条目（同一工作的不同语言版本）一般不算重复，保留两条并 在 manifest 注明疑似同工作对，交用户判断。

7. 落盘

目录 output/cn-literature/<slug>/latest/：

• papers.json：PaperDocument 数组；
• manifest.json：主题、来源与各自条数、工作流类型（parse / api / manual）、metadata-only 条数、errors、执行时间。

输出模板

papers.json

[
  {
    "id": "CNKI:a1b2c3d4",
    "title": "钠离子电池层状氧化物正极材料研究进展",
    "authors": ["张三", "李四"],
    "year": 2023,
    "venue": "电化学",
    "doi": null,
    "url": null,
    "abstract": "钠离子电池因资源丰富……",
    "source": ["CNKI"],
    "retrieved_at": "2026-08-18T00:00:00+08:00"
  }
]

manifest.json

{
  "topic": "钠离子电池 正极材料",
  "slug": "1a2b3c4d",
  "workflow": {"CNKI": "parse", "万方": "api"},
  "counts": {"CNKI": 12, "万方": 8},
  "metadata_only": 20,
  "errors": [{"connector": "wanfang", "type": "auth_missing", "message": "WANFANG_TOKEN 未配置"}],
  "executed_at": "2026-08-18T00:00:00+08:00"
}

本技能不做什么

• 不绕过 CNKI 验证码、不批量抓取 CNKI 网页；无公开 API 就只用 "人工检索 + 导出 + 解析"流程。
• 不获取付费墙全文；题录为 metadata-only 时如实标注。
• 不在未配置 WANFANG_TOKEN 时假装能直连万方。
• 不处理维普/超星的自动化检索；只整理用户粘贴的题录。
• 不把"某库未检索到"表述为"该研究不存在"——中文库覆盖各有盲区。
• 不做综述分析（交给 literature-survey）；与英文结果合并后如需核验 引用，交给 citation-verify。

收尾与下一步

1. 汇总：各来源条数、metadata-only 条数、走了哪种工作流、失败及原因， 5 行内说明。
2. 指向 output/cn-literature/<slug>/latest/papers.json。
3. 建议下一步：与 literature-search 结果合并后运行 literature-survey； 或把 metadata-only 条目清单交给用户，由其凭机构权限补全文。
4. 若用户在 CNKI 导出环节遇到困难，回到第 2 步话术逐项排查（导出格式 是否选 Refworks、编码是否 UTF-8），不提议任何绕过平台限制的做法。