Tony English Assistant V1.1 产品文档说明

产品名称：Tony English Assistant
当前版本：V1.1.0
插件 ID：tony-english-assistant
作者：TonyWang
适用平台：Obsidian 第三方插件
最低 Obsidian 版本：1.5.0
文档目标：我用这份文档沉淀插件的产品定义、交互规则、技术边界、接口配置、验收标准和迭代管理方法，便于后续继续开发本插件，也便于复用方法开发其他 Obsidian 学习类插件。

0. 一页纸结论

0.1 核心判断

我把 Tony English Assistant V1.1 定义为一款 Obsidian 原生英语学习助手插件，它不是简单翻译工具，而是围绕英文阅读场景建立「选中原文 → 手动激活 → 发音/语法拆解/翻译/句型拓展/生图记忆 → 保存学习卡片 → Canvas 归档 → 复习队列」的学习闭环。

0.2 本版最重要的设计原则

原则	结论	原因
手动激活优先	选中英文后不自动弹出卡片	自动弹窗会打断阅读和笔记书写节奏
悬浮卡片可控	卡片必须支持拖动和关闭	用户需要在阅读区、编辑区、解释区之间灵活切换视野
生图按需触发	生图必须是独立按钮，不默认调用	图片生成成本更高、耗时更长，不应在普通查词时自动发生
文本模型与图片模型分离	DeepSeek 用于文本分析，Image API 用于生图	文本接口与图片接口能力边界不同，强行复用会导致配置混乱
资产沉淀优先	分析结果必须写入 Markdown / Canvas / Review	Obsidian 的核心价值是本地知识资产，而不是一次性翻译
可替换模型	所有 API 都按 Provider 思路设计	后续可替换 DeepSeek、OpenAI 或其他 OpenAI-compatible API

1. 背景与问题定义

1.1 用户场景

我在 Obsidian 中阅读英文资料时，常见任务包括：

阅读英文教材、课程资料、技术文档、商业文章。
选中不会的单词、短语、句子或长段落。
希望快速理解原文含义、语法结构和可复用表达。
希望把高价值句子沉淀成可复习的英语学习卡片。
希望通过卡通图或真实场景图增强记忆点。

1.2 原始痛点

痛点	表现	对学习效率的影响
查词中断	复制文本到浏览器或词典	频繁切换窗口，阅读流中断
翻译浅层	只得到中文意思	不知道句子主干、语法结构、表达迁移方式
生词沉淀弱	查完就忘	无法形成复习资产
自动弹窗干扰	只要选中文本就弹卡片	干扰编辑、复制、划线和阅读
AI 结果不可管理	解释散落在聊天记录中	后续无法系统复盘
图片记忆缺失	纯文字卡片记忆点弱	长句和抽象表达难以长期记住

1.3 版本目标

V1.1 的目标不是做一个大而全的欧路词典替代品，而是优先做成 Obsidian 内高效率英文阅读学习工作台：

选中英文原文
↓
右键菜单 / 左侧图标手动激活
↓
悬浮卡片出现
↓
用户按需执行：发音 / AI 语法拆解 / 保存卡片 / 一键生图
↓
写入本地 Markdown、Canvas、Review 队列

2. 产品定位

2.1 一句话定位

Tony English Assistant 是一款为 Obsidian 英语学习场景设计的插件，帮助我在不离开当前笔记的前提下，完成英文原文理解、语法拆解、翻译、句型拓展、记忆图生成和学习卡片沉淀。

2.2 目标用户

用户类型	核心需求	插件价值
英语学习者	读懂原文、理解语法、积累表达	把每次阅读变成学习卡片
产品经理	阅读海外资料、竞品评论、技术文档	快速理解英文资料并沉淀表达库
考研/考试学习者	长难句拆解、翻译、句型积累	把长句拆成可复习结构
知识管理用户	把外部资料纳入 Obsidian	Markdown + Canvas + Review 本地资产化
插件开发者	想开发类似学习插件	复用本插件的入口、卡片、API、归档设计

2.3 不做什么

