@amaster.ai/pi-lark 0.1.2-beta.65 → 0.1.2-beta.67

package/skills/lark-okr/references/lark-okr-comment-solve-reopen.md

@@ -0,0 +1,83 @@
+# okr +comment-solve / +comment-reopen
+
+> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
+
+解决/重新打开一条评论。实体级评论按单条评论处理；划词评论则是操作整个评论串。只支持 user 身份。
+
+## 推荐命令
+
+```bash
+# 解决实体级评论或整个划词评论串。
+lark-cli okr +comment-solve --comment-id 7000000000000000004
+
+# 重新打开已解决的实体级评论或划词评论串。
+lark-cli okr +comment-reopen --comment-id 7000000000000000004
+
+# 预览解决评论的状态变更请求，不实际执行。
+lark-cli okr +comment-solve --comment-id 7000000000000000004 --dry-run
+```
+
+## 参数
+
+| 参数           | 必填 | 默认值  | 说明                                                                                  |
+|----------------|------|---------|---------------------------------------------------------------------------------------|
+| --comment-id   | 是   | —       | 评论 ID，int64 正整数。可从 +comment-list、+comment-detail 或 +comment-get 获取。     |
+| --user-id-type | 否   | open_id | open_id、union_id、user_id 或 user_key。                                              |
+| --style        | 否   | simple  | affected_comments 的正文风格：simple（SemiPlainContent）或 richtext（ContentBlock）。 |
+| --dry-run      | 否   | —       | 预览 API 调用而不实际执行。                                                           |
+| --format       | 否   | json    | 输出格式。                                                                            |
+
+## 工作流程
+
+1. 使用 [+comment-list](lark-okr-comment-list.md)、[+comment-detail](lark-okr-comment-detail.md) 或 [+comment-get](lark-okr-comment-get.md) 获取并确认 comment-id。
+2. 检查评论是否属于划词串：如果返回有 selection.id，solve/reopen 会影响同一 selection.id 下的全部评论。
+3. 根据用户动作选择 +comment-solve 或 +comment-reopen；先用 --dry-run 检查目标接口。
+4. 执行后检查 affected_comments，确认实体级评论或整条评论串的状态变化范围。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "affected_comments": [
+    {
+      "id": "7000000000000000004",
+      "target": {
+        "target_type": "objective",
+        "target_id": "2345678901234567890"
+      },
+      "commentator_id": "ou_xxx",
+      "status": "solved",
+      "create_time": "2025-01-15 10:30:00",
+      "update_time": "2025-01-15 11:30:00",
+      "selection": {
+        "id": "8000000000000000001",
+        "selected_text": "提升核心接口稳定性"
+      },
+      "content": {
+        "text": "请补充指标", "mention": [], "docs": [], "images": []
+      }
+    }
+  ],
+  "style": "simple"
+}
+```
+
+- +comment-solve 成功后 affected_comments 的 status 通常为 solved；+comment-reopen 成功后通常为 open。
+- simple 风格返回 SemiPlainContent；richtext 风格返回 ContentBlock。
+
+## 注意事项
+
+- 划词评论按评论串解决/重开，但 [+comment-delete](lark-okr-comment-delete.md) 仍然只删除单条评论。
+- 解决不是删除，之后可以用 +comment-reopen 恢复；删除后不可恢复。
+- 该操作是写操作，执行前应确认 comment-id 和目标动作。
+
+## 参考
+
+- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
+- [OKR 实体定义](lark-okr-entities.md) — Comment、评论串和状态规则
+- [ContentBlock 格式](lark-okr-contentblock.md) — affected_comments 正文格式
+- [okr +comment-get](lark-okr-comment-get.md) — 获取状态和 selection.id
+- [okr +comment-delete](lark-okr-comment-delete.md) — 永久删除单条评论
+- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则

package/skills/lark-okr/references/lark-okr-entities.md

@@ -10,9 +10,12 @@ Cycle (用户周期)
         ├── KeyResult (关键结果)
         │     └── Indicator (指标)
         │     └── list<Progress> (进展记录列表)
+        │     └── list<Comment> (评论列表)
         └── Indicator (指标)
         └── list<Progress> (进展记录列表)
+        └── list<Comment> (评论列表)
 
+Cycle、Progress 也可以直接挂载 Comment。
 Alignment (对齐关系): Objective ↔ Objective
 Category (分类): Objective 的分组标签
 ```
