docs(mail): clarify message read shortcuts

[bubbmon233]

Generated by the harness-coding skill.

• Branch: feat/9290d1a
• Target: main

Sprints

ID	Title	Status	Commit
S1	Update mail shortcut help, references, triage hint, and tests	passed	84653ff
S2	Synthesize transport contract for larksuite/cli	passed	1ba107d

---

This MR was created autonomously. Quality gates were enforced by the repo's own pre-commit hooks.

Summary by CodeRabbit

• Documentation
  • Clarified that mail +message reads a single message ID and mail +messages is for multiple IDs; --message-ids is comma-separated (not a page token) and the CLI auto-chunks/merges requests (20 IDs per chunk). Updated help, examples, and tips to reflect chunking and format guidance.
• Tests
  • Added CLI integration tests covering help text, dry-run messaging, triage tips, and actual chunking behavior when >20 IDs are provided.

[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: 99273b14-e466-467a-8dbb-77b075198ccd

📥 Commits

Reviewing files that changed from the base of the PR and between 84653ff and 30334ed.

📒 Files selected for processing (4)

• shortcuts/mail/mail_messages.go
• shortcuts/mail/mail_read_help_test.go
• skills/lark-mail/SKILL.md
• skills/lark-mail/references/lark-mail-messages.md

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

• skills/lark-mail/references/lark-mail-messages.md

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

• skills/lark-mail/SKILL.md
• shortcuts/mail/mail_read_help_test.go

---

📝 Walkthrough

Walkthrough

Clarifies mail shortcuts: mail +message is single-message only; mail +messages auto-chunks comma-separated IDs into 20-ID messages.batch_get calls and merges outputs. Adds tests validating help text, dry-run output, triage hints, and that 21 IDs produce two batch_get requests. Updates user docs and help text.

Changes

Mail shortcut usage clarification and test coverage

Layer / File(s)	Summary
Shortcut help text clarifications shortcuts/mail/mail_message.go, shortcuts/mail/mail_messages.go, shortcuts/mail/mail_triage.go	Updated MailMessage description and --message-id flag help to clarify single-message-only usage and point to mail +messages for multiple IDs. Updated MailMessages description and --message-ids flag help to document internal messages.batch_get usage, CLI chunking into 20-ID batches, comma-separated IDs (not page tokens), and adjusted DryRun messaging. Updated triage pagination tip to mention both mail +message and mail +messages.
Integration test suite for help text and batch behavior shortcuts/mail/mail_read_help_test.go	Added tests and helpers validating: mail +message -h explains single-ID usage; mail +messages -h documents messages.batch_get chunking/merge and correct argument form; mail +messages --dry-run --format json mentions chunking/merge; mail +triage --max 1 emits a read-hint routing single vs multiple reads (suppressed in JSON); and running mail +messages with 21 IDs issues two batch_get POSTs with 20 and 1 IDs respectively. Includes HTTP stubs, request-assert helpers, and a Cobra execution helper.
User-facing documentation updates skills/lark-mail/SKILL.md, skills/lark-mail/references/lark-mail-message.md, skills/lark-mail/references/lark-mail-messages.md, skills/lark-mail/references/lark-mail-triage.md	Clarified mail-reading workflows: +message for a single message_id, +messages for batch reads with auto-chunking and merge, and +thread for full conversations. Documented default HTML output behavior and added examples showing +messages --message-ids ... --html=false, updated reference rows to specify comma-separated IDs and mapping to messages.batch_get message_ids.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• larksuite/cli#301: Both PRs modify shortcuts/mail/mail_triage.go to update pagination hint output.
• larksuite/cli#1238: Related edits to mail +triage hint text and mailbox/contextual hints.
• larksuite/cli#1202: Overlaps on +messages --message-ids parsing/validation and batch_get chunking behavior.

Suggested labels

documentation

Suggested reviewers

• chanthuang
• infeng

Poem

🐰 Hop, hop — a shortcut rewrite so bright,
One ID: +message, multiple: +messages — that's right.
Twenty at once, the CLI splits the rest,
Tests chase the chunks to prove we did our best.
Help, docs, and hints now guide the light. ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is largely incomplete relative to the template. It lacks a proper Summary section, detailed Changes list, Test Plan checklist, and Related Issues section; instead it contains auto-generated harness metadata.	Add a Summary section (1-3 sentences on motivation/scope), a Changes list with main updates, a Test Plan section with verification steps, and clarify Related Issues per the template.
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 (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(mail): clarify message read shortcuts' clearly and concisely summarizes the main change: documentation updates to clarify how to use mail reading shortcuts.
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 unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/9290d1a

---

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.}

[bubbmon233]

🤖 AI Review | CR 汇总 | 可合入（未发现问题）

本次基于 PR diff、已有评论和 Lark Mail CLI 知识库规范完成审查，未发现需要新增落评的 P0-P3 问题。

验证信息：go test -count=1 -timeout 5m ./shortcuts/mail、go test -race -count=1 -timeout 5m ./shortcuts/mail 均通过；变更文件 gofmt 检查无输出，git diff --check HEAD^..HEAD 通过。

如有疑问或认为判断不准确，欢迎直接回复讨论。

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add bubbmon233/cli#feat/9290d1a -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.19%. Comparing base (3990151) to head (b065852).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1261      +/-   ##
==========================================
+ Coverage   70.17%   70.19%   +0.02%     
==========================================
  Files         671      671              
  Lines       65329    65330       +1     
==========================================
+ Hits        45843    45861      +18     
+ Misses      15796    15781      -15     
+ Partials     3690     3688       -2     

☔ View full report in Codecov by Harness.
📢 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.