不做事项	原因
不做自动划词弹窗	会打断阅读和编辑，V1.1 已改为手动激活
不做自建账号系统	Obsidian 本地优先，账号系统不是当前阶段核心价值
不做强绑定某一家模型	用户后续可能换 API，插件必须保留兼容层
不把 DeepSeek 当图片模型	DeepSeek 当前主要用于文本分析，生图需要独立 Image API
不做复杂学习算法	V1.1 只做复习队列，不做完整 SRS 算法

3. 当前版本功能范围

3.1 V1.1 已实现功能

模块	功能	当前状态
激活入口	右键菜单打开英语学习卡片	已实现
激活入口	左侧 Ribbon 图标打开卡片	已实现
选区捕获	选中英文后记录当前选区，但不自动弹窗	已实现
悬浮卡片	可显示原文、AI 分析、按钮操作	已实现
卡片移动	拖动卡片顶部移动位置	已实现
发音	使用系统 Web Speech 朗读选中文本	已实现
AI 语法拆解	句子主干、语法结构、翻译、句型拓展	已实现
手动标题	保存卡片前手动输入标题，标题不超过 140 字符	已实现
Markdown 归档	写入 English/Vocabulary.md	已实现
Canvas 归档	写入 English/归档汇总.canvas	已实现
复习队列	写入 English/Review.md	已实现
一键生图	点击按钮后生成记忆图	已实现
图片保存	图片保存到 English/MemoryImages	已实现
API 配置	支持 DeepSeek / OpenAI / Custom OpenAI-compatible	已实现
生图配置	支持 Image API Endpoint / Model / Size / Quality	已实现

3.2 当前版本文件结构

/tony-english-assistant
├── manifest.json     # Obsidian 插件声明文件
├── package.json      # 插件包信息和检查脚本
├── main.js           # 插件核心逻辑
├── styles.css        # 悬浮卡片、按钮、滚动区、图片区样式
└── README.md         # 安装与配置说明

3.3 插件生成的用户数据文件

文件	默认路径	作用
词句学习卡片	English/Vocabulary.md	保存标题、原文、句子主干、语法结构、翻译、句型拓展
Canvas 归档	English/归档汇总.canvas	把学习卡片转成 Obsidian Canvas 节点
复习队列	English/Review.md	记录待复习句子和日期
记忆图片	English/MemoryImages/	保存 AI 生成图片

4. 用户体验设计

4.1 总交互链路

用户选中英文词句
↓
插件只记录选区，不弹出卡片
↓
用户选择激活方式：
A. 鼠标右键 → 打开英语学习卡片
B. 点击左侧 Ribbon 图标
↓
悬浮卡片出现
↓
用户拖动卡片到合适位置
↓
用户按需点击功能按钮
↓
保存到 Obsidian 本地学习资产

4.2 为什么不自动弹卡片

自动弹卡问题	手动激活优势
选中文字复制时也会弹窗	用户确认需要插件时才打开
编辑笔记时被打断	保持写作和阅读流畅
多次误触发增加干扰	右键入口更符合“主动查询”心智
长文阅读中弹窗遮挡内容	悬浮卡出现时才占用视觉空间

4.3 悬浮卡片结构

区域	内容	设计目的
顶部标题栏	插件名称、关闭按钮、拖动区域	让用户明确当前工具，并可移动/关闭
原文区	被选中的英文词句	保留上下文输入来源
操作按钮区	发音、AI 语法拆解、保存卡片、生成记忆图、复制信息	高频动作集中在卡片内
AI 分析区	句子主干、语法结构、翻译、句型拓展	从“翻译”升级为“理解与迁移”
图片区	生图状态、图片预览、保存路径	把抽象句义转成视觉记忆点
状态提示区	API 成功/失败、保存结果	减少用户猜测

4.4 卡片拖动规则

规则	说明
拖动区域	只允许拖动卡片顶部标题栏
不影响按钮	点击按钮、选择下拉框时不触发拖动
保持可见	卡片移动时应尽量限制在视口内
关闭方式	点击右上角关闭按钮或按 Esc

4.5 生图交互规则

规则	说明
不自动生图	只有用户点击“生成记忆图”才调用 Image API
先选风格	支持卡通图 / 真实场景图
允许无生图 Key	若未配置 Image API Key，可先生成/展示提示词，避免功能完全不可用
图片本地保存	生成图片写入 Vault 文件夹，便于长期复习
允许只用文本功能	不配置 Image API 不影响 DeepSeek 文本分析

