@chinhae/atw-cli 0.2.8 → 0.2.10

package/dist/templates/common/bundled-skills/atw-prototype/references/design-direction.md

@@ -0,0 +1,170 @@
+# 设计方向
+
+模型不被推一把时，会给出让所有人都能接受的平均答案。“做得独特一点”“随机一点”推不动它，它只会换几处装饰。这里的方法都是在给模型一个具体的推力：先定调性，再用生成引擎起方向，最后用可检验的规则逼出真正的差异。
+
+本文件以方法为主，偶尔给的例子只示意要具体到什么程度，不是风格清单。方向里的题材、材质、场景、字体和配色，每次都从当前产品的内容、受众和使用场合里推出；想到的方向如果和常见的“网红风格”撞上，要能说出来自这个产品的理由，否则重选。
+
+## 先定调性，再求差异
+
+从产品的题材、受众、品牌语气和使用场合推出调性。用五个刻度描述，每个刻度都写出依据：
+
+| 刻度 | 两端 | 在画面上看什么 |
+| --- | --- | --- |
+| 能量 | 安静 ↔ 喧闹 | 饱和度、对比、元素是否碰撞 |
+| 完成度 | 粗粝 ↔ 精致 | 边缘处理、颗粒与噪点、对齐是否严格 |
+| 密度 | 疏 ↔ 密 | 留白尺度、叠层、网格纪律 |
+| 分量 | 轻 ↔ 重 | 字重、色块面积、阴影硬度 |
+| 严肃度 | 活泼 ↔ 庄重 | 圆角、插画语言、动效幅度 |
+
+例如“地下现场演出社区 → 喧闹、粗粝、密”，“冥想陪伴 → 安静、精致、疏”。两种都完全成立，失败的是没有依据的默认：
+
+- 证据指向喧闹粗粝，交付的却是米色卡片、柔和阴影和大留白。这是最常见的失败，设计被磨回了模型默认的“安静高级”。
+- 反过来，为了显得有趣，给一个本该安静的产品硬加颗粒、撕纸边和粗边框。
+
+证据已经锁定调性时，所有候选都留在这个调性里，在构图、色彩身份和主视觉上拉开差异。不要为了“平衡”放进一个安静极简的保底方案。只有证据确实模糊时，才让候选分布在不同调性上。
+
+### 模糊词必须翻译
+
+“高级、精致、克制、史诗、有文学感、简洁”不能当作设计理由。用户或你自己说出这类词时，先翻译成可观察的决定：
+
+| 模糊词 | 翻译成什么 |
+| --- | --- |
+| 高级 | 先说清是哪一种高级，再决定字体的对比、分隔的方式、间距的尺度和色相的数量。只说高级什么也没决定 |
+| 精致 | 公差：字距怎么调、对齐到几像素的网格、阴影最多几级、色相最多几种 |
+| 克制 | 饱和度预算，例如强调色不超过画面 10%；动效幅度上限；色相数量上限 |
+| 史诗 | 尺度：展示字多大、主图占多少面积、明暗对比多强 |
+| 文学感 | 字族的性格、行长、行高和配色，各取什么值 |
+| 粗糙 | 用哪些手段，各用到什么程度，例如错位多少像素、旋转多少度 |
+| 简洁 | 密度档位，以及删掉什么、为什么删。简洁是结果，不是指令 |
+
+翻译不出可观察决定的词，从理由里删掉。
+
+## 用生成引擎起方向
+
+每个方向都从一个具体的引擎出发，而不是从形容词出发。不同方向最好用不同的引擎：
+
+- **材质 × 环境**：一种材质放在一个具体的环境里，比如“湿陶土 × 午后的工作室”。由材质推出光照、深度、边缘的处理和动效的阻尼。
+- **一个具体场景**：一个有时间、地点和光线的场景，比如“凌晨两点的便利店”。由场景里的光线、声音、材料和节奏推出色彩、质感和动效速度。适合情绪型工具。
+- **角色原型**：给产品一个性格，比如“一丝不苟的档案管理员”，让性格决定字体、色彩和动作。
+- **一场设计运动或文化语法**：选一个和产品的题材、受众或地域有真实联系的设计运动或视觉传统，借用它的语法，而不是贴它的图案。
+- **其他领域的整套表现形式**：把另一个领域的媒介或器物的表达方式借过来，比如把行程做成一张登机牌。只借它最有辨识度的一两个手法，页面本身仍是原来的体裁；不把那个媒介的部件一件件搬来，那会变成道具堆砌。
+- **有意打破常规**：激进的非对称版式、不和谐的配色与字体、让人不安的留白，但整体仍然好看、功能完整。
+
+感受词从这个品牌出发，而不是从行业出发。“美味、温暖、有食欲”会把每个食品应用都推向橙色；“深夜治愈、独处、温柔”才属于某一个品牌。行业惯用色可以用，前提是理由来自这个品牌；如果理由只是“这个行业都这么用”，就换掉。
+
+写方向卡之前，先在心里把方向想厚：用起来是什么感觉，让人联想到什么表面和物件，页面怎样流转，在讨好哪一类人。卡片是从这些思考里提炼出来的。跳过这一步，卡片只剩三十个字的空壳，后面做出的页面也会是平的。
+
+随机种子也是一种引擎：让脚本生成一串随机字符，从中联想配色、布局和字体，种子不进入界面。它适合陷入重复时破局，但不如上面几种引擎可解释。
+
+## 先定首屏骨架，再写文案
+
+模型最顽固的习惯是左右分栏：一边大标题，另一边说明、按钮或一张图。换字体、换配色、换材质都改变不了它，因为它在写文案之前就定下来了：先想好标题、一段说明、一个按钮，把它们摆好，自然就是左右两栏。所以骨架要在写任何文案之前决定。
+
+每个方向先从下表选一个首屏骨架，再用 3–5 个方框画出首屏线框：每块是什么、占首屏多大面积、阅读从哪里开始。
+
+| 骨架 | 首屏长什么样 |
+| --- | --- |
+| 满版图像压字 | 一张图占满首屏，标题和动作压在图的安全区里 |
+| 居中单一物件 | 一个物件或一句话居中，四周是大面积空白 |
+| 画面即界面 | 首屏就是产品界面或一件实物本身，标题、导航和按钮都长在它上面 |
+| 满版文字 | 文字本身就是画面，字大到占满首屏、跨过边缘或被裁切 |
+| 通栏上下堆叠 | 通栏大标题横跨整个宽度，下面紧接内容 |
+| 网格拼贴 | 多块内容同时出现，按网格或拼贴排列，没有单一主角 |
+| 纵排或斜向 | 文字竖排、斜切或旋转，打破从左到右的阅读 |
+| 左右分栏 | 文字一侧，画面一侧。这是模型的默认，一轮最多一个方向使用，并写出为什么非它不可。另一侧必须是跨越结构的图像、色块或图形装置，不能是装在卡片里的产品界面 |
+
+规则：
+- 同一轮的方向，骨架互不相同。
+- 左右分栏最多出现一次。所谓“大标题九栏、说明三栏”同样算左右分栏。
+- 骨架定好之后再写文案。文案去适应骨架，不让骨架去适应“标题 + 说明 + 按钮”的组合。
+
+构图的大胆程度和调性无关。安静精致的产品，一样可以把一句话放在空白首屏正中，或让纵排标题贯穿整屏，或让界面本身占满首屏。调性决定音量，骨架决定结构；不要因为调性偏安静，就退回左右分栏。
+
+每一轮至少有一个方向让你自己觉得有点冒险：放在同类产品里会显得格格不入，但仍然好看，功能完整。模型只有被明确要求时才会这样做。如果你心里想的是“这不可能行得通”，通常说明方向是对的，做出来往往比预想好。
+
+最常见的模板核心不是左右分栏本身，而是“左边标题和两个按钮，右边一张装在圆角卡片里的产品界面”。那张卡片几乎总是该删的：要么让产品界面本身占满首屏，要么换成一张跨越版面结构的图、一个色块或一个图形装置。
+
+## 方向卡
+
+每个方向写一张方向卡，每项都填具体选择，不填形容词：
+
+| 字段 | 要写到的程度 |
+| --- | --- |
+| 北极星 | 一句能指导取舍的体验意图：用起来像在什么地方、做什么事 |
+| 调性 | 五个刻度的取值及依据 |
+| 生成引擎 | 用了哪一种，具体是什么，来自这个产品的什么证据 |
+| 首屏骨架 | 从骨架表里选的哪一种，附 3–5 个方框的首屏线框：每块是什么、占多大面积、阅读从哪里开始 |
+| 页面结构 | 首屏以下怎么组织，例如单列沉浸滚动，或导航、内容、详情三栏 |
+| 各区块的形式 | 首屏以下每个主要区块（产品实样、功能、价格、隐私、结尾等）在这个方向里长成什么东西。形式从生成引擎推出，不是同一个模块换颜色 |
+| 字体 | 具体字族、字重和尺度关系：展示、正文、数字各用什么，相差多大 |
+| 色彩 | 用到的十六进制色值及用途，说清这个方向的色彩身份；黑白灰加一种强调色也是完整的答案 |
+| 主视觉 | 哪张图或哪个图形承担情绪与识别，来自复用、生成还是排版本身 |
+| 图标 | 用哪一套、什么描边粗细和端点，或者不用图标、改用字符和编号 |
+| 结构性突破 | 改变首屏结构的那一处偏离常规，以及它怎样放大北极星。手写批注、质感按钮、划线这类局部细节不算 |
+| 记忆点 | 集中发力的一两处：在哪个时刻或位置，用什么材质、动作或画法，见“让人记住的一刻” |
+| 放弃什么 | 这个方向主动不要的常见做法 |
+
+北极星、字体、色板和特征直接写进对比页 manifest，与画面一同展示。
+
+## 差异检验
+
+方向卡写完、做小样之前，逐条检验：
+
+- **比线框，不比描述**：把各方向的首屏线框并排放在一起比。方向的描述可以各不相同，线框却可能都是“左边大标题，右边小块”。线框相似就是同一骨架，重选骨架。
+- **四项至多一项相同**：首屏骨架、字体、色彩、主视觉四项里，任意两个方向至多一项相同；否则就是同一方向的变体，换一个生成引擎重写其中一个。
+- **不按明暗分方向**：头号失败是“一个亮、一个暗、一个暖”。每个方向要有自己的色彩身份：不同的色相家族、不同的材质感，或者干脆是黑白。明暗是色彩身份的结果，不是区分方向的依据。
+- **黑白也是一种色彩身份**：黑白灰加一种强调色，甚至完全不用彩色，常常是最高级的选择。这时颜色交给内容：产品截图、用户的照片、一张画。它和多色方案同样算拉开了差异；不要为了显得特别，去找一组少见的颜色。
+- **结构也要不同**：不同方向可以有不同的页面组织。三个方向页面结构完全相同、只是颜色和质感不同，就还没有拉开差异。候选只需共享核心内容和主要任务。
+- **至少一个走到极端**：至少一个方向在各项上都取明确的一端，不做折中；折中的取值最多出现在一个方向里。
+- **至少一个打破品类套路**：在同一调性内，至少一个方向不用这个品类的默认版式。常见套路如下：
+  - 后台：左侧栏、顶栏加卡片网格。
+  - 电商：大横幅、商品网格加页脚。
+  - 社交：底部标签栏、信息流加悬浮按钮。
+  - 落地页：主视觉、特性、用户评价，最后一个行动按钮。
+  - 聊天：左侧联系人，右侧消息。
+- **盲看**：遮住名字和说明只看画面，仍能说出每个方向带给人的不同感受。
+
+小样做出来后再比一次实际画面：在对比页并排看首屏，眯起眼睛只看明暗块面。块面的分布如果相似，比如都是左边一大块、右边一小块，即使字体和颜色都不同，也回到骨架表重做，不靠换装饰补救。首屏之后，再按区块逐一比较整页。
+
+## 北极星与呼应
+
+北极星选定后，转成少量相互支持的关系：摄影的空旷与标题的留白呼应；窄字形与纵向画面呼应；低饱和环境色与唯一的行动色形成反差。每个方向明确主角、陪衬、重复的节奏和一处结构性突破。
+
+突破要改变结构，例如首屏的骨架、比例或阅读顺序，而不是多加一个装饰；它应增强主题或引导关键动作。精修时不要把有辨识度的选择修平。新增元素不能强化同一意图时，优先省略。大胆的方案也必须可读、可用。
+
+## 让人记住的一刻
+
+模型做的页面常常处处及格，却没有一处让人记住。惊艳很少来自整页都用力，而是来自一处做到极致：通常是一个组件的一次动作，结果、材质、光影、手感和节奏都做到位。每个方向选一两处集中发力，其余保持安静。
+
+去哪里找：
+
+- **用户会做的动作。** 点按、拖动、切换、提交，比滚动更容易成为记忆点。
+- **关键时刻。** 付款成功、第一次完成任务、升级、删除、上传、等结果。这些时刻情绪最强，一个小动画的回报最高。
+- **边角页面。** 404、空状态、加载、页脚。没人期待，风险又低，最容易出彩。
+- **AI 在工作的时候。** 把过程按顺序展开：步骤一个个亮起，日志一行行流进来，做完的一步收起，正在做的一步展开。白底黑字照样成立，不需要材质和发光。
+
+怎么想：
+
+- **让结果当场发生。** 状态切换不只换一个图标，而是让被影响的东西当场变化：打开深色模式，整页像拉下遮光帘一样暗下去；拖动时间，画面的天色跟着走。用户看到的是结果，不是控件在表演。
+- **把数字画成看得见的量。** 百分比、时长、余额，先问能不能画成一个量：点亮的格子、填满的长度、一格代表一天的网格。数字只是标签，量才是画面。
+- **给抽象的状态一种材质。** 先问“这个状态如果是一个实物，会是什么”，答案从产品所在的领域里找。
+- **借物件的动作交付结果，物件从用户手上找。** 选这个领域的用户本来就拿在手上的东西：旅行产品用登机牌成立，作品集用登机牌只是借梗。票据、打印机、卡带、老游戏机这类复古实物在灵感站上已经泛滥，用之前先问：这个产品自己的实物是什么。
+- **给控件物理和性格。** 拖动有弹性和重量，按下有光影变化，拉过头会不情愿地弹回来。
+- **画法要说得出来源。** 点阵、字符画、像素、粒子、写实材质这类画法，只有能说出它来自产品做的事时才选：把数据渲染成点阵的研究工具用点阵，长在终端里的工具用字符画。说不出来源就不选；选了就从主视觉一路用到加载、图标和空状态。
+- **一张画面垫底时，界面要退后。** 有情绪的摄影或绘画铺满，界面缩到只剩一行导航和一句话，排版严格；底图虚化或压暗，保证文字可读。
+
+## 参考怎样转为设计决定
+
+先说明参考用途：借鉴视觉关系、建立质量基线，还是精准还原。实际看过图片再描述它的视觉。借鉴时提取关系，例如“标题占主要视觉重量，图像提供情绪，辅助信息压低对比”，再用当前内容重新组织；不要照搬参考的业务模块、标识和文案。隐喻要转译成界面决策，不做成妨碍操作的仿真外壳。
+
+## 小样、选择与品味
+
+先用几句话比较设计意向，再给有希望的方向做代表性小样，不一开始就做多套完整产品。单个页面的小样通常是首屏加最能体现方向的一两个区块；用户明确要完整页面时照做，评审深度仍按探索阶段。方案数量按任务定，窄小的任务不强求多方案。
+
+挑能暴露方向优缺点的代表性页面：含复杂表单的产品不能只做封面，长页面的小样要包含关键内容结构。
+
+介绍产品的页面，必须让用户看到产品真正交付的东西：一张生成好的报表、一份导出的合同、一段处理后的真实数据，而不是只用文字承诺“能做什么”。这个实样往往比功能列表更有说服力，也最容易成为页面的第二个主角。需要实际比较多个小样，或由 Agent 自行选定方向时，先使用 [风格对比页](style-explorer.md) 生成对比页留档，再选定方向。
+
+比较任务适配、辨识度、内容承载、可读性和实现代价，主 Agent 给出推荐依据，由用户选定。选定后请用户用具体的话补充品味：想要什么感受，不要什么、为什么不要，哪些地方要保留。用户只说“再高级一点”时，用上面的翻译表追问，或拿两张小样让用户比较。
+
+把选定方向和品味写进设计说明，作为后续判断基线。评审提出新风格时，先判断它是否解决原目标；只有当前方向确实不适配，或用户改变目标时，才重新探索。

