AI 工作区

正文

web-nuxt 现在提供完整的 AI 工作区，而不是把所有任务都导向一个 Playground：

/dashboard/ai-chat 是正式的持久化对话产品面，支持历史记录与多轮续聊
/dashboard/ai-playground 是 AI 创作室，承载图像、视频、音频等结构化生成流程
/dashboard/image-agent 是对话式图片编辑工作台，包含持久化对话、参考图、生成历史、素材库与版本预览
/dashboard/usage 合并对话与 Provider 生成用量，覆盖图片、视频、音频、请求、Token、积分、每日活动和模型明细

为什么要统一到这里

这些产品面共用同一套会话生命周期，因此都能理解：

当前登录状态
访客会话
当前积分余额
API Key 生命周期
对话与生成记录
模型差异化输入
按用户隔离的用量与计费数据

站长可以继续使用原生 Workers AI Binding，也可以在管理端 AI 上游配置中填写任意 HTTPS OpenAI 兼容 Base URL 与 API Key。凭证只保存在 node10-ai-service 服务端，用户只能看到已启用模型，不会接触上游密钥。

Image Agent 接入

目前仅 Nuxt 模板接入。app/app.config.ts 中的 imageAgent.enabled 控制导航入口；页面与 API 均位于 apps/web-nuxt，其他前端模板不受影响。

重新打开对话会恢复最近使用的图片模型与生成设置；如果原模型已经不可用，需要先选择可用模型再发送下一条消息。后台进度更新会保留当前模型选择。

输入区的图片附件面板支持文件选择、拖拽、剪贴板图片、HTTPS 图片链接和素材库多选。每条消息最多添加 16 张图片，显示缩略图与顺序编号，可预览、移除或清空。即使所选图片模型不支持编辑，或每次只接受较少的参考图，Agent 仍可查看这些对话附件；真正执行图片工具时，仍遵守该模型的能力与参考图数量限制。文件上传复用平台 CDN 上传组件，支持进度、取消和失败重试，接受单张最大 10 MB 的 PNG、JPEG、WebP、GIF、AVIF。Mock 使用相同界面和校验，文件仅保留在浏览器内，不请求 CDN。

没有上传图片或补齐出图设置时，也可以先讨论创意。所选图片模型与设置用于 Agent 生成和编辑图片，不会阻止纯文字讨论或看图分析。上传图片作为对话上下文保存，Agent 在每次图片操作中选择符合模型限制的来源图。

助手回复和执行记录支持 Markdown 标题、强调、列表、表格和代码块。小屏幕上的宽表格、代码块在消息内横向滚动。模型返回的 HTML 按普通文字展示，回复不会加载 Markdown 中的图片链接；生成图片与参考图通过已保存的任务记录展示。HTTP(S) 链接会单独打开。

参考图缩略图和图片预览中的“标注图片”可打开编辑器，支持画笔、箭头、矩形、椭圆、文字、颜色、粗细、移动、撤销重做和修改备注。每条消息最多包含四张已标注原图，每张最多 64 个标记和 1,000 字备注。合成的 PNG 指引图通过共用 CDN 上传，原图、指引图、可编辑的归一化标记和备注一起随消息保存。Agent 同时查看原图与指引图，图片编辑工具只使用不含标记的原图。保存后可重新打开并继续修改标记。真实模式先将原图导入参考图存储，再通过鉴权同源接口读取，因此编辑器不依赖第三方浏览器 CORS。来源须符合导入策略，并在首次转存成功前保持可访问；无法读取或超过大小上限时显示重试状态。导出指引图的最长边不超过 2,048 像素。

Agent 可将下一次视觉查看聚焦到单张图片，也可按所选顺序对比多张图片。其他版本仍保留在对话中，可再次查看，但不会混入聚焦预览。标注指引会随对应原图一起提供。这有助于在多个版本容易混淆时单独复核细节，但不保证模型判断必然正确。查看会消耗模型步骤与 token，不会执行图片生成操作。

新任务在出图后会先检查最新返回的图片，同一步产生的多张结果一起复核。原图和旧版本仍可主动选中进行对比；再次编辑后，重新检查本次输出。已接收任务在恢复时继续使用原有复核策略。

