# AI 連線指南

> 將外部 AI App 連接到 Inkquation，讀取頁面，並新增影像、圖形和筆畫。

內容核對日期: 2026-09-10

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

## 功能與限制

Inkquation 支援 MCP，這是一種讓 AI App 呼叫工具的共通通訊協定。連線後，AI 可以將開啟的頁面或套索選取範圍讀取為影像，新增 PNG 影像、圖形和以點列定義的筆畫，查看結果，並復原符合條件的新增操作。

圖形會轉換為只有輪廓、沒有填色的普通筆畫。可以用橡皮擦和套索編輯，但沒有專用的圖形尺寸設定。文字和符號可以用筆畫繪製；目前不支援新增可編輯文字或 LaTeX 物件，也不支援編譯 LaTeX。讀取頁面時傳回的是影像，而不是經過文字辨識的文字。

## 連接 AI App

1. 在同一台 Mac 上使用支援本機 MCP 伺服器的 AI App。模型和帳號在該 App 中設定，Inkquation 不需要模型 API 金鑰。
2. 在 Inkquation 中開啟筆記，然後在「設定」→「AI 連線」中允許連線。此功能預設為關閉。
3. 從設定頁面拷貝 JSON 或 TOML 組態，合併到 AI App 的現有組態中。執行檔和連線路徑因 Mac 而異，請使用設定頁面顯示的值。
4. 重新連接 AI App，並保持 Inkquation 執行。將目標頁面捲動到可見區域。如果 AI App 要求批准編輯工具，請先確認要求的操作，再允許執行。

標準連線不需要安裝 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 的判斷，也無法阻止其透過其他工具向外傳送資料。

圖片新增與顯示載入共用 App 內的 9,600 萬像素額度，用於目前保留的顯示快取和正在處理的影像。畫面外不再需要的快取會自動釋放；原始影像、位置及復原/重做記錄會保留，再次顯示時會重新讀取。正在顯示的影像受到保護，空間不足時會暫停新增或載入。額度按目前保留量計算，開關 AI 連線也不會重設。原始資料和 PDF 高解析度檢視等另外使用記憶體，因此這不是整個 App 的記憶體上限。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 復原。請使用 App 的復原功能查看記錄。 |
| `session_limit` | 已達到 128 次新增操作的上限。請先確認結果，再於設定中關閉並重新啟用 AI 連線，重新連接 AI 應用程式並讀取頁面。不要使用新 ID 重複先前的編輯。 |

只有當該 AI 操作仍是最近一次可復原操作，且頁面未發生變更時，才能透過 MCP 復原。在設定中關閉 AI 連線或重新啟動 Inkquation 後，操作 ID 記錄不會保留。較早的操作請透過 App 的復原功能查看。

## 連線範圍與隱私權

連線透過同一台 Mac 上的本機程序通訊。本網站提供使用說明，並不是控制筆記的 MCP 伺服器。允許連線後，AI App 可以讀取 Inkquation 中已開啟筆記內的可用頁面。如果使用雲端模型，讀取的影像可能會傳送給模型供應商。

使用時請確認 AI 讀取的內容，不再需要時關閉 AI 連線。關閉連線不會刪除已經新增或儲存的內容，也不會刪除已經傳給外部服務的資料。

- [AI 連線與隱私權](https://inkquation.app/zh-Hant/privacy/#ai)

## 確認可用功能

本指南以 2026 年 9 月 9 日核對的實作為基礎。App 的發布情況與實際可用功能應分別確認；請查看所連接伺服器的 `tools/list`。如果沒有顯示圖形或筆畫新增工具，請確認目前 Inkquation 版本是否支援這些功能，並在更新 App 後重新連接 AI App。

- [Inkquation 的發布情況](https://inkquation.app/zh-Hant/#get-app)
- [MCP 工具規格](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)

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