weaver-work-cli 0.1.5 → 0.1.7

package/skills/weaver-e10-yimiaoban/SKILL.md

@@ -2,38 +2,53 @@
 name: weaver-e10-yimiaoban
 display_name: 泛微易秒办
 display_name_en: Weaver E10 Yimiaoban IM
-description: 泛微 E10 易秒办即时通讯能力（单聊/群聊消息、发消息与必达、群组管理、会话与系统消息），通过 weaver-work-cli yimiaoban 命令执行。
-description_zh: 泛微 E10 易秒办即时通讯能力（单聊/群聊消息拉取、发送/撤回/置顶/必达、群组管理、会话与系统消息），通过 weaver-work-cli yimiaoban 命令执行。
-description_en: Weaver E10 Yimiaoban IM capabilities (single/group chat messages, sending/withdraw/pin/ding, group management, sessions and system messages), delivered through the weaver-work-cli yimiaoban command.
-version: 1.0.0
+description: 泛微 E10 易秒办即时通讯能力（单聊/群聊消息、发送与必达、群组管理、会话与系统消息），通过 weaver-work-cli im 命令执行。
+description_zh: 泛微 E10 易秒办即时通讯能力：拉取单聊/群聊/系统消息、发送与撤回消息、发必达、群组管理（建群/邀人/踢人/退群/解散/公告）、会话列表、文件上传下载与人员解析，全部通过 weaver-work-cli im 命令执行，写操作走 prepare→apply 确认链。
+description_en: Weaver E10 Yimiaoban (IM) capabilities - fetching single/group/system messages, sending, withdrawing and ding messages, group management, sessions, file upload/download and people resolution, executed through the weaver-work-cli im command with a prepare-then-apply confirmation chain for writes.
+version: 1.1.0
 author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
   bins: ["weaver-work-cli"]
-cliHelp: "weaver-work-cli yimiaoban --help"
+dependencies:
+  - weaver-e10-login
+  - weaver-e10-shared
+cliHelp: "weaver-work-cli im --help"
 ---
 
-# 泛微易秒办
+# 泛微易秒办（im）
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --skills-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
 
 共享规则覆盖命令可用性检查、E10 认证、JSON 输出契约、大结果渲染和高风险写入确认链，本技能不再重复。
 
-本技能覆盖易秒办（E10 即时通讯）业务域：**消息（msg）**、**必达（ding）**、**群组（group）**、**会话（session）**、**系统消息（sysmsg）**，以及支撑能力**人员解析（person）**、**文件上传/预览/下载（file）**、**用户状态（user）**、**i18n 标签（i18n）**。所有写操作走 prepare→apply 确认协议。
+本技能覆盖易秒办（E10 即时通讯）业务域：**消息（msg）**、**必达（ding）**、**群组（group）**、**会话（session）**、**系统消息（sysmsg）**，以及支撑能力**人员解析（person）**、**文件上传/预览/下载（file）**、**用户状态与免打扰设置（user）**、**i18n 标签（i18n）**。所有写操作走 prepare→apply 确认协议。
 
-## 命令入口
+## 认证与请求头契约
+
+**登录与会话一律由 `weaver-e10-login` 技能提供**（小 E 宿主环境优先 `weaver-work-cli auth xiaoe`，其它环境由用户提供自有域名后走 `weaver-work-cli auth login`）。本技能**不自建登录**：禁止扫码/账号密码/自建 OAuth 取 token，禁止使用浏览器自动化登录，也不接触、打印、转存任何认证文件。
+
+`weaver-work-cli im` 发往 E10 的每个请求（`/api/em/msg/executeIm/...`、`/api/em/msg/createDing`、`/api/hrm/common/getEmployeeByIds`、`/api/file/...` 等）都由 CLI 统一携带以下三项用户信息参数，缺一不可（业务入参里不要传、也不要手工拼装请求头）：
 
 ```text
-weaver-work-cli yimiaoban --help
-weaver-work-cli yimiaoban schema
-weaver-work-cli --json yimiaoban run <operation> --input -
+Cookie: <weaver-e10-login 返回的完整原始 Cookie 串，原样透传，禁止裁剪/去重/改写>
+eteamsid: <weaver-e10-login 返回的 ETEAMSID>
+User-Agent: AgentType=<agentType>,IsAgent=true
 ```
 
-`schema` 是可用能力的唯一事实来源（含每个 operation 的 `inputSchema`、`risk`、`requiresConfirmation`）。禁止把本技能或源文档里的接口路径当成可直接调用的地址，也禁止把未出现在 `schema` 中的能力当作可用 operation。
+三项若缺任一，服务端无法识别操作者或会判定登录失效；`weaver-work-cli im` 的每个 operation 都已在请求头中带齐。
+
+业务输入只描述业务对象与意图，凭证与请求头由 CLI 托管；需要诊断登录态时只用 `weaver-work-cli auth` / `doctor --e10` 与业务命令返回的 JSON 错误。
 
-## 认证
+## 命令入口
+
+```text
+weaver-work-cli im --help
+weaver-work-cli im schema
+weaver-work-cli --json im run <operation> --input-json '{"key":"value"}'
+```
 
-所有请求复用 `weaver-work-cli` 托管的 E10 会话（含 `eteamsid` 请求头），业务输入只描述业务对象和意图。禁止读取、列出、打印或解析 `.e10-cli` 等认证目录和文件；认证诊断只能通过 `weaver-work-cli auth` 系列命令、`weaver-work-cli doctor --e10` 和业务命令返回的 JSON 错误完成。登录失效时按共享规则引导用户执行 `weaver-work-cli auth login`，禁止猜域名或手工拼凭证。
+`schema` 是可用能力的唯一事实来源（含每个 operation 的 `inputSchema`、`risk`、`requiresConfirmation`、`deprecatedInputAliases`）。禁止把本技能或源文档里的接口路径当成可直接调用的地址，也禁止把未出现在 `schema` 中的能力当作可用 operation。
 
 ## Reference 路由表
 
@@ -41,31 +56,33 @@ weaver-work-cli --json yimiaoban run <operation> --input -
 
 | 触发条件 | Reference |
 | --- | --- |
