English Reading Companion

English Reading Companion turns highlights from an English article into one structured, updateable learning note. It explains words, phrases, collocations, technical terms, and sentence patterns in their original context through an OpenAI-compatible API. The plugin controls all Markdown rendering and Vault writes locally, keeps one learning note per source article, and preserves anything you write outside its marked automatic section.

Overview

• Recognizes Obsidian ==highlights==, HTML <mark> elements, and Highlightr spans.
• Sends each highlight with a configurable amount of surrounding context.
• Requests structured JSON from an OpenAI-compatible Chat Completions endpoint.
• Creates or updates one aggregated learning note for each source article.
• Adds a bidirectional link between the source article and its learning note.
• Preserves user-authored content outside AUTO-LEARNING-START/END.
• Works on desktop and mobile without shell commands, local agents, telemetry, or Node.js runtime APIs.

Quick start

1. Install the three files from the latest release, or install the plugin from Obsidian's Community Plugins directory when available.
2. Enable English Reading Companion in Settings → Community plugins.
3. Configure the base URL, endpoint path, API key, and model.
4. Highlight unfamiliar English text in a Markdown article.
5. Run Generate or update English learning note from the command palette or ribbon icon.

The default endpoint shape is compatible with OpenAI Chat Completions. JSON Schema output automatically falls back to JSON Object and prompt-only JSON when the configured provider does not support the stricter format.

Privacy and data use

The plugin makes network requests only when you generate a note or test the connection. Those requests go to the API endpoint you configure and include the selected model, highlighted text, and the context range you chose. There is no analytics or telemetry. If API key persistence is enabled, the key is stored as plain text in the plugin's data.json; use a restricted, revocable key and take care when syncing plugin configuration. The plugin only changes files inside the current Vault and does not send absolute disk paths.

中文说明

English Reading Companion 是一个纯 API 的 Obsidian 插件：在英文剪藏笔记中阅读并高亮，执行一次“生成英语学习笔记”，插件会把当前文章的全部高亮交给 OpenAI-compatible 模型分析，生成或更新一篇聚合式学习笔记，并在原文建立双链。

功能特点

• 一篇英文原文对应一篇聚合式学习笔记。
• 支持 Obsidian 原生高亮、HTML <mark> 和 Highlightr。
• 根据原句和前后文解释单词、短语、术语、搭配与句型。
• API 只返回结构化 JSON，Markdown 与 Vault 写入完全由插件控制。
• 重复生成只更新自动区块，保留“我的理解”等手写内容。
• 支持 OpenAI-compatible Chat Completions API 与结构化输出降级。
• 不依赖本地 Agent、CLI、Shell 或遥测服务。

安装

从 GitHub Release 安装

1. 从 最新 Release 下载 main.js、manifest.json 和 styles.css。
2. 在 Vault 中创建 .obsidian/plugins/english-reading-companion/。
3. 将三个文件放入该目录。
4. 重启 Obsidian，在“设置 → 第三方插件”中启用 English Reading Companion。

从源码构建

需要 Node.js 20 或更高版本。

git clone https://github.com/haohao1101/english-reading-companion.git
Set-Location english-reading-companion
npm ci
npm run typecheck
npm run lint
npm test
npm run build

使用流程

1. 在 Obsidian 设置 → 第三方插件中启用 English Reading Companion。
2. 打开插件设置，填写 Base URL、Endpoint path、API Key 和 Model。
3. 用 ==...==、<mark>...</mark>、或 Highlightr 高亮标记不熟悉的内容。
4. 点击左侧 Ribbon 图标，或执行命令“生成或更新英语学习笔记”。

插件不会调用 Codex/Claude/Gemini CLI、Shell 或本地 Agent；模型只返回 JSON，所有 Vault 文件操作由插件完成。

设置与隐私

默认 API 是 OpenAI-compatible Chat Completions：

• Base URL：例如 https://api.openai.com/v1
• Endpoint path：默认 /chat/completions
• API Key：密码样式输入框
• Model：例如 gpt-4o-mini
• Structured output：默认 JSON Schema，不支持时可自动降级为 JSON Object 和 Prompt-only JSON
• Timeout：默认 120 秒；Maximum retries：默认 1 次

保存的 Key 位于插件 data.json，并同步备份到 Obsidian 配置目录下的 english-reading-companion-settings.json，以便插件目录被更新或重装后自动恢复。两者都不是加密保险库；不要上传 GitHub 或分享给他人。建议创建一个额度受限、可随时撤销的专用 Key。关闭“保存 API Key”后，持久化副本中的 Key 会被清空。

