@chinhae/atw-cli 0.5.0 → 0.7.0

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

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

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

@@ -0,0 +1,25 @@
+# 说服型页面首屏骨架
+
+落地页、品牌页、产品发布页、展览页等以说服、传递理念为主的页面，按本规范选定首屏骨架（整体设计方向流程见 [设计方向](design-direction.md)）。
+
+模型最顽固的习惯是左右分栏，它在写文案之前就定下来了：先想好标题、一段说明、一个按钮，摆好就是左右两栏。所以骨架要在写任何文案之前决定。
+
+每个方向先从下表选一个首屏骨架，再用 3–5 个方框画出首屏线框：每块是什么、占首屏多大面积、阅读从哪里开始。
+
+| 骨架 | 首屏长什么样 |
+| --- | --- |
+| 满版图像压字 | 一张图占满首屏，标题和动作压在图的安全区里 |
+| 居中单一物件 | 一个物件或一句话居中，四周是大面积空白 |
+| 画面即界面 | 首屏就是产品界面或一件实物本身，标题、导航和按钮都长在它上面 |
+| 满版文字 | 文字本身就是画面，字大到占满首屏、跨过边缘或被裁切 |
+| 通栏上下堆叠 | 通栏大标题横跨整个宽度，下面紧接内容 |
+| 网格拼贴 | 多块内容同时出现，按网格或拼贴排列，没有单一主角 |
+| 纵排或斜向 | 文字竖排、斜切或旋转，打破从左到右的阅读 |
+| 左右分栏 | 文字一侧，画面一侧。这是模型的默认，一轮最多一个方向使用，并写出为什么非它不可。另一侧必须是跨越结构的图像、色块或图形装置，不能是装在卡片里的产品界面 |
+
+规则：
+- 同一轮的方向，骨架互不相同。
+- 所谓“大标题九栏、说明三栏”同样算左右分栏。
+- 骨架定好之后再写文案。文案去适应骨架，不让骨架去适应“标题 + 说明 + 按钮”的组合。
+
+构图的大胆程度和调性无关。安静精致的产品，一样可以把一句话放在空白首屏正中，或让纵排标题贯穿整屏，或让界面本身占满首屏。调性决定音量，骨架决定结构；不要因为调性偏安静，就退回左右分栏。

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

@@ -75,7 +75,7 @@ macOS/Linux 通常使用 `python3`，Windows 通常使用 `py -3`；执行前确
 
 生成器根据本轮项目和候选内容生成 `fingerprint`。候选内容变化后会形成新一轮存储身份，避免把旧选择误用于新作品。点“选择”时同时复制一句简短的文字：轮次、编号和方向名，有备注时再附一行，例如“<轮次>：选 03 <方向名>”，并在底部提示已复制的内容。改完备注后再点一次“已选择”重新复制；选另一个方向会直接替换当前选择。
 
-用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到项目设计说明，继续实现。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
+用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到设计说明，回到 [界面原型](../ui.md) 第一段接着做。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
 
 ## 检查实际结果
 

package/dist/templates/common/bundled-skills/atw-prototype/ui.md

