chore: commit workspace updates

docs/content/docs/backend/backend-database.mdx

@@ -9,13 +9,18 @@ description: 影策后端核心持久化表与状态边界
 
 ## 结构迁移与版本
 
+### 云端 Agent 运行时
+
+每轮 Agent 存为 `tasks` 中 `operation = cloud_agent` 的 `canvas_text` 任务，任务 `input_json.cloudAgent` 保存版本 1 的已校验请求、父轮 ID、请求指纹和技能快照；历史从服务端父轮结果构造。任务 ID 由用户与幂等键确定，利用现有主键、任务 admission 和积分预留事务防止重复提交重复扣费。Agent 的模型循环、工具调用、审批、子任务和事件写入 `cloud_agent_executions.state_json`，任务 Worker 只负责推进状态，不依赖浏览器连接。公共任务创建与重试接口禁止绕过 Agent admission；删除任务会影响该轮继续对话与回放。
+
 | 表 | 用途 | 关键边界 |
 | --- | --- | --- |
 | `schema_migrations` | 保存已成功应用的结构版本、名称、校验和与时间 | 已应用版本的校验和发生变化时拒绝启动；数据库版本高于当前二进制支持版本时拒绝旧程序连接 |
+| `cloud_agent_executions` | 保存 Agent 每轮的持久化执行状态、修订号和运行状态 | `(id, user_id)` 归属受服务端校验；状态通过 revision CAS 更新；`state_json` 包含技能快照、工具调用、审批、活动子任务和事件，不保存浏览器密钥 |
 
 容器内命令 `migrate-schema up` 应用缺失迁移，`migrate-schema status` 输出当前和期望版本，`migrate-schema verify` 只检查兼容性。`CANVAS_AUTO_MIGRATE=true` 仅用于开发和旧部署兼容；受管生产部署设置为 `false`，并由 Compose 的一次性 `migrate` 服务先完成迁移。后续迁移必须新增版本，不得修改已经发布迁移的实现或校验和。
 
-当前结构版本为 10。版本 2 为 `schema_migrations.applied_at` 增加 `idx_schema_migrations_applied_at` 索引；版本 3 `asset_taxonomy_candidate_identity` 为资产候选增加规范化名称和来源，收敛资产分类，并为待确认候选建立项目内部分唯一索引；版本 4 `resource_upload_key` 为资源上传幂等补充 `resources.upload_key` 列和用户维度唯一索引；版本 5 `payment_topup` 创建积分充值、支付通知和对账所需结构；版本 6 `resource_playback_variant` 增加资源播放副本状态；版本 7 `asset_library_folders` 增加用户素材自定义分类及 `assets.folder_id`；版本 8 `logical_model_active_code` 将前台模型 code 的唯一约束限定为未归档记录；版本 9 `channel_presentation` 为渠道添加 `public_alias`（默认空字符串）与 `sort_order`（默认 0），为渠道模型添加 `sort_order`（默认 0），不重写既有凭据、价格或能力配置；版本 10 `creation_runtime` 创建创作运行与提交表，并为任务增加可空且唯一的 `creation_submission_id`，旧任务无需伪造提交标识即可继续使用。
+当前结构版本为 12。版本 2 为 `schema_migrations.applied_at` 增加 `idx_schema_migrations_applied_at` 索引；版本 3 `asset_taxonomy_candidate_identity` 为资产候选增加规范化名称和来源，收敛资产分类，并为待确认候选建立项目内部分唯一索引；版本 4 `resource_upload_key` 为资源上传幂等补充 `resources.upload_key` 列和用户维度唯一索引；版本 5 `payment_topup` 创建积分充值、支付通知和对账所需结构；版本 6 `resource_playback_variant` 增加资源播放副本状态；版本 7 `asset_library_folders` 增加用户素材自定义分类及 `assets.folder_id`；版本 8 `logical_model_active_code` 将前台模型 code 的唯一约束限定为未归档记录；版本 9 `channel_presentation` 为渠道添加 `public_alias`（默认空字符串）与 `sort_order`（默认 0），为渠道模型添加 `sort_order`（默认 0），不重写既有凭据、价格或能力配置；版本 10 `creation_runtime` 创建创作运行与提交表，并为任务增加可空且唯一的 `creation_submission_id`，旧任务无需伪造提交标识即可继续使用；版本 11 `cloud_agent_runtime` 创建 `cloud_agent_executions`，保存 Agent 的 durable runtime 状态和 revision CAS 信息；版本 12 `agent_token_charge_limit` 为账单增加可空语义的 `charge_limit_microcredits`，仅 Agent Token 任务写入非零值，将服务端预授权报价固化为最终用户扣费上限。
 
 历史发布曾使用版本 6 `asset_library_folders`，之后合并引入了上述 6/7 顺序冲突。迁移器仅在该历史记录的名称和校验和均精确匹配时选择历史顺序：保留版本 6 的素材目录记录及时间，在版本 7 应用 `resource_playback_variant`，再继续版本 8。新数据库及已采用“6 播放副本、7 素材目录”的数据库保持原顺序；状态检查与启动校验采用同一套识别规则。未知名称、被改动的校验和或冲突的版本 7 记录仍会拒绝迁移，不通过删除、改名或伪造已应用记录绕过检查。
 
