@pippit-dev/cli 1.0.21 → 1.0.22

package/README.md

@@ -249,9 +249,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 +273,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
+0ff3b8e87e45b5c39546b74588f7c45ffe5d463cc3618807855f498ed8bfa733  pippit-tool-cli-1.0.22-darwin-amd64.tar.gz
+1deea5a6c69b88146319eeca111cb121ffa24d28253a5d043b2985846ebeb602  pippit-tool-cli-1.0.22-darwin-arm64.tar.gz
+823e08be7d8a2a36176b95dc01a1b12d2dd50edb80901467629507a9ac5ff245  pippit-tool-cli-1.0.22-linux-amd64.tar.gz
+c286697382d43023657bca553c2ad5e34181e95329c4c702323eef00f6d8b279  pippit-tool-cli-1.0.22-linux-arm64.tar.gz
+ec53eae18219ce6456eebc43ba607f646c323b7e7f852d99d7e596e04fbd5591  pippit-tool-cli-1.0.22-windows-amd64.zip
+a913cc47ef12eaa71ffb7de4d4e58286351491fa3109d87fa62fe84001dcc1a4  pippit-tool-cli-1.0.22-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 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,

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/dist/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
+0ff3b8e87e45b5c39546b74588f7c45ffe5d463cc3618807855f498ed8bfa733  pippit-tool-cli-1.0.22-darwin-amd64.tar.gz
+1deea5a6c69b88146319eeca111cb121ffa24d28253a5d043b2985846ebeb602  pippit-tool-cli-1.0.22-darwin-arm64.tar.gz
+823e08be7d8a2a36176b95dc01a1b12d2dd50edb80901467629507a9ac5ff245  pippit-tool-cli-1.0.22-linux-amd64.tar.gz
+c286697382d43023657bca553c2ad5e34181e95329c4c702323eef00f6d8b279  pippit-tool-cli-1.0.22-linux-arm64.tar.gz
+ec53eae18219ce6456eebc43ba607f646c323b7e7f852d99d7e596e04fbd5591  pippit-tool-cli-1.0.22-windows-amd64.zip
+a913cc47ef12eaa71ffb7de4d4e58286351491fa3109d87fa62fe84001dcc1a4  pippit-tool-cli-1.0.22-windows-arm64.zip