Agent 平台（Expert + Agent Runtime）

Expert（AI 专家产品） 的对话与工具执行由 Agent Runtime（services/agent-runtime）承载，运行在 声明式 Sandbox（E2B 或 Docker） 中。每个 Expert 对应隔离的文件系统与运行环境，通过 SSE 协议实现实时流式对话。

概述

运行时架构

层级	说明
Core API	Expert / Sandbox 生命周期编排、鉴权、计费、`prepare-invoke` 等业务真源
Agent Runtime	`services/agent-runtime`，在 Sandbox 内执行模型对话、工具与文件访问

Web 经 SSE 代理将对话请求转发到已由 Core 准备好的 Sandbox 端点；编排细节见系统架构 — Expert 沙箱与 agent-runtime。

Expert / Sandbox 生命周期

状态

状态	标识	说明
创建中	`provisioning`	Sandbox 正在分配和启动
运行中	`running`	Expert 就绪，可接受对话
已停止	`stopped`	Sandbox 已释放；元数据与配置保留以便快速恢复
异常	`error`	Sandbox 或 Agent Runtime 不可达；恢复后可自动转为 `running`

停止与删除的区别

操作	Sandbox 行为	DNS / 路由	恢复速度
停止	暂停或销毁沙箱计算资源，编排元数据保留	对外入口由 Core/Web 统一维护时可保持路由稳定	通常秒级（重新 provision）
删除	元数据与工作区持久化按策略清理	关联 URL 失效	按产品策略可能不可恢复

设计决策：停止优先于「硬删路由对象」，避免反向代理 DNS 缓存 NXDOMAIN 导致的短时 404。旧 Kubernetes 方案中删除 Service 后 resolver 缓存曾造成唤醒窗口内无法路由，已在 Compose + 声明式 Sandbox 模型下由编排层显式管理。

Error 状态自动恢复

error 不是死胡同。checkInstanceHealth（或等价健康任务）在轮询时检测 Sandbox 与 Agent Runtime：

Sandbox 运行中 + Agent Runtime HTTP 可达 → 自动恢复为 running
Sandbox 仍在重启/崩溃循环 → 保持 error，等下次检查
Sandbox 已终结（失败 / 不存在）→ 保持 error，用户需手动重启

Health 路径对 error 状态的实例不应误触发「强制停止」，以免打断编排侧正在进行的自动恢复。

进入聊天的就绪门禁

前端在进入对话界面前，依次等待 3 个真实信号：

Sandbox 就绪 → Agent Runtime 可达 → 技能加载完成 → 文件列表预取 → 进入聊天
              ↓                      ↓                 ↓
         gatewayReady           skillsReady       filesLoaded → setView("chat")

步骤	信号	来源	含义
1. 启动服务	`gatewayReady`	Health API	Sandbox 运行中 + Agent Runtime HTTP 可达
2. 装载技能	`skillsReady`	Health API	config 中的 URL 技能全部安装到 `workspace/skills/`
3. 准备工作区	`filesLoaded`	前端本地	`loadInstanceFiles` 完成，文件列表已预取

用户在启动界面能看到每一步的真实进度和对勾。3 步全部完成后短暂展示全部对勾，再切入聊天。 所有入口统一走加载页：即使是已 running 的 Expert（如页面刷新、从列表重新进入），也会先显示加载页并执行 3 步就绪检查，确保文件列表在进入对话前就已就绪。对于已运行的实例，步骤 1-2 会在首次 health poll 时秒过。

前端文件状态管理

每个 Expert 通常映射一个主会话工作区。sandboxFiles（Sandbox 文件列表）是实例级状态，不随 session 生命周期重置：

概念	级别	说明
`sandboxFiles`	Expert / 实例级	Sandbox 文件系统列表，由 `loadInstanceFiles` 填充
`trajectoryData`	Session 级	对话轨迹（tool calls、todos 等）
`dbEvents`	Session 级	持久化的对话事件，用于刷新后回放

switchToSession 在创建新 session 快照时，会保留当前 sandboxFiles，避免因 session 初始化而清空已加载的 Sandbox 文件。

历史 Bug：switchToSession 曾用 initialWorkspaceSnapshot（sandboxFiles: []）创建 fresh session，导致 loadInstanceFiles 加载的文件在 setView("chat") 触发 session 恢复时被清空——表现为文件「闪一下然后消失」。

Expert / 实例管理接口

