docs: document mail sender allow and block commands

[chumbleyneria]

Document the lark-mail sender allow/block commands exposed by the user mailbox APIs.

• Add command coverage for allowed and blocked sender lists.
• Include batch create and batch remove operations for both sender sets.
• Keep the command descriptions aligned with the generated API surface.

Summary by CodeRabbit

• Documentation

  • Expanded Feishu/Lark mail command guidance: draft compose/edit flows, recipients search and confirmation steps, send/confirm rules, scheduled sending constraints, recall and IM sharing, calendar invite emails, templates (last-write-wins), attachment handling, and HTML authoring with linting and auto-fixes.
  • Updated shortcut and native API usage guidance, sender allow/block controls, and permissions coverage.

• Bug Fixes

  • Improved consistency in security header generation for trace/user-agent values.

[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: eb68b65e-a797-4e45-af86-74038e0fc9e8

📥 Commits

Reviewing files that changed from the base of the PR and between ef111ee and 1b2dd5d.

📒 Files selected for processing (1)

• skills/lark-mail/SKILL.md

---

📝 Walkthrough

Walkthrough

This PR expands skills/lark-mail/SKILL.md with broader mail operation guidance, stricter safety and HTML handling rules, larger API/resource and scope references, and changes BaseSecurityHeaders header assignment order.

Changes

Lark Mail SKILL.md documentation updates

Layer / File(s)	Summary
Front-matter, core concepts, and workflow overview skills/lark-mail/SKILL.md	Description, shared-auth reminder, core concepts list, workflow steps, and a new pre-command -h requirement are updated.
Recipient search and sending workflow skills/lark-mail/SKILL.md	Recipient search via multi_entity search is detailed; sending guidance adds confirmation requirements, scheduled send rules, send-as/mailbox options, delivery verification, cancellation, recall, IM sharing, and calendar invites.
Body format and HTML writing/linting rules skills/lark-mail/SKILL.md	HTML-first body guidance, style constraints, prohibition of manual EML construction, writing-path HTML lint behavior, and read-mode HTML return controls are documented.
Templates and native API calling rules skills/lark-mail/SKILL.md	Template create/update/apply merge rules, size constraints, and native API usage guidance are expanded.
Sender allow/block list and shortcuts reference skills/lark-mail/SKILL.md	New sender allow/block Meta API section is added; shortcuts table is updated with +draft-send and +lint-html.
API resources inventory and permission scope table skills/lark-mail/SKILL.md	API Resources section is expanded with a fuller method inventory and a comprehensive permission scope table.
Header assignment order internal/cmdutil/secheader.go	BaseSecurityHeaders now sets HeaderAgentTrace before HeaderUserAgent.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• larksuite/cli#749: Shares the same safety and confirmation guidance surface in skills/lark-mail/SKILL.md.
• larksuite/cli#1261: Also updates Lark mail shortcut guidance and message-reading behavior in the same skill document.
• larksuite/cli#1527: Overlaps on -h discovery guidance, workflow instructions, and native API usage in SKILL.md.

Suggested reviewers: chanthuang, infeng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the PR’s main change: documenting mail sender allow/block commands.
Description check	✅ Passed	The description covers the summary and key changes, but it omits the template’s Test Plan and Related Issues sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[chumbleyneria]

🤖 AI Review | [P2 正确性] 精确查询示例未处理分页，可能把后续页命中误判为 none

skills/lark-mail/SKILL.md:389 的精确状态查询示例只请求 page_size:100 的第一页，然后要求检查 items[].sender 精确匹配。后端当前是先让 PB 做关键词搜索，再对当前页 exact filter；当用户有超过 100 条包含同一关键词或同域的记录，目标命中在第二页时，第一页可能没有精确命中但仍有 has_more=true。Agent 会把状态误判为 none，进而重复添加或跳过删除。

修复建议: 文档中的精确状态查询必须要求 --page-all，或明确循环 page_token 直到 has_more=false 后再判断；如果后端后续提供真正 exact query，再改为调用 exact 语义。

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

---

🤖 AI Review | CR 汇总 | 可合入（1 个建议项）

本次对 larksuite/cli PR 增量审查新增 1 条问题：精确查询发件人白/黑名单状态的示例没有处理分页，目标命中后续页时可能被误判为 none。未发现 P0/P1 阻断问题。