# 开发者概览

> RooQi MCP 服务与命令行桥接能做什么、在哪里运行、不能做什么。

- Source: https://rooqi.cn/zh-hans/docs/developers/overview/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: RooQi Mac 1.0 测试版本 · 桥接协议 v1 · MCP 服务“RooQi” 0.1.0
- Status: 预览——包含在 Mac 测试版本中，尚未公开发布
- Last verified: 2026-10-26，依据 RooQi Mac 源码（RooQiBridge/Main.swift、RooQiIPCShared/Wire.swift、ExternalConnection.swift）
- Known limitations: 仅限 Mac，iPhone 与 iPad 没有外部连接。没有公开的 HTTP/REST API。正式发布前名称与限制可能调整。

RooQi Mac 版内置一个经过签名的小型辅助程序，让本机工具——通过模型上下文协议（MCP）接入的 AI 助手，或你自己的脚本——在**你于 RooQi 中批准每次连接之后**处理笔记。

## 能做什么

| 能力 | MCP 工具 | CLI |
|---|---|---|
| 检查 RooQi 是否可连接 | `rooqi_status` | `rooqi status` |
| 读取已授权文稿的已保存文字 | `rooqi_request_read_access`、`rooqi_list_approved_documents`、`rooqi_read_note` | `rooqi list`、`rooqi read <id>` |
| 新建笔记 / 追加文字 | `rooqi_request_write_access`、`rooqi_create_note`、`rooqi_append_text` | `rooqi run` |
| 读取 PDF 选区并新增高亮、下划线或评论 | `rooqi_request_pdf_annotation_access`、`rooqi_list_pdf_targets`、`rooqi_read_pdf_page`、`rooqi_annotate_pdf`、`rooqi_query_pdf_operation` | `rooqi pdf` |

## 工作方式

```text
MCP 客户端 / 脚本 ──stdio──> rooqi（桥接） ──XPC──> RooQi broker ──> RooQi.app
                                                     （校验代码签名）
```

- **桥接程序**（`rooqi`）作为客户端的子进程运行，通过标准输入输出交换 JSON。
- RooQi 注册的 **broker** 把请求转交给正在运行的 App，每一跳都校验代码签名。
- **App** 显示原生批准窗口，并执行范围、大小限制与幂等控制。

## 设计保证

- **未经批准不执行。** 每次连接都在 RooQi 原生窗口中询问。授权 **15 分钟**有效，连接断开即失效；新进程不会继承其他进程的授权。
- **一次一个项目。** 批准时选择一个项目，工具只能看到该项目。
- **只新增。** 写入只会新建笔记、追加新文字块或新增 PDF 批注；不会替换或删除已有正文、原始 PDF 与已有批注。
- **权限分开。** 读取、创建/追加与 PDF 批注分别批准。
- **如实失败。** 结果过大时拒绝而不截断；写入结果不确定时如实报告，便于查询而不是盲目重试。

## 不能做什么

- 读取手写、图像、表格、导图、选区以外的 PDF 原文或未保存草稿。
- 在同一台 Mac 未打开 RooQi 时运行，或连接其他设备上的 RooQi。
- 自行上传云端或调用 AI 服务。

## 下一步

- [安装、连接与授权](/zh-hans/docs/developers/connect/)
- [MCP 工具参考](/zh-hans/docs/developers/mcp-reference/)
- [CLI 参考](/zh-hans/docs/developers/cli-reference/)