docs: 根据最新代码架构更新 README

- 更新命令列表：移除已废弃的 listen/service，新增 daemon/task/tools - 重写架构描述：从旧版单进程改为三消费者 + 公平队列架构 - 更新源码结构：新增 queue/、channel/ 模块，工具抽象层 - 补充完整工具清单（24 个内置工具） - 更新配置项、数据库表、依赖列表
2026-06-17 10:40:10 +08:00
parent e20cd19e57
commit 52f2593464
1 changed files with 150 additions and 92 deletions
@@ -12,26 +12,29 @@ export DATABASE_URL="postgresql://..."   # PostgreSQL 可选
 # 2. 扫码登录微信
 ias login

-# 3. 启动 AI 自动回复
-ias listen --llm
+# 3. 启动守护进程（AI 自动回复）
+ias daemon

 # 4. 后台运行（配合 systemd）
-ias service
+ias daemon --log-file
 ```

 ## 命令一览

 | 命令 | 说明 |
 |------|------|
-| `ias login` | 扫码登录微信，认证信息存入 PostgreSQL / 本地文件 |
-| `ias listen --llm` | 启动长轮询 + AI 自动回复 |
-| `ias listen --echo` | 启动长轮询 + 原样回显 |
-| `ias listen` | 仅监听，不做回复 |
+| `ias login` | 扫码登录微信，认证信息存入 PostgreSQL |
+| `ias daemon` | 守护进程模式（主运行模式，长轮询 + 三消费者架构） |
+| `ias daemon --log-file` | 守护进程 + 文件日志（配合 systemd） |
 | `ias send --to <id> --text <msg>` | 手动发送消息 |
 | `ias whoami` | 查看登录状态 |
 | `ias usage` | Token 用量统计（默认 7 天） |
-| `ias service` | 后台服务模式（日志 + systemd） |
-| `ias daemon` | 守护进程模式（daemon + worker 分离架构） |
+| `ias task list` | 列出所有定时任务 |
+| `ias task add --name ...` | 添加定时任务 |
+| `ias task update <uuid>` | 更新定时任务 |
+| `ias task delete <uuid>` | 删除定时任务 |
+| `ias task toggle <uuid>` | 启用/禁用定时任务 |
+| `ias tools` | 列出所有可用的 LLM 工具 |
 | `ias tool datetime` | 获取当前时间 |
 | `ias tool weather <城市>` | 查询天气 |
 | `ias tool search <关键词>` | 联网搜索 |
@@ -45,7 +48,8 @@ ias service
 |------|------|------|
 | `DEEPSEEK_API_KEY` | ✅ | DeepSeek API 密钥 |
 | `DEEPSEEK_MODEL` | — | 模型名，默认 `deepseek-v4-flash` |
-| `DATABASE_URL` | — | PostgreSQL 连接串，无则降级文件存储 |
+| `DEEPSEEK_BASE_URL` | — | API 地址，默认 `https://api.deepseek.com/v1` |
+| `DATABASE_URL` | ✅ | PostgreSQL 连接串 |
 | `WEIXIN_LLM_SYSTEM_PROMPT` | — | 自定义系统提示词 |
 | `TAVILY_API_KEY` | — | Tavily 搜索 API Key |
 | `QWEATHER_API_HOST` | — | 和风天气 API 地址 |
