# PaperX 插件

PaperX 将「文献精读」「文献追踪」「论文写作」「NSFC标书」和「基金查询」五个模块和 **Codex / WorkBuddy 当前会话中选择的模型**连接起来。插件包含本地 MCP 传输、`paperx` 技能、宿主插件清单和安装脚本；不需要模型 API Key，也不运行独立模型 CLI。

## 2.9.22：青研立项情报

基金查询已替换为青研的项目总览、综合检索、多维分布分析与收藏。首次打开时填写个人访问令牌，在线查询 `https://lxlnsfc.site`；知识库、解密密钥和原始名单均保存在服务端，不随插件分发。安装包本身不包含个人令牌，详见 [在线知识库说明](grant-atlas-online.md)。

## 从源码安装

在项目目录执行：

```sh
# Codex：生成本地插件并通过官方 CLI 注册和安装。
.venv/bin/python plugins/paperx/setup.py --host codex --install

# WorkBuddy：生成插件，合并当前项目的 MCP 配置，不改其他 MCP 服务。
.venv/bin/python plugins/paperx/setup.py --host workbuddy --install --workbuddy-project .
```

Codex 安装后重新加载插件或新建会话。WorkBuddy 在“插件 → MCP 服务器”确认 PaperX 已连接；然后通过“技能 → 添加技能 → 上传技能”导入安装命令输出的 `paperx-skill.zip`。同时提供 `.workbuddy-plugin/plugin.json`，可供支持本地插件市场的 WorkBuddy / CodeBuddy 版本使用。WorkBuddy UI 的最终加载状态需要在 WorkBuddy 中确认。

`setup.py` 默认仅生成配置；加 `--install` 才安装。WorkBuddy 不带 `--workbuddy-project` 时写入用户级 `~/.workbuddy/mcp.json`。原有 MCP 配置会备份并合并，不覆盖其他服务。

## 可分发插件包

在项目根目录执行：

```sh
python3 plugins/build.py
```

产物为 `dist/plugins/paperx-codex.zip`、`dist/plugins/paperx-workbuddy.zip`。每个包包含 Python 运行源码和前端静态资源；不包含 `.venv`、`node_modules`、文献库、配置、令牌、日志或密钥。

把压缩包解压到一个固定目录，在解压后的 `paperx-codex` 或 `paperx-workbuddy` 目录执行：

```sh
python3 setup.py --host codex --prepare-runtime --install
# 或
python3 setup.py --host workbuddy --prepare-runtime --install
```

需要 Python 3.10+。`--prepare-runtime` 创建虚拟环境并安装 PDF 处理依赖，首次需要联网下载 Python 包。依赖安装不是模型调用。数据默认保存在 `~/PaperX`，可用 `--home /absolute/data/path` 指定。安装会解析本机绝对路径，移动解压目录后需重新运行 setup。

## 自动提交与连接恢复

首次调用 `paperx_open` 后，宿主在当前对话挂载 PaperX 连接页签。支持 OpenAI MCP 扩展时，插件提供 thread entrypoint 并偏好 fullscreen 内容页签，减少内嵌聊天卡片滚出视野造成的卸载；显示方式最终由宿主决定。

本地网页的翻译、提问、追踪分析和写作请求会自动提交到这个对话，使用当前选择的模型。无需复制粘贴指令。协议 2 每条消息只派发一个请求，完成后再自动提交下一条；长任务每 20 分钟通过 `paperx_renew` 续租。默认领取租约为一小时，不通过后台心跳假称模型仍在执行。

绑定与传输状态分开保存。绑定会一直保留到主动退出或明确切换会话；短暂超时、网页切换和宿主后台暂停不会解除绑定，也不会把任务交给另一个会话。`connected` 只表示最近有真实通道活动，恢复期间如实显示“原会话已绑定，通道恢复中”。

同一面板重新挂载时，宿主重播原 `paperx_open` 工具结果，其中 UI-only `_meta["paperx/connection"]` 的专属恢复凭据让新实例接续原绑定。凭据不放入模型可见文本、公共状态或网页 URL。送达收据仅保存在该面板标识限定的 `sessionStorage`；不同工具调用各有独立凭据，不能用跨会话共享的本地存储自动接管。旧实例被接替后停止恢复，不与新实例相互抢回通道。

提交前先通过服务端 `begin` 原子获取发送许可。同一批次即使出现两个面板，也只有一次发送机会。已成功发送但后端 ACK 丢失时，只重试 ACK；发送结果不明确时保留任务且不盲重发。若后台收到实际领取记录，会据此恢复处理状态，不伪造送达 ACK。服务重启、通道超时和短暂工具错误会自动重连并重新握手。MCP stdio 的连接控制请求使用独立处理通道，慢速 DOI 核验、导入或普通工具不会阻塞心跳与确认。

