用Codex四课时开发潮汐App小程序版：AI编程Agent实战教程

AI编程Agent快速构建小程序：项目概述

潮汐App是一款集睡眠、专注、呼吸、冥想于一体的身心健康应用，功能丰富、交互精致。如果从零开始手写一个小程序版本，即便是经验丰富的前端工程师也需要不少时间。但借助OpenAI的Codex编程Agent，整个过程被压缩到了四个课时之内。

OpenAI Codex是OpenAI推出的AI编程代理工具，它基于大语言模型构建，能够理解自然语言描述的需求并自动生成可运行的代码。与传统的代码补全工具（如GitHub Copilot的行级补全）不同，Codex作为Agent具备更强的自主性——它能够读取项目上下文、理解文件结构、规划实现步骤，并在一个沙盒环境中独立完成从架构设计到代码编写的完整流程。Codex的Agent模式意味着它不仅仅是响应单条指令，而是能够持续跟踪任务状态、主动获取信息、处理多步骤的复杂开发任务。

B站UP主WinterMiao通过一个完整的实操演示，展示了如何用Codex配合微信开发者工具，从项目初始化到功能实现，快速完成潮汐App小程序版的开发。这个案例不仅展示了AI编程的效率，也揭示了一些关键的实践技巧。

项目初始化与agents.md配置

创建小程序项目

第一步是在微信开发者工具中创建项目。项目命名为tab-mrp（小程序缩写），选择TypeScript基础模板。演示阶段可以使用测试号AppID，正式上线则需要注册正式的小程序账号。

微信小程序采用独特的双线程架构：逻辑层（AppService）运行JavaScript/TypeScript代码，渲染层（WebView）负责页面展示，两者通过Native层进行通信。小程序使用WXML（类HTML模板语言）、WXSS（类CSS样式语言）和JS/TS进行开发。project.config.json是小程序项目的核心配置文件，定义了AppID、项目设置、编译选项等信息。app.json则是应用级配置，其中pages数组声明了所有页面路径，tabBar配置定义了底部导航栏的结构。这种标准化的项目结构使得AI Agent能够通过读取配置文件快速理解项目的技术栈和组织方式。

关键步骤在于agents.md文件的编写。这个文件本质上是给AI编程Agent的「需求说明书」和「技术规范」。agents.md是Codex项目中的一种约定配置文件，类似于.editorconfig或.cursorrules等开发者工具的配置文件。它的作用是为AI Agent提供项目级别的上下文信息，包括项目定位、技术栈约束、编码规范、功能需求等。AI Agent在开始工作前会优先读取这个文件，将其作为所有后续决策的基础框架。这种机制的设计哲学是：与其让AI从零推断项目意图，不如由开发者显式声明关键约束，从而大幅减少AI的理解偏差。agents.md的质量直接影响AI输出的准确度，它本质上是人机协作中「人」这一端最重要的输入接口。

作者基于之前iOS版本的agents.md进行修改，核心改动包括：

• 删除所有iOS相关的描述（如「确保iOS17+编译通过」）
• 将角色定位改为「你是一名小程序工程师」
• 将产品描述改为「我正在开发一款潮汐类小程序」
• 功能需求保持不变（睡眠、专注、呼吸、冥想四大模块）

agents.md必须放在项目根目录下，这是Codex识别项目规范的入口文件。

导入Codex并启动计划模式

将项目根目录拖入Codex后，告诉它「我更新了agents.md」，Codex会自动读取文件内容。这里有一个重要的操作选择——开启计划模式（Plan Mode）。

计划模式是AI编程Agent中的一种交互策略，对应的是「先规划后执行」的软件工程方法论。在计划模式下，Agent不会立即生成代码，而是先输出一份实现计划——包括文件结构设计、模块划分、实现步骤等——并在存在歧义时主动向用户提问。这种模式借鉴了Chain-of-Thought（思维链）的理念，通过强制Agent进行显式推理来降低错误率。相比之下，直接执行模式虽然速度更快，但在需求复杂或描述不完整时容易产生方向性错误，导致大量返工。计划模式特别适合项目初始化阶段，因为架构层面的错误修复成本远高于实现层面的bug。

计划模式的好处在于：如果需求描述不够周全，Codex会主动提问以获取必要信息，而不是盲目开始编码。这比直接让它动手写代码更稳妥。

说个细节，作者并没有显式告诉Codex技术方案。Codex作为编程Agent，会自动读取项目中的project.config.json等配置文件，从而推断出技术栈和开发规范。

Codex的代码实现过程

自动化的项目架构搭建

Codex开始工作后，自动完成了以下架构搭建：

• AudioManager：音频管理模块
• AudioService：声音处理服务
• Breeze：呼吸相关的帮助类
• 多个页面文件：睡眠、专注、呼吸、冥想

在app.json中，Codex自动将所有页面注册到Pages数组，并配置了TabBar——包含睡眠、专注、呼吸、冥想四个Tab，与原版潮汐App的功能模块完全对应。

AI生成代码的规范性优势

作者特别强调了一个观察：AI写的代码比大多数程序员写的要规范得多。具体体现在：

• 文件命名清晰直观（如AudioManager一看就知道是管理音频的）
• 代码结构层次分明
• 模块职责划分合理

这是因为Codex在训练过程中阅读了大量优质开源项目，其编码水平相当于专家级别。大语言模型的训练数据包含了GitHub上数十亿行代码，其中不乏知名开源项目的最佳实践。模型通过统计学习，内化了命名规范、设计模式、模块化原则等软件工程知识。这使得AI生成的代码天然倾向于遵循社区公认的最佳实践，而非个人开发者可能养成的不良习惯。