5. 核心功能规格

5.1 选区捕获

项目	规格
输入	当前 Obsidian 编辑器或阅读区域选中文本
最小长度	小于 2 个字符不处理
自动弹窗	禁止
保存状态	记录 selectionText 和 selectionSourcePath
切换选区	新选区会清空上一轮 AI 分析和图片结果

5.2 右键菜单

菜单项	功能
打开英语学习卡片	显示悬浮卡片，但不自动调用 AI
AI 语法拆解	打开卡片并调用文本模型分析
保存英语学习卡	触发手动标题弹窗，保存 Markdown / Canvas / Review

5.3 左侧 Ribbon 图标

行为	说明
有选区	捕获选区并打开卡片
无选区但已有缓存	打开最近一次选区对应卡片
无选区且无缓存	提示“请先选中英文词句”

5.4 AI 语法拆解

AI 输出必须固定为四个字段：

字段	中文名称	输出要求
sentence_main	句子主干	提炼主谓宾、核心动作、核心信息
grammar_structure	语法结构	分析从句、非谓语、时态、连接词、修饰关系
translation	翻译	自然准确的中文翻译
sentence_pattern_expansion	句型拓展	提炼可复用句型，并生成例句

5.5 保存学习卡片

保存前必须弹出标题输入框：

标题规则	说明
手动输入	标题不能自动引用原文
最大长度	140 个字符
不能为空	空标题不可保存
推荐写法	用“用途 + 场景 + 语法点”命名，例如“自我介绍信中的亲属关系表达”

Markdown 保存结构：

## 手动标题

- 类型：英语学习卡片
- 创建时间：ISO 时间
- 来源笔记：source
- 作者：TonyWang

### 1. 标题
手动标题

### 2. 原文
> 选中的英文原文

### 3. 句子主干
AI 输出

### 4. 语法结构
AI 输出

### 5. 翻译
AI 输出

### 6. 句型拓展
AI 输出

### 7. 复习状态
- [ ] 已理解句子主干
- [ ] 已掌握语法结构
- [ ] 已能复用句型造句

5.6 Canvas 归档

项目	规格
文件	English/归档汇总.canvas
节点类型	text node
节点内容	标题、原文、句子主干、语法结构、翻译、句型拓展、作者
布局	按网格横向排列
默认开关	可在设置页开启/关闭

5.7 复习队列

项目	规格
文件	English/Review.md
默认复习时间	保存后次日
内容	日期、标题、原文摘要
未来升级	可加入熟悉度、复习次数、SRS 间隔算法

5.8 一键生图

项目	规格
触发方式	只能点击“生成记忆图”按钮触发
风格	卡通图 / 真实场景图
提示词来源	原文 + AI 分析结果 + 风格要求
图片接口	独立 Image API Endpoint
默认保存	English/MemoryImages
输出格式	b64_json 或 url 下载保存

6. API 与模型设计

6.1 文本分析 API

文本分析使用 OpenAI-compatible Chat Completions 风格设计，目的是让 DeepSeek、OpenAI 或其他兼容服务可替换。

配置项	示例	说明
API Provider Preset	DeepSeek / OpenAI / Custom	模型服务预设
API Key	sk-xxx	文本模型认证
API Base URL	https://api.deepseek.com	服务根地址
Model	deepseek-v4-flash	文本分析模型
JSON response_format	开启/关闭	强制结构化输出
Temperature	0.2	降低输出漂移
Max Tokens	2200	控制最长输出

6.2 为什么用 Provider 设计

问题	Provider 设计的价值
用户当前用 DeepSeek	默认提供 DeepSeek 配置
后续可能换 OpenAI	只需要换 Base URL / Model / Key
第三方 API 参数不一致	Custom 模式保留兼容空间
模型名容易写错	预设可以减少配置错误
response_format 可能导致 400	设置项允许关闭 JSON 模式

6.3 图片生成 API

图片生成与文本分析分开配置。

配置项	示例	说明
Image API Key	sk-xxx	图片服务 Key
Image API Endpoint	https://api.openai.com/v1/images/generations	图片生成接口
Image Model	gpt-image-1-mini	图片模型
Image Size	1024x1024	图片尺寸
Image Quality	low	成本与质量平衡
Image Output Folder	English/MemoryImages	本地保存路径

