Mural

一款你最终会删除的语言应用。

Mural 是一款通过对话学习的原生 iPhone 应用。对着一个温暖、会动的语音球说话，在需要时跟随含义字幕，并在之后的对话中再次练习生词。Mural 会根据你回答中的证据调整挑战难度。

应用使用 SwiftUI、Liquid Glass 和本地 SwiftData 存储构建。此版本使用你自己的 API key 直接连接 OpenAI。它需要网络连接，但不需要 Mural 账号或一台运行中的 Mac。

快速开始

你需要一台装有 Xcode 26 或更高版本的 Mac、一台运行 iOS 26.1 或更高版本的 iPhone、一个 Apple 账号，以及一个已开通计费并可访问 GPT-Live-1 和 GPT-5.6 Luna 的 OpenAI API 项目。ChatGPT 订阅不提供 API 额度。

使用本地 AI agent 安装

如果 Codex 或其他编程 agent 可以访问你 Mac 的文件和终端，粘贴下面的提示词。该 agent 可以克隆、构建并安装 Mural。你只需在 Xcode 中完成 Apple 账号登录和团队选择、设备信任和开发者模式提示，以及在应用内输入 API key。iPhone 安装指南 逐步介绍了每个环节。

帮我从 https://github.com/Chuloo/mural 构建并在我的 iPhone 上安装 Mural。

将仓库克隆到一个新的本地文件夹；如果该检出已经打开，就直接使用它。阅读 README.md、docs/run-on-iphone.md 和 docs/build-and-test.md。确认 Xcode 及其 iOS 工具就绪，解析固定版本的依赖，运行离线核心测试，并构建 iOS 模拟器目标。

引导我在 Xcode 中添加 Apple 账号并选择签名团队。首次安装时，如有需要帮助我选择唯一的 bundle identifier。更新 Mural 时保留现有的团队和标识符，不要卸载它或抹掉其学习数据。

检测我已连接的 iPhone，使用配置好的签名团队构建、安装 Mural 并启动它。当我需要解锁手机、信任这台 Mac 或开发者描述文件、开启开发者模式或批准系统提示时，及时告诉我。

我会选择学习和字幕语言，然后在 设置 > 高级 > 使用自己的 API key 中输入我自己的 OpenAI API key。不要让我把 key 粘贴到对话里、从 Keychain 读取它，或把它写进源代码文件或日志。保持托管账号、托管试用和购买功能处于禁用状态。

最后报告哪些构建和安装检查已通过，以及我在手机上还需要完成的步骤。我将开始第一次实时对话。

使用 Xcode 安装

1. 克隆 Chuloo/mural，或下载其 ZIP。从包含本 README 的目录打开 Mural.xcodeproj。
2. 在 Xcode 中打开 Settings → Accounts，添加你的 Apple 账号。
3. 选择 Mural target，打开 Signing & Capabilities，启用自动签名并选择你的团队。如果你使用自己的 fork，请将 bundle identifier 替换为唯一值，例如 com.yourname.mural，并在后续更新中保持该值稳定。
4. 连接并解锁 iPhone。如有提示请信任这台 Mac。在手机上打开 设置 → 隐私与安全性 → 开发者模式，重启并确认该设置。
5. 选择 Mural 作为 scheme，你的 iPhone 作为目标设备，然后点击 Run。如果 iOS 要求你信任开发者，请在 设置 → 通用 → VPN 与设备管理 中操作。
6. 在欢迎页面选择学习和字幕语言。在 设置 → 高级 → 使用你自己的 API key 中保存你自己的 OpenAI 项目 key。开始一次对话并允许麦克风访问。

你应该会听到 Mural 用你选择的语言问候你。现在你可以断开手机与 Mac 的连接，改用 Wi-Fi 或蜂窝网络。

免费的 Personal Team 可以在你自己的手机上运行该应用；TestFlight 和 App Store 分发需要 Apple Developer Program 会员资格。免费 provisioning profile 会在七天后过期。再次运行同一项目即可刷新，同时保留团队和 bundle identifier。在更改任一项或更换手机前，请导出学习备份。常见设置问题见详细 iPhone 指南。Apple 会员指南

目前可用的功能

