为什么值得关注

它提供了一个统一、模块化的控制面，涵盖消息平台适配器、LLM 配置、群参与策略、知识库（FAQ/RAG）、成员记忆、插件钩子以及运维可靠性（Redis Streams、Outbox、DLQ），并通过 React 前端和 FastAPI 后端提供 Docker Compose 快速启动体验。

适合谁使用

跨多个消息平台运营群聊机器人的团队
构建具有可定制知识与插件生态的 AI 助手的开发者
需要可观测、可恢复消息基础设施的运维工程师
寻求本地部署多租户 AI 运营仪表板的企业用户

典型使用场景

在微信群中通过已配置的 LLM 和 FAQ 知识库自动回答常见问题
通过单一控制台统一管理机器人在微信、Telegram 等不同适配器中的行为
运行带有积分奖励、内容审核和定时报告的群运营系统
上线前使用内置链路测试工具验证路由和回复结果

项目优势

插件 SPI 可轻松扩展消息平台，内置微信适配器但核心不依赖特定平台
生产级可靠性：Redis Streams、事务 Outbox、重试和死信队列重放
全栈可观测性：集成 OpenTelemetry、指标、日志、追踪和 Grafana 仪表板
完整的 Docker Compose 堆栈，支持离线 fake LLM，方便开发与测试

使用前须知

仅内置微信适配器，其他平台需自行实现适配器 SPI
知识库功能（FAQ/RAG）需要额外部署 Qdrant 并配置 Embedding 提供方
生产环境需要严格管理密钥，并准备独立的 .env.production 配置

README 快速开始

Agent Console

面向群聊与多消息平台的插件化 AI 运营控制台。

统一管理消息平台连接、LLM、群参与策略、知识与成员记忆、插件能力、消息链路和失败恢复。当前内置 WeChat SDK 适配器，但核心平台不依赖微信，可以独立启动，也可以通过适配器 SPI 扩展其他消息平台。

快速体验 · 核心能力 · 系统架构 · 源码开发 · 部署文档

核心能力

领域	能力
消息接入	适配器目录、平台连接、健康探测、会话与参与者同步、租户与群聊作用域
机器人行为	LLM 配置、群参与策略、回复风格、复读策略、行为模拟与链路测试
知识与记忆	FAQ、文档知识库、混合 RAG、成员记忆、人物档案、群聊关系图
Agent 与插件	多轮工具调用、插件 Hook、命令中心、插件安装/启停/升级与作用域策略
群运营	积分、内容审核、主动参与、画图、高德地图和微信管理工具
运维与恢复	Redis Streams、事务 Outbox、重试、消息队列、DLQ 重放、指标、日志与追踪

管理台按“上线向导、消息接入、机器人行为、知识、群运营、能力与集成、系统运维”组织功能，常见操作无需直接调用 API。

基本概念

适配器（Adapter）：让平台能够连接 WeChat 或其他消息提供商的可安装代码。
连接（Connection）：租户实际配置的 SDK、网关或账号实例。安装适配器不等于已经建立连接。
会话（Conversation）：连接下的群、频道或私聊范围。
参与者（Participant）：会话中的消息平台身份。

连接的非敏感配置在控制台“平台连接”页面维护；凭据只保存在部署侧的 Secret Provider 中，控制面仅保存 secret_ref。

系统架构

flowchart LR
    P["消息平台"] --> A["适配器与连接"]
    A --> I["Ingress API验签 · 幂等 · 限流"]
    I --> B["Redis Streams"]
    B --> W["Inbound Worker"]
    W --> O["消息编排器"]
    O --> C["FAQ / RAG / LLM / Agent"]
    O  X["插件 Hooks 与工具"]
    C --> E["Outbox / Effect Intent"]
    E --> D["Outbound Worker"]
    D --> P

    UI["React 管理控制台"] --> API["FastAPI 管理 API"]
    API --> DB[(PostgreSQL)]
    O --> DB
    C -. 可选 .-> Q[(Qdrant)]

核心 API 与 inbound、outbound、scheduler worker 分进程运行。PostgreSQL 保存持久状态，Redis 承担队列、热状态与协调，Qdrant 仅在知识/向量能力启用时需要。

快速体验

推荐使用 Docker Compose。你只需要 Docker Desktop（Windows/macOS）或 Docker Engine + Compose v2（Linux）。默认配置使用离线 fake LLM，未配置 API Key 也能启动控制台并验证链路。

Windows

.\scripts\windows-stack.ps1 start

脚本会在缺少 .env 时从 .env.example 创建一份本地开发配置，并启动完整核心栈。

macOS / Linux

cp .env.example .env
python3 -  |
| API |  |
| API 文档 |  |
| 本地演示管理员令牌 | 上一步生成并写入 `.env` 的随机令牌 |

Windows 启动脚本会完成同样的生成并显示管理员令牌。三个管理侧
secret 均独立生成且只保存在被 Git 忽略的 `.env` 中；不要提交、共享或复用于生产。

默认 `app` profile 会启动 PostgreSQL、Redis、OpenTelemetry Collector、数据库迁移任务、API、三个核心 worker 和前端；不会启动 Qdrant 或微信 bridge，知识向量能力默认关闭。

常用命令：

```bash
docker compose --profile app ps
docker compose --profile app logs -f --tail=100
docker compose --profile app stop
docker compose --profile app down

Windows 也可以使用：

.\scripts\windows-stack.ps1 status
.\scripts\windows-stack.ps1 health
.\scripts\windows-stack.ps1 logs
.\scripts\windows-stack.ps1 stop

down 会保留命名卷中的数据。不要

agent-console