以下 HTTP 路径沿用历史兼容前缀 /api/claw/*（实现上对应 Expert 与 Sandbox 编排）：

方法	路径	说明
POST	`/api/claw/instances`	创建 Expert / Sandbox
GET	`/api/claw/instances`	列出用户的实例
GET	`/api/claw/instances/:id`	实例详情
PATCH	`/api/claw/instances/:id`	重命名实例
DELETE	`/api/claw/instances/:id`	删除实例（`?permanent=true` 永久删除）
POST	`/api/claw/instances/:id/restart`	重启实例
POST	`/api/claw/instances/:id/stop`	停止实例

SSE 实时流式交互

Agent 平台的核心交互基于 Server-Sent Events（SSE）协议，前端通过 POST /api/claw/chat 发送消息并接收实时流式响应。

SSE 事件流

SSE 事件类型

事件	说明
`text`	AI 文本输出片段，增量渲染
`tool_call_chunk`	工具调用信息（函数名、参数、结果）
`complete`	对话回合完成
`error`	错误信息

消息处理架构

前端通过模块化的 Message Handler 处理不同事件类型：

apps/web/src/lib/message-handlers/
├── stream-processor.ts    # SSE 流解析和分发
├── tool-call-handler.ts   # 工具调用渲染
├── text-handler.ts        # 文本片段拼接
├── error-handler.ts       # 错误处理
└── complete-handler.ts    # 完成回调

Sandbox 与 Agent Runtime 访问

路由与端口

每个 Expert / Sandbox 分配由 Core 编排解析得到的运行时 URL（历史上常称 containerUrl）。Next.js 代理根据编排结果访问 Sandbox 内的 Agent Runtime，无需自建 Kubernetes Ingress。

端口	用途	访问方式
18789	Agent Runtime HTTP（API + SSE）	编排返回的默认入口
3000	Web 预览（开发服务器）	`runtimeUrl:3000`（视模板而定）
3001	备用预览端口	视模板而定
6080	noVNC 浏览器访问	视模板而定

实例配置

接口	说明
`GET /api/claw/instances/:id/config`	读取 Agent Runtime / 工作区配置
`PATCH /api/claw/instances/:id/config`	更新配置（`?apply=true` 立即生效）
`GET /api/claw/instances/:id/config-drift`	检测配置漂移

文件与预览

接口	说明
`GET /api/claw/files`	列出/读取/导出 Sandbox 工作区文件
`POST /api/claw/files`	上传文件到 Sandbox
`GET /api/claw/preview/:instanceId`	代理到 Sandbox 内的 Web 服务
`GET /api/claw/novnc`	noVNC 桌面预览代理

技能系统

Expert 支持在 Sandbox 内安装和管理技能（Skill），扩展 Agent 能力：

方法	路径	说明
GET	`/api/claw/instances/:id/skills`	实例已安装的技能
GET	`/api/claw/skills`	技能注册表
PATCH	`/api/claw/skills`	启用/禁用技能

技能市场通过 SkillMarketDialog 组件提供可视化的技能发现与安装体验。

金币与服务计划

Expert / Sandbox 的运行消耗金币，计费规则由服务计划（Service Plan）定义。

接口	说明
`GET /api/claw/credits`	查询余额（代理到 Core）
`GET /api/claw/service-plans`	服务计划列表（代理到 Core）
`GET /api/claw/credits/transactions`	消费记录

Auth 桥接

Expert 对话与 Portal 共享用户体系。Web 端相关路由通过以下机制桥接认证：

proxy.ts 保护需登录的页面路由，无 Token 重定向登录
getAuthUserId() 为上述 API 路由提供用户身份
Token 在代理转发时自动注入到上游请求

健康检查与清理

接口	说明
`GET /api/claw/health`	实例健康状态（含 `gatewayReady` + `skillsReady`）
`POST /api/claw/health`	超时实例清理 + error 状态自动恢复检测
`POST /api/claw/admin/cleanup`	管理员清理孤立实例

Health API 返回字段（名称可能随版本演进，以 OpenAPI/实现为准）：

字段	类型	说明
`healthy`	boolean	Sandbox / 进程是否存活
`gatewayReady`	boolean	Agent Runtime HTTP 端口可达
`skillsReady`	boolean	所有 URL 技能已安装到 `workspace/skills/`
`podStatus`	string	历史字段名；语义上表示编排状态如 `running` / `starting`
`uptime`	number	实例运行秒数

系统架构

Expert 与 Agent Runtime 在整体架构中的位置

金融支付

Expert / Sandbox 的金币计费

应用市场

技能市场与应用发现

部署指南

Docker Compose 与可选 E2B Sandbox

开始使用

架构

模块

应用开发

Agent 平台

Agent 平台（Expert + Agent Runtime）

概述

运行时架构

Expert / Sandbox 生命周期

状态

停止与删除的区别

Error 状态自动恢复

进入聊天的就绪门禁

前端文件状态管理

Expert / 实例管理接口

SSE 实时流式交互

SSE 事件流

SSE 事件类型

消息处理架构

Sandbox 与 Agent Runtime 访问

路由与端口

实例配置

文件与预览

技能系统

金币与服务计划

Auth 桥接

健康检查与清理

相关链接

系统架构

金融支付

应用市场

部署指南

开始使用

架构

模块

应用开发

Documentation Index

​Agent 平台（Expert + Agent Runtime）

​概述

​运行时架构

​Expert / Sandbox 生命周期

​状态

​停止与删除的区别

​Error 状态自动恢复

​进入聊天的就绪门禁

​前端文件状态管理

​Expert / 实例管理接口

​SSE 实时流式交互

​SSE 事件流

​SSE 事件类型

​消息处理架构

​Sandbox 与 Agent Runtime 访问

​路由与端口

​实例配置

​文件与预览

​技能系统

​金币与服务计划

​Auth 桥接

​健康检查与清理

​相关链接

系统架构

金融支付

应用市场

部署指南

Agent 平台（Expert + Agent Runtime）

概述

运行时架构

Expert / Sandbox 生命周期

状态

停止与删除的区别

Error 状态自动恢复

进入聊天的就绪门禁

前端文件状态管理

Expert / 实例管理接口

SSE 实时流式交互

SSE 事件流

SSE 事件类型

消息处理架构

Sandbox 与 Agent Runtime 访问

路由与端口

实例配置

文件与预览

技能系统

金币与服务计划

Auth 桥接

健康检查与清理

相关链接