@@ -49,8 +52,11 @@ Category (分类): Objective 的分组标签
 ### 常用术语
 
 - **当前周期**: 指周期的 start_time/end_time
-  指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。 注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。 如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
-  - 如果用户没有提及，那么当前周期一般不考虑年度周期（起止时间从 01-01 至 12-31 的周期）
+  指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。
+  注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。
+  如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1)
+  的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
+    - 如果用户没有提及，那么当前周期一般不考虑年度周期（起止时间从 01-01 至 12-31 的周期）
 - **所有者**: 绝大多数所有者都是用户，少部分租户启用了“团队OKR”功能，所有者可能是部门。用户身份下，只能编辑所有者为当前用户的
   OKR。
 
@@ -173,6 +179,64 @@ Category (分类): Objective 的分组标签
 > - `okr +progress-update` [lark-okr-progress-update.md](lark-okr-progress-update.md) 更新进展记录内容
 > - `okr +progress-delete` [lark-okr-progress-delete.md](lark-okr-progress-delete.md) 删除进展记录
 > - `okr +progress-list` [lark-okr-progress-list.md](lark-okr-progress-list.md) 获取目标/关键结果下的进展记录
+
+---
+
+## Comment (评论)
+
+评论可以挂载在 Cycle、Objective、KeyResult 或 Progress 上，用于对 OKR 实体或正文中的一段文字进行讨论。评论分为实体级评论和划词评论两种：
+
+- **实体级评论**：直接附着在 Cycle 或 Progress 上。一条评论就是一个评论项，solve/reopen 只影响该评论。
+- **划词评论**：附着在 Objective 或 KeyResult 的正文选区上，带有 `selection`。同一个 `selection.id`
+  下的评论属于同一个评论串；solve/reopen 按评论串处理，但 delete 仍然只删除指定的一条评论。
+
+### Comment 字段
+
+| 字段               | 类型                 | 必填 | 说明                                                                                            |
+|------------------|--------------------|----|-----------------------------------------------------------------------------------------------|
+| `id`             | `string`           | 是  | 评论 ID，int64 正整数。                                                                              |
+| `target`         | `CommentTarget`    | 是  | 评论挂载对象，包含 `target_type` 和 `target_id`。类型为 `cycle`、`progress`、`objective` 或 `key_result`。      |
+| `commentator_id` | `string`           | 是  | 评论者 ID，返回 ID 类型由请求参数 `user_id_type` 决定。                                                       |
+| `status`         | `string`           | 是  | 评论状态：`open`（打开）或 `solved`（已解决）。                                                               |
+| `create_time`    | `string`           | 是  | 创建时间；                                                                                         |
+| `update_time`    | `string`           | 是  | 最后更新时间；                                                                                       |
+| `content`        | `ContentBlock`     | 否  | 评论正文，见 [ContentBlock 定义](lark-okr-contentblock.md)。                                           |
+| `solver_id`      | `string`           | 否  | 解决评论的用户 ID。                                                                                   |
+| `solved_time`    | `string`           | 否  | 评论解决时间，毫秒时间戳。                                                                                 |
+| `ref_comment_id` | `string`           | 否  | 被引用评论 ID。Progress/Cycle 等实体级评论可用它表示回复关系；Objective/KeyResult 的划词评论创建时可用它定位已有划词串，但新评论本身不建立引用关系。 |
+| `selection`      | `CommentSelection` | 否  | 划词信息。实体级评论为空；划词评论包含 selection ID 和可选的选区文本。                                                    |
+
+### CommentTarget (评论目标)
+
+| 字段            | 类型       | 必填 | 说明                                             |
+|---------------|----------|----|------------------------------------------------|
+| `target_type` | `string` | 是  | `cycle`、`progress`、`objective` 或 `key_result`。 |
+| `target_id`   | `string` | 是  | 对应 Cycle、Progress、Objective 或 KeyResult 的 ID。  |
+
+### CommentSelection (划词信息)
+
+| 字段              | 类型       | 必填 | 说明                          |
+|-----------------|----------|----|-----------------------------|
+| `id`            | `string` | 是  | 划词 ID。同一 `id` 下的评论属于同一个评论串。 |
+| `selected_text` | `string` | 否  | 划词锚定的正文文字。                  |
+
+### 评论创建与状态规则
+
+- Cycle/Progress 创建实体级评论时不传 `selected_text`；可以通过 `ref_comment_id` 回复已有评论。
+- Objective/KeyResult 创建划词评论时，`selected_text` 与 `ref_comment_id` 二选一：前者新建划词，后者将评论挂入被引用评论所属的已有划词串。shortcut
+  另外提供 `--select-all` 替代 `selected_text` 以选中 O/KR 内的全部内容。
+- `solve` / `reopen` 的请求参数是单条评论 ID。对实体级评论只影响该评论；对划词评论会影响整条评论串。
+- `delete` 永久删除指定评论，不会连带删除同一评论串的其他评论，且删除后不可找回。
+
+> **SHORTCUT：**
+> - `okr +comment-detail` [lark-okr-comment-detail.md](lark-okr-comment-detail.md) 获取周期下全部对象的评论并按评论串整理
+> - `okr +comment-list` [lark-okr-comment-list.md](lark-okr-comment-list.md) 分页获取单个评论目标下的评论
+> - `okr +comment-get` [lark-okr-comment-get.md](lark-okr-comment-get.md) 获取单条评论
+> - `okr +comment-create` [lark-okr-comment-create.md](lark-okr-comment-create.md) 创建评论、回复或挂入已有划词串
+> - `okr +comment-patch` [lark-okr-comment-patch.md](lark-okr-comment-patch.md) 修改评论正文
+> - `okr +comment-delete` [lark-okr-comment-delete.md](lark-okr-comment-delete.md) 永久删除单条评论
+> - `okr +comment-solve` [lark-okr-comment-solve-reopen.md](lark-okr-comment-solve-reopen.md) 解决评论/评论串
+> - `okr +comment-reopen` [lark-okr-comment-solve-reopen.md](lark-okr-comment-solve-reopen.md) 重新打开评论/评论串
 ---
 
 ## Indicator (指标)

