{T}

古诗词 IOS 应用

从零开始开发一款 iOS 古诗词应用。这个 App 允许用户输入关键词，智能生成古诗的详细解析、意境配图以及语音朗读，并支持收藏功能

Xcode

Xcode 是 Apple 官方提供的集成开发环境（IDE），它只能运行在 macOS 系统上

创建新项目

在欢迎界面，点击 "Create New Project" 开始创建第一个项目。

在模版选择页面，确保上方选项卡选中了 iOS，然后在 Application 栏目中选择 "App"。点击 Next 下一步。需要填写项目的基本信息：

  • Product Name: 项目名称
  • Organization Identifier: 组织标识
  • 点击 Next 后，选择一个文件夹来保存你的项目文件

配置模拟器

项目创建成功后，会自动进入代码编辑界面。看左侧的文件列表，点击 ContentView 文件。这时右侧的预览窗口（Canvas）应该会显示一个手机界面，上面写着 "Hello World"

注意 Xcode 顶部工具栏，默认选中的设备可能是 "My Mac"。

这表示如果运行程序，它会作为 Mac 程序运行，而不是 iOS App。需要把它切换成 iPhone

点击 "My Mac"，在下拉菜单中查看 iOS Simulators（iOS 模拟器）。

  • 如果没有选项：说明你还没安装 iOS 系统镜像。点击 "Download iOS..." 或 "Manage Run Destinations"
  • 注意磁盘空间：iOS 模拟器文件通常很大（几个 GB），下载安装过程比较占磁盘空间，请耐心等待

运行应用

配置好设备后，点击左上角的 三角形（Run） 按钮。Xcode 会编译代码，并启动一个独立的 Simulator（模拟器） 应用

  • 模拟器就像一部真正的 iPhone 手机显示在你的桌面上
  • 可以像操作手机一样滑动屏幕、点击图标

在模拟器桌面上找到刚才创建的应用，点击打开。就能在模拟器里看到和预览界面一样的 "Hello World"

预览视图 vs 完整模拟器

Xcode 代码右侧的预览画面，和点击运行按钮弹出的模拟器的区别？

  1. 右侧预览 (Canvas Preview/SwiftUI Previews)
    • 用途：主要用于 写代码时的实时反馈
    • 特点：它是静态或轻量级的交互。当你修改代码（比如改了字体颜色），右侧会立即刷新，看到 UI 变化。它不需要编译整个 App，速度快，适合调布局
  2. 完整模拟器 (Simulator)
    • 用途：用于 全功能测试
    • 特点：点击左上角 Run 按钮时，是启动完整的 iOS 系统。这里可以测试应用的生命周期（启动、后台、关闭）、复杂的网络请求、数据库存储以及 App 之间的跳转

搭建 Coze 工作流

创建工作流 ，弹出 "创建工作流" 的对话框众横输入工作流名称、描述信息,然后点击 "创建" 按钮。

  • 工作流名称: poem_visual_voice_flow
  • 描述信息: 这是一个围绕古诗词的多模态工作流，能够根据用户输入生成对应的诗文、画面意境与语音朗读

古诗词工作流包含以下节点：

  • 开始节点：工作流入口,接收用户输入的主题
  • 大模型节点：根据主题生成古诗词内容,包括标题、作者、正文、描述、图片提示词和朝代
  • 优化图像提示词节点：优化大模型生成的图片提示词,使其更适合图像生成
  • 图像生成节点：根据优化后的图片提示词生成配图
  • 文本处理节点：将古诗词的各个部分(标题、作者、正文等)拼接成完整文本
  • 语音合成节点：将拼接后的文本转换为语音朗读
  • 结束节点: 返回最终结果

开始节点

设置输入参数，注意输入参数必须包含字母、数字或下划线,并且以字母或下划线开头:

  • input: 用户输入的主题或关键词

大模型节点