现有 node10 Worker 导出 Image Agent 的 Cloudflare Workflow。应用 Node1 截至 0040_credit_debit_cancellation.sql、企业账单服务截至 0004_usage_reservation_fences.sql、Provider1 截至 0034_task_recovery_legacy_visibility.sql、node10 截至 0016_image_agent_workflow_control.sql 的迁移，先发布 Node1 和企业账单服务，再按 Provider1、node10、Nuxt 的顺序发布。本地使用各服务的 db:migrate:local 脚本。node10 需要 IMAGE_AGENT_WORKFLOW、PROVIDER1_SERVICE 绑定，以及独立的 IMAGE_AGENT_CREDENTIAL_KEY Secret，值为 32 字节随机数编码成的 64 位十六进制字符串。前端沿用已有 AI_SERVICE、PROVIDER1_SERVICE 和 CDN 服务连接。图片 Provider 应配置公开模型信息、提示词字段和参考图字段，模型校验规则决定出图设置与工具可用的参考图数量。继续沿用 Provider 的 Turnstile、权限、内容审核、积分、退款和任务状态机制。

Cloudflare 环境中的 Admin AI 代理需要 AUTH_SERVICE 验证管理员，并通过 AI_SERVICE 调用 Agent。Nuxt Image Agent 代理需要 AI_SERVICE，旧式图片提交还需要 PROVIDER1_SERVICE。绑定缺失或失败时直接返回错误，不改走 HTTP 地址重试，包括写入可能已提交但响应丢失的情况。非 Cloudflare 本地开发继续使用配置的 HTTP 服务。可运行 pnpm --filter @zship/node10-ai-service test:admin-pages:local 验证编译后的 Admin API 与实际本地服务绑定，并运行 pnpm --filter @zship/web-nuxt test:server 检查 Nuxt 代理回归。这些检查不调用模型，也不替代远端部署验证。

共用 Nuxt 认证代理与 CDN 上传代理在 Cloudflare 环境中同样要求对应服务绑定。密码登录、刷新、Google 和 GitHub 登录不会在绑定响应丢失后改走 HTTP 重发。鉴权服务不可用时保留原会话 Cookie，但响应丢失仍可能意味着上游已轮换刷新凭据。pnpm --filter @zship/node10-ai-service test:nuxt-pages:local 构建 Nuxt API 并连接实际本地平台服务，检查生成、编辑、冷恢复、登录、刷新、上传与鉴权媒体读取。模型推理使用受控响应，测试存储为临时数据。追加 --pages-browser 可在检查通过后启动编译后的完整页面与静态资源；测试账户、媒体路由和清理方式见 Node10 README。实际 OAuth 供应商、公开媒体域名和云端部署仍需单独验证。

模板会将当前 Nuxt 层、应用清单和 UI 默认配置中使用的 Lucide、Simple Icons 字面量图标打入客户端包，生产构建中的上传控件、模型选择器和导航可直接显示这些图标。运行时动态提供的自定义图标名称仍需显式配置打包。

在 Admin 的 AI Gateway > 图片 Agent 中配置对话模型、新任务开关与全局额度，也可直接访问 /zh-CN/ai?tab=image-agent。请选择已启用、Token 定价有效且支持视觉输入和工具调用的模型；模型列表本身不证明其视觉或工具调用质量。这个对话模型与输入区选择的图片模型相互独立，沿用现有 Workers AI 或 OpenAI 兼容网关。保存通过 /api/ai/image-agent/config 一次写入 IMAGE_AGENT_ENABLED、IMAGE_AGENT_MODEL 和 IMAGE_AGENT_LIMITS。已存策略无效时会禁止新任务，可在此页面修复。未配置对话模型时，真实提交会显示图片助手暂不可用；本地 Mock 仍可体验。

管理页可按应用、完整邮箱和状态筛选任务。“需要处理”包含失败任务、等待积分、待付模型费用和图片状态待核实的记录。详情展示固定额度、模型用量、图片操作和事件类型，不返回提示词、凭据、图片 URL 或 Provider 原始响应。admin.provider.read 可查看诊断，admin.provider.write 可保存配置、停止和恢复任务。首次验证须由用户完成；当前恢复功能要求任务未结束，且保留的凭据未过期。关闭新任务不会阻止已接受操作继续结算。

