# iAs 代码调用图谱

> 微信 AI 智能助手 —— 完整架构与调用关系

---

## 1. 全局架构总览

```mermaid
flowchart TB
    subgraph CLI["CLI 入口 (main.rs)"]
        A1["clap::Parser Cli 解析"]
        A2["cmd_login"]
        A3["cmd_listen"]
        A4["cmd_send"]
        A5["cmd_whoami"]
        A6["cmd_usage"]
        A7["cmd_tool"]
        A8["cmd_daemon"]
    end
    subgraph DAEMON["守护进程 (daemon.rs)"]
        B0["run()"]
        B1["spawn_consumers()"]
        B2["llm_consumer_loop"]
        B3["tool_consumer_loop"]
        B4["send_consumer_loop"]
        B5["run_llm_round / resume_llm_round"]
        B6["handle_chat_result"]
        B7["execute_tool"]
    end
    subgraph QUEUE["消息队列 (queue/)"]
        C1["MessageQueue 公平轮转"]
        C2["QueueRunner 路由调度"]
        C3["EnqueueHandle"]
        C4["ConsumerChannels"]
    end
    subgraph LLM["LLM 对话系统 (llm/)"]
        D1["Conversation 对话管理器"]
        D2["chat_with_tools() / run_tool_loop()"]
        D3["DeepSeekProvider"]
        D4["LlmProvider trait"]
        D5["StreamReceiver"]
    end
    subgraph CONTEXT["上下文管理 (context/)"]
        E1["ChatSession 消息历史+摘要"]
        E2["builder Token估算+上下文构建"]
        E3["MemoryStore 长期记忆"]
        E4["read_summaries"]
    end
    subgraph TOOLS["工具系统 (tools/)"]
        F1["BuiltinRegistry 工具注册表"]
        F2["ApprovalManager 审批管理"]
        F3["build_capability_guide"]
        F4["unpack_call_params"]
        subgraph BUILTINS["内置工具 (builtins/)"]
            G1["datetime"]
            G2["weather"]
            G3["web_search"]
            G4["fetch_page"]
            G5["memos"]
            G6["amap"]
        end
    end
    subgraph WECHAT["微信通道 (wechat/)"]
        H1["WeChatClient"]
        H2["receive_messages()"]
        H3["send_text()"]
        H4["login()"]
        H5["notify_start/stop"]
    end
    subgraph DB["数据库 (db/)"]
        I1["Database::connect()"]
        I2["models CRUD 操作"]
    end
    subgraph OTHER["其他模块"]
        J1["state.rs 文件状态回退"]
        J2["scheduler.rs 定时任务"]
        J3["logger.rs 日志初始化"]
        J4["channel/mod.rs ChannelId"]
        J5["ipc.rs UDS 协议(已废弃)"]
        J6["worker.rs 旧架构(已废弃)"]
    end

    A1 --> A2 & A3 & A4 & A5 & A6 & A7 & A8
    A3 --> B0
    A8 --> B0
    B0 --> B1
    B1 --> B2 & B3 & B4
    B2 --> B5 & B6
    B3 --> B7
    B0 --> C1 & C2 & C3
    C2 --> C4
    C4 --> B2 & B3 & B4
    B2 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> D4
    D4 --> D5
    D1 --> E1
    D2 --> E2
    B2 --> E3 & E4
    D2 --> F1
    B3 --> F1 & F2
    B7 --> F1 & F3 & F4
    F1 --> G1 & G2 & G3 & G4 & G5 & G6
    B4 --> H1
    H1 --> H2 & H3
    B0 --> I1
    B2 --> I2
    B4 --> I2
    A2 --> I2 & J1
    A3 --> J1
    B0 --> J1 & J2
    A1 --> J3
```

---

## 2. 消息处理全链路