package/skills/lark-sheets/SKILL.md

@@ -186,6 +186,7 @@ reference 分两组：先读**通用方法与规范**（横切所有任务的样
 | [Lark Sheet Float Image](references/lark-sheets-float-image.md) | 管理飞书表格中的浮动图片。当用户需要在表格中插入浮动图片、调整图片位置和大小、查看已有浮动图片、删除图片时使用。也适用于"插入图片"、"添加 logo"、"放一张图"等场景。注意：如果用户需要将图片嵌入到某个单元格内部（单元格图片），请阅读 lark-sheets-write-cells。 |
 | [Lark Sheet History](references/lark-sheets-history.md) | 查询飞书表格的历史版本并回滚到指定版本。当用户需要查看一张表的编辑历史版本列表、回滚到某个历史版本、或查询回滚的异步状态（进行中/成功/失败）时使用。回滚为异步操作，发起后通过状态查询轮询结果。仅针对飞书表格。 |
 | [Lark Sheet Changeset](references/lark-sheets-changeset.md) | 读取两个版本（CS revision）之间的 changeset（原始变更操作清单），用于复核某次编辑——尤其是 AI 编辑——是否真实满足用户诉求。传入起始版本（编辑前基线），可选结束版本（省略取最新），版本差上限 20；返回里最外层带当前表格最新版本号。当用户需要"看看这次改了什么"、"核对 AI 改动"、"对比两个版本的变更"时使用。 |
+| [Lark Sheet 旧命令迁移指南](references/lark-sheets-legacy-command-migration.md) | 重构前的 42 个 sheets 旧命令（`+create`、`+read`、`+write`、`+create-sheet`、`+media-upload` 等）已删除，调用会直接报 `unknown subcommand`。当手上的脚本或 skill 早于本次重构、或收到该报错时，用本文查替代命令，以及那些不只是改名的差异：单元格 payload 词汇（`{"type":"formula","text":…}` 已被拒绝）、响应字段路径、`+update-sheet` / `+update-dimension` 拆成多个命令。 |
 
 ## 公共 flag 速查
 

package/skills/lark-sheets/references/lark-sheets-batch-update.md

@@ -34,7 +34,7 @@
 - 写时：用 `+batch-update` 一次性完成插行/写公式/复制模板等成套动作。
 - 写后：抽样回读之外，可继续跑 `lark-sheets-formula-verify` 做一次诊断。
 
