agent-fleet/openspec/changes/agent-onboarding-docs/design.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

2.6 KiB

Raw Blame History

Context

agent-fleet 核心功能已经实现并部署到 arm0 上运行。但没有任何 Agent 知道怎么用它。项目的可用性完全取决于 Agent 能否正确接入。

需要两个交付物：

API 参考文档：给 Agent 看的 HTTP API 手册
通用 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 不是人类。

2.6 KiB Raw Blame History Unescape Escape