# 示例与工作流

> 读取笔记、安全追加文字与批注 PDF 的完整流程。

- Source: https://rooqi.cn/zh-hans/docs/developers/examples/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: MCP 服务“RooQi” 0.1.0 · 桥接协议 v1
- Status: 预览——尚未公开发布
- Last verified: 2026-10-26，依据 RooQi Mac 源码；尚未在公开发布版本上重新运行
- Known limitations: 新流程请先在单独的测试项目中尝试。

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

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`：

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

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

## 在 PDF 中高亮一句话

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

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

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