feat: surface search API notices

[arnold9672]

sa: safe
doc: none
cfg: none
test: unit test

Summary

Surface search API notice strings in CLI output so agents can see server-side search hints such as query truncation.

Changes

• Pass through data.notice for search shortcuts that rebuild output across contact, docs, drive, IM, mail, minutes, task, and VC.
• Preserve the first non-empty notice for paginated search flows, and include per-query notices for contact fanout output.
• Add shortcut tests covering notice passthrough for the affected search domains.

Test Plan

• go test -count=1 ./shortcuts/contact ./shortcuts/doc ./shortcuts/drive ./shortcuts/im ./shortcuts/mail ./shortcuts/minutes ./shortcuts/task ./shortcuts/vc
• make unit-test attempted; failed in unrelated existing checks: schema envelope count expected >=193 but got 184, and apps tests require a git binary supporting git init --initial-branch.
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Search shortcuts now pass through server-provided data.notice into JSON output across Drive, Docs, IM (chat/messages), Tasks, Minutes, VC, and Contact.
  • Contact fanout/multi-page flows preserve notice in per-query results and (when applicable) the top-level response.
  • Mail +triage outputs notice in structured JSON and prints it to stderr in default table mode.
  • Chat search help/validation updated for long-query notice behavior.

• Tests

  • Added/updated tests to assert data.notice propagation and truncation/overlong-query handling.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Eight search and list shortcuts now capture an optional API data.notice string and propagate it into the CLI's rendered and JSON output when present. The notice field is typically used by the backend to indicate query truncation or other processing conditions. This change applies consistently across contact, doc, drive, IM chat, IM messages, mail, minutes, task, tasklist, and VC search flows.

Changes

Notice Field Passthrough Feature

Layer / File(s)	Summary
Contact Search API Structures (Single and Fanout) shortcuts/contact/contact_search_user.go, shortcuts/contact/contact_search_user_fanout.go	API response and output models gain Notice string fields; single-query handler populates notice; fanout schema extended with per-query and envelope-level notices.
Contact Search Tests shortcuts/contact/contact_search_user_test.go	Test stub includes data.notice; single-query JSON test and fanout tests validate notice preservation in both execution modes.
Doc and Drive Search shortcuts/doc/docs_search.go, shortcuts/doc/docs_search_test.go, shortcuts/drive/drive_search.go, shortcuts/drive/drive_search_test.go	Doc and Drive searches read data.notice from API responses and conditionally include it in output; test imports and new tests verify JSON passthrough for both commands.
IM Chat Search Flag and Validation shortcuts/im/im_chat_search.go, shortcuts/im/builders_test.go	Chat search --query flag description updated; client-side 64-rune length validation removed, delegating to server; validation tests extended to verify long queries pass with explicit --page-size.
IM Chat Search Output shortcuts/im/im_chat_search.go	Chat search Execute includes notice from response in output payload when non-empty.
IM Messages Search Function shortcuts/im/im_messages_search.go	searchMessages function signature returns notice string (captured once during pagination from first non-empty searchData["notice"]).
IM Messages Search Output shortcuts/im/im_messages_search.go	Execute handler captures notice and conditionally includes it in no-match, error-fallback, and successful results JSON responses.
IM Search Tests shortcuts/im/im_search_notice_test.go	New test file with two tests verifying IM chat and messages search propagate data.notice to JSON output; includes Cobra command builder and stdout JSON decoder utilities.
Mail Triage Search Path shortcuts/mail/mail_triage.go	Mail triage search captures notice from first search page during pagination and conditionally includes it in JSON output and stderr for table format (notice: <text>).
Mail Triage Tests shortcuts/mail/mail_triage_test.go	Test case struct extended with wantNotice field; search stub helper accepts variadic notices parameter; existing and new tests validate notice in JSON and stderr output.
Minutes Search shortcuts/minutes/minutes_search.go, shortcuts/minutes/minutes_search_test.go	Minutes search reads data.notice from API response and adds it to outData when non-empty; test extended with notice constant, mock response, envelope struct field, and output assertion.
Task Search shortcuts/task/task_search.go, shortcuts/task/task_search_test.go	Task search initializes and populates notice from data.notice during pagination and conditionally includes it in final output; test mock and assertions updated.
Task Tasklist Search shortcuts/task/task_tasklist_search.go, shortcuts/task/task_tasklist_search_test.go	Tasklist search captures notice from first search page and conditionally includes it in outData; mock response and test assertions updated.
VC Search shortcuts/vc/vc_search.go, shortcuts/vc/vc_search_test.go	VC search checks data.notice and conditionally includes it in outData; test imports and new test verify JSON passthrough of notice field.

Sequence Diagram

sequenceDiagram
  participant User as CLI User
  participant Shortcut as Search Shortcut<br/>(Doc/Drive/IM/Mail/Minutes/Task/VC)
  participant API as Larksuite API
  participant Output as JSON Output
  User->>Shortcut: execute search (--format json)
  Shortcut->>API: POST /search endpoint
  API-->>Shortcut: {data: {results[], notice?}}
  Shortcut->>Shortcut: capture notice if present
  Shortcut->>Output: emit {data: {results[], notice?}}
  Output-->>User: JSON with optional notice field

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#377: Introduces task search implementations that this PR extends to passthrough data.notice.
• larksuite/cli#658: Prior refactor of contact +search-user v3 response shaping; this PR extends the same response models to decode and emit notice.

Suggested labels

feature

Suggested reviewers

• fangshuyu-768
• YangJunzhou-01

Poem

🐰 A tiny notice hops through each search,
From backend APIs, perched and birthed,
Across chats and docs and tasks it flies,
Marking truncations, oh so wise!
Tests stand guard as notices flow home. 📌✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: surface search API notices' clearly and concisely describes the main change: exposing search API notice strings in CLI output.
Description check	✅ Passed	The description covers all required template sections: Summary (clear motivation), Changes (detailed list), Test Plan (execution results), and Related Issues. It is complete and substantive.
Docstring Coverage	✅ Passed	Docstring coverage is 88.46% which is sufficient. The required threshold is 80.00%.
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

---

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

[CLAassistant]

All committers have signed the CLA.

[BytedanceSearch]

Approved per request.

[BytedanceSearch]

LGTM. Reviewed notice passthrough paths and targeted tests passed locally.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add arnold9672/cli#feat/search-notice-passthrough -y -g

[BytedanceSearch]

LGTM. Re-reviewed after latest doc/comment update.