-| 按姓名/工号/手机/邮箱解析人员，uid/cid 批量解析 | [`references/person.md`](references/person.md) |
-| 名称 → ID 解析规则、同名消歧、接口间上下文传递契约 | [`references/field-resolution.md`](references/field-resolution.md) |
-| 拉取单聊/群聊消息、群置顶消息、消息阅读状态（读） | [`references/msg-read.md`](references/msg-read.md) |
+| 按姓名/工号/手机/邮箱解析人员，uid 批量解析 | [`references/person.md`](references/person.md) |
+| 名称 → ID 解析规则、同名消歧、未匹配处理、接口间上下文传递契约 | [`references/field-resolution.md`](references/field-resolution.md) |
+| 拉单聊/群聊消息、群置顶消息、消息阅读状态（只读） | [`references/msg-read.md`](references/msg-read.md) |
 | 发送单聊/群聊消息（文本/图片/文件）、撤回、群消息置顶（写） | [`references/msg-write.md`](references/msg-write.md) |
 | 必达消息：普通必达、已有消息转必达、仅未读/指定接收人（写） | [`references/ding-write.md`](references/ding-write.md) |
-| 搜索群、群信息、群成员、群主/管理员、群存在性、群公告（读） | [`references/group-read.md`](references/group-read.md) |
+| 搜群、群信息、群成员、群主/管理员、群存在性、群公告（读） | [`references/group-read.md`](references/group-read.md) |
 | 建群、邀请、踢人、退群、解散、申请入群、改群属性/群名、群公告增改删（写） | [`references/group-write.md`](references/group-write.md) |
 | 会话列表、系统消息分组/类型/消息查询 | [`references/session-sysmsg.md`](references/session-sysmsg.md) |
 | 文件上传/预览/下载到本地、用户在线状态、i18n 标签翻译 | [`references/file-user-i18n.md`](references/file-user-i18n.md) |
-| 易秒办红线（操作人字段、人名解析、id 边界、分页、展示完整）、写链停止条件 | [`references/safety-boundaries.md`](references/safety-boundaries.md) |
-| 业务错误码含义与处理建议（群 12xx / 消息 15xx / 数据 13xx） | [`references/error-codes.md`](references/error-codes.md) |
-| 源资料清单与 sha256（源 skill 更新检测用） | [`references/source-manifest.json`](references/source-manifest.json) |
+| 把某个群/某个人/某个系统会话设为免打扰或恢复提醒 | [`references/user-remind.md`](references/user-remind.md) |
+| 易秒办红线（操作人字段、本人身份取用、人名解析、id 边界、分页与全量、展示完整）、写链停止条件、已知禁用边界 | [`references/safety-boundaries.md`](references/safety-boundaries.md) |
+| 业务错误码含义与处理建议（群 12xx / 消息 15xx / 数据 13xx + CLI 校验错误） | [`references/error-codes.md`](references/error-codes.md) |
+| 源资料清单、chunk 与 operation 影响索引、产物基线（源资料更新检测用） | [`references/source-manifest.json`](references/source-manifest.json) |
 
 ## 关键差异（必须先知道）
 
-- **消息对象以 `msg` JSON 字符串 + `datas[].data[]` 行结构返回**：CLI 的 `msg.sync.*`/`msg.top.sync` 已把每条消息解析成结构化行（`sender/time/typeName/content/media/...`），`content` 为可读文本（@ 提及已替换、媒体显示为 `[图片]名称`/`[视频]名称`/`[文件]名称`、必达内容带 `[必达]` 前缀）。解析结果直接使用，不需要再本地拼装。
-- **发送者「我」由 CLI 判定**：`sender` 与当前登录 uid（CLI 会话 `userId`）比对，自己发的消息返回「我」；他人优先消息内 `sname`、其次 hrm 姓名、最后回退 uid。
-- **人名一律由 CLI 走 hrm 接口解析**（`/api/hrm/common/getEmployeeByIds`），本技能不展示也不依赖 IM 群成员 `name` 字段。群成员接口返回的 `name` 字段不可信且默认不请求。
-- **uid/cid/群 id 都是 uint64**：JSON 中必须按字符串传（`"1788334281700000004"`），CLI 会把数字/逗号串统一归一，`0` 一律拒绝。
-- **分页不自动翻页**：`msg.sync.*`/`session.list`/`sysmsg.*`/公告列表等每页默认 20（群搜索默认 100），单页最大 50（群搜索 200）；Agent 只取单页，需要更多数据时用返回的 `nextStart`（消息类）/`nextMsgid`（会话类）显式请求下一页，绝不静默全量循环。消息类下一页会把边界那条重复返回，必须按 `msgid` 去重。
-- **时间范围不是过滤条件**：单聊/群聊历史消息按**消息 id 区间**定位，`from/to` 时间会被 CLI 换算成 `[minId,maxId]` 区间；默认取当天。要"拉全部历史"必须显式给出 `from/to` 或 `latest:true`（仅最新一页）。`actionMsg.code=1303`（无聊天记录）按**成功空列表**返回，不报错，具体口径看返回的 `emptyReason`。
-- **展示完整不截断**：消息文本有多长就展示多长，不得自行省略；正文换行/`|` 等原始字符在结构化字段中原样保留。渲染为表格/卡片时按既有消息展示红线转义 `|`、保留必达 `[必达]` 前缀与媒体可点击链接。
-- **媒体需要登录态**：消息行里的 `media[].previewUrl/downloadUrl` 需登录态访问，直接嵌 Markdown 会 401；要真正查看图片/视频或取回附件，用 `yimiaoban.file.download` 落地到本地（`output` 为明确本地路径、父目录须存在、已存在则拒绝覆盖，图片会按文件头纠正扩展名）。
-- **单页数量、超时与空白消息**：`num` 默认 20、单页上限 50；普通请求 15 秒超时即失败且不重试（上传 15/60 秒）；全空白文本不算内容，禁止发送空白消息（返回 `content_required`）。
-- 写操作一律 `prepare` → 向用户摘要 → 用户确认 → `apply`；`apply` 不接受手工构造的 continuation。
+- **消息以 `msg` JSON 字符串 + `datas[].datas[]` 行结构返回**：CLI 的 `msg.sync.*`/`msg.top.sync` 已把每条消息解析成结构化行（`msgid/sender/time/typeName/content/media/must/fileName/...`），`content` 是可读文本（@ 提及已还原、媒体显示为 `[图片]名称`/`[视频]名称`/`[文件]名称`、必达内容带 `[必达]` 前缀）。解析结果直接使用，不要再本地拼装。
+- **分页口径（与源 skill 一致）**：消息类每页默认 **50** 条、单页上限 **50**；**有界区间（指定了时间范围、默认当天、或显式 `end`/`endId`）自动循环翻页把区间拉完再返回**（最多 100 页，触及上限时返回 `hasMore:true` + `nextStart`）；**无界区间（`latest:true`）只拉一页**，需要更早数据时用 `nextStart` 继续。**会话列表（`session.list`）不参与自动翻页**（默认 20、上限 50，用 `msgid`/`nextMsgid` 翻页）。
+- **时间范围强制收敛到 7 天**：单聊/群聊/系统消息的 `from`/`to` 跨度 > 7 天时，CLI 自动缩短为该范围**最后 7 个自然日**，并在 `data.rangeShrink` 返回 `notice`。**展示结果时必须把这条收敛提示原样转述给用户**，不要静默省略，也不要替用户改小范围。
+- **展示顺序**：消息按消息 id 从新到旧（最新在前）返回；`content` 完整不截断，表格化时自行转义 `|`、保留换行与 `[必达]` 前缀、媒体保持可点击链接。
+- **发送者「我」由 CLI 判定**：`sender` 与当前登录人 IM uid 比对，自己发的消息返回「我」；他人优先消息内 `sname`、其次 hrm 姓名、最后回退 uid。
+- **人名一律由 CLI 走 hrm 解析**（`/api/hrm/common/getEmployeeByIds`），本技能不展示也不依赖 IM 群成员 `name` 字段；群成员接口返回的 `name` 不可信。
+- **本人 IM 身份（cid/uid）只用于本机组装**：`group.search` 的 `members/owner/creator` 条件、撤回消息体、必达消息体、建群自检、消息展示「我」都用 CLI 通过 `teamsCheck` 取得的本人 `imCid`/`imUid`；**它绝不作为请求体操作人字段，也不接受调用方传入**（传 `user`/`sender`/`operator` 会被拒绝：`forbidden_key`）。
+- **uid/cid/群 id 都是 uint64**：JSON 中必须按字符串传（`"1788334281700000004"`），`0` 一律拒绝；`num` 超过 50 会被截断为 50。
+- **时间范围不是服务端过滤条件**：单聊/群聊历史按**消息 id 区间**定位，CLI 把 `from/to` 换算成 `[minId,maxId]`；缺省取当天。`actionMsg.code=1303`（无聊天记录）按**成功空列表**返回（`empty:true` + `emptyReason`），不报错。
+- **媒体需要登录态**：`media[].previewUrl/downloadUrl` 需登录态访问，直接嵌 Markdown 会 401；要真正查看图片/视频或取回附件，用 `im.file.download` 落地到本地（`output` 为明确本地路径、父目录须存在、已存在则拒绝覆盖，图片会按文件头纠正扩展名）。
+- **超时与空白消息**：普通请求 15 秒超时即失败且不重试（上传 15/60 秒）；全空白文本不算内容，禁止发送空白消息（`content_required`）。
 
 ## 写操作决策树（prepare → apply）
 
