iAs/docs/architecture-split-design.md

iAs 进程拆分设计方案

1. 设计结论

当前 ias-service::run_service() 同时承载微信长轮询、邮件轮询、AI 队列、HTTP 服务、control socket 和运行态快照，已经形成单进程强耦合。拆分后不再自研进程间队列，统一使用 async-nats + NATS JetStream 承担消息持久化、路由、Ack、重试和 DLQ。

目标边界：

• Daemon Control Plane：只负责 worker 启停、健康检查、control socket、JetStream 初始化和状态汇总。
• JetStream 数据面：承载所有业务消息，worker 直接 publish/consume。
• Worker：承载业务逻辑，包括渠道、AI、工具、日志、定时任务和 HTTP。

Daemon 不调用 AI、不读写上下文、不调用微信、不处理邮件业务、不决定 typing 生命周期。

2. 当前问题

• core/queue.rs 既是内存队列，又包含上下文记录、AI 调用、工具调用、typing 刷新和微信发送，职责过宽。
• 微信、邮件、AI、HTTP 共享同一 runtime，任何模块阻塞或崩溃都会影响整体。
• 邮件通知直接依赖微信 manager，缺少统一的消息路由。
• 现有 supervisor 只能管理单个后台服务进程，不能管理多个 worker。
• 内存 mpsc 不具备跨进程持久化、Ack、重试、DLQ 和恢复能力。

3. 目标架构

保留一张核心图，后续实现以这张图为准。

flowchart TB
    User["微信用户"] --> WeChatAPI["WeChat API"]
    MailSrv["IMAP / 邮件服务器"] --> MailWorker["Mail Worker"]
    Browser["浏览器 / 管理页面"] --> HttpSvc["HTTP Service"]

    subgraph Control["控制面"]
        CLI["ias CLI"]
        Daemon["Daemon Control Plane<br/>worker 启停 / health / control socket / JetStream bootstrap"]
        Runtime["runtime files<br/>pid / state / logs"]
        CLI --> Daemon
        HttpSvc -- status --> Daemon
        Daemon --> Runtime
    end

    subgraph MQ["数据面：NATS JetStream"]
        Inbound["IA_INBOUND<br/>inbound.wechat.* / inbound.mail.*"]
        Function["IA_FUNCTION<br/>function.call.* / function.result.*"]
        Outbound["IA_OUTBOUND<br/>outbound.wechat.* / outbound.mail.*"]
        Schedule["IA_SCHEDULE<br/>schedule.trigger.*"]
        Logs["IA_LOGS<br/>logs.*"]
        DLQ["IA_DLQ<br/>dlq.*"]
    end

    subgraph Workers["Worker"]
        WeChatWorker["WeChat Worker"]
        MailWorker["Mail Worker"]
        Assistant["Assistant Worker"]
        FunctionWorker["Function Worker"]
        Scheduler["Scheduler Worker"]
        Logging["Logging Worker"]
    end

    subgraph Storage["存储"]
        Pg["PostgreSQL<br/>账号 / 邮件 / 上下文 / 日志 / 定时任务"]
        JS["JetStream file store"]
    end

    WeChatAPI --> WeChatWorker
    WeChatWorker -- publish inbound --> Inbound
    MailWorker -- publish inbound/notification --> Inbound
    Inbound -- consume --> Assistant
    Assistant -- publish function call --> Function
    Function -- consume --> FunctionWorker
    FunctionWorker -- publish function result --> Function
    Function -- consume result --> Assistant
    Assistant -- publish outbound --> Outbound
    Outbound -- consume --> WeChatWorker
    WeChatWorker --> WeChatAPI
    Scheduler -- publish trigger --> Schedule
    Schedule --> Assistant
    Schedule --> FunctionWorker
    Daemon -. log .-> Logs
    WeChatWorker -. log .-> Logs
    MailWorker -. log .-> Logs
    Assistant -. log .-> Logs
    FunctionWorker -. log .-> Logs
    Scheduler -. log .-> Logs
    Logs --> Logging
    Logging --> Pg
    Inbound -. max deliver .-> DLQ
    Function -. max deliver .-> DLQ
    Outbound -. max deliver .-> DLQ
    Schedule -. max deliver .-> DLQ
    Inbound --- JS
    Function --- JS
    Outbound --- JS
    Schedule --- JS
    Logs --- JS
    DLQ --- JS
    Assistant <--> Pg
    WeChatWorker <--> Pg
    MailWorker <--> Pg
    Scheduler <--> Pg
    HttpSvc <--> Pg

4. 核心组件

4.1 Daemon Control Plane

职责：