模型栏会通过当前 Base URL 的 OpenAI-compatible /models 接口读取可用模型，支持下拉选择；不提供该接口的服务仍可直接输入自定义模型 ID。

默认发送范围是“标准”：每个高亮、所在段落（最多 1200 字符）、前后段（各最多 400 字符），以及文章开头最多 1800 字符。选择“完整”会发送清理后的整篇正文，请注意隐私和 token 消耗。Frontmatter、代码块、HTML 注释、自动生成区块和明显导航噪声会在发送前移除。不会把绝对磁盘路径发送给模型。

Disclosures / 披露

• Network use / 网络使用：仅在用户执行生成命令或测试连接时，请求用户配置的 OpenAI-compatible API；请求包含 API Key、模型参数、高亮文本和用户选择范围内的文章上下文。
• Account and cost / 账户与费用：需要用户自行提供第三方模型服务的 API Key；服务商可能按其规则收费。
• Local data / 本地数据：设置通过 Obsidian 插件数据接口保存在当前 Vault；启用“保存 API Key”时，Key 会以明文保存在插件 data.json。插件没有遥测、广告或客户端行为追踪。
• Vault changes / Vault 修改：执行生成命令后，插件会创建或更新学习笔记，并按设置更新原文 frontmatter 和可见双链；不会访问 Vault 之外的文件。

高亮格式

支持：

• ==native highlight==
• <mark>HTML highlight</mark>
• <mark class="hltr-yellow">Highlightr content</mark>
• 带 background / background-color 样式的 Highlightr <span>

不会解析 YAML frontmatter、围栏代码块、行内代码、HTML 注释和插件自动生成区块中的伪高亮。同一表达在同一段落中只保留一次；默认同词不同语境分别保留。

文件规则

默认学习笔记目录为 English Learning/Article Notes，文件名为 原文文件名 - 英语学习.md。学习笔记聚合一篇原文的全部高亮，不会创建“一词一个文件”。

学习笔记包含 AUTO-LEARNING-START/END 区块。重复运行时只重建该区块，区块外的“我的理解”和“我的例句”等手写内容原样保留。原文 frontmatter 会增加 english_learning_note，正文可显示一个对应学习笔记链接区块。

如果同名目标已属于另一篇原文，会使用源路径哈希后缀；如果已有笔记缺少完整 AUTO 边界，会先弹出冲突选择：取消、末尾补充自动区块、另存为新文件。

命令与排查

可用命令：

• 生成或更新英语学习笔记
• 预览当前文章的高亮内容
• 打开当前文章的英语学习笔记
• 测试模型 API 连接

常见问题：

• 401/403：检查 API Key、账户权限和模型权限。
• 404：检查 Base URL、Endpoint path 和 Model；Base URL 通常不应重复 /chat/completions。
• 429/5xx：检查额度或服务状态，插件会按设置最多重试一次。
• 没有高亮：检查高亮格式及设置页中的识别开关。
• 目标笔记冲突：选择取消最安全；选择补充会把自动区块追加到文件末尾。

插件在调用 API 前后会比较原文内容；API 失败、响应非法、Schema 校验失败或原文变化时不会写入 Vault。运行时不输出正文、上下文、API Key 或绝对路径日志。

安装、升级与卸载

如需使用本地安装脚本，先创建仅供本机使用的配置：

Copy-Item install.config.example.json install.config.local.json

编辑 install.config.local.json，填入 Vault 绝对路径，然后运行：

npm ci
npm run build
npm run install:obsidian

install.config.local.json 已加入 .gitignore，不得提交。安装脚本只从项目复制 main.js、manifest.json 和 styles.css，已有插件目录会先备份；现有 data.json 会安全放回活动目录，因此升级不会清空设置。

升级时重新构建并运行 npm run install:obsidian，设置保存在 Vault 插件目录的 data.json，不会被构建产物覆盖。卸载可在 Obsidian 设置中关闭并删除插件目录；如需保留已生成的学习笔记，请不要删除 English Learning/Article Notes。

开发与贡献

项目采用 TypeScript 严格模式、esbuild、ESLint、Vitest 和 GitHub Actions。贡献前请阅读 CONTRIBUTING.md；安全问题请按 SECURITY.md 私密报告。

许可证

本项目采用 MIT License。