172 lines
6.1 KiB
Markdown
172 lines
6.1 KiB
Markdown
# iAs 项目参考文档
|
||
|
||
> 自动生成于 2026-06-02，供新会话快速了解当前状态。
|
||
> 4950+ 行 Rust，20 次安全审查迭代后稳定运行。
|
||
|
||
---
|
||
|
||
## 项目定位
|
||
|
||
微信 AI 助手。扫码登录微信 iLink Bot，长轮询接收消息，DeepSeek 回复。
|
||
支持工具调用（天气/搜索/邮件/备忘录/定时任务）、长期记忆、审批确认、Token 统计。
|
||
|
||
---
|
||
|
||
## 运行方式
|
||
|
||
```bash
|
||
ias login # 扫码登录
|
||
ias listen --llm # 监听消息 + AI 回复
|
||
ias service # 后台模式（日志写入 ~/.ias/logs/）
|
||
ias usage # Token 统计
|
||
ias skills list # 列出可导入 Skill
|
||
ias skills import # 交互式导入 Skill 到 ~/.ias/skills/
|
||
ias skills delete # 交互式删除
|
||
```
|
||
|
||
---
|
||
|
||
## 源码结构
|
||
|
||
```
|
||
src/
|
||
├── main.rs (900行) CLI 入口 + 命令分发 + 监听循环 + 工具执行器
|
||
├── cli.rs clap 子命令定义
|
||
├── logger.rs 日志初始化（终端 + 文件滚动）
|
||
├── state.rs 文件状态管理（auth/runtime，PostgreSQL 不可用时的降级方案）
|
||
├── scheduler.rs 定时任务调度器（轮询 PostgreSQL + 事务保护）
|
||
├── skills_importer.rs Skills 导入扫描器
|
||
├── context/ 上下文管理
|
||
│ ├── types.rs ChatSession（checkpoint/messages/summaries/user_id）
|
||
│ ├── builder.rs token budget 构建 + 摘要触发
|
||
│ ├── tools.rs MemoryStore（HashMap<user_id, Vec<mem>>）+ read_summaries
|
||
│ └── DESIGN.md 上下文管理设计（未完全实现）
|
||
├── db/ 数据库
|
||
│ ├── mod.rs Database 连接池 + 迁移
|
||
│ └── models.rs CRUD（auth/chat/usage/summary）
|
||
├── llm/ 对话系统
|
||
│ ├── types.rs Message / Role / StreamChunk / Usage
|
||
│ ├── provider.rs create_provider / parse_chat_chunk（SSE 解析）
|
||
│ ├── deepseek.rs DeepSeek 流式客户端（thinking + tool_calls）
|
||
│ └── conversation.rs Conversation（chat + chat_with_tools 工具循环）
|
||
├── tools/ 工具系统
|
||
│ ├── skill.rs SkillSpec / RiskLevel / SkillResult
|
||
│ ├── registry.rs SkillRegistry（加载/执行/审批流程）
|
||
│ ├── builtin.rs BuiltinRegistry（datetime + memos）
|
||
│ ├── parser.rs SKILL.md 解析器（支持 YAML frontmatter）
|
||
│ ├── approval.rs ApprovalManager（确认码 + oneshot 通道）
|
||
│ └── DESIGN.md 工具系统设计文档
|
||
└── wechat/ 微信通道
|
||
├── types.rs iLink API 协议类型
|
||
└── client.rs HTTP 客户端（login/poll/send/notify）
|
||
```
|
||
|
||
---
|
||
|
||
## 配置（仅环境变量）
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 |
|
||
| `DEEPSEEK_MODEL` | 模型名（默认 deepseek-v4-flash） |
|
||
| `DATABASE_URL` | PostgreSQL 连接串（可选，无则用文件存储） |
|
||
| `TAVILY_API_KEY` | Tavily 搜索 API |
|
||
| `QWEATHER_API_HOST` | 和风天气 API |
|
||
| `QWEATHER_JWT_KEY_ID/PROJECT_ID/PRIVATE_KEY_FILE` | 天气 JWT |
|
||
| `WEIXIN_LLM_SYSTEM_PROMPT` | 自定义系统提示词 |
|
||
|
||
加载顺序：`./.env` → `~/.ias/.env` → 环境变量
|
||
|
||
---
|
||
|
||
## 工具架构
|
||
|
||
### LLM 看到的工具（Tool List）
|
||
|
||
```
|
||
query_capabilities → 列出所有可用工具及说明
|
||
call_capability → 按名称调用（name + prompt）
|
||
read_memories → 读长期记忆
|
||
write_memory → 写长期记忆
|
||
read_summaries → 读历史摘要
|
||
```
|
||
|
||
### 工具执行路径
|
||
|
||
```
|
||
executor:
|
||
├── 上下文工具: read_memories / write_memory / read_summaries
|
||
├── query_capabilities: 合并内置 + 外部 SkillSpecs
|
||
├── BuiltinRegistry（内置 Rust 工具）:
|
||
│ ├── get_current_datetime → chrono::Local::now()
|
||
│ └── manage_memos → 文件 I/O（High 先审批）
|
||
└── SkillRegistry（外部 Skills）:
|
||
├── query_weather → bash + openssl JWT
|
||
├── search_web → python Tavily
|
||
├── email → node.js IMAP
|
||
├── execute_shell → bash（High）
|
||
├── list_scheduled_tasks → psql
|
||
├── manage_scheduled_task → psql（High）
|
||
└── manage_skill → bash（High）
|
||
```
|
||
|
||
---
|
||
|
||
## 审批流程
|
||
|
||
```
|
||
High 风险工具 → builtin_approve() 或 approval_flow()
|
||
├── 生成 6 位确认码 → SHA-256 入库
|
||
├── 微信发送确认消息
|
||
├── await oneshot::Receiver（最多 300s）
|
||
├── 用户回复 → handle_reply() → oneshot::Sender
|
||
└── 结果返回 LLM（审批过程 LLM 不可见）
|
||
```
|
||
|
||
---
|
||
|
||
## 上下文管理（当前实现）
|
||
|
||
- **Token Budget**：28K tokens，按中/英文字符估算
|
||
- **检查点**：chatSession.checkpoint，之前的消息已被压缩
|
||
- **摘要触发**：预算溢出或 12h 空闲
|
||
- **用户切换**：清空 session + 加载新用户历史 + 加载记忆
|
||
- **摘要生成**：简单截断占位（未实现 LLM 生成）
|
||
|
||
---
|
||
|
||
## 数据库表
|
||
|
||
| 表 | 用途 |
|
||
|----|------|
|
||
| `app_state` | 认证 KV 存储 |
|
||
| `chat_records` | 收发消息记录 |
|
||
| `llm_usage` | Token 用量（缓存命中率） |
|
||
| `user_memories` | 长期记忆（按 user_id） |
|
||
| `pending_approvals` | 审批记录 |
|
||
| `session_summaries` | 会话摘要 |
|
||
| `scheduled_tasks` | 定时任务 |
|
||
|
||
---
|
||
|
||
## 已知限制
|
||
|
||
| 问题 | 状态 |
|
||
|------|------|
|
||
| 多用户并发（共享 Conversation） | ⚠️ 单用户假设 |
|
||
| 上下文摘要未用 LLM 生成 | ⚠️ 占位截断 |
|
||
| 子代理模式（call_capability prompt → 参数） | ⚠️ 简单关键词提取 |
|
||
| 外部 Skills 依赖 python3/psql/node | ⚠️ 需运行时 |
|
||
| 核心工具未全用 Rust（weather/search/email） | ⚠️ 仍为 bash |
|
||
|
||
---
|
||
|
||
## 最近重要 commit
|
||
|
||
```
|
||
6708fe3 fix: 3 项问题 (审批DB精确匹配 + delete id提取 + 清理变量)
|
||
065229b fix: 优先审批 + 首用户隔离 + 审批DB闭环 + memo错误
|
||
079150b refactor: 删除 config.json + 内置工具抽离 + 统一接口
|
||
b710518 refactor: 工具简化为「查询 + 调用」二元接口
|
||
```
|