• 启动、停止、重启 worker 和 HTTP 服务。
• 初始化 JetStream stream、consumer、DLQ。
• 提供 control socket 给 CLI 和 HTTP 状态页。
• 汇总 worker 心跳、JetStream consumer lag、DLQ 数量和最近错误。
• 输出本地运行日志，并发布关键控制事件到 IA_LOGS。

禁止：

• 不调用 ias-ai。
• 不调用 ias-context。
• 不调用 ias-wechat。
• 不解析业务消息 payload。
• 不直接消费或生产业务消息。

4.2 JetStream 数据面

固定使用 async-nats + NATS JetStream。

Streams：

• IA_INBOUND：渠道输入消息，例如 inbound.wechat.*、inbound.mail.*。
• IA_FUNCTION：工具调用和工具结果，例如 function.call.*、function.result.*。
• IA_OUTBOUND：渠道发送命令，例如 outbound.wechat.*。
• IA_SCHEDULE：定时任务触发事件，例如 schedule.trigger.*。
• IA_LOGS：结构化日志事件，例如 logs.daemon.*、logs.worker.*、logs.audit.*。
• IA_DLQ：死信消息，例如 dlq.*。

默认策略：

• 使用 file storage。
• 使用 durable pull consumer。
• 使用 explicit ack。
• 普通消息 AckWait 默认 60 秒，AI 和工具类消息可单独加长。
• MaxDeliver 默认 5 次，超过后进入 IA_DLQ。
• 所有业务处理按 at-least-once 设计，下游必须幂等。

4.3 Worker

• WeChat Worker：微信长轮询、updates_buf 持久化、发布 inbound、消费 outbound、执行发送和 typing。
• Mail Worker：邮件轮询、邮件通知事件、邮件 inbound 事件。
• Assistant Worker：上下文、AI 调用、/new、active turn、typing 决策、工具编排、生成 outbound。
• Function Worker：执行工具、HTTP API、内部功能，返回 function result。
• Scheduler Worker：扫描定时任务，到期后发布 scheduled trigger。
• Logging Worker：消费 IA_LOGS，落库、写文件、聚合错误和审计记录。
• HTTP Service：REST API、SPA、日志/更新查询、daemon 状态代理。

5. 消息标准

所有 JetStream payload 统一包一层业务消息信封，字段保持稳定：

• message_id：消息幂等键。
• topic：业务 topic，与 JetStream subject 对齐。
• trace_id：跨 worker 链路追踪。
• created_at_ms：生成时间。
• attempt_hint：业务层可读的尝试次数提示，真实投递次数以 JetStream 为准。
• payload：业务内容。

常用幂等键：

• 入站消息：message_id = channel/account/external_message_id。
• outbound 命令：command_id。
• function 调用：call_id。
• 定时触发：fire_id = schedule_id + fire_time。
• 日志事件：event_id。

消息内容可以使用 serde_json；不要在 daemon 中解析业务 payload。

6. 日志设计

日志分两层：

• 运行日志：所有进程继续用 tracing 输出到 stdout/file，方便 systemd 和本地排障。
• 结构化事件日志：关键事件发布到 IA_LOGS，由 Logging Worker 落库和归档。

日志事件来源：

• daemon：进程启动/停止、worker 重启、JetStream 初始化、DLQ 操作。
• channel worker：长轮询错误、发送成功/失败、账号状态变化。
• assistant worker：AI 请求摘要、工具调用、上下文错误、/new。
• function worker：工具执行耗时、结果摘要、错误。
• scheduler worker：任务触发、跳过、重复触发拦截。
• HTTP service：管理操作、配置变更、API 错误。

日志要求：

• 所有跨进程消息必须带 trace_id。
• message_id、command_id、call_id、fire_id 必须进入日志字段。
• 默认不记录完整用户正文，只记录摘要、长度和哈希。
• Logging Worker 失败不能阻塞业务流。
• IA_LOGS 必须设置保留周期和最大容量。

7. 定时任务设计

Scheduler Worker 独立运行，不放在 daemon 内。

定时任务来源：

• 数据库表，例如 ias_schedules。
• 少量系统级任务可来自配置文件或环境变量。

任务字段建议：

• schedule_id
• name
• schedule_type：cron 或 interval
• expression
• target_topic
• payload
• enabled
• last_fired_at
• next_fire_at

触发流程：

1. Scheduler Worker 周期扫描启用任务。
2. 到期后生成 fire_id = schedule_id + fire_time。
3. 通过数据库唯一约束抢占触发权。
4. 发布 ScheduledTrigger 到 IA_SCHEDULE。
5. 下游 worker 根据 target_topic 处理。

