# ChatPapers 开发文档

> 版本：v0.2（草案）  
> 更新日期：2026-07-20  
> 关联需求：[requirements.md](./requirements.md)

---

## 1. 技术选型

### 1.1 平台与形态

| 项 | 选择 | 理由 |
| --- | --- | --- |
| 宿主 | Zotero 9 Desktop | 需求明确；2026 年已有多款插件 bump 至 `9.*` |
| 扩展形态 | Bootstrapped Extension | Zotero 官方推荐路径（非 WebExtension 受限 API） |
| 清单 | `manifest.json` + `bootstrap.js` | Zotero 7+ 标准；9 需注意 bootstrap 导出方式 |
| 目标版本字段 | `strict_min_version: "9.0"`，`strict_max_version: "9.*"` | 与需求一致；若兼容 8 需额外回归 |

### 1.2 语言与工具链

| 项 | 选择 | 说明 |
| --- | --- | --- |
| 语言 | TypeScript | 类型安全；配合 `zotero-types` |
| 构建 | esbuild（经 `zotero-plugin-scaffold`） | 社区主流；热重载友好 |
| 脚手架 | [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template) + [zotero-plugin-scaffold](https://github.com/zotero-plugin-dev/zotero-plugin-scaffold) | 一键 build / start / release |
| UI Toolkit | `zotero-plugin-toolkit`（注意 Z9 API 迁移） | 菜单、快捷键、进度等；部分旧 API 已迁至原生 |
| 本地化 | Fluent（`.ftl`） | Zotero 未来方向；避免 DTD |
| 包管理 | pnpm 或 npm | 团队自定，文档示例用 npm |

### 1.3 Zotero 9 开发注意点

根据社区插件迁移经验，落地时需特别注意：

1. **`bootstrap.js` 导出方式**  
   Zotero 9 通过 `scope[method]` 解析生命周期函数。`bootstrap` 入口应产出**顶层** `function install/startup/shutdown/uninstall/...`，避免被 esbuild IIFE 包死导致钩子找不到。常见做法：对 `bootstrap.ts` **transpile 不 bundle**，或显式配置 esbuild 保留全局函数。

2. **废弃 `ChromeUtils.import`**  
   Firefox 128+ / Zotero 9 路径下优先使用 ESM / 官方推荐的模块加载方式，避免遗留 JSM import。

3. **UI 注册**  
   优先使用 Zotero 原生 PreferencePane、菜单注入点；Toolkit 大版本升级后核对 Breaking Changes。

4. **无重启启停**  
   `shutdown` / `onMainWindowUnload` 必须移除 DOM、监听、定时器、未完成的 fetch AbortController。

### 1.4 参考文档

- [Zotero 7 for Developers](https://www.zotero.org/support/dev/zotero_7_for_developers)（基础仍适用，9 在此之上演进）
- [Zotero Plugin Dev Docs](https://windingwind.github.io/doc-for-zotero-plugin-dev/)
- [Zotero Plugin Scaffold](https://zotero-plugin.dev/zotero-plugin-scaffold/)
- 官方示例：[make-it-red](https://github.com/zotero/make-it-red)

---

## 2. 工程结构（目标）

以 template 为起点，建议收敛为以下结构：

```text
chatpapers/
├── addon/                      # 打包进 xpi 的静态资源
│   ├── bootstrap.js            # 由 bootstrap.ts 转译生成（顶层函数）
│   ├── manifest.json
│   ├── prefs.js                # 默认偏好
│   ├── locale/
│   │   ├── en-US/chatpapers.ftl
│   │   └── zh-CN/chatpapers.ftl
│   └── content/                # 图标、样式、偏好 XHTML 等
├── src/
│   ├── index.ts                # 插件主入口（bundle）
│   ├── addon.ts                # Addon 单例、生命周期编排
│   ├── hooks.ts                # startup/shutdown/window hooks 业务
│   ├── modules/
│   │   ├── ui/
│   │   │   ├── readerPane.ts   # PDF Reader 侧边栏注入
│   │   │   ├── chatView.ts     # 对话 UI
│   │   │   └── prefs.ts        # 偏好面板
│   │   ├── pdf/
│   │   │   ├── extractor.ts    # 文本提取适配层
│   │   │   └── context.ts      # 上下文裁剪 / 分块
│   │   ├── llm/
│   │   │   ├── client.ts       # OpenAI 兼容客户端（stream / models）
│   │   │   ├── providers.ts    # Ollama / LM Studio / OpenRouter 等预设
│   │   │   ├── prompts.ts      # 系统提示与总结模板
│   │   │   └── types.ts
│   │   ├── storage/
│   │   │   ├── prefs.ts        # Preference 读写封装
│   │   │   └── sessions.ts     # 会话持久化
│   │   └── zotero/
│   │       ├── notes.ts        # 创建/追加 Note
│   │       └── items.ts        # 元数据读取
│   └── utils/
│       ├── logger.ts
│       └── abort.ts
├── docs/
│   ├── requirements.md
│   └── development.md
├── zotero-plugin.config.ts
├── package.json
├── tsconfig.json
└── readme.md
```

**命名约定**

- 插件 ID：`yehongyu@njau.edu.cn`
- Pref 前缀：`extensions.chatpapers.*`
- Fluent 文件：`chatpapers.ftl`（避免与其它插件冲突）
- 日志前缀：`[ChatPapers]`

---

## 3. 架构设计

### 3.1 分层

```text
┌─────────────────────────────────────────┐
│  UI Layer（Reader Pane / Prefs / Menus） │
├─────────────────────────────────────────┤
│  Application Services                    │
│  ChatSession · Summarize · SaveNote      │
├─────────────────────────────────────────┤
│  Adapters                                │
│  PdfExtractor · LlmClient · PrefStore    │
├─────────────────────────────────────────┤
│  Zotero Platform APIs                    │
└─────────────────────────────────────────┘
```

原则：

- UI 不直接 `fetch`；统一经 `LlmClient`
- PDF 提取细节隔离在 `PdfExtractor`，便于 Z9 API 变更时单点替换
- 所有偏好读写经 `PrefStore`，禁止散落魔法字符串

### 3.2 核心时序：提问

```text
User 发送
  → ChatView 收集：input + selection? + session history
  → ContextBuilder：metadata + pdfText(截断) + messages
  → LlmClient.chatStream(messages, AbortSignal)
  → 逐 chunk 更新 UI
  → 完成：写入 SessionStore
```

### 3.3 核心时序：保存笔记

```text
User 点击「保存为笔记」
  → 取当前 Assistant 消息（或总结全文）
  → Notes.createChildNote(item, { title, bodyHtmlOrMd })
  → Toast / 状态提示成功
```

Markdown → Zotero Note：优先转为简单 HTML（标题、段落、列表），保持可读。

---

## 4. 关键模块设计要点

### 4.1 Reader 侧边栏

- 在 Reader 窗口加载后注册侧边栏 Tab（具体 DOM/API 以 Zotero 9 Reader 为准，实现前用 DevTools 探测现网结构）
- Pane 与 `itemID` / `attachmentKey` 绑定；切换 PDF 时重置或切换会话
- 卸载时移除 Tab 与事件，防止重复注入

### 4.2 PDF 文本提取

实现顺序建议：

1. **优先**：使用 Zotero 已索引全文 / Reader 内可获取的文本 API（若可用）
2. **次选**：通过 PDF.js / 附件本地路径做页面级提取
3. **失败**：UI 提示「无文本层」，不发起无效大请求

`ContextBuilder` 策略（MVP）：

- 若 `len(text) <= maxContextChars`：全文注入
- 否则：标题页元数据 + 前 N 字 + 后 M 字，或「先让模型做分段摘要」二选一（由需求待决策项决定）

### 4.3 LLM Client

MVP 以 **单一 OpenAI 兼容客户端** 覆盖 Ollama、LM Studio、OpenRouter 及各类云端；差异用 **Provider 预设表** 表达，而不是为每个厂商写一套协议。

```http
POST {baseUrl}/chat/completions
Authorization: Bearer {apiKey}   # 本地预设可省略
Content-Type: application/json

{
  "model": "...",
  "messages": [...],
  "stream": true,
  "temperature": 0.3,
  "max_tokens": 2048
}
```

#### Provider 预设（与需求 §4.4 对齐）

| 预设 | 默认 Base URL | Key | 额外行为 |
| --- | --- | --- | --- |
| Ollama | `http://127.0.0.1:11434/v1` | 可空 | 可选 `GET /v1/models` 刷新列表；连接失败提示启动 Ollama |
| LM Studio | `http://127.0.0.1:1234/v1` | 可空 | 可选拉取 models；提示开启 Local Server |
| OpenRouter | `https://openrouter.ai/api/v1` | 必填 | 附加可选头 `HTTP-Referer`、`X-Title` |
| OpenAI / DeepSeek / 硅基流动 | 各官方 `/v1` | 必填 | 标准 Bearer |
| 自定义 | 用户输入 | 按需 | 无额外头 |

建议代码结构：

```text
src/modules/llm/
  ├── client.ts          # 统一 chatStream / listModels
  ├── providers.ts       # 预设常量：id → { baseUrl, needsKey, headers? }
  ├── url.ts             # Base URL 规范化（补 /v1、去尾斜杠）
  ├── prompts.ts
  └── types.ts
```

要求：

- 解析 SSE `data: {...}`；处理 `[DONE]`
- `AbortController` 支持停止生成
- 统一错误类型：`AuthError` / `RateLimitError` / `NetworkError` / `LocalServerDown` / `ProviderError`
- **禁止**将 API Key 打进日志；verbose 模式下对 Header 脱敏
- Base URL 规范化：兼容 `http://127.0.0.1:11434` 与 `.../v1`
- 切换预设时：写入默认 Base URL，**不覆盖**用户已改过的自定义 URL（可用「重置为预设默认」按钮）

本地联调建议：

- Ollama：`ollama pull qwen2.5` → Base URL 默认 → model 填实际名
- LM Studio：加载模型并 Start Server → 端口若非 1234 则改 URL
- OpenRouter：填 Key + 模型如 `openai/gpt-4o-mini`

### 4.4 会话存储

MVP 可选方案：

| 方案 | 优点 | 缺点 |
| --- | --- | --- |
| A. Preferences 存 JSON | 实现快 | 容量与性能差 |
| B. 插件数据目录 JSON 文件 | 清晰、易清理 | 需处理路径与并发 |
| C. IndexedDB / SQLite | 可扩展 | 实现成本高 |

**建议 MVP 用 B**，路径形如：`{profile}/chatpapers/sessions/{itemKey}-{attachmentKey}.json`。

### 4.5 偏好面板

使用 `Zotero.PreferencePanes.register`（Z9 推荐原生 API）注册：

- **Provider**：下拉预设（Ollama / LM Studio / OpenRouter / … / 自定义）+「重置为预设默认」
- 基本：Base URL、Key（本地可空）、Model、「刷新模型列表」
- 生成：temperature、maxTokens、timeout、maxContextChars
- OpenRouter 高级：Referer / Title（可折叠）
- 提示词：system / summary 可编辑文本框
- 隐私说明：明确当前预设是本地还是云端

---

## 5. 开发环境搭建

### 5.1 前置依赖

- Node.js 20+（LTS）
- 已安装 **Zotero 9** 桌面版
- Git

### 5.2 初始化（计划命令）

需求确认后，推荐从官方模板生成：

```bash
# 示例：使用 zotero-plugin-template 克隆后改名
npx tiged windingwind/zotero-plugin-template chatpapers
cd chatpapers
npm install
```

随后修改：

- `package.json` → `addonName` / `addonID` / `addonRef`
- `addon/manifest.json` → `strict_*_version` 设为 Zotero 9
- 清理 demo 代码，按本文结构迁入模块

### 5.3 本地调试

典型脚本（以 scaffold 为准）：

```bash
npm run start      # 启动 Zotero + 加载未打包插件 + 热重载
npm run build      # 产出 build/ 与 xpi
npm run lint
```

调试技巧：

1. 在 Zotero 中打开错误控制台（查看 `[ChatPapers]` 日志）
2. 对 Reader 窗口使用独立 DevTools（若可用）检查侧边栏 DOM
3. 用错误 Base URL 验证错误提示路径
4. 用本地 Ollama（`http://127.0.0.1:11434/v1`）验证兼容协议

### 5.4 环境变量

Scaffold 通常需要本机 Zotero 可执行文件路径，例如：

```bash
# Windows 示例（按实际安装路径调整）
set ZOTERO_PLUGIN_ZOTERO_CMD=C:\Program Files\Zotero\zotero.exe
```

具体变量名以当前 `zotero-plugin-scaffold` 文档为准。

---

## 6. 编码规范

1. **只改任务相关代码**；不顺手大重构模板无关文件  
2. TypeScript `strict`；避免无必要 `any`  
3. 异步：统一 `async/await`；外部请求必须可 Abort  
4. UI 字符串全部走 Fluent，禁止硬编码中文/英文（开发期临时除外，合并前清掉）  
5. 公共工具放 `utils/`；业务不互相深层耦合  
6. 每个模块顶部保持短注释（「做什么」），避免长篇叙述  

### 6.1 建议的 npm scripts

```json
{
  "scripts": {
    "start": "zotero-plugin serve",
    "build": "zotero-plugin build",
    "lint": "eslint .",
    "release": "zotero-plugin release"
  }
}
```

（实际命令以模板生成结果为准。）

---

## 7. 测试策略

| 层级 | 内容 | 时机 |
| --- | --- | --- |
| 手工冒烟 | 安装、侧边栏、提问、总结、存笔记、禁用清理 | 每个里程碑 |
| 单元测试 | `ContextBuilder` 截断、URL 规范化、错误映射 | M2+ |
| 集成（可选） | scaffold + Mocha 在真实 Zotero 中跑 | M4 |

最低验收清单见需求文档里程碑 M1–M4。

**手工测试用例（MVP）**

1. 未配置 API Key → 发送时友好提示  
2. 错误 Key → 401 可读错误  
3. 正常 PDF → 流式回复（分别用 Ollama / OpenRouter 各测一次）  
4. 选中文本提问 → 上下文包含选区  
5. 超长 PDF → 截断提示仍可回答  
6. 无文本 PDF → 明确失败原因  
7. Ollama 未启动 → `LocalServerDown` 友好提示  
8. 保存笔记 → 条目下可见 Note  
9. 禁用插件 → 侧边栏与菜单消失，无报错  

---

## 8. 发布流程

1. 更新版本号（`package.json` / `manifest.json`）  
2. `npm run build` 生成 `.xpi`  
3. GitHub Release 上传 `.xpi`  
4. 配置 `update_url` 指向 `updates.json`（Scaffold 可生成）  
5. 在干净 Zotero 9 Profile 中验证安装与更新  

版本号遵循 SemVer：`MAJOR.MINOR.PATCH`。

---

## 9. 实施计划（与需求里程碑对齐）

| 阶段 | 工程任务 | 预估 |
| --- | --- | --- |
| M0 | 确认需求待决策项；冻结插件 ID / 协议 | 0.5d |
| M1 | 从 template 初始化；偏好页；Reader 占位 Pane | 2–3d |
| M2 | PDF 提取 + 非流式/流式 Client + 单轮对话 | 3–5d |
| M3 | 多轮 UI、总结模板、存 Note、Abort | 3–4d |
| M4 | 会话持久化、i18n、日志脱敏、打包与 README 使用说明 | 2–3d |

以上为单人全职粗估，随 Reader API 熟悉度波动。

---

## 10. 目录外约定

- 密钥与真实 API Key **不得**提交仓库；提供 `.env.example`（若需要）仅含路径类配置  
- `docs/` 变更随功能演进；重大行为变更先更新需求再改代码  
- Issue / PR 标题建议前缀：`feat:` / `fix:` / `docs:` / `chore:`

---

## 11. 下一步（工程开工清单）

需求方确认 [requirements.md §10 待决策事项](./requirements.md#10-待决策事项需产品确认) 后，按序执行：

1. 从 `zotero-plugin-template` 初始化仓库代码  
2. 改名与 Zotero 9 manifest  
3. 落地 `PrefStore` + 空 Reader Pane  
4. 实现 `LlmClient` 与最小 Chat UI  
5. 接通 PDF 文本与「保存为笔记」  

如需，可在确认待决策项后直接进入 M1 脚手架初始化。