## 摘要
基于两份 Word 文档，我用 `#WorkBuddy#`AI 工作台生成了一个减脂增肌打卡台（单文件 HTML + 资料库云同步 + 在线链接 + 多设备实时同步），并迭代到 V0.0.0.4。最大收获：AI 生成的云同步代码藏着一个"漏写 return"的致命 bug，导致每刷新一次就新建一条记录；靠直连数据库取真实返回结构、用 Node 模拟复现才定位根因——印证了"AI 给的方案必须先验证再上线"。

---

## 一、任务背景与目标

上个月我让 AI 帮我做一个减脂打卡的小工具：单文件 HTML、能云端同步、手机电脑都能看。AI 很给力，半小时出了第一版，界面漂亮、逻辑通顺，我美滋滋地发了在线链接。

三天后用户找我："为什么我换个手机打开，里面啥都没填过？" 再查后端数据库，更离谱——同一张表里躺着 4 条一模一样的空记录，而且**每刷新一次页面就多一条**。

这篇文章不是来炫耀 AI 有多能干的，而是来复盘：当 AI 把"看起来写对了的代码"交给你时，哪些坑是它永远不会主动告诉你的；以及我用哪四道工序，把第一版变成能稳定上线的版本。

回到起点，最开始的诉求其实朴素：用户手里有两份文档——`核对表.docx`（展示/计划参考素材）和`打卡表.docx`（每日打卡字段），希望我"生成一个工作台"，里面要有展示页、打卡界面、热力图，并且**美观优雅**。

聊了几轮后，目标逐步收敛、也被用户主动加码，最终的成功标准可以拆成五条：

1. **展示与打卡分离**：展示页（计划参考/封面）单页呈现；打卡界面按「体重 / 饮食 / 锻炼 / 睡眠」四类做每日打卡。
2. **多周期视图**：今日打卡、打卡详情（可查任意一天）、热力图（完成度 + 体重趋势）。
3. **云端同步 + 在线链接 + 多设备实时同步**：这是用户后来明确要求的，也是本文主线。
4. **移动端可用**：手机打开要有完整导航，不能只剩"今日"一屏。
5. **版本可控**：用 Git 管理，每个有意义的改动打一个版本号。

