AI教程

用 smyw 让编码 Agent 先画原型再写代码：安装、评审与反馈完整教程

本教程介绍如何安装 smyw，让 Claude Code 等编码 Agent 在动手开发前生成界面与流程原型，并通过改动对比、交互演示、结构编辑和批注反馈反复确认方案。

AI我搜编辑部2026年11月11日阅读约 12 分钟

smyw 是什么

smyw，即“show me you want”，是一个面向编码 Agent 的 skill，适用于 Claude Code、DeepSeek Harness 等支持 SKILL.md 的 Agent。它让 Agent 在修改页面、交互流程或前后端接口之前，先阅读代码、编写结构化 spec，再生成可离线打开的单文件 HTML 原型。

这份原型不是最终视觉稿，而是用于表达模块组成、布局位置、触发关系和功能变化的低保真线框。正式实现仍应遵循项目已有的设计规范。

它解决了什么问题

传统的 Agent 编码流程往往从文字需求直接进入实现，容易在页面结构、交互方式或接口边界上产生理解偏差。smyw 在需求与代码之间增加了一个可视化确认阶段：

用户提出功能需求。
Agent 阅读项目代码并生成 spec.json。
构建脚本校验 spec，输出 preview.html。
用户在浏览器中查看、演示、拖动和批注方案。
用户复制反馈并发回对话。
Agent 应用反馈、生成下一版原型。
用户确认方案后，Agent 才开始编写代码。

smyw 的重点不是替代设计工具，而是让用户和编码 Agent 在实现前，对“要改什么、放在哪里、如何触发”形成一致理解。

核心功能

编号标记与前后对比

原型会按真实页面布局绘制完整画面，并用颜色区分变化：黄色表示修改，绿色表示新增，红色表示删除。只有最外层发生变化的模块会被编号，避免内部元素出现大量重复标记。

点击画布编号或左侧改动清单后，画布会聚焦到对应区域，右侧展示改动前后的局部线框、字段差异、Agent 说明、代码组件以及相关函数或接口。

如果整个模块都是新增内容，详情中的“改动前”会显示该模块原本不存在，内部按钮和文本不再逐项编号。

准确表达组件移动

组件从一个位置移动到另一个位置时，原位置显示红色“移出”，新位置显示绿色“移入”。两处记录可以互相跳转，便于确认这不是一次删除加一次无关新增。

弹层、菜单与展开内容

弹窗、抽屉、下拉菜单、气泡和点击后才展开的内容，会被放在主屏幕旁边的独立面板中，并通过连线指向触发按钮。一个弹层可以关联多个触发入口，被删除的弹层则使用红色虚线表示。

多级菜单会继续拆分成相邻面板。原地展开的内容会在页面中留下紫色虚线槽位，说明它展开后出现的位置。跳页和状态切换连线默认隐藏，可在选择相关元素时查看，或通过“全部连线”统一打开。

可点击的演示模式

点击右上角的“▶ 演示”，原型会隐藏改动框，以单屏方式模拟真实操作。它可以演示菜单展开、抽屉滑出、弹窗打开、按钮状态改变和页面跳转等行为。

如果点击了不可操作的区域，所有当前可点击位置会闪现蓝框，左侧也会列出可执行操作。演示支持返回、从头开始，以及在“改动前”和“改动后”之间切换。

直接编辑与集中反馈

编辑结构：拖动组件调整顺序或容器归属，并修改文字、类型、宽度和排列。
转换形态：把内联模块转换成弹窗、下拉菜单、抽屉或气泡，系统会生成触发按钮和连线。
撤销与重做：支持使用 Ctrl 或 Command 加 Z 撤销操作。
元素批注：为指定元素添加位置、交互、组件类型、样式、文案或功能缺失等类别的意见。
意见级别：批注可以标记为“必须改”“建议”或“疑问”。
整体反馈：记录风格意见、参考方向，并回答 Agent 预先列出的确认问题。
补丁回传：结构修改只以按 ID 定位的补丁形式附在反馈末尾，不必回传完整方案。

