docs: PROJECT_REFERENCE.md — 新会话参考文档
包含项目定位、源码结构、配置、工具架构、审批流程、上下文管理、 数据库表、已知限制
This commit is contained in:
@@ -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: 工具简化为「查询 + 调用」二元接口
|
||||
```
|
||||
Reference in New Issue
Block a user