lllin000_PaperForge/AGENTS.md

# PaperForge - Agent Guide

> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。如果还没有安装 PaperForge，请通过 Obsidian 插件市场安装，或查看 [README.md](README.md) 中的安装说明。Docs 版本与 v1.4.18 对应。

---

## 0. 安装后检查清单（第一次使用前必做）

```
[ ] Zotero 已安装 + Better BibTeX 插件已启用
[ ] Obsidian 已打开当前 Vault
[ ] PaperForge 已安装 (pip install paperforge)
[ ] PaddleOCR API Key 已配置（在 .env 中）
[ ] 目录结构已创建（安装向导会自动完成）
[ ] Zotero 数据目录已链接到 <system_dir>/Zotero
[ ] Better BibTeX 已按下方步骤导出 JSON 到 <system_dir>/PaperForge/exports/
```

> 安装向导是增量式的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会补充缺失的目录和文件，不会删除已有内容。

### Better BibTeX 自动导出配置

这一步应在安装向导完成之后再做，因为 `exports/` 目录需要先由安装流程创建。

1. 打开 Zotero
2. 对你要同步的文献库或分类右键 → `导出...`
3. 选择格式：**Better BibTeX JSON**
4. 勾选 **"Keep updated"**（自动导出）
5. 保存到：`{你的Vault路径}/<system_dir>/PaperForge/exports/`
6. JSON 文件名会作为 Base 名称，例如 `library.json`、`骨科.json`

---

## 1. 核心架构（v2.1 契约驱动）

PaperForge 在 v2.1（1.4.17rc4）重构为 **契约驱动架构**，分 5 层：

```
CLI/Plugin 调用
    ↓ PFResult 契约 {ok, command, version, data, error}
┌─────────────────────────────────────────────┐
│  commands/    CLI 分发层                      │
├─────────────────────────────────────────────┤
│  adapter/bbt, zotero_paths, frontmatter    │  ← 独立可测
│  services/sync_service       ← 编排适配器   │
├─────────────────────────────────────────────┤
│  core/result, errors, state   ← 共享数据契约 │
├─────────────────────────────────────────────┤
│  worker/sync, ocr, status     ← 机械劳动     │
│  setup/6个类                  ← 安装流程     │
├─────────────────────────────────────────────┤
│  schema/field_registry.yaml   ← 字段注册表   │
│  doctor/field_validator.py    ← 字段校验     │
└─────────────────────────────────────────────┘
```

| 层级 | 组件 | 触发方式 | 作用 |
|------|------|----------|------|
| **契约层** | `core/`（PFResult, ErrorCode, 状态机） | 被所有模块引用 | 定义 CLI/Plugin/Worker 之间的数据交换格式 |
| **适配器层** | `adapters/`（bbt, zotero_paths, frontmatter） | 被服务层调用 | 封装外部数据格式与 I/O 操作 |
| **服务层** | `services/sync_service` | 被 worker 调度 | 编排适配器，实现业务逻辑 |
| **Worker 层** | `worker/`（sync, ocr, status, repair 等） | Python CLI | 后台自动化（机械劳动） |
| **Agent 层** | `/pf-deep`, `/pf-paper` | 用户手动触发 | 交互式精读（深度思考） |

**操作速查**：
| 你要做什么 | 在终端输入 | 在 OpenCode 输入 |
|-----------|-----------|-----------------|
| 同步 Zotero 并生成笔记 | `paperforge sync` | `/pf-sync` |
| 运行 OCR | `paperforge ocr` | `/pf-ocr` |
| 查看精读队列 | `paperforge deep-reading` | `/pf-deep`（精读具体文献） |
| 查看系统状态 | `paperforge status` | `/pf-status` |
| 修复状态分歧 | `paperforge repair` | （终端操作） |
| 验证安装配置 | `paperforge doctor` | （终端操作） |
| 查看帮助 | `paperforge --help` | （终端操作） |

---

## 2. 完整数据流

