feat(drive): pre-flight per-text-element byte limit for +add-comment

[herbertliu]

Summary

The open-platform comment API returns an opaque [1069302] Invalid or missing parameters whenever a single reply_elements[i].text exceeds its implicit byte budget. The error does not name which element failed or that length is the cause, forcing callers to binary-search the content to locate the offender.

This PR moves that detection into the CLI as a pre-flight check so agents / users see a clear, actionable error before hitting the server.

Changes

• shortcuts/drive/drive_add_comment.go — parseCommentReplyElements now rejects any text element whose UTF-8 byte length exceeds 300 bytes (≈100 Chinese characters / 300 ASCII characters). The error:
  • names the 1-based element index (--content element #N)
  • shows both the rune count and byte count
  • ErrWithHint recommends the correct remediation: split into multiple {"type":"text","text":"..."} elements — the comment UI still renders them as one contiguous comment
  • The prior 1000-rune cap was too lenient (a Chinese text under that cap would still fail server-side), so it's replaced rather than stacked
• shortcuts/drive/drive_add_comment_test.go — 6 table-driven cases covering: ASCII at / over the boundary, Chinese at / over the boundary (exactly 100 chars = 300 bytes must fit), a 130-Chinese-char reproducer (390 bytes, reliably fails server-side), and correct index reporting when the second element is the offender. Hint text inspected via ExitError.Detail.Hint.
• skills/lark-drive/references/lark-drive-add-comment.md — new bullet documenting the per-element limit + the correct split pattern, so agents avoid constructing oversized single elements upstream in the first place.

Empirical basis

Chinese chars	Bytes	Result
~80	~240	succeeds
~130	~390	fails with [1069302]

300 bytes sits comfortably inside the known-good zone: it rejects the 390-byte failure case pre-flight while leaving headroom for typical ~100-character comments.

Test Plan

• go test ./shortcuts/drive/... passes (new TestParseCommentReplyElementsTextLength with 6 cases)
• go vet ./shortcuts/... clean
• gofmt -l shortcuts/ clean
• golangci-lint run --new-from-rev=origin/main — 0 issues

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Enhanced validation for comment text elements with improved error messages that specify which element exceeds the limit and provide guidance on splitting content.

• Documentation

  • Updated documentation to clarify that each comment text element is limited to approximately 300 bytes and explain how to split longer content across multiple elements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: eba7051a-c564-43dd-8085-d428b10677f0

📥 Commits

Reviewing files that changed from the base of the PR and between 4740361 and 1216876.

📒 Files selected for processing (3)

• shortcuts/drive/drive_add_comment.go
• shortcuts/drive/drive_add_comment_test.go
• skills/lark-drive/references/lark-drive-add-comment.md

✅ Files skipped from review due to trivial changes (1)

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

🚧 Files skipped from review as they are similar to previous changes (2)

• shortcuts/drive/drive_add_comment.go
• shortcuts/drive/drive_add_comment_test.go

---

📝 Walkthrough

Walkthrough

Replaced rune-count validation with UTF-8 byte-length validation (max 300 bytes) for {"type":"text","text":...} reply elements in the Drive comment shortcut; improved error reporting to include element index, rune and byte counts, and a hint. Added tests and documentation reflecting the change.

Changes

Cohort / File(s)	Summary
Comment Validation Logic shortcuts/drive/drive_add_comment.go	Added maxCommentTextElementBytes = 300; switched validation from rune-count to byte-length; changed overflow response to output.ErrWithHint including element index, rune count, byte count, and a hint to split text across elements.
Validation Tests shortcuts/drive/drive_add_comment_test.go	Added TestParseCommentReplyElementsTextLength covering ASCII and UTF-8 boundary cases, asserting error message content and *output.ExitError hint details; updated imports to include errors and internal/output.
Documentation skills/lark-drive/references/lark-drive-add-comment.md	Documented per-element ~300-byte limit for --content reply text elements and described pre-flight blocking behavior and guidance to split long text into consecutive text elements.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• fangshuyu-768

Poem

🐰 I nibble bytes beneath the moonlight,
Counting three hundred, neat and bright.
If words overflow, split them apart—
Little hops keep comments smart. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately summarizes the main change: adding a pre-flight per-text-element byte limit check for the add-comment feature.
Description check	✅ Passed	The PR description fully completes all required template sections with clear, substantive content including motivation, detailed changes, comprehensive test plan, and empirical basis.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/add-comment-length-precheck

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.83%. Comparing base (462d38e) to head (1216876).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #605      +/-   ##
==========================================
+ Coverage   59.82%   59.83%   +0.01%     
==========================================
  Files         404      404              
  Lines       42527    42534       +7     
==========================================
+ Hits        25440    25450      +10     
+ Misses      15082    15080       -2     
+ Partials     2005     2004       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@1216876519db467216e97b617a70f5f9bc4bfbc0

🧩 Skill update

npx skills add larksuite/cli#feat/add-comment-length-precheck -y -g