agent-fleet/openspec/changes/agent-onboarding-docs/specs/agent-api-reference/spec.md at d1a746a8cb6da9227b8d2e78c654ac1b1f0e4739

Zer4tul d1a746a8cb docs: add agent API reference, onboarding guide, and universal skill

- docs/agent-api-reference.md (473 lines): complete HTTP API reference for all 12 endpoints
- docs/agent-onboarding-guide.md (272 lines): ssh_cli and http_pull workflows, Forgejo integration
- skill/SKILL.md (281 lines): universal agent skill, platform-agnostic, curl-based examples

All content in English. No code changes.

2026-05-12 14:57:05 +08:00

3 KiB

Raw Blame History

ADDED Requirements

Requirement: Complete HTTP API reference documentation

项目 SHALL 提供完整的 HTTP API 参考文档（docs/agent-api-reference.md），供任何 Agent 阅读。文档 SHALL 覆盖所有公开端点，包含请求/响应格式、错误码、示例。

Scenario: Agent reads API reference to understand available endpoints

WHEN Agent 阅读 docs/agent-api-reference.md
THEN 文档 SHALL 列出所有端点：healthz、agents/register、agents/heartbeat、agents/deregister、agents (GET)、tasks (GET)、tasks/{id} (GET)、tasks/dequeue、tasks/{id}/status、tasks/{id}/retry、tasks/{id}/complete、receipts、webhooks/forgejo
AND 每个端点 SHALL 包含：HTTP 方法、URL、请求体格式、响应格式、错误码、curl 示例

Scenario: Agent checks authentication requirements

WHEN Agent 查看 API 参考的认证部分
THEN 文档 SHALL 说明：http_pull 模式需要 Bearer token（注册时获取），ssh_cli 模式不需要 Agent 认证，webhook 端点需要 HMAC-SHA256 签名

Scenario: Agent understands error responses

WHEN Agent 收到错误响应
THEN 文档 SHALL 列出所有错误码：401 Unauthorized、403 Forbidden、404 Not Found、400 Bad Request、500 Internal Server Error
AND 每个错误码 SHALL 包含触发场景描述

Requirement: Agent onboarding guide

项目 SHALL 提供 Agent 接入指南（docs/agent-onboarding-guide.md），描述两种执行模式的完整工作流程。

Scenario: New agent team leader reads onboarding guide

WHEN 新的 Team Leader Agent（如 Jeeves）阅读 onboarding guide
THEN 文档 SHALL 描述两种执行模式的区别和使用场景：
- ssh_cli：Orchestrator 主动调度，适用于 Codex、Claude Code、OpenCode 等有 CLI 的 Agent
- http_pull：Agent 自主拉取，适用于 OpenClaw/Jeeves、Hermes 等有自己的调度器的 Agent

Scenario: Agent follows ssh_cli workflow

WHEN Agent 按 ssh_cli 模式接入
THEN 文档 SHALL 描述完整流程：配置 host → Agent 安装 CLI → Orchestrator 自动发现 → 任务自动分配和执行 → PR 创建 → webhook 回调

Scenario: Agent follows http_pull workflow

WHEN Agent 按 http_pull 模式接入
THEN 文档 SHALL 描述完整流程：调用 register API → 获取 token → 定期 heartbeat → 调用 dequeue 拉任务 → 执行 → 调用 complete/receipt API

Scenario: Agent understands Forgejo integration

WHEN Agent 阅读 Forgejo 集成部分
THEN 文档 SHALL 描述：Issue 如何变成任务（webhook → label 解析）、任务如何关联 Git 分支（task/{task_id}）、PR 生命周期如何驱动状态更新（opened → review_pending、merged → completed）

Scenario: Agent understands structured prompt format

WHEN ssh_cli 模式的 Agent 需要理解传入的 prompt
THEN 文档 SHALL 描述结构化 prompt 的格式：Task ID、Type、Goal、Constraints、Branch、Expected output、Validation

3 KiB Raw Blame History Unescape Escape