@pippit-dev/cli 1.0.0 → 1.0.1

package/README.md

@@ -196,15 +196,17 @@ npx @pippit-dev/cli@latest install
 export XYQ_ACCESS_KEY="<access-key>"
 pippit-tool-cli --version
 pippit-tool-cli short-drama +submit-run --message "写一个赛博朋克短剧开头"
-pippit-tool-cli short-drama +upload-file --path ./reference.doc
-pippit-tool-cli short-drama +get-thread --thread-id thread_123 --run-id run_456
-pippit-tool-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL --updated-at 1779716734
+pippit-tool-cli upload-file --path ./reference.doc
+pippit-tool-cli get-thread --thread-id thread_123 --run-id run_456
+pippit-tool-cli list-thread-file --thread-id thread_123 --page-num 1 --page-size 200
+pippit-tool-cli download-result --output-path ./thread_123/results/result.mp4 --url URL --updated-at 1779716734
 ```
 
 `+submit-run`: 输出 `thread_id`、`run_id` 和 `web_thread_link`；其中 `--message` 为必填参数。
-`+get-thread`: 请求中带 `version=v2`，并输出 `readable_text`。
-`+upload-file`: 输出返回的 `asset_id`。 当前仅支持 `.doc`、`.docx` 和 `.txt` 文件。
-`+download-result`: 会把结果 URL 下载到 `--output-path` 指定的文件路径；传入 `--updated-at` 后，如果本地文件早于该时间戳会覆盖更新，否则跳过。
+`get-thread`: 请求中带 `version=v2`，并输出 `readable_text`。
+`list-thread-file`: 输出会话文件列表、分页提示和可直接传给下载命令的 `file_path`。
+`upload-file`: 输出返回的 `asset_id`。 当前仅支持 `.doc`、`.docx` 和 `.txt` 文件。
+`download-result`: 会把结果 URL 下载到 `--output-path` 指定的文件路径；传入 `--updated-at` 后，如果本地文件早于该时间戳会覆盖更新，否则跳过。
 
 短剧命令的错误日志会追加写入本地每日日志文件：`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`。日志路径会基于当前用户主目录和系统路径分隔符生成，因此可在 macOS、Linux 和 Windows 上使用。
 
@@ -214,4 +216,4 @@ pippit-tool-cli short-drama +download-result --output-path ./thread_123/results/
 
 ## 鉴权
 
-`short-drama +submit-run`、`short-drama +get-thread`、`short-drama +upload-file` 以及 `xyq-skill` Python 脚本都使用 `Authorization: Bearer <XYQ_ACCESS_KEY>` 鉴权。OAuth 命令代码仍保留在仓库中，但短剧运行时请求不使用 OAuth。
+`short-drama +submit-run`、`get-thread`、`list-thread-file`、`upload-file` 以及 `xyq-skill` Python 脚本都使用 `Authorization: Bearer <XYQ_ACCESS_KEY>` 鉴权。OAuth 命令代码仍保留在仓库中，但短剧运行时请求不使用 OAuth。

package/checksums.txt

@@ -1,6 +1,6 @@
-91020e43a8e12d7e491b43200a4c1df4dd88a41683e5fe531b3fe038f6573e1a  pippit-tool-cli-1.0.0-darwin-amd64.tar.gz
-a0eea79da53e4f6877aa27c731503c7434d5cb72ab0aa62cd602ac5da0e779f0  pippit-tool-cli-1.0.0-darwin-arm64.tar.gz
-babc1965565d1f2a458990b7bfa8f4b6b93c27ce74afc85d0099e82a14a332e0  pippit-tool-cli-1.0.0-linux-amd64.tar.gz
-0c202f681c1c85c1b4ddd0e5980eb6ef35fa36bc3d6bd4bc840406e5c2661fa8  pippit-tool-cli-1.0.0-linux-arm64.tar.gz
-3d6dae6812bd6fc95a2b6e54b8ef8bc24630d20cfc37417f3f84e787d81de11f  pippit-tool-cli-1.0.0-windows-amd64.zip
-1efdeaacda1dc09008ff0ed0582740ba989fdb766c26edec1ee667202bd565e0  pippit-tool-cli-1.0.0-windows-arm64.zip
+95c7bf8bb745dc6e390a8e71ebf9c464769b29f819e3dd9d77d3539453d320b4  pippit-tool-cli-1.0.1-darwin-amd64.tar.gz
+2163023d193b8886518d9b0481ae6306ddfde01de1f6fb61bbbd40a140b75b67  pippit-tool-cli-1.0.1-darwin-arm64.tar.gz
+15962cc45394ee0b204efb88753929b0842c8ad8d74333fe84ba91fe3f3e1596  pippit-tool-cli-1.0.1-linux-amd64.tar.gz
+dbad696c1c212c6d14ef3e9788597d1751386ab7685111832b3ec8b82964bd57  pippit-tool-cli-1.0.1-linux-arm64.tar.gz
+8c298e5200d83d72ddb6c044d63183aa0104ef2b62fb1b0492d3652bfd103f8a  pippit-tool-cli-1.0.1-windows-amd64.zip
+eebeac5fccccbf63e4949efbf92ae2e3518e34b0758a1379cd0f4cc7328e5997  pippit-tool-cli-1.0.1-windows-arm64.zip

package/cmd/download_result.go

@@ -0,0 +1,57 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newDownloadResultCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var opts common.DownloadResultOptions
+
+	cmd := &cobra.Command{
+		Use:   "download-result",
+		Short: "Download a generated result URL",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("download-result", func() map[string]string {
+			fields := map[string]string{
+				"output_path": opts.OutputPath,
+				"has_url":     strconv.FormatBool(strings.TrimSpace(opts.URL) != ""),
+				"workers":     strconv.Itoa(opts.Workers),
+			}
+			if opts.UpdatedAt > 0 {
+				fields["updated_at"] = strconv.FormatInt(opts.UpdatedAt, 10)
+			}
+			return fields
+		}, func(cmd *cobra.Command, _ []string) error {
+			opts.OutputPath = strings.TrimSpace(opts.OutputPath)
+			if opts.OutputPath == "" {
+				return fmt.Errorf("--output-path is required")
+			}
+			opts.URL = strings.TrimSpace(opts.URL)
+			if opts.URL == "" {
+				return fmt.Errorf("--url is required")
+			}
+			if opts.Workers <= 0 {
+				return fmt.Errorf("--workers must be greater than 0")
+			}
+
+			result, err := common.DownloadResult(cmd.Context(), opts, runner)
+			if err != nil {
+				return err
+			}
+			return writeJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&opts.URL, "url", "", "URL to download")
+	cmd.Flags().StringVar(&opts.OutputPath, "output-path", "", "local output file path")
+	cmd.Flags().Int64Var(&opts.UpdatedAt, "updated-at", 0, "remote file update time as a Unix timestamp")
+	cmd.Flags().IntVar(&opts.Workers, "workers", 5, "parallel download workers")
+	return cmd
+}

package/cmd/get_thread.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newGetThreadCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var opts common.GetThreadOptions
+
+	cmd := &cobra.Command{
+		Use:   "get-thread",
+		Short: "Get a thread detail",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("get-thread", func() map[string]string {
+			return map[string]string{
+				"thread_id": opts.ThreadID,
+				"run_id":    opts.RunID,
+			}
+		}, func(cmd *cobra.Command, _ []string) error {
+			opts.ThreadID = strings.TrimSpace(opts.ThreadID)
+			if opts.ThreadID == "" {
+				return fmt.Errorf("--thread-id is required")
+			}
+			opts.RunID = strings.TrimSpace(opts.RunID)
+
+			result, err := common.GetThread(cmd.Context(), &opts, runner)
+			if err != nil {
+				return err
+			}
+			_, err = fmt.Fprintln(stdout, result.ReadableText)
+			return err
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread ID to fetch")
+	cmd.Flags().StringVar(&opts.RunID, "run-id", "", "run ID to fetch")
+	return cmd
+}
+
+func withErrorLog(command string, fields func() map[string]string, run func(*cobra.Command, []string) error) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		err := run(cmd, args)
+		if err != nil {
+			logFields := map[string]string(nil)
+			if fields != nil {
+				logFields = fields()
+			}
+			_ = common.AppendDailyErrorLog(command, err, logFields)
+		}
+		return err
+	}
+}

package/cmd/json.go

@@ -0,0 +1,17 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/bytedance/sonic"
+)
+
+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
+}

package/cmd/list_thread_file.go

@@ -0,0 +1,51 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newListThreadFileCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var opts common.ListThreadFileOptions
+
+	cmd := &cobra.Command{
+		Use:   "list-thread-file",
+		Short: "List files in a thread",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("list-thread-file", func() map[string]string {
+			return map[string]string{
+				"thread_id": opts.ThreadID,
+				"page_num":  strconv.Itoa(opts.PageNum),
+				"page_size": strconv.Itoa(opts.PageSize),
+			}
+		}, func(cmd *cobra.Command, _ []string) error {
+			opts.ThreadID = strings.TrimSpace(opts.ThreadID)
+			if opts.ThreadID == "" {
+				return fmt.Errorf("--thread-id is required")
+			}
+			if opts.PageSize <= 0 || opts.PageSize > common.MaxListThreadFilePageSize {
+				return fmt.Errorf("--page-size must be between 1 and %d", common.MaxListThreadFilePageSize)
+			}
+			if opts.PageNum <= 0 {
+				return fmt.Errorf("--page-num must be greater than 0")
+			}
+
+			result, err := common.ListThreadFile(cmd.Context(), &opts, runner)
+			if err != nil {
+				return err
+			}
+			return writeJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread ID to list files for")
+	cmd.Flags().IntVar(&opts.PageNum, "page-num", 1, "page number (1-based)")
+	cmd.Flags().IntVar(&opts.PageSize, "page-size", common.MaxListThreadFilePageSize, fmt.Sprintf("number of files per page (between 1 and %d)", common.MaxListThreadFilePageSize))
+	return cmd
+}

package/cmd/root.go

@@ -39,6 +39,10 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root.SetOut(stdout)
 	root.SetErr(stderr)
 	// root.AddCommand(authcmd.NewCommand(stdout, stderr, runner)) // temporarily disabled; auth is via access key injection
+	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
+	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))
+	root.AddCommand(newListThreadFileCommand(stdout, stderr, runner))
+	root.AddCommand(newUploadFileCommand(stdout, stderr, runner))
 	root.AddCommand(short_drama.NewCommand(stdout, stderr, runner))
 	root.AddCommand(updatecmd.NewCommand(stdout, stderr))
 	return root

package/cmd/short_drama/short_drama.go

@@ -3,7 +3,6 @@ package short_drama
 import (
 	"fmt"
 	"io"
-	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -23,10 +22,6 @@ func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command
 	cmd.SetOut(stdout)
 	cmd.SetErr(stderr)
 	cmd.AddCommand(newShortDramaSubmitRunCommand(stdout, stderr, runner))
-	cmd.AddCommand(newShortDramaUploadFileCommand(stdout, stderr, runner))
-	cmd.AddCommand(newShortDramaDownloadResultCommand(stdout, stderr, runner))
-	cmd.AddCommand(newShortDramaGetThreadCommand(stdout, stderr, runner))
-	cmd.AddCommand(newShortDramaListThreadFileCommand(stdout, stderr, runner))
 	return cmd
 }
 
@@ -65,157 +60,6 @@ func newShortDramaSubmitRunCommand(stdout, stderr io.Writer, runner *common.Runn
 	return cmd
 }
 
-func newShortDramaUploadFileCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-	var opts common.UploadFileOptions
-
-	cmd := &cobra.Command{
-		Use:   "+upload-file",
-		Short: "Upload a file for the short drama scene",
-		Args:  cobra.NoArgs,
-		RunE: withErrorLog("short-drama +upload-file", func() map[string]string {
-			return map[string]string{
-				"file_name": fileNameForLog(opts.Path),
-			}
-		}, func(cmd *cobra.Command, _ []string) error {
-			opts.Path = strings.TrimSpace(opts.Path)
-
-			if opts.Path == "" {
-				return fmt.Errorf("--path is required")
-			}
-
-			result, err := common.UploadFile(cmd.Context(), opts, runner)
-			if err != nil {
-				return err
-			}
-			return writeJSON(stdout, result)
-		}),
-	}
-	cmd.SetOut(stdout)
-	cmd.SetErr(stderr)
-	cmd.Flags().StringVar(&opts.Path, "path", "", "local file path to upload")
-	return cmd
-}
-
-func newShortDramaDownloadResultCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-	var opts common.DownloadResultOptions
-
-	cmd := &cobra.Command{
-		Use:   "+download-result",
-		Short: "Download a generated result URL",
-		Args:  cobra.NoArgs,
-		RunE: withErrorLog("short-drama +download-result", func() map[string]string {
-			fields := map[string]string{
-				"output_path": opts.OutputPath,
-				"has_url":     strconv.FormatBool(strings.TrimSpace(opts.URL) != ""),
-				"workers":     strconv.Itoa(opts.Workers),
-			}
-			if opts.UpdatedAt > 0 {
-				fields["updated_at"] = strconv.FormatInt(opts.UpdatedAt, 10)
-			}
-			return fields
-		}, func(cmd *cobra.Command, _ []string) error {
-			opts.OutputPath = strings.TrimSpace(opts.OutputPath)
-			if opts.OutputPath == "" {
-				return fmt.Errorf("--output-path is required")
-			}
-			opts.URL = strings.TrimSpace(opts.URL)
-			if opts.URL == "" {
-				return fmt.Errorf("--url is required")
-			}
-			if opts.Workers <= 0 {
-				return fmt.Errorf("--workers must be greater than 0")
-			}
-
-			result, err := common.DownloadResult(cmd.Context(), opts, runner)
-			if err != nil {
-				return err
-			}
-			return writeJSON(stdout, result)
-		}),
-	}
-	cmd.SetOut(stdout)
-	cmd.SetErr(stderr)
-	cmd.Flags().StringVar(&opts.URL, "url", "", "URL to download")
-	cmd.Flags().StringVar(&opts.OutputPath, "output-path", "", "local output file path")
-	cmd.Flags().Int64Var(&opts.UpdatedAt, "updated-at", 0, "remote file update time as a Unix timestamp")
-	cmd.Flags().IntVar(&opts.Workers, "workers", 5, "parallel download workers")
-	return cmd
-}
-
-func newShortDramaGetThreadCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-	var opts common.GetThreadOptions
-
-	cmd := &cobra.Command{
-		Use:   "+get-thread",
-		Short: "Get a short drama thread detail",
-		Args:  cobra.NoArgs,
-		RunE: withErrorLog("short-drama +get-thread", func() map[string]string {
-			return map[string]string{
-				"thread_id": opts.ThreadID,
-				"run_id":    opts.RunID,
-			}
-		}, func(cmd *cobra.Command, _ []string) error {
-			opts.ThreadID = strings.TrimSpace(opts.ThreadID)
-			if opts.ThreadID == "" {
-				return fmt.Errorf("--thread-id is required")
-			}
-			opts.RunID = strings.TrimSpace(opts.RunID)
-
-			result, err := common.GetThread(cmd.Context(), &opts, runner)
-			if err != nil {
-				return err
-			}
-			_, err = fmt.Fprintln(stdout, result.ReadableText)
-			return err
-		}),
-	}
-	cmd.SetOut(stdout)
-	cmd.SetErr(stderr)
-	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread ID to fetch")
-	cmd.Flags().StringVar(&opts.RunID, "run-id", "", "run ID to fetch")
-	return cmd
-}
-
-func newShortDramaListThreadFileCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
-	var opts common.ListThreadFileOptions
-
-	cmd := &cobra.Command{
-		Use:   "+list-thread-file",
-		Short: "List files in a short drama thread",
-		Args:  cobra.NoArgs,
-		RunE: withErrorLog("short-drama +list-thread-file", func() map[string]string {
-			return map[string]string{
-				"thread_id": opts.ThreadID,
-				"page_num":  strconv.Itoa(opts.PageNum),
-				"page_size": strconv.Itoa(opts.PageSize),
-			}
-		}, func(cmd *cobra.Command, _ []string) error {
-			opts.ThreadID = strings.TrimSpace(opts.ThreadID)
-			if opts.ThreadID == "" {
-				return fmt.Errorf("--thread-id is required")
-			}
-			if opts.PageSize <= 0 || opts.PageSize > common.MaxListThreadFilePageSize {
-				return fmt.Errorf("--page-size must be between 1 and %d", common.MaxListThreadFilePageSize)
-			}
-			if opts.PageNum <= 0 {
-				return fmt.Errorf("--page-num must be greater than 0")
-			}
-
-			result, err := common.ListThreadFile(cmd.Context(), &opts, runner)
-			if err != nil {
-				return err
-			}
-			return writeJSON(stdout, result)
-		}),
-	}
-	cmd.SetOut(stdout)
-	cmd.SetErr(stderr)
-	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread ID to list files for")
-	cmd.Flags().IntVar(&opts.PageNum, "page-num", 1, "page number (1-based)")
-	cmd.Flags().IntVar(&opts.PageSize, "page-size", common.MaxListThreadFilePageSize, fmt.Sprintf("number of files per page (between 1 and %d)", common.MaxListThreadFilePageSize))
-	return cmd
-}
-
 func withErrorLog(command string, fields func() map[string]string, run func(*cobra.Command, []string) error) func(*cobra.Command, []string) error {
 	return func(cmd *cobra.Command, args []string) error {
 		err := run(cmd, args)
@@ -230,14 +74,6 @@ func withErrorLog(command string, fields func() map[string]string, run func(*cob
 	}
 }
 
-func fileNameForLog(path string) string {
-	path = strings.TrimSpace(path)
-	if path == "" {
-		return ""
-	}
-	return filepath.Base(path)
-}
-
 func writeJSON(w io.Writer, v any) error {
 	data, err := sonic.Marshal(v)
 	if err != nil {

package/cmd/short_drama_test.go

@@ -125,7 +125,11 @@ func TestRootHelpListsSupportedCommands(t *testing.T) {
 	got := stdout.String()
 	for _, want := range []string{
 		"Pippit CLI submits short-drama workflows",
+		"download-result",
+		"get-thread",
+		"list-thread-file",
 		"short-drama",
+		"upload-file",
 		"update",
 		"--version",
 	} {
@@ -140,6 +144,29 @@ func TestRootHelpListsSupportedCommands(t *testing.T) {
 	}
 }
 
+func TestShortDramaDoesNotIncludeCommonThreadCommands(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	cmd, _, err := root.Find([]string{"short-drama"})
+	if err != nil {
+		t.Fatalf("Find(short-drama) error = %v", err)
+	}
+	if cmd.CommandPath() != "pippit-tool-cli short-drama" {
+		t.Fatalf("CommandPath() = %q, want short-drama command", cmd.CommandPath())
+	}
+	removedCommands := map[string]bool{
+		"+download-result":  true,
+		"+get-thread":       true,
+		"+list-thread-file": true,
+		"+upload-file":      true,
+	}
+	for _, child := range cmd.Commands() {
+		if removedCommands[child.Name()] {
+			t.Fatalf("short-drama child %s = %#v, want nil", child.Name(), child)
+		}
+	}
+}
+
 func TestVersionFlagPrintsVersion(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
@@ -187,7 +214,7 @@ func TestShortDramaSubmitRunRequiresAccessKey(t *testing.T) {
 	assertAccessKeyGuidance(t, err)
 }
 
-func TestShortDramaUploadFile(t *testing.T) {
+func TestUploadFile(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)
@@ -238,7 +265,7 @@ func TestShortDramaUploadFile(t *testing.T) {
 
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
-	root.SetArgs([]string{"short-drama", "+upload-file", "--path", path})
+	root.SetArgs([]string{"upload-file", "--path", path})
 
 	if err := root.Execute(); err != nil {
 		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
@@ -250,10 +277,10 @@ func TestShortDramaUploadFile(t *testing.T) {
 	}
 }
 
-func TestShortDramaUploadFileRequiresPath(t *testing.T) {
+func TestUploadFileRequiresPath(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+upload-file"})
+	root.SetArgs([]string{"upload-file"})
 
 	err := root.Execute()
 	if err == nil {
@@ -264,7 +291,7 @@ func TestShortDramaUploadFileRequiresPath(t *testing.T) {
 	}
 }
 
-func TestShortDramaUploadFileRequiresAccessKey(t *testing.T) {
+func TestUploadFileRequiresAccessKey(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		t.Fatal("server should not receive request without access key")
 	}))
@@ -278,7 +305,7 @@ func TestShortDramaUploadFileRequiresAccessKey(t *testing.T) {
 
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommandWithAccessKey(t, &stdout, &stderr, server.URL, "")
-	root.SetArgs([]string{"short-drama", "+upload-file", "--path", path})
+	root.SetArgs([]string{"upload-file", "--path", path})
 
 	err := root.Execute()
 	if err == nil {
@@ -287,7 +314,7 @@ func TestShortDramaUploadFileRequiresAccessKey(t *testing.T) {
 	assertAccessKeyGuidance(t, err)
 }
 
-func TestShortDramaUploadFileRejectsUnsupportedFileType(t *testing.T) {
+func TestUploadFileRejectsUnsupportedFileType(t *testing.T) {
 	cwd := chdirTemp(t)
 	path := filepath.Join(cwd, "story.png")
 	if err := os.WriteFile(path, []byte("png-data"), 0o644); err != nil {
@@ -296,7 +323,7 @@ func TestShortDramaUploadFileRejectsUnsupportedFileType(t *testing.T) {
 
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+upload-file", "--path", path})
+	root.SetArgs([]string{"upload-file", "--path", path})
 
 	err := root.Execute()
 	if err == nil {
@@ -307,7 +334,7 @@ func TestShortDramaUploadFileRejectsUnsupportedFileType(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResult(t *testing.T) {
+func TestDownloadResult(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Header.Get("User-Agent") != "Pippit-CLI/1.0" {
 			t.Fatalf("User-Agent = %q, want Pippit-CLI/1.0", r.Header.Get("User-Agent"))
@@ -326,7 +353,7 @@ func TestShortDramaDownloadResult(t *testing.T) {
 	root := NewRootCommand(&stdout, &stderr)
 	outputPath := filepath.Join("results", "cover.jpeg")
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--workers", "2",
 		"--url", server.URL + "/image?filename=ignored.jpeg",
@@ -358,7 +385,7 @@ func TestShortDramaDownloadResult(t *testing.T) {
 	assertFileContent(t, wantFiles[0], "image-data")
 }
 
-func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
+func TestDownloadResultSkipsExistingFile(t *testing.T) {
 	serverCalled := false
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		serverCalled = true
@@ -378,7 +405,7 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--url", server.URL + "/image",
 	})
@@ -404,7 +431,7 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	assertFileContent(t, outputPath, "existing-data")
 }
 
-func TestShortDramaDownloadResultSkipsExistingFileWhenLocalIsFresh(t *testing.T) {
+func TestDownloadResultSkipsExistingFileWhenLocalIsFresh(t *testing.T) {
 	serverCalled := false
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		serverCalled = true
@@ -429,7 +456,7 @@ func TestShortDramaDownloadResultSkipsExistingFileWhenLocalIsFresh(t *testing.T)
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--updated-at", "1779716734",
 		"--url", server.URL + "/image",
@@ -450,7 +477,7 @@ func TestShortDramaDownloadResultSkipsExistingFileWhenLocalIsFresh(t *testing.T)
 	assertFileContent(t, outputPath, "existing-data")
 }
 
-func TestShortDramaDownloadResultOverwritesStaleExistingFile(t *testing.T) {
+func TestDownloadResultOverwritesStaleExistingFile(t *testing.T) {
 	serverCalled := false
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		serverCalled = true
@@ -478,7 +505,7 @@ func TestShortDramaDownloadResultOverwritesStaleExistingFile(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--updated-at", "1779716734",
 		"--url", server.URL + "/image",
@@ -509,7 +536,7 @@ func TestShortDramaDownloadResultOverwritesStaleExistingFile(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultDownloadsMetaJSON(t *testing.T) {
+func TestDownloadResultDownloadsMetaJSON(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/meta.json" {
 			t.Fatalf("path = %s, want meta.json", r.URL.Path)
@@ -524,7 +551,7 @@ func TestShortDramaDownloadResultDownloadsMetaJSON(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--url", server.URL + "/meta.json",
 	})
@@ -547,10 +574,10 @@ func TestShortDramaDownloadResultDownloadsMetaJSON(t *testing.T) {
 	assertFileContent(t, outputPath, `{"ok":true}`)
 }
 
-func TestShortDramaDownloadResultRequiresOutputPath(t *testing.T) {
+func TestDownloadResultRequiresOutputPath(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+download-result", "--url", "https://example.com/image.png"})
+	root.SetArgs([]string{"download-result", "--url", "https://example.com/image.png"})
 
 	err := root.Execute()
 	if err == nil {
@@ -561,11 +588,11 @@ func TestShortDramaDownloadResultRequiresOutputPath(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultRejectsOutputDirFlag(t *testing.T) {
+func TestDownloadResultRejectsOutputDirFlag(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-dir", filepath.Join("results", "image.png"),
 		"--url", "https://example.com/image.png",
 	})
@@ -579,10 +606,10 @@ func TestShortDramaDownloadResultRejectsOutputDirFlag(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultRequiresURL(t *testing.T) {
+func TestDownloadResultRequiresURL(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+download-result", "--output-path", filepath.Join("results", "image.png")})
+	root.SetArgs([]string{"download-result", "--output-path", filepath.Join("results", "image.png")})
 
 	err := root.Execute()
 	if err == nil {
@@ -593,10 +620,10 @@ func TestShortDramaDownloadResultRequiresURL(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultRejectsInvalidScheme(t *testing.T) {
+func TestDownloadResultRejectsInvalidScheme(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+download-result", "--output-path", filepath.Join("results", "image.png"), "--url", "file:///etc/passwd"})
+	root.SetArgs([]string{"download-result", "--output-path", filepath.Join("results", "image.png"), "--url", "file:///etc/passwd"})
 
 	err := root.Execute()
 	if err == nil {
@@ -607,7 +634,7 @@ func TestShortDramaDownloadResultRejectsInvalidScheme(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultAllFailed(t *testing.T) {
+func TestDownloadResultAllFailed(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 	}))
@@ -618,7 +645,7 @@ func TestShortDramaDownloadResultAllFailed(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", filepath.Join("results", "missing.png"),
 		"--url", server.URL + "/notfound",
 	})
@@ -643,7 +670,7 @@ func TestShortDramaDownloadResultAllFailed(t *testing.T) {
 	}
 }
 
-func TestShortDramaDownloadResultOutputPath(t *testing.T) {
+func TestDownloadResultOutputPath(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("image-data"))
 	}))
@@ -655,7 +682,7 @@ func TestShortDramaDownloadResultOutputPath(t *testing.T) {
 	root := NewRootCommand(&stdout, &stderr)
 	outputPath := filepath.Join("custom", "nested", "cover.png")
 	root.SetArgs([]string{
-		"short-drama", "+download-result",
+		"download-result",
 		"--output-path", outputPath,
 		"--url", server.URL + "/image.png",
 	})
@@ -671,7 +698,7 @@ func TestShortDramaDownloadResultOutputPath(t *testing.T) {
 	assertFileContent(t, outputPath, "image-data")
 }
 
-func TestShortDramaGetThread(t *testing.T) {
+func TestGetThread(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)
@@ -709,7 +736,7 @@ func TestShortDramaGetThread(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
 	root.SetArgs([]string{
-		"short-drama", "+get-thread",
+		"get-thread",
 		"--thread-id", "thread_123",
 		"--run-id", "run_456",
 	})
@@ -723,12 +750,12 @@ func TestShortDramaGetThread(t *testing.T) {
 	}
 }
 
-func TestShortDramaGetThreadRequiresThreadID(t *testing.T) {
+func TestGetThreadRequiresThreadID(t *testing.T) {
 	clearDailyErrorLog(t)
 
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+get-thread"})
+	root.SetArgs([]string{"get-thread"})
 
 	err := root.Execute()
 	if err == nil {
@@ -742,7 +769,7 @@ func TestShortDramaGetThreadRequiresThreadID(t *testing.T) {
 	if len(entries) != 1 {
 		t.Fatalf("log entries = %d, want 1: %#v", len(entries), entries)
 	}
-	if entries[0]["command"] != "short-drama +get-thread" {
+	if entries[0]["command"] != "get-thread" {
 		t.Fatalf("command = %v, want get-thread", entries[0]["command"])
 	}
 	if entries[0]["error"] != "--thread-id is required" {
@@ -750,7 +777,7 @@ func TestShortDramaGetThreadRequiresThreadID(t *testing.T) {
 	}
 }
 
-func TestShortDramaGetThreadRequiresAccessKey(t *testing.T) {
+func TestGetThreadRequiresAccessKey(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		t.Fatal("server should not receive request without access key")
 	}))
@@ -758,7 +785,7 @@ func TestShortDramaGetThreadRequiresAccessKey(t *testing.T) {
 
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommandWithAccessKey(t, &stdout, &stderr, server.URL, "")
-	root.SetArgs([]string{"short-drama", "+get-thread", "--thread-id", "thread_123"})
+	root.SetArgs([]string{"get-thread", "--thread-id", "thread_123"})
 
 	err := root.Execute()
 	if err == nil {
@@ -767,7 +794,7 @@ func TestShortDramaGetThreadRequiresAccessKey(t *testing.T) {
 	assertAccessKeyGuidance(t, err)
 }
 
-func TestShortDramaListThreadFile(t *testing.T) {
+func TestListThreadFile(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)
@@ -802,7 +829,7 @@ func TestShortDramaListThreadFile(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
 	root.SetArgs([]string{
-		"short-drama", "+list-thread-file",
+		"list-thread-file",
 		"--thread-id", "thread_123",
 		"--page-num", "2",
 		"--page-size", "10",
@@ -843,7 +870,7 @@ func TestShortDramaListThreadFile(t *testing.T) {
 	}
 }
 
-func TestShortDramaListThreadFileMessageWhenPageFull(t *testing.T) {
+func TestListThreadFileMessageWhenPageFull(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if !strings.Contains(r.URL.Path, "list_thread_file") {
 			t.Fatalf("path = %s, want list_thread_file path", r.URL.Path)
@@ -855,7 +882,7 @@ func TestShortDramaListThreadFileMessageWhenPageFull(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
 	root.SetArgs([]string{
-		"short-drama", "+list-thread-file",
+		"list-thread-file",
 		"--thread-id", "thread_123",
 		"--page-num", "2",
 		"--page-size", "200",
@@ -872,10 +899,10 @@ func TestShortDramaListThreadFileMessageWhenPageFull(t *testing.T) {
 	}
 }
 
-func TestShortDramaListThreadFileRequiresThreadID(t *testing.T) {
+func TestListThreadFileRequiresThreadID(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+list-thread-file"})
+	root.SetArgs([]string{"list-thread-file"})
 
 	err := root.Execute()
 	if err == nil {
@@ -886,7 +913,7 @@ func TestShortDramaListThreadFileRequiresThreadID(t *testing.T) {
 	}
 }
 
-func TestShortDramaListThreadFileRequiresAccessKey(t *testing.T) {
+func TestListThreadFileRequiresAccessKey(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		t.Fatal("server should not receive request without access key")
 	}))
@@ -894,7 +921,7 @@ func TestShortDramaListThreadFileRequiresAccessKey(t *testing.T) {
 
 	var stdout, stderr bytes.Buffer
 	root := newTestRootCommandWithAccessKey(t, &stdout, &stderr, server.URL, "")
-	root.SetArgs([]string{"short-drama", "+list-thread-file", "--thread-id", "thread_123"})
+	root.SetArgs([]string{"list-thread-file", "--thread-id", "thread_123"})
 
 	err := root.Execute()
 	if err == nil {
@@ -903,11 +930,11 @@ func TestShortDramaListThreadFileRequiresAccessKey(t *testing.T) {
 	assertAccessKeyGuidance(t, err)
 }
 
-func TestShortDramaListThreadFileRejectsPageSizeAboveMax(t *testing.T) {
+func TestListThreadFileRejectsPageSizeAboveMax(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
-		"short-drama", "+list-thread-file",
+		"list-thread-file",
 		"--thread-id", "thread_123",
 		"--page-size", "201",
 	})
@@ -942,13 +969,13 @@ func assertAccessKeyGuidance(t *testing.T, err error) {
 		t.Fatal("error = nil, want access key guidance")
 	}
 	msg := err.Error()
-	if !strings.Contains(msg, "XYQ_ACCESS_KEY is required") {
+	if !strings.Contains(msg, "XYQ_ACCESS_KEY") {
 		t.Fatalf("error = %q, want access key guidance", err)
 	}
 	if !strings.Contains(msg, "https://xyq.jianying.com/home?tab_name=home") {
 		t.Fatalf("error = %q, want access key settings URL", err)
 	}
-	if !strings.Contains(msg, `export XYQ_ACCESS_KEY="<access-key>"`) {
+	if !strings.Contains(msg, `export XYQ_ACCESS_KEY="<your-access-key>"`) {
 		t.Fatalf("error = %q, want setup command guidance", err)
 	}
 }

package/cmd/upload_file.go

@@ -0,0 +1,50 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/spf13/cobra"
+)
+
+func newUploadFileCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	var opts common.UploadFileOptions
+
+	cmd := &cobra.Command{
+		Use:   "upload-file",
+		Short: "Upload a file",
+		Args:  cobra.NoArgs,
+		RunE: withErrorLog("upload-file", func() map[string]string {
+			return map[string]string{
+				"file_name": fileNameForLog(opts.Path),
+			}
+		}, func(cmd *cobra.Command, _ []string) error {
+			opts.Path = strings.TrimSpace(opts.Path)
+
+			if opts.Path == "" {
+				return fmt.Errorf("--path is required")
+			}
+
+			result, err := common.UploadFile(cmd.Context(), opts, runner)
+			if err != nil {
+				return err
+			}
+			return writeJSON(stdout, result)
+		}),
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.Flags().StringVar(&opts.Path, "path", "", "local file path to upload")
+	return cmd
+}
+
+func fileNameForLog(path string) string {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return ""
+	}
+	return filepath.Base(path)
+}

package/internal/common/download_results.go

@@ -32,7 +32,7 @@ type DownloadResultError struct {
 	Error string `json:"error"`
 }
 
-// DownloadResultResponse is the JSON envelope printed by `pippit-tool-cli short-drama +download-result`.
+// DownloadResultResponse is the JSON envelope printed by `pippit-tool-cli download-result`.
 type DownloadResultResponse struct {
 	OutputPath   string                 `json:"output_path"`
 	Downloaded   []string               `json:"downloaded"`

package/internal/common/error_log_test.go

@@ -16,7 +16,7 @@ func TestAppendDailyErrorLog(t *testing.T) {
 	t.Setenv("HOME", home)
 	t.Setenv("USERPROFILE", home)
 
-	err := AppendDailyErrorLog("short-drama +get-thread", fmt.Errorf("request failed"), map[string]string{
+	err := AppendDailyErrorLog("get-thread", fmt.Errorf("request failed"), map[string]string{
 		"thread_id":  "thread_123",
 		"access_key": "secret",
 		"empty":      "",
@@ -24,7 +24,7 @@ func TestAppendDailyErrorLog(t *testing.T) {
 	if err != nil {
 		t.Fatalf("AppendDailyErrorLog(): %v", err)
 	}
-	if err := AppendDailyErrorLog("short-drama +get-thread", fmt.Errorf("second failure"), nil); err != nil {
+	if err := AppendDailyErrorLog("get-thread", fmt.Errorf("second failure"), nil); err != nil {
 		t.Fatalf("AppendDailyErrorLog() second call: %v", err)
 	}
 
@@ -42,7 +42,7 @@ func TestAppendDailyErrorLog(t *testing.T) {
 	if err := sonic.Unmarshal([]byte(lines[0]), &first); err != nil {
 		t.Fatalf("decode first log line: %v\n%s", err, lines[0])
 	}
-	if first["command"] != "short-drama +get-thread" {
+	if first["command"] != "get-thread" {
 		t.Fatalf("command = %v, want get-thread command", first["command"])
 	}
 	if first["error"] != "request failed" {

package/internal/common/get_thread.go

@@ -15,7 +15,7 @@ type GetThreadOptions struct {
 	RunID    string `json:"run_id,omitempty"`
 }
 
-// GetThreadResult is the parsed get_thread response used by `pippit-tool-cli short-drama +get-thread`.
+// GetThreadResult is the parsed get_thread response used by `pippit-tool-cli get-thread`.
 type GetThreadResult struct {
 	ReadableText string `json:"readable_text"`
 }

package/internal/common/list_thread_file.go

@@ -25,7 +25,7 @@ type ThreadFile struct {
 	UpdatedAt   *int64 `json:"updated_at,omitempty"`
 }
 
-// ListThreadFileResult is the JSON envelope printed by `pippit-tool-cli short-drama +list-thread-file`.
+// ListThreadFileResult is the JSON envelope printed by `pippit-tool-cli list-thread-file`.
 type ListThreadFileResult struct {
 	Files   []*ThreadFile `json:"files"`
 	Total   int64         `json:"total"`

package/internal/common/upload_file.go

@@ -17,7 +17,7 @@ type UploadFileOptions struct {
 	FileName string `json:"file_name"`
 }
 
-// UploadFileResult is the JSON envelope printed by `pippit-tool-cli short-drama +upload-file`.
+// UploadFileResult is the JSON envelope printed by `pippit-tool-cli upload-file`.
 type UploadFileResult struct {
 	AssetID string `json:"asset_id"`
 }

package/package.json

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

package/skills/short-drama/SKILL.md

@@ -29,7 +29,7 @@ metadata:
 4. **获取会话文件** - 根据 `thread_id` 拉取会话文件列表，得到 `file_path`、`download_url`。这和查询会话进展同等重要。
 5. **下载重要资产** - 使用文件列表中的 `download_url` 下载资源，并按 `file_path` 写入用户本地目标文件路径。
 
-重要资产包括但不限于：剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 `+list-thread-file` 返回了这些资产的 `download_url`，就要及时调用下载工具落盘，不要只展示文件元信息。
+重要资产包括但不限于：剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 `list-thread-file` 返回了这些资产的 `download_url`，就要及时调用下载工具落盘，不要只展示文件元信息。
 
 ## 短剧主流程顺序
 
@@ -94,17 +94,17 @@ pippit-tool-cli short-drama +submit-run --message "参考这个大纲写第一
 
 ```bash
 # 查询会话可读进展