“回复 Token 上限”和“推理强度”配置对话模型，与图片生成参数相互独立。默认每次调用最多输出 1600 Token，推理强度跟随上游默认值。输出上限可设为 256–8192；上游将推理 Token 计入输出用量时，二者共用此额度。仅在上游支持时指定推理强度。保存时在同一策略事务中写入 IMAGE_AGENT_INFERENCE，新任务会固定这些参数，之后修改配置不会改变已接受的任务。提高上限可能增加费用和等待时间。

Admin 图片 Agent 页的“测试模型”通过 Agent 使用的同一套模型适配器，检查图片识别、结构化工具调用和工具结果回传。可以使用当前推理参数测试所选模型而不保存策略；最多调用两次模型，关闭自动重试，上游请求超时与实际 Agent 调用一致，为 120 秒。测试可能产生上游模型用量，但不生成图片、不扣用户积分，仅 admin.provider.write 权限可执行。运行依赖中的“已配置”不代表连接已验证。结果只保留在当前页面，修改模型或推理参数、刷新后清除；这是基础连接与能力检查，不替代实际图片质量验证，也不是持久化的发布批准。本地 Workers AI 绑定仍需具备身份认证的远程推理能力才能通过。

“测试媒体”单独验证参考图存储链路：向配置的 R2 桶写入随机小 PNG，经公开地址核对原始字节后删除测试对象。页面分别显示写入、公开读取和清理结果，并提供失败处理提示。操作需要 Provider 写权限，会产生少量 R2 请求，但不调用模型、不生成图片、不扣用户积分，也不创建用户媒体记录。通过只代表当时 Worker 能访问参考图公开地址；图片 Provider 的交付、模型端访问和视觉质量仍需单独验证。刷新页面会清除结果。Node6 遵守对象缓存策略，诊断文件使用 no-store。可为 image-agent/diagnostics/ 配置较短的 R2 生命周期规则，以清理测试中断遗留的文件。

Agent 回复达到输出上限时，会在执行该条截断回复中的工具调用之前停止任务，保留并结算真实模型用量。此前步骤已生成的图片仍可查看和继续编辑，界面会明确说明回复未完成，可以发送新消息继续。本地可用 ?mock=1&case=workflow-output-limit 体验此状态。

AI SDK Agent 可以直接回答或追问、查看对话图片，并执行 generate_image 或 edit_image。Workflow 等待 Provider 完成后将实际图片结果交回模型，由模型决定结束或在额度内继续调整。图片工具保留用户所选 Provider、模型和设置，来源 ID 只能解析到当前对话图片和本次附件。执行过程展示持久化的步骤和中间图片。纯文字回复不会创建图片任务，也不会显示“没有返回图片”的错误。

对话按所配置模型的 Token 费率单独计费。新调用的正费用按整积分向上取整，与 Node1 账本一致：计算费用为 0.14 积分时实际扣 1 积分，免费模型仍不收费。每步回复和准确的应付金额先保存，再以 image-agent:run:<run-id>:model:<step> 作为 Node1 操作键扣费；新付费任务的余额和预算均至少为 1 积分，D1 在剩余额度不足 1 积分时阻止下一次模型调用。结算重试复用原金额，不重复已完成的推理，未结算的回复不会展示。已结算模型调用按任务和步骤生成唯一的平台用量记录，包含 Token 数和已付积分；Image Agent 消息不会混入普通 AI Chat 历史。默认上限为六个模型步骤、两次图片操作、100 积分和 30 分钟；服务端绝对上限为八步、三次图片操作、1,000 积分和 30 分钟。Admin 可为新任务设置更低上限，已接受任务保留原额度；输入区的积分和操作次数会限制在已配置范围内。图片生成失败沿用 Provider 的退款规则，不退还已完成的对话费用。

