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.
This commit is contained in:
parent
6efca09018
commit
1bc7580ecc
15 changed files with 435 additions and 2367 deletions
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-05-11
|
||||
73
openspec/changes/chatops-architecture-revision/design.md
Normal file
73
openspec/changes/chatops-architecture-revision/design.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
## 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
|
||||
|
||||
1. 删除 `src/integrations/matrix/` 目录
|
||||
2. 删除通知格式化代码
|
||||
3. 新增 API 端点和 EventStore 查询方法
|
||||
4. 清理 config 和依赖
|
||||
5. 更新测试
|
||||
|
||||
**Rollback**: git history 可恢复。
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Phase 2 是否需要 webhook/SSE 推送?还是 Agent heartbeat 轮询足够?
|
||||
38
openspec/changes/chatops-architecture-revision/proposal.md
Normal file
38
openspec/changes/chatops-architecture-revision/proposal.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
## Why
|
||||
|
||||
agent-fleet 当前实现了一个独立的 Matrix bot 连接(matrix-sdk),直接处理 ChatOps 命令和通知推送。这违反了架构职责分离原则:
|
||||
|
||||
1. **Session 冲突**:`@jeeves:0x08.org` 已被 OpenClaw 占用
|
||||
2. **架构冗余**:agent-fleet 重新实现了消息收发、命令路由、通知推送
|
||||
3. **违背最小化原则**:agent-fleet 的核心价值是编排引擎(任务队列、状态机、receipt 验证),不是聊天界面
|
||||
4. **平台绑定**:硬编码 Matrix 协议,但 agent-fleet 作为纯 API 服务应该是平台无关的
|
||||
|
||||
agent-fleet 应该是一个纯 HTTP API 服务,不知道也不关心聊天平台的存在。平台接入(Telegram、Matrix、Feishu 等)完全是 Agent 侧的事情:
|
||||
- OpenClaw/Jeeves 自己连接多个平台
|
||||
- Hermes Agent 自己连接 Telegram 或 Matrix
|
||||
- Claude Code / Codex / OpenCode 通过 cc-connect 等扩展工具连接平台
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: 移除 `src/integrations/matrix/` 中的独立 Matrix bot 实现
|
||||
- 移除通知格式化函数(不属于编排引擎的职责)
|
||||
- 新增 `GET /api/v1/tasks` 端点(任务列表查询,支持过滤)
|
||||
- 新增 `POST /api/v1/tasks/{id}/retry` 端点(任务重试)
|
||||
- `config.toml` 移除 `[matrix]` section
|
||||
- `Cargo.toml` 移除 `matrix-sdk` 依赖
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `task-api-endpoints`: 任务查询和操作 HTTP API 端点(`GET /api/v1/tasks`, `POST /api/v1/tasks/{id}/retry`),返回结构化 JSON
|
||||
|
||||
### Modified Capabilities
|
||||
- `matrix-chatops`: 移除独立 bot 连接和 ChatOps 功能。Orchestrator 只负责暴露 HTTP API,不涉及任何聊天平台集成。本 capability 修订后实质上变为"Orchestrator API 暴露足够信息供外部 Agent 展示"。
|
||||
|
||||
## Impact
|
||||
|
||||
- **代码**:删除 `src/integrations/matrix/` 目录及相关引用
|
||||
- **API**:新增 2 个端点,无破坏性变更
|
||||
- **配置**:`config.toml` 移除 `[matrix]` section
|
||||
- **依赖**:从 `Cargo.toml` 移除 `matrix-sdk`
|
||||
- **职责边界**:agent-fleet 只返回结构化 JSON,不关心如何展示给人类
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Orchestrator exposes status via API only
|
||||
Orchestrator SHALL 通过 HTTP API 暴露所有任务和 Agent 状态信息,不连接任何外部聊天或通知平台。平台接入由各 Agent 自行处理。
|
||||
|
||||
#### Scenario: Task state change queryable via API
|
||||
- **WHEN** 任务 #42 状态变更(assigned、completed、failed 等)
|
||||
- **THEN** 变更 SHALL 通过 `GET /api/v1/tasks` API 可查询
|
||||
- **AND** 变更 SHALL 记录在 task_events 表中
|
||||
|
||||
#### Scenario: Agent state change queryable via API
|
||||
- **WHEN** Agent `worker-03` 状态变更(online、offline 等)
|
||||
- **THEN** 变更 SHALL 通过 `GET /api/v1/agents` API 可查询
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Matrix room as coordination channel
|
||||
**Reason**: Orchestrator 不连接任何聊天平台。平台接入是 Agent 侧的职责。
|
||||
**Migration**: 各 Agent(OpenClaw/Jeeves、Hermes 等)自行连接聊天平台,通过 Orchestrator HTTP API 获取状态后展示。
|
||||
|
||||
### Requirement: Slash commands for orchestration
|
||||
**Reason**: Orchestrator 不处理命令。命令解析和路由由各 Agent 自行处理。
|
||||
**Migration**: 各 Agent 解析用户命令,调用 Orchestrator HTTP API 执行操作。
|
||||
|
||||
### Requirement: Matrix notifications for receipts
|
||||
**Reason**: Orchestrator 不推送通知。通知由各 Agent 根据所在平台能力自行处理。
|
||||
**Migration**: Agent 通过 API 轮询或 webhook 获取 receipt 状态变更,自行决定通知方式和格式。
|
||||
|
||||
### Requirement: Per-agent Matrix thread
|
||||
**Reason**: Orchestrator 不了解任何聊天平台概念。展示方式由各 Agent 根据平台能力决定。
|
||||
**Migration**: Agent 通过 `GET /api/v1/tasks?agent_id=xxx` 获取任务历史,自行选择展示方式。
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Task list API endpoint
|
||||
Orchestrator SHALL 提供 `GET /api/v1/tasks` 端点,返回任务列表的结构化 JSON。
|
||||
|
||||
#### Scenario: List all tasks
|
||||
- **WHEN** 发送 `GET /api/v1/tasks`
|
||||
- **THEN** SHALL 返回 JSON 数组,每项包含:task_id, source, task_type, priority, status, assigned_agent_id, retry_count, max_retries, created_at, assigned_at, started_at, completed_at
|
||||
|
||||
#### Scenario: Filter by status
|
||||
- **WHEN** 发送 `GET /api/v1/tasks?status=running`
|
||||
- **THEN** SHALL 仅返回 status 为 `running` 的任务
|
||||
|
||||
#### Scenario: Filter by agent
|
||||
- **WHEN** 发送 `GET /api/v1/tasks?agent_id=worker-03`
|
||||
- **THEN** SHALL 仅返回 assigned_agent_id 为 `worker-03` 的任务
|
||||
|
||||
### Requirement: Task retry API endpoint
|
||||
Orchestrator SHALL 提供 `POST /api/v1/tasks/{task_id}/retry` 端点。
|
||||
|
||||
#### Scenario: Retry a failed task
|
||||
- **WHEN** 发送 `POST /api/v1/tasks/org/repo#42/retry`
|
||||
- **AND** 任务当前状态为 `failed` 或 `agent_lost`
|
||||
- **THEN** SHALL 将任务状态转换为 `assigned`,返回更新后的任务 JSON
|
||||
|
||||
#### Scenario: Retry a non-retryable task
|
||||
- **WHEN** 发送 `POST /api/v1/tasks/org/repo#42/retry`
|
||||
- **AND** 任务当前状态不是 `failed` 或 `agent_lost`
|
||||
- **THEN** SHALL 返回 400 错误,说明任务不在可重试状态
|
||||
22
openspec/changes/chatops-architecture-revision/tasks.md
Normal file
22
openspec/changes/chatops-architecture-revision/tasks.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
## 1. 移除 Matrix bot 和通知格式化代码
|
||||
|
||||
- [ ] 1.1 删除 `src/integrations/matrix/` 目录
|
||||
- [ ] 1.2 从 `src/integrations/mod.rs` 移除 `pub mod matrix;`
|
||||
- [ ] 1.3 从 `src/main.rs` 移除 Matrix bot 启动逻辑
|
||||
- [ ] 1.4 从 `Cargo.toml` 移除 `matrix-sdk` 依赖
|
||||
- [ ] 1.5 从 `config.example.toml` 移除 `[matrix]` section
|
||||
- [ ] 1.6 从 `src/config.rs` 移除 `MatrixConfig` struct 及相关字段
|
||||
- [ ] 1.7 删除通知格式化函数和命令解析代码(如已从 matrix 模块导出)
|
||||
|
||||
## 2. 新增 HTTP API 端点
|
||||
|
||||
- [ ] 2.1 实现 `GET /api/v1/tasks`:返回任务列表 JSON,支持 `status` 和 `agent_id` 查询参数过滤
|
||||
- [ ] 2.2 实现 `POST /api/v1/tasks/{task_id}/retry`:对 failed/agent_lost 任务触发重新入队,非可重试状态返回 400
|
||||
- [ ] 2.3 在 EventStore 中添加 `list_tasks(status: Option<&str>, agent_id: Option<&str>)` 查询方法
|
||||
- [ ] 2.4 在 `src/main.rs` 注册新路由
|
||||
|
||||
## 3. 测试与验证
|
||||
|
||||
- [ ] 3.1 `cargo check` 通过(无 matrix-sdk 依赖)
|
||||
- [ ] 3.2 `cargo test` 全部通过(移除 matrix 相关测试,新增 API 端点测试)
|
||||
- [ ] 3.3 新增 API 端点测试:任务列表过滤、重试成功、重试失败场景
|
||||
Loading…
Add table
Add a link
Reference in a new issue