npm - @yandy0725/pi-lark - Versions diffs - 0.1.0 - Mend

@yandy0725/pi-lark 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (392) hide show

package/skills/lark-openapi-explorer/SKILL.md ADDED Viewed

@@ -0,0 +1,153 @@
+---
+name: lark-openapi-explorer
+version: 1.0.0
+description: "飞书/Lark 原生 OpenAPI 探索：从官方文档库中挖掘未经 CLI 封装的原生 OpenAPI 接口。当用户的需求无法被现有 lark-* skill 或 lark-cli 已注册命令满足，需要查找并调用原生飞书 OpenAPI 时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+# OpenAPI Explorer
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解认证、身份切换和安全规则。
+当用户的需求**无法被现有 skill 或 CLI 已注册 API 覆盖**时，使用本技能从飞书官方 markdown 文档库中逐层挖掘原生 OpenAPI 接口，然后通过 `lark-cli api` 裸调完成任务。
+## 文档库结构
+飞书 OpenAPI 文档以 markdown 层级组织：
+```
+llms.txt                          ← 顶层索引，列出所有模块文档链接
+  └─ llms-<module>.txt            ← 模块文档，包含功能概述 + 底层 API 文档链接
+       └─ <api-doc>.md            ← 单个 API 的完整说明（方法/路径/参数/响应/错误码）
+```
+文档入口：
+| 品牌 | 入口 URL |
+|------|----------|
+| 飞书 (Feishu) | `https://open.feishu.cn/llms.txt` |
+| Lark | `https://open.larksuite.com/llms.txt` |
+> 所有文档以**中文**编写。如果用户使用英文交流，需将文档内容翻译为英文后输出。
+## 挖掘流程
+严格按以下步骤逐层检索，**不要跳步或猜测 API**：
+### Step 1：确认现有能力不足
+```bash
+# 先检查是否已有对应的 skill 或已注册 API
+lark-cli <可能的service> --help
+```
+如果已有对应命令或 shortcut，直接使用，**不需要继续挖掘**。
+### Step 2：从顶层索引定位模块
+用 WebFetch 获取顶层索引，找到与需求相关的模块文档链接：
+```
+WebFetch https://open.feishu.cn/llms.txt
+  → 提取问题："列出所有模块文档链接，找出与 <用户需求关键词> 相关的链接"
+```
+- 飞书品牌使用 `open.feishu.cn`
+- Lark 品牌使用 `open.larksuite.com`
+- 如不确定用户品牌，默认使用飞书
+### Step 3：从模块文档定位具体 API
+用 WebFetch 获取模块文档，找到具体 API 的文档链接：
+```
+WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-<module>.txt
+  → 提取问题："找出与 <用户需求> 相关的 API 说明和文档链接"
+```
+### Step 4：获取 API 完整规范
+用 WebFetch 获取具体 API 文档，提取完整的调用规范：
+```
+WebFetch https://open.feishu.cn/document/server-docs/.../<api>.md
+  → 提取问题："返回完整 API 规范：HTTP 方法、URL 路径、路径参数、查询参数、请求体字段（名称/类型/必填/说明）、响应字段、所需权限、错误码"
+```
+### Step 5：通过 CLI 调用 API
+使用 `lark-cli api` 裸调：
+```bash
+# GET 请求
+lark-cli api GET /open-apis/<path> --params '{"key":"value"}'
+# POST 请求
+lark-cli api POST /open-apis/<path> --data '{"key":"value"}'
+# PUT 请求
+lark-cli api PUT /open-apis/<path> --data '{"key":"value"}'
+# DELETE 请求
+lark-cli api DELETE /open-apis/<path>
+```
+## 输出规范
+向用户呈现挖掘结果时，按以下格式组织：
+1. **API 名称与功能**：一句话描述
+2. **HTTP 方法与路径**：`METHOD /open-apis/...`
+3. **关键参数**：列出必填和常用可选参数
+4. **所需权限**：scope 列表
+5. **调用示例**：给出 `lark-cli api` 的完整命令
+6. **注意事项**：频率限制、特殊约束等
+如果用户使用英文交流，将以上所有内容翻译为英文。
+## 安全规则
+- **写入/删除类 API**（POST/PUT/DELETE）调用前必须确认用户意图
+- 建议先用 `--dry-run` 预览请求（如支持）
+- 不要猜测 API 路径或参数——必须从文档中获取确认
+- 涉及敏感操作（删除群、移除成员等）时，向用户说明影响范围
+## 使用场景示例
+### 场景 1：用户需要拉人进群（未被 CLI 封装）
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 发现没有 chat_members 相关的 create 命令
+# Step 2-4: 通过文档挖掘获得 API 规范
+# → POST /open-apis/im/v1/chats/:chat_id/members
+# Step 5: 调用
+lark-cli api POST /open-apis/im/v1/chats/oc_xxx/members \
+  --data '{"id_list":["ou_xxx","ou_yyy"]}' \
+  --params '{"member_id_type":"open_id"}'
+```
+### 场景 2：用户需要设置群公告
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 没有 announcement 相关命令
+# Step 2-4: 挖掘文档
+# → PATCH /open-apis/im/v1/chats/:chat_id/announcement
+# Step 5: 调用
+lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement \
+  --data '{"revision":"0","requests":["<html>公告内容</html>"]}'
+```
+## 参考
+- [lark-shared](../lark-shared/SKILL.md) — 认证和全局参数
+- [lark-skill-maker](../lark-skill-maker/SKILL.md) — 如需将挖掘到的 API 固化为新 Skill

