@xiaobuyu/nodesign 0.0.1 → 0.0.2

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

@@ -1,134 +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。
+# 构建道 —— 组件库与打包器站点的平台配方
+
+手写道（一夹 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

@@ -1,61 +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' }` 看一眼再算完成
+# 抠图叠层（贴纸感拼贴）
+
+透明抠图当**版面元素**用，不是当配图。配图待在自己的框里；版面元素参与排版 ——
+压线、越界、垫在文字后面。个人站 / 产品页 / 有吉祥物的品牌最吃这套。
+
+## 管线
+
+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' }` 看一眼再算完成