# AI 连接指南

> 将外部 AI 应用连接到 Inkquation，读取页面，并添加图像、图形和笔画。

内容核对日期: 2026-09-10

[HTML](https://inkquation.app/zh-Hans/ai/)

## 功能与限制

Inkquation 支持 MCP，这是一种让 AI 应用调用工具的通用协议。连接后，AI 可以将打开的页面或套索选区读取为图像，添加 PNG 图像、图形和由点列定义的笔画，查看结果，并撤销符合条件的添加操作。

图形会转换为只有轮廓、没有填充的普通笔画。可以用橡皮擦和套索编辑，但没有专门的图形尺寸设置。文字和符号可以用笔画绘制；目前不支持添加可编辑文本或 LaTeX 对象，也不支持编译 LaTeX。读取页面时返回的是图像，而不是经过文字识别的文本。

## 连接 AI 应用

1. 在同一台 Mac 上使用支持本地 MCP 服务器的 AI 应用。模型和账户在该应用中设置，Inkquation 不需要模型 API 密钥。
2. 在 Inkquation 中打开笔记，然后在“设置”→“AI 连接”中允许连接。此功能默认关闭。
3. 从设置页面拷贝 JSON 或 TOML 配置，合并到 AI 应用的现有配置中。可执行文件和连接路径因 Mac 而异，请使用设置页面显示的值。
4. 重新连接 AI 应用，并保持 Inkquation 运行。将目标页面滚动到可见区域。如果 AI 应用要求批准编辑工具，请先确认请求的操作，再允许执行。

标准连接不需要安装 Python 或下载源代码。如果移动或重命名了 Inkquation，请重新拷贝连接配置。将本网站的 URL 填入网页版 AI 服务的连接地址栏，并不能建立连接。

## 实用请求示例

- “读取选中的公式推导，检查是否缺少中间步骤，或可能存在正负号错误。”
- “整理这一页的假设、结论和未解决的问题，并在聊天中解释。”
- “绘制一张辅助理解这段说明的示意图，添加到笔记的空白处。”

## AI 编辑页面的步骤

1. 调用 `inkquation_list_open_notes`，取得准确的 `note_id` 和 `page_id`。使用 `available: true` 的页面。如果目标不明确，先向用户确认。
2. 调用 `inkquation_get_page`，读取页面图像、`revision` 和逻辑尺寸。如果要读取选区，用户需要先用套索选中内容，再调用 `inkquation_get_selection`。
3. 选择空白区域，然后调用添加工具。将读取到的 revision 作为 `expected_revision`，并使用新生成的 UUID 作为 `operation_id`。
4. 调用 `inkquation_get_page` 查看结果。如有需要，使用该添加操作的 `operation_id` 调用 `inkquation_undo`。

## 工具与参数

连接后，请查看 `tools/list` 返回的输入模式，确认可用工具及其参数。所有添加工具都需要 `note_id`、`page_id`、`expected_revision` 和 `operation_id`。下表中的“编辑共通字段”指这四项。

| 工具 | 必需参数 | 行为 |
| --- | --- | --- |
| `inkquation_list_open_notes` | 无 | 列出已打开的笔记、页面 ID 和可用状态。 |
| `inkquation_get_page` | `note_id`, `page_id` | 读取页面 PNG、revision 和逻辑尺寸。 |
| `inkquation_get_selection` | `note_id`, `page_id` | 将用户当前的套索选区读取为 PNG；revision 对应整个页面。 |
| `inkquation_insert_image` | 编辑共通字段及 `png_base64`, `x`, `y`, `width`, `height` | 添加一张 PNG。标准连接不接受图像 URL 或本地文件路径。 |
| `inkquation_insert_strokes` | 编辑共通字段及 `strokes` | 根据点数组添加笔画。 |
| `inkquation_insert_shapes` | 编辑共通字段及 `shapes` | 将线段、长方形、椭圆、圆和箭头添加为普通笔画。 |
| `inkquation_undo` | `operation_id` | 在仍满足撤销条件时，撤销最近一次 AI 添加操作。 |

## 坐标、笔画与图像的限制

- 坐标原点位于页面左下角：x 向右增大，y 向上增大。请使用读取结果中页面的逻辑 `width` 和 `height`，不要使用缩放后的 PNG 像素尺寸。
- 选区 PNG 是裁剪后的图像。使用 `image_bounds` 确认选区在页面中的位置，不要将裁剪图像的左上角视为页面原点。
- `shapes` 每次调用接受 1–64 项。`kind` 可为 `line`、`rectangle`、`ellipse`、`circle` 或 `arrow`。对于长方形、椭圆和圆，`start` 与 `end` 是外接矩形的对角顶点。圆要求矩形宽高相等。箭头由 `start` 指向 `end`。
- `strokes` 每次调用也接受 1–64 项。每项的 `points` 包含 1–4,096 个点，整个调用最多 16,384 个点。点之间以直线连接；只有一个点时绘制圆点，在末尾重复起点可闭合路径。曲线应采样为点列。
- 每个图形或笔画都需要 `stroke_width`（0.1–100 个页面单位）和不透明的 sRGB `color`（`#RRGGBB` 格式）。整个图形，包括笔画宽度和箭头尖端，都必须位于页面内。每批图形或笔画作为一次撤销操作处理。
- PNG 数据在 Base64 编码前最多为 1 MiB。通过 `png_base64` 传入，并确保整个放置矩形位于页面内。

## 工具调用参数示例

以下是传给工具的参数模板。请将尖括号中的占位符替换为实际 ID、读取到的 revision 和新生成的 UUID。坐标仅为示例，应根据页面尺寸和空白区域调整。每次独立的添加操作都应使用不同的 UUID。

调用 `inkquation_insert_shapes` 并传入以下参数，即可添加圆和箭头。

```json
{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}
```

调用 `inkquation_insert_strokes` 并传入以下参数，即可添加折线。

```json
{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}
```

## 安全措施与处理上限

笔记标题或图片中的指令不代表获得了执行其他操作的许可。请在 AI 应用中确认允许读取和编辑的内容。Inkquation 的 MCP 工具不提供任意命令执行、任意文件读取或 URL 获取功能。这些措施无法控制 AI 的判断，也无法阻止其通过其他工具向外发送数据。

图片添加和显示加载共用应用内的 9,600 万像素额度，用于当前保留的显示缓存和正在处理的图像。屏幕外不再需要的缓存会自动释放；原始图像、位置及撤销/重做记录会保留，再次显示时会重新读取。正在显示的图像受到保护，空间不足时会暂停添加或加载。额度按当前保留量计算，开关 AI 连接也不会重置。原始数据和 PDF 高分辨率视图等另行使用内存，因此这不是整个应用的内存上限。AI 连接保持启用期间的 128 次添加上限单独保留，用于记录操作并防止重试造成重复添加。

读取和编辑准备在 Inkquation 内的每次操作中有 30 秒时限，不包含 AI 思考的时间。编辑或撤销一旦生效，保存过程就不会因该时限、关闭连接或取消请求而被取消。实际的保存失败仍会报告。关闭连接后，客户端无法收到响应，请在应用中确认结果。

## 重试与撤销

如果响应中断，无法确定添加是否成功，请使用完全相同的 `operation_id` 和参数重试同一个工具。改用新 ID 可能导致重复添加。重试返回的是已记录的操作结果，不会重新检查之后的手动保存或撤销状态。

| 结果 | 处理方法 |
| --- | --- |
| `page_changed` | 重新读取页面并重新考虑放置位置，不要只替换 revision 就机械地重复编辑。 |
| `page_unavailable` / `empty_selection` | 在 Inkquation 中显示目标页面，或用套索选中内容，然后重新读取。 |
| `busy` | 等待书写、粘贴或其他编辑处理结束。若添加结果不确定，重试时使用相同 ID 和参数。 |
| `rate_limited` | 短时间内调用过多。请稍等后重试。如果无法确定添加是否成功，请使用相同的操作 ID 和参数。 |
| `read_limit` | 内容超过了单次读取上限。请用套索选择较小区域，再读取该选区。 |
| `image_memory_limit` | 正在显示或处理的图像占满了图像额度。请等待处理完成、滚动离开图像较多的页面，或关闭暂时不用的笔记，然后使用相同的操作 ID 和参数重试。如果页面有变化，请重新读取。 |
| `request_cancelled` | 读取或编辑准备已被取消，或超过了时限。必要时选择较小区域，重新读取页面后再试。 |
| `disconnected` | AI 连接已关闭。已经生效的编辑仍会继续保存。请在应用中确认结果，重新启用连接后再读取页面。 |
| `operation_id_reused` | 同一 ID 被用于不同的参数。如果是重试，请使用原来的工具和参数。 |
| `isError: true`, `applied: true`, `persisted: false` | 编辑或撤销已在应用中生效，但尚未确认保存成功。请检查页面，在应用中重试保存或使用撤销。不要使用新 ID 重复同一编辑。 |
| `undo_conflict` | 后续编辑或撤销历史的变化阻止了 MCP 撤销。请使用应用的撤销功能查看历史。 |
| `session_limit` | 已达到 128 次添加操作的上限。请先确认结果，再在设置中关闭并重新启用 AI 连接，重新连接 AI 应用并读取页面。不要使用新 ID 重复先前的编辑。 |

只有当该 AI 操作仍是最近一次可撤销操作，且页面未发生变化时，才能通过 MCP 撤销。在设置中关闭 AI 连接或重新启动 Inkquation 后，操作 ID 记录不会保留。较早的操作请通过应用的撤销功能查看。

## 连接范围与隐私

连接通过同一台 Mac 上的本地进程通信。本网站提供使用说明，并不是控制笔记的 MCP 服务器。允许连接后，AI 应用可以读取 Inkquation 中已打开笔记内的可用页面。如果使用云端模型，读取的图像可能会发送给模型提供商。

使用时请确认 AI 读取的内容，不再需要时关闭 AI 连接。关闭连接不会删除已经添加或保存的内容，也不会删除已经传给外部服务的数据。

- [AI 连接与隐私](https://inkquation.app/zh-Hans/privacy/#ai)

## 确认可用功能

本指南基于 2026 年 9 月 9 日核对的实现。应用的发布情况与实际可用功能应分别确认；请查看所连接服务器的 `tools/list`。如果没有显示图形或笔画添加工具，请确认当前 Inkquation 版本是否支持这些功能，并在更新应用后重新连接 AI 应用。

- [Inkquation 的发布情况](https://inkquation.app/zh-Hans/#get-app)
- [MCP 工具规范](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)

[返回 Inkquation 首页](https://inkquation.app/zh-Hans/)