Tailnet Resource Widget Showcase

v1 Capability（第一版能力）

Collector Pull（收集器拉取）mac mini 每 5 分鐘透過 Tailscale IP/MagicDNS（魔法 DNS）拉取 `/metrics`。

Android Widget（Android 小工具）WorkManager（背景工作管理器）嘗試 15 分鐘級自動更新，refresh button（刷新按鈕）立即抓 snapshot（快照）。

SQLite Housekeeping（資料清理）raw samples（原始樣本）保留 7 天，每次 poll cleanup（清理），每日 `VACUUM`。

Architecture Flow（架構流程）

1Windows/macOS agent（代理）只讀 CPU/RAM/Disk。

2mac mini collector（收集器）透過 tailnet（私有網路）輪詢。

3SQLite 保存 latest snapshot（最新快照）與 7 天 history（歷史）。

4Android app/Widget（應用/小工具）讀 `/api/v1/snapshot`。

Interfaces（介面）

Component	Endpoint	Purpose
Agent（代理）	`GET /health`	設備 agent health check（健康檢查）。
Agent（代理）	`GET /metrics`	CPU/RAM/Disk/Network optional（網路可選）摘要。
Collector（收集器）	`GET /api/v1/snapshot`	Widget（小工具）摘要資料。
Collector（收集器）	`GET /api/v1/devices/{id}/history?range=24h`	App（應用程式）詳細歷史資料。

Usage（使用方式）

Collector quick start（收集器快速啟動）

Copy-Item config\devices.example.json config\devices.json
Copy-Item .env.example .env
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
$env:MONITOR_TOKEN="change-this-shared-token"
$env:COLLECTOR_DEVICES_FILE=".\config\devices.json"
$env:COLLECTOR_AUTO_POLL="true"
uvicorn app.main:app --host 0.0.0.0 --port 8787

Agent handoff（代理交接）

把 prompts/windows-agent-handoff.md 或 prompts/macos-agent-handoff.md 貼給各設備上的 Codex。

Safety Boundary（安全邊界）

Allowed（允許）：CPU、RAM、Disk、Network optional（網路可選）、online/offline（在線/離線）、last updated（最後更新）。

Blocked（禁止）：Funnel（公開入口）、Tailscale Admin API key（管理 API 金鑰）放 Android、讀取使用者檔案、提交 SQLite runtime DB（執行資料庫）。

Verification（驗證）

.\scripts\verify.ps1

此 showcase（展示頁）是 static project showcase（靜態專案展示），不讀取任何真實設備資料。