@pippit-dev/cli 1.0.0 → 1.0.2

package/internal/common/client.go

@@ -20,6 +20,7 @@ import (
 
 type Client interface {
 	SendRequest(ctx context.Context, path string, body any, out any) error
+	SendRequestWithHeaders(ctx context.Context, path string, body any, headers map[string]string, out any) error
 	SendMultipartRequest(ctx context.Context, path string, fields map[string]string, file MultipartFile, out any) error
 }
 
@@ -53,6 +54,10 @@ func NewHTTPClient(baseURL string, timeout time.Duration, authorizer RequestAuth
 }
 
 func (c *httpClient) SendRequest(ctx context.Context, path string, body any, out any) error {
+	return c.SendRequestWithHeaders(ctx, path, body, nil, out)
+}
+
+func (c *httpClient) SendRequestWithHeaders(ctx context.Context, path string, body any, headers map[string]string, out any) error {
 	method := http.MethodPost
 	if body == nil {
 		method = http.MethodGet
@@ -67,27 +72,27 @@ func (c *httpClient) SendRequest(ctx context.Context, path string, body any, out
 	if body != nil {
 		payload, err := sonic.Marshal(body)
 		if err != nil {
-			return fmt.Errorf("encode body: %w", err)
+			return fmt.Errorf("编码请求体失败: %w", err)
 		}
 		reader = bytes.NewReader(payload)
 	}
 
 	req, err := http.NewRequestWithContext(ctx, method, reqURL, reader)
 	if err != nil {
-		return fmt.Errorf("build %s request: %w", method, err)
+		return fmt.Errorf("构造 %s 请求失败: %w", method, err)
 	}
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
 	}
 
 	if c.authorizer == nil {
-		return fmt.Errorf("authorized request requires authorizer")
+		return fmt.Errorf("授权请求缺少认证器")
 	}
 	if err := c.authorizer.Inject(ctx, req); err != nil {
-		return fmt.Errorf("inject auth headers: %w", err)
+		return fmt.Errorf("写入认证请求头失败: %w", err)
 	}
 
-	c.injectHeaders(req)
+	c.injectHeaders(req, headers)
 
 	// If out is **http.Response, return the raw response for streaming (e.g. file download).
 	if out != nil {
@@ -95,11 +100,11 @@ func (c *httpClient) SendRequest(ctx context.Context, path string, body any, out
 			if rv.Elem().Type().Elem() == reflect.TypeOf(http.Response{}) {
 				resp, err := c.httpClient.Do(req)
 				if err != nil {
-					return fmt.Errorf("%s %s failed: %w", method, reqURL, err)
+					return fmt.Errorf("%s %s 请求失败: %w", method, reqURL, err)
 				}
 				if resp.StatusCode >= 400 {
 					defer resp.Body.Close()
-					return fmt.Errorf("%s %s returned HTTP %d", method, reqURL, resp.StatusCode)
+					return fmt.Errorf("%s %s 返回 HTTP %d", method, reqURL, resp.StatusCode)
 				}
 				rv.Elem().Set(reflect.ValueOf(resp))
 				return nil
@@ -118,7 +123,7 @@ func (c *httpClient) SendMultipartRequest(ctx context.Context, path string, fiel
 		return err
 	}
 	if file.FieldName == "" {
-		return fmt.Errorf("multipart file field name is required")
+		return fmt.Errorf("multipart 文件字段名不能为空")
 	}
 	if file.FileName == "" {
 		file.FileName = filepath.Base(file.Path)
@@ -133,7 +138,7 @@ func (c *httpClient) SendMultipartRequest(ctx context.Context, path string, fiel
 	if err != nil {
 		_ = pr.Close()
 		_ = pw.Close()
-		return fmt.Errorf("build POST request: %w", err)
+		return fmt.Errorf("构造 POST 请求失败: %w", err)
 	}
 	req.Header.Set("Content-Type", writer.FormDataContentType())
 	req.Header.Set("Accept", "application/json")
@@ -141,14 +146,14 @@ func (c *httpClient) SendMultipartRequest(ctx context.Context, path string, fiel
 	if c.authorizer == nil {
 		_ = pr.Close()
 		_ = pw.Close()
-		return fmt.Errorf("authorized request requires authorizer")
+		return fmt.Errorf("授权请求缺少认证器")
 	}
 	if err := c.authorizer.Inject(ctx, req); err != nil {
 		_ = pr.Close()
 		_ = pw.Close()
-		return fmt.Errorf("inject auth headers: %w", err)
+		return fmt.Errorf("写入认证请求头失败: %w", err)
 	}
-	c.injectHeaders(req)
+	c.injectHeaders(req, nil)
 
 	go func() {
 		err := writeMultipartBody(writer, fields, file)
@@ -172,7 +177,7 @@ func writeMultipartBody(writer *multipart.Writer, fields map[string]string, file
 
 	f, err := os.Open(file.Path)
 	if err != nil {
-		return fmt.Errorf("open upload file: %w", err)
+		return fmt.Errorf("打开上传文件失败: %w", err)
 	}
 	defer f.Close()
 
@@ -184,7 +189,7 @@ func writeMultipartBody(writer *multipart.Writer, fields map[string]string, file
 		return err
 	}
 	if _, err := io.Copy(part, f); err != nil {
-		return fmt.Errorf("write upload file: %w", err)
+		return fmt.Errorf("写入上传文件失败: %w", err)
 	}
 	return nil
 }
@@ -195,38 +200,41 @@ func escapeQuotes(s string) string {
 	return quotesReplacer.Replace(s)
 }
 
-func (c *httpClient) injectHeaders(req *http.Request) {
+func (c *httpClient) injectHeaders(req *http.Request, headers map[string]string) {
 	for k, values := range c.headers {
 		for _, v := range values {
 			req.Header.Add(k, v)
 		}
 	}
 	req.Header.Set("User-Agent", "Pippit-CLI/1.0")
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
 }
 
 func (c *httpClient) do(req *http.Request, out any) error {
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
-		return fmt.Errorf("%s %s failed: %w", req.Method, req.URL.String(), err)
+		return fmt.Errorf("%s %s 请求失败: %w", req.Method, req.URL.String(), err)
 	}
 	defer resp.Body.Close()
 
 	data, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return fmt.Errorf("read response body: %w", err)
+		return fmt.Errorf("读取响应体失败: %w", err)
 	}
 	if resp.StatusCode >= 400 {
 		msg := strings.TrimSpace(string(data))
 		if msg == "" {
 			msg = http.StatusText(resp.StatusCode)
 		}
-		return fmt.Errorf("%s %s returned HTTP %d: %s", req.Method, req.URL.String(), resp.StatusCode, msg)
+		return fmt.Errorf("%s %s 返回 HTTP %d: %s", req.Method, req.URL.String(), resp.StatusCode, msg)
 	}
 	if out == nil || len(data) == 0 {
 		return nil
 	}
 	if err := sonic.Unmarshal(data, out); err != nil {
-		return fmt.Errorf("decode response body: %w", err)
+		return fmt.Errorf("解析响应体失败: %w", err)
 	}
 	return nil
 }
@@ -236,7 +244,7 @@ func (c *httpClient) resolveURL(path string, query map[string]string) (string, e
 		return appendQuery(path, query)
 	}
 	if c.baseURL == "" {
-		return "", fmt.Errorf("base URL is required for relative path %q", path)
+		return "", fmt.Errorf("相对路径 %q 需要配置 base URL", path)
 	}
 	if !strings.HasPrefix(path, "/") {
 		path = "/" + path
@@ -247,7 +255,7 @@ func (c *httpClient) resolveURL(path string, query map[string]string) (string, e
 func appendQuery(raw string, query map[string]string) (string, error) {
 	u, err := url.Parse(raw)
 	if err != nil {
-		return "", fmt.Errorf("parse URL: %w", err)
+		return "", fmt.Errorf("解析 URL 失败: %w", err)
 	}
 	values := u.Query()
 	for k, v := range query {

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"`
@@ -58,20 +58,26 @@ type downloadTaskResult struct {
 
 func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Runner) (*DownloadResultResponse, error) {
 	if err := ctx.Err(); err != nil {
-		return nil, err
+		if errors.Is(err, context.Canceled) {
+			return nil, fmt.Errorf("下载已取消")
+		}
+		if errors.Is(err, context.DeadlineExceeded) {
+			return nil, fmt.Errorf("下载超时")
+		}
+		return nil, fmt.Errorf("下载上下文异常: %w", err)
 	}
 	rawURL := strings.TrimSpace(opts.URL)
 	if rawURL == "" {
-		return nil, fmt.Errorf("download url is required")
+		return nil, fmt.Errorf("下载 URL 不能为空")
 	}
 
 	outputPath := strings.TrimSpace(opts.OutputPath)
 	if outputPath == "" {
-		return nil, fmt.Errorf("output_path is required")
+		return nil, fmt.Errorf("输出路径不能为空")
 	}
 	if info, err := os.Stat(outputPath); err == nil {
 		if info.IsDir() {
-			return nil, fmt.Errorf("output path %q is a directory", outputPath)
+			return nil, fmt.Errorf("输出路径 %q 是目录，请指定文件", outputPath)
 		}
 		if shouldSkipExistingFile(info, opts.UpdatedAt) {
 			return &DownloadResultResponse{
@@ -80,19 +86,19 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 			}, nil
 		}
 	} else if !os.IsNotExist(err) {
-		return nil, fmt.Errorf("stat output path: %w", err)
+		return nil, fmt.Errorf("获取输出路径信息失败: %w", err)
 	}
 	outputDir := filepath.Dir(outputPath)
 	if err := os.MkdirAll(outputDir, 0o755); err != nil {
-		return nil, fmt.Errorf("create output dir: %w", err)
+		return nil, fmt.Errorf("创建输出目录失败: %w", err)
 	}
 
 	parsed, err := url.Parse(rawURL)
 	if err != nil {
-		return nil, fmt.Errorf("invalid url %q: %w", rawURL, err)
+		return nil, fmt.Errorf("URL %q 不合法: %w", rawURL, err)
 	}
 	if parsed.Scheme != "http" && parsed.Scheme != "https" {
-		return nil, fmt.Errorf("invalid url scheme %q in %q, only http and https are allowed", parsed.Scheme, rawURL)
+		return nil, fmt.Errorf("URL %q 的协议 %q 不支持，仅支持 http 和 https", rawURL, parsed.Scheme)
 	}
 	tasks := []downloadTask{
 		{
@@ -166,7 +172,7 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 		Errors:     errorList,
 	}
 	if len(downloaded) == 0 && len(errorList) > 0 {
-		return result, fmt.Errorf("all %d download(s) failed", len(errorList))
+		return result, fmt.Errorf("全部 %d 个下载任务失败", len(errorList))
 	}
 	return result, nil
 }
@@ -200,7 +206,7 @@ func downloadFileWithRetry(ctx context.Context, client Client, rawURL string, ta
 			return err
 		}
 	}
-	return fmt.Errorf("failed after %d retries: %w", maxDownloadRetries, lastErr)
+	return fmt.Errorf("重试 %d 次后仍失败: %w", maxDownloadRetries, lastErr)
 }
 
 func isRetryableError(err error) bool {
@@ -230,18 +236,18 @@ func downloadFile(ctx context.Context, client Client, rawURL string, targetPath
 	}()
 	out, err := os.Create(tmpPath)
 	if err != nil {
-		return fmt.Errorf("create temp file: %w", err)
+		return fmt.Errorf("创建临时文件失败: %w", err)
 	}
 	_, copyErr := io.Copy(out, resp.Body)
 	closeErr := out.Close()
 	if copyErr != nil {
-		return fmt.Errorf("write temp file: %w", copyErr)
+		return fmt.Errorf("写入临时文件失败: %w", copyErr)
 	}
 	if closeErr != nil {
-		return fmt.Errorf("close temp file: %w", closeErr)
+		return fmt.Errorf("关闭临时文件失败: %w", closeErr)
 	}
 	if err := os.Rename(tmpPath, targetPath); err != nil {
-		return fmt.Errorf("replace target file: %w", err)
+		return fmt.Errorf("替换目标文件失败: %w", err)
 	}
 	tempActive = false
 	if updatedAt > 0 {

package/internal/common/error_log.go

@@ -1,6 +1,8 @@
 package common
 
 import (
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -21,6 +23,42 @@ type errorLogEntry struct {
 	Error   string            `json:"error"`
 }
 
+type logIDCarrier interface {
+	LogID() string
+}
+
+type LogIDError struct {
+	Message string
+	ID      string
+}
+
+func NewLogIDError(message string, logID string) error {
+	return &LogIDError{
+		Message: strings.TrimSpace(message),
+		ID:      strings.TrimSpace(logID),
+	}
+}
+
+func (e *LogIDError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.ID == "" {
+		return e.Message
+	}
+	if e.Message == "" {
+		return fmt.Sprintf("log_id=%s", e.ID)
+	}
+	return fmt.Sprintf("%s log_id=%s", e.Message, e.ID)
+}
+
+func (e *LogIDError) LogID() string {
+	if e == nil {
+		return ""
+	}
+	return strings.TrimSpace(e.ID)
+}
+
 // AppendDailyErrorLog appends one CLI error record to ~/.pippit_tool_cli/logs/yyyy-mm-dd.log.
 func AppendDailyErrorLog(command string, err error, fields map[string]string) error {
 	if err == nil {
@@ -38,7 +76,7 @@ func AppendDailyErrorLog(command string, err error, fields map[string]string) er
 	entry := errorLogEntry{
 		Time:    now.Format(time.RFC3339),
 		Command: strings.TrimSpace(command),
-		Fields:  cleanErrorLogFields(fields),
+		Fields:  cleanErrorLogFields(addLogIDField(fields, err)),
 		Error:   err.Error(),
 	}
 	data, marshalErr := sonic.Marshal(entry)
@@ -55,6 +93,29 @@ func AppendDailyErrorLog(command string, err error, fields map[string]string) er
 	return writeErr
 }
 
+func addLogIDField(fields map[string]string, err error) map[string]string {
+	logID := logIDFromError(err)
+	if logID == "" {
+		return fields
+	}
+	next := make(map[string]string, len(fields)+1)
+	for key, value := range fields {
+		next[key] = value
+	}
+	if strings.TrimSpace(next["log_id"]) == "" {
+		next["log_id"] = logID
+	}
+	return next
+}
+
+func logIDFromError(err error) string {
+	var carrier logIDCarrier
+	if errors.As(err, &carrier) {
+		return strings.TrimSpace(carrier.LogID())
+	}
+	return ""
+}
+
 func dailyErrorLogPath(now time.Time) (string, error) {
 	home, err := os.UserHomeDir()
 	if err != nil {

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" {
@@ -59,3 +59,33 @@ func TestAppendDailyErrorLog(t *testing.T) {
 		t.Fatalf("access_key should be omitted from log fields: %#v", fields)
 	}
 }
+
+func TestAppendDailyErrorLogAddsLogID(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+
+	err := AppendDailyErrorLog("query-result", NewLogIDError("request failed", "log_123"), map[string]string{
+		"thread_id": "thread_123",
+	})
+	if err != nil {
+		t.Fatalf("AppendDailyErrorLog(): %v", err)
+	}
+
+	path := filepath.Join(home, ".pippit_tool_cli", "logs", time.Now().Format("2006-01-02")+".log")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%s): %v", path, err)
+	}
+	var entry map[string]any
+	if err := sonic.Unmarshal([]byte(strings.TrimSpace(string(data))), &entry); err != nil {
+		t.Fatalf("decode log line: %v\n%s", err, string(data))
+	}
+	fields, ok := entry["fields"].(map[string]any)
+	if !ok {
+		t.Fatalf("fields = %#v, want object", entry["fields"])
+	}
+	if fields["log_id"] != "log_123" {
+		t.Fatalf("log_id = %v, want log_123", fields["log_id"])
+	}
+}

package/internal/common/get_thread.go

@@ -2,61 +2,75 @@ package common
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 
 	"github.com/Pippit-dev/pippit-cli/internal/config"
 )
 
-const getThreadVersionV2 = "v2"
+const GetThreadVersionV2 = "v2"
 
 // GetThreadOptions is the stable command-facing request shape for thread lookup.
 type GetThreadOptions struct {
 	ThreadID string `json:"thread_id"`
 	RunID    string `json:"run_id,omitempty"`
+	Version  string `json:"version,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"`
+	RawData      []byte `json:"-"`
 }
 
 type getThreadResponse struct {
-	Ret    string `json:"ret"`
-	Errmsg string `json:"errmsg"`
-	Data   struct {
-		ReadableText string `json:"readable_text"`
-	} `json:"data"`
+	Ret    string          `json:"ret"`
+	Errmsg string          `json:"errmsg"`
+	LogID  string          `json:"log_id"`
+	Data   json.RawMessage `json:"data"`
 }
 
 func GetThread(ctx context.Context, opts *GetThreadOptions, runner *Runner) (*GetThreadResult, error) {
 	if runner == nil || runner.Client == nil {
-		return nil, fmt.Errorf("get_thread runner client is required")
+		return nil, fmt.Errorf("get_thread 运行器客户端缺失")
 	}
 
 	body := map[string]any{
 		"thread_id": opts.ThreadID,
-		"version":   getThreadVersionV2,
 	}
 	if opts.RunID != "" {
 		body["run_id"] = opts.RunID
 	}
+	if opts.Version != "" {
+		body["version"] = opts.Version
+	}
 
 	var resp getThreadResponse
 	if err := runner.Client.SendRequest(ctx, getThreadPath(runner), body, &resp); err != nil {
-		return nil, fmt.Errorf("get_thread request failed: %w", err)
+		return nil, fmt.Errorf("获取线程请求失败: %w", err)
 	}
 	if resp.Ret != "0" {
 		if resp.Errmsg == "" {
-			resp.Errmsg = "unknown error"
+			resp.Errmsg = "未知错误"
 		}
-		return nil, fmt.Errorf("get_thread failed: ret=%s errmsg=%s", resp.Ret, resp.Errmsg)
+		return nil, NewLogIDError(fmt.Sprintf("获取线程请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
+	}
+	if len(resp.Data) == 0 {
+		return nil, fmt.Errorf("get_thread 响应缺少 data")
 	}
-	if resp.Data.ReadableText == "" {
-		return nil, fmt.Errorf("get_thread response missing data.readable_text")
+	readable := struct {
+		ReadableText string `json:"readable_text"`
+	}{}
+	if opts.Version == GetThreadVersionV2 {
+		_ = json.Unmarshal(resp.Data, &readable)
+		if readable.ReadableText == "" {
+			return nil, fmt.Errorf("get_thread v2 响应缺少 data.readable_text")
+		}
 	}
 
 	return &GetThreadResult{
-		ReadableText: resp.Data.ReadableText,
+		ReadableText: readable.ReadableText,
+		RawData:      resp.Data,
 	}, nil
 }
 

package/internal/common/get_thread_test.go

@@ -0,0 +1,74 @@
+package common
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/bytedance/sonic"
+)
+
+type getThreadFakeClient struct {
+	response string
+}
+
+func (c getThreadFakeClient) SendRequest(_ context.Context, _ string, _ any, out any) error {
+	return sonic.Unmarshal([]byte(c.response), out)
+}
+
+func (c getThreadFakeClient) SendRequestWithHeaders(ctx context.Context, path string, body any, _ map[string]string, out any) error {
+	return c.SendRequest(ctx, path, body, out)
+}
+
+func (c getThreadFakeClient) SendMultipartRequest(context.Context, string, map[string]string, MultipartFile, any) error {
+	return nil
+}
+
+func TestGetThreadAllowsStructuredDataWithoutVersion(t *testing.T) {
+	result, err := GetThread(context.Background(), &GetThreadOptions{
+		ThreadID: "thread_123",
+		RunID:    "run_456",
+	}, &Runner{
+		Client: getThreadFakeClient{response: `{"ret":"0","errmsg":"","data":{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":3}]}}}`},
+	})
+	if err != nil {
+		t.Fatalf("GetThread() error = %v", err)
+	}
+	if result.ReadableText != "" {
+		t.Fatalf("ReadableText = %q, want empty for non-v2 response", result.ReadableText)
+	}
+	if !strings.Contains(string(result.RawData), `"thread"`) {
+		t.Fatalf("RawData = %s, want structured thread data", string(result.RawData))
+	}
+}
+
+func TestGetThreadRequiresRetZero(t *testing.T) {
+	_, err := GetThread(context.Background(), &GetThreadOptions{
+		ThreadID: "thread_123",
+		RunID:    "run_456",
+	}, &Runner{
+		Client: getThreadFakeClient{response: `{"errmsg":"","data":{"thread":{"thread_id":"thread_123"}}}`},
+	})
+	if err == nil {
+		t.Fatal("GetThread() error = nil, want missing ret validation")
+	}
+	if !strings.Contains(err.Error(), "获取线程请求返回失败: ret=") {
+		t.Fatalf("error = %q, want missing ret validation", err)
+	}
+}
+
+func TestGetThreadV2RequiresReadableText(t *testing.T) {
+	_, err := GetThread(context.Background(), &GetThreadOptions{
+		ThreadID: "thread_123",
+		RunID:    "run_456",
+		Version:  GetThreadVersionV2,
+	}, &Runner{
+		Client: getThreadFakeClient{response: `{"ret":"0","errmsg":"","data":{"thread":{"thread_id":"thread_123"}}}`},
+	})
+	if err == nil {
+		t.Fatal("GetThread() error = nil, want v2 readable_text validation")
+	}
+	if !strings.Contains(err.Error(), "get_thread v2 响应缺少 data.readable_text") {
+		t.Fatalf("error = %q, want readable_text validation", err)
+	}
+}

package/internal/common/json.go

@@ -0,0 +1,18 @@
+package common
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/bytedance/sonic"
+)
+
+// WriteJSON writes v as one JSON line.
+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/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"`
@@ -51,7 +51,7 @@ type threadFileResponse struct {
 
 func ListThreadFile(ctx context.Context, opts *ListThreadFileOptions, runner *Runner) (*ListThreadFileResult, error) {
 	if runner == nil || runner.Client == nil {
-		return nil, fmt.Errorf("list_thread_file runner client is required")
+		return nil, fmt.Errorf("list_thread_file 运行器客户端缺失")
 	}
 
 	body := map[string]any{
@@ -66,13 +66,13 @@ func ListThreadFile(ctx context.Context, opts *ListThreadFileOptions, runner *Ru
 
 	var resp listThreadFileResponse
 	if err := runner.Client.SendRequest(ctx, listThreadFilePath(runner), body, &resp); err != nil {
-		return nil, fmt.Errorf("list_thread_file request failed: %w", err)
+		return nil, fmt.Errorf("获取线程文件列表请求失败: %w", err)
 	}
 	if resp.Ret != "0" {
 		if resp.Errmsg == "" {
-			resp.Errmsg = "unknown error"
+			resp.Errmsg = "未知错误"
 		}
-		return nil, fmt.Errorf("list_thread_file failed: ret=%s errmsg=%s", resp.Ret, resp.Errmsg)
+		return nil, fmt.Errorf("获取线程文件列表请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg)
 	}
 
 	files := make([]*ThreadFile, 0, len(resp.Data.Files))
@@ -101,9 +101,9 @@ func listThreadFileMessage(total int64, pageNum int) string {
 	}
 	var message string
 	if total >= MaxListThreadFilePageSize {
-		message = fmt.Sprintf("total reached %d; query the next page with --page-num %d", MaxListThreadFilePageSize, pageNum+1)
+		message = fmt.Sprintf("文件总数已达到 %d；请使用 --page-num %d 查询下一页", MaxListThreadFilePageSize, pageNum+1)
 	} else {
-		message = fmt.Sprintf("total is below %d; continue querying with current --page-num %d", MaxListThreadFilePageSize, pageNum)
+		message = fmt.Sprintf("文件总数小于 %d；继续使用当前 --page-num %d 查询", MaxListThreadFilePageSize, pageNum)
 	}
 	return fmt.Sprintf("%s\n- %s\n%s", start, message, end)
 }