Skip to content

Commit 0964ccf

Browse files
trvs-labtrvs-lab
authored
Merge pull request #7 from wzhulifantastic/feat/field-specific-prompts
feat: v 0.2.0 Field_Prompt Update & Strict JSON Protocol
2 parents dfdf5b3 + 7567bbd commit 0964ccf

File tree

11 files changed

+1852
-1738
lines changed

11 files changed

+1852
-1738
lines changed

‎CHANGELOG.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,52 @@
11
# LexiSage 更新日志
22

3+
## 版本 0.2.0 - 2026-01-12（架构重构版）
4+
**“从单点释义到全维解析的进化”**
5+
6+
本次更新是 LexiSage 发布以来最大规模的底层重构，全面支持多字段精细化生成与智能控制。
7+
8+
### 🚀 核心新功能
9+
10+
- **多字段精细化映射（Granular Field Mapping）**
11+
支持为每个笔记类型配置任意数量的目标字段，并为每个字段单独设置 Prompt。例如：一次生成即可同时填充 Meaning（中文释义）、Synonyms（同义词辨析）、Grammar（语法点）和 Sentences（场景例句）。
12+
13+
- **智能提示词路由（Smart Prompt Router）**
14+
若字段未配置自定义 Prompt，系统将根据字段名（如 `Synonym`、`Grammar`、`Example`）向AI发出默认内置指令。AI人设为“雅思 8 分导师”，涵盖费曼学习法释义、同义词深度辨析等策略。
15+
16+
- **非破坏性更新策略（Non-Destructive Update）**
17+
- **更新模式（默认）**：仅填充空字段，跳过已有内容，保护手动编辑数据。
18+
- **覆盖模式（新增）**：通过独立“覆盖”按钮强制重写所有目标字段，避免误操作。
19+
20+
- **可视化任务预检（Pre-flight Check）**
21+
批量执行前弹出统计窗口，清晰展示：选中笔记数、待填充空字段数、将跳过的非空字段数，消除操作不确定性。
22+
23+
### 🔧 交互与体验改进
24+
25+
- **全新设置界面（UI 2.0）**
26+
重写配置 UI，新增“已配置字段列表”视图，支持动态增删字段映射；集成 Prompt 预览功能，可实时查看完整的 JSON Payload 结构。
27+
28+
- **脏数据清洗增强**
29+
自动识别并忽略仅含 ` `、空格或空 HTML 标签的字段，将其视为真正“空”字段进行填充。
30+
31+
- **按钮布局优化**
32+
将高风险的“覆盖”按钮与安全的“更新/取消”按钮物理隔离，显著降低误触风险。
33+
34+
### 🎯 底层架构升级
35+
36+
- **严格 JSON 协议（Strict JSON Protocol）**
37+
强制 AI 输出结构化 JSON，彻底解决旧版 Markdown 残留问题，大幅提升多字段回填稳定性。
38+
39+
- **任务扁平化（Task Flattening）**
40+
重构多线程 Worker，支持单张笔记内多个字段任务的并发处理，提升批量效率。
41+
42+
- **事务安全机制**
43+
引入数据库事务：若操作被取消或发生错误，自动回滚，杜绝“半写入”脏数据。
44+
45+
- **代码整洁化**
46+
全面重构变量命名，移除冗余逻辑，显著提升可读性与可维护性。
47+
48+
---
49+
350
## 版本 0.1.8 - 2024-01-04
451

552
### 🚀 新功能

‎DEVELOPMENT.md‎

Lines changed: 175 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,61 +2,202 @@
22

33
[中文](DEVELOPMENT.md) | [English](DEVELOPMENT_EN.md)
44

5-
本文档提供了有关如何开发、构建和贡献LexiSage项目的详细信息。
5+
本文档提供了有关如何开发、构建和贡献LexiSage项目的详细信息。LexiSage是一个Anki插件，利用AI为语言学习者生成单词释义、同义词、语法说明和例句。
66

7-
## 环境设置
8-
1. 克隆此仓库
9-
2. 确保您已安装Python 3.8+
10-
3. 安装依赖：`pip install -r requirements.txt`（如果有）
7+
## 项目架构概述
118