安装前准备

构建 smyw 原型只需要 Node.js 18 或更高版本，项目本身不需要服务端，也没有运行依赖。首先确认 Node.js 版本：

node --version

如果准备运行仓库的端到端测试或重新生成截图，还需要安装 Google Chrome。非默认安装路径可以通过 CHROME 环境变量指定。

安装 smyw skill

第一步：克隆仓库

git clone https://github.com/nishuzumi/show-me-you-want-skill.git
cd show-me-you-want-skill

第二步：把 skill 放到 Agent 可读取的位置

Claude Code 用户可以创建全局符号链接，让所有项目都能使用 smyw：

ln -s "$PWD/skills/smyw" ~/.claude/skills/smyw

如果 Agent 会读取通用 skills 目录，也可以链接到：

ln -s "$PWD/skills/smyw" ~/.agents/skills/smyw

若只想在某个项目中启用它，则复制到该项目的本地 skill 目录：

cp -r skills/smyw <你的项目>/.claude/skills/smyw

安装完成后，可以向 Agent 提出会修改界面或接口的需求，或者直接说：“先出个原型给我看看。”

先运行仓库示例

仓库内已经提供两个生成好的 HTML 示例，无须启动服务器，直接用浏览器打开即可：

skills/smyw/examples/helpdesk-ai/preview.html：客服工作台加入 AI 建议回复的完整单屏示例。
skills/smyw/examples/task-tags/preview.html：展示整页新增与整页删除的多页面示例。

修改示例的 spec 后，可以用下面的命令重新生成预览：

node skills/smyw/scripts/build.mjs skills/smyw/examples/helpdesk-ai/spec.json

构建结果是纯前端单文件，可以离线打开和评审。

从需求到原型的基本用法

第一步：向 Agent 描述需求

尽量说明业务目标和约束，但不必提前决定所有界面细节。例如：

请在客服工单详情中加入 AI 建议回复。先阅读现有页面和接口，不要立即写代码；使用 smyw 生成原型，让我确认抽屉入口、回复替换流程和涉及的接口。

第二步：检查生成的 spec 和预览

Agent 会在类似下面的目录中保存结构化方案：

.smyw/<日期>-<名称>/spec.json

随后使用 build.mjs 校验并生成 preview.html。打开预览后，可以按以下顺序检查：

先使用“适应”将完整画布放进视口。
检查黄、绿、红改动框是否符合需求。
依次点击改动清单，核对前后对比和字段变化。
查看相关组件、函数和接口是否对应现有代码。
打开“流程变化”和“后端变化”，检查跨层影响。
进入演示模式，实际点击菜单、弹窗、抽屉和状态按钮。

第三步：编辑和批注方案

如果结构不符合预期，可以切换到“编辑方案”，直接拖动组件，或把内联内容转换为弹层。对于不适合直接修改的意见，选择元素后添加批注，并设置类别和优先级。

建议明确区分三类反馈：

必须改：实现前必须落实的问题。
建议：Agent 可以评估是否采纳，但不采纳时应说明理由。
疑问：需要先回答和澄清，再决定如何调整。

第四步：复制反馈并交回 Agent

进入“反馈”页，补充整体风格意见、回答待确认问题，然后点击“复制反馈”。将生成的 Markdown 粘贴回 Agent 对话即可。

Agent 通常会把反馈保存为 feedback-v<N>.md，再运行：

node skills/smyw/scripts/apply-feedback.mjs .smyw/<dir>/feedback-v1.md .smyw/<dir>/spec.json
node skills/smyw/scripts/build.mjs .smyw/<dir>/spec.json

apply-feedback.mjs 会备份旧 spec、应用反馈中的补丁并增加版本号。如果反馈版本与当前 spec 不一致，脚本会拒绝应用，避免覆盖较新的方案。

