# 搜索与替换

## 使用场景

用户说"搜索/查找/找单元格/搜内容/精确搜索/精确匹配/完全匹配/全字匹配":
- 搜索单元格 → `find`
- 精确匹配（只匹配完全等于的，不匹配包含的） → `find --match-entire-cell`
- 正则搜索 → `find --use-regexp`
- 搜索公式 → `find --match-formula`
- 不要用 `range read` 读取全量数据后在客户端过滤来替代 `find`，必须使用 `find` 命令的服务端搜索能力

用户说"替换/查找替换/全局替换/批量替换/把A替换成B/把所有的X改成Y":
- 查找替换 → `replace`
- 精确匹配后替换（只替换内容完全等于的单元格） → `replace --match-entire-cell`
- 正则替换 → `replace --use-regexp`
- 替换公式文本（改公式源码而非显示值） → `replace --match-formula`
- 删除匹配内容 → `replace --replacement ""`
- 请勿用 `find` + `range update`、`range read` + `range update` 等组合来模拟替换，`replace` 是服务端原子操作，效率更高且返回替换计数

## 命令详细参考

### 在工作表中搜索单元格内容
```
Usage:
  dws sheet find [flags]
Example:
  # 基本搜索
  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "销售额"

  # 在指定范围内搜索
  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "合计" --range "A1:D100"

  # 正则表达式搜索（不区分大小写）
  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "^total" --use-regexp --match-case=false

  # 精确匹配整个单元格内容
  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "完成" --match-entire-cell

  # 搜索公式文本
  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "SUM" --match-formula
Flags:
      --node string         表格文档 ID 或 URL (必填)
      --sheet-id string     工作表 ID 或名称 (必填)
      --find string         搜索文本 (必填)
      --range string        搜索范围，A1 表示法 (如 A1:D10)
      --match-case          区分大小写 (默认 true)
      --match-entire-cell   精确匹配整个单元格内容
      --use-regexp          启用正则表达式搜索
      --match-formula       搜索公式文本而非显示值
      --include-hidden      包含隐藏单元格
```

### 全局查找替换
```
Usage:
  dws sheet replace [flags]
Example:
  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "旧文本" --replacement "新文本"
  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "待处理" --replacement "已完成" --match-entire-cell
  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "\\d{4}" --replacement "****" --use-regexp
  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "旧" --replacement "新" --range "A1:D100"
  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "临时" --replacement ""
Flags:
      --node string            表格文档 ID 或 URL (必填)
      --sheet-id string        工作表 ID 或名称 (必填)
      --find string            查找文本 (必填)
      --replacement string     替换文本 (必填，可为空字符串表示删除)
      --range string           替换范围，A1 表示法 (如 A1:D100)
      --match-case             区分大小写 (默认 false)
      --match-entire-cell      完整单元格匹配
      --use-regexp             启用正则表达式匹配
      --match-formula          在公式文本中查找替换（默认 false，替换公式源码而非显示值）
      --include-hidden         包含隐藏行/列
```

返回被替换的单元格数量。`--replacement` 可以为空字符串，表示删除匹配内容。

## 核心工作流

```bash
# ── 工作流: 搜索表格数据 ──

# 1. 获取工作表列表
dws sheet list --node <NODE_ID> --format json

# 2. 基本搜索 — 在指定工作表中查找文本
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "销售额" --format json

# 3. 在指定范围内搜索
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "合计" --range "A1:D100" --format json

# 4. 正则搜索（不区分大小写）
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "^total" --use-regexp --match-case=false --format json

# 5. 精确匹配整个单元格
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "完成" --match-entire-cell --format json

# 6. 搜索公式文本
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "SUM" --match-formula --format json
```

## 上下文传递

| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `list` | 工作表的 `sheetId` | find / replace 的 --sheet-id |
| `find` | `matchedCells` 中的 `a1Notation` | 定位目标单元格，用于 range read / range update |
| `replace` | `replaceCount` 被替换的单元格数量 | 确认替换结果 |

## 注意事项

- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败
- ★ **搜索用 `find` 不用 `range read`**：`find` 是服务端搜索，禁止用 `range read` 全量读取后客户端过滤
- ★ **替换用 `replace` 不用 `range update`**：`replace` 是服务端原子操作，返回替换计数
- `find` 返回匹配单元格的地址（A1 表示法）和值，无匹配时返回空数组
- `find` 的 `--match-entire-cell` 用于精确匹配：只返回单元格内容完全等于搜索文本的结果，不会匹配包含该文本的单元格（例如搜索"苹果"时，只匹配"苹果"，不匹配"苹果手机""苹果汁"等）。用户说"精确搜索/完全匹配/只搜等于XX的"时必须使用此参数
- `find` 的 `--match-case` 默认为 true（区分大小写），设为 false 可忽略大小写
- `find` 的 `--use-regexp` 启用后，`--find` 参数作为正则表达式处理
- `replace` 的 `--find` 不能为空字符串，`--replace` 可以为空字符串（表示删除匹配内容）
- `replace` 的 `--match-case` 默认为 false（不区分大小写），与 `find` 的默认行为不同