@@ -147,17 +152,6 @@ description: 影策后端核心持久化表与状态边界
 
 有效状态由服务端计算为 `platform_available AND user_enabled`。官方应用插件没有平台状态记录时默认可用；用户没有个人记录时默认停用，历史上全局启用的工作流插件在用户首次保存个人选择前沿用旧状态。管理员上传包的来源和作用域由宿主覆盖，不能通过 Manifest 提权。
 
-## ComfyUI Bridge
-
-| 表 | 用途 | 关键边界 |
-| --- | --- | --- |
-| `comfy_bridges` | 保存用户注册的 Bridge 身份、Token 摘要、启用状态和心跳能力 | Token 明文只在注册时返回一次；查询和日志只使用摘要 |
-| `comfy_bridge_requests` | 保存云端任务交给本地 Bridge 的请求、领取状态和完成结果 | `id` 同时作为任务的 `provider_request_id`；状态按 `queued -> claimed -> succeeded/failed/cancelled` 单向流转 |
-
-`comfy_bridge_requests` 是 Bridge 交接的真相源。后端进程重启后，未领取请求继续从数据库投递；已领取请求的迟到结果先落库，任务 worker 恢复后使用原请求 ID 读取结果，不会创建第二次本地工作流执行。请求有效期当前为两小时，过期的排队或执行记录会转为失败。
-
-请求表保存工作流执行 payload 和结果，但不保存 Bridge Token。任务取消时，未领取请求可以确定取消；已经领取的本机工作流无法可靠中止，迟到结果会被丢弃并进入费用核对流程。
-
 ## 系统公告
 
 | 表 | 用途 | 关键边界 |
@@ -182,6 +176,6 @@ description: 影策后端核心持久化表与状态边界
 
 个人画布中的图片、视频和音频采用 `Asset -> Resource` 所有权约束：前端先提交素材，再提交带 `assetId` 的画布节点或时间线直连媒体；后端保存画布前校验资源属于当前用户、状态为 `ready`、素材存在且引用同一资源。素材更新、全量替换和删除也会反向检查已有画布，不能把仍在使用的资源从素材库中移除或替换成其他资源。登录历史账号时，前端会按资源键补建缺失素材并回写 `assetId`。这项修复复用现有表和 Outbox，不新增结构迁移。
 
-账号文件容量只统计 `ready` 资源，并按 Provider、Endpoint、Bucket、ObjectKey 对同一物理对象去重；上传中或失败记录不占用已存储容量，`session_files` 仍按实际大小计入。后台每小时检查资源生命周期：超过 1 小时的 `pending/failed` 记录，以及超过 24 小时仍没有任何素材、画布、任务或其他业务引用的 `ready` 记录，会在再次校验引用后删除数据库记录并写入 `resource_deletion_jobs`，由幂等 Worker 清理物理对象。
+账号文件容量只统计 `ready` 资源，并按 Provider、Endpoint、Bucket、ObjectKey 对同一物理对象去重。上传中或失败记录不占用已存储容量。后台每小时检查资源生命周期：超过 1 小时的 `pending/failed` 记录，以及超过 24 小时仍没有任何素材、画布、任务或其他业务引用的 `ready` 记录，会在再次校验引用后删除数据库记录并写入 `resource_deletion_jobs`，由幂等 Worker 清理物理对象。
 
 素材状态为 `archived` 时进入回收站。后台按“资源与请求策略”中的 `recycleBinRetentionDays` 定期扫描过期项；`0` 表示永久保留。自动清理与用户手动彻底删除复用同一 service 引用校验和 `resource_deletion_jobs` Outbox，仍被画布、项目、任务或其他业务记录引用的素材不会被删除。

docs/content/docs/backend/code-map.mdx

@@ -9,6 +9,8 @@ description: 从产品功能快速定位主要代码入口
 
 ## 前端页面
 
+云端 Agent：`web/src/components/canvas/canvas-cloud-agent-panel.tsx` 协调对话、Skills 和审批，`services/api/agent.ts` 适配运行快照与事件流；后端 `handler/agent.go` 负责 HTTP 合同，`app/cloud_agent.go` 负责权限、幂等、可信历史与画布摘要，`app/cloud_agent_runtime.go` 负责持久化模型循环，`app/cloud_agent_tools.go` 负责技能快照、画布工具和生成工具，`app/task_creation.go` 执行预算 admission，运行沿用任务 Worker。协议见 HTTP API 专题，未确认的真实登录态与上游联调见待测试清单。
+
 | 功能 | 页面入口 | 主要协作模块 |
 | --- | --- | --- |
 | 首页与导航 | `web/src/pages/home/`、`web/src/layouts/user-layout.tsx` | `components/layout/`、`router.tsx` |
