@pippit-dev/cli 1.0.23 → 1.0.25

package/skills/xyq-nest-skill/SKILL.md

@@ -1,510 +1,59 @@
 ---
 name: xyq-skill
-description: 通过小云雀的 AI 能力进行综合创作，支持生成和编辑图片/视频，并在用户明确要求图片或视频模型直出、指定图片或视频模型或直接调用 CLI 时使用 pippit-tool-cli generate-image / generate-video；用户要求视频超分、提升视频清晰度、擦字幕或去字幕时，使用 video-super-resolution / erase-video-subtitle。覆盖文生图、文生视频、图生视频、首尾帧生视频、视频编辑、风格转换、视频续写、视频复刻、TVC、宣传片、音乐 MV、产品广告、分镜和教育短视频等场景。当用户提到小云雀、xyq、上传参考图/视频/mp3或wav音频、查看生成进度，或查询小云雀积分余额、剩余积分、credits 时也应触发；积分查询使用 pippit-tool-cli get-credit-balance。
+description: 使用小云雀 pippit-tool-cli 生成或编辑图片、生成视频、超分和擦字幕，查询结果并交付媒体；操作小云雀个人 Canvas 画布、节点、布局、连线、角色/场景、生成提示词、3D 导演台与多轨草稿；查询积分及管理授权。用户提到小云雀、xyq 并需要这些操作时使用。
 user-invocable: true
 metadata:
-  {
-    "openclaw":
-      {
-        "emoji": "💬",
-        "requires":
-          {
-            "bins": ["python3", "node"],
-            "env": ["XYQ_ACCESS_KEY"]
-          },
-        "primaryEnv": "XYQ_ACCESS_KEY"
-      }
-  }
+  {"openclaw": {"emoji": "💬", "requires": {"bins": ["node"]}}}
 ---
 
-# 小云雀创作、图片/视频模型直出、视频处理与积分查询
+# 小云雀媒体创作与画布操作
 
-通过 小云雀的API 创建会话、发送消息（生图、生视频、编辑视频等）、上传图片/视频/mp3或wav音频文件，并查询会话消息进展；通过 CLI 查询个人有效积分余额。
+通过 CLI 完成生成、处理、结果下载与媒体交付。支持下表中的操作；不提供多轮会话续写或自动拆分剧本、分镜并编排成片的能力。复杂需求先确认能由所列命令完成的具体操作，不承诺未覆盖的流程。
 
-小云雀是一个 AI 综合创作平台，同时为人类创作者和 Agent 设计。Agent 通过 Skill 入口理解任务、调用模型并自动编排工作流。
+## 开始执行
 
-每次开始执行本技能任务时，先按“前置要求”运行 `scripts/ensure-cli.js`，检查已有 CLI，不存在或缺少必需命令时获取最新版本。本文命令中的 `pippit-tool-cli` 均代表该脚本返回的 `cli_path`；实际执行时替换为带引号的绝对路径。
+1. 画布任务运行 `node "{baseDir}/scripts/ensure-cli.js" --canvas`，其他任务运行 `node "{baseDir}/scripts/ensure-cli.js"`。保存返回的 `cli_path`；Canvas 还需保存 `canvas_entry`。文档中的 `pippit-tool-cli` 替换为带引号的 `cli_path`；画布语义命令按模块说明通过 Node 入口执行。同一任务复用，安装细节见 [安装说明](scripts/install.md)。
+2. 按下表选择操作，只读取命中的命令文档。执行需要鉴权的操作前，按 [授权说明](commands/auth.md) 检查登录；有效登录可复用。
+3. 生成、视频处理和查询已有媒体结果时，还必须读取 [异步结果与媒体交付](workflows/async-delivery.md)。画布任务使用 [画布查询、编辑与验证](workflows/canvas-edit.md)，不把画布编辑当作媒体生成。积分与授权操作直接返回结果。
 
-**平台核心能力：**
-- **生成**：文生图、文生视频、图生视频、视频续写
-- **编辑**：局部修改、元素替换、镜头调整、风格迁移
-- **视频处理**：视频超分、提升视频清晰度、擦字幕
-- **复杂创作**：复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
+参数是否存在、命令语法以当前 `cli_path` 对应的 `--help` 为准；返回字段和成功判断按命令文档及真实响应核对。文档与实际不一致时说明差异，不猜参数、不绕过 CLI 自行调用 HTTP。
 
-除“图片/视频模型直出”和“视频超分/擦字幕”外，创作和编辑需求通过发送自然语言消息来完成，后端 Agent 会自主编排工作流。复杂任务耗时较长，需耐心轮询。
+## 意图路由
 
-## 执行路由（必须先判断）
+按用户要做的操作选择命令，不能只看素材类型。有任务标识且用户只要求查询或取件时，复用该任务，不重新生成。
 
-积分余额查询优先走路由 E，不进入创作或视频处理工作流。
+| 用户意图 | CLI | 必读文档 |
+| --- | --- | --- |
+| 查看登录状态、登录、退出或切换账号 | `status` / `login` / `logout` | [授权](commands/auth.md) |
+| 创建或查询小云雀个人画布，编辑节点、布局、连线、角色/场景、提示词、3D 或多轨草稿 | `canvas` | [Canvas 能力与命令发现](commands/canvas.md) |
+| 生成图片，或基于参考图修改图片 | `generate-image` | [生图与图片编辑](commands/generate-image.md) |
+| 生成视频，使用图/视频/音频参考，首尾帧生视频 | `generate-video` | [生视频](commands/generate-video.md) |
+| 提升已有视频分辨率、视频超分 | `video-super-resolution` | [超分](commands/video-super-resolution.md) |
+| 去除已有视频字幕 | `erase-video-subtitle` | [擦字幕](commands/erase-video-subtitle.md) |
+| 查询已有任务进度、下载生成结果 | `query-result` | [查询结果](commands/query-result.md) |
+| 查询个人积分余额、剩余 credits | `get-credit-balance` | [积分](commands/get-credit-balance.md) |
 