第五步：确认后再开始编码

检查下一版原型，确认所有“必须改”意见已经落实、“疑问”已经回答。没有其他问题后，点击“确认方案，可以开始做”，再让 Agent 进入正式实现阶段。

理解 spec 的基本结构

smyw 使用一棵树同时描述改动前后的界面。每个节点通过 change 标记变化，交互和状态则由 on、hidden 与 states 描述。

{
  "id": "reply",
  "type": "form",
  "label": "回复客户",
  "component": "<ReplyBox>",
  "change": "modified",
  "before": { "label": "回复" },
  "children": [
    {
      "id": "reply-quick",
      "type": "select",
      "text": "快捷回复",
      "change": "removed"
    },
    {
      "id": "reply-polish",
      "type": "button",
      "label": "AI 润色",
      "change": "added",
      "fn": "openDraftDrawer({ mode: \"polish\" })",
      "on": [
        { "action": "open", "target": "ai-drawer" }
      ]
    }
  ]
}

这个例子表示回复表单标题由“回复”改成“回复客户”，原有快捷回复被删除，并新增一个打开 AI 抽屉的按钮。component 对应代码组件，fn 表示相关行为或接口占位。

完整字段说明可查看 spec-format.md，Agent 的执行规则可查看 SKILL.md。

进阶使用技巧

同时检查界面、流程和后端

不要只评审页面布局。对于涉及接口或数据变化的功能，还应查看流程泳道和后端变化。流程泳道会按用户、前端、后端、数据库和外部服务对比改动前后；步骤上的定位入口可以跳回对应界面元素。

利用工具栏理解代码影响

打开“ƒ 函数”，查看元素背后的行为或接口占位。
打开“组件”，查看模块对应的代码组件。
打开“淡化未改动”，集中关注本次需求影响范围。
需要审查完整触发关系时，再打开“全部连线”。

用演示模式验证状态变化

演示模式不只是查看跳转，还适合验证状态联动。例如，一个“替换到回复框”按钮可以把草稿填入回复框并关闭抽屉。批注会自动记录当时所在页面、已打开内容和点击历史，有助于 Agent 复现问题。

让 ID 保持稳定

反馈中的结构修改按节点 ID 定位，因此多轮迭代时应尽量保持已有节点 ID 稳定。除非元素本身被删除或语义完全变化，否则不要随意更换 ID。

重视构建校验

build.mjs 会检查重复 ID、修改节点缺少 before、使用“（不变）”代替真实模块、弹层缺少触发器等常见问题。出现错误时，应先修复 spec，再评审生成结果。

处理窄窗口和沙箱限制

在 Agent 侧边预览等窄窗口中，改动清单会收进“☰ 改动”按钮，详情则浮在画布上。在受限沙箱中，浏览器可能禁止保存进度或自动复制；如果复制失败，页面会自动选中反馈内容，此时按 Ctrl 或 Command 加 C 即可。

项目开发与测试

如果你需要修改 smyw 本身，可以运行端到端测试或重新生成 README 截图：

node tests/e2e.mjs
node tests/readme-shots.mjs

测试需要 Node.js 18 以上版本和 Google Chrome。Chrome 不在默认路径时，可这样指定：

CHROME=/path/to/chrome node tests/e2e.mjs

项目采用 MIT 许可证。

总结

smyw 把编码 Agent 的工作流程从“理解需求后直接写代码”改成“先读代码、生成 spec、展示可交互原型、收集结构化反馈，再开始实现”。它尤其适合涉及页面布局、弹层、状态切换、多页面流程或前后端接口的需求。

从仓库示例开始体验，确认 Agent 能读取 skill 后，再将其用于真实项目。通过改动标记、演示模式、直接编辑、批注和版本化反馈，可以显著降低需求理解偏差，让正式编码建立在已经确认的方案之上。