167 lines
7.9 KiB
Markdown
167 lines
7.9 KiB
Markdown
# sheet comment（表格单元格评论：list / create / reply / update / delete）
|
||
|
||
> **前置条件（MUST READ）：** 执行本命令前，必须先用 Read 工具读取以下文件：
|
||
> 1. [`../sheet.md`](../sheet.md) — 命令路由 + 场景索引 + 意图判断 + 全局约束
|
||
>
|
||
> **同任务常配合**：`dws aisearch person`（查 `--mention` 用 userId）/ [`sheet-workbook.md`](sheet-workbook.md)（未知工作表名称时先 `list` 确认真实名称）
|
||
|
||
---
|
||
|
||
## 适用范围
|
||
|
||
- 仅支持钉钉在线电子表格（`extension=axls`）。`xlsx` / `xls` / `csv` 等本地表格不支持评论。
|
||
- 评论锚定在**单元格位置**：`create` / `list` 通过 `--sheet-id`（工作表 ID 或名称）+ `--range`（单元格坐标）定位；`reply` / `update` / `delete` 通过 `--comment-key` 操作，不依赖单元格位置。
|
||
- `create` / `list` 通过单元格位置定位；`reply` / `update` / `delete` 通过前一步返回的 `commentKey` 定位评论线程，不需要重新传单元格位置。
|
||
- Agent 只使用命令返回的 `commentKey` 继续回复、更新或删除，不自行构造评论标识。
|
||
|
||
---
|
||
|
||
## sheet comment list（查询表格评论列表）
|
||
|
||
```
|
||
Usage:
|
||
dws sheet comment list [flags]
|
||
Example:
|
||
dws sheet comment list --node <SHEET_ID>
|
||
dws sheet comment list --node <SHEET_ID> --sheet-id Sheet1 --range A2
|
||
dws sheet comment list --node <SHEET_ID> --resolve-status unresolved
|
||
dws sheet comment list --node <SHEET_ID> --cursor <TOKEN>
|
||
Flags:
|
||
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
|
||
--limit int 每页返回的评论数量，默认 50，最大 50
|
||
--cursor string 分页游标，从上一次请求的返回结果中获取 (首次请求不传)
|
||
--resolve-status string 按解决状态过滤: resolved (已解决) / unresolved (未解决)
|
||
--sheet-id string 工作表 ID 或名称，如 Sheet1（与 --range 一起指定时按单元格过滤）
|
||
--range string 单元格位置，A1 表示法，如 A2、B5:C10（与 --sheet-id 一起指定时按单元格过滤）
|
||
```
|
||
|
||
- 同时传入 `--sheet-id` 和 `--range` 时，仅返回该单元格的评论（服务端按单元格精确过滤）；不传则返回表格全部单元格评论。
|
||
|
||
---
|
||
|
||
## sheet comment create（创建单元格评论）
|
||
|
||
```
|
||
Usage:
|
||
dws sheet comment create [flags]
|
||
Example:
|
||
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "这个数字有问题"
|
||
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "请核实" --mention uid1,uid2
|
||
Flags:
|
||
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
|
||
--sheet-id string 工作表 ID 或名称，如 Sheet1 (必填)
|
||
--range string 单元格位置，A1 表示法，仅支持单个单元格，如 A2 (必填)
|
||
--content string 评论的文字内容，纯文本 (必填)
|
||
--mention string 被 @ 的用户 uid 列表，逗号分隔
|
||
```
|
||
|
||
- 未知工作表名称时，先 `dws sheet list --node <SHEET_ID> --format json` 确认真实名称，禁止臆测 `Sheet1` / `0` / `default`。
|
||
|
||
---
|
||
|
||
## sheet comment reply（回复评论）
|
||
|
||
```
|
||
Usage:
|
||
dws sheet comment reply [flags]
|
||
Example:
|
||
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已核实"
|
||
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "比心" --emoji
|
||
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "请确认" --mention uid1,uid2
|
||
Flags:
|
||
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
|
||
--content string 回复的文字内容，表情回复时填写表情名称 (必填)
|
||
--comment-key string 被回复评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
|
||
--emoji 设为 true 时作为表情贴图回复 (默认 false)
|
||
--mention string 被 @ 的用户 uid 列表，逗号分隔
|
||
```
|
||
|
||
- 回复自动归属到被回复评论所在的单元格线程，无需再传 `--sheet-id` / `--range`。
|
||
|
||
---
|
||
|
||
## sheet comment update（更新评论）
|
||
|
||
```
|
||
Usage:
|
||
dws sheet comment update [flags]
|
||
Example:
|
||
dws sheet comment update --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已按最新数据修正"
|
||
Flags:
|
||
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
|
||
--comment-key string 待更新评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
|
||
--content string 更新后的评论文字内容，纯文本 (必填)
|
||
```
|
||
|
||
---
|
||
|
||
## sheet comment delete（删除评论）
|
||
|
||
> [强制] 危险操作：删除不可恢复。必须先向用户展示操作摘要并获得明确同意，用户同意后才加 `--yes` 执行。
|
||
|
||
```
|
||
Usage:
|
||
dws sheet comment delete [flags]
|
||
Example:
|
||
dws sheet comment delete --node <SHEET_ID> --comment-key <COMMENT_KEY> --yes
|
||
Flags:
|
||
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
|
||
--comment-key string 待删除评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
|
||
```
|
||
|
||
## 关键说明
|
||
|
||
- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --query "<姓名>" --dimension name` 拿到 userId。
|
||
- `--comment-key` 是 13 位毫秒时间戳 + 32 位 UUID 的拼接字符串，从 `list` / `create` 返回中提取，用于 `reply` / `update` / `delete`。
|
||
- `create` / `list`（按单元格过滤）的 `--sheet-id` 是工作表 ID 或名称；未知时先 `dws sheet list` 确认，禁止臆测。
|
||
- `reply` 加 `--emoji` 时 `--content` 填表情名称（如 `比心`、`赞`），不是文字内容。
|
||
- `delete` 是不可逆操作；AI Agent 必须先向用户展示操作摘要并获得明确同意，同意后才追加 `--yes`。
|
||
|
||
## 上下文传递
|
||
|
||
| 从返回中提取 | 用于 |
|
||
|-------------|------|
|
||
| `commentList[].commentKey` | `comment reply/update/delete` 的 `--comment-key` |
|
||
| `comment create` 的 `commentKey` | `comment reply/update/delete` 的 `--comment-key` |
|
||
| [`sheet-workbook.md`](sheet-workbook.md) `sheet list` 的工作表名称 | `comment create/list` 的 `--sheet-id` |
|
||
| `dws aisearch person` 的 `userId` | `comment create/reply` 的 `--mention` |
|
||
|
||
## 常用模板
|
||
|
||
```bash
|
||
# 查看表格全部单元格评论
|
||
dws sheet comment list --node <SHEET_ID> --format json
|
||
|
||
# 仅看某个单元格的评论
|
||
dws sheet comment list --node <SHEET_ID> --sheet-id Sheet1 --range A2 --format json
|
||
|
||
# 仅看未解决的评论
|
||
dws sheet comment list --node <SHEET_ID> --resolve-status unresolved --format json
|
||
|
||
# 在单元格上创建评论（未知工作表名先 sheet list 确认）
|
||
dws sheet list --node <SHEET_ID> --format json
|
||
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "这个数字有问题" --format json
|
||
|
||
# 创建评论 + @人（先 aisearch person 拿 userId）
|
||
dws aisearch person --query "张三" --dimension name --format json
|
||
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "请确认" --mention <uid1>,<uid2> --format json
|
||
|
||
# 文字回复
|
||
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已核实" --format json
|
||
|
||
# 表情回复（--content 填表情名称）
|
||
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "比心" --emoji --format json
|
||
|
||
# 更新评论
|
||
dws sheet comment update --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已按最新数据修正" --format json
|
||
|
||
# 删除评论（不可逆；必须用户确认后再加 --yes）
|
||
dws sheet comment delete --node <SHEET_ID> --comment-key <COMMENT_KEY> --yes --format json
|
||
```
|
||
|
||
## 参考
|
||
|
||
- [`../sheet.md`](../sheet.md)（如何路由到本命令族）
|
||
- [`./sheet-workbook.md`](sheet-workbook.md)（取工作表名称）
|
||
- `dws aisearch person`（取 mention 用的 userId，跨产品命令）
|