12-
## 项目结构
13-
- `__init__.py`: 插件入口点和主要功能
14-
- `config_ui.py`: 配置UI界面
15-
- `ai_service.py`: AI服务调用接口
16-
- `prompts.py`: 默认提示词模板
9+
LexiSage采用模块化设计，将不同功能分离到独立的Python文件中，便于维护和扩展。整个插件遵循MVC-like模式：
10+
- **模型层**：`ai_service.py` 和 `prompts.py` 处理数据逻辑和AI交互
11+
- **视图层**：`config_ui.py` 提供用户界面
12+
- **控制器层**：`__init__.py` 作为入口点协调各模块工作
13+
14+
## 文件结构详解
15+
16+
### 1. `__init__.py` - 插件入口点
17+
**核心功能**：插件的主要入口，负责注册Anki钩子、协调各个模块的工作。
18+
**主要内容**：
19+
- `BatchGenerationWorker`：后台线程类，用于批量生成释义，避免界面卡顿
20+
- `save_results()`：将AI生成的结果写回Anki数据库，包含事务处理
21+
- `on_browser_batch_generate()`：浏览器批量生成功能
22+
- `on_editor_gen()`：编辑器单卡生成功能
23+
- `setup_browser_menu()`：向Anki浏览器添加LexiSage菜单
24+
- `add_editor_button()`：向编辑器添加LexiSage按钮
25+
**关键特性**：
26+
- 完整的异常处理和资源清理
27+
- 数据库事务回滚机制，防止数据损坏
28+
- 进度对话框管理，确保界面响应
29+
30+
### 2. `ai_service.py` - AI服务层
31+
**核心功能**：封装与各种AI服务（OpenAI、XAI、DeepSeek）的通信逻辑。
32+
**主要内容**：
33+
- `generate_batch_explanation()`：核心函数，构建JSON payload并调用AI服务
34+
- `ExplanationTask`：表示单个释义生成任务的类
35+
- `ProgressTracker`：多线程进度跟踪器
36+
- `generate_explanations_batch()`：批量处理多个任务的函数
37+
- `format_text_to_html()`：清理AI返回文本的工具函数
38+
**关键特性**：
39+
- 支持多线程并发请求
40+
- 完整的日志记录系统（lexisage.log）
41+
- 自动重试机制（最大重试2次）
42+
- 统一的API接口，支持多种AI服务
43+
44+
### 3. `config_ui.py` - 配置界面
45+
**核心功能**：提供用户友好的配置界面，管理插件设置。
46+
**主要内容**：
47+
- `ConfigDialog`：主配置对话框类，包含三个标签页
48+
- `NoteTypeConfig`：笔记类型配置的数据类
49+
- 三个标签页：
50+
1. **笔记类型设置**：配置不同笔记类型的字段映射和提示词
51+
2. **AI系统指令**：设置全局AI系统提示词
52+
3. **AI服务设置**：配置API密钥、模型参数和高级选项
53+
**关键特性**：
54+
- 动态UI更新，实时预览AI发送内容
55+
- 配置验证和错误处理
56+
- 默认模板查看功能
57+
58+
### 4. `prompts.py` - 提示词管理
59+
**核心功能**：集中管理所有AI提示词模板，提供默认配置。
60+
**主要内容**：
61+
- `DEFAULT_GLOBAL_SYSTEM_PROMPT`：全局系统提示词，定义AI角色和行为规范
62+
- `DEFAULT_FIELD_PROMPT_TEMPLATE`：字段默认提示词，当字段未配置自定义提示词时使用
63+
- `BATCH_INSTRUCTION_TEMPLATE`：UI预览模板，仅用于显示目的
64+
**关键特性**：
65+
- 清晰的三层提示词架构（系统层、指令层、预览层）
66+
- 统一的字符串格式，支持变量替换（`{word}`, `{context}`）
67+
- 遵循"费曼原则"，强调通俗易懂的解释
68+
69+
## 代码架构优势
70+
71+
1. **关注点分离**：UI逻辑、业务逻辑和AI通信逻辑分离到不同文件
72+
2. **可扩展性**：易于添加新的AI服务或功能模块
73+
3. **可维护性**：清晰的模块边界和职责划分
74+
4. **错误处理**：全面的异常捕获和用户友好的错误提示
75+
5. **配置管理**：统一的配置系统，支持多种笔记类型
76+
77+
## 未来重构建议
78+
79+
### 1. 进一步模块化
80+
**建议**：将大型文件进一步拆分为更小的专用模块。
81+
- 创建 `threading_utils.py`：集中管理多线程相关代码（`BatchGenerationWorker`, `ProgressTracker`）
82+
- 创建 `database_utils.py`：处理所有数据库操作（`save_results`, 字段检查函数）
83+
- 创建 `logging_utils.py`：统一日志记录和错误处理
84+
85+
### 2. 配置系统改进
86+
**建议**：使用更结构化的配置管理。
87+
- 引入配置验证和迁移工具
88+
- 支持配置版本升级
89+
- 添加配置导入/导出功能
90+
91+
### 3. 测试框架
92+
**建议**：建立完整的测试套件。
93+
- 单元测试：测试各个模块的核心功能
94+
- 集成测试：测试模块间协作
95+
- 端到端测试：模拟真实Anki环境下的使用场景
96+
97+
### 4. 国际化支持
98+
**建议**：为多语言用户提供支持。
99+
- 提取所有UI文本到翻译文件
100+
- 支持动态语言切换
101+
- 提供翻译贡献指南
102+
103+
## 开发环境设置
104+
105+
1. **克隆仓库**：
106+
```bash
107+
git clone https://github.com/{你的用户名}/LexiSage.git
108+
cd LexiSage
109+
```
110+
111+
2. **Python环境**：
112+
- 需要Python 3.8或更高版本
113+
- 建议使用虚拟环境：`python -m venv venv`
114+
- 激活虚拟环境：
115+
- Windows: `venv\Scripts\activate`
116+
- macOS/Linux: `source venv/bin/activate`
117+
118+
3. **依赖安装**：
119+
```bash
120+
pip install requests
121+
# 其他依赖根据需求安装
122+
```
123+
124+
4. **Anki开发环境**：
125+
- 将插件目录链接到Anki的addons21文件夹
126+
- 重启Anki加载插件
127+
- 使用Anki的开发工具进行调试
17128

