AI 連線指南

連接 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 要求批准編輯工具，請先確認要求的操作，再允許執行。

一般重新啟動後仍可使用相同的連線設定。如果連線中斷，請重新連接 AI 用戶端。停用並重新啟用 AI 連線後，請拷貝新的設定。設定包含存取金鑰，請勿與他人分享。

標準連線不需要安裝 Python 或下載原始碼。如果移動或重新命名了 Inkquation，請重新拷貝連線設定。將本網站的 URL 填入網頁版 AI 服務的連線位址欄，並不能建立連線。

連接 Codex

1. 在 Inkquation 的「設定」→「AI 連線」中允許連線，選擇「Codex / TOML」，然後拷貝設定內容。
2. 使用文字編輯器開啟 Codex 設定檔，預設位置是~/.codex/config.toml。在 Finder 中選擇「前往」→「前往檔案夾」，輸入~/.codex/。
3. 加入拷貝的[mcp_servers.inkquation]區塊並儲存。如果已有該區塊，只更新其中的設定。保留其他伺服器與 Codex 設定，不要重複加入同名標題。
4. 保持 Inkquation 執行，重新啟動 Codex 的 MCP 連線，或儲存工作後重新啟動 Codex。開啟新聊天，使用下方的請求確認連線。

透過介面註冊時，在 Codex 的 MCP 伺服器設定中選擇 STDIO。指令欄填入拷貝設定中的command值，引數欄依原順序填入args的各項。此連線不使用網站 URL。介面名稱可能因用戶端版本而異。

如果不確定如何設定，可以向同一台 Mac 上的 Codex 傳送以下請求。連線設定包含存取密鑰，請將內容填入本機設定檔，不要貼到聊天中。

請協助我在這台 Mac 上透過 MCP 連接 Inkquation 與 Codex。閱讀 https://inkquation.app/zh-Hant/ai/ 的連線步驟，引導我拷貝並儲存設定。保留現有 Codex 設定，只新增或更新 inkquation 項目。不要在聊天或日誌中顯示存取密鑰或連線設定。連線後只列出已開啟的筆記，暫時不要編輯筆記。

• OpenAI 官方：Codex MCP 設定

連接 Claude Desktop

1. 在 Inkquation 的「AI 連線」設定中選擇「Claude Desktop / JSON」並拷貝設定內容。
2. 在 Claude Desktop 中開啟 Settings → Developer → Edit Config。Mac 上的預設檔案是~/Library/Application Support/Claude/claude_desktop_config.json。
3. 在現有的mcpServers物件中加入拷貝的inkquation項目。若已有同名項目，只更新該項目並保留其他項目。空白檔案可直接儲存拷貝的完整 JSON。
4. 保持 Inkquation 開啟，完全結束並重新啟動 Claude Desktop，再於新聊天中確認連線。

• MCP 官方：Claude Desktop 本機連線步驟

使用本機大型語言模型

若要在Mac上執行模型，需要本機模型執行環境，以及能呼叫Inkquation MCP工具的AI用戶端。LM Studio同時具備這兩種角色，因此這裡以它為設定範例。以下步驟依據官方文件撰寫，尚未在Mac上驗證與Inkquation搭配使用的完整流程。

1. 查看LM Studio的系統需求，下載並載入適合Mac記憶體容量的模型。目前的Mac版支援Apple Silicon。請選擇支援工具呼叫的模型；讀取頁面還需要支援影像輸入。
2. 在Inkquation的「設定」→「AI連線」中允許連線，複製「Claude Desktop / JSON」設定。在LM Studio右側的「Program」分頁開啟「Install」→「Edit mcp.json」。介面名稱可能因版本而異。
3. 將複製的inkquation項目加入現有的mcpServers物件並儲存。如已有同名項目，只更新該項目，保留其他設定。設定包含存取金鑰，請勿公開或貼到聊天中。
4. 保持Inkquation開啟，在LM Studio聊天中啟用inkquation工具，並使用下方的連線檢查提示詞取得筆記清單。清單傳回後，再用以下提示詞檢查影像讀取。

Inkquation以PNG影像傳回頁面。MCP連線成功不代表所選模型能讀取影像；AI用戶端還必須能將工具結果中的影像傳給模型。對於僅支援文字的模型，請先只檢查筆記清單的取得。

請列出Inkquation中開啟的筆記；如有多本，先讓我選擇。取得一個可讀取的頁面，只說明影像中可見的兩項內容。不要編輯筆記。如果影像未傳給模型或無法讀取，請回報此狀態，不要猜測內容。

若希望在Mac內處理筆記內容，請將推論目標設為本機模型，並避免切換到雲端模型或使用會向外傳送內容的工具。模型、執行環境的首次下載及更新檢查屬於另外的網路活動。

