导出与部署契约#
导出入口#
UI：“导出剧情”→“客户端剧情包”→勾“客户端包包含引用的媒体”→生成并下载。CLI 在编辑器安装目录运行：
python studio.py --workspace "REPO_PATH" validate "PROJECT_ID"
python studio.py --workspace "REPO_PATH" export "PROJECT_ID" --kind runtime输出包括 absolutePath；此可选 CLI 的结果保存在本机仓库 .studio/exports/；0.4 浏览器导出直接下载 / 写入所选 ZIP，服务器不留存。--config-only 只生成配置，已有媒体必须真实存在，不能用于首次全量交付。--kind project 导出一个章节的可编辑目录，不自动捆绑其他章节源工程。
源码 src/repository.py 的 dependencies/export 是当前权威：依赖按 jumpNodes 的跨章引用递归收集，同名变量定义不一致、缺失素材、无入口或缺失跳转点会阻止 runtime 导出。
输出路径#
| 内容 | ZIP 内路径 |
|---|---|
| 清单 | manifest.json，format=story-studio/runtime-export，chapterIds、includeMedia、editorVersion |
| 局部章节列表 | StreamingAssets/GameProduceFiles/Configs/ChapterList.json |
| 各章配置 | StreamingAssets/GameProduceFiles/Configs/ChaptersData/<chapterId>.json |
| 合并变量数组 | StreamingAssets/GameProduceFiles/Configs/Variables/Variables.json |
| 普通媒体 | StreamingAssets/GameProduceFiles/EditoData/Chapters/<chapterId>/<guid>.<ext> |
| 封面 | StreamingAssets/GameProduceFiles/GameResources/stories/ChapterImages/ChapterThumbnails/<chapterId>_chapterthumbnails.<ext> |
保留 EditoData 拼写和小写 stories。工程内相同 GUID 同时用作封面和剧情图片时，导出把相关引用都映射到该规范封面路径，只输出一份。不要再手工补一份旧 GUID 路径当作正确修复。
当前客户端优先探测 PNG 封面，正式封面优先真正 PNG 文件。导出保留其他图片原编码和扩展名；只改后缀不是转码。thumbnailPath 和 jsonFilePath 以 GameProduceFiles/... 开头，运行时内容根路径另加一次。
全局配置合并#
导出的 ChapterList 是 {"chapters":[...]}，仅包含本次依赖闭包。获取服务器完整版本，以 chapterId 为键更新明确发布的条目，追加新章，保留原列表排序及无关条目、顶层设置。对于同 ID 的已发布条目，保留原有未知字段并检查其意义；当前导出不带 packToLocal，不应为远程新章随意加 true。
Variables 导出为数组，以 name 去重。线上若使用对象包裹变量数组，保留实际结构；相同名称、不同定义是设计冲突，需确认默认值/范围及已有存档影响，不能简单选新值覆盖。
媒体引用静态验收时，配置相对路径 R 对应 ZIP StreamingAssets/R，服务器 <内容根>/R。含媒体包里实际文件必须存在且路径区分大小写。config-only 则报告依赖既有媒体的假设，并按已有环境验证。
当前站点背景（不是通用默认目标）#
此前用户手工部署站点：https://renzhe2.lp20.cn。用户提供的内容根为 /home/ubuntu/nginx/website/renzhe2/remote/StreamingAssets/。URL 前缀为 /StreamingAssets/，URL 不需要包含文件系统中的 remote。
历史章 ID 为 chapter-001-restore-test 和 memory-album；新练习使用自己的实际 ID。这些信息仅帮助识别已知环境，不构成未来所有任务的上传授权，也不替代当前配置检查。
上传顺序通常是媒体→章节/变量→章节列表，保持其他文件；已有版本目录切换机制时可按环境统一切换。准备旧文件备份和回滚清单。若旧新版同路径媒体内容不同，逐文件覆盖会出现混合版本窗口，报告这一风险并采用环境支持的发布机制。
典型验证#
- 章节可见需要新列表实际被读取，isHidden、isLocked、requiredChapterIds 等符合预期。前端缓存和 CDN 可保留旧文件。
- 404：核对完整 URL、大小写、章节 ID、扩展名、是否漏传媒体、StreamingAssets 是否重复一层。
- 200 不能播放：响应 Content-Type/内容是否真实媒体，文件是否完整，视频编码与 Range 服务是否兼容。
- 回忆锁定：奖励 key、登记 key、卡片条件及线上变量定义应一致；用户游戏存档和编辑器试走独立。
- 返回异常：必须从回忆录卡片进入回放来测返回来源；多段回放遵循上一视频链。
- 真广告、真实用户持久化没有测试时明确列为未测，不能凭模拟广告完成推断上线可用。