AI-IDE 操作手冊

什麼是 AI-IDE

AI-IDE 是一款專為 iPhone 與 iPad 設計的整合式編輯器,結合本地檔案編輯與大型語言模型(LLM)協作能力。

檔案編輯

10 種語言語法高亮,行號、自動儲存、搜尋取代

AI 協作

對話視窗中讓 AI 讀寫工作目錄裡的檔案

BYOK

自帶 API Key,連 OpenAI / Anthropic / Gemini / DeepSeek / OpenRouter / Groq / 等

安全可控

AI 改動皆顯示 Diff 卡片,使用者 Approve 才寫入磁碟

跨裝置 UI

iPad 三欄 Split View / iPhone 分頁式

三語介面

繁體中文 / 簡體中文 / English

1. 開始使用

第一次啟動時,App 會引導你選擇一個工作目錄。請點選「選擇工作目錄」按鈕,從 iOS Files App 選擇任何你希望 App 在裡頭工作的資料夾(iCloud Drive / 本機 / 第三方雲端皆可)。

2. 工作目錄

2.1 選擇資料夾

點下「選擇工作目錄」會彈出 iOS 系統的資料夾選擇器。Files App 中可見的任何位置都能挑(包含已連線的 Google Drive、Dropbox 等)。

2.2 多個工作目錄

選過的工作目錄會保留在「最近清單」中,可隨時切換。檔案分頁頂端有家圖示 + 工作目錄名稱,右上 ⋯ menu 可叫出切換選單。

• 左滑某個工作目錄項目可刪除或釘選
• 釘選的會永遠排在最上方
• 右上「＋」可隨時加新的工作目錄

3. 檔案管理

3.1 瀏覽檔案

檔案分頁左側顯示工作目錄樹狀結構。點資料夾展開/收合,點檔案開啟到編輯器。

3.2 新增檔案 / 資料夾

1. 點 home row(顯示工作目錄名稱那行)右側的 ⋯ menu
2. 選「新增檔案」或「新增資料夾」
3. 輸入名稱 → 建立

3.3 重新命名 / 刪除

對任何檔案 / 資料夾長按,可在 context menu 中選擇重新命名或刪除。

4. 編輯器

4.1 語法高亮

編輯器內建 10 種語言的語法高亮:Markdown / Swift / Python / JavaScript / TypeScript / JSON / YAML / HTML / CSS / Shell。對 Markdown 還會把標題依 # 數量顯示不同字級。

4.2 多分頁

同時開啟多個檔案,頂端 tab bar 切換。橙點代表「未儲存修改」,X 關閉分頁。

4.3 搜尋與取代

右上 ⋯ menu → 「搜尋與取代」。輸入關鍵字與取代字串後點「全部取代」即可。

4.4 鍵盤收起

iPhone 上鍵盤升起會擋住底部 TabBar。三種方式收起:

• 鍵盤上方的 「完成」工具列 — 一鍵收起
• 點上方的 tab bar 空白
• 點下方的狀態列(Markdown / UTF-8 那行)

4.5 狀態列

編輯器底部狀態列顯示:語言類型、唯讀標記、未儲存標記、外部檔標記、檔案編碼。

4.6 外部檔編輯

從 Files App 用「打開方式 → AI-IDE」開啟的檔案會顯示「外部檔」標記。儲存時會寫回原本位置(不會複製到工作目錄)。

4.7 Markdown 預覽

開啟 Markdown 檔(.md / .markdown)時,編輯器右上會出現編輯 / 預覽切換鈕。切到預覽會把 Markdown 轉成 HTML 排版顯示(標題、清單、引用、程式碼區塊、表格、分隔線等);切回編輯則維持原始(raw)文字。

• 預覽以離線方式算繪,不執行 JavaScript、不主動下載外部資源(圖片顯示為佔位框),確保安全與隱私
• 預覽為唯讀;要修改請切回編輯模式
• 非 Markdown 檔不會出現切換鈕

5. LLM Provider 設定

AI 對話需要先設定至少一個 LLM Provider(填入 API Key)才能使用,因此建議先完成這一步。

5.1 Provider 列表

5.2 一鍵預設範本

新增 Provider 時可從「從預設範本快速設定」挑常用端點,自動填入名稱、類型、Base URL:

• OpenAI / Anthropic / Google Gemini(官方)
• DeepSeek / OpenRouter / Groq / Cerebras / Mistral / NVIDIA NIM / Together AI(OpenAI 相容)
• MiniMax(Anthropic 相容)/ Moonshot Kimi / 通義千問
• Ollama(本機)

5.3 完整編輯介面

類型

OpenAI 相容 / Anthropic 相容 / Gemini 相容 / Ollama

Base URL

API 端點根 URL

API Key

儲存於 iOS Keychain,不入備份

