@pippit-dev/cli 0.0.18 → 0.0.20

package/README.md

@@ -1,11 +1,195 @@
 # pippit-tool-cli
 
-Minimal demo CLI for Pippit workflows.
+面向 Pippit / 小云雀工作流的命令行工具与智能体技能集合。
 
-## Short Drama Run Demo
+## 技能列表
 
-Install from npm after the package is published. The installer downloads the
-matching prebuilt binary for macOS, Linux, or Windows:
+本仓库在 `skills/` 目录下包含两个智能体技能：
+
+| 技能 | 说明 | 路径 |
+|-------|-------------|------|
+| `pippit-short-drama-skill` | 短剧工作流技能，支持提交创作任务、上传参考文件、查询进度、列出会话文件和下载产物。 | `skills/short-drama/` |
+| `xyq-nest-skill` | 通用 NestAgent 技能，支持图片/视频生成、编辑、文件上传、进度查询和结果下载。 | `skills/xyq-nest-skill/` |
+
+## 通用 NestAgent 技能
+
+`xyq-nest-skill` 通过接入小云雀 NestAgent 的综合创作能力，实现 AI 图片/视频生成、编辑、风格转换、文件上传、进度查询和结果下载。
+
+### 功能特性
+
+| 功能 | 说明 |
+|------|------|
+| 创建会话 / 发送消息 | 向小云雀发送自然语言指令，生成图片或视频。 |
+| 查询会话进展 | 增量拉取会话消息，轮询创作进度和产物结果。 |
+| 上传文件 | 上传图片/视频到小云雀资产库，获取 `asset_id` 用于编辑和参考。 |
+| 下载结果 | 批量下载生成的图片/视频到本地，支持并行下载。 |
+
+小云雀平台能力覆盖：
+
+- 生成：文生图、文生视频、图生视频、视频续写。
+- 编辑：局部修改、元素替换、镜头调整、风格迁移。
+- 复杂创作：一句话生成短剧、复刻视频/TVC/宣传片、音乐 MV 生成、产品展示片制作。
+
+### 配置
+
+所有 `xyq-nest-skill` 脚本都使用 Bearer 令牌鉴权：
+
+```bash
+export XYQ_ACCESS_KEY="<access-key>"
+```
+
+可选 API 地址：
+
+```bash
+export XYQ_OPENAPI_BASE="https://xyq.jianying.com"
+# 或
+export XYQ_BASE_URL="https://xyq.jianying.com"
+```
+
+### 创建会话 / 发送消息
+
+```bash
+# 创建新会话
+python3 skills/xyq-nest-skill/scripts/submit_run.py --message "生一个动漫视频"
+
+# 向已有会话发送消息
+python3 skills/xyq-nest-skill/scripts/submit_run.py \
+  --message "再生成一个故事视频" \
+  --thread-id THREAD_ID
+
+# 携带参考文件发送
+python3 skills/xyq-nest-skill/scripts/submit_run.py \
+  --message "参考这个视频做修改" \
+  --asset-ids asset_id1 asset_id2
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--message` | 是 | 创作指令内容。 |
+| `--thread-id` | 否 | 已有会话 ID，不传则创建新会话。 |
+| `--asset-ids` | 否 | 资产 ID 列表，支持多个。 |
+
+返回示例：
+
+```json
+{
+  "thread_id": "90f05e0c-...",
+  "run_id": "abc123-..."
+}
+```
+
+### 查询会话进展
+
+```bash
+python3 skills/xyq-nest-skill/scripts/get_thread.py \
+  --thread-id THREAD_ID \
+  --run-id RUN_ID \
+  --after-seq 0
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--thread-id` | 是 | 会话 ID。 |
+| `--run-id` | 否 | 运行 ID。 |
+| `--after-seq` | 否 | 增量拉取起始序号，默认 `0`。 |
+
+脚本会返回会话消息和产物条目。后续轮询时，根据已获取消息更新 `after_seq`。
+
+### 上传文件
+
+```bash
+# 上传图片
+python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/image.png
+
+# 上传视频
+python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/video.mp4
+```
+
+仅支持 `image/*` 和 `video/*` 类型，单文件大小限制 200 MB。
+
+返回示例：
+
+```json
+{
+  "asset_id": "asset_xxx"
+}
+```
+
+### 下载结果
+
+```bash
+python3 skills/xyq-nest-skill/scripts/download_results.py \
+  --urls URL1 URL2 URL3 \
+  --output-dir ./xyq_output \
+  --prefix "storyboard" \
+  --workers 5
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--urls` | 是 | 要下载的 URL 列表。 |
+| `--output-dir` | 否 | 输出目录，默认 `./xyq_output`。 |
+| `--prefix` | 否 | 文件名前缀，例如 `storyboard_01.png`。 |
+| `--workers` | 否 | 并行下载线程数，默认 `5`。 |
+
+返回示例：
+
+```json
+{
+  "output_dir": "./xyq_output",
+  "downloaded": ["./xyq_output/storyboard_01.png"],
+  "total": 1
+}
+```
+
+### 典型示例
+
+文生视频：
+
+```text
+1. submit_run.py --message "生成一个赛博朋克风格的城市夜景视频"
+2. 每 10 秒轮询：
+   get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE
+3. 拿到产物 URL 后下载：
+   download_results.py --urls URL1 URL2 --output-dir ./output --prefix "cyberpunk"
+```
+
+编辑已有视频：
+
+```text
+1. upload_file.py /path/to/video.mp4
+2. submit_run.py --message "把背景换成星空" --asset-ids asset_id
+3. 按文生视频流程轮询和下载。
+```
+
+多参考图/视频生成：
+
+```text
+1. upload_file.py /path/to/ref1.png
+2. upload_file.py /path/to/ref2.png
+3. upload_file.py /path/to/ref3.mp4
+4. submit_run.py --message "根据参考图和视频生成科普故事视频" --asset-ids asset_id1 asset_id2 asset_id3
+5. 按文生视频流程轮询和下载。
+```
+
+在已有会话中追加需求：
+
+```text
+1. submit_run.py --message "把刚才的视频加个片头" --thread-id EXISTING_THREAD_ID
+2. 使用新的 run_id 轮询和下载。
+```
+
+轮询策略：
+
+- 间隔：每 10 秒查询一次。
+- 增量拉取：首次 `--after-seq 0`，后续根据已获取消息数更新 seq。
+- 意图确认：如果智能体追问用户，先展示问题，再用同一个 `thread_id` 提交用户回复。
+- 超时：连续轮询 48 小时无结果则停止。
+- 错误重试：单次失败可重试 1 次，连续 3 次失败则停止。
+
+## 短剧工作流技能
+
+包发布后可以通过 npm 安装。安装器会按当前系统下载匹配的预构建二进制文件，支持 macOS、Linux 和 Windows：
 
 ```bash
 npx @pippit-dev/cli@latest install
@@ -17,43 +201,17 @@ pippit-tool-cli short-drama +get-thread --thread-id thread_123 --run-id run_456
 pippit-tool-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
 ```
 
