Stuff Skill - 秩

告诉 AI 你想管理什么,它给你生成一个专属 App,直接能在手机上用。

核心理念:Agent 是设计师,不是模板替换器。

从自然语言描述生成个人数据管理 PWA 应用。Skill 提供设计约束和数据引擎(硬规则、数据层 JS 模式、主题色彩系统),Agent 负责根据场景自由设计 UI 布局、卡片样式、交互细节--让每个应用看起来像它该有的样子,而不是同一个模板换张皮。

两种模式:

• 本地模式(默认):零依赖,双击 index.html 即可使用,数据存手机浏览器里。不需要任何账号、不需要安装任何东西,拿来就能用。
• 云模式:部署到 Cloudflare Pages + D1,多设备同步。手机和电脑数据实时一致。

云模式不一定非用 Cloudflare。 高级用户可以部署到任何支持静态托管 + 数据库的平台(Vercel + Turso、Netlify + Supabase、自有服务器等),只需自行适配 API 层。Skill 默认用 Cloudflare 是因为它免费额度大、部署最简单。

适用场景

• 个人收藏/库存管理
• 记录和追踪(训练日记、补剂、观影......)
• 清单管理(装备清单、购物清单、待办)
• 任何需要搜索、筛选、排序的个人数据

不适用

• 多人协作、用户认证、第三方 API 集成
• 复杂关系型数据(多表关联)
• 实时数据流、支付/审批等后端业务逻辑

能力圈

强势: 个人数据管理全品类 需用户配合: 带图片、复杂计算字段 不做: 多用户系统、>10000 条数据

必读 References

• references/inspiration.md - 场景灵感 + 能力边界(用户不知道做什么时给他看)
• references/field-inference.md - 字段类型推断规则
• references/components.md - 主题系统 + UI 组件规范
• references/deploy-guide.md - Cloudflare 部署全流程
• references/validation.md - 校验规则 R1-R7

种子模板和组件库(参考,不是规范)

种子模板和 references/components.md 都是参考实现,不是强制规范。

• 数据层 JS 模式(localStorage CRUD、Smart Select、导入导出)→ 必须复用,这是硬规则
• UI 组件(卡片样式、色条/色点、布局方式、信息层次)→ 自由设计,components.md 只是"一种可能的做法"
• 关键区别:Agent 可以用色点代替色条、用分组代替扁平列表、用时间线代替卡片--只要符合场景气质就行

Agent 必须读取种子模板来理解数据层的约定,但 UI 层自行设计。

Agent 读取种子模板的方式:

我读完种子模板了。数据层逻辑(localStorage CRUD / API 模式)我会保持兼容,
Smart Select 三件套逻辑我也复用。接下来 UI 完全根据场景来设计。

工作流

0. 环境检查

Agent 自动检测:Node.js / wrangler / Cloudflare 登录。

• 三项全通过 → 云模式
• 任一缺失 → 本地模式
• 用户可覆盖选择

1. Intake - 理解需求

抓住三件事:管什么、谁在用、怎么用。

用户画像推断: 如果用户描述了使用者特征(年龄、性别、职业、场景),Agent 应据此调整字段选择、主题偏好和设计语言。例如:

• 40岁女性营养补剂 → 不加价格字段(关注体感不是记账),选 Frost 主题(干净清爽)
• 男性健身者记录训练 → 加成绩字段,选 Obsidian 主题(力量感)
• 咖啡爱好者 → 加风味描述,选 Dark Roast 主题(温度感)

如果用户没描述画像,按通用默认走,不追问。

不要追问每个字段。 读 references/field-inference.md,推断一套合理字段,一次确认。

2. Schema 设计

生成字段元数据 JSON(类型、UI 组件、是否可搜索/筛选)。

规则不变:

• 必须有一个 display: "title" 字段
• 必须至少一个 type: "enum" 字段(状态筛选)
• Smart Select、Date、Number、Textarea 按规则分配

3. 选择主题

从预设主题中选一套。如果没有匹配场景气质的,Agent 可以基于最接近的预设主题进行微调(换强调色/字体),但背景/卡片/边框的明暗关系必须保持一致。

设计纪律(来自 tasteskill anti-slop 框架):

