diff --git a/PROJECT_REFERENCE.md b/PROJECT_REFERENCE.md
new file mode 100644
index 0000000..b030d96
--- /dev/null
+++ b/PROJECT_REFERENCE.md
@@ -0,0 +1,171 @@
+# 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: 工具简化为「查询 + 调用」二元接口
+```