# Vocabulary SRS Pro 使用手册

> 当前正式版本：`1.0.2`  
> 插件 ID：`obpl-vocab-srs`  
> 授权产品：`obpl-vocab-srs-pro`  
> 支持平台：Windows、macOS、Linux、iOS 与 Android（部分本地接口能力需在对应设备上可访问）

## 1. 产品简介

Vocabulary SRS Pro 是面向 Obsidian 英语阅读与长期词汇学习的本地优先插件。它把阅读中的划词收集、词典释义、句子翻译、发音、FSRS 复习、学习看板、顽固词识别、词汇图谱和可选 AI 助手放在同一套工作流中。

学习数据保存在本地 Obsidian 环境中。插件不会在后台检查更新，也不会把词汇、句子、复习记录或 AI 对话上传到 Peyote 授权服务。只有激活、设备管理、授权同步和主动检查更新时才会访问授权 API。

## 2. 安装与激活

1. 在安全下载页输入 Vocabulary SRS Pro 激活码并下载安装包。
2. 解压后确认根目录包含 `main.js`、`manifest.json` 和 `styles.css`。
3. 将文件放入当前 Vault 的插件目录：

   ```text
   .obsidian/plugins/obpl-vocab-srs/
   ```

4. 重启 Obsidian，进入“设置 → 第三方插件”，启用 Vocabulary SRS Pro。
5. 打开插件设置，在“授权与设备”中点击“输入激活码”。
6. 填写设备名称并联网完成首次激活。

激活完成后，日常启动和离线使用由本机许可证完成验证。默认授权最多绑定 5 台设备，实际权益以购买方案为准。

## 3. 快速开始

### 3.1 打开学习工作台

可以通过左侧功能区入口，或命令面板执行“打开词汇图谱/学习界面”。工作台用于查看词汇、句子、复习任务、统计看板和知识图谱。

### 3.2 从正文收集词汇

1. 打开一篇 Markdown 英文笔记。
2. 选择一个英文单词或句子。
3. 使用浮动查词入口或命令“Add selection to vocabulary”。
4. 核对释义、音标、词性、上下文和来源位置。
5. 保存为单词卡或句子卡。

收集时会保留来源文件和上下文，方便复习时回到原文。

### 3.3 手动添加与编辑

在词汇工作台中可以手动新增单词，或编辑已有卡片的：

- 单词或句子正文；
- 音标、词性和释义；
- 中文翻译与例句；
- 分组和来源；
- 创建时间与学习状态；
- 关联的 AI 解析。

已有词条不会因重新查词而自动删除，保存前请确认覆盖内容。

## 4. 查词、翻译与发音

插件支持多种查词来源，具体可用性取决于网络和第三方服务：

- 有道词典在线接口；
- 金山词霸在线接口；
- 欧路词典网页解析；
- Collins 本地 API。

整句翻译可以选择百度翻译或自建本地接口。使用百度翻译时需自行填写 App ID 与 Secret Key；本地接口默认示例为 `http://127.0.0.1:8000`，手机不能直接访问电脑的 `127.0.0.1`，应填写手机可访问的局域网地址。

发音优先使用在线语音，失败时可降级到系统 Web Speech 能力。在线词典、翻译和发音属于第三方服务，隐私政策和稳定性由相应服务提供方负责。

## 5. FSRS 复习

插件使用 FSRS 为单词卡和句子卡安排复习。

复习时根据实际记忆情况选择：

- 重来：几乎没有想起；
- 困难：勉强想起；
- 认识：正常回忆；
- 简单：可以轻松回忆。

评分会影响下一次到期时间。建议如实评分，不要为了减少任务量长期选择“简单”。

常用设置：

- 目标留存率：越高意味着复习更频繁；
- 最大间隔：限制最长复习间隔；
- 每日新卡上限：默认 50，只限制从未复习过的新卡；
- 顽固词阈值：达到指定遗忘次数后进入重点提醒。

