iAs/PROJECT_REFERENCE.md

iAs 项目参考文档

自动生成于 2026-06-02，供新会话快速了解当前状态。
4950+ 行 Rust，20 次安全审查迭代后稳定运行。

---

项目定位

微信 AI 助手。扫码登录微信 iLink Bot，长轮询接收消息，DeepSeek 回复。 支持工具调用（天气/搜索/邮件/备忘录/定时任务）、长期记忆、审批确认、Token 统计。

---

运行方式

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: 工具简化为「查询 + 调用」二元接口