-pippit-tool-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID
+pippit-tool-cli get-thread --thread-id THREAD_ID --run-id RUN_ID
 ```
 
 > `thread_id` 和 `run_id` 由 `+submit-run` 返回。`run_id` 可省略，省略时返回当前 `thread_id` 下的所有 Run；传入时只看指定 Run。
 
 ### 3. 上传文件
 
-当用户提供短剧大纲、人物设定、世界观设定、已有分集或剧本等本地参考文件时，可先上传文件。`+upload-file` 当前只接收本地文件路径，并且只支持 `.doc`、`.docx` 和 `.txt` 后缀；不要把 `.md`、`.pdf`、图片、视频或 URL 传给该命令。
+当用户提供短剧大纲、人物设定、世界观设定、已有分集或剧本等本地参考文件时，可先上传文件。`upload-file` 当前只接收本地文件路径，并且只支持 `.doc`、`.docx` 和 `.txt` 后缀；不要把 `.md`、`.pdf`、图片、视频或 URL 传给该命令。
 
 ```bash
-pippit-tool-cli short-drama +upload-file --path /path/to/outline.txt
+pippit-tool-cli upload-file --path /path/to/outline.txt
 ```
 
 上传成功后命令只返回 `asset_id`：
@@ -121,10 +121,10 @@ pippit-tool-cli short-drama +upload-file --path /path/to/outline.txt
 
 ```bash
 # 获取会话文件列表
-pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200
+pippit-tool-cli list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200
 ```
 
-`+list-thread-file` 返回的每个文件对象包含：
+`list-thread-file` 返回的每个文件对象包含：
 
 ```json
 {
@@ -134,16 +134,16 @@ pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1
 }
 ```
 
-`+list-thread-file` 只负责获取会话文件列表，不负责下载文件，也不需要判断本地文件是否已存在。
+`list-thread-file` 只负责获取会话文件列表，不负责下载文件，也不需要判断本地文件是否已存在。
 
 ### 5. 下载文件资源
 
 ```bash
 # 下载文件资源到指定文件路径
-pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT
+pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT
 ```
 
-`FILE_PATH` 必须直接使用 `+list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`UPDATED_AT` 使用同一文件对象返回的 `updated_at`；如果没有 `updated_at`，可省略 `--updated-at`。`+download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在且本地修改时间不早于 `updated_at`，跳过下载；如果本地文件早于 `updated_at`，覆盖更新。
+`FILE_PATH` 必须直接使用 `list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`UPDATED_AT` 使用同一文件对象返回的 `updated_at`；如果没有 `updated_at`，可省略 `--updated-at`。`download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在且本地修改时间不早于 `updated_at`，跳过下载；如果本地文件早于 `updated_at`，覆盖更新。
 
 ## 典型工作流
 
@@ -154,8 +154,8 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
    → 拿到 thread_id、run_id 和 web_thread_link
 2. 立即将 web_thread_link 展示给用户
 3. 并行发起，二者同等重要：
-   a. pippit-tool-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID
-   b. pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 200
+   a. pippit-tool-cli get-thread --thread-id THREAD_ID --run-id RUN_ID
+   b. pippit-tool-cli list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 200
 4. 检查 `get-thread` 返回的 readable_text：
    - 如果任务仍在进行中：展示可读进展，继续查询
    - 如果后端 Agent 提出问题：从 readable_text 中提取问题并展示，等待用户回复
@@ -163,9 +163,9 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
    - 对每个文件取 file_path、download_url、updated_at
    - 将 file_path 作为本地目标文件路径，包含文件名
    - 有 download_url 的重要资产：加入本轮下载队列
-   - 不判断 file_path 在本地是否已存在，是否跳过由 +download-result 内部处理
+   - 不判断 file_path 在本地是否已存在，是否跳过由 download-result 内部处理
    - 如果本轮 total 达到 200：下一轮将 PAGE_NUM 加 1，继续查询新一页文件
-6. 对重要资产，立即调用 +download-result 并行下载资源：
+6. 对重要资产，立即调用 download-result 并行下载资源：
    - 使用第 5 步获取的 download_url 作为 --url
    - 使用第 5 步获取的完整 file_path 作为 --output-path
    - 如果第 5 步返回 updated_at，作为 --updated-at 传入
@@ -179,7 +179,7 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 
 ```
 1. 检查用户提供的是一个本地 `.doc`、`.docx` 或 `.txt` 剧本文件路径；如果不是，告知当前上传命令只支持这三类文件，不要擅自转换或改写文件。