新快照固定计费版本 1。此前已接受的快照和已保存的旧回复保留原金额，重试时不会重新定价。历史小数扣费无法在当前仅支持整数的 Node1 账本结算；如待发布环境存在这类记录，须先明确核对账务。pnpm --filter @zship/node10-ai-service test:platform:local 使用实际 node10、Provider1、Node1 Worker 和独立临时 D1/R2 数据执行平台检查，仅外部模型响应受控。

对于已经保存的图片任务，Provider 会先固定失败结果和生成退款金额，再调用 Node1。退款失败或退款响应丢失时保留待处理状态，通过状态查询、已认证回调或 Provider 的五分钟定时恢复任务重试。各路径复用 provider1:failure-refund:<task-id>，保留已收取的审核费用。Agent 显示“正在退回图片积分”，确认结算后才继续最终回复，不重复失败的图片操作。图片操作失败会让整轮任务保留失败状态，同时保留解释文字和此前成功的图片；已完成的对话用量仍然计费。没有固定退款记录的历史失败需要单独核对账务。

新 Provider 任务与固定生成价格先入库，再处理生成扣费。未确认付款的任务不能提交图片；扣费结果不明或支付准入超过两分钟时，会取消原扣费键，仅退回已确认扣除的部分，Node1 阻止该键后续的新扣款。恢复保留原任务 ID，不提交替代图片。企业用量预约通过原身份取消。审核费用仍先于任务创建处理，取得提交资格后上游是否已接单不明，也与尚未提交的支付故障分别处理。

内容审核在扣费前保存审核结果与固定价格，涵盖图片任务创建前就中止的请求。扣费确认丢失时，Agent 显示“正在确认内容审核费用”，等待 Provider 定时恢复原计费操作并更新审核记录。已完成的审核仍收取审核费，不会虚构生成扣费或退款。生成准入过期后，即使旧请求迟到返回也不能生成图片。Admin 将待确认费用单独标记，不显示为零。本地可通过 ?mock=1&case=workflow-review 查看待确认状态与最终说明，第一版图片和草稿都会保留。

企业 Provider 请求在图片接单时仅预约用量，上游最终成功后才提交费用。Provider 先保存成功结果，账本确认后才发布任务成功；响应丢失时通过状态查询、回调或定时任务恢复原操作，不重新生成。竞争的失败回调不能取消已保存的成功，图片转存可在计费后继续等待。企业生成与审核价格均须使用整数积分。历史已提交但生成失败的账单、孤立或小数扣费、永久预约拒绝、上游接单结果不明仍需单独核账，不自动取消已提交账单。

每条消息固定生成参数、有顺序的参考图、对话模型费率和运行额度。Provider 操作键为 image-agent:run:<run-id>:image:<sequence>，网络重试和状态核对复用原身份及 API Key。浏览器通过 node10 查询持久化进度。“停止任务”撤销继续生成的授权，并保留上游已接受任务的结果；断线或补充积分后，“恢复任务”唤醒同一个后台任务。执行凭据按账号与应用加密保存在 Workflow 检查点之外，最长保留一小时用于核对已接受操作，结束后清除。切换 API Key 后不能修改旧任务。此前保存的消息仍沿用原执行路径和操作键。

任务已结束或执行凭据过期后，“核对已有结果”使用当前登录账号的原 API Key 查询原 Provider 操作、结算已保存模型回复，并补齐缺失的执行记录。它不启动推理、不提交图片、不修改原额度，也不重启任务。界面显示待核对图片数量和固定的待付积分，直至核对完成。失败任务保留原终态，恢复出的图片可在对话与素材库中使用。缺少 Provider 明确证据的提交继续标为待核实；丢失的模型响应不能由此操作重建。并发结算和响应丢失测试验证每个已保存模型调用只对应一笔账本操作和一条用量记录。

