@pippit-dev/cli 1.0.46 → 1.0.48

package/dist/xyq-canvas-command-runtime.cjs.sha256

@@ -1,2 +1,2 @@
-f258da52a41a6e5631c169037db8f6bfd34b06c96926e094d85cd6418e6fca31  xyq-canvas-command-runtime.cjs
+8e14b9a2c496491c2ee44da3ed950ac8301b67981dfaba3ab1e042cf8b937298  xyq-canvas-command-runtime.cjs
 3b97217c41dfb3c298185c80b1e70c2b469f552450e53d00fc1dcf7098740ffb  xyq-canvas-command-runtime.cjs.LEGAL.txt

package/internal/canvas/upload.go

@@ -29,6 +29,7 @@ var uploadContentTypeFallbacks = map[string]string{
 
 type UploadOptions struct {
 	Path         string
+	URL          string
 	PollInterval time.Duration
 	WaitTimeout  time.Duration
 }
@@ -69,34 +70,40 @@ func Upload(ctx context.Context, opts UploadOptions, runner *common.Runner) (*Up
 	if opts.PollInterval < 0 || opts.WaitTimeout < 0 {
 		return nil, fmt.Errorf("canvas upload polling durations must not be negative")
 	}
-	path := strings.TrimSpace(opts.Path)
-	if path == "" {
-		return nil, fmt.Errorf("canvas upload path is required")
-	}
-	info, err := os.Stat(path)
-	if err != nil {
-		return nil, fmt.Errorf("inspect canvas upload file: %w", err)
-	}
-	if !info.Mode().IsRegular() {
-		return nil, fmt.Errorf("canvas upload path %q is not a regular file", path)
-	}
-	fileName := filepath.Base(path)
-	extension := strings.ToLower(filepath.Ext(fileName))
-	contentType := mime.TypeByExtension(extension)
-	if contentType == "" {
-		contentType = uploadContentTypeFallbacks[extension]
-	}
-	if contentType == "" {
-		contentType = "application/octet-stream"
+	source := common.UploadFileOptions{Path: opts.Path, URL: opts.URL}
+	if err := source.ValidateSource(); err != nil {
+		return nil, err
 	}
 
 	var envelope responseEnvelope
-	if err := client.SendMultipartRequest(ctx, UploadPath, nil, common.MultipartFile{
-		FieldName:   "file",
-		Path:        path,
-		FileName:    fileName,
-		ContentType: contentType,
-	}, &envelope); err != nil {
+	if sourceURL := strings.TrimSpace(opts.URL); sourceURL != "" {
+		err = client.SendRequest(ctx, UploadPath, map[string]string{"url": sourceURL}, &envelope)
+	} else {
+		path := strings.TrimSpace(opts.Path)
+		info, statErr := os.Stat(path)
+		if statErr != nil {
+			return nil, fmt.Errorf("inspect canvas upload file: %w", statErr)
+		}
+		if !info.Mode().IsRegular() {
+			return nil, fmt.Errorf("canvas upload path %q is not a regular file", path)
+		}
+		fileName := filepath.Base(path)
+		extension := strings.ToLower(filepath.Ext(fileName))
+		contentType := mime.TypeByExtension(extension)
+		if contentType == "" {
+			contentType = uploadContentTypeFallbacks[extension]
+		}
+		if contentType == "" {
+			contentType = "application/octet-stream"
+		}
+		err = client.SendMultipartRequest(ctx, UploadPath, nil, common.MultipartFile{
+			FieldName:   "file",
+			Path:        path,
+			FileName:    fileName,
+			ContentType: contentType,
+		}, &envelope)
+	}
+	if err != nil {
 		return nil, fmt.Errorf("canvas upload request failed; outcome may be ambiguous, check assets before retrying: %w", err)
 	}
 	if err := envelope.validate("canvas upload"); err != nil {

package/internal/canvas/upload_url_test.go

@@ -0,0 +1,72 @@
+package canvas
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestUploadURLPreservesRecoveryAndErrors(t *testing.T) {
+	const uploaded = `{"ret":"0","log_id":"upload-log","data":{"asset_id":"source-id","pippit_asset_id":"asset-url"}}`
+	for _, tc := range []struct {
+		name        string
+		upload      string
+		query       string
+		timeout     bool
+		wantErr     string
+		wantWarn    string
+		wantQueries int
+	}{
+		{"query_timeout", uploaded, "", true, "", "not queryable", 1},
+		{"query_failure", uploaded, `{"ret":"1","errmsg":"denied","log_id":"query-log"}`, false, "", "query-log", 1},
+		{"media_not_ready", uploaded, `{"ret":"0","data":{"Assets":[{"PippitAssetID":"asset-url","AssetType":1,"Image":{}}]}}`, false, "", "cloud media ID is not ready", 1},
+		{"rejected", `{"ret":"1","errmsg":"rejected","log_id":"upload-log"}`, "", false, "upload-log", "", 0},
+		{"missing_id", `{"ret":"0","log_id":"upload-log","data":{"asset_id":"source-id"}}`, "", false, "upload-log", "", 0},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			uploads, queries := 0, 0
+			client := &fakeClient{send: func(ctx context.Context, path string, body, out any) error {
+				switch path {
+				case UploadPath:
+					uploads++
+					return decodeInto(out, tc.upload)
+				case QueryPath:
+					queries++
+					if tc.timeout {
+						<-ctx.Done()
+						return ctx.Err()
+					}
+					return decodeInto(out, tc.query)
+				default:
+					t.Fatalf("unexpected request: %s", path)
+					return nil
+				}
+			}}
+			waitTimeout := time.Second
+			if tc.timeout {
+				waitTimeout = time.Millisecond
+			}
+			result, err := Upload(context.Background(), UploadOptions{
+				URL: "https://assets.example.invalid/media", WaitTimeout: waitTimeout,
+			}, runnerWithClient(client))
+			if uploads != 1 || queries != tc.wantQueries {
+				t.Fatalf("uploads=%d queries=%d; import must not be replayed", uploads, queries)
+			}
+			if tc.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tc.wantErr) || result != nil {
+					t.Fatalf("result=%+v err=%v, want upload error with LogID", result, err)
+				}
+				return
+			}
+			if err != nil || result == nil {
+				t.Fatalf("result=%+v err=%v", result, err)
+			}
+			if result.State != StateProcessing || result.PippitAssetID != "asset-url" || result.AssetID != "source-id" ||
+				result.Locator.PippitAssetID != "asset-url" || result.MediaAssetID != "" ||
+				!strings.Contains(result.Warning, tc.wantWarn) {
+				t.Fatalf("result=%+v, want recoverable processing result", result)
+			}
+		})
+	}
+}

package/internal/common/upload_file.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"mime"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -15,9 +16,26 @@ import (
 // UploadFileOptions is the stable command-facing request shape for file upload.
 type UploadFileOptions struct {
 	Path     string `json:"path"`
+	URL      string `json:"url,omitempty"`
 	FileName string `json:"file_name"`
 }
 
+// ValidateSource checks the source before either command-level file validation
+// or direct callers can read a file or send a request.
+func (opts UploadFileOptions) ValidateSource() error {
+	path, sourceURL := strings.TrimSpace(opts.Path), strings.TrimSpace(opts.URL)
+	if (path == "") == (sourceURL == "") {
+		return fmt.Errorf("--path 与 --url 必须且只能提供一个")
+	}
+	if sourceURL != "" {
+		u, err := url.Parse(sourceURL)
+		if err != nil || u.Scheme != "https" || u.Hostname() == "" || u.User != nil || u.Fragment != "" {
+			return fmt.Errorf("--url 必须是有效的 HTTPS 素材链接，不能包含用户凭据或 fragment")
+		}
+	}
+	return nil
+}
+
 // UploadFileResult is the shared JSON output for media and short-drama uploads.
 type UploadFileResult struct {
 	TeamID  string `json:"team_id"`
@@ -56,39 +74,45 @@ func UploadFile(ctx context.Context, opts UploadFileOptions, runner *Runner) (*U
 		return nil, fmt.Errorf("上传文件运行器客户端缺失")
 	}
 
-	path := strings.TrimSpace(opts.Path)
-	if path == "" {
-		return nil, fmt.Errorf("上传文件路径不能为空")
+	if err := opts.ValidateSource(); err != nil {
+		return nil, err
 	}
-	info, err := os.Stat(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil, fmt.Errorf("上传文件不存在: %s", path)
+
+	var resp uploadFileResponse
+	if sourceURL := strings.TrimSpace(opts.URL); sourceURL != "" {
+		if err := runner.Client.SendRequest(ctx, uploadFilePath(runner), map[string]string{"url": sourceURL}, &resp); err != nil {
+			return nil, fmt.Errorf("URL 导入请求失败，结果可能未确认，请检查资产后再重试: %w", err)
 		}
-		if os.IsPermission(err) {
-			return nil, fmt.Errorf("没有权限读取上传文件: %s", path)
+	} else {
+		path := strings.TrimSpace(opts.Path)
+		info, err := os.Stat(path)
+		if err != nil {
+			if os.IsNotExist(err) {
+				return nil, fmt.Errorf("上传文件不存在: %s", path)
+			}
+			if os.IsPermission(err) {
+				return nil, fmt.Errorf("没有权限读取上传文件: %s", path)
+			}
+			return nil, fmt.Errorf("获取上传文件信息失败: %w", err)
+		}
+		if info.IsDir() {
+			return nil, fmt.Errorf("上传路径 %q 是目录，请指定文件", path)
 		}
-		return nil, fmt.Errorf("获取上传文件信息失败: %w", err)
-	}
-	if info.IsDir() {
-		return nil, fmt.Errorf("上传路径 %q 是目录，请指定文件", path)
-	}
-
-	ext := strings.ToLower(filepath.Ext(path))
-	fileName := filepath.Base(path)
-	contentType := mime.TypeByExtension(ext)
-	if contentType == "" {
-		contentType = uploadFileContentTypeFallbacks[ext]
-	}
 
-	var resp uploadFileResponse
-	if err := runner.Client.SendMultipartRequest(ctx, uploadFilePath(runner), nil, MultipartFile{
-		FieldName:   uploadFileFieldName,
-		Path:        path,
-		FileName:    fileName,
-		ContentType: contentType,
-	}, &resp); err != nil {
-		return nil, fmt.Errorf("上传文件请求失败: %w", err)
+		ext := strings.ToLower(filepath.Ext(path))
+		fileName := filepath.Base(path)
+		contentType := mime.TypeByExtension(ext)
+		if contentType == "" {
+			contentType = uploadFileContentTypeFallbacks[ext]
+		}
+		if err := runner.Client.SendMultipartRequest(ctx, uploadFilePath(runner), nil, MultipartFile{
+			FieldName:   uploadFileFieldName,
+			Path:        path,
+			FileName:    fileName,
+			ContentType: contentType,
+		}, &resp); err != nil {
+			return nil, fmt.Errorf("上传文件请求失败: %w", err)
+		}
 	}
 	if resp.Ret != "0" {
 		if resp.Errmsg == "" {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "description": "Pippit CLI",
   "bin": {
     "pippit-tool-cli": "scripts/run.js"
@@ -10,7 +10,7 @@
     "test:marketing-skill": "node scripts/marketing-skill.test.js",
     "prepack": "node scripts/prepare-canvas-runtime.js",
     "prepare:canvas-runtime": "node scripts/prepare-canvas-runtime.js",
-    "test": "node scripts/version-check.test.js && node scripts/skills.test.js && node scripts/marketing-skill.test.js && node scripts/install-wizard.test.js && node scripts/install-cli.test.js && node scripts/run-help.test.js && node scripts/canvas-command.test.js && node scripts/canvas-command-schema.test.js && node scripts/canvas-command-guides.test.js && node scripts/prepare-canvas-runtime.test.js && node scripts/canvas-command-runtime.test.js && node scripts/canvas-media-identity.test.js && npm run test:canvas-operations && go test ./... && go vet ./...",
+    "test": "node scripts/version-check.test.js && node scripts/skills.test.js && node scripts/marketing-skill.test.js && node scripts/install-wizard.test.js && node scripts/install-cli.test.js && node scripts/run-help.test.js && node scripts/canvas-command.test.js && node scripts/canvas-command-schema.test.js && node scripts/canvas-command-guides.test.js && node scripts/prepare-canvas-runtime.test.js && node scripts/canvas-command-runtime.test.js && node scripts/canvas-media-identity.test.js && node scripts/canvas-video-ratio.test.js && npm run test:canvas-operations && go test ./... && go vet ./...",
     "verify:canvas-runtime": "node scripts/prepare-canvas-runtime.js --check-only",
     "test:canvas-runtime": "node scripts/canvas-command-runtime.test.js",
     "test:canvas-operations": "node scripts/canvas-command-canvas-operations.test.js && node scripts/canvas-command-scene3d-operations.test.js && node scripts/canvas-command-timeline-operations.test.js"

package/scripts/canvas-command-guides.js

@@ -36,7 +36,7 @@ const GUIDES = [
       "先用 list 确认 xyq.generation.update_prompt 可用，再 describe 获取参数。该命令接收 nodeId、prompt、可选 dryRun；nodeId 是当前 Canvas 的目标图片或视频节点 ID。get_snapshot 可查节点，get_asset 可读节点资产与 generation.references；用 describe 查看这两个查询命令的输入，避免混淆 Canvas ID、节点 ID 与媒体 Pippit ID。",
       '<node-asset>NODE_ASSET_ID</node-asset> 引用已有节点。标签 ID 来自查询结果中的真实节点资产身份；不要用展示名称代替。CLI 复用 Web 标签匹配、节点连边和角色默认选材，保留标签属性。角色已有 data-reference-selection="IMAGE_ID,VOICE_ID" 属性使用逗号分隔选择 ID，需与角色已有资料匹配，不另传 selectedIds 或 reference 数组。',
       "独立上传/素材库媒体可以没有节点。对已在目标 generation.references 中的素材，用 <pippit-asset-id>MEDIA_PIPPIT_ASSET_ID</pippit-asset-id>，ID 取自该草稿的 pippitAssetId。视频目标可使用已有图片、视频、音频候选；图片目标须符合自身支持的引用类型。无须新增 referenceSource 入参。",
-      "只有 canvas upload 返回的 ID 还不够：本命令不会查询未知媒体并加入草稿。canvas get 只查询，不添加引用。找不到的普通标签返回 UNRESOLVED_PROMPT_REFERENCE，不写文档。相同媒体若匹配到已有 Canvas 源节点，沿用 Web 节点优先规则连边。新独立素材先通过现有 Web 上传/素材库流程建立草稿。",
+      "外链素材可用 canvas upload --url 导入并等待查询，复用其 pippit_asset_id；同一素材不重复导入。只有 upload-file 或 canvas upload 返回的素材 ID 还不够：本命令不会查询未知媒体并加入草稿。canvas get 只查询，不添加引用。找不到的普通标签返回 UNRESOLVED_PROMPT_REFERENCE，不写文档。需要画布参考节点时，先用 create_biz_node 的 initialData.pippitAssetId 关联已导入素材，再引用实际节点；upload-file.asset_id 是稳定 Pippit ID，canvas upload 则取 pippit_asset_id。相同媒体若匹配到已有 Canvas 源节点，沿用 Web 节点优先规则连边。新独立素材也可通过现有 Web 上传/素材库流程建立草稿。",
       "dryRun:true 在隔离文档预演，不改变原文档。成功编辑保留其他 generation 参数及 caption/title/name；空 prompt 清空文本并保留现有引用与连边。本命令不触发生成。不要浅覆盖整个 generation。故事板有自己的脚本与引用流程，见 storyboard 指南。",
     ].join("\n\n"),
     next_commands: [

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

@@ -1,6 +1,6 @@
 ---
 name: xyq-skill
-description: 使用小云雀 pippit-tool-cli 生成或编辑图片、生成视频、超分和擦字幕，查询结果并交付媒体；操作小云雀个人或团队 Canvas 画布、节点、布局、连线、角色/场景、生成提示词、3D 导演台与多轨草稿；查询积分及管理授权。用户提到小云雀、xyq 并需要这些操作时使用。
+description: 使用小云雀 pippit-tool-cli 上传本地素材或通过 URL 导入素材，生成或编辑图片、生成视频、超分和擦字幕，查询结果并交付媒体；操作小云雀个人或团队 Canvas 画布、节点、布局、连线、角色/场景、生成提示词、3D 导演台与多轨草稿；查询积分及管理授权。用户提到小云雀、xyq 并需要这些操作时使用。
 user-invocable: true
 metadata:
   {"openclaw": {"emoji": "💬", "requires": {"bins": ["node"]}}}
@@ -8,13 +8,13 @@ metadata:
 
 # 小云雀媒体创作与画布操作
 
-通过 CLI 完成生成、处理、结果下载与媒体交付。支持下表中的操作；不提供多轮会话续写或自动拆分剧本、分镜并编排成片的能力。复杂需求先确认能由所列命令完成的具体操作，不承诺未覆盖的流程。
+通过 CLI 完成素材上传或 URL 导入、生成、处理、结果下载与媒体交付。支持下表中的操作；不提供多轮会话续写或自动拆分剧本、分镜并编排成片的能力。复杂需求先确认能由所列命令完成的具体操作，不承诺未覆盖的流程。
 
 ## 开始执行
 
 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)，不把画布编辑当作媒体生成。积分与授权操作直接返回结果。
+3. 生成、视频处理和查询已有媒体结果时，还必须读取 [异步结果与媒体交付](workflows/async-delivery.md)。画布任务使用 [画布查询、编辑与验证](workflows/canvas-edit.md)，不把画布编辑当作媒体生成。素材上传或导入保存返回的资产 ID 与空间；积分与授权操作直接返回结果，不套用生成任务轮询。
 
 参数是否存在、命令语法以当前 `cli_path` 对应的 `--help` 为准；返回字段和成功判断按命令文档及真实响应核对。文档与实际不一致时说明差异，不猜参数、不绕过 CLI 自行调用 HTTP。
 
@@ -36,6 +36,7 @@ metadata:
 | 用户意图 | CLI | 必读文档 |
 | --- | --- | --- |
 | 查看登录状态、登录、退出或切换账号 | `status` / `login` / `logout` | [授权](commands/auth.md) |
+| 上传本地素材，或从 HTTPS URL 导入素材 | `upload-file`；画布流程可用 `canvas upload` | [素材上传与 URL 导入](commands/upload-file.md)；[Canvas 上传与查询等待](commands/canvas-assets.md#url-import) |
 | 创建或查询小云雀个人或团队画布，编辑节点、布局、连线、角色/场景、提示词、3D 或多轨草稿 | `canvas` | [Canvas 能力与命令发现](commands/canvas.md) |
 | 生成图片，或基于参考图修改图片 | `generate-image` | [生图与图片编辑](commands/generate-image.md) |
 | 查询当前可用的图片/视频模型、比例、分辨率及推理强度等参数配置 | `model list` / `model describe` | [模型发现](commands/model.md) |
@@ -57,7 +58,7 @@ metadata:
 - 图片模型对用户只展示服务端返回的名称；列表、选择、详情与生成命令均使用完整名称，不解释或展示对应底层枚举。名称到提交标识由 CLI 解析，详见 [模型发现](commands/model.md)。
 - 用户明确要求生成或处理，即可在该范围内执行；仅咨询用法、费用或方案时不提交。范围、必填信息或消耗 credits 的授权不明确时，先确认，不重复索要已给出的授权。
 - 提问优先使用宿主实际提供且当前模式允许的工具：Codex 的 `request_user_input` 或 `request_user_input_async`，WorkBuddy 的 `ask_user_question`；不可用时用普通聊天。需要答案时等待答复。
-- 素材参数接收本地文件路径，CLI 内部上传。远程链接不能冒充本地路径；缺少可访问文件时先解决素材获取。单文件必须小于 500 MB（500000000 字节）。
+- 生成和视频处理命令的素材参数接收本地文件路径，CLI 内部上传，单文件必须小于 500 MB（500000000 字节）；不能把 URL 或资产 ID 填入这些路径参数。用户要求从外链导入素材时，使用 `upload-file --url`，或在画布流程中使用 `canvas upload --url` 并保留其查询等待与输出，由服务端读取源文件，无需先下载到本机；参数、限制及后续资产复用见 [上传说明](commands/upload-file.md)。
 - `generate-image` / `generate-video` 上传素材失败时，向用户说明 CLI 返回的素材类型、类型内序号、文件名、原始原因和可用的 LogID，并说明尚未提交生成任务。序号按同类型参数的传入顺序从 1 开始，不是所有附件的混合序号；只有服务端明确返回审核拒绝时才说明审核未通过，不能把网络、权限等失败都归为审核问题。
 - `generate-image` / `generate-video` 将所有参考素材按最多 10 个并发上传，等待本批上传结束后统一返回全部失败项；某个素材失败不会跳过其他素材。错误按图片、视频、音频分组及各自输入顺序列出，生成引用也保留输入顺序，不按上传完成先后排序。任一素材失败均不提交生成；向用户一次性列全失败素材，不只转述第一项。网络失败、取消或超时不代表审核通过。根据失败原因等待用户替换对应素材或解决问题，不自动删减素材、重传或重新提交生成。旧 CLI 如首错即停或未返回文件定位，须如实说明其结果范围，不凭图片内容猜测未检查素材的审核结论。
 - 提交成功后立即展示真实 `web_thread_link`；未返回链接时如实说明，保留任务 ID。后续查询和下载失败不能触发重复生成。

package/skills/xyq-nest-skill/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "小云雀创作工具包"
-  short_description: "原子工具集合，生成和编辑图片、视频，处理视频清晰度与字幕，查询积分，并操作小云雀画布等"
+  short_description: "上传或通过 URL 导入素材，生成和编辑图片、视频，处理清晰度与字幕，查询积分及编辑小云雀画布"

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

@@ -6,7 +6,7 @@
 | --- | --- | --- |
 | `canvas create` | `--title` 最多 50 字符；`--request-id` 可选；`--wait` 等初始化；可调 `--poll-interval`、`--timeout` | 保存 `project_id`、`canvas_asset_id`、`web_url`、`request_id`；检查 `state`、`warning` 和退出码 |
 | `canvas get` | `--asset-id` 必填，可重复 | 返回 `requested_asset_ids`、`assets` 及可用的 `log_id`；核对实际返回资产 |
-| `canvas upload` | `--path` 本地文件；可调 `--poll-interval`、`--timeout` | 返回 `pippit_asset_id`、可用的 `media_asset_id`、`source_id`、`locator`、`state`、`warning`；素材可查询不代表已插入画布 |
+| `canvas upload` | `--path` 本地文件或 `--url` HTTPS 媒体直链，必须且只能提供一个；可调 `--poll-interval`、`--timeout` | 返回 `pippit_asset_id`、可用的 `media_asset_id`、`source_id`、`locator`、`state`、`warning`；素材可查询不代表已插入画布 |
 | `canvas allocate` | `--count` 分配数量 | 返回 `asset_ids[]`；只预留 ID，不创建节点或资产 |
 | `canvas apply` | `--project-id` 项目 ID；`--file` JSON 文件，默认 `-` 读 stdin | 一个 transaction，可含多条 patch；检查事务 ACK 和目标资产版本 |
 
@@ -14,15 +14,26 @@
 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"
+pippit-tool-cli canvas upload --url 'https://example.com/reference?signature=...' --team-id TEAM_ID
 ```
 
 示例代表不同操作，不应因为读到示例就全部执行。创建、上传可能以退出码 0 返回 `creating` / `processing` 和 `warning`：保留已返回的 ID，稍后用 `canvas get` 回查资产可见性；不要重复创建或上传。画布初始化概览尚未完成时，回查根资产仅证明资产可见，不足以宣称所有初始化完成，应保留 `web_url` 和原始状态说明限制。`request_id` 用于追踪，不能假定跨故障重试严格幂等。
 
+## URL Import
+
+画布流程可使用 `canvas upload --url` 导入外链；只需要稳定资产 ID 时也可按 [上传说明](upload-file.md) 使用 `upload-file --url`，同一素材选择一个入口，不重复导入。导入和目标画布使用相同 `--team-id`。Canvas 上传保存 `pippit_asset_id` 和 `state`，通用上传保存 `team_id` 与 `asset_id`。
+
+URL 导入前检查实际入口的 `--help` 含 `--url`；旧版缺少时按 [安装说明](../scripts/install.md) 更新并重新检查，仍不支持则说明缺口。服务端也须部署 URL 能力。仅支持服务端可访问且不重定向的 HTTPS 图片、视频、音频直链；当前服务端上限为 200 MiB，仍需格式校验和审核。不要求素材类型或文件名；保留原签名和查询参数，不把 URL 放进 `--path`。CLI 不读取、下载或缓存源素材。
+
+`--poll-interval` 与 `--timeout` 只控制上传返回后的素材可查询等待，不是服务端导入的超时参数。等待失败或超时仍输出已有稳定 ID、`processing` 和 `warning`，后续用 `canvas get` 查询，不重放上传。`ready` 不表示已创建节点；批量需控制导入和查询并发。
+
+这里的 `canvas upload.pippit_asset_id` 与 `upload-file.asset_id` 都是稳定的 Pippit 素材 ID。先用 `pippit-tool-cli canvas get --asset-id PIPPIT_ASSET_ID --team-id TEAM_ID` 查询真实素材，再在用户要求建节点时，将该 ID 填入语义 `create_biz_node.initialData.pippitAssetId`，其余输入按当前 schema 和目标画布确定。节点中的真实云媒体身份由现有 CLI 查询并填写，不把源 URL 写成节点 ID 或媒体 ID。写后按 [画布编辑流程](../workflows/canvas-edit.md) 回读；素材导入成功不代表节点已创建。
+
 ## 低层事务的使用边界
 
 媒体节点优先通过语义 `create_biz_node` 创建，`initialData` 只传 `pippitAssetId`：CLI 查询素材并填写真实云媒体 `assetId`。用 `update_asset.contentPatch` 或 `update_node_data.patch` 替换素材时也可只传新的 `pippitAssetId`。显式填写的 `assetId` 必须与素材查询结果匹配，否则返回 `INVALID_MEDIA_IDENTITY` 并拒绝写入。
 
-上传顶层旧字段 `asset_id` 是保留兼容的 workspace/source ID，不能当节点媒体 ID。`media_asset_id` 来自查询结果对应的 `Image/Video/Audio.asset_id`；缺失时不能用 `source_id`、`pippit_asset_id` 或画布节点 ID 补位。`node_asset_refs[].pippit_asset_id` 使用画布节点资产 ID。
+`canvas upload` 顶层旧字段 `asset_id` 是保留兼容的 workspace/source ID，不能当节点媒体 ID；它与 `upload-file.asset_id` 的含义不同。`media_asset_id` 来自查询结果对应的 `Image/Video/Audio.asset_id`；缺失时不能用 `source_id`、`pippit_asset_id` 或画布节点 ID 补位。`node_asset_refs[].pippit_asset_id` 使用画布节点资产 ID。
 
 批量 `apply_mutations` 默认非原子执行：必须检查 `data.results` 中每一项的 `committed` / `aborted` 状态，保留已成功项，不重跑整批。需要任一失败时整批回滚，可显式传 `atomic: true`。
 

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

@@ -22,7 +22,8 @@
 
 | 操作 | 入口或可定位的语义命令 | 要点 |
 | --- | --- | --- |
-| 创建画布、查资产、上传素材、分配 ID、提交事务 | `canvas create/get/upload/allocate/apply` | 见 [原生资产命令](canvas-assets.md) |
+| 创建画布、查资产、上传本地或 URL 素材、分配 ID、提交事务 | `canvas create/get/upload/allocate/apply` | 见 [原生资产命令](canvas-assets.md) |
+| 导入外链素材并用于画布 | `canvas upload --url`（带查询等待）或 `upload-file --url`，再按需创建节点 | 见 [URL 导入与资产复用](canvas-assets.md#url-import) |
 | 读取画布和资产 | `get_snapshot`、`get_asset`、`get_permissions` | 取得真实节点/资产 ID，不用名称猜 ID |
 | 创建业务节点 | `create_biz_node` | 支持类型和初始字段用 `--node-kind` 查看；不要手拼业务节点结构 |
 | 节点位置、大小、样式、布局、分组 | `move_nodes`、`resize_node`、`set_node_style`、`align_nodes`、`arrange_nodes`、`group_nodes` 等 | 先查询目标和归属；删除与重排仅限用户请求范围 |

package/skills/xyq-nest-skill/commands/upload-file.md

@@ -0,0 +1,40 @@
+# upload-file：素材上传与 URL 导入
+
+将本地文件或 HTTPS 媒体链接导入当前个人或团队空间，返回可复用的 Pippit 资产 ID。`--path` 与 `--url` 必须且只能提供一个。URL 模式只需用户提供链接，素材类型和内部文件名由服务端识别，不要求 `asset_type` 或 `file_name`。
+
+先用 `pippit-tool-cli upload-file --help` 确认当前版本支持 `--url`；旧版缺少该参数时先更新到支持版本，再核对帮助。可用发布版本仍不支持时说明能力缺口，不反复升级。URL 导入还需要服务端部署对应能力，帮助检查通过不代表服务端已可用。
+
+## Inputs
+
+```bash
+pippit-tool-cli upload-file --path "/path/to/reference.png" --team-id TEAM_ID
+pippit-tool-cli upload-file --url 'https://example.com/reference?signature=...' --team-id TEAM_ID
+```
+
+示例二选一执行。`TEAM_ID` 使用本次工作流已确定的空间，个人为 `0`，后续查资产或建节点仍使用相同空间。
+
+- `--path`：本地普通文件，支持图片、视频及 `.mp3` / `.wav` 音频。CLI 要求小于 500 MB（500000000 字节）；还须满足服务端的格式、大小和审核限制。
+- `--url`：服务端可访问的 HTTPS 图片、视频或音频直链，可以是有效签名 URL，也可以没有文件后缀。服务端拒绝自动重定向，短链接或返回 3xx 的地址需换成最终素材直链。不能含 `user:password@host` 或 fragment；保留原始查询参数与签名，不擅自解码、删改或重签。shell 中为完整 URL 加单引号，避免 `&` 等字符被解释为命令。
+- URL 模式由服务端探测内容并导入，CLI 不下载、读取或缓存源素材。当前服务端上限为 200 MiB，仍须通过格式校验和审核；不能仅凭 URL 后缀判断素材类型或可用性。
+
+## Output
+
+成功输出示例：
+
+```json
+{"team_id":"0","asset_id":"PIPPIT_ASSET_ID"}
+```
+
+保存这两个字符串。此处 `asset_id` 取自 API 的 `data.pippit_asset_id`，是稳定的 Pippit 资产 ID，不是云媒体 ID 或画布节点 ID。命令不返回 thread/run ID，也不提供 Canvas 的 `state`、`locator` 或就绪轮询；不要调用 `query-result` 等待导入。
+
+用户只要求导入时，返回该资产 ID 与空间即可。用户还要求建立画布参考节点时，按 [Canvas 资产说明](canvas-assets.md#url-import) 和 [画布编辑流程](../workflows/canvas-edit.md) 查询素材，再用现有节点创建能力关联该 ID，写后回读。取得 ID 不代表节点已经创建或生成任务已经完成。
+
+生成、超分与擦字幕命令的文件参数仍接收本地路径；不能将本命令返回的资产 ID 或源 URL 填入这些参数。
+
+## Failures
+
+双传或均未提供来源时，先修正参数。链接过期、源站拒绝访问、格式/大小不符或审核失败时，保留实际错误与可用的 LogID，按原因处理；不能把所有失败都归为审核拒绝。
+
+收到资产 ID 后复用已有资产。超时或请求结果不确定时，保留已有 ID 和错误信息；有 ID 可在原空间查询，没有 ID 时不能猜测或声称导入成功，也不自动重放请求。批量调用控制并发，逐项保留成功 ID 与失败原因，不重跑已成功项。
+
+URL 导入失败不自动改为本地下载再上传。画布流程也可以使用 [`canvas upload --url`](canvas-assets.md#url-import)，它复用相同服务端导入接口，但另有素材查询等待和 `state` / `locator` 输出；稳定 ID 取 `pippit_asset_id`，不能套用本命令的 `asset_id` 含义。已导入素材直接复用，不为等待就绪再调用另一个上传入口。

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

@@ -7,7 +7,7 @@ const os = require("os");
 const path = require("path");
 
 const REQUIRED_COMMANDS = [
-  "status", "login", "logout", "query-result",
+  "status", "login", "logout", "query-result", "upload-file",
   "space list", "space use",
   "generate-image", "generate-video", "video-super-resolution",
   "erase-video-subtitle", "get-credit-balance", "model list", "model describe",

package/skills/xyq-nest-skill/scripts/install.md

@@ -12,7 +12,9 @@ node "{baseDir}/scripts/ensure-cli.js"
 
 ## 查找与复用
 
-脚本依次检查 PATH 中的 CLI 和自身缓存，验证版本及本 Skill 使用命令的 `--help`；命令集合维护在脚本的 `REQUIRED_COMMANDS`，包含 `model list`、`model describe`、`space list` 和 `space use`。同时从 `generate-image --help` 检查各业务命令共用的全局 `--team-id` 参数；缺少该参数时沿用缺少必需命令的升级流程。帮助检查不调用生成服务，也不需要凭据，不证明账号权限或服务端运行状态。
+脚本依次检查 PATH 中的 CLI 和自身缓存，验证版本及本 Skill 使用命令的 `--help`；命令集合维护在脚本的 `REQUIRED_COMMANDS`，包含 `upload-file`、`model list`、`model describe`、`space list` 和 `space use`。同时从 `generate-image --help` 检查各业务命令共用的全局 `--team-id` 参数；缺少该参数时沿用缺少必需命令的升级流程。帮助检查不调用生成服务，也不需要凭据，不证明账号权限或服务端运行状态。
+
+可选参数按实际任务检查帮助：URL 导入前核对所选入口 `upload-file --help` 或 `canvas upload --help` 含 `--url`，缺少时先更新到支持版本。安装脚本只检查必需命令，不因未使用的 URL 参数自动升级，也不证明服务端已部署 URL 导入能力。
 
 命令齐全则直接复用，不检查最新版本；不存在或缺少必需命令时，获取 `@pippit-dev/cli@latest`。PATH 旧版本缺少命令但缓存完整时复用缓存，避免每次升级。版本命令不能运行或检查超时则报告运行错误。
 

package/skills/xyq-nest-skill/workflows/canvas-edit.md

@@ -5,7 +5,7 @@
 1. **准备入口**：执行 Canvas 安装检查，保存 `cli_path` 和 `canvas_entry`，按授权文档确认身份，并按 Space Selection 确定 TeamID。后续独立命令均显式使用同一 `--team-id TEAM_ID`，个人为 `0`；已有画布沿用原空间。只查命令目录和离线指南无需登录；查询真实画布、执行编辑需要授权。
 2. **确定目标**：已有画布使用真实 `canvas_asset_id` 作为语义命令的 `--canvas-id`。用户提供的信息无法唯一定位时先补齐，不创建替代画布。新画布仅在用户要求创建时使用原生 `canvas create`，检查其返回状态。
 3. **发现与查询**：`list → describe/schema` 定位操作。用 `get_snapshot` 查节点，用 `get_asset` 查具体资产；3D/多轨再查询其独立文档。`run` 是统一执行入口，其中 query/get 类操作是读取，不等于所有 run 都是写入。
-4. **准备输入**：使用查询所得的节点、子对象和资产 ID。多轨 `expectedRevision` 来自最新查询。复杂输入写入 JSON 文件后传 `--file`；不要同时传 `--file` 和 `--input`。只操作用户指定范围。
+4. **准备输入**：使用查询所得的节点、子对象和资产 ID。外链素材通过 `canvas upload --url` 导入并保存 `pippit_asset_id`、`state` 与可能的 `warning`；也可复用 `upload-file --url` 返回的稳定 `asset_id`，再按 [URL 导入与资产复用](../commands/canvas-assets.md#url-import) 创建所需节点；已有资产直接复用，不重复导入。多轨 `expectedRevision` 来自最新查询。复杂输入写入 JSON 文件后传 `--file`；不要同时传 `--file` 和 `--input`。只操作用户指定范围。
 5. **预演与写入**：当前 schema 支持 `dryRun` 时可先预演，再在已有授权范围内执行真实修改。不能给所有命令强加此字段：领域命令的 dryRun 验证具体编辑，通用 `apply_mutations.dryRun` 不能替代领域预演。删除、恢复等操作仅按用户明确要求执行。
 6. **验证结果**：检查退出码与 JSON 的 `ok`、错误信息，`ok=false` 即失败。`dryRun=true` 成功不代表落盘；实际写入成功后，用对应查询回读目标字段及关联关系，确认没有误改其他对象。
 7. **反馈交付**：说明已验证的画布变化，保留已有/返回的画布链接及目标 ID。只完成文档编辑时不要声称图片/视频已生成；确有媒体文件待交付时遵循 [媒体交付标准](async-delivery.md)。