# reminder-adi

**Repository Path**: andershsueh/reminder-adi

## Basic Information

- **Project Name**: reminder-adi
- **Description**: No description available
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Reminder Adi

Windows 系统托盘应用：驻留任务栏右下角，点击图标弹出菜单（Hello、分隔线、Exit），点 Exit 退出。采用 Python + pystray，不做原生 GUI；需要“看到”或鼠标操作时，用浏览器打开本地页面或本地 HTTP。

---

## 一、需求与目标

- **运行环境**：Windows 10/11
- **形态**：驻留任务栏右下角（系统托盘）
- **图标**：`./images/logo.ico`
- **交互**：点击托盘图标弹出菜单
  - `Hello`
  - `-`（分隔线）
  - `Exit`
- **行为**：点击 `Exit` 退出应用

---

## 二、设计原则

- **不做原生 GUI**：应用本身不包含窗口、对话框等桌面界面。
- **可视化交给浏览器**：当用户需要“看到”内容或进行鼠标操作时，由托盘程序打开**系统默认浏览器**，展示本地 HTML 或本地 HTTP 服务页面；用完即关标签页，不常驻桌面。
- **保持应用简洁**：托盘只负责常驻、菜单与后台逻辑；界面迭代用 HTML/CSS/JS 即可，无需引入 Electron 等重框架。

---

## 三、技术栈

| 项 | 说明 |
|----|------|
| 运行时 | Python 3（建议 3.9+） |
| 托盘 | pystray |
| 图标 | Pillow 加载 `./images/logo.ico` |
| 可视化策略 | 需要时启动本地 HTTP 或打开本地 HTML，用 `webbrowser.open()`；不做原生窗口 |
| 打包（可选） | PyInstaller，产出 Windows 单 exe，将 `images/logo.ico` 一并打包 |

---

## 四、项目结构

```
reminder-adi/
├── images/
│   └── logo.ico              # 托盘图标
├── documents/                 # 计划与报告
│   ├── plan-1.md, plan-2.md  # 工作计划
│   ├── dev-1.md, dev-2.md    # 开发步骤与测试方法
│   ├── test-rpt.md, test-rpt-2.md  # 测试结果记录表
│   └── about qwen-code.md    # qwen CLI 帮助说明
├── module_part/               # 功能模块（由主模块调用）
│   ├── webhook_sender.py      # 读取 config 的 webhook，向飞书发送消息
│   └── qwen_webhook.py        # 调用 qwen -y -p 获取输出并总结，可发飞书
├── test/                      # 测试脚本
├── logs/                      # 应用日志（按小时轮转）
├── temp_files/                # 临时文件（如录音、生成文件）
├── config.py                  # 配置（webhook_url、webhook_keyword 等）
├── main.py                    # 入口：托盘、菜单、生命周期
├── requirements.txt           # pystray, Pillow
└── README.md                  # 本说明
```

---

## 五、运行与构建

### 运行（开发环境）

```bash
# 安装依赖
pip install -r requirements.txt

# 带控制台运行（便于调试）
python main.py

# 无控制台运行（仅托盘，推荐日常使用；不会出现黑窗口）
pythonw main.py
```

**步骤 1 自检**：`python main.py --check` 会输出 `ok` 后退出，用于验证依赖与入口。

### 配置（config.py）

- `webhook_url`：飞书机器人 Webhook 地址。
- `webhook_keyword`：飞书要求的关键字（如 `[Reminder-Adi]`），发送时放在正文开头。

### 测试

```bash
# 飞书 webhook 发送测试（发送 "test ok"）
python test/test_webhook_sender.py

# qwen 最简测试（qwen -y -p "hello"）
python test/test_qwen_minimal.py

# qwen 总结 plan-2 技术难点并发送飞书
python test/test_qwen_webhook_plan2.py
```

