agent-fleet/openspec/changes/chatops-architecture-revision/design.md at 1bc7580ecce167b5807501c44216a47f164af74b

Zer4tul 1bc7580ecc refactor: remove Matrix bot, make agent-fleet platform-agnostic API service

- Remove src/integrations/matrix/ (bot connection, command parsing, notification formatting)
- Remove matrix-sdk dependency from Cargo.toml
- Remove MatrixConfig from config.rs and [matrix] from config.example.toml
- Add GET /api/v1/tasks (list with status/agent_id filter)
- Add POST /api/v1/tasks/{task_id}/retry (Failed/AgentLost → Assigned)
- Add EventStore::list_tasks() with parameterized query
- 29/29 tests pass

Platform integration (Telegram, Matrix, Feishu) is Agent-side responsibility.
agent-fleet is now a pure HTTP API orchestration engine.

2026-05-12 10:59:19 +08:00

3 KiB

Raw Blame History

Context

agent-fleet Phase 1 实现了独立的 Matrix bot（通过 matrix-sdk），直接处理 ChatOps 命令和通知推送。这违反了架构职责分离原则：agent-fleet 的角色是纯编排引擎，不应该知道聊天平台的存在。

正确的职责边界：

agent-fleet：纯 HTTP API 服务，管理任务队列、状态机、receipt 验证。返回结构化 JSON。
Agent 层：各自负责平台接入。OpenClaw/Jeeves 连接 Telegram/Matrix/Feishu；Hermes 连接 Telegram/Matrix；Claude Code / Codex / OpenCode 通过 cc-connect 等工具连接。Agent 通过 HTTP API 调用 agent-fleet，自行决定如何展示给人类。

Goals / Non-Goals

Goals:

agent-fleet 成为纯 HTTP API 服务，不持有任何聊天协议连接
新增 HTTP API 端点暴露任务查询和操作
移除 matrix-sdk 依赖，减小编译时间和二进制体积
删除所有不属于编排引擎职责的代码（通知格式化、命令解析）

Non-Goals:

不设计 webhook/SSE 推送机制（Phase 2 考虑）
不实现 Agent 侧的展示逻辑（各 Agent 自行处理）
不关心 Agent 如何连接聊天平台（Agent 自己的事）

Decisions

Decision 1: agent-fleet 是纯 API 服务，平台无关

选择: agent-fleet 不连接任何聊天平台，只暴露 HTTP API

理由:

编排引擎不应该绑定特定聊天平台
平台接入是 Agent 侧的职责：OpenClaw、Hermes 自行连接，Claude Code / Codex 通过 cc-connect 连接
用户可能同时使用 Telegram、Matrix、Feishu，agent-fleet 不需要知道这些
减少 matrix-sdk 依赖（编译慢、体积大）

替代方案:

内置多平台支持（Telegram bot + Matrix bot + Feishu bot）：严重过度设计
单平台 bot：限制了平台选择

Decision 2: 删除通知格式化函数

选择: 不在 agent-fleet 中保留任何通知格式化代码

理由:

agent-fleet 返回结构化 JSON，格式化为人类可读文本是 Agent 的事
不同平台有不同的展示能力（Telegram 支持 Markdown，Feishu 支持卡片，Matrix 支持-thread）
保留格式化函数会诱导未来继续往 agent-fleet 里塞展示逻辑

Decision 3: 新增任务查询和重试 API

选择: GET /api/v1/tasks + POST /api/v1/tasks/{id}/retry

理由:

Agent 需要查询任务状态来展示给人类
Agent 需要触发重试操作响应人类命令
RESTful 风格，与已有 API 一致

Risks / Trade-offs

[实时性] Agent 需要轮询获取状态变更 → Phase 1 可接受；Phase 2 加 SSE 或 webhook
[重复劳动] 每个 Agent 都要写通知格式化 → 各 Agent 最了解自己平台的展示能力，这不算重复

Migration Plan

删除 src/integrations/matrix/ 目录
删除通知格式化代码
新增 API 端点和 EventStore 查询方法
清理 config 和依赖
更新测试

Rollback: git history 可恢复。

Open Questions

Phase 2 是否需要 webhook/SSE 推送？还是 Agent heartbeat 轮询足够？

3 KiB Raw Blame History Unescape Escape