package/dist/templates/common/bundled-skills/atw-prototype/references/style-explorer.md

@@ -0,0 +1,92 @@
+# 风格对比页
+
+## 固定外壳，独立候选
+
+用内置 [模板](../assets/style-explorer.html) 展示实际小样。外壳参照专业选片工具，采用无色相的浅灰画布和系统字体，让作品本身最突出，也便于判断颜色；左上角只有“风格对比”字样和本轮项目名，强调色只用在选中标记和复制提示这几处小面积。它只承担比较和挑选的功能，不带风格倾向，也不作为候选的参考。并排视图只负责比较画面：每个方向等大排列，作品下方只有一行编号、名称、色条和“选择”，再加两行以内的北极星，也可以关闭说明只看作品。色值、字体和特征放在单张查看的侧栏里。模板负责并排与单张查看、候选筛选、统一视口、实际尺寸、选择即复制与备注；每个候选在独立框架中渲染，其 CSS 不影响其他候选和外壳。
+
+默认并排且等大，保证比较公平。点击任一画面进入单张查看：画面从卡片放大到主区域，右侧栏滑入，栏顶是方向列表，下面是该方向的完整说明；键盘 ← → 让画面整条左右滑动切换方向，P 选定，Esc 缩回并排。
+
+外壳的动效只服务于看清变化：分段控件和方向列表用滑块移动表示当前项，视图之间用同一画面的放大与缩回保持连续，切换视口、筛选和缩放时外框直接变形，不做叠影；选定时标记弹出确认。控件用短促的咔嗒手感，画面切换用平滑减速，系统开启“减少动态效果”时全部直接到位。
+
+先保持核心内容、主要动作和目标用户一致，再改变构图、信息组织、字体气质、色彩关系、密度与图像语言。数量按请求和有效差异决定，不复制整个产品来凑方案，也不把内置外壳的风格套给候选。
+
+对比页是视觉探索工具。HTML 小样默认不执行脚本和提交，标记为可操作的小样和本机地址候选除外（见“准备输入”）；需要真实数据、登录或后端的交互验收，仍在项目里进行。
+
+## 准备输入
+
+在任务目录放置 `manifest.json` 和候选文件。HTML 候选为带 `head` 的文档，CSS 写在页面里。图片、字体和视频用相对路径引用任务目录里的文件，例如 `img/hero.jpg`，生成器会把它们内嵌进对比页；不要自己把图片转成 base64 写进候选，文件会变得很大、难以修改。不引用网络资源和任务目录以外的文件，链接只使用本页锚点。可以保留代码供独立打开，但比较页不执行其脚本。
+
+候选必须在不运行脚本时也能显示设计内容。依赖脚本生成界面的页面，先取得静态 HTML 或实际截图；不能把只有空挂载节点的应用入口交给对比页。
+
+候选内部不使用 iframe、object 或 embed 等嵌套文档；先将需要的内容转为静态页面或截图。另存的现有页面常带 `srcset` 或 `<picture><source>` 响应式图片，生成器会拒绝：改成一张用相对路径引用的 `<img>`，或直接用截图作为图片候选。
+
+图片候选支持 PNG、JPEG、WebP。实际查看图片并记录它代表的页面与状态，避免拿不同任务或不同状态的图比较风格。源文件必须位于 manifest 同目录或子目录。
+
+manifest 使用固定字段，结构如下。尖括号内是占位说明，全部换成本轮方向卡里的实际内容；不要沿用占位文字作为风格：
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "<项目名称>",
+  "brief": "<所有候选共同表达的内容与主要任务>",
+  "round": "<轮次，例如 01>",
+  "candidates": [
+    {
+      "id": "<小写唯一标识>",
+      "name": "<方向名称>",
+      "concept": "<北极星：一句能指导取舍的体验意图>",
+      "typography": "<实际使用的字族、字重与尺度关系>",
+      "palette": ["<十六进制色值>", "<十六进制色值>", "<十六进制色值>"],
+      "traits": ["<可观察特征>", "<可观察特征>"],
+      "kind": "html",
+      "source": "<候选文件的相对路径>"
+    }
+  ]
+}
+```
+
+自己写的可运行小样（单个 HTML、脚本内联），在 manifest 里给候选加 `"interactive": true`。单张查看时就能直接操作，对比页仍是可离线移动的单个文件，不需要服务器；卡片左下角标注“可操作”。这类候选只能运行内联脚本，不能联网或加载外部文件；浏览器存储换成页面关闭即清空的内存版本；`alert`、`confirm` 这类系统弹窗不会出现，需要确认时用页面内的对话框。
+
+已有仓库里要运行起来的应用（例如 React、Vue 项目），把 `kind` 设为 `url`，用 `url` 字段代替 `source`，指向本机开发服务器上的页面，例如 `http://localhost:5173/orders?variant=b`。这类候选在对比页里实时运行，脚本和表单照常工作，切换手机视口时应用会真实重排；卡片左下角标注“本地运行”。地址只能是 localhost、127.0.0.1 或 ::1；页面空白时，确认开发服务器已启动，且没有用响应头禁止被嵌入。对比页离开这台机器、或开发服务器关闭后，这类候选就看不到了，需要留存时另存截图作为图片候选。多文件的小样确实需要服务器时，用只监听本机的静态服务器，并用 `--directory` 只暴露任务目录，例如 `python3 -m http.server 8765 --bind 127.0.0.1 --directory <任务目录>`，看完就关掉。
+
+给当前版本加 `"baseline": true`，它会排在第一位，编号显示为“现状”，其余方向从 01 开始编号。每轮最多一个基线。改动存量页面时，都把现状放进来，让每个方向都和它对照。
+
+`id` 使用唯一的小写字母、数字、连字符或下划线。`typography` 描述实际使用的文字关系，`palette` 使用十六进制颜色，`traits` 简述可观察差异。图片候选将 `kind` 改为 `image`、`source` 指向对应图像。
+
+## 生成和打开
+
+确认 Python 不低于 3.10，将脚本与输入输出参数解析为绝对路径后运行 [生成器](../scripts/build_explorer.py)：
+
+```text
+<python> <skill>/scripts/build_explorer.py <任务目录>/manifest.json --output <任务目录>/style-explorer.html
+```
+
+macOS/Linux 通常使用 `python3`，Windows 通常使用 `py -3`；执行前确认实际解释器。没有生成器运行能力时保留输入与候选供直接查看，说明尚未组装对比页，不临时重写另一套工具。
+
+默认拒绝覆盖。确实要更新已有本轮对比页时显式加 `--force`，或使用新的输出文件名。输入错误时保留旧产物；生成器不覆盖源候选，也不允许把运行产物写入 Skill 目录。
+
+用浏览器打开返回的本地 HTML，无需服务器和联网。输出已内嵌候选，移动单个 HTML 仍可查看。模板原文件只有空状态，不是用户最终对比页。
+
+## 查看与记录选择
+
+默认使用相同逻辑视口展示 HTML 候选：桌面 1280×900，手机 390×844。卡片等比缩放以便同屏比较；判断文字大小与细节时进入单张查看，使用“实际尺寸 100%”检查真实排版；适应窗口仍可能缩小，不能据此宣称可读性通过。切换手机视口后确认真实重排，而非仅看缩小后的桌面。
+
+用筛选入口保留想同时比较的方案。选定一个方向，按需记录喜欢的特征与需要调整的部分。选择和备注保存在浏览器；存储不可用时界面保留当前会话，并仍可复制。当前选择和备注在顶部栏右侧，不另设底部栏，也没有单独的复制按钮，把高度留给作品。
+
+生成器根据本轮项目和候选内容生成 `fingerprint`。候选内容变化后会形成新一轮存储身份，避免把旧选择误用于新作品。点“选择”时同时复制一句简短的文字：轮次、编号和方向名，有备注时再附一行，例如“<轮次>：选 03 <方向名>”，并在底部提示已复制的内容。改完备注后再点一次“已选择”重新复制；选另一个方向会直接替换当前选择。
+
+用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到项目设计说明，继续实现。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
+
+## 检查实际结果
+
+检查候选内容是否可比，元数据与画面是否相符，以及中文字体是否真实可用。确认并排、单张查看与切换、筛选、桌面/手机、实际尺寸、返回并排、选择恢复和选择即复制都能操作；检查窄屏与存储不可用情况。
+
+模板和生成器的程序回归测试不随技能分发，由 ATW 维护者在修改模板或生成器时运行。普通新增候选只核对该轮内容和页面。
+
+## 修改模板本身
+
+模板和生成器随 ATW 分发。在用户项目里使用时不要修改它们；对比页不满足需要时，说明缺什么，不临时改模板。以下规则写给 ATW 维护者。
+
+模板的功能是本 Skill 对用户的承诺：并排与单张查看、桌面与手机、筛选、设计说明开关、实际尺寸、选择即复制、备注、本地地址候选与现状基线，以及存储不可用时的提示。调整外观时这些功能一项都不能少；确实要删减，先同步修改本文件和回归测试。
+
+直接编辑 `assets/style-explorer.html`，不要在任务目录写一次性脚本去替换模板里的字符串。改完运行程序回归，再用浏览器实际走一遍单张切换、选定复制、备注和返回并排；改动效时放慢播放，截取过渡中间的画面检查有没有叠影和跳动。