作者也指出，如果你觉得AI「笨」，最可能的原因有两个：一是需求描述太含糊，AI无法准确理解意图；二是上下文窗口的限制，就像人一次只能专注有限的事情一样。上下文窗口（Context Window）是大语言模型的核心限制之一，它决定了模型在一次交互中能够「看到」和「记住」的信息总量。当项目代码量超出上下文窗口时，模型可能会遗忘早期的约束条件或产生前后不一致的输出。

调试与小程序特有的注意事项

网络请求域名配置

编译通过后，第一个遇到的问题是「网络加载失败」。这是微信小程序开发中的经典问题——必须在小程序后台配置合法请求域名。

微信小程序出于安全考虑，实施了严格的网络请求管控策略。所有通过wx.request、wx.uploadFile、wx.downloadFile等API发起的网络请求，其目标域名必须事先在微信公众平台的小程序后台进行配置登记。这一机制被称为「合法域名」配置，要求域名必须经过ICP备案、支持HTTPS协议，且不能使用IP地址或localhost。这种设计防止了小程序被用于恶意数据采集或连接未经审核的服务器。对于开发阶段，开发者可以在微信开发者工具中勾选「不校验合法域名」选项来绕过此限制，但正式发布时必须完成域名配置。

具体操作路径：微信开发者工具 → 详情 → 项目配置 → request合法域名，将API的base URL添加进去。如果使用测试号，需要登录对应的测试账号后台进行配置。配置保存后可能还需要清除网络缓存才能生效。

小程序的权限双层限制

作者深入分析了小程序与原生App在权限上的本质差异。小程序的权限受到双层限制：

1. 第一层：操作系统对微信App开放了哪些权限
2. 第二层：微信对小程序开放了哪些权限

小程序的权限模型与原生App有本质区别。原生App直接与操作系统交互，通过系统级API获取权限（如相机、定位、通知等）。而小程序运行在微信的沙盒环境中，形成了「操作系统→微信App→小程序」的三层嵌套结构。第一层限制是操作系统授予微信的权限范围，第二层限制是微信通过其小程序框架API暴露给开发者的能力子集。例如，即使操作系统允许微信设置系统闹钟，微信也未必将这一能力开放给小程序。此外，小程序还受到后台运行时间限制（通常5分钟后被挂起）、内存限制、包体积限制（单包2MB，总包20MB）等约束。这些限制决定了某些原生App功能在小程序中需要寻找替代方案或降级处理。

这意味着像系统闹钟这样的功能，小程序可能无法直接调用。潮汐App中的定时提醒功能，在小程序中只能在前台运行时生效。经过实测，当小程序保持在前台时，闹钟提醒功能正常工作。

Codex使用的实用技巧

在使用过程中，作者分享了几个提升效率的技巧：

• 引导功能（Nudge）：Codex工作时可以随时打断它，比如发送「帮我快速完成」来加速进度，它会减少检查环节优先保证交付
• 插件系统：Codex提供了iOS、Frontend等插件，开发小程序时可以勾选Frontend Scale插件，因为小程序本质上也是用JS/TS编写的前端应用
• 自动检查：Codex会自动进行基础的语法检查和编译检查，即使agents.md中没有明确要求
• 关闭热重载：Codex修改文件时会触发微信开发者工具的热重载，影响测试。可以在设备设置中关闭自动热重载，改为手动刷新

热重载（Hot Reload）是现代开发工具的常见功能，它能在代码文件发生变化时自动重新编译并刷新应用界面，帮助开发者即时看到修改效果。但当AI Agent在短时间内连续修改多个文件时，频繁的热重载反而会造成干扰——每次文件保存都触发一次重载，可能导致应用处于中间状态或频繁闪烁，影响开发者对最终效果的判断。

最终效果验证

经过Codex的自动化开发，四个核心功能模块全部实现：

• 睡眠模块：支持设置醒来时间、倒计时、闹钟提醒（前台有效）
• 专注模块：播放专注音效，支持后台播放
• 呼吸模块：呼吸引导练习，节奏控制正常
• 冥想模块：快速入眠等冥想引导功能

所有功能在微信开发者工具的模拟器中测试通过。Tab图标等细节问题可以后续让Codex补充完善，只需一句「帮我给每个tab添加图标」即可。

总结与启示

这个案例展示了AI编程Agent在实际项目中的强大能力。从一个agents.md文件出发，Codex自动完成了项目架构设计、代码编写、页面注册、功能实现等全流程工作。开发者的角色从「写代码的人」转变为「需求定义者和质量把关者」。

这种转变反映了软件开发行业正在经历的范式迁移：从「手工编码」到「AI辅助编码」再到「AI自主编码，人类监督」。开发者的核心竞争力正在从编码能力转向系统设计能力、需求分析能力和质量判断能力。理解业务逻辑、把控技术方向、识别AI输出中的潜在问题，这些高层次的工程能力变得比具体的语法知识更加重要。

核心经验可以归纳为：

• agents.md的质量决定了AI输出的质量，写好需求说明书是第一要务
• 计划模式比直接执行更可靠，让AI先理解再动手
• 了解平台限制仍然不可替代，比如小程序的权限双层限制需要开发者自行判断
• 善用引导、插件等辅助功能可以显著提升AI编程效率

核心要点