-**`+dropdown-update` 的选项模式（`--options` / `--source-range` 二选一）+ 配色规则**（`--colors` 长度可短不能长、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本文不重复。`+dropdown-delete` 不涉及这些 flag。
+**`+dropdown-update` 的选项模式（`--options` / `--source-range` 二选一）+ 配色规则**（更新会重写完整验证规则；需要保留已有配色时先回读并透传 `--colors`）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本文不重复。`+dropdown-delete` 不涉及这些 flag。
 
 ## Shortcuts
 
@@ -84,8 +84,8 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（最多 100 个，如 `["Sheet1!A2:A100","Sheet1!C2:C100"]`，前缀裸写不加引号），每项必须带 sheet 前缀；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id |
 | `--options` | string + File + Stdin（复合 JSON） | xor | 下拉选项 JSON 数组，例如 `["opt1","opt2"]`。服务端不限制选项数量，也不限制单个选项长度；含逗号的选项可以接受（写入时会自动转义）。大量选项建议改用 `--source-range`。 |
-| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置 10 色色板循环补色。**单独传即生效**；`--highlight=false` 时被忽略。 |
-| `--multiple` | bool | optional | 启用多选 |
+| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组。更新会重写整条验证规则：若用户未要求重置配色，先用 `+dropdown-get` 回读并将现有 `highlight_colors` 作为本 flag 传回；省略会按内置 10 色色板重建。用户明确要求新配色或选项有清晰语义配色时，应选浅色、低饱和度背景以适配黑色文字。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置色板循环补色。单独传即生效；`--highlight=false` 时被忽略。 |
+| `--multiple` | bool | optional | 启用多选。本 flag 只更新验证规则，不会写入选中值；后续用 `+cells-set` 写值时必须传 `multiple_values` 数组，不要传逗号拼接的 `value` |
 | `--highlight` | bool | optional | 下拉胶囊背景色高亮开关。**不传 = 开**（按内置 10 色色板循环上色）；`--highlight=false` 关闭得到纯白下拉。配色用 `--colors` 覆盖。 |
 | `--source-range` | string | xor | listFromRange 模式的下拉源 range，A1 表示法 + sheet 前缀（如 `'Sheet1'!T1:T3`）。映射到 server `data_validation.range`，搭配 server `data_validation.type='listFromRange'` 自动生效。跟 `--options` 二选一：传 `--options` 走 inline 列表（type=list），传本 flag 走 range 引用（type=listFromRange）。`--colors` 长度规则不变（≤ 源 range 单元格数），`--highlight` / `--multiple` 行为相同。当 `--highlight` 开启且 source 覆盖单元格数超过 2000 时，服务端会将该下拉判为 option-error（这是不支持的组合）；CLI 会在返回结果的 `data.warnings` 中给出 warning。如需取消，传 `--highlight=false`。 |
 

package/skills/lark-sheets/references/lark-sheets-legacy-command-migration.md