@@ -32,7 +34,7 @@ description: 从产品功能快速定位主要代码入口
 | 项目恢复、持久化和项目级动作 | `web/src/pages/canvas/use-canvas-project-lifecycle.ts` |
 | Patch 历史、生成任务和重试控制 | `web/src/pages/canvas/use-canvas-history.ts`、`use-canvas-generation.ts`、`use-canvas-generation-executor.ts`、`use-canvas-generation-retry.ts` |
 | 文本、图片、视频和音频生成执行 | `web/src/pages/canvas/canvas-*-generation-executor*.ts` |
-| Agent、助手面板、导演台和全局快捷键控制 | `web/src/pages/canvas/use-canvas-agent-operations.ts`、`use-canvas-assistant-visibility.ts`、`use-canvas-director.ts`、`use-canvas-keyboard.ts`；面板容器 `components/canvas/canvas-assistant-panel.tsx`，展示层 `canvas-assistant-panel-views.tsx`，在线工具 `canvas-assistant-online-tools.ts`，影视续写 `canvas-cinematic-continuation.ts` |
+| 云端 Agent、助手面板、导演台和全局快捷键控制 | `web/src/components/canvas/canvas-cloud-agent-panel.tsx`、`web/src/pages/canvas/use-canvas-assistant-visibility.ts`、`use-canvas-director.ts`、`use-canvas-keyboard.ts`；画布操作契约在 `web/src/lib/canvas/canvas-operation-contract.ts` |
 | 选择拖拽与连线控制 | `web/src/pages/canvas/use-canvas-selection-controller.ts`、`use-canvas-connection-controller.ts` |
 | 上传、素材插入、媒体工具和短剧编排 | `web/src/pages/canvas/use-canvas-upload.ts`、`use-canvas-timeline-asset-insert.ts`、`use-canvas-media-tools.ts`、`use-canvas-storyboard.ts`、`use-canvas-generation-batches.ts`、`use-canvas-short-drama.ts` |
 | 节点操作、节点编辑和视口导航 | `web/src/pages/canvas/use-canvas-node-operations.ts`、`use-canvas-node-editor.ts`、`use-canvas-viewport-controller.ts` |
@@ -50,8 +52,9 @@ description: 从产品功能快速定位主要代码入口
 | 布局和连线算法 | `web/src/lib/canvas/canvas-layout.ts`、`canvas-frame.ts` |
 | 任务结果回填 | `web/src/lib/canvas/canvas-generation-task-sync.ts` |
 | 本地持久化状态 | `web/src/stores/canvas/use-canvas-store.ts` |
-| Agent 会话状态 | `web/src/stores/canvas/use-canvas-agent-store.ts` |
-| 官方提示词目录与客户端起始稿 | `backend/internal/prompts/`、`web/src/lib/prompts/`、`web/src/lib/canvas/canvas-agent-protocol.ts` |
+| 云端 Agent 运行与事件 API | `web/src/services/api/agent.ts`、`web/src/components/canvas/canvas-cloud-agent-panel.tsx` |
+| Agent 画布上下文、操作与历史 | `web/src/lib/canvas/canvas-context-discovery.ts`、`canvas-operation-contract.ts`、`web/src/pages/canvas/use-canvas-operation-history.ts` |
+| 官方提示词目录与客户端起始稿 | `backend/internal/prompts/`、`web/src/lib/prompts/` |
 
 ## 前端 HTTP 与产品壳
 
@@ -112,8 +115,7 @@ HTTP 请求 -> handler -> service（稳定导入面 / 别名）-> app（组合
 
 ## 其他入口
 
-- `canvas-agent/src/`：本地 Agent、MCP 工具和当前画布会话桥接。
-- `plugins/infinite-canvas/`：Codex App 插件清单与技能。
+- 旧版 `canvas-agent/` 和 Codex App/MCP 插件已删除；Agent 运行统一由后端云端控制面承载。
 - `docs/content/docs/`：产品、操作、开发和进度文档。
 - `docker-compose.local.yml`：本地前后端编排；`nginx.conf`：生产静态资源和 API 代理。
 

docs/content/docs/backend/creative-agent-runtime.mdx

