Personal Workbench

Ship a personal daily workbench the user opens in any browser. No build step, no backend — data lives in localStorage, with a built-in 导出/导入 JSON escape hatch so users never lose everything. Every module follows the same shape (记录 → 执行 → 统计 → 反馈); only the fields differ.

Two template files, one shared CONFIG shape:

• 桌面版 scripts/workbench-desktop.html — 左侧栏导航、多列宽屏布局。
• 移动版 scripts/workbench-mobile.html — 抽屉 + 底部 Tab 栏 + 浮动按钮，单列手机布局，适配安全区。

Which file(s) to ship is decided by §1 形态路由 — not always both. When full mode is active, both read/write the same storageKey (workbench-v1 by default), so on one device + one browser they show the same data automatically.

> [!IMPORTANT]
> 交付时务必用大白话说明存储模型，别堆术语。 像跟朋友讲一样：
> - "默认情况下，东西都存在你自己这台设备的这个浏览器里。换台电脑、换个浏览器、或者清了浏览记录，之前填的就没了。"
> - "好在左下角 / 抽屉底部有『导出备份』，点一下能存成一个 JSON 文件；以后用『导入恢复』就能找回。建议定期导一份。"
> - "如果你想要手机和电脑实时同步同一份数据，现在可以了：点『同步』连一个轻量后端就行（见 §8）。不连的话就是纯本机，跟以前一样。"
>
> 默认仍是单机本地存储；多端同步是可选增强（需自托管一个零依赖后端），未配置时前端完全不联网，行为与旧版一致。

> [!TIP]
> 30 秒上手（TL;DR）：① 复制 reference/config-template.js 整段 → ② 替换模板 <script> 顶部的 CONFIG → ③ 双击打开 scripts/workbench-desktop.html（电脑）或 workbench-mobile.html（手机）→ 搞定。新手只需改 3 处：owner（标题）、modules（要哪些功能）、tabbar（仅手机底部 Tab）。完整字段见 §3。

蓝图 · Blueprint

> 积木哲学：先有蓝图，再选积木。 本 skill 把"个人工作台"拆成若干独立、可替换的模块，按请求形态组装交付；扩展能力放 reference/，按需取用，不污染主操作手册。

工作台由下面 6 块核心积木拼成：

扩展积木（高级，见 reference/）：自定义字段 · 图标系统 · 卡片布局 · 图片槽位 · Hero 图。

组合顺序：接请求 → 跑 §1 定形态 → 按形态在对应文件操作（§2 交付 / §3 配置 / §4 模块 / §5 换肤）。所有改动遵守"下游穿透"规则（§1.4）。

1. 形态路由（Form Router）

Before any other workflow, decide which form (产物形态) the user wants. This determines which template file(s) to create and which file(s) every subsequent workflow (delivery, re-skin, add-module, add-layout, add-icon) operates on.

1.1 三种形态

1.2 信号识别

判定维度只有一个：用户在什么设备上用。

1.3 仲裁规则

full 信号 → full
app 信号（手机能看 / 手机上用 / 移动端） → app
desktop 信号（电脑 / 桌面 / 浏览器） → desktop
都没有 → desktop（默认）

优先级：full > app > desktop > 默认 desktop。

关键规则：只要用户提到"手机上用 / 手机能看"，无论后面跟的是"网页"还是"app"，都判 app。用户的约束是使用场景（在手机上看），不是技术形态。

1.4 下游穿透

形态判定结果穿透所有工作流，决定操作哪个文件：

1.5 形态判定与状态持久化

靠目录文件存在性判断，不在 CONFIG 里加 form 字段：

目录里只有 workbench-desktop.html  → 当前形态 = desktop
目录里只有 workbench-mobile.html   → 当前形态 = app
两个文件都在                        → 当前形态 = full

• 用户说"换个莫兰迪配色"时，Agent 扫一眼目录就知道改哪个文件，不需要用户重复说形态。
• 用户想从 desktop 升级到 full（"给我也加个手机版"）→ 补出 mobile 文件，形态自动变为 full。
• 用户想从 full 降为 app（"删掉桌面版"）→ 删 desktop 文件，形态降为 app。

