# 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 dws sheet comment list --node --sheet-id Sheet1 --range A2 dws sheet comment list --node --resolve-status unresolved dws sheet comment list --node --cursor 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 Sheet1 --range A2 --content "这个数字有问题" dws sheet comment create --node --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 --format json` 确认真实名称，禁止臆测 `Sheet1` / `0` / `default`。 --- ## sheet comment reply（回复评论） ``` Usage: dws sheet comment reply [flags] Example: dws sheet comment reply --node --comment-key --content "已核实" dws sheet comment reply --node --comment-key --content "比心" --emoji dws sheet comment reply --node --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 --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 --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 --format json # 仅看某个单元格的评论 dws sheet comment list --node --sheet-id Sheet1 --range A2 --format json # 仅看未解决的评论 dws sheet comment list --node --resolve-status unresolved --format json # 在单元格上创建评论（未知工作表名先 sheet list 确认） dws sheet list --node --format json dws sheet comment create --node --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 Sheet1 --range A2 --content "请确认" --mention , --format json # 文字回复 dws sheet comment reply --node --comment-key --content "已核实" --format json # 表情回复（--content 填表情名称） dws sheet comment reply --node --comment-key --content "比心" --emoji --format json # 更新评论 dws sheet comment update --node --comment-key --content "已按最新数据修正" --format json # 删除评论（不可逆；必须用户确认后再加 --yes） dws sheet comment delete --node --comment-key --yes --format json ``` ## 参考 - [`../sheet.md`](../sheet.md)（如何路由到本命令族） - [`./sheet-workbook.md`](sheet-workbook.md)（取工作表名称） - `dws aisearch person`（取 mention 用的 userId，跨产品命令）