@@ -0,0 +1,194 @@
+# 界面原型
+
+界面原型分两段：
+
+- **第一段：选方向。** 先认品类、拆标杆，用文字写出三个风格和结构都明显不同的方向请用户选；用户想看实际画面时，再把三个方向各做成一张首屏放进同一个对比页挑，并说出具体喜欢和不喜欢哪里。
+- **第二段：深化成可交互原型。** 只在问题包含“用起来对不对”时才做：把选定方向做成完整页面，接上按 [logic.md](logic.md) 写的纯逻辑模块，让人能把真实业务流程完整点一遍。
+
+两段的产物都是用来做决定的，不是正式代码。选定之后的正式界面由 atw-ui 按设计说明重新实现。
+
+如果问题只关于逻辑或状态、与外观无关，分支选错了，改用 [logic.md](logic.md)。
+
+## 什么时候用
+
+- “这个页面应该长什么样？”
+- “正式做之前，我想先看看这个后台有几种可能。”
+- “给设置页换个布局试试。”
+- “这个下单流程连同规则，用起来顺不顺？”（两段都做）
+- 任何用户本来要在脑子里对着三张模糊草图纠结一整天的时候。
+
+## 承载方式：优先挂在已有页面上
+
+要做出画面时才选承载方式：第一段的三个首屏，或第二段的完整页面。用户从文字里就选定了方向、又不做第二段时，不建任何页面。
+
+界面原型**贴着应用的其他部分**才好判断：真实的顶栏、侧栏、数据和密度。一个孤零零的新页面是真空，每个方案单独看都还行。所以只要有合理的宿主页面，就优先方式 A。
+
+### 方式 A：在已有页面上调整（优先）
+
+路由已经存在。各方案**在同一路由上**渲染，用 URL 参数 `?variant=` 切换。现有的数据获取、参数和权限都保留，只换渲染部分。
+
+还没有页面、但*自然属于某个页面*的东西（后台里的新区块、设置页里的新卡片、现有流程中的新一步）也算方式 A：把方案挂在宿主页面里。
+
+这些方案同时放进对比页作为本机地址候选（`"kind": "url"`），并把当前页面作为基线（`"baseline": true`），每个方向都和现状对照。见 [风格对比页](references/style-explorer.md)。
+
+### 方式 B：独立小样（没有宿主页面时）
+
+只有确实没有可挂靠的页面时才用，例如全新的顶层界面、或嵌不进任何现有位置的流程。先确认：真的没有现有页面能挂吗？空页面会掩盖有数据时才暴露的设计问题。
+
+方式 B 默认做成自包含的单个 HTML 小样，直接放进对比页，双击就能打开，不需要服务器。小样必须用到项目里的组件或框架时，按项目已有的路由约定建一个一次性路由，名字里带 `prototype`，同样用 `?variant=` 切换，并作为本机地址候选放进对比页。
+
+## 第一段：选方向
+
+### 1. 写下问题，定方向数量
+
+默认写 **3 个方向**。用户要更多时照做，但超过 5 个就不再是“明显不同”而是噪音，上限 5。窄小的任务不强求多方案；任务明确只要一个方向时只写一个，见第 6 步。
+
+把计划写成一句话；做出画面时放在原型所在位置或文件顶部注释里：
+
+> “设置页的三个方向，先用文字问；要看画面时用 `?variant=` 在现有 `/settings` 路由上切换，并汇总到对比页。”
+
+用户在不在场都适用。
+
+### 2. 认品类，拆标杆，写方向卡
+
+方向未定时按 [设计方向](references/design-direction.md) 的顺序做：先认品类、拆标杆，标杆的真实画面存进 ATW 任务目录的 `references/`（没有任务时放在原型旁边），不写进技能安装目录；再从产品题材、受众和使用场合推出调性；每个方向从一个具体的生成引擎出发，色彩按“定色彩”的四步从产品推出；写文案之前先定首屏骨架，说服型页面按 [说服型页面首屏骨架](references/direction-persuasion.md) 选，内容和工作区页面的首屏就是第一排内容；为每个方向填方向卡，最后逐条做差异检验。
+
+这一轮几个方向共用调性和标杆与取舍，每个方向只填北极星、生成引擎、首屏骨架、字体、色彩、主视觉、图标和控件语法；其余各栏在方向选定后补齐，见第 7 步。
+
+方向**必须在结构上不同**：布局、信息层级、主要操作方式都不一样，不只是换颜色。三个微调过的卡片网格不是界面原型，是墙纸。两个方向太像时，回到骨架重选其中一个，不靠换装饰补救。
+
+方向由用户的品味来定，不直接采用模型自己想出的方向。任务目录里已有 `ui-direction.md`，或用户明确指定了一个完整的方向时，跳过第一段，直接进入第二段或交给 atw-ui。用户只给了参考图、品牌规范或说了想要的风格，不算给定方向：仍写三个方向、走第 3 步，三个方向怎样写见第 6 步。
+
+### 3. 先用文字问一次
+
+方向卡写完，不急着做页面。把每个方向用三四行写给用户：它给人什么感觉，首屏长什么样，用什么字体和色彩，主视觉靠什么。附上你推荐哪一个和理由，然后问：按其中一个定下来，还是把三个都做成首屏放在一起比。发给用户后这一轮结束。
+
+- 用户选了一个，或者从描述里已经说清想要什么：方向就定了，定下的就是这一个方向。第一段不做首屏，也不做对比页：按 [设计方向](references/design-direction.md) 的“差异检验”把它和拆过的标杆并排比一次，确认不撞脸，然后到第 7 步补齐方向卡、写设计说明。完整页面在第二段或 atw-ui 里做。
+- 用户想看实际画面：按第 4 步把三个都做成首屏。
+- 之后凡是要做出几个候选让用户挑，都先这样用文字问一次：用户从文字里定得下来，就定选中的那一个，不把几个候选都做成画面。
+
+### 4. 用户要看实际画面时，做三个首屏
+
+每个方向都是一张真实的首屏，骨架、字体、色彩和主视觉都拉开。只做看得出风格所需的东西：
+
+- 每个方向一个文件（方式 A 是一个方向组件，导出清楚的组件名，例如 `VariantA`、`VariantB`、`VariantC`；方式 B 是一个 HTML）、一个视口、只有主状态；不写交互，不做响应式和动效，不取证，不派评审。
+- 几个方向共用同一份示例文字和数据，只写一次；页面的用途、核心内容和主要操作也相同。结构和样式各写各的：不用同一个模板换几组样式来生成，那样几个方向的骨架天生是同一个。
+- 方式 A 用项目已有的组件库和样式体系（TailwindCSS、shadcn、MUI、纯 CSS 等）；方式 B 的独立首屏不受此限，但图标只内联用到的 SVG，不引用外部资源。
+- 主视觉靠图的方向，生成一张，至多重新生成一次；其余图位先用从页面取色的色块占着。
+- 每个方向用宿主的浏览器工具截一张图自己看过，改掉重叠、裁切和明显的粗糙就交。
+
+首屏选能暴露方向优缺点的那一页：含复杂表单的产品不能只做封面。示例内容按真实产品的样子写，避免整数指标和“标题”“描述”这类占位字；画面上不出现“示例”“示意图”“按钮未接入”这类制作说明，这些写进交付说明。视觉层级、字体、色彩和留白的判断见 [视觉语言](../atw-ui/references/visual-language.md)。
+
+按 [风格对比页](references/style-explorer.md) 准备 `manifest.json`，把方向卡里的北极星、字体、色板和特征写进去，用内置生成器组装成一个离线 HTML。不要每次自己重做对比工具。对比页和 manifest 放在 ATW 任务目录（没有任务时放在原型旁边），不写进技能安装目录。
+
+### 5. 交对比页，版式也先用文字问
+
+把对比页交给用户，这一轮到此结束：附上推荐理由，请用户选一个方向、说出具体喜欢和不喜欢哪里，并说明想比较不同的版式也可以说。用户只说“再高级一点”这类模糊词时，用设计方向里的翻译表追问，或拿两张首屏让用户比较。三个首屏和版式变体不派评审；用户明确要求时，才按 atw-ui 的 [视觉评审派发协议](../atw-ui/references/visual-review.md) 评一轮。协议里说的“本 Skill 目录”是 atw-ui 的目录：给评审者的是 [评审手册](../atw-ui/references/reviewer-manual.md) 的绝对路径。首屏没跑截图工具，没有 `report.json`，不交默认做法提示，交接里写明未跑截图工具。
+
+用户要比版式，先用文字写出两三种骨架的差别；从文字里定得下来就按选中的定，要看实际画面再做成首屏，连同选中的那一版放进对比页再选一次。版式之间保持选定方向的字体、色彩和控件语法，只在骨架、主视觉的摆法和页面结构上拉开。用户只回了选哪个，就把意见并进去，到第 7 步；想把两个方向拼在一起的，先做出拼合后的首屏给用户确认。
+
+### 6. 哪些情况不这样走
+
+- 只要设计说明时不做页面，用文字写下方向的决定。
+- 用户已经给了参考图、品牌规范或说清了风格，风格就定了：三个方向都留在这个风格里，只在骨架、主视觉和页面结构上拉开。
+- 用户说了“你定”“直接做”，或者无人值守时，不问：三个首屏仍做出来放进对比页留档，把三张截图缩到 480px 宽并排看一次，自己选定并写明理由，接着到第 7 步。
+- 任务明确只要一个方向时不问也不做对比页，直接写方向卡，再按 [设计方向](references/design-direction.md) 的“差异检验”把它和拆过的标杆并排比一次，确认不撞脸。
+
+### 7. 写设计说明
+
+方向选定后先把方向卡补齐：第 2 步没填的页面结构、各区块的形式、动效、结构性突破、记忆点和放弃什么都填上，“标杆与取舍”里写明标杆画面的存放路径。
+
+再写一份简短的**设计说明**：用户任务、内容与主动作、选定方向（附补齐后的方向卡，标杆与取舍、各区块的形式、控件语法和动效四栏都在）、用户的喜欢与不喜欢、视觉关系、关键状态、设备约束和验收重点。放在 ATW 任务目录的 `ui-direction.md`；已有说明直接更新。这份说明是第二段和 atw-ui 的依据。
+
+## 第二段：深化成可交互原型
+
+只有问题包含业务规则或完整操作流程时才做；只问外观时，第一段选定后就收尾。
+
+### 1. 先写逻辑模块
+
+按 [logic.md](logic.md) 第 2 步，把业务规则写成一个纯模块（reducer、状态机或纯函数），不碰 DOM。这部分以后能整体搬进正式代码，是第二段最值得保留的产物。
+
+### 2. 选定方向做成完整页面
+
+把选定方向做成完整页面（做过首屏的从首屏扩展），作为逻辑模块外面的一层外壳：页面只调用模块、渲染模块返回的状态。关键状态都要在界面上有样子——空、加载、成功、失败、被拒绝的非法操作——不只做漂亮的默认状态。
+
+方向卡里的记忆点（某个动作的反馈、完成的那一刻）在这里做出来；动效遵循方向的调性。修改数据的动作一律经过逻辑模块，接口用桩代替，不接真实后端。
+
+默认只深化**一个**选定方向。用户要求同时比较两三个方向的完整体验时，多个外壳共用同一个逻辑模块，逻辑只写一次。
+
+### 3. 加一个状态抽屉
+
+logic.md 里的“当前状态面板”和“引导演练”放进一个可开关的抽屉，供不写代码的人逐步走查业务规则：
+
+- 抽屉视觉上明显不属于设计本身（例如高对比的面板），和浮动切换条一样，不参与设计评判。
+- 抽屉里保持朴素：标签式的状态字段、标出刚变化的部分、按场景划分的演练按钮；不加动画。
+- 开始演练时重置到已知初始状态。
+- 生产构建中隐藏。
+
+### 4. 承载
+
+- **没有现成项目**：单个 HTML，脚本内联，双击即可打开；放进对比页时加 `"interactive": true`，单张查看时就能直接操作。
+- **有现成项目**：挂在已有页面上，用 `?variant=` 切换；作为本机地址候选放进对比页。
+
+## 接线（方式 A）
+
+在路由上建一个切换组件：
+
+```tsx
+// 伪代码——按项目框架改写
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+已有页面：现有数据获取都放在切换组件之上，各方向只替换渲染的子树。一次性路由：同一个切换组件挂在 `prototype` 路由下。
+
+## 浮动切换条（方式 A）
+
+屏幕底部居中、固定位置的小条，三部分：
+
+- **左箭头**：切到上一个方向（循环）。
+- **方向标签**：当前方向的编号，方向有名字时一并显示，例如 `B — 侧栏布局`。
+- **右箭头**：切到下一个方向（循环）。
+
+行为：
+
+- 点箭头时用框架的路由更新 URL 参数（Next 用 `router.replace`，React Router 用 `navigate` 等），保证方向可分享、刷新不丢。
+- 键盘 `←` `→` 也能切换。焦点在 `<input>`、`<textarea>` 或 `[contenteditable]` 上时不拦截方向键。
+- 视觉上明显区别于页面（例如高对比胶囊、轻阴影），一看就不属于被评判的设计。
+- 生产构建中隐藏——用 `process.env.NODE_ENV !== 'production'` 或等价判断，避免误合并后把切换条发给用户。
+
+切换条做成一个共享组件，放在项目存放共享界面组件的位置。对比页适合并排比较；切换条适合在真实页面里来回看，开发服务器禁止被嵌入时也只能靠它。
+
+## 交给用户
+
+做了画面时，给出对比页路径、页面地址和 `?variant=` 的取值；第二段还要说明状态抽屉怎么打开、有哪些演练场景。用户有空时会翻看。最有价值的反馈常常是 **“我要 B 的顶栏配 C 的侧栏”**——那才是他们真正想要的设计。
+
+交付说明里写清：哪些是模拟数据、生成图片、未接入的动作；实际查看过哪些视口；哪一步没做以及原因。
+
+## 记录结论，收起原型
+
+用户选定后，先记录结论——选了哪个方向、为什么、用户的喜欢与不喜欢——更新到 `ui-direction.md`，并把影响需求的部分写进任务的需求文档。然后按 [SKILL](SKILL.md) 的规则收起原型。所有方向、切换组件、对比页和 manifest 进入一次性分支，作为一手资料保存，不进主分支：
+
+- **方式 A**：主分支上去掉所有方向和切换条，现有页面保持原样。
+- **方式 B**：主分支上去掉一次性路由和切换条。
+- **第二段**：验证过的逻辑模块搬进正式代码；页面外壳留在一次性分支。
+
+正式界面交给 atw-ui，按 `ui-direction.md` 在正式代码里重新实现。留在主分支的方向组件和切换条很快会腐烂，还会误导下一个读代码的人。
+
+## 反模式
+
+- **不问就做三个首屏。** 用户在场时先用文字问一次；从文字里定得下来，就不做首屏和对比页。
+- **方向之间只差颜色或文案。** 那是微调，不是原型。真正的方向在结构上互不相同。
+- **按明暗分方向。** “一个亮、一个暗、一个暖”是最常见的失败；每个方向要有自己的色彩身份。
+- **默认左右分栏。** 一轮里最多一个方向用左右分栏，并写出为什么非它不可。
+- **方向之间共享太多代码。** 共享 `<Header>` 可以；共享 `<Layout>` 就失去意义了。每个方向都应该能推翻布局。
+- **把方向接到真实的写操作上。** 只读原型没问题；需要修改数据时经过逻辑模块、指向桩。问题是“它应该长什么样、用起来对不对”，不是“后端通不通”。
+- **把业务逻辑写进页面事件里。** 第二段的规则必须在纯模块里，否则既不能搬走，也没法在状态抽屉里走查。
+- **把原型直接提升为正式代码。** 原型代码是在原型约束下写的（没有测试、错误处理很少）。正式实现交给 atw-ui 和实现阶段重新写。

package/dist/templates/common/bundled-skills/atw-reflect/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: atw-reflect
+description: "复盘（reflect）：从这次对话里找出值得改进的地方，以便同样的问题下次不再出现。派三个子代理分别从判断、工具、发散三个角度看，再由一个子代理合成「采纳 / 驳回 / 建议开任务」；每条采纳写明去处（项目规范、某个 skill 的附加说明、项目里新建的 skill），等用户同意才写；不建任务、不改代码。只有用户能启动。用于用户说「复盘一下」「回头看看这次对话有什么值得改进」「这次踩的坑怎么让下次不再犯」时。"
+disable-model-invocation: true
+---
+
+Only the user starts this skill. You never invoke it yourself — not when a task is archived, not when the user corrects you. `finish-work` only mentions that it can be run.
+
+# Reflect
+
+Look back over this conversation for lessons worth keeping, so the same problem does not come up again, then route each one to where it belongs once the user agrees.
+
+Skip when the conversation is trivial, off-topic, or already covered by a skill that was followed correctly: say plainly that there is nothing worth keeping and stop. Do not make lessons up to fill the reply. A one-off is not a lesson.
+
+This skill changes no code and creates no task. It writes only two things: the transcript file of step 1, deleted when the reflect ends, and the adopted items the user agrees to in step 5.
+
+## 1. Read this conversation
+
+Find this conversation's id with the same `resolve_context_key()` that `decision_log.py run` uses — it takes `ATW_CONTEXT_ID` when the tool passes it and otherwise the id the tool itself sets, such as `CODEX_THREAD_ID` on Codex:
+
+```bash
+python3 -c "import sys; sys.path.insert(0, '.atw/scripts'); from common.active_task import resolve_context_key; print(resolve_context_key() or '')"
+```
+
+Then read this conversation with each command and the start and end of its result — the reading the log self-check uses — into a file named for this conversation:
+
+```bash
+mkdir -p .atw/.runtime && atw mem extract --context <id> --tools > .atw/.runtime/reflect-<id>.txt
+```
+
+Pass the file's absolute path to each reviewer. Delete the file when the reflect ends — after step 6, or wherever you stop.
+
+When the conversation cannot be read — the id prints empty, the tool is not one of the four where `atw mem`'s `--tools` reading has been verified (Claude Code, Codex, pi, omp), or `atw mem extract` fails (give its error) — write a tight summary of this conversation instead, pass that to the reviewers, and tell the user the review rests on a summary and why. Never read another conversation in its place.
+
+## 2. Three reviewers in parallel
+
+Dispatch three sub-agents in one message, using the current tool's own sub-agents; no model from another company is needed. Give each its template verbatim, with the transcript path or the summary filled in where marked:
+
+| Lens | Template |
+| --- | --- |
+| Judgment | `references/judgment-reviewer.md` |
+| Tooling | `references/tooling-reviewer.md` |
+| Divergent | `references/divergent-reviewer.md` |
+
+The reviewers read and look things up; they write nothing. They return their findings in their reply. On a tool without sub-agents, apply the three lenses yourself one after another, each from its template, and keep the three outputs apart.
+
+## 3. Merge
+
+One more sub-agent gets `references/synthesizer.md` verbatim, with each reviewer's full output filled in where marked. It sorts the findings into 采纳 (adopt), 驳回 (reject) and 建议开任务 (suggest a task), and proposes a destination for each adopted item. On a tool without sub-agents, merge them yourself from that template.
+
+## 4. Move what a check could enforce
+
+Move any adopted item that a test, lint rule, script or other check would enforce more reliably to suggest a task. Written rules are for what no check can enforce — the same order `atw-update-spec` follows in its step 2: remove the mistake by design, then types, then a test, and written rules last.
+
+## 5. Ask before writing
+
+First read the skill notes that exist — `.atw/skill-notes/*.md` and `~/.atw/skill-notes/*.md` — and compare each with its skill as installed now. Remind the user of any note that the skill as installed now already covers, that contradicts the skill, or that is plainly stale (it names a file, command or step that no longer exists). Only remind: never delete or edit a note. The user decides.
+
+Show the merger's full output — adopt, reject, suggest a task — then list each adopted item with its destination and wait for the user's consent. They may pick some items and change any destination. Write nothing before they agree; never write on your own. Then write only what they agreed to, where they agreed:
+
+- **A project convention → the project spec.** How this project's code is written goes into `.atw/spec/` through `atw-update-spec`. Write it as a written rule only; an item a check would enforce better belongs in suggest a task — move it there and tell the user, rather than change code or write a ticket.
+- **Better behaviour of an existing skill → that skill's notes.** `.atw/skill-notes/<installed name>.md` for the project — it travels with the repository and the whole team uses it — or `~/.atw/skill-notes/<installed name>.md` for the user alone, on every project on this machine. Ask the user, item by item, which of the two. Write short, direct instructions about how the skill should behave differently, not a second copy of the skill. Never edit an ATW skill's installed copy and never copy it under a new name. Notes exist only for ATW's own skills and commands — the ones whose installed copy opens with the paragraph telling the AI to read its notes. A project's own skill, whose name does not start with `atw-`, is edited directly instead. Any other skill — one from a third party or in the user's personal skill directory — gets no notes and no edit: list the finding for the user as a suggestion only and write nothing.
+- **A missing whole capability → a new project skill.** Create a skill whose name does not start with `atw-`, the same content in every skill directory the project's tools use — each directory that holds ATW's own `atw-*` skills, such as `.claude/skills/` and `.agents/skills/`. Its description says when to use it.
+
+An ATW skill that did not start when it would have helped cannot be fixed by its notes, which are read only once the skill runs, nor by its description, which ATW owns: route that finding to the project spec, as a line saying when this project uses that skill.
+
+Suggest-a-task items are only listed for the user: reflect creates no task and changes no code. Whether to open one is the user's call.
+
+## 6. Short list
+
+End with a short list, no preamble:
+
+- Written: `<path>` — what changed, one line each.
+- New skills: `<path>` — one line each (rare).
+- Suggested tasks: the pattern and the check that would enforce it, one line each.
+- Suggestions for other skills: the skill and the change, one line each — nothing was written.
+- Rejected: one line per rejected finding, with the merger's reason.

package/dist/templates/common/bundled-skills/atw-reflect/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "ATW Reflect"
+  short_description: "复盘这次对话，找出值得改进的地方，经你同意再写"
+policy:
+  allow_implicit_invocation: false