@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.4e64c13 → 0.1.0-dev.5abff3b

package/miaoda-modern/lark-apps-ops/references/lark-apps-user-id-convert.md

@@ -0,0 +1,63 @@
+# apps +user-id-convert
+
+把一批已知 ID 在**妙搭 user_id** 与**飞书开放平台 ID**（open_id / union_id / 飞书 user_id）之间互转。运行时命令事实以 `lark-cli apps +user-id-convert --help` 为准。
+
+## 何时用
+
+沙箱里常通过 `contact` / `im` 域拿到飞书 `open_id`，但下游（妙搭插件、审批、网关）消费的是妙搭 `user_id` 或飞书 `user_id`。这个命令补上中间那一步转换。典型场景：
+
+- feishu-approval 插件要发起审批，`createApprovalInstance` 需要飞书 `user_id`，而手里只有妙搭 `user_id` → 用 `miaoda-to-feishu-user-id`。
+- 插件配置表单 / 人员选择器返回 `open_id`，但最终要落库妙搭 `user_id` → 用 `open-id-to-miaoda`。
+
+它只做一件事——转换。**没有**本地映射表、缓存、权限预判，也不猜方向。它不替代权限校验：能不能拿到目标 ID 仍由上游 scope 和文档/审批自身的可见范围决定，本命令只转换一个已知 ID 的格式。
+
+## 命令骨架
+
+- 必填 `--convert-type`：转换方向枚举，缺失或非法直接报可读的校验错误，不猜默认方向。
+- 必填 `--ids`：逗号分隔，或 `@文件` / `-`（stdin）。每次 1–100 个（服务端上限 100；CLI 额外拒绝空批以免空跑）。**不去重**，按输入顺序返回。
+- 只读命令，无写副作用，不需要 `--yes`。
+- 需要 scope `spark:directory.user.id_convert:read`。限流 50 req/s，CLI 不自动重试。
+
+### `--convert-type` 方向表
+
+| `--convert-type` | 含义 | 目标形态 |
+| --- | --- | --- |
+| `miaoda-to-open-id` | 妙搭 user_id → 飞书 Open ID | `ou_…` |
+| `miaoda-to-union-id` | 妙搭 user_id → 飞书 Union ID | `on_…` |
+| `open-id-to-miaoda` | 飞书 Open ID → 妙搭 user_id | 数字串 |
+| `union-id-to-miaoda` | 飞书 Union ID → 妙搭 user_id | 数字串 |
+| `miaoda-to-feishu-user-id` | 妙搭 user_id → 飞书 user_id | 数字（employee_id） |
+
+## 示例
+
+```bash
+# 批量把 open_id 转妙搭 user_id
+lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids ou_abc123,ou_def456
+
+# 从 stdin 读 ID 列表
+printf 'ou_abc123,ou_def456' | lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids -
+
+# 只看将要发送的请求体，不真正调用
+lark-cli apps +user-id-convert --convert-type miaoda-to-feishu-user-id --ids 1234567890123456 --dry-run
+```
+
+## 输出契约
+
+标准 apps stdout 信封，agent 用 `ok == true` 判成功（不是 `code == 0`）。响应字段保持服务端 `snake_case`。
+
+- `data.convert_type`：回显所传的 `--convert-type`。
+- `data.items[]`：`{index, source_id, target_id}`，`index` 是该 ID 在 `--ids` 中的 0 基位置。
+- `data.missed[]`：服务端静默丢弃的未解析 ID，CLI 用输入位置 diff 重建，`{index, source_id, reason: "not_found"}`。
+- `meta`：`{total, hit_count, missed_count}`，`total` = `--ids` 输入数（含重复，不去重），且 `hit_count + missed_count = total`。
+
+**部分命中**：批量里只要有 ID 转不出，它不是错误——服务端省略该项，CLI 把它落到 `missed`（`reason: not_found`），并保留 `index` = 输入位置，重复 ID 也能按位置回填。
+
+## Agent 规则
+
+- **方向不匹配不是错误**：比如在 `miaoda-to-open-id` 下传了 `ou_` 开头的 ID，服务端省略它 → 落到 `missed`。看到 `missed` 时先检查 ID 前缀是否与 `--convert-type` 方向一致。
+- **整批被拒**（服务端 `code != 0`）才是 `api` 错误，带透传 code 和 `log_id`，不重试；限流同理，降低调用频率。
+- 结果只在 stdout 返回一次，不落盘、不写会话上下文。
+
+## 边界
+
+只转换 ID 格式，不判断调用方是否有权拿到目标 ID。是否有权限由上游 scope 与资源自身可见范围决定，本命令不做预检。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.0-dev.4e64c13",
+  "version": "0.1.0-dev.5abff3b",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [

package/shared/lark-cli/SKILL.md

@@ -96,7 +96,7 @@ lark-cli docs +search --query "<关键词>"
 ### drive —— 云盘盘点与评论/访问记录
 
 - 触发词：云盘里有什么、列文件夹、文档评论、谁看过这个文档。
-- 能力：`drive +search`（按关键词搜云空间文件，支持类型/归属/时间窗过滤）、`drive files list`（列子项、可递归盘点）、`drive file.comments list`（评论）、`drive file.view_records list`（访问记录）。仅 1 个快捷命令 + 3 个只读原生 API。
+- 能力：`drive +search`（按关键词搜云空间文件，支持类型/归属/时间窗过滤）、`drive +batch-query-comments`（按 comment_id 批量取评论详情）、`drive +list-replies`（取某条评论的回复列表）、`drive files list`（列子项、可递归盘点）、`drive file.comments list`（评论分页遍历）、`drive file.view_records list`（访问记录）。3 个只读快捷命令 + 3 个只读原生 API。
 - 入口：[lark-drive/README.md](lark-drive/README.md)
 
 ```bash
@@ -139,12 +139,12 @@ lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实
 ### slides —— 幻灯片读取
 
 - 触发词：看演示文稿、读 slides、某页幻灯片内容、幻灯片历史版本。
-- 能力：整份 XML（`slides xml_presentations get`）、单页 XML（可指定历史版本）、历史版本列表与回滚任务状态查询。
+- 能力：整份 XML（`slides xml_presentations get`）、单页 XML（可指定历史版本）、历史版本列表（`slides +history-list`）与回滚任务状态查询（`slides +history-revert-status`）。
 - 入口：[lark-slides/README.md](lark-slides/README.md)
 
 ```bash
-lark-cli schema slides.xml_presentation.history.list   # 先看参数结构
-lark-cli slides xml_presentation.history list --as user --params '<json_params>'
+lark-cli slides +history-list --presentation "<url_or_id>" --page-size 20
+lark-cli slides +history-revert-status --presentation "<url_or_id>" --task-id "<task_id>"
 ```
 
 ### task —— 任务与清单查询

package/shared/lark-cli/lark-doc/references/lark-doc-fetch.md

@@ -48,7 +48,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
 | `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |
 | `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按"最小包容单元"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |
 | `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |
-| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
+| `keyword` | 只有模糊关键词 | `--keyword`（该模式必填；**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
 
 > 💡 **多关键词用 `\|` 拼接（OR 语义，任一命中即返回）**：例 `"部署\|发布\|上线"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\|缺陷\|故障`）。
 
@@ -107,7 +107,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
+| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/`、`/wiki/` 和带 `#share-...` 的选区链接） |
 | `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `im-markdown`（仅用于获取内容后在 `lark-im` 场景下使用） |
 | `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
 | `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |
@@ -130,7 +130,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
 <whiteboard token="..."/>
 ```
 
-- `<img>` / `<source>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。
+- `<img>` / `<source>` 带 `url` 时，可直接用该 URL 下载，但仅限可信的公开 HTTPS URL：拒绝带 userinfo 的 URL，以及解析到 private / loopback / link-local / multicast / unspecified 地址的 host，且重定向需逐次校验；不满足时禁止请求。
 - 没有 `url`（或目标是 `<whiteboard>`）的素材，本沙箱不提供下载 / 预览类命令；只需把标签里的 `token` 等信息如实呈现给用户。
 
 ## 嵌入电子表格 / 多维表格

package/shared/lark-cli/lark-drive/README.md

@@ -1,8 +1,12 @@
 # drive (v1)
 
-## 能力范围（本沙箱仅开放 1 个快捷命令 + 3 个只读 API）
+## 能力范围（本沙箱仅开放 3 个只读快捷命令 + 3 个只读 API）
 
-快捷命令只有 `+search`（按关键词搜云空间，见下方专节）；其余能力是下面三个只读的原生 API 调用：
+| 快捷命令 | 用途 |
+|----------|------|
+| `+search` | 按关键词搜云空间（见下方专节） |
+| `+batch-query-comments` | 按评论 ID 批量获取评论卡片，见 [`references/lark-drive-batch-query-comments.md`](references/lark-drive-batch-query-comments.md) |
+| `+list-replies` | 分页获取某条评论下的全部回复，见 [`references/lark-drive-list-replies.md`](references/lark-drive-list-replies.md) |
 
 | API 命令 | 用途 |
 |----------|------|
@@ -10,13 +14,25 @@
 | `drive file.comments list` | 分页获取某个文档的评论列表 |
 | `drive file.view_records list` | 获取文档的访问者记录（view records） |
 
-其余 drive 能力（上传 / 下载 / 导入 / 导出 / 复制 / 移动 / 删除 / 新建文件夹、评论写入与回复、
+其余 drive 能力（上传 / 下载 / 导入 / 导出 / 复制 / 移动 / 删除 / 新建文件夹、评论与回复的写入、
 权限与协作者、密级标签、版本管理、封面、订阅等）在本沙箱**不作为可用入口**，不要尝试拼这些命令。
 
+### 评论读取：shortcut 与原生 API 的分工
+
+意图命中 shortcut 时**优先用 shortcut**——两个评论 shortcut 直接接受 `--url`（含 wiki URL
+自动解包到底层文档），无需先手动解析 `file_token` / `file_type`：
+
+| 意图 | 用什么 |
+|------|--------|
+| 分页遍历评论卡片、全量统计、找最新/最早评论 | `drive file.comments list`（原生 API，见下方 file.comments 节） |
+| 已知 `comment_id`，精确取一批评论卡片 | `drive +batch-query-comments`（不要翻 `file.comments list` 的分页去过滤） |
+| 某张评论卡片 `item.has_more=true` 回复没拉全，或要按 `comment_id` 独立分页看全部回复 | `drive +list-replies` |
+
 ### 文档类型与 Token（读取前提）
 
-不同类型的文档有不同的 URL 格式和 Token 处理方式。列取评论或访问记录前，必须先拿到正确的
-`file_token` 与对应 `file_type`。
+不同类型的文档有不同的 URL 格式和 Token 处理方式。用**原生 API** 列取评论或访问记录前，
+必须先拿到正确的 `file_token` 与对应 `file_type`；两个评论 shortcut 则直接接受 `--url`
+（含 wiki URL 自动解包），或裸 token + `--type`。
 
 | URL 格式 | 示例 | Token 类型 | 处理方式 |
 |----------|------|-----------|----------|
@@ -64,7 +80,10 @@ lark-cli drive files list \
   - 真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的"评论本身"。
   - 统计"评论数 / 评论卡片数"：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
   - 是否还有下一页以返回里的 `has_more` 为准；`page_token` 只作为 `has_more=true` 时续跑下一页的游标。
-  - 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中。
+  - 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中——用
+    `drive +list-replies --comment-id <items[].comment_id>` 拉全该卡片的回复。
+  - 已知 `comment_id` 要精确取评论卡片时，不要翻本 API 的分页去过滤，改用
+    `drive +batch-query-comments`。
 
 ### file.view_records
 
@@ -74,7 +93,7 @@ lark-cli drive files list \
 
 | 错误信息 | 原因 | 解决方案 |
 |----------|------|----------|
-| `not exist` | 使用了错误的 token | 检查 token 类型；wiki 链接背后是 docx/sheet/bitable 等不同对象，不能只按 `/wiki/<token>` 猜底层类型 |
+| `not exist` | 使用了错误的 token | 检查 token 类型；wiki 链接背后是 docx/sheet/bitable 等不同对象，不能只按 `/wiki/<token>` 猜底层类型（两个评论 shortcut 传 `--url` 会自动解包 wiki，原生 API 没有这层解包） |
 | `permission denied` | 没有相关操作权限 | 当前身份对该文档/文件没有读取权限；把 `error.hint` 转述给用户，不要自行补登录或改身份 |
 | `invalid file_type` | file_type 参数错误 | 根据实际 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable/apps） |
 
@@ -100,6 +119,16 @@ lark-cli drive +search --query "<关键词>" --only-title --as user
 - `--folder-tokens` 与 `--space-ids` 互斥，分别限定云盘文件夹与 wiki 空间
 - `--sort` 取值 `default|edit_time|edit_time_asc|open_time|create_time`
 
+### 按完整标题定位
+
+用户按**完整标题**定位某个资源时，使用 `--only-title`：
+
+- 标题不超过 30 个字符时直接查询；超长标题使用不超过限制的稳定片段召回，再按返回标题严格匹配
+- 使用相同 query 和过滤条件按 `--page-token` 检查，最多 3 页
+- 仅在 `has_more=false` 且跨页恰好一个严格匹配时才把该结果当作唯一定位继续后续操作，
+  否则请用户缩小范围或补充信息
+- `drive files list` 只用于枚举已知文件夹的直接子项，不当作标题检索手段
+
 ### 标题词 + 正文词要同时满足时
 
 用户同时给标题关键词和正文关键词、且要求同一资源同时满足两项时，**发一条联合搜索**：

package/shared/lark-cli/lark-drive/references/lark-drive-batch-query-comments.md

@@ -0,0 +1,44 @@
+# drive +batch-query-comments
+
+按评论 ID 批量获取评论卡片。已知 `comment_id` 时用它精确取；要分页遍历、全量统计或找最新/最早评论，用原生 API `drive file.comments list`（见 [`../README.md`](../README.md) 的 file.comments 节）。
+
+## 命令
+
+```bash
+# 推荐：完整 URL + 评论 ID（逗号分隔或重复 --comment-ids，单次上限 100）
+lark-cli drive +batch-query-comments --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --comment-ids '<id1>,<id2>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
+| `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--comment-ids` | 是 | 评论 ID，逗号分隔或重复传，单次最多 100 个；来自 `drive file.comments list` 返回的 `items[].comment_id` |
+| `--need-reaction` | 否 | 返回评论卡片上的 reaction 数据 |
+| `--need-relation` | 否 | docx 评论定位关系（返回 `items[].relation` 及块位置）；仅 docx 生效，非 docx 静默忽略 |
+
+## 行为说明
+
+- `--need-relation` 通过请求 **body** 发送，只在解析后的目标是 docx 时发送；该参数未收录于平台 metadata，但服务端支持，返回 `items[].relation` 及块位置。
+- 输出的 `items` 始终是 JSON 数组（服务端省略时归一化为 `[]`），外层补 `file_token`、`file_type`、`count`。
+
+## 输出
+
+```json
+{
+  "file_token": "docx_token",
+  "file_type": "docx",
+  "items": [],
+  "count": 0
+}
+```
+
+`items` 是命中的评论卡片数组（外层补 `file_token`/`file_type`，wiki 输入再加 `wiki_token`）；`count` 是命中数。
+
+## 参考
+
+- [`../README.md`](../README.md) file.comments 节 —— 用 `drive file.comments list` 分页获取评论列表（`comment_id` 的来源）
+- [`lark-drive-list-replies.md`](lark-drive-list-replies.md) —— 分页获取某条评论下的回复

package/shared/lark-cli/lark-drive/references/lark-drive-list-replies.md

@@ -0,0 +1,49 @@
+# drive +list-replies
+
+分页获取某条评论下的回复。`drive file.comments list` 返回的评论卡片自带 `reply_list.replies`，但当卡片 `item.has_more=true` 时回复没有拉全——这时（或需要按 `comment_id` 独立分页看全部回复时）用本命令。
+
+## 命令
+
+```bash
+# 推荐：完整 URL + 评论 ID
+lark-cli drive +list-replies --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --comment-id '<id>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
+| `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--comment-id` | 是 | 评论 ID；来自 `drive file.comments list` 返回的 `items[].comment_id` |
+| `--page-size` | 否 | 1-100，默认 50 |
+| `--page-token` | 否 | 上次输出的 `page_token`；`has_more=true` 时用它续拉 |
+| `--need-reaction` | 否 | 在回复上返回 reaction 数据 |
+
+## 行为说明
+
+- 根回复承载评论正文本身，是回复列表中创建最早的一条：**仅第一页（未传 `--page-token`）的 `items[0]` 是根回复**；翻页后（传了 `--page-token`）返回的 `items[0]` 只是普通回复，不要按位置当作根回复。
+- 输出字段：`items[].reply_id` / `user_id` / `create_time` / `update_time` / `content.elements`；`items[].user_id` 是 open_id，可与当前身份比对判断回复归属。
+- 输出的 `items` 始终是 JSON 数组（服务端省略时归一化为 `[]`）。
+
+## 输出
+
+```json
+{
+  "file_token": "docx_token",
+  "file_type": "docx",
+  "comment_id": "<comment_id>",
+  "items": [],
+  "has_more": false,
+  "page_token": "",
+  "count": 0
+}
+```
+
+`items` 是回复数组；是否继续翻页以 `has_more` 为准，`has_more=true` 时用返回的 `page_token` 续拉。
+
+## 参考
+
+- [`../README.md`](../README.md) file.comments 节 —— 评论卡片模型与统计口径（`comment_id` 的来源）
+- [`lark-drive-batch-query-comments.md`](lark-drive-batch-query-comments.md) —— 按评论 ID 批量获取评论卡片

package/shared/lark-cli/lark-im/README.md

@@ -48,18 +48,6 @@ lark-cli im <resource> <method> [flags]  # 调用 API
   - `bots` — 读取群内机器人成员信息。上游 skill 未提供 typed-flag 文档，调用前先 `lark-cli schema im.chat.members.bots` 查看参数与返回结构。
   - `get` — 读取群成员信息。上游 skill 未提供 typed-flag 文档，调用前先 `lark-cli schema im.chat.members.get` 查看参数与返回结构。
 
-### chat.moderation
-
-  - `get` — 获取群成员发言权限。调用方需在目标群内并与群属于同一租户。
-
-### chat.nickname
-
-  - `get` — 获取自己的群昵称（self-only）；未设置昵称时返回空字符串。
-
-### chat.user_setting
-
-  - `batch_query` — 批量查询当前用户在群内的个人偏好设置（如 `is_muted` 静音普通消息、`is_mute_at_all` 静音 @all 消息）；单次最多 10 个群；调用方需在每个目标群内。
-
 ### pins
 
   - `list` — 获取群内 Pin 消息。
@@ -77,8 +65,6 @@ lark-cli im <resource> <method> [flags]  # 调用 API
 | `+chat-list` / `+chat-search` | `im:chat:read` |
 | `chat.members.get` | `im:chat.members:read` |
 | `+chat-members-list` | `im:chat.members:read` |
-| `chat.user_setting.batch_query` | `im:chat.user_setting:read` |
-| `chat.moderation.get` | `im:chat.moderation:read` |
 | `reactions.batch_query` | `im:message.reactions:read` |
 | `reactions.list` | `im:message.reactions:read` |
 | `pins.list` | `im:message.pins:read` |

package/shared/lark-cli/lark-sheets/README.md

@@ -25,7 +25,7 @@
 
 | 你要做的事 | ✅ 正确写法 | 参考 |
 | --- | --- | --- |
-| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `lark-sheets-read-data` |
+| 读数据（纯值 / CSV） | `+csv-get`（`--range` 可省略 = 读整个子表，无需先探行列；限定范围才传） | `lark-sheets-read-data` |
 | 按列类型结构化读出（喂 DataFrame / round-trip） | `+table-get` | `lark-sheets-read-data` |
 | 读值 + 公式 / 样式 / 批注 / 数据验证 | `+cells-get --include value,formula,style,comment,data_validation` | `lark-sheets-read-data` |
 | 看某区域下拉框（数据验证）的选项 | `+dropdown-get`（范围用 `--range`） | `lark-sheets-read-data` |
@@ -50,13 +50,13 @@
 
 ## 执行要点（读取 / 陷阱）
 
-端到端只读工作流：了解结构（`+workbook-info`）→ 读数据 → 理解语义 → 按需读对象配置 / 自检公式。
+端到端只读工作流：了解结构（`scripts/lark_inspect_workbook.py` / `+workbook-info`）→ 读数据 → 理解语义 → 按需读对象配置 / 自检公式。
 
 ### 读取：按需求选路径（细则见 `lark-sheets-read-data`）
 
 | 用户需求 | 读取路径 |
 |---|---|
-| "查一下 / 看看 / 统计 / 汇总"等只读 | `+csv-get` 读到上下文（大表按 `--range` 行窗口分批读） |
+| "查一下 / 看看 / 统计 / 汇总"等只读 | 小表 `+csv-get` 读到上下文；大表先 `+workbook-info` + 小窗口 `+csv-get` 定边界，再对未截断窗口跑 `scripts/lark_detect_subtables.py` / `scripts/lark_profile_table.py` |
 | 需要按列类型结构化读出（喂 DataFrame） | `+table-get` |
 | 需要公式 / 样式 / 批注 / 数据验证 | `+cells-get --include …` |
 | 需要看某区域下拉选项 | `+dropdown-get` |
@@ -66,12 +66,13 @@
 ### 用脚本配合 CLI 时
 
 - **只读 stdout**：CLI 数据走 stdout、诊断走 stderr；解析 JSON 别 `2>&1`（警告混入会解析失败），用管道或单独重定向 stdout。
+- **读表理解优先用 `scripts/lark_*.py`**：`lark_inspect_workbook.py` / `lark_detect_subtables.py` / `lark_profile_table.py` 是随本 skill 分发的只读脚本，用来把在线表格整理成结构摘要（底层只调 `+workbook-info` / `+sheet-info` / `+csv-get`）。可选增强，不是必经步骤——脚本不可用时直接用 CLI 等价路径（对照表见 `lark-sheets-read-data`：`+workbook-info` / `+sheet-info` / 小窗口 `+csv-get`）；需要公式 / 样式 / 批注 / 精确原始值时仍直接用 `+cells-get` / `+table-get`。
 - **喂 CLI 的 CSV / JSON 用 UTF-8 无 BOM**；临时文件放系统临时目录、勿落项目目录。
 - **命令失败先读 stderr 再调整**，别原样重发。
 
 ### 易漏陷阱
 
-- **隐藏行列**：`+csv-get` 默认含隐藏行列；设 `--skip-hidden=true` 只看可见，但返回行序号与实际行号不再对应。
+- **隐藏行列**：`+csv-get` 默认含隐藏行列；`--skip-hidden=true` 只看可见，真实行号会跳空——禁止按返回数组下标推导行号，用 `annotated_csv` 的 `[row=N]` 或 `row_indices`。
 - **跨 sheet 对象**：图表 / 条件格式 / 透视表 / 浮动图片可能分布在多个子表，读取前先 `+workbook-info` 掌握全局。
 - **大数字精度**：15 位以上的身份证 / 参考号做去重 / 比较时禁止用 `+csv-get` 的显示值（会显示成科学计数、误判重复），改用 `+cells-get` 取原始精确值（见 `lark-sheets-read-data`）。
 

package/shared/lark-cli/lark-sheets/references/lark-sheets-read-data.md

@@ -32,7 +32,72 @@
 - 需要公式/样式/批注 → `+cells-get`
 - 只想知道某区域下拉框有哪些选项 → `+dropdown-get`
 
-⚠️ **大数据优先落盘、别灌进上下文**：`+csv-get` / `+cells-get` 都受调用方 Bash / 终端的单命令 stdout 输出上限约束（常见默认约 30000 字符，超过会被截断或转存为文件）。纯值分析优先 `+csv-get --format csv` 按 `--range` 行窗口（`A1:Z500` / `A501:Z1000` …）分批重定向到文件 + 本地脚本处理；若确实要让结果直接进上下文又不想触发转存，给任一命令把 `--max-chars`（默认 500000）调小到略低于该上限（如 `25000`），CLI 改为优雅截断 + `has_more` 分页。
+## 读表理解脚本（Agent 优先入口）
+
+当目标是"先理解表格内容 / 结构 / 子表边界"时，优先用本 skill 随包分发的只读理解脚本 `scripts/lark_*.py`（与本文件同级的 `scripts/` 目录），再决定是否直接调用上述 shortcut。脚本是可选捷径，不是必经入口——脚本不可用时直接按下表右列的 CLI 等价路径执行：如果任务很小，或需要公式 / 样式 / 批注 / 精确原始值等脚本未覆盖的信息，可以直接用 CLI 做等价或更精细读取。
+
+| 脚本 | 底层 shortcut | 适用场景 |
+| --- | --- | --- |
+| `scripts/lark_inspect_workbook.py` | `+workbook-info` / `+sheet-info` / `+csv-get` | 在线表格第一步预检：拿 sheet 清单、布局、预览、`current_region` |
+| `scripts/lark_detect_subtables.py` | `+workbook-info` / `+sheet-info --include merges,hidden_rows,hidden_cols` / 小窗口 `+csv-get` | 同一 sheet 可能有多个表格区域、汇总块、备注块时，在**已知且未截断的窗口**内识别候选子表 range |
+| `scripts/lark_profile_table.py` | `+csv-get` / `+sheet-info --include hidden_rows,hidden_cols`（默认包含隐藏行列时；必要时再手工 `+cells-get` / `+table-get`） | 对**已确认且未截断的候选 range**做表头、数据范围、列类型、特殊行画像，并输出 `summary` / `field_map` / `risk_warnings` / `write_hints` |
+
+（`scripts/lark_sheet_range.py` 与 `scripts/lark_sheet_read_cli.py` 是上面三个脚本 import 的公共库，不单独调用。）
+
+`lark_profile_table.py` 是**启发式画像**，不是最终判定器：它能降低手工数行列和漏看特殊行的风险，但表头、多行标题、数据末行、列类型、特殊行和追加列都可能需要二次确认。汇总、去重、lookup / 匹配、透视 / 图表范围推导等操作前，不能只凭 profile 结果下结论；必须把 profile 输出与任务语义、样本值、必要的 CLI 补读一起核对。
+
+`lark_profile_table.py` 的使用口径：
+
+| 任务类型 | 建议 |
+| --- | --- |
+| 只读取用户明确指定的单个单元格 / 很小范围，且不需要理解整表 | 可直接用 CLI |
+| 统计 / 汇总、排序筛选核对、去重、lookup / 匹配、条件与范围推导 | 优先对目标区域运行 `lark_profile_table.py`；若已用等价 CLI 明确确认表头、数据范围、字段列、列类型和特殊行，可跳过脚本。去重 / lookup 若目标列含 `long_numeric_like_id`、前导 0 或格式化数字，profile 只能定位列，比较值必须改用 `+cells-get` 或 `+table-get` |
+| 多块表、表头不确定、存在合并 / 汇总 / 空行 / 备注块、选区是单格但任务语义是整表 | 先 `lark_detect_subtables.py` 或补充 CLI 确认候选范围，再对目标 range 跑 `lark_profile_table.py` |
+| 需要公式、样式、批注、数据验证、精确原始值、长数字 ID 精确比较 | 先用脚本形成结构化理解，再按需补 `+cells-get` / `+table-get` / 分批 `+csv-get` |
+
+推荐链路（大表先定窗口，脚本不接受截断结果）：
+
+```bash
+python scripts/lark_inspect_workbook.py --url "<表格URL>"
+# 先用 +workbook-info 和小窗口 +csv-get 确认真实 sheet、列边界和起始区域；大表按行窗口推进。
+python scripts/lark_detect_subtables.py --url "<表格URL>" --sheet-name "<子表名>" --range "A1:H200"
+python scripts/lark_profile_table.py --url "<表格URL>" --sheet-name "<子表名>" --range "A1:H200"
+```
+
+`lark_detect_subtables.py` / `lark_profile_table.py` 的 `+csv-get` 命中 `has_more` 会以错误退出并报告已读取的 `actual_range`，绝不基于半截数据给出候选范围或画像。遇到此错误，以 `actual_range` 为已完成窗口，缩小列数或从其末行之后继续读；跨窗口的候选范围、汇总行必须再用 CLI 核对，不能把单个窗口结果当整表结论。
+
+脚本只读，不做任何写入。它们的输出用于降低 token 和定位错误；后续需要公式、样式、批注、精确原始值时，仍按本文件规则直接调用 `+cells-get` / `+table-get` / `+csv-get`。使用了 `lark_profile_table.py` 后下结论前，至少读取并使用这些字段：`summary.header_row`、`summary.data_range`、`summary.data_row_segments`、`field_map`、`risk_warnings`、`visibility` 和 `special_rows`。仅当 `risk_warnings` 不含 `data_range_has_gaps` 时，才可把 `data_range` 当连续数据范围；有缺口时按 `data_row_segments` 分段读取。
+
+脚本关键 flag：
+
+| Flag | 脚本 / 默认 | 何时调整 |
+| --- | --- | --- |
+| `--skip-hidden` | profile / detect，关闭（默认包含隐藏行列） | 只分析可见数据时开启；此时必须使用 profile 的 `data_row_segments`，不要把连续 `data_range` 直接当真实连续区间。 |
+| `--max-chars` | inspect `8000`；profile / detect `25000` | 输出过大时缩小范围或降低值；profile / detect 若截断会报错并给 `actual_range`，按窗口继续。 |
+| `--header-scan-rows` | profile `20` | 表头前有多行标题、说明或空行时提高；过大时结合 `possible_multi_row_header` 补读确认，不要仅凭评分结果下结论。 |
+| `--max-sheets` | inspect `3` | 未指定 sheet 时仅前 N 个 sheet 带 layout / preview，其余仍返回摘要并在 warnings 说明。 |
+| `--max-merge-components` | detect `2000` | 超限会跳过 gap 合并并告警；需缩小窗口或人工复核子表边界。 |
+| `--gap-rows` / `--gap-cols` | detect `1` / `0` | 子表被切碎或粘连时调整；每次调整后复核候选范围。 |
+
+detect 最多确认 10 个跨窗口合并锚点；超限会在 `warnings` 中说明跳过的数量。遇到该 warning，缩小扫描窗口后再复核受影响的子表边界。
+
+`lark_profile_table.py` 输出触发补读的规则：
+
+- `risk_warnings` 非空时，不要把画像当最终事实；按下表补读或调整，不在表内的 warning 也先保守复核。
+
+| Warning | 必做动作 |
+| --- | --- |
+| `mixed_value_types` / `long_numeric_like_id` / `formula_or_value_errors` | 补 `+cells-get` 或 `+table-get`，确认原始值、类型和公式。 |
+| `duplicate_headers` / `unnamed_columns` / `header_not_detected` / `header_row_not_first` / `many_empty_cells` | 补 `+csv-get` 读取表头附近和空值样本，确认真正表头与字段列。 |
+| `data_range_not_detected` / `special_rows_present` / `empty_rows_present` | 补 `+csv-get` 读取尾部和特殊行样本，确认有效数据末行。 |
+| `possible_multi_row_header` | 补读表头上下各 1-2 行；必要时 `+sheet-info --include merges` 核对跨列合并。 |
+| `hidden_rows_in_range` / `hidden_columns_in_range` | 用 `+sheet-info --include hidden_rows,hidden_cols` 确认隐藏区间，决定是过滤还是照常解读。 |
+| `data_range_has_gaps` | 不把连续 `data_range` 当真实连续区间；用 `summary.data_row_segments` 对每个实际读取行段单独处理。 |
+| `data_range_has_col_gaps` | 返回的列不连续（`--skip-hidden` 跳过了隐藏列）；不要把 `data_range` 当连续列区解读，按 `summary.data_col_segments` 分列段处理，否则缺口右侧的值会整体错位。 |
+
+- `write_hints.safe_append_col` 只是候选追加列（脚本为通用画像输出保留该字段），不代表绝对安全；引用它之前必须用 `+csv-get` / `+cells-get` / `+sheet-info` 核对该列为空、没有隐藏列 / 公式 / 样式 / 对象依赖。该字段已自动跳过隐藏列（跳过的列名列在 `write_hints.skipped_hidden_cols`）——注意 `--skip-hidden` 下隐藏列根本不出现在返回网格里，若它们正好都贴在数据右边缘，`data_range_has_col_gaps` 也不会告警，所以这层跳过是唯一的保护，别绕过它自己按「最后一列 +1」推落点。
+
+⚠️ **大数据优先落盘、别灌进上下文**：`+csv-get` / `+cells-get` 都受调用方 Bash / 终端的单命令 stdout 输出上限约束（常见默认约 30000 字符，超过会被截断或转存为文件）。纯值分析优先用 `+csv-get` 按 `--range` 行窗口（`A1:Z500` / `A501:Z1000` …）分批重定向到文件 + 本地脚本处理；若确实要让结果直接进上下文又不想触发转存，给任一命令把 `--max-chars`（默认 500000）调小到略低于该上限（如 `25000`），CLI 改为优雅截断 + `has_more` 分页。
 
 > **落盘不等于读全**：`--output-path` 只是把上限从 stdout 口径放宽到有界的 2000 万字符（读取链路非流式，该上限是内存保护），不是无限。stdout 回执带 `complete` 字段——`complete:false` 时另有 `truncated` 与提示，文件里只有半截数据；多子表读取还会给 `unread_sheets` 列出预算耗尽前没读到的子表。**拿到回执先看 `complete`，不要默认整表已落全。**
 
@@ -46,6 +111,7 @@
 
 - `+csv-get` 和 `+cells-get` 支持分页/截断，注意检查 `has_more` / `truncated` 标志；两者在处理返回数据之前都必须先读 `warning_message`（上游 schema 要求先读它再用其它字段，内含定位与截断续读提示），`+cells-get` 还要用每个 range 的 `actual_range` / `row_indices` / `col_indices` 判断真实位置
 - 隐藏行列默认包含在返回结果中（`--skip-hidden=false`），如需只看可见数据设为 `true`。读取原语本身不标注哪些行列被隐藏：若要识别隐藏区间（以决定是否过滤、或如何解读混入的隐藏数据），用 `+sheet-info --include hidden_rows,hidden_cols` 取隐藏行列集合，再结合 `+csv-get` / `+cells-get` 返回的 `row_indices` / `col_indices` 判断每行 / 每列是否隐藏
+- 要判断单元格内容是否被行高列宽挤到显示不全（排版检查），给 `+cells-get` 加 `--include truncation`：会按字号 / 自动换行 / 行高列宽估算并返回被截断单元格的 `isRowTruncated` / `isColTruncated`（未返回视为未截断）。有额外计算开销，仅需要时才开
 
 **常见配置错误（必须注意）**：
 - **全量读取导致上下文溢出**：不要对大表（数百行以上）直接用 `+csv-get` 或 `+cells-get` 读取全部数据到上下文。大表场景必须分批读取：用 `--range` 切行窗口逐块读（`+csv-get` / `+cells-get` 单次返回量由 `--max-chars` 自动兜底，截断时返回 `has_more`）；过大时考虑导出到本地文件后用脚本处理再分批回写
@@ -101,7 +167,7 @@ _公共四件套 · 系统：`--dry-run`_
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `--range` | string | required | A1 范围，如 `A1:F10`（不带 sheet 前缀；用 `--sheet-id` / `--sheet-name` 指定 sheet） |
-| `--include` | string_slice | optional | 要返回的信息类别，逗号分隔多个（可选值：`value` / `formula` / `style` / `comment` / `data_validation`） |
+| `--include` | string_slice | optional | 要返回的信息类别，逗号分隔多个。`truncation` 会额外按行高列宽 / 字号 / 自动换行估算每个单元格是否被截断显示，返回 `isRowTruncated` / `isColTruncated`（有额外计算开销，仅排版检查时才开）（可选值：`value` / `formula` / `style` / `comment` / `data_validation` / `truncation`） |
 | `--max-chars` | int | optional | 单次返回字符上限，默认 500000（兜底防爆）。要整表无截断直接用 `--output-path` 落盘（上限自动放宽到 2000 万字符）；仅当要让结果直接进上下文、又不落盘时才调小（如 25000），按 has_more 分页。传 `0` 表示「不自设上限」，等价于不传（仍是 500000 / 落盘时 2000 万），不会退回底层工具那个更小的默认截断 |
 | `--output-path` | string | optional | 把完整读取结果写入本地路径（如 `./out.json`），文件内容为 data 载荷的 JSON；stdout 只回一个含 output_path / 字节数的确认信息。**一旦设置，字符上限自动放宽到有界的 2000 万字符**（覆盖 `--max-chars` 默认），并非无限——读取链路非流式，该上限是内存保护；显式 `--max-chars` 优先。stdout 回执带 `complete` 字段（命中上限时另有 `truncated` 与提示），据此判断文件是否完整，不要默认整表已落全。省略时按常规把结果打到 stdout |
 | `--skip-hidden` | bool | optional | 跳过隐藏行列，默认 `false` |
@@ -120,7 +186,7 @@ _公共四件套 · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--range` | string | required | A1 范围，如 `A1:F30`（不带 sheet 前缀；用 `--sheet-id` / `--sheet-name` 指定 sheet） |
+| `--range` | string | optional | A1 范围，如 `A1:F30`（不带 sheet 前缀；用 `--sheet-id` / `--sheet-name` 指定 sheet）。**可省略：缺省读取整个子表**（按表格实际边界裁剪，返回的 `actual_range` 标注实际读取范围）；大表配合 `--max-chars` / `--output-path` 控制体量 |
 | `--max-chars` | int | optional | 单次返回字符上限，默认 500000（兜底防爆）。要整表无截断直接用 `--output-path` 落盘（上限自动放宽到 2000 万字符）；仅当要让结果直接进上下文、又不落盘时才调小（如 25000），按 has_more 分页。传 `0` 表示「不自设上限」，等价于不传 |
 | `--output-path` | string | optional | 把完整读取结果写入本地路径，文件内容为 data 载荷的 JSON；stdout 只回一个含 output_path / 字节数的确认信息。**一旦设置，字符上限自动放宽到有界的 2000 万字符**；stdout 回执带 `complete` 字段（命中上限时另有 `truncated`），据此判断文件是否完整。⚠️ 落盘的是 data 载荷的 **JSON**（CSV 文本是 JSON 里的一个字段），不是直接可用的 `.csv` 文件；要纯 CSV 文件请把 stdout 重定向到文件 |
 | `--include-row-prefix` | bool | optional | 是否在每行前加 `[row=N]` 前缀，默认 `true` |
@@ -153,6 +219,10 @@ lark-cli sheets +csv-get --url "https://example.feishu.cn/sheets/shtXXX" --sheet
 
 # 用 sheet-name 模糊定位（运行时框架会先解析到 sheet-id）
 lark-cli sheets +csv-get --spreadsheet-token shtXXX --sheet-name "销售明细" --range "A1:F30"
+
+# 全量读：省略 --range 即读整个子表（按实际边界裁剪，返回 actual_range 标注实读范围），
+# 无需先 +workbook-info 探行列再拼 range；大表配合 --max-chars / --output-path
+lark-cli sheets +csv-get --spreadsheet-token shtXXX --sheet-name "销售明细"
 ```
 
 输出契约（envelope.data）：