docs: add ark agentplan setup notes

docs/canvas-node-manual.md

@@ -45,7 +45,10 @@
 - 视频节点使用原生播放器展示内容，可在节点内直接播放、暂停和拖动进度。
 - 空视频节点下方对话框可输入提示词生成视频，结果会回填到当前节点。
 - 从文本、图片或配置节点创建视频生成时，会在右侧生成新的视频节点并自动连接。
-- 视频生成接口使用 OpenAI 兼容的 `POST /v1/videos`、`GET /v1/videos/{id}` 和 `GET /v1/videos/{id}/content`。
+- 生成配置节点的视频模式会读取上游文本作为 prompt，读取上游图片作为参考图，读取上游视频作为参考视频，并在输入预览里显示参考视频。
+- 视频生成接口支持 OpenAI 风格的 `POST /v1/videos`、`GET /v1/videos/{id}` 和 `GET /v1/videos/{id}/content`。
+- 使用火山方舟 Agent Plan / Seedance 2.0 时，Base URL 配置为 `https://ark.cn-beijing.volces.com/api/plan/v3`，模型名使用 Seedance 2.0 对应模型；系统会改用 `POST /contents/generations/tasks` 创建异步任务，并轮询 `GET /contents/generations/tasks/{id}`。
+- Seedance 参考视频必须是公网可访问 URL，或由本项目后端在配置 `PUBLIC_BASE_URL` 后上传并暴露的参考素材 URL。本地/内网地址无法被火山服务器拉取。
 
 ### 推荐流程
 

docs/features.md

@@ -52,13 +52,25 @@
 
 ## AI 生成
 
-项目通过前端直接请求 OpenAI 兼容接口：
+项目支持两种 AI 调用方式：
+
+- 本地直连：前端使用本地配置的 Base URL、API Key 和 Model 直接请求 OpenAI 兼容接口。
+- 后台渠道：前端请求本项目后端 `/api/v1/*` 代理接口，后端按模型选择管理后台配置的渠道。
+
+OpenAI 兼容图像和文本能力继续复用现有接口：
 
 - `/v1/images/generations`：文生图。
 - `/v1/images/edits`：图生图/参考图编辑。
 - `/v1/chat/completions`：文本问答和带图问答。
 - `/v1/models`：读取模型列表。
 
+视频能力支持两类接口：
+
+- OpenAI 风格视频：`POST /v1/videos`、`GET /v1/videos/{id}`、`GET /v1/videos/{id}/content`。
+- 火山方舟 Agent Plan / Seedance 2.0：Base URL 使用 `https://ark.cn-beijing.volces.com/api/plan/v3`，创建任务为 `POST /contents/generations/tasks`，查询任务为 `GET /contents/generations/tasks/{id}`，成功结果读取 `content.video_url`。
+
+Base URL 如果已经以 `/v1`、`/api/v3` 或 `/api/plan/v3` 结尾，系统不会再追加 `/v1`。因此 cpa 反代或火山方舟 Agent Plan 可以继续通过现有 Base URL + API Key + Model 方式配置，不需要新增火山生图 Provider。
+
 可配置项：
 
 - Base URL。
@@ -67,9 +79,13 @@
 - 图片质量。
 - 图片比例。
 - 生成数量。
+- 视频模型。
+- 视频比例、清晰度和时长。
 
 普通图片/文本节点可以直接输入提示词生成结果。生成配置节点可以读取上游节点内容，并按节点自己的配置批量生成多个图片或文本结果。生成配置节点支持预览当前提示词和参考图输入，并调整输入顺序。
 
+视频生成可从文本节点读取 prompt，从图片节点读取参考图，从视频节点读取参考视频。生成成功后会把视频插入画布为视频节点并使用原生播放器预览。Seedance 参考视频需要公网可访问 URL；本地上传视频会先通过 `/api/v1/media/references` 保存到服务端，再由 `PUBLIC_BASE_URL` 生成可供火山服务器拉取的公开链接。
+
 ## 画布助手
 
 画布右侧助手面板支持：
@@ -161,6 +177,8 @@
 ## 当前限制
 
 - 画布项目和“我的素材”目前只保存在浏览器本地，不会随账号同步。
-- AI API Key 目前保存在浏览器本地，并由浏览器直接请求配置的 OpenAI 兼容接口。
+- 本地直连模式下，AI API Key 保存在浏览器本地，并由浏览器直接请求配置的 OpenAI 兼容接口；只适合本地或个人使用，公网多人使用不安全。公网部署推荐使用后台渠道，把真实密钥保存在服务端配置中。
 - 服务器素材库目前主要保存 URL 或文本，暂未提供文件上传接口。
+- Seedance 本地参考图/视频上传依赖 `PUBLIC_BASE_URL`，如果服务部署在 localhost、内网或不可被火山访问的地址，火山无法拉取参考素材。
+- Seedance 返回远程视频 URL 时，前端会尽量下载为本地 Blob 持久化；如果因 CORS 或网络限制无法下载，会保留远程 URL，后续是否可播放取决于上游 URL 的有效期。
 - 画布更适合桌面端使用，移动端触控体验还未系统完善。

docs/pending-test.md

@@ -21,3 +21,6 @@
 - 视频生成前端会识别后端 `{ code, msg }` 错误响应，创建失败不再继续轮询 `undefined`。
 - 新增 `/video` 视频创作台页面，参考生图工作台布局，支持提示词、参考图、视频参数、生成结果、保存素材、下载和本地生成记录；清晰度和秒数均支持常用值选择与手动输入，生成记录只保存媒体 `storageKey` 并可回填本次提示词、参考图和参数。
 - 视频创作台生成前会把模型、尺寸、秒数、清晰度归一化为视频接口支持的参数，并展示后端返回的错误信息，避免页面侧残留的生图参数影响视频请求。
+- 火山方舟 Agent Plan / Seedance 2.0 视频生成需要在真实账号下验证：`/contents/generations/tasks` 创建任务、轮询状态、`content.video_url` 回填画布，以及 401/403/429/超时错误提示。
+- `PUBLIC_BASE_URL` 已配置公网域名时，需要验证本地上传参考视频能被火山拉取；未配置或配置为内网地址时，需要验证前端能给出明确提示。
+- Seedance 返回远程视频 URL 但浏览器无法下载为 Blob 时，需要验证视频节点刷新后仍保留远程 URL，并确认上游 URL 有效期限制。