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.
2.4 KiB
2.4 KiB
ADDED Requirements
Requirement: Universal Agent Skill definition
项目 SHALL 提供一个通用 Agent Skill（skill/SKILL.md），遵循标准 skill 规范（YAML frontmatter + Markdown body）。Skill SHALL 不绑定任何特定 Agent 平台（OpenClaw、Claude Code、Codex、OpenCode、Hermes 等均可使用）。
Scenario: Any agent discovers and loads the skill
- WHEN 任意 Agent（Codex、Claude Code、OpenCode、Hermes 等）加载 skill/SKILL.md
- THEN Skill SHALL 包含 YAML frontmatter：
name: agent-fleet-integration，description描述用途和触发条件 - AND Skill body SHALL 使用标准 Markdown 格式（标题、代码块、示例）
Scenario: Skill teaches agent how to interact with agent-fleet
- WHEN Agent 阅读 Skill 内容
- THEN Skill SHALL 包含 Quick Start 部分（最简单的接入示例，3 步以内）
- AND 包含 Instructions 部分（详细的 API 调用流程）
- AND 包含 Examples 部分（每种操作的 curl 示例）
- AND 包含 Guidelines 部分（错误处理、重试策略、认证规则）
Scenario: Skill covers both execution modes
- WHEN Agent 需要选择执行模式
- THEN Skill SHALL 清晰说明 ssh_cli 和 http_pull 的区别
- AND 指导 Agent 如何判断自己应该使用哪种模式：
- 如果有 CLI 且在配置的主机上 → ssh_cli（由 Orchestrator 调度）
- 如果有自己的调度器或不在配置的主机上 → http_pull（自主拉取）
Scenario: Skill includes Forgejo workflow
- WHEN Agent 需要理解 Git 工作流
- THEN Skill SHALL 描述分支命名约定（
task/{task_id}）、PR 创建流程、webhook 触发机制
Scenario: Skill includes error recovery guidance
- WHEN Agent 遇到 API 错误
- THEN Skill SHALL 提供常见错误的处理方式：
- 401 → 检查 token，必要时重新注册
- 404 → 任务可能已完成或不存在
- 409/400 → 检查任务状态是否允许该操作
- 网络错误 → 重试（指数退避）
Scenario: Skill is portable across agent platforms
- WHEN Skill 被不同平台的 Agent 使用
- THEN Skill SHALL 不包含任何平台特定的语法或指令（如 OpenClaw 的
sessions_send、Claude Code 的hooks等） - AND 所有交互通过标准 HTTP 请求描述（curl 格式）
- AND Agent 可根据自身能力将 curl 转换为对应的 HTTP 调用方式