@pippit-dev/cli 1.0.38 → 1.0.41

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。