@pippit-dev/cli 1.0.21 → 1.0.23

package/README.md

@@ -39,53 +39,58 @@
 
 - 生成：文生图、文生视频、图生视频、视频续写。
 - 编辑：局部修改、元素替换、镜头调整、风格迁移。
-- 复杂创作：一句话生成短剧、复刻视频/TVC/宣传片、音乐 MV 生成、产品展示片制作。
+- 复杂创作：复刻视频/TVC/宣传片、音乐 MV 生成、产品展示片制作。
 
 ### 配置
 
-所有 `xyq-skill` 脚本都使用 Bearer 令牌鉴权：
+单独上传 `xyq-skill` ZIP 时，保留 Skill 内的 `scripts/ensure-cli.js`。每次开始执行 Skill 任务先运行：
 
 ```bash
-export XYQ_ACCESS_KEY="<access-key>"
+node /path/to/xyq-skill/scripts/ensure-cli.js
 ```
 
-可选 API 地址：
+环境需要 Node.js 16+ 和 Python 3；首次安装或自动升级时需要 npm、`curl`、系统解压工具（macOS/Linux 的 `tar`，Windows 的 PowerShell）及访问 npm 源和 GitHub Release 的网络。脚本优先复用 PATH 或自身缓存中命令齐全的 CLI；均不存在或缺少必需命令时获取 `@pippit-dev/cli@latest`，安装到 `~/.cache/pippit-tool-cli/xyq-skill/<平台>-<架构>/current`，返回 `{ "cli_path": "CLI绝对路径", "version": "实际安装版本" }`。后续示例中的 `pippit-tool-cli` 替换为该绝对路径；同一任务内复用，不在轮询时重复安装。已有 CLI 缺少关键命令时自动升级；升级后的缓存可被后续任务复用，避免 PATH 旧版本触发重复下载。每次调用最多下载安装一次，升级失败保留原安装；最新版本仍缺少必需命令时报告阻塞。
+
+新入口 `node scripts/install-cli.js` 只安装 npm 包对应版本的 CLI 二进制，不安装或清理全局 Skill。ZIP 安装脚本先以 `--ignore-scripts` 获取 npm 包，再调用这个入口。发布包含新入口的 npm 包及对应 GitHub Release 后，ZIP 的最新版本安装流程才能完整使用。
+
+`submit-run` 和 `upload-file` 使用原生 CLI 登录凭证（`pippit-tool-cli login`），也可通过 `XYQ_ACCESS_KEY` 显式覆盖。保留的查询脚本 `get_thread.py` 仍需配置同一用户的 Bearer 凭证：
 
 ```bash
-export XYQ_OPENAPI_BASE="https://xyq.jianying.com"
-# 或
-export XYQ_BASE_URL="https://xyq.jianying.com"
+export XYQ_ACCESS_KEY="<access-key>"
 ```
 
+CLI 和 Python 脚本携带用户密钥的 API 请求地址固定为 `https://xyq.jianying.com`，不接受 `XYQ_OPENAPI_BASE` / `XYQ_BASE_URL` 覆盖。CLI 拒绝 API 跨域重定向，Python API 脚本禁止自动重定向。上传只在 Authorization 请求头携带密钥。
+
 ### 创建会话 / 发送消息
 
 ```bash
 # 创建新会话
-python3 skills/xyq-nest-skill/scripts/submit_run.py --message "生一个动漫视频"
+pippit-tool-cli submit-run --message "生一个动漫视频"
 
 # 向已有会话发送消息
-python3 skills/xyq-nest-skill/scripts/submit_run.py \
+pippit-tool-cli submit-run \
   --message "再生成一个故事视频" \
   --thread-id THREAD_ID
 
 # 携带参考文件发送
-python3 skills/xyq-nest-skill/scripts/submit_run.py \
+pippit-tool-cli submit-run \
   --message "参考这个视频做修改" \
-  --asset-ids asset_id1 asset_id2
+  --asset-ids asset_id1 --asset-ids asset_id2
 ```
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--message` | 是 | 创作指令内容。 |
+| `--message` | 是 | 非空白的创作指令，原样发送。 |
 | `--thread-id` | 否 | 已有会话 ID，不传则创建新会话。 |
-| `--asset-ids` | 否 | 资产 ID 列表，支持多个。 |
+| `--asset-ids` | 否 | 每次传一个资产 ID；多个素材重复该参数。 |
 
 返回示例：
 
 ```json
 {
   "thread_id": "90f05e0c-...",
-  "run_id": "abc123-..."
+  "run_id": "abc123-...",
+  "web_thread_link": "https://xyq.jianying.com/..."
 }
 ```
 
@@ -108,18 +113,20 @@ python3 skills/xyq-nest-skill/scripts/get_thread.py \
 
 ### 上传文件
 
+使用顶层 `upload-file --path`，每次上传一个本地图片、视频或 MP3/WAV 音频文件，文件须小于 500 MB（500000000 字节）。成功返回 `{"asset_id":"..."}`，可直接传给 `submit-run --asset-ids`。
+
 ```bash
 # 上传图片