@@ -0,0 +1,152 @@
+# Lark Sheet 旧命令迁移指南
+
+## 适用场景
+
+调用 `sheets` 旧命令（`+create`、`+read`、`+write`、`+create-sheet`、`+media-upload` 等 42 个）时收到
+`unknown subcommand`，或手上的脚本 / skill 早于表格命令重构。本文给出全部旧命令的替代命令，以及
+**不只是改名**的那些差异（flag 名、单元格 payload 写法、响应字段路径）。
+
+这些旧命令在重构后曾以别名形式保留了一段时间，线上使用量降到 5% 以下后整体删除。它们不再存在，
+也没有 deprecation 提示——直接报 `unknown subcommand`。
+
+## 一、命令名对照表
+
+### 工作簿
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create` | `+workbook-create` |
+| `+info` | `+workbook-info` |
+| `+export` | `+workbook-export` |
+
+### 子表
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create-sheet` | `+sheet-create` |
+| `+copy-sheet` | `+sheet-copy` |
+| `+delete-sheet` | `+sheet-delete` |
+| `+update-sheet` | 按意图拆开：`+sheet-rename` / `+sheet-move` / `+sheet-hide` / `+sheet-unhide` / `+dim-freeze` |
+
+### 单元格数据
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+read` | `+cells-get`（只要纯值 / CSV 用 `+csv-get`，整表用 `+table-get`） |
+| `+write` | `+cells-set` |
+| `+append` | `+table-put --sheets '{"sheets":[{…,"mode":"append"}]}'`（追加到已有数据下方；顶层必须是 `{"sheets":[…]}` 信封，裸数组会被拒绝）；若已知目标行号，`+cells-set` 写该区域即可 |
+| `+find` | `+cells-search` |
+| `+replace` | `+cells-replace` |
+
+### 样式 / 合并 / 单元格图片
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+set-style` | `+cells-set-style` |
+| `+batch-set-style` | `+cells-batch-set-style` |
+| `+merge-cells` | `+cells-merge` |
+| `+unmerge-cells` | `+cells-unmerge` |
+| `+write-image` | `+cells-set-image` |
+
+### 行列
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+add-dimension` | `+dim-insert` |
+| `+insert-dimension` | `+dim-insert` |
+| `+move-dimension` | `+dim-move` |
+| `+delete-dimension` | `+dim-delete` |
+| `+update-dimension` | 按意图拆开：`+rows-resize` / `+cols-resize` / `+dim-hide` / `+dim-unhide` / `+dim-group` / `+dim-ungroup` / `+dim-freeze` |
+
+### 筛选视图
+
+条件（condition）不再是独立对象，已折叠进视图自身的 flag。
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create-filter-view` | `+filter-view-create` |
+| `+update-filter-view` | `+filter-view-update` |
+| `+list-filter-views` | `+filter-view-list` |
+| `+get-filter-view` | `+filter-view-list` |
+| `+delete-filter-view` | `+filter-view-delete` |
+| `+create-filter-view-condition` | `+filter-view-update` |
+| `+update-filter-view-condition` | `+filter-view-update` |
+| `+delete-filter-view-condition` | `+filter-view-update` |
+| `+list-filter-view-conditions` | `+filter-view-list` |
+| `+get-filter-view-condition` | `+filter-view-list` |
+
+### 下拉列表
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+set-dropdown` | `+dropdown-set` |
+| `+update-dropdown` | `+dropdown-update` |
+| `+get-dropdown` | `+dropdown-get` |
+| `+delete-dropdown` | `+dropdown-delete` |
+
+### 浮动图片
+
+单独的上传步骤已折叠进创建命令：`+float-image-create` 直接收本地 `--image` 路径。
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+media-upload` | `+float-image-create`（嵌入单元格内的图片用 `+cells-set-image`） |
+| `+create-float-image` | `+float-image-create` |
+| `+update-float-image` | `+float-image-update` |
+| `+delete-float-image` | `+float-image-delete` |
+| `+get-float-image` | `+float-image-list` |
+| `+list-float-images` | `+float-image-list` |
+
+## 二、只改命令名会踩的坑
+
+### 1. 单元格 payload 词汇变了
+
+旧命令的 `--values` 里，公式写成 `{"type":"formula","text":"=SUM(C2:C5)"}`。这类带 `type` / `text`
+的写法会被 `+cells-set` **直接拒绝**：
+
+```text
+--cells[0][0].type is not a cell field — the value type is inferred from the JSON value;
+control display format via cell_styles.number_format
+```
+
+新写法把字段直接放在 cell 对象上（`{"formula":"=SUM(C2:C5)"}`）：
+
+```bash
+lark-cli sheets +cells-set --range C6 --cells '[[{"formula":"=SUM(C2:C5)"}]]'
+```
+
+内容字段只能选一个：`value` / `formula` / `rich_text` / `multiple_values`；`cell_styles`、`border_styles`、
+`note`、`data_validation` 可与内容字段自由叠加。纯标量（`"文本"`、`123`）也可直接放在格位上。
+完整字段用 `+cells-set --print-schema --flag-name cells` 查看。
+
+`--values` 在 `+cells-set` 上仍作为 `--cells` 的别名被接受，所以**只有携带旧对象写法的调用才会失败**。
+
+### 2. 响应字段路径变了
+
+| 命令 | 取值路径 |
+| --- | --- |
+| `+workbook-create` | spreadsheet token 在 `data.spreadsheet.spreadsheet_token` |
+| `+workbook-info` | 子表列表在 `data.sheets[]`（旧 `+info` 是 `data.sheets.sheets[]`）；**不再回显** spreadsheet token |
+| `+cells-get` | 值在 `data.ranges[].cells[][].value` |
+| `+cells-search` | `data.total_matches`、`data.matches[].address` |
+| `+sheet-create` / `+sheet-copy` | 新子表 id 在 `data.sheet_id` |
+| `+sheet-rename` / `+sheet-hide` | **只返回 `data.revision`**，要确认结果需回读 `+workbook-info`（`sheet_name`、`is_hidden`） |
+| `+dim-freeze` | `data.frozen_rows`、`data.frozen_columns` |
+
+### 3. `+update-sheet` 的一次调用要拆成多次
+
+旧命令在一次调用里同时设置标题、隐藏态和冻结行列；新命令按意图拆开，需要分别调用
+`+sheet-rename`、`+sheet-hide` / `+sheet-unhide`、`+dim-freeze`。
+
+注意 `+dim-freeze` 是**整份冻结状态覆盖**：`--rows` 与 `--cols` 一起表达完整状态，没写的那个轴会变成未冻结。
+
+### 4. 底层接口换了
+
+子表增删改查从 `sheets/v2/spreadsheets/{token}/sheets_batch_update` 换成了
+`sheet_ai/v2/spreadsheets/{token}/tools/invoke_write`（`modify_workbook_structure`）。
+只有直接断言过 HTTP 请求体的调用方需要关心这条。
+
+## 三、找不到对应命令时
+
+`lark-cli sheets --help` 列出全部当前命令；单个命令的 flag 与示例用 `lark-cli sheets <命令> --help`。
+按任务选命令的决策表见 [SKILL.md](../SKILL.md)。