package/dist/templates/common/bundled-skills/atw-prototype/references/visual-language.md

@@ -0,0 +1,88 @@
+# 视觉语言
+
+## 从整体到局部
+
+先查看信息焦点、构图和内容密度，再调整空间、排版、色彩与细节。前一层已经解决问题时，不为显得精修而继续添加样式。
+
+使用项目有效的视觉变量、组件和参考关系。没有标准时只定义当前需要的文字、颜色与间距角色；不凭空生成完整设计系统。
+
+每次修改能说明：哪个可见元素、哪种关系存在问题、调整什么、期待改善什么。源码检查可以证明样式不一致，不能单独证明画面更好。
+
+## 焦点与空间
+
+- 每个任务区域有可辨认的主信息或主动作，辅助信息通过尺度、字重、对比或位置退后；不用多种强强调同时争夺注意力。
+- 同类关系保持同类间距，组内更紧、组间更松。先用对齐与留白建立结构，再判断是否需要容器或分隔线。
+- 留白承担分组、焦点或节奏。工具界面不为追求空旷牺牲必要信息，品牌页面也不强制塞满首屏。
+- 非对称、越界图形或大尺度文字可以表达选定方向，但需要稳定的局部对齐和清楚阅读顺序；不把有意的非对称自动当成错误。
+- 父布局负责区域排列，组件负责自身内部空间。同一距离不要同时由多层样式重复增加。
+- 先把内容直接放在画布上，通过对齐、字号和留白组织。容器只在确有分组、选择、背景对比或操作边界时出现；不要把页面、模块、条目和条目说明逐层套成卡片。
+- 分隔线和边框不要重复。每条线只做一件事：同一处分隔不叠双线、单线再加一个框；留白已经分开的地方不再补线；不要每个层级都画一遍线。线的粗细对应层级，例如粗线分版面、细线分栏，全页一致。线本身是风格的一部分时照样保留，只删重复的那些。
+
+## 字体与内容
+
+- 按标题、正文、辅助信息、标签和数据建立文字角色。角色稳定，层级有足够区别；实际内容长度决定换行和空间。
+- 检查目标语言的字形、字重与回退字体。英文样例好看不能证明中文排版成立；中英混排检查基线与视觉重量。
+- 正文行长与行高服务阅读；密集表格按扫描与比较安排，不套用文章排版。需要纵向比较的数字可使用等宽数字。
+- 重要名称和说明不靠固定高度裁切。确需截断时保留完整内容的可访问入口，避免相近名称截断后无法区分。
+- 先写具体产品内容再调布局。按钮说明动作结果；价值表达使用真实用途，不用空泛口号、虚构背书或无意义英文填版。
+
+### 可读性是交付门槛
+
+字号与行高在真实视口、实际字体和 100% 阅读尺寸下判断，缩略图只能用来判断构图。阅读型页面的中文正文通常从 16–18px 起步，产品界面正文 14–16px，每天长时间使用的高密度工具可以到 13–14px（见设计方向里的密度）；正文无单位行高 1.6–1.75；操作文字通常 14–16px。它们是起点，不是跨产品的死规定。不要靠 9–12px 的说明、低对比细字或压缩行高营造“精致”。信息太多先删冗余、调层级或重排。
+
+多行中文标题通常先用 1.2–1.35 的行高，按真实字形检查。不要照搬英文大写海报的极紧行高，不把标题高度固定为单行，不用负外边距挤压后续内容。展示字确需更紧时，必须看过每个支持视口的实际换行并确认字形不碰撞。
+
+中文断行要主动控制：`text-wrap: pretty` 或 `balance` 只能减少孤字，不能消除。数字和单位（38 秒、47 分钟）、“不会”这类不可拆的词用不换行包起来；首屏说明、页边批注这类短段落按语义手动断句。行末只剩一两个字，或者词被拆到两行，都算缺陷。
+
+验收时看长标题、两到三行正文、中英混排、数字单位与字体回退；在窄屏和放大阅读后检查行间、上下区块及按钮内部。文字重叠、截断关键信息或被相邻区域压住属于未完成。先修行高、内容驱动高度和容器伸缩，再考虑减小字号。
+
+### 示例数据要像真的
+
+示例数据会暴露模板感，即使视觉层已经很好。要避开：整数指标（1,000 位用户、+10%）、张三李四和示例公司、每条都是“2 小时前”、写着“标题”“描述”的占位字、页面上反复出现的“了解更多”“立即开始”。真实数据是不整齐的：1,238 位用户、+1.83%，时间有“刚刚”“昨天 16:12”“3 月 14 日”；名字有长有短，顺带验证长名字的排版。按钮说出具体动作，例如“保存草稿”“周二发送”。一页上有很多演示（组件目录、模板库、功能展示）时，让它们共用一个具体的虚构场景：同一个产品、同一批人、同一组文件和数字，演示之间互相呼应，比各自编一条“示例标题”可信得多；不要把库名、技术栈当成演示内容。
+
+## 色彩与表面
+
+颜色按文字、背景、动作、选中与状态等含义使用。品牌色与语义状态可以共存，但不能只靠颜色区别重要状态。
+
+边框、阴影、材质和渐变要与方向一致，并帮助分层、表达氛围或建立品牌识别。不要把紫色、圆角、渐变列为一律禁用；问题在于无意义重复、主次混乱和不适合任务。
+
+避免每张普通卡片都使用不同的强调色、重边框与重阴影。相同层级保持一致重量；内部嵌套轮廓与外部容器协调。
+
+配色做两个自检：去掉所有发光和模糊后，配色是否还成立；能否说出一个用类似配色的成功产品或出版物。表面层级优先用色温和色相的偏移来区分，而不只靠明暗；背景用带一点温度的中性色；选了黑白方向时，纯白和接近纯黑都可以用，层次靠几级灰来分。
+
+质感按调性的完成度取用，不混用：
+- 精致一端：表面的高光、层次柔和的阴影、细微的冷暖交叉色、细线分隔。
+- 粗粝一端：手工和印刷留下的痕迹，从这个方向的生成引擎里找，不套一组固定的道具。
+
+核对文字、控件边界、焦点和选中态在实际背景上的可辨认性，尤其是图像、透明和动态背景。遵循项目已有的可访问性目标；基础阅读与操作不能依赖猜测。
+
+## 控件与图标
+
+同一界面维持一致的图标语言、光学大小与文字对齐。通用图标优先使用成熟资源；特殊品牌插图单独制作，不为每个标题机械添加图标。
+
+可点击元素需要可识别的入口及相应反馈。默认、按下、聚焦、选中、禁用与处理中表达不同含义；鼠标悬停不能替代触屏与键盘入口。反馈变化保持点击区域与邻近布局稳定。
+
+陌生图标配可见文字；纯图标按钮仍需可访问名称。箭头符号有含义：↗ 表示打开新页面或外部链接，提交、检查这类原地动作不用它。静态标签和装饰不要伪装成按钮，行内按钮不要误触外层卡片动作。
+
+### 图标库也会趋同
+
+模型的默认是 Lucide 或 Heroicons：24px、2px 描边、圆头端点。库本身没有问题，问题是每个方向都用同一套、同一种摆法。图标和字体一样是方向的一部分，在方向卡里写明用哪一套、什么粗细和端点，或者干脆不用。
+
+| 方向的气质 | 可以考虑 | 特点 |
+| --- | --- | --- |
+| 精致、编辑、奢侈 | Phosphor 的 Thin 或 Light，Iconoir | 细描边，配细字重的衬线或无衬线 |
+| 工业、仪器、企业工具 | Carbon，Material Symbols 的 Sharp，Radix Icons | 直角端点、网格严格；Radix 专为 15px 的紧凑界面设计 |
+| 友好、圆润、消费 | Phosphor 的 Fill 或 Duotone，MingCute | 圆角端点，实心或双色 |
+| 中文产品，需要大量业务图标 | IconPark，Remix Icon | 覆盖面广；IconPark 能调描边粗细、端点和主题 |
+| 需要连续调粗细和填充 | Material Symbols | 可变字体，填充、字重、光学尺寸都能连续调节 |
+| 像素、游戏、复古 | Pixelarticons | 像素网格 |
+| 品牌标志 | Simple Icons | 各品牌标志的矢量形状 |
+
+用 Iconify 可以按名称取到上面大多数库的单个 SVG。
+
+- **一个产品只用一套。** 需要补缺时，挑描边、端点和圆角一致的，统一成相同的画布尺寸和描边宽度。
+- **粗细跟字重走。** 图标描边接近同尺寸正文的笔画粗细：细字配 1–1.5px，粗黑体配 2px 以上或实心。图标尺寸约为字号的 1–1.25 倍，按视觉中心和文字对齐，不按外框。
+- **能不用就不用。** 编辑类方向常用字符本身：→ ↗ ※ §、编号、缩写。只在能加快识别的地方用图标。
+- **品牌时刻手绘。** 核心动作、空状态这类少数位置，可以用方向自己的线条语言画专属 SVG；通用动作仍用库。
+- **小样内联。** 自包含小样只内联用到的 SVG，不引用图标字体或 CDN。存量项目沿用已有的库，换库属于改版。
+- **核对许可。** 多数是 MIT、Apache 或 ISC；SF Symbols 只能用在 Apple 平台的界面里，不能用于网页；需要署名的库按要求署名。