使用Ollama時，僅啟動模型並不能完成Inkquation連線設定。還需要搭配能使用Ollama進行推論，並註冊本機STDIO MCP伺服器的AI用戶端。請將設定加入該用戶端，分別檢查工具呼叫與影像傳遞。

• LM Studio官方：MCP伺服器設定
• LM Studio官方：系統需求
• LM Studio官方：離線使用
• Ollama官方：工具呼叫

確認連線的請求範例

請先將以下內容複製到 AI 聊天中。若沒有開啟筆記，請先在 Inkquation 中開啟一本。

請使用 Inkquation MCP 工具 inkquation_list_open_notes，告訴我目前已開啟的筆記名稱及可讀取的頁面。這次只確認連線，不要取得頁面影像或編輯內容。如果無法使用工具，請說明連線在哪一步失敗，不要推測已連線成功。

工具回傳結果即可確認連線。如果清單為空，請開啟筆記後再試。「已就緒 · 等待用戶端連線」表示 Inkquation 已準備好，不代表 AI 已連線。請同時確認用戶端數量與工具執行結果。

實用要求範例

連線後，可以嘗試以下請求。若開啟了多本筆記，請指定筆記名稱與頁面。

• 「讀取選取的公式推導，檢查是否缺少中間步驟，或可能有正負號錯誤。」
• 「整理這一頁的假設、結論和未解決的問題，並在聊天中說明。」
• 「繪製一張輔助理解這段說明的示意圖，新增到筆記的空白處。」

將工作資料夾交給 AI App

工作資料夾可存放與 AI 一起處理的程式碼、參考資料和產生的圖片。選擇儲存位置後，新增、複製筆記或從 PDF 匯入筆記時，App 會在筆記儲存後自動準備一個空的工作資料夾。複製筆記不會複製原筆記的工作檔案。

1. 在 Inkquation 中建立目標筆記，然後在筆記列表中按右鍵。
2. 用「打開工作資料夾」查看位置，再用「拷貝工作資料夾路徑」拷貝實際資料夾的路徑。
3. 在 Codex 等 AI App 中，將該路徑的資料夾設為工作目錄，並授予所需的檔案存取權限。之後即可請 AI 在其中建立存放參考資料的資料夾等。

透過 MCP 查詢時，請先開啟目標筆記，再使用 inkquation_list_open_notes 傳回的 note_id 呼叫 inkquation_get_workspace。引數範例：

{
  "note_id": "<note UUID>"
}

此工具僅供讀取，不會建立資料夾、改變 AI App 的工作目錄或授予檔案存取權限。移轉過程中或工作資料夾發生其他問題時，可能傳回 workspace_unavailable 錯誤；請檢查 Inkquation 的處理狀態和設定後再重試。

也可以將現有專案資料夾關聯到筆記。工作檔案的內容不包含在 Inkquation 的筆記備份中，請使用 Git 或其他備份方式管理。

Workspaces 與 Library 的差異

以下路徑展示所選儲存位置中的目錄結構。Library/ 下的筆記項目是指向實際資料夾的符號連結。透過連結編輯檔案也會改變實際檔案。

只有同一階層中發生名稱衝突時，才會附加短 ID，例如 Experiment--1a2b3c4d。大小寫或替換不適合檔案名稱的字元所造成的衝突也包括在內。如果短 ID 仍然衝突，會延長後綴直到名稱可以區分。

重新命名或移動筆記會改變其 Library/ 路徑，因此請將拷貝的實際資料夾路徑用作 AI 的工作目錄。在磁碟上建立資料夾或重新命名連結，不會建立或重新命名筆記資料庫中的筆記和資料夾。

無法連線時

功能與限制

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

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

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 連線預設關閉。啟用後，使用私人存取密鑰和正版內建轉接器的用戶端可透過 MCP 讀取已開啟的筆記和選取範圍並插入影像。設定包含存取金鑰，請勿與他人分享。重新啟動後能否保留設定取決於App版本。請查看AI整合指南中的連線與重新設定步驟。

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

• AI 連線與隱私權

確認可用功能

連接步驟以 2026 年 9 月 27 日核對的實作為基礎；工作資料夾和 Library 的說明以 2026 年 10 月 1 日的實作為基礎。這不代表所有已發布版本都支援這些功能。請查看所連接伺服器的 tools/list。如果缺少所需工具或工作資料夾選單，請更新到支援該功能的版本並重新連接 AI App。即使工具或選單已經顯示，舊版本的工作資料夾自動準備方式和 Library 命名規則也可能與此處的說明不同。

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