重置复习进度会改变排程数据。执行前建议备份插件数据；界面提供短时间撤销时应及时确认。

## 6. 学习看板与顽固词

学习看板可用于观察：

- 今日待复习数量；
- 新卡与到期卡压力；
- 学习活跃度；
- 词汇和句子总量；
- 遗忘次数较高的顽固词；
- 分类、词性和时间分布。

建议先处理到期复习卡，再引入新卡。若连续多日积压，可暂时降低每日新卡上限，而不是删除历史学习数据。

## 7. 词汇知识图谱

知识图谱用于连接主题、词根、核心单词、派生词和常用短语。可以打开已有图谱，也可以使用已配置的 LLM 生成全局已学习词汇图谱。

默认图谱输出目录为：

```text
Vocabulary/lexigraph-out
```

生成图谱前需要配置可用的本地服务或 OpenAI 兼容 LLM 接口。生成结果需要人工复核，尤其是词根、派生关系和固定搭配，不应把模型输出当作词源学权威结论。

## 8. AI 助手

AI 助手是可选功能，不影响基础收集和复习。

可配置：

- API Endpoint；
- API Key；
- 模型名称；
- 是否显示悬浮入口；
- 图谱生成使用的 LLM 地址和模型。

Endpoint 使用 OpenAI 兼容的 `/v1/chat/completions` 接口。API Key 保存在当前插件数据中；如果 Vault 或插件目录会同步到其他设备，请确认同步范围和目标位置可信。

## 9. 数据与备份

核心学习数据通常保存在当前插件目录的 `data.json` 中；按设置生成的单词笔记和图谱文件保存在 Vault 内的 Vocabulary 相关目录。

建议备份：

```text
.obsidian/plugins/obpl-vocab-srs/data.json
Vocabulary/
```

更新插件时不要删除 `data.json`。卸载前如果希望保留学习记录，应先复制上述数据。普通的插件自动更新只替换运行文件，不会主动清空学习数据。

## 10. 授权、设备与更新

插件设置中的“授权与设备”支持：

- 输入激活码；
- 使用恢复码；
- 管理已激活设备；
- 联网同步授权状态；
- 输入续期码延长权益；
- 主动检查 Pro 更新。

检查更新只在点击按钮后进行一次，不在后台轮询。更新前会验证发布签名和产品身份；安装时保留插件数据，并为被替换文件建立回滚备份。

公开文档：

- 使用手册：`https://peyote.info/plugins/vocabulary-srs/manual/`
- 更新日志：`https://peyote.info/plugins/vocabulary-srs/changelog/`

## 11. 常见问题

### 手机无法访问本地词典或 AI 接口

`127.0.0.1` 在手机上指向手机本身，而不是电脑。请把服务绑定到局域网地址，并填写手机能够访问的 IP；同时检查系统防火墙和 Wi-Fi 网络隔离。

### 划词后没有出现入口

确认插件已授权并启用，当前处于 Markdown 阅读或编辑场景，且选中的内容包含有效英文。移动端请使用长按形成文本选区。

### 在线词典返回空结果

切换其他词典来源，或稍后重试。第三方网页结构和接口可能变化，本地已有卡片不会因此被删除。

### 复习数量突然增加

通常是多日未复习或每日新卡过多。优先完成到期卡，并降低每日新卡上限；不要通过删除数据规避排程。

### 更新失败

确认授权仍包含更新权益、网络可访问授权服务，并检查插件目录是否可写。失败时保留原版本，不要手动删除 `data.json`。

## 12. 隐私与安全

- 词汇、句子、复习记录和图谱默认保存在本地；
- 使用在线词典、翻译或 AI 时，请求内容会发送给你选择的第三方接口；
- 不要公开分享 API Key、激活码、恢复码或 `data.json`；
- 从官网安全下载页获取安装包，并在插件内主动检查更新；
- 不从来源不明的网盘或群文件安装修改版。