@@ -59,114 +63,140 @@ ias service
 ## 架构

 ```
-┌─────────────────────────────────────────────────┐
-│                   iAs CLI                         │
-│  main.rs → clap 子命令路由                        │
-├─────────────────────────────────────────────────┤
-│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
-│  │ WeChat   │  │   LLM    │  │   Tools       │ │
-│  │ 长轮询   │  │ DeepSeek │  │   内置工具    │ │
-│  │ HTTP API │  │ 流式对话 │  │   审批管理    │ │
-│  └────┬─────┘  └────┬─────┘  └──────┬────────┘ │
-│       │              │               │          │
-│  ┌────┴──────────────┴───────────────┴────────┐ │
-│  │           Context / Memory                   │ │
-│  │  ChatSession · Token Budget · 摘要压缩      │ │
-│  │  MemoryStore · 长期记忆                     │ │
-│  └──────────────────────┬──────────────────────┘ │
-│                         │                        │
-│  ┌──────────────────────┴──────────────────────┐ │
-│  │              Database (PostgreSQL)           │ │
-│  │  auth · chat_records · llm_usage            │ │
-│  │  user_memories · pending_approvals          │ │
-│  │  session_summaries · scheduled_tasks        │ │
-│  └─────────────────────────────────────────────┘ │
-├─────────────────────────────────────────────────┤
-│              Daemon / Worker IPC (可选)           │
-│         Unix Domain Socket · 帧协议 · 进程隔离    │
-└─────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                      iAs CLI (main.rs)                        │
+│  clap 子命令路由 → login / daemon / send / tool / task / ... │
+├──────────────────────────────────────────────────────────────┤
+│                     Daemon (daemon.rs)                        │
+│  持有 WeChat 长连接 + 数据库 + 审批管理器 + 长期记忆          │
+├──────────────────────────────────────────────────────────────┤
+│               MessageQueue (公平轮转队列)                      │
+│  按用户轮转出队，防止一个用户刷屏饿死其他人                   │
+├────────────────┬────────────────┬───────────────────────────┤
+│  LLM Consumer  │  Tool Consumer │  Send Consumer             │
+│  Conversation  │  execute_tool  │  WeChatClient.send_text()  │
+│  DeepSeek 流式 │  ApprovalMgr   │  入库 chat_records         │
+│  上下文管理    │  内置工具执行  │                            │
+├────────────────┴────────────────┴───────────────────────────┤
+│                    Context / Memory                           │
+│  ChatSession · Token Budget · 摘要压缩 · MemoryStore         │
+├──────────────────────────────────────────────────────────────┤
+│                    Database (PostgreSQL)                      │
+│  app_state · chat_records · llm_usage · user_memories        │
+│  pending_approvals · session_summaries · scheduled_tasks     │
+└──────────────────────────────────────────────────────────────┘
 ```

 ## 核心数据流

 ```
 微信消息到达
-  → 保存 inbound chat_records
-  → 用户切换：加载历史 + 记忆
-  → 构建 LLM 上下文（token budget + 摘要注入）
-  → Conversation.chat_with_tools()
-     ├── LLM 流式回复
-     ├── 工具调用 → query_capabilities / call_capability
-     │   ├── 上下文工具：read_memories / write_memory / read_summaries
-     │   ├── 内置工具：datetime / weather / search / memos / fetch_page / amap
-     │   └── High 风险工具 → 审批流程
-     └── 工具结果注入对话 → LLM 继续
-  → 保存 outbound chat_records + LLM usage
-  → 微信发送回复
+  → 存 inbound chat_records
+  → enqueue PipelineMessage → MessageQueue 公平轮转
+  → LLM Consumer 消费
+     → 加载用户历史 + 记忆 + 摘要
+     → 构建 LLM 上下文（token budget + 摘要注入）
+     → Conversation.chat_with_tools()
+        ├── LLM 流式回复
+        ├── 工具调用 → enqueue ToolCall → Tool Consumer
+        │   ├── 高风险工具 → ApprovalManager 审批流程
+        │   └── 执行工具 → 结果回喂 LLM
+        └── 最终回复 → enqueue LLMReply → Send Consumer
+  → Send Consumer 发送微信消息 + 入库 outbound chat_records
 ```

 ## 源码结构

 ```
 src/
-├── main.rs              CLI 入口 + 命令实现 + 监听循环 + 工具执行器
-├── cli.rs               clap 子命令定义（login/listen/send/tool 等）
-├── logger.rs            日志初始化（终端 + 文件滚动）
-├── state.rs             本地文件状态（auth.json / runtime.json，无DB时降级）
-├── scheduler.rs         定时任务调度器
-├── context/             上下文管理
-│   ├── types.rs         ChatSession（checkpoint/messages/summaries）
-│   ├── builder.rs       Token budget 估算 + 上下文构建 + 摘要触发
-│   └── tools.rs         MemoryStore（HashMap<user_id, Vec<mem>>）
-├── db/                  数据库
+├── main.rs              CLI 入口 + 命令实现
+├── cli.rs               clap 子命令定义（login/daemon/send/tool/task/tools）
+├── logger.rs            日志初始化（终端 + 文件日滚）
+├── daemon.rs            守护进程核心（长轮询 + 三消费者 + 调度器）
+├── scheduler.rs         定时任务调度器（每 5s 轮询到期任务）
+├── channel/
+│   └── mod.rs           ChannelId（平台+用户标识）、IncomingMessage
+├── queue/
+│   ├── message_queue.rs 公平轮转队列（按用户轮转出队）
+│   └── runner.rs        QueueRunner（出队 → 按类型路由到消费者）
+├── context/
+│   ├── types.rs         ChatSession（消息历史、摘要、checkpoint、token budget）
+│   ├── builder.rs       Token 估算、上下文构建、摘要触发
+│   └── tools.rs         MemoryStore（长期记忆管理器）
+├── db/
 │   ├── mod.rs           Database 连接池 + 迁移
-│   └── models.rs        CRUD（auth/chat/usage/summary）
-├── llm/                 对话系统
+│   └── models.rs        CRUD（auth/chat/usage/summary/memory/task）
+├── llm/
 │   ├── types.rs         Message / Role / ToolCall / StreamChunk / Usage
-│   ├── provider.rs      LlmProvider trait + SSE 解析
-│   ├── deepseek.rs      DeepSeek 流式客户端
+│   ├── provider.rs      LlmProvider trait + SSE 解析 + 工厂函数
+│   ├── deepseek.rs      DeepSeek 流式客户端实现
 │   └── conversation.rs  Conversation（chat + chat_with_tools 工具循环）
-├── tools/               工具系统
+├── tools/
 │   ├── types.rs         RiskLevel / SkillSpec / SkillResult / ExecutionContext
-│   ├── builtin.rs       BuiltinRegistry 路由
+│   ├── tool.rs          Tool trait + ToolRegistry（统一注册表）
+│   ├── api_tool.rs      ApiTool（Rust 闭包实现的工具）
+│   ├── shell_tool.rs    ShellTool（shell 命令执行的工具）
+│   ├── stdio_tool.rs    StdioTool（子进程 stdin/stdout 通信的工具）
+│   ├── builtin.rs       BuiltinRegistry（旧接口兼容层）
 │   ├── approval.rs      ApprovalManager（确认码 + oneshot 通道）
+│   ├── mod.rs           全局注册表 + unpack_call_params + build_capability_guide
 │   └── builtins/        内置工具实现
 │       ├── datetime.rs  日期时间
-│       ├── weather.rs   和风天气（JWT + reqwest）
+│       ├── weather.rs   和风天气（实时/每日预报/逐时预报）
 │       ├── web_search.rs Tavily 搜索
-│       ├── fetch_page.rs 网页抓取
-│       ├── memos.rs     备忘录
-│       └── amap.rs      高德地图（POI/地理编码/路径/旅游规划）
-├── wechat/              微信通道
-│   ├── types.rs         iLink API 协议类型
-│   └── client.rs        HTTP 客户端（login/poll/send/notify）
-├── daemon.rs            守护进程（持有 WeChat + DB，spawn worker）
-├── worker.rs            Worker 进程（无状态 LLM 执行）
-└── ipc.rs               Unix Domain Socket 帧协议
+│       ├── fetch_page.rs 网页抓取（可读性算法）
+│       ├── memos.rs     备忘录（文件存储，增删查）
+│       ├── amap.rs      高德地图（POI/地理编码/路径规划/旅游规划/地图链接）
+│       └── scheduled_task.rs 定时任务管理（增删改查切换）
+└── wechat/
+    ├── types.rs         iLink API 协议类型
+    └── client.rs        HTTP 客户端（login/poll/send/notify）
 ```

 ## 工具系统