package/skills/lark-sheets/references/lark-sheets-read-data.md

@@ -24,13 +24,13 @@
 | 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本（每行带 `[row=N]` 前缀）；大表请按 `--range` 行窗口分批读（截断时看 `has_more`） |
 | 按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`） | `+table-get` | 对话上下文 | 返回 typed 协议（`columns:[列名]` + `data` + `dtypes`/`formats` + `range`），输出形状对齐 pandas split；可一行 `pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])` 还原 DataFrame，或直接 round-trip 回 `+table-put`。不带 `--range` 时读**完整 used range**（跨过表中部空行 / 空列），每个子表回传读取范围 `range`；被 `max_chars` 裁掉时**该子表**带 `truncated: true` 与 `truncation_warning`，预算耗尽导致后续整表未读时**顶层**也带同组字段，`--output-path` 落盘模式另看 stdout 回执的 `complete` / `truncated`——**先看截断字段再用数据；三层都没报也不等于逻辑读全**，仍要用返回数据实际行数、关键末行与源数据交叉核对（详见下文）。注意这与下文 `current_region` "遇表中部空行截断"不矛盾：`+table-get` 读的是子表物理 used range（飞书记录的已用矩形，含中间空行），`current_region` 是从锚点连通扩展、遇整行空行就断 |
 | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 |
-| 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |
+| 查看某区域的下拉框（数据验证）配置 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围的下拉选项、多选开关和胶囊配色 |
 
 **选择原则**：
 - 只看值或做数据处理 → `+csv-get`；大表分批读取，避免一次拉全表撑爆上下文
 - 要按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`）→ `+table-get`
 - 需要公式/样式/批注 → `+cells-get`
-- 只想知道某区域下拉框有哪些选项 → `+dropdown-get`
+- 查看某区域下拉框的选项、多选开关或胶囊配色 → `+dropdown-get`
 
 ## 读表理解脚本（Agent 优先入口）
 

package/skills/lark-sheets/references/lark-sheets-write-cells.md

@@ -193,14 +193,38 @@ Step 2: `+styles-put` — 对 A2:A100 声明统一的 fill + border 样式
 
 两个 flag **必须传一个、且只能传一个**——同时传或都不传，CLI 会立刻报错。`--source-range` 用 A1 + sheet 前缀写法（如 `'Sheet1'!T1:T3`，sheet 名按 A1 标准单引号包裹），可以指同 sheet 也可以指其它 sheet（如 `'Refs'!A1:A10`）。
 
-### 配色：默认即上色，三种意图三条线
+### 多选下拉：验证规则与选中值是两层数据
 