-2. pippit-tool-cli short-drama +upload-file --path /path/to/file.txt
+2. pippit-tool-cli upload-file --path /path/to/file.txt
    → 拿到 asset_id
 3. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求" --asset-ids asset_id
    → 拿到 thread_id、run_id 和 web_thread_link
@@ -199,23 +199,23 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 ## 轮询策略
 
 - **间隔**：每 10 秒查询一次。
-- **进展查询**：每轮调用 `+get-thread` 查看 `readable_text`。优先带上本轮 `run_id` 聚焦当前任务；需要查看整个会话时可省略 `--run-id`。
-- **并行查询**：每次 `+submit-run` 返回 `thread_id` 后，同时发起 `+get-thread` 和 `+list-thread-file`；二者同等重要，不能只查询会话进展而忽略会话文件。
-- **文件分页**：`+list-thread-file` 使用 `--page-size 200`。如果本轮返回的 `total` 达到 200，下一轮使用 `--page-num` 加 1 查询新一页结果；如果未达到 200，保持当前页继续轮询新增产物。
-- **重要资产识别**：每轮都检查 `+list-thread-file` 返回的文件。剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物都是重要资产。
-- **文件下载**：解析 `+list-thread-file` 的结果后，对带 `download_url` 的重要资产立即调用 `+download-result` 下载资源；不要在 `list-thread-file` 阶段检查文件是否已存在，存在性检查由下载工具内部处理。
+- **进展查询**：每轮调用 `get-thread` 查看 `readable_text`。优先带上本轮 `run_id` 聚焦当前任务；需要查看整个会话时可省略 `--run-id`。
+- **并行查询**：每次 `+submit-run` 返回 `thread_id` 后，同时发起 `get-thread` 和 `list-thread-file`；二者同等重要，不能只查询会话进展而忽略会话文件。
+- **文件分页**：`list-thread-file` 使用 `--page-size 200`。如果本轮返回的 `total` 达到 200，下一轮使用 `--page-num` 加 1 查询新一页结果；如果未达到 200，保持当前页继续轮询新增产物。
+- **重要资产识别**：每轮都检查 `list-thread-file` 返回的文件。剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物都是重要资产。
+- **文件下载**：解析 `list-thread-file` 的结果后，对带 `download_url` 的重要资产立即调用 `download-result` 下载资源；不要在 `list-thread-file` 阶段检查文件是否已存在，存在性检查由下载工具内部处理。
 - **下载完成标准**：不要把文件元信息展示当成下载完成；必须拿到本地 `file_path`，或明确记录该文件在重试后仍下载失败。
 - **用户确认**：如果消息中出现需要用户确认、补充设定或回答问题的内容，先判断是否包含表单、问卷、选项或按钮；包含时按“短剧主流程顺序”和“表单与问卷选项处理原则”清洗选项，再展示给用户并等待回复。
 - **超时**：如果长时间无结果，告知用户任务仍在生成中，可稍后通过 `web_thread_link` 查看。