```
Zotero 添加文献
    ↓ Better BibTeX 自动导出 JSON
<system_dir>/PaperForge/exports/library.json
    ↓ 运行 sync
<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md（正式笔记，含 frontmatter）
    ↓ 用户在正式笔记 frontmatter 中设置 do_ocr: true
运行 ocr → <system_dir>/PaperForge/ocr/<key>/
    ↓ 用户在正式笔记 frontmatter 中设置 analyze: true
运行 deep-reading（查看队列，确认就绪）
    ↓ 用户执行 Agent 命令
/pf-deep <zotero_key>
    ↓ Agent 生成
正式笔记中新增 ## 🔍 精读 区域
```

---

## 3. 目录结构（Lite 版，5 个核心目录）

```
{你的Vault根目录}/
├── <resources_dir>/
│   ├── <literature_dir>/                    ← 正式文献笔记（sync 生成，含 frontmatter 状态跟踪）
│   │   ├── 骨科/
│   │   ├── 运动医学/
│   │   └── ...（你的分类）
│
├── <system_dir>/
│   ├── PaperForge/
│   │       ├── exports/                   ← Better BibTeX 自动导出的 JSON
│   │       │   └── library.json
│   │       ├── ocr/                       ← OCR 结果（每个文献一个子目录）
│   │       │   └── ABCDEFG/               ← Zotero key 作为目录名
│   │       │       ├── fulltext.md        ← OCR 提取的全文
│   │       │       ├── images/            ← 图表切割图片
│   │       │       ├── meta.json          ← OCR 元数据（含 ocr_status）
│   │       │       └── figure-map.json    ← 图表索引（自动创建）
│   │       ├── indexes/                   ← 索引缓存（formal-library.json 等）
│   │       └── config/                    ← 领域-收藏夹映射等配置
│   └── Zotero/                        ← Junction/Symlink 到 Zotero 数据目录
│
├── <agent_config_dir>/                         ← OpenCode Agent 配置（自动创建）
│   └── skills/
│       └── literature-qa/             ← 深度阅读 Skill
│           ├── scripts/
│           │   └── ld_deep.py         ← /pf-deep 核心脚本
│           ├── prompt_deep_subagent.md ← Agent 精读提示词
│           └── chart-reading/         ← 14 种图表阅读指南
│
├── .env                               ← API Key 等敏感配置
└── AGENTS.md                          ← 本文件
```

### 各目录作用速查

| 目录 | 内容 | 谁生成/修改 |
|------|------|------------|
| `<resources_dir>/<literature_dir>/` | 正式文献笔记（含 frontmatter + 精读内容） | sync 生成，Agent 写入精读 |
| `<system_dir>/PaperForge/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 |
| `<system_dir>/PaperForge/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 |
| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 |
| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 |
| `<system_dir>/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction |

---

## 4. 核心 Workers（Lite 版，4 个）

### sync
- **作用**：检测 Zotero 中的新条目并生成正式文献笔记
- **运行时机**：添加新文献到 Zotero 后，或需要更新笔记格式时
- **输出**：
  - `<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md`
- **示例**：
  ```bash
  paperforge sync
  # Legacy (备用):
  # python -m paperforge sync --vault "{vault路径}"
  ```

### ocr
- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表
- **触发条件**：正式笔记 frontmatter 中 `do_ocr: true`
- **输出**：`<system_dir>/PaperForge/ocr/<key>/` 目录
  - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记）
  - `images/`：自动切割的图表图片
  - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`）
  - `figure-map.json`：图表索引（后续自动生成）
- **注意**：OCR 是异步的，大文件可能需要几分钟
- **示例**：
  ```bash
  paperforge ocr
  # 诊断模式（不运行，仅检查状态）
  paperforge ocr --diagnose
  # Legacy (备用):
  # python -m paperforge ocr --vault "{vault路径}"
  ```

### deep-reading
- **作用**：扫描所有正式笔记，列出 `analyze=true` 且 OCR 完成的文献
- **运行时机**：用户想看看哪些文献可以开始精读了
- **输出**：控制台表格，显示队列状态
- **重要**：这只是**查看队列**，不会自动触发 Agent 精读
- **示例**：
  ```bash
  paperforge deep-reading
  paperforge deep-reading --verbose  # 显示阻塞条目的修复指令
  # Legacy (备用):
  # python -m paperforge deep-reading --vault "{vault路径}"
  ```