防重复要求：

• fire_id 必须唯一。
• JetStream publish 使用 message_id 去重窗口。
• 下游 worker 必须按 fire_id 幂等。

8. 模块拆分

目标 crate：

• ias-daemon：control daemon、worker registry、process manager、JetStream bootstrap。
• ias-common：消息类型、JetStream 薄封装、RuntimeSnapshot、control 协议。
• ias-channel：微信和邮件 worker。
• ias-assistant：AI、上下文、工具编排、typing 决策。
• ias-function：工具执行 worker。
• ias-scheduler：定时任务 worker。
• ias-logging：日志消费 worker。
• ias-http：HTTP 服务和 daemon 状态代理。

依赖约束：

• ias-daemon 可以依赖 ias-common 和 async-nats。
• ias-daemon 禁止依赖 ias-ai、ias-context、ias-wechat、ias-mail。
• ias-channel 禁止依赖 ias-ai 和 ias-context。
• ias-assistant 禁止依赖 ias-wechat。
• ias-logging 和 ias-scheduler 不直接调用渠道 SDK 和 AI SDK。

9. CLI 入口

保留现有账号管理命令，不复用 ias channel 作为 worker 启动命令。

新增或调整入口：

• ias service start|stop|restart|status|logs
• ias daemon run
• ias worker assistant
• ias worker wechat --account-ids ...
• ias worker mail
• ias worker function --name ...
• ias worker scheduler
• ias worker logging
• ias http --host 0.0.0.0:9003

10. 部署配置

核心环境变量：

• NATS_URL=nats://127.0.0.1:4222
• IAS_NATS_STREAM_PREFIX=IA
• IAS_NATS_ACK_WAIT_SECS=60
• IAS_NATS_MAX_DELIVER=5
• IAS_CONTROL_SOCKET=/run/user/1000/ias/ias.sock
• IAS_LOG_EVENT_ENABLED=true
• IAS_LOG_EVENT_RETENTION_DAYS=30
• IAS_SCHEDULER_ENABLED=true
• IAS_SCHEDULER_TICK_SECS=10
• HOST=0.0.0.0:9003

JetStream 部署方式：

• NATS Server 作为独立基础设施部署，iAs 只通过 NATS_URL 连接。
• 开发和单机部署优先使用 Docker Compose，便于本地启动、清理和迁移。
• Docker Compose 中的 NATS 启动参数必须等价于 nats-server --jetstream --store_dir=/data --http_port=8222。
• Docker Compose 必须挂载持久化目录，例如 ./data/nats:/data。
• 本机开发端口只绑定 127.0.0.1:4222 和 127.0.0.1:8222，不要暴露公网。
• 生产单机也可以用 systemd 管理 nats-server，推荐配置文件放在 /etc/ias/nats-server.conf，JetStream 数据放在 /var/lib/ias/nats。
• 跨主机或多节点 JetStream 集群不作为第一阶段要求；确实需要时必须补充鉴权、TLS、cluster routes、备份和监控设计。
• daemon 启动时只负责检查和创建 stream、consumer、DLQ，不负责启动 Docker 容器或 systemd 服务。
• NATS 不可用时，worker 必须退避重连；daemon 和 HTTP 状态接口显示 MQ 降级状态。

11. 施工计划

Phase 0：边界收敛

• 确认 daemon 只做 control plane。
• 确认 JetStream stream、subject、consumer 命名。
• 确认 worker CLI 命名不与现有账号管理命令冲突。

Phase 1：公共协议

• 在 ias-common 定义业务消息信封、payload 类型、日志事件和定时触发事件。
• 封装 JetStreamBus，集中处理 publish、consumer、stream 初始化和错误映射。
• 增加消息序列化、幂等键生成和 subject 生成测试。

Phase 2：日志和定时基础

• 创建 IA_LOGS 和 IA_SCHEDULE。
• 实现 Logging Worker 原型。
• 实现 Scheduler Worker 原型。
• 将关键操作日志改成发布 LogEvent，保留本地 tracing 输出。

Phase 3：队列解耦

• 从 core/queue.rs 拆出 JetStream publish/consume 适配。
• 将 AI、上下文、工具编排、typing 决策迁移到 Assistant Worker。
• 将微信发送调用改成 OutboundCommand。
• 先保持单进程兼容模式，验证行为不变。

Phase 4：Daemon 和 Worker 提取

• 创建 ias-daemon，只迁移 control、worker registry、process manager、JetStream bootstrap。
• 创建 ias-assistant、ias-channel、ias-scheduler、ias-logging。
• 实现 worker 注册、心跳、JetStream Ack/Nack、断线重连。