> ![图1 原始文档到最终界面] (https://developer.qcloudimg.com/http-save/yehe-12704060/dabc6db8bed078dcdf108fad4c16fcfb.png)


---

## 二、方案选型

摆在面前其实有三条路，我按"代价/收益"做了取舍：

| 方案 | 做法 | 优点 | 代价 | 结论 |
|------|------|------|------|------|
| A 纯本地 | 单文件 HTML + `localStorage` | 零依赖、断网可用、双击即开 | 无法跨设备；换手机数据全丢 | 作为降级方案保留 |
| B 单文件 + 资料库云同步 | 同一份 HTML，绑定资料库数据库做读写，发布为在线链接 | 多设备实时同步、无需自建后端、发布即用 | 依赖平台 SDK 注入；需处理同步收敛 | **选用** |
| C 独立后端 | 自己起 FastAPI + SQLite + 前端 | 完全可控、可扩展 | 要服务器、要部署、要鉴权，单人小工具过度设计 | 否决 |

**为什么选 B 而不是 C**：用户要的是"多设备查看 + 实时同步"，不是"高并发 SaaS"。自建后端把 90% 的精力花在了运维上，而 B 方案借力平台已有的资料库/在线链接能力，把代码收敛成"一个 JSON 对象的读写"，性价比最高。代价是必须吃透平台 SDK 的真实契约——这正是后面踩坑的根源。

---

## 三、实战过程

整体是一条"先跑通、再打磨、最后修同步"的线。

**步骤 1：解析原始文档。** `editor_sdk` 打不开 `.docx`，改用 Python 直接解析 docx 的 XML 拿到字段结构，确认了打卡表的字段（体重、饮食、锻炼、睡眠等）。

**步骤 2：产出单文件 HTML。** 整个应用就是一个内联了 CSS/JS/SVG 的 `.html`，数据模型核心是：

```js
// 每日打卡记录的数据形状（gather() 序列化后整体存云端）
var rec = {
  wakeW: 74.2, eveW: 73.8,                 // 晨起/晚间体重
  diet: { breakfast:'ok', lunch:'ok', dinner:null,
          water:true, snack:false, alcohol:false },  // 饮食 6 项
  exercise: { noon:{done:true,kcal:320}, eve:{done:true,kcal:280} },
  sleep: { nap:{...}, night:{ toBed:'23:00', wake:'07:10',
               hours:8.17, bedOk:true, wakeOk:true } },
  note: ''
};
```

**步骤 3：连接资料库 + 发布在线链接。** 加载「资料库」技能，运行模式判定为 `client`，通过 WorkBuddy 开放平台令牌（基于当前 IDE 登录会话）鉴权；把最新 HTML 重导入并绑定数据库 `WbC4ugEF3LVn9JiXkiLbUF`，发布为公开链接 `https://workbuddy.link/p/Xfj3MDQqfnB1TnEUvzxNgR`。

**步骤 4：移动端导航修复。** 用户反馈手机打开只有"今日"一屏——原因见第四章。补了底部标签栏后重新发布。

**步骤 5：云同步收敛修复。** 用户反映"每换设备封面都是全新的"，再到"每刷新一次后台新建一条记录"——这是全文最核心的坑，单独在第四章展开。


>![图2 桌面端四导航界面](https://developer.qcloudimg.com/http-save/yehe-12704060/64776ec2145956516aa1bf640013980b.png)


**步骤 6：Git 版本管理。** 新建文件夹、初始化仓库，按里程碑提交：`9f38899`(V0.0.0.1 初始版本) → `6d2671f`(V0.0.0.2 优化身体表) → `e169ff1`(V0.0.0.3 修复手机端导航) → `dc73d57`(V0.0.0.4 修复云同步)。

---

## 四、踩坑与原理剖析

### 坑 1：睡眠时间相等却被算成 24 小时

**① 现象**：用户记录「入睡 2026-08-12 15:01、睡醒 2026-08-12 15:01」，界面输出睡眠时长 24 小时。

**② 根因**：`computeSleep` 里判断跨天的条件是 `if(diff<=0) diff+=24;`。当入睡与睡醒时间**相等**时 `diff===0`，被 `<=0` 命中，错误地加上了 24。本质是把"时间相等"和"跨天"两种语义混为一谈。

**③ 解决**：把阈值收紧为真正跨天才补 24：

```js
// 修复前：相等时间误判为跨天 → 输出 24h
if (diff <= 0) diff += 24;
// 修复后：仅当真正跨天（入睡晚于睡醒）才加 24
if (diff < 0) diff += 24;
```

**④ 验证**：代入相等时间用例，`diff=0` 不再进入补 24 分支，输出 0 小时；代入 23:00→07:00，`diff=-8` 补 24 得 16 小时（按业务口径即 8 小时），符合预期。

### 坑 2：手机端导航整体消失

**① 现象**：桌面端有左侧「今日/计划参考/打卡详情/热力图」导航，但手机打开只剩"今日打卡"一屏，其余三个入口完全看不到。

**② 根因**：响应式 CSS 里写了 `@media(max-width:860px){.sidebar{display:none;}}`——手机端把整个侧边栏 `display:none` 了，却**没有补一个移动端替代导航**。侧边栏一隐藏，四个页面的切换入口就全没了。说人话：你把门拆了，但忘了在墙上另外开一扇。

**③ 解决**：新增固定在底部的标签栏 `.mob-nav`（仅 ≤860px 显示，含 4 个带图标+文字的按钮），并扩展导航 JS 选择器为 `.nav button,.mob-nav button`，让桌面/移动端 active 状态同步；同时把主内容区底部内边距加大、设置按钮上移，避免被底部栏遮挡。

**④ 验证**：JS 语法 `node --check` 通过；重新导入发布后，用户在手机端刷新即可见底部四标签。

> ![图3 手机端修复前后对比](https://developer.qcloudimg.com/http-save/yehe-12704060/308c30e2738201f8894f19093ec9a4cf.png)

### 坑 3（核心）：云同步每刷新一次就新建一条记录

**① 现象**：用户先反映"换设备封面都是全新的"，后来更具体地报"每刷新一次页面，后台都会新建一条新记录，根本没有更新同一条"。我用工具直连数据库 `WbC4ugEF3LVn9JiXkiLbUF` 查，第一次看到 3 条、后来变成 4 条，且槽位全是 `main`、内容都是默认空数据。

**② 根因（讲到原理层）**：同步层 `cloudLoad` 加载已有记录时用了一段 `filter`：

```js
// 修复前（致命）：回调是花括号块体，却漏写了 return
var rows = cloudRows(res).filter(function(r){
  (r['槽位'] || '') === 'main';   // ← 这条判断结果没有返回！
});
```

箭头函数省略 `return` 和**普通函数块体省略 `return`** 是两码事。这里是普通 `function` 块体，里面只有一条表达式语句、没有 `return`,于是回调函数**永远返回 `undefined`**。而 `Array.filter` 把 `undefined` 当作 falsy,导致 `rows` **永远为空**。连锁反应：`cloudLoad` 永远认为"没有记录" → `cloudRecId` 永远取不到 → 每次 `cloudSave` 都走 `addRecord` 新建分支 → 每刷新/保存一次就多一条。

> 这里有个值得记下的小插曲：我**第一版误诊**为"记录 id 字段名写错（`_id` 应为 `record_id`）"。但直连数据库 dump 出真实返回结构 `{record_id, 槽位:"main", 数据:"<json>"}` 后，发现字段名其实对得上。**真正的敌人是漏写的 `return`**。这恰好说明：凭"感觉"猜根因会翻车，必须拿"地面真相"对账。

**③ 解决**：三道防线一起上——
- 修掉 `filter` 的 `return`（直接病因），并抽一个兼容字符串/`{text:...}` 两种形态的 `cloudSlotOf` 兜底；
- 把 `cloudSave` 改成**幂等 upsert**：已知 id 就 `updateRecord` 同一条；未知 id 时先 `query` 已有 `main` 记录，有则更新、多余的删除、无才新建，绝不再盲目 `addRecord`；

```js
function cloudSave(){
  var db = window.__SMART_PAGE__ && window.__SMART_PAGE__.database;
  if (!db) return;
  var payload = JSON.stringify(gather());
  if (cloudRecId) {
    // 已知主记录 → 直接更新同一条（顺手写回槽位，防止字段被清）
    db.updateRecord({databaseId:DATABASE_ID, recordId:cloudRecId,
      properties:{'数据':{text:payload}, '槽位':{text:'main'}}}).catch(function(e){console.warn('[cloud] save',e);});
  } else {
    // 未知 id → 幂等 upsert：先查再决定更新还是新建
    db.query({databaseId:DATABASE_ID, pageSize:50}).then(function(res){
      var rows = cloudRows(res).filter(function(r){ return cloudSlotOf(r) === 'main'; });
      if (rows.length) {
        cloudRecId = cloudRecIdOf(rows[0]);
        return db.updateRecord({databaseId:DATABASE_ID, recordId:cloudRecId,
          properties:{'数据':{text:payload}, '槽位':{text:'main'}}});
      }
      return db.addRecord({databaseId:DATABASE_ID,
        properties:{'槽位':{text:'main'}, '数据':{text:payload}}}).then(function(r){ cloudRecId = cloudRecIdOf(r); });
    }).catch(function(e){console.warn('[cloud] upsert',e);});
  }
}
```

- `bootstrap` 增加"本地优先"保护：本地已填数据比云端更完整时不覆盖，且只在本地有真实数据时才上传，杜绝推空数据制造重复。

**④ 验证**：
- JS 语法 `node --check` 通过；
- 用 Node 模拟真实返回结构（含字符串形态与 `{text}` 形态混合）跑一遍：新逻辑正确命中 3 条 `main` 记录并取到 id/数据；旧逻辑（缺 `return`）命中数为 **0**——直接证明那就是 bug；
- 用工具清理掉累积的重复记录，库内收敛为唯一 1 条（`Ana2NMhxGRKwq3UgqT7JQi`，含真实数据）；
- 换新鲜令牌重查，`record_count = 1`，多次刷新/保存后不再增长。

> ![图4 数据库记录增长vs收敛](https://developer.qcloudimg.com/http-save/yehe-12704060/d3bda096ccdcf38097f5802cc5be2cda.png)

---

## 五、最终效果

- **版本与提交**：Git 仓库共 4 个里程碑，`9f38899`→`6d2671f`→`e169ff1`→`dc73d57`，对应 tag `V0.0.0.1`~`V0.0.0.4`，工作区干净。
- **云端收敛数据**：数据库 `WbC4ugEF3LVn9JiXkiLbUF` 经工具复查，**稳定为 1 条**主记录（修复前曾累积到 4 条），多次刷新/保存不再新增。
- **多端可用**：公开链接 `https://workbuddy.link/p/Xfj3MDQqfnB1TnEUvzxNgR` 已含全部修复；桌面四导航、手机底部四标签均正常；任意设备打卡后，其他设备刷新即可见。
- **降级兜底**：本机双击 HTML 走 `localStorage`，断网也能用。

> ![图5 工具复查与手机端导航](https://developer.qcloudimg.com/http-save/yehe-12704060/88235b52a7a4abf8d5af23ee48fbfc64.png)

---

## 六、经验总结：如何更好地使用 AI 工具实现自己的目标和需求

这套活儿绝大部分代码是 AI 生成的，但"能跑"和"跑对"之间隔着的，恰恰是几个需要人把关的动作。落到可复用的方法论，我提炼 4 条：

1. **让 AI 先拿"地面真相"再改代码，而不是凭描述猜。** 这次云同步的坑，我第一版按"字段名不对"去改，直到直连数据库 dump 出真实返回结构（`record_id`/`槽位`/`数据` 都是扁平字段）才发现自己猜错了。以后凡是涉及"外部 SDK/接口契约"，先让 AI 用工具把真实响应打出来对账，再动手——比让 AI 脑补 API 形状可靠十倍。

2. **把"可复现的验证"设为 AI 交付的强制环节。** 我没有只靠"看起来改对了"，而是用 Node 把真实数据结构喂进去跑了一遍 filter 逻辑，旧逻辑命中 0 条、新逻辑命中 3 条，bug 当场坐实。建议你给 AI 提需求时直接加一句"改完用最小用例模拟验证逻辑"，它会主动补验证，而不是交一份没测过的代码。

3. **对 AI 的"第一诊断"保留怀疑，用事实回填。** AI 很会编一套自洽的解释，但自洽 ≠ 正确。这次误诊被真实数据推翻就是例子。做法是：AI 给根因时，要求它"给出验证这一步的具体命令/用例"，能当场证伪的，就别信。

4. **关键逻辑要做"幂等"和"降级"设计，别把正确性寄托在 happy path。** `cloudSave` 从"无脑 addRecord"改成"幂等 upsert"，本质是把"第一次就要走对"的脆弱假设，换成"走错也能自愈"。让 AI 写任何"写数据"的代码时，明确要求"考虑重复执行/并发/失败重试"的场景，它会主动加幂等和保护，少很多线上诡异 bug。

一句话收口：**AI 负责把想法快速落成第一版，人负责用"取真实数据 + 跑最小验证 + 怀疑第一诊断 + 要求幂等降级"这四道工序把第一版变成能上线的版本。** 工具越强，验证这道关越不能省。

---

## 配图清单汇总表

| 图号 | 所在章节 | 内容说明 | 制作方式 |
|------|----------|----------|----------|
| 图1 | 一、任务背景与目标 | 原始两份 docx 缩略图 + 最终四导航界面草图对比 | 文档截图 + 界面录屏拼图 |
| 图2 | 三、实战过程（步骤 2） | 桌面端四导航界面截图，标注单文件 HTML 结构 | 浏览器截图 |
| 图3 | 四、坑 2（手机端导航消失） | 用户提供的手机端无导航截图 vs 修复后底部标签栏 | 微信截图 + 修复后录屏 |
| 图4 | 四、坑 3（云同步重复记录） | 数据库记录随刷新增长示意 vs 收敛为 1 条对比 | 查询输出截图 + 示意图 |
| 图5 | 五、最终效果 | 工具查询输出（record_count=1）+ 手机端底部导航正常 | 命令行截图 + 手机录屏 |


基于两份 Word 文档，我用 #WorkBuddy#AI 工作台生成了一个减脂增肌打卡台（单文件 HTML + 资料库云同步 + 在线链接 + 多设备实时同步），并迭代到 V0.0.0.4。最大收获：AI 生成的云同步代码藏着一个"漏写 return"的致命 bug，导致每刷新一次就新建一条记录；靠直连数据库取真实返回结构、用 Node 模拟复现才定位根因——印证了"AI 给的方案必须先验证再上线"。

#WorkBuddy# AI 工作台写的云同步，为什么每刷新一次就新建一条记录？——一次真实踩坑全记录

基于两份 Word 文档，我用 `#WorkBuddy#`AI 工作台生成了一个减脂增肌打卡台（单文件 HTML + 资料库云同步 + 在线链接 + 多设备实时同步），并迭代到 V0.0.0.4。最大收获：AI 生成的云同步代码藏着一个"漏写 return"的致命 bug，导致每刷新一次就新建一条记录；靠直连数据库取真实返回结构、用 Node 模拟复现才定位根因——印证了"AI 给的方案必须先验证

编程语言

数据库

开发工具

基于AI生成的减脂打卡工具开发实践，复盘云同步功能"漏写return"致命bug的定位过程，提炼出"先验证真实数据结构、用最小用例模拟复现、保留对AI诊断的怀疑、设计幂等降级机制"四道验收工序，为AI辅助开发提供可复用的质量保障方法论。

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

#WorkBuddy# AI 工作台写的云同步，为什么每刷新一次就新建一条记录？——一次真实踩坑全记录-腾讯云开发者社区-腾讯云

#WorkBuddy# AI 工作台写的云同步，为什么每刷新一次就新建一条记录？——一次真实踩坑全记录

#WorkBuddy# AI 工作台写的云同步，为什么每刷新一次就新建一条记录？——一次真实踩坑全记录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