---

## 5. Agent 命令（用户手动触发）

PaperForge 的命令分为两类：

| 类型 | 命令 | 用途 | 说明 |
|------|------|------|------|
| **深度思考** | `/pf-deep <key>` | 完整 Keshav 三阶段精读 | **必须 Agent 执行** — 需要理解论文、分析图表、生成 callout |
| **深度思考** | `/pf-paper <key>` | 文献问答 | **必须 Agent 执行** — 需要理解内容并写作 |
| **机械操作** | `/pf-sync` | 同步 Zotero 并生成笔记 | Agent 可帮你检查状态并执行 |
| **机械操作** | `/pf-ocr` | 运行 PDF OCR | Agent 可帮你检查队列并执行 |
| **机械操作** | `/pf-status` | 查看系统状态 | Agent 可帮你解读诊断结果 |

> **双模式调用**：`/pf-sync`、`/pf-ocr`、`/pf-status` 本质上是 CLI 命令的 Agent 包装。你可以在终端直接运行 `paperforge sync/ocr/status`，也可以在 OpenCode 中使用 `/pf-*` 让 Agent 帮你检查前置条件、执行命令、解读输出。

> **v1.4 新增**：所有命令支持全局 `--verbose` / `-v` 参数（如 `paperforge sync --verbose`），输出 DEBUG 级别的诊断信息到 stderr，不影响 stdout 的正常输出。

> **v1.4 新增 — auto_analyze_after_ocr**：如果开启了 `paperforge.json` 中的 `auto_analyze_after_ocr`，OCR 完成后 `analyze` 会自动设为 `true`，无需手动修改 formal note frontmatter。

### 必须 Agent 执行的命令

#### `/pf-deep <zotero_key>` — 完整精读

**用途**：完整 Keshav 三阶段精读
**前置条件**：OCR 完成 (`ocr_status: done`)

执行流程：
1. **prepare 阶段**（自动）：查找正式笔记、检查 OCR、生成 figure-map
2. **精读阶段**（Agent 执行）：Pass 1 概览 → Pass 2 精读还原 → Pass 3 深度理解
3. **验证阶段**（自动）：检查 callout 间距、section 完整性

#### `/pf-paper <zotero_key>` — 文献问答

**用途**：文献问答（无 OCR 要求）
**前置条件**：有正式笔记即可

---

## 6. Path Resolution（路径解析）

PaperForge 支持三种 Better BibTeX 导出路径格式，并统一转换为 Obsidian wikilink：

### 支持的 BBT 路径格式

| 格式 | 示例 | 处理方式 |
|------|------|----------|
| **Absolute Windows** | `D:\Zotero\storage\KEY\file.pdf` | 提取 8 位 KEY，转换为 `storage:KEY/file.pdf` |
| **storage: prefix** | `storage:KEY/file.pdf` | 直接透传，仅规范化斜杠 |
| **Bare relative** | `KEY/file.pdf` | 自动添加 `storage:` 前缀 |

### Wikilink 生成规则

- 所有 PDF 路径在正式笔记中存储为 **Obsidian wikilink** 格式：`[[relative/path/to/file.pdf]]`
- 使用正斜杠 `/`（即使 Windows 系统）
- 支持中文文件名，无需转义
- 示例：`[[99_System/Zotero/storage/KEY/中文论文.pdf]]`

### Junction / Symlink 设置

如果 Zotero 数据目录在 Vault 外部，需创建 junction：

```powershell
# 以管理员身份运行 PowerShell
New-Item -ItemType Junction -Path "C:\你的Vault\99_System\Zotero" -Target "C:\Users\用户名\Zotero"
```

或 CMD：

```cmd
mklink /J "C:\你的Vault\99_System\Zotero" "C:\Users\用户名\Zotero"
```

运行 `paperforge doctor` 会自动检测 Zotero 位置并推荐正确的 junction 命令。

### 多附件处理

当一篇文献有多个 PDF 附件时：
- **Main PDF**：title="PDF" 的附件，或最大文件，或第一个 PDF
- **Supplementary**：其他 PDF 附件列表，以 wikilink 数组形式存储

---

## 7. Frontmatter 字段参考

