Zer4tul
d1a746a8cb
- 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.
43 lines
3 KiB
Markdown
43 lines
3 KiB
Markdown
## 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
|