@pippit-dev/cli 1.0.18 → 1.0.21

package/README.md

@@ -9,10 +9,11 @@
 | 技能 | 说明 | 路径 |
 |-------|-------------|------|
 | `xyq-short-drama-skill` | 短剧工作流技能，支持提交创作任务、上传参考文件、查询进度、列出会话文件和下载产物。 | `skills/short-drama/` |
-| `xyq-skill` | 通用创作技能，支持 NestAgent 图片/视频生成与编辑，并在视频模型直出时调用 `pippit-tool-cli generate-video`。 | `skills/xyq-nest-skill/` |
+| `xyq-skill` | 通用创作技能，支持 NestAgent 图片/视频生成与编辑、个人积分余额查询，并在视频模型直出时调用 `pippit-tool-cli generate-video`。 | `skills/xyq-nest-skill/` |
 
 ### 技能路由
 
+- 小云雀积分余额、剩余积分或 credits 查询由 `xyq-skill` 调用 `pippit-tool-cli get-credit-balance`，直接展示个人有效积分余额，无需创建会话或轮询。
 - 通用图片/视频生成、编辑和复杂参考素材编排使用 `xyq-skill`。
 - 用户明确要求视频模型直出、指定视频模型或直接调用 CLI 时，由 `xyq-skill` 调用 `pippit-tool-cli generate-video`，再用 `query-result` 查询和下载结果。
 - 短剧生成、续写、改写、人物设定、分集创作和短剧会话文件处理使用 `xyq-short-drama-skill`，不要与通用创作流程混用。
@@ -29,6 +30,7 @@
 |------|------|
 | 创建会话 / 发送消息 | 向小云雀发送自然语言指令，生成图片或视频。 |
 | 查询会话进展 | 增量拉取会话消息，轮询创作进度和产物结果。 |
+| 积分余额查询 | 调用 `get-credit-balance`，读取 `total_remain_amount` 并展示个人有效积分余额。 |
 | 上传文件 | 上传图片/视频/mp3或wav音频到小云雀资产库，获取 `asset_id` 用于编辑和参考。 |
 | 下载结果 | 批量下载生成的图片/视频到本地，支持并行下载。 |
 | 视频模型直出 | 调用 `generate-video` 提交请求，展示 `web_thread_link`，再用 `query-result` 查询并下载视频。 |
@@ -207,6 +209,7 @@ python3 skills/xyq-nest-skill/scripts/download_results.py \
 npx @pippit-dev/cli@latest install
 pippit-tool-cli login
 pippit-tool-cli --version
+pippit-tool-cli get-credit-balance
 pippit-tool-cli short-drama +submit-run --message "写一个赛博朋克短剧开头"
 pippit-tool-cli short-drama +upload-file --path ./reference.doc
 pippit-tool-cli get-thread --thread-id thread_123 --run-id run_456