@@ -76,14 +93,15 @@ weaver-work-cli --json yimiaoban run <operation> --input -
 3. 用户确认后调用 `<op>.apply`，传 `{"confirm":true,"continuation":"<prepare 返回的 token>"}`。
 4. `apply` 返回 `partial` / `write_uncertain` 或网络中断时**立即停止，不自动重试**，先做一次只读回查（如群成员、消息是否已存在）再决定。
 
-任何一步出现登录失效/上下文变化（`context_mismatch`/`continuation_expired`）都回到第一步重新 prepare。
+任何一步出现登录失效/上下文变化（`context_mismatch`/`continuation_expired`/`target_changed`）都回到第一步重新 prepare。
 
 ## 失败处理
 
 - 业务失败看 stderr JSON 的 `error.type` / `error.subtype` / `error.message`，不要用退出码 `0` 判断成功。
-- `code=302` 或认证类错误：引导用户执行 `weaver-work-cli auth login`。
+- `code=302` 或认证类错误（`session_expired`）：按共享规则引导用户重新登录，禁止猜域名或手工拼凭证。
 - 业务语义错误码：`1303` 表示无聊天记录（成功空列表，看 `emptyReason`）；群不存在 `1209`；`members_resolve_failed`/`members_empty` 说明成员解析失败，向用户说明后请其决定是否 `removeFailed:true` 继续；其余码值对照 [`references/error-codes.md`](references/error-codes.md)。
-- 展示给用户时保持"完整不截断"红线，参考 [`references/safety-boundaries.md`](references/safety-boundaries.md)。
+- `alias_conflict`：旧字段（如 `filePath`/`shareGroups`）与新字段同时出现且取值不一致，请只保留一个。
+- 展示给用户时保持「完整不截断」红线，参考 [`references/safety-boundaries.md`](references/safety-boundaries.md)。
 
 ## 平台兼容
 
@@ -92,13 +110,13 @@ weaver-work-cli --json yimiaoban run <operation> --input -
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":20,"latest":true}'
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":20,"latest":true}'
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
 ```
 
-复杂 JSON 建议保存为 UTF-8 文件后按平台传给 `--input <file>`。
+复杂 JSON 建议保存为 UTF-8 文件后按平台传给 `--input <file>`；Windows PowerShell 下不要使用 `printf`、`~/` 路径或反斜杠续行。

package/skills/weaver-e10-yimiaoban/references/ding-write.md

@@ -6,7 +6,7 @@
 
 | operation 对 | 动作 |
 | --- | --- |
-| `yimiaoban.ding.send.prepare` / `.apply` | 发普通必达 或 已有消息转必达（走 `/api/em/msg/createDing`，非 executeIm） |
+| `im.ding.send.prepare` / `.apply` | 发普通必达 或 已有消息转必达（走 `/api/em/msg/createDing`，非 executeIm） |
 
 ## 场景与输入要点
 
@@ -30,15 +30,15 @@
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.prepare --input-json '{"groupId":"1788334281700000004","txt":"请今天下班前确认三季度预算"}'
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.prepare --input-json '{"groupId":"1788334281700000004","convertMsgid":"9000000000000000001","unreadOnly":true}'
+weaver-work-cli --json im run im.ding.send.prepare --input-json '{"groupId":"1788334281700000004","txt":"请今天下班前确认三季度预算"}'
+weaver-work-cli --json im run im.ding.send.prepare --input-json '{"groupId":"1788334281700000004","convertMsgid":"9000000000000000001","unreadOnly":true}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.prepare --input-json '{"groupId":"1788334281700000004","txt":"请今天下班前确认三季度预算"}'
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.prepare --input-json '{"groupId":"1788334281700000004","convertMsgid":"9000000000000000001","unreadOnly":true}'
+weaver-work-cli --json im run im.ding.send.prepare --input-json '{"groupId":"1788334281700000004","txt":"请今天下班前确认三季度预算"}'
+weaver-work-cli --json im run im.ding.send.prepare --input-json '{"groupId":"1788334281700000004","convertMsgid":"9000000000000000001","unreadOnly":true}'
 ```
 
 向用户展示 prepare 的 `summary`（动作=发送必达/转必达、目标=群/单聊、是否全体/未读/指定人、是否发短信），确认后：
