@pippit-dev/cli 1.0.37 → 1.0.40

package/skills/short-drama/workflows/creation.md

@@ -2,6 +2,18 @@
 
 提交使用 [short-drama +submit-run](../commands/submit-run.md)。首次新建；续写、修改或回复问题复用原 thread_id，并保存新 run_id。原样传递用户文本，不替后端创作。单会话只绑定一个剧本，缺少必要输入时先询问。
 
+## 业务内容查询
+
+用户询问当前项目的角色、场景、外观、画布节点、分镜片段、设定、关联、数量或资产状态时，原样通过 `short-drama +submit-run --thread-id THREAD_ID --message "用户原始问题"` 提交到当前会话，记录新 run_id，并用 `get-thread` 获取本次服务端回答。保留用户指定的范围，例如“画布中的场景”不能替换成“剧本提到的场景”。缺少目标且上下文无法确定时才询问，不猜会话或资产 ID。
+
+- 宿主可忠实整理服务端回答，但不自行补全、合并去重、计算数量或解释未返回的业务关系。历史回复只用于定位上下文，不代替本次查询。
+- 不通过文件名、目录、文件数量、内部 JSON、已下载剧本或网页内容推断业务信息；不切换到浏览器、其他技能或自行调用 API 作为内容查询兜底。网页入口仍可供用户查看。
+- 文件读取仅用于用户明确要求的文件内容查看，或规定范围内的下载、校验、预览和交付。回答须限定为该文件的内容，不据此宣称当前项目或画布状态。“片段1内容是什么”是业务内容查询，不等于请求下载或解析 `storyboard.json`。
+- 纯内容查询只授权读取和回答，不授权重新分析、补资产、修改或生成。混合请求（如“看看有哪些场景，把缺的图补齐”）仍原样提交，按用户已明确授权的范围执行，不重复确认；服务端提出超出已有授权的操作时，说明所需动作并等待用户授权。不要为了回答问题自行推进创作阶段；若服务端已意外执行未授权操作，报告实际情况，不继续扩大操作。
+- 服务端查询失败、缺项、范围不符或回答与工具错误矛盾时，报告已确认的信息和无法确认的部分，不以宿主推断补齐，也不把 Run 完成或笼统的“工具已完成”等同于资产生成成功。
+
+进度查询仅使用 `get-thread`；文件取件使用 `list-thread-file` 和 `download-result`，不为这两类请求新增 Run。业务内容查询提交后按 [轮询与文件交付](poll-and-deliver.md) 跟进本次 Run，确认终态后展示最终回答，不将中间说明当作最终结果；后端提问、明确失败、用户停止或超时按轮询规则结束。纯查询不自动进入下一创作阶段。
+
 ## 任务页与宿主衔接
 
 提交后立即展示真实 web_thread_link，并优先使用当前宿主实际提供的内置浏览器或页面打开能力打开。豆包、Codex Desktop、WorkBuddy、TRAE 各用自己的能力，不套用其它宿主的工具名。无法自动打开时说明原因并提供手动链接，继续 CLI 查询和交付；网页只供查看、确认和调整，不代替 CLI 取件。
@@ -12,27 +24,29 @@
 
 短剧创作按以下主流程推进。用户侧 Agent 在展示后端 Agent 的表单、问卷、选项或确认问题时，必须先参考这个顺序判断当前阶段和合理下一步。
 