“暂停自动提交”保留绑定；“退出插件连接”才主动撤销。宿主卸载面板不等于用户退出，同一原始面板恢复后可继续。要切换到另一会话，需明确点击“连接到此会话”；旧绑定不会因心跳过期被自动接管。宿主明确拒绝权限时仍须由用户在宿主内授权，插件不绕过权限机制。

**能力边界：**自动发送仍需要活跃的 MCP App View 以及 `serverTools`、`message.text` 能力。宿主完全冻结或销毁所有相关 View 时，没有 JavaScript 可以执行 `ui/message`；本地服务会继续保存待办与原绑定，面板恢复后继续。标准 MCP 服务没有在没有 View 时向任意当前对话主动发送消息的接口。插件不会创建新聊天、启动其他模型/CLI 或伪造“在线”来掩盖这一限制。恢复还依赖宿主保留并重播原工具结果；重新调用 `paperx_open` 会产生新面板，不会冒充旧面板。

WorkBuddy / CodeBuddy 使用标准 MCP Apps，并在 `ui/message` 中指定 `codebuddy.ai/sendMessageMode: "send"`。支持 OpenAI 消息扩展时明确使用 `target:"active",send:true`。两个宿主均只向所属当前对话发送，不向新聊天发送。WorkBuddy 本机未安装，原生 UI 行为以实际能力握手与验收为准。

从旧版升级到 2.8.0 需要一次宿主 MCP / 插件重载，使新工具参数、后台进程和 v2 面板资源一致；先完成正在领取的任务再升级。之后同一面板的正常卸载与恢复由协议处理，无需每项任务重新连接。

## 本地定时追踪

无需 Docker。计划、原始候选和报告位于数据目录 `tracking/`，使用 SQLite 存储，并另存 JSON / Markdown 报告。启用计划时，本地服务在网页关闭后继续运行；电脑休眠或服务退出期间暂停，恢复后每计划补跑一次。不会替用户默认创建研究计划或开机启动项。

采集与模型分析独立：未连接对话也会保存 RSS 与公共索引元数据，连接恢复后由同一个自动面板提交分析。输入 2–10 个关键词，至少匹配 2 个关键词且有相关证据才入选，匹配越多排序越靠前。高级选项支持调研数量 1–200 篇（默认 20），近 1–3650 天（新计划默认 30）或指定起止日期。RSS 联合 Crossref、Europe PMC 检索；每轮公共索引最多读取 600 条候选，不能保证穷尽时间窗。每批最多 4 篇交给当前会话选中的模型，未达门槛不会凑数，界面明确显示来源错误和截断。

记录可按未归档 / 已归档 / 全部筛选、分页，并支持单条或批量归档、恢复和删除。活动任务需先取消；删除清理本地报告但保留去重状态和已导入的精读文献。历史报告在查看时按至少 2 词的规则重新计算入选数，不会调用模型重跑。

报告用可点击图表展示关键词覆盖和组合匹配，优先推荐同时命中更多关键词的论文。推荐指数不是概率；逐词主观估计的乘积依赖条件独立近似，未经统计校准。历史报告使用标明来源的相关级别映射，不额外调用模型。

「导入精读」只收藏标题、DOI/原文链接、期刊、发表时间和作者等题录。用户在精读模块访问原文、自行下载后，为同一条目上传 PDF；导入题录与上传 PDF 均不自动翻译。已有记录会复用，重复 PDF 会提示现有文献入口。

每次追踪在提交宿主分析前，会与同一计划的昨日及全部历史记录对比。按 DOI、规范化链接，以及足够长的完整标题与第一作者识别重复；修改关键词、来源、时间范围或数量不会重置去重。归档、删除和服务重启后仍保留最小去重索引（文献标识、记录 ID 和执行时间），不再次分析已处理论文。上次因数量限制未纳入、或尚未成功分析的候选可在后续重试。报告展示历史重复、其中昨日重复、待分析重复与本轮新增数量；旧报告只展示原有统计，不伪造逐日快照。不同追踪计划独立比较。

## 本地工具与协议