@@ -46,20 +46,20 @@ weaver-work-cli --json yimiaoban run yimiaoban.ding.send.prepare --input-json '{
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+weaver-work-cli --json im run im.ding.send.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.ding.send.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+weaver-work-cli --json im run im.ding.send.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
 ```
 
 ## 注意
 
 - 必达是**高打扰**动作：默认全体成员 + 发短信，必须向用户明确说明接收范围和短信费用，经确认后才 apply。
 - `unreadOnly:true` 转必达依赖目标消息存在且群内有未读人员；源消息找不到（`source_not_found`）或全员已读（`unread_empty`）都会失败，按错误向用户说明，不自动回退全员。
-- apply 不确定（网络/超时）时停止，用 `yimiaoban.msg.top.sync`/拉群消息或系统消息只读回查必达是否已发出，**不自动重试**（避免重复必达）。
+- apply 不确定（网络/超时）时停止，用 `im.msg.top.sync`/拉群消息或系统消息只读回查必达是否已发出，**不自动重试**（避免重复必达）。
 
 ## 失败处理
 

package/skills/weaver-e10-yimiaoban/references/error-codes.md

@@ -41,6 +41,7 @@
 | 1233 / 1237 / 1246 | 部门群/全员群/事项群已存在 | 普通群建群不涉及；如需其他类型请在客户端操作 |
 | 1269 / 1270 | 创建群聊功能关闭 / 超过每日建群上限 | 联系管理员或改日再试 |
 | 1271 | 加入群需要对方同意 | 属于审批流程，等待管理员/群主处理 |
+| 1210（退群后） | 退出群聊后再对同一群执行 `join` / `destroy` 会被拒绝 | 群主或最后一人退群会让群变成无主空群，只能由客户端或管理员处理；`group.exit.prepare` 已内置该风险护栏 |
 
 ## 消息相关
 
@@ -72,6 +73,7 @@
 | subtype | 含义与处理 |
 |---|---|
 | `forbidden_key` | 输入含操作人字段（`user`/`sender`/`creator` 等），去掉后重试 |
+| `alias_conflict` | 旧字段（`filePath`/`shareGroups`）与新字段（`file`/`shareGroup`）同时出现且取值不一致，只保留一个 |
 | `id_invalid` / `id_required` | uid/cid/群 id 缺失、为 0 或非数字 |
 | `content_required` | 发送内容为空（含全空白文本）或必达既无 `txt` 也无 `convertMsgid` |
 | `content_conflict` | 一次只允许一种媒体（`img` 与 `file` 不能同时传） |
@@ -81,5 +83,19 @@
 | `unread_only_group_only` | `unreadOnly` 仅支持群聊转必达 |
 | `source_not_found` / `source_invalid` / `unread_empty` | 转必达源消息缺失/无法解析、群内无未读人员（不自动回退全员） |
 | `self_not_included` | 建群成员必须包含操作者自己 |
+| `owner_exit_ack_required` | 群主或最后一个成员退群未传 `acknowledgeOrphanRisk:true`（退群后群会变成无主空群，无法再 join/destroy） |
 | `output_required` / `output_parent_missing` / `output_exists` | `file.download` 输出路径缺失、父目录不存在、目标已存在（拒绝覆盖） |
 | `context_mismatch` / `continuation_expired` / `target_changed` | 确认上下文变化/过期/目标变化，重新 `prepare` |
+| `self_identity_missing` / `self_identity_incomplete` | 当前登录态解析不到本人 `imCid`/`imUid`（`group.search` 的 members/owner/creator、撤回、必达、建群自检需要），按共享规则重新登录后重试；**不要用 0 兜底** |
+| `num_invalid` / `time_invalid` | `num` 非正整数，或时间参数无法解析（支持 unix 秒 / `YYYY-MM-DD` / `YYYY-MM-DD HH:mm:ss`） |
+| `session_type_invalid` / `reminder_invalid` | 会话提醒设置（`im.user.setRemind`）的 `sessionType` 不是 `1` 单聊会话 / `2` 群聊会话 / `4` 系统会话，或 `reminder` 不是 `0` 接收提醒 / `1` 免打扰 |
+| `target_required` 补充 | 会话免打扰目标缺失：单聊会话缺 `toUid`/`toCid`、群聊会话缺 `groupId`、系统会话缺 `group` |
+
+## 拉取口径相关的成功语义（非错误）
+
+| 现象 | 说明 |
+| --- | --- |
+| `data.empty=true` + `emptyReason` | `actionMsg.code=1303`（无聊天记录）按成功空列表返回，用 `emptyReason` 说明是"当天无消息/时间范围无消息/会话无历史" |
+| `data.rangeShrink.notice` | 时间范围跨度 > 7 天时自动收敛为该范围最后 7 天，**必须把 notice 转述给用户** |
+| `data.pages` / `data.autoPaged` / `data.hasMore` / `data.nextStart` | 本次实际拉了几页、是否自动翻页、是否还有更早数据、续拉锚点（有界区间自动翻页最多 100 页） |
+| `data.hasMore=true` 且 `cappedAtMaxPages=true` | 已达单次自动翻页上限，用 `nextStart` 显式续拉 |

package/skills/weaver-e10-yimiaoban/references/field-resolution.md

@@ -12,10 +12,10 @@
 
 | 对象 | 解析方式 | 产出 |
 | --- | --- | --- |
-| 人员 | `yimiaoban.person.resolve`（姓名/工号/手机/邮箱模糊，走 hrm） | `uid`、`cid`（**成对使用**，对方 cid 可能与本人不同） |
-| 人员（批量） | `yimiaoban.person.resolveByIds`（uid 列表 → 姓名/部门/cid） | 姓名、`cid`、部门、岗位 |
-| 群聊 | `yimiaoban.group.search`（`name` + `precise:true` 精确匹配） | `id`（群 id） |
-| 系统消息分组 | `yimiaoban.sysmsg.groupSearch`（名称模糊） | `groupId`、`typesIds` |
+| 人员 | `im.person.resolve`（姓名/工号/手机/邮箱模糊，走 hrm） | `uid`、`cid`（**成对使用**，对方 cid 可能与本人不同） |
+| 人员（批量） | `im.person.resolveByIds`（uid 列表 → 姓名/部门/cid） | 姓名、`cid`、部门、岗位 |
+| 群聊 | `im.group.search`（`name` + `precise:true` 精确匹配） | `id`（群 id） |
+| 系统消息分组 | `im.sysmsg.groupSearch`（名称模糊） | `groupId`、`typesIds` |
 
 解析优先级：① 本对话已出现的实体直接复用（已解析的 uid/cid、已拉取会话里的群 id）；② 精确匹配；③ 模糊搜索 + 消歧。**禁止跳过前两步直接全量模糊搜索。**
 
@@ -38,9 +38,9 @@
 
 | 上游操作（产出） | 提取字段 | 下游操作（消费） |
 | --- | --- | --- |
-| `yimiaoban.person.resolve` | `uid`、`cid` | `msg.send.single`（`toUid`/`toCid`）、`msg.sync.single`（`fromUid`/`fromCid`）、`ding.send`（单聊 `toUid`/`toCid`）、`group.invite`/`group.kick`/`group.create`（`users`） |
-| `yimiaoban.group.search` / `group.info` | `groupId` | `msg.sync.group`、`msg.send.group`、`ding.send`（群）、`group.users`/`group.admins`/`group.invite`/`group.kick`/`group.exit`/`group.destroy`/`group.modify`/`group.rename`/`group.announce.*` |
-| `yimiaoban.session.list` | 会话类型、`fuser.uid/cid`（单聊）、`lastMsgid`（翻页锚点）、系统会话 `group` | `msg.sync.single` / `msg.sync.group` / `sysmsg.query`；翻页传 `msgid` |
-| `yimiaoban.msg.sync.*` / `msg.top.sync` | `messages[].msgid`（`ser_msgid`）、`media[].fileId`、`nextStart` | `msg.withdraw`（`msgid`）、`msg.top.set`（`msgid`）、`ding.send`（`convertMsgid`）、`file.download`（`fileId`+`msgid`）、下一页 `start`/`startId` |
-| `yimiaoban.sysmsg.groupSearch` / `sysmsg.typeSync` | `groupId`、`typeId` | `sysmsg.query`（`group`/`type`） |
-| `yimiaoban.file.upload` | `fileObj.id` | 发消息的 `img`/`file`（或直接用本地路径让 CLI 内部上传） |
+| `im.person.resolve` | `uid`、`cid` | `msg.send.single`（`toUid`/`toCid`）、`msg.sync.single`（`fromUid`/`fromCid`）、`ding.send`（单聊 `toUid`/`toCid`）、`group.invite`/`group.kick`/`group.create`（`users`） |
+| `im.group.search` / `group.info` | `groupId` | `msg.sync.group`、`msg.send.group`、`ding.send`（群）、`group.users`/`group.admins`/`group.invite`/`group.kick`/`group.exit`/`group.destroy`/`group.modify`/`group.rename`/`group.announce.*` |
+| `im.session.list` | 会话类型、`fuser.uid/cid`（单聊）、`lastMsgid`（翻页锚点）、系统会话 `group` | `msg.sync.single` / `msg.sync.group` / `sysmsg.query`；翻页传 `msgid` |
+| `im.msg.sync.*` / `msg.top.sync` | `messages[].msgid`（`ser_msgid`）、`media[].fileId`、`nextStart` | `msg.withdraw`（`msgid`）、`msg.top.set`（`msgid`）、`ding.send`（`convertMsgid`）、`file.download`（`fileId`+`msgid`）、下一页 `start`/`startId` |
+| `im.sysmsg.groupSearch` / `sysmsg.typeSync` | `groupId`、`typeId` | `sysmsg.query`（`group`/`type`） |
+| `im.file.upload` | `fileObj.id` | 发消息的 `img`/`file`（或直接用本地路径让 CLI 内部上传） |

package/skills/weaver-e10-yimiaoban/references/file-user-i18n.md

@@ -6,15 +6,15 @@
 
 | operation | 用途 |
 | --- | --- |
-| `yimiaoban.file.upload` | 上传本地文件（module=im），返回 fileObj + 消息对象形态（供 `img`/`file` 引用） |
-| `yimiaoban.file.preview` | 生成图片/视频预览与下载 URL（需登录态访问；图片支持 small/large/original） |
-| `yimiaoban.file.download` | 把消息里的图片/视频/文件**下载到本地**（需登录态；父目录须存在、拒绝覆盖） |
-| `yimiaoban.user.state` | 查指定人员各在线设备状态（sub_state 强制 0 不订阅） |
-| `yimiaoban.i18n.labels` | 批量翻译国际化标签 id → 当前语言文案 |
+| `im.file.upload` | 上传本地文件（module=im），返回 fileObj + 消息对象形态（供 `img`/`file` 引用） |
+| `im.file.preview` | 生成图片/视频预览与下载 URL（需登录态访问；图片支持 small/large/original） |
+| `im.file.download` | 把消息里的图片/视频/文件**下载到本地**（需登录态；父目录须存在、拒绝覆盖） |
+| `im.user.state` | 查指定人员各在线设备状态（sub_state 强制 0 不订阅） |
+| `im.i18n.labels` | 批量翻译国际化标签 id → 当前语言文案 |
 
 ## 输入要点
 
-- `file.upload`：`file` 本地路径（兼容旧名 `filePath`）+ 可选 `name`/`shareGroup`（发群消息用，兼容 `shareGroups`）/`shareUsers`（uid 数组，发单聊用）/`permission`。返回 `fileObj`、`img`、`file` 两种消息对象形态；发消息也可以直接传本地路径让 CLI 内部上传。
+- `file.upload`：`file` 本地路径 + 可选 `name`/`shareGroup`（发群消息用）/`shareUsers`（uid 数组，发单聊用）/`permission`。旧名 `filePath`（= `file`）与 `shareGroups`（= `shareGroup`）仍兼容，但**与新名同时出现且取值不一致会返回 `alias_conflict`**（不要依赖静默覆盖）。返回 `fileObj`、`img`、`file` 两种消息对象形态；发消息也可以直接传本地路径让 CLI 内部上传。
 - `file.preview`：需要 `fileId` + `msgid` + `kind`(img/video) + 场景（`groupId` 或 `toUid`+`toCid`）；`imgFormat` small/large/original。返回的是**绝对地址**（含 baseUrl），但需要登录态才能访问，直接嵌 Markdown 会 401。
 - `file.download`：`fileId` + `msgid` + `output`（明确的本地文件路径）+ 场景（`groupId` 或 `toUid`+`toCid`）；可选 `kind`（img/video/file，默认 img）、`imgFormat`（默认 small，要原图传 original）。父目录必须存在，目标文件已存在会拒绝覆盖；下载内容若是图片且扩展名与文件头不符会自动纠正（如实际为 PNG 时 `.jpg` → `.png`，返回 `renamedFrom`）。
 - 用户状态：`users` uid 数组（不要写成 `uids`）+ 可选 `devType` 过滤；`mask` 控制返回字段（默认 7）。解析失败的 uid 需确认后传 `removeFailed:true` 跳过。
@@ -26,17 +26,17 @@
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.file.upload --input-json '{"file":"C:\\tmp\\方案.docx","name":"方案.docx"}'
-weaver-work-cli --json yimiaoban run yimiaoban.file.download --input-json '{"fileId":"FILE1","msgid":"1788334281700000004","kind":"img","groupId":"1788334281700000004","output":"C:\\tmp\\photo.png"}'
-weaver-work-cli --json yimiaoban run yimiaoban.i18n.labels --input-json '{"ids":["1001","1002"]}'
+weaver-work-cli --json im run im.file.upload --input-json '{"file":"C:\\tmp\\方案.docx","name":"方案.docx"}'
+weaver-work-cli --json im run im.file.download --input-json '{"fileId":"FILE1","msgid":"1788334281700000004","kind":"img","groupId":"1788334281700000004","output":"C:\\tmp\\photo.png"}'
+weaver-work-cli --json im run im.i18n.labels --input-json '{"ids":["1001","1002"]}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.file.upload --input-json '{"file":"/tmp/方案.docx","name":"方案.docx"}'
-weaver-work-cli --json yimiaoban run yimiaoban.file.download --input-json '{"fileId":"FILE1","msgid":"1788334281700000004","kind":"img","groupId":"1788334281700000004","output":"/tmp/photo.png"}'
-weaver-work-cli --json yimiaoban run yimiaoban.i18n.labels --input-json '{"ids":["1001","1002"]}'
+weaver-work-cli --json im run im.file.upload --input-json '{"file":"/tmp/方案.docx","name":"方案.docx"}'
+weaver-work-cli --json im run im.file.download --input-json '{"fileId":"FILE1","msgid":"1788334281700000004","kind":"img","groupId":"1788334281700000004","output":"/tmp/photo.png"}'
+weaver-work-cli --json im run im.i18n.labels --input-json '{"ids":["1001","1002"]}'
 ```
 
 ## 输出处理

