docs: 补全 Agent 开发、Runtime SDK、Scheduler API 与 Daemon 集成文档

[kingfs]

背景

当前项目已经具备比较丰富的 CLI、声明式 YAML、Guest Runtime、Scheduler，以及完整的 daemon Connect RPC 控制面。但从外部用户和集成开发者视角看，官方站点 https://agent-compose.ai/ 的文档主要覆盖产品介绍、快速开始、CLI 和 YAML 配置，尚未完整呈现项目已经提供的开发与集成能力。

目前相关信息分散在 README、docs/pages、runtime 包内 README、docs/design、examples、proto 源码和测试中。维护者可以从源码还原契约，但外部开发者很难建立一条从入门到生产集成的完整路径。

建议将官方文档按“使用产品、在平台上开发、集成 daemon”三个交接面系统补全，并明确哪些接口是稳定的公开契约。

建议补充的文档

1. 开发一个可运行的 Agent

提供端到端教程，而不只是 YAML 字段参考：

• 创建 workspace 和脚本；
• 声明 agent、provider、model、image、env、skills、MCP、volume；
• 选择或构建 Guest Image；
• 启动 project 和 run；
• 查看日志、事件、artifact 和失败原因；
• 本地验证、调试和生产部署建议。

同时明确三种 JavaScript 接口的边界：

• Guest Runtime SDK：运行在 sandbox 内；
• Scheduler JavaScript API：运行在 daemon 的 QuickJS 环境；
• Daemon Client API：供外部系统通过 Connect RPC 调用。

2. Guest Runtime JavaScript SDK

将 runtime/agent-compose-runtime-sdk/README.md 升级为官网正式、双语文档，并补充：

• 安装、离线安装和版本兼容；
• 完整 API reference，包括 exec、shell、agent、llm、env、log、report、ssh；
• TypeScript 类型、输入、返回值和错误；
• 结构化输出与 Zod/JSON Schema；
• runtime paths、环境变量、artifact；
• timeout、取消、输出截断、密钥处理和安全建议；
• 一个可以直接运行的完整项目。

当前包内 README 已经覆盖多数核心 API，但不在官网发布导航中、缺少中文版本，也未完整覆盖源码导出的能力，例如 SSH API。

3. Scheduler JavaScript API

现有 YAML 手册较好地说明了声明式 cron、interval、timeout 和 event trigger，但脚本开发只有少量示例。建议增加正式 Scheduler API 手册，覆盖：

• QuickJS 执行模型、支持的 JavaScript 能力和限制；
• interval、timeout、cron、on 及 trigger ID；
• agent、llm、exec、shell、log；
• event.publish；
• state.get、state.set、state.delete；
• sandbox 生命周期 API；
• main(payload) 和 trigger callback payload；
• schema/结构化输出；
• validation 与 execution 阶段差异；
• sandbox policy、并发、timeout、取消、错误传播；
• 测试、调试及完整 workflow 示例。

4. Daemon 对外集成与 Connect RPC API

CLI 和 Web UI 已经通过 Connect RPC 调用 daemon，Connect RPC 也是当前控制面的正式传输边界，但官网缺少外部集成手册。建议新增：

• daemon API 总览以及 control plane/data plane 边界；
• protobuf/Connect protocol、base URL 和 procedure 规则；
• Bearer Token、Unix socket、HTTP/HTTPS 和反向代理；
• Project、Revision、Agent、Scheduler、Run、Sandbox、Event、Artifact 资源模型；
• TypeScript/Connect-Web、Go、Python，以及可行时原始 HTTP 调用示例；
• ValidateProject、ApplyProject、StartAgentRun、StreamAgentRun、AttachAgentRun、StopRun 的完整流程；
• unary、server streaming、bidirectional streaming 的连接、取消、重连和终态语义；
• resource ID、短 ID、ResolveID、pagination/cursor；
• Connect error code、可重试性、幂等性和兼容性；
• Webhook/Event、Workspace File API、Jupyter Proxy、Runtime LLM Facade 等非通用控制面边界。

建议从 proto descriptor 自动生成 service、method、message、field、enum 和 streaming 类型的 API reference，避免文档与实现漂移。

如果希望降低外部集成成本，也可以考虑正式发布 daemon client SDK，并与 Guest Runtime SDK 使用清晰不同的包名和定位。

5. 官网信息架构与可发现性

建议官网形成以下一级入口：

1. 使用 agent-compose：安装、产品概念、YAML、CLI、部署运维；
2. 在 agent-compose 上开发：Agent 教程、Runtime SDK、Scheduler API、Guest Image、MCP/Skills；
3. 集成 agent-compose：Daemon API、认证、资源模型、Connect RPC、streaming、webhook、API reference。

官网导航应直接链接这些正式手册，而不是要求用户从仓库 design 文档或源码中自行发现。

建议的验收标准

• 中文和英文文档保持同步；
• Runtime SDK、Scheduler API、Daemon API 都进入官网导航；
• 三类 JavaScript/客户端执行环境的边界被明确说明；
• 每类接口至少有一个从零开始、可直接运行的示例；
• protobuf/Connect reference 可以由 proto 自动生成或由 CI 校验；
• 文档明确稳定接口、内部接口和版本兼容策略；
• 认证、错误、streaming、取消、重试和安全语义有独立说明；
• docs build/CI 能检查链接、双语页面和公开 API 覆盖。

价值

补齐这些文档可以让 agent-compose 从“CLI 功能丰富、源码契约完整的项目”进一步成为“外部团队可以独立开发 Agent、编写 Scheduler、集成 daemon 的平台”，同时减少维护者回答重复集成问题以及外部用户依赖源码推断行为的成本。

[agent-compose-coder]

Issue triage

Classification

• Type: unresolved (conflicting existing labels)
• Priority: pending
• Priority basis: This is a broad documentation enhancement covering several important developer and integration surfaces. It likely affects many external adopters and increases onboarding and support costs, but the existing README files, examples, design documents, source definitions, and tests provide a workaround. No outage, security impact, data loss, blocked core flow, SLA risk, or confirmed release-blocking condition is reported, so urgency appears moderate rather than critical.

Information needed

• Documentation roadmap or target milestone
• Usage data showing how many users need the undocumented integration surfaces
• Known support incidents or integration failures caused by the documentation gaps
• Whether the documented APIs are stable enough to publish as public contracts
• Whether this documentation work blocks a planned release

Maintainer next step

• When this Issue is ready for implementation, a maintainer can add the agent:ready label. The Agent will open a Draft Pull Request and will not merge it automatically.
• Add skip-triage to opt out of automated triage.

This is an automated initial assessment based on the Issue text and related candidates; no repository code was inspected.