Paper Doctor

---
name: paper-doctor
description: Paper 环境就绪度体检命令。当用户要检查 Paper 核验/检索环境能不能用、数据源通不通、凭证配没配、运行环境是否满足要求，或说 doctor / 体检 / 自检 / 环境检查 / 能不能用 / 跑不跑得起来 / 为什么核验不了 时使用——即使用户只说"这个工具到底能不能用"也应使用。行为铁律：跑一次体检脚本、转成中文报告、只体检不代修。一条命令查清运行环境、数据源 API、网络、凭证、缓存五维就绪度，给四态结论（环境未就绪/核验不可用/可用但有降级/就绪）。
---

# 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 / 子进程时）：

```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`](../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` 越界转化](../paper-help/SKILL.md)）：

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`）留脚本契约与日志，用户可见转中文。
- **产出披露**：无落盘产物，不附人机分工页脚。