```mermaid
sequenceDiagram
    participant WX as 微信用户
    participant WC as WeChatClient
    participant MQ as MessageQueue
    participant QR as QueueRunner
    participant LC as LLM Consumer
    participant TC as Tool Consumer
    participant SC as Send Consumer
    participant LLM as DeepSeek API
    participant BT as BuiltinRegistry

    WX->>WC: 发送消息
    WC->>MQ: enqueue(UserMessage)
    MQ->>QR: dequeue (公平轮转)
    QR->>LC: llm_tx.send(UserMessage)
    LC->>LC: 加载历史/记忆/摘要
    LC->>LLM: chat_stream(上下文)
    LLM-->>LC: 流式回复 + tool_calls

    alt 有工具调用
        LC->>MQ: enqueue(ToolCall)
        MQ->>QR: dequeue
        QR->>TC: tool_tx.send(ToolCall)

        alt 高风险工具
            TC->>TC: ApprovalManager.create()
            TC->>MQ: enqueue(LLMReply: 确认码)
            MQ->>QR: dequeue
            QR->>SC: send_tx.send(LLMReply)
            SC->>WC: send_text(确认码)
            WX-->>WC: 回复确认码
            WC->>MQ: enqueue(UserMessage: 确认码)
            MQ->>QR: dequeue
            QR->>LC: llm_tx.send(确认码)
            LC->>TC: ApprovalManager.handle_reply()
            TC-->>LC: Approved
            LC->>MQ: enqueue(ToolCall + approved=true)
            MQ->>QR: dequeue
            QR->>TC: tool_tx.send(ToolCall)
        end

        TC->>BT: execute(工具名, 参数)
        BT-->>TC: SkillResult
        TC->>MQ: enqueue(ToolResult)
        MQ->>QR: dequeue
        QR->>LC: llm_tx.send(ToolResult)
        LC->>LLM: resume_tool_loop()
        LLM-->>LC: 最终回复
    end

    LC->>MQ: enqueue(LLMReply)
    MQ->>QR: dequeue
    QR->>SC: send_tx.send(LLMReply)
    SC->>WC: send_text(回复)
    WC->>WX: 显示回复
```

---

## 3. 模块依赖关系

```mermaid
flowchart LR
    subgraph CORE["核心层"]
        MAIN["main.rs"]
        DAEMON["daemon.rs"]
        CLI["cli.rs"]
    end
    subgraph PIPELINE["消息管线"]
        QUEUE["queue/"]
        CHANNEL["channel/"]
    end
    subgraph AI["AI 层"]
        LLM["llm/"]
        CTX["context/"]
    end
    subgraph TOOL["工具层"]
        TOOLS["tools/"]
        BUILTINS["tools/builtins/"]
        APPROVAL["tools/approval.rs"]
    end
    subgraph IO["IO 层"]
        WECHAT["wechat/"]
        DB["db/"]
        STATE["state.rs"]
        SCHED["scheduler.rs"]
    end
    subgraph UTIL["工具层"]
        LOG["logger.rs"]
        IPC["ipc.rs"]
        WORKER["worker.rs"]
    end

    MAIN --> CLI & DAEMON & LOG & STATE & DB & CTX & LLM & TOOLS & WECHAT & SCHED
    DAEMON --> QUEUE & CHANNEL & WECHAT & DB & STATE & LLM & CTX & TOOLS & SCHED
    QUEUE --> CHANNEL
    LLM --> CTX & TOOLS
    TOOLS --> BUILTINS & APPROVAL
    CTX --> DB
    TOOLS --> DB
    APPROVAL --> DB
    DB --> STATE
    WORKER --> IPC & LLM & TOOLS
```

---

## 4. 数据流（消息生命周期）

