@pippit-dev/cli 1.0.53 → 1.0.55

package/README.md

@@ -77,6 +77,14 @@ pippit-tool-cli get-credit-balance --team-id 0      # 仅本次使用个人
 
 `space list/use TEAM_ID` 依赖 API 部署 `/api/biz/v1/skill/get_lite_team_list` 的 AK 适配入口，业务团队使用还依赖对应 API 团队权限实现；不直连 commerce Web 接口。宿主 Agent 的选择、任务恢复与不回退规则已写入三个 Skill 的 `Space Selection` 章节。
 
+## 查询出口 IP
+
+```bash
+pippit-tool-cli ip
+```
+
+输出 `{"client_ip":"..."}`，返回服务端看到的出口 IP，无需登录或 AK；沿用 `config.toml` 的 API 地址与 PPE 配置。AK 的 IP 白名单仍在网页密钥管理页设置。
+
 ## 账号 AIGC 水印设置
 
 ```bash

package/checksums.txt

@@ -1,6 +1,6 @@
-08e0f157a05bdcbbb4c7a53eeeee3374d5be4bf86ec31139c5d42328c8cc781e  pippit-tool-cli-1.0.53-darwin-amd64.tar.gz
-fa1b79ed862a997d7ec8117895158f1914d2fcaa30792b303fd924d2856a834f  pippit-tool-cli-1.0.53-darwin-arm64.tar.gz
-e0d30c4edf201108587da2bd1ce97f9e7a30721e41700c50e7ddb57cc4c2474a  pippit-tool-cli-1.0.53-linux-amd64.tar.gz
-b60c817d9b58659838baf9954e5cc110ddc92ed2736e5512047dc2b20a9dfde8  pippit-tool-cli-1.0.53-linux-arm64.tar.gz
-b890470552424b37fbd98d8a0e202d66526f7f575233cfb860599dadbc802be2  pippit-tool-cli-1.0.53-windows-amd64.zip
-cf549f5b6e7d929d7b8b48b0a1a3df467ad921c23b4a93361799d7723b023bde  pippit-tool-cli-1.0.53-windows-arm64.zip
+99a7ec8c86f332f9a3a8e7538d9eb1c237e0d8eebdacdaeb262f77ea716d3bd7  pippit-tool-cli-1.0.55-darwin-amd64.tar.gz
+8cefadb8e6ac41a7c6ff2f1a1ab89448176734ff449238cbcd3f38bbc0acc8cf  pippit-tool-cli-1.0.55-darwin-arm64.tar.gz
+69d0d83c74c95b46f1eb859ed5a9fe4aaf3b38f25465ff5a4d0c0bf33d815988  pippit-tool-cli-1.0.55-linux-amd64.tar.gz
+086db5207fbe14e15fb97f0a3c970c36de06e67d333cd68373be6a0e5af2626a  pippit-tool-cli-1.0.55-linux-arm64.tar.gz
+14cda14f712ff2c09566fbeb68f39296b200e3d54cdc659e13baf1e9f9b1ed92  pippit-tool-cli-1.0.55-windows-amd64.zip
+86ae993c8b32c1a6a09c81882e21bac7e8368468fe28b1e7be90b68466d8fe23  pippit-tool-cli-1.0.55-windows-arm64.zip

package/cmd/ip.go

@@ -0,0 +1,28 @@
+package cmd
+
+import (
+	"io"
+
+	"github.com/Pippit-dev/pippit-cli/internal/adapter"
+	"github.com/Pippit-dev/pippit-cli/internal/commandnames"
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newIPCommand(stdout, stderr io.Writer, runner *common.Runner, policy adapter.HTTPAdapter) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   commandnames.IP,
+		Short: "Query the outbound IP observed by the server",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog(commandnames.IP, nil, func(cmd *cobra.Command, _ []string) error {
+			result, err := common.GetClientIP(cmd.Context(), runner, policy)
+			if err != nil {
+				return err
+			}
+			return common.WriteJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	return cmd
+}

package/cmd/ip_test.go

@@ -0,0 +1,101 @@
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Pippit-dev/pippit-cli/internal/adapter"
+	"github.com/Pippit-dev/pippit-cli/internal/auth"
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+)
+
+type ipCredentialStore struct {
+	auth.CredentialStore
+	loads int
+}
+
+func (store *ipCredentialStore) Load(context.Context) (*auth.Credential, error) {
+	store.loads++
+	return nil, errors.New("corrupt credential fixture")
+}
+
+type ipCommandPolicy struct {
+	adapter.Default
+	options adapter.CLIOptions
+}
+
+func (policy ipCommandPolicy) CLIOptions() adapter.CLIOptions { return policy.options }
+
+func TestIPCommandDoesNotReadCredentialsOrInitializeSpace(t *testing.T) {
+	for _, accessKey := range []string{"", "existing-key"} {
+		t.Run("configured_key="+accessKey, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				for _, header := range []string{"Authorization", "Cookie", "X-Team-Id"} {
+					if r.Header.Get(header) != "" {
+						t.Errorf("anonymous command sent %s", header)
+					}
+				}
+				_, _ = io.WriteString(w, `{"ret":"0","data":{"client_ip":"8.8.8.8"}}`)
+			}))
+			defer server.Close()
+			cfg := config.Load()
+			cfg.BaseURL, cfg.AccessKey = server.URL, accessKey
+			cfg.HTTPTimeout = time.Second
+			policy := ipCommandPolicy{options: adapter.CLIOptions{
+				DefaultAllowRootCommands: true,
+				LocalCredentialsEnabled:  true,
+			}}
+			runner := newRootRunnerWithAdapter(cfg, policy)
+			store := &ipCredentialStore{}
+			runner.Auth = auth.NewManager(cfg, auth.WithCredentialStore(store))
+			var stdout, stderr bytes.Buffer
+			root := newRootCommandWithAdapter(&stdout, &stderr, runner, policy)
+			root.SetArgs([]string{"--team-id", "42", "ip"})
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute() = %v, stderr = %q", err, stderr.String())
+			}
+			if store.loads != 0 {
+				t.Fatalf("credential loads = %d, want 0 even with corrupt credentials", store.loads)
+			}
+			command, _, err := root.Find([]string{"ip"})
+			if err != nil || command == nil || common.SpaceSession(command.Context()) != nil {
+				t.Fatalf("ip initialized a space session: %v", err)
+			}
+			var output map[string]string
+			if err := json.Unmarshal(stdout.Bytes(), &output); err != nil || len(output) != 1 || output["client_ip"] != "8.8.8.8" {
+				t.Fatalf("stdout = %q, error = %v, want only client_ip", stdout.String(), err)
+			}
+		})
+	}
+}
+
+func TestIPCommandRespectsAdapterFiltering(t *testing.T) {
+	for _, allowed := range []bool{true, false} {
+		options := adapter.CLIOptions{}
+		if allowed {
+			options.AllowedRootCommands = []string{"ip"}
+		}
+		root := NewRootCommandWithAdapter(io.Discard, io.Discard, ipCommandPolicy{options: options})
+		command, _, _ := root.Find([]string{"ip"})
+		if got := command != nil && command.Name() == "ip"; got != allowed {
+			t.Fatalf("ip present = %v, want %v", got, allowed)
+		}
+	}
+}
+
+func TestIPCommandRejectsArguments(t *testing.T) {
+	command := newIPCommand(io.Discard, io.Discard, nil, adapter.Default{})
+	command.SetArgs([]string{"unexpected"})
+	if err := command.Execute(); err == nil || !strings.Contains(err.Error(), "unexpected") {
+		t.Fatalf("Execute() = %v, want positional argument rejection", err)
+	}
+}

package/cmd/root.go

@@ -120,6 +120,7 @@ func newRootCommandWithAdapter(stdout, stderr io.Writer, runner *common.Runner,
 	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
 	root.AddCommand(newGetCreditBalanceCommand(stdout, stderr, runner))
 	root.AddCommand(newWatermarkCommand(stdout, stderr, runner))
+	root.AddCommand(newIPCommand(stdout, stderr, runner, policy))
 	root.AddCommand(newModelCommand(stdout, stderr, runner))
 	root.AddCommand(newMarketingCommand(stdout, stderr, runner, policy))
 	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))

package/cmd/space.go

@@ -30,7 +30,7 @@ func prepareCommandSpace(cmd *cobra.Command, runner *common.Runner, stderr io.Wr
 		top = top.Parent()
 	}
 	switch top.Name() {
-	case commandnames.Space, commandnames.Login, commandnames.Logout, commandnames.Status, commandnames.Update, commandnames.Completion, commandnames.Help, commandnames.DownloadResult, commandnames.Watermark:
+	case commandnames.Space, commandnames.Login, commandnames.Logout, commandnames.Status, commandnames.Update, commandnames.Completion, commandnames.Help, commandnames.DownloadResult, commandnames.Watermark, commandnames.IP:
 		return nil
 	}
 	raw, _ := cmd.Flags().GetString("space-context")

package/dist/checksums.txt

@@ -1,6 +1,6 @@
-08e0f157a05bdcbbb4c7a53eeeee3374d5be4bf86ec31139c5d42328c8cc781e  pippit-tool-cli-1.0.53-darwin-amd64.tar.gz
-fa1b79ed862a997d7ec8117895158f1914d2fcaa30792b303fd924d2856a834f  pippit-tool-cli-1.0.53-darwin-arm64.tar.gz
-e0d30c4edf201108587da2bd1ce97f9e7a30721e41700c50e7ddb57cc4c2474a  pippit-tool-cli-1.0.53-linux-amd64.tar.gz
-b60c817d9b58659838baf9954e5cc110ddc92ed2736e5512047dc2b20a9dfde8  pippit-tool-cli-1.0.53-linux-arm64.tar.gz
-b890470552424b37fbd98d8a0e202d66526f7f575233cfb860599dadbc802be2  pippit-tool-cli-1.0.53-windows-amd64.zip
-cf549f5b6e7d929d7b8b48b0a1a3df467ad921c23b4a93361799d7723b023bde  pippit-tool-cli-1.0.53-windows-arm64.zip
+99a7ec8c86f332f9a3a8e7538d9eb1c237e0d8eebdacdaeb262f77ea716d3bd7  pippit-tool-cli-1.0.55-darwin-amd64.tar.gz
+8cefadb8e6ac41a7c6ff2f1a1ab89448176734ff449238cbcd3f38bbc0acc8cf  pippit-tool-cli-1.0.55-darwin-arm64.tar.gz
+69d0d83c74c95b46f1eb859ed5a9fe4aaf3b38f25465ff5a4d0c0bf33d815988  pippit-tool-cli-1.0.55-linux-amd64.tar.gz
+086db5207fbe14e15fb97f0a3c970c36de06e67d333cd68373be6a0e5af2626a  pippit-tool-cli-1.0.55-linux-arm64.tar.gz
+14cda14f712ff2c09566fbeb68f39296b200e3d54cdc659e13baf1e9f9b1ed92  pippit-tool-cli-1.0.55-windows-amd64.zip
+86ae993c8b32c1a6a09c81882e21bac7e8368468fe28b1e7be90b68466d8fe23  pippit-tool-cli-1.0.55-windows-arm64.zip

package/internal/commandnames/names.go

@@ -11,5 +11,6 @@ const (
 	Help           = "help"
 	Model          = "model"
 	Watermark      = "watermark"
+	IP             = "ip"
 	DownloadResult = "download-result"
 )

package/internal/common/client_ip.go

@@ -0,0 +1,58 @@
+package common
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/netip"
+
+	"github.com/Pippit-dev/pippit-cli/internal/adapter"
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+)
+
+type ClientIPResult struct {
+	ClientIP string `json:"client_ip"`
+}
+
+type clientIPRequestPolicy struct {
+	adapter.HTTPAdapter
+}
+
+func (clientIPRequestPolicy) PrepareAPIRequest(context.Context, *http.Request) (adapter.AuthDecision, error) {
+	return adapter.UseDefaultAuth, nil
+}
+
+// GetClientIP keeps the host transport and routing, without resolving account credentials.
+func GetClientIP(ctx context.Context, runner *Runner, policy adapter.HTTPAdapter) (*ClientIPResult, error) {
+	if runner == nil || runner.Config == nil {
+		return nil, fmt.Errorf("查询出口 IP 的运行配置缺失")
+	}
+	cfg := runner.Config
+	anonymousPolicy := clientIPRequestPolicy{HTTPAdapter: adapter.HTTPOrDefault(policy)}
+	client := NewHTTPClientWithAdapter(cfg.BaseURL, cfg.HTTPTimeout, NewAccessKeyAuthorizer(""), adapter.WithPPE(anonymousPolicy, cfg.PPEEnv))
+	// This query is anonymous even when the caller's context carries a selected team.
+	ctx = WithSpace(ctx, nil)
+	var resp struct {
+		Ret    string          `json:"ret"`
+		Errmsg string          `json:"errmsg"`
+		LogID  string          `json:"log_id"`
+		Data   *ClientIPResult `json:"data"`
+	}
+	if err := client.SendRequest(ctx, config.GetClientIPPath, nil, &resp); err != nil {
+		return nil, fmt.Errorf("查询出口 IP 请求失败: %w", err)
+	}
+	if resp.Ret != "0" {
+		if resp.Errmsg == "" {
+			resp.Errmsg = "未知错误"
+		}
+		return nil, NewLogIDError(fmt.Sprintf("查询出口 IP 请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
+	}
+	if resp.Data == nil || resp.Data.ClientIP == "" {
+		return nil, NewLogIDError("查询出口 IP 响应缺少 data.client_ip", resp.LogID)
+	}
+	ip, err := netip.ParseAddr(resp.Data.ClientIP)
+	if err != nil || ip.Zone() != "" {
+		return nil, NewLogIDError("查询出口 IP 响应的 data.client_ip 无效", resp.LogID)
+	}
+	return &ClientIPResult{ClientIP: ip.Unmap().String()}, nil
+}

package/internal/common/client_ip_test.go

@@ -0,0 +1,135 @@
+package common
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Pippit-dev/pippit-cli/internal/adapter"
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+	"github.com/Pippit-dev/pippit-cli/internal/space"
+)
+
+type clientIPPolicy struct {
+	adapter.Default
+	prepareCalls int
+}
+
+func (p *clientIPPolicy) PrepareAPIRequest(_ context.Context, req *http.Request) (adapter.AuthDecision, error) {
+	p.prepareCalls++
+	req.Header.Set("Authorization", "Bearer adapter-key")
+	req.Header.Set("Cookie", "sessionid=adapter-cookie")
+	req.Header.Set("X-Team-Id", "99")
+	return adapter.AuthProvided, nil
+}
+
+func (*clientIPPolicy) WrapTransport(next http.RoundTripper) http.RoundTripper {
+	if next == nil {
+		next = http.DefaultTransport
+	}
+	return clientIPTransport{next: next}
+}
+
+type clientIPTransport struct{ next http.RoundTripper }
+
+func (transport clientIPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	request := req.Clone(req.Context())
+	request.Header.Set("X-Test-IP-Transport", "present")
+	return transport.next.RoundTrip(request)
+}
+
+func TestGetClientIPIsAnonymousAndPreservesTransportAndRouting(t *testing.T) {
+	for _, env := range []string{"", "ppe_first", "ppe_second"} {
+		t.Run("env="+env, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.Method != http.MethodGet || r.URL.Path != "/api/biz/v1/skill/get_client_ip" {
+					t.Errorf("request = %s %s, want anonymous client IP GET", r.Method, r.URL.Path)
+				}
+				body, err := io.ReadAll(r.Body)
+				if err != nil || len(body) != 0 || r.Header.Get("Content-Type") != "" {
+					t.Errorf("GET body = %q, Content-Type = %q, error = %v", body, r.Header.Get("Content-Type"), err)
+				}
+				for _, header := range []string{"Authorization", "Cookie", "X-Team-Id"} {
+					if r.Header.Get(header) != "" {
+						t.Errorf("anonymous request retained %s", header)
+					}
+				}
+				if r.Header.Get("X-Test-IP-Transport") != "present" {
+					t.Error("anonymous request bypassed adapter transport")
+				}
+				wantUsePPE := ""
+				if env != "" {
+					wantUsePPE = "1"
+				}
+				if r.Header.Get("x-tt-env") != env || r.Header.Get("x-use-ppe") != wantUsePPE {
+					t.Error("anonymous request did not follow the configured PPE environment")
+				}
+				_, _ = io.WriteString(w, `{"ret":"0","data":{"client_ip":"8.8.8.8"}}`)
+			}))
+			defer server.Close()
+
+			cfg := config.Load()
+			cfg.BaseURL, cfg.PPEEnv, cfg.AccessKey = server.URL, env, "existing-key"
+			cfg.HTTPTimeout = time.Second
+			policy := &clientIPPolicy{}
+			runner := NewRunner(cfg, NewHTTPClientWithAdapter(server.URL, time.Second, NewAccessKeyAuthorizer(cfg.AccessKey), policy))
+			teamID := "42"
+			ctx := WithSpace(context.Background(), &space.Session{Explicit: &teamID})
+			result, err := GetClientIP(ctx, runner, policy)
+			if err != nil || result == nil || result.ClientIP != "8.8.8.8" {
+				t.Fatalf("GetClientIP() = %#v, %v", result, err)
+			}
+			if policy.prepareCalls != 0 {
+				t.Fatalf("adapter authentication calls = %d, want 0", policy.prepareCalls)
+			}
+		})
+	}
+}
+
+func TestGetClientIPRejectsUnusableResponses(t *testing.T) {
+	for _, tc := range []struct {
+		name, response, wantError string
+		status                    int
+	}{
+		{"unavailable_source", `{"ret":"53001","errmsg":"暂时无法识别当前来源 IP","log_id":"log_ip"}`, "53001", http.StatusOK},
+		{"unavailable_source_http503", `{"ret":"53001","errmsg":"暂时无法识别当前来源 IP","log_id":"log_ip"}`, "53001", http.StatusServiceUnavailable},
+		{"missing_data", `{"ret":"0","log_id":"log_ip"}`, "data", http.StatusOK},
+		{"missing_ip", `{"ret":"0","log_id":"log_ip","data":{}}`, "client_ip", http.StatusOK},
+		{"invalid_ip", `{"ret":"0","log_id":"log_ip","data":{"client_ip":"not-an-ip"}}`, "client_ip", http.StatusOK},
+		{"zoned_ip", `{"ret":"0","log_id":"log_ip","data":{"client_ip":"fe80::1%eth0"}}`, "client_ip", http.StatusOK},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(tc.status)
+				_, _ = io.WriteString(w, tc.response)
+			}))
+			defer server.Close()
+			cfg := config.Load()
+			cfg.BaseURL = server.URL
+			cfg.HTTPTimeout = time.Second
+			_, err := GetClientIP(context.Background(), NewRunner(cfg, nil), adapter.Default{})
+			if err == nil || !strings.Contains(err.Error(), tc.wantError) || !strings.Contains(err.Error(), "log_ip") {
+				t.Fatalf("GetClientIP() error = %v, want %q and log ID", err, tc.wantError)
+			}
+		})
+	}
+}
+
+func TestGetClientIPSupportsIPv6(t *testing.T) {
+	const ip = "2001:4860:4860::8888"
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = io.WriteString(w, `{"ret":"0","data":{"client_ip":"`+ip+`"}}`)
+	}))
+	defer server.Close()
+	cfg := config.Load()
+	cfg.BaseURL = server.URL
+	cfg.HTTPTimeout = time.Second
+	result, err := GetClientIP(context.Background(), NewRunner(cfg, nil), adapter.Default{})
+	if err != nil || result == nil || result.ClientIP != ip {
+		t.Fatalf("GetClientIP() = %#v, %v, want IPv6 %s", result, err, ip)
+	}
+}

package/internal/config/config.go

@@ -21,6 +21,7 @@ const (
 	SubmitMarketingRunPath       = "/api/biz/v1/agent/submit_marketing_run"
 	QueryGenerateVideoResultPath = "/api/biz/v1/agent/query_generate_video_result"
 	GetCreditBalancePath         = "/api/biz/v1/skill/get_credit_balance"
+	GetClientIPPath              = "/api/biz/v1/skill/get_client_ip"
 	GetWatermarkSettingPath      = "/api/biz/v1/skill/mget_user_setting"
 	UpdateWatermarkSettingPath   = "/api/biz/v1/skill/update_user_setting"
 	GetLiteTeamListPath          = "/api/biz/v1/skill/get_lite_team_list"

package/package.json

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

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

@@ -33,6 +33,22 @@ URL 导入前检查实际入口的 `--help` 含 `--url`；旧版缺少时按 [
 
 媒体节点优先通过语义 `create_biz_node` 创建，`initialData` 只传 `pippitAssetId`：CLI 查询素材并填写真实云媒体 `assetId`。用 `update_asset.contentPatch` 或 `update_node_data.patch` 替换素材时也可只传新的 `pippitAssetId`。显式填写的 `assetId` 必须与素材查询结果匹配，否则返回 `INVALID_MEDIA_IDENTITY` 并拒绝写入。
 
+普通 `biz/image` 的素材绑定在同层 `content.pippitAssetId` 与 `content.assetId`。`content.appearanceInfo`、`content.sourceInfos` 属于角色/场景结构，不能套用于普通图片；角色/场景继续按各自领域命令及 schema 操作。
+
+以下仅用于核对保存后的节点结构，ID 占位符须替换为同空间真实查询结果，不作为完整写入请求直接执行：
+
+```json
+{"type":"biz/image","content":{"pippitAssetId":"PIPPIT_MATERIAL_ID","assetId":"CLOUD_IMAGE_ASSET_ID"}}
+```
+
+错误反例：同层绑定缺失，即使保存 ACK，也不是可用参考图：
+
+```json
+{"type":"biz/image","content":{"appearanceInfo":{"pippitAssetId":"PIPPIT_MATERIAL_ID","assetId":"CLOUD_IMAGE_ASSET_ID"}}}
+```
+
+可先创建不含绑定的图片空草稿；不能用 `generation`、`sourceInfos` 或手改“已上传”状态把空草稿视为素材已就绪。已有错绑数据先回读、核对真实素材，再在用户授权的编辑范围内修正，不自动迁移用户画布。
+
 `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/scripts/ensure-cli.js

