# PersonalAssistant

**Repository Path**: linght/personal-assistant

## Basic Information

- **Project Name**: PersonalAssistant
- **Description**: PersonalAssistant
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人助手（PersonalAssistant）

常驻 Windows 系统托盘的私人助手：任务管理 + 到期/每日提醒 + 自动周报。**支持 Kimi K3 自然语言录入与 AI 润色**。

## 快速开始

```bash
pip install -r requirements.txt
mkdir data
cp config.example.json data/config.json
# 编辑 data/config.json：
#   - ai.api_key 填 Kimi K3 的 key（platform.kimi.com 申请，K3 需充值解锁）
#   - ai.base_url 保持 https://api.moonshot.cn/v1
#   - ai.model 保持 k3
#   - db_path / report_dir 指向你的 OneDrive/坚果云同步目录
python run.py
```

启动后系统托盘出现图标，右键：

- **打开主窗口**：录入任务、查看今日/本周、手动生成晨报/周报
- **立即生成今日晨报**：手动触发每日晨报
- **立即生成本周周报**：手动触发周报
- **退出**

### 验证 Kimi K3 配置

```bash
python scripts/probe_kimi.py
# 探活成功会输出 [OK] 探活成功 ✓
```

## 功能

| 功能 | 说明 |
|---|---|
| **自然语言录入** | 主窗口「录入」Tab 顶部输入框，一句话录入（"下周三下午要交月报"），AI 自动解析为标题/截止时间/优先级/分类 |
| 手动表单录入 | 同 Tab 下方的表单：标题/截止时间/优先级/分类/备注 |
| 到期提醒 | 距截止时间 60 分钟（`lead_minutes`）弹 Toast，按钮可「完成」或「推迟 30 分钟」 |
| 免打扰 | 23:00-07:00（`quiet_hours`）期间不弹到期提醒 |
| 逾期标记 | 过了截止时间未完成 → 自动标 `overdue` 并通知 |
| **每日晨报**（AI） | 每天 09:00 汇总今日 + 逾期任务，Kimi K3 生成简洁晨报，Toast 提醒 + 落库 |
| **周报**（AI） | 每周五 17:00 生成本周周报 MD，Kimi K3 润色并推断下周计划，保存到 `report_dir` |
| 多设备同步 | `db_path` 指向云盘目录，SQLite 文件天然同步 |
| 开机自启 | `python scripts/install_autostart.py` |

## AI 降级机制

所有 AI 调用失败时自动降级，**绝不打断流程**：

- **录入失败** → 整句作为标题，无截止时间，priority=medium
- **晨报/周报 AI 失败** → 走纯规则模板（带 ✅⏳ 图标的列表）
- **AI 客户端初始化失败**（启动时） → 纯规则模式启动，启动日志显示 `AI=off`

启动日志能看到当前状态：`个人助手启动，托盘运行中（AI=on）` 或 `（AI=off）`。

## 测试

```bash
pytest
```

## 配置说明

见 `config.example.json`。运行时配置在 `data/config.json`（gitignored）。

关键配置项：

| 配置 | 默认 | 说明 |
|---|---|---|
| `ai.base_url` | `https://api.moonshot.cn/v1` | Kimi 官方 OpenAI 兼容端点 |
| `ai.model` | `k3` | 模型名（需在 platform.kimi.com 开通 K3） |
| `ai.api_key` | — | Kimi API Key |
| `db_path` | — | SQLite 文件路径，建议放云盘目录 |
| `report_dir` | — | 周报 MD 输出目录，建议放云盘目录 |
| `reminder.lead_minutes` | `60` | 提前几分钟提醒 |
| `reminder.quiet_hours` | `23:00-07:00` | 免打扰时段（支持跨午夜） |
| `daily.time` | `09:00` | 每日晨报触发时间 |
| `weekly.weekday` / `weekly.time` | `fri` / `17:00` | 周报触发时间 |

## 项目结构

```
pa/
├── ai/             # Kimi K3 客户端 + 自然语言解析 + 晨报/周报润色
├── core/           # task/reminder/daily/report 业务服务
├── db/             # SQLAlchemy ORM + session 工厂
├── notify/         # Win10/11 Toast 封装
├── ui/             # pystray 托盘 + Tkinter 主窗口
└── scheduler.py    # APScheduler 作业注册
scripts/
├── probe_kimi.py              # Kimi K3 探活
├── install_autostart.py       # 开机自启安装
└── uninstall_autostart.py
```

## 设计文档

- 设计稿：`docs/specs/2026-07-21-personal-assistant-design.md`
- MVP 实施计划：`docs/superpowers/plans/2026-07-21-personal-assistant-mvp.md`