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

[dfshuang]

问题现象

im +chat-messages-list 固定发送 only_thread_root_messages=true（#635 引入，动机是"与 topic-group 用法保持一致"）。在话题群（chat_mode=topic）里，这会让 --start/--end 按话题根消息（thread root）的
create_time 过滤，而不是按每条消息自身的时间——于是一条发在查询窗口内、但所在话题的 root 早于窗口的回复，会被整体排除。结果是：群里明明在活跃讨论，带时间窗的查询却返回 messages: []。

这对本 CLI 的主要使用者（做增量读取的 AI agent）非常危险：空结果会被解读成"这段时间没有任何新消息"，而真相是"这种查询形态看不到它"。目前 CLI 侧没有任何办法关掉这个参数——它硬编码在
buildChatMessageListParams（shortcuts/im/im_chat_messages_list.go）里。

复现步骤

1. 在话题群 oc_xxx 里开一个话题，放几天不动。
2. 今天在这个话题里发一条回复。
3. lark-cli im +chat-messages-list --chat-id oc_xxx --start <今天> --end <明天> --as user
   → 今天这条回复不见了（常见返回 total: 0）。

用 raw 调用（lark-cli api GET /open-apis/im/v1/messages，同一个群、同一个时间窗、只改这一个参数）做过对照：

only_thread_root_messages	返回条数
true	0
false	1 —— 今天的那条回复，其 root 创建于窗口之前

传 false 时，服务端把 root 和话题回复作为一个平铺列表返回，按每条消息自身的 create_time 过滤、且遵循 sort_type 排序（实测 ByCreateTimeAsc 下严格升序，root 与回复交织；回复带
parent_id/root_id）。

诉求

1. 提供一个可选开关——例如给 +chat-messages-list 加 --include-thread-replies，置位时发送
   only_thread_root_messages=false（默认行为不变），并保留现有的富化能力（正文解码、发送人姓名、message_app_link）。
2. 无论最终怎么改，请在 skills/lark-im/SKILL.md / 命令参考文档里把这个坑写清楚：话题群里带时间窗查询返回空，不代表这段时间没人说话。 Agent 是逐字照着这份文档执行的。
3. only_thread_root_messages 在公开的「获取会话历史消息」文档里没有记载，但 CLI 目前已经无条件依赖它——能否确认这个参数（尤其是 =false）会长期支持？

[YangJunzhou-01]

Hi @dfshuang, a follow-up after further investigation and live API verification.

We confirmed that only_thread_root_messages has different semantics depending on the chat type:

• In a native topic chat (chat_mode=topic), setting it to false returns thread roots and replies as a flat list. Each message participates in time filtering and sorting using its own create_time.
• In a regular group chat (chat_mode=group), including one using thread display mode (group_message_type=thread), thread replies do not participate in the chat message timeline. Changing this parameter therefore does not affect the result.

This means a shortcut-level switch would only work for native topic chats. Applying the same processing to other chat types could disable the existing nested reply expansion without receiving flat replies from the server, causing replies to be silently omitted.

For that reason, To preserve backward compatibility and avoid introducing inconsistent behavior, we will keep the existing shortcut behavior unchanged, document the current semantics, and provide a raw API workaround.

To query roots and replies in a native topic chat by their own creation times:

lark-cli api GET /open-apis/im/v1/messages \
  --params '{
    "container_id_type": "chat",
    "container_id": "oc_xxx",
    "start_time": "<START_UNIX_SECONDS>",
    "end_time": "<END_UNIX_SECONDS>",
    "sort_type": "ByCreateTimeAsc",
    "page_size": "50",
    "only_thread_root_messages": "false"
  }'

When continuing with the returned page_token, preserve the original time range, sort order, and only_thread_root_messages=false.

We verified this flow against the live API:

• With only_thread_root_messages=true, a time window containing only a new reply returned no messages.
• With only_thread_root_messages=false, the same window returned the reply whose root was created before the window.
• Pagination using the returned page_token successfully returned the next flat message.

PR #2113 updates the IM Skill documentation with these semantics, executable raw API examples, pagination guidance, and the differences between raw API output and shortcut enrichment.