agent-fleet/openspec/changes/agent-fleet-platform/proposal.md at 2658a747303fac6d201075ed7e815bcccf18f2ac

Zer4tul aabd52ed52 init: OpenSpec project scaffolding with proposal, design, specs, tasks

- 7 capabilities: agent-registry, task-router, receipt-protocol,
  forgejo-integration, matrix-chatops, agent-adapter, orchestrator-core
- Tech stack: Rust + axum + zigbuild (single binary)
- Forgejo as task source of truth
- Matrix as real-time ChatOps layer
- Adapter pattern for multi-agent type support

2026-05-11 14:37:43 +08:00

3.4 KiB

Raw Blame History

Why

多台机器上运行着不同类型的 AI Agent（OpenClaw、Claude Code、Codex、Hermes Agent 等），目前缺乏统一的跨机任务编排与协同机制。Agent 之间只能靠人工传递上下文，无法自动分发任务、追踪进度、回写结果。需要一个 agent-fleet platform，让任意类型的 Agent 通过统一的协议加入舰队，接收任务、汇报状态、协同完成复杂工程。

What Changes

引入 Git 仓库（Forgejo）作为任务事实来源：Issue = 任务单元，PR = 交付物，Label/Milestone = 分类与排期
引入实时协同层：Matrix 作为 ChatOps 通道，Agent 状态变更、任务分配、完成通知等通过 Matrix 房间实时推送
建立 Agent Registry：每台机器上的 Agent 启动时向 Registry 注册（类型、能力、负载），支持动态发现与路由
建立 Task Router：Orchestrator 根据 Issue 类型、Agent 能力、负载状态，自动将任务路由到合适的 Agent
建立结构化 Receipt 协议：Agent 完成工作后回写结构化 receipt（Issue comment / PR / Matrix 通知），系统不信任模型口头声明
支持多 Agent 类型：OpenClaw、Claude Code、Codex CLI、Hermes Agent、任意 ACP-compatible agent，只要能读写 Git repo 并发 Matrix 消息即可加入
支持 hooks/webhook：Forgejo webhook → 路由到编排层 → 触发 Agent 执行

Capabilities

New Capabilities

agent-registry: Agent 注册、心跳、能力声明、动态发现。每台机器上的 Agent 启动时注册自身（类型、hostname、能力标签、当前负载），Orchestrator 据此做任务路由
task-router: 任务解析与分发。从 Forgejo Issue/PR 事件中解析任务需求，匹配 Agent 能力与负载，生成执行指令并投递
receipt-protocol: 结构化完成回执。Agent 完成工作后必须回写结构化 receipt（Issue comment / PR / Matrix 通知），系统据此判定完成状态，不依赖模型口头声明
forgejo-integration: 与 Forgejo 的双向集成。监听 Issue/PR webhook 事件；Agent 执行完成后回写 comment、创建 PR、更新 label/milestone
matrix-chatops: Matrix 实时协同层。Agent 状态变更、任务分配、完成通知、人类审批等通过 Matrix 房间流转；支持 slash command 触发编排操作
agent-adapter: 多类型 Agent 适配层。定义统一 adapter 接口，各类型 Agent（OpenClaw、Claude Code、Codex CLI、Hermes Agent、ACP agent）实现自己的 adapter，接入统一编排
orchestrator-core: 编排核心。管理任务生命周期（created → assigned → running → completed/failed），调度 Agent，处理超时/重试/升级，维护全局状态

Modified Capabilities

（初始项目，无既有 capability 需修改）

Impact

新系统：需要部署 Forgejo 实例 + Matrix homeserver（或复用现有）
网络：各机器需要能访问 Forgejo API（HTTP）、Matrix federation（HTTPS）、Orchestrator API（HTTP/WebSocket）
Agent 端：每种 Agent 需要实现 adapter，最小要求：能读 Git repo、能调用 Forgejo API 写 comment/PR、能发 Matrix 消息
依赖：Forgejo（Git + Issue + PR + webhook）、Matrix（实时消息）、Node.js/Python（Orchestrator runtime）
运维：需要 monitor Agent 心跳、任务超时、Forgejo webhook 健康检查

3.4 KiB Raw Blame History Unescape Escape

Why