CloudAgent 试用指引

CodeBuddy CloudAgent（内部代号 AgentOS）是核心 Agentic 能力 + 企业级云端沙箱运行时环境，为第三方应用提供通过 API 创建和管理 AI Agent 沙箱的能力。

本仓库提供两种试用方式：

🖥️ Dashboard 控制台（推荐）— 可视化管理 Runtime / Session / ACP 对话
🐍 Python Demo 脚本 — 命令行快速验证所有 API 功能

🖥️ Dashboard 控制台

全功能 Web 管理控制台，支持 Runtime 管理、ACP 实时对话、Checkpoint/Version 快照等。

# 1. 进入目录 & 安装依赖
cd dashboard-v2 && npm install

# 2. 启动开发服务器
npm run dev
# → http://localhost:5174

# 3. 打开浏览器，在「设置」页填入 API Key 即可使用

Dashboard 功能

页面	功能
概览	Runtime 统计卡片、快速创建、近期活动
Runtime 管理	列表 + 详情（7 个 Tab：概要/Sessions/Checkpoints/Versions/Releases/Manifest/ACP 对话）
创建 Runtime	简单模式（名称+提示词）/ 高级 JSON 模式（完整 Manifest）
ACP 工作台	全屏沉浸式对话（5 种消息气泡 + 右侧调试面板）
设置	API Key / Base URL / 自动刷新 / 主题切换

🐍 Python Demo 脚本

7 个场景覆盖所有 API 能力，开箱即用。

# 1. 安装依赖
pip install requests sseclient-py

# 2. 配置 API Key
export E2E_API_KEY="ck_xxx.yyy"

# 3. 运行基础验证（8 步全流程）
python3 demo_1_full_flow.py

# 4. 运行全部 7 个场景
python3 run_all.py

# 5. 只运行指定场景
python3 run_all.py 1 2 4

7 个验证场景

#	场景	脚本	验证能力
1	基础全流程	`demo_1_full_flow.py`	Runtime 创建/查询/删除、SSE 连接、ACP 握手、Agent 对话
2	Manifest 配置注入	`demo_2_manifest.py`	rules/skills/mcp/secrets/envs 注入、envd 文件操作
3	快照管理	`demo_3_version_checkpoint.py`	Version × 6 + Checkpoint × 6 = 12 个接口
4	Session + ACP	`demo_4_session_acp.py`	Session 幂等性、断线重连、set_model、cancel
5	Webhook 回调	`demo_5_webhook.py`	HMAC-SHA256 签名、13 种事件类型
6	产物发布	`demo_6_artifact_release.py`	Static/Web 发布、域名验证
7	高级运维	`demo_7_advanced_runtime.py`	Runtime Fork、sandboxSpec、SSE 重连

📁 项目结构

AgentOS-试用指引/
│
├── dashboard-v2/                       # 🖥️ Web 控制台（React + TypeScript + Vite）
│   ├── src/                            #   源码
│   │   ├── api/                        #     API 客户端（Runtime/Session/Checkpoint/Version/Release）
│   │   ├── stores/                     #     Zustand 状态管理（auth/runtimes/chat）
│   │   ├── hooks/                      #     自定义 Hook（useAcpConnection SSE 连接）
│   │   ├── pages/                      #     页面组件（overview/runtimes/workbench/settings）
│   │   ├── features/                   #     业务组件（StatusBadge/EmptyState/CreateDialog）
│   │   └── components/ui/              #     shadcn/ui 基础组件
│   ├── docs/                           #   设计文档 & 测试报告
│   └── e2e-test.py                     #   端到端 API 测试脚本
│
├── lib/                                # 🐍 Python 公共库（所有 Demo 复用）
│   ├── client.py                       #   RuntimeClient — 全功能 API 客户端
│   ├── acp.py                          #   ACPSession — SSE + ACP 协议通信
│   ├── manifest.py                     #   ManifestBuilder — 链式 Manifest 构建
│   ├── logger.py                       #   彩色终端输出
│   └── utils.py                        #   JSON 解析、配置读取
│
├── demo_1_full_flow.py                 # 场景一：基础全流程
├── demo_2_manifest.py                  # 场景二：Manifest 配置注入
├── demo_3_version_checkpoint.py        # 场景三：快照管理
├── demo_4_session_acp.py               # 场景四：Session + ACP
├── demo_5_webhook.py                   # 场景五：Webhook 回调
├── demo_6_artifact_release.py          # 场景六：产物发布
├── demo_7_advanced_runtime.py          # 场景七：高级运维
├── run_all.py                          # 一键运行全部场景
│
├── fixtures/
│   └── manifest-full.json              # 完整 AgentManifest 样本（27 个 skills）
│
├── AgentOS-测试验证方案.md              # 完整测试验证方案文档
├── api-reference.md                    # API 接口参考
└── 验证报告-2026-04-04.md              # 历史验证报告

常见问题

问题	排查方向
Dashboard 白屏	确认 `npm run dev` 已启动，检查浏览器控制台错误
Dashboard 数据不显示	检查「设置」页 API Key 是否已填入
`session/new` 拿不到 sessionId	确认 SSE → Initialize → Session/New 顺序正确
SSE 连接失败	确认 `acpUrl` 使用 `https://`，检查网络代理
HTTP 401	检查 API Key 格式和有效性

文档参考

完整测试方案：AgentOS-测试验证方案.md
API 参考：api-reference.md
Dashboard 文档：dashboard-v2/README.md · 部署指南 · 专家与技能集成

🚀 在线体验（Demo 环境）

体验地址：http://120.79.95.108/

这是一个基于 CloudAgent 方案构建的全功能 Web 管理控制台，客户可直接访问体验「被集成方」视角下的完整能力。

能力范围

能力	说明
Runtime 管理	创建/查看/Fork/停止/删除 AI Agent 沙箱，查看 Session、Checkpoint、Version、Release
ACP 实时对话	在浏览器内直接与沙箱里的 Agent 对话，支持流式输出、思考过程展示、工具调用可视化
多 Runtime 并发	同时连接多个 Agent 沙箱，切换时对话历史和 SSE 连接保持不断
专家模式	召唤预置专家（如"造世界""市场分析师"），Agent 自动切换到专业人设
技能注入	本地技能（daily-brief / market-entry-analyzer 等）+ Manifest 固化技能 + MCP 工具
权限模式切换	Always Ask / Accept Edits / Plan / Bypass Permissions 四档切换
调试面板	请求日志、SSE 事件流、会话产物、已加载技能——全可视化

使用说明

打开 http://120.79.95.108/
首次进入会自动跳到「配置你的账号」页面
获取 API Key（两种方式）：

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

粘贴 Key → 点「测试连接」→ 看到「连接成功 · 当前账号下有 N 个 Runtime」
点「保存并开始使用」 → 进入控制台
在 Runtime 管理 页创建沙箱，点击 ACP 对话 Tab 直接和 Agent 对话

隐私说明：控制台是纯前端应用，API Key 仅保存在你的浏览器本地（localStorage），不会上传到任何服务器。所有 API 调用从浏览器直接经反向代理发往 CloudAgent 平台，按你的 Key 计费。

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111