package/skills/lark-shared/SKILL.md ADDED Viewed

@@ -0,0 +1,168 @@
+---
+name: lark-shared
+version: 1.0.0
+description: "Use when first setting up lark-cli, running auth login, switching user/bot identity (--as), handling permission denied or scope errors, needing to update lark-cli, or seeing _notice in JSON output."
+---
+# lark-cli 共享规则
+本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
+## 配置初始化
+首次使用需运行 `lark-cli config init` 完成应用配置。
+当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
+**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时：**必须生成二维码**：你必须调用 `lark-cli auth qrcode` 将 URL 转为二维码并展示给用户，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**URL 输出规则**：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），二维码和链接请一起展示给用户。
+```bash
+# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
+lark-cli config init --new
+```
+## 认证
+### 身份类型
+两种身份类型，通过 `--as` 切换：
+| 身份 | 标识 | 获取方式 | 适用场景 |
+|------|------|---------|---------|
+| user 用户身份 | `--as user` | `lark-cli auth login` 等 | 访问用户自己的资源（日历、云空间/云盘/云存储等） |
+| bot 应用身份 | `--as bot` | 自动，只需 appId + appSecret | 应用级操作,访问bot自己的资源 |
+### 身份选择原则
+输出的 `[identity: bot/user]` 代表当前身份。bot 与 user 表现差异很大，需确认身份符合目标需求：
+- **Bot 看不到用户资源**：无法访问用户的日历、云空间（云盘/云存储）文档、邮箱等个人资源。例如 `--as bot` 查日程返回 bot 自己的（空）日历
+- **Bot 无法代表用户操作**：发消息以应用名义发送，创建文档归属 bot
+- **Bot 权限**：只需在飞书开发者后台开通 scope，无需 `auth login`
+- **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足
+### 权限不足处理
+遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
+错误响应中包含关键信息：
+- `permission_violations`：列出缺失的 scope (N选1)
+- `console_url`：飞书开发者后台的权限配置链接
+- `hint`：建议的修复命令
+#### Bot 身份（`--as bot`）
+将错误中的 `console_url` 原样提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
+#### User 身份（`--as user`）
+```bash
+lark-cli auth login --domain <domain>           # 按业务域授权
+lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推荐,符合最小权限原则）
+```
+**规则**：auth login 必须指定范围（`--domain` 或 `--scope`）。多次 login 的 scope 会累积（增量授权）。
+#### Agent 代理发起认证（推荐）
+当你作为 AI agent 需要帮用户完成认证时，优先使用 split-flow，避免在同一轮对话中阻塞等待用户授权：
+```bash
+# 发起授权（立即返回 device_code 和 verification_url）
+lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json
+```
+拿到 `verification_url` 后，将它原样作为本轮最终消息发给用户，并结束本轮/交还控制权。不要在同一轮中展示 URL 后立刻执行 `--device-code` 阻塞轮询；在不透传中间输出的 agent harness 里，这会导致用户永远看不到 URL。
+用户回复已完成授权后，再在后续步骤执行：
+```bash
+lark-cli auth login --device-code <device_code>
+```
+**Split-Flow 完整步骤**：
+**第一步：发起授权（当前轮）**
+1. 执行 `lark-cli auth login --scope "xxx" --no-wait --json`（必须加 `--no-wait --json`）
+2. 从 JSON 输出中提取 `verification_url` 和 `device_code`
+3. 生成二维码：`lark-cli auth qrcode <verification_url> --output "xxx"`
+4. 将 URL 和二维码展示给用户（先 URL，后二维码）
+5. **结束本轮对话前，必须明确告知用户**："请完成授权后，回来告诉我已授权完成，我会帮你完成后续步骤"
+**第二步：完成授权（后续轮）**
+1. 等待用户回复"已完成授权"
+2. **由你（AI agent）亲自执行**：`lark-cli auth login --device-code <device_code>`
+3. 此命令会轮询授权状态并完成登录
+4. 如果返回授权成功，流程结束
+**关键规则**：
+- **你必须亲自执行 `--device-code` 命令**，不要指示用户自行执行
+- **不要在同一轮中展示 URL 后立刻执行 `--device-code`**，这会导致用户看不到 URL
+- **禁止缓存 `verification_url` 或 `device_code`**：每次需要授权时，必须重新执行 `lark-cli auth login --no-wait --json` 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用
+## 更新检查
+lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
+**当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
+1. 告知用户当前版本和最新版本号
+2. 提议执行更新（同时更新 CLI 和 Skills）：
+   ```bash
+   lark-cli update
+   ```
+3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
+**重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
+**规则**：不要静默忽略更新提示。即使当前任务与更新无关，也应在完成用户请求后补充告知。
+## 安全规则
+- **禁止输出密钥**（appSecret、accessToken）到终端明文。
+- **写入/删除操作前必须确认用户意图**。
+- 用 `--dry-run` 预览危险请求。
+- **文件路径只接受相对路径**：`--file`、`--output`、`--output-dir`、`@file` 等路径参数只接受 cwd 下的相对路径，传绝对路径会报 `unsafe file path`。数据输入（`@file`、大 JSON）优先用 stdin 传入，避免路径和转义问题。
+## 高风险操作的审批协议（exit 10）
+lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。当你不带 `--yes` 调用这类命令时，CLI 会退出码 `10`、并在 stderr 返回如下结构化 envelope：
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "confirmation_required",
+    "message": "drive +delete requires confirmation",
+    "hint": "add --yes to confirm",
+    "risk": {
+      "level": "high-risk-write",
+      "action": "drive +delete"
+    }
+  }
+}
+```
+**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
+1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation_required"`
+2. **向用户确认**：把 `error.risk.action` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
+3. **用户同意** → 在你**原始 argv 的末尾追加 `--yes`** 后重试
+4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁
+**绝对不允许**：
+- 看到 exit 10 就默认加 `--yes` 静默重试（这等于禁用门禁）
+- 把 `confirmation_required` 当网络错误/权限错误处理
+- 在用户没明确同意的前提下追加 `--yes` 重试
+- 用 `sh -c` 等 shell 方式拼接命令重试——用 `exec.Command(argv...)` 参数数组形式，避免 shell 解析把用户参数当作语法
+提前预判：想先让用户 review 危险操作的具体请求，调用时加 `--dry-run`——它不触发门禁，会打印完整请求详情（URL / body / params），你可以把这个预览给用户看过再去真正执行。
+### 如何识别一条命令是高风险
+- shortcut：`lark-cli <service> +<cmd> --help` 顶部会显示 `Risk: high-risk-write`
+- service 命令：`lark-cli schema <service>.<resource>.<method> --format json` 的返回值里 `"risk": "high-risk-write"`

