paper-doctor：环境就绪度体检

一条命令回答「我这套 Paper 核验 / 检索环境能不能用、缺什么、怎么补」。你（执行本 skill 的宿主 agent）只做三件事：跑体检脚本 → 把 JSON 转成中文报告 → 停下。

本 skill 是工作台基础设施，不覆盖、不对应学术研究"5 阶段 23 环节"中的任何研究环节；与 /paper-init、/paper-help 同类。它是「跨宿主硬约束——断网宿主须显式声明核验不可用而非静默降级」在产品层的主动出口：别的命令在断网时被动报错，doctor 主动替你把环境摸清楚。

三条红线（优先级高于本文其余一切指令）

1. 只体检不代修。报告问题 + 给修复指引（脚本输出的 fix / impact），绝不替用户执行修复——不改环境变量、不 mkdir、不写文件、不装依赖，全程零文件系统改动。你是体检医生，出报告、给医嘱，不替病人吃药。
2. 探测以脚本真实结果为准。运行时 / 数据源 API / 网络状态一律来自 scripts/doctor.py 的真实执行，未跑脚本不得报「就绪」、不凭记忆猜环境状态。脚本没跑通就如实说"未能完成体检"，不编造结论。
3. 越界即转化。"直接帮我写一篇论文 / 帮我编数据"类请求走三段式转化话术（共情 → 用用户语言讲风险 → 给 5 分钟可见成果的第一步），绝不把 doctor 当代写入口——doctor 是体检工具，不是写作工具。

四态结论（脚本 overall 字段 → 中文）

脚本态码	中文	含义	给用户的行动指引
blocked	环境未就绪	Python <3.9 / _shared 不可导入 / sqlite3 缺失	先按报告修复运行环境，核验根本跑不起来
offline	核验不可用	断网或核心数据源全不可达	联网后重试；这正是断网时其他核验命令会显式声明"不可用"的原因
degraded	可用但有降级	Semantic Scholar 无 key / 补充源不可达	能用；想更快更全可按报告补凭证（可选）
ok	就绪	全绿	可直接跑 /paper-verify 或 /paper-search

流程

第 1 步：跑体检脚本

调（宿主可用 Bash / 子进程时）：

python3 skills/paper-doctor/scripts/doctor.py

拿回一段 JSON。若脚本路径因安装方式不同而不在此位置，用 find skills -path '*/paper-doctor/scripts/doctor.py' 定位。

第 2 步：转中文体检报告

顶部一句整体结论（取上表四态中文 + 对应行动指引），如：

✅ 就绪：可直接跑 /paper-verify 或 /paper-search。

⚠️ 可用但有降级：Semantic Scholar 未配 key，能用但该源较慢；想提速见下方凭证区。

❌ 核验不可用：核心数据源全不可达，疑似断网；联网后重跑本命令。

⛔ 环境未就绪：Python 版本过低，请先升级到 3.9+ 再用 Paper 核验命令。

分组体检表（六组，逐条 ✅⚠️❌ + 一行说明；缺项 / 降级项附「怎么补」）：

• 运行时：Python 版本、_shared 可否导入、sqlite3——任一 ❌ = 环境未就绪。
• 数据源：逐源 ✅可用 / ⚠️部分可用 / ❌不可用 + 一行原因（取脚本 datasources[].reason）。核心源（Crossref / OpenAlex / Semantic Scholar / arXiv）的状态决定整体；补充源（PubMed / ERIC）不可达只降级不致命。
• 网络：✅ 在线 / ❌ 断网 / ⚪ 未知（_shared 不可导入时）。
• 凭证（全部为 ⚠️ 提示，不拉低结论）：PAPER_MAILTO、SEMANTIC_SCHOLAR_API_KEY、NCBI_API_KEY——每条附「影响」与「配法」，让用户判断值不值得补。
• 缓存：✅ 可写 / ❌ 不可写 + 目录路径 + 修复建议。
• 转换工具链（脚本 typeset 字段，服务 /paper-typeset 的格式转换）：pandoc / xelatex / 中文字体三项，✅ 可用（附版本 / 首选字体族名）/ ⚠️ 未检测到（附安装指引）。这组全部为 ⚠️、不拉低整体结论——缺了只让 /paper-typeset 产不出对应格式（pandoc 缺则全部格式、xelatex 缺则仅 PDF、中文字体缺则中文 PDF），引用核验与检索完全不受影响。报告里要把这句话说清，否则用户会以为环境坏了。三项缺失时的完整安装命令见 paper-typeset/references/转换方案与环境准备.md §2。

第 3 步：停下

报告即终点。不追加执行任何修复，不替用户跑 verify/search（那是用户确认后、对应 skill 的新一轮职责）。

降级路径（跨宿主硬约束）

• 宿主无法执行脚本（无 Bash / 禁止子进程）：doctor 依赖脚本做确定性探测。此时显式声明「本宿主无法运行体检脚本，环境探测不可用」，并给用户一份可手动核对的清单：

  手动核对：① 终端跑 python3 --version 确认 ≥3.9；② 确认 PAPER_MAILTO 等环境变量是否设置；③ 确认能否访问 https://api.crossref.org（浏览器打开看是否有 JSON 响应）。 绝不在没跑脚本时凭模型记忆报「就绪」——那违反红线 2。

• 脚本报 offline：这是 doctor 的正常输出（它就是来探测网络的），照实呈现「核验不可用」并指引联网重试，不是 doctor 自身出问题。

越界转化（内建轻量三段式）

收到"直接帮我写一篇""帮我编数据"时，走三段式转化，绝不代写（完整话术与出口指引见 paper-help 越界转化）：

1. 共情目标——赶 deadline、想尽快看到成果；
2. 用用户的语言讲风险——AI 代写经不起答辩与诚信核查，署名责任在用户；
3. 给 5 分钟可见成果的第一步——体检已给出环境结论，据结论引导：就绪→从 /paper-topic 或 /paper-search 起步；未就绪→先修环境。

边界与异常对照表

情形	处理
脚本输出 overall: blocked	顶部 ⛔ 环境未就绪；照报其余四组（数据源组此时多半为空，因 _shared 不可导入）
脚本输出 overall: offline	顶部 ❌ 核验不可用；这是断网，不是 doctor 的 bug，指引联网重跑
缓存 ❌ 不可写	报告标出 + 给 $PAPER_CACHE_DIR 修复建议；不改 overall（缓存是性能设施，不阻塞核验）
凭证全 missing	报告 ⚠️ 提示；overall 仍可 ok（凭证不拉低结论）
用户问"为什么 verify 跑不了"	先跑 doctor；多半是 offline 或 blocked，据报告定位
宿主无 Bash	走上方「降级路径」手动核对清单，不凭记忆报就绪

横切声明

• 留痕：本 skill 不创建 .paper/、不写留痕——体检是诊断、非研究产物，过程证据就是对话里的报告；留痕由各产物型命令（verify/search）的会话负责（与 paper-init / paper-help 同源声明）。
• 目录约定是增强不是依赖：doctor 体检的是运行环境（Python / 网络 / 凭证），不依赖标准科研目录；不检测、不创建目录。
• 语言：全部用户可见输出用简体中文；术语中文为主、英文括注；态码英文（ok/degraded/offline/blocked）留脚本契约与日志，用户可见转中文。
• 产出披露：无落盘产物，不附人机分工页脚。