6.4 为什么生图不用 DeepSeek 主接口

判断	说明
DeepSeek 适合文本分析	用于句子主干、语法结构、翻译、句型拓展、图片提示词
图片生成需要独立 API	图像模型通常有不同 endpoint、参数和返回结构
独立配置更稳定	避免把文本 API Key、图片 API Key、模型名混在一起
成本可控	用户只有明确点击生图按钮时才消耗图片额度

7. 数据结构设计

7.1 内部状态

状态	作用
selectionText	当前选中的英文原文
selectionSourcePath	来源笔记路径
currentAnalysis	当前 AI 分析结果
currentImage	当前生成图片或提示词结果
lastSelectionHash	判断选区是否变化
panelEl	悬浮卡片 DOM
dragState	卡片拖动状态

7.2 AI 分析对象

{
  "sentence_main": "句子主干",
  "grammar_structure": "语法结构",
  "translation": "翻译",
  "sentence_pattern_expansion": "句型拓展",
  "raw_ai_output": "兜底原始输出"
}

7.3 图片对象

{
  "prompt": "图片提示词",
  "style": "cartoon 或 realistic",
  "path": "Vault 内图片路径",
  "src": "Obsidian resource path 或外部 URL",
  "url": "可选外部图片 URL"
}

7.4 Canvas 节点结构

{
  "id": "tea-时间戳-hash",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 600,
  "height": 500,
  "text": "# 标题\n\n## 原文\n..."
}

8. 设置页说明

8.1 文本模型设置

设置项	推荐值	说明
API Provider Preset	DeepSeek	当前推荐使用 DeepSeek 进行文本分析
API Base URL	https://api.deepseek.com	DeepSeek API 入口
Model	deepseek-v4-flash	日常英语学习够用
Use JSON response_format	开启	让 AI 输出结构稳定
Temperature	0.2	减少随机性
Max Tokens	2200	适合中短段落分析

8.2 发音与归档设置

设置项	推荐值	说明
Voice Language	en-US / en-GB	美音或英音
Voice Rate	0.92	适合跟读
Vocabulary File	English/Vocabulary.md	学习卡片总表
Canvas File	English/归档汇总.canvas	视觉归档
Review File	English/Review.md	复习队列
Auto write Canvas	开启	保存时同步归档
Auto write Review	开启	保存时加入复习
Floating card width	620	可按屏幕尺寸调整

8.3 生图设置

设置项	推荐值	说明
Image API Endpoint	https://api.openai.com/v1/images/generations	OpenAI Images 接口示例
Image Model	gpt-image-1-mini	成本优先
Image Size	1024x1024	记忆卡片足够
Image Quality	low	控制成本
Image Output Folder	English/MemoryImages	图片资产集中保存

9. 错误处理与边界条件

9.1 常见错误

错误	可能原因	处理方式
请先选中英文词句	没有捕获到选区	重新选中文本后右键打开
AI 请求失败 HTTP 400	模型名、Base URL、JSON response_format 不兼容	检查模型名；必要时关闭 JSON response_format
HTTP 401 / 403	API Key 错误或无权限	重新生成 Key 并填写
没有返回 message.content	API 不兼容 Chat Completions 格式	更换兼容接口或适配 Provider
生图失败	Image API Key / endpoint / model 不正确	检查生图设置
图片未保存	返回格式不是 b64_json 或 url	适配该图片服务返回结构
Canvas 无法打开	JSON 格式损坏	回滚文件或重新创建 Canvas

9.2 重要边界

边界	当前处理
过长原文	由 Max Tokens 和模型上下文决定，当前不做分段
多语言原文	当前主要按英文学习场景设计
PDF 选区	如果 Obsidian 能复制到 window selection，则可部分支持；未做专门 PDF 阅读器适配
Canvas 内文本选区	依赖 Obsidian DOM 选区能力，需实测
移动端	插件声明非 desktop-only，但拖动和右键体验主要面向桌面端

10. 安全与隐私说明

10.1 数据流向

