--- name: smyw description: smyw(show me you want)。在做会改动页面、交互流程或前后端接口的功能时,生成一个单文件 HTML「变更预览」:按真实界面画出每一整屏的线框(模块名和代码组件对得上),放在可拖动缩放的画布上,最外层改动的模块按编号画框(黄=修改,绿=新增,红=删除);点编号查看这一处的改动前后、相关交互步骤和函数/接口。组件框架为 Base UI(@base-ui/react):spec 的 type 直接写 Dialog / Switch / Tabs / Accordion / Select 等原语,实现时按同一套组件拼。另有流程泳道和后端模块的前后对比。用户可以直接在 HTML 里拖动组件、把内联卡片改成按钮触发的弹窗/下拉菜单、改文字和组件类型、写批注和整体风格意见,然后复制结构化反馈粘贴回对话。纯前端单文件,不需要服务端。默认用于写代码之前的原型阶段,也可用于实现后回顾。 whenToUse: 用户提出新功能、改版或重构,且会新增/删除/修改页面、改变交互流程、或改动前后端接口时;用户说「出个原型」「先给我看看要改什么」「画个前后对比」「展示这次的变化」时;实现完成后需要向用户展示改了什么时。 --- # smyw(show me you want):变更预览 + 原型反馈 一次功能变化 → 一份 JSON spec → 一个可交互的 HTML。用户在 HTML 上看懂"改哪里、加什么、怎么触发",直接动手改方案或写批注,再把反馈交回给你。 本 skill 目录(下文称 `$SKILL`)里有: - `scripts/build.mjs`:校验 spec,生成单文件 `preview.html`(纯前端、无外部依赖、离线可开) - `scripts/apply-feedback.mjs`:从用户粘贴回来的反馈里取出修改后的方案,生成下一版 spec - `references/spec-format.md`:spec 完整字段说明,**第一次写 spec 前先读一遍** - `references/base-ui.md`:**组件框架**。spec 的 `type` 用 Base UI 原语(`dialog` / `switch` / `accordion` / `select`…),写 spec 和实现前都先看它 - `examples/base-ui/spec.json`:Base UI 组件示例(Dialog / Switch / Tabs / Accordion / Progress / Toast) - `examples/task-tags/spec.json`:完整示例(新增页、删除页、内联卡片、表格列变化、流程、后端) 构建只需要 Node ≥ 18;生成的 HTML 是纯前端的,**不需要也不要启动任何服务**。**不要手写 HTML**:永远写 spec 再 build。 ## 什么时候用 - **默认**:功能会动到页面、交互或接口时,在写代码**之前**先出原型(`stage: "prototype"`),给用户看,等反馈或确认后再实现。 - 很小的改动(改一处文案、加一个字段)先问用户要不要预览;用户说"直接做"就跳过。 - 实现之后:把同一份 spec 改成 `stage: "done"`,按**实际实现**修正,并在 note 里标出和原型的偏差,重新 build 给用户回顾。 ## 工作流 ### 1. 摸清现状:按真实界面画,不按功能点画 读路由、布局、页面组件、接口、模型代码,先弄清**用户实际看到的一整屏长什么样**: - **一个 page = 用户看到的一整屏**,而不是一个组件或一个功能点。比如「左侧侧栏 + 右侧主面板」是同一屏,要画在同一个 page 里(`root.layout: "row"`,侧栏 `w: "1/4"`),不要拆成「侧栏」「详情」两个 page。不同路由或不同模式下的界面才算不同的 page。 - **模块要和代码对得上**:每个区域(侧栏、头部、主面板、列表、对话框……)用它在界面上的名字做 `label`,用 `component` 写代码里的组件或文件(如 `" TicketQueue.vue"`)。 - **没改的模块也要画出来**,写 label 和 component,**不展开 children** 就行(预览里会显示「内容不变,未展开」)。不要用「xxx(不变)」这种 placeholder 代替真实模块,build 会警告。 - 顺序、左右、上下要和真实界面一致,这样用户一眼能认出是哪里。 ### 2. 写 spec 在目标项目根目录下: ~~~ .smyw/-<短名>/spec.json ~~~ (产物都在这个目录:`preview.html`、每轮的 `feedback-v.md`、旧版 `spec-v.json`。第一次创建 `.smyw/` 时问用户是否加进 `.gitignore`。) **省 token 的写法**: - 第一版写完整 spec,用 JSON、缩进 2(不要用 YAML:缩进和引号容易出错,`on` 这类键在一些解析器里会变成布尔值)。 - 之后每一版**用编辑工具只改变动的地方**(改字段、插入/删除节点),不要整份重写,也不要为了改几处把整份 spec 重新读一遍。 - 用户的结构修改以补丁形式回来(见第 6、7 步),由脚本应用,不需要你读全量方案。 **组件框架:Base UI。** 界面用 Base UI 的原语来拼,不要用抽象方框代替真实组件: - `type` 写 Base UI 组件名:`dialog` / `alert-dialog` / `drawer` / `popover` / `preview-card` / `tooltip` / `menu` / `context-menu` / `toast` / `switch` / `checkbox` / `checkbox-group` / `radio-group` / `select` / `combobox` / `autocomplete` / `input` / `field` / `fieldset` / `form` / `number-field` / `otp-field` / `slider` / `progress` / `meter` / `tabs` / `accordion` / `collapsible` / `toolbar` / `menubar` / `navigation-menu` / `scroll-area` / `toggle` / `toggle-group` / `avatar` / `separator` / `button`。旧类型 `modal` / `radio` / `divider` 也还能用,但新方案优先用对应的 Base UI 类型;`toggle` 不是开关的旧名,它是 Base UI 的 Toggle 按钮(开/关设置请用 `switch`)。 - 弹层用 `trigger` 指向打开它的按钮;展开 / 收起用 `hidden` + `on: toggle`,Tabs 切换用 `hidden` + `on: show/hide`;选中态用 `states` + `on: state`。预览的「▶ 演示」能真的点。具体切分见 `references/base-ui.md`。 - `component` 写实现时要写的 Base UI 组件(如 `" InviteDialog.tsx"`),用户靠它把线框和代码对上。 - **不要写样式**:Base UI 是 headless 的,颜色/间距/字体由项目决定;线框也不表达视觉。 要点(完整说明见 references/spec-format.md,先看 `references/base-ui.md` 和 `examples/base-ui/spec.json`): - **一棵合并树**:同一棵树同时描述前后两侧。每个节点用 `change` 标注 `added / removed / modified`,不写就是不变。 - **在最外层标注**:整块模块是新增或删除时,只在这个模块上写 `change`,里面的子元素**不要**再逐个标。预览只给最外层改动的模块画框编号(黄 = 修改,绿 = 新增,红 = 删除),用户点编号再看这一处的改动前后。 - **修改**:`change: "modified"`,旧值写在 `before` 里(如 `"before": {"label": "添加"}`),旧值不存在就写 `null`。容器改了名、里面又加了几块时,容器标 modified,新加的子块各自标 added。 - **移动**: - **单版本内相对 `v0` 移动**:旧位置放一个 `change: "removed", movedTo: "<新id>"` 的节点,新位置放 `change: "added", movedFrom: "<旧id>"` 的节点(用不同 `id`)。 - **跨版本迭代(如 `v1 → v2`)搬家**:直接保留该节点在 `v1` 里的原 `id` 放到新容器即可(若它同时相对 `v0` 也移动了,旧位置放一个新 id 的 `removed` 幽灵指向原 `id`),多版本 diff 会自动按同 `id` 换父容器识别为跨容器移动。 - **弹窗、抽屉、下拉菜单(二级菜单)、气泡**:放在 `page.overlays`,`trigger` 指向打开它的按钮 id;几个按钮打开同一个弹层时写成 id 数组。画布上会从每个触发按钮画一条弯曲连线到弹层,所以 trigger 一定要写全。 - **交互要写成数据,不要写成说明文字**。「点了才出现」「点不开」「可折叠」「点击切换」这类话,改用下面三个字段(build 会对这类文字报警): - `on`:点击后发生什么,如 `[{ "action": "open", "target": "settings" }]`。action 取 open(打开弹层)/ close(关闭所在弹层)/ navigate(跳到另一个 page)/ toggle(展开收起)/ show / hide / state(切换状态)/ back。 - `hidden: true`:默认不显示、点了才出现的内容(展开的详情、二级列表、节点详情……)。有元素用 toggle / show 指向它时,画布上会把它画成**旁边的单独面板**并连线,原位置留一个「在这里展开」的槽位。 - `states` + `state`:同一个元素的几种样子,如 `{ "done": { "label": "已验收" } }`,用 `{ "action": "state", "target": "ac-btn", "state": "done" }` 切换。 - 下拉菜单、二级菜单、弹窗、抽屉用 overlays + trigger(也可以在按钮上写 `on` open);菜单里还有一级的,用 hidden + toggle。 用户可以点右上角「▶ 演示」像 Figma 原型一样点着试,所以每个可点的东西都写上交互。 - **函数占位**:用 `fn` 写组件背后的行为,例如 `onClick → openTagEditor()`、`GET /api/tags`。 - **原型文字只写界面真实文案,不要把注释塞进 `label` / `text`**:像「原平铺卡片 1/4」「点击后展开」「供安全审计」这类说明请全部写进 `note`——预览里会渲染成类似 Figma 的角落悬浮注释气泡(悬停查看,不污染界面排版)。 - **自动继承项目主题(0 额外 token)**:`build.mjs` 会自动从目标项目的 `src/app/globals.css` / `src/index.css` 等文件提取 `:root` CSS 变量(主色、背景、卡片、边框、圆角)应用到原型上;需要自定义时也可以在 spec 顶层写可选的 `"theme": { "primary": "#4F46E5", "radius": "6px" }`。 - `note` 用一句话写「为什么这么改」,会出现在悬浮注释气泡、改动清单和详情里。 - `versionNote`(顶层可选字符串):多轮迭代时用一句话写「这一版相对上一版改了什么」(如 `"收敛为 3 格概览,去掉页头冗余按钮"`),会直接显示在预览顶部的版本对比下拉框里。 - `id` 要稳定、有语义(kebab-case),并在整个 spec 内唯一且必填(`build.mjs` 对缺 id 直接报错),因为补丁和多版本 diff 都按 id 对齐元素。**跨版本迭代修改或搬家同一个模块/按钮/步骤时,务必保留原 `id`**(不要改名或重新编号),这样才能在任意两个版本间精确展示修改与跨容器移动。 - `questions`:需要用户拍板的点写在这里(可带 `options`),不要藏在 summary 里。 - `flows`:按用户实际操作顺序写步骤,`actor` 取 user / frontend / backend / db / external / system,`fn` 写函数或接口,`node` 写这一步发生在哪个界面元素上(id,可以是数组)。详情面板靠它显示「相关交互」,流程页也能一键定位回界面。 - `backend`:模块 → 条目(api / function / model / field / table / job / event / config)。 - **不要写样式**。线框不表达颜色、间距、字体。用户若在意风格,会在反馈里说。 ### 3. 构建 ~~~bash node $SKILL/scripts/build.mjs .smyw//spec.json ~~~ 出现 ✖ 必须修好;出现 ⚠ 要逐条看(例如 modified 却没有 before/note,用户就看不出改了什么)。 **多版本自动归档与任意版本对比**: - 每次对 `spec.json` 构建成功时,`build.mjs` 会自动把当前版本归档为同目录下的 `spec-v.json`(需要跳过时可加 `--no-archive`),并扫描同目录全部 `spec-v*.json` 一起打进单文件 `preview.html`(自动提取 `v0 现状` 与 `v1..vN` 各版快照)。 - 只有一个版本时,预览保持 `改动前 → 改动后` 不变;当存在多轮迭代(`v1`、`v2`、`v3`…)时,预览顶部会出现版本对比栏,**默认展示上一版 → 最新版(`v(N-1) → vN`)**,支持任意切换左右两个版本,也可一键切换「对比现状 `v0→vN` / 只看本轮 `v(N-1)→vN`」。 - 每次迭代更新 `spec.json` 时,把 `version` 递增(`1 → 2 → 3`)并写一句 `versionNote`,**不要删除旧的 `spec-v*.json`**,直接重新 `build.mjs` 即可。 ### 4. 交给用户 预览打开后是一张可拖动、可缩放的画布: - **默认「纯净预览」+ 左右对比**:每个有改动的页面装在一个前后对比框里,中间用红→绿箭头连接「改动前」和「改动后」,默认不画满屏改动框,下拉框(`