工程与预览契约#

存储#

仓库标识 story.repository.json，章节目录固定结构：

text

chapters/<folder>/
  story.project.json
  variables.json
  story/chapter.json
  story/nodes/<nodeId>.json
  editor/layout.json
  assets/<media> 与 <media>.meta

入口格式 story-studio/chapter、schemaVersion=2。story.project.json 保存 projectId、章节信息；每个节点文件为 {type, node}；story/chapter.json 保存入口、节点顺序等。editor/layout.json 保存 positions、behaviors、memories，不能只搬走节点忽略这些向导元数据。空目录可能由 .gitkeep 保留。

素材字段保存 asset://<guid>，meta 包括 guid、kind、sha256、schemaVersion。GUID 按工程隔离；哈希用于同章重复导入检查。移动/替换保持 GUID，不能用新文件名替换所有引用。JSON 为 UTF-8/LF、键稳定排序，数组路由顺序保留含义。

工具入口#

发行包目录中有 studio.py（输出 JSON）。示例参数均需替换为实际值：

python studio.py --workspace "REPO_PATH" list
python studio.py --workspace "REPO_PATH" inspect "PROJECT_ID"
python studio.py --workspace "REPO_PATH" validate "PROJECT_ID"
python studio.py --workspace "REPO_PATH" new tutorial-001 --name "第一章 · 从零练习"
python studio.py --workspace "REPO_PATH" import-assets "PROJECT_ID" "MEDIA_PATH"
python studio.py --workspace "REPO_PATH" move-asset "PROJECT_ID" "ASSET_GUID" videos/opening.mp4
python studio.py --workspace "REPO_PATH" import-project "CHAPTER_DIRECTORY" --folder tutorial-001-copy --fork
python studio.py --workspace "REPO_PATH" save "DRAFT_JSON"

save 输入为 inspect 的完整模型，保留读取时 revision；过期会拒绝。不要把命令输出存为含 PowerShell UTF-16 默认编码的文件后误当 UTF-8 JSON；用明确 UTF-8 的文件写入方式。

0.4 UI 使用浏览器本地仓库层，HTTP API 已移除。CLI 直接操作本机文件，不能读取 IndexedDB：先导出工程包并解压。浏览器与 CLI revision 算法不同，修改前在所用工具重新读取，不跨工具复用版本号；勿同时写同一章节。网站访问控制由 NPM 管理。

向导映射#

向导	当前生成内容	验证
动作	点击 choice、失败逻辑 video、宿主进入时清动作变量	窗口点击成功；未点片尾失败；重试重置
奖励	key=0 可领取 choice；key>=1 已领取 choice；成功设置 key 和积分	广告前不发奖；完成一次；重复不加
登记回忆	标记入口 isJumpPoint/jumpPointId；editor.memories；可选授予 effect 和提示 choice	广告解锁关闭 grant；提示不应改变奖励规则
回忆录卡片	锁定/解锁互斥 choices + jumpNode	跨章 ID 与跳转点正确；锁定禁用
返回	isReturnButton choice	从卡片进入再返回来源；多段遵循上一视频链
重试	失败片尾 choice 指向训练，并取消失败结局	再次训练仍可成功或失败

当前 conditions 的 operation 0 表示等于，4 表示大于等于；effects 的 0 表示赋值，1 表示加。不要把条件操作编号与数值效果编号混为一套。持久奖励使用 persistenceType=1。需要生成低层节点时以安装版 core.js/behaviors.js 为准并保留完整默认字段。

保存和验收边界#

修改默认自动保存（约 1.3 秒），也可手工保存；确认页头保存状态。浏览器选择工程、主题、列宽与预览存档不属于章节剧情配置。

预览变量存储 key 为 story-studio.preview.v3，同一网站来源共享，不是按仓库 ID 隔离。重置入口在“工程变量 / 预览状态 → 试走存档”。动作的每次重置与奖励持久化是两回事。

运行导出会把素材引用转为文件路径；正常工程文件仍保留 asset://。项目包包含一章所有文件，可导入；runtime 包是客户端输入，不可当目录工程导入。

GUI 测试可使用当前环境可用的浏览器工具；若没有浏览器工具，可以执行 CLI 校验并提供人工验收步骤，但不能声称交互已亲测。