從 Provider 拉取模型清單

自動取得該端點可用模型

停用工具呼叫

遇到不支援 tools 的相容端點時可關閉

5.4 篩選顯示的模型

對於 OpenRouter 這種有 300+ 模型的端點,可從「篩選顯示的模型」勾選你要在對話 picker 中看到的:

5.5 對話中切換模型

6. AI 對話

6.1 介面總覽

對話清單(≡)

切換歷史對話或刪除

標題

自動以第一條訊息前 20 字命名

模型 picker

切換要用哪個 LLM 模型

⊕ menu

開啟新對話 / 重置目前對話

⚙ 設定

直接跳設定頁面

6.2 發送訊息

在輸入框輸入訊息,用 @檔案路徑 引用工作目錄中的檔案內容(例如 @notes.md)。AI 在這輪會看到該檔案的完整內容。

6.3 模型選擇

頂部模型 chip 可點開,看到當前 Profile 的所有可用模型。系統會根據訊息類型(程式 / 對話 / 長上下文 / 視覺)建議合適的模型。

標籤顏色:Code=藍 / Vision=紫 / Long Context=綠 / Chat=灰。

6.4 工具呼叫顯示

AI 呼叫工具(讀檔、寫檔、列目錄、搜尋、網路搜尋)時,訊息中會顯示橙色 wrench chip。工具結果以綠色 seal chip 顯示。

6.5 對話管理

• 開啟新對話:保留舊 thread,新開一個
• 重置目前對話:刪除當前 thread 並開新的(徹底清乾淨)

6.6 錯誤訊息

AI 端點若回傳錯誤(API Key 錯誤、模型不存在、tool calling 不支援等),會顯示橙色 banner 含具體錯誤訊息。

7. Prompt 庫（AI 指令）

Prompt 庫讓你建立多個「系統提示 preset」，選一個設為全域生效。生效的指令會自動加在每次對話最前面，用來提升輸出品質、降低幻覺、或固定某種寫作 / 程式風格。

7.1 進入與切換

• 管理:設定 → Prompt 庫（AI 指令）
• 隨時切換:對話視窗標頭，模型名稱旁的 📋 目前 Prompt 小選單 — 不必進設定即可切換或關閉
• 選「不使用自訂指令」即關閉(行為與舊版相同)

7.2 建立自己的 Prompt

1. 設定 → Prompt 庫 → 右上「＋」→「新建」
2. 填名稱與指令內容 → 儲存
3. 在清單中點它即設為生效(打勾)

7.3 從 GitHub 匯入

右上「＋」→「從 GitHub 匯入」，貼上 github.com/.../blob/... 或 raw.githubusercontent.com 連結，App 會自動轉成 raw 連結並下載、預覽，確認後「加入並啟用」。

7.4 內建「推薦 Skills」目錄

Prompt 庫 →「瀏覽推薦 Skills」提供 10 個精選用途。每個可先改別名(預設已填好)，再按下載鈕由你的裝置向 GitHub 取得；已下載的會顯示 reload 圖示，重複下載會詢問是否覆蓋。

8. Diff 套用流程

當 AI 想修改檔案,絕對不會直接寫 — 而是顯示一張 Diff 卡片讓你檢視。

三個操作選項

1. 套用(綠色) — 寫入磁碟,自動 snapshot 原檔到 .aiide/snapshots/
2. 拒絕(紅色) — 不寫入,告訴 AI 已拒絕,可繼續對話
3. 編輯後套用(灰色) — 進入 CodeTextView 手動微調 AI 提案,再點套用

9. 版本控制

為任何工作目錄啟用「版本控制」，就能把目前狀態存成一個個版本（commit），日後檢視差異、還原單一檔案或整個版本。這是本機、選用的功能 — 不啟用就完全不作用。

9.1 啟用

• 檔案分頁右上角的 🕘 圖示 → 開啟版本控制畫面
• 第一次使用按「啟用版本控制」即可(會在工作目錄寫入一個小的 .aiide/vcs.json 標記，預設隱藏)

9.2 建立版本（commit）

1. 「未提交的變更」區會列出與最新版本不同的檔案;🕘 圖示也會顯示未提交數量徽章
2. 點「建立版本」→ 勾選要納入的檔案、填訊息 → 建立

9.3 檢視差異與還原

• 在「歷史」點某個版本 → 點檔案 → 看這個版本改了什麼(與上一版的紅綠差異)
• 還原單檔:把該檔還原成這個版本的內容
• 還原整個版本:以這個版本覆蓋工作目錄;若有多餘檔案會詢問是否一併刪除
• 還原前都會自動建立還原點，可再反悔

9.4 AI 核准後自動建立版本

在設定 → 版本控制開啟「AI 核准後自動建立版本」後，每次核准 AI 的檔案修改就自動 commit 一個版本(訊息取自你的指令)。預設關閉。