@@ -1,112 +0,0 @@
----
-title: 智能创作会话与执行
-description: 第一期在线创作的问答、审批、任务幂等与画布提交边界
----
-
-# 智能创作会话与执行
-
-画布沿用原 `CanvasAssistantPanel` 的会话、输入框、模型选择、素材引用、Skills 和在线工具循环。`creative_respond` 是原工具目录中的新能力：模型自主判断是否需要补问或方案，同批出现该工具时直接形成等待屏障，不执行其余工具。普通对话可以直接输出文字，原画布读写工具继续保留。
-
-`CanvasCreativeInteraction` 只渲染原助手消息中的交互卡片，没有独立输入框或会话列表。`CreativeAgentController.presentInteraction` 接收原 Agent 已返回的内容，负责校验、保存、批准和媒体执行，不再次请求模型。用户提交回答后回到原 Agent 工具循环，结合已确认需求继续规划。
-
-首页独立“智能创作”入口已撤回；结构化创作从原画布助手使用。画布里的批准作用于当前真实画布。首页原会话通过下述接续入口进入画布。
-
-## 首页会话接续
-
-首页/创作页沿用原文本与媒体创作逻辑，新增工具栏“画布中继续”，原媒体结果入口也接到同一流程。`creation-canvas-conversation.ts` 将当前对话转换为画布原 `CanvasAssistantSession`，保留用户/助手消息、生成状态、任务 ID、模型规格及资料/技能引用目录；内部事实只写入 detail，并在后续模型请求中提供，不向用户展示大段协议 JSON。
-
-来源会话记录 `canvasId`，画布 session 和来源消息使用稳定 ID。重复进入加载已关联画布，更新来源消息并保留画布中新增的对话与执行状态。首次进入把会话作为初始画布内容保存，源会话与画布均使用已有账号隔离存储；云端同步失败时明确提示仅本机保存。来源绑定目前随首页本机历史保存，不宣称跨设备双向同步或统一服务端任务 run。
-
-媒体结果及可匹配的上传参考图/视频复用原 asset handoff，在画布页面加载后插入，已有 assetId 不重复插入。生成尚未完成时要求完成或停止；生成结果尚未对应到已保存资产时明确等待。音频和文件保留资料目录，此次不新增对应节点导入能力。会话合并是单向接续，画布中新对话不会反向复制首页。
-
-画布通过 `conversation` 查询参数选择已保存的会话并打开原在线助手；参数只携带 ID，消费后移除，不自动发送模型请求、批准方案或重放任务。首页没有引入任何画布操作工具；需要继续执行时在画布原输入框输入要求。后续可在此基础上接电商工作台及更完整的角色上下文。
-
-## 简化交互
-
-模型根据相邻明确建议理解“可以/好的”，在当前任务范围内承接用户授权；常规创意选择、读取、已授权编辑和技术纠错不重复询问。请求上下文携带实际工具确认开关：关闭时直接调用授权范围内的普通画布工具，开启时交给原工具确认 UI，不增加前置口头确认。继续创作入口发送继续执行语义，默认回复简短。结构化方案及具体费用仍以程序批准记录为准，当前没有把自然语言自动转换为这两类批准。
-
-前端仅传递 `input.agentRequests.canonical`，其中包括标准 `messages`、`tools`、`toolChoice`、`systemPrompt`。后端完成真实模型路由与资源归属检查、素材读取后，才转换实际供应商协议。普通内建协议只构造所选请求；声明式插件所需的四套字段仅在执行内存中展开，不写回任务正文。工具选择降级仍沿用原路径。
-
-初始上下文只提供图片目录；模型通过只读 `canvas_inspect_image` 读取当前画布真实图片节点。构图预览最长边不超过 1600 像素、单图不超过 256 KiB；`original` 使用原图，`crop` 按归一化区域读取原始像素 PNG。单轮图片总预算为 6 MiB，超出则要求分批或缩小局部，不能悄悄降低细节精度。工具历史保存节点和读取方式，像素仅加入模型请求，新一批看图时释放上一批像素。原素材不变，读取事实不等于模型已完成视觉判断。
-
-看图派生的预览与裁剪结果先上传资源存储，以内容摘要作为上传幂等键；原图复用已有账号资源。标准消息的图片地址只允许 `resource:` 引用，任务准备入口从这些引用生成去重的 `referenceImages` 清单。后端按当前用户校验资源归属和就绪状态，执行时才将引用替换为供应商需要的图片数据或临时地址；任务持久化正文不包含 Base64。上传失败时明确返回工具错误，不继续发送缺失素材的模型请求。
-
-初始文本上下文按 192 KiB / 粗估 48,000 token 预算组织；当前要求、系统指令和已确认需求不截断，旧对话按完整会话组省略并告知模型。已落地方案使用结构摘要，待确认/失败修正方案保留原文。实时工具调用与结果保持配对，不做截断；包含工具目录的完整文本交换另有 384 KiB / 粗估 96,000 token 上限。估算不等于供应商 tokenizer 或真实模型窗口，达到预算时保留执行事实并提示缩小范围。完整工具任务发送前检查 15 MiB，后端 `/tasks` 的 16 MiB 限制不变。
-
-当前消息自动恢复执行租约，连接异常后在后台重试，不再要求用户反复点击接管。历史消息只读，不竞争执行权；方案批准和具体费用批准仍保留，自动恢复连接不会自动批准或重新生成。
-
-历史问答、已确认方案和报价默认折叠。当前阶段突出一个主操作，修改放在旁边，作品重做等低频操作收进“更多”；报价明细按需展开。布局沿用系统主题、间距和控件 token。点击修改回到原输入框，当前方案修改会撤销未消费的批准；已提交生成须先同步结果再调整。停止只阻止后续制作，画布撤销沿用原助手的撤销能力，不取消生成任务或退费。过期报价点击确认时先更新价格，仍须再次确认。
-
-通用 Agent 根据所在页面提供角色、技能与素材上下文；本次只调整画布助手，不新增首页或其他工作台入口。
-
-后端入口为 `handler/creation.go`，业务和权限在 `service/creation.go`、`creation_canvas.go`、`creation_agent_references.go`，持久化在 `repository/creation.go`。两张创作表和 Task 的提交关联见[数据库说明](backend-database.mdx)。
-
-## 正式场景配置
-
-内置场景统一维护在 `web/src/lib/creation/creative-scenarios.ts`，由 `creativeScenarioPrompt` 注入原在线 Agent 请求，模型自动识别场景，无需另选“智能创作”。当前属于随应用版本发布的内置策略，不是后台在线编辑器。已提交或已报价的请求保留原快照，发布配置后新的规划请求才采用新规则。
-
-| 场景 | 主要业务 | 关键配置 |
-| --- | --- | --- |
-| 通用创作 | 咨询、文字创作、跨行业创作与场景识别 | 交付目标、受众、平台、素材、数量与必要规格；按主要目标选择行业 |
-| 短剧创作 | 原创故事、剧本改编、单集片段与预告 | 剧情、题材、角色、场景、道具、对白、时长与画幅；输出完整剧情和视听时序 |
-| 营销创作 | 品牌海报、社交种草、促销文案与单段广告视频 | 商品、受众、卖点、钩子、品牌、真实优惠、文案、数量与视频时长 |
-| 电商创作 | 商品主图、详情图、场景图、搭配展示与商品视频 | 商品/服装/模特素材角色、外观保留、展示角度、真实规格、数量和视频时长 |
-
-每个场景包含 `instruction`（角色与目标）、`fields`（需求字段白名单）、`questionGuides`（补问条件、问法和候选选项）、`proposalSections`（方案内容要求）及 `workflowRules`（节点和引用规则）。短剧展示名更新，持久化标识仍为 `short-film`。
-
-模型先读取已知信息，再按条件选问，默认每轮 1～3 题，必要时最多 6 题；推荐选项须根据当前需求和真实模型能力调整。场景字段仅作为参考，允许通过安全字段校验的自定义需求；需求字段不能赋予审批或执行权限。用户已明确的题材、数量、比例、时长等不再询问。用户授权自主创意时可直接提方案，建议不能伪装成用户已确认信息。
-
-`creative_respond.plan` 可以描述最多 12 个动态步骤及调整原因；`creative-plan.ts` 将其关联到真实问答、方案、画布与媒体状态，不接受模型填写完成状态。计划保存在原消息 state，并在下一轮保留已观察完成的步骤。未返回动态计划的旧消息继续采用原进度展示。专业指导可以跨场景组合，当前仍按原批准与媒体依赖执行，不等同于新任务级调度器。
-
-已完成或暂停的交互提供“让助手分析结果与下一步”，用户点击后发起原文本模型请求，携带最近执行记录与当前画布。此操作不自动重跑媒体；新方案继续要求批准。结果是否可视觉检查取决于实际输入和模型能力，任务成功不等于画面质量检查通过。
-
-`creative-agent-recovery.ts` 在原模型首轮与后续工具回复呈现前校验交互。错误及原始工具参数回到模型，最多两次自动修正，只开放创作交互工具；不能执行同批夹带的画布操作。模型可修正方案或提出动态问题；持续无效时展示恢复选择，原错误保留诊断日志。自动修正属于文本推理请求，沿用文本计费，不代表免费，也不替代媒体费用批准。取消时不再启动后续修正。
-
-短剧只按真实内容需要生成缺失角色/场景/道具图；营销的海报版本分别体现不同传播角度；电商明确商品主体与可变背景。已有图片作为引用节点，不进入重复收费的生成项。只要文案时不自动附加媒体任务；缺少真实商品素材时不以虚构商品冒充实物。独立配音、合成和精确试衣不由场景提示词凭空赋予。
-
-### 模型、素材与技能设置
-
-场景不绑定固定模型或价格。部署中需要配置可用的系统受管文本模型；问答和方案使用工具调用，有图片资料时文本模型还需支持视觉理解。图片模型需配置真实支持的尺寸和参考图数量；视频模型需配置真实支持的时长、比例、参考图数量及声音能力。生成报价仍走现有模型计费，不能使用场景推荐值作为价格或能力依据。
-
-用户继续通过原助手的模型选择、选中画布素材和技能入口提供上下文。Skills 仍由原在线 Agent 按现有运行时装载，不自动安装插件或绑定不存在的技能。没有额外行业 Skill 也会加载内置场景策略。
-
-### 原历史会话中的持久化
-
-交互存入 `CanvasAssistantMessage.detail`，标记为 `creative-interaction`，包含原模型输入、服务端 runId、结构化需求、问题与已提交答案、方案及版本、报价与批准摘要、执行状态和产物资源引用。它随原 `chatSessions` 进入已有账号隔离的画布存储与云同步，不建立第二套聊天历史。
-
-每条结构化回复拥有稳定的提交身份，刷新按 runId 读取服务端运行事实；回看旧卡片不会自动批准或重放任务。未提交答案按账号、原会话和消息暂存本机。已提交答案进入原会话，并作为下一次原 Agent 请求的上下文。报价历史保留金额与批准摘要，账务仍以服务端为准。
-
-在使用过程中调整补问方式修改 `questionGuides`，调整方案内容修改 `proposalSections`，调整素材依赖和产物组织修改 `workflowRules`；发布后对新的规划请求生效。已批准方案和费用不会因场景配置变动而自动扩大执行范围。
-
-## API 合同
-
-以下路径均以 `/api/creation-runs` 为前缀，使用现有登录 Cookie 和统一业务响应。对象归属由 service 校验。
-
-| 请求 | 用途 |
-| --- | --- |
-| `POST /`、`GET /`、`GET /:id` | 按 clientKey 幂等创建、列表和恢复 run/submissions |
-| `PATCH /:id` | 用 revision 保存结构化会话和状态 |
-| `POST /:id/claim` | 用 expectedEpoch 接管执行，更新 owner 和 epoch |
-| `POST /:id/heartbeat`、`release` | 续租与释放执行权 |
-| `POST /:id/proposal-approve`、`proposal-invalidate` | 批准具体版本和操作范围，或使原批准失效 |
-| `POST /:id/canvas` | 批准后绑定稳定画布，不提前建草稿节点 |
-| `POST /:id/submissions/prepare` | 按 itemKey 准备具体请求和报价，不扣费、不提交 Task |
-| `POST /:id/submissions/approve` | 批准列出的提交，核对报价有效性 |
-| `POST /:id/submissions/refresh` | 从原请求生成后继报价，撤销未消费旧项，等待新批准 |
-| `POST /:id/execute` | 使用已批准提交进入原 Task/账务事务，幂等返回任务 |
-| `GET /:id/canvas-snapshot` | 获取当前画布和 snapshotHash |
-| `POST /:id/canvas-commit` | 检查 epoch、批准范围与 snapshotHash 后提交画布 |
-
-写请求携带 `owner`、`executionEpoch`；会话和方案写入还携带 `revision`。服务端批准字段独立于页面 state JSON；修改 state 不能自行授权。execute 返回 Task，不修改 run revision，刷新依 submission.taskId 对账，不以超时作为重复生成依据。
-
-图片在会话中使用 `resource:` 标识，后端检查资源归属和模型视觉能力，执行时转换为相应供应商输入；不把带签名 URL 或 data URL 持久化进规划。图片生成先进入现有素材库再回写节点 assetId，引用下游生成时使用真实已就绪资源。
-
-结构化方案的媒体提交仅支持受管模型，单次输出 count 为 1，媒体生成单独报价批准。原在线 Agent 的对话与工具推理沿用既有文本请求和计费方式，不再使用被撤回独立界面的分析报价入口。估算价格按实际用量结算，不代表消费上限。修改模型、参数、提示词或引用需重新批准具体提交；原任务仍运行或账务不明确时不能重做收费。
-
-## 恢复与限制
-
-关闭浏览器不会取消已提交的后端任务，后续编排需要重新打开会话并取得执行权。方案批准、费用批准和结果回写分别持久化；重做保留原节点及成功产物，新一轮使用新的提交标识。失败不得自动创建第二个收费任务。
-
-画布写入只在对应画布适配器就绪时发生，服务端按批准范围限制改动。当前标签页通过现有远端同步队列串行化提交；这不是全站协作协议，旧页面跨标签或设备保存仍需避免同时编辑同一画布。既有直接生成和本机 Agent 不因此获得新审批规则。
-
-实际短片、UI 与 PostgreSQL 联调状态见[待测试](../progress/pending-test.mdx)。

