为了口醋，我包了顿饺子——从零构建 Mureka Client

最近换赛道，尝试走独立音乐人的路，有些上头。目前在深度使用Mureka AI音乐平台进行创作，准备充值成为会员，长期使用。对比了下它的套餐，基础会员一年要398/年，有点小贵，发现它有个API Platform套餐一年才200元，这个太划算了，就是有点小门槛，需要自己动手编程，做个客户端调用它的API。有了方向，开干。

下面记录了使用 Claude Code AI 辅助开发 Mureka Client 桌面应用的完整过程——从需求分析、架构设计、实施计划、编码实现、到踩坑排查的全流程。技术栈为 Tauri 2.0 + React + TypeScript + TailwindCSS，后端 Rust，我之前完全没有接触过。

第一阶段：需求分析与架构设计

项目从一个简单的想法开始：为独立音乐人构建一款 Mureka API 专业客户端。核心工作流覆盖从歌词编写到分轨导出的全链路。

在写代码之前，调用Skill Brainstorm（如果你要做开发，这个技能很重要，一定要装，我之后会频繁用到）,叫AI 辅助完成了两份关键文档：

图 1：9 阶段实施计划总览

图 2：应用三层架构

计划中包含了一个重要的「Review 修正」环节——初始方案中有些设计不够合理，在 review 阶段被纠正：

• API Key 原计划用 Zustand persist 存储，修正为使用 tauri-plugin-store 加密存储
• 项目数据原计划用 Zustand persist，修正为 SQLite 持久化
• 音频播放原计划直接使用 HTMLAudioElement，修正为通过 Rust 后端下载再本地播放
• useAutoSave 需要使用 ref 稳定回调，避免 debounce 失效
• API 模型标识符修正为实际的 auto/mureka-8/mureka-7.6 等

第二阶段：快速实施

有了详尽的实施计划，编码阶段进展极快。以下是 Git 提交记录还原的真实时间线：

从空项目到功能完整：仅用约 2 小时，完成了 Phase 1 到 Phase 8 的全部代码实现。这得益于详尽的实施计划——每个文件的完整代码模板都已预先写好，AI 只需按计划逐阶段执行。

第三阶段：调试与优化

核心功能实现后，进入了「让应用真正可用」的调试阶段。这个阶段持续了整个晚上，遇到了多个非显而易见的问题：

坑一：代码改了但应用没有任何变化

最初修改了 App.tsx 的默认路由，将首页从「歌词」改为「音乐库」，但运行 npm run tauri dev 后，应用始终显示歌词页面。

修复：在 tauri.conf.json 的 build 段添加：

"build": {
  "devUrl": "http://localhost:1420",
  ...
}

坑二：侧边栏图标全部消失

初始版本使用 emoji 作为导航图标：📝、🎵、🎛️ 等。在 macOS 上显示正常，但在 Linux 上，Tauri 的 webkit2gtk webview 不渲染 emoji，导致整个侧边栏看起来是空的。

修复：将所有 emoji 替换为内联 SVG 图标，并加宽侧边栏、添加文字标签：

// Before: emoji
{ path: '/lyrics', label: '歌词', icon: '📝' }
// After: inline SVG
{
  path: '/lyrics',
  label: '歌词',
  icon: (
    <svg viewBox="0 0 24 24" fill="none"
         stroke="currentColor" strokeWidth="2">
      <path d="M14 2H6a2 2 0 0 0-2 2v16..." />
    </svg>
  ),
}

坑三：SQLite 操作静默失败

点击「创建项目」按钮后没有任何反馈——不成功也不报错。排查后发现，Tauri 2.0 的安全模型要求在 capabilities/default.json 中显式声明每个插件的权限。初始配置只写了 "sql:default"，但这并不包含 execute 和 select 权限。

修复：在 capabilities 中列出具体权限：

"permissions": [
  "core:default",
  "sql:allow-load",
  "sql:allow-execute",
  "sql:allow-select",
  "store:default",
  "http:default"
]

同时在 handleCreate 中添加 try/catch 和可见的 UI 错误提示：

try {
  await addProject(newTitle.trim());
} catch (e) {
  setError('创建失败: ' + String(e));
}

坑四：删除 dist 目录导致编译失败

为了清理缓存执行了 rm -rf dist，结果 Rust 编译报错：

error: proc macro panicked
= help: The `frontendDist` configuration is set to "../dist"
        but this path doesn't exist

原因是 tauri::generate_context!() 宏在编译时读取 dist/ 目录，必须存在。

最终确立的开发规范

经过以上踩坑，我们基于 Harness Engineering 原则建立了 7 条强制规则，写入 CLAUDE.md 文件：

Tauri tauri.conf.json 必须配置 devUrl

其他改进

• 音乐库优先：将侧边栏「音乐库」调整到第一位，作为应用首页；按钮文案简化为「+ 新建」
• 歌词术语中文化：Verse(主歌)、Chorus(副歌)、Pre-Chorus(预副歌)、Bridge(桥段)、Intro(前奏)、Outro(尾奏)
• 模型更新：生成控制台新增 Mureka 9 模型选项
• README 重写：从模板文字改为完整的项目文档
• 文档清理：移除一次性脚本（md2pdf.py）和冗余 PDF

技术栈总结

总结

回顾整个开发过程，AI 辅助开发展现了三个鲜明的阶段：

阶段一：规划（设计规格书 + 实施计划）

AI 在规划阶段表现出色。它能快速分析 API 文档、理解需求、设计架构，并输出包含完整代码模板的 9 阶段实施计划。更重要的是，Review 环节纠正了多个初始设计缺陷（加密存储、SQLite 持久化、音频播放方案），避免了后期的架构返工。

阶段二：实施（约 2 小时完成全部功能）

有了详细的实施计划，编码阶段几乎是在「填模板」。从空项目到功能完整只用了 2 小时，9 个 Phase 的代码一次性通过编译。这个速度得益于规划阶段对每个文件级别的精确描述。

阶段三：调试（耗时超过实施阶段本身）

真正花时间的是让应用「真正能用」。AI 生成的代码缺少对 Tauri 框架隐式约束的理解：

1. 环境差异：AI 默认的代码假设（如 emoji 兼容性）在不同平台表现不同
2. 框架陷阱：Tauri 2.0 的安全模型、权限系统和构建流程有许多隐式约束
3. 反馈缺失：异步操作的静默失败会让调试变得极其困难

关键经验是：将踩过的坑固化为可执行的规则。通过 Harness Engineering 的方式，把每个问题的根因和防范措施写入 CLAUDE.md，确保后续开发不会重蹈覆辙。

不是记住错误，而是让错误不可能再次发生。