### Formal Note（`Literature/<domain>/<key> - <Title>.md`）

这是**用户控制工作流的核心**。每个文献对应一个 formal note 文件，frontmatter 包含元数据 + 工作流控制字段：

```yaml
---
zotero_key: "ABCDEFG"           # Zotero citation key（自动生成）
domain: "骨科"                   # 分类领域（对应 Zotero 收藏夹）
title: "论文标题"
year: 2024
doi: "10.xxxx/xxxxx"
collection_path: "子分类"        # Zotero 子收藏夹路径
has_pdf: true                    # 是否有 PDF 附件（自动生成）
pdf_path: "[[99_System/Zotero/storage/KEY/文件名.pdf]]"  # Wikilink 格式
bbt_path_raw: "D:\\Zotero\\storage\\KEY\\文件名.pdf"     # 原始 BBT 路径（调试用）
zotero_storage_key: "KEY"        # 8 位 Zotero storage key
attachment_count: 2              # 附件总数
supplementary:                   # 其他 PDF 附件（wikilink 列表）
  - "[[99_System/Zotero/storage/KEY/supp1.pdf]]"
  - "[[99_System/Zotero/storage/KEY/supp2.pdf]]"
fulltext_md_path: "[[99_System/PaperForge/ocr/KEY/fulltext.md]]"
recommend_analyze: true          # 系统推荐精读（有 PDF 时自动设为 true）
analyze: false                   # 【用户控制】是否生成精读？设为 true 触发
do_ocr: true                     # 【用户控制】是否运行 OCR？设为 true 触发
ocr_status: "done"               # OCR 状态（pending/processing/done/failed）
deep_reading_status: "pending"   # 精读状态（pending/done）
path_error: ""                   # 路径错误（not_found/invalid/permission_denied）
analysis_note: ""                # 预留字段
---
```

**用户操作方式**：
- 在 Obsidian 中打开 formal note 文件
- 修改 `analyze: false` → `analyze: true` 标记要精读的文献
- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR
- 或使用 Obsidian Base 视图批量操作

---

## 8. 第一次使用指南（手把手）

### Step 1: 完成 Better BibTeX 自动导出

先按上面的步骤把 JSON 导出到 `<system_dir>/PaperForge/exports/`。这一步没完成前，`sync` 不会读到文献。

### Step 2: 确认 Zotero 有文献

确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。

### Step 3: 运行 sync

```bash
# 在 Vault 根目录执行
paperforge sync
```

预期输出：
```
[INFO] Found 5 new items
[INFO] Created 骨科/XXXXXXX.md
[INFO] Generated 5 formal notes
[INFO] Output: <resources_dir>/<literature_dir>/骨科/XXXXXXX - Title.md
...
```

### Step 4: 在 Base 视图中标记 OCR

打开 Obsidian Base 视图，找到该文献，将 `do_ocr` 设为 `true`。

### Step 5: 运行 OCR

```bash
paperforge ocr
```

等待完成（可能需要几分钟）。

### Step 6: 在 Base 视图中标记精读

OCR 完成后，在 Base 视图中找到该文献，将 `analyze` 设为 `true`。

### Step 7: 执行精读

先确认队列就绪：
```bash
paperforge deep-reading
```

然后在 OpenCode Agent 中输入：
```
/pf-deep XXXXXXX
```

Agent 会自动：
1. 准备精读骨架（prepare）
2. 逐阶段填写精读内容
3. 验证结构完整性

### Step 8: 查看结果

在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。

---

## 9. 常用命令速查

```bash
# 检测 Zotero 新条目并生成正式笔记
paperforge sync
paperforge sync --verbose      # 显示详细诊断信息



# 运行 OCR（处理 do_ocr=true 的文献）
paperforge ocr
paperforge ocr --verbose       # 显示 OCR 详细日志
paperforge ocr --diagnose      # 诊断模式，不实际运行
paperforge ocr --no-progress   # 静默模式，不显示进度条

# 查看精读队列
paperforge deep-reading
paperforge deep-reading --verbose  # 显示阻塞条目修复指令

# 修复状态分歧（默认 dry-run）
paperforge repair --verbose        # 查看三向状态分歧详情
paperforge repair --fix           # 实际修复（慎用）

# 查看整体状态
paperforge status

# 验证安装配置
paperforge doctor
```

