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
4.7 KiB
4.7 KiB
1. 项目脚手架与基础设施
- 1.1 初始化 Node.js 项目：package.json、tsconfig.json、ESLint、Vitest
- 1.2 搭建项目目录结构：src/core、src/adapters、src/integrations、src/api
- 1.3 部署 Forgejo 实例（WSL2 或 Docker），创建初始 repo 和 webhook token
- 1.4 配置 Matrix bot 账号（复用现有 @jeeves:0x08.org 或新建专用 bot）
- 1.5 编写 config.toml schema 和示例配置文件
2. Orchestrator Core
- 2.1 实现数据模型：Agent、Task、Receipt、Artifact、TaskEvent 类型定义
- 2.2 实现 Event Store：SQLite append-only event log，写入和查询接口
- 2.3 实现 Task 状态机：created → assigned → running → completed/failed/agent_lost/cancelled
- 2.4 实现全局任务队列：按优先级排序，支持入队/出队/重新入队
- 2.5 实现任务超时检测：定时扫描 running 任务，超时标记为 failed
- 2.6 实现重试策略：可配置 max_retries + 退避间隔，自动重试 transient failure
- 2.7 编写 Orchestrator Core 单元测试
3. Agent Registry
- 3.1 实现
POST /api/v1/agents/register：Agent 注册，支持重复注册更新 - 3.2 实现
POST /api/v1/agents/heartbeat：心跳更新，记录 last_heartbeat_at - 3.3 实现
POST /api/v1/agents/deregister：注销，重新入队该 Agent 的 running 任务 - 3.4 实现
GET /api/v1/agents：查询 Agent 列表，支持 capability 和 status 过滤 - 3.5 实现心跳超时检测：后台定时扫描，3 次超时标记 offline，触发 agent_lost
- 3.6 编写 Agent Registry 单元测试
4. Forgejo Integration
- 4.1 实现 Forgejo API client：Issue CRUD、Comment、Label、PR、Webhook 验证
- 4.2 实现
POST /api/v1/webhooks/forgejo：接收 Forgejo webhook，验证签名，解析事件 - 4.3 实现 Issue → Task 转换：解析 label 推断 type/priority，创建 Task 对象
- 4.4 实现 Task 状态 → Issue label 同步：status:todo/doing/done，assignee 更新
- 4.5 实现 Receipt → Issue comment 回写：结构化 comment（emoji + summary + artifact links）
- 4.6 实现 Reconciliation（对账）：定期轮询 Forgejo Issue，弥补 webhook 丢失
- 4.7 编写 Forgejo Integration 单元测试和集成测试
5. Matrix ChatOps
- 5.1 实现 Matrix bot 连接：使用 matrix-bot-sdk，连接 0x08.org homeserver
- 5.2 实现
/fleet statusslash command：展示所有 Agent 状态 - 5.3 实现
/assign <agent> <issue>slash command：手动分配任务 - 5.4 实现
/retry <issue>slash command：重新入队失败任务 - 5.5 实现通知推送：task assigned、completed、failed、agent offline 等事件推送到协同房间
- 5.6 实现 per-agent thread：每个 Agent 的执行日志发到独立 thread/topic
- 5.7 编写 Matrix ChatOps 单元测试
6. Receipt Protocol
- 6.1 实现
POST /api/v1/receipts：接收 Agent 提交的 receipt - 6.2 实现 receipt validation：验证 PR 是否存在（Forgejo API 查询）、commit 是否包含修改
- 6.3 实现 no-trust 检查：任务只在 receipt 验证通过后才变更为 completed
- 6.4 编写 Receipt Protocol 单元测试
7. Agent Adapter Interface
- 7.1 定义 adapter interface TypeScript 类型：register/heartbeat/execute/submit_receipt/deregister
- 7.2 实现 adapter 配置加载：从 config.toml 读取各 Agent 实例的 adapter 类型和参数
- 7.3 实现 adapter health check：CLI 检查、API 可达性检查
- 7.4 实现 adapter runner：管理 adapter 生命周期（启动、心跳、停止）
8. Claude Code Adapter（第一个具体实现）
- 8.1 实现 Claude Code adapter：spawn
claude -p --output-format json，注入 task prompt - 8.2 解析 Claude Code JSON 输出为 receipt（提取 PR、文件修改、summary）
- 8.3 实现 workspace 管理：为每个任务创建/复用 git worktree
- 8.4 编写 Claude Code adapter 集成测试
9. Codex CLI Adapter（第二个具体实现）
- 9.1 实现 Codex adapter：spawn
codex exec --json，注入 task prompt - 9.2 解析 Codex JSON 输出为 receipt
- 9.3 实现 Codex session resume（可选）
- 9.4 编写 Codex adapter 集成测试
10. 端到端验证
- 10.1 部署完整系统：Forgejo + Orchestrator + Matrix bot + 1 个 Claude Code Agent
- 10.2 端到端测试：创建 Issue → webhook → 任务创建 → Agent 分配 → 执行 → Receipt → Issue comment → Matrix 通知
- 10.3 端到端测试：Agent 离线 → 心跳超时 → 任务 agent_lost → 重新入队
- 10.4 端到端测试：任务超时 → 自动 failed → Matrix 通知
- 10.5 编写运维文档：部署、配置、排障