-### LLM 可见工具
+### 架构设计（两层元工具）

-| 工具名 | 说明 |
-|--------|------|
-| `query_capabilities` | 列出所有可用工具及参数说明 |
-| `call_capability` | 按名称调用任意工具 |
-| `read_memories` | 读取用户长期记忆 |
-| `write_memory` | 写入长期记忆 |
-| `read_summaries` | 读取历史会话摘要 |
+LLM 不直接感知每个具体工具，而是通过两个**元工具**间接调用：
+
+1. **`query_capabilities`** — 列出所有可用工具的名称、描述、参数格式
+2. **`call_capability`** — 按名称调用工具，参数通过 JSON 传递
+
+### 工具抽象
+
+所有工具分为三种类型：
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `ApiTool` | Rust 闭包实现的工具（HTTP API / 本地计算 / 文件 I/O） | 天气、搜索、高德地图 |
+| `ShellTool` | 通过 shell 命令执行的工具 | 定时任务、系统命令 |
+| `StdioTool` | 通过子进程 stdin/stdout 通信的工具 | 外部脚本、可执行程序 |

 ### 内置工具

-| 工具 | 风险 | 说明 |
-|------|------|------|
+| 工具名 | 风险 | 说明 |
+|--------|------|------|
 | `get_current_datetime` | Low | 获取北京时间 |