-1. 剧本上传 / AI 剧本生成 / AI 剧本编辑
-2. 剧本合并与完整剧本确认
-3. 剧本分析
-4. 短剧风格推荐确认
-5. 剧本标准化（可选）
-6. 场景分析
-7. 所有必要场景图生成
-8. 角色分析
-9. 所有必要角色图生成
-10. 分镜设计
-11. 分镜视频生成
-12. 完整视频合成
+1. 剧本准备：上传剧本、AI 生成剧本、编辑、改编或续写。
+2. 确认当前剧本并分析：向用户确认使用最新剧本后进入分析；角色、场景分析由该分析流程自动衔接，不作为用户侧独立阶段。
+3. 风格确认：确认短剧风格推荐。
+4. 故事版：生成或修改故事版、分镜和相关素材。
+5. 片段视频：生成或重生成片段视频。
+6. 完整视频：合成完整视频。
+
+剧本标准化是风格确认后的可选操作，只在用户明确希望标准化整理、旁白改编或统一表达时执行。主流程是能力范围，不是每次必须从头执行的清单；按用户意图和当前真实资产进入对应步骤。
+
+## 独立素材创作边界
+
+用户要求直接生成或编辑图片、视频、音频、画布节点或画布素材时，先确认当前会话已完成剧本解析/分析。未完成时，先推进剧本准备、确认当前剧本并分析；不要绕过剧本解析直接进入素材生成。
+
+完成剧本解析后，可按用户原始需求提交给服务端处理。服务端可直接完成这类独立素材创作，不要求继续完成风格确认、故事版或片段视频；产物也不会因为生成成功就自动绑定、替换或推进短剧项目。只有用户明确要求把产物应用到项目时，才回到对应项目流程，核实目标范围并按授权规则执行。
 
 ## 表单与问卷选项处理原则
 
 后端 Agent 通过 `readable_text` 发出表单、问卷、选项、按钮或询问用户时，用户侧 Agent 不要机械原样转述所有选项。先结合短剧主流程顺序清洗选项，再把合理、必要、当前可执行的流程项呈现给用户。
 
 - 保留当前阶段的确认项，以及不会跳过必要阶段的下一步流程项。
-- 剔除跳过必要阶段的选项。例如未完成“剧本合并与完整剧本确认”前，不应让用户直接进入“剧本分析”；未完成“所有必要场景图生成”前，不应让用户直接进入“角色分析”。
+- 剔除跳过必要阶段的选项。例如未确认当前最新剧本前，不应让用户直接进入“剧本分析”；未完成风格确认前，不应让用户直接进入故事版；未确认故事版和片段视频范围前，不应进入完整视频合成。
 - 剔除倒退到无关阶段的选项。只有用户明确要求返工、修改或重新生成时，才展示回退选项。
-- `剧本标准化` 是可选阶段，只能出现在“短剧风格推荐确认”之后、“场景分析”之前。不要把它包装成任意阶段都可以跳过或补做的通用选项。
+- `剧本标准化` 是可选阶段，只能出现在“风格确认”之后、“故事版”之前。不要把它包装成任意阶段都可以跳过或补做的通用选项。
 - 不替用户决定创意内容，例如风格、剧情方向、角色设定、镜头方案。只能清洗流程选项，不能代替用户选择创作偏好。
 - 如果服务端问题混入跨度过大的多个流程选项，重新组织成当前阶段可回答的问题，并说明已按主流程剔除不合理或跳跃选项。
 

package/skills/short-drama/workflows/poll-and-deliver.md

@@ -4,20 +4,30 @@
 
 | 模式 | 执行范围 | 结束条件 |
 | --- | --- | --- |