1.6 双端数据共享（已默认打通）

两个模板都默认 storageKey: "workbench-v1"，所以 full 模式同浏览器自动共享数据，开箱即用，Agent 不必再手动对齐 key。

• 想强制清空重来 → 把两端 storageKey 改成新值（如 workbench-v2），或让用户用「导入恢复」覆盖。
• 想让桌面版和手机版各自独立 → 给两个文件设不同的 storageKey。

2. 快速开始（Quick Start）

1. 确定形态 — 跑 §1 形态路由，只把对应文件复制到目标位置。
2. （可选）生成 Hero 图 — 若当前环境支持图像生成工具（如 WorkBuddy 的 ImageGen），可为首页"晚上好"区生成一张真实 hero 图；否则不必强求——模板已内置 CSS 渐变占位，没有照片也能正常、好看地显示。Prompt 模板与规则见 reference/hero-image.md。
3. （可选自定义）若想用生成图替换默认的 CSS 渐变 hero 背景，把图存到 assets/greet-banner.jpg（或改 :root 的 --greet-image 指向新文件）。默认无需任何图片。
4. 编辑 <script> 顶部的 CONFIG 对象。在 full 模式下两端 CONFIG 必须一致，桌面与移动才能同步；desktop / app 模式只编辑单文件。新手只需改这 3 个字段就能跑起来：owner（标题）、modules（要哪些模块）、tabbar（手机底部 Tab）；其余保持默认即可（完整字段见 §3，最小可抄脚手架见 reference/config-template.js）。
5. 在对应设备打开文件，提醒用户定期点「导出备份」。

3. CONFIG 配置块

最小可用 CONFIG（新手直接照抄，只改标题 / 模块即可）

> ⚠ 铁律：模块的身份证是 key（唯一字符串），不是 seed 里的 id；id 只在每条记录的 seed 内部用。tabbar 引用的是模块的 key，不是 id。

const CONFIG = {
  owner: "我的工作台",              // 侧栏/抽屉顶部标题（注意：直接写 owner，不要套 profile）
  slogan: "每日工作台",             // 副标题
  storageKey: "workbench-v1",       // 双端共享桶名；改它=重置/隔离
  modules: [
    { key:"todo", type:"todo", icon:"list", name:"今日待办", desc:"每天的小目标", seed:[] },
    { key:"note", type:"note", icon:"pen",  name:"随手记",   desc:"灵感与日记",   seed:[] }
  ],
  tabbar: ["todo", "note"]          // 仅手机版：底部 Tab，引用模块的 key（不是 id）
};

> 上面 modules 只放 2 个示例模块；full 模式两端务必用同一份 CONFIG。完整可抄脚手架见 reference/config-template.js（带中文注释）。

字段说明

• owner / slogan — 侧栏/抽屉顶部显示的标题与副标题（直接写顶层字段，不要写成 profile:{owner,slogan}，模板不读 profile）。
• storageKey — localStorage 桶名。双端默认都是 workbench-v1，即同浏览器自动共享；改它可强制重置或隔离两端（见 §1.6）。
• quotes — 每日一句数组（7 句，按周一→周日轮换），可整段替换。
• overview — 首页概览环数组（含 key/label/icon/color 与 calc(d) 函数），key 对应某模块 key。
• trend — { title, unit, series: d => number[] }，读取用户填写的 __trend（7 个数字）画趋势。
• quickAdd — 首页快速记录按钮数组（{label,icon,module,tint,color}），点了直接给对应模块新建。
• modules — 有序模块列表；每个含 key(主键,唯一字符串) / type / name / icon(ICONS key 或 emoji) / tint(卡片底色) / color / desc / 类型专属字段(priorities/categories/moods/unit) / seed(记录数组，记录内用 id)。
• tabbar (mobile only) — 底部 Tab 栏展示的约 5 个模块 key（不是 seed 的 id）。

