当 AI 编码助手遇上非遗文化：我的「非遗月饼文化馆」开发手记

作者：Eddygit　|　项目：mooncake-heritage-tool
技术关键词：CodeArts ACP 智能编码助手 · 纯前端单文件应用 · Canvas 2D · 古风国潮 UI

一、技术路线：为什么选「单文件纯前端」

这个项目的诉求很朴素——做一个能让人直观感受月饼非遗文化的小工具，但它承载着三重约束：

1. 零部署成本：作品要能直接双击 index.html 在浏览器打开，观众不需要装环境、跑服务；
2. 零依赖：不引 CDN、不引框架，保证离线可用、加载秒开；
3. 强表现力：古风国潮的视觉质感 + 交互趣味（问答、制饼），不能因为"简单"而失去设计感。

基于这三点，我选择了单文件 HTML + 内嵌 CSS/JS + Canvas 2D 的路线。这是纯前端作品里最"轻"的形态，也是最能检验编码助手对设计细节理解力的场景——没有框架帮你兜底，每个像素、每段交互逻辑都得自己写对。

项目结构

mooncake-heritage-tool/
├── index.html   # 全部样式、脚本、内容内嵌的单文件应用（约 43KB）
└── README.md    # 使用说明

二、技术心得：AI 一起写代码的正确打开方式

这次开发全程使用华为云 CodeArts ACP 智能编码助手，我有三点比较深的体会：

1. 把需求讲成"验收标准"，而不是"功能清单"

给 AI 的 prompt 里，我刻意写了这样的句子：

“五大流派（广式/苏式/京式/滇式/潮式）介绍卡片 + 特色标签”
“传统制作工艺时间轴（备料→制馅→包制→压模→烘烤→晾晒）”
“制作一枚虚拟月饼（选馅料/饼皮/模具 → 生成你的专属月饼卡，用 Canvas 绘制）”

对比"做个月饼网站"，后者是功能清单，前者是验收标准——每一个括号都是可检查的交付物。AI 拿到这样的描述，生成结果可以直接对照验收，返工率大幅下降。

2. 审查代码比让 AI 重写更高效

生成完成后我没有让 AI 反复"美化"，而是先检查三个关键点：

• JS 语法：node --check 通过；
• 数据完整性：10 道问答题目、onclick 事件引用是否齐全；
• 标签闭合：HTML 结构完整。

确认骨架正确后，再做局部微调。分段审查 + 局部修改，比"不满意就重来"省钱得多。

3. 工具链的"最后一公里"往往是人的事

CodeArts 生成代码后自动启动了本地 HTTP 预览，我能立刻看到成品效果。这里有个小插曲：生成过程中助手直接用 bash 写 43KB 大文件时触发过一次 JSON 解析错误，但它很快切换为分片写入（_p1.html → 合并）并完成。AI 工具的容错与自愈能力，在实际生产中比单次成功率更重要。

三、实战经验：从 0 到发布的全链路

完整链路是：需求 → CodeArts 生成 → 本地预览验收 → git 仓库 → 推送 GitCode → 发布到开发者作品展览馆。几个实战坑：

坑 1：沙箱文件系统视图

CodeArts 在 bwrap 沙箱内工作，宿主机直接看项目目录可能是空的。但 HTTP 服务返回 200 且 43KB 文件完整——判断作品是否生成，要以服务可访问性为准，而不是凭目录列表。最终我通过 curl 拉取确认了文件内容。

坑 2：GitCode 仓库 URL 格式

创建仓库用 API POST /user/repos 返回的 full_name 是 Eddygit/mooncake-heritage-tool，但 push 时 URL 若写成 https://gitcode.com/user/Eddygit/... 会 403。正确格式是 https://gitcode.com/<owner>/<repo>.git（owner 是登录名，不带 /user/ 前缀）。

坑 3：发布平台的隧道降级

发布到展览馆需要在线预览地址（envUrl），本机服务经 DevBridge 隧道暴露。由于隧道域名升级公告（9月20日21点切换），旧隧道连接偶发失败。发布 skill 设计了完善的降级出口：隧道失败 → envUrl="" 照常发布，作品仍可提交，只是没有在线访问地址。这提醒我们：做工具设计时，要把"可选能力失败"和"核心流程失败"分开处理。

四、存在问题与优化空间

当前已知问题

1. 无后端、无持久化：问答分数、制饼卡片导出都只在浏览器内存/本地完成，换设备即失；
2. 内容为静态数据：流派介绍、题目都硬编码在 HTML 里，更新内容需要改代码；
3. Canvas 导出受字体影响：卡片上的中文字体依赖本地系统字体栈，不同设备渲染略有差异；
4. 无障碍体验一般：交互元素缺少完整的 ARIA 标注，屏幕阅读器支持不完善。

优化空间（按优先级）

构想的进阶形态

如果后续要产品化，可以演进为：

• 图片分享裂变：制饼卡片导出更精美的分享图（带二维码/水印），引导传播；
• 方言语音：为各流派加入方言朗读的文化彩蛋；
• AR 互动：摄像头识别真实月饼，叠加流派知识标签——从"看"到"玩"再到"扫"。

五、写在最后

非遗文化的传承，需要年轻人愿意"打开看、动手玩"。AI 编码助手把开发成本降到了一个下午能完成的量级，这本身就是文化传播的基础设施升级。

希望这个小工具，能让更多人在中秋月圆时，不仅吃到月饼，也读懂月饼背后六百年的匠心。

📌 本项目代码托管于 gitcode.com/Eddygit/mooncake-heritage-tool，欢迎 Star 与交流。