💡 怎么开局：看到心仪的世界？直接发一句：「开局，舞厅大班与乐台后台 压力模式」 或 「开局，赛博街区」，AI 会自动加载对应风土与专属人物关系。

普通游玩不需要运行脚本。以下命令适合需要固定随机结果、生成转折方向、查看状态或检查内容的场景。请在仓库根目录执行，先装依赖：

# 依赖只有 PyYAML（Python 3.10+）
python -m pip install -r requirements.txt

# 维护和运行测试额外安装
python -m pip install -r requirements-dev.txt

# 全自动开局：一次生成可开场的 v3 状态与开局简报（「开局」命令的后端）
python scripts/build_opening.py --complete --opening-mode daily --seed 42
# 压力开局将 daily 替换为 pressure；省略模式只返回选择提示，不写状态。
# 默认 auto 只选审查有效的框架；没有合格框架时报错，不隐式回退 legacy 旧池。
# 需要定向检查某个框架时显式追加 --framework <框架名>。

# 生成 2～3 个中期转折方向（压力模式首次跨天或玩家明确要求时）
python scripts/roll_opening.py --twist --seed 42

# 人话状态视图（「状态」命令的后端）
python scripts/live_slice.py --session <session> --human

# 后台切片与定向事件查询（session 来自成功开局 brief）
python scripts/live_slice.py --session <session> --format json
python scripts/live_slice.py --session <session> --event <ID>

# 明确绑定本会话，并校验上一拍看到的 token
python scripts/commit_turn.py --session <session> --expected-state-token <state_token> --patch '<json>'

# 校验 YAML 存档的结构和状态
python scripts/validate_state.py path/to/save.yaml

# 列出命名存档 / 校验并查看某个命名存档
python scripts/manage_saves.py list
python scripts/manage_saves.py load main

build_opening.py 支持 --framework auto|框架名称 选择世界框架（不传该参数视同 auto），支持 --lock 字段=值 锁定特定设定（可重复）、--force-table 仅用自带素材、--all-custom 配合 --custom KEY=VALUE 自拟核心设定。存档由 manage_saves.py 原子写入：每个存档目录包含 state.yaml（v3 叙事状态）与 manifest.yaml（创建/更新时间），覆盖保存需携带载入时记录的 --expected-updated-at，不一致即拒绝且不自动合并——按提示读取最新版本、另存为其他名称或取消。

--all-custom 不解除框架约束：默认 auto 下，自拟核心规则、时代等若与所有已审框架都不兼容，开局会拒绝，不会静默回退。独立旧池入口（legacy）已随阶段 4 拆除，--framework legacy 会被直接拒绝；需要自由表外世界时用 --all-custom 并补齐所需 --custom KEY=VALUE，这也不绕过日常模式限制或状态校验。

新局默认工作档是唯一的 saves/sessions/<uuid>/state.yaml，可用 --session ID 显式指定稳定会话。后台返回 session/state_path/state_token，token 是文件原始字节 SHA256，不进 v3 状态。提交必须显式指定 --session 或 --state；前者必须携带 token，旧路径可显式 --state saves/current_state.yaml 接续。保留 --out、--working、--no-working 工件用法，细节见 开局流程。输出已存在或状态写入失败不污染开局历史。

命名槽与工作会话分开；load CLI 只返回 manifest，宿主用 SaveStore.load_slot 的同锁快照建立会话副本，详见 载入流程。槽位解析和 checksum 校验使用同一字节快照；保存失败恢复原有效文件对，初始化失败不留可用槽。终态事件保留在 events 中，不做物理归档；新解决/取消结果通过 event_changes 和 outcome 返回，旧事件可用 live_slice.py --event 定向读取。

维护日常顺序是 编辑 authoring → build_frameworks --write → sync_governance --write → qa：

python scripts/build_frameworks.py --write
python scripts/sync_governance.py --write
python scripts/qa.py --changed

qa.py --framework <名称>、--material <稳定ID> 用于定向验证；--full 做全量结构与回归检查；--smoke 跳过穷举型慢测试（全框架×双模式、多种子多样性等 slow 标记项）与纯报告性的分布分析，适合提交前快速把关，CI 的 push/PR 即走此档（tag 与发布门禁仍跑 --full）；--full --release 另核验当前语义审查与实玩证据；--full --update-fingerprint 只在检查通过且数据未再次变化时更新指纹。--plan 只查看计划。构建和同步不会代替人工审查。脚本自身已按 UTF-8 处理输出，裸跑 python scripts/<工具>.py 无需再带 -X utf8。

单框架源或 review 连同生成聚合、registry、指纹的改动，在 --changed 中仍按框架抽样；其他共享改动可扩大范围。--material 遇框架 ID 同样选择对应框架。全量 QA 的分布分析运行 analyze_content.py --samples 1000，默认是 --framework auto --opening-mode pressure；legacy 独立旧池入口已拆除，分布分析不再有该口径，抽查历史对照只能读 saves/legacy/ 只读存档。重复候选由 check_duplicates.py 对照人工记录核验，不自动删重；当前保留项与人物资源复用的计数口径见 加内容。

结构通过不等于语义通过，不等于 416 条实玩响应已完成。 实玩门槛为 52 框架 × daily/pressure × 新局及 3 次续写，证据与独立评分由 playtest_report.py 检查。实玩验收尺度为成人张力叙事级：情节张力全放开、文字保持叙事级不露骨（maintenance/baseline.yaml scope: adult_tension_narrative）。逐回合按六维（世界辨识度、人物可信度、选择意义、后果连续性、表达自然度、张力浓度）各 0–2 分评分，最低回合总分至少 9。run_playtest.py --framework <名称> 必须显式调用，会消耗模型额度；默认 QA 不会自动调用它。未跑、缺评分或来源哈希过期时如实报告，不用内存开局或单测数充当实玩完成数。

日常不实玩、发布才实玩。 日常迭代只跑静态与指纹：python -X utf8 scripts/qa.py --full --update-fingerprint（零模型调用）。素材更新后 maintenance/playtests/ 里 source_hash 失配的旧证据是预期状态，不修、不补、不重跑。实玩只在用户明确说「发布」时进行，由 scripts/release_playtest.py 编排既有命令并只补跑失配框架——哈希未变的框架保留旧证据；完成判据是 python -X utf8 scripts/qa.py --full --release 通过。发布前先跑 --dry-run 看范围与用量（不调用模型、不移动文件）。细节见 加内容 第 2 节与第 15 节。

📁 仓库文件结构

职责导航见 素材架构，L0-L3 扩充、审查和有证据的直接清理见 加内容。maintenance/data_manifest.yaml 管文件职责与依赖，maintenance/core_review_decisions.yaml 管核心池人工处置，maintenance/framework_reviews/*.yaml 管框架审查。冻结整节的字节哈希须与 maintenance/baseline.yaml 一致；历史记录见 PROGRESS.md，不当作当前验收证明。