# 🤖 Butler - 智能个人助理系统

> 一个企业级质量的模块化个人助理系统，专注于数据驱动的健康追踪、生物黑客实验和桌面自动化

[![Python](https://img.shields.io/badge/Python-3.12-blue.svg)](https://www.python.org/)
[![Code Quality](https://img.shields.io/badge/Code%20Quality-Enterprise-green.svg)](docs/REVIEW_AND_ROADMAP.md)
[![Architecture](https://img.shields.io/badge/Architecture-⭐⭐⭐⭐⭐-yellow.svg)](docs/ARCHITECTURE.md)
[![License](https://img.shields.io/badge/License-Private-red.svg)](LICENSE)

---

## 📋 目录

- [项目概览](#-项目概览)
- [核心特性](#-核心特性)
- [设计原则](#-设计原则)
- [架构设计](#-架构设计)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [模块详解](#-模块详解)
- [使用指南](#-使用指南)
- [开发规范](#-开发规范)
- [性能指标](#-性能指标)
- [未来规划](#-未来规划)
- [贡献指南](#-贡献指南)

---

## 🎯 项目概览

Butler 是一个为生物黑客和数据驱动决策者设计的**个人 AI 助理系统**。它将健康数据管理、智能分析和桌面自动化无缝集成，通过 Slack Bot 提供自然语言交互界面，让你可以像与私人助理对话一样管理个人数据。

### 为什么选择 Butler?

- 🏥 **全面的健康数据管理**: 自动同步 Garmin 设备数据，涵盖 14+ 种健康指标
- 🤖 **智能 AI 助理**: 基于 Gemini 2.0 的 Slack Bot，支持自然语言查询和复杂工具调用
- 📊 **高级数据分析**: Pandas 驱动的相关性分析、趋势预测和驱动因素识别
- 🔒 **隐私优先**: 所有数据本地存储，无云依赖，完全掌控你的数据
- 🛠️ **高度可扩展**: 模块化架构，轻松添加新功能和数据源
- 💻 **桌面自动化**: 持久化 Shell 会话，执行系统任务和脚本

### 项目统计

```
核心代码:      ~10,600 行 Python
模块数量:      3 个主要模块 (Health, Obsidian, Shell)
工具数量:      14 个 AI 可调用工具
健康指标:      14+ 种 (睡眠、心率、HRV、压力等)
数据存储:      104 MB (SQLite + JSON)
代码质量:      ⭐⭐⭐⭐⭐ (5/5)
总体评分:      ⭐⭐⭐⭐☆ (4.1/5)
```

---

## ✨ 核心特性

### 1. 🏥 健康数据管理

#### Garmin 自动同步
- **增量同步**: 智能检测最后同步日期，只同步新数据
- **批处理**: 历史数据回填，避免 API 限流
- **14+ 健康指标**:
  - 睡眠 (总睡眠、深睡、REM、睡眠评分)
  - 心率 (静息心率、最大/最小/平均心率、心率区间)
  - HRV (心率变异性、基线、状态)
  - 压力 (平均/最大压力、时间分布)
  - Body Battery (充电/消耗、最高/最低值)
  - 步数、距离、卡路里、楼层
  - 血氧饱和度 (SpO2)
  - 呼吸率、水合作用
  - 运动活动 (类型、时长、距离、心率、配速)

#### 手动记录系统
- **饮食日志**: 餐食类型、时间、描述、卡路里
- **补剂追踪**: 名称、剂量、时间
- **酒精记录**: 类型、数量、时间
- **感受日志**: 症状类型、严重程度、描述
- **禁食模式**: OMAD、PSMF 等饮食方案追踪

#### 高级分析引擎
```python
# 相关性分析: 酒精对睡眠的影响
analyze_driver(
    driver_metric="alcohol_units",
    target_metric="sleep_score",
    method="correlation"
)

# 趋势分析: HRV 和静息心率趋势
get_health_insights(
    analysis_type="fitness_trends",
    lookback_days=90
)

# 生活方式影响: 禁食对 Body Battery 的影响
get_health_insights(
    analysis_type="lifestyle_impact",
    lookback_days=60
)
```

---

### 2. 🤖 Slack AI Bot

#### 双 Bot 架构
- **Health Bot**: 专注健康数据查询、记录和分析
- **Shell Bot**: 系统管理和命令执行

#### 14 个 AI 工具

| 类别 | 工具名称 | 功能 |
|------|---------|------|
| **读取** | `get_daily_detailed_stats` | 获取某日完整健康摘要 |
|  | `get_metric_history` | 查询指标历史趋势 |
|  | `get_activity_history` | 获取运动记录 |
|  | `get_manual_history` | 查询手动日志 |
| **写入** | `log_diet` | 记录饮食 |
|  | `log_alcohol` | 记录酒精 |
|  | `log_supplement` | 记录补剂 |
|  | `log_feeling` | 记录身体感受 |
|  | `log_fasting` | 记录禁食模式 |
| **同步** | `sync_garmin` | 同步 Garmin 数据 |
|  | `sync_obsidian` | 同步 Obsidian 笔记 |
| **分析** | `get_health_insights` | 高级健康洞察 |
|  | `analyze_driver` | 驱动因素分析 |
| **系统** | `search_web` | 网络搜索 |
|  | `execute_shell` | 执行 Shell 命令 |

#### 智能对话示例

```
你: 昨天我睡得怎么样?
Bot: [调用 get_daily_detailed_stats(2024-01-22)]
     昨天你的睡眠质量不错:
     - 总睡眠: 7小时32分
     - 睡眠评分: 82/100
     - 深睡: 1小时45分
     - REM: 1小时58分
     - 早上静息心率: 52 bpm

你: 过去一周酒精对我睡眠有什么影响?
Bot: [调用 analyze_driver(alcohol, sleep_score)]
     分析过去 7 天的数据:
     - 相关系数: -0.68 (中度负相关)
     - 喝酒后睡眠评分平均下降 12 分
     - 建议: 睡前 4 小时避免饮酒

你: 帮我记录今天午餐吃了鸡胸肉沙拉
Bot: [调用 log_diet(description="鸡胸肉沙拉", meal_type="lunch")]
     ✅ 已记录今天的午餐
```

#### 防幻觉机制
- **数据验证**: 图片下载失败时禁用工具，明确告知用户
- **结果截断**: 防止超长响应导致 API 错误
- **上下文管理**: 滑动窗口保留 40 条消息历史
- **错误优雅降级**: 工具执行失败时返回友好错误信息

---

### 3. 📝 Obsidian 集成

#### Vault 索引
- 扫描 Markdown 文件，索引 `#writing_sample` 和 `#reply_sample` 标签
- 提供随机采样功能，用于 LLM 风格学习

#### 内容生成
- 每日笔记生成器
- 健康数据整合到 Obsidian 格式

---

### 4. 💻 Shell 自动化

#### 持久化 Shell 会话
- **PTY 模拟**: 真实 zsh 终端环境
- **会话管理**: 每个 Slack Channel 独立会话
- **超时重启**: 自动恢复长时间未使用的会话
- **自定义 Prompt**: 便于解析命令输出

#### 安全特性
- **命令黑名单**: 拒绝危险命令 (`rm -rf /`, `sudo` 等)
- **超时控制**: 默认 2 秒超时，防止阻塞
- **输出截断**: 防止超长输出

---

## 🎨 设计原则

### 1. 隐私优先 (Privacy First)
- **本地存储**: 所有数据存储在本地，无云依赖
- **数据主权**: 用户完全掌控数据的读写和删除
- **JSON 格式**: 人类可读，易于备份和迁移
- **环境变量**: 敏感信息仅存储在 `.env` 文件

### 2. 类型安全 (Type Safety)
```python
# ✅ 强制类型提示
def sync_daily_metric(
    self,
    metric_type: str,
    target_date: date,
    force: bool = False
) -> bool:
    """Sync a single daily metric."""
    ...

# ✅ Pydantic 数据验证
class SleepData(BaseModel):
    date: date
    total_sleep_seconds: Optional[int]
    sleep_score: Optional[int]  # 0-100
    sleep_start_time: Optional[time]
```

### 3. 模块化与可扩展 (Modular & Extensible)
- **插件化架构**: 每个模块可独立运行
- **工具注册表**: 添加新工具只需注册到 `TOOLS_SCHEMA`
- **依赖注入**: 构造函数支持依赖注入，便于测试

### 4. 防御性编程 (Defensive Programming)
- **错误处理**: 分层错误捕获，自定义异常类
- **重试机制**: Garmin API 调用支持指数退避重试
- **数据验证**: 所有输入使用 Pydantic 验证
- **日志完善**: 结构化日志，便于追踪问题

### 5. 性能优化 (Performance)
- **混合存储**: SQLite 索引 + JSON 文件，兼顾查询性能和灵活性
- **WAL 模式**: SQLite Write-Ahead Logging，提升并发性能
- **批量操作**: 数据库批量插入，减少 I/O
- **LRU 缓存**: API 调用结果缓存

---

## 🏗️ 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                         用户交互层                             │
│  Slack Bot  │  CLI  │  Web Dashboard (未来)                   │
└─────────────┬───────────────────────────────────────────────┘
              │
┌─────────────▼───────────────────────────────────────────────┐
│                        应用编排层                              │
│  MessageDispatcher │ ToolRegistry │ ContextStorage           │
└─────────────┬───────────────────────────────────────────────┘
              │
┌─────────────▼───────────────────────────────────────────────┐
│                        业务逻辑层                              │
│  HealthDataSync │ HealthDataQuery │ AnalyticsEngine          │
│  ManualLogStorage │ ObsidianIndexer │ ShellSessionManager    │
└─────────────┬───────────────────────────────────────────────┘
              │
┌─────────────▼───────────────────────────────────────────────┐
│                        数据访问层                              │
│  HealthRepository │ HealthStorage │ GarminHealthClient       │
└─────────────┬───────────────────────────────────────────────┘
              │
┌─────────────▼───────────────────────────────────────────────┐
│                         数据存储层                             │
│  SQLite (索引) │ JSON Files (数据) │ Garmin API               │
└─────────────────────────────────────────────────────────────┘
```

### 三层架构详解

#### 1. 数据获取层
- **GarminHealthClient**: Garmin Connect API 封装
- **职责**: 处理认证、API 调用、数据转换

#### 2. 业务逻辑层
- **HealthDataSync**: 同步编排，增量逻辑，批处理
- **HealthDataQuery**: 数据查询，聚合计算
- **AnalyticsEngine**: Pandas 驱动的分析引擎
- **职责**: 核心业务逻辑，无外部依赖

#### 3. 数据访问层
- **HealthRepository**: SQLite CRUD 操作
- **HealthStorage**: JSON 文件读写
- **职责**: 数据持久化，屏蔽存储细节

### 数据流图

```
┌──────────┐    ┌──────────────┐    ┌──────────────┐
│ Garmin   │───▶│ GarminClient │───▶│ DataSync     │
│ API      │    │              │    │ Service      │
└──────────┘    └──────────────┘    └──────┬───────┘
                                            │
                ┌───────────────────────────┴──────────┐
                │                                       │
                ▼                                       ▼
      ┌─────────────────┐                   ┌──────────────────┐
      │ HealthStorage   │                   │ HealthRepository │
      │ (JSON)          │                   │ (SQLite)         │
      └─────────────────┘                   └──────────────────┘
                │                                       │
                └───────────────┬───────────────────────┘
                                │
                                ▼
                      ┌──────────────────┐
                      │ HealthDataQuery  │
                      │ (读取 + 聚合)     │
                      └────────┬─────────┘
                               │
                               ▼
                     ┌───────────────────┐
                     │ Slack Bot Tools   │
                     │ (AI 调用)         │
                     └───────────────────┘
```

### 设计模式

| 模式 | 应用 | 好处 |
|------|------|------|
| **Repository** | `HealthRepository` | 封装数据访问，便于替换数据库 |
| **Service Layer** | `HealthDataSync` | 业务逻辑与数据访问分离 |
| **Registry** | `TOOLS_SCHEMA + TOOL_FUNCTIONS` | 动态工具注册，易于扩展 |
| **Strategy** | `LLM` 抽象基类 | 支持多个 LLM 提供商 |
| **Factory** | `create_llm_client()` | 统一创建逻辑 |
| **Sliding Window** | `ContextStorage` | 上下文压缩，防止超长 |

---

## 🔧 技术栈

### 核心技术

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **语言** | Python | 3.12 | 主要开发语言 |
| **数据验证** | Pydantic | 2.8.2+ | 类型安全和数据验证 |
| **数据库** | SQLite | 3.x | 元数据索引 |
| **数据分析** | Pandas | Latest | 数据聚合和分析 |
| **LLM** | Gemini | 2.0 Flash Exp | AI 对话和工具调用 |
| **Slack** | Slack Bolt | 1.18.0+ | Slack Bot 框架 |
| **CLI** | Click | 8.1.0+ | 命令行界面 |
| **HTTP** | Requests | Latest | API 调用 |
| **图片** | Pillow | Latest | 图片处理 |
| **搜索** | DuckDuckGo | Latest | 网络搜索 |

### 依赖管理

```bash
# 核心依赖
garminconnect>=0.2.38      # Garmin API
pydantic>=2.8.2            # 数据验证
slack_bolt>=1.18.0         # Slack Bot
google-generativeai>=0.3.2 # Gemini
pandas                     # 数据分析

# 开发依赖
pytest>=7.0.0              # 测试框架
pytest-cov>=4.0.0          # 测试覆盖率
pytest-mock>=3.10.0        # Mock 工具
```

---

## 🚀 快速开始

### 环境要求

- **Python**: 3.12+
- **操作系统**: macOS / Linux (推荐)
- **Garmin 账号**: Garmin Connect China
- **Slack 工作区**: 需要管理员权限

### 1. 克隆项目

```bash
git clone <repository-url>
cd butler
```

### 2. 创建虚拟环境

```bash
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

复制 `.env.example` 并编辑:

```bash
cp .env.example .env
```

编辑 `.env` 文件:

```bash
# Garmin Connect China
GARMIN_EMAIL=your_email@example.com
GARMIN_PASSWORD=your_password

# Slack Bot (Health Bot)
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token

# Slack Bot (Shell Bot)
SHELL_SLACK_BOT_TOKEN=xoxb-your-shell-bot-token
SHELL_SLACK_APP_TOKEN=xapp-your-shell-app-token

# Gemini API
GEMINI_API_KEY=your-api-key
GEMINI_BASE_URL=http://127.0.0.1:8045  # 可选: 使用代理
GEMINI_MODEL=gemini-2.0-flash-exp

# Obsidian (可选)
OBSIDIAN_VAULT_PATH=/path/to/your/vault

# 数据路径 (可选)
DATA_DIR=./data/health
DB_PATH=./data/health/health.db
```

### 5. 初始化数据库

```bash
python -m health.db.schema
```

### 6. 验证系统

```bash
python scripts/verify_system.py
```

### 7. 首次数据同步

```bash
# 同步最近 7 天的数据
python -m health.cli.sync sync --days 7
```

### 8. 启动 Slack Bot

```bash
# 启动 Health Bot
python scripts/bot_manager.py start health

# 启动 Shell Bot
python scripts/bot_manager.py start shell

# 查看状态
python scripts/bot_manager.py status
```

---

## 📚 模块详解

### Health 模块

#### 目录结构

```
health/
├── config.py              # 配置管理
├── models/                # Pydantic 数据模型
│   ├── daily_metrics.py   # 每日指标模型
│   ├── activity.py        # 运动活动模型
│   ├── body_metrics.py    # 身体指标模型
│   └── manual_log.py      # 手动记录模型
├── db/                    # 数据库层
│   ├── schema.py          # 数据库 Schema
│   └── repository.py      # 数据访问对象
├── services/              # 业务逻辑层
│   ├── garmin_client.py   # Garmin API 客户端
│   ├── data_sync.py       # 同步服务
│   ├── storage.py         # JSON 存储
│   ├── query.py           # 查询服务
│   └── manual_log_storage.py  # 手动记录存储
├── analytics/             # 分析引擎
│   └── engine.py          # Pandas 分析
├── cli/                   # 命令行界面
│   ├── sync.py            # 同步命令
│   ├── query.py           # 查询命令
│   └── manual.py          # 手动记录命令
└── utils/                 # 工具函数
    ├── logging_config.py  # 日志配置
    ├── date_utils.py      # 日期工具
    └── exceptions.py      # 自定义异常
```

#### CLI 命令

```bash
# 查看同步状态
python -m health.cli.sync status

# 同步最近 N 天
python -m health.cli.sync sync --days 7

# 增量同步 (自动检测最后同步日期)
python -m health.cli.sync sync-incremental

# 历史数据回填
python -m health.cli.sync backfill --start-date 2024-01-01 --end-date 2024-01-31

# 手动记录饮食
python -m health.cli.manual diet --time 12:30 --desc "午餐" --meal-type lunch

# 手动记录补剂
python -m health.cli.manual supplement --name "Vitamin D" --dosage "2000 IU"

# 查询数据
python -m health.cli.query metrics --type sleep --start 2024-01-01 --end 2024-01-31
```

#### 数据存储

**SQLite 数据库** (`data/health/health.db`)

| 表名 | 用途 |
|------|------|
| `sync_records` | 同步历史记录 |
| `last_sync_state` | 最后同步状态 (用于增量同步) |
| `daily_metrics_index` | 每日指标文件索引 |
| `activity_index` | 运动活动索引 |

**JSON 文件结构**

```
data/health/
├── daily_metrics/
│   ├── sleep/
│   │   └── 2024/
│   │       └── 01/
│   │           └── 2024-01-15.json
│   ├── steps/
│   ├── heart_rate/
│   ├── hrv/
│   └── ...
├── activities/
│   └── 2024/
│       └── 01/
│           └── activity_12345678.json
└── manual_logs/
    └── 2024-01.json
```

---

### Slack Bot 模块

#### 目录结构

```
slack_bot/
├── main.py                # Health Bot 入口
├── shell_main.py          # Shell Bot 入口
├── dispatcher.py          # 消息分发器
├── llm/                   # LLM 接口层
│   ├── base.py            # 抽象基类
│   └── gemini.py          # Gemini 实现
├── tools/                 # 工具函数
│   ├── registry.py        # 工具注册表
│   ├── health_read.py     # 健康数据读取
│   ├── health_write.py    # 健康数据写入
│   ├── analytics.py       # 分析工具
│   ├── garmin.py          # Garmin 同步
│   ├── obsidian.py        # Obsidian 工具
│   ├── shell_tool.py      # Shell 执行
│   └── web.py             # 网络搜索
├── context/               # 上下文管理
│   ├── storage.py         # 持久化存储
│   └── compressor.py      # 上下文压缩
├── shell/                 # Shell 会话管理
│   ├── session.py         # PTY 会话
│   └── manager.py         # 会话管理器
└── utils/                 # 工具函数
    └── mrkdwn.py          # Slack Markdown 格式化
```

#### 消息处理流程

```
1. Slack 消息 → MessageDispatcher.dispatch()
2. 加载对话上下文 (ContextStorage)
3. 下载图片 (如有)
4. LLM 生成响应 + 工具调用 (GeminiLLM)
5. 执行工具 (TOOL_FUNCTIONS)
6. LLM 分析工具结果
7. 格式化响应 (Markdown → Slack mrkdwn)
8. 分块发送 (最多 3 条消息)
9. 保存上下文
```

---

### Obsidian 模块

#### 功能

- **Vault 索引**: 扫描并索引 Markdown 文件
- **标签采样**: 随机采样 `#writing_sample` 和 `#reply_sample`
- **内容生成**: 每日笔记生成器
- **健康数据整合**: 将健康数据格式化为 Obsidian 格式

---

### Shell 模块

#### 持久化会话

- **PTY 模拟**: 使用 `pty` 模块模拟真实终端
- **zsh 环境**: 完整的 shell 环境
- **会话隔离**: 每个 Slack Channel 独立会话
- **超时重启**: 30 分钟未使用自动重启

#### 安全特性

```python
# 危险命令黑名单
DANGEROUS_COMMANDS = [
    "rm -rf /",
    "mkfs",
    "dd if=/dev/zero",
    ":(){ :|:& };:"  # Fork bomb
]
```

---

## 📖 使用指南

### Slack Bot 对话示例

#### 查询健康数据

```
你: 今天的数据
Bot: [调用 get_daily_detailed_stats(2024-01-23)]
     📊 2024-01-23 健康数据摘要:

     💤 睡眠:
     - 总睡眠: 7小时18分
     - 睡眠评分: 79/100
     - 深睡: 1小时32分

     ❤️ 心率:
     - 静息心率: 53 bpm
     - 最低心率: 48 bpm

     ⚡ Body Battery:
     - 充电: 85
     - 消耗: 42

     🏃 运动:
     - 步数: 8,234 步
     - 距离: 6.2 km
```

#### 记录数据

```
你: 帮我记录今天中午吃了牛排和蔬菜沙拉
Bot: [调用 log_diet(...)]
     ✅ 已记录 2024-01-23 的午餐:
     - 牛排和蔬菜沙拉

你: 今天早上吃了 5000 IU 的维生素 D
Bot: [调用 log_supplement(name="Vitamin D", dosage="5000 IU")]
     ✅ 已记录补剂: Vitamin D (5000 IU)
```

#### 数据分析

```
你: 过去 30 天我的 HRV 趋势如何?
Bot: [调用 get_health_insights(analysis_type="fitness_trends", lookback_days=30)]
     📈 HRV 趋势分析 (过去 30 天):

     - 平均 HRV: 62 ms
     - 趋势: 上升 +8%
     - 最高: 78 ms (2024-01-18)
     - 最低: 48 ms (2024-01-05)

     💡 建议:
     - HRV 稳步上升,恢复状态良好
     - 保持当前训练强度

你: 分析一下镁对我睡眠的影响
Bot: [调用 analyze_driver(driver_metric="has_magnesium", target_metric="sleep_score", method="group_compare")]
     🔬 驱动因素分析:

     有镁 vs 无镁:
     - 有镁组平均睡眠评分: 84.2
     - 无镁组平均睡眠评分: 76.5
     - 差异: +7.7 分 (p=0.03, 统计显著)

     💡 结论:
     - 镁对睡眠质量有正面影响
     - 建议睡前 1-2 小时服用
```

#### Shell 命令执行

```
你: 检查一下系统负载
Bot: [调用 execute_shell("uptime")]
     📟 命令执行结果:
     15:23  up 7 days,  2:14, 3 users, load averages: 1.52 2.03 1.87

你: 当前目录有哪些文件?
Bot: [调用 execute_shell("ls -lh")]
     📟 ls -lh:
     total 48
     drwxr-xr-x  12 lili  staff   384B Jan 23 15:20 health
     drwxr-xr-x   8 lili  staff   256B Jan 23 15:20 slack_bot
     -rw-r--r--   1 lili  staff   2.1K Jan 23 15:20 README.md
```

---

### CLI 使用示例

#### 健康数据同步

```bash
# 查看当前同步状态
python -m health.cli.sync status

# 输出:
# 📊 Health Data Sync Status
#
# ✅ Synced Data Types:
#   • sleep               Last sync: 2024-01-22  (180 records)
#   • steps               Last sync: 2024-01-22  (180 records)
#   • hrv                 Last sync: 2024-01-22  (175 records)
#   • activities          Last sync: 2024-01-22  (45 records)

# 同步最近 7 天
python -m health.cli.sync sync --days 7

# 增量同步 (推荐用于定时任务)
python -m health.cli.sync sync-incremental

# 历史数据回填
python -m health.cli.sync backfill \
    --start-date 2024-01-01 \
    --end-date 2024-01-31 \
    --batch-size 15
```

#### 手动记录

```bash
# 记录饮食
python -m health.cli.manual diet \
    --time 12:30 \
    --desc "鸡胸肉沙拉" \
    --meal-type lunch \
    --cals 450

# 记录补剂
python -m health.cli.manual supplement \
    --name "Magnesium Glycinate" \
    --dosage "400mg" \
    --time 22:00

# 记录酒精
python -m health.cli.manual alcohol \
    --type "红酒" \
    --amount "150ml" \
    --time 19:30

# 记录身体感受
python -m health.cli.manual feeling \
    --type "头痛" \
    --severity 3 \
    --desc "轻微偏头痛,可能是睡眠不足"
```

---

## 👨‍💻 开发规范

### 代码标准 (CLAUDE.md)

项目遵循严格的开发标准,定义在 `CLAUDE.md`:

#### 1. Python 标准

**类型提示** (强制):
```python
# ✅ 正确
def sync_data(
    self,
    metric_type: str,
    target_date: date
) -> bool:
    ...

# ❌ 错误
def sync_data(self, metric_type, target_date):
    ...
```

**Pydantic 模型** (强制):
```python
# ✅ 正确
class SleepData(BaseModel):
    date: date
    sleep_score: Optional[int]

# ❌ 错误
sleep_data = {
    "date": "2024-01-23",
    "sleep_score": 82
}
```

**Pathlib** (强制):
```python
# ✅ 正确
from pathlib import Path
data_path = Path("data/health")

# ❌ 错误
import os.path
data_path = os.path.join("data", "health")
```

**Google 风格文档字符串**:
```python
def sync_daily_metric(
    self, metric_type: str, target_date: date, force: bool = False
) -> bool:
    """Sync a single daily metric for a specific date.

    Args:
        metric_type: Type of metric to sync (e.g., 'sleep', 'steps')
        target_date: Date to sync
        force: If True, re-sync even if data already exists

    Returns:
        True if data was synced, False if skipped or no data available

    Raises:
        GarminAPIError: If API request fails
    """
    ...
```

#### 2. Human-in-the-Loop 协议

生成超过 20 行代码或修改核心逻辑后,必须:

1. **自我解释**: 简明说明修改了什么、为什么
2. **结构检查**: 是否引入新依赖?是否改变函数签名?
3. **风险评估**: 最可能出现的问题是什么?
4. **验证计划**: 提供具体的测试命令

---

### Git 工作流

```bash
# 功能分支
git checkout -b feature/add-blood-pressure-metric

# 提交规范 (Conventional Commits)
git commit -m "feat: add blood pressure metric support"
git commit -m "fix: resolve Garmin API timeout issue"
git commit -m "docs: update README with new features"
git commit -m "test: add integration tests for sync flow"

# 提交前检查
pytest --cov
```

---

### 测试规范

```bash
# 运行所有测试
pytest

# 测试覆盖率
pytest --cov=health --cov=slack_bot --cov-report=html

# 查看覆盖率报告
open htmlcov/index.html

# 只运行特定模块
pytest tests/health/

# 只运行集成测试
pytest tests/integration/
```

---

## 📊 性能指标

### 系统性能

| 指标 | 数值 | 备注 |
|------|------|------|
| **Garmin 同步速度** | ~2 秒/天 | 单个指标,无网络延迟 |
| **增量同步时间** | 10-30 秒 | 同步昨天的所有指标 |
| **SQLite 查询** | <10 ms | 索引查询 |
| **LLM 响应时间** | 1-3 秒 | Gemini 2.0 Flash |
| **工具执行** | 0.1-2 秒 | 取决于工具类型 |
| **数据库大小** | 2.2 MB | 180 天数据 |
| **JSON 数据大小** | ~100 MB | 180 天数据 |

### 可靠性

| 指标 | 数值 | 备注 |
|------|------|------|
| **同步成功率** | 99.5%+ | 基于 30 天运行 |
| **Bot 可用性** | 99%+ | 自动重启机制 |
| **数据完整性** | 100% | Pydantic 验证 |
| **API 重试成功率** | 95%+ | 3 次重试 |

---

## 🗺️ 未来规划

### 短期 (1-2 周)

#### 🔴 P0: 安全和稳定性
- [x] 修复敏感信息日志泄露
- [x] 添加环境变量验证 (Pydantic Settings)
- [x] Shell 命令黑名单
- [x] Garmin API 重试机制 (tenacity)
- [x] SQLite WAL 模式优化

#### 🟡 P1: 文档和测试
- [ ] 编写架构文档 (`docs/ARCHITECTURE.md`)
- [ ] 编写工具参考手册 (`docs/TOOLS_REFERENCE.md`)
- [ ] 测试覆盖率提升到 60%+
- [ ] 添加集成测试

详见: [`docs/TODO.md`](docs/TODO.md)

---

### 中期 (1-2 月)

#### 数据分析增强
- [ ] **睡眠质量预测模型** (scikit-learn)
  - 基于历史数据预测明天睡眠质量
  - 特征: HRV, 压力, 运动强度, 饮食, 补剂

- [ ] **多变量相关性分析**
  - 探索多个因素的组合影响
  - 例如: "禁食 + 镁 + 低压力 → 高质量睡眠"

- [ ] **可视化仪表板** (Streamlit)
  - 交互式数据探索
  - 趋势图表、热力图、相关性矩阵

#### 跨平台集成
- [ ] **Apple Health 导入**
  - 支持从 Apple Health 导出的 XML 文件
  - 合并 iPhone 和 Garmin 数据

- [ ] **数据导出**
  - CSV 导出 (便于 Excel 分析)
  - PDF 报告生成 (周报、月报)

#### LLM 能力扩展
- [ ] **图表生成工具**
  - 自动生成趋势图、对比图
  - 发送到 Slack

- [ ] **个性化健康建议引擎**
  - 基于数据分析自动生成建议
  - 例如: "你的 HRV 持续下降,建议减少训练强度"

---

### 长期 (3-6 月)

#### 架构演进

**目标**: Modular Monolith (模块化单体)

```
butler/
├── packages/              # 独立包
│   ├── health/
│   ├── obsidian/
│   ├── shell/
│   ├── llm/
│   └── analytics/
├── apps/                  # 应用层
│   ├── slack_bot/
│   ├── cli/
│   └── web/              # 新增 Web Dashboard
└── shared/               # 共享模块
    ├── config/
    ├── db/
    └── utils/
```

#### Web Dashboard
- **技术栈**: Next.js + Tailwind CSS + Chart.js
- **功能**:
  - 健康数据可视化
  - 手动记录界面
  - 分析报告查看
  - LLM 聊天界面
  - 数据导出

#### 知识图谱
- **技术**: Neo4j
- **功能**:
  - 构建健康数据知识图谱
  - 关系: 补剂 → 影响 → 睡眠质量
  - 复杂查询: "哪些因素组合对 HRV 有正面影响?"

#### 多用户支持
- 用户认证和授权
- 数据隔离
- 共享分析模板

---

## 🤝 贡献指南

### 报告问题

如果发现 Bug 或有功能建议,请创建 Issue:

```markdown
**问题描述**
简明描述问题

**复现步骤**
1. 步骤 1
2. 步骤 2
3. ...

**期望行为**
应该发生什么

**实际行为**
实际发生了什么

**环境**
- Python 版本:
- 操作系统:
```

### 开发流程

1. Fork 项目
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 遵循代码规范 (参考 `CLAUDE.md`)
4. 添加测试
5. 确保测试通过: `pytest --cov`
6. 提交代码: `git commit -m 'feat: add amazing feature'`
7. 推送分支: `git push origin feature/amazing-feature`
8. 创建 Pull Request

---

## 📄 许可证

本项目为私人项目,仅供个人使用。

---

## 🙏 致谢

### 开源项目
- [garminconnect](https://github.com/cyberjunky/python-garminconnect) - Garmin Connect API Python 库
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证和设置管理
- [Slack Bolt](https://slack.dev/bolt-python/) - Slack Bot 框架
- [Google Gemini](https://ai.google.dev/) - 强大的 LLM

### 灵感来源
- [Quantified Self](https://quantifiedself.com/) - 自我量化运动
- [Biohacking](https://www.reddit.com/r/Biohacking/) - 生物黑客社区

---

## 👤 作者

**Lili**
- 职业: Tech Executive / Programmer
- 兴趣: Bio-hacking, 数据驱动决策
- 目标: 通过数据优化健康和生活质量

---

## 📞 联系方式

如有问题或建议,欢迎通过以下方式联系:

- **GitHub Issues**: [创建 Issue](../../issues)
- **Email**: [你的邮箱]

---

## 📚 相关文档

- 📖 [完整审查报告](docs/REVIEW_AND_ROADMAP.md)
- 📋 [待办事项清单](docs/TODO.md)
- 🚀 [快速开始指南](docs/QUICK_START_AFTER_RETURN.md)
- 🏗️ [架构文档](docs/ARCHITECTURE.md) *(待补充)*
- 🛠️ [工具参考手册](docs/TOOLS_REFERENCE.md) *(待补充)*
- 📊 [数据流图](docs/DATA_FLOW.md) *(待补充)*

---

<div align="center">

**Built with ❤️ for data-driven self-optimization**

⭐ 如果这个项目对你有帮助,请给个 Star!

</div>