数据	是否离开本地	说明
选中英文原文	是，调用 AI 时发送给文本模型 API	用于语法拆解和翻译
图片提示词	是，调用 Image API 时发送给图片模型服务	用于生成记忆图
学习卡片 Markdown	否，保存在 Vault	除非用户同步 Vault
Canvas 文件	否，保存在 Vault	除非用户同步 Vault
API Key	本地插件设置保存	不应提交到公开仓库

10.2 安全建议

建议	原因
API Key 不写入代码	防止泄露后产生费用
单独为插件创建 Key	便于额度统计和失效管理
Git 同步时忽略插件 data.json	防止 Key 被同步到远程仓库
不上传敏感英文资料	模型 API 会接收选中文本
生图前检查原文	防止误把隐私内容发给图片服务

建议在 .gitignore 中加入：

.obsidian/plugins/tony-english-assistant/data.json
.obsidian/plugins/tony-english-assistant/settings.json

11. 验收标准

11.1 功能验收

编号	测试项	操作	预期结果
A-01	选中不自动弹窗	选中英文句子	不出现卡片
A-02	右键打开卡片	选中文本后右键	出现“打开英语学习卡片”
A-03	左侧图标打开卡片	选中文本后点击 Ribbon 图标	出现悬浮卡片
A-04	卡片拖动	拖动卡片顶部	卡片位置改变
A-05	发音	点击发音	系统朗读原文
A-06	AI 语法拆解	点击 AI 语法拆解	输出四段结构化内容
A-07	标题保存	点击保存卡片	弹出标题输入框
A-08	标题限制	输入 141 字符标题	阻止保存或提示错误
A-09	Markdown 归档	保存卡片	写入 Vocabulary.md
A-10	Canvas 归档	开启自动 Canvas	写入 .canvas 文件
A-11	复习队列	开启自动 Review	写入 Review.md
A-12	生图手动触发	不点击生图按钮	不调用 Image API
A-13	生图生成	配置 Image API 后点击按钮	生成图片并保存到 MemoryImages

11.2 体验验收

编号	标准	目标
UX-01	用户选中文本后不被打断	0 次自动弹窗
UX-02	打开卡片步骤	≤2 步
UX-03	卡片主要内容可滚动	长内容不被截断
UX-04	主要按钮可见	发音、分析、保存、生图均可直接点击
UX-05	生图成本可控	只在用户明确点击时消耗图片额度

11.3 技术验收

编号	标准	目标
T-01	main.js 语法检查	`node --check main.js` 通过
T-02	manifest 版本一致	manifest.json 与 package.json 版本一致
T-03	API 错误展示	显示 HTTP status 和 error detail
T-04	文件夹自动创建	English 子目录不存在时自动创建
T-05	JSON Canvas 合法	Canvas 文件可被 Obsidian 打开

12. 迭代路线图

12.1 V1.2 建议

功能	优先级	原因
设置页一键测试 Image API	P0	当前只支持测试文本 API，生图配置更容易出错
卡片位置记忆	P1	用户希望下次打开保持上次位置
卡片大小手动拖拽调整	P1	长文场景需要更大阅读区
图片插入 Markdown 卡片	P1	当前图片可保存，后续应自动写入卡片
生图提示词可编辑	P1	用户可能想控制画面内容
选区来源定位	P2	从学习卡片回到原文位置

12.2 V1.3 建议

功能	优先级	原因
SRS 间隔复习算法	P0	把 Review.md 从队列升级为复习系统
熟悉度 0-5 分	P0	量化掌握程度
学习统计面板	P1	统计今日新增、复习、掌握率
标签体系	P1	支持考研、商务、产品、技术等分类
批量分析	P2	一次处理多句或整段文本

12.3 V2.0 建议

功能	价值
PDF/EPUB 阅读器内查词	从 Markdown 扩展到文档阅读
本地词库接入	降低 API 成本，支持离线解释
多 Provider 适配器抽象	DeepSeek / OpenAI / Claude / Gemini / OpenRouter 独立封装
插件内学习面板	从悬浮卡升级为完整学习工作区
卡片模板可视化编辑	用户自定义输出结构

13. 版本管理规范

13.1 版本号规则

类型	示例	说明
Patch	1.1.1	修复 bug，不改变功能结构
Minor	1.2.0	新增功能，但保持兼容
Major	2.0.0	架构大改或数据结构大改

