feat(drive): pre-flight 10000-rune total cap for +add-comment reply_elements

shortcuts/drive/drive_add_comment.go

@@ -18,6 +18,35 @@ import (
 
 const defaultLocateDocLimit = 10
 
+// maxCommentTotalRunes is the cap on the combined character (rune) count
+// across all `reply_elements[].text` fields in a single
+// `drive +add-comment` request.
+//
+// The open-platform `/open-apis/drive/v1/files/{token}/new_comments`
+// endpoint returns an opaque `[1069302] Invalid or missing parameters`
+// when this is exceeded — no indication that length is the cause or
+// which element is at fault.
+//
+// Empirically (probing the live API):
+//
+//   - 10000 runes in a single text element: OK (10000 ASCII / 30000
+//     bytes for Chinese / 40000 bytes if all '<' — server counts the
+//     raw rune count, not byte width and not the post-escape form)
+//   - 10001 runes in a single text element: [1069302]
+//   - 5000 + 5000 across two elements (total 10000): OK
+//   - 5000 + 5001 across two elements (total 10001): [1069302]
+//
+// So the cap is applied to the *total* across all reply_elements, not
+// per element. Splitting an over-the-cap message into multiple text
+// elements does NOT help — the server enforces the same limit on the
+// sum.
+//
+// The schema doc currently advertises a 1-1000 character limit, but
+// the live API accepts up to 10000 runes; the schema is out of date.
+// If this constant ever needs to track a server-side change, re-probe
+// with `drive file.comments create_v2` against a fresh docx.
+const maxCommentTotalRunes = 10000
+
 type commentDocRef struct {
 	Kind  string
 	Token string
@@ -604,6 +633,7 @@ func parseCommentReplyElements(raw string) ([]map[string]interface{}, error) {
 	}
 
 	replyElements := make([]map[string]interface{}, 0, len(inputs))
+	totalRunes := 0
 	for i, input := range inputs {
 		index := i + 1
 		elementType := strings.TrimSpace(input.Type)
@@ -612,9 +642,27 @@ func parseCommentReplyElements(raw string) ([]map[string]interface{}, error) {
 			if strings.TrimSpace(input.Text) == "" {
 				return nil, output.ErrValidation("--content element #%d type=text requires non-empty text", index)
 			}
-			if utf8.RuneCountInString(input.Text) > 1000 {
-				return nil, output.ErrValidation("--content element #%d text exceeds 1000 characters", index)
+			// Measure the raw rune count of the user input — that is what
+			// the server actually counts. byte width and post-escape form
+			// don't matter (10000 '<' chars succeed even though they
+			// expand to 40000 bytes when escaped, and 10000 Chinese chars
+			// succeed even though they encode as 30000 UTF-8 bytes).
+			runes := utf8.RuneCountInString(input.Text)
+			totalRunes += runes
+			if totalRunes > maxCommentTotalRunes {
+				return nil, output.ErrWithHint(
+					output.ExitValidation,
+					"text_too_long",
+					fmt.Sprintf("--content reply_elements text totals %d characters at element #%d (this element: %d); the server caps the combined length at %d characters across ALL reply_elements",
+						totalRunes, index, runes, maxCommentTotalRunes),
+					fmt.Sprintf("shorten the comment so the combined text across all reply_elements fits within %d characters. The server enforces this cap on the TOTAL — splitting one long element into multiple smaller text elements does NOT help (they all add up against the same %d-rune budget). Server returns an opaque [1069302] on overflow, so this check is pre-flight; no escape transform changes the count (server reads raw runes).", maxCommentTotalRunes, maxCommentTotalRunes),
+				)
 			}
+			// Escape '<' and '>' so the rendered comment displays them as
+			// literal characters instead of being interpreted as markup
+			// by Lark's comment renderer. This is independent of the
+			// length check — the server sees the escaped form, but
+			// counts characters by the raw input length above.
 			replyElements = append(replyElements, map[string]interface{}{
 				"type": "text",
 				"text": escapeCommentText(input.Text),

shortcuts/drive/drive_add_comment_test.go

@@ -5,11 +5,13 @@ package drive
 
 import (
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func decodeJSONMap(t *testing.T, raw string) map[string]interface{} {
@@ -292,6 +294,186 @@ func TestParseCommentReplyElementsEscapesAngleBrackets(t *testing.T) {
 	}
 }
 
+func TestParseCommentReplyElementsTextLength(t *testing.T) {
+	t.Parallel()
+
+	// Cap is 10000 runes total across all reply_elements text fields,
+	// empirically derived from the live API. See the comment on
+	// maxCommentTotalRunes for the probe results.
+	exactCapASCII := strings.Repeat("a", 10000)
+	overCapASCII := strings.Repeat("a", 10001)
+
+	// Chinese chars cost 3 bytes each in UTF-8 but the server counts
+	// runes, not bytes — so the cap is the same 10000 here.
+	exactCapCJK := strings.Repeat("文", 10000)
+	overCapCJK := strings.Repeat("文", 10001)
+
+	// '<' would expand to '&lt;' (4 bytes) under escapeCommentText, but
+	// since the server counts raw runes the cap is still 10000 chars,
+	// not 2500. This pins that distinction.
+	exactCapAngle := strings.Repeat("<", 10000)
+	overCapAngle := strings.Repeat("<", 10001)
+
+	// Two-element split exactly hitting the cap together.
+	splitFiveK := strings.Repeat("a", 5000)
+	splitFiveKPlusOne := strings.Repeat("a", 5001)
+
+	tests := []struct {
+		name      string
+		input     string
+		wantErr   string
+		wantHint  string // substring of the hint portion; "" means don't check hint
+		wantCount int    // expected parsed element count when no error expected
+	}{
+		{
+			name:      "single element exactly at 10000 ASCII chars accepted",
+			input:     `[{"type":"text","text":"` + exactCapASCII + `"}]`,
+			wantCount: 1,
+		},
+		{
+			name:     "single element at 10001 ASCII chars rejected",
+			input:    `[{"type":"text","text":"` + overCapASCII + `"}]`,
+			wantErr:  "totals 10001 characters at element #1",
+			wantHint: "splitting one long element into multiple smaller text elements does NOT help",
+		},
+		{
+			name:      "single element exactly at 10000 chinese chars accepted (server counts runes, not bytes)",
+			input:     `[{"type":"text","text":"` + exactCapCJK + `"}]`,
+			wantCount: 1,
+		},
+		{
+			name:    "single element at 10001 chinese chars rejected",
+			input:   `[{"type":"text","text":"` + overCapCJK + `"}]`,
+			wantErr: "totals 10001 characters at element #1",
+		},
+		{
+			name:      "10000 angle brackets accepted (server counts raw runes, not escaped form)",
+			input:     `[{"type":"text","text":"` + exactCapAngle + `"}]`,
+			wantCount: 1,
+		},
+		{
+			name:    "10001 angle brackets rejected (escape state irrelevant to cap)",
+			input:   `[{"type":"text","text":"` + overCapAngle + `"}]`,
+			wantErr: "totals 10001 characters at element #1",
+		},
+		{
+			// Pins the multi-element TOTAL cap: two 5000-char elements
+			// fit together exactly (10000 sum). This is the boundary the
+			// previous PR's "split into multiple elements" advice
+			// implied was a workaround — it's actually only valid if
+			// the sum still fits.
+			name:      "two elements totalling exactly 10000 accepted",
+			input:     `[{"type":"text","text":"` + splitFiveK + `"},{"type":"text","text":"` + splitFiveK + `"}]`,
+			wantCount: 2,
+		},
+		{
+			// Companion to the above and the headline reason the prior
+			// "split into multiple elements" hint is wrong: 5000+5001
+			// sums to 10001 which the server rejects with the same
+			// opaque [1069302], regardless of how many elements it's
+			// distributed across.
+			name:     "two elements totalling 10001 rejected with index pointing at offending element",
+			input:    `[{"type":"text","text":"` + splitFiveK + `"},{"type":"text","text":"` + splitFiveKPlusOne + `"}]`,
+			wantErr:  "totals 10001 characters at element #2",
+			wantHint: "splitting one long element into multiple smaller text elements does NOT help",
+		},
+		{
+			// Streaming-cap correctness: when an EARLY element by itself
+			// already overshoots, the index reported is that early
+			// element (not the last one in the array).
+			name:    "first element over the cap reports index 1",
+			input:   `[{"type":"text","text":"` + overCapASCII + `"},{"type":"text","text":"trailing"}]`,
+			wantErr: "totals 10001 characters at element #1",
+		},
+		{
+			// mention_user / link elements don't count toward the
+			// rune cap (their content is ID / URL, not user-visible
+			// running text). Pin that a moderate text plus a mention
+			// stays accepted even though the mention adds bytes.
+			name:      "text plus mention_user does not double-count toward cap",
+			input:     `[{"type":"text","text":"` + exactCapASCII + `"},{"type":"mention_user","text":"ou_1234567890abcdef"}]`,
+			wantCount: 2,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := parseCommentReplyElements(tt.input)
+			if tt.wantErr != "" {
+				if err == nil {
+					t.Fatalf("expected error containing %q, got nil (parsed %d elements)", tt.wantErr, len(got))
+				}
+				if !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("expected error containing %q, got %q", tt.wantErr, err.Error())
+				}
+				if tt.wantHint != "" {
+					// Hint lives on ExitError.Detail.Hint, not err.Error().
+					var exitErr *output.ExitError
+					if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+						t.Fatalf("expected ExitError with Detail, got %T (%v)", err, err)
+					}
+					if !strings.Contains(exitErr.Detail.Hint, tt.wantHint) {
+						t.Errorf("expected hint substring %q, got %q", tt.wantHint, exitErr.Detail.Hint)
+					}
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(got) != tt.wantCount {
+				t.Fatalf("expected %d reply elements, got %d", tt.wantCount, len(got))
+			}
+		})
+	}
+}
+
+// TestParseCommentReplyElementsHintForbidsSplitAdvice pins that the
+// over-cap hint does NOT recommend splitting into multiple text
+// elements as a workaround. An earlier version of this PR shipped
+// that advice; live-API probing showed the cap is on the *total* run
+// of characters across all reply_elements, so splitting doesn't
+// bypass it. If the hint ever drifts back into recommending a split,
+// users will be sent down a dead end where their first attempt fails
+// pre-flight, their "fixed" attempt also fails server-side, and
+// they're stuck.
+func TestParseCommentReplyElementsHintForbidsSplitAdvice(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseCommentReplyElements(`[{"type":"text","text":"` + strings.Repeat("a", 10001) + `"}]`)
+	if err == nil {
+		t.Fatal("expected over-cap error, got nil")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with Detail, got %T (%v)", err, err)
+	}
+	hint := exitErr.Detail.Hint
+
+	// The hint must explicitly call out that splitting does NOT help.
+	if !strings.Contains(hint, "does NOT help") {
+		t.Errorf("hint must explicitly say splitting does NOT help, got: %q", hint)
+	}
+	// Anti-pattern check: the hint must not phrase any "split into
+	// multiple elements" recommendation as a workaround. Look for the
+	// previous PR's exact phrasing variants.
+	for _, banned := range []string{
+		"split the content across multiple",
+		"split into multiple text elements",
+		"renders them as one contiguous comment",
+	} {
+		if strings.Contains(hint, banned) {
+			t.Errorf("hint must not contain the discredited %q advice, got: %q", banned, hint)
+		}
+	}
+	// And it should reference the actual number so callers know the
+	// budget without having to read the source.
+	if !strings.Contains(hint, "10000") {
+		t.Errorf("hint should name the 10000-rune budget, got: %q", hint)
+	}
+}
+
 func TestParseCommentReplyElementsInvalid(t *testing.T) {
 	t.Parallel()
 

skills/lark-drive/references/lark-drive-add-comment.md

@@ -148,6 +148,10 @@ lark-cli drive +add-comment \
 
 - `--content` 接收结构化评论元素数组；`type` 支持 `text`、`mention_user`、`link`。为便于书写，`mention_user` / `link` 元素可以直接把用户 ID 或链接地址放在 `text` 字段中，shortcut 会转换成 OpenAPI 所需字段。
 - `type=text` 的评论文本不能直接包含 `<`、`>`；应优先传 `&lt;`、`&gt;`。shortcut 在发送前也会自动将 `<`、`>` 转义为 `&lt;`、`&gt;` 作为兜底。
+- **所有 `type=text` 元素的字符总和 ≤ 10000**（按字符算，中英文 / 符号一视同仁）。超过会被 shortcut 在发送前拒绝，并指出累计超长的元素。**拆成多个 text element 不能绕过这个上限**——上限是总额，不是每元素。需要更长内容就缩短或拆成多条评论。
+- 长度限制只对 `type=text` 生效，`mention_user` / `link` 不计入。
+- 局部评论走 `locate-doc` 时，内部固定使用 `limit=10`。
+- 当 `locate-doc` 命中多处时，shortcut 会中止并提示用户继续收窄 `--selection-with-ellipsis`，不支持手动指定匹配序号。
 - 写入评论前会自动生成符合 OpenAPI 定义的请求体：
   - 统一接口：`POST /new_comments`
   - 统一字段：`file_type` + `reply_elements`