使用 qwen 相关功能需本机已安装 [qwen-code](https://github.com/QwenLM/qwen-code) 并在 PATH 中；详见 `documents/about qwen-code.md`。  
语音转写（Whisper）需本机已安装 **ffmpeg** 并加入 PATH（如 `winget install ffmpeg` 或从 [ffmpeg.org](https://ffmpeg.org) 下载）；未安装时录音后转写会失败，日志中会提示“未找到 ffmpeg”。  
提高转写准确率：在 `config.py` 中可配置 `whisper_model`（如 small/medium）、`whisper_language`（如 "zh"）、`whisper_initial_prompt`（可能出现的词，空格分隔）；转写完成后会用 qwen 做同音字/错别字纠错。

### 打包（可选）

- 使用 PyInstaller，将 `images/logo.ico` 通过 `--add-data` 打入包内，运行时用 `sys._MEIPASS` 解析资源路径。
- 打包时加 `--noconsole`（或 `-w`），生成无黑窗口的 exe。
- 系统要求：Windows 10+；若仅运行 exe 则无需安装 Python。

---

## 六、开发与测试规范

### 目录约定

| 目录 | 用途 |
|------|------|
| `./test` | 所有测试脚本、测试用例均放在此目录。 |
| `./logs` | 应用生成的日志文件均放在此目录；日志按小时轮转。 |

### 日志要求

- 每一步动作（启动、创建托盘、菜单点击、退出、单实例检测等）都应有日志输出。
- 日志输出到 `./logs`；按小时轮转（如 `logging` + `TimedRotatingFileHandler`），避免单文件无限增大。

### 测试与报告

- 每完成一步开发，按 [documents/dev-1.md](documents/dev-1.md) 中该步骤的「测试方法」执行测试。
- 每通过或不通过一个测试点，在 **[documents/test-rpt.md](documents/test-rpt.md)** 中更新对应行的「结果」（通过/不通过）与「备注」。

---

## 七、文档索引

| 文档 | 说明 |
|------|------|
| [documents/plan-1.md](documents/plan-1.md) | 工作计划（托盘应用） |
| [documents/plan-2.md](documents/plan-2.md) | 工作计划（热键+按住说话录音） |
| [documents/dev-1.md](documents/dev-1.md) | 开发步骤（托盘） |
| [documents/dev-2.md](documents/dev-2.md) | 开发步骤（热键+录音） |
| [documents/test-rpt.md](documents/test-rpt.md) | 测试报告（托盘） |
| [documents/test-rpt-2.md](documents/test-rpt-2.md) | 测试报告（热键+录音） |
| [documents/about qwen-code.md](documents/about%20qwen-code.md) | qwen CLI 帮助说明 |

---

## 八、验收标准

- [ ] 在 Windows 下执行 `python main.py` 或 `pythonw main.py` 后，任务栏右下角出现托盘图标，且为 `logo.ico`。
- [ ] 点击托盘图标，弹出菜单，从上到下为：`Hello`、分隔线、`Exit`。
- [ ] 点击 “Hello” 有可识别反馈（如提示框或占位逻辑，后续可改为打开浏览器页面）。
- [ ] 点击 “Exit” 后进程完全退出，托盘图标消失。
- [ ] 无多余窗口、无控制台窗口常驻（使用 `pythonw` 或打包时 `--noconsole`）。

---

## 九、风险与注意事项

- **图标路径**：开发时用 `__file__` 解析项目根与 `images/logo.ico`；PyInstaller 打包后资源在 `sys._MEIPASS`，需在运行时根据是否打包选择路径。
- **杀毒/防火墙**：部分环境下 PyInstaller 打包的 exe 可能被拦截，可说明“需允许运行”或后续考虑签名。
- **单实例**：若不加单实例锁，多次启动会多个托盘图标；可选在开发步骤中完成单实例逻辑。
- **浏览器依赖**：可视化依赖用户已安装的默认浏览器；本地 HTTP 仅监听 127.0.0.1，不对外网开放。

---

## 十、后续扩展方向（供参考）

- “Hello” 可改为：打开本地页面或本地 HTTP 地址（如 `http://127.0.0.1:port/settings`），在浏览器中做设置或提醒列表。
- 增加定时提醒、系统通知（如 Windows 通知 API 或 toast）。
- 增加开机自启（Windows 注册表或快捷方式放入启动文件夹）。
- 本地 HTTP 可用 Flask/FastAPI 等轻量框架，仅监听 127.0.0.1，与托盘进程同进程或子进程即可。