Add mail attachment download URL usage hint

[bubbmon233]

This updates mail attachment download handling to include a short-lived URL usage hint in successful responses.

• Adds response metadata for generated download URLs.
• Covers the response transformation path with tests.
• Refreshes the related mail command references.

Summary by CodeRabbit

• New Features

  • Download responses now include a helpful usage hint for mail attachment links when applicable.

• Bug Fixes

  • Prevents the hint from appearing for unrelated responses or business errors.
  • Preserves any existing server-provided hint value.

• Documentation

  • Clarified that download links are short-lived and should be generated only when needed for immediate download.

[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: 80c6bce4-9b50-476e-804e-a46f04c288f9

📥 Commits

Reviewing files that changed from the base of the PR and between ee46e22 and 14bf3e8.

📒 Files selected for processing (6)

• cmd/service/response_transform_test.go
• cmd/service/service.go
• internal/client/response.go
• 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

Adds a Transform hook to ResponseOptions in the client response handler, wires a new serviceResponseTransform/injectMailAttachmentDownloadURLHint mechanism into the service command to inject a download_url_usage_hint for mail attachment download URLs, adds corresponding tests, and updates mail documentation about short-lived download URLs.

Changes

Download URL usage hint feature

Layer / File(s)	Summary
Transform hook in response handling internal/client/response.go	ResponseOptions gains an optional Transform field applied to the decoded JSON result in the success path, before safety scanning/output logic, and skipped for business errors.
Service-level hint injection wiring cmd/service/service.go	New constants define the target mail attachment download URL schema path and hint text; serviceResponseTransform and injectMailAttachmentDownloadURLHint are added and wired into ResponseOptions.Transform to inject data.download_url_usage_hint when appropriate.
Transform behavior tests cmd/service/response_transform_test.go	Tests cover hint injection for the target schema, skipping non-target schemas, jq visibility of the injected hint, exclusion on business errors, and preservation of an existing server-provided hint.
Documentation updates for short-lived download URLs skills/lark-mail/references/lark-mail-message.md, skills/lark-mail/references/lark-mail-messages.md, skills/lark-mail/references/lark-mail-thread.md	Docs clarify download_url is a short-lived pre-signed URL (~2 hours or less), should be generated only at download time, and must not be stored/forwarded as a long-lived clickable link.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant HandleResponse
  participant serviceResponseTransform
  participant injectMailAttachmentDownloadURLHint

  Client->>HandleResponse: request mail attachment download_url
  HandleResponse->>HandleResponse: decode JSON result
  HandleResponse->>serviceResponseTransform: Transform(result)
  serviceResponseTransform->>serviceResponseTransform: check schemaPath match
  alt schemaPath matches target
    serviceResponseTransform->>injectMailAttachmentDownloadURLHint: inject hint into data
    injectMailAttachmentDownloadURLHint-->>serviceResponseTransform: updated data
  else no match or business error
    serviceResponseTransform-->>HandleResponse: unchanged result
  end
  serviceResponseTransform-->>HandleResponse: transformed result
  HandleResponse-->>Client: formatted output

Loading

Suggested reviewers: chanthuang, haidaodashushu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description omits the required Summary/Changes/Test Plan/Related Issues template structure and has no actual test plan.	Rewrite it using the repository template headings, add a brief summary, list the main changes, include test steps, and note related issues.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately captures the main change: adding a mail attachment download URL usage hint.
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.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add bubbmon233/cli#feat/5a2d50b -y -g

[bubbmon233]

🤖 AI Review | CR 汇总 | 有风险（2 个 P2）

本次 GitHub PR 新增运行时 hint 注入和文档说明，相关 Go 包 go test ./cmd/service ./internal/client 已通过。新增 2 个正确性问题：--output 保存路径缺少增强字段，以及 hint 文案未覆盖“最多使用两次”的既有约束。

[bubbmon233]

🤖 AI Review | [P2 正确性] 提示文案遗漏“最多使用两次”的链接约束

cmd/service/service.go 第 33 行的固定 hint 只说明链接大约 2 小时内有效，但技术方案追溯的既有接口说明还包含“下载链接仅可使用两次”。Agent 可能先预取/验证一次链接，再把同一个链接发给用户或在重试链路中复用，导致用户收到的链接已经接近或耗尽使用次数。

修复建议: 把固定 hint、三份 lark-mail reference 和 registry example 统一补充“最多使用两次，不要预取验证后再转发同一 URL；需要下载时重新生成”。

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

[bubbmon233]

🤖 AI Review | [P2 正确性] --output 保存的 JSON 不包含新增 hint

internal/client/response.go 第 115-128 行先把 hint 注入到解析后的 result，但 --output 分支仍调用 saveAndPrint 保存原始 resp.RawBody。因此 mail user_mailbox.message.attachments download_url --output urls.json 落盘的 JSON 没有 data.download_url_usage_hint，stdout 也只是保存元数据；使用 --output 做中间结果持久化的 Agent 仍可能长期保存或转发短时效 URL。

修复建议: 对 JSON 成功响应的 --output 分支保存 transform 后的 JSON，或对该目标 schemaPath 明确拒绝/提示 --output 不包含增强字段；补一条目标 schemaPath + OutputPath 的单测。

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