场景预设（选一个，照着填 modules / tabbar）

我想加功能，该怎么「叫」出来？（需求话术 → 配置）

不用记字段名，照下面开口提需求即可；积木会翻译成对应配置：

> 这些词（打卡 / 记账 / 灵感记录…）同时也是本 skill 的触发词——你在对话里提到它们，积木就会调出这个工作台。

4. 模块类型（Module Types）

Every module is one type; pick per need and add as many as you want. 类型名以代码为准——配置 CONFIG 时务必用下面这五个名字：

• dashboard（内置，非 CONFIG 模块） — 首页由 renderHome() 自动生成（问候 + 进度环 + 模块网格 + 快速记录），不在 modules 数组里声明，且保持唯一，不要手写一个 type:"dashboard" 的模块。
• todo — 每日计划: checkable tasks with priority; seed items are { text, level: high|mid|low, done }.
• checkin — 习惯打卡: tap-to-complete cards with 连续天数 streak; auto-clears each new day (streak kept). Seed items { name, emoji, done, streak }.
• progress — 长期计划 / 阅读进度: progress bars with a +1 button. Seed items { name, emoji, current, target, unit, note }.
• finance — 记账本: income/expense entries with categories, monthly totals and a 支出构成 bar chart. Seed items { kind: income|expense, cat, amount, note, date }.
• note — 内容记录 / 日记: free-text cards with optional tags / 心情. Seed items { title, body, tag, date }.

> [!WARNING]
> 早期文档曾把类型写成 ledger / goal / notes。现已统一为 finance / progress / note。引擎 renderModule() 仅对 todo/checkin/progress/finance/note 有渲染分支；若误用旧名（如 type:"ledger"），统计头会为空、记录渲染退化，"加出来的模块不能用"。务必用代码里的名字。

加模块：在 modules 追加一条支持的 type 与其 seed。要复用为别的场景（护肤打卡、阅读进度、情绪日记），选最接近的 type 并重命名 name/icon/字段——补品/护肤/运动 → checkin，阅读/学习 → progress，记账 → finance，日记/摘录/灵感 → note。只操作 §1 形态路由决定的文件：desktop 只改 desktop，app 只改 mobile，full 两端都改。

自定义字段 / 图片槽位：模块的 fields 自定义字段与五类图片位置机制见 reference/custom-fields.md / reference/image-slots.md。

5. 主题与换肤（Theme）

All visual style lives in CSS variables under :root at the top of <style>. Zero hardcoded colors in component CSS — every color, radius, shadow, and background image references a token, so editing :root alone re-skins the entire app without touching component code.

5.1 Token 体系与色板约束（→ reference/theme-tokens.md）

完整 token 表、选 token 规则、换肤色板 WCAG 约束见 reference/theme-tokens.md。要点：

• Token 按角色命名（--surface-card / --accent / --module-1..5 / --drawer-* 等），组件层只用 var() 引用，换肤零改组件代码或 JS。
• 想整组替换，直接套 reference/presets.md 的墨色中性 / 莫兰迪暖粉 / 冷色科技预设。

5.2 换肤工作流（Agent 执行）

When the user describes a style in natural language (e.g. "换成莫兰迪粉系" / "make it dark mode" / "换成冷色科技感"), execute this pipeline:

1. 解析意图 — 从用户描述提取 3 个维度：色温（暖/冷/中性）、明度（浅/深）、饱和度（低/中/高）。若用户提到具体颜色名，以此为准。
2. 生成 token — 按 reference/theme-tokens.md 的 Token 体系与 WCAG 约束，生成一整套 :root 变量值。所有颜色必须满足 WCAG AA 对比度（文本≥4.5:1，大字≥3:1）。--on-accent 必须与 --accent 对比度≥4.5:1。抽屉色板必须与主色板协调。
3. 应用到 HTML — 只替换 :root 块内的值，不碰组件 CSS、不碰 JS、不碰 CONFIG。组件层全部用 var() 引用，无需改动。
4. 校验 — 改完后用浏览器打开，检查：主色上的文字可读、抽屉文字可读、日历已打卡格颜色与模块色一致、图表数据色不撞色、暗色背景下的文本对比度达标。
5. 同步两端 — 按 §1 形态路由决定的作用范围操作：desktop 只改 desktop，app 只改 mobile，full 两端都改且保持一致。