-NPM package names must be lowercase, so the publishable package name is
-`@pippit-dev/cli` rather than `@Pippit-dev/cli`.
+`+submit-run`: 输出 `thread_id`、`run_id` 和 `web_thread_link`；其中 `--message` 为必填参数。
+`+get-thread`: 请求中带 `version=v2`，并输出 `readable_text`。
+`+upload-file`: 输出返回的 `asset_id`。 当前仅支持 `.doc`、`.docx` 和 `.txt` 文件。
+`+download-result`: 会把结果 URL 下载到 `--output-path` 指定的文件路径。
 
-Submit a Run task for the short drama scene:
+短剧命令的错误日志会追加写入本地每日日志文件：`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`。日志路径会基于当前用户主目录和系统路径分隔符生成，因此可在 macOS、Linux 和 Windows 上使用。
 
-```bash
-export XYQ_ACCESS_KEY="<access-key>"
-go run . --version
-go run . short-drama +submit-run --message "写一个赛博朋克短剧开头"
-go run . short-drama +upload-file --path ./reference.doc
-go run . short-drama +get-thread --thread-id thread_123 --run-id run_456
-go run . short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
-```
-
-`+submit-run` calls `/api/biz/v1/skill/submit_run` and prints `thread_id`,
-`run_id`, and `web_thread_link`; `--message` is required.
-`+get-thread` calls
-`/api/biz/v1/skill/get_thread` with `version=v2` and prints `readable_text`.
-`+upload-file` calls `/api/biz/v1/skill/upload_file` with
-`multipart/form-data` and prints the returned `asset_id`.
-Only `.doc`, `.docx`, and `.txt` file extensions are supported.
-`+download-result` downloads the result URL to
-the `--output-path` file path.
-
-Short drama command errors are appended to a daily local log file under
-`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`. The path is built with the current
-user home directory and the platform path separator, so it works on macOS,
-Linux, and Windows.
-
-## HTTP Client
-
-Command modules should receive `common.Runner` for service calls. Runtime
-settings such as base URL, HTTP timeout, and API paths are loaded by
-`internal/config` and paired with `common.Client` in the runner.
-
-## Auth
-
-`short-drama +submit-run`, `short-drama +get-thread`, and `short-drama +upload-file` authenticate with
-`Authorization: Bearer <XYQ_ACCESS_KEY>`. OAuth command code remains available,
-but runtime short drama requests do not use it.
+## HTTP 客户端
+
+命令模块通过 `common.Runner` 发起服务调用。运行时配置，例如基础地址、HTTP 超时时间和接口路径，由 `internal/config` 加载，并在运行器中与 `common.Client` 组合使用。
+
+## 鉴权
+
+`short-drama +submit-run`、`short-drama +get-thread`、`short-drama +upload-file` 以及 `xyq-nest-skill` Python 脚本都使用 `Authorization: Bearer <XYQ_ACCESS_KEY>` 鉴权。OAuth 命令代码仍保留在仓库中，但短剧运行时请求不使用 OAuth。

package/checksums.txt

@@ -1,6 +1,6 @@
-2cd3bb5e214d85004196806643c3b7d0a8ceb141ef3df58d1bbfc7aa9642f6ab  pippit-tool-cli-0.0.18-darwin-amd64.tar.gz
-8fb57bef9d7e81b8bcc3421f2179879b656134c23387104e01a1090022f6e7c9  pippit-tool-cli-0.0.18-darwin-arm64.tar.gz
-bdde278cbee36f2b90602b1b58f7be05790a186b3adbc90b8dd8fd970b48b20c  pippit-tool-cli-0.0.18-linux-amd64.tar.gz
-878c6b0cd41a2cafdd62f99be98968eee05f0d16de0c6b173f84bb0328c1bef6  pippit-tool-cli-0.0.18-linux-arm64.tar.gz
-e4423154ba1a52625f255e11060459844a4c5bcf3aab21af682f3e1adcce82cd  pippit-tool-cli-0.0.18-windows-amd64.zip
-cca47eab19bdc7200aabcea2d59a535c63267fe293f993b1013aa049a4be16b4  pippit-tool-cli-0.0.18-windows-arm64.zip
+200e40ca3a4ef54a76860bcbe807233fc548d5686eea8b4bb5069f4d393e6fd2  pippit-tool-cli-0.0.20-darwin-amd64.tar.gz
+2371e7b72c39b8b590604afe1abdba34e583b69ad787a78913b306de0145401b  pippit-tool-cli-0.0.20-darwin-arm64.tar.gz
+1df765184d0f7061c15e2829c7792f7982eeb711da534f3883488efc34b02b5d  pippit-tool-cli-0.0.20-linux-amd64.tar.gz
+d5e0d1fcd774cc7d05ab3c749fff79e7f3507e8f92c0c5abaed4ef884ff46f20  pippit-tool-cli-0.0.20-linux-arm64.tar.gz
+0ccfa68f9fd289b680756ba664a82d68af6636c1337368946c53fc58d74f1f2a  pippit-tool-cli-0.0.20-windows-amd64.zip
+2fac1102a7e0fbd75fae736636a3c2e9a2559b7a1a297530f18fa66adc5e11c7  pippit-tool-cli-0.0.20-windows-arm64.zip

