FAQ
常見問題
關於啟動與復原、程式碼編輯與執行、函式庫與擴充、檔案傳輸、AI 模型與助手，以及購買與還原。
啟動與復原
一打開 Pythona 就閃退怎麼辦？
可以嘗試安全啟動：在主畫面長按 Pythona 圖像，選擇「安全啟動」。
啟動時的閃退可能與還原上次開啟的檔案或檔案夾有關。安全啟動會重設上次開啟的分頁和檔案夾記錄，進入空白編輯器和本機 Documents 檔案夾。你的腳本檔案會保留。
成功啟動後，可以逐一開啟先前使用的檔案夾和檔案，排查是否與特定檔案或位置有關。如果開啟檔案時再次閃退，而且已開啟「語義高亮」，可以再次安全啟動，在「設定 → 主題」中關閉「語義高亮」後重試。
升級後範例指令碼無法執行怎麼辦？
App 升級不會自動替換已儲存的範例指令碼。如果升級後範例無法執行，可以先還原目前版本附帶的範例，再試著執行。
請先備份你修改過的範例，再到「設定 → 還原範例指令碼」操作。還原會覆寫 examples 資料夾中的同名範例檔案。
還原範例不會重設已安裝的 Python 套件。若仍出現相依套件版本衝突，請依照錯誤訊息檢查已安裝套件的版本。
查看相依套件衝突說明編輯與執行
輸入程式碼時閃退怎麼辦？
如果在編輯器中輸入程式碼時反覆閃退，可能與自動補全有關。可以在「設定 → 程式碼補全」中關閉「自動顯示建議」，然後在同一檔案中重新嘗試輸入，觀察是否仍會閃退。
回報問題時，請附上觸發問題的程式碼片段、具體輸入步驟，以及關閉「自動顯示建議」後是否仍會閃退。
為什麼點擊「停止」後沒有立即停止？
點擊「停止」會要求中斷目前執行，但無法立即中斷所有操作。time.sleep()、等待網路回應、等待鎖定和部分原生函式庫運算，都需要等操作返回後才能停止；匯入模組時也會等匯入結束。
如果長時間無法停止，可以先儲存檔案，再從 iOS 的 App 切換器關閉 Pythona 後重新開啟。
為什麼執行腳本時，App 會直接退出？
退出函式
如果腳本透過 quit()、exit() 或 sys.exit() 結束執行，Pythona 預設會退出整個 App。
在「設定 → quit() / exit()」中，將「退出 Pythona」改為「僅結束目前執行」，就可以只結束目前執行，讓 App 保持開啟。
記憶體不足
處理大型陣列或執行大型模型時，如果記憶體用量過高，iOS 可能直接終止 App，不一定會出現 Python 錯誤訊息。這種退出不受「quit() / exit()」設定控制。可以嘗試減少資料量、使用較小的模型，或分批處理。
UIKit 執行緒
Pythona 的 Python 腳本預設在背景執行緒執行。透過 ctypes 或 rubicon-objc 呼叫 UIKit 時，建立、更新介面等操作需要在 iOS 主執行緒（UI 執行緒）執行，否則可能導致 App 閃退。
可以將這些操作封裝為函式，透過內建的 run_on_ui(...) 非同步提交到主執行緒，也可以自行透過 GCD 提交到主佇列。App 內的 WKWebView 範例展示了 run_on_ui 的用法。
如果問題反覆出現，請附上可重現問題的程式碼和操作步驟回報。
怎麼結束輸入、傳送 EOF？
執行腳本時，在主控台輸入欄位的編輯選單中選擇「結束輸入（EOF）」，也可使用外接鍵盤 Ctrl+D。輸入欄位中的文字會先送出，再結束本次執行的輸入。
怎麼向腳本傳入參數？
長按編輯器的執行按鈕，選擇「帶參數執行…」。參數會傳給腳本的 sys.argv[1:]。常用參數可以透過同一選單裡的「編輯執行配置…」儲存，並設為預設配置。
怎麼從系統「捷徑」執行腳本？
在編輯器中點一下頂部檔案名稱，選擇「捷徑」，複製「腳本路徑」。然後在系統「捷徑」App 中加入 Pythona 的「執行 Python 腳本」動作，填入路徑。需要時可以加入參數，動作傳回的文字輸出也可以交給後續動作使用。
怎麼從主畫面一鍵執行腳本？
在 Pythona 中打開腳本，點一下編輯器頂部的檔案名稱，選擇「捷徑」，複製「URL」。
在系統「捷徑」App 中建立捷徑，加入「打開 URL」動作，填入剛才複製的 URL。
在該捷徑的「詳細資訊」中選擇「加入主畫面」，設定名稱和圖像後加入。
之後點一下主畫面上的圖像，就會打開 Pythona 並執行對應腳本。
查看 Apple 的加入說明函式庫與擴充
為什麼有些第三方函式庫無法安裝？
套件管理員支援安裝以純 Python wheel 形式發布的第三方函式庫。有些函式庫只提供原始碼，或依賴 C、C++、Rust 等編譯擴充模組，無法按照電腦上的方式直接安裝。NumPy、SciPy 等原生函式庫由 App 預先編譯提供。
純 Python 函式庫也需要相容於 Python 3.14 和 iOS；如果依賴目前環境不支援的系統功能，仍可能無法執行。
查看主要內建函式庫安裝套件時為什麼會更換相依套件版本，或提示衝突？
所有專案共用目前裝置的使用者套件環境。安裝時會沿用符合需求的既有相依套件；不符合需求時，可能升級或降級使用者安裝的純 Python 相依套件。App 內建套件不會被自動替換。
更換版本前，安裝程式會檢查其他已安裝套件宣告的相關相依需求。發現衝突或無法處理的需求時，會停止並說明原因；它不會窮舉所有版本組合，也無法涵蓋所有相容性問題。
可以指定相容版本、解除安裝不再需要的衝突套件後重試，或自行撰寫 Python 腳本下載、部署純 Python 套件並管理相依套件。呼叫 pythona.packages.install() 仍遵循以上規則；自行安裝也受 Python 和 iOS 的相容性限制。更換已匯入的套件後，請重新啟動 Pythona。
安裝的第三方函式庫會透過 iCloud 同步嗎？
不會。透過套件管理員安裝的第三方函式庫只儲存在目前裝置上。本機、iCloud 和外部資料夾中的腳本都可以使用這些函式庫。
透過 iCloud 同步專案後，需要在另一台裝置上另外安裝專案依賴的函式庫。
Pythona 提供哪些 iOS 功能函式庫？怎麼呼叫？
Pythona 內建 cocoa-py，其中 scene 用於遊戲、動畫與互動圖形；photos 用於透過系統相簿選取或儲存照片、影片；audio 提供音訊播放、錄音和音效處理；coreml 用於載入 Core ML 模型並在裝置上執行推論。
透過 pythona 可以使用 App 本身的功能：用 pythona.packages 安裝第三方套件，用 pythona.ai 建立、讀取和更新自訂 AI 供應商的設定。
需要呼叫更多 iOS 系統功能時，建議使用 rubicon-objc，透過 Python 呼叫 iOS 原生 API，包括用 UIKit 建立原生介面。可以參考 App 內的裝置資訊和 WKWebView 範例。
cocoa-py 已開源，也支援 macOS，實際功能因平台而異。原始碼與 API 文件可在 GitHub 查看，歡迎提交 Issue 或 Pull Request。
查看 cocoa-py 原始碼與文件開發遊戲或圖形介面，建議使用什麼？
2D 遊戲、動畫和音訊播放建議使用 pygame（App 內建 pygame-ce）。pygame.mixer 可以單獨播放音樂或音效，無須建立視窗。
製作介面或網頁遊戲，可以使用 HTML、CSS 和 JavaScript，並在 Pythona 中透過 WKWebView 顯示。網頁內容便於跨平台重複使用。移植到其他平台時，需要調整 WKWebView 的顯示程式碼，以及網頁與 Python 或 iOS 功能互動的程式碼。
需要 iOS 原生介面時，可以透過 rubicon-objc 呼叫 UIKit。使用 UIKit 的程式碼仍然依賴 iOS。
Pythona 也支援 Tkinter，適合執行既有的 Tkinter 腳本或製作簡單工具。介面採用傳統桌面風格；如果更重視行動裝置的外觀和互動，建議使用網頁介面，或透過 rubicon-objc 呼叫 UIKit。App 內有對應範例。
檔案
如何與電腦交換檔案？
程式碼專案建議使用 Git：在 Pythona 和電腦上複製同一個遠端儲存庫，修改後提交並推送，再在另一端提取更新。
也可以透過 iCloud Drive 同步檔案，或使用系統分享功能匯出檔案；與 Mac 交換檔案時，也可以使用 AirDrop。
也可以在 App 中啟用「檔案伺服器」，讓位於同一區域網路的電腦透過瀏覽器開啟 App 顯示的位址，上傳和下載檔案。檔案伺服器沒有登入密碼，請在可信任的網路中使用，傳輸完成後停止服務。
AI
可以在 Python 中使用哪些本機 AI 模型？
MLX：App 內建 MLX，可搭配 mlx-lm 執行相容的語言模型。可以參考 App 內的 examples/llm_demo.py；首次執行會連網安裝相依套件，並從 Hugging Face 下載模型。裝置需要支援 MLX，並有足夠的記憶體；執行速度和可用的模型規模取決於裝置效能及記憶體。
Apple Foundation Models：透過內建的 apple-fm-sdk 呼叫 Apple 提供的裝置端模型，在 Python 中使用 import apple_fm_sdk 匯入。需要 iOS / iPadOS 26 或更新版本、支援並啟用 Apple Intelligence 的裝置，以及已就緒的系統模型。可用性也受語言和地區限制，API 用法請見下方文件。
這兩種方式的模型推論都在裝置上完成。下載相依套件和模型需要連網；腳本或助手呼叫需要連網的工具時，也會存取網路。
查看 Foundation Models Python SDK 用法怎麼將本機模型串接至 AI 助手？
可以使用開源專案 Pythona AI Setup，為 Apple Foundation Models 或 MLX 本機模型建立 AI 助手設定。
在 Pythona 中複製專案，執行專案根目錄的 main.py，依頁面提示選擇模型和工具並新增設定，然後在 AI 助手設定中選擇對應的連線。詳細步驟請見專案 README。
MLX 模型需要支援工具呼叫，才能使用助手的檔案讀寫、執行 Python 等工具；不支援工具呼叫的模型可以關閉所有工具後用於對話。
查看 Pythona AI Setup 專案與使用說明AI 助手會讀寫哪些檔案？
AI 助手以目前對話的工作區作為預設專案目錄。在新對話傳送第一則訊息前，可以透過「切換工作區」選擇資料夾。切換檔案瀏覽器中的目錄不會改變既有對話的工作區。
AI 助手也可以呼叫 run_python 執行 Python 程式碼，讀取 App 內的檔案和資料夾，包括工作區以外的內容。這類存取不受所選工作區範圍限制。
AI 助手支援 AGENTS.md 嗎？
支援。在目前對話的工作區根目錄建立 AGENTS.md，可以寫入專案說明、程式碼風格和其他協作要求。
助手會在處理每則新訊息時自動讀取該檔案；修改並儲存後，下次傳送訊息時即可生效。只自動載入工作區根目錄的 AGENTS.md，不會自動合併子目錄中的同名檔案。
自訂供應商（JS Provider）有什麼用途？
透過自訂供應商，可以用 JavaScript 自行串接 AI 服務，使用內建供應商尚未支援的 API、驗證方式或服務功能，也可以加入自訂工具。
這裡使用 JavaScript，是為了把 AI 服務的連線、驗證和回應處理放在獨立的執行環境中，避免干擾使用者的 Python 環境。
自訂工具可以呼叫外部服務，也可以封裝 run_python，讓助手執行 Python 腳本，或透過腳本呼叫 iOS 功能。
如果內建供應商已經滿足需求，就不需要額外設定。需要擴充時，可以參考設定頁提供的 JavaScript API 和範例。
購買與還原
購買 Pro 後，換裝置還需要重新購買嗎？
不需要。在其他裝置的 App Store 中登入購買時使用的同一 Apple 帳號，即可繼續使用已購買的 Pro。
在新裝置上安裝或重新安裝 Pythona 後，如果仍顯示試用提示或購買頁面，可能是購買狀態尚未同步。請連接網路，在購買頁面點一下「還原購買項目」。
還原購買項目不會收費。即使再次點選購買，同一 Apple 帳號對已擁有的同一 Pro 項目也不會被重複扣款。
切換 Apple 帳號後，為什麼 Pro 無法使用？
Pro 購買項目會與購買時使用的 App Store 帳號連結。切換到另一個未購買 Pro 的帳號後，可能無法使用 Pro。請在 App Store 中切回購買時的帳號，再於 Pythona 中點一下「還原購買項目」。
如果頻繁切換 App Store 帳號影響了你使用 Pythona，請聯絡我們。