Studio 技术接入

来源：oceanway-drama 仓库 docs/integration/studio.md，提交 45524ef。2026-10-01 补充新架构映射；下方固定提交的实现入口描述原型，不代表最终 Next.js 接口。已冻结的 Core/Contracts 不作为迁移依赖。

产品规则见标准 1.7.0，模块职责见架构，运行命令见本地运行。本说明面向产品迁移开发者。@manju/contracts 0.4.0 是原型仓内业务契约，不是已冻结的 oceanway-contracts，也不是新平台的集成契约。

新架构接入映射

原型依赖	新归属	迁移约束
Identity / IAM	平台会话、用户和产品角色	产品向平台确认身份；不自行注册用户或授予平台权限
Project、成员能力	Drama 产品领域	保存平台用户引用并校验项目访问；首期不引入组织多人协作服务
AssetVersion、File	产品工程共用媒体模块	维持来源、版本、引用保护与授权读取；不恢复 Core 文件授权
Provider 端口	产品调用平台模型 API 的适配层	保留输入快照与业务任务；凭据和供应路由不进入产品
reserve / settle / release	平台唯一账务服务	关联授权 `operation_id`，使用原价格快照；模型消费不在 Drama 再扣一次
Run / Task / Attempt、队列	产品业务任务与共用 Worker；平台/网关分别持有客户/供应任务	持久关联，未知结果先查询，禁止多层重复付费创建
Studio Host / Canvas	同一产品工程的共用画布	显式校验产品、用户、来源与素材引用，不因同仓放开访问

以上是目标映射，尚未完成迁移或联调。原型中 Provider、File 和独立 Node 服务仅用于原实现验收；新后端按 Next.js + PostgreSQL 重写，参考下方行为约束和原型证据，不照搬旧部署拓扑。公共能力见共用任务与媒体，平台凭据见身份与权限。

接入入口

入口	内容
OpenAPI	当前 HTTP 路径、请求与响应
路由清单	服务实际注册的方法和路径
契约覆盖	源码指纹、声明来源与覆盖边界
正式契约	公开类型和传输语义
HTTP 客户端	调用、下载、SSE 与精确重放
隔离客户端示例	独立 File/HTTP 接手演练

接入步骤：配置可信身份和数据适配器，接入 Provider 与共享媒体，接入预算/审计/队列，再验证可靠提交、候选登记、播放与下载。 Studio Canvas 与助手会话可分别绑定。各项联调结果在验收状态记录。

适配职责

能力	工作台提供	接入方提供
身份与项目	项目访问、命令和结果登记校验	平台提供身份/角色，产品工程提供项目，不新增平台组织成员服务
内容与资产	文档、修订、范围、版本与血缘	产品工程共用素材版本与资源访问
模型	输入快照、业务任务、结果登记	平台模型目录与受限调用，网关执行供应请求
预算与审计	请求及 Run 关联、拒绝与恢复	平台预留/结算/释放与资金审计，产品维护业务审计
媒体与任务	完整性检查、候选、授权播放和导出	产品工程对象存储、授权链接及 Worker，与平台任务持久关联
Canvas	Handoff、输入版本、返回目标与候选校验	共用画布、产品授权和真实往返

当前本地 Provider 生成有明确标识的测试媒体，沿用完整任务与候选链。视频文件内嵌音频随媒体保留。用户选择视频后下载素材，在外部工具完成最终剪辑。

文档与版本

WorkbenchDocument = { schemaVersion: 1, content: { type: "doc", content: DocumentNode[] } }。文档内核统一校验、序列化、范围替换与指纹。适配器保留完整文档和派生文本；不支持的结构给出明确校验错误。

对象	正式保存字段与指纹
剧本及生产准备	`episodes[].document` 和 `text`，共用 `saveScriptDraft`；`fingerprint` 表示语义，`contentFingerprint` 覆盖完整内容
分镜	`content.document` 为正文，`prompt.document` 为生成提示词；`documentFingerprint` 覆盖完整文档，`contentFingerprint` 覆盖文本
提示词库	顶层 `document` 与 `prompt` 同存，修订、复制、默认项和恢复均保留格式
视频要求	`settings.promptDocument` 与统一序列化的 `settings.prompt`
视频来源	`shots` 或 `documentRange` 二选一；范围携带偏移、精确引用、文档指纹和可选有序子 `ranges`