添加一个大模型节点，用于生成古诗词的完整内容。

  • 模型选择: 选择一个合适的大模型，这里使用豆包大模型 (豆包-1.5-Pro-32k)
  • 输入: 输入需要处理的主题，这里引用的是开始节点的 input 参数
  • 系统提示词：
  • 用户提示词: 这里直接传入 {{input}} 即可
  • 输出: 设置希望大模型返回的变量，包括:
    • title(标题): 古诗的标题
    • author(作者): 作者名称
    • content(正文): 古诗正文,数组类型
    • description(描述): 对古诗的详细描述
    • image_prompt(图片生成提示词): 用于生成配图
    • dynasty(朝代): 古诗所属朝代
  • 输出格式: 开启 "输出格式 JSON" 并定义好格式

系统提示词:

null
你是一位精通中国古典诗词与意象表达的文化助手。

请根据用户输入的内容（可能是一首诗的名字、一位诗人的名字，或一个主题词），找出最相关的一首古诗，并输出结构化信息。

输出字段说明如下：
- title：诗的标题。例如“静夜思”。
- dynasty：诗的朝代。例如 “唐”
- author：诗的作者。例如“李白”。
- content：诗句内容，输出为数组，每个元素为一行或一句诗，便于前端分段渲染。
- description：将诗的白话译文、主题解读、创作背景或典故等内容整合成一段简明连贯的文字，不要分项输出。
- image_prompt：根据诗句意境生成画面描述提示词（用于AI绘图）。要求：
  - 用简洁的中文写，描述整首诗的意境与画面；
  - 不出现诗人名字、文字、书法或诗句；
  - 风格可为“中国水墨画”或“古风插画”，体现自然与情感意象。

输出时只返回 JSON 数据，不要额外文字。

示例输出：
{
  "title": "静夜思",
  "dynasty": "唐",
  "author": "李白",
  "content": [
    "床前明月光，疑是地上霜。",
    "举头望明月，低头思故乡。"
  ],
  "description": "明亮的月光照在床前，好像地上泛起了一层白霜。诗人抬头望着明月，低头思念着家乡。这首诗表达了李白旅居他乡时对故乡的深切思念。",
  "image_prompt": "明月洒在古代卧室的窗前，床榻静谧，窗外夜空澄澈，一位旅人仰望月亮，充满思乡之情，中国水墨画风格"
}

优化图像提示词节点

大模型生成的图像提示词可能不够精确，添加一个 sd_better_prompt 节点（提示词优化节点）：

  • 输入: 引用大模型节点输出的 image_prompt 变量
  • 输出: 优化后的提示词 data

图像生成节点

添加一个图像生成节点，用于生成古诗的配图：

  • 模型: 使用 Seedream 4.0

  • 比例: 3:4 (1728x2304)

  • 输入: 引用优化图像提示词节点输出的 data 变量

  • 提示词: 将输入的优化后的提示词填入正向提示词中。这里设置详细的提示词要求:

null
请根据以下古诗的内容，生成一段用于绘图的提示词，描述画面意境。
要求：
- 突出古诗所表达的意境、自然景象和情感；
- 体现诗中的季节、时间、场景或氛围；
- 使用中文短语，简洁连贯；
- 不出现文字、诗人姓名或诗句；
- 画面风格建议为“中国水墨画”或“古风插画”，唯美而富有意境。

文本处理节点

添加文本处理节点，用于将古诗的各个部分拼接成完整的文本。这个节点会将大模型输出的 title、author、content(数组) 等字段拼接成一段完整的文本，供语音合成节点使用

  • 选择应用: 字符串拼接
  • 输入: 引用大模型节点的多个输出变量:
    • String1 → 大模型 - title
    • String2 → 大模型 - author (可能还需要加上朝代等)
    • String3 → 大模型 - content (数组)
    • String4、String5 等,根据需要添加
  • 字符串拼接: 将这些变量按格式拼接,例如 {{String1}}\n{{String5}}\n{{String2}}\n{{String3}}\n{{String4}}
  • 输出: 拼接后的完整文本 output

语音合成节点

添加语音合成节点（语音合成），用于将古诗文本转换为语音：

  • 输入: 引用文本处理节点输出的 output 变量
  • voice_id: 选择合适的音色,这里使用"温柔淑女
  • speed_ratio: 语速比例,设置为 0.9
  • 输出: 语音数据 data、日志ID log_id、消息 msg、状态码 code

结束节点