-下拉**默认带胶囊高亮**——什么 flag 都不传时，所有选项按内置 10 色色板循环上色，跟 UI 手动配下拉的默认行为对齐。三种意图：
+`+dropdown-set --multiple` 只把目标单元格的验证规则设为“允许多选”，**不会写入当前选中值**。后续用 `+cells-set` 填充多选结果时，必须把每个选项写成 `multiple_values` 数组项；不要把多个选项用逗号拼成一个普通 `value`，否则整串会被当成单值并触发数据验证失败。
+
+```bash
+# 先创建允许多选的下拉规则
+lark-cli sheets +dropdown-set \
+  --spreadsheet-token shtXXX --sheet-id "$SID" \
+  --range "E2:E15" \
+  --options '["A","B","C","D"]' \
+  --multiple
+
+# 再向 E6 写入 3 个选中值
+lark-cli sheets +cells-set \
+  --spreadsheet-token shtXXX --sheet-id "$SID" \
+  --range "E6" \
+  --cells '[[{"multiple_values":[{"value":"A"},{"value":"B"},{"value":"C"}]}]]'
+```
+
+### 配色：新建默认用内置色板，更新保留已有配色
+
+下拉**默认带胶囊高亮**——新建时不传 `--highlight` / `--colors`，所有选项按内置 10 色色板循环上色，跟 UI 手动配下拉的默认行为对齐。只有用户明确指定自定义颜色，或选项具有清晰的语义配色（如状态、风险、优先级，且颜色有助于理解）时才传 `--colors`。
+
+下拉胶囊文字默认是黑色。自定义颜色时应使用**浅色、低饱和度背景**，避免鲜艳或偏深的色值影响可读性。
+
+`+dropdown-update` 会重写整条验证规则。若用户没有要求重置已有配色，先用 `+dropdown-get` 回读，并把现有 `highlight_colors` 作为 `--colors` 传回；省略会按内置色板重建。
 
 | 想要的效果 | 怎么传 |
 |---|---|
-| 默认色板循环上色 | 都不传 `--highlight` / `--colors` |
-| 按选项指定具体颜色 | 只传 `--colors '["#hex",...]'`（不需要再传 `--highlight`） |
+| 新建时使用默认色板 | 都不传 `--highlight` / `--colors` |
+| 更新时保留已有配色 | 先 `+dropdown-get` 回读，再将 `highlight_colors` 作为 `--colors` 传回 |
+| 用户明确要求或选项有语义配色 | 只传浅色、低饱和度的 `--colors '["#hex",...]'`（不需要再传 `--highlight`） |
 | 纯白下拉、不要高亮 | 传 `--highlight=false`（注意 `=false` 不能省，单写 `--highlight` 在 cobra 里等价于 true） |
 
 `--colors` 长度**可以短于**选项数（list 模式短于 `--options` 长度，listFromRange 模式短于 `--source-range` 的单元格数），未指定的选项按内置色板循环补色；但**不能长于**——CLI 在 Validate 阶段就会拦截，错误形如 `--colors length (4) must not exceed dropdown source size (3)`。
@@ -211,36 +235,35 @@ Step 2: `+styles-put` — 对 A2:A100 声明统一的 fill + border 样式
 
 **`--options` 模式 — 默认色板（最常见）**：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
   --options '["待开始","进行中","已完成","已取消"]'
 ```
 
-**`--options` 模式 — 指定颜色**（4 个选项配 3 个颜色，第 4 个按色板补）：
+**用户明确要求语义配色时**：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
-  --options '["待开始","进行中","已完成","已取消"]' \
-  --colors '["#bff7d9","#FFE699","#bacefd"]'
+  --options '["待开始","进行中","已完成"]' \
+  --colors '["#E8F3FF","#FFF3D6","#E8F8E8"]'
 ```
 
 **`--source-range` 模式**（先在 `'Sheet1'!T1:T3` 维护「男/女/保密」三行，再让 `B2:B21` 引用它）：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range B2:B21 \
-  --source-range ''\''Sheet1'\''!T1:T3' \
-  --colors '["#cce8ff","#ffd6e7","#e6e6e6"]'
+  --source-range ''\''Sheet1'\''!T1:T3'
 ```
 
 **纯白下拉**（明确告诉用户"不要彩色"时才用）：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
@@ -252,7 +275,7 @@ lark-cli sheets +dropdown-set \
 >
 > ⚠️ **`--ranges` 类批量 flag 的 sheet 前缀必须「裸写」**——`+cells-batch-clear` / `+dropdown-update` / `+dropdown-delete` 的 `--ranges` 解析器不接受引号：表名含点或空格（如 `2025.9`、`一月份`）也直接写 `2025.9!A1`，写成 `'2025.9'!A1` 会被当成表名一部分、报 `sheet not found`。**但 `--source-range`、透视表 `--source`、`--range` 走 A1 标准**：sheet 名带单引号（如 `'Sheet1'!A1:B2`）是标准写法、裸写也接受，回读统一返回带引号形式——别把 `--ranges` 的裸写要求套到这些 flag 上。
 
-`+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。
+`+dropdown-update`（多 range 批量更新）的目标 `--ranges` 是 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。它会替换完整验证规则；需要保留现有配色时，按上文先回读并透传 `--colors`。
 
 ## Shortcuts
 