-### 路由 A：图片模型直出
+- 普通生图、生视频也走对应生成命令，无需用户额外声明“模型直出”。
+- 明确要求修改现有画布或其中节点时优先走 Canvas；普通生图、生视频不自动创建画布。“修改节点提示词”只修改配置，不隐含生成；指定节点生成或导出须先确认当前命令目录有对应能力。
+- “参考这个视频生成新的”走生视频；“把这个视频变清晰”走超分。意图不清时先问清。
+- 同时提出多个明确操作时，分别选模块；有输入依赖则顺序执行。仅在用户请求包含多个步骤时组合，不自动增加收费处理。
+- 后续修改某张结果图片时，将对应本地文件作为新一次图片编辑的参考图；需要隐式会话上下文时，先补齐具体素材和指令。
 
-满足任一条件时，必须直接使用 `pippit-tool-cli generate-image`，不要改走 `pippit-tool-cli submit-run`：
+## 执行总则
 
-- 用户明确说“图片模型直出”、“直接调图片模型”或明确要求用 CLI 生图。
-- 用户指定了具体图片模型（如 `seedream_5.0_pro`），并希望单次直接生成图片。
-- 上游流程已明确将任务标记为图片 direct-model / 模型直出。
+- 保留用户原始 prompt，不擅自扩写、润色、翻译或增加风格词；参数转换按对应命令文档执行。生成和视频处理只传用户给定的可选创作参数，缺少必填项先询问。画布输入还需使用实际查询的 ID、版本和当前 schema。模型和参数最终合法性由服务端判断。
+- 用户明确要求生成或处理，即可在该范围内执行；仅咨询用法、费用或方案时不提交。范围、必填信息或消耗 credits 的授权不明确时，先确认，不重复索要已给出的授权。
+- 提问优先使用宿主实际提供且当前模式允许的工具：Codex 的 `request_user_input` 或 `request_user_input_async`，WorkBuddy 的 `ask_user_question`；不可用时用普通聊天。需要答案时等待答复。
+- 素材参数接收本地文件路径，CLI 内部上传。远程链接不能冒充本地路径；缺少可访问文件时先解决素材获取。单文件必须小于 500 MB（500000000 字节）。
+- 提交成功后立即展示真实 `web_thread_link`；未返回链接时如实说明，保留任务 ID。后续查询和下载失败不能触发重复生成。
+- 每个最终图片/视频都通过宿主文件交付或媒体渲染能力展示为真实附件或可预览媒体。URL、路径列表仅作补充；详细完成标准见共用交付流程。
 
-执行原则：
+## 按需参考的完整场景
 
-1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
-2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
-3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
-4. `--model` 必填；用户未提供图片模型时，先询问使用哪个模型。只添加用户已经给出的 `--ratio`、`--resolution`、`--generate-image-count`、`--image` 参数，不补默认值。
-5. `--resolution` 的使用说明是：仅 `seedream_5.0_pro` 支持 `1K`、`2K`、`4K`。不要在 skill 侧维护额外 allowlist 或自行改写用户值，实际合法性由服务端决定。
-6. `generate-image` 返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
-7. 每隔 10 秒调用 `query-result`，直到 `completed=true`。出现 `error_message` 时停止并报告；成功时展示并下载 `images[].output_path`。
+命令文档含最小调用示例；需要了解从需求到交付的组合过程时，再读对应场景：
 
