@xiaobuyu/nodesign 0.0.1

package/server/engine/plugins/nodesign/skills/site-craft/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: site-craft
+version: 0.5.0
+description: NoDesign 站点设计方法论 —— 静态站点（手写起步，CDN 库与构建按需），先把用户脑子里的感觉翻译成一个真实存在的风格名给他挑，再对齐一页的气质，然后铺开全站。含骨架推导、风格命名与翻译词典、排版与色彩系统、图像手法（抠图叠层）、中文排版基线、反默认清单、构建道配方（React / vite / Tailwind / 组件库站点）。当用户要做网站 / 官网 / 个人站 / 落地页 / 作品集 / 博客 / landing page / 多页站点，或要做带功能的站（登录 / 列表 / 表单 / 后台 / 管理界面 / 可运行原型，数据用模拟的），或要"能发出去的一个地址"时使用。不要用于 deck / 幻灯片 / PPT（那是 deskskill-engine-mini）。
+---
+
+# 核心守则：先定气质，再铺页
+
+跟 deck 同一条路：**命名 → 试作 → 给看 → 改 → 用户说"就这个" → 锚定 → 铺开**。
+
+命名是把他嘴里的形容词换成一个真实存在的风格名（下面单独一节），它决定试作往
+哪个方向做；跳过它直接试作，等于拿模型均值去猜他的心思。
+
+区别在试作做什么。deck 试作一页封面；站点试作**首页的上半屏加一段正文** —— 站点
+的气质八成由正文排版决定，只做个漂亮 hero 给用户看，等铺到正文那天他会说"怎么
+跟我想的不一样"。试作放 `_drafts/<名字>.html`，各自渲成卡并排给用户挑。
+
+并排的那几份是**同一个名字的不同解法**，不是几种不同风格 —— 名字在上一步已经定了，
+再摆三种风格等于推翻他刚点过的锚。例外：命名那轮没收敛（两个候选他都想看），那就
+跳过选名字，每个候选各做一份真试作、文件名带上名字并排给他挑；真稿的判别力比
+240×140 的小样高一个量级。
+
+## 骨架从一个问题长出来
+
+动手前先答：**访客带着什么来，你想让他带着什么走？**（做成一件事？记住一个印象？
+读完一篇？玩明白一个东西？）答案定了，骨架自己会长出来 —— 要一个动作就把全站
+收束到那个动作，要一个印象就让首页本身成为印象，要人读下去就把一切让位给正文。
+
+几个常见答案长出来的样子，当参考不当分类：
+
+- 「做一件事」→ 单页长滚动，一句话开场 → 证据 → 一个行动点，导航可以没有
+- 「认识一个人」→ 首页是气质本身，作品/文章各一页；个性 > 信息效率
+- 「读下去」→ 首页即目录（标题列表就很好），正文页才是全站核心
+- 「搞懂一个东西」→ 概览 + 分主题子页，导航要清楚，别炫技
+- 「在里面做事」（登录 / 列表 / 表单 / 后台）→ 数据是主角，走**应用道**：数据全用
+  模拟的但要真的跑起来，配方 Read `patterns/mock-app.md`
+
+不在这几种里的站（活动邀请 / 展览预告 / 互动玩具 / 纪念页……）多得是 —— 别硬套，
+回到那个问题现推。骨架跟上面撞了是巧合，没撞是正常。用户没说清他要什么，
+问一句，或按 brief 推两个不同答案做进试作里给他挑。
+
+## 先给风格一个名字
+
+骨架定了、动手之前，还差一步：**把他脑子里那个感觉，翻译成一个现实中真实存在的
+风格名**。
+
+用户说得出的是感觉（"高级一点""有质感""别太商务"），你能执行的是名字。形容词
+只会把你推向模型均值 —— "温暖克制的现代感"做出来就是那张 AI 默认落地页；"拼贴"
+做出来立刻就有样子，因为它在现实里有实物、有做法、有可仿照的对象。反默认清单
+说的是**别去哪**，风格名说的是**去哪**，这两件是一对。
+
+这一步的产出：**一个用户点过头的名字**。
+
+1. 从他的话里抠特征：他提到的东西、举的例子、否掉的东西，以及这个站是干嘛的
+   （个人站 / 作品集 / 同人本宣传 / 长文阅读页各有自己的风格谱系）
+2. 翻译成 2-4 个候选名字（词典在下面，那是你的词汇量）
+3. `AskUserQuestion` 给他挑：label 就是名字，`preview` 放一张 240×140 的 HTML
+   小样（全 inline style，演示这个风格的字体 / 配色 / 版式关系）。小样比找张照片
+   来得准 —— 照片是别人的作品，小样是**你打算怎么做**。
+   ⚠️ 别把网上的图片网址塞进 `preview`：只有以 `.png/.jpg/.webp` 结尾的地址才会
+   渲染成图，其余会**静默退成一行网址**，用户看到的就是一串链接
+4. 他点中的名字就是锚，试作**照着这个名字的做法做**，不是凭形容词现编
+
+⚠️ **不要为了"理解风格"去搜图**。Bauhaus、拼贴、risograph 这些名字模型脑子里本来
+就有，搜一轮只是白烧时间和上下文。
+
+⭐ 但**"看参考站"是另一回事，而且值得做**：要参考的是**版面结构**（开场是刊物封面
+还是 banner、正文页两侧的空白怎么用、滚动有没有惯性）而不是风格词条时，去看真站。
+一次真实对比：搜关键词收益为零，直接看三个站十分钟就定位到三个具体缺口。
+**别搜词，去看站**——这跟上面那条不冲突，一条说的是词，一条说的是版面。
+
+**怎么看**（2026-08-18 起有了真浏览器，不再只能截一张）：
+
+⭐ **搜索和浏览器是一套动作，不是两条路**。`web_search` 回答"哪些站值得看"，
+浏览器回答"它长什么样、怎么做到的" —— snippet 里没有版面、没有节奏、没有配色。
+所以搜完就进去看，别拿搜索结果的文字描述当参考。
+
+1. `web_search` 找到几个候选站的 URL（浏览器不管搜索）
+2. `browser_navigate` 打开 —— 它**顺手把页面摘要带回来**（标题层级 + 正文节选 +
+   站内链接），多数时候不用再 `browser_read` 一次
+3. ⭐ **顺着站内链接往里翻两三层**。首页是一个站最用力也最套路的一屏；真正能学的
+   东西在**案例页、产品详情页、定价页、博客单篇、关于页**。碰到一个好站，
+   **别截一张首屏就走** —— 能翻子页正是这条通道存在的全部理由
+   （`screenshot_url` 只能截一张，那个是"看一眼"）。JS 驱动的导航用 `browser_click`；
+   selector 够不着的（icon 按钮、画布、拖拽）用 `browser_find` 拿 ref 或
+   `browser_computer` 按截图坐标点。逛完再决定采什么，别一进门就采。
+4. ⭐ `browser_capture` 把可复用的带回来 —— 不只是截图：
+   **调色板**（带用途：底色/正文色/强调色）、**字体**（字族 + 实际字号字重行高）、
+   某一块的 **CSS 片段**、**结构三数**，以及 ⭐ **动效清单**（`kinds:['motion']`：
+   这站靠什么在动 —— @keyframes / transition / CSS 滚动驱动动画 / scroll-snap /
+   sticky / GSAP+ScrollTrigger 每个 trigger 的 start·end·scrub / Lenis 劫持 /
+   哪些元素是滚动入场、哪些随滚动走）。想看它**动起来的样子**用
+   `browser_screenshot { frames:[…], scrollBy: … }`（格数 2~30 自己定：6~10 看细节、
+   12~16 看整段、20~30 看长滚动的节奏；scrollBy 按要看的那段滚动量给）：一张按时刻拼的
+   胶片条 + 元素探针（谁在动、位移多少、什么时候）。"看全"一个参考站 = 版面（截图）
+   + 用料（palette/fonts/css）+ 骨架（skeleton）+ 动效（motion + 胶片条），四样齐了再下手。
+   ⭐ 采 token 是**多页多步**的活：从摘要里挑好两三个内页后，**一趟 `browser_batch`**
+   把它们串起来 —— navigate A → capture palette+fonts → navigate B → capture →
+   navigate C → capture，结尾自动补截图。六个回合变一个；一页一个回合太慢。
+5. 结构三数正好是上面「用户说无聊的时候」那节要数的三样。⭐ **拿参照站的数字跟你
+   正在做的那个站比**：「这个站 6 种节的形状，你现在的站 1 种」比「我觉得有点单调」
+   能落地得多。（那三个数是启发式，当对照不当真相。）
+6. 采下来的东西落在 `assets/references/web/`，**类别写在文件名里** ——
+   `.screenshot.webp` / `.palette.json` / `.fonts.json` / `.skeleton.json` /
+   `.css`（真 CSS，命中规则按级联顺序，能直接照抄）。出处在同目录 `.meta/`。
+   **下个会话还在**，所以**开工前先看看有没有现成的**，别把同一个站重逛一遍。
+
+用户桌面上有一张**浏览器卡片**：你逛到哪它就显示到哪，他随时能双击进去看、
+也能自己接手操作。所以别把浏览器停在一张错误页上就走。
+
+撞上人机验证过不去时用 `browser_request_help` 叫用户点一下 —— 但先想清楚是不是
+真需要：有些墙看的是服务器 IP，人点多少次都一样，那就换一个参考站并跟用户说明。
+
+搜图是留给**你确实不认识的具体东西**：用户点名的
+IP、角色、真人、某个具体产品型号、小众品牌 —— 那种情况才走
+`web_search { include_images: true }`，把图喂 `generate_image` 的 `referenceImages`
+当锚（完整的来源策略在首次生图时注入的 cookbook 里）。
+
+三条红线：
+
+- **形容词不是名字**。"温暖克制的现代风"是三个形容词摞在一起，不是锚。
+- **自造词作废**。名字得是**公认的** —— 你说得出它的实例、指得出现实里的作品。
+  "新中式赛博风"这种当场拼出来的词没有共识，写进锚里等于没锚。
+- **别把词典摊开当菜单让用户选**。名字是从他的话里翻译出来的；他该看到的是
+  2-4 个带小样的候选，不是一张风格大全。摊开菜单就退回模板思维了。
+
+他已经点了名字（"我要拼贴风"）的，跳过前两步直接进试作；直接甩了参考图的，
+读图读出那是什么风格、跟他确认一下名字，再进试作。名字定下来之后调 `record_decision` 落锚：`title` 名字打头
+（`风格锚 = 拼贴`），取值写进 `rationale`；⚠️ 入参是 title / rationale（都必填）/
+scope / alternatives，**没有 `topic`**。参照图留在 `assets/references/` 别删 ——
+铺到第五页跑偏时靠它回锚。
+
+### 翻译词典 —— 你的词汇量，不是给用户的菜单
+
+第三列才是这张表的价值：名字得能立刻落到代码上，否则做出来的还是"那个名字的
+均值版"。表外的风格多得是，照样现推。
+
+| 他可能这么说 | 名字 | 落到代码上是哪几条 |
+|---|---|---|
+| 手作感 / 有温度 / 像手账 | **拼贴 collage** | 微旋转 -3°~3°、`filter: drop-shadow` 不用 box-shadow、白边、元素骑线或探出边缘、纸纹底（深配方 Read `patterns/cutout-collage.md`） |
+| 干净 / 专业 / 别花哨 | **瑞士国际主义 / 网格派** | 单一无衬线字族、模块化栅格且元素严格落格、非对称排布、左对齐不居中、双色以内 + 大面积留白（具体色值仍走色彩节，别真用纯黑） |
+| 像杂志 / 有编辑感 / 高级 | **杂志编辑风 editorial** | 衬线大标题 + 无衬线正文、通栏与窄栏混排、首字下沉、图片出血、栏目名页码这类细节排版 |
+| 复古 / 怀旧 / 像老印刷 | **risograph / 活版** | 2-3 套色叠印、故意错位、纸纹噪点、低饱和荧光色 |
+| 科技 / 未来 / 赛博 | **终端 / HUD**（不是紫蓝渐变） | 等宽字、扫描线、坐标刻度与标注线、深底上单一荧光色 |
+| 可爱 / 二次元 / 谷子 | **贴纸风** | 圆角厚白边、高饱和、硬投影、元素堆叠遮挡 |
+| 安静 / 留白 / 想让人慢下来 | **日式极简** | 行高字距都拉开、正文宽收窄、近乎无彩色、层级靠留白不靠字号 |
+| 有冲击 / 反叛 / 别装精致 | **粗野主义 brutalist** | 系统默认字体、纯色硬边框、零圆角零阴影、故意的不对齐 |
+
+风格名定的是气质，下面三节（排版 / 色彩 / 图像）定的是它在这个站上的具体取值 ——
+名字选完，那三组数就有了判据，不用再凭空拍。
+
+## 排版系统：气质的地基
+
+**三个数定生死**（写进 `:root`，锚定时固化；**先定这三个数再配色**，反过来做
+配色调半天也不对味）：
+
+- **字距** `letter-spacing`：中文正文 0.02~0.04em；大标题 0 到 -0.01em
+  （汉字本身方正，字距一松就散）
+- **行高** `line-height`：中文正文 1.75~1.85，标题 1.3~1.5，比英文站需要的高
+- **正文宽**按**每行字数**定：一行 36~42 个汉字最舒服。写成 `em` 不写 `px`
+  （`--measure: 40em`），字号一变宽度跟着走；16px 正文下约 600~700px
+
+配套：正文字号 **16px** 起（屏读中文 15px 偏小，长文 17px 更舒服）；字重正文
+≥400、标题 500~600，300 只给装饰性小字。这三个数一改就是换气质，改配色只是换衣服。
+
+**标题梯度**：两级够用（页题 + 节题），最多三级。相邻级差要明显（1.6× 以上），
+差 20% 的两级读者分不出来，等于没有层级。标题跟正文拉开的方式不止字号 ——
+字重、颜色深浅、上方留白，选一两个维度用足，比每级都放大一点有效。
+
+**间距节奏是长页气质的另一半**：段间距 < 节内块间距 < 节间距，比例拉开
+（比如 1 : 2 : 4~6）。节与节之间敢留大白 —— 长页的"呼吸感"几乎全靠节间距，
+挤在一起的精致排版读起来还是喘不过气。全篇用一套间距刻度（如 8 的倍数），
+别每处现拍一个数。
+
+## 色彩方法
+
+- **一个主色 + 一套中性灰**，够做绝大多数站点。主色用在链接、细线、选中态这些
+  小面积处才显贵；大面积铺主色是海报做法，不是网页
+- **文字别用纯黑纯白**：深色文字往主色方向偏一点（比如 #1a1a1a 带一丝暖或冷），
+  背景白也可以是米白 / 暖白。整站的"温度"就是这么来的
+- **中性灰要成梯度**：正文、次要文字、注脚、分隔线、底色，各取一档，全站复用。
+  灰是排版里用得最多的颜色，梯度乱了整站就脏
+- 深浅模式不用都做，跟用户确认默认哪种就好
+
+## 图像手法
+
+三种用法，按页面角色选：
+
+1. **全幅大图**：hero 或章节开场。图上压字时只压文字落脚的局部（局部渐变），
+   别用整层半透明黑罩压全图
+2. **抠图叠层（贴纸感）**：`remove_background` 抠出透明主体，当**版面元素**用而
+   不是当"配图"——人物骑在分隔线上、吉祥物探出正文边缘、物件散落在标题周围。
+   加一点微旋转（-3°~3°）和阴影就有手作拼贴的味道。个人站和产品页的差异化利器，
+   具体配方 Read `patterns/cutout-collage.md`
+3. **装饰性小元素**：小图钉、胶带、手绘箭头、纹理角标。少量、有主题一致性，
+   跟站点气质同源（复古站用纸纹胶带，科技站用坐标刻度线）
+
+生图走 `generate_image`（cookbook 首次调用时注入），抠图走 `remove_background`。
+图先落任务本地 `assets/` 再引用。没有合适的图时，大字排版本身就是视觉主角，
+不要拿 emoji 或免费图凑数。
+
+## 动效预算
+
+CDN 库随便拉（gsap / lenis / three / alpine / htmx），但动效是调味不是主菜：
+
+- **一页最多两种动效语言**：比如"滚动淡入 + hover 微移"就是全部。首屏可以有
+  一处大的（打字机 / 视差 / 3D 背景），后面全篇克制
+- 滚动揭示别每个元素都做，按**节**做；时长 0.4~0.7s，缓动统一一个函数
+- `prefers-reduced-motion` 尊重一下，media query 三行的事
+- 动效永远不该让人等：进场动画挡住内容超过 1s 就是负资产
+
+## 中文排版基线
+
+- 标点用**全角**（，。：；？！……），半角逗号冒号在中文里很扎眼
+- 字体链每段 latin family 后面必须跟 CJK family：
+  `'Inter', 'PingFang SC', 'Noto Sans SC', system-ui, sans-serif`
+  少了 CJK 那段，换台机器中文就掉到系统默认字体
+- 细字重（300 以下）在 13~15px 的汉字上会糊笔画。气质靠行高字距留白撑，
+  不靠细体 —— 大标题（28px+）用细体没问题
+
+## 响应式
+
+一到两个断点通常够（`max-width: 860px` 单栏化是最常用的一个），复杂布局需要
+第三个就加，别为档位而档位。**做完必须自己看过真实宽度**：
+`screenshot_canvas { device: 'mobile' }` 是真的按 390px 渲染 —— 媒体查询有没有
+生效只有这样才看得出来。抠图叠层在窄屏最容易出事（盖住正文），mobile 档重点看它。
+
+## 工程形态
+
+**站点住自己的文件夹**（按站名起，别把 index.html 直接放工作区根 ——
+根是整个项目的桌面）。夹里**唯一硬要求是产物根上有 `index.html`**；多页同目录
+加 `.html`，样式怎么组织你定（手写道常见全站一份 `style.css`，构建道是 `dist/`
+里的分片）。简单站点这样就够，别为它们引工程。构建道（React /
+打包器 / 生成脚本）什么时候值得上、怎么配才不跟平台打架（`base: './'`、
+页=html 入口、build 节奏），配方在 `patterns/build-lane.md` —— **动手搭
+package.json 之前先 Read 它**。硬约束不变：**产物必须是纯静态文件**
+（落 `dist/`，系统自动认），SSR / 常驻进程不行。
+
+**站点要有功能**（用户能登录 / 提交 / 筛选 / 管理）就进**应用道**：数据全用模拟的，
+但要**真的跑起来**（四态齐全、写了刷新还在、失败路径真能触发），并且全部收在一层
+`api/` 里 —— 那一层的函数签名就是用户未来后端的接口清单，他换真数据只改那一个目录。
+配方 Read `patterns/mock-app.md`，**动手写第一个交互之前先看**（尤其 localStorage
+命名空间那条：预览时所有任务同源，不带站名前缀会串数据）。
+口径要跟用户对齐：**我们做设计和交接，不做托管运行** —— 交出去的是完整前端加一份
+「你的后端要实现这些」的清单。
+
+样式建议集中在一份 CSS 里 —— 用户自己才改得动；utility class（Tailwind 等）
+散在几百个标签上，改行高要改一百处。用户点名要就用。（构建道上这笔账不一样，
+立场见 `patterns/build-lane.md`。）
+
+打算上**页面转场或客户端路由**（点站内链接不整页刷新那种）：脚本必须从
+`boot` / `initPage` 两段起手，别写成单遍执行再回头改。配方
+Read `patterns/page-transitions.md` —— **动手写第一个转场之前先看**。
+
+## 反默认清单
+
+下面这些是 AI 生成网页的统计均值 —— 出现任何一条，说明那里**没有做设计决策**，
+只是滑进了模型的默认输出。它们不是错，是平庸：
+
+| 均值 | 它替代掉了什么思考 |
+|---|---|
+| 全宽 hero + 居中大标题 + 渐变背景 | 这一屏到底想让人记住哪句话 |
+| 三张等高功能卡片平铺 | 这三件事真的同等重要吗 |
+| emoji 当图标 | 这里需要图吗？需要的话是什么图 |
+| box-shadow 卡片堆叠 | 内容之间的关系用线还是留白表达 |
+| "Get Started" / "了解更多"按钮组 | 用户此刻真正想去哪 |
+| 每段配一个渐变色块 | 主色到底是哪个、用在哪 |
+
+写完扫一眼，命中的地方回去把那个被跳过的问题答了 —— 答案有时候恰好就是默认
+形态，那也行，但要是选出来的，不是滑出来的。
+
+## 用户说"无聊"的时候
+
+这一节是复盘出来的：有一轮用户三次表达不满，前两次的第一反应都错了一半。
+
+1. "为什么不多加些超棒的特效" → 加了滚动揭幕 + hover 微动 + 胶片颗粒。**没用。**
+2. "为什么不生成专用的图" → 补了角色一致的配图。有用，但不解决根本。
+3. "太简单太无趣了" → 这次才诊断对：站是 3 页、1 篇文章、每一节都是"左图右字"
+   的同一种节奏，读者三屏到底。
+
+**"无聊"八成是骨架太薄，不是皮肤不对。** 而加动效是往薄纸上刷漆 —— 纸还是那么薄，
+只是现在反光。
+
+诊断次序，先数三样可数的东西：
+
+- **页数**：3 页和 8 页是两种体验。一页承载不了两个重心，硬塞就成了大杂烧
+- **"节的形状"种类**：全站有几种不同的版面节奏？如果每一节都是"左图右字"，
+  那读者第三屏就知道后面长什么样了 —— 这是无聊的最常见来源
+- **交互重心数**：每页有没有一件"值得动手"的事？拖拽前后对比、手风琴、
+  三题自测、标签筛选、tab、侧边目录 + 阅读进度 —— 一页一个就够，但要有
+
+三样都薄的时候，解法是**补结构**：扩页数、每页给一个自己的交互重心、
+插一段深色内页打断连续的暖底。那一轮风格锚一个字没改，用户就满意了。
+
+**动效是最后一步，不是第一步。** 骨架撑起来了，动效才是让它顺;骨架是薄的，
+动效只是让薄这件事动起来。
+
+## 铺开时
+
+- 每一页只回答一个问题，导航里说得清它是什么
+- 页与页之间用**相对链接**（`about.html`、`posts/x.html`），绝不用 `/about.html`
+- 站内链接指向的文件必须真的存在 —— `list_pages` 会给断链清单，做完看一眼
+- 铺到一半发现锚不对，停下来跟用户说，不要悄悄漂
+
+## 上线
+
+用户明确说「发布 / 上线 / 挂到公网」时才动 `publish_site`（发公网是用户的决定，
+不是你的）。要点：
+
+- `publish_site({ task, action: 'publish' })` 发布或更新，返回永久 URL；重新发布
+  地址不变，所以「改完更新一下线上」就是再调一次。
+- 全新域名生效可能要一两分钟 —— 把这句话带给用户，别让他以为发失败了。
+- 额度或权限被拒（试用账号 / 超出每人上限）就把错误原话转告，不要重试。
+- 下线用 `action: 'unpublish'`，公网地址即刻失效。
+
+---
+
+> 起手：没有模板，从骨架和风格名自己写起（模板会把每个站同化成同一副样子，
+> 08-21 撤了）。硬要求只有产物根上的 `index.html`；样式文件的拆法和名字按站定。两条让预览出错的硬规则 —— `<meta name="viewport">`
+> 必须有、站内链接一律相对路径 —— 系统在你每次写站点页后自动 lint，违反会提醒。
+> 目录约定、产物根、`_drafts/`、导出交付在站点技术参考（首次写站点 html 时注入）。
+> 抠图叠层配方按需 Read 本 skill 目录下的 `patterns/cutout-collage.md`。
+> 构建道（React / vite / Tailwind / 组件库）配方 Read `patterns/build-lane.md`。