@@ -12,6 +12,18 @@ const REQUIRED_COMMANDS = [
   "generate-image", "generate-video", "video-super-resolution",
   "erase-video-subtitle", "get-credit-balance", "model list", "model describe",
 ];
+// v1.0.50 first ships ordinary-image binding guards in both Canvas entries.
+const MIN_CANVAS_VERSION = [1, 0, 50];
+
+function supportsCanvasBindings(version) {
+  const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+  if (!match) return false;
+  const parts = match.slice(1, 4).map(Number);
+  for (let i = 0; i < MIN_CANVAS_VERSION.length; i++) {
+    if (parts[i] !== MIN_CANVAS_VERSION[i]) return parts[i] > MIN_CANVAS_VERSION[i];
+  }
+  return true;
+}
 
 function npmCommand() {
   if (process.platform !== "win32") return ["npm", []];
@@ -80,6 +92,11 @@ function ensureCLI({ canvas = false } = {}) {
     if (expectedVersion && version !== expectedVersion) {
       throw new Error(`CLI 版本 ${version} 与 npm 包版本 ${expectedVersion} 不一致。`);
     }
+    if (canvas && !supportsCanvasBindings(version)) {
+      const failure = new Error(`Canvas 需要 CLI >=${MIN_CANVAS_VERSION.join(".")} 正式版以校验图片绑定，当前版本：${version}。`);
+      failure.missingCommand = "Canvas 图片绑定校验（CLI >=1.0.50 正式版）";
+      throw failure;
+    }
     const commands = REQUIRED_COMMANDS.map((command) => command.split(" "));
     if (canvas) {
       for (const command of ["create", "get", "allocate", "upload", "apply"]) commands.push(["canvas", command]);
@@ -165,7 +182,7 @@ function ensureCLI({ canvas = false } = {}) {
 
 if (require.main === module) {
   if (process.argv.length === 3 && process.argv[2] === "--help") {
-    console.log("Usage: node ensure-cli.js [--canvas]\n优先复用 PATH 或缓存中命令齐全的 CLI，不存在或缺少必需命令时安装 npm latest，成功输出 {cli_path, version} JSON。--canvas 额外验证画布原生命令和 npm 运行时，并返回 canvas_entry。");
+    console.log("Usage: node ensure-cli.js [--canvas]\n优先复用 PATH 或缓存中命令齐全的 CLI，不存在或缺少必需命令时安装 npm latest，成功输出 {cli_path, version} JSON。--canvas 要求 CLI >=1.0.50 正式版，额外验证画布原生命令和 npm 运行时，并返回 canvas_entry。");
   } else if (process.argv.length !== 2 && !(process.argv.length === 3 && process.argv[2] === "--canvas")) {
     console.error("不支持的参数。用法：node ensure-cli.js [--canvas]");
     process.exitCode = 1;

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

@@ -16,7 +16,7 @@ node "{baseDir}/scripts/ensure-cli.js"
 
 可选参数按实际任务检查帮助：URL 导入前核对所选入口 `upload-file --help` 或 `canvas upload --help` 含 `--url`，缺少时先更新到支持版本。安装脚本只检查必需命令，不因未使用的 URL 参数自动升级，也不证明服务端已部署 URL 导入能力。
 
-命令齐全则直接复用，不检查最新版本；不存在或缺少必需命令时，获取 `@pippit-dev/cli@latest`。PATH 旧版本缺少命令但缓存完整时复用缓存，避免每次升级。版本命令不能运行或检查超时则报告运行错误。
+命令齐全则直接复用，不检查最新版本；Canvas 另有下述最低版本要求。不存在、缺少必需命令或不满足 Canvas 最低版本时，获取 `@pippit-dev/cli@latest`。PATH 旧版本不兼容但缓存完整时复用缓存，避免每次升级。版本命令不能运行或检查超时则报告运行错误。
 
 需要安装时，脚本跳过 npm 生命周期脚本获取包，调用包内 `scripts/install-cli.js` 只安装 CLI。成功后缓存到 `~/.cache/pippit-tool-cli/xyq-skill/<平台>-<架构>/current`。不要求全局 npm 写入权限，也不安装或清理全局 Skill。
 
@@ -36,7 +36,9 @@ node "{baseDir}/scripts/ensure-cli.js"
 
 ## Canvas 运行时检查
 
-画布任务改用 `node "{baseDir}/scripts/ensure-cli.js" --canvas`。除原有检查外，再验证五个原生资产子命令的帮助，并通过同一个 npm 包的 Node 入口真实执行离线 `canvas command list`，确认运行时可加载且含基本查询与节点创建能力。该检查不登录、不访问画布、不写入远端。
+画布任务改用 `node "{baseDir}/scripts/ensure-cli.js" --canvas`。要求 CLI 至少为 `1.0.50` 正式版，该版本起原生 `canvas apply` 和 npm 语义运行时均包含普通图片绑定校验；仅有同名命令不能证明旧版包含该修复。旧版、预发布版或无法识别的版本按不兼容处理，先查缓存，再至多安装一次；最新包仍不兼容则报错。普通媒体任务不受此最低版本限制。
+
+除原有检查外，再验证五个原生资产子命令的帮助，并通过同一个 npm 包的 Node 入口真实执行离线 `canvas command list`，确认运行时可加载且含基本查询与节点创建能力。该检查不登录、不访问画布、不写入远端。保留当前 Skill 的实际路径及返回的 `version`、`cli_path`、`canvas_entry`，便于故障定位；`Pippit-CLI/1.0` 是 User-Agent，不能作为 CLI 发行版本。
 
 成功额外返回 `canvas_entry`，供 `node "CANVAS_ENTRY" canvas command ...` 使用；`cli_path` 仍用于原生命令。语义操作的实际支持范围以当前目录为准，检查通过不代表所有业务操作或服务端权限都可用。
 

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

@@ -7,7 +7,7 @@
 3. **发现与查询**：`list → describe/schema` 定位操作。用 `get_snapshot` 查节点，用 `get_asset` 查具体资产；3D/多轨再查询其独立文档。`run` 是统一执行入口，其中 query/get 类操作是读取，不等于所有 run 都是写入。
 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` 成功不代表落盘；实际写入成功后，用对应查询回读目标字段及关联关系，确认没有误改其他对象。
+6. **验证结果**：检查退出码与 JSON 的 `ok`、错误信息，`ok=false` 即失败。`dryRun=true` 成功不代表落盘；实际写入成功后，用对应查询回读目标字段及关联关系，确认没有误改其他对象。素材绑定还须按[图片绑定契约](../commands/canvas-assets.md#低层事务的使用边界)核对节点类型、字段位置和素材身份：普通 `biz/image` 的 `content.pippitAssetId` 必须是所选图片素材，`content.assetId` 必须匹配该素材查询的 `Image.asset_id`。保存 ACK 只证明事务被接受，不证明参考素材可用。
 7. **反馈交付**：说明已验证的画布变化，保留已有/返回的画布链接及目标 ID。只完成文档编辑时不要声称图片/视频已生成；确有媒体文件待交付时遵循 [媒体交付标准](async-delivery.md)。
 
 语义执行骨架（占位符替换为当前目录中的命令、真实 ID 和已准备的输入文件）：
@@ -17,3 +17,5 @@ node "CANVAS_ENTRY" canvas command run COMMAND_NAME --canvas-id CANVAS_ASSET_ID
 ```
 
 写请求失败或返回“未确认事务已隔离”时保留错误上下文，先回读状态，不自动重跑、不删除本地恢复记录。多轨版本冲突需重新查询并基于新状态准备操作；检查点恢复会改变画布，不能作为所有失败的自动回滚方式。
+
+后续任务要把节点用于生视频参考时，先在原空间回读并完成上述核对。绑定缺失、错层或素材未就绪时停止提交，明确指出节点和缺失字段；保留原始错误与 LogID，不反复重试或手改上传状态。`node asset resource not ready` 表示素材预处理未就绪；即使外层显示“服务器繁忙”，也不能据此把重复生成当作恢复方式。