papilot 0.6.0 → 0.8.0

package/README.md

@@ -1,13 +1,14 @@
 <div align="center">
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
-  <img src="docs/assets/logo.svg" width="104" height="104" alt="Papilot logo">
-</picture>
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <img src="docs/assets/logo.svg" width="48" height="48" align="absmiddle" alt="Papilot logo">
+  </picture>
+  Papilot
+</h1>
 
-<h1>Papilot</h1>
-
-<p><b>A Cursor-like workspace for your papers:<br>annotate and review PDFs directly without ever touching LaTeX.</b></p>
+<p><b>A Cursor-like workspace for your papers: annotate and review PDFs directly without ever touching LaTeX.</b></p>
 
 <p>English · <a href="README.zh-CN.md">简体中文</a></p>
 
@@ -20,51 +21,64 @@
 [![LaTeX](https://img.shields.io/badge/LaTeX-008080?logo=latex&logoColor=white)](https://www.latex-project.org)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-22c55e)](https://github.com/cu1ch3n/papilot/pulls)
 
-[![Codex](https://img.shields.io/badge/Codex-supported-10A37F?logo=openai&logoColor=white)](#-agents)
-[![Claude](https://img.shields.io/badge/Claude-supported-D97757?logo=claude&logoColor=white)](#-agents)
-[![Antigravity](https://img.shields.io/badge/Antigravity-supported-4285F4?logo=google&logoColor=white)](#-agents)
-
-<br>
+**Contents:** [Features](#-features) · [Quick start](#-quick-start) · [Agents](#-agents) · [Documentation](#-documentation) · [Community](#-community) · [Friends](#-friends) · [License](#-license)
 
-<img src="docs/assets/demo.gif" alt="Papilot: describe a revision, review the typeset diff, read the PDF, annotate it and commit" width="100%">
+<img src="docs/assets/demo.gif" alt="Papilot: mark up a passage of the PDF, hand it to an agent, accept the typeset change and commit it" width="100%">
 
 </div>
 
-<br>
-
 You read and mark up the PDF the way a supervisor marks up a draft. An AI agent makes the edits in LaTeX, and every change comes back to you as a before-and-after of the typeset page. Nothing touches your paper until you accept it.
 
+> [!TIP]
+> **New in 0.7:** a redesigned workspace, color-grouped notes, files and images in tasks, a skill library, and a choice of where accepted changes go. See the [changelog](CHANGELOG.md).
+
 ## ✨ Features
 
 <table>
 <tr>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-note.png" alt="A note on a selected passage of the PDF">
+<img src="docs/assets/readme-note.jpg" alt="Two passages in a yellow note group and a region note on an equation">
 <h3>📝 Mark up the PDF</h3>
-Select a sentence or circle an equation and say what should change. SyncTeX hands the agent the exact LaTeX lines.
+Select a sentence or box an equation and say what should change. SyncTeX hands the agent the exact LaTeX lines. Color related notes into a group and give the whole group one instruction.
 </td>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-review.png" alt="A change shown before and after, with Accept and Reject">
+<img src="docs/assets/readme-review.jpg" alt="A change shown before and after on the typeset page, with Accept, Reject and Comment">
 <h3>✅ Approve change by change</h3>
-Each edit comes back as a typeset diff. Accept, reject or comment on it, and undo any decision.
+Each edit comes back as a typeset diff, together with the places it moves elsewhere, such as renumbered equations and the table of contents. Accept, reject or comment, and undo any decision.
 </td>
 </tr>
 <tr>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-contents.png" alt="The PDF viewer with its contents menu open">
+<img src="docs/assets/readme-deliver.jpg" alt="The finished review with an agent-written commit message, Apply to working directory and Commit">
+<h3>📦 Choose where it goes</h3>
+Accepted changes stay inside the task until you finish reviewing. Then apply them to your working directory, or commit them to a separate <code>papilot/…</code> branch with a message the agent writes.
+</td>
+<td width="50%" valign="top">
+<img src="docs/assets/readme-git.jpg" alt="The Git panel with a staged file, a generated commit message, task worktrees and the commit graph">
+<h3>🌿 Git without leaving the page</h3>
+Stage files and commit them with a message an agent writes, then pull and push. Every task's worktree shows in the commit graph, and an agent can resolve conflicts when you merge a co-author's changes.
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="docs/assets/readme-contents.jpg" alt="The PDF viewer with its contents panel open">
 <h3>📖 Read it like a real PDF</h3>
 Jump to any section from the contents, search every page and zoom in sharply. Selecting text picks exactly the printed words.
 </td>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-git.png" alt="The Git panel with a diff and a commit message">
-<h3>🌿 Commit when you're happy</h3>
-Diff files and commit the ones you choose, with a commit message an agent writes. Pull and push, or merge a coauthor's changes and let an agent resolve the conflicts.
+<h3>🧰 And more</h3>
+<ul>
+<li>✨ <b>Skills</b> such as Polish, Proofread and Check math, one <code>/</code> away. Write your own in Settings.</li>
+<li>📎 <b>Files and images</b> attached to any task or message</li>
+<li>🤖 <b>Codex, Claude, Cursor, Kimi Code, GLM, DeepSeek, Qwen Code, OpenCode or Antigravity</b>: whichever is on your computer, with your own login</li>
+<li>🌳 <b>A Git worktree for every task</b>, up to two running at once</li>
+<li>🌗 <b>Light and dark</b>, in English or Chinese</li>
+<li>📱 <b>Runs on your computer</b>, and you can open it from your phone</li>
+</ul>
 </td>
 </tr>
 </table>
 
-Also: ✨ **skills** such as Polish, Proofread and Check math, one `/` away, plus your own · 🤖 **Codex, Claude or Antigravity**, each with your own login · 🌳 **every task in its own Git worktree**, up to two at once · 🌗 **light and dark** · 📱 **runs on your computer**, and you can open it from your phone.
-
 ## 🚀 Quick start
 
 > [!NOTE]
@@ -75,19 +89,27 @@ npm install -g papilot
 papilot demo
 ```
 
-Open **http://127.0.0.1:7274** and choose **PDF** in the sidebar. The demo adds an example paper to revise: a 26-page LaTeX paper about Papilot itself, full of equations. When you are ready, run `papilot` and choose **Add paper** to add any LaTeX project in a Git repository.
+Open **http://127.0.0.1:7274** and choose **Manuscript** in the sidebar. The demo adds an example paper to revise: a 26-page LaTeX paper about Papilot itself, full of equations. When you are ready, run `papilot` and choose **Add paper…** from the paper menu to select a LaTeX folder or drop a ZIP. Papilot identifies the main file, prepares Git history and tries compilation, with help for any errors during import.
 
 ## 🤖 Agents
 
 | Agent | Sign in once | How Papilot runs it |
 | --- | --- | --- |
 | **Codex** | `papilot codex login` | Through the Codex app server, in its workspace sandbox. Papilot uses your `codex` if you have one, or installs it on first start. |
-| **Claude** | Start `papilot` with `ANTHROPIC_API_KEY` set | Through the Claude Agent SDK, downloaded the first time. The SDK does not accept a Pro or Max subscription login. |
+| **Claude** | Install [Claude Code](https://code.claude.com) and run `claude auth login`, or start `papilot` with `ANTHROPIC_API_KEY` set | With Claude Code installed, runs `claude -p` on your own login (your Claude plan or a key), in Claude Code's sandbox. Without it, through the Claude Agent SDK, which needs an API key. |
+| **Cursor** | Start `papilot` with `CURSOR_API_KEY` set | Through the Cursor SDK, downloaded the first time, in Cursor's sandbox. The SDK does not use the Cursor app or CLI login. |
+| **Kimi Code** | Install [Kimi Code CLI](https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started) and run `kimi login` | Runs `kimi acp` with your local configuration; streams replies, resumes sessions and forwards tool approvals. |
+| **GLM** | Start `papilot` with `ZHIPU_API_KEY` (or `ZAI_API_KEY`) set | Claude Code on Zhipu's Anthropic-compatible endpoint, as Zhipu documents for GLM Coding Plan. |
+| **DeepSeek** | Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`npm install -g @deepseek-ai/dsh`) and set up a model in it | Runs `dsh acp` in its workspace sandbox; anything outside the worktree asks for approval. |
+| **Qwen Code** | Install [Qwen Code](https://github.com/QwenLM/qwen-code) and sign in by running `qwen` | Runs `qwen --acp` in Auto Edit mode: edits go ahead, commands ask for approval. |
+| **OpenCode** | Install [OpenCode](https://opencode.ai) and connect a provider with `opencode auth login` | Runs `opencode acp` with your providers; commands and anything outside the worktree ask for approval. |
 | **Antigravity** | Install Antigravity and sign in to `agy` | `agy -p`, one process per turn, editing files only. If your region needs it, set `PAPILOT_AGY_PROXY`. |
 
-Papilot never reads, stores or forwards your credentials. An agent that isn't installed or signed in shows as unavailable.
+Papilot finds the agents on your computer by itself and offers only those; Codex is always there. After installing or signing in to one while Papilot is running, select **Reconnect**. If a CLI is not on the server’s `PATH`, point `PAPILOT_KIMI_BIN`, `PAPILOT_DSH_BIN`, `PAPILOT_QWEN_BIN` or `PAPILOT_OPENCODE_BIN` at it. See the [agent guide](docs/guide.md#agents) for what each one supports and the tested versions.
 
-Having trouble getting started? Run `papilot doctor` for environment checks and fixes, or `papilot doctor --repo /path/to/paper` to check a paper too. Add `--json` for a machine-readable report. Diagnostics do not install software, start the server or change your paper. See the [diagnostics guide](docs/guide.md#diagnostics) for what is checked.
+Papilot never stores your credentials. CLI agents use their own login, and a key you set for Claude, Cursor or GLM goes only to that service. An agent that is found but not signed in shows as unavailable.
+
+Having trouble getting started? Open **Settings → Runtime** and choose **Agents** for agent setup or **LaTeX** for the detected distribution, version, and location, or run `papilot doctor` for environment checks and fixes and `papilot doctor --repo /path/to/paper` to check a paper too. Add `--json` for a machine-readable report. Diagnostics do not install software, start the server or change your paper. See the [diagnostics guide](docs/guide.md#diagnostics) for what is checked.
 
 <details>
 <summary><b>⚙️ Options and remote access</b></summary>
@@ -101,9 +123,11 @@ papilot service install        # macOS: start after login, restart if it exits
 npm uninstall -g papilot       # remove it; your state stays in ~/.papilot until you delete it
 ```
 
+When a release is available, **New version** appears next to **Settings**. Click it to install from the browser. Papilot waits for tasks and PDF builds to finish, restarts, and reconnects the page. Updates keep your data and preserve the previous installation for rollback. See [Updates](docs/guide.md#updates).
+
 Papilot listens only on `127.0.0.1`. To use it from another device, publish it on your tailnet with Tailscale Serve and set `PAPILOT_PUBLIC_ORIGIN` and `PAPILOT_TAILSCALE_LOGIN`. Papilot then checks the host, the browser origin and the Tailscale identity of every request. The [guide](docs/guide.md#remote-access-with-tailscale) has the steps.
 
-To invite an advisor or co-authors, give Papilot a public HTTPS address with `PAPILOT_ACCOUNT_ORIGIN` and open **People**: each person signs in with a passkey and sees only the papers you share. Invite only people you would trust with access to the computer Papilot runs on; see [Collaborators](docs/guide.md#collaborators).
+To invite an advisor or co-authors, give Papilot a public HTTPS address with `PAPILOT_ACCOUNT_ORIGIN` and open **Settings → Sharing**: each person signs in with a passkey and sees only the papers you share. Invite only people you would trust with access to the computer Papilot runs on; see [Collaborators](docs/guide.md#collaborators).
 
 </details>
 
@@ -136,6 +160,10 @@ If Papilot saves you time on a paper, a ⭐ helps other researchers find it.
 
 <a href="https://github.com/cu1ch3n/papilot/graphs/contributors"><img src="https://contrib.rocks/image?repo=cu1ch3n/papilot" alt="Papilot contributors"></a>
 
+## 🔗 Friends
+
+[LINUX DO](https://linux.do/)
+
 ## 📄 License
 
 [MIT](LICENSE) © 2026 Cui Chen. The bundled review engine in [`vendor/latex-review`](vendor/latex-review) is also MIT-licensed.

package/README.zh-CN.md

@@ -1,13 +1,14 @@
 <div align="center">
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
-  <img src="docs/assets/logo.svg" width="104" height="104" alt="Papilot 标志">
-</picture>
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <img src="docs/assets/logo.svg" width="48" height="48" align="absmiddle" alt="Papilot 标志">
+  </picture>
+  Papilot
+</h1>
 
-<h1>Papilot</h1>
-
-<p><b>像 Cursor 一样改论文：<br>直接在 PDF 上批注和审阅，完全不用碰 LaTeX。</b></p>
+<p><b>像 Cursor 一样改论文：直接在 PDF 上批注和审阅，完全不用碰 LaTeX。</b></p>
 
 <p><a href="README.md">English</a> · 简体中文</p>
 
@@ -20,51 +21,64 @@
 [![LaTeX](https://img.shields.io/badge/LaTeX-008080?logo=latex&logoColor=white)](https://www.latex-project.org)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-22c55e)](https://github.com/cu1ch3n/papilot/pulls)
 
-[![Codex](https://img.shields.io/badge/Codex-supported-10A37F?logo=openai&logoColor=white)](#-智能体)
-[![Claude](https://img.shields.io/badge/Claude-supported-D97757?logo=claude&logoColor=white)](#-智能体)
-[![Antigravity](https://img.shields.io/badge/Antigravity-supported-4285F4?logo=google&logoColor=white)](#-智能体)
-
-<br>
+**目录：** [功能](#-功能) · [快速开始](#-快速开始) · [智能体](#-智能体) · [文档](#-文档) · [社区](#-社区) · [友情链接](#-友情链接) · [许可证](#-许可证)
 
-<img src="docs/assets/demo.gif" alt="Papilot：描述修改、审阅排版后的差异、阅读 PDF、在页面上批注并提交" width="100%">
+<img src="docs/assets/demo.gif" alt="Papilot：在 PDF 上批注一段文字，交给智能体，接受排版后的改动并提交" width="100%">
 
 </div>
 
-<br>
-
 你像导师批改学生的稿子一样，直接在 PDF 上阅读和批注；AI 智能体去改 LaTeX，每一处改动都以排版后修改前后的对比回到你面前。你点头之前，论文一个字都不会变。
 
+> [!TIP]
+> **0.7 新功能**：全新设计的工作台、按颜色分组的批注、任务中附带文件和图片、技能库，以及接受的改动保存到哪里由你选择。详见[更新日志](CHANGELOG.md)。
+
 ## ✨ 功能
 
 <table>
 <tr>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-note.png" alt="在 PDF 选中的段落上写批注">
+<img src="docs/assets/readme-note.zh-CN.jpg" alt="两段文字在黄色批注组里，一个公式上有区域批注">
 <h3>📝 在 PDF 上批注</h3>
-选中一句话或框出一个公式，写下要怎么改。SyncTeX 会把对应的 LaTeX 行准确交给智能体。
+选中一句话或框出一个公式，写下要怎么改。SyncTeX 会把对应的 LaTeX 行准确交给智能体。相关的批注可以用颜色归成一组，整组只写一条要求。
 </td>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-review.png" alt="改动的修改前后对比，带接受和拒绝按钮">
+<img src="docs/assets/readme-review.zh-CN.jpg" alt="排版页面上改动的修改前后对比，带接受、拒绝和评论按钮">
 <h3>✅ 逐条点头</h3>
-每处改动都以排版后的差异呈现。接受、拒绝或评论，任何决定都能撤销。
+每处改动都以排版后的差异呈现，连同它在别处引起的变化，比如重新编号的公式和目录。接受、拒绝或评论，任何决定都能撤销。
 </td>
 </tr>
 <tr>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-contents.png" alt="打开目录菜单的 PDF 阅读器">
+<img src="docs/assets/readme-deliver.zh-CN.jpg" alt="审阅结束后，带智能体写好的提交信息，以及「应用到工作目录」和「提交」按钮">
+<h3>📦 改动去哪由你定</h3>
+审阅结束前，接受的改动只保存在任务里。之后可以应用到工作目录，也可以提交到独立的 <code>papilot/…</code> 分支，提交信息由智能体来写。
+</td>
+<td width="50%" valign="top">
+<img src="docs/assets/readme-git.zh-CN.jpg" alt="Git 面板：已暂存的文件、自动生成的提交信息、任务工作树和提交关系图">
+<h3>🌿 不离开页面用 Git</h3>
+暂存文件，让智能体写提交信息，再 pull、push。每个任务的工作树都显示在提交关系图里；合并合作者的改动时，冲突可以交给智能体解决。
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="docs/assets/readme-contents.zh-CN.jpg" alt="打开目录面板的 PDF 阅读器">
 <h3>📖 像本地 PDF 一样阅读</h3>
 用目录随意跳转，全文搜索，缩放清晰。选中的文字与印出的词完全对齐。
 </td>
 <td width="50%" valign="top">
-<img src="docs/assets/feature-git.png" alt="带差异和提交信息的 Git 面板">
-<h3>🌿 满意了再提交</h3>
-查看差异，只提交你勾选的文件，提交信息可以让 agent 来写。可以 pull、push，也可以合并合作者的改动，冲突交给 agent 解决。
+<h3>🧰 还有</h3>
+<ul>
+<li>✨ <b>技能（skill）</b>，如润色、校对、检查数学，输入 <code>/</code> 即可选用，也能在设置里写你自己的</li>
+<li>📎 任务和消息都能附带<b>文件和图片</b></li>
+<li>🤖 <b>Codex、Claude、Cursor、Kimi Code、GLM、DeepSeek、Qwen Code、OpenCode 或 Antigravity</b>：电脑上装了哪个就用哪个，各用你自己的登录</li>
+<li>🌳 <b>每个任务都有独立的 Git 工作树</b>，最多两个同时运行</li>
+<li>🌗 <b>浅色与深色</b>，界面支持中文和英文</li>
+<li>📱 <b>运行在你的电脑上</b>，也能用手机打开</li>
+</ul>
 </td>
 </tr>
 </table>
 
-此外：✨ **技能（skill）**，如润色、校对、检查数学，输入 `/` 即可选用，也能添加你自己的 · 🤖 **Codex、Claude 或 Antigravity**，各用你自己的登录 · 🌳 **每个任务都有独立的 Git 工作树**，最多两个同时运行 · 🌗 **浅色与深色** · 📱 **运行在你的电脑上**，也能用手机打开。
-
 ## 🚀 快速开始
 
 > [!NOTE]
@@ -75,19 +89,27 @@ npm install -g papilot
 papilot demo
 ```
 
-打开 **http://127.0.0.1:7274**，在侧栏选择 **PDF**。demo 会添加一篇示例论文供你修改：一篇讲 Papilot 本身的 26 页 LaTeX 论文，满是公式。准备好之后，运行 `papilot`，选择 **Add paper**，即可添加任何放在 Git 仓库里的 LaTeX 项目。
+打开 **http://127.0.0.1:7274**，在侧栏选择 **稿件**。demo 会添加一篇示例论文供你修改：一篇讲 Papilot 本身的 26 页 LaTeX 论文，满是公式。准备好之后，运行 `papilot`，在论文菜单中选择 **添加论文…**，选择 LaTeX 文件夹或拖入 ZIP。Papilot 会识别主文件、准备 Git 历史并尝试编译，遇到问题可在导入窗口中重试或请求助手修复。
 
 ## 🤖 智能体
 
 | 智能体 | 登录（一次即可） | Papilot 如何运行它 |
 | --- | --- | --- |
 | **Codex** | `papilot codex login` | 通过 Codex app server 在其工作区沙箱中运行；已装有 `codex` 就直接用，没有则在首次启动时自动安装。 |
-| **Claude** | 设置好 `ANTHROPIC_API_KEY` 再启动 `papilot` | 通过 Claude Agent SDK 运行，首次使用时下载；该 SDK 不接受 Pro 或 Max 订阅登录。 |
+| **Claude** | 安装 [Claude Code](https://code.claude.com) 并运行 `claude auth login`，或设置好 `ANTHROPIC_API_KEY` 再启动 `papilot` | 装了 Claude Code 时，用你自己的登录（Claude 订阅或密钥）运行 `claude -p`，在 Claude Code 的沙箱中工作；没装时通过 Claude Agent SDK 运行，需要 API 密钥。 |
+| **Cursor** | 设置好 `CURSOR_API_KEY` 再启动 `papilot` | 通过 Cursor SDK 在 Cursor 的沙箱中运行，首次使用时下载；该 SDK 不使用 Cursor 应用或 CLI 的登录。 |
+| **Kimi Code** | 安装 [Kimi Code CLI](https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started)，运行 `kimi login` | 通过 `kimi acp` 使用本机配置，支持流式回复、会话恢复和工具审批。 |
+| **GLM** | 设置好 `ZHIPU_API_KEY`（或 `ZAI_API_KEY`）再启动 `papilot` | 按智谱为 GLM Coding Plan 给出的方式，让 Claude Code 连接智谱的 Anthropic 兼容接口。 |
+| **DeepSeek** | 安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`npm install -g @deepseek-ai/dsh`）并在其中配置好模型 | 通过 `dsh acp` 在其工作区沙箱中运行；工作树以外的操作需要审批。 |
+| **Qwen Code** | 安装 [Qwen Code](https://github.com/QwenLM/qwen-code)，运行 `qwen` 登录 | 以自动编辑模式运行 `qwen --acp`：改文件直接进行，运行命令需要审批。 |
+| **OpenCode** | 安装 [OpenCode](https://opencode.ai)，用 `opencode auth login` 连接模型服务商 | 用你配置的服务商运行 `opencode acp`；运行命令和工作树以外的操作需要审批。 |
 | **Antigravity** | 安装 Antigravity 并登录 `agy` | 运行 `agy -p`，每轮一个进程，只编辑文件；所在地区需要代理时设置 `PAPILOT_AGY_PROXY`。 |
 
-Papilot 从不读取、保存或转发你的凭据。没有安装或没有登录的智能体会显示为不可用。
+Papilot 会自动找出电脑上已有的智能体，只列出这些；Codex 始终可用。Papilot 运行期间安装或登录了新的智能体，点击 **重新连接** 即可。如果服务找不到 CLI，可以用 `PAPILOT_KIMI_BIN`、`PAPILOT_DSH_BIN`、`PAPILOT_QWEN_BIN` 或 `PAPILOT_OPENCODE_BIN` 指定其路径。各智能体支持的功能和已验证的版本见[智能体指南](docs/guide.md#agents)。
 
-启动遇到问题？运行 `papilot doctor` 检查环境并查看修复建议，或用 `papilot doctor --repo /path/to/paper` 一并检查论文。加上 `--json` 可输出机器可读的报告。诊断不会安装软件、启动服务或修改论文。检查范围见[诊断指南](docs/guide.md#diagnostics)。
+Papilot 从不保存你的凭据。CLI 智能体使用各自的登录；为 Claude、Cursor 或 GLM 设置的密钥只会交给对应的服务。已找到但没有登录的智能体会显示为不可用。
+
+启动遇到问题？打开 **设置 → 运行环境**，在**智能体**中查看智能体配置，或在 **LaTeX** 中查看识别到的发行版、版本和位置，或运行 `papilot doctor` 检查环境并查看修复建议，用 `papilot doctor --repo /path/to/paper` 一并检查论文。加上 `--json` 可输出机器可读的报告。诊断不会安装软件、启动服务或修改论文。检查范围见[诊断指南](docs/guide.md#diagnostics)。
 
 <details>
 <summary><b>⚙️ 选项与远程访问</b></summary>
@@ -101,9 +123,11 @@ papilot service install        # macOS：登录后自动启动，退出后自动
 npm uninstall -g papilot       # 卸载；状态仍保留在 ~/.papilot，可自行删除
 ```
 
+有新版本时，**设置** 旁会出现 **有新版本**，点击即可在浏览器中安装。Papilot 会等任务和 PDF 编译结束后重启，并重新连接页面。更新会保留你的数据，也会保留上一版安装以便回滚。详见[更新](docs/guide.md#updates)。
+
 Papilot 只监听 `127.0.0.1`。若要从其他设备访问，用 Tailscale Serve 把它发布到你的 tailnet，并设置 `PAPILOT_PUBLIC_ORIGIN` 和 `PAPILOT_TAILSCALE_LOGIN`；Papilot 会校验每个请求的主机、浏览器来源和 Tailscale 身份。具体步骤见[指南](docs/guide.md#remote-access-with-tailscale)。
 
-要邀请导师或合作者，用 `PAPILOT_ACCOUNT_ORIGIN` 给 Papilot 一个公开的 HTTPS 地址，然后打开 **成员**：每个人用通行密钥登录，只能看到你共享的论文。只邀请你愿意让其访问运行 Papilot 的这台电脑的人，详见[协作者](docs/guide.md#collaborators)。
+要邀请导师或合作者，用 `PAPILOT_ACCOUNT_ORIGIN` 给 Papilot 一个公开的 HTTPS 地址，然后打开 **设置 → 共享**：每个人用通行密钥登录，只能看到你共享的论文。只邀请你愿意让其访问运行 Papilot 的这台电脑的人，详见[协作者](docs/guide.md#collaborators)。
 
 </details>
 
@@ -136,6 +160,10 @@ npm run build && npm start
 
 <a href="https://github.com/cu1ch3n/papilot/graphs/contributors"><img src="https://contrib.rocks/image?repo=cu1ch3n/papilot" alt="Papilot 贡献者"></a>
 
+## 🔗 友情链接
+
+[LINUX DO](https://linux.do/) 是一个交流技术、分享开源项目的中文社区。Papilot 认同真诚、友善、团结、专业的社区理念，欢迎大家去发现有趣的项目、交流使用经验。
+
 ## 📄 许可证
 
 [MIT](LICENSE) © 2026 Cui Chen。内置的审阅引擎 [`vendor/latex-review`](vendor/latex-review) 同样采用 MIT 许可证。

package/bin/doctor.mjs

@@ -34,6 +34,13 @@ function executable(command, env = process.env) {
     try { fs.accessSync(file, fs.constants.X_OK); return fs.statSync(file).isFile(); } catch { return false; }
   });
 }
+// Agent CLIs are also looked for where they install themselves, as the server does.
+function agentExecutable(command) {
+  if (command.includes('/') || command.includes('\\')) return executable(command);
+  const home = process.env.HOME || os.homedir();
+  const dirs = ['.local/bin', '.claude/local', '.kimi-code/bin', '.opencode/bin', '.bun/bin', '.npm-global/bin'].map(dir => path.join(home, dir)).concat('/opt/homebrew/bin', '/usr/local/bin');
+  return executable(command) || executable(command, { PATH: dirs.join(path.delimiter) });
+}
 function command(file, args, options = {}) {
   return new Promise(resolve => {
     // Never return raw stderr: login commands can print credentials or account data.
@@ -141,14 +148,24 @@ export async function doctor(args) {
     return false;
   }
   async function claudeCheck() {
+    // With Claude Code installed, Claude runs claude -p on its own login; only the login state is read.
+    const cli = agentExecutable(process.env.PAPILOT_CLAUDE_BIN || 'claude');
+    if (cli) {
+      const result = await command(cli, ['auth', 'status', '--json']);
+      let login = null;
+      try { login = JSON.parse(result.stdout); } catch { /* Reported below. */ }
+      const ready = Boolean(login?.loggedIn);
+      check('agent.claude', ready, 'warn', `${cli}: ${ready ? `Claude Code signed in${login.subscriptionType ? ` (${login.subscriptionType} plan)` : ''}; generation was not tested` : login ? 'Claude Code is not signed in' : result.reason || 'login status unavailable'}.`, 'Run claude auth login, then select Reconnect in Papilot. Set PAPILOT_CLAUDE_BIN if needed.');
+      return ready;
+    }
     const sdk = installedModule('@anthropic-ai/claude-agent-sdk') || installedModule('@anthropic-ai/claude-agent-sdk', path.join(data, 'agents'));
     const configured = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'].some(key => Boolean(process.env[key]));
-    check('agent.claude', Boolean(sdk && configured), 'warn', !configured ? 'Claude API credentials are not configured in this environment; SDK-managed credentials were not checked.' : sdk ? 'Claude SDK installed; API credentials configured (not validated).' : 'Claude API credentials configured; the Agent SDK is not installed yet.', !configured ? 'Start Papilot with ANTHROPIC_API_KEY or a supported cloud provider configured. A Claude subscription alone cannot be used by this adapter.' : 'Start papilot once to install the Claude Agent SDK.');
+    check('agent.claude', Boolean(sdk && configured), configured ? 'warn' : 'info', !configured ? 'Claude Code is not installed and no Claude API key is configured, so Papilot does not offer Claude.' : sdk ? 'Claude SDK installed; API credentials configured (not validated).' : 'Claude API credentials configured; the Agent SDK is not installed yet.', !configured ? 'Install Claude Code and sign in with claude auth login to use your Claude plan, or start Papilot with ANTHROPIC_API_KEY or a supported cloud provider configured.' : 'Start papilot once to install the Claude Agent SDK.');
     return Boolean(sdk && configured);
   }
   async function agyCheck() {
-    const file = executable(process.env.PAPILOT_AGY_BIN || 'agy');
-    if (!file) { check('agent.antigravity', false, 'warn', 'Antigravity CLI is not installed or PAPILOT_AGY_BIN is invalid.', 'Install Antigravity and sign in to agy, or choose another agent.'); return false; }
+    const file = agentExecutable(process.env.PAPILOT_AGY_BIN || 'agy');
+    if (!file) { check('agent.antigravity', false, 'info', missingAgent('agy', 'PAPILOT_AGY_BIN'), 'Install Antigravity and sign in to agy on this host. If already installed, correct PAPILOT_AGY_BIN or the server PATH, then restart Papilot.'); return false; }
     const proxy = process.env.PAPILOT_AGY_PROXY;
     const env = proxy ? { ...process.env, HTTPS_PROXY: proxy, HTTP_PROXY: proxy, https_proxy: proxy, http_proxy: proxy, NO_PROXY: '127.0.0.1,localhost' } : process.env;
     const result = await command(file, ['models'], { env });
@@ -156,7 +173,37 @@ export async function doctor(args) {
     check('agent.antigravity', ready, 'warn', `${file}: ${ready ? 'model listing succeeded (no generation tested)' : result.reason || 'no models returned'}.`, 'Sign in to agy and try agy models. If your region requires a proxy, set PAPILOT_AGY_PROXY.');
     return ready;
   }
-  const agents = await Promise.all([codexCheck(), claudeCheck(), agyCheck()]);
+  // ACP agents: the CLI must offer its ACP mode. Login is not checked, so no credential is read.
+  function missingAgent(command, variable) {
+    return process.env[variable] ? `${variable} does not resolve to a runnable executable in Papilot's environment.`
+      : `${command} was not found on the PATH or in the standard agent folders available to Papilot. It may be installed for a different user or shell.`;
+  }
+  async function acpCheck(id, name, bin, help, install, update) {
+    const file = agentExecutable(process.env[bin.env] || bin.name);
+    if (!file) { check(`agent.${id}`, false, 'info', missingAgent(bin.name, bin.env), `${install}. If already installed, correct ${bin.env} or the server PATH, then restart Papilot.`); return false; }
+    const result = await command(file, help);
+    const ready = result.ok && /\bACP\b|Agent Client Protocol/i.test(result.stdout + '\n' + result.stderr);
+    check(`agent.${id}`, ready, 'warn', `${file}: ${ready ? 'ACP command available; login and generation were not tested' : result.reason || 'ACP command unavailable'}.`, `${update} Set ${bin.env} if needed.`);
+    return ready;
+  }
+  const kimiCheck = () => acpCheck('kimi', 'Kimi CLI', { env: 'PAPILOT_KIMI_BIN', name: 'kimi' }, ['acp', '--help'], 'Install Kimi Code CLI and run kimi login', 'Update Kimi Code CLI and run kimi login.');
+  const qwenCheck = () => acpCheck('qwen', 'Qwen Code', { env: 'PAPILOT_QWEN_BIN', name: 'qwen' }, ['--help'], 'Install Qwen Code and sign in by running qwen once', 'Update Qwen Code and sign in by running qwen once.');
+  const deepseekCheck = () => acpCheck('deepseek', 'DeepSeek Harness (dsh)', { env: 'PAPILOT_DSH_BIN', name: 'dsh' }, ['acp', '--help'], 'Install DeepSeek Harness with npm install -g @deepseek-ai/dsh and set up a model in dsh', 'Update DeepSeek Harness and set up a model in dsh.');
+  const opencodeCheck = () => acpCheck('opencode', 'OpenCode', { env: 'PAPILOT_OPENCODE_BIN', name: 'opencode' }, ['acp', '--help'], 'Install OpenCode and connect a provider with opencode auth login', 'Update OpenCode and connect a provider with opencode auth login.');
+  // SDK agents: a key in the environment (or the SDK's own login) selects them; keys are not validated.
+  async function cursorCheck() {
+    const configured = Boolean(process.env.CURSOR_API_KEY) || fs.existsSync(path.join(os.homedir(), '.cursor/sdk/auth.json'));
+    const sdk = installedModule('@cursor/sdk') || installedModule('@cursor/sdk', path.join(data, 'agents'));
+    check('agent.cursor', Boolean(configured && sdk), configured ? 'warn' : 'info', !configured ? 'Neither CURSOR_API_KEY nor a saved Cursor SDK login was found for the user running Papilot.' : sdk ? 'Cursor SDK installed; SDK credentials detected (not validated).' : 'Cursor SDK credentials detected; the SDK is installed on first use.', !configured ? 'Start Papilot with CURSOR_API_KEY set to a key from the Cursor dashboard, or configure the Cursor SDK login. The Cursor app and CLI login are not used. Restart Papilot after changing its environment.' : 'Start papilot and choose Cursor once to install the SDK.');
+    return configured;
+  }
+  async function glmCheck() {
+    const configured = Boolean(process.env.ZHIPU_API_KEY || process.env.ZAI_API_KEY);
+    const sdk = installedModule('@anthropic-ai/claude-agent-sdk') || installedModule('@anthropic-ai/claude-agent-sdk', path.join(data, 'agents'));
+    check('agent.glm', Boolean(configured && sdk), configured ? 'warn' : 'info', !configured ? 'ZHIPU_API_KEY or ZAI_API_KEY is not set, so Papilot does not offer GLM.' : sdk ? `GLM key configured for ${process.env.ZHIPU_API_KEY ? 'open.bigmodel.cn' : 'api.z.ai'} (not validated).` : 'GLM key configured; the Claude Agent SDK that runs GLM is installed on first use.', !configured ? 'Start Papilot with ZHIPU_API_KEY (open.bigmodel.cn) or ZAI_API_KEY (api.z.ai) set to your GLM Coding Plan or API key.' : 'Start papilot and choose GLM once to install the Claude Agent SDK.');
+    return configured;
+  }
+  const agents = await Promise.all([codexCheck(), claudeCheck(), cursorCheck(), agyCheck(), kimiCheck(), glmCheck(), deepseekCheck(), qwenCheck(), opencodeCheck()]);
   check('agents', agents.some(Boolean), 'warn', agents.some(Boolean) ? 'At least one agent passed its configuration check; live editing was not tested.' : 'No agent passed its configuration check. PDF reading can still be used with a working TeX installation.', 'Configure one agent before starting editing tasks.');
 
   if (repo) {
@@ -232,14 +279,14 @@ export async function doctor(args) {
     }
   }
   // Keep reports stable even though independent probes finish in any order.
-  const order = ['node', 'dependencies', 'frontend', 'review-engine', 'data', 'git', 'latexmk', 'synctex', 'tex-engines', 'agent.codex', 'agent.claude', 'agent.antigravity', 'agents', 'project', 'project.git', 'project.head', 'project.main', 'project.engine', 'project.worktrees', 'remote', 'server', 'service', 'service.tools', 'service.data'];
+  const order = ['node', 'dependencies', 'frontend', 'review-engine', 'data', 'git', 'latexmk', 'synctex', 'tex-engines', 'agent.codex', 'agent.claude', 'agent.cursor', 'agent.antigravity', 'agent.kimi', 'agent.glm', 'agent.deepseek', 'agent.qwen', 'agent.opencode', 'agents', 'project', 'project.git', 'project.head', 'project.main', 'project.engine', 'project.worktrees', 'remote', 'server', 'service', 'service.tools', 'service.data'];
   checks.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
   const report = { name: 'Papilot', version: pkg.version, ok: !checks.some(item => !item.ok && item.severity === 'error'), checks };
   if (json) console.log(JSON.stringify(report, null, 2));
   else {
     console.log(`Papilot ${pkg.version} doctor\n`);
     for (const item of checks) {
-      console.log(`${item.ok ? '✓' : item.severity === 'error' ? '✗' : '!'} ${item.id}: ${item.detail}`);
+      console.log(`${item.ok ? '✓' : item.severity === 'error' ? '✗' : item.severity === 'info' ? '-' : '!'} ${item.id}: ${item.detail}`);
       if (item.fix) console.log(`  Fix: ${item.fix}`);
     }
     const errors = checks.filter(item => !item.ok && item.severity === 'error').length;

package/bin/installation.d.mts

@@ -0,0 +1,8 @@
+export function stableVersion(value: unknown): value is string;
+export function devRevision(value: unknown): string | null;
+export function releaseVersion(value: unknown): value is string;
+export function newerVersion(next: string, current: string): boolean;
+export function readJson(file: string): any;
+export function writeJson(file: string, value: unknown): void;
+export function activeInstallation(root: string, data: string): string;
+export function waitForActivation(data: string): Promise<void>;

package/bin/installation.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const stableVersion = value => typeof value === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value) && value.length < 40;
+export const devRevision = value => typeof value === 'string' && value.length < 100 && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-dev\.([a-f0-9]{40})$/.exec(value)?.[4] || null;
+export const releaseVersion = value => stableVersion(value) || Boolean(devRevision(value));
+export function newerVersion(next, current) {
+  if (!stableVersion(next)) return false;
+  const match = /^(\d+)\.(\d+)\.(\d+)(.*)$/.exec(current);
+  if (!match) return false;
+  const parts = next.split('.').map(BigInt), previous = match.slice(1, 4).map(BigInt);
+  for (let i = 0; i < 3; i++) if (parts[i] !== previous[i]) return parts[i] > previous[i];
+  return match[4].startsWith('-');
+}
+export function readJson(file) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } }
+export function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(temporary, JSON.stringify(value), { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+// Updates live beside the database, never over a global installation or checkout.
+// All launch methods (CLI, npm start, launchd) enter through main.ts.
+export function activeInstallation(root, data) {
+  const active = readJson(path.join(data, 'updates/active.json'));
+  const version = readJson(path.join(root, 'package.json'))?.version;
+  if (!active || !releaseVersion(active.version)) return root;
+  // Explicit channel selections also cover dev builds and returning to stable.
+  // Older activation records retain their upgrade-only behavior.
+  if (!['stable', 'dev'].includes(active.channel) && !newerVersion(active.version, version)) return root;
+  if (active.channel && (active.channel === 'dev') !== Boolean(devRevision(active.version))) return root;
+  if (typeof active.root !== 'string') return root;
+  try {
+    const releases = fs.realpathSync(path.join(data, 'updates/releases')) + path.sep;
+    if (!fs.realpathSync(active.root).startsWith(releases)) return root;
+  } catch { return root; }
+  const pkg = readJson(path.join(active.root, 'package.json'));
+  if (pkg?.name !== 'papilot' || pkg.version !== active.version || !fs.existsSync(path.join(active.root, 'src/server/start.ts'))) return root;
+  return active.root;
+}
+export async function waitForActivation(data) {
+  const file = path.join(data, 'updates/active.json');
+  for (let attempt = 0; attempt < 200; attempt++) {
+    const active = readJson(file);
+    if (active?.phase !== 'pending') return;
+    try { process.kill(active.pid, 0); }
+    catch {
+      if (active.previous) writeJson(file, active.previous); else fs.rmSync(file, { force: true });
+      return;
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('The update is still restarting.');
+}

package/bin/papilot.mjs

@@ -5,6 +5,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { activeInstallation } from './installation.mjs';
 
 const usage = `Usage: papilot [doctor | demo | codex <args> | service install | service stop] [--port <number>] [--data <folder>]
 
@@ -18,7 +19,9 @@ const usage = `Usage: papilot [doctor | demo | codex <args> | service install |
   --data <folder>          Keep state in another folder (PAPILOT_DATA, default ~/.papilot)
   --version                Print the version`;
 
-const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+let pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+const installedPackage = () => JSON.parse(readFileSync(path.join(activeInstallation(packageRoot, process.env.PAPILOT_DATA || path.join(os.homedir(), '.papilot')), 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 async function main() {
   const doctor = args[0] === 'doctor';
@@ -37,7 +40,7 @@ async function main() {
     }
     else if (arg === '--data' && args[i + 1]) process.env.PAPILOT_DATA = path.resolve(args[++i]);
     else if (arg === '--version' || arg === '-v') {
-      console.log(pkg.version);
+      console.log(installedPackage().version);
       process.exit(0);
     } else {
       if (arg !== '--help' && arg !== '-h') console.error(`Unknown argument: ${arg}\n`);
@@ -78,6 +81,7 @@ async function main() {
   const emitWarning = process.emitWarning;
   process.emitWarning = (warning, ...rest) => String(warning).includes('SQLite') ? undefined : emitWarning.call(process, warning, ...rest);
   process.env.PAPILOT_DATA ||= path.join(os.homedir(), '.papilot');
+  pkg = installedPackage();
 
   // Papilot drives Codex through its app server. A codex on PATH at least as new
   // as the tested version is used as it is; otherwise that version is installed