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.
65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
## Context
|
||
|
||
agent-fleet 核心功能已经实现并部署到 arm0 上运行。但没有任何 Agent 知道怎么用它。项目的可用性完全取决于 Agent 能否正确接入。
|
||
|
||
需要两个交付物：
|
||
1. **API 参考文档**：给 Agent 看的 HTTP API 手册
|
||
2. **通用 Skill**：遵循标准 skill 规范的能力描述，不绑定特定平台
|
||
|
||
关键约束：Skill 必须是平台无关的。承担 Team Leader 角色的不一定是 OpenClaw，Codex、Claude Code、OpenCode、Hermes Agent 都可能是调度者。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 提供完整、准确、可直接使用的 API 参考文档
|
||
- 提供通用 Skill，任何 Agent 加载后就知道如何与 agent-fleet 交互
|
||
- 覆盖两种执行模式（ssh_cli + http_pull）的完整工作流
|
||
- 覆盖 Forgejo 集成的 Git 工作流
|
||
|
||
**Non-Goals:**
|
||
- 不写人类运维文档（部署、配置、排障）→ 这是另一个 change
|
||
- 不写特定平台的集成脚本（如 OpenClaw skill 的安装脚本）
|
||
- 不实现 SDK 或客户端库
|
||
|
||
## Decisions
|
||
|
||
### Decision 1: 通用 Skill 规范，不绑定平台
|
||
|
||
**选择**: Skill 使用标准 YAML frontmatter + Markdown body 格式
|
||
|
||
**理由**:
|
||
- 所有主流 Agent 平台都支持这种格式（OpenClaw、Claude Code、Codex CLI、OpenCode）
|
||
- 不包含任何平台特定语法，Agent 自行转换
|
||
- curl 格式是通用语言，所有 Agent 都能理解
|
||
|
||
**替代方案**:
|
||
- OpenClaw 专用 skill：限制了使用范围
|
||
- 多平台各自写：重复劳动，容易不一致
|
||
|
||
### Decision 2: 文档放在 repo 内
|
||
|
||
**选择**: `docs/` 目录放 API 参考和接入指南，`skill/` 目录放 SKILL.md
|
||
|
||
**理由**:
|
||
- 与代码同仓库，版本一致
|
||
- Agent 可以通过 Forgejo 直接读取文档
|
||
- Skill 可以被各平台 fork 或 symlink
|
||
|
||
### Decision 3: 文档从代码自动生成 + 手动补充
|
||
|
||
**选择**: API 端点列表手动维护（Phase 1），后续考虑从代码注释自动生成
|
||
|
||
**理由**:
|
||
- Phase 1 端点数量有限（~12 个），手动维护成本低
|
||
- 自动生成需要额外工具链（如 `utoipa`），Phase 1 不值得投入
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[文档过时] 代码变更后文档可能不一致** → 文档与代码同仓库，PR review 时检查
|
||
- **[Skill 通用性限制] 通用意味着不能利用平台特性** → 通用是正确选择，平台特定优化由各 Agent 自行处理
|
||
|
||
## Open Questions
|
||
|
||
_(resolved)_
|
||
|
||
- ~~Skill 是否需要包含多语言版本（中/英）？~~ → 全部使用英文。原因：LLM 训练语料以英文为主，英文更 token-efficient、语义歧义更小。Skill 的受众是 Agent 不是人类。
|