package/dist/templates/common/bundled-skills/atw-prototype/references/visual-review.md

@@ -0,0 +1,63 @@
+# 视觉评审协议
+
+## 评审者的独立性
+
+选择能实际看图的隔离执行者，不固定供应商、模型价格或参数规模。遵循用户的模型偏好和预算，不假定更贵必然更懂设计。
+
+首次评审与后续独立复查均使用新上下文。只传当前版本的必要证据，不继承制作对话，也不将旧评审粘进去。主 Agent 保留历史，用于判断建议是否反复和修改是否有效。
+
+没有隔离看图能力时，主 Agent 可以直接检查当前画面，但不能称为独立评审。不能看图时只给结构或源码诊断，不根据文件名猜测画面。
+
+## 交接内容
+
+| 提供 | 不提供 |
+| --- | --- |
+| 用户任务、受众、交付范围和目标设备 | 制作者的论证、已经投入的时间 |
+| 已确定的方向、品牌与不可改变约束 | 源码、实现细节与技术借口 |
+| 当前版本截图，注明页面、状态与逻辑视口 | 旧版本截图、旧评分和旧评审结论 |
+| 已实际查看的必要参考与其用途 | 预设问题清单、希望评审者赞同的答案 |
+| 需要评估的可见状态或过程证据；记忆点是动效时，一段 3–5 秒录屏或开始、中间、结束三帧，并写明触发它的动作 | “必须给到某个分数”等通过暗示 |
+
+有记忆点时，评审单独回答：这一刻是否让人记住，动作和结果能否一眼对上。只有静态截图时，评审记录写明记忆点没有评审。
+
+新评审者需要理解任务约束，不能只凭一张图自由改题。参考图用于说明方向或质量基线，精准还原任务除外，不作为要求照抄的目标。
+
+截图文件必须能被评审者访问。交接前确认文件属于当前版本；长页同时提供整体与必要局部，细节图不能替代整体构图。交互只能依据提供的状态与过程证据判断，单张截图不能证明提交或键盘行为正确。
+
+## 可直接使用的评审任务
+
+> 根据提供的用户任务、设计方向、约束和当前画面评审设计。先用一两句话说出这个画面想成为什么体裁和风格；再设想这一体裁里顶尖的设计团队会怎样完成同一任务，可以举一两类真实可参照的作品；然后指出当前画面与那个标准之间差距最大的一到三处。先看主构图、阅读顺序、主视觉和内容与操作的关系，再看排版、空间、色彩和细节。留意过度、夸张或一看就是模型生成的做法并扣分，例如首屏左边大标题、右边说明或图片的默认分栏，无来由的渐变与发光，处处圆角卡片，表情符号图标、随意给文字上色、空泛或晦涩的比喻式文案。画面里多个元素同时争当主角、处处都在用力，也算问题；反过来，处处及格却没有一处让人记住，也指出来，并说出最值得集中发力的位置。留意重复的线框：同一处分隔叠了好几条线，留白已经分开的地方又加线，或者每个层级都画一遍线，让画面发碎。承担风格和结构的线不算问题。单侧的彩色边线（引文、提示、反馈、当前项左边的一条色条）也算问题。画面上的制作说明，例如“示例”“待核实”“示意图”“未接入”，也列进可以直接删掉的文字。体裁指产品本身，例如展览落地页；借用的其他媒介只是风格来源，不按“像不像那个媒介”评判，也不为了更像而建议补上更多部件。如果是工具或后台，再说出一屏能看到几个对象、主动作离当前对象有多远，并和这一体裁里最好的工具比较密度。另外单独列出两类小问题：可以直接删掉的文字，以及对齐、圆角、阴影、标点、状态这类看得出的细节瑕疵；表格和列表要放大看，各列的行线和基线是否对齐。每处问题写清位置、观察、影响和可执行的调整方向，必要时给伪代码或属性关系，不写含糊的散文。敢下判断，给出有主见的建议，不退回安全、容易的做法。区分可观察缺陷与风格偏好；没有明显问题时直接说明，不为凑数提出修改。最后按 10 分制打分，表示当前画面离顶尖水准还有多远。只提供评审，不修改文件，不启动其他评审者。未看到或无法验证的内容明确说明。
+
+如果有同类的优秀作品截图，更好的做法是把它们和当前画面放在一起，例如四张专业作品加一张当前截图，请评审者按完成度和品味排序并说明差距。有视觉基线的比较比“想象顶尖团队”更稳定。这些作品是基线和情绪板，不是要照抄的目标。
+
+用“顶尖团队会怎么做”作为参照，是为了拉高标准、让建议有方向，不是要求照抄某个作品。评审只给方向和具体修改点，不自己重做页面；让评审者直接重做通常时间和成本都会翻倍。
+
+主 Agent 在任务后附实际材料。没有真实材料时不能原样发送模板并让评审者自行想象。
+
+评审同时核对设计北极星是否在构图、字体、素材和交互中形成呼应，突破是否增强主题，以及是否用冗余文字和层层容器掩盖薄弱的主视觉。阅读尺寸下的文字碰撞、过小正文和错误裁切应直接指出；不要仅凭整体缩略图判定可读性通过。
+
+## 反馈格式
+
+先用短段落说明当前画面如何表达任务与方向。随后按影响列问题，每项包含：
+
+- 位置：页面、区域、状态或元素。
+- 观察与证据：实际看到了什么；不能只说“普通”“不高级”。
+- 影响：妨碍了识别、任务完成、视觉焦点或选定方向中的哪一项。
+- 建议：可执行的调整，必要时提供布局示意或属性关系；不猜不存在的文件与行号。
+- 验证：修改后应检查什么，并指出是否只是主观偏好。
+
+10 分制评分用来衡量差距。分数必须附带具体差距，只有数字的评审不算有效。同一评审模型的前后分数可以比较；不同模型的数值不直接比较，也不把分数当作审美事实。分数高但用户不喜欢时，以用户判断为准。
+
+## 主 Agent 如何处理反馈
+
+先处理任务阻碍、内容错误与明显视觉层级问题，再处理有依据的精修。将接受的反馈映射到实际实现；用户指定的风格不能被评审者随意替换。
+
+评审单独列出的“可以直接删掉的文字”默认照删；只有删了会影响理解时才保留，并在记录里写一句理由。
+
+多个评审对不同方向给出同一条建议时，分别在每个方向里找它自己的落地形式，不用一种实现套到所有方向上。
+
+建议违反用户约束、仅表达另一种偏好或缺乏证据时，可以不采纳并保留简短理由。为了更像借用的媒介而增加部件、线框或装饰的建议，先对照北极星判断，通常不采纳。一次完成相关改动后集中取证；不每改一个细节就重新派发。
+
+记录版本、已接受改动、未解决问题与检查结果。保持相当的视口、内容和状态进行前后比较；后续独立评审只看当前版本，前后收益由主 Agent 检查，重大主观取舍由用户判断。
+
+出现持续换风格、互相推翻或细节调整无可见收益时停止美学循环，保留最符合任务与方向的版本。停止不能掩盖仍然存在的功能缺陷或未经验证的部分。