6. 双端差异（Desktop vs Mobile）

• Desktop — persistent sidebar; each module fills a wide area (grids up to 3–4 columns); modals are centered dialogs. 左下角「导出备份 / 导入恢复」位于侧栏底部。
• Mobile — drawer opens from the ☰ button; a bottom tab bar switches the main modules; a floating + button creates records; modals are bottom sheets. Layout is single-column and respects the phone's safe areas. 「导出备份 / 导入恢复」位于抽屉底部。

> 何时该用哪端（辅助 §1 形态路由判断）：在电脑浏览器里长时间停留、需要宽屏多列看板整理 → 选 desktop；主要在手机上随手记、打卡、看进度 → 选 app；既要电脑深度整理又要手机随时记 → 选 full（两端默认共享同一份数据）。

7. 扩展机制（Extensions → reference/）

高级扩展都不改 JS 渲染逻辑，只需在 CONFIG / :root / <style> 声明，详见对应参考文件。

7.1 自定义字段 → reference/custom-fields.md

在模块里用 fields 数组声明自定义字段，自动渲染为表单控件与卡片 .meta-tag。支持 text / textarea / number / select 四种类型；key 小写驼峰且不与内置字段冲突。

7.2 图标系统 → reference/icons.md

26 个内置 Lucide 图标；概念未被覆盖时按 Lucide 官方规范新增 ICONS 条目并引用（key 小写、单字、语义化）。

7.3 卡片布局变体 → reference/layout-variants.md

layout 字段控制卡片样式（default / feature / quote），可在 <style> 加 .rec.rec-layout-xxx 无限扩展。硬约束：颜色用 var()、圆角用 --radius-*、字号限 12–18px，且不影响其他卡片。

7.4 图片槽位 → reference/image-slots.md

首页 hero / 页面纹理 / 模块封面 / 记录缩略图 / 用户头像 五类图片位置及其对应 CSS token 或 CONFIG 字段。

7.5 Hero 图 → reference/hero-image.md

可选增强：图像生成 Prompt 模板与色温/构图规则；环境不支持时直接跳过，CSS 占位照常好看。

8. 同步能力（Sync · 可选增强）

默认单机本地存储；本技能额外提供真正多端同步：用户自托管一个轻量后端，手机 / 电脑 / 平板填「后端地址 + 令牌」即可实时共享同一份数据。未配置时前端完全不联网，向后兼容。

8.1 它是什么

• 在 store.save() 之外挂了一层 sync 引擎：每次本地改动防抖 1 秒自动 PUT 推送；打开页面时静默 GET 拉取一次最新数据。
• 后端按 token 隔离成独立"保险箱"——同 token 多设备共享，不同 token 彼此隔离。
• 配置（后端地址 / 令牌 / 缓存 rev）存在独立的 storageKey + "::sync" 里，不污染业务数据；业务数据仍走原 storageKey。

8.2 交付 / 启用流程（前端侧 3 步）

> 后端怎么搭、怎么部署、协议与安全细节 → 一律看 reference/sync.md（顶部有「3 分钟自建同步」总览 + 决策树）。本节只讲前端连接，不复述后端细节。

1. 前端点「同步」按钮（侧栏底部 / 抽屉底部）→ 填后端地址与令牌（同一令牌即共享数据；可选填访问口令，仅当后端开启了 SYNC_PASSWORD）。
2. 点「保存并同步」——设备立刻与云端做一次"拉取 + 推送"，之后本地改动自动（防抖 1 秒）推送。
3. 徽标显示状态：未启用同步 / 已连接 / 同步中… / 已同步 / 同步失败 · <原因> · <重试/待推送>。失败会自动重试（5s→15s→60s，最多 5 次），离线改动进「待推送队列」并显示计数，恢复联网自动补推，无需手动点重试。