-```bash
-pippit-tool-cli generate-image \
-  --prompt "用户原始描述" \
-  --model IMAGE_MODEL
-  --ratio RATIO
-  --resolution RESOLUTION
-  --generate-image-count COUNT
-  --image 参考图路径
-
-pippit-tool-cli query-result \
-  --thread-id THREAD_ID \
-  --run-id RUN_ID \
-  --download-dir OUTPUT_DIR
-```
-
-### 路由 B：视频模型直出
-
-满足任一条件时，必须直接使用 `pippit-tool-cli generate-video`，不要改走 `pippit-tool-cli submit-run`：
-
-- 用户明确说“视频模型直出”、“直接调模型”或“直接调用 CLI”。
-- 用户指定了具体视频模型（如 `Seedance_2.5`），并希望单次直接生成视频。
-- 用户明确要求“首尾帧生视频”、指定首帧和尾帧，或要求从第一张图过渡到第二张图。
-- 上游流程已明确将任务标记为 direct-model / 模型直出。
-
-执行原则：
-
-1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
-2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
-3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
-4. 只添加用户已经给出的 `--model`、`--duration`、`--ratio`、`--resolution`、`--image`、`--video`、`--audio`、`--generate-type` 参数；未给参数交给 CLI 默认值。
-5. 普通用户支持模型 `Seedance_2.0_mini_lite`；VIP 专属模型包括 `seedance2.0_vision`、`seedance2.0_fast_vision`、`Seedance_2.0_mini` 和 `Seedance_2.5`。该列表仅用于指导用户选择和传入准确的 `--model` 值，不要在 skill 侧增加模型枚举校验，实际合法性由服务端决定。
-6. 首尾帧请求固定传 `--generate-type 1`，并按首帧、尾帧顺序传入两次 `--image`，不得重排。用户未明确两张图片的角色或缺少任一张时，先询问用户；不要在 skill 侧维护额外的 `generate_type` 枚举 allowlist，其他值原样交给服务端处理。
-7. `generate-video` 返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
-8. 每隔 10 秒调用 `query-result`，直到 `completed=true`。出现 `error_message` 时停止并报告；成功时展示并下载 `videos[].output_path`。
-
-```bash
-pippit-tool-cli generate-video --prompt "用户原始描述" --model "Seedance_2.5"
-
-pippit-tool-cli generate-video \
-  --prompt "用户原始描述" \
-  --image FIRST_FRAME_PATH \
-  --image LAST_FRAME_PATH \
-  --generate-type 1
-
-pippit-tool-cli query-result \
-  --thread-id THREAD_ID \
-  --run-id RUN_ID \
-  --download-dir OUTPUT_DIR
-```
-
-`--image` 最多重复 9 次，`--video` 和 `--audio` 最多各重复 3 次。
-
-### 路由 C：视频超分和擦字幕
-
-用户明确要求视频超分、提升视频清晰度、擦字幕或去字幕时，直接调用对应的 `pippit-tool-cli` 视频处理命令，不要改走 `pippit-tool-cli submit-run`：
-
-- 视频超分、提升视频清晰度：`video-super-resolution`
-- 擦字幕、去字幕：`erase-video-subtitle`
-
-执行原则：
-
-1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
-2. 真实提交会消耗 credits；如果用户本轮尚未明确确认处理，按“用户确认与反问”规则征得明确确认后再运行。
-3. 把用户提供的本地视频路径和处理参数直接交给对应 CLI；缺少必填输入时先询问用户。
-4. 命令返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
-5. 每隔 10 秒调用 `query-result`，直到 `completed=true`。出现 `error_message` 时停止并报告；成功时展示并下载 `videos[].output_path`。
-
-```bash
-pippit-tool-cli video-super-resolution \
-  --video VIDEO_PATH \
-  --output-resolution OUTPUT_RESOLUTION
-
-pippit-tool-cli erase-video-subtitle \
-  --video VIDEO_PATH
-
-pippit-tool-cli query-result \
-  --thread-id THREAD_ID \
-  --run-id RUN_ID \
-  --download-dir OUTPUT_DIR
-```
-
-### 路由 D：小云雀后端 Agent 编排
-
-需要意图确认、脚本/分镜拆解、MV、TVC、局部编辑、复杂参考素材编排，或者用户未明确要求模型直出的创作需求，使用 `pippit-tool-cli submit-run` 提交消息，再用 `get_thread.py` 查询会话进展；明确的首尾帧请求走路由 B，明确的视频超分和擦字幕请求走路由 C；积分余额查询走路由 E。
-
-提交前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path` 调用 `submit-run`；失败时报告版本或安装阻塞。
-
-### 路由 E：积分余额查询
-
-用户询问小云雀“积分余额”、“还剩多少积分”、“剩余 credits”或要求查询个人有效积分时，直接使用 `pippit-tool-cli get-credit-balance`。
-
-执行原则：
-
-1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；不可用或版本不支持该命令时报告阻塞，不要改走 `pippit-tool-cli submit-run`。
-2. 使用当前 CLI 登录凭证或显式配置的 `XYQ_ACCESS_KEY` 查询凭证所属用户的个人有效积分余额；无需传入用户 ID、`thread_id` 或 `run_id`。鉴权要求见“前置要求”。
-3. 这是只读查询，不需要积分消耗确认；不创建会话，不提交生成任务，也不调用 `get_thread.py` 或 `query-result` 轮询。
-4. 成功时读取 JSON 中字符串类型的 `total_remain_amount`，向用户展示当前有效积分余额；`"0"` 是有效的零余额。查询失败或缺少余额字段时报告错误，不得当作零余额。
-5. 需要排查请求时可添加 `--with-log-id`，同时保留返回的 `log_id`。该命令只返回总余额，不提供积分明细、到期时间或生成任务的费用预估。
-
-```bash
-pippit-tool-cli get-credit-balance
-
-# 排查请求时同时返回 log_id
-pippit-tool-cli get-credit-balance --with-log-id
-```
-
-默认输出示例：
-
-```json
-{"total_remain_amount":"123"}
-```
-
-## 用户确认与反问
-
-后端返回意图确认问题、真实提交前需要 credits 确认，或缺少无法安全推断的必需信息时，暂停执行并向用户提问。
-
-1. 优先使用当前 Agent 宿主提供的结构化用户提问或确认工具。
-   - **Codex**：准确工具名是 `request_user_input`。仅在工具已暴露且当前模式允许时调用；不可用时退回普通聊天提问。不要在 Codex 中调用 `ask_user_question`。
-   - **WorkBuddy**：准确工具名是 `ask_user_question`（Ask User Question）。需要用户补充、选择或确认时优先调用；工具未暴露时才退回普通聊天提问。
-   - **Trae 及其他宿主**：先查看当前宿主实际暴露的工具，再使用同类结构化提问、确认或表单工具；不要臆造具体工具名。没有同类工具时退回普通聊天提问。
-2. 涉及 credits 消耗、真实生成、外部提交或不可逆操作时，必须等待用户明确答复；不要默认同意或超时后继续。路由 E 的只读积分余额查询不需要额外确认。
-3. 后端已经给出问题或选项时，保持原意传给用户，不要代替用户回答。
-4. 当前宿主没有结构化提问工具，或当前模式不允许调用时，使用一条简洁的普通聊天问题并暂停。
-5. 收到回复后，把用户答案原样发回同一 `thread_id`，获取新的 `run_id`，再继续轮询；不要新开会话。
-
-## 功能
-
-1. **创建会话 / 发消息** - 创建新会话或向已有会话发送一条消息（如「创作一个视频」）
-2. **查询会话进展** - 根据 `thread_id` 、 `run_id`、`after_seq` 增量拉取该会话的消息列表，用于轮询创作过程的消息和最终产物结果
-3. **上传文件** - 支持上传`单张图片`、`单个视频文件`或`单个mp3/wav音频文件`到小云雀资产库，得到文件对应的 `asset_id`（编辑或参考已有图片/视频/音频时需要先上传）
-4. **下载结果** - 将会话中生成的图片/视频批量下载到本地，支持指定输出目录和文件名前缀。
-5. **图片模型直出** - 使用 `pippit-tool-cli generate-image` 直接调用图片模型，使用 `query-result` 查询并下载图片结果。
-6. **视频模型直出** - 使用 `pippit-tool-cli generate-video` 直接调用视频模型，使用 `query-result` 查询并下载视频结果。
-7. **视频处理** - 使用 `pippit-tool-cli video-super-resolution` 或 `erase-video-subtitle` 处理本地视频，使用 `query-result` 查询并下载视频结果。
-8. **积分余额查询** - 使用 `pippit-tool-cli get-credit-balance` 查询当前凭证所属用户的个人有效积分余额，直接展示 `total_remain_amount`。
-
-
-## 前置要求
-
-### 检查并按需安装 CLI
-
-运行环境需要 Python 3、Node.js 16+，支持执行本地程序。首次安装或自动升级 CLI 时需要 npm、可写的用户缓存目录、访问 npm 源及 GitHub Release 的网络、`curl` 和解压工具（macOS/Linux 的 `tar`，Windows 的 PowerShell）。复用已有 CLI 不需要 npm 或下载网络；安装或升级缺少这些能力时，报告具体安装阻塞。
-
-开始执行本技能任务时运行以下脚本。它先检查 PATH 中的 CLI，再检查自身的安装缓存；找到命令齐全的 CLI 就复用，不访问 npm 或下载二进制。两处均不存在 CLI，或已有 CLI 的必需命令帮助检查返回非零退出码时，获取 npm `latest` 并安装或升级。PATH 中的旧版本缺少命令但缓存可用时，直接复用缓存，不重复升级。同一任务内的提交、轮询、上传和下载复用返回路径。
-
-```bash
-node "{baseDir}/scripts/ensure-cli.js"
-```
-
-需要安装或升级时，脚本跳过 npm 生命周期脚本获取 `@pippit-dev/cli@latest`，再调用包内的 `scripts/install-cli.js` 只安装 CLI。新版本通过全部检查后保存在 `~/.cache/pippit-tool-cli/xyq-skill/<平台>-<架构>/current`，供后续任务复用。它不会安装、清理全局 Skill，也不要求全局 npm 写入权限。安装与检查日志写入 stderr，成功时 stdout 返回 JSON：
-
-```json
-{"cli_path":"/absolute/cache/path/current/node_modules/@pippit-dev/cli/bin/pippit-tool-cli","version":"实际安装版本"}
-```
-
-保存 `cli_path`，后续用它替换所有示例中的 `pippit-tool-cli`。不要依赖上一次 shell 调用中的临时环境变量；Windows PowerShell 用 `& "绝对路径" 参数` 调用。保留安装缓存以便后续任务复用；如果路径已被清理，重新运行安装脚本。
-
-脚本验证 CLI 版本命令，以及 `login`、`submit-run`、`upload-file`、`download-result`、`query-result`、`generate-image`、`generate-video`、`video-super-resolution`、`erase-video-subtitle`、`get-credit-balance` 的 `--help`。检查不发送创作请求，也不需要凭据。已有 CLI 缺少必需命令时自动升级；版本命令无法运行或检查超时时报告运行错误。单次调用最多下载安装一次，最新版本仍不支持必需命令时停止并报告，不反复升级。升级成功前保留原安装；下载失败或最新包缺少只安装 CLI 的入口时，报告安装阻塞。
-
-### 配置凭据
-
-创建会话/发送消息、媒体上传、图片/视频模型直出、视频处理和积分余额查询（路由 A/B/C/D/E）使用原生 CLI。首次使用时运行网页登录，CLI 会自动申请或复用本机专属凭证，并保存到系统安全凭证库：
-
-```bash
-pippit-tool-cli login
-```
-
-`XYQ_ACCESS_KEY` 仅作为原生 CLI 在 CI、Agent 等非交互环境中的显式覆盖。如果该环境变量已经设置但无效，CLI 不会静默改用网页登录凭证，应先修正或取消该环境变量。
-
-路由 D 使用 CLI 提交消息和上传素材；查询进展仍使用独立 Python 脚本 `get_thread.py`。该脚本尚未接入 CLI 的系统安全凭证库，使用前必须配置同一用户的凭证：
-
-```bash
-export XYQ_ACCESS_KEY="your-access-key"
-```
-
-原生 CLI 和保留的 Python 脚本携带用户密钥的 API 请求固定发往 `https://xyq.jianying.com`，不接受 `XYQ_OPENAPI_BASE` 或 `XYQ_BASE_URL` 覆盖。CLI 拒绝 API 跨域重定向，Python API 脚本禁止自动重定向；上传只通过 Authorization 请求头携带密钥。
-
-所有 CLI 路由使用本次安装检查返回的 `cli_path`。保留的 Python 脚本仅使用标准库；安装检查脚本仅使用 Node.js 内置模块。
-
-## 使用方法
-
-### 1. 创建会话 / 发送消息
-
-```bash
-# 创建新会话并发送「生一个动漫视频」
-pippit-tool-cli submit-run --message "生一个动漫视频"
-
-# 向已有会话发送消息
-pippit-tool-cli submit-run --message "再生成一个故事视频" --thread-id THREAD_ID
-
-# 携带多个已上传的素材，每个 ID 重复一次参数
-pippit-tool-cli submit-run --message "根据参考素材生成视频" --asset-ids ASSET_ID1 --asset-ids ASSET_ID2
-```
-
-`--message` 必填且不能全为空白，内容原样发送。`--thread-id` 可选；`--asset-ids` 每次接收一个 ID，多个素材必须重复该参数，不能在一次参数后以空格罗列多个 ID。
-
-### 2. 查询会话进展
-
-```bash
-# 查询会话消息列表
-python3 {baseDir}/scripts/get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE
-```
-
-> `run_id` 由 `submit_run` 返回，用于指定查询某次具体运行的结果。
-
-### 3. 上传文件
-
-先完成“前置要求”的CLI 安装检查，再使用返回的 `cli_path` 调用 `upload-file`；缺少命令时报告版本或安装阻塞。该命令使用 CLI 登录凭证或显式设置的 `XYQ_ACCESS_KEY`，成功输出 `{"asset_id":"..."}`。
-
-- 当用户提供了参考的文件地址时，先进行文件上传，仅支持图片、视频、`.mp3/.wav` 音频。
-- 单次指令执行仅支持单个文件，多个文件可并行调用，单个文件必须小于 500 MB（500000000 字节，达到上限会拒绝上传）。
-
-```bash
-# 上传图片
-pippit-tool-cli upload-file --path /path/to/image.png
-
-# 上传视频
-pippit-tool-cli upload-file --path /path/to/video.mp4
-
-# 上传音频
-pippit-tool-cli upload-file --path /path/to/audio.mp3
-```
-
-### 4. 下载结果
-
-会话 API 路由从 `get_thread.py` 返回的 `messages` 中提取产物 URL，逐文件调用 `pippit-tool-cli download-result` 下载到本地。
-
-- 输出目录沿用用户指定的目录，未指定时使用 `./xyq_output`。
-- 保留原有命名规则：按产物 URL 列表顺序从 `01` 开始编号，有前缀时为 `前缀_01.ext`，无前缀时为 `01.ext`。扩展名优先取 URL 查询参数 `filename` 中的扩展名，其次取 URL 路径的扩展名，无法取得时使用 `.bin`。
-- 将目录和文件名拼成完整的 `--output-path`；每个 URL 调用一次，可最多并行执行 5 个下载命令。重试时保持 URL 与目标路径的对应关系。
-
-```bash
-# 示例：输出目录 ./xyq_output，前缀 artifact，两个 URL 的扩展名分别为 .png 和 .mp4
-pippit-tool-cli download-result --url "URL1" --output-path "./xyq_output/artifact_01.png"
-pippit-tool-cli download-result --url "URL2" --output-path "./xyq_output/artifact_02.mp4"
-```
-
-CLI 默认跳过已存在的目标文件，返回 `already_exist`。仅在来源提供真实的文件更新时间时传入 `--updated-at`（Unix 秒），让 CLI 根据本地文件修改时间决定是否重新下载；不要用当前时间代替远端更新时间。跳过不代表已校验本地内容与远端一致，不能将已知属于其他产物的同名文件当作本次结果。
-
-逐项收集下载结果；单项失败不阻断其他文件，只对失败项重试一次，仍失败则记录该产物、目标路径及 CLI 返回的错误。
-
-## 典型工作流
-
-理解这些工作流，才能正确组合上面的 CLI 和脚本完成用户需求。
-
-### 场景 1：用户要求生成图片或视频（非模型直出）
-
-```
-1. pippit-tool-cli submit-run --message "用户的描述"  →  拿到 thread_id、run_id 和 web_thread_link
-2. **立即**将 `web_thread_link` 展示给用户（如"任务已提交，可在此查看：{web_thread_link}"）
-3. 每隔 `10` 秒钟调用 get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE 进行轮询
-4. 检查 messages：
-  - 当任务还在创作中：
-    - 将过程创作信息展示给用户，继续轮询
-  - 当任务完成（run 结束）：
-    - 如果涉及意图确认/流程中断（如"请回答以下问题"）：
-      → 优先调用当前宿主的结构化用户提问工具展示问题，等待用户回复
-      → 使用 `thread_id` 重新提交任务（保持同一会话，产生新的 run_id）
-      → 回到步骤 2 继续轮询（可能多轮，直到不再意图确认）
-    - 如果 content 中包含产物 URL：
-      → 信息展示 → 下载产物 → 结果展示
-5. 自动下载：按“下载结果”的目录、前缀和编号规则，为每个产物 URL 调用 pippit-tool-cli download-result --url URL --output-path 完整文件路径
-6. 汇总每次调用的下载成功、已存在跳过和失败结果，向用户展示产物链接及对应的本地文件
-```
-
-### 场景 2：用户明确要求图片模型直出
-
-```
-1. 按“前置要求”检查并按需安装 CLI，后续使用返回的 cli_path
-2. 检查图片模型：用户未提供时先询问，不要自行选择
-3. pippit-tool-cli generate-image --prompt "用户原始描述" --model IMAGE_MODEL [仅添加用户已给出的其他参数]
-4. 拿到 thread_id、run_id 和 web_thread_link，立即展示 web_thread_link
-5. 每隔 10 秒调用 query-result --thread-id THREAD_ID --run-id RUN_ID --download-dir OUTPUT_DIR
-6. completed=true 后展示并下载 images[].output_path；出现 error_message 时停止并报告
-```
-
-### 场景 3：用户明确要求视频模型直出（含首尾帧）
-
-```
-1. 按“前置要求”检查并按需安装 CLI，后续使用返回的 cli_path
-2. 普通视频模型直出：pippit-tool-cli generate-video --prompt "用户原始描述" [仅添加用户已给出的其他参数]
-3. 首尾帧直出：确认两张图片的首帧/尾帧角色，按顺序执行 generate-video --image FIRST_FRAME_PATH --image LAST_FRAME_PATH --generate-type 1
-4. 拿到 thread_id、run_id 和 web_thread_link，立即展示 web_thread_link
-5. 每隔 10 秒调用 query-result --thread-id THREAD_ID --run-id RUN_ID --download-dir OUTPUT_DIR
-6. completed=true 后展示并下载 videos[].output_path；出现 error_message 时停止并报告
-```
-
-### 场景 4：用户提供图片/视频/音频要求编辑修改或作为参考（如"参考这个视频做一个新的"、"用这首歌做MV"）
-
-```
-1. pippit-tool-cli upload-file --path /path/to/video.mp4  →  拿到 asset_id1
-2. pippit-tool-cli upload-file --path /path/to/audio.mp3  →  拿到 asset_id2
-3. pippit-tool-cli submit-run --message "参考这个视频并用这首歌做一个新的" --asset-ids asset_id1 --asset-ids asset_id2  →  拿到 thread_id、run_id、web_thread_link
-4. 后续同场景 1 的步骤 2-6
-```
-
-用户给了文件路径 + 编辑指令 = 先上传文件，再把编辑指令和 所有asset_id 一起发送。
-
-### 场景 5：用户提供参考图/视频/音频要求生成新内容
-
-```
-1. pippit-tool-cli upload-file --path /path/to/ref1.png  →  拿到 asset_id1
-2. pippit-tool-cli upload-file --path /path/to/ref2.mp4  →  拿到 asset_id2
-3. pippit-tool-cli upload-file --path /path/to/ref3.mp3  →  拿到 asset_id3
-4. 直到所有文件上传完成，拿到所有 asset_id
-5. pippit-tool-cli submit-run --message "根据参考图、视频、音频生成xxx" --asset-ids asset_id1 --asset-ids asset_id2 --asset-ids asset_id3  →  拿到 thread_id、run_id、web_thread_link
-6. 后续同场景 1 的步骤 2-6
-```
-
-### 场景 6：在已有会话中追加新需求
-
-```
-1. pippit-tool-cli submit-run --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
-2. 后续同场景 1 的步骤 2-6
-```
-
-### 场景 7：用户要求视频超分或擦字幕
-
-```
-1. 按“前置要求”检查并按需安装 CLI，后续使用返回的 cli_path
-2. 根据用户意图调用 video-super-resolution 或 erase-video-subtitle，并传入用户提供的本地视频路径和处理参数
-3. 拿到 thread_id、run_id 和 web_thread_link，立即展示 web_thread_link
-4. 每隔 10 秒调用 query-result --thread-id THREAD_ID --run-id RUN_ID --download-dir OUTPUT_DIR
-5. completed=true 后展示并下载 videos[].output_path；出现 error_message 时停止并报告
-```
-
-### 轮询策略
-
-- **间隔**：每 10 秒查询一次
-- **增量拉取**：首次用 --after-seq 0，后续根据messages消息列表长度，计算新的 seq 值
-- **完成判断**：当创作任务完成且messages的content中包含产物结果 URL（图片/视频地址）
-- **超时**：连续轮询 `48 小时`仍无结果，告知用户"生成时间较长，可稍后查看"，不再继续轮询
-- **错误重试**：单次查询失败可重试 1 次，连续 3 次失败则停止并告知用户
-
-## 输出格式
-
-**pippit-tool-cli submit-run** 返回：
-```json
-{
-  "thread_id": "90f05e0c-...",
-  "run_id": "abc123-...",
-  "web_thread_link": "https://xyq.jianying.com/..."
-}
-```
-
-**get_thread** 返回：
-```json
-{
-  "messages": [
-    {"id": "1", "role": "user", "content": "生一个动漫视频"},
-    {"id": "2", "role": "assistant", "content": [
-      {
-        "type": "{type}",
-        "subtype": "{sub_type}",
-        "data": {...}
-      }
-    ]},
-    {"id": "3", "role": "assistant", "content": [
-      {
-        "type": "{type}",
-        "subtype": "{sub_type}",
-        "data": {..., "url": "{url}"....}
-      }
-    ]}
-  ]
-}
-```
-
-**pippit-tool-cli upload-file** 返回：
-```json
-{
-  "asset_id": "{asset_id}"
-}
-```
-
-**pippit-tool-cli download-result** 每次下载一个文件，成功返回：
-```json
-{
-  "output_path": "./xyq_output/artifact_01.png",
-  "downloaded": ["./xyq_output/artifact_01.png"]
-}
-```
-
-目标文件已存在而跳过时返回：
-```json
-{
-  "output_path": "./xyq_output/artifact_01.png",
-  "downloaded": null,
-  "already_exist": ["./xyq_output/artifact_01.png"]
-}
-```
-
-单文件下载失败时，命令以非零退出码返回错误，不保证输出 JSON；不能只检查 JSON 中是否有 `errors` 来判断成功。由用户侧 Agent 汇总各次调用的 `downloaded`、`already_exist` 和失败项，不再依赖批量返回的 `output_dir`、`total`。
-
-## 会话 API 路由的下载完成标准
-
-- run 结束后，先处理意图确认或流程中断；收到产物 URL 后才进入下载交付。
-- 每个待交付产物都要有对应结果：本次下载成功、已存在而跳过，或下载失败。只有所有产物均已下载或明确复用已有文件时，才能报告本地交付完成。
-- 已存在跳过的文件须单独说明，不能计为本次新下载；仍有失败项时报告“生成已完成，部分产物下载失败”，列出失败项和原始产物链接，不宣称全部下载完成。
-
-## 向用户展示内容
-
-- 任务提交后：立即将 `web_thread_link` 展示给用户，方便用户直接打开浏览器查看任务页面
-- 任务在创作中：
-  - 展示过程中的创作信息等，继续轮询
-- 任务完成（run 结束）：
-  - 若涉及意图确认/流程中断（如"请回答以下问题"）→ 按“用户确认与反问”规则优先调用结构化提问工具 → 等待用户回复 → 使用同一 `thread_id` 重新提交任务 → 继续轮询（可能多轮）
-  - 若 content 中包含产物 URL：展示来自 `get_thread` 返回的 `messages` 的产物链接，以及对应本地文件的可点击绝对路径；区分本次下载、已存在跳过和下载失败，并按上述完成标准说明交付状态。
-
-## 核心原则：用户侧不做创作，只做传话
-
-你（用户侧 Agent）的职责是**搬运工**，不是创作者。会话 API 路由由后端 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt；图片/视频模型直出和视频处理路由把用户原始参数传给 CLI。积分余额查询按路由 E 直接查询并展示余额；以下步骤适用于创作和视频处理任务：
-
-1. **准备素材**：会话 API 路由用 `pippit-tool-cli upload-file` 把本地文件转为 asset_id；图片/视频模型直出和视频处理路由把本地路径直接交给对应 CLI；首尾帧任务固定传 `--generate-type 1` 并保持首帧、尾帧顺序
-2. **提交任务**：先按“执行路由”判断；图片模型直出调用 `pippit-tool-cli generate-image`，视频模型直出调用 `pippit-tool-cli generate-video`，视频超分和擦字幕调用对应的视频处理命令，其余通用创作任务把用户的原始描述 + asset_id 原封不动发给 `pippit-tool-cli submit-run`
-3. **传话**：根据 `get_thread.py` 返回的消息列表，展示过程中的意图询问、创作信息等
-4. **取件**：会话 API 路由用 `get_thread.py` 轮询，图片/视频模型直出和视频处理路由用 `query-result` 轮询 → 检查结果 → 下载产物 → 结果展示给用户
-
-**绝对不要做的事：**
-- 不要替用户扩写、润色、翻译 prompt（用户说"帮我推演分镜"，就直接传"帮我推演分镜"，不要自己先写个分镜表再逐条发）
-- 不要自行编排镜头描述、剧情推演、风格分析
-- 不要在消息中添加自己编的 prompt（如"超写实风格，电影级光影，8K分辨率"之类的描述词）
-
-后端 Agent 对模型能力、参数配置、prompt 工程远比用户侧更专业。用户侧越俎代庖只会降低生成质量，换个弱模型更是灾难。
-
-**正确示例：**
-```
-用户说：「根据多张参考图，做个科普故事视频」
-用户给了参考图：/path/to/ref1.png, /path/to/ref2.png, /path/to/ref3.png
-
-→ pippit-tool-cli upload-file --path /path/to/ref1.png →  拿到 asset_id1
-→ pippit-tool-cli upload-file --path /path/to/ref2.png →  拿到 asset_id2
-→ pippit-tool-cli upload-file --path /path/to/ref3.png →  拿到 asset_id3
-→ pippit-tool-cli submit-run --message "根据参考图、视频生成xxx" --asset-ids asset_id1 --asset-ids asset_id2 --asset-ids asset_id3  →  拿到 web_thread_link，立即展示给用户
-→ 轮询 ─┬─ 意图确认 → 用户确认 → 使用 thread_id 重新提交 → 继续轮询
-        └─ 无意图确认 → 信息展示 → 下载产物 → 结果展示
-```
-
-**错误示例：**
-```
-❌ 用户侧自己先写了个九宫格分镜表（对峙、交锋、危机...）
-❌ 然后把自己编的描述发给后端
-❌ 或者拆成9次 submit_run 分别发送
-```
-
-## 注意事项
-
-- 独立 Python 会话 API 脚本的鉴权方式为请求头 `Authorization: Bearer <XYQ_ACCESS_KEY>`
-- 创建会话时 `message` 是用户的指令要求，不能为空
-- 查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
-- 上传文件仅支持图片（image/*）、视频（video/*）和 `.mp3/.wav` 音频文件，其他类型会被拒绝，文件必须小于 500 MB（500000000 字节）
-- 生成过程中将过程中的创作信息展示给用户；任务完成后给出**产物结果（图片/视频）URL链接**和下载的**本地文件列表**。
-- 图片/视频模型直出和视频处理任务必须保留 CLI 返回的 `thread_id` / `run_id`，并用 `query-result` 取回最终图片或视频。
+- [基础生图到交付](examples/generate-and-deliver.md)：第一次执行完整生成流程。
+- [参考图编辑](examples/image-edit.md)：保留底图与参考图的角色。
+- [首尾帧生视频](examples/first-last-frame.md)：保持素材顺序。
+- [擦字幕后超分](examples/video-process-chain.md)：前一步结果作为下一步输入。
+- [画布内创建角色节点](examples/canvas-role.md)：发现契约、查询真实 ID、编辑后回读。

package/skills/xyq-nest-skill/commands/auth.md

@@ -0,0 +1,35 @@
+# 登录授权：status / login / logout
+
+适用于检查登录、首次授权、退出和切换账号。所有业务命令共享 CLI 凭据，无需为查询或媒体处理单独设置密钥。
+
+## 调用与结果
+
+```bash
+pippit-tool-cli status
+```
+
+读取 JSON 的 `logged_in`、`source`，以及存在时的 `uid`、`expires_at`。`logged_in=true` 表示 CLI 找到了可用凭据，不保证服务端尚未撤销凭据或具有某个模型的使用权限。
+
+未登录时执行：
+
+```bash
+pippit-tool-cli login
+```
+
+引导用户在 CLI 提供的浏览器页面完成授权，等待命令成功返回 `logged_in=true`。CLI 自动申请或复用本机凭据并保存到系统安全凭证库。无浏览器交互能力且没有可用凭据时，报告授权阻塞。
+
+用户要求退出时执行：
+
+```bash
+pippit-tool-cli logout
+```
+
+`logged_out=true` 表示清除了本机浏览器登录凭据；`remote_credential_preserved=true` 表示远端密钥未撤销。切换账号时先退出，再重新登录，在新授权页选择目标账号；不要刷新旧授权页。
+
+## 显式凭据覆盖与故障处理
+
+- `XYQ_ACCESS_KEY` 是 CI、Agent 等环境的显式覆盖，优先于网页登录凭据。已设置但无效时不会自动回退；应修正该环境的配置或取消覆盖，再重试原操作。
+- `logout` 不清除环境变量；返回 `environment_still_active=true` 时，显式密钥仍生效。不要把本机退出解释成所有凭据均已失效。
+- 浏览器登录凭据被服务端拒绝时可使用 `pippit-tool-cli login --force` 轮换本机密钥；不要作为每次调用的例行步骤。
+- 不展示、回显或把密钥写入文档和命令参数。错误信息中出现凭据时，向用户展示前须隐藏凭据。
+- 带凭据的 API 请求固定发往 `https://xyq.jianying.com`，不通过修改 API 域名修复鉴权问题。

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

@@ -0,0 +1,32 @@
+# Canvas 原生资产命令
+
+本页命令通过 `cli_path` 执行。仅面向个人画布，所有 ID 保持原始字符串，不能转换成 JavaScript Number；`project_id`、`canvas_asset_id`、节点 ID 和媒体 `pippit_asset_id` 不可混用。
+
+| 命令 | 输入 | 返回与完成判断 |
+| --- | --- | --- |
+| `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 allocate` | `--count` 分配数量 | 返回 `asset_ids[]`；只预留 ID，不创建节点或资产 |
+| `canvas apply` | `--project-id` 项目 ID；`--file` JSON 文件，默认 `-` 读 stdin | 一个 transaction，可含多条 patch；检查事务 ACK 和目标资产版本 |
+
+```bash
+pippit-tool-cli canvas create --title "产品方案" --wait
+pippit-tool-cli canvas get --asset-id CANVAS_ASSET_ID
+pippit-tool-cli canvas upload --path "/path/to/reference.png"
+```
+
+示例代表不同操作，不应因为读到示例就全部执行。创建、上传可能以退出码 0 返回 `creating` / `processing` 和 `warning`：保留已返回的 ID，稍后用 `canvas get` 回查资产可见性；不要重复创建或上传。画布初始化概览尚未完成时，回查根资产仅证明资产可见，不足以宣称所有初始化完成，应保留 `web_url` 和原始状态说明限制。`request_id` 用于追踪，不能假定跨故障重试严格幂等。
+
+## 低层事务的使用边界
+
+普通节点和领域编辑优先使用 [语义命令](canvas.md)，由 SDK 分配 ID 并构造事务。仅在用户确实提供或需要底层资产事务且契约已核实时执行：
+
+```bash
+pippit-tool-cli canvas allocate --count 2
+pippit-tool-cli canvas apply --project-id PROJECT_ID --file "/path/to/validated-patch.json"
+```
+
+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 校验。