first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,29 @@
+# 文档评论 Golden Route
+
+## Review 聚合
+
+```bash
+dws doc +review --node <DOC_ID_OR_URL> --format json
+```
+
+需要一次看到未解决评论、引用原文和 block 上下文时优先使用 `+review`。从真实返回取得 `commentKey` 和 `blockId`，禁止按数组位置或猜测 ID。
+
+## 精确评论动作
+
+```bash
+dws doc +comment-list --node <DOC_ID> --resolve-status unresolved --limit 20 --format json
+dws doc +comment-list --node <DOC_ID> --limit 20 --cursor <NEXT_TOKEN> --format json
+dws doc +comment-create --node <DOC_ID> --content "这里需要补充证据"
+dws doc +comment-create --node <DOC_ID> --selection "计划下周发布" --content "请确认日期"
+dws doc +comment-reply --node <DOC_ID> --comment-key <COMMENT_KEY> --content "已补充"
+dws doc +comment-update --node <DOC_ID> --comment-key <COMMENT_KEY> --content "修订后的意见"
+dws doc +comment-delete --node <DOC_ID> --comment-key <COMMENT_KEY>
+```
+
+- 全文与划词评论统一使用公开的 `+comment-create`：优先传唯一 `--selection`；已知真实 block 时传 `--block-id --start --end`，CLI 自动回读并校验 `selectedText`。不要选用未公开的 `+comment-create-inline`。
+- `--mention` 传单个 uid 或逗号分隔列表，例如 `--mention 550582,123456`；不要传 JSON 数组。
+- 列表用 `--limit` 控制页大小（兼容 `--page-size`），有 `nextToken` 时原样传给 `--cursor`；不能把单页当作全部评论。
+- 创建、回复、删除等写操作执行前消费 leaf Schema `confirmation`；需确认时先询问，示例不得预填 `--yes`。
+- 删除不可恢复，必须核对 node 与 commentKey。部分或未知结果不得自动重试。
+
+只有 shortcut 未公开必要字段时，才读取精确原子 leaf Schema；不要加载整份评论参考或产品 Catalog 来猜参数。