- `paperx_open`：启动或复用服务并返回地址，`module` 选择 `reading` 文献精读、`tracking` 文献追踪、`writing` 论文写作或 `nsfc` NSFC标书。
- `paperx_status`、`paperx_list_papers`、`paperx_read_paper`：状态、文献库、论文数据。
- `paperx_import_pdf`、`paperx_translate`：导入用户选择的本地 PDF、排入翻译。
- `paperx_save_tracking_paper`：将指定追踪报告中的题录收藏到精读库，无全文下载或模型调用。
- `paperx_attach_pdf`：为已有题录附加用户选择的本地 PDF，保持 ID 和笔记，只做本地整理。
- `paperx_claim`、`paperx_read_request`、`paperx_complete`、`paperx_fail`、`paperx_renew`、`paperx_cancel`：恢复或领取、分页读取、提交、失败、续租、取消。
- `paperx_tracking_status`、`paperx_tracking_sources`：追踪计划/调度状态，以及可按名称、出版社和学科搜索的来源目录。
- `paperx_save_tracking_plan`、`paperx_toggle_tracking_plan`、`paperx_run_tracking`：创建/更新计划、启用/暂停、立即执行。关键词 2–10 项，单计划 RSS 来源最多 20 项；空来源列表使用默认 RSS，公共检索保持启用。
- `paperx_tracking_reports`：查看本地历史列表或某次完整报告，包括失败来源和分析范围，支持归档过滤及 offset 分页。
- `paperx_archive_tracking_report`、`paperx_delete_tracking_report`、`paperx_manage_tracking_reports`：归档 / 恢复、删除与批量整理；不会删除精读库文献。
- `paperx_dispatch`：仅供连接面板调用，维护会话绑定、派发与送达确认。
- `resources/list`、`resources/read`：自动连接面板，以及本 MCP 会话已领取的请求图片。

传输使用 newline-delimited JSON-RPC 2.0 stdio；stdout 只输出协议，错误写入 stderr。服务仅连接 loopback 地址，不跟随重定向、不经过 HTTP 代理。写入需要本地 `.server.json` 中的 `X-Token`；提交结果还需当前 MCP 连接的私有领取凭据或原领取令牌；不能仅凭请求 ID 或宿主名称接管其他连接的任务。图片限定在请求工作目录内。

下列 CLI 传输入口供宿主代理诊断协议、开发集成测试使用，不代替自动连接面板，也不需要用户逐项执行。这个脚本不调用模型，答案仍由当前会话生成：

```sh
python3 plugins/paperx/scripts/paperx_mcp.py --host codex --call paperx_status
python3 plugins/paperx/scripts/paperx_mcp.py --host codex --call paperx_claim
python3 plugins/paperx/scripts/paperx_mcp.py --host codex --call paperx_complete --arguments-file /tmp/paperx-result.json
```

每次 CLI 调用是新 MCP 连接，因此兼容入口仍需显式提供原领取令牌；常规原生工具由连接管理凭据，无需模型传入。`--arguments-file` 内容形如 `{"request_id":"…","claim_token":"…","result":"完整结果"}`。不要公开此文件，提交后删除。可用 `--project-root`、`--home` 明确指定本地项目与数据；`--no-autostart` 禁用自动启动。

## 结果提交与恢复

原生 MCP 正常流程只需 `paperx_claim({request_id})` 和 `paperx_complete({request_id,result})`。连接私下生成独立的随机领取凭据，服务端只保存摘要，不按 `codex` / `workbuddy` 名称共享身份。同一连接丢失 HTTP 领取响应时再次领取会恢复原任务，不误领下一项。重连本地服务保留这项能力；替换整个 MCP 进程则需短信息头中的原 `claim_token` 一次恢复，不能承诺没有可信会话身份的跨进程自动接管。宿主必须保持 MCP 连接的会话隔离，插件不自行猜测聊天身份。

领取结果先返回 ID、恢复令牌与租约。普通任务每页最多 12,000 字符；新版受控证据批次的完整提示不超过 20,000 字符时单页返回。模型通过 `paperx_read_request` 的 `next_offset` 读完剩余内容；原文不再同时重复放进两个 MCP 返回字段。任务给出的图片仍需全部查看。结果支持 JSON 对象或 JSON 文本，文本上限与服务端一致为 8 MiB，不再误用普通参数的 10,000 字符限制。

格式、候选 ID 或字段校验失败会保留原领取，直接修正同一请求的结果即可，不重跑追踪计划、不等待租约到期。已被服务端接受但响应丢失时，重复提交同一结果能确认完成；不同结果不能覆盖已完成任务。长任务仍需主动续租，后台进程在线不等于模型一直在执行。

## 已验证范围

