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。下表中的「編輯共通欄位」指這四項。

座標、筆畫與圖像的限制

• 座標原點位於頁面左下角：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 的判斷，也無法阻止其透過其他工具向外傳送資料。

圖片新增與顯示載入共用 App 內的 9,600 萬像素額度，用於目前保留的顯示快取和正在處理的圖像。畫面外不再需要的快取會自動釋放；原始圖像、位置及還原/重做記錄會保留，再次顯示時會重新讀取。正在顯示的圖像受到保護，空間不足時會暫停新增或載入。額度按目前保留量計算，開關 AI 連線也不會重設。原始資料和 PDF 高解像度檢視等另外使用記憶體，因此這不是整個 App 的記憶體上限。AI 連線保持啟用期間的 128 次新增上限單獨保留，用於記錄操作並防止重試造成重複新增。

讀取及編輯準備在 Inkquation 內的每次操作中有 30 秒時限，不包含 AI 思考的時間。編輯或還原一旦生效，儲存程序就不會因該時限、停用連線或取消要求而被取消。實際的儲存失敗仍會報告。停用連線後，用戶端無法收到回應，請在應用程式中確認結果。

重試與還原

如果回應中斷，無法確定新增是否成功，請使用完全相同的 operation_id 和參數重試同一個工具。改用新 ID 可能造成重複新增。重試傳回的是已記錄的操作結果，不會重新檢查之後的手動儲存或還原狀態。

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

連線範圍與私隱

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

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

• AI 連線與私隱

確認可用功能

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

• Inkquation 的發布情況
• MCP 工具規格