• 不用纯黑 #000000,不用纯白 #ffffff -- off-black/off-white 保持深度
• 强调色饱和度 \x3C 80% -- 和中性底色融合,不刺眼
• 一个项目一套色温 -- 暖灰不混冷灰,底色和文字色同色温
• 对比度层级锁定 -- --bg \x3C --surface \x3C --surface2 \x3C --surface3 递进不跳跃
• 字体选择有场景意图 -- 不无脑用 Inter,轻套产品用衣线、极客场景用等宽、运动场景用大写无衣线
• accent 只有一个色相方向 -- 不在同一个项目里混用蕴色和蓝色强调

主题规则:

• 主题只决定颜色变量 + 字体,不决定布局/卡片样式/排版
• Agent 从主题中提取 CSS 变量,然后自由设计 UI
• 允许微调:换强调色(--accent)、换字体、调整状态色
• 不允许乱改:背景明暗关系、对比度层级(--bg \x3C --surface \x3C --surface2 \x3C --surface3)

主题解耦(用户可个性化):

• CSS 中包含全部4套主题的变量定义,用 [data-theme="xxx"] 选择器
• HTML \x3Chtml> 标签加 data-theme="xxx" 属性指定当前主题
• 应用的所有样式只引用变量(如 background: var(--bg)),不硬编码色值
• 用户切换主题:只需改 data-theme 的值(如 blaze → frost)
• 用户自定义主题:复制任意一套 [data-theme="xxx"] 块,改个名称和色值即可

4. 🔥 设计提案(Agent 发挥创意的环节)

这是整个工作流最重要的一步。在这里 Agent 是设计师。

Agent 根据场景特征,提出一个设计概念,包含:

a) 布局方案: 根据数据特征选择/发明合适的布局:

不限于以上布局。 Agent 可以混合、可以发明。

b) 卡片设计:

• 信息层次:主标识 > 状态/标签 > 关键属性 > 时间/备注
• 视觉强调:色条、标签、图标、排版节奏
• 留白策略:数据密集型 vs 呼吸感

c) 交互细节:

• 筛选器位置(顶部 sticky / 侧边 / 底部弹出)
• 排序方式(按钮切换 / 下拉 / 拖拽)
• 空状态设计
• 过渡动效

d) 输出格式:

给用户一个清晰的视觉提案:

🎨 设计提案:[场景名]

布局:[时间线 / 网格 / 卡片列表 / 看板 / 自定义混合]
主题:[主题名]

📐 结构:
[ASCII 线框图,展示关键页面的布局结构]

🎴 卡片预览(假数据):
┌──────────────────────┐
│  [具体展示一张卡片的样子]    │
│  包括色条位置、信息排列、标签样式 │
└──────────────────────┘

🎨 配色:
[色块] 背景 #xxx  [色块] 卡片 #xxx  [色块] 强调 #xxx  [色块] 状态色1 2 3

✨ 亮点:
- 这个布局为什么适合这个场景
- 有什么特别的设计决策

这个方案可以吗?还是想换布局/换主题?

一次确认,不反复追问。

5. 视觉 Mockup(可选但强烈建议)

如果 Agent 有能力(有 browser/canvas 工具),生成一个真实的 HTML Mockup 让用户看:

• 只渲染 2-3 张假数据卡片
• 包含关键 UI 元素(TopBar、FAB、Filter Chips)
• 交互可以先不做(这是视觉稿,不是成品)
• 用户确认后,再写完整代码

如果 Agent 没有渲染能力,用 ASCII 线框图 + 文字描述即可。

6. 生成应用

⚠️ 关键转变:不复制种子模板的 HTML/CSS,只复用数据层 JS 模式。

所有模式通用:

1. 创建项目目录 pwa-\x3Cslug>/
2. 读取对应的 JS 种子模板(学习数据层模式,不是复制)
3. 按设计提案编写 HTML/CSS--从头写,自由设计
4. app.js 的数据层(load/save/CRUD/filter/sort/export/import)保持与种子模板兼容
5. Smart Select 三件套逻辑从种子模板复用
6. 加入导入/导出按钮

本地模式: 3 个文件(index.html + styles.css + app.js),所有功能在前端 云模式: 加入 functions/ + schema.sql + manifest.json + sw.js

关于 CSS 变量: 从当前主题提取变量名(--bg, --surface, --text 等),用自己的 CSS 选择器使用它们。不要复制种子模板的 CSS 文件。

7. 预览 → 部署 → 交付

与之前相同。关键原则:先给用户看,再问要不要校验,交付时包含数据导入导出说明。

设计指南

场景 → 布局映射(参考,不强制)