package/server/engine/plugins/nodesign/skills/site-craft/patterns/build-lane.md

@@ -0,0 +1,134 @@
+# 构建道 —— 组件库与打包器站点的平台配方
+
+手写道（一夹 html + css）解决八成站点。这份配方讲剩下两成：什么时候值得上
+构建，上了之后怎么不跟平台打架。
+
+## 什么时候上构建道
+
+**真信号**（有一条就值得）：
+
+- 同一块 UI 结构在三处以上重复、而且还会继续长 —— 组件复用是唯一还不掉的债
+- 交互核心有状态：筛选器 / 计算器 / 播放器 / 小编辑器。手写 DOM 操作超过
+  两百行，就该让框架管状态了
+- 内容源是数据不是页面：几十篇 md、一份 JSON 目录 —— 页面应该被**生成**，
+  不该被逐页维护
+- 要用 npm 独占的库（CDN 上没有，或 CDN 版残缺）
+
+**假信号**（听着像，其实不是）：
+
+- 「显得正经 / 专业」—— 观感由排版和素材决定，不由构建工具决定
+- 「以后可能要扩展」—— 到那天再迁。迁移的一次性成本低于工具链税的利息
+- 「动效复杂」—— gsap / lenis 走 CDN 就够，动效从来不是上构建的理由
+
+## 三条平台硬约束（违反 = 404 或感知失明）
+
+1. **`base: './'`**。预览与导出都挂在 `…/artifact-file/<路径>` 深前缀下，打包器
+   默认产出的 `/assets/xx.js` 根路径会跳出前缀直接 404。vite 一行 `base: './'`
+   解决；选别的工具前先确认它能**全相对**输出（Astro / Next 在这点上很拧，
+   别硬掰）。
+2. **页 = html 入口，router 不进站点**。`list_pages`、按页截图、按页刷新、整站
+   导出全按 html 文件寻址；SPA + 客户端路由让这些全部失明，深链接发布后照样
+   404。多页 = vite `rollupOptions.input` 多入口。例外：纯应用站（整站就是一个
+   工具）单页、无路由，随意。
+3. **产物纯静态**照旧（SSR / 常驻进程不行）。`vite build` 落 `dist/`，系统自动
+   认作产物根。
+
+## 起手：五个文件手写，不用脚手架
+
+`npm create vite` 是交互式命令（会挂住回合），给的还是单页 App 模板 —— 跟
+约束 2 打架。自己来，30 秒的事：
+
+```bash
+mkdir 站名 && cd 站名
+npm i --no-audit --no-fund react react-dom
+npm i -D --no-audit --no-fund vite @vitejs/plugin-react tailwindcss @tailwindcss/vite
+```
+
+版本让 npm 解到当前大版本，**别手填猜的版本号**（猜错一个 peer 链全断）。
+发布不满一年的新锐库默认不用 —— 你对它的知识大概率是错版本的。
+
+```jsonc
+// package.json 里 build 必须写进 scripts ——
+// 工程交付包带源不带依赖，接手的人靠 `npm i && npm run build` 续命
+{ "scripts": { "build": "vite build" } }
+```
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  base: './',                                            // 硬约束 1
+  plugins: [react(), tailwindcss()],
+  build: { rollupOptions: { input: ['index.html', 'about.html'] } },  // 每页一入口
+})
+```
+
+其余两件：`index.html`（真内容写在里面，见下节）和 `src/`（每页一个小入口 js）。
+
+## html 是骨架，React 是器官
+
+平台的感知层读的是 html：`list_pages` 从产物 html 里抓 `<a>` 拼站点结构和断链
+清单，Read 产物页看到的是标签正文。整页 JSX 渲染 = 产物 html 只剩一个
+`<div id="root">` —— 结构失明、断链失明，发布后搜索引擎同样瞎。
+
+所以：**内容仍写在真 html 里**（或由脚本生成真 html），React 只挂需要状态的
+那一块：
+
+```html
+<section id="filter-app"></section>   <!-- 只有这一块是 React 的 -->
+```
+
+每页一个小入口 js 挂自己的器官。纯应用站例外：整页 React，感知靠截图，
+结构靠你自己心里有数。
+
+## 组件库：抄进来，不是装进来
+
+装一个 kit（MUI / AntD / Chakra）= 把整站气质外包给别人的默认值 —— 反默认
+清单里每一条它都替你答了，答的全是均值；而且它跟你的排版系统（三个数、间距
+刻度、灰梯度）各论各的。需要现成组件时用**抄**的：
+
+- 行为复杂、样式想自己定的（弹层 / 下拉 / tabs / 无障碍）：headless 一层
+  （radix 系），皮全自己画
+- shadcn 式 copy-in：组件**源码落进工作区**才改得动气质；装成依赖的组件
+  你只能"配置"它
+- 图表（echarts）、3D（three）这类**画布型**库不在此列 —— 它们不带 UI 气质，
+  正常装正常 import
+
+## Tailwind 的立场（跟手写道不同，不矛盾）
+
+手写道不推 utility，理由是**用户自己要改得动**（改行高不能改一百处）。构建道
+上改样式的人是你，这条理由消失，utility 的密度优势成立。但气质旋钮必须还是
+集中的：三个数（字距 / 行高 / 正文宽）、间距刻度、灰梯度、主色，全部进
+`@theme`（Tailwind 4 的 CSS-first 配置），页面上只允许出现刻度里的值。
+`tracking-[0.06em]` 这类任意值逃逸写法出现在正文上，= 排版系统破产的信号。
+字体链 CJK 规矩照旧。
+
+## 回合节奏（一核机器的现实）
+
+- **凑一批改动跑一次 build**，不是每笔一 build。小工程一次 build 5~15 秒，
+  回合里最贵的不是它，是你为它排队的次数
+- build 验收后才准截图：`npm run build && echo BUILD_OK` —— 没看到 BUILD_OK
+  就去修错，**别截图**。build 失败时 dist 里躺着上一版，截图会"看见"旧画面，
+  让你以为改动无效、往错误方向排查 —— 这是构建道最贵的幻觉
+- **绝不起 dev server**：`npm run dev` 是常驻进程，会挂死你的命令回合；平台
+  预览也不看它 —— 预览只认产物根的静态文件。构建道的"热重载"就是
+  build + 按页刷新
+- 每加一个包先问一句：CDN 一行、或手写三十行，是不是就够 —— node_modules
+  不进导出、不进发布，纯粹是工作区里的重量
+
+## 素材与内容站
+
+- 素材放 `public/assets/`（build 原样拷进 dist），页面里按手写道同样的相对
+  路径规矩引。生成图落地后要**再 build 一次**才出现在产物里 —— 跟改源同一
+  节拍，凑批处理
+- 几十篇 md 的内容站：**自写 build 脚本优先**（node + marked，六十行的事）——
+  模板全权在你手里，相对路径天然合规。Astro / 11ty 也跑得通，但它们的链接
+  与资源默认根路径，你得逆着它们的世界观拧配置；不熟就别选贵的
+
+## DirectEdit 回写（构建道上会致命，多提一次）
+
+用户在预览里直接改的字落在**产物**上，下一次 build 会冲掉。收到构建型站点的
+DirectEdit 变更：先把改动同步回源（JSX / md / 模板里对应那处），再 build。

package/server/engine/plugins/nodesign/skills/site-craft/patterns/cutout-collage.md

@@ -0,0 +1,61 @@
+# 抠图叠层（贴纸感拼贴）
+
+透明抠图当**版面元素**用，不是当配图。配图待在自己的框里；版面元素参与排版 ——
+压线、越界、垫在文字后面。个人站 / 产品页 / 有吉祥物的品牌最吃这套。
+
+## 管线
+
+1. `generate_image` 出主体（prompt 里要求简洁背景、主体完整、边缘清晰 ——
+   纯色底的图抠得最干净）
+2. `mcp__nodesign__remove_background({ inputPath })` → RGBA PNG
+3. `cp` 进任务本地 `assets/`，站内相对路径引用
+
+薄透元素（玻璃 / 烟雾 / 飘发 / 半透明纱）抠不干净是 ML 抠图的物理极限，
+这类主体生图时就避开，或者接受边缘软。
+
+## 三种叠法
+
+**① 骑线**：主体跨在两个区块的分界上，把"分割"变成"衔接"。
+
+```css
+.divider-figure {
+  position: relative;
+  margin-top: -60px;        /* 探进上一节 */
+  margin-bottom: -20px;     /* 压住下一节开头 */
+  z-index: 2;
+}
+```
+
+**② 探出边缘**：吉祥物 / 人物从正文容器边上探出来，打破盒子感。
+
+```css
+.peek {
+  position: absolute;
+  right: -48px;             /* 一部分出界 */
+  bottom: 0;
+  width: 180px;
+  transform: rotate(3deg);
+}
+.text-block { position: relative; overflow: visible; }
+```
+
+**③ 散落**：小物件（星星 / 邮票 / 道具）随机感地撒在标题周围或节间空白。
+每个带一点不同的旋转和尺寸，两三个就够，撒多了变星空背景。
+
+## 让它像贴纸而不是浮着的 PNG
+
+- **微旋转**：-3° ~ 3°，每张不同。0° 的抠图看着像素材库，歪一点才像人手贴的
+- **阴影贴地**：`filter: drop-shadow(0 6px 12px rgba(0,0,0,.18))` ——
+  用 drop-shadow 不用 box-shadow（后者会给透明区画一个矩形影子）
+- **白边贴纸风**（可选，适合手帐 / 复古气质）：
+  `filter: drop-shadow(0 0 0 #fff) drop-shadow(0 0 1px #fff)` 叠几层出白描边，
+  或生图时直接要求 sticker style with white border
+- **尺寸克制**：版面元素不是主图，探出的部分占正文宽 15~25% 就有效果
+
+## 责任边界
+
+- 叠层元素一律 `position: absolute` / 负 margin + `z-index`，**别让它参与文档流**，
+  不然改一段文字整页元素跟着跳
+- 窄屏必须处理：探出屏幕外、盖住正文都是常见事故。`max-width: 860px` 断点里
+  要么缩小收回，要么 `display: none` —— 装饰元素在手机上消失是完全正当的
+- `screenshot_canvas { device: 'mobile' }` 看一眼再算完成