人物与产品的一致性取决于所选模型。上下文使用最近 24 轮消息和有数量上限的图片目录，包含视觉参考图。上传和生成结果沿用现有 CDN/R2 分发策略，对话鉴权不代表公开 CDN URL 自动成为私有文件。存在运行中 Workflow 消息的对话不能归档；归档已完成对话会隐藏历史和素材条目，不删除文件。最近对话、对话历史和素材库读取分别限制为 100 条记录。本地认证启动、事件、恢复、核对接口及 Workerd 重启测试使用受控模型、Provider 和账本替身。Admin 浏览器测试使用受控 Agent 响应，覆盖桌面和手机明暗主题、配置保存、权限、筛选与任务操作。核对界面测试覆盖等待结果、部分结算后报错、再次核对及桌面和手机明暗主题。标注验证覆盖编辑、原图与指引图分离、保存重开、触屏、取消与上传重试。正式发布前仍需完成真实 Provider 验证、完整图片来源关系、持久化媒体保障，以及发布审计。

新建 Workflow 还需要 Provider 迁移 0027_required_image_delivery.sql。请开启文件转存，配置能实际读取目标桶的公开地址、允许下载的上游 HTTPS 来源域名，以及从映射后响应中选取图片的规则。Provider 当前绑定 zship-provider1 桶，绑定其他桶的 CDN 入口不能读取这些结果。缺少存储配置时，会在对话模型运行前阻止授权。生成完成但图片仍在转存时，时间线显示“正在保存生成的图片”；只有全部保存成功后，结果才交给 Agent。文件重试保留原任务与费用，不重新生成；已结束任务可通过核对继续保存。此前已接受的任务保留原交付策略。完整历史来源关系、真实模型执行和发布验证仍是独立的上线要求。

参考图存储

真实模式会先转存图片链接，再将其加入参考图。node10 的 IMAGE_AGENT_MEDIA R2 绑定使用现有 zship-cdn 桶，文件路径位于 image-agent/references/ 下。IMAGE_AGENT_MEDIA_PUBLIC_URL 必须指向实际提供这个桶内容的公开地址。使用 Node6 Worker 的文件路由时，基础地址须包含 /file；直接绑定 R2 的自定义域名使用根路径。两个 Worker 必须绑定同一个桶。IMAGE_AGENT_MEDIA_ALLOWED_ORIGINS 是允许下载的 HTTPS 来源 JSON 数组，例如 ["https://images.example.com"]，最多 32 个；公开存储地址的来源也默认允许。每次重定向都重新检查来源，不向第三方发送用户凭据。下载限时 20 秒，单图不超过 10 MB、3200 万像素，支持 PNG、JPEG、WebP、GIF 和 AVIF。实际模型可接收的图片格式仍由所选上游模型决定。

POST /ai/image-agent/media/import 和 GET /ai/image-agent/media/:id/content 沿用 Node1 API Key 鉴权，按应用与账户校验归属。D1 固定导入身份与文件清单，R2 使用条件写入；即使检查点保存失败或上游链接过期，重试也可恢复已保存的图片。存储记录和对象元数据仅保留原始签名链接的哈希。每个账户、应用每小时最多创建 30 条导入记录，总共 500 条，最多同时进行两次转存；失败记录也计入限额。重复链接沿用已保存的快照。公开图片地址仍遵循平台 CDN 的公开访问策略。

链接面板在失败时保留地址，支持取消，关闭面板后仍可继续导入。标注编辑器通过 Nuxt 的鉴权同源代理读取已保存字节。新建 Workflow 在调用模型前，也会转存有限图片目录中的全部图片及其标注指引：基于最近 24 轮消息，保留最近 48 个目录条目和当前附件。执行过程会显示参考图准备状态。每次导入有可恢复的检查点，独立且不可变的 D1 上下文固定存储地址、图片编号和附件顺序。存储失败或取消后不会开始模型调用或图片生成。后台转存沿用相同导入限额和来源白名单，包括此前尚未转存的旧图片。

Agent 查看历史原图时可同时查看标注指引，且明确标为过去的上下文；指引图不会进入编辑工具的原图目录。此前已接受的任务保持原来的重放行为，原始消息记录不会改写。历史、素材库和任务读取会将已保存的参考图、指引图和结果展示为存储地址。首次转存前就已过期的文件，无法仅凭链接恢复。本地验证覆盖真实 Nuxt、node10、Node1、D1、R2 和一张 ZShip 公开图片；受控 Workerd 测试还验证了参考图、指引图和固定上下文在服务重启后保持一致，未调用付费模型。