package/cmd/update/update.go

@@ -74,7 +74,7 @@ func installSkills(root string, stderr io.Writer) error {
 	} else if !info.IsDir() {
 		return fmt.Errorf("%s is not a directory", filepath.Join(root, "skills"))
 	}
-	return runInherit(stderr, "npx", "-y", "skills", "add", root, "-g", "-y")
+	return runInherit(stderr, "npx", "-y", "skills", "add", root, "-g", "-y", "--skill", "*")
 }
 
 func runInherit(stderr io.Writer, name string, args ...string) error {

package/cmd/update/update_test.go

@@ -0,0 +1,47 @@
+package updatecmd
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestInstallSkillsInstallsAllBundledSkills(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("test uses a POSIX shell script to stub npx")
+	}
+
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, "skills"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	binDir := t.TempDir()
+	capturePath := filepath.Join(t.TempDir(), "args.txt")
+	npxPath := filepath.Join(binDir, "npx")
+	script := "#!/bin/sh\nfor arg in \"$@\"; do printf '%s\\n' \"$arg\"; done > \"$CAPTURE_ARGS\"\n"
+	if err := os.WriteFile(npxPath, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv("PATH", binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("CAPTURE_ARGS", capturePath)
+
+	var stderr bytes.Buffer
+	if err := installSkills(root, &stderr); err != nil {
+		t.Fatalf("installSkills() error = %v, stderr = %s", err, stderr.String())
+	}
+
+	gotBytes, err := os.ReadFile(capturePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := strings.Split(strings.TrimSpace(string(gotBytes)), "\n")
+	want := []string{"-y", "skills", "add", root, "-g", "-y", "--skill", "*"}
+	if strings.Join(got, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("npx args mismatch\ngot:  %#v\nwant: %#v", got, want)
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Pippit CLI",
   "bin": {
     "pippit-tool-cli": "scripts/run.js"

package/scripts/skills.js

@@ -10,7 +10,7 @@ function installSkillsFromRoot(root, opts = {}) {
   if (!fs.existsSync(skillsDir)) {
     throw new Error(`skills directory not found: ${skillsDir}`);
   }
-  run("npx", ["-y", "skills", "add", source, "-g", "-y"], {
+  run("npx", ["-y", "skills", "add", source, "-g", "-y", "--skill", "*"], {
     timeout: opts.timeout || 120000,
   });
 }

package/skills/short-drama/SKILL.md

@@ -31,6 +31,34 @@ metadata:
 
 重要资产包括但不限于：剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 `+list-thread-file` 返回了这些资产的 `download_url`，就要及时调用下载工具落盘，不要只展示文件元信息。
 
+## 短剧主流程顺序
+
+短剧创作按以下主流程推进。用户侧 Agent 在展示后端 Agent 的表单、问卷、选项或确认问题时，必须先参考这个顺序判断当前阶段和合理下一步。
+
+1. 剧本上传 / AI 剧本生成 / AI 剧本编辑
+2. 剧本合并与完整剧本确认
+3. 剧本分析
+4. 短剧风格推荐确认
+5. 剧本标准化（可选）
+6. 场景分析
+7. 所有必要场景图生成
+8. 角色分析
+9. 所有必要角色图生成
+10. 分镜设计
+11. 分镜视频生成
+12. 完整视频合成
+
+## 表单与问卷选项处理原则
+
+后端 Agent 通过 `readable_text` 发出表单、问卷、选项、按钮或询问用户时，用户侧 Agent 不要机械原样转述所有选项。先结合短剧主流程顺序清洗选项，再把合理、必要、当前可执行的流程项呈现给用户。
+
+- 保留当前阶段的确认项，以及不会跳过必要阶段的下一步流程项。
+- 剔除跳过必要阶段的选项。例如未完成“剧本合并与完整剧本确认”前，不应让用户直接进入“剧本分析”；未完成“所有必要场景图生成”前，不应让用户直接进入“角色分析”。
+- 剔除倒退到无关阶段的选项。只有用户明确要求返工、修改或重新生成时，才展示回退选项。
+- `剧本标准化` 是可选阶段，只能出现在“短剧风格推荐确认”之后、“场景分析”之前。不要把它包装成任意阶段都可以跳过或补做的通用选项。
+- 不替用户决定创意内容，例如风格、剧情方向、角色设定、镜头方案。只能清洗流程选项，不能代替用户选择创作偏好。
+- 如果服务端问题混入跨度过大的多个流程选项，重新组织成当前阶段可回答的问题，并说明已按主流程剔除不合理或跳跃选项。
+
 ## 前置要求
 
 需要已安装 `pippit-tool-cli`：
@@ -167,7 +195,7 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 - **重要资产识别**：每轮都检查 `+list-thread-file` 返回的文件。剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物都是重要资产。
 - **文件下载**：解析 `+list-thread-file` 的结果后，对带 `download_url` 的重要资产立即调用 `+download-result` 下载资源；不要在 `list-thread-file` 阶段检查文件是否已存在，存在性检查由下载工具内部处理。
 - **下载完成标准**：不要把文件元信息展示当成下载完成；必须拿到本地 `file_path`，或明确记录该文件在重试后仍下载失败。
-- **用户确认**：如果消息中出现需要用户确认、补充设定或回答问题的内容，先展示给用户，等待用户回复。
+- **用户确认**：如果消息中出现需要用户确认、补充设定或回答问题的内容，先判断是否包含表单、问卷、选项或按钮；包含时按“短剧主流程顺序”和“表单与问卷选项处理原则”清洗选项，再展示给用户并等待回复。
 - **超时**：如果长时间无结果，告知用户任务仍在生成中，可稍后通过 `web_thread_link` 查看。
 - **错误处理**：`+get-thread`、`+list-thread-file` 或 `+download-result` 任一调用失败时，记录失败原因和参数，在后续轮询中主动重试；重试期间继续处理其他成功返回的消息和文件。连续多轮失败后再向用户说明仍未完成的查询或下载项。
 
@@ -178,7 +206,8 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 1. 已处理 `+get-thread` 返回的最新 `readable_text`、用户确认问题和最终消息。
 2. 已用 `--page-size 200` 调用 `+list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 200，已在后续轮询中递增 `page-num` 查询新一页。
 3. 对所有带 `download_url` 的重要资产，已调用 `+download-result` 下载到本地 `file_path`。
-4. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
+4. 已按短剧主流程顺序检查服务端表单、问卷和选项，没有把跳过必要阶段的选项直接呈现给用户；如果跳过 `剧本标准化`，已明确这是可选阶段。
+5. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
 
 ## 输出格式
 
@@ -271,7 +300,7 @@ Thread: thread_...
 
 - 任务提交后：立即展示 `web_thread_link`。
 - 任务进行中：展示后端 Agent 返回的过程消息。
-- 需要用户补充信息时：原样展示后端 Agent 的问题，等待用户回复。
+- 需要用户补充信息时：如果是普通问题，展示后端 Agent 的问题并等待用户回复；如果包含表单、问卷、选项或按钮，先按短剧主流程清洗不合理或跳跃的流程选项，再展示给用户。
 - 任务完成后：展示短剧内容、分集草稿、设定说明或其他结果信息，同时检查是否有未下载的重要资产。
 - 获取会话文件后：展示或记录文件元信息，不把它当成已下载结果。
 - 文件资源下载后：展示已落盘的本地文件路径；已存在而跳过下载的文件也要标明。
@@ -285,7 +314,7 @@ Thread: thread_...
 
 1. **上传**：如果用户给了本地 `.doc` / `.docx` / `.txt` 参考文件，先调用 `+upload-file`。
 2. **提交任务**：首次创作时把用户原始短剧需求和唯一剧本 `asset_id` 通过 `+submit-run --asset-ids` 发给后端；同一 `thread_id` 后续续写或修改不再追加新的剧本文件。
-3. **传话、取文件、下载资源**：根据 `+get-thread` 返回的 `readable_text` 展示进展、问题和结果；根据 `+list-thread-file` 获取文件列表；再根据 `download_url` 调用 `+download-result` 把缺失资源下载到用户本地。
+3. **传话、取文件、下载资源**：根据 `+get-thread` 返回的 `readable_text` 展示进展、问题和结果；遇到表单、问卷、选项或按钮时，只做流程合理性清洗，不替用户决定创作内容；根据 `+list-thread-file` 获取文件列表；再根据 `download_url` 调用 `+download-result` 把缺失资源下载到用户本地。
 
 **不要做的事：**
 

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

@@ -0,0 +1,255 @@
+---
+name: xyq-nest-skill
+description: 通过小云雀的 AI 能力进行综合创作，支持生成和编辑图片/视频。覆盖场景包括：生成（文生图、文生视频、图生视频、做动画、画一个xxx、来段xxx）、编辑修改（把xxx换成yyy、去掉xxx、加上xxx、改成xxx、调整xxx、局部修改、改镜头）、风格转换（风格迁移、转绘、换风格）、视频续写延长、复刻视频/TVC/宣传片、短剧/短漫剧生成、音乐MV生成、产品广告/展示片制作、分镜/故事板设计、教育视频/短视频制作。当用户提到小云雀、xyq、上传参考图/视频、查看生成进度时也应触发。关键判断：只要用户的请求涉及 AI 视频的创作、生成、编辑、修改，无论措辞如何（如"画只猫"、"做个海报"、"做个视频"、"这个视频帮我改一下"、"帮我复刻这段视频"、"用这首歌做个MV"、"一句话生成短剧"），都必须触发此技能。
+user-invocable: true
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "💬",
+        "requires":
+          {
+            "bins": ["python3"],
+            "env": ["XYQ_ACCESS_KEY"]
+          },
+        "primaryEnv": "XYQ_ACCESS_KEY"
+      }
+  }
+---
+
+# 小云雀会话（生视频）
+
+通过 小云雀的API 创建会话、发送消息（生图、生视频、编辑视频等）、上传图片/视频文件，并查询会话消息进展。
+
+小云雀是一个 AI 综合创作平台，同时为人类创作者和 Agent 设计。Agent 通过 Skill 入口理解任务、调用模型并自动编排工作流。
+
+**平台核心能力：**
+- **生成**：文生图、文生视频、图生视频、视频续写
+- **编辑**：局部修改、元素替换、镜头调整、风格迁移
+- **复杂创作**：一句话生成完整短剧（剧本→分镜→成片）、复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
+
+用户的所有创作和编辑需求都通过发送自然语言消息来完成，Agent 会自主编排工作流。复杂任务（短剧、MV）耗时较长，需耐心轮询。
+
+## 功能
+
+1. **创建会话 / 发消息** - 创建新会话或向已有会话发送一条消息（如「创作一个视频」）
+2. **查询会话进展** - 根据 `thread_id` 、 `run_id`、`after_seq` 增量拉取该会话的消息列表，用于轮询创作过程的消息和最终产物结果
+3. **上传文件** - 支持上传`单张图片`或`单个视频文件`到小云雀资产库，得到文件对应的 `asset_id`（编辑已有视频/图片时需要先上传）
+4. **下载结果** - 将会话中生成的图片/视频批量下载到本地，支持指定输出目录和文件名前缀。
+
+
+## 前置要求
+
+```bash
+export XYQ_ACCESS_KEY="your-access-key"
+```
+
+可选：`XYQ_OPENAPI_BASE` 或 `XYQ_BASE_URL`，默认 `https://xyq.jianying.com`。
+
+无需安装额外依赖，仅使用 Python 标准库。
+
+## 使用方法
+
+### 1. 创建会话 / 发送消息
+
+```bash
+# 创建新会话并发送「生一个动漫视频」
+python3 {baseDir}/scripts/submit_run.py --message "生一个动漫视频"
+
+# 向已有会话发送消息
+python3 {baseDir}/scripts/submit_run.py --message "再生成一个故事视频" --thread-id THREAD_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. 上传文件
+
+- 当用户提供了参考的文件地址时，先进行文件上传，仅支持图片、视频。
+- 单次指令执行仅支持单个文件，多个文件可并行调用，单个文件大小必须在200MB以下。
+
+```bash
+# 上传图片
+python3 {baseDir}/scripts/upload_file.py /path/to/image.png
+
+# 上传视频
+python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4
+```
+
+### 4. 下载结果
+
+任务完成后，可以将会话中的所有产物批量下载到本地。
+
+```bash
+# 指定 URL 列表，指定输出目录，指定文件名前缀（如 artifact_01.png, artifact_02.png ...）进行下载
+python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./xyq_output --prefix "artifact"
+```
+
+## 典型工作流
+
+理解这些工作流，才能正确组合上面的脚本完成用户需求。
+
+### 场景 1：用户要求生成图片或视频（最常见）
+
+```
+1. submit_run.py --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. 自动下载：download_results.py --urls URL1 URL2 URL3 --output-dir 输出目录 --prefix 有意义的前缀
+6. 向用户展示：过程中的创作信息，以及下载后的本地文件列表
+```
+
+### 场景 2：用户提供图片/视频要求编辑修改（如"参考这个视频做一个新的"）
+
+```
+1. upload_file.py /path/to/video.mp4  →  拿到 asset_id
+2. submit_run.py --message "参考这个视频做一个新的" --asset-ids asset_id  →  拿到 thread_id、run_id、web_thread_link
+3. 后续同场景 1 的步骤 2-6
+```
+
+用户给了文件路径 + 编辑指令 = 先上传文件，再把编辑指令和 所有asset_id 一起发送。
+
+### 场景 3：用户提供参考图/视频要求生成新内容
+
+```
+1. upload_file.py /path/to/ref1.png  →  拿到 asset_id1
+2. upload_file.py /path/to/ref2.mp4  →  拿到 asset_id2
+3. 直到所有文件上传完成，拿到所有 asset_id
+4. submit_run.py --message "根据参考图、视频生成xxx" --asset-ids asset_id1 asset_id2, ...  →  拿到 thread_id、run_id、web_thread_link
+5. 后续同场景 1 的步骤 2-6
+```
+
+### 场景 4：在已有会话中追加新需求
+
+```
+1. submit_run.py --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
+2. 后续同场景 1 的步骤 2-6
+```
+
+### 轮询策略
+
+- **间隔**：每 10 秒查询一次
+- **增量拉取**：首次用 --after-seq 0，后续根据messages消息列表长度，计算新的 seq 值
+- **完成判断**：当创作任务完成且messages的content中包含产物结果 URL（图片/视频地址）
+- **超时**：连续轮询 `48 小时`仍无结果，告知用户"生成时间较长，可稍后查看"，不再继续轮询
+- **错误重试**：单次查询失败可重试 1 次，连续 3 次失败则停止并告知用户
+
+## 输出格式
+
+**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}"....}
+      }
+    ]}
+  ]
+}
+```
+
+**upload_file** 返回：
+```json
+{
+  "asset_id": "{asset_id}"
+}
+```
+
+**download_results** 返回：
+```json
+{
+  "output_dir": "./xyq_output",
+  "downloaded": ["./xyq_output/01.png", "..."],
+  "total": 10
+}
+```
+
+## 向用户展示内容
+
+- 任务提交后：立即将 `web_thread_link` 展示给用户，方便用户直接打开浏览器查看任务页面
+- 任务在创作中：
+  - 展示过程中的创作信息等，继续轮询
+- 任务完成（run 结束）：
+  - 若涉及意图确认/流程中断（如"请回答以下问题"）→ 展示问题 → 等待用户回复 → 使用同一 `thread_id` 重新提交任务 → 继续轮询（可能多轮）
+  - 若 content 中包含产物 URL：
+  - 结果地址：来自 `get_thread` 返回的 `messages` 中，任务创作完成会包含产物 URL，将产物链接、下载的本地文件等信息告知用户。
+
+## 核心原则：用户侧不做创作，只做传话
+
+你（用户侧 Agent）的职责是**搬运工**，不是创作者。后端有专门的 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt。你要做的只有三件事：
+
+1. **上传**：如果用户给了本地文件 → `upload_file.py` 拿到 asset_id
+2. **提交任务**：把用户的原始描述 + asset_id 原封不动发给 `submit_run.py`
+3. **传话**：根据 `get_thread.py` 返回的消息列表，展示过程中的意图询问、创作信息等
+4. **取件**：`get_thread.py` 轮询结果 → 检查结果 → 下载产物 → 结果展示给用户
+
+**绝对不要做的事：**
+- 不要替用户扩写、润色、翻译 prompt（用户说"帮我推演分镜"，就直接传"帮我推演分镜"，不要自己先写个分镜表再逐条发）
+- 不要自行编排镜头描述、剧情推演、风格分析
+- 不要在消息中添加自己编的 prompt（如"超写实风格，电影级光影，8K分辨率"之类的描述词）
+
+后端 Agent 对模型能力、参数配置、prompt 工程远比用户侧更专业。用户侧越俎代庖只会降低生成质量，换个弱模型更是灾难。
+
+**正确示例：**
+```
+用户说：「根据多张参考图，做个科普故事视频」
+用户给了参考图：/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，立即展示给用户
+→ 轮询 ─┬─ 意图确认 → 用户确认 → 使用 thread_id 重新提交 → 继续轮询
+        └─ 无意图确认 → 信息展示 → 下载产物 → 结果展示
+```
+
+**错误示例：**
+```
+❌ 用户侧自己先写了个九宫格分镜表（对峙、交锋、危机...）
+❌ 然后把自己编的描述发给后端
+❌ 或者拆成9次 submit_run 分别发送
+```
+
+## 注意事项
+
+- 鉴权方式为请求头 `Authorization: Bearer <XYQ_ACCESS_KEY>`
+- 创建会话时 `message` 是用户的指令要求，不能为空
+- 查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
+- 上传文件仅支持图片（image/*）和视频（video/*）类型，其他类型会被拒绝，文件大小须在 200MB 以下
+- 生成过程中将过程中的创作信息展示给用户；任务完成后给出**产物结果（图片/视频）URL链接**和下载的**本地文件列表**。

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

@@ -0,0 +1,158 @@
+"""小云雀 agent-im OpenAPI 公共模块：创建会话、查询会话（鉴权为 Authorization: Bearer <access_key>）"""
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+
+XYQ_BASE = os.environ.get("XYQ_OPENAPI_BASE", os.environ.get("XYQ_BASE_URL", "https://xyq.jianying.com"))
+ACCESS_KEY = os.environ.get("XYQ_ACCESS_KEY", "")
+
+# API 路径常量
+SUBMIT_RUN_PATH = "/api/biz/v1/skill/submit_run"
+GET_THREAD_PATH = "/api/biz/v1/skill/get_thread"
+UPLOAD_FILE_PATH = "/api/biz/v1/skill/upload_file"
+
+if not ACCESS_KEY:
+    print("错误：请设置 XYQ_ACCESS_KEY 环境变量", file=sys.stderr)
+    sys.exit(1)
+
+
+def _headers():
+    return {
+        "Authorization": f"Bearer {ACCESS_KEY}",
+        "Content-Type": "application/json"
+    }
+
+
+def api_post(path: str, body: dict) -> dict:
+    """POST 请求 agent-im OpenAPI"""
+    url = f"{XYQ_BASE.rstrip('/')}{path}"
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers=_headers(),
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8") if e.fp else ""
+        print(f"API 错误 {e.code}: {err_body}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"网络错误: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def api_get(path: str) -> dict:
+    """GET 请求 agent-im OpenAPI"""
+    url = f"{XYQ_BASE.rstrip('/')}{path}"
+    req = urllib.request.Request(url, method="GET", headers=_headers())
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8") if e.fp else ""
+        print(f"API 错误 {e.code}: {err_body}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"网络错误: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def parse_response(resp: dict) -> dict:
+    """
+    分析 API 响应。
+    响应结构：{"ret":"0","errmsg":"","data":{}}
+    如果 ret 不是 "0"，打印错误信息并退出；否则返回 data。
+    """
+    ret = resp.get("ret", "")
+    if ret != "0":
+        errmsg = resp.get("errmsg", "未知错误")
+        print(f"错误码: {ret}, 错误信息: {errmsg}", file=sys.stderr)
+        sys.exit(1)
+    return resp.get("data", {})
+
+
+def submit_run(thread_id: str = "", message: str = "", asset_ids: list = None) -> dict:
+    """
+    创建会话或向已有会话发消息。
+    返回 data: { projectUuid, sessionId }。
+    """
+    body = {}
+    if thread_id:
+        body["thread_id"] = thread_id
+    if message:
+        body["message"] = message
+    if asset_ids:
+        body["asset_ids"] = asset_ids
+    resp = api_post(SUBMIT_RUN_PATH, body)
+    return parse_response(resp)
+
+
+def get_thread(thread_id: str, run_id: str = "", after_seq: int = 0) -> dict:
+    """
+    查询会话消息列表。
+    返回 data: { messages: [...] }。
+    """
+    body = {}
+    if thread_id:
+        body["thread_id"] = thread_id
+    if run_id:
+        body["run_id"] = run_id
+    body["after_seq"] = after_seq
+    resp = api_post(GET_THREAD_PATH, body)
+    resp = parse_response(resp)
+    thread = resp.get("thread", {})
+    run_list = thread.get("run_list", [])
+    if len(run_list) == 0:
+        print("错误：未返回 run_list", file=sys.stderr)
+        sys.exit(1)
+    run = run_list[0]
+    run_state = run.get("state", "")
+
+    # 判断 run_state
+    if run_state == 3:
+        # 成功
+        print("成功：本次创作已完成", file=sys.stderr)
+        return run
+    elif run_state == 4:
+        # 失败
+        fail_reason = run.get("fail_reason", "未知失败原因")
+        print(f"错误：{fail_reason}", file=sys.stderr)
+        sys.exit(1)
+    elif run_state == 5:
+        # 取消
+        print("错误：本次创作已被终止", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("本次创作进行中", file=sys.stdout)
+        return run
+
+
+def extract_entries_from_run(run: dict) -> list:
+    """
+    从 Run 的 EntryList 中提取符合条件的 entry。
+    """
+    matched = []
+    for entry in run.get("entry_list") or []:
+        e = {}
+        message = entry.get("message")
+        artifact = entry.get("artifact")
+        if message:
+            e["id"] = message.get("message_id", "")
+            e["role"] = message.get("role", "")
+            e["content"] = message.get("content", [])
+            client_tool_calls = message.get("client_tool_calls", [])
+            if len(client_tool_calls) > 0:
+                e["content"].extend(client_tool_calls)  
+        if artifact:
+            e["id"] = artifact.get("artifact_id", "")
+            e["role"] = artifact.get("role", "")
+            e["content"] = artifact.get("content", [])
+        matched.append(e)
+    return matched

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""下载生成结果：从会话中提取所有图片/视频 URL 并批量下载到本地"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+
+def download_file(url, filepath):
+    """下载单个文件"""
+    import shutil
+    req = urllib.request.Request(url, headers={"User-Agent": "XYQ-Nest-Skill/1.0"})
+    tmp_path = filepath + ".tmp"
+    try:
+        with urllib.request.urlopen(req, timeout=600) as resp:
+            with open(tmp_path, "wb") as f:
+                shutil.copyfileobj(resp, f, length=1024 * 1024)
+        os.replace(tmp_path, filepath)
+        return filepath, None
+    except Exception as e:
+        if os.path.exists(tmp_path):
+            os.remove(tmp_path)
+        return filepath, str(e)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="根据产物URL，下载生成的产物到本地，支持指定输出目录和文件名前缀",
+        epilog="""
+使用方式:
+  # 直接下载指定 URL 列表
+  python3 download_results.py --urls URL1 URL2 URL3 --output-dir ./output --prefix "storyboard"
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--urls", nargs="+", required=True, help="直接指定要下载的 URL 列表")
+    parser.add_argument("--output-dir", default="", help="输出目录（默认 ./xyq_output")
+    parser.add_argument("--prefix", default="", help="文件名前缀（如 'storyboard' → storyboard_01.png）")
+    parser.add_argument("--workers", type=int, default=5, help="并行下载线程数（默认 5）")
+    args = parser.parse_args()
+    
+    # 准备输出目录
+    output_dir = args.output_dir or "./xyq_output"
+    os.makedirs(output_dir, exist_ok=True)
+
+    def _get_ext(url):
+        """从 URL 中提取文件扩展名，优先从 query 的 filename 参数取，其次从路径取"""
+        from urllib.parse import urlparse, parse_qs
+        parsed = urlparse(url)
+        qs = parse_qs(parsed.query)
+        filenames = qs.get("filename", [])
+        if filenames:
+            _, ext = os.path.splitext(filenames[0])
+            if ext:
+                return ext
+        _, ext = os.path.splitext(parsed.path)
+        return ext or ".bin"
+
+    # 构建下载任务
+    tasks = []
+    for i, url in enumerate(args.urls, 1):
+        ext = _get_ext(url)
+        if args.prefix:
+            filename = f"{args.prefix}_{i:02d}{ext}"
+        else:
+            filename = f"{i:02d}{ext}"
+        filepath = os.path.join(output_dir, filename)
+        tasks.append((url, filepath))
+
+    # 并行下载
+    results = []
+    errors = []
+    with ThreadPoolExecutor(max_workers=args.workers) as pool:
+        futures = {pool.submit(download_file, url, fp): (url, fp) for url, fp in tasks}
+        for future in as_completed(futures):
+            fp, err = future.result()
+            if err:
+                errors.append({"file": fp, "error": err})
+            else:
+                results.append(fp)
+
+    # 按文件名排序输出
+    results.sort()
+
+    output = {
+        "output_dir": output_dir,
+        "downloaded": results,
+        "total": len(results),
+    }
+    if errors:
+        output["errors"] = errors
+
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""查询会话进展：POST /api/biz/v1/skill/get_thread，返回消息列表"""
+
+from _common import extract_entries_from_run
+import argparse
+import json
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _common import get_thread
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="查询会话消息列表（会话进展）",
+        epilog="""
+环境变量:
+  XYQ_ACCESS_KEY  必填，Bearer 鉴权
+  XYQ_OPENAPI_BASE 或 XYQ_BASE_URL  可选，默认 https://xyq.jianying.com
+
+示例:
+  python3 get_thread.py --thread-id abc123 --run-id def456 --after-seq 0
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--thread-id",
+        required=True,
+        help="会话 ID（由 submit_run 返回）",
+    )
+    parser.add_argument(
+        "--run-id",
+        default="",
+        help="运行 ID（由 submit_run 返回）",
+    )
+    parser.add_argument(
+        "--after-seq",
+        type=int,
+        default=0,
+        help="只返回 seq 大于等于该值的消息，用于增量拉取（默认 0）",
+    )
+    args = parser.parse_args()
+
+    run = get_thread(args.thread_id, run_id=args.run_id, after_seq=args.after_seq)
+    # 从run中提取Message和Artifact
+    entries = extract_entries_from_run(run)
+    out = {"messages": entries}
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""创建会话 / 向会话发送消息（生图、生视频等）：POST /api/biz/v1/skill/submit_run"""
+
+import argparse
+import json
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _common import submit_run
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="创建会话或向已有会话发送消息（仅用于生视频）",
+        epilog="""
+环境变量:
+  XYQ_ACCESS_KEY  必填，Bearer 鉴权
+  XYQ_OPENAPI_BASE 或 XYQ_BASE_URL  可选，默认 https://xyq.jianying.com
+
+示例:
+  # 创建新会话并发送「生一个动漫视频」
+  python3 submit_run.py --message 生一个动漫视频
+
+  # 向已有会话发送消息
+  python3 submit_run.py --message 再生成一个动漫视频 --thread-id 90f05e0c-5d08-4148-be40-e30fc7c7bedf
+
+  # 传入文件资产 ID
+  python3 submit_run.py --message 生成视频 --asset-ids asset123
+
+  # 传入多个文件资产 ID
+  python3 submit_run.py --message 生成视频 --asset-ids asset123 asset456 asset789
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--message",
+        required=True,
+        help="要发送的消息内容（生图/生视频描述等），必填",
+    )
+    parser.add_argument(
+        "--thread-id",
+        default="",
+        help="已有会话 ID，不传则创建新会话或返回已有默认会话",
+    )
+    parser.add_argument(
+        "--asset-ids",
+        nargs="+",
+        default=[],
+        help="资产 ID 列表，可传入多个，例如：--asset-ids id1 id2 id3",
+    )
+    args = parser.parse_args()
+
+    data = submit_run(
+        thread_id=args.thread_id or "",
+        message=args.message or "",
+        asset_ids=args.asset_ids if args.asset_ids else None
+    )
+    run_data = data.get("run", {})
+    web_thread_link = data.get("web_thread_link", "")
+    thread_id = run_data.get("thread_id", "")
+    run_id = run_data.get("run_id", "")
+
+    if not thread_id:
+        print("错误：未返回 thread_id", file=sys.stderr)
+        sys.exit(1)
+    if not run_id:
+        print("错误：未返回 run_id", file=sys.stderr)
+        sys.exit(1)
+
+    out = {"thread_id": thread_id, "run_id": run_id, "web_thread_link": web_thread_link}
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""上传图片/视频到小云雀资产库：POST /api/biz/v1/skill/upload_file（multipart/form-data）"""
+
+import argparse
+import json
+import mimetypes
+import os
+import sys
+import uuid
+import urllib.request
+import urllib.error
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _common import XYQ_BASE, ACCESS_KEY, UPLOAD_FILE_PATH, parse_response
+
+# 允许的 MIME 类型前缀
+ALLOWED_PREFIXES = ("image/", "video/")
+
+
+def upload_file(file_path: str) -> dict:
+    """
+    上传本地文件到小云雀资产库。
+    返回 data: { asset_id: str }。
+    """
+    if not os.path.isfile(file_path):
+        print(f"错误：文件不存在: {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # 检查 MIME 类型
+    mime_type, _ = mimetypes.guess_type(file_path)
+    if mime_type and not any(mime_type.startswith(p) for p in ALLOWED_PREFIXES):
+        print(f"错误：不支持的文件类型: {mime_type}，仅支持图片和视频", file=sys.stderr)
+        sys.exit(1)
+
+    # 构建 multipart/form-data 请求体
+    boundary = f"----PythonUpload{uuid.uuid4().hex}"
+    filename = os.path.basename(file_path)
+
+    body_parts = []
+
+    # accessKey 字段
+    body_parts.append(f"--{boundary}\r\n".encode())
+    body_parts.append(b'Content-Disposition: form-data; name="accessKey"\r\n\r\n')
+    body_parts.append(f"{ACCESS_KEY}\r\n".encode())
+
+    # file 字段
+    content_type = mime_type or "application/octet-stream"
+    body_parts.append(f"--{boundary}\r\n".encode())
+    body_parts.append(
+        f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'.encode()
+    )
+    body_parts.append(f"Content-Type: {content_type}\r\n\r\n".encode())
+    with open(file_path, "rb") as f:
+        body_parts.append(f.read())
+    body_parts.append(b"\r\n")
+
+    # 结束边界
+    body_parts.append(f"--{boundary}--\r\n".encode())
+
+    data = b"".join(body_parts)
+
+    url = f"{XYQ_BASE.rstrip('/')}{UPLOAD_FILE_PATH}"
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {ACCESS_KEY}",
+            "Content-Type": f"multipart/form-data; boundary={boundary}"
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+            return parse_response(result)
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8") if e.fp else ""
+        print(f"API 错误 {e.code}: {err_body}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"网络错误: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="上传图片或视频文件到小云雀资产库",
+        epilog="""
+环境变量:
+  XYQ_ACCESS_KEY  必填，Bearer 鉴权
+  XYQ_OPENAPI_BASE 或 XYQ_BASE_URL  可选，默认 https://xyq.jianying.com
+
+示例:
+  # 上传图片
+  python3 upload_file.py /path/to/image.png
+
+  # 上传视频
+  python3 upload_file.py /path/to/video.mp4
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "file",
+        help="要上传的图片或视频文件路径",
+    )
+    args = parser.parse_args()
+
+    data = upload_file(args.file)
+    asset_id = data.get("pippit_asset_id", "")
+
+    if not asset_id:
+        print("错误：未返回 asset_id", file=sys.stderr)
+        sys.exit(1)
+
+    out = {"asset_id": asset_id}
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()