mirror of
https://github.com/larksuite/cli.git
synced 2026-07-05 07:31:22 +08:00
Compare commits
1 Commits
feat-histo
...
feat/lark-
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0e691781eb |
@@ -28,6 +28,7 @@ metadata:
|
||||
- 用户要比较原生 `.md` 文件的**历史版本差异**,或比较远端 Markdown 与本地草稿,切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`;需要版本号时先用 `drive +version-history`。
|
||||
- 用户要查看、下载、回滚或删除文件的**历史版本**,使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`;这组命令同时支持 `--as user` 和 `--as bot`,自动化场景优先 `--as bot`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格,使用 `lark-cli drive +import --type sheet`。
|
||||
- **`+import` 只接受 cwd 下的本地相对路径**:没有 `--url` flag、也不接受绝对路径。源文件在远端(http(s) / TOS)时,**先 `cd` 到工作区 `wget`/`curl` 下载,再用相对路径 `--file` 导入**,例:`cd <工作区> && wget -O data.xlsx "<链接>" && lark-cli drive +import --file data.xlsx --type sheet`(细节与反例见 [`+import`](references/lark-drive-import.md))。
|
||||
- 用户要在云空间(云盘/云存储)里新建文件夹,优先使用 `lark-cli drive +create-folder`。
|
||||
- 用户要查看某个文件有哪些可下载预览格式,或想下载 PDF / HTML / 文本 / 图片等预览产物,使用 `lark-cli drive +preview`。
|
||||
- 用户要获取某个文件的封面图,优先使用 `lark-cli drive +cover`;先 `--list-only` 看规格,再选 `--spec` 下载。
|
||||
|
||||
@@ -57,12 +57,27 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file` | 是 | 本地文件路径,根据文件后缀名自动推断 `file_extension`;文件需满足对应格式的导入大小限制,超过 20MB 且仍在允许范围内时会自动切换分片上传 |
|
||||
| `--file` | 是 | **本地文件路径,且只接受 cwd 下的相对路径**(出于安全,绝对路径会被拒);根据文件后缀名自动推断 `file_extension`;文件需满足对应格式的导入大小限制,超过 20MB 且仍在允许范围内时会自动切换分片上传 |
|
||||
| `--type` | 是 | 导入目标云文档格式。可选值:`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格)、`slides` (飞书幻灯片) |
|
||||
| `--folder-token` | 否 | 目标文件夹 token,不传则请求中的 `point.mount_key` 为空字符串,Import API 会将其解释为导入到云空间(云盘/云存储)根目录 |
|
||||
| `--name` | 否 | 导入后的在线云文档名称,不传默认使用本地文件名去掉扩展名后的结果 |
|
||||
| `--target-token` | 否 | 已有的多维表格 token,将数据导入到该多维表格中(**仅支持 `--type bitable`**);传入后数据会挂载到目标多维表格而非新建一个 |
|
||||
|
||||
> [!CAUTION]
|
||||
> **`drive +import` 高频误用(会被 cobra / 安全校验直接拒,别试):**
|
||||
>
|
||||
> - ❌ **不存在 `--url` flag**:`drive +import` **只能导入本地文件**,不能直接传网络 / TOS 链接。
|
||||
> - 报错形如:`unknown flag "--url" for "lark-cli drive +import"`。
|
||||
> - ✅ 正解:源文件在远端(http(s) / TOS)时,**先下载到工作区再导入**:
|
||||
> ```bash
|
||||
> cd <你的工作区目录>
|
||||
> wget -O data.xlsx "https://tosv.byted.org/.../Data001.xlsx" # 或 curl -o
|
||||
> lark-cli drive +import --file data.xlsx --type sheet
|
||||
> ```
|
||||
> - ❌ **`--file` 不接受绝对路径**:传 `--file /home/user/.../Data001.xlsx` 会报 `unsafe file path: --file must be a relative path within the current directory`。
|
||||
> - ✅ 正解:先 `cd` 到文件所在工作区目录,再用**相对路径**(如 `--file Data001.xlsx`)。
|
||||
> - ❌ 报错提示里若建议你"改用绝对路径 / 移动文件"之类,**不要照做绕过**——只用 cwd 内相对路径。
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **完整执行流程**:此 shortcut 内部封装了完整流程:
|
||||
|
||||
@@ -24,6 +24,11 @@
|
||||
7. **分组汇总必须用透视表**:"按 X 统计 Y / 分组汇总 / 各部门数量金额"必须用 `+pivot-{create|update|delete}`(推荐省略 sheet_id 自动新建子表),**禁止**用 SUMIF / COUNTIF 或本地脚本覆盖原表替代。
|
||||
8. **任务拆成可验证 checklist**:落地前把指令拆成所有"独立可验证子要点",每点一个 `assert`,全部通过才交付:多维度操作(按部门一/二/三级排序)每维一个 assert;多目标(删 N 行)每目标一个;多格式兼容(多种日期格式)每种至少一个样本;范围类(A1:H11 加边框)起 / 末行 / 末列三边界都核。只完成第一个要点(只排一级、只删 1 行)属违规。**题面 / 表头里写明的格式规范也是子要点**:表头注明"需标注某字段"就必须给对应单元格加规定前缀并逐条 assert 前缀存在(反例:漏加规定前缀,该要点即不达标);"相同编号连续行合并"必须遍历所有相同编号组全部合并(反例:只合并了其中一部分组)。
|
||||
9. **全量处理要前置断言条数**:翻译 / 打标 / 批量公式落地等逐条任务,落地前把"预期处理条数"硬编码进代码,处理完 `assert actual == expected`。**严禁**输出"已完成前 N 条,剩余将继续"的半成品。
|
||||
10. **数值与日期交付前必做正确性自检**(高频致命失分,子 skill 不得放宽):写回后,对"用户会逐个核对的计算列 / 汇总值"逐项自检,**不通过不得交付**。三类最易翻车、必查:
|
||||
- **单位 / 量级**:源数据单位(元 / 万元 / 亿)与目标输出单位不一致时,换算因子(÷10000 / ÷1e8)必须显式落实并核对量级——把首行结果与源值手算比一遍数量级,例如"总额 235.97 万"绝不能落成 "2359731.87 万"(漏除 10000)。求和 / 占比 / 同比的中间值也要带正确单位。
|
||||
- **日期月日不颠倒**:序列号 / 字符串解析日期后,抽 3-5 个样本核对**月、日没有互换**(`2024-08-09` 不能写成 `2024-09-08`),跨格式列(`YYYYMM`/`M/D/Y`/带时间戳)逐种格式各核一个样本。
|
||||
- **公式结果 sanity**:写完公式读结果列**首 5 + 末 5 行**,检查有无不合理值——负的时长 / 年龄、超界百分比(>100% 或 <0)、量级离谱的金额、`#VALUE!`/`#REF!`/`#DIV/0!`;跨天时间差、身份证算年龄等易错逻辑必须用真实样本验算一遍再全量落地。
|
||||
11. **交付前核对"未改动区"**(最小改动的强校验,配合铁律 1):凡是"在原表/原文件上追加 / 补列 / 修正"类任务,交付前必须显式确认原有内容 1:1 保留:① 原有 Sheet 清单(数量 / 名称)一个不少、未被删 / 改名 / 覆盖;② 用户明示要改的列之外,原有列的值未被改写;③ 对关键原始区域回读做 diff 比对(读改动前快照或重新读原列样本),确认非目标区零异常 diff。**严禁**新建一张表只填自己生成的内容、却丢掉或覆盖原表的其它 Sheet / 列。
|
||||
|
||||
## 推荐工作流程
|
||||
|
||||
@@ -58,7 +63,11 @@
|
||||
|
||||
6. **写入与修改(细节见 `lark-sheets-write-cells`)**:`+cells-set` 的 `range` 必须落在已有行列范围内、`cells` 二维数组与 `range` 严格同维;表尾追加先用 `+dim-insert` 插行列再写;整列 / 整行同结构的值 / 公式 / 格式用模板单元格 + `--copy-to-range`,禁止逐行 `+cells-set`;多步写入合并为 `+batch-update`;改尺寸先读相邻可见行列当前尺寸再决定 `pixel` / `standard` / `auto`,不要猜数值。
|
||||
|
||||
7. **验证**:重新读取受影响区域确认值 / 公式 / 样式 / 批注符合预期;对象类(图表 / 透视表 / 条件格式 / 筛选 / 迷你图 / 浮动图片)重新读对象配置确认;出错先定位错误类型 / 受影响区域 / 根因再修复重验。
|
||||
7. **验证**:重新读取受影响区域确认值 / 公式 / 样式 / 批注符合预期;对象类(图表 / 透视表 / 条件格式 / 筛选 / 迷你图 / 浮动图片)重新读对象配置确认;出错先定位错误类型 / 受影响区域 / 根因再修复重验。验证必须落到以下可执行清单(对应铁律 8-11):
|
||||
- **逐要点 checklist**:把用户指令拆成的每个独立子要点(每种应扣项 / 每个统计量 / 每段说明文字 / 底部备注等)逐条确认已真实落地,缺一即不算完成——常见漏项:要求"拆分五险一金为 6 项"只写了 1 项、要求"含底部备注/趋势分析文字"却没写、要求"每个 sheet 含最大/最小/平均"漏了某个统计量。
|
||||
- **数值/日期自检**(铁律 10):单位量级、月日不颠倒、公式结果 sanity 三项各抽样核对。
|
||||
- **未改动区 diff**(铁律 11):原 Sheet 清单与原列内容 1:1 保留,非目标区零异常 diff。
|
||||
- **对象非空**:透视表 / 图表创建后必须回读确认**有实际行列内容**,不能只建了空壳子表(空透视表 = 未完成)。
|
||||
|
||||
## 用本地代码 / 脚本时的 CLI 配合要点
|
||||
|
||||
|
||||
@@ -120,6 +120,12 @@ _公共四件套 · 系统:`--dry-run`_
|
||||
| `--include-row-prefix` | bool | optional | 是否在每行前加 `[row=N]` 前缀,默认 `true` |
|
||||
| `--skip-hidden` | bool | optional | 跳过隐藏行列,默认 `false` |
|
||||
|
||||
> [!CAUTION]
|
||||
> **`+csv-get` 高频臆造 flag(不存在,传了会被 cobra 拒,报 `unknown flag`):**
|
||||
> - ❌ `--rows-json` / `--json-rows` / `--as-json` / `--format json-rows` —— `+csv-get` **只输出带 `[row=N]` 前缀的 CSV 文本**,没有"按行 JSON / 结构化"开关。
|
||||
> - ✅ **要结构化 / 类型化输出(喂 DataFrame、按列类型读出、round-trip 回写)请改用 `+table-get`**(见下),它返回 `columns:[{name,type}]` + `rows` 的 typed 协议。
|
||||
> - ✅ 只要纯值就用 `+csv-get`;下游要行号 / 列坐标直接从 `[row=N]` 前缀与 `col_indices` 取,不需要额外 flag。
|
||||
|
||||
### `+table-get`
|
||||
|
||||
_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_
|
||||
|
||||
Reference in New Issue
Block a user