• 温暖的欢迎： 在两个简短页面中选择学习语言和字幕语言，问候语会随语言变化。
• 对话练习： 实时语音、温和纠错、可选含义字幕、单词查询、静音，以及说话不便时的文字回复。
• 主题： 24 种对话场景，每种语言模块提供文化细节。你也可以请求一个当前话题；网络搜索会提供来源链接。
• 自适应练习： 词汇和临时能力观察来自经过验证的对话证据。每种学习语言保持独立进度。
• 记忆条： 一到三条杠总结一段时间内的重复提取情况。三条杠需要在不同情境下的间隔式证据。这些是产品启发式规则，而非经过校准的遗忘概率或语言证书。
• 全新开始： 对话结束 15 秒后，Talk 页面会返回问候语。点击 New conversation 可立即重置。你保存的对话和学习记录仍然保留。
• 本地记录： 从设置中导出或导入 JSON 学习备份、删除某段对话，或删除全部学习数据。

各模块教授挪威语书面语（Bokmål，以东部挪威语音为目标）、西班牙语（西班牙）、国际英语、法语（法国）、德语（德国）、意大利语（意大利）、巴西葡萄牙语，以及标准普通话（简体中文）。每种语言都有各自的对话主题、教学指导和进度。有效的地区变体同样被接受。

普通话在 Talk、转录和单词详情中支持可选拼音。中文单词查询使用词边界，原始汉字仍可从转录中复制。拼音使用系统词典读音；人名、歧义词和连读变调仍需通过听力检查确认。语音口音和教学指导属于模型指令，在就发音或学习效果做出声明之前，仍需母语者审校。

隐私与 API 费用

Mural 将对话、词汇和偏好设置存储在你的设备上。此版本的 iPhone 应用没有 Mural 云同步、分析 SDK、广告或账号关联。你的 API key 存储在设备的 Keychain 中，不会包含在学习数据导出里，并且只发送给 OpenAI。

练习期间，音频、选定的对话文本、学习上下文和请求的搜索会发送给 OpenAI。Mural 不保存原始音频。API 请求在支持的地方设置了 store: false，但这并不能禁用所有提供商的数据保留策略；OpenAI 的滥用监测规则和你的项目设置仍然适用。OpenAI 数据控制

OpenAI 会就语音、文本和搜索向你的项目收费。应用内的用量显示是估算值，其对话时长限制并非计费上限。请自行查看你的 OpenAI 项目的用量和支出设置。

规划中的公共服务

托管免费分钟数、账号和额度购买在 iPhone 应用或 Mural 实时服务中均不可用。后端基础 包含账号验证、额度账本和沙盒支付支持。其 runbook 列出了商业激活前剩余的工作。任何共享的提供商 key 都不应出现在本仓库或分发的应用二进制文件中。

公开的 TestFlight 链接和 App Store 上架暂未提供。发布准备 记录了待完成的要求。

Mural 网站 位于独立的 Chuloo/mural-website 仓库。

构建与测试

在包含 Package.swift 的目录中：

swift test
xcodebuild -project Mural.xcodeproj -scheme Mural \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath .build/DerivedData \
  CODE_SIGNING_ALLOWED=NO ARCHS=arm64 ONLY_ACTIVE_ARCH=YES build

对于 UI 测试，在 Xcode 中创建或选择一台 iPhone 17 模拟器，然后运行 Product → Test。测试使用内存 fixture，不需要 API key。更多命令和预览选项见构建指南。

2026 年 9 月 13 日，八语言构建通过了 70 项核心测试和 20 项原生 UI 测试，涵盖普通话拼音、全部四个新增引导选项和最大辅助功能字号。79 项后端测试在隔离的 PostgreSQL 数据库下全部通过，无跳过。德语、意大利语、巴西葡萄牙语和普通话各自通过了一次真实 iPhone 检查，使用合成的文字回复和真实的语音输出、含义显示及单词查询。这些检查并不能证明人类语音识别、发音或纠错的质量水平。验证记录

代码地图

阅读语言架构的工作原理和如何添加一种语言。贡献代码请遵循 CONTRIBUTING.md；安全问题请使用私密报告流程。

依赖与许可证

原生 WebRTC 包固定为 stasel/WebRTC 152.0.0。应用捆绑了第三方声明和 SDK 的隐私清单。更改依赖时请查阅上游声明。

Mural 基于 MIT 许可证 发布。第三方组件保留各自许可证。Mural 名称和标识用于标识原项目；软件许可证不授予商标权利。