• 日记/训练/记录 → 时间线布局(日期轴 + 内容块),反向时间序
• 书籍/影音/收藏 → 网格或卡片列表,封面图占位
• 咖啡豆/装备/器材 → 属性卡片,关键参数一眼可见
• 待办/购物 → 清单 + 复选框 + 归档区
• 投资/持仓 → 数据面板 + 列表

审美原则

• 信息架构 > 视觉装饰 - 先排好信息的阅读顺序,再加样式
• 场景气质对路 - 健身 App 该有力量感,图书馆 App 该有书卷气
• 克制配色 - 背景 1 色 + 卡片 1 色 + 强调 1 色 + 状态色 3-5 色,足够了
• 排版节奏 - 大字号标题 + 中等正文 + 小字辅助信息,形成视觉层次
• 动效轻量 - 卡片入场 fade-up、点击微缩放,不抢戏

硬规则(Non-Negotiables)

设计自由,功能不自由。以下规则必须遵守,不管 UI 怎么设计:

数据层(不可妥协)

• 数据必须持久化。 localStorage(关浏览器不丢)或 D1(云模式)。
• 导入/导出必须有。 JSON 格式,数据安全底线。
• Smart Select 三件套不可少。 select + hidden input + custom input。
• Smart Select 必须带管理功能。 每个 smart-select 字段旁边必须有 ⚙ 管理按钮,点击弹出管理面板,支持改名和删除。删除会清空所有使用该值的记录的对应字段,改名会批量更新。模板已内置(template-app.js 的 openSmartSelectManager + template-app.html 的 #smartSelectManager dialog + template-styles.css 的 .smart-manage-btn / .smart-manager-* 样式)。

组件约束(不可妥协)

• Editor 必须是 \x3Cdialog> 模态框。 不用路由跳转,不用侧边栏。
• FAB 按钮必须有 safe-area 适配。 bottom: calc(24px + env(safe-area-inset-bottom, 0px))。
• 状态必须有视觉区分。 色条/标签/颜色--用什么形式 Agent 决定,但必须一眼能区分。

主题约束(不可妥协)

• 优先用 4 套预设主题。 允许微调强调色和字体,但背景明暗层级必须保持一致。
• 至少一个 enum 字段用于筛选。

本地模式额外

• 双击即用。 不依赖服务器、npm、Node.js。
• 不用 type="module"。 file:// 协议下有 CORS 问题。

云模式额外

• 离线 fallback。 Service Worker + localStorage。
• API 带 CORS。
• 从项目根目录部署,不是 public/ 子目录。

迭代

• 增减字段 → 改 HTML 表单 + app.js 字段列表
• 换主题 → 换 CSS 变量值
• 换布局 → 这是大改动,重新走设计提案流程
• 本地→云模式升级 → 加 API 层 + D1 + SW

设计哲学

好的设计是“这应用就该长这样”。CrossFit 日记不该看起来像图书馆，图书馆不该看起来像咖啡豆仓。

种子模板是乐高积木的说明书，不是乐高成品。Agent 读说明书，搭自己的东西。

用户部署指南

以下内容是给用户看的（不是给 Agent）。生成应用后，把这段贴给用户作为部署指引。

本地模式（零配置，拿来就用）

不需要任何账号，不需要安装任何软件。

1. Agent 会给你生成 3 个文件（index.html + styles.css + app.js）
2. 拖到浏览器里打开 index.html，就能用了
3. 数据存在浏览器里，关掉再打开也不会丢
4. 想备份？用应用里的“导出 JSON”功能

限制： 只能在一个设备上用。手机和电脑的数据不会同步。

云模式（多设备同步）

想在手机和电脑上都能用、数据实时同步？需要部署到云上。

默认方案：Cloudflare（推荐，免费）

你需要：

1. 注册一个 Cloudflare 账号（免费，不需要绑卡）
2. 电脑上安装 Node.js（nodejs.org 下载安装）
3. 打开终端，运行 npm install -g wrangler
4. 运行 wrangler login，在浏览器里授权

做完这 4 步，告诉 Agent“我 Cloudflare 配好了”，Agent 会自动帮你部署。部署完你会拿到一个网址，手机打开就能用。

其他平台（高级用户）

如果你熟悉其他平台，也可以部署到：

• Vercel + Turso — 前端开发者常用
• Netlify + Supabase — 功能强大但配置稍多
• 自有服务器 — 完全自由，需要自己損定数据库

只需要告诉 Agent 你想用哪个平台，Agent 会适配 API 层。但注意：非 Cloudflare 平台需要你自己有一定技术基础。