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.
41 lines
2.4 KiB
Markdown
41 lines
2.4 KiB
Markdown
## 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 调用方式
|