package/skills/weaver-e10-yimiaoban/references/group-read.md

@@ -6,14 +6,14 @@
 
 | operation | 用途 |
 | --- | --- |
-| `yimiaoban.group.search` | 按条件搜群（`name`/`type`/`members`/`owner`/`creator`/`today`/`yesterday`/`createBegin`/`createEnd`，服务端过滤） |
-| `yimiaoban.group.info` | 群基础信息（`groupIds` 数组或 `groupId`，支持批量） |
-| `yimiaoban.group.users` | 群成员列表（`groupId`；`syncType` 0 全量/1 增量 + `clientUc` 游标） |
-| `yimiaoban.group.admins` | 群主/管理员批量获取（`mask` 位 1=群主/负责人、2=管理员，默认 3） |
-| `yimiaoban.group.exist` | 群是否存在（ret=0 存在；1209 不存在） |
-| `yimiaoban.group.userExist` | 某用户是否在群内 |
-| `yimiaoban.group.announce.get` | 群公告（`aid` 不传/0 = 最新） |
-| `yimiaoban.group.announce.list` | 公告列表（id 降序，`end_flag` 表示是否还有下一页） |
+| `im.group.search` | 按条件搜群（`name`/`type`/`members`/`owner`/`creator`/`today`/`yesterday`/`createBegin`/`createEnd`，服务端过滤） |
+| `im.group.info` | 群基础信息（`groupIds` 数组或 `groupId`，支持批量） |
+| `im.group.users` | 群成员列表（`groupId`；`syncType` 0 全量/1 增量 + `clientUc` 游标） |
+| `im.group.admins` | 群主/管理员批量获取（`mask` 位 1=群主/负责人、2=管理员，默认 3） |
+| `im.group.exist` | 群是否存在（ret=0 存在；1209 不存在） |
+| `im.group.userExist` | 某用户是否在群内 |
+| `im.group.announce.get` | 群公告（`aid` 不传/0 = 最新） |
+| `im.group.announce.list` | 公告列表（id 降序，`end_flag` 表示是否还有下一页） |
 
 ## 输入要点
 