8.3 冲突模型（字段 / 记录级 3 路合并）

前端在每次成功同步后缓存"云端快照"为 base；拉取时按 base→local→remote 三方比对、逐模块逐记录（按 id）合并：双方各自新增都保留、仅一端改动取那端、同一记录被两端同时改动则保留本机并把云端版另存为 __conflict 标记记录，互不冲突的并发离线改动全部无损合并。详见 reference/sync.md §4。强调：同步不替代「导出备份」（§1 IMPORTANT）。

8.4 Agent 操作约束

• 同步是用户自助功能；Agent 交付工作台时只需确保模板已含「同步」按钮与 sync 引擎（当前模板已内置），不要替用户硬编码后端地址 / 令牌。
• 若用户要求"帮我接同步"，交付后端运行说明（reference/sync.md）即可，后端由用户自己跑——Agent 不替用户持有令牌或公网暴露服务。
• 改模板时，store.save() 必须保持 this.saveLocal(); sync.schedulePush(); 的不变量；新增写入路径若绕过 store.save()（如头像、番茄钟的直接 store.save()），属本地缓存写，无需触发推送（拉取时会以云端为准校正）。

> 后端协议、CORS / file:// 说明、HTTPS 部署、令牌生成、数据安全与局限 → reference/sync.md。
> 想零配置直接体验多端同步？见 examples/README.md——已预填本地后端连接的演示页（examples/sync-demo.html）+ 一键启动脚本。

参考索引（References）

• reference/presets.md — 预设色板（墨色中性 / 莫兰迪暖粉 / 冷色科技）
• reference/theme-tokens.md — 主题 Token 体系与换肤色板 WCAG 约束
• reference/custom-fields.md — 自定义字段 fields 数组与字段类型表
• reference/icons.md — 图标系统与扩展（Lucide 配方）
• reference/layout-variants.md — 卡片布局变体
• reference/image-slots.md — 图片槽位与背景图 token
• reference/hero-image.md — Hero 图生成（Prompt 模板）
• reference/sync.md — 多端同步：总览决策树、后端协议、自托管、部署与安全（SHA-256 哈希 / 可选口令 / 限流锁定 / 字段级 3 路合并）
• examples/README.md — 同步演示页：一键启动后端 + 已预填连接，零配置体验多端同步
• reference/faq.md — 常见问题（数据去哪 / 类型名 / 同步失败 / 配置错自查 / 双端不同步 / 自定义）
• reference/config-template.js — 最小可用 CONFIG 脚手架（带中文注释，复制改标题即可跑）

Changelog

