示例与工作流

#让助手总结笔记（只读）

1. 调用 rooqi_request_read_access → approvalRequired。在 RooQi 中批准并选择项目。
2. 再次调用 rooqi_request_read_access → ready。
3. rooqi_list_approved_documents → { "<id>": "第三讲", … }
4. 以 { "documentID": "<id>" } 调用 rooqi_read_note → 已保存文字与 revision。

助手只能看到已保存文字，看不到手写、图像或 PDF 原文。

#安全地追加摘要

1. 请求写入授权并批准。
2. 读取笔记，获得当前 revision。
3. 为 operationID 生成新的 UUID，在调用前先保存。
4. 调用 rooqi_append_text：

{
  "operationID": "3B1F7A2C-9E44-4D51-A0C6-1E2F3A4B5C6D",
  "documentID": "<id>",
  "text": "摘要：…",
  "expectedVersion": 7,
  "provider": "example-assistant",
  "model": "example-model-1",
  "promptVersion": "summary-v1"
}

1. 遇到 mutationUncertain 或超时，用相同内容再次调用。遇到 mutationRejected，重新读取；只有确实要发起新写入时才使用新的 operationID。

#在 PDF 中高亮一句话

1. 调用 rooqi_request_pdf_annotation_access，批准后再次调用。
2. 以文稿调用 rooqi_list_pdf_targets → 从 availableSourcePages 中选择 surfaceID 与页。
3. 以某个区域调用 rooqi_read_pdf_page，例如第 0 页上半部分：

{ "documentID": "<doc>", "surfaceID": "<surface>", "pageIndex": 0,
  "rect": { "x": 0, "y": 0, "width": 1000000, "height": 500000 } }

1. 根据返回的 lines[].rect 把 rect 缩小到目标行并再次读取，然后调用 rooqi_annotate_pdf：使用相同 query、以返回的 revision 作为 expectedVersion、sourceAssetID 与三个 digest、kind: "highlight"、空的 comment。
2. 结果不确定时，用同一 operationID 调用 rooqi_query_pdf_operation。