210 lines
5.5 KiB
Markdown
210 lines
5.5 KiB
Markdown
# 🏥 健康守护助手 · Health Guardian v0.4
|
||
|
||
跨平台健康提醒工具，支持 Windows / macOS / Linux。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
health-guardian/
|
||
├── Cargo.toml # Workspace 根
|
||
├── config.toml # 用户配置文件
|
||
│
|
||
├── health-core/ # 纯逻辑引擎（lib）
|
||
│ └── src/
|
||
│ ├── lib.rs
|
||
│ ├── config/ # 配置加载 & 结构体
|
||
│ ├── task/ # Task / Interval / TaskStats
|
||
│ ├── state/ # 线程安全运行状态 AppState
|
||
│ ├── notifier/ # 系统通知 / 声音 / 日志
|
||
│ └── scheduler/ # 异步调度引擎
|
||
│
|
||
├── health-cli/ # 命令行入口 → hguard
|
||
│ └── src/
|
||
│ ├── main.rs # CLI 子命令 & 主流程
|
||
│ └── display.rs # 终端美化渲染（与逻辑解耦）
|
||
│
|
||
├── health-daemon/ # 后台守护进程 → hguard-daemon
|
||
│ └── src/main.rs # Unix double-fork / Windows Service
|
||
│
|
||
└── health-tray/ # 系统托盘 UI → hguard-tray
|
||
└── src/main.rs # tray-item 跨平台托盘
|
||
```
|
||
|
||
---
|
||
|
||
## 编译
|
||
|
||
### 依赖安装
|
||
|
||
```bash
|
||
# 安装 Rust（所有平台）
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
# Linux 额外依赖
|
||
sudo apt install -y libdbus-1-dev pkg-config libasound2-dev
|
||
# AppIndicator 托盘支持（Linux）
|
||
sudo apt install -y libayatana-appindicator3-dev
|
||
```
|
||
|
||
### 编译所有 crate
|
||
|
||
```bash
|
||
cd health-guardian
|
||
cargo build --release
|
||
```
|
||
|
||
### 仅编译特定组件
|
||
|
||
```bash
|
||
cargo build --release -p health-cli # hguard
|
||
cargo build --release -p health-daemon # hguard-daemon
|
||
cargo build --release -p health-tray # hguard-tray
|
||
```
|
||
|
||
### 产物位置
|
||
|
||
```
|
||
target/release/hguard
|
||
target/release/hguard-daemon
|
||
target/release/hguard-tray
|
||
```
|
||
|
||
---
|
||
|
||
## 使用
|
||
|
||
### CLI（hguard）
|
||
|
||
```bash
|
||
# 正常启动（自动搜索 config.toml）
|
||
hguard
|
||
|
||
# 指定配置文件
|
||
hguard --config /path/to/config.toml
|
||
|
||
# 子命令
|
||
hguard list # 列出所有任务
|
||
hguard test # 立即触发所有通知（测试）
|
||
hguard log-path # 显示日志文件路径
|
||
hguard status # 显示任务状态快照
|
||
hguard --default run # 使用内置默认配置启动
|
||
hguard --verbose run # 开启详细日志
|
||
```
|
||
|
||
### 后台守护（hguard-daemon）
|
||
|
||
```bash
|
||
# 前台运行（调试）
|
||
hguard-daemon
|
||
|
||
# Unix 后台运行（double-fork）
|
||
hguard-daemon --daemonize
|
||
|
||
# 停止守护进程
|
||
kill $(cat ~/.local/share/health-guardian/hguard.pid)
|
||
```
|
||
|
||
#### systemd 用户服务（Linux）
|
||
|
||
```bash
|
||
mkdir -p ~/.config/systemd/user/
|
||
cat > ~/.config/systemd/user/hguard.service << 'EOF'
|
||
[Unit]
|
||
Description=Health Guardian Daemon
|
||
|
||
[Service]
|
||
ExecStart=/usr/local/bin/hguard-daemon
|
||
Restart=on-failure
|
||
|
||
[Install]
|
||
WantedBy=default.target
|
||
EOF
|
||
|
||
systemctl --user enable --now hguard
|
||
journalctl --user -u hguard -f
|
||
```
|
||
|
||
#### launchd（macOS）
|
||
|
||
```bash
|
||
cat > ~/Library/LaunchAgents/com.hguard.daemon.plist << 'EOF'
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||
<plist version="1.0">
|
||
<dict>
|
||
<key>Label</key> <string>com.hguard.daemon</string>
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>/usr/local/bin/hguard-daemon</string>
|
||
</array>
|
||
<key>RunAtLoad</key> <true/>
|
||
<key>KeepAlive</key> <true/>
|
||
</dict>
|
||
</plist>
|
||
EOF
|
||
|
||
launchctl load ~/Library/LaunchAgents/com.hguard.daemon.plist
|
||
```
|
||
|
||
#### Windows 服务
|
||
|
||
```powershell
|
||
# 以管理员身份运行
|
||
sc.exe create hguard binPath="C:\path\to\hguard-daemon.exe" start=auto
|
||
sc.exe start hguard
|
||
```
|
||
|
||
### 托盘 UI（hguard-tray）
|
||
|
||
```bash
|
||
hguard-tray # 启动后出现托盘图标，右键显示菜单
|
||
```
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
配置文件搜索顺序：
|
||
1. `--config <path>` 命令行指定
|
||
2. `./config.toml`（当前目录）
|
||
3. `~/.config/health-guardian/config.toml`
|
||
|
||
```toml
|
||
[settings]
|
||
log_dir = "" # 空 = 系统默认；可指定绝对路径
|
||
sound_file = "" # 空 = 内置蜂鸣；可指定 .wav/.mp3 路径
|
||
|
||
[[tasks]]
|
||
name = "补水提醒"
|
||
title = "💧 喝水时间到！"
|
||
body = "请喝一杯温水（约 200ml）。"
|
||
initial_delay_minutes = 30 # 启动后首次触发延迟（分钟）
|
||
sound = true # 是否播放声音
|
||
|
||
[tasks.interval]
|
||
unit = "minutes" # "hours" 或 "minutes"
|
||
value = 30
|
||
```
|
||
|
||
---
|
||
|
||
## 日志格式
|
||
|
||
```
|
||
════════════════════════════════════════════════════════════════════════
|
||
🚀 会话开始 2026-02-18 09:00:00
|
||
════════════════════════════════════════════════════════════════════════
|
||
[2026-02-18 09:20:00] # 1 眼部放松 👁️ 远眺放松眼睛！
|
||
[2026-02-18 09:30:00] # 1 补水提醒 💧 喝水时间到！
|
||
[2026-02-18 09:40:00] # 2 眼部放松 👁️ 远眺放松眼睛！
|
||
```
|
||
|
||
## 声音说明
|
||
|
||
| 场景 | 行为 |
|
||
|------|------|
|
||
| `sound_file = ""` | 内置合成蜂鸣：三声 × 0.5s，间隔 0.15s，频率 660 Hz |
|
||
| `sound_file = "/path/to/x.wav"` | 播放指定文件，失败自动降级为蜂鸣 |
|
||
| 任务 `sound = false` | 完全静音 |
|