13.2 每次迭代必须更新的文件

文件	更新内容
manifest.json	version、description
package.json	version、description
README.md	新功能、安装、配置、已知问题
main.js	功能逻辑
styles.css	UI 样式
产品文档	需求、验收、风险、变更记录

13.3 变更记录模板

## Vx.x.x 更新记录

### 新增
-

### 修复
-

### 调整
-

### 移除
-

### 已知问题
-

### 验收结果
- [ ] main.js 语法检查通过
- [ ] 插件可启用
- [ ] 核心流程通过
- [ ] 设置页可保存
- [ ] API 错误可提示

14. 类似插件开发复用框架

14.1 复用方法论

以后我开发类似 Obsidian 学习类插件时，建议固定采用以下结构：

1. 明确学习场景
2. 定义用户选区/输入入口
3. 设计手动触发动作
4. 构建悬浮卡片或侧边栏
5. 调用 AI 生成结构化结果
6. 写入 Markdown 学习资产
7. 写入 Canvas 或 Review 形成复盘
8. 增加设置页管理 API、路径、模板
9. 增加错误提示和验收清单
10. 建立版本迭代文档

14.2 可复用的插件模块

模块	可复用价值
选区捕获模块	适合翻译、摘要、摘录、批注插件
手动激活入口	适合避免自动弹窗干扰的插件
悬浮卡片模块	适合轻量交互工具
拖动模块	适合所有浮窗类插件
Provider API 模块	适合多模型兼容插件
Markdown 写入模块	适合知识沉淀类插件
Canvas 写入模块	适合视觉归档类插件
Review 队列模块	适合学习复习类插件
图片生成模块	适合视觉记忆、图文笔记插件
设置页模块	适合所有需要配置 API 的插件

14.3 成功率最高的开发顺序

阶段	目标	不建议做什么
MVP	先跑通选区 → 卡片 → AI → Markdown	不先做复杂 UI
V0.5	加入稳定设置页和错误提示	不先做多模型复杂抽象
V1.0	固化学习卡片结构	不频繁改数据格式
V1.1	优化交互摩擦	不自动触发高成本 API
V1.2+	增强复习、图像、统计	不破坏旧数据兼容

15. 当前已知风险

风险	等级	说明	应对
Image API 兼容性	高	不同服务商图片接口返回格式不一致	V1.2 增加 Provider 适配器
移动端体验	中	右键和拖动主要适合桌面端	后续增加命令面板和移动端按钮
长文本分析	中	过长原文可能超出模型输出限制	增加分段分析
Canvas 节点膨胀	中	大量卡片会让 Canvas 变重	增加分文件归档或按日期归档
API Key 泄露	高	用户误把 data.json 同步到公开仓库	README 和设置页增加安全提醒
自动测试不足	中	当前主要是语法检查，缺少真实 Obsidian 环境测试	建立人工验收脚本和测试 Vault

16. 最终总结表

维度	我的结论	后续动作
产品定位	Obsidian 英语学习助手，不是单纯翻译插件	保持学习闭环设计
交互策略	手动激活优于自动弹窗	保留右键和 Ribbon 两个入口
核心卡片	原文 + AI 四段分析 + 手动标题	后续支持模板自定义
模型架构	文本模型和图片模型分离	增强 Provider 适配层
数据沉淀	Markdown / Canvas / Review 三层归档	增加学习统计和 SRS
生图能力	只在用户点击时触发	增加提示词编辑和图片写入卡片
迭代管理	每版更新文档、README、manifest、验收清单	形成稳定发布流程
复用价值	可作为 Obsidian AI 学习类插件模板	复用入口、浮窗、API、归档模块

17. 外部依据与参考链接

以下链接用于后续开发时核对 API 与插件生态能力，实际参数以对应服务商最新文档为准。

Obsidian Developer Docs：插件开发、命令、事件、设置页、Vault 文件读写。
DeepSeek API Docs：https://api-docs.deepseek.com/
OpenAI API Reference - Images：https://platform.openai.com/docs/api-reference/images/create
JSON Canvas Specification：https://jsoncanvas.org/
Obsidian Sample Plugin：https://github.com/obsidianmd/obsidian-sample-plugin