## Context

当前有多台机器（WSL2 workstation、MacBook、可能的云服务器）运行不同类型的 AI Agent：
- **OpenClaw**：Jeeves orchestrator + 多个 sub-agent
- **Claude Code**：本地 CLI 编码
- **Codex CLI**：OpenAI 编码
- **Hermes Agent**：其他类型
- **ACP-compatible agents**：Devin 等

现状：Agent 之间无统一协同机制，任务靠人工传递，进度靠人工追踪，没有结构化的完成验证。

已有基础设施：
- **Matrix**：0x08.org homeserver 已运行
- **Forgejo**：需要部署（建议自建，或用 Gitea 替代）
- 各机器可以互相网络通信

## Goals / Non-Goals

**Goals:**
- 建立统一的 Agent 编排平台，支持任意类型 Agent 加入
- Forgejo Issue/PR 作为任务事实来源，人类和 Agent 共用同一界面
- Matrix 作为实时协同层，提供 ChatOps 和通知
- 结构化 receipt 协议，不信任模型口头声明
- 最小化对现有 Agent 的侵入性（adapter 模式）
- 可扩展：新 Agent 类型只需实现 adapter 即可接入

**Non-Goals:**
- 不做 Agent 自身的改进（Agent 内部行为不在 scope 内）
- 不做 IDE 集成（VS Code / JetBrains 插件）
- 不做 LLM provider 管理（使用各 Agent 自己的 provider 配置）
- 不做前端 Web UI（Phase 1 用 Forgejo + Matrix 作为 UI）
- 不替换 cc-connect / cc-telegram-bridge（它们可以作为 adapter 接入）

## Decisions

### Decision 1: Forgejo（而非 Gitea）作为 Git 平台

**选择**: Forgejo

**理由**:
- Forgejo 是 Gitea 的社区 fork，治理更开放
- 内置 CI/CD（Forgejo Actions），未来可扩展
- API 兼容 Gitea，迁移成本低
- 支持 F3 (Friendly Forge Format)，数据可移植

**替代方案**:
- Gitea：更成熟但治理有争议（公司化）
- GitHub：不方便自建，网络可达性差
- GitLab：太重，资源消耗大

### Decision 2: Orchestrator 用 Rust + zigbuild

**选择**: Rust + cargo-zigbuild（交叉编译）

**理由**:
- 内存安全：无 GC、无 data race、无 null pointer
- 单二进制部署：zigbuild 交叉编译，无 libc 兼容性问题
- 性能：原生性能，适合长运行服务
- 类型系统：强类型 + algebraic data types，适合状态机建模
- 生态：reqwest（HTTP）、matrix-sdk（Matrix）、rusqlite（SQLite）、serde（JSON/TOML）
- 交叉编译：cargo-zigbuild 一行命令产出 Linux/macOS/Windows 二进制

**替代方案**:
- TypeScript (Node.js)：开发快但需要运行时，非单二进制
- Go：单二进制但内存安全不如 Rust，交叉编译有 libc 问题

### Decision 3: Agent-Orchestrator 通信用 HTTP API（axum）

**选择**: Agent 通过 HTTP API 与 Orchestrator 通信，Orchestrator 端用 axum 框架

**理由**:
- 跨语言、跨平台：任何 Agent 都能发 HTTP 请求
- 防火墙友好
- 与 Forgejo webhook 统一协议栈
- axum 是 Rust 生态最成熟的 async HTTP 框架

**替代方案**:
- WebSocket：实时性好但复杂度高，重连逻辑麻烦
- gRPC：性能好但 Agent 端实现门槛高
- Message Queue（NATS/Redis）：增加基础设施依赖

### Decision 4: Event sourcing 作为审计基础（rusqlite）

**选择**: 所有状态变更作为不可变事件 append 到 SQLite，通过 rusqlite 访问

**理由**:
- 完整审计追踪
- 可重放
- 轻量，不需要外部数据库，适合单二进制打包
- rusqlite 是 Rust 生态最成熟的 SQLite 绑定
- 适合中小规模 Agent 舰队（< 100 agents）

**替代方案**:
- PostgreSQL：强大但引入运维复杂度，破坏单二进制部署
- JSON 文件：简单但无查询能力
- 只记录当前状态：无法审计

### Decision 5: Adapter 模式接入多类型 Agent

**选择**: 定义统一 adapter interface，各 Agent 实现自己的 adapter

**理由**:
- 最小侵入：Agent 不需要改内部逻辑
- 可扩展：新 Agent 类型只需写 adapter
- 隔离：adapter 故障不影响 Orchestrator

**adapter 执行方式**:
- Claude Code adapter：spawn `claude -p` 子进程
- Codex adapter：spawn `codex exec` 子进程
- OpenClaw adapter：调用 gateway HTTP API
- ACP adapter：通过 ACP 协议 WebSocket
- Shell adapter：执行任意 shell 命令（最通用）

### Decision 6: 配置用 TOML

**选择**: TOML（与 cc-connect 一致）

**理由**:
- 人类可读性好
- 类型比 YAML 更明确
- cc-connect 已验证