-| 单次查询，如“现在什么进度” | 调用一次 [get-thread](../commands/get-thread.md)，回复实际进展和待回答问题；需要时按下文有界重试 | 本次查询结果已告知用户；不自动持续轮询、下载或续交任务，不将查询完成表述为创作完成 |
+| 业务内容查询，如“画布有哪些场景”“第一集片段1内容是什么” | 按 [业务内容查询](creation.md#业务内容查询) 原样提交到已有会话，随后跟进本次 Run 的服务端回答 | 本次 Run 已到终态且最终回答已处理，或遇到后端提问、明确失败、停止请求、等待时限；纯查询不自动推进创作 |
+| 单次进度查询，如“现在什么进度” | 调用一次 [get-thread](../commands/get-thread.md)，回复实际进展和待回答问题；需要时按下文有界重试 | 本次查询结果已告知用户；不自动持续轮询、下载或续交任务，不将查询完成表述为创作完成 |
 | 仅取件，如“下载已有剧本” | 用 [list-thread-file](../commands/list-thread-file.md) 定位用户所需文件，再用 [download-result](../commands/download-result.md) 下载交付；已持有可靠文件信息时可直接下载 | 请求的已有文件已交付，或已明确报告缺失、失败、未交付项；无需等待 Run 终态，不自动等待未来产物 |
 | 持续跟进：提交创作任务后，或用户明确要求持续查询 | 同时查询进展和会话文件，按下文轮询、处理问题并交付产物 | 达到下文创作完成标准，或遇到用户问题、失败、停止请求、等待时限 |
 
-单次查询和仅取件均复用已有会话；除非用户追加创作需求或回复后端问题，不调用提交命令。
+单次进度查询和仅取件不调用提交命令；业务内容查询需要在同一会话提交新的查询 Run，不能用旧 Run 的历史内容代答。业务内容查询沿用下文轮询间隔、失败恢复与等待上限；并行文件核对只用于发现可交付产物，不参与业务回答。
 
 ## 持续跟进：查询与停止
 
 1. 保存 thread_id、run_id、任务链接和任务工作目录。每轮并行查询会话进展与文件列表；宿主不能并行时逐项执行，不能遗漏任一项。
-2. 每隔 10 秒查询一次，同一任务不重新安装 CLI。展示后端实际进展，对带 download_url 的重要资产及时下载，不等用户再次要求。按文件命令说明分页和记录版本。
+2. 每隔 10 秒查询一次，同一任务不重新安装 CLI。展示后端实际进展，对带 download_url 的保留产物及时下载，不等用户再次要求。按文件命令说明分页和记录版本。
 3. 后端要求用户回答时，处理本轮已发现产物，再按 [创作与续接](creation.md) 提问并暂停主动轮询；等待回复，不代答。收到回复后复用 thread_id，跟踪新 run_id。
-4. 明确成功终态时核对文件列表并交付；明确业务失败时停止轮询，仍交付已确认可用的产物。文本没有明确状态时如实说明无法确认，不能把无新消息当成仍在生成或已完成。
+4. 明确成功终态时从第 1 页重新核对文件列表并交付；明确业务失败时停止任务进度轮询，仍处理已发现的可用产物，不重新提交创作。文本没有明确状态时如实说明无法确认，不能把无新消息当成仍在生成或已完成。
 5. 用户要求停止时立即停止本地轮询；这不等于取消服务端任务。遵守用户或宿主更短的等待时限；未指定时单次主动等待最多 30 分钟。到时保存 ID、分页位置、文件版本及未完成项，交付已有产物并提供后续查询入口，不承诺后台持续执行。
 
+## 下载记录与收尾
+
+在任务工作目录保存本地交付记录，按 `thread_id + file_path + updated_at` 区分文件版本。记录发现页、版本、实际本地路径，以及待链接、待下载、已校验、已交付、失败等状态；不保存 AK 或带签名的下载 URL。updated_at 缺失时标为版本未知，不能认定与旧文件相同；首次发现或用户明确要求刷新时下载到新的批次目录，同一轮后续查询不因版本未知反复下载，并如实说明无法确认版本新旧。下载成功和交付成功分别登记，失败或缺链接不能标为已处理。后续页面暂时不再列出某文件，不删除已有记录或本地文件。
+
+- 新 Run 和恢复任务时加载已有记录；同版本已校验但未交付的文件继续交付，不重复下载；本地文件缺失或校验失败则保持待处理。不同版本不能因同名文件存在而跳过。
+- Run 成功或后端提问时，先处理已发现的待交付产物。若存在缺链接文件、用户明确要求的产物尚未发现，或最终扫描仍出现新增/更新，在整体等待时限内每隔 10 秒最多额外核对文件列表 2 次，并处理新发现的可下载版本；不等待无限期后台产物。仅取件采用同样的有界文件核对，不等待未来创作。用户要求停止、鉴权/权限错误或查询重试已耗尽时，不启动收尾重查。
+- 收尾重查不会重置查询或单文件的失败计数。失败 Run 仅处理已发现产物，不因缺文件启动恢复创作。结束时逐项保留缺链接、下载失败、校验失败、未交付和分页未核全记录，说明已交付部分及剩余项。
+- 核对用户要求的交付范围，例如明确要求 5 集正文时，检查对应 5 个正式正文文件是否已取得。这里只检查文件交付完整性，不从文件推断角色、场景或画布状态。
+
 ## 有界恢复
 
 - 可识别的暂时网络错误或下载错误：按同一查询（命令及查询参数）或同一文件分别记录连续失败；首次失败后间隔 10 秒最多额外重试 2 次，仍失败则停止该项并记录。该项成功后重置连续失败计数；仅进入下一轮不清零，也不重新启用已停止项。其他正常项继续处理。重试受用户或宿主时限约束；持续跟进时不延长整体 30 分钟等待上限。
@@ -28,10 +38,18 @@
 
 ## 文件与媒体交付
 
-剧本设计、场景/角色设定、分集草稿、故事板、图片和视频都是重要产物。下载后逐项检查实际 output_path 存在、非空且属于当前会话；already_exist 只代表复用，不代表新下载。失败和缺链接项单独记录。
+默认只下载并交付正式保留产物。保留范围为：
+
+- `ai_script/script_outline.json`，以及兼容带 `asset/` 前缀的同名文件：故事设定、大纲与分集梗概。
+- `ai_script/episode_<episode_id>.json`，以及兼容带 `asset/` 前缀的同名文件：AI 生成的分集正文。
+- `.mp4`、`.jpg` 和 `.jpeg`：片段视频、完整视频、角色图、场景图等媒体正式产物。
+
+内部元数据、索引、缓存、调试文件、中间结果、临时校验文件，以及不在上述范围内的 JSON、Markdown、日志或配置文件，不因出现在文件列表中就下载或交付。用户明确指定某个非保留文件时，先说明它不属于默认交付范围，再按实际能力和安全路径规则处理。
+
+下载后逐项检查实际 output_path 存在、非空且属于当前会话；already_exist 只代表复用，不代表新下载。失败和缺链接项单独记录。
 
-- 剧本、设定及其他文档：使用宿主实际文件交付能力提供可打开或下载的真实附件，可同时概述内容。
-- 图片、视频：逐项通过宿主附件工具或媒体渲染能力展示真实文件。宿主要求绝对路径时，将实际 output_path 解析为绝对路径后传入。
+- `script_outline.json` 和 `episode_<episode_id>.json`：使用宿主实际文件交付能力提供可打开或下载的真实附件，可同时概述内容。
+- `.mp4`、`.jpg` 和 `.jpeg`：逐项通过宿主附件工具或媒体渲染能力展示真实文件。宿主要求绝对路径时，将实际 output_path 解析为绝对路径后传入。
 - 豆包和其他宿主都以实际文件交付接口为准，不臆造工具名。web_thread_link、下载 URL、本地文件列表仅作补充，不能替代附件或媒体展示。
 - 某文件下载或展示失败时仍交付其他可确认产物，逐项说明未交付原因。宿主无交付能力时说明“已下载，未完成附件交付”，不能宣称全部完成。
 
@@ -39,7 +57,7 @@
 
 1. 已处理当前 Run 的最新文本、后端问题和终态；需用户回复时只能报告等待确认。
 2. 已展示任务链接，并按宿主能力尝试打开或提供手动入口。
-3. 已核对会话文件及分页，按 updated_at 检查已发现的重要产物版本；存在未核全页面时说明。
+3. 已核对会话文件及分页，按 updated_at 检查已发现的保留产物版本；存在未核全页面时说明。
 4. 所有待交付产物已通过宿主实际交付；下载、复用、失败和未交付分别记录。
 
-以上标准用于持续跟进创作；单次查询和仅取件按开头表格结束，不要求额外取得 Run 终态或打开任务页。需要交付文件的任务，只有用户请求的工作已完成且对应产物交付成功，才称“完成”；发生失败、超时或能力阻塞时可汇报部分结果，但必须明确剩余项。仅得到文本进展、URL 或本地路径不算文件交付完成。
+以上标准用于持续跟进创作；业务内容查询在本次 Run 终态及最终回答确认后结束（提问、失败、停止或超时除外），单次进度查询和仅取件按开头表格结束，不要求额外取得 Run 终态或打开任务页。需要交付文件的任务，只有用户请求的工作已完成且对应产物交付成功，才称“完成”；发生失败、超时或能力阻塞时可汇报部分结果，但必须明确剩余项。仅得到文本进展、URL 或本地路径不算文件交付完成。

package/skills/xyq-nest-skill/commands/canvas-assets.md

@@ -6,7 +6,7 @@
 | --- | --- | --- |
 | `canvas create` | `--title` 最多 50 字符；`--request-id` 可选；`--wait` 等初始化；可调 `--poll-interval`、`--timeout` | 保存 `project_id`、`canvas_asset_id`、`web_url`、`request_id`；检查 `state`、`warning` 和退出码 |
 | `canvas get` | `--asset-id` 必填，可重复 | 返回 `requested_asset_ids`、`assets` 及可用的 `log_id`；核对实际返回资产 |
-| `canvas upload` | `--path` 本地文件；可调 `--poll-interval`、`--timeout` | 返回 `pippit_asset_id`、`locator`、`state`、`warning`；素材可查询不代表已插入画布 |
+| `canvas upload` | `--path` 本地文件；可调 `--poll-interval`、`--timeout` | 返回 `pippit_asset_id`、可用的 `media_asset_id`、`source_id`、`locator`、`state`、`warning`；素材可查询不代表已插入画布 |
 | `canvas allocate` | `--count` 分配数量 | 返回 `asset_ids[]`；只预留 ID，不创建节点或资产 |
 | `canvas apply` | `--project-id` 项目 ID；`--file` JSON 文件，默认 `-` 读 stdin | 一个 transaction，可含多条 patch；检查事务 ACK 和目标资产版本 |
 
@@ -20,6 +20,12 @@ pippit-tool-cli canvas upload --path "/path/to/reference.png"
 
 ## 低层事务的使用边界
 
+媒体节点优先通过语义 `create_biz_node` 创建，`initialData` 只传 `pippitAssetId`：CLI 查询素材并填写真实云媒体 `assetId`。用 `update_asset.contentPatch` 或 `update_node_data.patch` 替换素材时也可只传新的 `pippitAssetId`。显式填写的 `assetId` 必须与素材查询结果匹配，否则返回 `INVALID_MEDIA_IDENTITY` 并拒绝写入。
+
+上传顶层旧字段 `asset_id` 是保留兼容的 workspace/source ID，不能当节点媒体 ID。`media_asset_id` 来自查询结果对应的 `Image/Video/Audio.asset_id`；缺失时不能用 `source_id`、`pippit_asset_id` 或画布节点 ID 补位。`node_asset_refs[].pippit_asset_id` 使用画布节点资产 ID。
+
+批量 `apply_mutations` 默认非原子执行：必须检查 `data.results` 中每一项的 `committed` / `aborted` 状态，保留已成功项，不重跑整批。需要任一失败时整批回滚，可显式传 `atomic: true`。
+
 普通节点和领域编辑优先使用 [语义命令](canvas.md)，由 SDK 分配 ID 并构造事务。仅在用户确实提供或需要底层资产事务且契约已核实时执行：
 
 ```bash
@@ -30,3 +36,5 @@ pippit-tool-cli canvas apply --project-id PROJECT_ID --file "/path/to/validated-
 JSON 根包含 `batch_id`、`client_id`、`transactions`，可含 `root_pippit_asset_id` 和 `Base`；单一 transaction 含 `transaction_id`、`patches`。每个 patch 使用实际 `asset_id`、`op`、`path`、所需 `value` 与适用的 `base_asset_version`，具体版本及内容必须来自真实查询或已核实调用契约。保留调用方原有 batch/transaction ID，不擅自改前缀；不手工绕过语义命令的业务校验。
 
 写入结果不明确、超时或版本冲突时，先查询受影响资产，再决定如何恢复；不能照原请求盲目重放。不要使用隐藏传输参数绕过 ACK 校验。
+
+`canvas apply` 在发送写入前验证本次修改涉及的媒体身份，包括部分字段 patch；按整笔事务最终结果校验，拒绝 Pippit ID、source ID、节点 ID 与真实媒体 ID 的错配。低层写入不会自动改写调用方的 patch。