Phase 5：HTTP 和部署

• 添加独立 ias http 入口。
• 添加 daemon control client。
• 更新 service start/stop/status/logs。
• 增加 NATS JetStream Docker Compose 和 systemd 部署说明。

Phase 6：端到端验证

• 微信消息到回复链路。
• AI 工具调用链路。
• worker 崩溃后的 redelivery。
• 定时任务触发和去重。
• 结构化日志落库和查询。
• HTTP 独立运行和 daemon 状态降级。

12. 施工标准

12.1 架构标准

• daemon 不在业务消息数据路径中。
• 所有业务消息必须经过 JetStream。
• worker 之间不得直接调用彼此内部 API。
• 新增业务能力优先通过新增 subject 和 worker 实现，不扩展 daemon 职责。

12.2 依赖标准

• ias-daemon 只能依赖 ias-common、async-nats、日志和进程管理相关依赖。
• ias-common 可以定义协议和薄封装，但不能包含业务逻辑。
• 渠道 SDK 只允许出现在 channel worker。
• AI 和上下文依赖只允许出现在 assistant worker。

12.3 消息标准

• 所有消息必须有 message_id 和 trace_id。
• 所有 outbound 必须有 command_id。
• 所有 function call 必须有 call_id。
• 所有定时触发必须有 fire_id。
• 所有 worker 按 at-least-once 投递语义实现幂等。

12.4 日志标准

• 所有关键状态变化必须发 LogEvent。
• 日志字段必须包含相关 ID：message_id、command_id、call_id、fire_id。
• 默认不得记录完整用户正文。
• 日志流必须设置保留周期和容量上限。

12.5 定时任务标准

• 定时任务触发权必须通过数据库唯一约束或等价机制保证。
• Scheduler Worker 可以多副本运行，但同一 fire_id 只能触发一次。
• 定时任务失败必须可重试或进入 DLQ。

12.6 测试标准

• 每个 worker 至少有消息序列化和幂等测试。
• JetStream consumer Ack/Nack、redelivery、DLQ 必须有集成测试。
• daemon 边界必须通过依赖检查验证。
• 关键端到端链路必须有人工或自动化验证记录。

12.7 部署标准

• NATS 必须作为独立进程或容器部署，不嵌入 iAs daemon。
• JetStream 必须开启 file storage，并配置持久化目录。
• 开发和单机默认使用 Docker Compose；生产单机可改用 systemd。
• NATS client 端口和监控端口默认只监听本机。
• NATS 跨主机访问必须启用鉴权；公网访问必须启用 TLS。
• iAs 代码只能负责连接、初始化和检查 JetStream，不能负责管理 Docker 或 systemd 生命周期。

13. 验收标准

架构验收：

• ias-daemon 编译依赖中不包含 ias-ai、ias-context、ias-wechat、ias-mail。
• 不存在自研 ias-queue.sock 业务数据面。
• 所有 MQ 访问通过 async-nats + JetStream 或 ias-common 的 JetStream 薄封装完成。

消息验收：

• 没有 assistant worker 时，IA_INBOUND 能接收并保留消息。
• 没有 channel worker 时，IA_OUTBOUND 能保留 outbound 消息。
• worker 崩溃或断线后，未 Ack 消息能 redeliver。
• 超过最大投递次数的消息进入 IA_DLQ。

业务验收：

• 微信消息能完成：inbound -> assistant -> outbound -> 微信回复。
• /new 仍能打断同一会话旧 turn。
• typing 由 assistant 生成命令，channel worker 执行。
• 邮件提醒不直接调用微信 manager，而是发布消息后由路由完成发送。

日志验收：

• Logging Worker 能消费 IA_LOGS。
• 结构化日志能写入数据库或文件。
• 日志中能通过 trace_id 串起跨 worker 链路。
• 默认不会记录完整用户正文。

定时任务验收：

• Scheduler Worker 能按 cron/interval 发布 ScheduledTrigger。
• 同一 fire_id 重复启动不会重复触发。
• 定时任务失败能重试或进入 DLQ。

运维验收：

• HTTP 可以在 daemon 不在线时启动，状态接口返回降级结果。
• daemon 重启不影响 JetStream 中未 Ack 消息。
• Docker Compose 或 systemd 重启 NATS 后，JetStream file store 中的未处理消息仍保留。
• NATS 重启后 worker 能退避重连并恢复消费。
• NATS 端口默认只绑定本机；跨主机部署时必须验证鉴权配置。
• service status 能看到 daemon、worker、stream、consumer lag 和 DLQ 摘要。