结束节点是工作流的出口，这里返回以下信息:

  • title: 大模型节点的 title
  • author: 大模型节点的 author
  • content: 大模型节点的 content(数组)
  • image: 图像生成节点的 data(图片URL)
  • audio: 语音合成节点的 data(音频数据)
  • dynasty: 大模型节点的 dynasty
  • description: 大模型节点的 description

测试与发布

按照逻辑将各节点连接起来,形成完整的工作流,如下所示:

  1. 开始节点 → 大模型节点
  2. 大模型节点 → 优化图像提示词节点 (分支1)
  3. 大模型节点 → 文本处理节点 (分支2)
  4. 优化图像提示词节点 → 图像生成节点
  5. 文本处理节点 → 语音合成节点
  6. 图像生成节点 → 结束节点
  7. 语音合成节点 → 结束节点
  8. 大模型节点 → 结束节点 (提供文本信息)

发布工作流：

  1. 点击右上角的 "发布" 按钮
  2. 设置版本号和描述信息
  3. 点击发布即可

要准备 API 调用信息,以便在应用中调用古诗词 API。需要准备以下信息：

  • 工作流 ID：7602144658996002835
  • API 密钥
  • API 接口地址

UI 原型设计

利用 HTML 代码来构建 iOS 应用的原型图，并将其上传至 Figma

生成原型代码

在前端代码的生成与还原能力上，Google 最新推出的 Gemini 3 Pro 模型表现得更为惊艳：

null
我要做一个 IOS App，内容是用户输入古诗信息之后点击按钮生成古诗详情，生成的古诗详情信息有：古诗图片、音频、作者、朝代、古诗词句、解释信息等。用户可以选择对生成的古诗进行收藏，之后可以从列表查看收藏的古诗，并且可以删除或查看已收藏的古诗。
你是一名经验丰富的产品设计专家，擅长UI构图与前端页面还原。现在请你帮我完成这个古诗词应用的 UI/UX 原型图设计。请输出一个包含所有设计页面的完整HTML文件，用于展示完整UI界面。
古诗的详细信息如以下 JSON 所示
{
  "audio": {
    "duration": 11.376,
    "link": "https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/VolcanoUserVoice/speech_7468518753626505253_723e6798-3441-4ef7-81a7-0ae3f33be99d.mp3?lk3s=da27ec82&x-expires=1770278185&x-signature=re%2BSOS%2FEd8diulIb6ZhU%2Fa%2B3g8s%3D"
  },
  "author": "李白",
  "content": "[\"床前明月光，疑是地上霜。\",\"举头望明月，低头思故乡。\"]",
  "description": "明亮月光洒在床前，诗人起初以为是地上结霜。他抬头望向明月，不禁低头陷入对故乡的思念。此诗创作于李白客居他乡之时，真切表达出他的思乡之情。",
  "dynasty": "唐",
  "image": "https://s.coze.cn/t/6GuwOb3-hk4/",
  "title": "静夜思"
}

通常 AI 会生成一个交互式的 App，需要点击才能跳转。但作为 UI 设计稿，需要一眼看到所有页面的布局。因此明确要求 AI “将所有页面在单个 HTML 文件中平铺展示”

将 HTML 设计稿导入 Figma

设计稿生成后，需要将其转移到专业的 UI 设计工具 Figma 中。这里推荐使用 html.to.design 插件

  • 费用说明：该插件免费版每月提供 10 次导入机会，对于个人项目来说完全够用
  • 插件安装：关于插件的具体安装步骤，可以回顾 MCP 实战章节中的 Figma 部分

1. 创建 Figma 项目

登录 Figma 并创建一个新的设计文件（Design file）

2. 启动插件

在 Figma 的画布区域，调出插件搜索框，找到并运行 html.to.design 插件

3. 上传 HTML 文件

在插件界面中，切换到 File（文件）选项卡。点击上传或拖拽刚才用 Gemini 生成的 HTML 文件

4. 最终效果确认

导入完成后，会看到网页上的设计被完美还原到 Figma 的画布上，并且所有的图层、文字和样式都是可编辑的

这种“AI 生成代码 -> 导入 Figma”的方式，相比传统的从零绘制，还原度极高且效率提升显著，这是目前我推荐的一种原型设计方案

