@agentunion/kite 1.4.0 → 1.6.0

package/docs/Evol/346/250/241/345/235/227/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,1154 @@
+# Evol 模块设计方案
+
+> 版本: v1.0
+> 日期: 2026-03-07
+> 作者: Kite Team
+
+---
+
+## 1. 概述
+
+Evol 模块是 Kite 框架的独立服务模块，用于集成 Evol AI 平台的账户管理功能。用户通过手机号短信验证完成配对后，可以查看 Evol 账户信息、积分、团队、网关等数据。
+
+### 1.1 核心特性
+
+- **双 Token 机制**：Kite Token 控制设备访问权限，Evol Token 用于 API 调用
+- **跨实例共享**：数据存储在用户级路径，多个 Kite 实例共享同一份数据
+- **安全配对**：短信验证码由后端接收，前端输入验证，确保配对安全性
+- **设备管理**：支持多设备配对，可查看和吊销已配对设备
+
+---
+
+## 2. 为什么必须后端调用 Evol API
+
+**关键原因：配对验证的安全性**
+
+```
+【后端调用方案】（当前方案）
+后端调用 Evol API 发送验证码 → 用户手机收到验证码
+→ 前端输入验证码 → 后端验证
+✅ 验证码由后端掌握，前端必须正确输入才能通过验证
+✅ 类似 Kite 配对码机制，确保只有持有手机的用户才能配对
+
+【前端调用方案】（不可行）
+前端调用 Evol API 发送验证码 → 用户手机收到验证码
+→ 前端输入验证码 → 前端验证 → 告诉后端"我验证通过了"
+❌ 后端无法验证前端是否真的收到验证码
+❌ 前端可以伪造验证通过的请求
+❌ 失去配对验证的作用
+```
+
+**结论**：必须由后端调用 Evol API，确保验证码的真实性和配对的安全性。
+
+---
+
+## 3. 架构设计
+
+### 3.1 模块结构
+
+```
+extensions/services/evol/
+├── entry.py                    # 模块入口（WebSocket 服务器）
+├── rpc_handler.py              # RPC 方法处理
+├── evol_api.py                 # Evol API 调用封装
+├── auth_manager.py             # 认证管理（Token 缓存、验证、吊销）
+├── stats_manager.py            # 积分统计管理（定时采集、数据分析）
+├── static/                     # 前端静态文件
+│   ├── index.html              # 主页面
+│   ├── css/
+│   │   └── style.css
+│   └── js/
+│       ├── main.js             # 主逻辑
+│       ├── auth.js             # 登录逻辑
+│       ├── user-center.js      # 用户中心
+│       └── stats.js            # 积分统计图表
+└── README.md
+```
+
+### 3.2 数据目录结构
+
+```
+$KITE_DATA/evol/
+├── auth/
+│   ├── evol_token.json          # Evol API Token + 账户信息缓存
+│   └── kite_tokens.json         # 已配对设备的 Kite Token 列表
+├── cache/
+│   └── user_info.json           # 用户信息缓存（可选）
+├── stats/
+│   ├── credits_history.jsonl    # 积分历史记录（每5分钟一条）
+│   └── credits_summary.json     # 积分统计汇总（按天/周/月）
+└── log/
+    └── auth.log                 # 认证相关日志
+```
+
+#### 3.2.1 `auth/evol_token.json`
+
+```json
+{
+  "phone": "18616612455",
+  "token": "eyJhbGciOiJIUzUxMiJ9...",
+  "obtainedAt": 1709800000,
+  "expiresAt": 1710404800,
+  "userInfo": {
+    "userId": 102,
+    "aid": "evol_1760591501_0.aid.pub",
+    "userName": "18616612455",
+    "nickName": "夙夜无偕",
+    "phone": "18616612455",
+    "avatar": "",
+    "isProfileComplete": true
+  },
+  "accountInfo": {
+    "accountId": 4,
+    "vipType": 4,
+    "vipTypeName": "Unknown",
+    "vipExpireTime": "2026-10-21T16:26:42.000+08:00",
+    "vipRemainingDays": 227,
+    "credits": 4096,
+    "creditsLimit": 40000,
+    "creditsRecoveryRate": 1000
+  },
+  "teamInfo": {
+    "currentTeamId": 1,
+    "currentTeamName": "EVOL",
+    "teams": [...]
+  },
+  "gatewayInfo": {
+    "gatewayId": 2,
+    "gatewayName": "新企业版网关",
+    "apiKey": "mg-56f5bb5e-5666-418d-bda8-5d1092598d88",
+    "modelBaseUrl": "https://mg-new.evolai.cn"
+  }
+}
+```
+
+#### 3.2.2 `auth/kite_tokens.json`
+
+```json
+{
+  "tokens": [
+    {
+      "token": "kite_abc123def456...",
+      "deviceId": "device-uuid-1",
+      "deviceName": "Desktop-PC",
+      "createdAt": 1709800000,
+      "lastUsedAt": 1709900000,
+      "expiresAt": 1712492000,
+      "isValid": true
+    },
+    {
+      "token": "kite_xyz789uvw012...",
+      "deviceId": "device-uuid-2",
+      "deviceName": "Laptop",
+      "createdAt": 1709810000,
+      "lastUsedAt": 1709920000,
+      "expiresAt": 1712502000,
+      "isValid": false
+    }
+  ]
+}
+```
+
+#### 3.2.3 `stats/credits_history.jsonl`
+
+每5分钟自动记录一条积分快照，用于统计分析：
+
+```jsonl
+{"timestamp":1709800000,"credits":4096,"creditsLimit":40000,"vipType":4,"chatbotCredits":0,"codexCredits":0,"claudeCodeCredits":0,"geminiCredits":0,"openclawCredits":0,"generalCredits":0}
+{"timestamp":1709800300,"credits":4050,"creditsLimit":40000,"vipType":4,"chatbotCredits":0,"codexCredits":0,"claudeCodeCredits":0,"geminiCredits":0,"openclawCredits":0,"generalCredits":0}
+{"timestamp":1709800600,"credits":4000,"creditsLimit":40000,"vipType":4,"chatbotCredits":0,"codexCredits":0,"claudeCodeCredits":0,"geminiCredits":0,"openclawCredits":0,"generalCredits":0}
+```
+
+**字段说明**：
+- `timestamp`：记录时间戳（秒）
+- `credits`：当前通用积分
+- `creditsLimit`：积分上限
+- `vipType`：VIP类型
+- `chatbotCredits` ~ `generalCredits`：各类型积分包剩余积分
+
+#### 3.2.4 `stats/credits_summary.json`
+
+按天/周/月统计的积分用量汇总：
+
+```json
+{
+  "daily": {
+    "2026-03-07": {
+      "startCredits": 4096,
+      "endCredits": 3500,
+      "consumed": 596,
+      "recovered": 0,
+      "dataPoints": 288
+    }
+  },
+  "weekly": {
+    "2026-W10": {
+      "startCredits": 4096,
+      "endCredits": 3500,
+      "consumed": 596,
+      "recovered": 0
+    }
+  },
+  "monthly": {
+    "2026-03": {
+      "startCredits": 4096,
+      "endCredits": 3500,
+      "consumed": 596,
+      "recovered": 0
+    }
+  }
+}
+```
+
+---
+
+## 4. 双 Token 机制
+
+### 4.1 Kite Token（设备访问凭证）
+
+**作用**：控制哪台设备可以访问 Evol 模块前端
+
+**生成时机**：Evol 短信登录成功后，后端生成
+
+**有效期**：30 天，每次使用时重新计时
+
+**存储位置**：
+- 前端：`localStorage`（key: `evol_kite_token`）
+- 后端：`$KITE_DATA/evol/auth/kite_tokens.json`
+
+**验证流程**：
+1. 前端每次请求携带 Kite Token
+2. 后端从 `kite_tokens.json` 读取 Token 列表
+3. 验证 Token 是否存在、是否有效、是否过期
+4. 如果验证通过，更新 `lastUsedAt` 和 `expiresAt`（重新计时 30 天）
+
+**吊销机制**：
+- 后端提供 RPC 方法 `revoke_kite_token(kite_token, target_token)`
+- 将目标 Token 的 `isValid` 设置为 `false`
+- 被吊销的设备无法再访问前端
+
+---
+
+### 4.2 Evol Token（API 调用凭证）
+
+**作用**：后端调用 Evol API 获取用户数据
+
+**获取时机**：从 Evol 登录接口 `/api/auth/sms/login` 返回
+
+**有效期**：假设 7 天（根据实际情况调整）
+
+**存储位置**：仅后端 `$KITE_DATA/evol/auth/evol_token.json`
+
+**刷新策略**：
+- 每次使用前检查是否过期（距离获取时间超过 6 天则主动刷新）
+- 如果 Evol API 返回 401/500 "Token已失效"，清除缓存并要求重新登录
+
+**安全隔离**：
+- Evol Token 永不暴露给前端
+- 前端只能通过 RPC 方法间接使用
+
+---
+
+## 5. RPC 方法定义
+
+### 5.1 `send_sms`
+
+**功能**：发送短信验证码
+
+**参数**：
+```json
+{
+  "phone": "18616612455"
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "msg": "验证码发送成功"
+}
+```
+
+**错误**：
+```json
+{
+  "success": false,
+  "msg": "发送过于频繁，请稍后再试"
+}
+```
+
+---
+
+### 5.2 `verify_sms`
+
+**功能**：验证短信并完成登录配对
+
+**参数**：
+```json
+{
+  "phone": "18616612455",
+  "code": "708101",
+  "deviceInfo": {
+    "deviceId": "device-uuid-1",
+    "deviceName": "Desktop-PC"
+  }
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "kiteToken": "kite_abc123def456...",
+  "userInfo": {
+    "userId": 102,
+    "nickName": "夙夜无偕",
+    "phone": "18616612455",
+    "avatar": ""
+  }
+}
+```
+
+**错误**：
+```json
+{
+  "success": false,
+  "msg": "验证码错误或已过期"
+}
+```
+
+**后端逻辑**：
+1. 调用 Evol API `/api/auth/sms/login` 验证登录
+2. 缓存 Evol Token 到 `$KITE_DATA/evol/auth/evol_token.json`
+3. 生成 Kite Token（UUID + 时间戳）
+4. 缓存 Kite Token 到 `$KITE_DATA/evol/auth/kite_tokens.json`
+5. 返回 Kite Token 和基本用户信息
+
+---
+
+### 5.3 `get_user_info`
+
+**功能**：获取用户详细信息
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456..."
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "data": {
+    "userInfo": {...},
+    "accountInfo": {...},
+    "teamInfo": {...},
+    "gatewayInfo": {...}
+  }
+}
+```
+
+**错误**：
+```json
+{
+  "success": false,
+  "msg": "Kite Token 无效或已过期",
+  "code": "INVALID_TOKEN"
+}
+```
+
+**后端逻辑**：
+1. 验证 Kite Token（检查有效性、过期时间）
+2. 更新 Kite Token 的 `lastUsedAt` 和 `expiresAt`（重新计时 30 天）
+3. 读取缓存的 Evol Token
+4. 调用 Evol API `/api/auth/sms/userInfo` 获取最新数据
+5. 如果 Evol Token 过期，返回错误要求重新登录
+6. **记录积分快照到 `stats/credits_history.jsonl`**
+7. 返回完整用户信息
+
+---
+
+### 5.4 `refresh_user_info`
+
+**功能**：强制刷新用户信息（忽略缓存）
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456..."
+}
+```
+
+**返回**：同 `get_user_info`
+
+---
+
+### 5.5 `list_devices`
+
+**功能**：列出所有已配对设备
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456..."
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "devices": [
+    {
+      "deviceId": "device-uuid-1",
+      "deviceName": "Desktop-PC",
+      "createdAt": 1709800000,
+      "lastUsedAt": 1709900000,
+      "expiresAt": 1712492000,
+      "isValid": true,
+      "isCurrent": true
+    },
+    {
+      "deviceId": "device-uuid-2",
+      "deviceName": "Laptop",
+      "createdAt": 1709810000,
+      "lastUsedAt": 1709920000,
+      "expiresAt": 1712502000,
+      "isValid": false,
+      "isCurrent": false
+    }
+  ]
+}
+```
+
+---
+
+### 5.6 `revoke_kite_token`
+
+**功能**：吊销指定的 Kite Token
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456...",
+  "targetToken": "kite_xyz789uvw012..."
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "msg": "设备已吊销"
+}
+```
+
+**权限**：
+- 用户可以吊销自己的任何设备
+- 不支持跨用户吊销
+
+---
+
+### 5.7 `get_credits_stats`
+
+**功能**：获取积分统计数据
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456...",
+  "period": "day",
+  "date": "2026-03-07"
+}
+```
+
+**参数说明**：
+- `period`：统计周期，可选值：`day`（按天）、`week`（按周）、`month`（按月）
+- `date`：查询日期（可选，默认今天）
+
+**返回**：
+```json
+{
+  "success": true,
+  "data": {
+    "period": "day",
+    "date": "2026-03-07",
+    "startCredits": 4096,
+    "endCredits": 3500,
+    "consumed": 596,
+    "recovered": 0,
+    "dataPoints": [
+      {"timestamp": 1709800000, "credits": 4096},
+      {"timestamp": 1709800300, "credits": 4050},
+      {"timestamp": 1709800600, "credits": 4000}
+    ]
+  }
+}
+```
+
+---
+
+### 5.8 `logout`
+
+**功能**：退出登录（清除 Evol Token，保留 Kite Token）
+
+**参数**：
+```json
+{
+  "kiteToken": "kite_abc123def456..."
+}
+```
+
+**返回**：
+```json
+{
+  "success": true,
+  "msg": "已退出登录"
+}
+```
+
+**后端逻辑**：
+- 删除 `$KITE_DATA/evol/auth/evol_token.json`
+- 保留 `kite_tokens.json`（设备仍然配对，但需要重新登录 Evol）
+
+---
+
+## 6. 数据流程
+
+### 6.1 首次登录流程
+
+```
+┌─────────┐                  ┌─────────┐                  ┌──────────┐
+│  前端   │                  │  后端   │                  │ Evol API │
+└────┬────┘                  └────┬────┘                  └────┬─────┘
+     │                            │                            │
+     │ 1. 输入手机号              │                            │
+     ├───────────────────────────>│                            │
+     │ RPC: send_sms(phone)       │                            │
+     │                            │ 2. 发送验证码              │
+     │                            ├───────────────────────────>│
+     │                            │ POST /api/auth/sms/send    │
+     │                            │                            │
+     │                            │<───────────────────────────┤
+     │                            │ {"code": 200, "msg": "..."}│
+     │<───────────────────────────┤                            │
+     │ {"success": true}          │                            │
+     │                            │                            │
+     │ 3. 用户手机收到验证码      │                            │
+     │                            │                            │
+     │ 4. 输入验证码              │                            │
+     ├───────────────────────────>│                            │
+     │ RPC: verify_sms(phone,     │                            │
+     │       code, deviceInfo)    │                            │
+     │                            │ 5. 验证登录                │
+     │                            ├───────────────────────────>│
+     │                            │ POST /api/auth/sms/login   │
+     │                            │                            │
+     │                            │<───────────────────────────┤
+     │                            │ {"token": "...", "data":{}}│
+     │                            │                            │
+     │                            │ 6. 缓存 Evol Token         │
+     │                            │    到 evol_token.json      │
+     │                            │                            │
+     │                            │ 7. 生成 Kite Token         │
+     │                            │    缓存到 kite_tokens.json │
+     │                            │                            │
+     │<───────────────────────────┤                            │
+     │ {"success": true,          │                            │
+     │  "kiteToken": "...",       │                            │
+     │  "userInfo": {...}}        │                            │
+     │                            │                            │
+     │ 8. 存储 Kite Token 到      │                            │
+     │    localStorage            │                            │
+     │                            │                            │
+     │ 9. 跳转到用户中心          │                            │
+     │                            │                            │
+```
+
+### 6.2 后续访问流程
+
+```
+┌─────────┐                  ┌─────────┐                  ┌──────────┐
+│  前端   │                  │  后端   │                  │ Evol API │
+└────┬────┘                  └────┬────┘                  └────┬─────┘
+     │                            │                            │
+     │ 1. 页面加载，读取          │                            │
+     │    localStorage 中的       │                            │
+     │    Kite Token              │                            │
+     │                            │                            │
+     │ 2. 请求用户信息            │                            │
+     ├───────────────────────────>│                            │
+     │ RPC: get_user_info(        │                            │
+     │       kiteToken)           │                            │
+     │                            │ 3. 验证 Kite Token         │
+     │                            │    (检查有效性、过期时间)  │
+     │                            │                            │
+     │                            │ 4. 更新 lastUsedAt         │
+     │                            │    重新计时 30 天          │
+     │                            │                            │
+     │                            │ 5. 读取 Evol Token         │
+     │                            │    从 evol_token.json      │
+     │                            │                            │
+     │                            │ 6. 获取用户信息            │
+     │                            ├───────────────────────────>│
+     │                            │ GET /api/auth/sms/userInfo │
+     │                            │ Authorization: Bearer ...  │
+     │                            │                            │
+     │                            │<───────────────────────────┤
+     │                            │ {"code": 200, "data": {}}  │
+     │                            │                            │
+     │<───────────────────────────┤                            │
+     │ {"success": true,          │                            │
+     │  "data": {...}}            │                            │
+     │                            │                            │
+     │ 7. 渲染用户中心页面        │                            │
+     │                            │                            │
+```
+
+### 6.3 跨实例场景
+
+```
+机器 A（实例 1）：
+  - 完成短信登录配对
+  - Evol Token 存储在 $KITE_DATA/evol/auth/evol_token.json
+  - Kite Token A 存储在 $KITE_DATA/evol/auth/kite_tokens.json
+
+机器 B（实例 2）：
+  - 启动另一个 Kite 实例
+  - 读取同一份 $KITE_DATA/evol/auth/evol_token.json（共享 Evol Token）
+  - 前端需要重新配对获取 Kite Token B
+  - Kite Token B 追加到 $KITE_DATA/evol/auth/kite_tokens.json
+
+结果：
+  - 两个实例共享同一个 Evol 账户
+  - 每个实例的前端有独立的 Kite Token
+  - 可以独立管理和吊销每个设备
+```
+
+---
+
+## 7. 前端页面设计
+
+### 7.1 页面结构
+
+```
+┌─────────────────────────────────────┐
+│  Evol 模块                          │
+├─────────────────────────────────────┤
+│  [Module] [User Center] [Stats]     │  ← 标签页
+├─────────────────────────────────────┤
+│                                     │
+│  【未登录状态】                     │
+│  ┌───────────────────────────────┐ │
+│  │  手机号: [______________]     │ │
+│  │  [发送验证码]                 │ │
+│  │                               │ │
+│  │  验证码: [______]             │ │
+│  │  [登录]                       │ │
+│  └───────────────────────────────┘ │
+│                                     │
+│  【已登录状态 - User Center】      │
+│  ┌───────────────────────────────┐ │
+│  │  用户信息                     │ │
+│  │  昵称: 夙夜无偕               │ │
+│  │  手机: 186****2455            │ │
+│  │  AID: evol_1760591501_0...    │ │
+│  ├───────────────────────────────┤ │
+│  │  账户信息                     │ │
+│  │  VIP: Unknown (227天)         │ │
+│  │  余额: ¥0.00                  │ │
+│  ├───────────────────────────────┤ │
+│  │  积分信息                     │ │
+│  │  当前积分: 4096 / 40000       │ │
+│  │  ████░░░░░░░░░░░░░░ 10.2%     │ │
+│  │  恢复速率: 1000 积分/小时     │ │
+│  │  积分包: [详情]               │ │
+│  ├───────────────────────────────┤ │
+│  │  团队信息                     │ │
+│  │  当前团队: EVOL (管理员)      │ │
+│  │  所属团队: [列表]             │ │
+│  ├───────────────────────────────┤ │
+│  │  网关信息                     │ │
+│  │  API Key: mg-56f5bb5e-...     │ │
+│  │  Base URL: https://mg-new...  │ │
+│  ├───────────────────────────────┤ │
+│  │  已配对设备                   │ │
+│  │  Desktop-PC (当前)  [吊销]    │ │
+│  │  Laptop (已吊销)              │ │
+│  └───────────────────────────────┘ │
+│                                     │
+│  【已登录状态 - Stats】            │
+│  ┌───────────────────────────────┐ │
+│  │  积分统计                     │ │
+│  │  [按天] [按周] [按月]         │ │
+│  ├───────────────────────────────┤ │
+│  │  2026-03-07                   │ │
+│  │  消耗: 596  恢复: 0           │ │
+│  ├───────────────────────────────┤ │
+│  │  积分曲线图                   │ │
+│  │  ┌─────────────────────────┐ │ │
+│  │  │  4500 ┤                 │ │ │
+│  │  │  4000 ┤  ╱╲             │ │ │
+│  │  │  3500 ┤ ╱  ╲            │ │ │
+│  │  │  3000 ┤╱    ╲___        │ │ │
+│  │  │       └─────────────────│ │ │
+│  │  │       00:00      23:55  │ │ │
+│  │  └─────────────────────────┘ │ │
+│  ├───────────────────────────────┤ │
+│  │  积分包详情                   │ │
+│  │  通用: 400                    │ │
+│  │  Chatbot: 1000                │ │
+│  │  Codex: 500                   │ │
+│  │  Claude Code: 2000            │ │
+│  │  Gemini: 800                  │ │
+│  │  OpenClaw: 300                │ │
+│  └───────────────────────────────┘ │
+│                                     │
+│  [刷新] [退出登录]                  │
+└─────────────────────────────────────┘
+```
+│  │  当前团队: EVOL (管理员)      │ │
+│  │  所属团队: [列表]             │ │
+│  ├───────────────────────────────┤ │
+│  │  网关信息                     │ │
+│  │  API Key: mg-56f5bb5e-...     │ │
+│  │  Base URL: https://mg-new...  │ │
+│  ├───────────────────────────────┤ │
+│  │  已配对设备                   │ │
+│  │  Desktop-PC (当前)  [吊销]    │ │
+│  │  Laptop (已吊销)              │ │
+│  └───────────────────────────────┘ │
+│                                     │
+│  [刷新] [退出登录]                  │
+└─────────────────────────────────────┘
+```
+
+### 7.2 前端逻辑
+
+#### 7.2.1 `auth.js` - 登录逻辑
+
+```javascript
+// 发送验证码
+async function sendSMS() {
+  const phone = document.getElementById('phone').value;
+  const result = await rpcCall('send_sms', { phone });
+  if (result.success) {
+    startCountdown(); // 60秒倒计时
+  } else {
+    showError(result.msg);
+  }
+}
+
+// 验证登录
+async function verifyLogin() {
+  const phone = document.getElementById('phone').value;
+  const code = document.getElementById('code').value;
+  const deviceInfo = {
+    deviceId: getDeviceId(), // 从 localStorage 获取或生成
+    deviceName: getDeviceName() // 浏览器信息
+  };
+
+  const result = await rpcCall('verify_sms', { phone, code, deviceInfo });
+  if (result.success) {
+    localStorage.setItem('evol_kite_token', result.kiteToken);
+    showUserCenter();
+  } else {
+    showError(result.msg);
+  }
+}
+```
+
+#### 7.2.2 `user-center.js` - 用户中心
+
+```javascript
+// 加载用户信息
+async function loadUserInfo() {
+  const kiteToken = localStorage.getItem('evol_kite_token');
+  if (!kiteToken) {
+    showLoginForm();
+    return;
+  }
+
+  const result = await rpcCall('get_user_info', { kiteToken });
+  if (result.success) {
+    renderUserInfo(result.data);
+  } else if (result.code === 'INVALID_TOKEN') {
+    localStorage.removeItem('evol_kite_token');
+    showLoginForm();
+  } else {
+    showError(result.msg);
+  }
+}
+
+// 刷新用户信息
+async function refreshUserInfo() {
+  const kiteToken = localStorage.getItem('evol_kite_token');
+  const result = await rpcCall('refresh_user_info', { kiteToken });
+  if (result.success) {
+    renderUserInfo(result.data);
+  }
+}
+
+// 退出登录
+async function logout() {
+  const kiteToken = localStorage.getItem('evol_kite_token');
+  await rpcCall('logout', { kiteToken });
+  localStorage.removeItem('evol_kite_token');
+  showLoginForm();
+}
+```
+
+#### 7.2.3 `stats.js` - 积分统计
+
+```javascript
+// 加载积分统计数据
+async function loadCreditsStats(period = 'day', date = null) {
+  const kiteToken = localStorage.getItem('evol_kite_token');
+  const result = await rpcCall('get_credits_stats', {
+    kiteToken,
+    period,
+    date: date || new Date().toISOString().split('T')[0]
+  });
+
+  if (result.success) {
+    renderCreditsChart(result.data);
+  }
+}
+
+// 渲染积分曲线图
+function renderCreditsChart(data) {
+  // 使用 Chart.js 或其他图表库绘制曲线
+  const ctx = document.getElementById('creditsChart').getContext('2d');
+  new Chart(ctx, {
+    type: 'line',
+    data: {
+      labels: data.dataPoints.map(p => formatTime(p.timestamp)),
+      datasets: [{
+        label: '积分',
+        data: data.dataPoints.map(p => p.credits),
+        borderColor: 'rgb(75, 192, 192)',
+        tension: 0.1
+      }]
+    },
+    options: {
+      responsive: true,
+      scales: {
+        y: {
+          beginAtZero: false
+        }
+      }
+    }
+  });
+}
+
+// 切换统计周期
+function switchPeriod(period) {
+  loadCreditsStats(period);
+}
+```
+}
+
+// 退出登录
+async function logout() {
+  const kiteToken = localStorage.getItem('evol_kite_token');
+  await rpcCall('logout', { kiteToken });
+  localStorage.removeItem('evol_kite_token');
+  showLoginForm();
+}
+```
+
+---
+
+## 8. 安全性设计
+
+### 8.1 配对验证安全
+
+- 短信验证码由后端接收，前端必须正确输入才能通过验证
+- 类似 Kite 配对码机制，确保只有持有手机的用户才能配对
+
+### 8.2 Token 隔离
+
+- Evol Token 永不暴露给前端，只在后端使用
+- 前端只持有 Kite Token，无法直接调用 Evol API
+
+### 8.3 设备管理
+
+- 每个设备有独立的 Kite Token
+- 支持查看所有已配对设备
+- 支持吊销任意设备的访问权限
+
+### 8.4 Token 有效期
+
+- Kite Token：30 天有效期，每次使用重新计时
+- Evol Token：7 天有效期，过期后要求重新登录
+
+### 8.5 跨实例安全
+
+- 数据存储在用户级路径，多实例共享
+- 每个实例的前端需要独立配对
+- 吊销操作影响所有实例
+
+---
+
+## 9. 实现优先级
+
+### Phase 1：基础登录功能
+- [ ] 后端 RPC 方法：`send_sms`、`verify_sms`
+- [ ] Evol API 调用封装
+- [ ] Token 缓存机制
+- [ ] 前端登录表单
+
+### Phase 2：用户中心
+- [ ] 后端 RPC 方法：`get_user_info`、`refresh_user_info`
+- [ ] 前端用户中心页面
+- [ ] 数据展示（用户信息、账户、积分、团队、网关）
+
+### Phase 3：积分监控与统计
+- [ ] 后端定时任务：每 5 分钟采集积分数据
+- [ ] 积分历史记录（JSONL 格式）
+- [ ] 积分统计汇总（按天/周/月）
+- [ ] 后端 RPC 方法：`get_credits_stats`
+- [ ] 前端积分曲线图表
+- [ ] 数据清理策略
+
+### Phase 4：设备管理
+- [ ] 后端 RPC 方法：`list_devices`、`revoke_kite_token`
+- [ ] 前端设备列表页面
+- [ ] 吊销功能
+
+### Phase 5：优化
+- [ ] Token 自动刷新
+- [ ] 错误处理优化
+- [ ] 日志记录
+- [ ] 性能优化
+
+---
+
+## 10. Evol API 参考
+
+### 10.1 发送验证码
+
+```
+POST https://api.evolai.cn:8550/api/auth/sms/send
+Content-Type: application/json
+
+{
+  "phone": "18616612455",
+  "codeType": "LOGIN"
+}
+```
+
+### 10.2 验证码登录
+
+```
+POST https://api.evolai.cn:8550/api/auth/sms/login
+Content-Type: application/json
+
+{
+  "phone": "18616612455",
+  "code": "708101",
+  "source": "WEB"
+}
+```
+
+### 10.3 获取用户信息
+
+```
+GET https://api.evolai.cn:8550/api/auth/sms/userInfo
+Authorization: Bearer {evol_token}
+```
+
+详细接口文档见：`docs/05-短信认证与用户信息接口文档.md`
+
+---
+
+## 11. 积分监控与统计
+
+### 11.1 自动采集机制
+
+**采集频率**：每 5 分钟自动调用一次 Evol API 获取用户信息
+
+**触发条件**：
+- Evol Token 有效
+- 至少有一个设备在线（Kite Token 未过期）
+
+**采集流程**：
+1. 后端启动定时任务（5分钟间隔）
+2. 检查 Evol Token 是否有效
+3. 调用 Evol API `/api/auth/sms/userInfo`
+4. 提取积分相关数据
+5. 追加一条记录到 `stats/credits_history.jsonl`
+6. 更新 `stats/credits_summary.json` 汇总数据
+
+**记录格式**：
+```jsonl
+{"timestamp":1709800000,"credits":4096,"creditsLimit":40000,"vipType":4,"chatbotCredits":0,"codexCredits":0,"claudeCodeCredits":0,"geminiCredits":0,"openclawCredits":0,"generalCredits":0}
+```
+
+### 11.2 数据统计
+
+#### 11.2.1 按天统计
+
+**计算逻辑**：
+- 起始积分：当天第一条记录的 `credits`
+- 结束积分：当天最后一条记录的 `credits`
+- 消耗积分：`startCredits - endCredits`（如果为负数，说明有恢复）
+- 恢复积分：如果 `endCredits > startCredits`，则 `recovered = endCredits - startCredits`
+- 数据点数：当天记录总数（理论值：288 = 24小时 × 12次/小时）
+
+**示例**：
+```json
+{
+  "2026-03-07": {
+    "startCredits": 4096,
+    "endCredits": 3500,
+    "consumed": 596,
+    "recovered": 0,
+    "dataPoints": 288
+  }
+}
+```
+
+#### 11.2.2 按周统计
+
+**周定义**：ISO 8601 周（周一为第一天）
+
+**计算逻辑**：
+- 起始积分：本周第一条记录的 `credits`
+- 结束积分：本周最后一条记录的 `credits`
+- 消耗/恢复：同按天统计
+
+**示例**：
+```json
+{
+  "2026-W10": {
+    "startCredits": 4096,
+    "endCredits": 2800,
+    "consumed": 1296,
+    "recovered": 0
+  }
+}
+```
+
+#### 11.2.3 按月统计
+
+**计算逻辑**：同按周统计
+
+**示例**：
+```json
+{
+  "2026-03": {
+    "startCredits": 4096,
+    "endCredits": 1500,
+    "consumed": 2596,
+    "recovered": 0
+  }
+}
+```
+
+### 11.3 前端展示
+
+#### 11.3.1 实时积分卡片
+
+```
+┌─────────────────────────────┐
+│  当前积分                   │
+│  4096 / 40000               │
+│  ████████░░░░░░░░░░ 10.2%   │
+│                             │
+│  恢复速率: 1000 积分/小时   │
+│  预计恢复满: 36 小时        │
+└─────────────────────────────┘
+```
+
+#### 11.3.2 积分用量曲线
+
+**按天查看**：
+- X 轴：时间（00:00 ~ 23:55，每5分钟一个点）
+- Y 轴：积分数量
+- 曲线：显示积分变化趋势
+- 标注：消耗峰值、恢复时段
+
+**按周查看**：
+- X 轴：星期（周一 ~ 周日）
+- Y 轴：每日消耗积分
+- 柱状图：显示每日消耗量
+
+**按月查看**：
+- X 轴：日期（1日 ~ 31日）
+- Y 轴：每日消耗积分
+- 柱状图：显示每日消耗量
+
+#### 11.3.3 积分包详情
+
+```
+┌─────────────────────────────┐
+│  积分包统计                 │
+├─────────────────────────────┤
+│  通用积分: 400              │
+│  Chatbot: 1000              │
+│  Codex: 500                 │
+│  Claude Code: 2000          │
+│  Gemini: 800                │
+│  OpenClaw: 300              │
+├─────────────────────────────┤
+│  总计: 5000                 │
+└─────────────────────────────┘
+```
+
+### 11.4 数据清理策略
+
+**历史数据保留**：
+- 最近 7 天：保留所有 5 分钟级数据
+- 8-30 天：保留每小时数据（取整点数据）
+- 31-90 天：保留每天数据（取 00:00 数据）
+- 90 天以上：删除原始数据，仅保留汇总数据
+
+**清理时机**：
+- 每天凌晨 3:00 执行一次清理任务
+
+---
+
+## 12. 附录
+
+### 12.1 环境变量
+
+- `KITE_DATA`：用户级数据路径（默认 `~/.kite/data`）
+
+### 12.2 配置项
+
+```json
+{
+  "evol": {
+    "api_base_url": "https://api.evolai.cn:8550",
+    "kite_token_ttl": 2592000,
+    "evol_token_ttl": 604800,
+    "stats_interval": 300,
+    "stats_retention_days": 90
+  }
+}
+```
+
+**配置说明**：
+- `api_base_url`：Evol API 基础地址
+- `kite_token_ttl`：Kite Token 有效期（秒，默认 30 天）
+- `evol_token_ttl`：Evol Token 有效期（秒，默认 7 天）
+- `stats_interval`：积分采集间隔（秒，默认 300 = 5 分钟）
+- `stats_retention_days`：原始数据保留天数（默认 90 天）
+
+### 12.3 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `INVALID_TOKEN` | Kite Token 无效或已过期 |
+| `EVOL_TOKEN_EXPIRED` | Evol Token 已过期，需要重新登录 |
+| `DEVICE_REVOKED` | 设备已被吊销 |
+| `SMS_SEND_FAILED` | 短信发送失败 |
+| `SMS_CODE_INVALID` | 验证码错误或已过期 |
+
+---
+
+**文档结束**