开发者指南 · 09

Inbox(收件箱)

9.1 用途

Service Agent 通过 contact_admin 工具向 Admin 发送通知,Admin 可在收件箱处理;启用了 Admin WeChat 接入时,Inbox Agent 会自动评估并转发到 WeChat。

9.2 数据结构

text
users/{admin_id}/inbox/
└── inbox_{message_id}.json

字段含 from_service_id / from_conv_id / subject / content / urgency / status: unread|read|archived / created_at 等(详见 docs/filesystem-architecture.md §7)。

9.3 处理链路

text
Service Agent
  └── contact_admin(subject, content, urgency)  [sync tool]
        └── inbox.post_to_inbox()  [via run_coroutine_threadsafe → _main_loop]
              ├── 写 inbox_{id}.json
              ├── _trigger_inbox_agent()
              │     └── 注入最近 3 条 inbox 历史 → 评估 Agent
              │           └── send_message → Admin WeChat(如已连接)
              └── 前端轮询 GET /api/inbox/unread-count → 显示徽章

9.4 关键修复

  • inbox agent 线程池问题contact_admin 是 sync tool,LangGraph 通过 run_in_executor 在线程池执行,asyncio.get_running_loop() 失败。修复:缓存主事件循环 + run_coroutine_threadsafe
  • thread_id 稳定化inbox-{admin_id}(同一 Admin 共用,有累积记忆)

9.5 API 端点

方法路径说明
GET/api/inbox列表
GET/api/inbox/unread-count未读数
GET/api/inbox/{id}详情
PUT/api/inbox/{id}更新状态
DELETE/api/inbox/{id}删除