# Claude AI 助手记忆 - Anki 插件开发

本文档为 Claude Code 提供专业的 Anki 插件开发指导和项目上下文信息。

请在每一轮对话中都牢记以下规则：

1. 在确定执行计划和生成代码时，应始终优先考虑使用同级目录下 **ANKI.md** 中的最新开发模式
2. 当编写的代码无法实现预期效果的时候，请重新认真阅读  **ANKI.md** 中的开发模式和示例
3. 如果 **ANKI.md** 中没有相应内容，则搜索项目根目录下 `.venv` 下 `anki` 和 `aqt` 两个核心库的源代码
4. 绝对不要使用网络搜索查找对应的 API 和方法，网络上的内容已全部过时，没有任何参考价值

## 开发决策原则

1. **功能实现** > 技术完美
2. **简单可靠** > 复杂优雅  
3. **易于维护** > 展示技巧
4. **满足需求** > 过度设计

## 参考资料

1. **优先项目文档**: 项目根目录下 `ANKI.md` 中的 API 详解和最佳实践
2. **辅助本地源代码**: 如果 `ANKI.md` 中没有相应内容，则检查项目根目录下 `.venv` 下 `anki` 和 `aqt` 两个核心库的源代码
3. **禁止网络搜索**: 网络上可以搜集到的内容已全部过时，绝对不要搜索和参考使用

## 项目技术栈

- **src-layout**: 最佳实践项目结构
- **python**: Python 3.13，充分利用静态类型特性。
- **qt6**: PyQt 6.9，通过 `aqt.qt.*` 导入其 Anki 绑定
- **uv**: 强制使用 uv 管理当前目录下项目的依赖
- **ruff**: 强制使用 `uv ruff` 进行代码语法检查和格式化
- **ty**: 强制使用 `uv ty` 进行静态类型检查
- **aadt**: 尽可能使用 aadt 库的相关功能辅助进行快速的开发

### UI 开发

- **仅支持 Qt6**: 此项目仅支持 Qt6，不要添加 Qt5 的兼容代码
- **直接调整 .ui 文件**: 需要修改 UI 设计时，直接修改根目录下 `ui/designer` 子目录中的 `.ui` 文件
- **使用 aadt 转化 ui 文件**: 不要手动进行转化和复制，而是使用 `aadt ui` 命令自动转化 
- **资源文件**: 禁止使用 QRC 文件，使用直接文件路径，放在 `ui/resources` 子目录中

## 项目结构

```
your-addon/
├── src/your_module/            # 主 Python 包 (src-layout)
│   ├── __init__.py             # 插件入口点和主要功能
│   └── gui/                    # 编译的 UI 文件 (使用 aadt 从 .ui 转换)
├── ui/                         # UI 源文件
│   ├── designer/               # Qt Designer .ui 文件
│   └── resources/              # UI 资源 (图标、样式等)
├── tests/                      # 测试文件 (TDD 方法)
├── addon.json                  # 插件配置
├── pyproject.toml              # 项目配置和依赖
├── .python-version             # Python 版本规范
├── README.md                   # 插件说明
├── ANKI.md                     # ANKI 核心库详解
└── CLAUDE.md                   # 本文件
```

## 依赖管理

本项目使用单一 `dev` 组包含所有开发依赖：

```bash
# 安装/更新所有开发依赖
uv sync --group dev

# 包含:
# - anki>=25.6                  # Anki 核心库
# - aqt>=25.6                   # Anki 专属 PyQt6 库
# - aadt>=1.1.0                 # 开发工具库
# - ruff>=0.12.1                # 快速代码检查和格式化
# - ty>=0.0.1a14                # 静态类型检查
# - pytest>=8.0.0               # 测试框架
```