已通过 34 项面板协议行为测试和 MCP stdio / HTTP / 持久队列及追踪工具测试，包括初始化与连接失败后自动恢复、慢发送期间独立心跳、后台恢复、单次自动消息、ACK 丢失仅重试确认、拒绝或超时不重复提交、能力缺失不标记已连接，以及资源 MIME / CSP / 应用工具可见性。还在独立本地测试服务上验证了安装插件的真实 Handler 连接与派发心跳。

```sh
node --test plugins/tests/widget.test.cjs
.venv/bin/python -m unittest discover -s plugins/tests -p "test_*.py" -q
.venv/bin/python -m unittest tests.server.test_plugin_mcp tests.server.test_tracking_plugin -q
```

新增 7 项真实 loopback 测试验证领取/提交响应被丢弃、后端重新加载、跨连接拒绝接管、原令牌恢复、长结果、分页完整性以及同一任务修正。

这些协议测试不等同于原生宿主端验收。恢复测试覆盖同一工具结果的重挂载、ACK 收据恢复、发送许可跨实例互斥、旧实例停止恢复、显式退出持久化和控制请求不被慢工具阻塞。生产中的真实任务不会为了测试而强制接管或重启；新版本原生验收应在活动任务结束后加载一致的 2.8.0 服务与面板。WorkBuddy 本机未安装，不能把协议测试视为其原生验收。

## 官方格式依据

核对日期：2026-10-08。

- [OpenAI：打包插件](https://developers.openai.com/plugins/build/plugins) — 支持 `.codex-plugin/plugin.json` 兼容格式、Skills、MCP 和本地 marketplace；本插件使用该已验证格式。
- [WorkBuddy：插件系统](https://www.codebuddy.cn/docs/workbuddy/Plugins) — 插件类型与市场入口。
- [WorkBuddy：MCP](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide) — 用户级 / 项目级 `mcp.json` 和 stdio command/args 配置。
- [WorkBuddy：技能](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) — 本地技能包的上传和启用。
- [腾讯云：插件 API 参考](https://cloud.tencent.com/document/product/1831/137036) — `.workbuddy-plugin/plugin.json`、Skills 和 MCP 组件字段。

- [CodeBuddy：MCP Apps](https://www.codebuddy.cn/docs/cli/mcp-apps) — `ui/message` 的 send / fill 语义、工具调用与宿主权限。
- [OpenAI：MCP 界面](https://developers.openai.com/plugins/build/chatgpt-ui) — 标准 UI 资源与 `ui/message`。
- [MCP Apps 协议](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) — 宿主能力握手和消息格式。

CodeBuddy 的 Channels 另有终端会话专用支持；未据此假定 WorkBuddy 桌面具备同样能力。当前自动提交实现选择标准 MCP Apps 桥，不调用 sampling 或独立模型。

- [OpenAI MCP Extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md) — 对话独立入口、显示模式偏好与当前对话消息语义；这些是宿主可选能力，不构成后台 View 生命周期保证。

## 原始论文链接

2.6.2 优先保留检索来源提供的出版社页面。旧报告点击“原始论文”时按 DOI 精确核对 Crossref / Europe PMC 元数据，并将成功解析的地址单独缓存七天；不会重新追踪或改写报告。原文查询超时时，在系统提供 curl 的情况下使用有时限、保持 HTTPS 证书校验的备用请求。无法取得直达地址时显示题录、DOI 和重试入口；出版社本身的登录或访问限制仍由出版社处理。

## 写作确认与引用（2.7.0）

重新生成计划前收集修改意向并保留原计划上下文；文献确认每页 10 篇，自动获取公开全文并分批阅读。无法获取的来源提供出版社跳转、PDF 文件上传和移除入口。图谱记录论文—原文证据—主张—实体的出处链，保留局限和待核对的跨文献差异。正文及图注按首次引用顺序统一预览与导出编号，未引用条目单独标注；原文解释仍需核对上下文。

## NSFC 标书（2.8.0）

打开 `/nsfc` 或调用 `paperx_open({module: "nsfc"})`。申请项目保存于本机独立的 `nsfc/` 目录，复用原有宿主自动派发，不引入新的模型接口、数据库服务或账户。

`paperx_nsfc_projects` 查看项目，`paperx_nsfc_catalog` 检索2026代码快照，`paperx_create_nsfc_project` 新建；`paperx_nsfc_task` 排队计划、推荐、章节草稿/修改、整合检查和模拟评审。用户采用计划后使用 `paperx_confirm_nsfc_plan` 确认，其他建议通过 `paperx_apply_nsfc_suggestion` 按版本采用。源码引用、证据、配图与历史版本继续沿用现有协议。产物为辅助草稿，不是可直接提交的正式申请书。