5.3 KiB
5.3 KiB
Lark Sheet Search & Replace
替换前 dry-run + 范围明确（替换前必做）
+cells-replace 的副作用是不可逆的（除非另写代码回滚）。执行前必须：
- 明确替换范围：必须显式说明"只替换 X 列 / X 区域，还是全表替换"。禁止默认全表替换——容易误改无关列。范围应由用户指令决定，模糊时主动询问。
- dry-run 命中数量：先用
+cells-search在同一范围、同一关键词、同一匹配选项（大小写 / 精确 / 正则）下统计命中数量。把数量和期望命中数（用户明示的或基于业务理解推断的）对照——一致才进入+cells-replace，不一致先排查（关键词太宽？范围太大？）。 - 替换后回读校验：执行后再次
+cells-search旧关键词，预期为 0；并对替换后的若干代表性单元格回读确认值符合预期。
使用场景
读写。在飞书表格中搜索和替换文本。本 reference 覆盖 2 个 shortcut：
| 操作需求 | 使用工具 | 说明 |
|---|---|---|
| 搜索/定位文本 | +cells-search |
返回匹配的单元格位置，支持正则、精确匹配等 |
| 查找并替换文本 | +cells-replace |
批量替换文本；--regex 模式下 --replacement 可用 $1、$2 引用 --find 的捕获组 |
常见配置错误（必须注意）：
- 不要把操作动词当搜索词：用户说"汇总金额"是一个操作动作（求和），不是要搜索"汇总金额"这个文本。只有当确实需要定位某个文本值的位置时才用
+cells-search - 不要用搜索来了解表格结构：要了解表头和数据结构时，应使用
+csv-get读取前几行，而不是用+cells-search逐个猜测字段名 - 注意正则特殊字符：使用正则匹配时，
.、*、(、)等特殊字符需要转义
Shortcuts
| Shortcut | Risk | 分组 |
|---|---|---|
+cells-search |
read | 单元格 |
+cells-replace |
write | 单元格 |
Flags
+cells-search
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--find |
string | required | 待查找文本（与 --regex 配合时按正则解释） |
--range |
string | optional | 查找范围（A1 格式）；省略时整表 |
--match-case |
bool | optional | 大小写敏感 |
--match-entire-cell |
bool | optional | 完全匹配整个单元格 |
--regex |
bool | optional | 把 --find 按正则解释 |
--include-formulas |
bool | optional | 也在公式文本中搜索 |
--max-matches |
int | optional | 防爆，默认 5000（隐藏 flag：不在 --help 列出，但可正常传入） |
--offset |
int | optional | 跳过前 N 个匹配（分页用），默认 0 |
+cells-replace
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--find |
string | required | 待替换文本 |
--replacement |
string | required | 替换为；传空字符串 "" 等价于「删除内容」 |
--range |
string | optional | 替换范围（A1 格式）；省略时整表 |
--match-case |
bool | optional | 大小写敏感 |
--match-entire-cell |
bool | optional | 完全匹配整个单元格 |
--regex |
bool | optional | 把 --find 按正则解释 |
--include-formulas |
bool | optional | 也在公式文本中替换 |
Examples
公共四件套：所有 shortcut 顶部排列 --url / --spreadsheet-token / --sheet-id / --sheet-name（XOR 规则）。
+cells-search
示例：
# 普通查找
lark-cli sheets +cells-search --url "https://example.feishu.cn/sheets/shtXXX" \
--sheet-name "Sheet1" --find "张三"
# 正则 + 范围限定
lark-cli sheets +cells-search --spreadsheet-token shtXXX --sheet-id "$SID" \
--find "^[A-Z]{2}-\\d{4}$" --regex --range "A2:A1000"
输出契约（envelope.data）：
matches— 命中 cell 列表，每条含address（A1）+value+sheet_idtotal_matches— 匹配总数has_more/next_offset— 分页游标（命中数超过单页上限时用于继续读取）
+cells-replace
示例：
# 先 dry-run 预览
lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
--sheet-name "Sheet1" --find "v1" --replacement "v2" --dry-run
# 确认后执行
lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
--sheet-name "Sheet1" --find "v1" --replacement "v2"
# 正则捕获组：把 "2026-03" 重排成 "03/2026"（$1/$2 引用 --find 的捕获组）
lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
--sheet-name "Sheet1" --regex --find "(\\d{4})-(\\d{2})" --replacement "$2/$1" --dry-run
+cells-replace虽然 Risk = write，但范围大或正则错可能改一堆。强烈推荐工作流：先+cells-search看匹配数，再+cells-replace --dry-run预览，最后真正执行。
Validate / DryRun / Execute 约束
Validate：XOR 公共四件套；--find非空；正则模式下--find必须是合法正则。DryRun：+cells-search输出请求模板；+cells-replace额外返回预估替换数（would_replace_count）。Execute：写后不自动回读；如需确认，自行用+cells-search复查旧值是否已不再命中。