```mermaid
flowchart TB
    START(["📱 用户发消息"]) --> A["WeChatClient receive_messages()"]
    A --> B["入库: chat_records (inbound)"]
    B --> C["PipelineMessage kind: UserMessage"]
    C --> D["MessageQueue 公平轮转"]
    D --> E["加载历史消息 (最近20条)"]
    E --> F["加载长期记忆 (MemoryStore)"]
    F --> G["加载摘要 (read_summaries)"]
    G --> H["构建上下文 (builder)"]
    H --> I["Conversation chat_with_tools()"]
    I --> J{"LLM 调用了工具？"}
    J -->|"是"| K["Tool Consumer 执行工具"]
    K --> L{"高风险？→ 审批流程"}
    L --> M["结果回喂 LLM"]
    M --> I
    J -->|"否"| N["LLM 生成最终回复"]
    N --> O["Send Consumer send_text()"]
    O --> P["入库: chat_records (outbound)"]
    P --> ENDD(["📱 用户收到回复"])
```

---

## 5. 关键函数调用关系

### 5.1 工具执行链路

```mermaid
flowchart TB
    subgraph LLM_SIDE["LLM 侧"]
        A["LLM 调用 call_capability()"]
        B["ToolExecutor (闭包)"]
        C["返回 ASYNC_MARKER + 工具名"]
    end
    subgraph QUEUE_SIDE["队列侧"]
        D["PipelineMessage::tool_call()"]
        E["MessageQueue.enqueue()"]
        F["QueueRunner → Tool Consumer"]
    end
    subgraph TOOL_SIDE["工具侧"]
        G["tool_consumer_loop()"]
        H{"高风险？"}
        I["ApprovalManager 审批流程"]
        J["execute_tool()"]
        K{"工具类型？"}
        L["BuiltinRegistry.execute()"]
        M["上下文工具 直接处理"]
        N["unpack_call_params()"]
    end
    subgraph RESULT["结果回喂"]
        O["PipelineMessage::tool_result()"]
        P["LLM Consumer resume_llm_round()"]
        Q["Conversation resume_tool_loop()"]
    end

    A --> B --> C --> D --> E --> F --> G
    G --> H
    H -->|"是"| I --> J
    H -->|"否"| J
    J --> K
    K -->|"内置工具"| L
    K -->|"上下文工具"| M
    K -->|"call_capability"| N --> K
    J --> O --> P --> Q
```

### 5.2 审批流程

```mermaid
flowchart TB
    A["LLM 请求高风险工具"] --> B["ApprovalManager.create(user_id, tool)"]
    B --> C["生成 6 位确认码 SHA-256 哈希存储"]
    B --> D["创建 oneshot channel"]
    C --> E["发送消息给用户 ⚠️ 操作确认"]
    D --> F["等待用户回复 超时 5 分钟"]
    F --> G{"用户回复"}
    G -->|"匹配确认码"| H["ApprovalDecision::Approved"]
    G -->|"输入 0/取消"| I["ApprovalDecision::Rejected"]
    G -->|"不匹配(最多3次)"| J["减少尝试次数"]
    G -->|"超时"| K["ApprovalDecision::Expired"]
    J --> F
    H --> L["重新入队 UserMessage + approved_tool"]
    I --> M["回复用户: 已取消"]
    K --> N["回复用户: 已超时"]
```

### 5.3 上下文构建流程

```mermaid
flowchart TB
    A["ChatSession (消息历史)"] --> B["estimate_tokens()"]
    B --> C{"Token 超 budget? (默认 28000)"}
    C -->|"是"| D{"checkpoint 之前有未摘要消息？"}
    D -->|"是"| E["trigger_overflow_summary() → 调用 LLM 生成摘要"]
    D -->|"否"| F["裁剪最早的消息 直到符合 budget"]
    C -->|"否"| G{"空闲超时? (12h 无消息)"}
    G -->|"是"| H["trigger_idle_summary() → 清空消息, 保留摘要"]
    G -->|"否"| I["build_context() → 组装最终上下文"]
    E --> I
    F --> I
    H --> I
    I --> J["发送给 LLM"]
```

---

## 6. 文件依赖矩阵