项目实现

进入 SOLO 界面，Trae 提供两种核心智能体：

  • SOLO Coder：面向复杂项目开发的智能体。它擅长处理需求迭代、架构重构等全流程工作。通过智能任务规划，它能自主拆解任务并执行（选择这个）
  • SOLO Builder：专为构建 Web 应用设计。它能从零开始，根据自然语言生成 PRD、编写代码，并支持集成 Supabase 数据库和 Vercel 一键部署

阶段一：开启 Plan 模式与需求拆解

为了让 AI 更好地理解上下文，开启 Plan 模式。在这个模式下，AI 不会急于写代码，而是先生成一份执行计划供确认：

null
做一个古诗词 IOS App，输入古诗信息后，点击生成古诗详解按钮，会调用 Coze 的 API 接口获取生成古诗的详细数据。

Coze API 返回的信息如下：

古诗的详细信息如以下 JSON 所示
{
  "audio": {
    "duration": 11.376,
    "link": "https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/VolcanoUserVoice/speech_7468518753626505253_723e6798-3441-4ef7-81a7-0ae3f33be99d.mp3?lk3s=da27ec82&x-expires=1770278185&x-signature=re%2BSOS%2FEd8diulIb6ZhU%2Fa%2B3g8s%3D"
  },
  "author": "李白",
  "content": "[\"床前明月光，疑是地上霜。\",\"举头望明月，低头思故乡。\"]",
  "description": "明亮月光洒在床前，诗人起初以为是地上结霜。他抬头望向明月，不禁低头陷入对故乡的思念。此诗创作于李白客居他乡之时，真切表达出他的思乡之情。",
  "dynasty": "唐",
  "image": "https://s.coze.cn/t/6GuwOb3-hk4/",
  "title": "静夜思"
}

用户可以选择对生成的古诗进行收藏，之后可以从列表查看收藏的古诗，并且可以删除或查看已收藏的古诗。

App 还需要提供一设置页面，用户可以在此配置 Coze API 的 Token 信息，避免将 Token 硬编码在项目中。

图中是我们的设计稿内容，设计稿是在 Figma 上。这一块我打算分为两步完成，第一步先根据 Figma 上的设计稿完成 App 前端页面开发。第二步是调用 Coze API 完成接口对接，第二张图是 Coze API 的接口请求信息。

同时提供了 UI 设计稿截图和 Coze API 截图。

发出需求后，AI 迅速生成了一份开发计划

markdown
# 古诗雅集 (Poetic Zen) iOS App 开发计划

我们将分为两个主要阶段完成此项目：**前端页面开发** 和 **Coze API 接口对接**。

## 第一阶段：前端页面开发
在此阶段，我们将根据 Figma 设计稿构建 App 的 UI 结构和基础逻辑。

### 1. 数据模型与状态管理
- **定义 Poem 模型**：包含标题、作者、朝代、内容、描述、音频信息、图片 URL 等字段，并支持 Codable 以便处理 JSON。
- **持久化存储**：使用 `SwiftData` (推荐 iOS 17+) 或 `UserDefaults` 存储用户收藏的古诗列表以及 Coze API Token。
- **创建 ViewModel**：管理全局状态，如收藏列表、API 配置信息以及生成古诗的加载状态。

### 2. 构建核心页面
- **MainTabView**：设置 App 的主导航框架，包含“首页”和“我的收藏”两个主要标签。
- **HomeView (首页)**：
  - 设计“寻章摘句”输入区域，使用 `TextEditor` 供用户输入关键词。
  - 实现“生成古诗详解”按钮及其点击逻辑。
  - 实现“推荐赏析”列表展示。
  - 在导航栏添加“设置”按钮，跳转至配置页面。
- **PoemDetailView (详情页)**：
  - 顶部展示古诗意境图。
  - 中间卡片展示标题、作者、播放按钮（带时长显示）及诗词正文。
  - 下方卡片展示“诗意赏析”描述。
  - 底部提供“返回”和“收藏/取消收藏”按钮。
- **CollectionView (收藏页)**：
  - 展示已收藏古诗的列表。
  - 每个列表项包含缩略图、标题、作者及删除按钮。
  - 点击列表项可跳转至详情页查看。
