@oh-story/dsh 0.1.3 → 0.1.5

package/lib/drama/skills/short-drama/references/reference-roles.md

@@ -1,142 +1,39 @@
 # 一张参考图可以决定什么
 
-## 目录
+绑定参考图等于告诉下游“哪些地方照着它”。不说明边界，身份参考会越权决定服装、构图、背景或文字。
 
-- [绑定前先回答四个问题](#绑定前先回答四个问题)
-- [绑定不等于看过](#绑定不等于看过)
-- [两种观察不能混成一条](#两种观察不能混成一条)
-- [每种用途允许借用什么](#每种用途允许借用什么)
-- [多图、联系表与首尾帧](#多图联系表与首尾帧)
-- [审查顺序](#审查顺序)
+## 每张参考回答五个问题
 
-绑定一张参考图，等于告诉下游"照着它写"。问题是"照着"到底指哪些内容——同一张人物定妆照，
-可以用来定脸，也可能被当成定构图、定服装、定表情，甚至把图里背景一起搬走。
-不说清楚，下游只能猜；猜错了不会报错，只会拍错。
+1. 它的稳定 `REF-...` 槽位和显式顺序是什么；
+2. 它的可见项目相对路径和中文名称是什么，例如 `输入/参考图/江辰定妆.jpg《江辰定妆照》`；
+3. 本次参考身份、造型状态、地理、构图、尺度、效果、起始帧、结束帧还是风格；
+4. 哪些可见内容允许照着写；
+5. 哪些身份、文字、人数、道具和空间锚点不能跟着变。
 
-本文只回答两件事：一次绑定要写清什么，以及每种用途各自允许借用什么。
-观众何时能知道某件事见 [audience-reveal.md](audience-reveal.md)；
-一个缩小范围的版本是否仍算母版见 [pickup-and-alternate.md](pickup-and-alternate.md)。
+第 3 问在创作文档里有固定落点：`REF-...` 槽位的 `用途` 字段，取值只能是下表左列的九个词之一。
+它同时回答创作者的「这一镜要送哪一张分镜起始帧、哪些人物/道具/场景图」，和执行端的「这张图翻成哪个
+供应商 role」。同一张图承担两个作用时分开成两个槽位，不写“全参考”。
 
-## 绑定前先回答四个问题
-
-1. **它是哪一条记录**：写准确的产物引用与记录 ID，不是"参考图二"。
-2. **这次参考它的什么**：身份、造型状态、地点方位、构图、尺度、效果还是起始帧。
-3. **哪些内容可以照着写**：在 `may_control` 里列出这次确实要参考的可见内容。
-4. **哪些内容不能跟着变**：在 `must_not_control` 里保护身份、文字、人数、道具和空间锚点。
-
-同一张图若要承担两个不同作用，拆成两条绑定分别审查，不写"全参考"。
-
-### 绑定不等于看过
-
-`artifact_ref` 只说明绑定了哪条文本记录，**不能证明智能体真的看过那张图**。所以每条绑定
-还要写清证据到了哪一步：
-
-| `admission_status` | 什么情况 | 可以下什么结论 |
+| 用途 | 可以控制 | 默认不能控制 |
 |---|---|---|
-| `creator_described` | 创作者或图片权利人给了可核对的画面说明 | 按说明内容判断 |
-| `visually_inspected` | 运行环境获授权检查输入参考图并完成检查 | 按检查记录判断 |
-| `unverified` | 只有 JSON 或文字描述，媒体不可见或没有授权 | **不得**声称像素、文字、水印或裁切已通过 |
-
-前两种都要绑定准确的 `reference_observation_ref`，记录所看的文件、检查区域、
-文字处理结论、检查方式与未决风险，格式见
-[reference-observation.example.jsonl](../assets/reference-observation.example.jsonl)。
-
-### 两种观察不能混成一条
-
-输入准入记录固定写 `observation_kind: input_reference`——它只支持"这张参考图上有什么"。
-
-若创作者另行提供某个准确提示词/规格版本下的授权**生产**观察，用独立的
-[production-observation.example.jsonl](../assets/production-observation.example.jsonl)，写
-`observation_kind: generated_result`、`evidence_state: active`，并绑定 prompt/spec、
-稳定参考槽位与制作配置。
-
-`evidence_state: active` 只表示这份证据仍可使用，**不表示产物通过或被接受**。
-
-两种观察不能混为一条：一条讲输入里有什么，另一条讲某次结果发生了什么，能支持的结论
-完全不同。任务成功、结果地址或文件存在，都不能代替其中任何一种。
-
-两条容易被绕过的边界：
-
-- **检查输入参考 ≠ 生成图片，也 ≠ 验收成片**。 三件事各自需要各自的证据。
-- **负面提示词擦不掉参考图上已有的像素**。 图里有水印就是有水印，写"不要文字"不会让它消失；
-  要么裁切、清理、遮罩、替换，要么退回参考图归属方决策。
-
-## 每种用途允许借用什么
-
-| 用途 | 可以借用 | 默认不可借用 |
-|---|---|---|
-| `identity` | 稳定脸型、体态、识别标记 | 临时服装、姿势、场景、画中文字 |
-| `look_state` | 已接受的造型，或伤损、湿污等状态 | 新身份、无来源道具、背景方位 |
-| `geography` | 入口、区域、固定锚点、方向关系 | 图中临时人物、光线以外的故事状态 |
-| `composition` | 占画比例、视线布局、镜头所在一侧、留白 | 图中人物是谁、穿什么、发生什么 |
-| `scale` | 主体之间或主体与环境的相对尺度 | 风格、身份、数量、动作结果 |
-| `effect` | 已接受效果的形态、范围或材质表现 | 非目标对象的消失、复制或变形 |
-| `start_frame` | 本镜已接受的起始构图与可见状态 | 尚未发生的动作、终态或下一镜事实 |
-| `end_frame` | 本镜 `end_boundary` 已接受的投影 | 新终点、未由镜头承担的动作结果 |
-| `style` | 色彩层级、材质处理、阴影边缘、景深倾向、画面密度 | 角色身份、固定地理、剧情状态、道具文字 |
-
-"只参考构图"是有效而且重要的边界：可以借用前景/背景占比和压迫关系，同时明确不导入图中
-角色、服装、道具、文字与事件。尺度也优先写成可比较的空间关系、遮挡和画面占比；
-具体比例只有被创作者或项目配置接受后才是约束，不能从案例总结成通用数字。
-
-### 合成示例
-
-一张剧照要用来定"谁站在画面哪一侧、占多大"，但图里那个人不是本镜的角色。
-
-这条绑定所在的文件在第一行声明它引用到的上游快照：
-
-```json
-{"record_type":"sources","schema_version":"1.0.0","sources":{"keyframes":{"owner":"short-drama-storyboard","artifact":"剧集/EP001/storyboard/keyframes.jsonl"}}}
-```
-
-之后每条绑定只写快照键、记录 ID 和这一条自己的 `authority`：
-
-```json
-{
-  "slot_id": "REF-COMPOSITION-01",
-  "order": 1,
-  "artifact_ref": {
-    "src": "keyframes",
-    "record_id": "KEY-012",
-    "authority": "candidate"
-  },
-  "role": "composition",
-  "may_control": ["主体占画比例", "镜头所在一侧", "留白位置"],
-  "must_not_control": ["角色身份", "服装", "道具文字", "故事状态"],
-  "admission_status": "unverified",
-  "reference_observation_ref": null,
-  "unresolved_risks": ["尚无对该图文字/水印的检查记录"]
-}
-```
-
-这条绑定的意思是：**照着它排版，不要照着它选人**。 若它同时还要负责这个角色的长相，
-就再写一条 `role: identity` 的绑定，而不是把 `may_control` 加长。
-
-## 多图、联系表与首尾帧
-
-多张图可能是三种完全不同的东西，不能因为排在一张版面里就混成一个资产：
-
-- **一组参考绑定**：各自有各自的用途；
-- **方便人工浏览的联系表**：只是交付包装，每格仍保留自己的 artifact、用途和文字政策；
-- **同一段运动的起止边界**：见下。
-
-每条绑定使用稳定 `slot_id` 和显式 `order`。数组重排、插入新参考或联系表换版时**不得改变
-已有槽位的语义**——重排不会报错，只会拍错。固定九宫格也不是叙事密度公式，格间顺序不能
-替代独立镜头的起止边界。
-
-首尾帧契约是"**默认 start，按需 end**"：关键帧默认 `boundary_role: start`。执行方式确实需要
-首尾帧时，storyboard owner 可以增加 `boundary_role: end` 的关键帧；它只投影同一镜头已接受的
-`end_boundary`，**不是第二个终点权威**，也不能从动作说明自行发明。视频提示词可按
-`role: end_frame` 只读绑定这条记录，终点报告仍然对照 shot 的 `end_boundary`。
-
-动作跨度过大、或关键动作只存在于首尾插值的空隙里时，先拆镜——不能让尾帧替镜头承担动作本身。
-
-## 审查顺序
-
-1. 引用与 `authority` 能否解析；
-2. 每条绑定的用途、可借用内容、不可照搬内容是否写清；
-3. 观察记录是否存在，没有证据是否老实保持 `unverified`；
-4. 最后才评价措辞与审美。
-
-不要用引用数量、固定裁切方式、关键词清单或提示词长度代替这些判断，也不要从文字规格声称身份或特效
-在真实成片里已经成功。
+| 身份 | 稳定脸型、体态、识别标记 | 临时服装、姿势、场景、文字 |
+| 造型状态 | 已决定的服装、伤损、湿污 | 新身份、无来源道具、背景方位 |
+| 地理 | 入口、区域、固定锚点、方向关系 | 临时人物、剧情状态 |
+| 构图 | 占画比例、视线布局、镜头一侧、留白 | 人物身份、服装、道具文字 |
+| 尺度 | 主体之间或主体与环境的相对尺度 | 风格、身份、数量、动作结果 |
+| 效果 | 已决定效果的形态、范围、材质 | 非目标对象的消失、复制或变形 |
+| 起始帧 | 本镜起始构图与状态 | 尚未发生的动作和终态 |
+| 结束帧 | 本镜明确终点 | 新终点或未由镜头承担的结果 |
+| 风格 | 色彩层级、材质、阴影边缘、景深、密度 | 身份、固定地理、剧情、道具文字 |
+
+## 观察边界
+
+创作者或权利人给出的可核对说明可以作为文字证据；运行环境获授权看过参考图时，可以报告实际可见
+内容。两者都没有时保持“未验证”，不得声称水印、文字、裁切或身份已经通过。负面提示词不能擦掉
+参考图已有的像素。
+
+真实参考图使用 `REF-...` 稳定槽位，不使用 `IMG-...`；后一前缀专属《图片提示词.md》的可见提示词标题。多张真实图的每个槽位绑定显式顺序、项目相对路径、中文名称、用途、可控制范围和不可控制范围；联系表只是浏览包装，不改变每张图自己的用途。首尾帧默认只使用起点；
+确实需要终点帧时，它只能投影 `SHOT-...` 已写明的终点，不能自行发明结果。
+
+观众知情时机见 [观众揭示](audience-reveal.md)，补拍是否能替代母版见
+[补拍与替代](pickup-and-alternate.md)。

package/lib/drama/skills/short-drama/references/runtime-preflight.md

@@ -1,27 +1,24 @@
-# 项目定位与发布纪律
+# 项目定位与安全写入
 
-core 只管理当前项目的目录、生命周期和交付。
+## 定位项目
 
-## 1. 读取项目状态
+优先使用用户给出的项目路径；没有项目时可以直接在用户指定目录完成独立任务。需要项目配置时运行：
 
-定位 `short-drama.json` 后运行：
-
-```text
-python3 <core>/scripts/project_tool.py status <project>
+```bash
+python3 <core>/scripts/project_tool.py init <project> --title "项目名"
 ```
 
-使用 `status.layout.roots` 返回的项目目录。`mode=mixed` 表示中英文阶段目录并存，应先合并；
-空项目在第一次阶段发布时固定布局。只读取本次任务需要的直接输入。
+本文各处写作 `python3`；Windows 原生环境没有这个名字，改用 `py -3` 或 `python`。
+套件脚本（含 Dashboard）在 macOS、Linux、WSL 与 Windows 原生都可运行。
+
+创作文档固定写入 `剧集/<EP>/`。只读取当前任务需要的直接输入；不要扫描整个项目寻找可补造的上游。
 
-## 2. 通过公开命令写入
+## 写入纪律
 
-- owner 用 `publish` 原子发布一项产物，并用可重复的 `--input <project-path>` 声明直接输入。
-- `accept` 只记录创作者对当前输出的接受或拒绝。
-- `review` 只记录当前输出的复核结论；reviewer 不直接改 owner 文件。
-- 输入或输出变化后，该产物显示 `update_needed`，重新发布即可；不递归改写下游状态。
-- `package` 只收录当前 `approved` 的文本/JSON，不能替代接受或复核。
-- 第一次发布由任意非空 owner 认领合法阶段路径，此后这条路径归该 owner。
-- 同一项目路径仍只能属于一个 artifact，输入、交付和机器状态目录仍受保护。
+- 创作正文直接写五份 Markdown，修改时保留未受影响内容与稳定可见 ID。
+- 输入目录、隐藏运行目录、制作成果和凭据不是创作正文；不要把它们复制进提示词。
+- 文本写入使用临时文件加原子替换；外部编辑发生时先重新读取，不静默覆盖。
+- Dashboard 只展示和编辑项目文件，不承担创作路由或生产授权。
+- 外部生产仍由 `$short-drama-produce` 预览精确任务、取得显式确认后执行。
 
-完整参数见 [lifecycle-commands.md](lifecycle-commands.md)，权威边界见
-[contract-and-ownership.md](contract-and-ownership.md)。
+输出语言、稳定 ID 与信任边界见 [契约与所有权](contract-and-ownership.md)。