18129
## 打包插件
19-
1. 确保项目包含以下必要文件:
130+
131+
1. **确保包含必要文件**：
20132
- `__init__.py`: 插件入口点
21133
- `ai_service.py`: AI服务接口
22134
- `config_ui.py`: 配置界面
23135
- `prompts.py`: 默认提示词
24136
- `manifest.json`: 插件元数据，包含名称、版本等信息
25-
- `meta.json`: Anki版本兼容性信息(重要，决定支持的Anki版本)
26-
- `config.json`: 默认配置(可选)
27-
- `LICENSE`: 许可证文件 (GNU通用公共许可证v3.0)
137+
- `meta.json`: Anki版本兼容性信息（重要，决定支持的Anki版本）
138+
- `config.json`: 默认配置（可选）
139+
- `LICENSE`: 许可证文件（GNU通用公共许可证v3.0）
28140

29-
2. 更新版本号:
30-
- 在`manifest.json`文件中更新`version`字段
31-
- 在`ankiweb.json`文件中同步更新版本号(用于提交到AnkiWeb)
141+
2. **更新版本号**：
142+
- 在`manifest.json`中更新`version`字段
143+
- 在`ankiweb.json`中同步版本号
32144

33-
3. 使用以下命令打包:
145+
3. **打包命令**：
34146
```bash
35-
zip -r anki_lexisage.ankiaddon __init__.py ai_service.py config_ui.py prompts.py manifest.json meta.json LICENSE config.json -x ".*" "__pycache__/*" "*.pyc"
147+
zip -r LexiSage.ankiaddon __init__.py ai_service.py config_ui.py prompts.py manifest.json meta.json LICENSE -x ".*" "__pycache__/*" "*.pyc"
36148
```
37149

38-
4. 验证打包内容:
150+
4. **验证打包内容**：
39151
```bash
40-
unzip -l anki_lexisage.ankiaddon
152+
unzip -l LexiSage.ankiaddon
41153
```
42-
确保只包含必要文件，没有多余的`.git`、`__pycache__`等文件
43-
44-
5. 测试安装:
45-
- 在测试环境中通过Anki的"从文件安装插件"功能安装`.ankiaddon`文件
46-
- 验证插件功能是否正常运行
154+
确保不包含`.git`、`__pycache__`等多余文件。
47155

48156
## 提交到AnkiWeb
157+
49158
1. 注册[AnkiWeb账户](https://ankiweb.net/account/register)
50-
2. 登录后，访问[共享页面](https://ankiweb.net/shared/info/)
51-
3. 点击"Upload Add-on"提交你的插件
52-
4. 填写插件信息并上传打包好的文件
159+
2. 登录后访问[共享页面](https://ankiweb.net/shared/info/)
160+
3. 点击"Upload Add-on"提交插件
161+
4. 填写插件信息并上传打包文件
53162
5. 等待审核通过
54163

55164
## 贡献指南
165+
56166
欢迎贡献代码、报告问题或提出新功能建议！
57167

58-
1. Fork此仓库
59-
2. 创建您的特性分支: `git checkout -b feature/amazing-feature`
60-
3. 提交您的更改: `git commit -m '添加了一些很棒的功能'`
61-
4. 推送到分支: `git push origin feature/amazing-feature`
62-
5. 开启一个Pull Request
168+
1. **Fork仓库**：在GitHub上fork此仓库
169+
2. **创建分支**：`git checkout -b feature/your-feature-name`
170+
3. **提交更改**：`git commit -m 'Add some feature'`
171+
4. **推送分支**：`git push origin feature/your-feature-name`
172+
5. **创建PR**：在GitHub上创建Pull Request
173+
174+
### 代码规范
175+
- 遵循PEP 8代码风格
176+
- 添加适当的注释和文档字符串
177+
- 确保新功能有相应的错误处理
178+
- 更新相关文档
179+
180+
### 测试要求
181+
- 新功能应包含测试用例
182+
- 确保现有测试通过
183+
- 更新测试文档
184+
185+
## 故障排除
186+
187+
### 常见问题
188+
1. **AI服务连接失败**：检查API密钥和网络连接
189+
2. **配置保存失败**：检查文件权限和磁盘空间
190+
3. **UI显示异常**：重启Anki或清除缓存
191+
192+
### 调试技巧
193+
1. **查看日志文件**：在运行过一次填充字段后，`lexisage.log`记录了所有API请求和错误
194+
2. **简化配置**：从最小配置开始，逐步添加复杂功能
195+
196+
## 许可证
197+
198+
本项目采用GNU通用公共许可证v3.0 (GPL-3.0)。详情请参阅[LICENSE](LICENSE)文件。
199+
200+
---
201+
202+
*最后更新：2026年1月*
203+
*版本：基于LexiSage当前架构的分析和优化建议*

0 commit comments

Comments
 (0)