• 2026-08-10 重组（积木哲学）：① 修正原 ## 3.1 / 3.2 串号（3.1 实为卡片布局、3.2 才是图标系统）；② 统一编号 §0–§5 → §1–§6，子节顺序归正（3.0.1/3.0.2 顺移为扩展参考）；③ 新增「蓝图」总览，体现"先蓝图后积木"；④ 将 Hero 图、自定义字段、图片槽位、卡片布局、图标系统、预设色板 6 类参考性内容外置到 reference/；⑤ 所有交叉引用同步更新。
• 2026-08-11 新增多端同步能力（§8）：① scripts/sync-backend/ 零依赖同步后端（server.mjs Node / server.py Python），GET/PUT /data?token= + /health，按 token 隔离、rev 单调递增、CORS 放行、JSON 落盘；② 桌面 / 移动双模板注入 sync 引擎（store.save 自动防抖推送、启动静默拉取）、「同步」按钮 + 状态徽标 + 设置面板；③ 未配置后端时完全退化为本地存储，向后兼容；④ 新增 reference/sync.md 协议与自托管指南；⑤ 更新顶部存储声明与参考索引。
• 2026-08-11 新增同步演示页（降低上手门槛）：examples/sync-demo.html（单文件零依赖、预填 url=http://127.0.0.1:8787/token=demo 的精简工作台，sync 引擎与桌面模板同源）、examples/start-demo.mjs（跨平台一键启动后端并打开演示页，替换原被 skillhub 拒绝的 .bat/.sh）、examples/README.md（三步上手）；并在 reference/sync.md §8 与 SKILL.md §8 / 参考索引增加指向。
• 2026-08-14 精简 SKILL.md + 外置主题参考：① 将 §5.1 Token 体系大表与 §5.3 换肤色板 WCAG 约束外置到 reference/theme-tokens.md（与 presets/custom-fields 等参考文件风格统一），SKILL.md §5 仅保留 §5.2 换肤工作流与一句式指针，体量显著降低；② 同步更新 §5.2 步骤 2 的交叉引用与参考索引；③ source 与 dist 包同步。
• 2026-08-14 落地完善建议（P1–P3 全量）：① 前端同步引擎（desktop / mobile / demo 三套模板同构改造）新增失败原因分类 + 指数退避自动重试（5s→15s→60s，最多 5 次）+ 待推送队列计数，并显式冲突覆盖预警、设置面板加可选访问口令字段与「何时用哪端」提示；② 后端 server.mjs / server.py 加固：SHA-256 令牌哈希落盘（明文 token 不落盘、旧键自动迁移）、可选访问口令 SYNC_PASSWORD、限流 + 失败锁定（每 60s 120 次 / 连错 5 次锁 60s），已冒烟实测（读写/401/403/429 全通过）；③ reference/sync.md 顶部加「3 分钟自建同步」总览 + 决策树、§4 补错误码与前端失败处理、§5 补三层安全加固；④ 后端 README.md 同步；⑤ SKILL.md §8.2 收敛为"前端 3 步 + 指向 sync.md 总入口"，§3 加最小可用 CONFIG 与场景预设，§6 加路由引导；⑥ source 与 dist 包同步。
• 2026-08-14 同步冲突模型升级为字段级 3 路合并（替代整包 Last-Write-Wins）：① 前端（desktop / mobile / demo 三套同源引擎）新增 jsonEq / mergeRecords / threeWayMerge，pull 改为按 base（云端快照）→local→remote 三方比对、逐模块逐记录（按 id）合并——双方新增都保留、单方改取单方、同记录双改保留本机并把云端版另存为 __conflict 标记记录（绝不静默丢数据）；② 每次成功同步后把云端快照存 base（SYNC_KEY），schedulePush 改为走 now()（先拉后推）提升收敛，push 加"相对云端无变化则跳过上传"优化；③ newItem 加 updatedAt；④ 设置面板冲突说明、SKILL §8.3、sync.md §4/§6、后端 README 冲突模型与局限措辞统一更新；⑤ sync.md §5.1 + README §4.1 增补"5 分钟套 HTTPS"实战（Caddy 自动证书 / Nginx+Certbot / Cloudflare Tunnel 三方案）；⑥ 合并算法已用 9 组场景单测验证（双方新增 / 单方改 / 同记录双改 / 删改冲突 / 首次并集等全过）；⑦ source 与 dist 包同步。
• 2026-08-15 用户体验完善（P0–P2 全量落地）：① 修正 §3 最小 CONFIG（profile→owner、id→key，补全 quotes/overview/trend/quickAdd/tint 字段说明）并加「需求话术→配置」对照表与顶部 TL;DR 30 秒路径；② 新增 reference/faq.md（用户视角 FAQ）与 reference/config-template.js（可抄脚手架）；③ 桌面/手机双模板加 validateConfig()：配置写错→顶部红条、未知模块类型→黄色警告而非空白；④ 生成页加「?常见问题」入口 + 首次打开引导条（数据存本机提醒）+ 首页功能引导卡；⑤ 高级动作归组（桌面 ⋮ 菜单、手机抽屉分区）；⑥ 自助换肤（三套预设循环切换）+ 配置自检面板；⑦ source 与 dist 包同步。