@pippit-dev/cli 1.0.17 → 1.0.20

package/README.md

@@ -205,8 +205,9 @@ python3 skills/xyq-nest-skill/scripts/download_results.py \
 
 ```bash
 npx @pippit-dev/cli@latest install
-export XYQ_ACCESS_KEY="<access-key>"
+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 +215,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`。
@@ -222,6 +225,40 @@ pippit-tool-cli download-result --output-path ./thread_123/results/result.mp4 --
 
 短剧命令的错误日志会追加写入本地每日日志文件：`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`。日志路径会基于当前用户主目录和系统路径分隔符生成，因此可在 macOS、Linux 和 Windows 上使用。
 
+## Canvas 原子命令
+
+CLI 提供个人漫剧画布的通用原子命令，不包含特定来源的导入或转换逻辑：
+
+```bash
+# 首次使用时打开小云雀网页授权
+pippit-tool-cli login
+pippit-tool-cli status
+
+# 创建、分配资产 ID、查询、上传与提交单个画布 transaction
+pippit-tool-cli canvas create --title "CLI Canvas" --wait
+pippit-tool-cli canvas allocate --count 3
+pippit-tool-cli canvas get --asset-id PIPPIT_ASSET_ID
+pippit-tool-cli canvas upload --path ./reference.png
+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 提交生图请求：
@@ -333,4 +370,6 @@ pippit-tool-cli query-result \
 
 ## 鉴权
 
-`short-drama +submit-run`、`get-thread`、`list-thread-file`、`short-drama +upload-file` 以及 `xyq-skill` Python 脚本都使用 `Authorization: Bearer <XYQ_ACCESS_KEY>` 鉴权。OAuth 命令代码仍保留在仓库中，但短剧运行时请求不使用 OAuth。
+原生 CLI 命令通过 `pippit-tool-cli login` 打开小云雀网页授权，并把本机设备专属凭证保存到系统安全凭证库；Access Key 不会显示在终端。可用 `pippit-tool-cli status` 查看状态、`pippit-tool-cli logout` 清除本机登录。
+
+CI 或 Agent 可继续显式设置 `XYQ_ACCESS_KEY`，它会覆盖本机网页登录凭证；配置错误时不会静默回退到个人登录。`skills/xyq-nest-skill/scripts` 下的独立 Python 脚本尚未接入原生 CLI 凭证库，当前仍需要该环境变量。

package/checksums.txt

@@ -1,6 +1,6 @@
-d6750507d8f6aa3c5ca7eccc020eda460d8d6d928de927da9a977696e36dd41d  pippit-tool-cli-1.0.17-darwin-amd64.tar.gz
-1583340a524e123f9458044468c1a2950d36b0eb79f85c19f4801811565caf87  pippit-tool-cli-1.0.17-darwin-arm64.tar.gz
-8a6bc206694a141a860971964b4c7493bfec21539c85b406092be6aae7712269  pippit-tool-cli-1.0.17-linux-amd64.tar.gz
-5e25609c585e4f6e02ae7adc2eb0e4be7d14c35152f23d6113070b3e679617ab  pippit-tool-cli-1.0.17-linux-arm64.tar.gz
-ef883ce5b445bd41774303729fefda216cce17610131f9a34b5f441ad6607cfd  pippit-tool-cli-1.0.17-windows-amd64.zip
-ff47a915c07718b40e6342e35b21091f8db84ea7efd1adc351da274f5a2c6e62  pippit-tool-cli-1.0.17-windows-arm64.zip
+8bbce765a6e25262d7b65c426f74809cb1b56f38e8509c821cff8a5b06d59ba9  pippit-tool-cli-1.0.20-darwin-amd64.tar.gz
+0cc1d8f2cf1197dcc2992f19e593279e9bc4fb1c72f25f220a933288ab7c8877  pippit-tool-cli-1.0.20-darwin-arm64.tar.gz
+38e1fb6590cbe62876625ffbc027099992db1a0cb42099c4b3b64e1cc5aae5b3  pippit-tool-cli-1.0.20-linux-amd64.tar.gz
+d44a96fa3cadd7da7e9e1279cb49659d2d9ab7da12f8695267deeb4fd08b33bc  pippit-tool-cli-1.0.20-linux-arm64.tar.gz
+53d350752fcacb60667f0a1733b9edc0be4e2b77744e042f90726584493fb506  pippit-tool-cli-1.0.20-windows-amd64.zip
+2c04a6f002f3aa0005e6cab4eb18dba5d87bc4f1e158b432bf19c658e4f59b1f  pippit-tool-cli-1.0.20-windows-arm64.zip

package/cmd/auth/auth.go

@@ -1,144 +1,138 @@
 package authcmd
 
-//import (
-//	"fmt"
-//	"io"
-//	"strings"
-//	"time"
-//
-//	"github.com/Pippit-dev/pippit-cli/internal/auth"
-//	"github.com/Pippit-dev/pippit-cli/internal/common"
-//	"github.com/bytedance/sonic"
-//	"github.com/spf13/cobra"
-//)
-//
-//type checkResult struct {
-//	Pending bool `json:"pending"`
-//	State   any  `json:"state,omitempty"`
-//}
-//
-//func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-//	cmd := &cobra.Command{
-//		Use:   "auth",
-//		Short: "Manage Pippit OAuth login state",
-//	}
-//	cmd.SetOut(stdout)
-//	cmd.SetErr(stderr)
-//	cmd.AddCommand(newLoginCommand(stdout, stderr, runner))
-//	cmd.AddCommand(newCheckCommand(stdout, stderr, runner))
-//	cmd.AddCommand(newStatusCommand(stdout, stderr, runner))
-//	cmd.AddCommand(newLogoutCommand(stdout, stderr, runner))
-//	return cmd
-//}
-//
-//func newLoginCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-//	cmd := &cobra.Command{
-//		Use:   "login",
-//		Short: "Start an OAuth device login flow",
-//		Args:  cobra.NoArgs,
-//		RunE: func(cmd *cobra.Command, _ []string) error {
-//			if runner == nil || runner.AuthAuthorizer == nil {
-//				return fmt.Errorf("auth manager is required")
-//			}
-//			flow, err := runner.AuthAuthorizer.NewLoginFlow(cmd.Context())
-//			if err != nil {
-//				return err
-//			}
-//			return writeJSON(stdout, flow)
-//		},
-//	}
-//	cmd.SetOut(stdout)
-//	cmd.SetErr(stderr)
-//	return cmd
-//}
-//
-//func newCheckCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-//	var deviceCode string
-//	cmd := &cobra.Command{
-//		Use:   "check",
-//		Short: "Check whether an OAuth device login has completed",
-//		Args:  cobra.NoArgs,
-//		RunE: func(cmd *cobra.Command, _ []string) error {
-//			deviceCode = strings.TrimSpace(deviceCode)
-//			if deviceCode == "" {
-//				return fmt.Errorf("--device-code is required")
-//			}
-//			if runner == nil || runner.AuthAuthorizer == nil {
-//				return fmt.Errorf("auth manager is required")
-//			}
-//			state, err := runner.AuthAuthorizer.CheckLogin(cmd.Context(), deviceCode)
-//			if auth.IsLoginPending(err) {
-//				return writeJSON(stdout, checkResult{Pending: true})
-//			}
-//			if err != nil {
-//				return err
-//			}
-//			v := map[string]any{
-//				"logged_in":  state.LoggedIn,
-//				"expires_at": state.ExpiresAt.Format(time.RFC3339),
-//			}
-//			return writeJSON(stdout, checkResult{State: v})
-//		},
-//	}
-//	cmd.SetOut(stdout)
-//	cmd.SetErr(stderr)
-//	cmd.Flags().StringVar(&deviceCode, "device-code", "", "device code returned by auth login")
-//	return cmd
-//}
-//
-//func newStatusCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-//	cmd := &cobra.Command{
-//		Use:   "status",
-//		Short: "Show current OAuth login state",
-//		Args:  cobra.NoArgs,
-//		RunE: func(cmd *cobra.Command, _ []string) error {
-//			if runner == nil || runner.AuthAuthorizer == nil {
-//				return fmt.Errorf("auth manager is required")
-//			}
-//			state, err := runner.AuthAuthorizer.State(cmd.Context())
-//			if err != nil {
-//				return err
-//			}
-//			if !state.LoggedIn {
-//				return fmt.Errorf("not logged in")
-//			}
-//			v := map[string]any{
-//				"logged_in":  state.LoggedIn,
-//				"expires_at": state.ExpiresAt.Format(time.RFC3339),
-//			}
-//			return writeJSON(stdout, v)
-//		},
-//	}
-//	cmd.SetOut(stdout)
-//	cmd.SetErr(stderr)
-//	return cmd
-//}
-//
-//func newLogoutCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-//	cmd := &cobra.Command{
-//		Use:   "logout",
-//		Short: "Clear local OAuth login state",
-//		Args:  cobra.NoArgs,
-//		RunE: func(cmd *cobra.Command, _ []string) error {
-//			if runner == nil || runner.AuthAuthorizer == nil {
-//				return fmt.Errorf("auth manager is required")
-//			}
-//			if err := runner.AuthAuthorizer.Logout(cmd.Context()); err != nil {
-//				return err
-//			}
-//			return writeJSON(stdout, map[string]bool{"logged_out": true})
-//		},
-//	}
-//	cmd.SetOut(stdout)
-//	cmd.SetErr(stderr)
-//	return cmd
-//}
-//
-//func writeJSON(w io.Writer, v any) error {
-//	data, err := sonic.Marshal(v)
-//	if err != nil {
-//		return err
-//	}
-//	_, err = fmt.Fprintln(w, string(data))
-//	return err
-//}
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	internal_auth "github.com/Pippit-dev/pippit-cli/internal/auth"
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+type loginResult struct {
+	LoggedIn        bool   `json:"logged_in"`
+	Source          string `json:"source"`
+	UID             string `json:"uid,omitempty"`
+	CredentialScope string `json:"credential_scope,omitempty"`
+	ExpiresAt       string `json:"expires_at,omitempty"`
+}
+
+type logoutResult struct {
+	LoggedOut                 bool `json:"logged_out"`
+	EnvironmentStillActive    bool `json:"environment_still_active,omitempty"`
+	RemoteCredentialPreserved bool `json:"remote_credential_preserved"`
+}
+
+// NewLoginCommand creates the top-level `pippit-tool-cli login` command.
+func NewLoginCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var forceRefresh bool
+	command := &cobra.Command{
+		Use:   "login",
+		Short: "通过浏览器登录小云雀 CLI",
+		Args:  cobra.NoArgs,
+		RunE: func(command *cobra.Command, _ []string) error {
+			manager, err := requireAuthManager(runner)
+			if err != nil {
+				return err
+			}
+			credential, err := manager.Login(command.Context(), internal_auth.LoginOptions{
+				Progress: stderr, ForceRefresh: forceRefresh,
+			})
+			if err != nil {
+				return err
+			}
+			if runner.Config != nil && strings.TrimSpace(runner.Config.AccessKey) != "" {
+				_, _ = fmt.Fprintln(stderr, "提示：当前进程设置了 XYQ_ACCESS_KEY，它会继续优先于刚保存的浏览器登录凭证。")
+			}
+			return writeJSON(stdout, loginResult{
+				LoggedIn:        true,
+				Source:          "browser",
+				UID:             credential.UID,
+				CredentialScope: credential.CredentialScope,
+				ExpiresAt:       time.Unix(credential.ExpiredAt, 0).Format(time.RFC3339),
+			})
+		},
+	}
+	command.SetOut(stdout)
+	command.SetErr(stderr)
+	command.Flags().BoolVar(&forceRefresh, "force", false, "强制轮换当前设备的 CLI Access Key（仅在旧密钥被拒绝时使用）")
+	return command
+}
+
+// NewStatusCommand creates the top-level `pippit-tool-cli status` command.
+func NewStatusCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	command := &cobra.Command{
+		Use:   "status",
+		Short: "查看小云雀 CLI 登录状态",
+		Args:  cobra.NoArgs,
+		RunE: func(command *cobra.Command, _ []string) error {
+			manager, err := requireAuthManager(runner)
+			if err != nil {
+				return err
+			}
+			status, err := manager.Status(command.Context())
+			if err != nil {
+				return err
+			}
+			result := loginResult{LoggedIn: status.LoggedIn, Source: status.Source, UID: status.UID, CredentialScope: status.CredentialScope}
+			if !status.ExpiresAt.IsZero() {
+				result.ExpiresAt = status.ExpiresAt.Format(time.RFC3339)
+			}
+			return writeJSON(stdout, result)
+		},
+	}
+	command.SetOut(stdout)
+	command.SetErr(stderr)
+	return command
+}
+
+// NewLogoutCommand clears only the browser-managed local credential. An
+// explicit XYQ_ACCESS_KEY belongs to the caller's environment and is never
+// modified or revoked by this command.
+func NewLogoutCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	command := &cobra.Command{
+		Use:   "logout",
+		Short: "清除本机小云雀 CLI 登录（不撤销远程 Access Key）",
+		Args:  cobra.NoArgs,
+		RunE: func(command *cobra.Command, _ []string) error {
+			manager, err := requireAuthManager(runner)
+			if err != nil {
+				return err
+			}
+			if err := manager.Logout(command.Context(), false); err != nil && !errors.Is(err, internal_auth.ErrCredentialNotFound) {
+				return err
+			}
+			environmentActive := runner.Config != nil && strings.TrimSpace(runner.Config.AccessKey) != ""
+			if environmentActive {
+				_, _ = fmt.Fprintln(stderr, "提示：XYQ_ACCESS_KEY 仍由当前 shell 提供，CLI 无法替你清除该环境变量。")
+			}
+			_, _ = fmt.Fprintln(stderr, "已清除本机登录密钥；远程 Access Key 未撤销，并保留非秘密设备标识供下次登录安全复用。")
+			return writeJSON(stdout, logoutResult{
+				LoggedOut: true, EnvironmentStillActive: environmentActive, RemoteCredentialPreserved: true,
+			})
+		},
+	}
+	command.SetOut(stdout)
+	command.SetErr(stderr)
+	return command
+}
+
+func requireAuthManager(runner *common.Runner) (common.AuthManager, error) {
+	if runner == nil || runner.Auth == nil {
+		return nil, fmt.Errorf("小云雀 CLI 浏览器授权尚未配置")
+	}
+	return runner.Auth, nil
+}
+
+func writeJSON(writer io.Writer, value any) error {
+	payload, err := json.Marshal(value)
+	if err != nil {
+		return fmt.Errorf("编码登录结果失败: %w", err)
+	}
+	_, err = fmt.Fprintln(writer, string(payload))
+	return err
+}

package/cmd/auth/auth_test.go

@@ -0,0 +1,134 @@
+package authcmd
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+	"time"
+
+	internal_auth "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 fakeAuthManager struct {
+	credential    *internal_auth.Credential
+	status        *internal_auth.Status
+	loginProgress string
+	loginCalls    int
+	loginOptions  []internal_auth.LoginOptions
+	logoutCalls   int
+}
+
+func (manager *fakeAuthManager) ResolveAccessKey(context.Context) (string, error) {
+	if manager.credential == nil {
+		return "", internal_auth.ErrCredentialNotFound
+	}
+	return manager.credential.AccessKey, nil
+}
+
+func (manager *fakeAuthManager) Login(_ context.Context, options internal_auth.LoginOptions) (*internal_auth.Credential, error) {
+	manager.loginCalls++
+	manager.loginOptions = append(manager.loginOptions, options)
+	if options.Progress != nil {
+		message := manager.loginProgress
+		if message == "" {
+			message = "正在完成浏览器授权…\n"
+		}
+		_, _ = options.Progress.Write([]byte(message))
+	}
+	return manager.credential, nil
+}
+
+func TestLoginCommandCanRequestSafeCredentialRotation(t *testing.T) {
+	manager := &fakeAuthManager{credential: &internal_auth.Credential{
+		UID: "123", CredentialScope: "account-device-scope", ExpiredAt: time.Now().Add(time.Hour).Unix(),
+	}}
+	command := NewLoginCommand(io.Discard, io.Discard, &common.Runner{Config: &config.Config{}, Auth: manager})
+	command.SetArgs([]string{"--force"})
+	if err := command.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(manager.loginOptions) != 1 || !manager.loginOptions[0].ForceRefresh {
+		t.Fatalf("login options = %#v, want forced refresh", manager.loginOptions)
+	}
+}
+
+func (manager *fakeAuthManager) Status(context.Context) (*internal_auth.Status, error) {
+	return manager.status, nil
+}
+
+func (manager *fakeAuthManager) Logout(context.Context, bool) error {
+	manager.logoutCalls++
+	return nil
+}
+
+func (manager *fakeAuthManager) CredentialScope(context.Context) (string, error) {
+	return "device-scope", nil
+}
+
+func TestLoginCommandPrintsMetadataWithoutAccessKey(t *testing.T) {
+	const accessKey = "must-never-be-printed"
+	const loginURL = "https://xyq.jianying.com/cli/pippit-tool-login?callback=http%3A%2F%2F127.0.0.1%3A1234&random_secret_key=one-time-secret"
+	expiresAt := time.Now().Add(time.Hour).Unix()
+	manager := &fakeAuthManager{credential: &internal_auth.Credential{
+		AccessKey: accessKey, UID: "123", CredentialScope: "device-scope", ExpiredAt: expiresAt,
+	}, loginProgress: "正在完成浏览器授权…\n授权地址：\n" + loginURL + "\n"}
+	var stdout, stderr bytes.Buffer
+	command := NewLoginCommand(&stdout, &stderr, &common.Runner{Config: &config.Config{}, Auth: manager})
+	command.SetArgs(nil)
+	if err := command.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if manager.loginCalls != 1 || !strings.Contains(stderr.String(), "浏览器授权") {
+		t.Fatalf("login calls/stderr = %d/%q", manager.loginCalls, stderr.String())
+	}
+	if strings.Contains(stdout.String(), accessKey) || strings.Contains(stderr.String(), accessKey) {
+		t.Fatalf("command output leaked Access Key: stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), loginURL) || strings.Contains(stdout.String(), loginURL) {
+		t.Fatalf("login URL stream contract violated: stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+	var result loginResult
+	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	if !result.LoggedIn || result.Source != "browser" || result.UID != "123" || result.CredentialScope != "device-scope" {
+		t.Fatalf("login result = %#v", result)
+	}
+}
+
+func TestStatusAndLogoutDoNotModifyExplicitEnvironmentCredential(t *testing.T) {
+	manager := &fakeAuthManager{status: &internal_auth.Status{LoggedIn: true, Source: "environment"}}
+	runner := &common.Runner{Config: &config.Config{AccessKey: "explicit-ci-key"}, Auth: manager}
+	var statusOut, statusErr bytes.Buffer
+	status := NewStatusCommand(&statusOut, &statusErr, runner)
+	if err := status.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(statusOut.String(), runner.Config.AccessKey) {
+		t.Fatal("status output leaked explicit Access Key")
+	}
+
+	var logoutOut, logoutErr bytes.Buffer
+	logout := NewLogoutCommand(&logoutOut, &logoutErr, runner)
+	if err := logout.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if manager.logoutCalls != 1 || runner.Config.AccessKey != "explicit-ci-key" {
+		t.Fatalf("logout calls/key = %d/%q", manager.logoutCalls, runner.Config.AccessKey)
+	}
+	if !strings.Contains(logoutErr.String(), "无法替你清除") || strings.Contains(logoutErr.String(), runner.Config.AccessKey) {
+		t.Fatalf("logout stderr = %q", logoutErr.String())
+	}
+	var result logoutResult
+	if err := json.Unmarshal(logoutOut.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	if !result.LoggedOut || !result.RemoteCredentialPreserved || !strings.Contains(logoutErr.String(), "远程 Access Key 未撤销") {
+		t.Fatalf("logout result/stderr = %#v/%q", result, logoutErr.String())
+	}
+}