Hook 系统架构设计方案

[NLick47]

Hook 系统架构设计

扩展系统架构，支持用户自定义数据处理，遵循自由开源理念

---

核心理念

Taix 是记录工具，不是管理工具。

• 数据完全属于用户，用户决定怎么用
• 简洁、透明、不干预
• 可扩展、可定制

不应该做的事：

• 不教用户"怎么管理时间"
• 不评价用户"效率高低"
• 不制造焦虑或成就感

Hook 系统的设计原则：

• 只提供原始数据和聚合能力
• 一切结论由用户自己下
• 脚本只是"数据处理器"，不是"决策器"
• 示例脚本默认不启用，用户自主选择
• 不打扰、不评价、不干预

---

技术栈

层级	技术	职责
核心调度	Rust	周期触发、Python 执行、HTTP 服务
配置界面	Web	触发器管理、脚本配置、日志查看
客户端	C#/Avalonia	状态显示、入口集成
扩展脚本	Python	用户可编写的数据处理脚本（示例）

---

事件体系

周期事件

事件	说明
on_period_ready	用户指定的周期触发（每日/每周/每月/自定义 cron）
on_user_request	用户手动触发

数据事件

事件	说明
on_export_complete	数据导出完成时

---

触发器配置

{
  "triggers": [
    {
      "id": "my-daily-export",
      "name": "每日数据导出",
      "enabled": true,
      "schedule": {
        "type": "daily",
        "time": "22:00"
      },
      "script": "hooks/my_scripts/export.py",
      "config": {
        "target_directory": "/mnt/nas/taix_backup"
      }
    }
  ]
}

---

脚本交互

输入 (stdin)：

{
  "event": "on_period_ready",
  "period_type": "daily",
  "timestamp": "2024-06-09T22:00:00Z",
  "data": {
    "date": "2024-06-09",
    "records": [ /* 原始记录 */ ],
    "summary": {
      "total_active_seconds": 28800,
      "app_breakdown": [ /* 应用聚合 */ ],
      "category_breakdown": { /* 分类聚合 */ }
    }
  },
  "config": {
    "target_directory": "/mnt/nas/taix_backup"
  }
}

输出 (stdout)：

{
  "actions": [
    {"type": "log", "message": "数据已导出到 /mnt/nas/taix_backup"}
  ]
}

支持的 Actions

Action	说明
log	写入执行日志
notify	发送系统通知（可选，默认静默）
suggest_category	建议应用分类（需用户确认）

---

架构图

┌─────────────────────────────────────────────────────────────┐
│                        用户层                               │
│  ┌─────────────┐              ┌─────────────────────────┐  │
│  │   客户端    │              │    Web 配置界面         │  │
│  │  (Avalonia) │              │   (浏览器打开)          │  │
│  │  - 状态显示 │              │   - 触发器管理          │  │
│  │  - 快捷入口 │              │   - 脚本配置            │  │
│  └──────┬──────┘              └───────────┬─────────────┘  │
└─────────┼─────────────────────────────────┼────────────────┘
          │                                 │
          ▼                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                      Rust 核心层                            │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────┐  │
│  │   调度器    │   │  执行器     │   │   HTTP 服务     │  │
│  │  - 周期触发 │   │ - Python    │   │  - 配置 API     │  │
│  │  - 事件分发 │   │ - 超时控制  │   │  - 静态页面托管 │  │
│  └──────┬──────┘   └──────┬──────┘   └────────┬────────┘  │
└─────────┼─────────────────┼───────────────────┼───────────┘
          │                 │                   │
          ▼                 ▼                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      扩展层                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    Python 脚本                       │   │
│  │  示例脚本（默认不启用） | 用户自定义脚本             │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

示例脚本目录

Taix/
├── data/                    # 用户数据
├── hooks/                   # 用户脚本目录（初始为空）
│   ├── examples/            # 示例脚本（只读参考）
│   │   ├── ai_aggregator.py    # AI 数据聚合
│   │   ├── device_sync.py      # 设备间数据同步
│   │   ├── data_export.py      # 数据导出
│   │   └── webhook_notify.py   # Webhook 通知
│   └── (用户放自己的脚本)
└── config/
    └── hooks.json           # 触发器配置

---

内置示例脚本

脚本	触发事件	功能
ai_aggregator.py	on_period_ready	聚合数据为结构化 JSON，供用户自行接入 AI 分析
device_sync.py	on_period_ready	导出数据到用户指定的同步目录（Syncthing、NAS 等）
data_export.py	on_period_ready / on_export_complete	导出数据到指定格式或位置
webhook_notify.py	on_period_ready	推送数据到用户自建的 Webhook 端点

---

客户端集成

设置页入口

在设置页添加"扩展"Tab，显示：

• Python 环境状态
• 活跃触发器数量
• 示例脚本列表（只读，可一键复制到用户目录）
• 用户脚本管理（启用/禁用/配置）
• "打开扩展配置"按钮（跳转 Web 界面）

---

[NLick47]

hook 方案或许可以解决 #10 扩展比python更轻量级hook方案进行多设备数据同步，同步服务在rust 服务端维护成本或许太大了