图片版本

Workflow 结果在后续编辑中保留任务、操作和图片编号。可选的有序 reference_ids 在消息接受时校验每个版本对应的 URL 和账户归属，接受后不可修改。新上下文为上传参考图分配稳定的媒体编号，生成版本保留原操作编号。GET /ai/image-agent/versions/:id 根据现有不可变操作记录返回当前版本与有序来源。Nuxt 预览中的“来源图片”支持逐级查看父版本，也支持多张来源图合成；本地 composition 案例可直接体验，不上传或调用模型。

归档会隐藏对话和素材库条目，已有引用仍可读取本账户的图片来源。早期 Workflow 的编号会尽可能通过已接受的目录还原；由旧客户端自行同步的任务缺少权威操作记录，不会冒充经过核实的 Workflow 来源。真实模型与 Provider 联调以及发布审计仍需完成。

本地 Mock 案例

在 nuxt dev 中打开 /dashboard/image-agent?mock=1。页面案例菜单包含单张成功、多轮改图（默认）、一次返回多张、生成中、失败重试、中断后恢复、成功但无图片、积分不足和空白对话。也可以直接通过 ?mock=1&case=failed 分享具体案例。

Mock 对话、模型、积分、上传和任务响应仅存在于当前页面实例中，不调用生成、扣费、Turnstile 或 CDN 上传接口；应用原有的登录状态检查仍可能执行。上传参考图使用浏览器对象 URL。发送后先显示生成中，下次轮询返回图片；“恢复任务”可完成预置的生成中案例，“重试”可恢复失败请求并重新提交。重命名、归档、素材库、预览和下载均可操作样例记录。刷新或切换案例会重置数据。图片是随模板提供的演示素材，不是模型实际生成结果。生产构建忽略 mock=1，仍执行正常鉴权和生成流程。

案例参数：success、edits、annotated、multiple、pending、failed、prepared、no-output、insufficient、empty、clarify、discussion、planning、agent-error。

annotated 预置人像原图、带可编辑矩形和箭头的背景指引、修改备注及暖色结果样例。将原图用作参考图后可恢复已有标注继续修改，编辑工具仍以不含标记的原图作为参考。

后台任务案例：workflow、workflow-delivery、workflow-credits、workflow-completed、workflow-cancelled，展示同一套执行过程、中间图片、生成结果保存中、停止和积分等待界面。运行中案例点击“恢复任务”后完成；等待积分案例需要先“补充模拟积分”。停止后保留第一版图片。这些案例仅在本地模拟任务状态，不启动 Cloudflare Workflow。

workflow-recovery 预置一个已中断任务，保留第一张图，另有一张图片待核对和 1 模拟积分待结算。“核对已有结果”补回第二张图及执行记录，仅结算一次模拟积分，原任务仍保留失败终态，不发起新生成。

workflow-refund 展示图片调整失败后等待退款的过程。点击“恢复任务”会确认模拟退款，保留第一张图片，并以失败状态结束任务、展示解释回复。此过程仅退回一次 4 模拟图片积分，并收取一次最终回复的 1 模拟积分。

clarify 展示追问，补充下一条消息后进入演示图片任务；discussion 只返回文字，不生成新图片；planning 和 agent-error 可通过回复操作恢复。这些是固定案例数据，不是本地大模型推理。新一轮 Mock 对话消耗 1 模拟积分，图片任务另按演示模型计费。

通过 ?mock=1&case=insufficient 可直接查看输入区上方的积分不足提示，显示当前余额 0 和所选模型的预计消耗。点击“补充模拟积分”会增加 240 本地积分，保留草稿并允许继续生成，不会发起支付请求。真实模式提供新标签页打开价格页面和刷新余额的入口；提交被拒绝时保留草稿。

产品上应避免的做法

不要在用户还没理解产品前，就先要求他们粘贴手动 API Key
不要把 Chat 与结构化生成塞进语义重复的界面；每个入口应对应明确任务
不要把积分、AI 生成与账户状态拆成彼此孤立的页面，却又没有默认引导路径