diff --git a/README.md b/README.md index ad76670..4e8f977 100644 --- a/README.md +++ b/README.md @@ -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 --text ` | 手动发送消息 | | `ias whoami` | 查看登录状态 | | `ias usage` | Token 用量统计（默认 7 天） | -| `ias service` | 后台服务模式（日志 + systemd） | -| `ias daemon` | 守护进程模式（daemon + worker 分离架构） | +| `ias task list` | 列出所有定时任务 | +| `ias task add --name ...` | 添加定时任务 | +| `ias task update ` | 更新定时任务 | +| `ias task delete ` | 删除定时任务 | +| `ias task toggle ` | 启用/禁用定时任务 | +| `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>） -├── 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 | 系统目录路径 |