38 lines
3.2 KiB
Markdown
38 lines
3.2 KiB
Markdown
# 图片与视频画布原生 ZCode Agent
|
||
|
||
## 目标与边界
|
||
|
||
Agent/Auto Agent（含预设任务）统一进入原生 zai-org/ZCode CLI 核心；Claw 保持原入口。禁止用自研循环加 ZCode 名称替代实际核心。固定上游提交、构建摘要和许可证，部署时校验原生 bundle。
|
||
|
||
每个 CanvasAgentRun 分配独立 OS 沙箱、工作区、home、临时目录和会话存储。Linux 使用 bubblewrap 的 mount/user/PID/network/IPC namespaces；macOS 开发验证使用 sandbox-exec。沙箱不可用时拒绝启动，不在宿主直接执行。全任务进程树可取消并受运行时长、内存、进程数、输出和磁盘预算限制。
|
||
|
||
## 所有者与执行链路
|
||
|
||
画布 Agent -> 已鉴权 API -> 用户/画布/任务租约
|
||
-> 单任务模型及工具网关
|
||
-> 独立沙箱里的原生 ZCode
|
||
原生 ZCode -> 带运行令牌的 MCP -> 先持久化 started -> 业务能力
|
||
-> 持久化结果 -> 原生 ZCode
|
||
API -> 节点变更与进度 -> 画布
|
||
|
||
宿主仅负责身份、业务工具、模型凭据、持久化、租约与 UI 回传；ZCode 独占规划、上下文整理、工具调度及核心会话。模型和工具通过每任务 Unix socket（macOS 本地受限端口）网关通信。提供临时运行令牌，不向沙箱传递模型/云存储/数据库密钥或宿主环境。
|
||
|
||
## 授权与工具契约
|
||
|
||
图片画布 capability registry、节点操作、视图、素材、下载和全部界面入口，以及视频画布 function config、媒体处理和节点工作流统一注册为 MCP 工具。权限与按钮隐藏独立；功能授权不虚构不存在的后台，也不绕过用户/项目所有权、管理员停用状态或具体删除/覆盖操作的授权。
|
||
|
||
MCP 工具注册使用现有 inputSchema 的 JSON Schema；执行仍进行运行时 schema 校验。调用必须携带工具 callId，started 先持久化，已结算结果可重放，不确定的收费调用禁止自动重做。大结果截断或归档；模型不能提供任意 userId/projectId/服务商凭据。
|
||
|
||
## 状态、恢复及错误
|
||
|
||
CanvasAgentRun 保存 ZCode sessionId、sandbox 类型/构建、调用记录、节点 ID、补充要求、原始终止原因和最终验收。浏览器断开不取消收费任务。取消先停止后续工具，再终止整个沙箱进程树；已完成结果保留。重启后带 started/uncertain 调用的任务进入 needs_review，不重复扣费。补充要求进入同一任务队列，在下一原生回合交付，不丢失。
|
||
|
||
## 验收
|
||
|
||
- 实际原生 CLI 用模拟 OpenAI 服务及真实 MCP 完成多步工具、取消、恢复、流式事件、上下文处理。
|
||
- 沙箱内不能读取项目 .env、宿主 SSH 文件、其他任务工作区，不能写宿主文件，不能直接访问外网或宿主服务。
|
||
- 错误/过期/跨任务令牌、重复/并发工具 ID、不确定收费、跨项目节点均被拒绝。
|
||
- 每项 registry/config 功能有对应可调用工具或明确真实交互入口，缺后端明确报错。
|
||
- 图片/视频 Agent 走新入口，Claw 路由不变；服务端阻止旧 Agent 请求静默回退自研循环。
|
||
- 先本地与 48 的私有测试实例验证，再切换生产；保留旧构建回滚。
|