@@ -28,23 +28,23 @@
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.group.search --input-json '{"members":true,"pageSize":100}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.users --input-json '{"groupId":"1788334281700000004"}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.info --input-json '{"groupIds":["1788334281700000004"]}'
+weaver-work-cli --json im run im.group.search --input-json '{"members":true,"pageSize":100}'
+weaver-work-cli --json im run im.group.users --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.group.info --input-json '{"groupIds":["1788334281700000004"]}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.group.search --input-json '{"members":true,"pageSize":100}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.users --input-json '{"groupId":"1788334281700000004"}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.info --input-json '{"groupIds":["1788334281700000004"]}'
+weaver-work-cli --json im run im.group.search --input-json '{"members":true,"pageSize":100}'
+weaver-work-cli --json im run im.group.users --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.group.info --input-json '{"groupIds":["1788334281700000004"]}'
 ```
 
 ## 输出处理
 
-- 群搜索结果量大时按共享规则汇总渲染（列群名/id/人数/类型），不要整表倾倒。
-- 成员列表渲染姓名走 `data.members[].name`（hrm 解析结果），角色取 `roleName`、入群时间取 `addTime`。展示大群成员时按需分页输出。
+- 群搜索结果：`data.groups[]` 每行是 `id`（群 id）/`name`/`type`/`num`（群人数）/`createTime`；结果量大时按共享规则汇总渲染（列群名/id/人数/类型），不要整表倾倒。
+- 成员列表：`data.members[].name` 是 hrm 解析结果，角色取 `roleName`、入群时间取 `addTime`；响应还带 `totalNum`（成员总数）、`endFlag`、`serverUc`（增量同步游标）。展示大群成员时按需分页输出。
 - 「谁在群里」用 `group.userExist`：返回 `users[].inGroup` 布尔，便于区分在群/不在群。
 - 群公告内容同样"完整展示不截断"。
 

package/skills/weaver-e10-yimiaoban/references/group-write.md

@@ -6,15 +6,15 @@
 
 | operation 对 | 动作 |
 | --- | --- |
-| `yimiaoban.group.create.prepare` / `.apply` | 创建普通群 |
-| `yimiaoban.group.invite.prepare` / `.apply` | 邀请成员入群 |
-| `yimiaoban.group.kick.prepare` / `.apply` | 踢出群成员 |
-| `yimiaoban.group.exit.prepare` / `.apply` | 退出群聊 |
-| `yimiaoban.group.destroy.prepare` / `.apply` | **解散群聊**（仅群主，不可恢复） |
-| `yimiaoban.group.join.prepare` / `.apply` | 申请加入群聊（`groupId` 或 `token`） |
-| `yimiaoban.group.modify.prepare` / `.apply` | 批量改群属性（人数/开关/管理员/转让群主等，batModGroupInfo） |
-| `yimiaoban.group.rename.prepare` / `.apply` | 单字段改群信息（群名/历史/群主/显示/打扰/标记/gtid） |
-| `yimiaoban.group.announce.modify.prepare` / `.apply` | 新增/修改/删除群公告 |
+| `im.group.create.prepare` / `.apply` | 创建普通群 |
+| `im.group.invite.prepare` / `.apply` | 邀请成员入群 |
+| `im.group.kick.prepare` / `.apply` | 踢出群成员 |
+| `im.group.exit.prepare` / `.apply` | 退出群聊 |
+| `im.group.destroy.prepare` / `.apply` | **解散群聊**（仅群主，不可恢复） |
+| `im.group.join.prepare` / `.apply` | 申请加入群聊（`groupId` 或 `token`） |
+| `im.group.modify.prepare` / `.apply` | 批量改群属性（人数/开关/管理员/转让群主等，batModGroupInfo） |
+| `im.group.rename.prepare` / `.apply` | 单字段改群信息（群名/历史/群主/显示/打扰/标记/gtid） |
+| `im.group.announce.modify.prepare` / `.apply` | 新增/修改/删除群公告 |
 
 ## 输入要点
 
@@ -26,21 +26,22 @@
 - 建群成功返回新建群 `groupId`（服务端字段 `group_id`）与 `rawData`；`group.announce.modify` 新增/修改返回 `aid`，删除返回被删除的 `aid` 且 `deleted:true`。
 - 公告：`annouce` 内容；`aid` 缺省/0=新增、非 0=修改、`del:true`+`aid`=删除。`notice` 0 发通知(默认)/1 不发/2 发并@全体；`fmark` 新人必看。
 - 群 id 一律字符串非 0。
+- **加入群（`group.join`）是"提交申请"而不是"立即进群"**（联机实测）：`apply` 成功会返回 `flag:0` + `note:"需管理员/群主审批"`，真正入群要等群主/管理员审批；若该群已无成员或不允许申请，会直接业务失败 `1210 没有权限`。申请后不要反复重试，也不要自行猜测是否已入群，用 `group.userExist` 复核。
 
 ## 命令
 
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.group.invite.prepare --input-json '{"groupId":"1788334281700000004","users":["100234","100235"]}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.rename.prepare --input-json '{"groupId":"1788334281700000004","name":"季度评审群"}'
+weaver-work-cli --json im run im.group.invite.prepare --input-json '{"groupId":"1788334281700000004","users":["100234","100235"]}'
+weaver-work-cli --json im run im.group.rename.prepare --input-json '{"groupId":"1788334281700000004","name":"季度评审群"}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.group.invite.prepare --input-json '{"groupId":"1788334281700000004","users":["100234","100235"]}'
-weaver-work-cli --json yimiaoban run yimiaoban.group.rename.prepare --input-json '{"groupId":"1788334281700000004","name":"季度评审群"}'
+weaver-work-cli --json im run im.group.invite.prepare --input-json '{"groupId":"1788334281700000004","users":["100234","100235"]}'
+weaver-work-cli --json im run im.group.rename.prepare --input-json '{"groupId":"1788334281700000004","name":"季度评审群"}'
 ```
 
 向用户展示 `summary`（动作/群/人数/变更字段），确认后：
