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
44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: Agent self-registration
|
||
每台机器上的 Agent 启动时 SHALL 向 Orchestrator Registry 注册自身信息：agent_id、agent_type（openclaw / claude-code / codex-cli / hermes / acp 等）、hostname、capabilities（能力标签列表）、max_concurrency、metadata（版本、工作目录等）。
|
||
|
||
#### Scenario: New agent starts and registers
|
||
- **WHEN** 一个新的 Codex CLI Agent 在 host-worker-02 上启动
|
||
- **THEN** 它 SHALL 调用 `POST /api/v1/agents/register`，Orchestrator 记录该 Agent 信息并返回 agent_id 和 registry token
|
||
|
||
#### Scenario: Duplicate registration with same agent_id
|
||
- **WHEN** 已注册的 Agent 重启后再次注册（相同 agent_id）
|
||
- **THEN** 系统 SHALL 更新该 Agent 的信息（hostname、capabilities 等）而非创建重复条目
|
||
|
||
### Requirement: Agent heartbeat
|
||
已注册的 Agent SHALL 每隔可配置的间隔（默认 60 秒）发送心跳。Orchestrator 据此判定 Agent 是否在线。
|
||
|
||
#### Scenario: Agent sends heartbeat on time
|
||
- **WHEN** Agent 在 60 秒内发送心跳
|
||
- **THEN** Orchestrator 更新 `last_heartbeat_at` 并保持 Agent 状态为 `online`
|
||
|
||
#### Scenario: Agent misses 3 consecutive heartbeats
|
||
- **WHEN** Agent 连续 3 个心跳周期未发送心跳（180 秒）
|
||
- **THEN** Orchestrator SHALL 将该 Agent 状态标记为 `offline`，并将该 Agent 上所有 `running` 状态的任务标记为 `agent_lost`
|
||
|
||
### Requirement: Agent capability declaration
|
||
Agent 注册时 SHALL 声明自己的能力标签（如 `code:typescript`、`code:python`、`review`、`test`、`deploy`、`research`）。Task Router 据此匹配任务。
|
||
|
||
#### Scenario: Task requiring specific capability
|
||
- **WHEN** 一个 Issue 被标记为 `agent:review` 且需要 TypeScript 能力
|
||
- **THEN** Task Router SHALL 只将其分配给声明了 `review` 和 `code:typescript` 能力的在线 Agent
|
||
|
||
### Requirement: Agent graceful deregistration
|
||
Agent 正常关闭时 SHALL 调用 `POST /api/v1/agents/deregister`，Orchestrator 将其标记为 `offline`。
|
||
|
||
#### Scenario: Agent deregisters on shutdown
|
||
- **WHEN** Agent 调用 deregister API
|
||
- **THEN** Orchestrator SHALL 将该 Agent 状态设为 `offline`，该 Agent 上所有 `running` 任务 SHALL 被重新入队
|
||
|
||
### Requirement: Agent list and query
|
||
Orchestrator SHALL 提供 API 查询当前所有注册 Agent 的状态、能力、负载。
|
||
|
||
#### Scenario: Query agents by capability
|
||
- **WHEN** 调用 `GET /api/v1/agents?capability=code:python&status=online`
|
||
- **THEN** 返回所有在线且声明了 `code:python` 能力的 Agent 列表
|