@pippit-dev/cli 1.0.22 → 1.0.23

package/scripts/install-cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+const { install } = require("./install");
+
+if (require.main === module) {
+  if (process.argv.length === 3 && process.argv[2] === "--help") {
+    console.log("Usage: node scripts/install-cli.js\nInstall this package's CLI binary without changing global Skills.");
+  } else if (process.argv.length !== 2) {
+    console.error("Unsupported arguments. Usage: node scripts/install-cli.js");
+    process.exitCode = 1;
+  } else {
+    try {
+      install({ cliOnly: true });
+    } catch (err) {
+      console.error(`Failed to install pippit-tool-cli: ${err.message || err}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/scripts/install.js

@@ -115,7 +115,7 @@ function extractArchive(archivePath, destDir) {
   run("tar", ["-xzf", archivePath, "-C", destDir]);
 }
 
-function install() {
+function install({ cliOnly = false } = {}) {
   if (!platform || !arch) {
     throw new Error(`Unsupported platform: ${process.platform}-${process.arch}`);
   }
@@ -133,11 +133,13 @@ function install() {
     fs.copyFileSync(extracted, dest);
     fs.chmodSync(dest, 0o755);
 
-    if (process.env.PIPPIT_CLI_SKIP_SKILLS !== "1") {
-      installSkillsFromRoot(ROOT);
-      reportBundledSkillTelemetry("install", "npm_install");
-    } else {
-      cleanupLegacyGlobalSkills();
+    if (!cliOnly) {
+      if (process.env.PIPPIT_CLI_SKIP_SKILLS !== "1") {
+        installSkillsFromRoot(ROOT);
+        reportBundledSkillTelemetry("install", "npm_install");
+      } else {
+        cleanupLegacyGlobalSkills();
+      }
     }
     console.log(`${NAME} v${VERSION} installed successfully`);
   } finally {

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

@@ -1,6 +1,6 @@
 ---
 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。短剧生成、续写、改写、人物设定和分集创作应使用 xyq-short-drama-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。
 user-invocable: true
 metadata:
   {
@@ -9,7 +9,7 @@ metadata:
         "emoji": "💬",
         "requires":
           {
-            "bins": ["python3"],
+            "bins": ["python3", "node"],
             "env": ["XYQ_ACCESS_KEY"]
           },
         "primaryEnv": "XYQ_ACCESS_KEY"
@@ -23,6 +23,8 @@ metadata:
 
 小云雀是一个 AI 综合创作平台，同时为人类创作者和 Agent 设计。Agent 通过 Skill 入口理解任务、调用模型并自动编排工作流。
 
+每次开始执行本技能任务时，先按“前置要求”运行 `scripts/ensure-cli.js`，检查已有 CLI，不存在或缺少必需命令时获取最新版本。本文命令中的 `pippit-tool-cli` 均代表该脚本返回的 `cli_path`；实际执行时替换为带引号的绝对路径。
+
 **平台核心能力：**
 - **生成**：文生图、文生视频、图生视频、视频续写
 - **编辑**：局部修改、元素替换、镜头调整、风格迁移
@@ -33,11 +35,11 @@ metadata:
 
 ## 执行路由（必须先判断）
 
-积分余额查询优先走路由 F，不进入创作、视频处理或短剧工作流。
+积分余额查询优先走路由 E，不进入创作或视频处理工作流。
 
 ### 路由 A：图片模型直出
 
-满足任一条件时，必须直接使用 `pippit-tool-cli generate-image`，不要改走 `submit_run.py`：
+满足任一条件时，必须直接使用 `pippit-tool-cli generate-image`，不要改走 `pippit-tool-cli submit-run`：
 
 - 用户明确说“图片模型直出”、“直接调图片模型”或明确要求用 CLI 生图。
 - 用户指定了具体图片模型（如 `seedream_5.0_pro`），并希望单次直接生成图片。
@@ -45,7 +47,7 @@ metadata:
 
 执行原则：
 
-1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用时报告阻塞，不要悄悄降级到会话 API。
+1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
 2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
 3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
 4. `--model` 必填；用户未提供图片模型时，先询问使用哪个模型。只添加用户已经给出的 `--ratio`、`--resolution`、`--generate-image-count`、`--image` 参数，不补默认值。
@@ -70,7 +72,7 @@ pippit-tool-cli query-result \
 
 ### 路由 B：视频模型直出
 
-满足任一条件时，必须直接使用 `pippit-tool-cli generate-video`，不要改走 `submit_run.py`：
+满足任一条件时，必须直接使用 `pippit-tool-cli generate-video`，不要改走 `pippit-tool-cli submit-run`：
 
 - 用户明确说“视频模型直出”、“直接调模型”或“直接调用 CLI”。
 - 用户指定了具体视频模型（如 `Seedance_2.5`），并希望单次直接生成视频。
@@ -79,7 +81,7 @@ pippit-tool-cli query-result \
 
 执行原则：
 
-1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用时报告阻塞，不要悄悄降级到会话 API。
+1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
 2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
 3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
 4. 只添加用户已经给出的 `--model`、`--duration`、`--ratio`、`--resolution`、`--image`、`--video`、`--audio`、`--generate-type` 参数；未给参数交给 CLI 默认值。
@@ -107,14 +109,14 @@ pippit-tool-cli query-result \
 
 ### 路由 C：视频超分和擦字幕
 
-用户明确要求视频超分、提升视频清晰度、擦字幕或去字幕时，直接调用对应的 `pippit-tool-cli` 视频处理命令，不要改走 `submit_run.py`：
+用户明确要求视频超分、提升视频清晰度、擦字幕或去字幕时，直接调用对应的 `pippit-tool-cli` 视频处理命令，不要改走 `pippit-tool-cli submit-run`：
 
 - 视频超分、提升视频清晰度：`video-super-resolution`
 - 擦字幕、去字幕：`erase-video-subtitle`
 
 执行原则：
 
-1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用时报告阻塞，不要悄悄降级到会话 API。
+1. 执行前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path`；失败时报告阻塞，不要悄悄降级到会话 API。
 2. 真实提交会消耗 credits；如果用户本轮尚未明确确认处理，按“用户确认与反问”规则征得明确确认后再运行。
 3. 把用户提供的本地视频路径和处理参数直接交给对应 CLI；缺少必填输入时先询问用户。
 4. 命令返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
@@ -136,19 +138,17 @@ pippit-tool-cli query-result \
 
 ### 路由 D：小云雀后端 Agent 编排
 
-需要意图确认、脚本/分镜拆解、MV、TVC、局部编辑、复杂参考素材编排，或者用户未明确要求模型直出的创作需求，继续使用本技能内置的 `submit_run.py` / `get_thread.py` 会话工作流；明确的首尾帧请求走路由 B，明确的视频超分和擦字幕请求走路由 C；积分余额查询走路由 F。
-
-### 路由 E：短剧工作流
+需要意图确认、脚本/分镜拆解、MV、TVC、局部编辑、复杂参考素材编排，或者用户未明确要求模型直出的创作需求，使用 `pippit-tool-cli submit-run` 提交消息，再用 `get_thread.py` 查询会话进展；明确的首尾帧请求走路由 B，明确的视频超分和擦字幕请求走路由 C；积分余额查询走路由 E。
 
-用户要求短剧生成、续写、改写、剧情扩展、人物设定、分集草稿或短剧会话文件处理时，停止本技能流程并转交 `xyq-short-drama-skill`，不要用 `submit_run.py`、`generate-image` 或 `generate-video` 假装执行完整短剧流程。
+提交前完成“前置要求”的CLI 安装检查，使用返回的 `cli_path` 调用 `submit-run`；失败时报告版本或安装阻塞。
 
-### 路由 F：积分余额查询
+### 路由 E：积分余额查询
 
 用户询问小云雀“积分余额”、“还剩多少积分”、“剩余 credits”或要求查询个人有效积分时，直接使用 `pippit-tool-cli get-credit-balance`。
 
 执行原则：
 
-1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用或版本不支持该命令时报告阻塞，不要改走 `submit_run.py`。
+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"` 是有效的零余额。查询失败或缺少余额字段时报告错误，不得当作零余额。
@@ -175,7 +175,7 @@ pippit-tool-cli get-credit-balance --with-log-id
    - **Codex**：准确工具名是 `request_user_input`。仅在工具已暴露且当前模式允许时调用；不可用时退回普通聊天提问。不要在 Codex 中调用 `ask_user_question`。
    - **WorkBuddy**：准确工具名是 `ask_user_question`（Ask User Question）。需要用户补充、选择或确认时优先调用；工具未暴露时才退回普通聊天提问。
    - **Trae 及其他宿主**：先查看当前宿主实际暴露的工具，再使用同类结构化提问、确认或表单工具；不要臆造具体工具名。没有同类工具时退回普通聊天提问。
-2. 涉及 credits 消耗、真实生成、外部提交或不可逆操作时，必须等待用户明确答复；不要默认同意或超时后继续。路由 F 的只读积分余额查询不需要额外确认。
+2. 涉及 credits 消耗、真实生成、外部提交或不可逆操作时，必须等待用户明确答复；不要默认同意或超时后继续。路由 E 的只读积分余额查询不需要额外确认。
 3. 后端已经给出问题或选项时，保持原意传给用户，不要代替用户回答。
 4. 当前宿主没有结构化提问工具，或当前模式不允许调用时，使用一条简洁的普通聊天问题并暂停。
 5. 收到回复后，把用户答案原样发回同一 `thread_id`，获取新的 `run_id`，再继续轮询；不要新开会话。
@@ -194,7 +194,29 @@ pippit-tool-cli get-credit-balance --with-log-id
 
 ## 前置要求
 
-图片/视频模型直出、视频处理和积分余额查询（路由 A/B/C/F）使用原生 CLI。首次使用时运行网页登录，CLI 会自动申请或复用本机专属凭证，并保存到系统安全凭证库：
+### 检查并按需安装 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
@@ -202,15 +224,15 @@ pippit-tool-cli login
 
 `XYQ_ACCESS_KEY` 仅作为原生 CLI 在 CI、Agent 等非交互环境中的显式覆盖。如果该环境变量已经设置但无效，CLI 不会静默改用网页登录凭证，应先修正或取消该环境变量。
 
-默认的后端 Agent 编排（路由 D）仍由独立 Python 脚本 `submit_run.py`、`get_thread.py` 和 `upload_file.py` 执行。这些脚本尚未接入 CLI 的系统安全凭证库，使用前必须配置：
+路由 D 使用 CLI 提交消息和上传素材；查询进展仍使用独立 Python 脚本 `get_thread.py`。该脚本尚未接入 CLI 的系统安全凭证库，使用前必须配置同一用户的凭证：
 
 ```bash
 export XYQ_ACCESS_KEY="your-access-key"
 ```
 
-可选：`XYQ_OPENAPI_BASE` 或 `XYQ_BASE_URL`，默认 `https://xyq.jianying.com`。
+原生 CLI 和保留的 Python 脚本携带用户密钥的 API 请求固定发往 `https://xyq.jianying.com`，不接受 `XYQ_OPENAPI_BASE` 或 `XYQ_BASE_URL` 覆盖。CLI 拒绝 API 跨域重定向，Python API 脚本禁止自动重定向；上传只通过 Authorization 请求头携带密钥。
 
-会话 API 路由无需安装额外依赖，仅使用 Python 标准库。图片/视频模型直出、视频处理和积分余额查询路由要求 `pippit-tool-cli` 在 `PATH` 中可用。
+所有 CLI 路由使用本次安装检查返回的 `cli_path`。保留的 Python 脚本仅使用标准库；安装检查脚本仅使用 Node.js 内置模块。
 
 ## 使用方法
 
@@ -218,12 +240,17 @@ export XYQ_ACCESS_KEY="your-access-key"
 
 ```bash
 # 创建新会话并发送「生一个动漫视频」
-python3 {baseDir}/scripts/submit_run.py --message "生一个动漫视频"
+pippit-tool-cli submit-run --message "生一个动漫视频"
 
 # 向已有会话发送消息
-python3 {baseDir}/scripts/submit_run.py --message "再生成一个故事视频" --thread-id THREAD_ID
+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
@@ -235,37 +262,48 @@ python3 {baseDir}/scripts/get_thread.py --thread-id THREAD_ID --run-id RUN_ID --
 
 ### 3. 上传文件
 
+先完成“前置要求”的CLI 安装检查，再使用返回的 `cli_path` 调用 `upload-file`；缺少命令时报告版本或安装阻塞。该命令使用 CLI 登录凭证或显式设置的 `XYQ_ACCESS_KEY`，成功输出 `{"asset_id":"..."}`。
+
 - 当用户提供了参考的文件地址时，先进行文件上传，仅支持图片、视频、`.mp3/.wav` 音频。
-- 单次指令执行仅支持单个文件，多个文件可并行调用，单个文件大小必须在200MB以下。
+- 单次指令执行仅支持单个文件，多个文件可并行调用，单个文件必须小于 500 MB（500000000 字节，达到上限会拒绝上传）。
 
 ```bash
 # 上传图片
-python3 {baseDir}/scripts/upload_file.py /path/to/image.png
+pippit-tool-cli upload-file --path /path/to/image.png
 
 # 上传视频
-python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4
+pippit-tool-cli upload-file --path /path/to/video.mp4
 
 # 上传音频
-python3 {baseDir}/scripts/upload_file.py /path/to/audio.mp3
+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
-# 指定 URL 列表，指定输出目录，指定文件名前缀（如 artifact_01.png, artifact_02.png ...）进行下载
-python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./xyq_output --prefix "artifact"
+# 示例：输出目录 ./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. submit_run.py --message "用户的描述"  →  拿到 thread_id、run_id 和 web_thread_link
+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：
@@ -278,14 +316,14 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
       → 回到步骤 2 继续轮询（可能多轮，直到不再意图确认）
     - 如果 content 中包含产物 URL：
       → 信息展示 → 下载产物 → 结果展示
-5. 自动下载：download_results.py --urls URL1 URL2 URL3 --output-dir 输出目录 --prefix 有意义的前缀
-6. 向用户展示：过程中的创作信息，以及下载后的本地文件列表
+5. 自动下载：按“下载结果”的目录、前缀和编号规则，为每个产物 URL 调用 pippit-tool-cli download-result --url URL --output-path 完整文件路径
+6. 汇总每次调用的下载成功、已存在跳过和失败结果，向用户展示产物链接及对应的本地文件
 ```
 
 ### 场景 2：用户明确要求图片模型直出
 
 ```
-1. command -v pippit-tool-cli  →  确认 CLI 可用
+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
@@ -296,7 +334,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 ### 场景 3：用户明确要求视频模型直出（含首尾帧）
 
 ```
-1. command -v pippit-tool-cli  →  确认 CLI 可用
+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
@@ -307,9 +345,9 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 ### 场景 4：用户提供图片/视频/音频要求编辑修改或作为参考（如"参考这个视频做一个新的"、"用这首歌做MV"）
 
 ```
-1. upload_file.py /path/to/video.mp4  →  拿到 asset_id1
-2. upload_file.py /path/to/audio.mp3  →  拿到 asset_id2
-3. submit_run.py --message "参考这个视频并用这首歌做一个新的" --asset-ids asset_id1 asset_id2  →  拿到 thread_id、run_id、web_thread_link
+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
 ```
 
@@ -318,25 +356,25 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 ### 场景 5：用户提供参考图/视频/音频要求生成新内容
 
 ```
-1. upload_file.py /path/to/ref1.png  →  拿到 asset_id1
-2. upload_file.py /path/to/ref2.mp4  →  拿到 asset_id2
-3. upload_file.py /path/to/ref3.mp3  →  拿到 asset_id3
+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. submit_run.py --message "根据参考图、视频、音频生成xxx" --asset-ids asset_id1 asset_id2 asset_id3, ...  →  拿到 thread_id、run_id、web_thread_link
+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. submit_run.py --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
+1. pippit-tool-cli submit-run --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
 2. 后续同场景 1 的步骤 2-6
 ```
 
 ### 场景 7：用户要求视频超分或擦字幕
 
 ```
-1. command -v pippit-tool-cli  →  确认 CLI 可用
+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
@@ -353,7 +391,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 
 ## 输出格式
 
-**submit_run** 返回：
+**pippit-tool-cli submit-run** 返回：
 ```json
 {
   "thread_id": "90f05e0c-...",
@@ -385,22 +423,38 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 }
 ```
 
-**upload_file** 返回：
+**pippit-tool-cli upload-file** 返回：
 ```json
 {
   "asset_id": "{asset_id}"
 }
 ```
 
-**download_results** 返回：
+**pippit-tool-cli download-result** 每次下载一个文件，成功返回：
+```json
+{
+  "output_path": "./xyq_output/artifact_01.png",
+  "downloaded": ["./xyq_output/artifact_01.png"]
+}
+```
+
+目标文件已存在而跳过时返回：
 ```json
 {
-  "output_dir": "./xyq_output",
-  "downloaded": ["./xyq_output/01.png", "..."],
-  "total": 10
+  "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` 展示给用户，方便用户直接打开浏览器查看任务页面
@@ -408,15 +462,14 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
   - 展示过程中的创作信息等，继续轮询
 - 任务完成（run 结束）：
   - 若涉及意图确认/流程中断（如"请回答以下问题"）→ 按“用户确认与反问”规则优先调用结构化提问工具 → 等待用户回复 → 使用同一 `thread_id` 重新提交任务 → 继续轮询（可能多轮）
-  - 若 content 中包含产物 URL：
-  - 结果地址：来自 `get_thread` 返回的 `messages` 中，任务创作完成会包含产物 URL，将产物链接、下载的本地文件等信息告知用户。
+  - 若 content 中包含产物 URL：展示来自 `get_thread` 返回的 `messages` 的产物链接，以及对应本地文件的可点击绝对路径；区分本次下载、已存在跳过和下载失败，并按上述完成标准说明交付状态。
 
 ## 核心原则：用户侧不做创作，只做传话
 
-你（用户侧 Agent）的职责是**搬运工**，不是创作者。会话 API 路由由后端 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt；图片/视频模型直出和视频处理路由把用户原始参数传给 CLI。积分余额查询按路由 F 直接查询并展示余额；以下步骤适用于创作和视频处理任务：
+你（用户侧 Agent）的职责是**搬运工**，不是创作者。会话 API 路由由后端 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt；图片/视频模型直出和视频处理路由把用户原始参数传给 CLI。积分余额查询按路由 E 直接查询并展示余额；以下步骤适用于创作和视频处理任务：
 
-1. **准备素材**：会话 API 路由用 `upload_file.py` 把本地文件转为 asset_id；图片/视频模型直出和视频处理路由把本地路径直接交给对应 CLI；首尾帧任务固定传 `--generate-type 1` 并保持首帧、尾帧顺序
-2. **提交任务**：先按“执行路由”判断；图片模型直出调用 `pippit-tool-cli generate-image`，视频模型直出调用 `pippit-tool-cli generate-video`，视频超分和擦字幕调用对应的视频处理命令，其余通用创作任务把用户的原始描述 + asset_id 原封不动发给 `submit_run.py`
+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` 轮询 → 检查结果 → 下载产物 → 结果展示给用户
 
@@ -432,10 +485,10 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 用户说：「根据多张参考图，做个科普故事视频」
 用户给了参考图：/path/to/ref1.png, /path/to/ref2.png, /path/to/ref3.png
 
-→ upload_file.py /path/to/ref1.png →  拿到 asset_id1
-→ upload_file.py /path/to/ref2.png →  拿到 asset_id2
-→ upload_file.py /path/to/ref3.png →  拿到 asset_id3
-→ submit_run.py --message "根据参考图、视频生成xxx" --asset-ids asset_id1 asset_id2, asset_id3  →  拿到 web_thread_link，立即展示给用户
+→ 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 重新提交 → 继续轮询
         └─ 无意图确认 → 信息展示 → 下载产物 → 结果展示
 ```
@@ -452,6 +505,6 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 - 独立 Python 会话 API 脚本的鉴权方式为请求头 `Authorization: Bearer <XYQ_ACCESS_KEY>`
 - 创建会话时 `message` 是用户的指令要求，不能为空
 - 查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
-- 上传文件仅支持图片（image/*）、视频（video/*）和 `.mp3/.wav` 音频文件，其他类型会被拒绝，文件大小须在 200MB 以下
+- 上传文件仅支持图片（image/*）、视频（video/*）和 `.mp3/.wav` 音频文件，其他类型会被拒绝，文件必须小于 500 MB（500000000 字节）
 - 生成过程中将过程中的创作信息展示给用户；任务完成后给出**产物结果（图片/视频）URL链接**和下载的**本地文件列表**。
 - 图片/视频模型直出和视频处理任务必须保留 CLI 返回的 `thread_id` / `run_id`，并用 `query-result` 取回最终图片或视频。

package/skills/xyq-nest-skill/scripts/ensure-cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+// Self-contained entrypoint shipped inside the Skill ZIP. No npm dependencies.
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const REQUIRED_COMMANDS = [
+  "login", "submit-run", "upload-file", "download-result", "query-result",
+  "generate-image", "generate-video", "video-super-resolution",
+  "erase-video-subtitle", "get-credit-balance",
+];
+
+function npmCommand() {
+  if (process.platform !== "win32") return ["npm", []];
+  // Run npm's JS entrypoint directly, avoiding cmd.exe quoting for paths with spaces.
+  const dirs = [path.dirname(process.execPath), ...(process.env.PATH || "").split(path.delimiter)];
+  for (const dir of dirs.filter(Boolean)) {
+    const script = path.join(dir, "node_modules", "npm", "bin", "npm-cli.js");
+    if (fs.existsSync(script)) return [process.execPath, [script]];
+  }
+  throw new Error("未找到 npm，请先安装 Node.js 16+ 和 npm。");
+}
+
+function findCLIOnPath() {
+  for (const dir of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.resolve(dir, `pippit-tool-cli${process.platform === "win32" ? ".exe" : ""}`);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      const resolved = fs.realpathSync(candidate);
+      // Bypass the npm JS launcher, which may download a binary or check for updates.
+      if (resolved.endsWith(path.join("scripts", "run.js"))) {
+        const binary = path.resolve(path.dirname(resolved), "../bin/pippit-tool-cli");
+        if (fs.existsSync(binary)) return binary;
+      } else {
+        return candidate;
+      }
+    }
+    if (process.platform === "win32" && fs.existsSync(path.join(dir, "pippit-tool-cli.cmd"))) {
+      const binary = path.resolve(dir, "node_modules/@pippit-dev/cli/bin/pippit-tool-cli.exe");
+      if (fs.existsSync(binary)) return binary;
+    }
+  }
+  return null;
+}
+
+function ensureCLI() {
+  if (Number(process.versions.node.split(".")[0]) < 16) {
+    throw new Error("需要 Node.js 16+ 和 npm。");
+  }
+  if (!["darwin", "linux", "win32"].includes(process.platform)
+      || !["x64", "arm64"].includes(process.arch)) {
+    throw new Error(`不支持的平台：${process.platform}-${process.arch}`);
+  }
+  const cacheDir = path.join(os.homedir(), ".cache", "pippit-tool-cli", "xyq-skill", `${process.platform}-${process.arch}`);
+  const installedDir = path.join(cacheDir, "current");
+  const binaryRelative = path.join("node_modules", "@pippit-dev", "cli", "bin", `pippit-tool-cli${process.platform === "win32" ? ".exe" : ""}`);
+  const cachedCLI = path.join(installedDir, binaryRelative);
+  const env = { ...process.env };
+  delete env.XYQ_ACCESS_KEY;
+  env.PIPPIT_CLI_DISABLE_UPDATE_CHECK = "1";
+  let installDir;
+
+  function run(command, args, label, quiet = false) {
+    try {
+      return execFileSync(command, args, {
+        cwd: installDir, env, timeout: quiet ? 10000 : 180000,
+        stdio: quiet ? ["ignore", "pipe", "pipe"] : ["ignore", 2, 2],
+      });
+    } catch (err) {
+      const failure = new Error(`${label}失败（${err.code || err.status || "unknown"}），请检查安装、命令支持情况和网络。`);
+      failure.exitStatus = err.status;
+      throw failure;
+    }
+  }
+
+  function checkCLI(cliPath, expectedVersion) {
+    const version = run(cliPath, ["--version"], "检查 CLI 版本", true).toString().trim();
+    if (expectedVersion && version !== expectedVersion) {
+      throw new Error(`CLI 版本 ${version} 与 npm 包版本 ${expectedVersion} 不一致。`);
+    }
+    for (const command of REQUIRED_COMMANDS) {
+      try {
+        run(cliPath, [command, "--help"], `检查 ${command} 命令`, true);
+      } catch (err) {
+        if (Number.isInteger(err.exitStatus) && err.exitStatus !== 0) {
+          err.missingCommand = command;
+        }
+        throw err;
+      }
+    }
+    return { cli_path: cliPath, version };
+  }
+
+  const candidates = new Set([findCLIOnPath(), fs.existsSync(cachedCLI) ? cachedCLI : null]);
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try {
+      return checkCLI(candidate);
+    } catch (err) {
+      if (!err.missingCommand) throw err;
+      console.error(`已有 CLI 的 ${err.missingCommand} 命令检查未通过；继续检查缓存，无可用缓存时自动安装最新版本。`);
+    }
+  }
+
+  const [npm, npmArgs] = npmCommand();
+  fs.mkdirSync(cacheDir, { recursive: true });
+  installDir = fs.mkdtempSync(path.join(cacheDir, "install-"));
+  try {
+    run(npm, [...npmArgs, "install", "--prefix", installDir,
+      "--cache", path.join(installDir, ".npm-cache"), "--global=false", "--no-save",
+      "--package-lock=false", "--ignore-scripts", "--prefer-online",
+      "--no-audit", "--no-fund", "@pippit-dev/cli@latest"], "下载最新 npm 包");
+    const packageDir = path.join(installDir, "node_modules", "@pippit-dev", "cli");
+    const installer = path.join(packageDir, "scripts", "install-cli.js");
+    if (!fs.existsSync(installer)) {
+      throw new Error("npm latest 尚未提供 scripts/install-cli.js，请先发布包含只安装 CLI 入口的版本。");
+    }
+    run(process.execPath, [installer], "下载并安装最新 CLI 二进制");
+    const cliPath = path.join(packageDir, "bin", `pippit-tool-cli${process.platform === "win32" ? ".exe" : ""}`);
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    const result = checkCLI(cliPath, pkg.version);
+    // Preserve the previous installation until the replacement passes all checks.
+    fs.rmSync(installedDir, { recursive: true, force: true });
+    fs.renameSync(installDir, installedDir);
+    return { ...result, cli_path: cachedCLI };
+  } catch (err) {
+    fs.rmSync(installDir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+if (require.main === module) {
+  if (process.argv.length === 3 && process.argv[2] === "--help") {
+    console.log("Usage: node ensure-cli.js\n优先复用 PATH 或缓存中命令齐全的 CLI，不存在或缺少必需命令时安装 npm latest，成功输出 {cli_path, version} JSON。");
+  } else if (process.argv.length !== 2) {
+    console.error("不支持的参数。用法：node ensure-cli.js");
+    process.exitCode = 1;
+  } else {
+    try {
+      console.log(JSON.stringify(ensureCLI()));
+    } catch (err) {
+      console.error(err.message);
+      process.exitCode = 1;
+    }
+  }
+}
+
+module.exports = { ensureCLI };

package/skills/xyq-nest-skill/scripts/get_thread.py

@@ -17,7 +17,7 @@ def main():
         epilog="""
 环境变量:
   XYQ_ACCESS_KEY  必填，Bearer 鉴权
-  XYQ_OPENAPI_BASE 或 XYQ_BASE_URL  可选，默认 https://xyq.jianying.com
+  API 地址固定为 https://xyq.jianying.com，不支持环境变量覆盖
 
 示例:
   python3 get_thread.py --thread-id abc123 --run-id def456 --after-seq 0