CloudAgent 试用指引

CodeBuddy CloudAgent（内部代号 AgentOS）是核心 Agentic 能力 + 企业级云端沙箱运行时，第三方应用通过 REST API 创建并管理 AI Agent 沙箱，再以 ACP（Agent Client Protocol）协议与沙箱内的 Agent 实时对话。

本仓库是面向集成方的端到端示例，包含两条独立的体验路径：

入口	形态	适合
🖥️ Dashboard 控制台	React + Vite Web 应用	想直观看到 Runtime / Session / ACP 全貌
🐍 Python Demo 脚本	7 个独立 CLI 场景	想最快验证 API、写自动化集成

两套代码使用同一组平台 API（默认 https://www.codebuddy.cn），可独立运行，互不依赖。

声明：Dashboard 子项目是面向 CloudAgent 公开 ACP 协议的独立开源 Demo，非腾讯/CodeBuddy 官方产品，亦未经其背书。

🚀 在线体验

直接打开 **http://120.79.95.108/**，按提示填入 API Key 即可使用。Key 仅存浏览器 localStorage，不上传任何服务器；所有 API 调用从浏览器经反向代理直发 CloudAgent 平台，按 Key 自身额度计费。

获取 API Key（二选一）：

类型	适用场景	格式	获取地址
个人账号	快速测试	`ck_xxx.yyy`	https://www.codebuddy.cn/profile/keys
团队账号	企业正式使用	`pt_xxx.yyy`	企业管理后台 → 开放与集成（暂未开放）

🖥️ Dashboard 控制台（本地启动）

cd dashboard-v2
npm install

# 可选：复制 .env.example 为 .env.local，填入专家/Skill CDN 地址
# cp .env.example .env.local

npm run dev          # 开发服务器：http://localhost:5173
npm run build        # 生产构建（tsc -b && vite build）
npm run lint         # ESLint
npm run preview      # 预览生产构建

启动后右上角点 API Key 胶囊填入 Key 即可使用。

主要能力

页面	能力
概览	Runtime 统计、快速创建、近期活动
Runtime 管理	列表 + 详情（Sessions / Checkpoints / Versions / Releases / Manifest / ACP 对话）
创建 Runtime	简单模式（名称 + 提示词）/ 高级模式（完整 Manifest JSON）
ACP 工作台	全屏沉浸式对话；流式输出、思考过程、工具调用、Plan 模式可视化
专家中心	从外部 manifest 加载专家人设，召唤后以专家口吻对话
设置	API Key / Base URL / 自动刷新 / 主题切换

专家、Skill、MCP 资源不内置，需自备外部清单 + 资源（详见 dashboard-v2/README.md）：

VITE_EXPERT_MANIFEST_BASE — 专家清单根路径

VITE_SKILLS_RELEASE_BASE — Skill zip 包根路径（GitHub Release / 对象存储）

VITE_MCP_RELEASE_BASE — MCP 配置根路径（可选，回退到上一项）

部署

# 见 dashboard-v2/deploy.sh 与 README，最小方案为 Nginx 反代
cd dashboard-v2
export SERVER_IP=1.2.3.4 SERVER_USER=root \
       REMOTE_PATH=/data/app/CloudAgentDashboard \
       UPSTREAM_HOST=www.codebuddy.cn
bash deploy.sh

Nginx 的 /v2/ 反代是为了绕开浏览器 CORS（平台默认不对浏览器开放跨域）。

🐍 Python Demo 脚本（命令行）

环境

pip install requests sseclient-py

export E2E_API_KEY="ck_xxx.yyy"                      # 必填
export E2E_BASE_URL="https://www.codebuddy.cn"       # 可选，默认正式环境
export E2E_SOURCE_APP="agentos-demo"                 # 可选，仅作来源标记

运行

python3 demo_1_full_flow.py            # 单场景
python3 run_all.py                     # 全部 7 场景 + 汇总报告
python3 run_all.py 1 2 4               # 指定场景
python3 run_all.py --list              # 列出可选场景

run_all.py 用子进程串行执行各 demo，按返回码汇总通过/失败；单场景超时 600 秒。

7 个场景

#	场景	脚本	核心覆盖
1	基础全流程	`demo_1_full_flow.py`	创建 Runtime → SSE → ACP 握手 → `session/new` → `set_mode` → `prompt`，8 步走通
2	Manifest 配置注入	`demo_2_manifest.py`	rules/skills/mcp/secrets/envs 注入；`${CODEBUDDY_API_KEY}` 占位符；envd 文件读写
3	快照管理	`demo_3_version_checkpoint.py`	Version × 6 + Checkpoint × 6 = 12 个接口；`restore` 后状态校验
4	Session + ACP 扩展	`demo_4_session_acp.py`	`session/new` 幂等性、`session/load` 上下文恢复、`set_model`、`cancel`、SSE 重连
5	Webhook 回调	`demo_5_webhook.py`	平台 Hook 事件接收、HMAC-SHA256 签名校验；本地 HTTP 服务器收包（事件清单见 `api-reference.md §9`）
6	产物发布	`demo_6_artifact_release.py`	Static/Web 两种 `artifactType`；列表、取消、域名校验
7	高级运维	`demo_7_advanced_runtime.py`	Runtime Fork、`sandboxSpec`、SSE `Last-Event-ID` 重连

常用 CLI 参数

绝大多数 demo 都支持：