> 如果 `paperforge` 命令未注册，可使用 fallback：
> ```bash
> python -m paperforge <command>
> ```
> 例如：`python -m paperforge status`

### Agent 命令
```
/pf-deep <zotero_key>    # 完整三阶段精读（必须 Agent 执行）
/pf-paper <zotero_key>   # 文献问答（必须 Agent 执行）
/pf-sync                 # 同步 Zotero（Agent 包装 CLI）
/pf-ocr                  # 运行 OCR（Agent 包装 CLI）
/pf-status               # 查看状态（Agent 包装 CLI）
```

> 注：`/pf-sync`、`/pf-ocr`、`/pf-status` 与 `paperforge sync/ocr/status` 是同一命令的两种调用方式。在终端直接运行 CLI 即可；在 OpenCode 中使用 `/pf-*` 可以让 Agent 帮你检查前置条件并解读输出。

### Chart-Reading 指南索引

`/pf-deep` 精读时会参考 19 种图表类型的阅读指南，按生物医学文献常见度排序。完整索引参见 `chart-reading/INDEX.md`。

---

## 10. 常见问题

### Q: 运行 sync 后没有生成正式笔记？
- 检查 Better BibTeX JSON 导出路径是否正确
- 检查 JSON 文件是否包含文献数据
- 确认 Zotero 中该文献有 citation key

### Q: OCR 一直显示 pending？
- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件）
- 检查网络连接
- 查看 `<system_dir>/PaperForge/ocr/<key>/meta.json` 中的错误信息

### Q: /pf-deep 提示 OCR 未完成？
- 确认正式笔记 frontmatter 中 `ocr_status: done`
- 如 OCR 失败，可重新设置 `do_ocr: true` 再运行 ocr worker

### Q: Base 视图中 pdf_path 显示为绝对路径？
- 这是 Obsidian 渲染问题，数据本身是相对路径
- 不影响功能，可忽略

### Q: 可以批量操作吗？
- 可以。使用 Obsidian Base 视图批量修改 `do_ocr` 和 `analyze` 字段
- 或使用脚本批量修改 formal note frontmatter

---

## 11. 升级与维护

### 更新 PaperForge 代码

#### 方式 1：自动更新（推荐）

```bash
# 自动检测安装方式并更新
paperforge update
```

系统会自动检测你是通过 pip、git 还是手动安装，并执行对应的更新方式。

#### 方式 2：Windows 一键脚本

双击运行 Vault 根目录下的 `scripts/update-paperforge.ps1`：
- 自动检测安装方式
- 自动执行更新
- 无需手动输入命令

```powershell
# 或在 PowerShell 中执行
.\scripts\update-paperforge.ps1

# 强制更新（跳过确认）
.\scripts\update-paperforge.ps1 -Force

# 只检测不更新
.\scripts\update-paperforge.ps1 -DryRun
```

#### 方式 3：手动更新

**推荐：自动更新**
```bash
paperforge update
```
系统会自动检测安装方式并执行对应的更新命令。

**pip 安装用户：**
```bash
pip install --upgrade paperforge
```

**pip editable / git clone 用户：**
```bash
cd 你的仓库目录
git pull origin master
pip install -e .
```

#### 方式 4：手动复制（最后手段）

```bash
cp -r 新下载的代码/* <vault_path>/
```

> [!WARNING] 手动复制容易遗漏文件，建议优先使用自动更新。

### 备份注意事项
- `<resources_dir>/` 和 `<system_dir>/PaperForge/ocr/` 包含你的数据，需备份
- `.env` 包含 API Key，不要提交到 git
- `<system_dir>/PaperForge/exports/` 可重新生成（由 Zotero 自动导出）

---

## 12. 命令迁移说明（v1.1 → v1.2）

从 v1.2 开始，PaperForge 采用统一的命令接口：

