# 工程与预览契约

## 存储

仓库标识 `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）。示例参数均需替换为实际值：

```sh
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 校验并提供人工验收步骤，但不能声称交互已亲测。