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。下表中的“编辑共通字段”指这四项。

坐标、笔画与图像的限制

• 坐标原点位于页面左下角：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 并传入以下参数，即可添加圆和箭头。

{
  "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 并传入以下参数，即可添加折线。

{
  "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 可能导致重复添加。重试返回的是已记录的操作结果，不会重新检查之后的手动保存或撤销状态。

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

连接范围与隐私

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

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

• AI 连接与隐私

确认可用功能

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

• Inkquation 的发布情况
• MCP 工具规范