package/skills/lark-shared/references/lark-wiki-token-routing.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Wiki token routing
+Wiki URL 中的 `/wiki/<token>` 是节点 token，不一定是底层文档、表格、Base、文件或幻灯片的对象 token。需要对底层对象做读取、评论、导出、下载、表内操作等动作时，先解包，再按底层类型路由。
+## 推荐方式
+优先使用 `lark-drive` 的 `drive +inspect`：
+```bash
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/<wiki_token>'
+```
+输出中的 `type` 是底层对象类型，`token` 是后续命令应使用的 canonical token。`wiki_node` 字段保留节点侧信息，如 `space_id`、`node_token`、`obj_token`、`obj_type`。
+## 手动方式
+如果不能使用 shortcut，再调用 Wiki 节点接口：
+```bash
+lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
+```
+从返回值中读取：
+| 字段 | 含义 |
+|------|------|
+| `node.obj_type` | 底层对象类型，如 `docx`、`doc`、`sheet`、`bitable`、`slides`、`file`、`mindnote` |
+| `node.obj_token` | 底层对象 token，用于对应业务 skill 或原生 API |
+| `node.node_token` / `token` | Wiki 节点 token，用于 Wiki 节点层级操作 |
+| `node.space_id` | 所属知识空间 |
+## 路由
+| `obj_type` | 后续操作 |
+|------------|----------|
+| `docx` / `doc` | 文档内容走 `lark-doc`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `sheet` | 表内数据走 `lark-sheets`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `bitable` | 表内数据走 `lark-base`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `slides` | 幻灯片内容编辑走 `lark-slides`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `file` | 普通文件上传、下载、评论、权限等走 `lark-drive` |
+| `mindnote` | 思维笔记的移动、删除、快捷方式、权限、安全标签等云空间能力走 `lark-drive`；知识库节点层级操作走 `lark-wiki` |
+| wiki 节点层级 / 空间成员 | 走 `lark-wiki`，不要把底层对象 token 当节点 token |