9.5 清理

版本畫面左上 ⋯ →「清理未使用的版本資料」可釋放沒有任何版本參照的資料區塊。版本資料採內容去重 + 壓縮，通常很精簡。

10. 上傳檔案

對話輸入框左側的迴紋針圖示可上傳檔案,四種來源:

從檔案上傳

iOS Files App,任何位置

從相簿上傳

PhotosPicker — 圖片直接餵給 Vision 模型

使用相機拍攝

當場拍照上傳

從剪貼簿貼上

剪貼簿是圖 → 附圖;是文字 → 插入輸入框

圖片附件

圖片會顯示在輸入框上方,可單獨關閉。發送時連同訊息送給 AI(Vision 模型直接看圖,其他模型會被忽略)。

檔名衝突

上傳的檔案會落到工作目錄的 uploads/ 子資料夾。若同名衝突,可選自動重新命名、覆蓋或取消。

PDF / DOCX 自動轉錄

上傳 PDF 或 Word 文件時會自動產生 .txt 轉錄檔,輸入框會自動 @ 引用轉錄檔(讓 LLM 看純文字,省 token)。原檔同樣保留在 uploads/。

11. 網路搜尋 web_search 工具

讓 AI 在對話中搜尋網路。三家後端可選:

• Brave Search — 2,000 次 / 月免費
• Tavily — 1,000 次 / 月免費,為 LLM 設計
• Perplexity Search — $5 / 月免費額度

1. 設定 → 網路搜尋
2. 選後端 → 點「申請 API Key」連結到該家網站註冊
3. 貼上 Key,按 ▶ 測試
4. 回到對話,AI 可呼叫 web_search 工具

12. 應用程式設定

12.1 語言

支援跟隨系統 / 繁體中文 / 簡體中文 / English。切換後大部分 UI 文字即時更新。

12.2 外觀

跟隨系統 / 強制淺色 / 強制深色。

12.3 編輯器偏好

• 字級:10 ~ 28 pt
• 自動儲存:打字停止後 0.5 ~ 10 秒自動存檔

12.4 資料流向

進到「資料流向說明」可看到本 App 對你資料的具體承諾。

12.5 關於

版本資訊與技術支援連結(sportusagi@gmail.com)。

13. iOS 系統整合

13.1 設為 .md 預設編輯器

AI-IDE 已註冊為 Markdown、Plain Text、Source Code、JSON / YAML / XML 等檔案類型的可開啟 App。

1. 在 iOS Files App 找到 .md 檔
2. 長按 → 共享 或 打開方式…
3. 選 AI-IDE
4. 檔案會在 AI-IDE 編輯器中開啟,狀態列顯示「外部檔」

13.2 iPad Split View

iPad 橫向會自動展開三欄:檔案樹 / 編輯器 / 對話。可同時看到三個 pane。

13.3 iPhone 分頁式

iPhone 採用底部 TabBar:檔案 / 編輯 / 對話 / 設定。點檔案後自動切到編輯分頁;關掉所有分頁則自動切回檔案分頁。

14. 鍵盤快捷鍵

iPad 外接鍵盤(或 iPhone Magic Keyboard)可用以下快捷鍵:

⌘ S

儲存當前檔案

⌘ P

快速開檔(輸入檔名跨工作目錄搜尋)

⌘ ,

開啟設定

⌘ ⇧ N

新對話

⌘ ⏎

在對話輸入框中按 Enter 送出

15. 隱私與安全

• API Key 儲存於 iOS Keychain,僅本機可用,不會同步至其他裝置
• 對話紀錄與設定儲存於本機 SwiftData 資料庫,可隨時刪除
• AI 修改檔案前一律顯示 Diff 卡片,使用者 Approve 才寫入
• 每次寫入前的原檔會 snapshot 到 .aiide/snapshots/
• 本 App不做任何遙測 / 使用分析
• 對外連線僅指向使用者自行設定的 LLM 端點,不經第三方代理

16. 疑難排解

「AI 端點未回傳任何事件」

常見原因:

• Base URL 拼錯
• API Key 過期 / 無效
• 模型名稱不存在於該家服務
• 該模型不支援 tool calling — 試到 Provider 設定打開「停用工具呼叫」

切到英文後仍有部分文字是中文

大部分文字會即時更新,少數系統元件(原生 alert / picker)需要重啟 App 才會套用。

新增檔案後沒反應

確認工作目錄有寫入權限(iCloud Drive 同步衝突也會擋寫入)。若仍失敗會跳具體錯誤 alert。

iPad multitasking 灰掉

請更新到最新版 App(v1.0.0 之後已支援四向 orientations)。

關閉所有檔案後 App 變空白

iPhone 上會自動切回「檔案」分頁;若卡住請手動切。