ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# Lark Sheet Search & Replace
|
||
|
||
## 替换前 dry-run + 范围明确（替换前必做）
|
||
|
||
`+cells-replace` 的副作用是不可逆的（除非另写代码回滚）。执行前必须：
|
||
|
||
1. **明确替换范围**：必须显式说明"只替换 X 列 / X 区域，还是全表替换"。**禁止**默认全表替换——容易误改无关列。范围应由用户指令决定，模糊时主动询问。
|
||
2. **dry-run 命中数量**：先用 `+cells-search` 在同一范围、同一关键词、同一匹配选项（大小写 / 精确 / 正则）下统计命中数量。把数量和**期望命中数**（用户明示的或基于业务理解推断的）对照——一致才进入 `+cells-replace`，不一致先排查（关键词太宽？范围太大？）。
|
||
3. **替换后回读校验**：执行后再次 `+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`
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 普通查找
|
||
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_id`
|
||
- `total_matches` — 匹配总数
|
||
- `has_more` / `next_offset` — 分页游标（命中数超过单页上限时用于继续读取）
|
||
|
||
### `+cells-replace`
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 先 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` 复查旧值是否已不再命中。
|