| 文件 | 依赖的关键模块 |
|------|---------------|
| `main.rs` | cli, daemon, db, llm, context, tools, wechat, state, scheduler, logger |
| `daemon.rs` | queue, channel, wechat, db, state, llm, context, tools, scheduler |
| `cli.rs` | clap (独立) |
| `llm/conversation.rs` | context/builder, context/types, llm/provider, llm/types |
| `llm/deepseek.rs` | llm/provider, llm/types |
| `llm/provider.rs` | llm/types |
| `llm/types.rs` | serde (独立) |
| `context/types.rs` | llm/types |
| `context/builder.rs` | context/types, llm/types |
| `context/tools.rs` | db/models |
| `queue/message_queue.rs` | channel/mod |
| `queue/runner.rs` | queue/message_queue |
| `tools/builtin.rs` | tools/types, tools/builtins/* |
| `tools/approval.rs` | db/models |
| `tools/mod.rs` | tools/types |
| `wechat/client.rs` | wechat/types |
| `wechat/types.rs` | serde (独立) |
| `db/mod.rs` | db/models |
| `db/models.rs` | sqlx (独立) |
| `state.rs` | serde (独立) |
| `scheduler.rs` | db/models |
| `worker.rs` | ipc, llm, tools (已废弃) |
| `ipc.rs` | serde (已废弃) |

---

## 7. 启动流程

```mermaid
flowchart TB
    START(["ias listen --llm"]) --> A["main()"]
    A --> B["clap::Parser::parse()"]
    B --> C{"命令类型"}
    C -->|"Tool"| D["cmd_tool() 直接执行工具"]
    C -->|"Login"| E["cmd_login() 扫码登录"]
    C -->|"Listen/Service"| F["cmd_listen()"]

    F --> G["加载 .env"]
    F --> H["Database::connect()"]
    H --> I{"数据库可用？"}
    I -->|"是"| J["创建 MemoryStore (DB 模式)"]
    I -->|"否"| K["创建 MemoryStore (文件模式)"]

    F --> L["加载认证信息"]
    L --> M{"已登录？"}
    M -->|"否"| N["报错退出"]
    M -->|"是"| O["WeChatClient.set_auth()"]

    O --> P["WeChatClient.notify_start()"]
    P --> Q["创建 ApprovalManager"]
    Q --> R["创建 Conversation + ToolExecutor"]
    R --> S["启动 Scheduler (定时任务)"]
    S --> T["启动 listen_loop()"]

    T --> U["WeChatClient.receive_messages()"]
    U --> V{"收到消息？"}
    V -->|"是"| W["enqueue PipelineMessage"]
    W --> X["LLM/Tool/Send 消费者处理"]
    V -->|"否/超时"| U
```

---

## 8. 消费者架构（三消费者）

```mermaid
flowchart TB
    subgraph QUEUE2["消息队列"]
        Q["MessageQueue 公平轮转"]
        R["QueueRunner 路由"]
    end
    subgraph LLM_C["LLM Consumer"]
        L1["接收: UserMessage / ToolResult / ScheduledTask"]
        L2["加载用户历史 + 记忆 + 摘要"]
        L3["创建/恢复 Conversation"]
        L4["chat_with_tools() / resume_tool_loop()"]
        L5{"有异步工具等待？"}
        L6["发送 LLMReply"]
        L7["保留 session"]
        L8["清理 session"]
    end
    subgraph TOOL_C["Tool Consumer"]
        T1["接收: ToolCall / ApprovalRequest"]
        T2{"高风险 + 未审批？"}
        T3["ApprovalManager.create()"]
        T4["发送确认码"]
        T5["execute_tool()"]
        T6["发送 ToolResult"]
    end
    subgraph SEND_C["Send Consumer"]
        S1["接收: LLMReply"]
        S2["WeChatClient.send_text()"]
        S3["入库: chat_records (outbound)"]
    end

    Q --> R
    R -->|"UserMessage / ToolResult"| L1
    R -->|"ToolCall"| T1
    R -->|"LLMReply"| S1
    L1 --> L2 --> L3 --> L4
    L4 --> L5
    L5 -->|"是"| L7
    L5 -->|"否"| L6
```