- **SettingsView (设置页)**：
  - 提供文本框供用户输入并保存 Coze API Token，确保信息安全。

## 第二阶段：Coze API 接口对接
在此阶段，我们将实现与后端的通信。

### 1. API 服务层开发
- **封装 CozeAPIService**：
  - 使用 `URLSession` 实现异步请求。
  - 配置请求头（Authorization, Content-Type）。
  - 处理 Coze 工作流的请求参数（workflow_id, input）。
  - 解析返回的复杂 JSON 数据并映射到 `Poem` 模型。

### 2. 交互逻辑完善
- **生成逻辑对接**：点击“生成古诗详解”时，调用 API 服务，显示加载动画（ProgressView），请求成功后自动跳转至详情页。
- **错误处理**：处理网络异常、Token 无效或 API 调用限制等情况，并向用户提供友好提示。

## 技术要点
- **SwiftUI**：用于构建声明式 UI。
- **SwiftData**：用于本地数据持久化（收藏夹和配置）。
- **Combine/Async-Await**：处理异步 API 调用。
- **Markdown**：处理古诗内容的格式化展示（如 JSON 中的数组转行）。

您是否同意此开发计划？如果同意，我将开始第一步：创建数据模型和基础 UI 结构。

阶段二：Figma 深度集成

Trae SOLO 模式对 Figma 的支持非常流畅

  1. 在对话框中点击 Figma 图标，首次使用完成登录
  2. Trae 会直接加载你的设计稿文件
  3. 选择需要开发的页面 Frame，点击右上角的 “添加到对话”

从左下角的截图可以看到，Trae 自动截取了页面预览并解析了元素信息。只需要补充一句简单的指令：“根据 Figma 的 UI 设计稿完成页面开发”

提交后，因为依然处于 Plan 模式，AI 重新调整设计稿的实现方案。确认无误后，点击执行，AI 便开始自动编写代码

阶段三：产物验证与 iOS 模拟器调试

等待片刻，第一阶段执行完成。点击产物汇总中的 “查看变更”，Trae 会弹出一个清晰的 Diff 视图，展示本次修改涉及的文件和具体代码行数。

与 Web 应用可以直接在右侧浏览器预览不同，iOS 开发需要依赖 Xcode 编译环境

  1. 点击左上角的运行按钮
  2. 启动 iOS 模拟器

模拟器成功启动，页面还原度非常高，基本复刻了 Figma 的设计

阶段四：优化预览体验

点击左侧的代码文件时，IDE 右侧并没有出现实时的预览区域。虽然模拟器能看到最终效果，但无法在编码时通过“所见即所得”的方式快速微调

code
在 Xcode 中部分页面怎么没有预览区域？帮我解决这个问题

AI 迅速定位到了问题核心：SwiftUI 的代码中缺少 #Preview 宏定义，导致 Canvas 无法渲染。它立刻给出了修复方案，为相关视图自动补全 Preview 代码

修复完成后，再次点击任意 SwiftUI 文件，右侧终于出现了熟悉的实时预览窗口。现在可以一边看代码，一边实时查看 UI 变化，开发体验得到了补全

阶段五：逻辑对接与 Coze API 开发

页面 UI 开发验证无误后，继续向 Trae SOLO 发出指令，要求开发 Coze API 的对接逻辑

code
完成 第二阶段：Coze API 接口对接

AI 自动完成网络请求层的编写，需要在应用中配置 API Token。打开模拟器的设置页面，填入 Workflow ID 和 Token 信息

配置完成后，回到首页尝试输入内容并点击“生成详解”按钮。

在模拟器界面上无法看到详细的错误堆栈，但 Xcode 的控制台（Console）会输出详细的运行日志。如果发现控制台没有输出关键信息，可以明确要求 AI 在代码的关键路径上添加日志打印，以便于排查

阶段六：灵活切换——IDE 模式辅助修复

分享 Trae 的实用技巧：不必死磕 SOLO 模式，随时可以切换到 IDE 模式（如果要是查看代码，还是这个界面更舒服）

我直接将 Xcode 控制台中的错误日志复制下来，扔给 Chat 模式下的 AI，让它根据日志修复代码