@lingjingai/scriptctl 0.49.15 → 0.50.0

package/skills/scriptctl/references/atomic-write-workflow.md

@@ -1,176 +0,0 @@
-# 从零原子写 — 资产先行，按真实场界写正文
-
-适用：**没有现成剧本文本**，从零写（手里只有题材 / 灵感 / 集纲）。
-
-核心理念：**写手是你**。你自己想好每一句正文，用原子能力把它灌进结构化剧本里。scriptctl 负责「合法的骨架 + 引用完整性 + 校验」，不负责「写得好不好」。
-
-人物、路人群体、地点粒度、门口跨空间、蒙太奇、对白、Action 和场内状态变化统一执行 [production-writing-standard.md](production-writing-standard.md)。
-
----
-
-## 端到端流程
-
-```
-create（空白剧本，既有剧本略过）
-  → worldview                              设世界观
-  → 资产批次
-      add-actor / add-location / add-prop 注册或完善资产
-      state-rename / state-add / describe 定义默认与持久视觉状态
-      do assets.txt --apply → 读回资产与 states
-  → 正文批次
-      add-episode / synopsis               建分集与梗概
-      insert <ep> --location               仅在真实场界处建 scene
-      scene-ref --state                    绑定本场全部资产与实际 state
-      insert <ep/scn> --type ...           按 action 批次连续写正文
-  → scenes / actions / validate               收尾自查
-  → publish                                   入库（沙箱必做）
-```
-
-> 发声源写在**对白行内联**（`dialogue <at> --actor/--kind`，或 `insert --actor/--kind`）；造型挂在**场景 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`）。同一人物需要多份引用时用 `--append` 追加，用 `--occurrence <n>` 定位第 n 份。正文插入前，本场必须已有地点，并且本场全部地点/人物/道具引用都绑定已建立的 state。空镜、环境动作或非角色发声场可以没有人物引用。
-
-资产/分集/场景的 id **自动按序分配**：第一个 actor 是 `act_001`、location 是 `loc_001`、prop 是 `prp_001`、episode 是 `ep_001`、它下面第一场是 `scn_001`……所以你能在后续命令里直接引用这些可预测的 id（也可以 `--id` 显式指定）。
-
----
-
-## 两种写法
-
-### A. 增量（少量、边想边写）：逐条原子 verb
-
-```bash
-scriptctl create --title "夏夜便利店"
-scriptctl worldview 现代
-scriptctl add-actor 林夏 --role 主角 --description "高三女生，沉默寡言"
-scriptctl add-actor 陈默 --role 配角 --description "便利店夜班店员"
-scriptctl add-location 便利店 --description "24h 便利店，冷白光"
-scriptctl state-rename actor:act_001/default "平日造型"
-scriptctl describe actor:act_001/default "整洁校服，黑色长发"
-scriptctl state-rename actor:act_002/default "夜班造型"
-scriptctl describe actor:act_002/default "便利店制服，胸前佩戴工牌"
-scriptctl state-rename location:loc_001/default "常态"
-scriptctl describe location:loc_001/default "冷白灯全部亮起"
-scriptctl add-episode --title "第一集：相遇"
-scriptctl synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
-scriptctl synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
-scriptctl insert ep_001 --location loc_001 --time night --space interior   # → scn_001
-scriptctl scene-ref ep_001/scn_001 location:loc_001 --state default
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state default
-scriptctl scene-ref ep_001/scn_001 actor:act_002 --state default
-scriptctl insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店，浑身湿透。" --emotion "狼狈"
-scriptctl insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
-scriptctl insert ep_001/scn_001 --type inner_thought --content "陈默又出现了。" --actor act_001
-scriptctl validate
-```
-
-同一人物在本场需要第二份参考时，继续追加而不是新建 actor：
-
-```bash
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state st_rain --append
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state default --occurrence 2
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --remove --occurrence 2
-```
-
-### B. 整集 / 整本（推荐）：资产与正文分两段 `do`
-
-一集几十个 action 用 `do` 批量写入。先独立落盘资产批次，读回自动分配的 id；再用正文批次建集、按真实场界建 scene、绑定 state 并写 action。这两次落盘让宿主先展示人物、地点、道具及状态，再展示正文。
-
-```bash
-scriptctl create --title "夏夜便利店"   # 先有空白剧本
-scriptctl do assets.txt                  # 资产批次 dry-run
-scriptctl do assets.txt --apply          # 先落盘资产与 states
-scriptctl actors                         # 读回资产 id
-scriptctl locations
-scriptctl props
-scriptctl states act_001                 # 逐个确认 state id / 名称 / 描述
-scriptctl states loc_001
-scriptctl states prp_001
-scriptctl do ep01.txt                    # 正文批次 dry-run
-scriptctl do ep01.txt --apply            # 再落盘场景与正文
-```
-
-`assets.txt` 先注册资产与持久视觉状态：
-
-```
-worldview 现代
-add-actor 林夏 --role 主角 --description "高三女生，沉默寡言"
-add-actor 陈默 --role 配角 --description "便利店夜班店员"
-add-location 便利店 --description "24h 便利店，冷白光"
-add-prop 黑伞 --description "林夏随身携带的旧黑伞"
-state-rename actor:act_001/default "平日造型"
-describe actor:act_001/default "整洁校服，黑色长发"
-state-add actor:act_001 "雨天造型" --state-id st_rain --description "校服湿透，发梢滴水"
-state-rename actor:act_002/default "夜班造型"
-describe actor:act_002/default "便利店制服，胸前佩戴工牌"
-state-rename location:loc_001/default "常态"
-describe location:loc_001/default "冷白灯全部亮起"
-state-add location:loc_001 "停电" --state-id st_outage --description "冷白灯熄灭，应急灯发绿"
-state-rename prop:prp_001/default "常态"
-describe prop:prp_001/default "伞面完整，伞骨可正常开合"
-state-add prop:prp_001 "破损" --state-id st_torn --description "伞面裂开，一根伞骨外翻"
-```
-
-`ep01.txt` 再建分集和真实 scene，然后写正文：
-
-```
-add-episode --title "第一集：相遇"
-synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
-synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
-insert ep_001 --location loc_001 --time night --space interior
-scene-ref ep_001/scn_001 actor:act_001 --state st_rain
-scene-ref ep_001/scn_001 actor:act_002 --state default
-scene-ref ep_001/scn_001 location:loc_001 --state default
-scene-ref ep_001/scn_001 prop:prp_001 --state default
-insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店。" --emotion "狼狈"
-insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
-```
-
-地点、时段和叙事线连续时，后续节拍继续向 `ep_001/scn_001` 追加 action。同场人物需要多个造型或多份画面引用时，对同一 actor 追加 scene-ref，并在 Action 中写清变化顺序。互动式写作可把长场拆成多个 action 批次依次 `do --apply`，每批都指向同一 scene。场界规则以 SKILL.md「标准剧本通用流程」为准。
-
-动词与单条命令完全一致（参数见 `scriptctl <verb> --help`）。`do` 也读 stdin：`… | scriptctl do -`。
-
-> 机器/程序化生成的批量（如 jq 变换查询结果）才用 JSON：`scriptctl actions … --json | jq '[…ops…]' | scriptctl patch -`。手写一律 `do`。
-
----
-
-## 写到哪里去（落库）
-
-`create` 和所有编辑 verb 只写本地 `--script-path <file>`；省略时是
-`<cwd>/workspace/script.json`。远端剧本必须遵循：
-
-```text
-checkout → 本地查询/原子编辑/do/patch → validate → publish
-```
-
-- 已有远端剧本先 `scriptctl checkout --script-path draft.json`。
-- 全程对同一个 `draft.json` 编辑。新增原子能力只需实现本地操作，不增加远端业务 API。
-- `scriptctl status --script-path draft.json` 查看是否 dirty。
-- `scriptctl publish --script-path draft.json` 拉最新 snapshot 后以本地稿为准生成 patch；CAS/网络失败会重拉重试，最终远端内容与本地稿一致。
-- 本地新剧可直接 create/ingest 后首次 publish；没有 working-copy metadata 时只尝试从 revision 0 创建。
-
-### 两份 script.json（洗稿 / 对标 / 转绘）
-
-同时开着原剧与新剧时，一次只作用于 `--script-path` 指的那份：从原剧读（`summary`/`actions`（带 timestamp）/`states`（带弧线）/`scenes`（带时段）），往新剧写（`create` → `do --apply`）。换文件 = 换 `--script-path` 的值。详见 SKILL.md「两个 script.json」。
-
----
-
-## 校验语义（重要）
-
-空骨架可以逐步搭建，但正文入口有更严格的前置门：
-
-- **骨架阶段**：可以先建空剧本、空集和空场，再逐项补资产引用。
-- **正文插入门**：`insert <ep/scn>` 要求本场已有地点，且本场全部地点/人物/道具引用都带已物化 state；对白/心声使用 actor 时，该 actor 必须已在本场 cast。空镜、环境动作或非角色发声场可以没有人物引用。
-- **全局硬错误**：悬挂引用、重复 id、人物真名重复、说话人物不在本场、非法枚举、缺 id/name、非人类注册成 actor。
-
-随时 `scriptctl validate` 看整体，`scriptctl issues --severity warning` 专看「还没填」的清单。
-
----
-
-## 提醒
-
-- 资产 state 判定（哪些进 `states[]`）见 SKILL.md「资产 state 判定」。
-- 非角色发声源（系统/广播/画外/群体）用 `dialogue <at> --kind system|broadcast|offscreen|group [--label ...]`（对白行内联），**不要**注册成 actor。
-- 人物真名全剧唯一且稳定：动作中只用 `actor_name`；称呼、绰号、职位放 aliases，只能出现在自然对白等不要求资产解析的文本里。别在名字里塞状态注解（`林夏（受伤）`会被拒），外观档位用 `state-add`。
-- action 禁止“他 / 她 / 对方 / 其中一人 / 另一个人”等指代；逐个写明行动者真名。对白内容允许自然使用人称代词。
-- action 写明具体动作、作用对象、空间方向和可见结果；对白的短促伴随动作放 `emotion`，影响走位、道具或连续性的动作单独写 action。
-- 一个 scene 只绑定一个地点和每项资产的一个 state；多地点或多状态参考需求按 [production-writing-standard.md](production-writing-standard.md) 处理并报告结构限制。
-- action 情绪放 `emotion` 字段：插入时用 `insert ... --emotion "紧张"`，修改时用 `emotion <ep/scn#idx> "紧张"` / `emotion <ep/scn#idx> --clear`，不要把 `[紧张]` 这类标记塞进 content。
-- 参数 / 退出码以 `scriptctl <cmd> --help` 为准。