## 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 健康检查