一、需求拆解:先问对问题 这个项目的原始需求只有一句话: 「AI 帮别人搭建一个简易的工作台」。 一句需求做产品,最怕的是想当然。
真正动手前,先把它翻译成 6 个必须问客户的问题:
| # | 问题 | 为什么问 | 常见答案 → 方案 |
|---|---|---|---|
| 1 | 每天要完成哪 3 个动作? | 决定模块数量 | 「看任务 / 记想法 / 开网站」→ 待办 + 便签 + 链接 |
| 2 | 数据能上云吗? | 决定要不要后端 | 「我自己电脑用」→ 纯前端 + localStorage |
| 3 | 会换电脑吗? | 决定要不要同步 | 「会」→ 必须做导出导入 |
| 4 | 电脑装了 Node / Python 吗? | 决定交付形态 | 「没装」→ 双击 HTML |
| 5 | 要对接 OA / 钉钉吗? | 决定集成成本 | 「没有」→ 先独立版 |
| 6 | 预算和交付时间? | 决定边界 | 单页 + 文档 + 截图 |
二、技术选型:为什么放弃框架 我先把候选方案摆到一张表里对比:
| 方案 | 客户上手成本 | 开发者成本 | 结论 |
|---|---|---|---|
| 纯前端 HTML + 原生 JS + localStorage | 双击即用 | 低 | ✅ 采用 |
| Streamlit | 需装 Python + pip | 低 | 备选 |
| React + Vite | 需装 Node + 构建 | 中 | 不适合非技术客户 |
| Notion 模板 | 需账号、需联网 | 极低 | 无法交付源码,不能售卖 |
选择依据只有一条:客户的第一次使用必须在 1 分钟内成功。任何需要「先装环境」的方案,都会在交付当天产生售后。 具体到代码层面,有两个「反直觉但正确」的决定: 1. 不用 ES Module。因为 import/export 在 file:// 协议下会被浏览器拦截,必须用普通 <script> 顺序引入才能保证双击可用。 2. 不用任何第三方库,不联网也能跑。
三、三层架构:
谁该碰什么 项目只有四个文件,职责严格分离:
midlle/ ├── index.html 结构:四大卡片 + 数据面板 ├── assets/ │ ├── style.css 样式:CSS 变量双主题 + 响应式 │ ├── store.js 数据层:唯一碰 localStorage 的文件 │ └── app.js 交互层:唯一碰 DOM 的文件
分层的黄金法则:
只有 store.js 碰 localStorage,只有 app.js 碰 DOM。这样将来把 localStorage 换成 IndexedDB 或云端 API,只改一个文件。
数据模型 存储键 workbench.state.v1,一个带版本号的 JSON:
json { "version": 1, "profile": { "name": "王工", "theme": "light" }, "todos": [ { "id": "lqw3k2a1", "title": "整理本周需求清单", "priority": "high", "done": false, "createdAt": 1763000000000 } ], "notes": [], "links": [], "focus": { "minutes": 25, "sessions": 3, "seconds": 4500 } } ``` ### 数据流(一次点击发生了什么) ``` 用户点击「添加」 ↓ app.js: onTodoSubmit() 读输入 → 调 Store.update() ↓ store.js: 克隆当前 state → 执行 mutator → normalizeState 规整 ↓ 写入 localStorage(120ms 防抖) ↓ notify() → 所有订阅者收到新 state ↓ app.js: renderAll(state) → 概览 / 待办 / 便签 / 链接 / 专注 全部重绘
四、五大核心实现
4.1 单一数据源 + 事件委托
这是从 TodoMVC 借鉴的核心思想,但真正值钱的是两个点:
① 单一数据源:所有列表从同一份 todos 派生,改数据 → 重渲染,绝不做局部 DOM 拼接。 ② 事件委托:只在列表容器上挂一个 click 监听,通过 data-action 分发,而不是给每个条目绑定监听:
javascript function onTodoListClick(event) { var button = event.target.closest('[data-action]'); if (!button) return; var item = button.closest('.todo'); if (!item) return; var id = item.dataset.id; if (button.dataset.action === 'toggle') { Store.update(function (state) { state.todos.forEach(function (todo) { if (todo.id === id) todo.done = !todo.done; }); }); } else if (button.dataset.action === 'remove') { Store.update(function (state) { state.todos = state.todos.filter(function (todo) { return todo.id !== id; }); }); } }
两个直接好处:
-
新增 100 条待办也只挂 1 个监听;
-
列表重渲染后不需要重新绑定事件——这是新手最容易踩的坑。
4.2 数据层规整 normalizeState 导入的备份文件可能被客户手改过,可能是旧版本,甚至是一段乱写的 JSON。所以所有数据在进库前必须过一遍规整函数:
javascript function normalizeState(raw) { var base = defaults(); if (!raw || typeof raw !== 'object') return base; return { version: SCHEMA_VERSION, profile: { name: typeof profile.name === 'string' ? profile.name.trim().slice(0, 20) : '', theme: profile.theme === 'dark' ? 'dark' : 'light' }, todos: Array.isArray(raw.todos) ? raw.todos.map(normalizeTodo).filter(Boolean).slice(0, 500) : [], // ... focus: { minutes: clamp(toInt(focus.minutes, 25), 1, 120), sessions: clamp(toInt(focus.sessions, 0), 0, 100000), seconds: clamp(toInt(focus.seconds, 0), 0, 100000000) } }; }三个关键防护: 1. 类型兜底:
toInt/clamp把非法值拉回合法区间; 2. 白名单:规整后的对象只保留已知字段,多出来的字段被丢弃; 3. 上限截断:待办 500 条、便签 200 条、链接 100 条,防存储爆炸。 配合导入逻辑,损坏数据自动备份:javascript function load() { var raw = readStorage(); if (!raw) return defaults(); try { return normalizeState(JSON.parse(raw)); } catch (e) { try { global.localStorage.setItem(BACKUP_KEY, raw); // 保留原始内容 } catch (ignore) {} return defaults(); } }4.3 防漂移的专注计时器 新手写计时器通常是这样:
javascript setInterval(function () { remaining--; }, 1000); // ❌ 会漂移问题在于:切到别的标签页时浏览器会节流
setInterval,电脑睡眠后更是直接停摆,回来时间就错了。 成熟做法(借鉴 pomofocus 类番茄钟)是记录结束时间戳,每次 tick 反算剩余时间:javascript function startTimer() { // ... timer.endAt = Date.now() + timer.remaining * 1000; // 记录结束时刻 timer.running = true; timer.tickId = setInterval(tick, 250); } function tick() { // 无论 tick 被延迟多久,反算出的剩余时间始终准确 timer.remaining = Math.max(0, Math.round((timer.endAt - Date.now()) / 1000)); paintTimer(); if (timer.remaining <= 0) finishTimer(); }暂停也简单:清掉定时器、保存剩余秒数,下次开始再重新算
endAt。4.4 渲染前的 XSS 转义 本地应用同样需要防 XSS——客户可能往待办里粘贴
<script>,也可能导入来源不明的备份文件。所有用户输入在拼进innerHTML前一律转义:javascript var HTML_ESCAPES = { '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }; function escapeHtml(value) { return String(value).replace(/[&<>"']/g, function (ch) { return HTML_ESCAPES[ch]; }); }渲染时统一套用:
javascript '<span class="todo-title">' + escapeHtml(item.title) + '</span>'这样
<script>alert(1)</script>只会显示成文字,不会执行。4.5 演示参数注入
做演示和截图时,最烦的是每次都要手动点出目标状态。于是我在 URL 上实现了参数注入,一键进入指定状态:
javascript function boot() { Store.init(); var params = new URLSearchParams(window.location.search); if (params.get('demo')) seedDemo(params.get('demo') === 'reset'); applyDemoParams(params); // 注入主题、筛选 // ... if (params.get('panel') === 'data') openModal(); if (params.get('focus') === 'running') { // 自动开始计时 var elapsed = Math.min(timer.total - 30, Math.max(30, Number(params.get('elapsed')) || 420)); timer.remaining = timer.total - elapsed; startTimer(); } } ``` 效果: | 参数 | 效果 | | --- | --- | | `?demo=1` | 注入演示数据 | | `?theme=dark` | 直接深色模式 | | `?filter=active` | 筛选「未完成」 | | `?focus=running&elapsed=420` | 打开即计时中,已走过 7 分钟 | | `?panel=data` | 打开数据面板 |
五、自动化截图:告别手动 演示状态能一键进入,截图自然也能自动化。用 Edge 无头模式批量出图:
powershell $base = (New-Object System.Uri((Resolve-Path 'index.html').Path)).AbsoluteUri $url = $base + '?demo=1&theme=dark'
# 字符串拼接,不能内插
$args = @('--headless','--disable-gpu','--hide-scrollbars', "--user-data-dir=$profileDir",'--window-size=1440,940', '--virtual-time-budget=4000',"--screenshot=$tempShot",$url) Start-Process -FilePath
$edge -ArgumentList $args -Wait -NoNewWindow
六、总结
这个项目最终的价值不在「写了一个工作台」,而在于验证了一条低摩擦交付的路径:
- 需求先行:6 个问题问完,方案基本就定了,省下 80% 返工;
- 选择以客户体验为唯一标准:双击即用 > 技术先进;
- 架构分层的边界要清晰:数据层碰存储、交互层碰 DOM,各司其职;
- 借鉴成熟逻辑而非重复造轮子:单一数据源、时间戳倒计时、归一化规整,都是久经验证的工程实践;
- 把「重复劳动」自动化:演示参数 + 无头截图,让交付物可一键复现。 最后留一个值得思考的问题:如果将来客户要「多端同步」,这套纯前端架构怎么平滑升级?答案是——只改
store.js的存储实现,把persistNow()里的localStorage.setItem换成云端 API 调用,其余代码一行不动。这就是分层带来的复利。
程序完整源代码和文档地址:download.csdn.net/download/wj…