@@ -214,6 +217,8 @@ pippit-tool-cli list-thread-file --thread-id thread_123 --page-num 1 --page-size
 pippit-tool-cli download-result --output-path ./thread_123/results/result.mp4 --url URL --updated-at 1779716734
 ```
 
+`get-credit-balance`: 使用当前登录凭证查询个人有效积分余额，并输出 `{"total_remain_amount":"123"}`；零余额会显式输出为 `"0"`。加 `--with-log-id` 可在输出中同时保留本次请求的 `log_id`。
+
 `+submit-run`: 输出 `thread_id`、`run_id` 和 `web_thread_link`；其中 `--message` 为必填参数。
 `get-thread`: 请求中带 `version=v2`，并输出 `readable_text`。
 `list-thread-file`: 输出会话文件列表、分页提示和可直接传给下载命令的 `file_path`。
@@ -241,6 +246,21 @@ pippit-tool-cli canvas apply --project-id PROJECT_ID --file ./patch.json
 
 五个命令均输出单行 JSON，资源 ID 保持字符串。`allocate` 只预留 ID，实际资产仍由后续 `apply` transaction 创建。`create` 的 `request_id` 用于追踪，不是跨服务崩溃窗口的严格幂等键；写请求结果不明确时不要盲目重放，应先使用 `canvas get` 回读确认。`apply` 当前只接受一个 transaction，但该 transaction 可以包含多个 patches；CLI 会严格检查 transaction ACK 和每个目标资产的新版本。
 
+通过 npm 安装的 CLI 还提供基于同一 Canvas SDK 的语义命令目录：
+
+```bash
+# 查看全部公开命令及其参数说明
+pippit-tool-cli canvas command list
+pippit-tool-cli canvas command describe create_biz_node
+
+# 由 SDK 业务工厂创建角色节点；修改会通过现有 canvas apply 原子提交
+pippit-tool-cli canvas command run create_biz_node \
+  --canvas-id PIPPIT_CANVAS_ASSET_ID \
+  --input '{"nodeKind":"role","initialData":{"nodeName":"测试角色"}}'
+```
+
+`canvas command` 由 npm 包内固定的 Canvas SDK 运行时提供，复用网页登录、`canvas get`、`canvas allocate` 和 `canvas apply`；不会读取或打印 Access Key，也不直接选择服务端地址。公开目录只包含已登记的 mutation 和业务命令，不开放任意内部 command 调用。
+
 ## 生图 CLI
 
 `generate-image` 会上传本地参考图片，然后向综合 Nest Agent 提交生图请求：

package/checksums.txt

@@ -1,6 +1,6 @@
-34184e1dab803c7c25acb2ef2b95c0358afe39aaf5423140342b5c12e1e80bb3  pippit-tool-cli-1.0.18-darwin-amd64.tar.gz
-0e66993f2b09950e206ee9e9f36c8a8994f6413fffc6a38ef4808457d66eb218  pippit-tool-cli-1.0.18-darwin-arm64.tar.gz
-24dbe1e620a760d7b43636f881e7716e0beefa32f81e45311983fc6a6fc94acf  pippit-tool-cli-1.0.18-linux-amd64.tar.gz
-1cdb7cbf054ef1203579cd1c8e71035ce0c434cbfaed7dd3f1bc35605bfedd72  pippit-tool-cli-1.0.18-linux-arm64.tar.gz
-9028a53a9ac03967e245f4e1348bdea82f03dcd30dc85a72c30bcf744ff1bd56  pippit-tool-cli-1.0.18-windows-amd64.zip
-6fe7de9b87de3bdd41f7eefb6514e9c48acd079fdc4ff2c5e917b03d01a8ecc0  pippit-tool-cli-1.0.18-windows-arm64.zip
+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

package/cmd/canvas/canvas.go

@@ -118,6 +118,7 @@ func newGetCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comma
 func newApplyCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
 	var filePath string
 	var projectID string
+	var transportResult bool
 	cmd := &cobra.Command{
 		Use:   "apply",
 		Short: "Apply one Canvas patch transaction",
@@ -128,8 +129,9 @@ func newApplyCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Com
 				return err
 			}
 			result, err := canvascore.Apply(cmd.Context(), canvascore.ApplyOptions{
-				ProjectID: projectID,
-				Request:   request,
+				ProjectID:                   projectID,
+				Request:                     request,
+				AllowNonAcknowledgedResults: transportResult,
 			}, runner)
 			if err != nil {
 				logCanvasError("canvas apply", err, map[string]string{
@@ -147,6 +149,10 @@ func newApplyCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Com
 	flags := cmd.Flags()
 	flags.StringVar(&filePath, "file", "-", "BatchPatch JSON request file, or - for stdin")
 	flags.StringVar(&projectID, "project-id", "", "personal novel project ID as a decimal string")
+	flags.BoolVar(&transportResult, "transport-result", false, "return explicit transaction outcomes for transport decoding")
+	if err := flags.MarkHidden("transport-result"); err != nil {
+		panic(err)
+	}
 	return cmd
 }
 

package/cmd/canvas/canvas_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
 )
 
 type commandFakeClient struct {
@@ -124,3 +125,58 @@ func TestApplyRequestRejectsTeamOrImportExtensions(t *testing.T) {
 		}
 	}
 }
+
+func TestApplyTransportResultFlagIsHiddenAndPrintsExplicitReject(t *testing.T) {
+	client := &commandFakeClient{response: `{"ret":"0","log_id":"transport-log","data":{"results":[{"transaction_id":"tx-1","status":"reject","message":"version conflict","current_asset_versions":{"asset-1":9},"server_detail":{"reason":"conflict"}}]}}`}
+	var stdout, stderr bytes.Buffer
+	cmd := NewCommand(&stdout, &stderr, &common.Runner{Client: client})
+	var applyCommand *cobra.Command
+	for _, child := range cmd.Commands() {
+		if child.Name() == "apply" {
+			applyCommand = child
+			break
+		}
+	}
+	if applyCommand == nil {
+		t.Fatal("apply command not found")
+	}
+	flag := applyCommand.Flags().Lookup("transport-result")
+	if flag == nil || !flag.Hidden {
+		t.Fatalf("transport-result flag = %#v, want hidden flag", flag)
+	}
+
+	request := `{"batch_id":"batch-1","client_id":"client-1","transactions":[{"transaction_id":"tx-1","patches":[{"asset_id":"asset-1","op":"replace","path":"","value":{}}]}]}`
+	cmd.SetIn(strings.NewReader(request))
+	cmd.SetArgs([]string{"apply", "--file", "-", "--transport-result"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var output map[string]any
+	if err := json.Unmarshal(bytes.TrimSpace(stdout.Bytes()), &output); err != nil {
+		t.Fatalf("stdout = %q, want JSON: %v", stdout.String(), err)
+	}
+	result := output["results"].([]any)[0].(map[string]any)
+	if result["status"] != "reject" || result["message"] != "version conflict" || result["server_detail"] == nil {
+		t.Fatalf("result = %#v, want complete explicit reject", result)
+	}
+}
+
+func TestApplyTransportResultPrintsRootCreateAckWithoutVersion(t *testing.T) {
+	client := &commandFakeClient{response: `{"ret":"0","data":{"results":[{"transaction_id":"tx-1","status":"ack","server_detail":{"created":true}}]}}`}
+	var stdout, stderr bytes.Buffer
+	cmd := NewCommand(&stdout, &stderr, &common.Runner{Client: client})
+	request := `{"batch_id":"batch-1","client_id":"client-1","transactions":[{"transaction_id":"tx-1","patches":[{"asset_id":"asset-new","op":"add","path":"","value":{}}]}]}`
+	cmd.SetIn(strings.NewReader(request))
+	cmd.SetArgs([]string{"apply", "--file", "-", "--transport-result"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var output map[string]any
+	if err := json.Unmarshal(bytes.TrimSpace(stdout.Bytes()), &output); err != nil {
+		t.Fatalf("stdout = %q, want JSON: %v", stdout.String(), err)
+	}
+	result := output["results"].([]any)[0].(map[string]any)
+	if result["status"] != "ack" || result["asset_versions"] != nil || result["server_detail"] == nil {
+		t.Fatalf("result = %#v, want unchanged root-create ACK", result)
+	}
+}

package/cmd/get_credit_balance.go

@@ -0,0 +1,37 @@
+package cmd
+
+import (
+	"io"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newGetCreditBalanceCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var withLogID bool
+	cmd := &cobra.Command{
+		Use:   "get-credit-balance",
+		Short: "Get the effective credit balance",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("get-credit-balance", nil, func(cmd *cobra.Command, _ []string) error {
+			result, err := common.GetCreditBalance(cmd.Context(), runner)
+			if err != nil {
+				return err
+			}
+			if withLogID {
+				return common.WriteJSON(stdout, struct {
+					TotalRemainAmount int64  `json:"total_remain_amount,string"`
+					LogID             string `json:"log_id"`
+				}{
+					TotalRemainAmount: result.TotalRemainAmount,
+					LogID:             result.LogID,
+				})
+			}
+			return common.WriteJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().BoolVar(&withLogID, "with-log-id", false, "include the request log ID in JSON output")
+	return cmd
+}

package/cmd/get_credit_balance_test.go

@@ -0,0 +1,73 @@
+package cmd
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestGetCreditBalanceCommand(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Fatalf("method = %s, want POST", r.Method)
+		}
+		if r.URL.Path != "/api/biz/v1/skill/get_credit_balance" {
+			t.Fatalf("path = %s, want get_credit_balance path", r.URL.Path)
+		}
+		if r.Header.Get("Authorization") != "Bearer test-token" {
+			t.Fatalf("Authorization = %q, want test bearer token", r.Header.Get("Authorization"))
+		}
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			t.Fatalf("read body: %v", err)
+		}
+		if string(body) != "{}" {
+			t.Fatalf("body = %s, want empty JSON object", body)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"ret":"0","data":{"total_remain_amount":"0"}}`))
+	}))
+	defer server.Close()
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+	root.SetArgs([]string{"get-credit-balance"})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+	if got, want := stdout.String(), "{\"total_remain_amount\":\"0\"}\n"; got != want {
+		t.Fatalf("stdout = %q, want %q", got, want)
+	}
+}
+
+func TestGetCreditBalanceCommandRejectsArguments(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	root.SetArgs([]string{"get-credit-balance", "unexpected"})
+
+	if err := root.Execute(); err == nil {
+		t.Fatal("Execute() error = nil, want argument rejection")
+	}
+}
+
+func TestGetCreditBalanceCommandSupportsLogID(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"ret":"0","log_id":"log_123","data":{"total_remain_amount":"48592"}}`))
+	}))
+	defer server.Close()
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+	root.SetArgs([]string{"get-credit-balance", "--with-log-id"})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+	if got, want := stdout.String(), "{\"total_remain_amount\":\"48592\",\"log_id\":\"log_123\"}\n"; got != want {
+		t.Fatalf("stdout = %q, want %q", got, want)
+	}
+}

package/cmd/root.go

@@ -56,7 +56,7 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root := &cobra.Command{
 		Use:           "pippit-tool-cli",
 		Short:         "Pippit CLI",
-		Long:          "Pippit CLI generates and processes videos and images, submits short-drama workflows, downloads generated assets, and updates the installed CLI package.",
+		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.",
 		Version:       version.Current(),
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -70,6 +70,7 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root.AddCommand(authcmd.NewLogoutCommand(stdout, stderr, runner))
 	root.AddCommand(canvascmd.NewCommand(stdout, stderr, runner))
 	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
+	root.AddCommand(newGetCreditBalanceCommand(stdout, stderr, runner))
 	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))
 	root.AddCommand(newListThreadFileCommand(stdout, stderr, runner))
 	root.AddCommand(generate_image.NewCommand(stdout, stderr, runner))

package/cmd/root_test.go

@@ -48,6 +48,15 @@ func TestRootRegistersCanvas(t *testing.T) {
 	}
 }
 
+func TestRootRegistersGetCreditBalance(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	command, _, err := root.Find([]string{"get-credit-balance"})
+	if err != nil || command == nil || command.Name() != "get-credit-balance" {
+		t.Fatalf("root.Find(%q) = %#v, %v", "get-credit-balance", command, err)
+	}
+}
+
 func TestRootRegistersTopLevelBrowserAuthCommands(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)

package/cmd/short_drama_test.go

@@ -128,6 +128,7 @@ func TestRootHelpListsSupportedCommands(t *testing.T) {
 		"erase-video-subtitle",
 		"generate-video",
 		"download-result",
+		"get-credit-balance",
 		"get-thread",
 		"list-thread-file",
 		"query-result",

package/dist/checksums.txt

@@ -0,0 +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