-- **错误处理**：`+get-thread`、`+list-thread-file` 或 `+download-result` 任一调用失败时，记录失败原因和参数，在后续轮询中主动重试；重试期间继续处理其他成功返回的消息和文件。连续多轮失败后再向用户说明仍未完成的查询或下载项。
+- **错误处理**：`get-thread`、`list-thread-file` 或 `download-result` 任一调用失败时，记录失败原因和参数，在后续轮询中主动重试；重试期间继续处理其他成功返回的消息和文件。连续多轮失败后再向用户说明仍未完成的查询或下载项。
 
 ## 完成标准
 
-一次短剧任务不能只以 `+get-thread` 返回的 `readable_text` 作为结束条件。完成前必须同时检查：
+一次短剧任务不能只以 `get-thread` 返回的 `readable_text` 作为结束条件。完成前必须同时检查：
 
-1. 已处理 `+get-thread` 返回的最新 `readable_text`、用户确认问题和最终消息。
-2. 已用 `--page-size 200` 调用 `+list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 200，已在后续轮询中递增 `page-num` 查询新一页。
-3. 对所有带 `download_url` 的重要资产，已调用 `+download-result` 下载到本地 `file_path`。
+1. 已处理 `get-thread` 返回的最新 `readable_text`、用户确认问题和最终消息。
+2. 已用 `--page-size 200` 调用 `list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 200，已在后续轮询中递增 `page-num` 查询新一页。
+3. 对所有带 `download_url` 的重要资产，已调用 `download-result` 下载到本地 `file_path`。
 4. 已按短剧主流程顺序检查服务端表单、问卷和选项，没有把跳过必要阶段的选项直接呈现给用户；如果跳过 `剧本标准化`，已明确这是可选阶段。
 5. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
 
