agent-fleet/openspec/changes/agent-fleet-platform/specs/agent-registry/spec.md at b1a4d66c1302131a8af73a9aebb88e5e5c2f9320

Zer4tul aabd52ed52 init: OpenSpec project scaffolding with proposal, design, specs, tasks

- 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

2026-05-11 14:37:43 +08:00

2.5 KiB

Raw Blame History

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 列表

2.5 KiB Raw Blame History Unescape Escape