FAQ
常见问题
关于启动与恢复、代码编辑与运行、库与扩展、文件传输、AI 模型与助手，以及购买与恢复。
启动与恢复
打开 Pythona 就闪退怎么办？
可以尝试安全启动：在主屏幕长按 Pythona 图标，选择「安全启动」。
启动时的闪退可能与恢复上次打开的文件或文件夹有关。安全启动会重置上次打开的标签页和文件夹记录，进入空白编辑器和本机 Documents 文件夹。你的脚本文件会保留。
成功启动后，可以逐个打开之前使用的文件夹和文件，排查是否与某个文件或位置有关。如果打开文件时再次闪退，并且已开启「语义高亮」，可以再次安全启动，在「设置 → 主题」中关闭「语义高亮」后重试。
升级后示例脚本无法运行怎么办？
App 升级不会自动替换已保存的示例脚本。如果升级后示例无法运行，可以先恢复当前版本附带的示例，再试运行。
请先备份你修改过的示例，然后在「设置 → 恢复示例脚本」中操作。恢复会覆盖 examples 文件夹中的同名示例文件。
恢复示例不会重置已安装的 Python 包。若仍出现依赖版本冲突，请根据报错检查已安装包的版本。
查看依赖冲突说明编辑与运行
输入代码时闪退怎么办？
如果在编辑器中输入代码时反复闪退，可能与自动补全有关。可以在「设置 → 代码补全」中关闭「自动显示建议」，然后在同一文件中重新尝试输入，观察是否仍会闪退。
反馈问题时，请附上触发问题的代码片段、具体输入步骤，以及关闭「自动显示建议」后是否仍会闪退。
为什么点击 Stop 后没有立即停止？
Stop 会请求中断当前运行，但不能立即打断所有操作。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 可以单独播放音乐或音效，无需创建窗口。
制作界面或 Web 游戏，可以使用 HTML、CSS 和 JavaScript，并在 Pythona 中通过 WKWebView 展示。网页内容便于跨平台复用。移植到其他平台时，需要相应调整 WKWebView 的显示代码，以及网页与 Python 或 iOS 功能交互的代码。
需要 iOS 原生界面时，可以通过 rubicon-objc 调用 UIKit。使用 UIKit 的代码仍然依赖 iOS。
Pythona 也支持 Tkinter，适合运行已有的 Tkinter 脚本或制作简单工具。界面采用传统桌面风格；如果更注重移动端的外观和交互，建议使用 Web 界面，或通过 rubicon-objc 调用 UIKit。App 内有对应示例。
文件
怎么与电脑交换文件？
代码项目推荐使用 Git：在 Pythona 和电脑上克隆同一个远程仓库，修改后提交并推送，再在另一端拉取更新。
可以通过 iCloud Drive 同步文件，或使用系统分享功能导出文件；与 Mac 交换文件时也可以使用隔空投送。
也可以在 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，请联系我们。