docs(im): explain querying topic replies by time

[YangJunzhou-01]

Summary

Document the time-range behavior of im +chat-messages-list for native topic chats and provide a raw API workaround for querying replies by their own creation times.

This PR does not change existing CLI behavior.

Changes

• Document that +chat-messages-list uses only_thread_root_messages=true and expands replies under the returned roots.
• Clarify that, for native topic chats (chat_mode=topic), an empty time-window result does not mean no new replies were posted.
• Add a copy-ready raw Messages API example using only_thread_root_messages=false to query topic roots and replies as a flat, server-paginated list.
• Clarify that the parameter does not change results for regular group chats, including groups using thread display mode (chat_mode=group, group_message_type=thread).
• Document pagination requirements and the enrichment differences between raw API output and the shortcut output.

Test Plan

• go test ./shortcuts/im
• git diff --check
• Manually verified that only_thread_root_messages=false returns replies by their own creation times in a native topic chat.
• Manually verified that the parameter does not change results for regular groups or regular groups using thread display mode.

Related Issues

• Related to 话题群里带时间窗的 +chat-messages-list 会静默漏掉话题回复（only_thread_root_messages=true 被硬编码） #2074

Summary by CodeRabbit

• Documentation
  • Clarified time-range behavior for native topic chats, including how thread roots and replies are handled.
  • Added guidance for retrieving topic roots and replies together through the raw API.
  • Expanded pagination instructions for topic chat message queries.
  • Documented differences between shortcut results and raw API responses, including thread replies, sender names, reactions, and downloads.

[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

Updated the Lark IM chat message-list reference with native topic time-range semantics, raw Messages API examples for retrieving replies by creation time, pagination instructions, output limitations, and corresponding AI usage guidance.

Changes

Topic chat time ranges

Layer / File(s)	Summary
Topic time-range semantics skills/lark-im/references/lark-im-chat-messages-list.md	Documents root-based filtering for native topic chats, nested thread replies, missed replies under older roots, and the applicable AI guidance.
Raw API reply retrieval skills/lark-im/references/lark-im-chat-messages-list.md	Adds raw API parameters for flat root-and-reply results, JSON pagination examples, preserved query settings, and raw output limitations.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• 话题群里带时间窗的 +chat-messages-list 会静默漏掉话题回复（only_thread_root_messages=true 被硬编码） #2074: Documents the same native topic time-range behavior and only_thread_root_messages workaround.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
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 (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main documentation change about topic reply time queries.
Description check	✅ Passed	The description follows the template with Summary, Changes, Test Plan, and Related Issues sections filled in.
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@5a33f3de356750d30edaf35fd978ab275f06fdbc

🧩 Skill update

npx skills add YangJunzhou-01/cli#feat/flat-thread-replies -y -g

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/lark-im/references/lark-im-chat-messages-list.md`:
- Line 52: Update the pagination example in the chat messages list documentation
to repeat --include-thread-replies alongside --page-token when demonstrating
flat-mode pagination. Ensure the example preserves
only_thread_root_messages=false across subsequent requests instead of reverting
to root-only results.

In `@tests/cli_e2e/im/chat_messages_include_thread_replies_workflow_test.go`:
- Around line 28-41: Add verified teardown for the chat created in the setup
flow around chatID extraction: after obtaining and using chatID, invoke the
existing chat-delete CLI workflow with the bot credentials and assert the
command succeeds and exits successfully. Ensure cleanup runs even when the test
fails by registering it with the test’s teardown mechanism, preserving the
self-contained create/use/cleanup lifecycle.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a75b530d-1db3-4656-9b50-129154801306

📥 Commits

Reviewing files that changed from the base of the PR and between a575a8b and 09e8980.

📒 Files selected for processing (9)

• shortcuts/im/im_chat_messages_list.go
• shortcuts/im/im_chat_messages_list_test.go
• skill-template/domains/im.md
• skills/lark-im/SKILL.md
• skills/lark-im/references/lark-im-chat-messages-list.md
• skills/lark-im/references/lark-im-message-enrichment.md
• tests/cli_e2e/im/chat_messages_include_thread_replies_dryrun_test.go
• tests/cli_e2e/im/chat_messages_include_thread_replies_workflow_test.go
• tests/cli_e2e/im/coverage.md