docs(mail): clarify JSON output is directly usable without extra encoding

[infeng]

Summary

Users reported that AI agents sometimes wrote shell scripts to manually extract and re-decode JSON string fields (e.g. unicode_escape), causing Chinese character corruption. Add notes to mail skill docs clarifying that JSON output can be read directly without additional encoding conversion.

Changes

• skill-template/domains/mail.md + SKILL.md: add one-liner in "读取邮件" section noting JSON output is directly usable
• references/lark-mail-message.md: add "JSON 输出可直接使用" as first note, add jq -r hint for \u003c/\u003e
• references/lark-mail-messages.md and lark-mail-thread.md: add same "JSON 输出可直接使用" note

Test Plan

• Verified JSON output contains correct UTF-8 Chinese via +message --format json
• Verified AI agent can directly read and understand JSON output without extra decoding

Summary by CodeRabbit

Documentation

• Clarified that JSON output from mail reading commands is directly consumable without requiring additional encoding conversions or transformation steps
• Added clear guidance on plain text output options available when verifying operation results
• Enhanced documentation explaining how special characters in mail content are represented in JSON format and how they can be processed

[greptile-apps]

Greptile Summary

This documentation-only PR adds clarifying notes across five Markdown files to inform AI agents (and human readers) that the lark-cli mail JSON output is valid UTF-8 and can be consumed directly without extra encoding steps. It also surfaces the jq -r tip for handling the \u003c/\u003e HTML-safe escapes in body_html.

Confidence Score: 5/5

Safe to merge — pure documentation update with no code or logic changes.

All five changed files are Markdown documentation. The added text is factually accurate (UTF-8 JSON output, jq -r behaviour), consistent with existing content, and directly addresses the reported user confusion. No P0/P1 findings.

No files require special attention.

Important Files Changed

Filename	Overview
skill-template/domains/mail.md	Adds one-liner noting JSON output is directly usable without extra encoding; no logic changes
skills/lark-mail/SKILL.md	Mirrors the same one-liner from skill-template/domains/mail.md; clean documentation addition
skills/lark-mail/references/lark-mail-message.md	Adds bold "JSON 输出可直接使用" note with em-dash phrasing and a jq -r comment on the HTML example; accurate and helpful
skills/lark-mail/references/lark-mail-messages.md	Adds "JSON 输出可直接使用" note with comma-style phrasing (slightly different from lark-mail-message.md but cosmetically minor); adds jq -r hint
skills/lark-mail/references/lark-mail-thread.md	Adds "JSON 输出可直接使用" note and jq -r hint, consistent with lark-mail-messages.md

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["lark-cli mail\n+message / +messages / +thread"] -->|"--format json"| B["UTF-8 JSON output\n(valid, no extra encoding needed)"]
    B --> C{Need raw HTML?}
    C -->|Yes| D["jq -r '.data.body_html'\n(resolves \\u003c → <)"]
    C -->|No| E["Read JSON directly\nin AI agent / script"]

Loading

_{Reviews (1): Last reviewed commit: "docs(mail): clarify JSON output is direc..." | Re-trigger Greptile}

[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: 9c2bcf13-2aef-4be7-b906-31f73472dc8a

📥 Commits

Reviewing files that changed from the base of the PR and between 1f3d9e0 and ce4c867.

📒 Files selected for processing (5)

• skill-template/domains/mail.md
• 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-thread.md

---

📝 Walkthrough

Walkthrough

Documentation updates across five markdown files related to the lark-cli mail command, clarifying that JSON output is structured and consumable directly without additional encoding conversion, and explaining HTML character escaping behavior when using --html=false.

Changes

Cohort / File(s)	Summary
Mail Command Documentation skill-template/domains/mail.md, 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-thread.md	Clarified that JSON output from mail reading commands (+message, +messages, +thread) is valid, structured UTF-8 that can be consumed directly. Added guidance on --html=false behavior (plain text for token efficiency) and explained JSON escaping of HTML special characters (</> as \u003c/\u003e) with jq -r restoration notes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰✨ Docs dance with clarity bright,
JSON flows right, needs no rewrite,
HTML escapes explained with care,
Structured data beyond compare!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation clarification that JSON output from mail commands is directly usable without extra encoding conversion.
Description check	✅ Passed	The description includes all required sections from the template: Summary explains the motivation, Changes lists specific file updates, Test Plan covers verification steps, and Related Issues is addressed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mail-json-output-guidance

---

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#docs/mail-json-output-guidance -y -g