常见问题

Stop 会请求中断当前运行，但不能立即打断所有操作。time.sleep()、网络等待、等待锁和部分原生库计算，需要等操作返回后才能停止；导入模块时也会等导入结束。

如果长时间无法停止，可以先保存文件，再从 iOS 的 App 切换器关闭 Pythona 后重新打开。

如果脚本通过 quit()、exit() 或 sys.exit() 结束运行，Pythona 默认会退出整个 App。

在「设置 → quit() / exit()」中，将「退出 Pythona」改为「仅结束当前运行」，就可以只结束当前运行，让 App 保持打开。

处理大数组或运行大模型时，如果内存占用过高，iOS 可能直接终止 App，不一定会出现 Python 报错。这种退出不受「quit() / exit()」设置控制。可以尝试减小数据或模型规模，或分批处理。

如果问题反复出现，请附上复现代码和操作步骤反馈。

长按编辑器的运行按钮，选择「带参数运行…」。参数会传给脚本的 sys.argv[1:]。常用参数可以通过同一菜单里的「编辑运行配置…」保存，并设为默认配置。

在编辑器中点击顶部文件名，选择「快捷指令」，复制「脚本路径」。然后在系统“快捷指令”App 中添加 Pythona 的「运行 Python 脚本」动作，填入路径。需要时可以添加参数，动作返回的文本输出也可以交给后续动作使用。

包管理器支持安装以纯 Python wheel 形式发布的第三方库。有些库只提供源代码，或依赖 C、C++、Rust 等编译扩展，无法按电脑上的方式直接安装。NumPy、SciPy 等原生库由 App 预编译提供。

纯 Python 库也需要兼容 Python 3.14 和 iOS；如果依赖当前环境不支持的系统功能，仍可能无法运行。

不会。通过包管理器安装的第三方库只保存在当前设备上。本机、iCloud 和外部文件夹中的脚本都可以使用这些库。

通过 iCloud 同步项目后，需要在另一台设备上单独安装项目依赖的库。

Pythona 内置的 scene 用于游戏、动画与交互图形；photos 用于通过系统相册选择或保存照片、视频；audio 提供音频播放、录音和音效处理；coreml 用于加载 Core ML 模型并在设备上执行推理。

通过 pythona 可以使用 App 本身的功能：用 pythona.packages 安装第三方包，用 pythona.ai 创建、读取和更新自定义 AI 提供方的配置。

这些模块依赖 Pythona 的运行环境。迁移到其他 Python 环境时，需要替换或调整相关调用。其他 App 中的同名模块也可能使用不同的 API。

需要调用更多 iOS 系统功能时，推荐使用 rubicon-objc，通过 Python 调用 iOS 原生 API，包括用 UIKit 创建原生界面。可以参考 App 内的设备信息和 WKWebView 示例。

这些专有扩展目前不提供独立的 API 文档。可以参考 App 内的示例、可读取的 Python 模块源码和模块自带的帮助信息，也可以让 AI 助手先查看这些资料，再编写和运行代码。

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 助手以当前对话的工作区作为默认项目目录。在新对话发送第一条消息前，可以通过「更换工作区」选择文件夹。切换文件浏览器中的目录不会改变已有对话的工作区。

AI 助手也可以调用 run_python 执行 Python 代码，读取 App 内的文件和文件夹，包括工作区之外的内容。这类访问不受所选工作区范围限制。

支持。在当前对话的工作区根目录创建 AGENTS.md，可以写入项目说明、代码风格和其他协作要求。

助手会在处理每条新消息时自动读取该文件；修改并保存后，下次发送消息时即可生效。只自动加载工作区根目录的 AGENTS.md，不会自动合并子目录中的同名文件。

通过自定义提供方，可以用 JavaScript 自行接入 AI 服务，使用内置提供方尚未支持的 API、认证方式或服务功能，也可以添加自定义工具。

这里使用 JavaScript，是为了把 AI 服务的连接、认证和响应处理放在独立的运行环境中，避免干扰用户的 Python 环境。

自定义工具可以调用外部服务，也可以封装 run_python，让助手运行 Python 脚本，或通过脚本调用 iOS 功能。

如果内置提供方已经满足需求，就不需要额外配置。需要扩展时，可以参考配置页提供的 JavaScript API 和示例。