## Risks / Trade-offs

### Risk: Agent 执行环境差异
不同机器上的 Agent 运行环境（OS、依赖、权限）不同，可能导致同一任务在不同 Agent 上行为不一致。
→ **Mitigation**: adapter 负责环境检查；任务描述尽量环境无关；receipt 验证在 Forgejo 侧（与执行环境解耦）。

### Risk: Orchestrator 单点故障
Orchestrator 挂了，整个舰队停摆。
→ **Mitigation**: Phase 1 接受单点，Orchestrator 做到无状态（状态在 SQLite + Forgejo），快速重启恢复。

### Risk: Forgejo webhook 延迟或丢失
网络抖动可能导致 webhook 丢失。
→ **Mitigation**: Orchestrator 定期轮询 Forgejo 做对账（reconciliation），弥补 webhook 丢失。

### Risk: Agent 心跳风暴
大量 Agent 同时发心跳可能导致 Orchestrator 负载过高。
→ **Mitigation**: 心跳间隔可配置（默认 60s）；Orchestrator 做好限流。

### Trade-off: 简单性 vs 实时性
选择 HTTP 而非 WebSocket/MQ 意味着实时性稍差。
→ 对于任务编排场景，秒级延迟完全可接受。Matrix 通知提供实时感。

## Architecture Overview

```
┌─────────────┐     webhook      ┌──────────────────┐
│   Forgejo    │ ───────────────→ │   Orchestrator    │
│  (Git+Issue) │ ←─── API ────── │   (Node.js)       │
└─────────────┘                  │                   │
                                 │  - Agent Registry │
┌─────────────┐     HTTP API     │  - Task Router    │
│   Matrix     │ ←──────────────→│  - Event Log      │
│  (ChatOps)   │                  │  - Receipt Validator│
└─────────────┘                  └────────┬──────────┘
                                          │ HTTP API
                      ┌───────────────────┼───────────────────┐
                      │                   │                   │
               ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
               │  Adapter A  │     │  Adapter B  │     │  Adapter C  │
               │ Claude Code │     │  Codex CLI  │     │  OpenClaw   │
               │  (host-01)  │     │  (host-02)  │     │  (host-03)  │
               └─────────────┘     └─────────────┘     └─────────────┘
```

## Data Model (Core)

```typescript
interface Agent {
  agent_id: string;
  agent_type: "openclaw" | "claude-code" | "codex-cli" | "hermes" | "acp" | "shell";
  hostname: string;
  capabilities: string[];
  max_concurrency: number;
  current_tasks: number;
  status: "online" | "offline" | "draining";
  last_heartbeat_at: string; // ISO 8601
  registered_at: string;
  metadata: Record<string, string>;
}

interface Task {
  task_id: string;
  source: string; // "forgejo:<repo>#<issue>"
  type: string;   // from label: "code", "review", "test", "deploy", "research"
  priority: "low" | "normal" | "high" | "urgent";
  status: TaskStatus;
  assigned_agent_id?: string;
  requirements: string; // Issue body
  labels: string[];
  created_at: string;
  assigned_at?: string;
  started_at?: string;
  completed_at?: string;
  retry_count: number;
  max_retries: number;
  timeout_seconds: number;
}

type TaskStatus = "created" | "assigned" | "running" | "completed" | "failed" | "agent_lost" | "cancelled";

interface Receipt {
  task_id: string;
  agent_id: string;
  status: "completed" | "failed" | "partial";
  duration_seconds: number;
  summary: string;
  artifacts: Artifact[];
  error?: string;
}

interface Artifact {
  type: "pr" | "commit" | "file" | "comment" | "url";
  url?: string;
  path?: string;
  description?: string;
}

interface TaskEvent {
  event_id: string;
  task_id: string;
  event_type: string; // "created", "assigned", "started", "receipt_submitted", "completed", "failed", ...
  agent_id?: string;
  timestamp: string;
  payload: Record<string, unknown>;
}
```

## Migration Plan

1. **部署 Forgejo**：自建实例，配置 webhook
2. **部署 Orchestrator**：Node.js 进程，连接 Forgejo + Matrix
3. **实现 Claude Code adapter**：第一个 adapter，验证端到端流程
4. **实现 Codex adapter**：第二个 adapter
5. **实现 OpenClaw adapter**：第三个 adapter（可选 Phase 2）
6. **逐步迁移现有任务到 Forgejo Issue**

### Rollback
- Orchestrator 可随时停止，不影响 Forgejo 和 Matrix
- Agent 可独立运行（只是没有编排）
- 所有状态在 Forgejo Issue + SQLite，可手动接管

## Open Questions

1. ~~**Forgejo 部署位置**~~：✅ 已部署在 arm0.0x08.org，域名 git.0x08.org
2. **Orchestrator 部署位置**：TBD（arm0 / WSL2 / 独立机器）
3. **Agent 工作目录策略**：每个任务 clone 新 worktree 还是共享 workspace？
4. **权限模型**：Issue comment 中的 `/assign` 命令是否需要权限控制？
5. **cc-connect 集成**：✅ 放 Phase 2