@@ -48,18 +49,19 @@ weaver-work-cli --json yimiaoban run yimiaoban.group.rename.prepare --input-json
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.group.invite.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+weaver-work-cli --json im run im.group.invite.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.group.invite.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+weaver-work-cli --json im run im.group.invite.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
 ```
 
 ## 注意
 
 - 踢人、解散、转让群主都是不可逆/高影响动作，summary 必须讲清对象与后果，等用户明确确认。
+- **退群（`group.exit`）有护栏**：`prepare` 会只读回查群人数与群主；当你**是群主**或**是群里最后一个成员**时，必须显式传 `acknowledgeOrphanRisk:true` 才会签发 continuation，否则返回 `owner_exit_ack_required`。原因（联机实测）：这两种情形退群后群会变成**无主空群**，之后 `group.join` / `group.destroy` 都会被服务端拒绝（`1210 没有权限`），只能由客户端或管理员处理——不要为了"演练"随意退掉自己建的群。
 - 退群/解散/踢人前可先 `group.users` 只读回查当前成员与身份，避免误操作。
 - apply 阶段只传 `confirm:true` + continuation；业务参数以 prepare 快照为准。
 - 不确定结果（partial/超时）时**不自动重试**，先 `group.info`/`group.users` 回查实际状态。

package/skills/weaver-e10-yimiaoban/references/msg-read.md

@@ -6,18 +6,19 @@
 
 | operation | 用途 |
 | --- | --- |
-| `yimiaoban.msg.sync.single` | 拉单聊消息（必填 `fromUid`+`fromCid`，为**对方**身份） |
-| `yimiaoban.msg.sync.group` | 拉群聊消息（必填 `groupId`；type=0 由 CLI 固定，无需传） |
-| `yimiaoban.msg.top.sync` | 群置顶消息摘要 + 内容（必填 `groupId`） |
-| `yimiaoban.msg.read.single` | 单聊消息阅读状态（`msgids`=自己发出 / `recvMsgids`=自己接收） |
-| `yimiaoban.msg.read.group` | 群消息阅读汇总（每条已读/未读情况） |
-| `yimiaoban.msg.read.group.detail` | 群阅读详情（unread/read 数 + 每人状态，支持分页） |
+| `im.msg.sync.single` | 拉单聊消息（必填 `fromUid`+`fromCid`，为**对方**身份） |
+| `im.msg.sync.group` | 拉群聊消息（必填 `groupId`；type=0 由 CLI 固定，无需传） |
+| `im.msg.top.sync` | 群置顶消息摘要 + 内容（必填 `groupId`） |
+| `im.msg.read.single` | 单聊消息阅读状态（`msgids`=自己发出 / `recvMsgids`=自己接收） |
+| `im.msg.read.group` | 群消息阅读汇总（每条已读/未读情况） |
+| `im.msg.read.group.detail` | 群阅读详情（unread/read 数 + 每人状态，支持分页） |
 
 ## 输入要点
 
-- `fromUid`/`fromCid`/`groupId` 必须是**字符串数字**，禁止 `0`。对方 uid/cid 用 `yimiaoban.person.resolve`（按姓名/工号/手机/邮箱）先拿到，不要猜。
-- 单页 `num` 默认 20、上限 50。**CLI 只返回一页**，不自动翻页。
-- 时间范围：`from`/`to` 支持 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`、unix 秒。默认当天。要跨天拉取必须显式给 `from`/`to`（内部换算成消息 id 区间）；给 `latest:true` 则忽略日期拉最新一页。
+- `fromUid`/`fromCid`/`groupId` 必须是**字符串数字**，禁止 `0`。对方 uid/cid 用 `im.person.resolve`（按姓名/工号/手机/邮箱）先拿到，不要猜。
+- 每页 `num` 默认 **50**、单页上限 **50**（超过会被截断为 50）。
+- **翻页口径**：**有界区间**（给了 `from`/`to`、缺省当天、或显式 `end`/`endId`）→ CLI 在该区间内**自动循环翻页拉完再返回**（最多 100 页；触及上限时 `hasMore:true` + `nextStart`）；**无界区间**（`latest:true`）→ **只拉一页**，需要更早数据时把 `nextStart` 作为下一次的 `start`/`startId` 再请求。
+- 时间范围：`from`/`to` 支持 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`、unix 秒；缺省为当天。**跨度 > 7 天时 CLI 自动收敛为该范围最后 7 个自然日**，并在 `data.rangeShrink.notice` 给出提示——**必须把这条提示转述给用户**（例如"拉上个月"→实际只拉最后 7 天）。要覆盖更早历史时按 ≤ 7 天分段多次调用。
 - 显式 id 区间优先级最高：单聊用 `start`/`end`，群聊用 `startId`/`endId`（消息 id 即 `ser_msgid`，取自上页首/尾行）。
 - `imgFormat`：`small`（默认）`large`/`original`，决定图片预览 URL 规格。
 
@@ -26,30 +27,33 @@
 Windows PowerShell：
 
 ```powershell
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":20,"latest":true}'
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.single --input-json '{"fromUid":"100234","fromCid":"102","from":"2026-08-01","to":"2026-08-31"}'
-weaver-work-cli --json yimiaoban run yimiaoban.msg.top.sync --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
+weaver-work-cli --json im run im.msg.sync.single --input-json '{"fromUid":"100234","fromCid":"102","from":"2026-08-01","to":"2026-08-31"}'
+weaver-work-cli --json im run im.msg.top.sync --input-json '{"groupId":"1788334281700000004"}'
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":20,"latest":true}'
-weaver-work-cli --json yimiaoban run yimiaoban.msg.sync.single --input-json '{"fromUid":"100234","fromCid":"102","from":"2026-08-01","to":"2026-08-31"}'
-weaver-work-cli --json yimiaoban run yimiaoban.msg.top.sync --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
+weaver-work-cli --json im run im.msg.sync.single --input-json '{"fromUid":"100234","fromCid":"102","from":"2026-08-01","to":"2026-08-31"}'
+weaver-work-cli --json im run im.msg.top.sync --input-json '{"groupId":"1788334281700000004"}'
 ```
 
 ## 输出处理
 
 - `data.messages[]` 是已解析的结构化行：`sender`（姓名，走 hrm）、`time`、`typeName`（文本/图片/视频/文件…）、`content`（完整文本，不截断）、`media`（图片/视频/文件的预览与下载 URL，需登录态访问）、`must`（必达标记，`true` 展示加 `[必达]` 前缀）等。
+- 顺序：消息按消息 id **从新到旧**（最新在最前）返回。
+- 分页字段：`pages`（本次实际拉了几页）、`autoPaged`（是否走了自动翻页）、`pageSize`、`exhausted`、`hasMore`、`nextStart`（还有更早数据时的续拉锚点）、`range.scope`（`today`/`range`/`latest`/`explicit-id`）、`rangeShrink`（7 天收敛提示）。
 - `sender` 为自己时显示「我」（CLI 用会话 uid 判定）；媒体消息的 `content` 形如 `[图片]a.png` / `[视频]b.mp4` / `[文件]c.pdf`，同时单列 `fileName` 便于渲染。
 - 展示整段消息**不自行截断**；若将多行渲染进表格，保留换行提示、把 `|` 转义，媒体链接保留为可点击的 Markdown 链接。
-- `data.hasMore` 为 `true` 时用返回的 `data.nextStart`（本页最小 `ser_msgid`）作为下页 `start`/`startId` 再请求；**服务端会重复返回该边界消息，务必按 `msgid` 去重**。除非用户明确要连续翻页，否则只交付当前页并告知还有更早内容。
+- `data.hasMore=true` 时用 `data.nextStart`（本次最小 `ser_msgid`）作为下页 `start`/`startId` 再请求（保持同一时间范围）；CLI 已按 `msgid` 去重服务端重复返回的边界消息。**不要**为了"统计总数"而反复续拉（见 [`safety-boundaries.md`](safety-boundaries.md) 红线）。
 - `data.empty=true` 表示本次为空页（`actionMsg.code=1303`）：按成功处理，用 `data.emptyReason` 向用户说明口径（当天无消息 / 该时间范围无消息 / 该会话暂无任何消息记录），不要当报错重试。
+- 展示口径必须写明本次实际范围（如"默认拉了今天，共 N 条"或"已自动收敛为 2026-09-09~2026-09-15，自动翻页拉完共 N 条"）。
 
 ## 注意
 
-- 消息内容可能较长（含敏感业务信息），返回内容会进入大模型上下文；拉取范围默认当天，跨天/全量必须经用户确认。
+- 消息内容可能较长（含敏感业务信息），返回内容会进入大模型上下文；缺省范围是当天，跨天大量拉取前先和用户确认口径（"拉全部历史"要分段，不要指望一次拉完）。
 - 群聊必须给 `type=0` 是内部固定行为，接口文档要求，无需业务传入。
 
 ## 失败处理