-| `query_weather` | Low | 和风天气查询 |
+| `weather_now` | Low | 实时天气（和风天气） |
+| `weather_forecast` | Low | 每日天气预报 |
+| `weather_hourly` | Low | 逐时天气预报 |
 | `web_search` | Low | Tavily 联网搜索 |
-| `fetch_page` | Low | 网页正文提取 |
-| `manage_memos` | Low | 备忘录增删查 |
-| `amap_*` | Low | 高德地图系列 |
+| `fetch_page` | Low | 网页正文提取（可读性算法） |
+| `memos_list` | Low | 列出备忘录 |
+| `memos_add` | Low | 添加备忘录 |
+| `memos_get` | Low | 查看指定备忘录 |
+| `memos_delete` | Low | 删除备忘录 |
+| `amap_poi_search` | Low | POI 搜索 + 周边搜索 |
+| `amap_geocode` | Low | 地理编码（地址→坐标） |
+| `amap_reverse_geocode` | Low | 逆地理编码（坐标→地址） |
+| `amap_route_plan` | Low | 路径规划（步行/驾车/骑行/电动车/公交） |
+| `amap_travel_plan` | Low | 智能旅游规划 |
+| `amap_map_link` | Low | 生成地图可视化链接 |
+| `scheduled_task_list` | Low | 列出定时任务 |
+| `scheduled_task_add` | Low | 添加定时任务 |
+| `scheduled_task_update` | Low | 更新定时任务 |
+| `scheduled_task_delete` | Low | 删除定时任务 |
+| `scheduled_task_toggle` | Low | 启用/禁用定时任务 |

 ### 审批流程

@@ -191,6 +221,28 @@ LLM 不感知确认码和审批过程，只看到最终的执行结果。
 - **长期记忆**：LLM 按需通过 `read_memories` / `write_memory` 读写
 - **用户隔离**：切换用户时清空 session，按需加载新用户历史

+## 消息队列（三消费者架构）
+
+```
+                    ┌──────────────┐
+    enqueue ──────→ │ MessageQueue │ ← 公平轮转（按用户）
+                    └──────┬───────┘
+                           │ dequeue
+                           ▼
+                    ┌──────────────┐
+                    │ QueueRunner  │ ← 路由循环
+                    └──┬───┬───┬──┘
+                     ┌─┘   │   └─┐
+                     ▼     ▼     ▼
+                  LLM    Tool    Send
+                Consumer Consumer Consumer
+```
+
+消息路由规则：
+- `UserMessage` / `ToolResult` / `ScheduledTask` → **LLM Consumer**
+- `ToolCall` / `ApprovalRequest` → **Tool Consumer**
+- `LLMReply` → **Send Consumer**
+
 ## 数据库表

 | 表 | 用途 |
@@ -201,7 +253,7 @@ LLM 不感知确认码和审批过程，只看到最终的执行结果。
 | `user_memories` | 长期记忆（按 user_id） |
 | `pending_approvals` | 待审批记录（SHA-256 确认码） |
 | `session_summaries` | 会话摘要 |
-| `scheduled_tasks` | 定时任务 |
+| `scheduled_tasks` | 定时任务（支持 model/system 类型） |

 ## 部署

@@ -215,10 +267,10 @@ sudo systemctl enable --now ias

 ### 天气 API 密钥

-将和风天气 Ed25519 密钥对放入 `qweather/` 目录：
+将和风天气 Ed25519 密钥对放入 `~/.ias/qweather/` 目录：

 ```
-qweather/
+~/.ias/qweather/
 ├── ed25519-private.pem
 └── ed25519-public.pem
 ```
@@ -236,5 +288,11 @@ qweather/
 | tracing | 结构化日志 |
 | async-trait | 异步 trait |
 | ed25519-dalek | 天气 API JWT 签名 |
-| scraper | 网页正文提取 |
+| scraper | 网页正文提取（可读性算法） |
 | sha2 / hex / rand | 审批确认码加密 |
+| uuid | 会话/任务唯一标识 |
+| base64 | Base64 编码 |
+| qrcode / image | 二维码生成 |
+| rustyline / dialoguer / console | 终端交互 |
+| futures-util | 流式处理工具 |
+| dirs | 系统目录路径 |