@@ -274,7 +297,7 @@ _公共四件套 · 系统：`--dry-run`_
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `--range` | string | xor | 写入区域（A1 格式）。与 `--writes` 二选一（单区域用 --range+--cells，多区域用 --writes） |
-| `--cells` | string + File + Stdin（复合 JSON） | xor | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等，完整字段跑 `--print-schema` |
+| `--cells` | string + File + Stdin（复合 JSON） | xor | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `multiple_values` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等。向启用多选的下拉单元格写入选中值时，必须用 `multiple_values:[{"value":...}]`，不要把多个选项用逗号拼成一个 `value`；完整字段跑 `--print-schema` |
 | `--writes` | string + File + Stdin（复合 JSON） | xor | 多区域写入 JSON 数组（最多 100 项），每项 `{sheet_name\|sheet_id, range, cells}`——**sheet 定位必须写在每项里**（与 +batch-update 子操作、+styles-put 项同惯例，不认顶层 --sheet-name），cells 结构同 `--cells`（二维数组，可逐格带 cell_styles/border_styles）。整批展开为**单次批量提交**（fail-fast，失败后先回读再补发），支持跨 sheet；典型场景：批量修复散布多处的公式、跨表同构写入——不要为此拼 +batch-update 的 --operations。与 `--range`+`--cells` 二选一；范围级统一样式不在此做，写完接 +styles-put |
 | `--allow-overwrite` | bool | optional | 允许覆盖非空 cell（默认 true）；设为 false 时遇非空 cell 报错 |
 | `--max-cells` | int | optional | 防爆，默认 50000（隐藏 flag：不在 `--help` 列出，但可正常传入） |
@@ -318,8 +341,8 @@ _公共四件套 · 系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） |
 | `--options` | string + File + Stdin（复合 JSON） | xor | 下拉选项 JSON 数组，例如 `["opt1","opt2"]`。服务端不限制选项数量，也不限制单个选项长度；含逗号的选项可以接受（写入时会自动转义）。大量选项建议改用 `--source-range`。 |
-| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置 10 色色板循环补色。**单独传即生效**；`--highlight=false` 时被忽略。 |
-| `--multiple` | bool | optional | 启用多选；默认 `false` |
+| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组。新建时默认不要传：省略即使用内置 10 色色板；仅在用户明确要求或选项有清晰语义配色时传。胶囊文字默认黑色，应选浅色、低饱和度背景。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置色板循环补色。单独传即生效；`--highlight=false` 时被忽略。 |
+| `--multiple` | bool | optional | 启用多选；默认 `false`。本 flag 只设置验证规则，不会写入选中值；后续用 `+cells-set` 写值时必须传 `multiple_values` 数组，不要传逗号拼接的 `value` |
 | `--highlight` | bool | optional | 下拉胶囊背景色高亮开关。**不传 = 开**（按内置 10 色色板循环上色）；`--highlight=false` 关闭得到纯白下拉。配色用 `--colors` 覆盖。 |
 | `--source-range` | string | xor | listFromRange 模式的下拉源 range，A1 表示法 + sheet 前缀（如 `'Sheet1'!T1:T3`）。映射到 server `data_validation.range`，搭配 server `data_validation.type='listFromRange'` 自动生效。跟 `--options` 二选一：传 `--options` 走 inline 列表（type=list），传本 flag 走 range 引用（type=listFromRange）。`--colors` 长度规则不变（≤ 源 range 单元格数），`--highlight` / `--multiple` 行为相同。当 `--highlight` 开启且 source 覆盖单元格数超过 2000 时，服务端会将该下拉判为 option-error（这是不支持的组合）；CLI 会在返回结果的 `data.warnings` 中给出 warning。如需取消，传 `--highlight=false`。 |