-python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/image.png
+pippit-tool-cli upload-file --path /path/to/image.png
 
 # 上传视频
-python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/video.mp4
+pippit-tool-cli upload-file --path /path/to/video.mp4
 
 # 上传音频
-python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/audio.mp3
+pippit-tool-cli upload-file --path /path/to/audio.mp3
 ```
 
-仅支持 `image/*`、`video/*` 和 `.mp3/.wav` 音频文件，单文件大小限制 200 MB。
+仅支持 `image/*`、`video/*` 和 `.mp3/.wav` 音频文件，单文件大小限制 500 MB。
 
 返回示例：
 
@@ -131,65 +138,71 @@ python3 skills/xyq-nest-skill/scripts/upload_file.py /path/to/audio.mp3
 
 ### 下载结果
 
+每个产物 URL 调用一次 CLI，`--output-path` 必须包含文件名：
+
 ```bash
-python3 skills/xyq-nest-skill/scripts/download_results.py \
-  --urls URL1 URL2 URL3 \
-  --output-dir ./xyq_output \
-  --prefix "storyboard" \
-  --workers 5
+pippit-tool-cli download-result \
+  --url "URL1" \
+  --output-path "./xyq_output/storyboard_01.png"
 ```
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--urls` | 是 | 要下载的 URL 列表。 |
-| `--output-dir` | 否 | 输出目录，默认 `./xyq_output`。 |
-| `--prefix` | 否 | 文件名前缀，例如 `storyboard_01.png`。 |
-| `--workers` | 否 | 并行下载线程数，默认 `5`。 |
+| `--url` | 是 | 单个产物的下载 URL。 |
+| `--output-path` | 是 | 包含文件名的本地目标路径。 |
+| `--updated-at` | 否 | 远端文件真实更新时间（Unix 秒），用于判断是否覆盖已有文件。 |
+| `--workers` | 否 | 下载 worker 数，默认 `5`；当前单 URL 调用实际只使用一个 worker。 |
 
-返回示例：
+Skill 沿用用户指定的输出目录，未指定时使用 `./xyq_output`，按 URL 列表顺序从 `01` 编号，组成 `前缀_01.ext`（无前缀时为 `01.ext`）。扩展名优先取 URL 查询参数 `filename`，其次取 URL 路径，无法取得时使用 `.bin`。多文件逐项调用，可最多并行执行 5 个命令；重试保持原目标路径。
+
+下载成功返回示例：
 
 ```json
 {
-  "output_dir": "./xyq_output",
-  "downloaded": ["./xyq_output/storyboard_01.png"],
-  "total": 1
+  "output_path": "./xyq_output/storyboard_01.png",
+  "downloaded": ["./xyq_output/storyboard_01.png"]
 }
 ```
 
+未传 `--updated-at` 时，CLI 默认跳过已有文件，返回 `already_exist`，此时 `downloaded` 为 `null`；传入真实更新时间后，仅当本地文件修改时间早于该时间时覆盖更新。跳过不代表已校验本地内容与远端一致。
+
+下载失败时命令以非零退出码返回错误，不保证输出 JSON。Skill 汇总各次调用的下载成功、已存在跳过和失败项，只对失败项重试一次；仍有失败时明确报告未完整交付。
+
 ### 典型示例
 
 文生视频：
 
 ```text
-1. submit_run.py --message "生成一个赛博朋克风格的城市夜景视频"
+1. pippit-tool-cli submit-run --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"
+   pippit-tool-cli download-result --url "URL1" --output-path "./output/cyberpunk_01.mp4"
+   pippit-tool-cli download-result --url "URL2" --output-path "./output/cyberpunk_02.mp4"
 ```
 
 编辑已有视频：
 
 ```text
-1. upload_file.py /path/to/video.mp4
-2. submit_run.py --message "把背景换成星空" --asset-ids asset_id
+1. pippit-tool-cli upload-file --path /path/to/video.mp4
+2. pippit-tool-cli submit-run --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
+1. pippit-tool-cli upload-file --path /path/to/ref1.png
+2. pippit-tool-cli upload-file --path /path/to/ref2.png
+3. pippit-tool-cli upload-file --path /path/to/ref3.mp4
+4. pippit-tool-cli submit-run --message "根据参考图和视频生成科普故事视频" --asset-ids asset_id1 --asset-ids asset_id2 --asset-ids asset_id3
 5. 按文生视频流程轮询和下载。
 ```
 
 在已有会话中追加需求：
 
 ```text
-1. submit_run.py --message "把刚才的视频加个片头" --thread-id EXISTING_THREAD_ID
+1. pippit-tool-cli submit-run --message "把刚才的视频加个片头" --thread-id EXISTING_THREAD_ID
 2. 使用新的 run_id 轮询和下载。
 ```
 
@@ -249,9 +262,21 @@ pippit-tool-cli canvas apply --project-id PROJECT_ID --file ./patch.json
 通过 npm 安装的 CLI 还提供基于同一 Canvas SDK 的语义命令目录：
 
 ```bash
-# 查看全部公开命令及其参数说明
+# 先看精简目录，再按类别或参数定位
 pippit-tool-cli canvas command list
+pippit-tool-cli canvas command list --category timeline
 pippit-tool-cli canvas command describe create_biz_node
+pippit-tool-cli canvas command describe create_biz_node --node-kind role
+pippit-tool-cli canvas command describe xyq.timeline.apply --operation set_output_size
+pippit-tool-cli canvas command describe xyq.generation.update_prompt --path properties.prompt
+
+# 完整 schema 按需导出；不指定命令时导出全部
+pippit-tool-cli canvas command schema xyq.timeline.apply
+pippit-tool-cli canvas command schema
+
+# 离线指南：先取主题索引，再读正文
+pippit-tool-cli canvas command guide
+pippit-tool-cli canvas command guide storyboard
 
 # 由 SDK 业务工厂创建角色节点；修改会通过现有 canvas apply 原子提交
 pippit-tool-cli canvas command run create_biz_node \
@@ -261,6 +286,58 @@ pippit-tool-cli canvas command run create_biz_node \
 
 `canvas command` 由 npm 包内固定的 Canvas SDK 运行时提供，复用网页登录、`canvas get`、`canvas allocate` 和 `canvas apply`；不会读取或打印 Access Key，也不直接选择服务端地址。公开目录只包含已登记的 mutation 和业务命令，不开放任意内部 command 调用。
 
+`list [--category <category>]` 返回精简命令目录；`describe <command>` 说明入口参数，按 `--operation <name>` 查看一种领域操作、按 `--node-kind <kind>` 查看业务节点初始字段、按 `--path <schema.path>` 查看 schema 子路径。需要完整嵌套结构时使用 `schema [command]` 显式导出。`create_biz_node.nodeKind` 包含 `scene3d` 与 `timeline-composition`；字段枚举、必填项、默认值与动态来源以当前安装版本的 schema 为准。
+
+发现输出使用 `schema_version: 2`：`list` 只包含名称、分类和摘要；`describe` 的 `schema_view: "summary"` 表示展示视图，嵌套内容通过 `schema_path` 继续展开，不能直接当作完整校验 schema。原来从 `list` 或 `describe` 读取完整 `input_schema` 的脚本应改用 `schema [command]`。默认索引预算为 16 KiB，单次字段说明预算为 32 KiB；完整导出需要显式调用，执行命令的输入与返回值不受这一发现协议调整影响。
+
+`guide [topic]` 提供无需登录的离线帮助。无主题时仅返回索引，可选 `storyboard`、`prompt-references`、`time`、`timeline`、`scene3d`；正文包含单位、ID 来源、前置条件和最小示例。指南不启用新能力，先用 `list` 确认本机运行时支持哪些命令。故事板指南说明原生 `<duration-ms>` 标签累加与引用格式；目前没有公开的故事板脚本编辑、镜头排序或指定镜头生成领域命令，通用视频生成与资产补丁不能替代其业务流程。
+
+3D 导演台和多轨道都通过外层画布节点定位，其编辑内容保存在节点引用的独立文档或草稿资产中。先查询取得内部对象、轨道、片段 ID 和版本，再执行编辑：
+
+```bash
+pippit-tool-cli canvas command describe xyq.scene3d.apply
+pippit-tool-cli canvas command run xyq.scene3d.query \
+  --canvas-id CANVAS_ID --input '{"nodeId":"DIRECTOR_NODE_ID"}'
+pippit-tool-cli canvas command run xyq.scene3d.apply \
+  --canvas-id CANVAS_ID \
+  --input '{"nodeId":"DIRECTOR_NODE_ID","operations":[{"command":"create_node","args":{"kind":"camera","id":"camera-2","name":"Close-up"}}]}'
+
+pippit-tool-cli canvas command describe xyq.timeline.apply
+pippit-tool-cli canvas command run xyq.timeline.query \
+  --canvas-id CANVAS_ID --input '{"nodeId":"TIMELINE_NODE_ID"}'
+# expectedRevision 使用上一步返回的 draft.revision
+pippit-tool-cli canvas command run xyq.timeline.apply \
+  --canvas-id CANVAS_ID \
+  --input '{"nodeId":"TIMELINE_NODE_ID","expectedRevision":0,"commands":[{"type":"set_output_size","payload":{"width":1920,"height":1080}}]}'
+```
+
+领域命令的 `dryRun:true` 会完整预演编辑并保留原文档。多轨时间以整数微秒表示；3D 关键帧以帧表示，动作片段 `trimStart/trimEnd` 以源动画秒数表示。3D 对象旋转以度表示，几何体的 `theta/phi/arc` 参数以弧度表示，具体以字段 schema 为准。新增多轨素材须复用已有来源，或关联真实画布素材节点。截图、渲染导出、上传和生成仍需各自的运行环境。
+
+运行结构为 `npm 的 JS 入口 → Canvas SDK CJS → Go 二进制的资产命令`。Go 二进制可独立执行其原生命令，无需安装 Go；`canvas command` 需要 npm 包中的 Node.js 入口与 CJS 运行时。
+
+图片或视频节点通过 `xyq.generation.update_prompt` 更新提示词，`prompt` 直接使用前端已有的标签文本。CLI 与前端粘贴调用同一份 SDK 标签解析、引用匹配和连边逻辑：
+
+```bash
+pippit-tool-cli canvas command describe xyq.generation.update_prompt
+pippit-tool-cli canvas command run xyq.generation.update_prompt \
+  --canvas-id CANVAS_ID \
+  --input '{"nodeId":"TARGET_IMAGE_NODE_ID","prompt":"参考 <node-asset label=\"人物\">REFERENCE_IMAGE_NODE_ID</node-asset> 的人物，改为雨夜街景"}'
+```
+
+示例 ID 应替换为查询到的真实节点或资产 ID。`get_asset` 可查看当前节点与草稿；`describe` 按需查看参数，`schema` 导出完整输入结构。角色连边沿用前端既有默认选择与草稿处理，标签属性原样保留给编辑器和提交解析器。无需另传 `text/reference` 数组、`asset` 包装或 `referenceSource`；引用类型和独立素材前置条件可查看 `guide prompt-references`。
+
+直接上传或从素材库选出的素材可以没有节点。对于已在目标 `generation.references` 草稿中的素材，直接使用其 `pippitAssetId`：
+
+```bash
+pippit-tool-cli canvas command run xyq.generation.update_prompt \
+  --canvas-id CANVAS_ID \
+  --input '{"nodeId":"TARGET_IMAGE_NODE_ID","prompt":"参考 <pippit-asset-id label=\"参考图\">PIPPIT_ASSET_ID_IN_DRAFT</pippit-asset-id> 的人物"}'
+```
+
+当前版本只解析已有画布候选与目标草稿中的引用；找不到的普通标签返回 `UNRESOLVED_PROMPT_REFERENCE`，不写入文档。仅拿到 `canvas upload` 返回的 ID，还不会自动查询并加入草稿。新独立素材 ID 的自动解析属于后续能力。已有独立素材草稿可由前端上传或素材库流程产生，视频生成可使用其中的图片、视频和音频。同一媒体 ID 若同时匹配到画布源节点，则遵循前端现有的节点优先规则建立关联。`canvas get --asset-id PIPPIT_ASSET_ID` 可查询外部素材，但查询本身不添加引用。
+
+该命令先在隔离文档上按前端原有顺序执行 SDK commands，再把实际补丁一次性提交，保留模型参数、已有引用及 caption/title/name 等展示字段。`dryRun:true` 只执行隔离预演，原文档和撤销历史不变；清空 prompt 不移除引用。节点引用由现有生成流程转换成 `node_asset_refs`，独立图片进入 `pippit_asset_ids`，视频生成的独立素材按类型进入 `images`、`videos`、`audios`。本命令不触发生成、上传或远端素材查询。不要用浅合并的 `update_asset.contentPatch.generation` 更新提示词，否则可能覆盖其他生成参数。
+
 ## 生图 CLI
 
 `generate-image` 会上传本地参考图片，然后向综合 Nest Agent 提交生图请求：

package/checksums.txt

@@ -1,6 +1,6 @@
-c1657ee91f7f964dd936ecd723ff4985c12be4585f7f64dff96adba0277ec669  pippit-tool-cli-1.0.21-darwin-amd64.tar.gz
-ebfe75d1a8fbd6e76125b49917e97a3a81db6c4bae35ab5a1cb9625c618ea490  pippit-tool-cli-1.0.21-darwin-arm64.tar.gz
-3d828780c00f985378df61072d633e84dd2bcba3b8f7b7e6619fbd9ee34bf2a2  pippit-tool-cli-1.0.21-linux-amd64.tar.gz
-14dfb1412da253c62a4a52c27a40ce09c3af8480be9c4a94565952e7eed9afff  pippit-tool-cli-1.0.21-linux-arm64.tar.gz
-0d7b8bc575efb3928f8881cb2ba76f2583c2d4ed3f53c7ab3c98f53cf278d0c3  pippit-tool-cli-1.0.21-windows-amd64.zip
-3145e59e584bfd618b06d8a4e1586d242ff8c568f7221737f2f06d8f111a2cd7  pippit-tool-cli-1.0.21-windows-arm64.zip
+259ad5fb69598b646e035e5dd70fd6c905a25128b1b9c8e9689c58e09ec0a3d9  pippit-tool-cli-1.0.23-darwin-amd64.tar.gz
+610ec13e42a53a472759daf322701e178b062ff2ca2e854382cf5a8b6b894953  pippit-tool-cli-1.0.23-darwin-arm64.tar.gz
+3d371bb915e4b6adaf29cd3b1b06a9ee6a40896f962051ce97adeb1937a1b4a1  pippit-tool-cli-1.0.23-linux-amd64.tar.gz
+541f8a8e1913a591ad98ed3835525eba8459fd12ec289f9b206f9588812311c8  pippit-tool-cli-1.0.23-linux-arm64.tar.gz
+0ded272a827aa39427c53135465c99e6e1f94c81ef1f5e0982c6726d385e03bf  pippit-tool-cli-1.0.23-windows-amd64.zip
+ab6fd1baeac84e4e3cdde2392462534bd2a6279ee1cab0395437f1a03b5ace55  pippit-tool-cli-1.0.23-windows-arm64.zip

package/cmd/canvas/canvas.go

@@ -23,6 +23,7 @@ func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command
 	cmd := &cobra.Command{
 		Use:   "canvas",
 		Short: "Create and operate personal novel canvases",
+		Long:  "Create and operate personal novel canvases.\n\n" + CommandDiscoveryHelp,
 		Args:  cobra.NoArgs,
 	}
 	cmd.SetOut(stdout)
@@ -32,6 +33,7 @@ func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command
 	cmd.AddCommand(newAllocateCommand(stdout, stderr, runner))
 	cmd.AddCommand(newApplyCommand(stdout, stderr, runner))
 	cmd.AddCommand(newUploadCommand(stdout, stderr, runner))
+	cmd.AddCommand(newCommandHelp())
 	return cmd
 }
 

package/cmd/canvas/canvas_test.go

@@ -40,8 +40,8 @@ func TestCommandExposesOnlyProviderNeutralPublicVerbs(t *testing.T) {
 	for _, child := range cmd.Commands() {
 		got = append(got, child.Name())
 	}
-	if strings.Join(got, ",") != "allocate,apply,create,get,upload" {
-		t.Fatalf("commands = %v, want allocate/apply/create/get/upload", got)
+	if strings.Join(got, ",") != "allocate,apply,command,create,get,upload" {
+		t.Fatalf("commands = %v, want allocate/apply/command/create/get/upload", got)
 	}
 	for _, forbidden := range []string{"import", "bind", "team"} {
 		if strings.Contains(strings.ToLower(cmd.CommandPath()+" "+cmd.Short+" "+strings.Join(got, " ")), forbidden) {

package/cmd/canvas/command_help.go

@@ -0,0 +1,40 @@
+package canvas
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// CommandDiscoveryHelp connects native transport help to the npm command catalogue.
+const CommandDiscoveryHelp = `Canvas command catalogue (provided by the npm launcher):
+  pippit-tool-cli canvas command list [--category <category>]
+  pippit-tool-cli canvas command describe <name> [--operation <operation>] [--node-kind <kind>] [--path <schema.path>]
+  pippit-tool-cli canvas command schema [name]
+  pippit-tool-cli canvas command guide [topic]
+  pippit-tool-cli canvas command run <name> --canvas-id <id> [--input <JSON> | --file <path|->]
+
+Start with list, inspect inputs with describe/schema, then read guide for workflows.
+Use the pippit-tool-cli installed by npm, or node <package>/scripts/run.js.
+The standalone native binary provides Canvas transport commands and this help;
+executing the command catalogue requires the npm launcher.`
+
+func newCommandHelp() *cobra.Command {
+	return &cobra.Command{
+		Use:                "command",
+		Short:              "Discover list, describe, schema, guide, and run via the npm launcher",
+		Long:               CommandDiscoveryHelp,
+		DisableFlagParsing: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 || (len(args) == 1 && (args[0] == "--help" || args[0] == "-h")) {
+				return cmd.Help()
+			}
+			switch args[0] {
+			case "list", "describe", "schema", "guide", "run":
+				return fmt.Errorf("canvas command %s requires the npm launcher; use the npm-installed pippit-tool-cli or node <package>/scripts/run.js canvas command %s; the standalone native binary cannot execute this command", args[0], args[0])
+			default:
+				return fmt.Errorf("unknown canvas command action %q; expected list, describe, schema, guide, or run via the npm launcher; see canvas command --help", args[0])
+			}
+		},
+	}
+}

package/cmd/root.go

@@ -54,9 +54,10 @@ func newRunnerAuthorizer(runner *common.Runner) common.RequestAuthorizer {
 
 func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
 	root := &cobra.Command{
-		Use:           "pippit-tool-cli",
-		Short:         "Pippit CLI",
-		Long:          "Pippit CLI generates and processes videos and images, queries credit balances, submits short-drama workflows, downloads generated assets, and updates the installed CLI package.",
+		Use:   "pippit-tool-cli",
+		Short: "Pippit CLI",
+		Long: "Pippit CLI generates and processes videos and images, queries credit balances, submits creative conversations and short-drama workflows, downloads generated assets, and updates the installed CLI package.\n\n" +
+			canvascmd.CommandDiscoveryHelp + "\n\nInstallation help (npm launcher): pippit-tool-cli install --help",
 		Version:       version.Current(),
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -72,6 +73,8 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
 	root.AddCommand(newGetCreditBalanceCommand(stdout, stderr, runner))
 	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))
+	root.AddCommand(newSubmitRunCommand(stdout, stderr, runner))
+	root.AddCommand(newUploadFileCommand(stdout, stderr, runner))
 	root.AddCommand(newListThreadFileCommand(stdout, stderr, runner))
 	root.AddCommand(generate_image.NewCommand(stdout, stderr, runner))
 	root.AddCommand(generate_video.NewCommand(stdout, stderr, runner))

package/cmd/root_test.go

@@ -67,3 +67,41 @@ func TestRootRegistersTopLevelBrowserAuthCommands(t *testing.T) {
 		}
 	}
 }
+
+func TestHelpDiscoversNpmCanvasCommands(t *testing.T) {
+	for _, args := range [][]string{{"--help"}, {"canvas", "--help"}, {"canvas", "command", "--help"}, {"canvas", "command"}} {
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			root := NewRootCommand(&stdout, &stderr)
+			root.SetArgs(args)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			for _, action := range []string{"list", "describe", "schema", "guide", "run"} {
+				if !strings.Contains(stdout.String(), "canvas command "+action) {
+					t.Fatalf("help does not expose %s: %s", action, stdout.String())
+				}
+			}
+			if !strings.Contains(stdout.String(), "npm launcher") {
+				t.Fatalf("help does not explain launcher boundary: %s", stdout.String())
+			}
+		})
+	}
+}
+
+func TestNativeCanvasCommandsRequireNpmLauncher(t *testing.T) {
+	for _, action := range []string{"list", "describe", "schema", "guide", "run", "unknown-action"} {
+		t.Run(action, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			root := NewRootCommand(&stdout, &stderr)
+			root.SetArgs([]string{"canvas", "command", action, "--category", "example"})
+			err := root.Execute()
+			if err == nil || !strings.Contains(err.Error(), "npm launcher") {
+				t.Fatalf("Execute() error = %v, want launcher guidance", err)
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q, must not claim execution success", stdout.String())
+			}
+		})
+	}
+}

package/cmd/submit_run.go

@@ -0,0 +1,40 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newSubmitRunCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var body struct {
+		Message  string   `json:"message"`
+		ThreadID string   `json:"thread_id,omitempty"`
+		AssetIDs []string `json:"asset_ids,omitempty"`
+	}
+	cmd := &cobra.Command{
+		Use:   "submit-run",
+		Short: "Create a creative conversation or send a message to an existing thread",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("submit-run", nil, func(cmd *cobra.Command, _ []string) error {
+			if strings.TrimSpace(body.Message) == "" {
+				return fmt.Errorf("缺少必填参数 --message")
+			}
+			// Preserve the original message and identifiers; the backend owns routing.
+			result, err := common.SubmitRun(cmd.Context(), "submit-run", body, runner)
+			if err != nil {
+				return err
+			}
+			return common.WriteJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&body.Message, "message", "", "original message to send (required)")
+	cmd.Flags().StringVar(&body.ThreadID, "thread-id", "", "existing thread ID; omit to create a new thread")
+	cmd.Flags().StringArrayVar(&body.AssetIDs, "asset-ids", nil, "asset ID to attach; repeat for multiple assets")
+	return cmd
+}

package/cmd/submit_run_test.go

@@ -0,0 +1,103 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+)
+
+func TestSubmitRunCommandPreservesScriptContract(t *testing.T) {
+	for _, existing := range []bool{false, true} {
+		t.Run(map[bool]string{false: "new", true: "existing_with_assets"}[existing], func(t *testing.T) {
+			message := "  根据参考素材生成视频\n保留原文  "
+			want := map[string]any{"message": message}
+			args := []string{"submit-run", "--message", message}
+			if existing {
+				want["thread_id"] = "skill_original_thread"
+				want["asset_ids"] = []any{"asset_original_1", "asset_original_2"}
+				args = append(args, "--thread-id", "skill_original_thread", "--asset-ids", "asset_original_1", "--asset-ids", "asset_original_2")
+			}
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.Method != http.MethodPost || r.URL.Path != config.SubmitRunPath {
+					t.Errorf("request = %s %s", r.Method, r.URL.Path)
+				}
+				if r.Header.Get("Authorization") != "Bearer test-token" {
+					t.Error("missing bearer authorization")
+				}
+				var got map[string]any
+				if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
+					t.Error(err)
+				}
+				if !reflect.DeepEqual(got, want) {
+					t.Errorf("body = %#v, want %#v", got, want)
+				}
+				_, _ = w.Write([]byte(`{"ret":"0","data":{"run":{"thread_id":"thread_1","run_id":"run_1"},"web_thread_link":"https://xyq.jianying.com/thread_1"}}`))
+			}))
+			defer server.Close()
+			var stdout, stderr bytes.Buffer
+			root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+			root.SetArgs(args)
+			if err := root.Execute(); err != nil {
+				t.Fatal(err)
+			}
+			if got := stdout.String(); got != "{\"thread_id\":\"thread_1\",\"run_id\":\"run_1\",\"web_thread_link\":\"https://xyq.jianying.com/thread_1\"}\n" {
+				t.Fatalf("unexpected output: %s", got)
+			}
+		})
+	}
+}
+
+func TestSubmitRunCommandValidatesBeforeRequest(t *testing.T) {
+	for _, args := range [][]string{
+		{"submit-run"},
+		{"submit-run", "--message", " \n "},
+		{"submit-run", "--message", "hello", "unexpected"},
+	} {
+		var stdout, stderr bytes.Buffer
+		root := newRootCommand(&stdout, &stderr, nil)
+		root.SetArgs(args)
+		if err := root.Execute(); err == nil {
+			t.Fatalf("Execute(%v) should fail before accessing the runner", args)
+		}
+	}
+}
+
+func TestSubmitRunHelpDoesNotRequireCredentials(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	root := newRootCommand(&stdout, &stderr, nil)
+	root.SetArgs([]string{"submit-run", "--help"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	for _, flag := range []string{"--message", "--thread-id", "--asset-ids"} {
+		if !strings.Contains(stdout.String(), flag) {
+			t.Errorf("help missing %s", flag)
+		}
+	}
+}
+
+func TestSubmitRunCommandRejectsInvalidResponse(t *testing.T) {
+	for _, response := range []string{
+		`{"ret":"1","errmsg":"rejected"}`,
+		`{"ret":"0","data":{"run":{"run_id":"run_1"}}}`,
+		`{"ret":"0","data":{"run":{"thread_id":"thread_1"}}}`,
+	} {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			_, _ = w.Write([]byte(response))
+		}))
+		var stdout, stderr bytes.Buffer
+		root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+		root.SetArgs([]string{"submit-run", "--message", "hello"})
+		err := root.Execute()
+		server.Close()
+		if err == nil || stdout.Len() != 0 {
+			t.Fatalf("response %s: error = %v, stdout = %s", response, err, stdout.String())
+		}
+	}
+}

package/cmd/upload_file.go

@@ -0,0 +1,64 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"mime"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+const maxMediaUploadBytes int64 = 500 * 1000 * 1000
+
+func newUploadFileCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var opts common.UploadFileOptions
+	cmd := &cobra.Command{
+		Use:   "upload-file",
+		Short: "Upload an image, video, or MP3/WAV audio file",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("upload-file", nil, func(cmd *cobra.Command, _ []string) error {
+			opts.Path = strings.TrimSpace(opts.Path)
+			if err := validateMediaUpload(opts.Path); err != nil {
+				return err
+			}
+			result, err := common.UploadFile(cmd.Context(), opts, runner)
+			if err != nil {
+				return err
+			}
+			return common.WriteJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&opts.Path, "path", "", "local media file to upload (required, less than 500 MB)")
+	return cmd
+}
+
+func validateMediaUpload(path string) error {
+	if path == "" {
+		return fmt.Errorf("缺少必填参数 --path")
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return fmt.Errorf("获取上传文件信息失败: %w", err)
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("上传路径必须是普通文件")
+	}
+	if info.Size() >= maxMediaUploadBytes {
+		return fmt.Errorf("上传文件必须小于 500 MB（500000000 字节）")
+	}
+	ext := strings.ToLower(filepath.Ext(path))
+	contentType := mime.TypeByExtension(ext)
+	if strings.HasPrefix(contentType, "image/") || strings.HasPrefix(contentType, "video/") {
+		return nil
+	}
+	if ext == ".mp3" || ext == ".wav" {
+		return nil
+	}
+	return fmt.Errorf("不支持的文件类型 %q，仅支持图片、视频和 .mp3/.wav 音频", ext)
+}