文档来源快照 schema 2 固定正文、范围、文档修订、分镜修订与输入指纹，使用稳定键序列化计算哈希。schema 1 记录按其原格式和哈希读取。生成及迟到结果登记先验证原快照完整性，再校验当前实际输入与版本。纯样式变化按实际模型输入判定影响。

change-source.promptMode 为 auto | sync-latest | keep-current。服务产生 promptProvenance 和 promptState；自动描述可同步，手改描述由用户明确决定。无可信基线的非空描述按手改内容保护，历史任务及候选保留原指纹。

PostgreSQL 提示词通过内部 PersistedPromptUsage 的 usage.document 保存富文档，公共客户端仍发送顶层 document。存储映射负责规范化、校验和读回；修订、复制、默认选择、归档与恢复均保留该载体。 File、SQL mock 与独立 PostgreSQL 分别验证往返。

可靠提交

宿主保存 requestId、幂等身份、预期修订及完整 payload 后再发送。命令 requestId 与响应 X-Request-ID 的链路追踪身份不同；原始来源 PUT 以请求 X-Request-ID 承载上传命令身份，响应追踪仍独立。

成功响应与领域回执匹配后才解除本地恢复记录。超时、断网、响应丢失和协议错误保留原操作，查询或精确重放确认结果。若回执之后已有新修订，保留本地输入并呈现冲突。错误传递错误码、请求 ID、可重试性及可用的冲突/字段信息，页面使用可执行中文提示。

SSE 提供事件游标与快照；断线后按游标恢复并查询权威 Run。停止 HTTP 等待与取消持久任务是两个动作，任务取消通过独立命令完成。

当前会话绑定为 assistantSurface.conversation = { available: true, send(request) }。 send 接收固定 requestId、项目、集数、页面、修订、sourceText、content 和 contexts，返回 { content: string }。聊天仅呈现绑定返回的文字。未配置时保留消息草稿和引用，发送不可用。

失败或刷新保留原请求身份；成功只清理仍与本次请求一致的草稿和引用。批注使用稳定 ID 与 editorAnchor，事务映射状态为 current、changed 或 detached。脱离位置的批注保留原引用，避免同名文字误绑定。内容修改建议接入使用现有显式应用、权限、版本和修订命令，聊天回复与保存分别处理。

Canvas

能力可用时显示入口。Handoff 固定项目、集数、片段、输入版本与返回目标；宿主按 Handoff ID 持久去重。返回时再次校验真实身份、权限、来源、共享资产和媒体，登记视频候选，正式选择仍由用户完成。工作台领域状态由现有服务持有，宿主绑定使用Canvas 服务。

视频导出

当前 GET 入口为：

/api/manju/projects/:id/episodes/:episodeId/videos/delivery
/api/manju/projects/:id/episodes/:episodeId/videos/delivery/manifest
/api/manju/projects/:id/episodes/:episodeId/videos/delivery/export

导出返回按视频段顺序排列的 JSON 素材清单。每项包含 segmentId、order、title、 revisionId、candidateId、mediaPath、storageKey、mimeType、bytes 和 registration。通过修订及候选身份可继续查询生产来源。单段下载返回经授权的原媒体字节；验收对下载字节计算哈希。媒体 GET 支持范围响应，HEAD 按传输协议返回元数据。

接手验证

先运行 npm run check、npm run test:browser:current 和 npm run test:clean-start。数据库环境具备后运行 npm run test:postgres，再对真实适配器执行权限撤销、预算拒绝、任务取消、未知回执、候选登记及下载哈希联调。迁移前清点数据并备份，保持历史 schema 和指纹的兼容读取。当前完成范围与外部待接入项统一见验收状态。

Studio 技术接入

On this page