package/skills/lark-sheets/SKILL.md ADDED Viewed

@@ -0,0 +1,165 @@
+---
+name: lark-sheets
+version: 3.0.0
+description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+    siblings: ["lark-shared"]
+  cliHelp: "lark-cli sheets --help"
+---
+# sheets
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。**
+## 术语约定
+下列词在本 skill 各文档中可能交替出现，但**指同一对象**；解析用户口语时按此映射，不要当成不同概念：
+| 标准用语 | 同义 / 口语（均指同一对象） | 说明 |
+| --- | --- | --- |
+| 工作表（sheet） | 子表、tab、标签页 | spreadsheet 内的单张表；`sheet_id` 是其稳定标识 |
+| 电子表格（spreadsheet） | 工作簿、表格 | 顶层容器；由 `--url` 或 `--spreadsheet-token` 定位 |
+| reference_id | id | **表内对象**的稳定标识，即各对象主键 flag 接受的值（见下表）。⚠️ 与 `lark-sheets-float-image` 的 `--image-uri`（图片上传句柄）不是一回事，后者不属于 reference_id |
+每类对象用各自的主键 flag 定位（命名不统一，按此表对照，不要凭直觉拼）：
+| 对象 | 主键 flag | 对象 | 主键 flag |
+| --- | --- | --- | --- |
+| 工作表 sheet | `--sheet-id` | 条件格式规则 | `--rule-id` |
+| 图表 chart | `--chart-id` | 筛选视图 | `--view-id` |
+| 透视表 pivot | `--pivot-table-id` | 迷你图（按组） | `--group-id` |
+| 浮动图片 | `--float-image-id` | | |
+## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
+把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。
+| 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 cobra 拒） |
+| --- | --- | --- |
+| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `+get-range`、`+range-get`、`+cells-read` |
+| 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` |
+| 写纯文本值（整块 CSV 平铺，列里没有需保留的数值 / 日期语义） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | — |
+| 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数，要可排序 / 求和 / 入图表 / 透视） | `+table-put --sheets` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理，详见 write-cells） | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力） |
+| **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢，详见 workbook） | 用 `--values` 灌日期 / 数字（会落成文本、丢类型） |
+| 写值 / 公式 / 样式 | `+cells-set`（定位用 `--range`） | — |
+| 插图：图片**绑定到某条记录**、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） | `+cells-set-image`（单格 `--range`，嵌入单元格内） | — |
+| 插图：**自由摆放、不绑数据**的装饰 / 标识（logo / 水印 / 封面大图 / banner） | `+float-image-create`（浮动图片，自由定位 + 尺寸 + 层级） | — |
+| 查找单元格 | `+cells-search`（关键字用 `--find`） | `+cells-find`、`+find`、`--query` |
+| 查找并替换 | `+cells-replace` | — |
+| 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `+sheet-info` | `+sheet-get`、`+structure-get`、`+sheet-structure-get` |
+| 看工作簿 / 子表清单 | `+workbook-info` | `+sheet-list`、`+workbook-get`、`+workbook-list` |
+| 导出 xlsx / 单表 csv | `+workbook-export` | — |
+| 导入本地 xlsx/xls/csv 文件为飞书电子表格 | `+workbook-import --file ./x.xlsx`（本地表格文件 → 飞书电子表格的正解；仅要导成多维表格 bitable 时才用 `drive +import --type bitable`） | `drive +import`（导电子表格时绕了 drive 通道、还要多给 `--type`，应直接用 `+workbook-import`）、把 .xlsx 在本地读成数据再 `+workbook-create` 重灌 |
+| 清除内容 / 格式 | `+cells-clear`（范围维度用 `--scope`，取值 content / formats / all） | `--type` |
+| 批量清除多区域 | `+cells-batch-clear`（`--scope`） | `--target` |
+| 调整列宽 / 行高 | `+cols-resize` / `+rows-resize`（行、列是两个独立命令） | `--dimension`（无此 flag） |
+| 分组汇总 / 透视 | `+pivot-create`（默认不传落点 flag → 自动新建子表，零覆盖） | 用 SUMIF / 本地脚本拼一张假透视表 |
+> ⚠️ **两种图片别选错**：图若**绑定某条记录、要随行排序 / 筛选 / 增删**（凭证 / 证件照 / 每行配图，话里带「对应 / 每行 / 这列」等绑定词）→ 单元格图片 `+cells-set-image`；只是自由摆放的装饰（logo / 水印 / 封面）→ 浮动图片 `+float-image-create`。别因「浮动图更好控制 / 更熟」默认选浮动图。
+> ⚠️ **纯文本还是数值语义**：要写的列里有数字 / 金额 / 百分比 / 日期 / 计数 → `+table-put`（写入已有表；外层 `{"sheets":[...]}` 包裹、列 pandas dtype 用 `dtypes`、展示格式用 `formats`，保留排序 / 求和 / 图表 / 透视能力；**目标表还不存在就用 `+workbook-create --sheets`**，同 typed 协议、一步建表 + 写入，别先建空表再 `+table-put`）；只有纯文本才用 `+csv-put`。两者写完显示可以完全相同，但 `+csv-put` 落的是文本、不能参与计算——别把数值在本地拼成带 `$` / `%` 的字符串再走 `+csv-put`。
+> ⚠️ **定位 flag**：`+cells-get` / `+cells-set` / `+csv-get` 用 `--range`；`+csv-put` 规范用 `--start-cell`（单个左上角锚点格），也接受 `--range` 别名（区间自动取左上角），二者择一即可。
+> ⚠️ **读取附加信息**一律走 `+cells-get --include …`，**没有** `--with-styles` 这类 flag；**看合并单元格**用 `+sheet-info` 的 `merged_cells`，不要在 `+cells-get` 里找 merge flag。
+## References
+本 skill 的 reference 分两组：先读**通用方法与规范**（横切所有任务的工作流、铁律、样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入**工具参考**查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，其中的铁律对所有工具参考一律生效。
+### 通用方法与规范（先读，横切所有任务，不含具体 shortcut）
+| Reference | 描述 |
+| --- | --- |
+| [飞书表格核心操作：分析、编辑与可视化](references/lark-sheets-core-operations.md) | 飞书表格核心操作工作流。当用户需要对已有的飞书表格进行查看、分析、编辑或可视化时使用。适用场景：数据查询与统计、公式计算、表格美化、创建图表/透视表、筛选排序、批量修改数据、调整表格结构等。即使用户没有明确说"飞书表格"，只要操作对象是已有的在线表格，都应触发此工作流。 |
+| [飞书表格样式与配色规范](references/lark-sheets-visual-standards.md) | 飞书表格样式与配色规范：表头/数据区/汇总行的颜色、字号、对齐、边框等取值标准，以及新增汇总行、追加行列继承原表风格、已有区域美化等典型场景的决策流程与样式要点。工具调用参数细节请参考对应的 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮、标红、数据条、色阶）请使用 lark-sheets-conditional-format。 |
+| [飞书表格公式生成规则](references/lark-sheets-formula-translation.md) | Excel 公式到飞书表格公式的迁移与生成规则。核心目标不是保留 Excel 原语法，而是按飞书表格可执行规则重写公式，并在结果上尽量对齐 Excel。当用户要求把 Excel 公式改写成飞书表格公式，或需要生成飞书公式（尤其涉及 ARRAYFORMULA、原生数组函数、INDEX/OFFSET、MAP/LAMBDA、日期差、多层范围结果与二次展开）时使用。 |
+### 按对象的工具参考（含 shortcut）
+| Reference | 描述 |
+| --- | --- |
+| [Lark Sheet Workbook](references/lark-sheets-workbook.md) | 管理飞书表格的工作簿结构（子表列表及元数据）。当用户提到"看看这个表格有什么"、"表格结构"、"有哪些 sheet"、"新建一个 sheet"、"删除这个工作表"、"重命名"、"复制一份"、"移动到前面"时使用。 |
+| [Lark Sheet Sheet Structure](references/lark-sheets-sheet-structure.md) | 管理飞书表格的子表结构与布局。适用场景：查看行高、列宽、隐藏行列、合并单元格等布局信息，以及"插入一行"、"删除这列"、"隐藏行"、"冻结表头"、行列分组（大纲折叠/展开）等操作。行列大纲仅在用户明确提到"行分组"、"列分组"、"大纲"、"outline"时才触发，"按XXX分组"等数据分组场景请使用 lark-sheets-pivot-table。如需在表尾追加数据，应先通过此 skill 插入行，再通过 lark-sheets-write-cells 写入。 |
+| [Lark Sheet Read Data](references/lark-sheets-read-data.md) | 读取飞书表格中的单元格数据。当用户需要"看看数据"、"分析数据"、"统计/汇总"时使用；也适用于需要查看公式、样式、批注等详细信息的场景。 |
+| [Lark Sheet Search & Replace](references/lark-sheets-search-replace.md) | 在飞书表格中搜索和替换文本，支持限定范围、大小写匹配、精确匹配、正则表达式。当用户需要"查找"、"搜索"、"定位"某个值，或"替换"、"批量修改文本"、"把 A 改成 B"时使用。不要用于理解表格结构（应读取数据）、不要用于数据分析（应读取数据后计算）、不要把用户操作动作中的关键词（如"汇总金额""统计数量"）当作搜索词。 |
+| [Lark Sheet Write Cells](references/lark-sheets-write-cells.md) | 向飞书表格的指定区域批量写入值、公式、样式、批注或单元格图片。适用场景：填写数据、设置公式、修改格式、添加批注、嵌入单元格图片（如需操作浮动图片，请使用 lark-sheets-float-image）；若只需把一块 CSV 批量铺到表格上（值或公式，不带样式/批注），直接使用 `+csv-put` 更短更快。追加数据需先通过 lark-sheets-sheet-structure 插入行列。 |
+| [Lark Sheet Range Operations](references/lark-sheets-range-operations.md) | 对飞书表格中指定区域执行结构性操作（不涉及写入单元格数据值）。适用场景：清除内容或格式（"清空"、"删除内容"、"去掉格式"）、合并/取消合并单元格、调整行高列宽（"加宽列"、"自适应列宽"）、移动/复制/填充/排序数据（"移动数据"、"复制到"、"自动填充"、"按某列排序"）。写入单元格数据请使用 lark-sheets-write-cells。 |
+| [Lark Sheet Batch Update](references/lark-sheets-batch-update.md) | 将多个飞书表格写入操作合并为一次批量执行，按顺序依次完成。适合需要连续执行多个写入操作的场景（如先修改结构再写入数据）。 |
+| [Lark Sheet Chart](references/lark-sheets-chart.md) | 管理飞书表格中的图表（柱形图、折线图、饼图、条形图、面积图、散点图、组合图、雷达图等）。当用户需要创建图表、修改图表样式或数据源、查看已有图表配置、删除图表时使用。也适用于用户提到"数据可视化"、"画个图"、"趋势分析"、"对比图"、"占比分析"、"做个图表"等数据可视化相关场景。 |
+| [Lark Sheet Pivot Table](references/lark-sheets-pivot-table.md) | 管理飞书表格中的数据透视表。当用户需要创建透视表、修改透视表的行列字段/聚合方式/筛选条件、查看已有透视表配置、删除透视表时使用。也适用于用户提到"分组汇总"、"交叉分析"、"按XXX统计"、"按字段分组"、"再分下组"、"多维分析"、"数据透视"等场景。 |
+| [Lark Sheet Conditional Format](references/lark-sheets-conditional-format.md) | 管理飞书表格中的条件格式规则（重复值高亮、单元格值比较、数据条、色阶、排名、自定义公式等）。当用户需要创建条件格式、修改已有规则的范围或样式、查看当前条件格式配置、删除规则时使用。也适用于用户提到"高亮"、"标红"、"颜色标记"、"数据条"、"色阶"、"条件样式"等场景。 |
+| [Lark Sheet Filter](references/lark-sheets-filter.md) | 管理飞书表格中的筛选器（filter）。当用户需要筛选数据（按文本/数值/颜色/日期条件过滤行）、查看已有筛选配置、修改或删除筛选器时使用。也适用于"只看"、"筛选出"、"仅保留符合条件的"等场景。 |
+| [Lark Sheet Filter View](references/lark-sheets-filter-view.md) | 管理飞书表格中的筛选视图（filter view）。当用户需要"建一个 XX 视图"、"保存这个筛选状态"、"切换不同筛选"、维护一个 sheet 上多份独立筛选配置时使用。视图与筛选器（filter）相互独立，可在同一 sheet 共存；视图的隐藏行仅在用户进入该视图时本地生效，不影响其他协作者。 |
+| [Lark Sheet Sparkline](references/lark-sheets-sparkline.md) | 管理飞书表格中的迷你图（折线迷你图、柱形迷你图、胜负迷你图）。当用户需要在单元格内嵌入小型图表来展示数据趋势时使用。也适用于"趋势线"、"单元格内图表"、"迷你图"等场景。注意：不等同于被禁用的 SPARKLINE() 公式函数。 |
+| [Lark Sheet Float Image](references/lark-sheets-float-image.md) | 管理飞书表格中的浮动图片。当用户需要在表格中插入浮动图片、调整图片位置和大小、查看已有浮动图片、删除图片时使用。也适用于"插入图片"、"添加 logo"、"放一张图"等场景。注意：如果用户需要将图片嵌入到某个单元格内部（单元格图片），请阅读 lark-sheets-write-cells。 |
+## 公共 flag 速查
+各 reference 的每个 shortcut 标题下用一行徽章标注该 shortcut 支持的公共 / 系统 flag，例如：
+- `_公共四件套 · 系统：--dry-run_` — URL/token + sheet 定位（两组各**必给一个**，详见下方「公共 flag」），加 `--dry-run`
+- `_公共：URL/token（无 sheet 定位） · 系统：--yes、--dry-run_` — 只接 URL/token，常见于 `+batch-update` 等不强制 sheet 定位的 shortcut
+徽章里只列名字。type / 必填 / 描述都在本段统一声明：
+### 公共 flag（定位资源）
+**公共四件套** = `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`，分成两组 XOR，**每组都必须给且只能给一个**（XOR = 二选一必填，不是"可选"）：
+1. **spreadsheet 定位（必填）**：`--url` 与 `--spreadsheet-token` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --url or --spreadsheet-token`；两个都给 → 互斥冲突。
+   - **`--url` 解析 `/sheets/`、`/spreadsheets/` 与 `/wiki/` 三种链接**（从路径里抽出 token；也可以直接把裸 token 传给 `--spreadsheet-token`）。其它形态的链接不会被解析成表格 token。
+   - **`/wiki/` 知识库链接可直接传 `--url`**：会自动定位到链接背后的电子表格；若该链接背后不是电子表格（而是文档 / 多维表格等），则报错。
+   - **例外**：`+workbook-create`（新建表 + 可选写入数据）与 `+workbook-import`（把本地文件导入为新表）都产出一张**还不存在**的表格，**不接受任何 spreadsheet / sheet 定位 flag**——`+workbook-create` 只有 `--title` / `--folder-token` / `--values` / `--styles` / `--sheets`，`+workbook-import` 只有 `--file`（必填）/ `--folder-token` / `--name`。
+2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。
+   - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`，比先查多耗一次失败调用 + 重试。
+   - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range 'Sheet1!A1:B2'`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。
+   - ⚠️ **A1 reference 含 `!`**（`--source` / `--range` / `--ranges`）**：整段用单引号包裹**，如 `--range 'Sheet1!A1:B2'`——单引号能挡住 bash 的 history expansion（`!` 被拦成 `event not found`；双引号挡不住；别改用 `set +H`，原因见下方「复合 JSON / 大入参」）。sheet 名含特殊字符（`-` / 空格 / 非 ASCII）需在内部按 A1 标准再包一层单引号时，用 `'\''` 转义保持外层单引号，如 `--source ''\''Sales-2025'\''!A1:D100'`。
+   - **例外**：徽章标为 `_公共：URL/token（无 sheet 定位）…_` 的 shortcut（如 `+workbook-info` / `+workbook-export` / `+batch-update` / `+dropdown-update|delete` / `+cells-batch-set-style` / `+cells-batch-clear` / `+sheet-create`）**不接受也不需要** sheet 定位，只给一组 spreadsheet 定位即可。`+pivot-create` 用 `--target-sheet-id` / `--target-sheet-name`（XOR，可都不传，落点细节见 `lark-sheets-pivot-table`）。
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--url` | string | 二选一必填（与 `--spreadsheet-token`） | spreadsheet 或 wiki URL |
+| `--spreadsheet-token` | string | 二选一必填（与 `--url`） | spreadsheet token |
+| `--sheet-id` | string | 二选一必填（与 `--sheet-name`；仅公共四件套 shortcut） | 工作表 reference_id |
+| `--sheet-name` | string | 二选一必填（与 `--sheet-id`；仅公共四件套 shortcut） | 工作表名称 |
+**统一调用范式**（公共四件套 shortcut 的所有示例都遵循此形状，两组定位缺一不可）：
+```bash
+lark-cli sheets <shortcut> <workbook 定位> <sheet 定位> <其它 flag>
+#   workbook 定位：--url "..."        或 --spreadsheet-token "..."           （二选一，必给）
+#   sheet 定位：    --sheet-id "$SID"  或 --sheet-name "<真实表名>"            （二选一，必给；占位符不要原样填）
+# 例：lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实表名>" --range "A1:F30"
+# 注意：真实表名不要直接填 "Sheet1"——大多数表的子表不叫这个；先 +workbook-info 拿 sheets[].title 再代入。
+```
+### 系统 flag
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--dry-run` | bool | 否 | 零副作用：仅打印请求路径与参数模板，不发起调用；多步操作会输出每个子操作的请求模板 |
+| `--yes` | bool | 是（仅 `high-risk-write`） | 二次确认；不带时退出码 10。详见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 高风险审批协议 |
+| `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name <name>` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。**仅在 shortcut 含复合 JSON flag 时有效**——判断方法：该 shortcut 的 Flags 表里出现类型标注为「复合 JSON」的 flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options`）即支持；纯标量 flag 的 shortcut 不支持。 |
+| `--flag-name` | string | 否 | 配合 `--print-schema` 使用，指定要打印 JSON Schema 的 flag 名（不带 `--` 前缀，如 `cells` / `properties` / `operations`）。 |
+**Agent 使用提示**：写复合 JSON flag（`--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options` 等）时，如果对结构不确定，先跑 `lark-cli sheets <shortcut> --print-schema --flag-name <name>` 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 `## Schemas` 段只给一层结构，深层只能靠 `--print-schema` 或 `## Examples` 的真实示例。
+### flag 内容类型与输出约定（术语速记）
+- flag 表里 JSON 类入参标三类：**复合 JSON** = 深层嵌套对象（用 `--print-schema` 取完整结构）；**简单 JSON** = 一维 / 二维标量数组（如 `["sheet1!A1:B2",...]` / `[["alice",95]]`，结构简单无需 print-schema）；**非 JSON 文本** = 原样文本（如 CSV）。`--print-schema` 只对**复合 JSON** flag 有效（同一 shortcut 的简单 JSON flag 如 `--colors` 不在此列）。
+- **envelope**：所有 shortcut 返回统一外层结构 `{ok, identity, data, ...}`。正文里 `envelope.data` 指业务数据层（如 `+csv-get` 的 `annotated_csv`）；写操作不会自动回读，如需校验请自行调用对应的 `+*-list` / `+*-get` / `+cells-get`。
+## 复合 JSON / 大入参：优先 stdin
+flag 帮助里标注支持 **Stdin** 的入参，当 payload 较大、含换行 / 引号等特殊字符，或已经落在某个文件里时，优先用 stdin（`-`）传入，避免命令行超长与 shell 转义问题。
+推荐写法：payload 写到用户项目目录之外的临时文件（放系统临时目录，避免污染项目），再用 stdin 喂进去：
+```bash
+# TMPFILE 指向系统临时目录下的 payload 文件（脚本里用 tempfile.gettempdir() / os.tmpdir() 等取临时目录）
+lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --cells - < "$TMPFILE"
+```
+**参数含特殊字符（`!` / 引号 / 空格 / 非 ASCII）时，用单引号包裹该参数即可，不要起手 `set +H` 之类的 shell 开关来防转义。** `set +H`（关 bash history expansion）在 `sh` / `dash` 下是非法选项（`set: Illegal option -H`）、会让整条命令直接失败；而单引号挡得住 `!` 的 history expansion（否则报 `event not found`），对 bash 与 `sh` / `dash` 一致安全。参数本身含单引号、或 payload 较大时，按上文走 stdin。
+**`@file` 接绝对路径会被拒，且被拒后不要照报错提示做。** `@file` 出于安全只接受 cwd 下的相对路径，传 cwd 之外的绝对路径会被拒。此时报错会建议"先 cd 到目标目录，或改用相对路径"——**两条都不要照做**：cd 过去、或把临时文件写进用户项目目录，都会污染工作目录。正解是改用 stdin（`--<flag> - < 文件`）。