# iPet → Rust (iAs) 迁移计划

## 项目定位
将 iPet（Bun/JS 微信 AI 聊天机器人）迁移到 Rust 实现的 `iAs` 项目。

## 技术栈

| 模块 | Rust 方案 |
|------|-----------|
| 运行时 | `tokio`（full） |
| HTTP 客户端 | `reqwest`（json + stream） |
| 序列化 | `serde` / `serde_json` |
| CLI | `clap`（derive） |
| 数据库 | `sqlx`（postgres + uuid + chrono） |
| 邮箱 | `async-imap` + `mailparse` |
| JWT | `jsonwebtoken` |
| 定时任务 | `tokio-cron-scheduler` |
| 流式 | `tokio-stream` + `futures` |
| 加密 | `sha2` + `hex` + `uuid` |

## 分阶段计划

### Phase 1 ✅ CLI 框架 + 配置系统
- [x] clap 子命令：login, listen, send, whoami
- [x] 配置文件读取（config.json + env var 替换）
- [x] 日志系统（tracing + EnvFilter）
- [x] 状态管理（auth.json / runtime.json 持久化）

### Phase 2 🔜 微信通道（当前阶段）
- [x] API 类型定义
- [ ] 扫码登录（get_bot_qrcode + get_qrcode_status）
- [ ] 长轮询收消息（getupdates）
- [ ] 发送消息（sendmessage）
- [ ] 注册/注销监听器（notifystart/notifystop）
- [ ] 身份和 token 持久化

### Phase 3 ✅ AI 对话（纯对话，无工具）
- [x] DeepSeek 流式 API（SSE + thinking 模式）
- [x] LM Studio 兼容（OpenAI 接口）
- [x] Provider 抽象（LlmProvider trait）
- [x] 对话管理器（Conversation）
  - 消息历史管理
  - 系统提示词
  - 自动修剪历史
  - 流式消费 + 自动记录
- [x] listen 命令集成 LLM 回复

### Phase 4 ✅ PostgreSQL 集成（认证+聊天记录入库）
- [x] sqlx 迁移框架（`migrations/` 目录）
- [x] `app_state` 表：认证信息 Key-Value 存储
- [x] `chat_records` 表：消息收发记录
- [x] 数据库连接池管理（`Database` 结构体）
- [x] 文件存储 → 数据库的自动迁移
- [x] 文件存储降级（无 DB 时保持可用）
- [x] 入库时机：
  - login → auth 入库
  - 收到消息 → inbound 记录
  - echo/LLM 回复 → outbound 记录
  - send 命令 → outbound 记录

### Phase 5 🎯 一切皆 Skill（工具系统）

**设计文档：** `src/tools/DESIGN.md`

**核心思想：** 没有"内置工具"和"外部技能"的区别——所有工具都是 SKILL.md。
- 系统 skills — `resources/skills/`，随 iAs 分发
- 用户 skills — `skills/`，用户自行添加
- 加载时合并，同名用户覆盖系统

**安全模型（仅两级）：**
| 等级 | 行为 |
|------|------|
| Low | 自动执行 |
| High | 微信确认码审批（6位码，5分钟过期）|

**系统 Skills（7个）：**
| Skill | 风险 | 说明 |
|-------|------|------|
| `get_current_datetime` | Low | 获取时间 |
| `query_weather` | Low | 和风天气 |
| `search_web` | Low | Tavily 搜索 |
| `email` | High | 收发邮件 |
| `execute_shell` | High | 执行 shell |
| `list_scheduled_tasks` | Low | 列定时任务 |
| `manage_scheduled_task` | High | 管理定时任务 |

**去掉的模块：**
- ~~MCP 桥接~~（由 Skills 替代）
- ~~Shell 能力~~（由 Skills 替代）
- ~~Medium 风险层~~（仅保留 Low/High）

**实施步骤：**
- [x] 设计文档（DESIGN.md）
- [x] Step 1: SkillSpec/Skill/SkillRegistry 基础设施
- [x] Step 2: SKILL.md 解析器 + 目录扫描（system + user 合并）
- [x] Step 3: 技能执行器（子进程 + stdin 参数 + 结果解析）
- [x] Step 4: 系统 Skills 脚本实现（7 个）
  - get_current_datetime ✅ / query_weather ✅ / search_web ✅
  - email ✅ / execute_shell ✅ / list_scheduled_tasks ✅ / manage_scheduled_task ✅
- [x] Step 5: 审批系统（pending_approvals + 确认码 + oneshot 通道）
  - approval.rs: ApprovalManager（内存 + 数据库双存储）
  - 确认码生成/验证（SHA-256 哈希）
  - 取消支持（0 / 取消）
  - 3 次重试机制
  - 透明模式（LLM 不感知审批过程，确认码回复被 consume 不传 LLM）
- [x] Step 6: LLM function calling 集成
  - ToolCall 类型 + StreamChunk::ToolCalls
  - 流式解析器支持 tool_calls delta
  - Conversation::chat_with_tools() 工具循环
  - SkillSpec → LLM tools JSON 转换
  - ToolExecutor 回调桥接 SkillRegistry
  - 审批回复拦截（handle_reply 优先于 LLM）
  - WeChatClient 可克隆（用于 send_wechat 闭包）

### Phase 6 定时任务（PostgreSQL 调度）
- [ ] 基于 PostgreSQL 的定时任务调度

### Phase 7 上下文管理 + 信任系统
- [ ] 长短期记忆
- [ ] 滚动摘要
- [ ] 用户验证/授权

### Phase 8 优化、测试、部署
- [ ] 错误处理完善
- [ ] 日志优化
- [ ] systemd 服务

## 微信通道 API 参考

Base URL: `https://ilinkai.weixin.qq.com`

### 认证
headers:
- `Authorization: Bearer <token>`
- `AuthorizationType: ilink_bot_token`
- `Content-Type: application/json`
- `iLink-App-Id: <app_id>`
- `iLink-App-ClientVersion: <encoded_uint32>`
- `X-WECHAT-UIN: <random_uint32_b64>`

### 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/ilink/bot/get_bot_qrcode?bot_type=3` | 获取登录二维码 |
| GET | `/ilink/bot/get_qrcode_status?qrcode=<qrcode>` | 轮询扫码状态 |
| POST | `/ilink/bot/msg/notifystart` | 注册监听器 |
| POST | `/ilink/bot/msg/notifystop` | 注销监听器 |
| POST | `/ilink/bot/getupdates` | 长轮询消息 |
| POST | `/ilink/bot/sendmessage` | 发送消息 |
| POST | `/ilink/bot/getconfig` | 获取配置 |
| POST | `/ilink/bot/sendtyping` | 发送输入状态 |