--no-cleanup — 不删 Runtime，便于对照排查
--prompt "..." — 自定义首条用户消息（demo 1/2/6）
--json — 末尾以单行 JSON 输出汇总（status / total / passed / failed / items / meta），便于外部脚本消费。目前 demo 3/4/5/6/7 + run_all.py 支持，schema 详见 lib/results.py 顶部 docstring

特殊参数：

脚本	参数	用途
`demo_2_manifest.py`	`--manifest-file fixtures/manifest-full.json`	加载完整 manifest（含 27 个 skill / 1 个 rule / 1 个 mcp）
`demo_2_manifest.py`	`--write-text "/path:content"` / `--upload-file`	验证 envd 文件写入
`demo_2_manifest.py`	`--no-manifest`	创建纯净沙箱
`demo_5_webhook.py`	`--webhook-url https://xxx.ngrok.io/webhook`	真实模式（无此参数走"模拟模式"，仅校验签名算法）
`demo_5_webhook.py`	`--webhook-port 9876` / `--webhook-secret`	本地端口、签名密钥

Webhook 真实模式需要公网可达回调 URL：
# 终端 1
ngrok http 9876
# 终端 2
python3 demo_5_webhook.py --webhook-url https://xxxx.ngrok.io/webhook

📁 项目结构

AgentOS-demo/
├── README.md                            ← 本文件
├── CODEBUDDY.md                         AI Coding Agent 上手指引
├── api-reference.md                     平台 API 参考
├── AgentOS-测试验证方案.md              完整验证方案（场景化）
│
├── lib/                                 🐍 Python 公共库（demo 复用）
│   ├── client.py                        RuntimeClient — Runtime/Session/Checkpoint/Version/Release + envd 文件
│   ├── acp.py                           ACPSession — SSE 长连接 + JSON-RPC + prompt 流处理
│   ├── manifest.py                      ManifestBuilder — 链式构建 agentManifest
│   ├── utils.py                         safe_parse_json（大整数 ID 防丢精度）+ 配置读取
│   └── logger.py                        彩色终端输出
│
├── demo_1_full_flow.py … demo_7_advanced_runtime.py   7 个场景脚本
├── run_all.py                           批量执行 + 汇总报告
│
├── fixtures/
│   └── manifest-full.json               完整样本（27 skills + 1 rule + 1 mcp，资源托管在 cnb.cool 外部仓库）
│
└── dashboard-v2/                        🖥️ Web 控制台（独立 npm 项目，独立 README）
    ├── src/
    │   ├── api/        REST 客户端：runtimes / sessions / checkpoints / versions / releases / envd / experts
    │   ├── app/        全局 layout / Header / ApiKeyPill
    │   ├── stores/     zustand：auth / runtimes / chat / experts / skills
    │   ├── hooks/
    │   │   └── useAcpConnection.ts        ⭐ ACP 连接池（跨 React 组件保活，对应 Python lib/acp.py）
    │   ├── pages/      overview / runtimes / workbench / settings
    │   ├── features/   chat / common / experts / mcp / runtimes / skills（按业务切分）
    │   ├── components/ui/  shadcn/ui 基础组件
    │   └── lib/        safe-json / message-storage / time
    ├── docs/           设计 & 部署文档
    ├── e2e-test.py     端到端 API 测试脚本（Python）
    ├── deploy.sh       scp + Nginx reload
    └── skills-release/ git submodule（cloudagent-skills.git）— Skill zip 资源

⚠️ 集成时需要知道的几件事

下列约束读 README 看不出，但写代码会反复踩到：

ACP 协议顺序：必须 SSE 连接 → initialize → session/new → 业务 prompt。顺序错乱拿不到 sessionId。
acpUrl 必须 https://：RuntimeClient 里已自动把 http:// 改写成 https://，自己实现客户端时记得照做。
大整数 ID：runtimeId / sessionId / checkpointId / versionId / releaseId 等都是 16 位以上的纯数字，JS / Python float 会丢精度。lib/utils.safe_parse_json 用正则把这些字段强制成字符串，新增此类字段时记得加进白名单。
1 Runtime = 1 Session（当前平台行为）：同一个 Runtime 下 session/new 始终返回同一个 sessionId，断线重连也是同一个；多 Session 共存能力尚未开放（demo 4 验证了这一行为）。
envd Token 可能过期：write_file / read_file 在 401/403 时会自动刷一次 token 重试；快照恢复后 token 必失效，需要主动 client.envd_token = None 再 get_envd_token()。
Webhook 注册方式：当前 demo 5 通过 metadata.webhook_url 注入仅作示例，最终注册方式以平台 API 文档为准（见 api-reference.md）。

完整运行时约束清单与权威定义：见 api-reference.md 附录 §B（"平台当前已知行为"）。本 README 只摘要常见的几条。

❓ 常见问题

问题	排查方向
Dashboard 白屏	确认 `npm run dev` 已启动，浏览器控制台看错误
Dashboard 列表为空	设置页 API Key 是否已填入
`session/new` 拿不到 `sessionId`	顺序：SSE → Initialize → Session/New
SSE 连接失败	`acpUrl` 必须是 `https://`，检查代理
HTTP 401	检查 API Key 格式与有效性
envd 写入返回 401/403	Token 已失效，置空后重取
Webhook 收不到事件	隧道 URL 是否公网可达；`--webhook-url` 必须是 `https://`