- **CLI 统一入口**：`paperforge sync`（替代 `selection-sync` + `index-refresh`）、`paperforge ocr`（替代 `ocr run`）
- **Agent 统一前缀**：`/pf-deep`、`/pf-paper`、`/pf-ocr`、`/pf-sync`、`/pf-status`（替代 `/LD-*` 和 `/lp-*`）
- **Python 包重命名**：`paperforge`（替代 `paperforge_lite`）

**旧命令仍兼容**：v1.2 继续支持旧命令名（`selection-sync`、`index-refresh`、`ocr run`），但文档已统一使用新命令。

> **v1.4 新增**：结构化日志（`--verbose`）、自动重试、进度条、代码自动化检查。详细迁移步骤和回滚说明参见 [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md)（v1.1→v1.2）和 [docs/MIGRATION-v1.4.md](docs/MIGRATION-v1.4.md)（v1.3→v1.4）。

---

## 13. 开发者指南（AI Agent 必读）

### v2.1 新增模块

v2.1（1.4.17rc4）引入了以下新增模块，开发时请注意：

| 路径 | 内容 | 注意事项 |
|------|------|---------|
| `paperforge/core/` | 契约层 — PFResult, ErrorCode, 状态机 | 所有模块都可引用，不循环依赖 |
| `paperforge/adapters/` | 适配器 — bbt, zotero_paths, frontmatter | 独立可测，从 `sync.py` 提取 |
| `paperforge/services/` | 服务层 — SyncService | 编排适配器，`sync.py` 变调度壳 |
| `paperforge/setup/` | 安装层 — 6 个类 | 从 `setup_wizard.py` 拆出 |
| `paperforge/schema/` | 字段注册表 — `field_registry.yaml` | 44 字段定义 |
| `paperforge/doctor/` | 校验 — `field_validator.py` | `doctor` 命令使用 |

所有 `--json` 输出统一为 PFResult 格式 `{ok, command, version, data, error}`。修改输出结构时需同时更新 `core/result.py` 和下游 consumer（plugin）。

### 版本号管理

PaperForge 版本只在 `paperforge/__init__.py` 一处定义。升版本时不要手动改多个文件，使用自动化脚本：

```bash
# 升 patch 版本（1.4.11 → 1.4.12），自动 git commit + tag
python scripts/bump.py patch

# 升 minor 版本（1.4.11 → 1.5.0）
python scripts/bump.py minor

# 指定版本号
python scripts/bump.py 2.0.0

# 预览（不实际修改）
python scripts/bump.py patch --dry-run

# 只改文件不 commit
python scripts/bump.py patch --no-git
```

 脚本会自动更新：
| 文件 | 字段 |
|------|------|
| `paperforge/__init__.py` | `__version__` |
| `paperforge/plugin/manifest.json` | `version` |
| `manifest.json` | `version` |
| `paperforge/plugin/versions.json` | 追加 `"version": "minAppVersion"` |

### 发布 Release 流程

```bash
# 1. 升版本（自动 commit + tag）
python scripts/bump.py patch

# 2. 推送代码和 tag
git push && git push --tags

# 3. 创建 GitHub Release 并上传插件文件
gh release create v1.4.12 \
    --title "v1.4.12" \
    --notes "简短说明" \
    paperforge/plugin/main.js \
    paperforge/plugin/styles.css \
    paperforge/plugin/manifest.json \
    paperforge/plugin/versions.json
```

> Obsidian 社区插件要求 Release 附带 `main.js`、`manifest.json`、`styles.css`、`versions.json` 四个单独文件（非 zip）。

### 插件 i18n

插件界面通过 `paperforge/plugin/i18n.js` 做中英文适配：
- 语言自动检测：读取 Obsidian 语言设置，`zh*` 用中文，其他用英文
- 新增文本时，需同时在 `i18n.js` 的 `zh` 和 `en` 两块加 key
- 代码中使用 `t('key_name')` 读取翻译
- Dashboard 的 `ACTIONS` 标题保持英文（Obsidian 命令面板统一使用英文 ID）

### pre-commit 检查

```bash
# 提交前运行 ruff lint + format + 一致性审计
ruff check --fix paperforge/ && ruff format paperforge/

# 运行测试（173 tests）
python -m pytest tests/unit/ -q --tb=short
```

---

*PaperForge | 快速开始指南 | 安装后阅读*