docs/content/docs/backend/http-api.mdx

@@ -9,6 +9,38 @@ description: 信封、错误码与 OpenAPI
 
 机器可读规范：运行中的 `GET /api/openapi.yaml`，源文件 `backend/internal/handler/openapi.yaml`。前端 TypeScript 仍走 `web/src/services/api` 的 `http`，不从 OpenAPI 生成客户端。
 
+## 云端 Agent
+
+所有 `/agent` 路径都需要登录 Cookie。`GET /agent/capabilities` 返回当前版本（2）、权限模式、上下文范围、技能和工具清单。Agent 运行由服务端任务 Worker 驱动，浏览器断开不会停止运行。
+
+- `POST /agent/runs` 创建一轮；`POST /agent/runs/:id/messages` 以上一轮为父节点创建新的不可变轮次，两者返回 `{ run }`，追加后必须使用新的 `run.id` 订阅。
+- 请求字段：`canvasId`、`prompt`、受管 `logicalModelId` 或 `channelId` + `channelModelKey`、`permissionMode: "read_only" | "request_approval" | "auto"`、`skillIds`、`contextScope: [] | ["canvas"]`、`budget: { maxCredits, maxGenerationTasks, maxVideoSeconds }`、`idempotencyKey`。不接受密钥、自定义 URL、客户端历史或未知字段。
+- 同用户同幂等键及相同请求返回同一运行；不同请求复用键返回 409。失败后重试同一提交应保留键。上一轮未完成时禁止追加；成功轮次历史从服务端加载，最多携带 8 对历史消息及 64KB 历史 JSON，超限提示新建对话。
+- 创建和追加消息可传 `thinking: boolean`（默认关闭），贯穿首轮及工具后续模型调用；内置 Chat Completions、Responses、Claude 协议复用文本推理配置，上游模型仍需支持。声明式 Agent 渠道暂不支持，开启时明确报错，不静默忽略。思考模式可能增加耗时和费用。
+- 已安装且属于当前用户的技能会在创建时固定版本快照，模型只能通过 `skill_read_file` 读取快照文件。技能正文是不可信输入，不能改变权限或系统规则。
+- 当前工具为 `canvas_get_state`、`skill_read_file`、`task_get`、`model_list`、`canvas_apply_ops`、`generate_media`。画布写入工具要求本轮授权 `contextScope: ["canvas"]`。禁止 shell、任意网络请求和外部 MCP。
+- `canvas_apply_ops` 必须带 `snapshotHash`，每批最多 20 项；支持新增文本、Markdown、图片、视频、音频、分组与分镜表节点，以及 `connect_nodes` 引用连线。媒体占位节点的 `content` 是提示词，不是媒体 URL；只建节点不提交收费生成。`update_node` 仅允许更新未锁定文本 / Markdown 的标题和正文；禁止删除、任意元数据写入、自连接、重复边与不存在的端点。
+- `model_list` 复用生成面板的当前模型目录。每项的 `selection` 是 `logicalModelId` 或 `channelId` + `channelModelKey`，工具调用必须原样选择一种，不猜 ID 或混用；能力、规格、价格与任务准入再次核对。
+- `generate_media` 支持图片 / 视频：必填 `mode`、`prompt`、`size`、`durationSeconds`（图片为 0）、`snapshotHash`、新 `nodeId`、`title`、有序 `referenceNodeIds`（无参考传空数组），再加一种模型选择；可传来源节点 `sourceNodeId`、`quality`、视频 `videoGenerateAudio`。`sourceNodeId` 仅接文本 / 镜头提示词节点；参考图片、视频、音频只放 `referenceNodeIds`，无文本来源时留空且不重复传入。引用从当前画布节点的账号资源解析，校验归属、类型、就绪状态和模型能力，不接受任意 URL。图片生成仅接图片参考；视频可按模型能力接图片、视频、音频参考。
+- 参数选择与收费授权分开：用户明确说“随便 / 你决定 / 按默认”时，Agent 可从当前目录选择能力及预算匹配的模型，优先用户最近明确使用的可用模型，其次价格清楚的低成本选项；支持时沿用参考图原始比例，否则选目录默认，时长用目录默认。未要求音频且模型不支持时用默片。用户接受已推荐方案后不再要求特定确认口令；仅真正缺失或冲突的阻塞项一次性询问。本轮已有目录结果应复用。以上是 Agent 的参数选择策略，服务端仍强校验具体规格，不提供绕过预算 / 能力校验的默认兜底，也不绕过独立收费审批。
+- 媒体参数先进行无任务、无预留账单的准入校验，再在同一事务创建草稿节点、来源 / 资产连线及待审批检查点；`approval_requested` 和运行中的 `approval` 携带目录真实 `modelName`。用户批准后才在事务中绑定任务、创建预留账单并更新检查点；拒绝或取消保留未生成草稿，不提交媒体任务。草稿仅允许原运行认领，不能覆盖其他节点。已明确审批的规格不得被模型默认值静默替换。媒体终态回写原节点；已删除或已换任务的节点不自动复活，结果仍可从任务中心查看。
+- Agent 的 `snapshotHash` 忽略顶层 `viewport`、`updatedAt`，避免平移 / 聚焦自动保存使审批失效；节点、连线、标题等内容改动仍需重新读取并审批，数据库写入仍使用完整快照 CAS。客户端刷新同样区分视口和真实内容编辑，并保留本地视口。
+- `read_only` 只允许读取；`request_approval` 对写画布和媒体生成暂停为 `waiting_approval`；`auto` 可在预算内执行已授权画布操作，但图片 / 视频生成始终独立审批，不能绕过。每轮最多 8 次模型调用、8 个生成任务和 120 秒视频，实际报价在创建任务及预留积分前校验。失败事件保留具体错误和已有任务的 `taskId`、`nodeId`、`status`；媒体结果的 `phase` 区分 `admission` 与 `completion`，`taskSubmitted` 表达是否已提交。模型应报告错误，不能自行删减提示词或自动重试收费生成。
+- 必须有当前用户已保存的画布。首轮摘要最多取前 80 个节点；`canvas_get_state` 可按 `offset` 每页读取 40 个节点、资产可引用状态及相关连线，按 `nodeIds` 精读最多 8 个节点（正文每字段最多 16000 字符），通过 `hasMore` / `nextOffset` 和字段 `Truncated` 判断是否完整。分镜表包含镜头、角色节点与资产绑定；摘要每页最多 20 行，精读每次 1 行，可用 `storyboardOffset` 翻页；单行叙事文本累计最多 24000 字符，角色 / 绑定各最多 16 项。上下文不含媒体 URL、任意元数据或未同步修改；节点名称不等于图像视觉识别。普通任务重试接口不能重试 Agent 任务。
+- `GET /agent/runs/:id` 返回运行信息；`POST /agent/runs/:id/cancel` 取消当前运行及活动子任务；`POST /agent/runs/:id/approvals/:approvalId/decision` 接受 `{"decision":"approve"|"reject","reason":"..."}`，审批决定幂等且服务端校验归属。
+- `GET /agent/runs/:id/events` 返回 `agent_event` 和首次 / 状态版本变化时的紧凑 `run_snapshot` SSE；无变化时只发送 heartbeat。事件 `Seq` 在运行内递增；支持 `?after=` / `Last-Event-ID`，游标不是运行 ID。`cleanupPending: true` 时即使运行已进入终态也会继续推送，直到后台收尾完成。前端应以快照恢复状态，代理只对这一精确路径关闭缓冲。
+- `generation_task_created` 携带 `canvasId`、`nodeId`、`taskId`、`title`、`mode`、`referenceNodeIds`。草稿、提交、画布工具写入，以及媒体成功 / 失败 / 取消的真实节点变更，均在画布写入与运行检查点的同一事务持久化 `canvas_updated`。节点已删除或换任务时不伪造更新；`run_failed` 本身不代表节点媒体任务失败。
+- `canvas_updated` 包含 `canvasId`、`operation`、`callId`、`actions` 和 `canvasPatch`。`canvasPatch` 为 `{ canvasId, updatedAt, nodes: [{ before, after }], connections: [{ before, after }] }`；新增对象的 `before` 为 `null`，仅包含有变化的节点和连线。当前工具不开放删除。`actions` 固定保存操作类型、节点 ID、标题、类型，引用操作还带目标节点 ID，供历史消息显示和点击定位；`callId` 用于合并同一画布操作的工具完成消息。
+- 前端对增量按 40ms 窗口合批，三方合并远端基线、当前 Store 和编辑器，正常完成 / 失败无需全量 GET；保留无关节点编辑、拖动与视口，同字段冲突、删除或新任务绑定不强行覆盖。只有事件缺口、断流、增量冲突或没有增量的事件源需要全量校准，同一画布协调器最多每秒发起一次，单请求在途，期间重复通知合并为一次尾随校准。已识别增量协议后，相邻 `tool_failed` / `run_failed` 不重复触发整图刷新。
+- Agent 创建 / 续聊请求在客户端先持久化完整正文、幂等键、父运行和消息 ID，再提交；网络超时或响应丢失只允许用同一正文和 key 有界重放，不能换 key 生成新收费轮次。待确认记录损坏时对话暂停发送，不把它当成“从未提交”。
+- 生成按钮与提交入口共用节点任务状态：排队 / 运行中不可重复生成，终态解除任务锁，历史 `taskId` 不永久禁用。聊天留痕保留节点名、引用与失败任务 ID，点击使用现有画布聚焦；已删除节点只提示，不自动重建。聊天缓存不重复保存增量中的完整节点正文。
+
+Agent 的聊天列表缓存只负责 UI 恢复；运行、技能快照、审批、工具调用、子任务和事件均以服务端持久化状态为准。提交响应丢失时，客户端应使用同一幂等键重试，不生成新的提交。
+
+Skills 的 `tool_completed` / `tool_failed` 事件附带 `skillId`、`skillName`（已启用技能）和 `path`；空路径表示列目录，不表示已读取文件。目录结果中的 `files` 为本轮固定快照的可读路径，空数组时应使用已加载正文继续。同一运行内同技能同路径只允许请求一次（包括不存在的路径），重复请求返回工具失败和继续执行指引，状态随运行持久化。模型初始上下文包含技能 ID 和可读文件清单。
+
+模型任务失败的 `run_failed` 事件保留 `taskId`，并提供安全分类 `reason`：`model_connection_reset`、`model_request_timeout`、`model_connection_refused` 或 `model_task_failed`。`text` 不透传原始上游错误，避免泄露地址和凭证；前端用事件类型而非摘要关键词判断工具成功 / 失败。失败不会触发自动付费重试。
+
 ## 管理员支付订单
 
 `GET /api/admin/payments/orders` 需要管理员权限，支持 `status`、`keyword`、`page`、`pageSize`。关键词匹配订单号、渠道交易号、用户名称、用户名或邮箱，也支持完整用户 ID 精确匹配。用户名和邮箱搜索忽略大小写；状态过滤同时生效，返回匹配总数和当前页订单。

docs/content/docs/backend/local-development.mdx

@@ -54,7 +54,7 @@ bun install --frozen-lockfile
 bun run dev
 ```
 
-`web/` 与 `canvas-agent/` 只使用 `bun.lock`。不要用 pnpm 或 npm 往同一套 `node_modules` 里再装一遍。
+`web/` 只使用 `bun.lock`。不要用 pnpm 或 npm 往同一套 `node_modules` 里再装一遍。
 
 前端默认监听 `0.0.0.0:3000`，Vite 将 `/api` 和 OAuth 回调代理到 `127.0.0.1:8080`。如需修改代理目标，可设置 `VITE_API_PROXY_TARGET`。