@@ -231,7 +231,7 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 }
 ```
 
-**+get-thread** 返回：
+**get-thread** 返回：
 
 ```text
 Thread: thread_...
@@ -242,7 +242,7 @@ Thread: thread_...
        [assistant] ...
 ```
 
-**+upload-file** 返回：
+**upload-file** 返回：
 
 ```json
 {
@@ -250,9 +250,9 @@ Thread: thread_...
 }
 ```
 
-`+upload-file` 通过 `multipart/form-data` 上传文件，表单文件字段名为 `file`。本地文件必须存在、不能是目录，后缀必须是 `.doc`、`.docx` 或 `.txt`；不支持的后缀会直接报错。返回的 `asset_id` 来自服务端 `pippit_asset_id`，如果没有该字段才回退到 `asset_id`。
+`upload-file` 通过 `multipart/form-data` 上传文件，表单文件字段名为 `file`。本地文件必须存在、不能是目录，后缀必须是 `.doc`、`.docx` 或 `.txt`；不支持的后缀会直接报错。返回的 `asset_id` 来自服务端 `pippit_asset_id`，如果没有该字段才回退到 `asset_id`。
 
-**+list-thread-file** 返回：
+**list-thread-file** 返回：
 
 ```json
 {
@@ -270,7 +270,7 @@ Thread: thread_...
 
 当 `total` 达到 200 时，`message` 会用 `<system-remind>` 提示下一轮将 `page-num` 加 1 查询新一页。
 
-**+download-result** 返回：
+**download-result** 返回：
 
 ```json
 {
@@ -281,16 +281,16 @@ Thread: thread_...
 
 ## 会话文件与资源下载
 
-先用 `+list-thread-file` 获取会话文件列表，再用 `+download-result` 并行下载重要资产。获取文件元信息不是最终目标，重要资产落盘才是核心目标。文件是否已存在由下载工具内部检查，`+list-thread-file` 阶段不要做本地存在性判断。
+先用 `list-thread-file` 获取会话文件列表，再用 `download-result` 并行下载重要资产。获取文件元信息不是最终目标，重要资产落盘才是核心目标。文件是否已存在由下载工具内部检查，`list-thread-file` 阶段不要做本地存在性判断。
 
 ### 获取会话文件
 
-从 `+list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`file_name`、`download_url`、`updated_at`。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。
+从 `list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`file_name`、`download_url`、`updated_at`。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。
 
 ```
 1. 有download_url的重要资产
    → 记录该file_path、URL和updated_at
-   → 使用 +download-result 将URL资源下载到该file_path；有updated_at时传入--updated-at
+   → 使用 download-result 将URL资源下载到该file_path；有updated_at时传入--updated-at
 2. 本轮total达到200
    → 下一轮page-num加1，继续查询新一页结果
 3. 本轮total未达到200
@@ -304,7 +304,7 @@ Thread: thread_...
 
 对带 `download_url` 的重要资产调用下载工具，可并行。重要资产必须主动下载，不要等用户再次要求，也不要在调用下载工具前先检查本地文件是否存在。
 
-1. 调用 `pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT`；如果文件对象没有 `updated_at`，省略 `--updated-at`。
+1. 调用 `pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT`；如果文件对象没有 `updated_at`，省略 `--updated-at`。
 2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，记录失败项并在后续轮询中重试，不阻塞已成功落盘的文件展示。
 
 ## 向用户展示内容
@@ -323,9 +323,9 @@ Thread: thread_...
 
 你要做的只有三件事：
 
-1. **上传**：如果用户给了本地 `.doc` / `.docx` / `.txt` 参考文件，先调用 `+upload-file`。
+1. **上传**：如果用户给了本地 `.doc` / `.docx` / `.txt` 参考文件，先调用 `upload-file`。
 2. **提交任务**：首次创作时把用户原始短剧需求和唯一剧本 `asset_id` 通过 `+submit-run --asset-ids` 发给后端；同一 `thread_id` 后续续写或修改不再追加新的剧本文件。
-3. **传话、取文件、下载资源**：根据 `+get-thread` 返回的 `readable_text` 展示进展、问题和结果；遇到表单、问卷、选项或按钮时，只做流程合理性清洗，不替用户决定创作内容；根据 `+list-thread-file` 获取文件列表；再根据 `download_url` 调用 `+download-result` 把缺失资源下载到用户本地。
+3. **传话、取文件、下载资源**：根据 `get-thread` 返回的 `readable_text` 展示进展、问题和结果；遇到表单、问卷、选项或按钮时，只做流程合理性清洗，不替用户决定创作内容；根据 `list-thread-file` 获取文件列表；再根据 `download_url` 调用 `download-result` 把缺失资源下载到用户本地。
 
 **不要做的事：**
 
@@ -340,10 +340,10 @@ Thread: thread_...
 
 - `--message` 是用户的原始短剧需求，不能为空。
 - 查询进展时优先使用 `+submit-run` 返回的 `thread_id` 和 `run_id`；如果需要查看整个会话，可以省略 `--run-id`。
-- `+get-thread` 当前固定走服务端 v2 响应，输出字段是 `readable_text`；不要解析旧版 `messages` 数组。
-- `+upload-file` 当前用于短剧场景文件上传链路，只支持本地 `.doc` / `.docx` / `.txt` 文件；`--path` 不能为空，路径必须指向真实文件，不能是目录。
-- `+upload-file` 上传成功后只返回 `asset_id`；把该值原样作为 `+submit-run --asset-ids` 的参数。
+- `get-thread` 当前固定走服务端 v2 响应，输出字段是 `readable_text`；不要解析旧版 `messages` 数组。
+- `upload-file` 当前用于短剧场景文件上传链路，只支持本地 `.doc` / `.docx` / `.txt` 文件；`--path` 不能为空，路径必须指向真实文件，不能是目录。
+- `upload-file` 上传成功后只返回 `asset_id`；把该值原样作为 `+submit-run --asset-ids` 的参数。
 - 单次创作会话中（相同 `thread_id`），`+submit-run` 只支持绑定一个剧本文件。不要在同一 `thread_id` 下重复上传并追加第二个剧本 `asset_id`；用户给多个剧本时，先让用户选择一个，或分别开启新的创作会话。
-- `+list-thread-file` 只需要 `thread_id`；分页参数使用 `--page-num 1 --page-size 200` 起步，`total` 达到 200 时下一轮递增 `page-num`。
-- `+list-thread-file` 和 `+download-result` 是两个不同的 CLI 指令：前者获取会话文件元信息，后者下载 URL 资源并写入到本地目标文件路径。
-- `+download-result` 接收 `--url`、`--output-path`、`--updated-at`、`--workers`；`--output-path` 必须是包含文件名的目标文件路径。
+- `list-thread-file` 只需要 `thread_id`；分页参数使用 `--page-num 1 --page-size 200` 起步，`total` 达到 200 时下一轮递增 `page-num`。
+- `list-thread-file` 和 `download-result` 是两个不同的 CLI 指令：前者获取会话文件元信息，后者下载 URL 资源并写入到本地目标文件路径。
+- `download-result` 接收 `--url`、`--output-path`、`--updated-at`、`--workers`；`--output-path` 必须是包含文件名的目标文件路径。