Zer4tul
aabd52ed52
- 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
37 lines
3.4 KiB
Markdown
37 lines
3.4 KiB
Markdown
## 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 健康检查
|