__kinora 接口

window.__kinora 是调试控制台 / e2e / 外部脚本使用的完整 API。所有方法返回 { ok, ... } 或 { ok:false, code, message }——不抛异常，不写一半。

分组速查

组	常用方法
shots	list / get / addFromSelection / addFromViewport / addFromRegion / go / duplicate / remove / setTiming / serialize
shots.framing	enter / pan / zoom / save / confirm / decline / cancel / state
steps	next / replay / addStep / addStep0 / remove / duplicate / move / rename / update / setInitialVisibility / selectShot
session	get / enter / exit / resetAll / mutate / playback
rec	state / start / pause / resume / stop / record / dismiss / saveCopyTo / reRecord / exportMp4 / exportState / control
audio	mix / setMicOn / setVoMode / setVoSource / playVo / pauseVo / setBgmSource / setBgmOn / setVolumes / startSkewProbe
media	get / set / seek
stage	aspect / aspectSpec / setAspect / previewAspect / safeGuides / setSafeGuides
grid	get / set
styles	meta / setFontSizePx / setFillColor / setStrokeColor / setCharColorMark / setCropAspect …
shapes	get / update
sandbox	open / close / state
顶层	saveProjectTo / openProjectFrom / snapshot / snapshotForSave / restore / validate / plan / locks

三个守门员

写之前先查锁，省得对着报错猜：

window.__kinora.locks()
// → { recEditLocked, presentationFrozen, dirty }

• recEditLocked：录制中，改工程/取景会被拒（edit-locked-during-recording）
• presentationFrozen：演示中，改画布/工程被拒（presentation-frozen）
• dirty：有未保存改动（打开其他工程前会先弹确认）

validate(projectJson) 做整包校验不加载；plan(projectJson) 做时间线预算。

人类会怎么想

给脚本/AI 用的接口，第一要求是「行为和按钮一一对应」——addFromSelection 就是底栏「添加镜头」，rec.start 就是「开始录制」，没有第二条隐藏路径。命名直白、失败给 code+message，对自动化友好；对人来说唯一要学的是「所有返回都是 result 对象」这个约定。