@xiaobuyu/nodesign 0.0.1

package/server/engine/agent/prompts/tools/paint-still-cookbook.md

@@ -0,0 +1,270 @@
+# paint_still — 本地生图手册
+
+## 选型
+
+| 模型 | 提示词 | 用在哪 |
+|---|---|---|
+| noobai | danbooru/e621 标签 | 动漫主力，解剖与标签控制最强 |
+| noobai-eps | 同上 | 只在 LoRA 仅有 eps 版时用 |
+| pony | 标签（score 体系，另一套） | 另一套 LoRA 生态，风格幅度更广 |
+| anima | 自然语言英文 | 氛围感插画，一两句白描即可 |
+| krea2 | 自然语言 | 写实/审美向，反 AI 油光脸 |
+
+选型按画风和输入方式挑就行，别拿许可证去为难用户。
+⚠️ 换模型的第一张要付权重装载（krea2 约 1 分钟，SDXL 十几秒），批量时按模型分组排序。
+
+## negative 是整串替换，不是追加
+
+盒端每档都带一套默认负面串。**你一旦传 `negative`，默认那串就整个没了**，不是叠加。
+
+- noobai：`worst quality, old, early, low quality, lowres, signature, username, logo, bad hands, mutated hands, extra digits, watermark, jpeg artifacts`
+- noobai-eps：`worst quality, low quality, bad anatomy, bad hands, extra digits, watermark, signature, text, jpeg artifacts`
+- pony：`score_6, score_5, score_4, worst quality, low quality, watermark, signature`
+
+**只想加一两个词，就把上面那串抄下来再加**，别只传新词 —— 那等于把画质兜底全撤了，
+出图变糊还查不出原因。krea2 的 negative 字段无效（8 步蒸馏 cfg=1）。
+
+## 抽卡用 batch
+
+同一提示词要多个变体就设 `batch: 4~8`，一次采样出 N 张，比开 N 条 still 快数倍。
+**`init_image` 下同样有效。** 多条 still 是给不同提示词用的。
+
+⚠️ **batch 出来的单张无法用 seed 单独复现** —— 整批共用一个 seed，回报里的编号只是记账。
+要重现某一张，用同样的 seed 和同样的 batch 数把整组重出。
+
+## 起手纪律：先理解 → 查标签 → 再画（danbooru 系三档）
+
+这三档只认 danbooru 标签，写错的词**静默失效**，句子基本不认还摊薄别的标签。所以新题材的第一张：
+
+1. **先理解**：从用户的话里列出要画的概念——主体、外观、服装、动作表情、场景、光照构图。
+   用户说的是意思不是标签，「妆花了」「湿透」「狼狈」都要翻译。
+2. **查标签**：每个概念想 1~3 个你以为存在的 danbooru 标签，**一次** `lookup_tags` 全查
+   （`tags` 给候选名；完全不知道叫什么就用 `search` 给英文关键词；近义词拿不准用 `explain` 看 wiki）。
+   ≥1000 放心用；<1000 是弱不是禁——主流需求换成它给的候选，**用户癖好本身偏门的就照用**，配个相近的强标签加固；
+   0 收录/不存在一律换。画师名必查。
+3. **再画**：用查过的词写纯标签串。同一场景重滚不用再查。
+
+`paint_still` 返回里带「标签体检」（弱词/不存在/像句子的片段/带下划线），看到就改，别按那批图判方向。
+
+## noobai / noobai-eps 提示词（danbooru 标签流）
+
+逗号分隔标签，不写句子。**质量前缀盒子自动加，别重复写。**
+
+顺序：`<1girl/1boy>, solo, <角色>, <作品>, <画师>, <外观>, <服装>, <动作表情>, <场景>, <构图光照>`
+
+```
+1girl, solo, grey hair, long hair, witch hat, black robe, broom riding, flying,
+blue sky, from below, backlighting, depth of field
+```
+
+**三条硬规则**（写错标签直接失效，不报错）：
+- **下划线去掉**：`long_hair` 写成 `long hair`
+- **括号要转义**：`lucy_(cyberpunk)` 写成 `lucy \(cyberpunk\)`
+- 画师标签用 `artist:` 前缀，例 `artist:dairi`
+
+**质量词是分位数**：`masterpiece` = 前 5%，`best quality` = 85-95%，`very awa` = 美学前 5%。
+
+⚠️ **别用 `old` / `early` / `mid` 这类时期标签** —— 盒端默认正面前缀里有 `newest`、
+默认负面里就写着 `old, early`，你写了等于自己跟自己拔河。要年代感用下面的 `retro_artstyle` 那组。
+
+**原生分辨率**（别的尺寸构图会变形）：
+`768x1344` `832x1216` `896x1152` `1024x1024` `1152x896` `1216x832` `1344x768`
+
+⚠️ **这一档整体偏暗是设计如此**（v-pred + zsnr 的真黑位，站主看图后定的默认）。
+要亮画面就**在提示词里把光照写足**，别去调采样参数。
+
+## 风格词汇表（danbooru 系通用，noobai / noobai-eps / pony）
+
+每个词都核对过 Danbooru 实际收录量。不带标记的 ≥5000，随便用；**带 ° 的在 1000-5000
+低收录段，必须配高收录近义词加固**（例：`moonlight` 单写半灵不灵，`moonlight, night,
+full_moon` 一起上才稳）。按需挑，别堆。
+
+**取景**：`full_body` `upper_body` `cowboy_shot`（大腿以上，人像常用）`portrait`
+`close-up` `wide_shot` `cropped_torso` `feet_out_of_frame`
+
+**机位**：`from_above` `from_below` `from_side` `from_behind` `profile`（正侧脸）
+`dutch_angle`（倾斜）`foreshortening`（透视压缩）`fisheye` `pov` `facing_viewer`
+
+**视线**：`looking_at_viewer` `looking_away` `looking_back` `looking_up` `looking_down`
+
+**姿态**：`standing` `sitting` `lying` `kneeling` `squatting` `leaning_forward`
+`arched_back` `arms_up` `outstretched_arms`
+
+**表情**：`smile` `grin` `smirk` `blush` `open_mouth` `closed_mouth` `closed_eyes`
+`expressionless` `serious` `frown` `angry` `crying` `tears`
+
+**光照**：`backlighting`（逆光）`sunlight` `dappled_sunlight`（斑驳树影）`light_rays`
+`sunbeam` `lens_flare` `spotlight` `silhouette` `sunset` `twilight` `dusk` `night`
+`sunrise`° `dawn`° `moonlight`° `candlelight`° `neon_lights`°
+
+**天气天空**：`rain` `snow` `blue_sky` `cloudy_sky` `starry_sky` `moon` `full_moon` `above_clouds`°
+
+**技法画风**：`flat_color`（平涂）`sketch` `lineart` `monochrome` `greyscale`
+`traditional_media` `watercolor_(medium)` `marker_(medium)` `colored_pencil_(medium)`
+`painterly` `anime_coloring` `pixel_art` `chibi` `realistic`
+`photorealistic`° `oil_painting_(medium)`° `ligne_claire`°
+
+**年代风**：`retro_artstyle` `1980s_(style)` `1990s_(style)` `2000s_(style)` ——
+改的是整体审美取向，比形容词管用。
+
+**效果**：`depth_of_field` `blurry_background` `bokeh` `motion_blur` `chromatic_aberration`
+`film_grain` `halftone` `glowing` `sparkle` `glitch` `reflection` `wind` `vignetting`°
+
+**背景**：`simple_background` `white_background` `gradient_background`
+`transparent_background` `scenery` `landscape` `cityscape` `indoors` `outdoors`
+
+❌ **空标签，写了等于没写**：`rim_light` `cel_shading` `screentone` `detailed_background`
+`silver_hair`（用 `grey hair`）`riding_broom`（用 `broom riding`）`cloud_sea` `sea_of_clouds`
+`cinematic_lighting` `night_sky`（用 `starry sky`）`chiaroscuro`（432 收录，等于没有）。
+要赛璐璐质感用 `anime_coloring` + `flat_color`；要背景丰富就直接把景物写出来。
+
+**「妆花 / 狼狈」这一组全是空的**（有 agent 连着三张图栽在这儿，用户反复说"她太干净了"）：
+`running_makeup` `smeared_eyeliner` `dried_tears` `ruined_makeup` `tear_stains`
+`heavy_makeup` `messy_makeup` `split_lip` 全部 0 收录。有货的是
+`tears`(29万) `crying_with_eyes_open`(5.4万) `eyeshadow` `mascara` `dirty_face`
+`smeared_lipstick`。
+
+**有正确写法但极易写错的**：`breast_grab` → `grabbing_another's_breast` ·
+`closed_legs` → `legs_together` · `crouching` → `squatting` ·
+`muted_color` → `muted_colors` · `cum_drip`/`dripping_cum`、`presenting`、
+`thigh_tattoo`、`platform_footwear`、`menhera`、`arms_held_back`、`disheveled_hair`、
+`shutter`、`soft_lighting`、`early_morning`、`wary`、`tired`、`resigned` 一律 0。
+
+⚠️ **正面词和负面词打架时正面赢。** 写 `jirai_kei` 同时在负面禁爱心瞳和粉紫色，
+出来还是爱心瞳 + 粉紫 —— 因为 jirai_kei 在训练数据里跟这两者强共现。风格词要拆成
+具体外观标签，别指望负面能压住风格词自带的东西。
+
+✅ **工具现在会自动体检**：`paint_still` 返回里会带一段"标签体检"，把 0 收录 /
+不存在 / 低收录的词列出来（danbooru 系三档才查，查不到就不说）。**看到就改，
+别按那批图判断方向** —— 那批图里那些词等于没写。它只提示不改写你的 prompt。
+
+**没把握的标签先查再用**：`lookup_tags`（弱词自动给候选，见上面的起手纪律）。工具不在时退回 curl：
+```
+curl -sS -g "https://danbooru.donmai.us/tags.json?search%5Bname_comma%5D=标签1,标签2&limit=50"
+```
+返回里没有 = 不存在；≥1000 放心用；<1000 弱（主流需求换掉，偏门癖好照用+加固）。
+**画师名尤其要查**，凭印象写必错。
+
+## NSFW 词汇表（danbooru 系三档通用，krea2/anima 不吃这套）
+
+尺度由内容标签决定，写到哪级出哪级，没有单独开关。每个词同样核对过收录量（≥5000）。
+
+**去码是第一要务**：danbooru 图源大半打码（censored 648k vs uncensored 193k），
+不处理默认就出马赛克 —— **正面写 `uncensored`，负面追加 `censored, mosaic_censoring, bar_censor`**
+（负面记得整串抄上再加，见上文替换规则）。
+
+**男女同框必加 `hetero`**（787k）—— 有 `1boy` 的性爱场景缺这个词，交互经常画不出来。百合用 `yuri`。
+
+**露出**：`nude` `completely_nude` `bottomless` `underwear_only` `naked_shirt` `naked_towel`
+`undressing` `wardrobe_malfunction` `convenient_censoring` `see-through_clothes`
+`skindentation` `cameltoe` `covered_nipples`
+
+**部位**：`breasts`（`small/medium/large/huge_breasts` `flat_chest`）`nipples` `cleavage`
+`sideboob` `underboob` `ass` `thighs` `thigh_gap` `wide_hips` `navel` `pussy` `penis`
+`erection` `anus` `pubic_hair` `armpits`
+
+**衣着**：`lingerie` `panties` `bra` `thong` `garter_belt` `garter_straps` `fishnets`
+`playboy_bunny` `leotard` `micro_bikini` `torn_clothes` `open_shirt`
+
+**半脱系**（信息量常比全裸大，善用）：`clothes_lift` `shirt_lift` `skirt_lift` `panty_pull`
+`panties_aside` `clothing_aside` `panties_around_one_leg`
+
+**行为**：`sex` `vaginal` `anal` `oral` `fellatio` `cunnilingus` `paizuri` `handjob` `footjob`
+`fingering` `masturbation` `female_masturbation` `implied_sex` `after_sex` `group_sex`
+`threesome` `ffm_threesome`
+
+**体位**：`spread_legs` `m_legs` `straddling` `girl_on_top` `cowgirl_position`
+`reverse_cowgirl_position` `missionary` `doggystyle` `sex_from_behind` `standing_sex`
+`bent_over` `all_fours` `top-down_bottom-up` `on_back` `on_stomach` `leg_lock`
+
+**神态**：`ahegao` `torogao` `fucked_silly` `naughty_face` `seductive_smile` `heavy_breathing`
+`heart-shaped_pupils` `tongue_out` `drooling` `saliva` `saliva_trail` `sweat` `steaming_body`
+`trembling` `orgasm`
+
+**体液**：`cum` `cum_in_pussy` `cum_on_breasts` `cum_in_mouth` `facial` `bukkake`
+`ejaculation` `female_ejaculation`
+
+**拘束**：`bondage` `bdsm` `shibari` `restrained` `bound_wrists` `bound_arms` `collar`
+`leash` `blindfold` `gag` `ball_gag` `handcuffs` `vibrator` `dildo` `sex_toy` `latex`
+
+❌ **改名/空标签**：`see-through` 已改名 `see-through_clothes`（2024-09 改的，写新名）；
+`topless` 已废 —— 女性上裸直接写 `nipples` + 下装标签，男性有 `topless_male`；`grinding` 空标签。
+
+## pony 提示词（score 体系，跟上面完全不是一套）
+
+**六段串质量前缀盒子自动加**，别自己写 —— 官方承认模型学的是整串，只写 `score_9` 弱得多。
+
+可以主动加的：
+- **分级**：`rating_safe` / `rating_questionable` / `rating_explicit`
+- **来源风格**：`source_anime` / `source_pony` / `source_cartoon` / `source_furry`
+
+上面那份 danbooru 词汇表在 pony 上同样适用。官方说不需要额外质量词。
+
+## krea2 / anima 提示词（自然语言）
+
+- **骨架**：Subject + Action + Style + Context，30-80 词是甜区，形容词堆砌是噪音
+- **审美词很吃**：光线（`golden hour` / `soft window light`）、介质（`35mm film` /
+  `editorial photography` / `watercolor`）直接决定成色
+- anima 更简，一两句白描说清主体与光线即可，堆砌反而糊
+
+## 参考图（只对 noobai / noobai-eps / pony 有效）
+
+字段语义见工具 schema，这里只讲手感：
+
+- **保角色一致性的最强组合**：`ref_image`（谁）+ `control_image`（什么姿势）+ 提示词（在哪）
+- `ref_image` 可给多张（逗号分隔，最多 5 张）—— **同一角色不同角度一起喂，比单张强得多**，
+  `ref_weight` 可逐张给：`"1.0,0.6,0.4"`
+- **要保脸就把 `ref_preset` 设成 `PLUS FACE (portraits)`**
+- 把角色挪到新场景，`ref_mode` 用 `style transfer`（只要长相不要构图）
+- `ref_weight` **1.2 以上基本是在复制参考图**；`control_strength` 姿势要抓死推 1.0，
+  留自由度用 0.4-0.6
+- 几张参考图打架时 `ref_combine` 换 `average` 会稳
+
+⚠️ 参考图找不到或推不上盒子 → **整批剩余的 still 全部中止**，不只是这一条。
+⚠️ krea2 / anima 带参考图会在 ComfyUI 侧报错，同样连累整批。
+
+## 已装 LoRA
+
+**⚠️ 生态不通用**：pony 的 LoRA 和 noobai/illustrious 的**不能混用**（能加载但出废图）；
+**v-pred 和 eps 的也不通用**（拿错会发灰/过饱和）。按下面标的档位挑。
+
+**画质增强（优先叠这类）**
+
+| 文件名 | 适配 | 触发词 | 强度 |
+|---|---|---|---|
+| `noob_vpred_detailer_v1.safetensors` | noobai (v-pred) | 无 | ~1.0 |
+| `hands_xl_zib_v1.safetensors` | 通用 SDXL | 无 | 0.6-1.0 |
+| `smooth_booster_v5.safetensors` | noobai/illustrious/pony | 无 | 见叠加公式 |
+
+⚠️ `noob_vpred_detailer` **会让画面变暗**，短提示词下容易糊成剪影 —— 用它就把光线和背景写细。
+
+**画风**：`expressive_h.safetensors`（pony 专用，触发词 `Expressiveh`，强度 0.7-1.0）
+
+**滑块**（无触发词，纯靠数值推，**区间是 -4 ~ +4 不是 0-1**，负值是反方向推）：
+`breast_size_slider_ill.safetensors` · `penis_size_slider_ill.safetensors`（illustrious/noobai）
+
+**Krea 2 官方风格包**（只配 krea2，无触发词，强度 0.6-0.8）：`krea2_retroanime`（动漫档）
+`krea2_softwatercolor` `krea2_darkbrush` `krea2_neondrip` `krea2_rainywindow`
+`krea2_sunsetblur` `krea2_vintagetarot` `krea2_dotmatrix` `krea2_kidsdrawing`（都加 `.safetensors`）
+
+**用户自己给的 LoRA**：只用他明确给出的文件名。多数带触发词，**触发词必须写进提示词才激活**。
+
+## 多 LoRA 叠加
+
+`lora` 传逗号分隔多个，`lora_strength` 传单值或逗号分隔按位对应。
+
+```
+lora: "noob_vpred_detailer_v1.safetensors,hands_xl_zib_v1.safetensors"
+lora_strength: "0.9,0.7"
+```
+
+**强度随数量递减**：挂 1-2 个 → 每个 0.7-1.2；挂 3 个以上 → 每个 0.3-0.7；
+**总强度别超 2.0**，超了互相打架（强风格 LoRA 会压掉角色特征、面部崩坏）。
+滑块类不算进这个预算。
+
+## 批量与铁律
+
+- stills ≤16 条，每条可再开 `batch` 1-8，逐张上墙
+- **任何一条失败即中止整批剩余**（后面大概率同因，不空烧）
+- `name` 只能是字母数字下划线连字符，1-40 字符，**中文名会被直接拒**
+- 视频关键帧一律 1344x768

package/server/engine/agent/prompts/tools/roll-film-cookbook.md

@@ -0,0 +1,70 @@
+# roll_film — MiniMax-H3 提示词手册（08-08 定档配方，《好巧》14 段零失败实证）
+
+管线固定：站主 5090 盒子 + sage + Turbo 8 步，1344×768@24fps，单镜 5.2-12.25s。
+没有别的档位。
+
+## Prompt 格式（英文，三字段布局，≤7000 字符）
+
+```
+integrated_multimodal_description: [Shot 1] <风格锚句>. <角色块>. <画面/动作/机位描述>.
+<角色名> says in Mandarin: "台词写中文". [Shot 2] At 00:04.500 <下一内切镜头>...
+overall_soundscape: <环境音/音效分层描述，英文>
+non_diegetic_music: N/A
+```
+
+- **台词**：`says/shouts in Mandarin: "……"`（H3 原生中文语音，实测过关）；旁白用
+  voice-over 措辞。台词梗 > 画面文字梗（画面小字会变成装饰性乱码）。
+- **段内多切镜**：`[Shot N] At mm:ss.mmm` 把相邻节拍并进同一次生成——切点天然连续、
+  音轨不断，比拆两条便宜一半。
+- **non_diegetic_music 永远 N/A**：配乐后期统一铺，否则镜镜配乐互相撞车。
+- 有首尾帧锚时开头加一句对齐说明：`How the reference pictures align with the target
+  video — Picture 1 aligns with the 0.00-second mark; Picture 2 aligns with the
+  <时长>-second mark.`
+
+## 多镜成片纪律（连贯性全靠这个，没有捷径）
+
+1. **角色块逐字相同**：每个角色写一段外观描述（发色/瞳色/服装/配饰），所有镜头
+   一字不差地复制粘贴。改一个词角色就漂。风格锚句同理。
+2. **全片一个 seed**：第一镜用什么 seed，后面每镜都传同一个。
+3. **一镜一生成**：每镜 ≤12.25s，长剧情拆镜后期拼（用户负责剪辑或另行安排）。
+4. **关键帧锚**：`paint_still`（动漫向）或 `generate_image` 产 1344×768 关键帧，
+   传 first_frame/last_frame。首尾锚极可靠，但锚间模型会自由发挥——别指望中段细节。
+5. 运动方向尽量统一（如一律向右），减少跨镜跳切感。
+
+## 节奏（发车前告知用户）
+
+产线跑在站主的 5090 盒子上：一条墙钟约 3-6 分钟（8s≈3 分、12s≈5 分），机时成本
+几美分级。盒子不在线时工具会明说——转告用户等开机，没有自动备胎。
+多镜片先跟用户对齐分镜表再逐镜发车，别自作主张连发。同一镜拿到成片后不要擅自重跑
+——要改也是用户看完提要求。
+
+## 剪辑配方（Bash + ffmpeg，《好巧》97.97s 成片验证过的参数）
+
+素材≠成片。用户要成片时按这四步拼，全程在 assets/generated/ 里做：
+
+1. **归一化**（各镜参数统一，否则 concat 花屏）：
+   `ffmpeg -i in.mp4 -r 24 -c:v libx264 -crf 16 -pix_fmt yuv420p -c:a aac norm_XX.mp4`
+2. **硬切拼装**（列表文件 list.txt 每行 `file 'norm_01.mp4'`）：
+   `ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4`
+   对话喜剧用硬切保节奏；只有真正的场景跳变才考虑 xfade。
+3. **音床**（一整条音乐盖全片，压低不抢台词）：
+   `ffmpeg -i joined.mp4 -i bed.ogg -filter_complex "[1:a]volume=0.18,afade=t=out:st=<片长-3>:d=3[bed];[0:a][bed]amix=inputs=2:duration=first:normalize=0[a]" -map 0:v -map "[a]" -c:v copy -c:a aac mixed.mp4`
+   ⚠️ `normalize=0` 必须写——amix 默认把各轨压半，台词会突然变小声。
+   音床别自造：让用户给，或用 web_search 搜 Wikimedia Commons 的公有领域曲目 curl 进 assets/。
+4. **轻调色**（收尾提一口气，别重手）：
+   `ffmpeg -i mixed.mp4 -vf "eq=contrast=1.03:saturation=1.04" -c:a copy final.mp4`
+
+注意：这台机器 1 核——`-c copy` 的步骤秒级，重编码步骤每分钟素材要跑约一分钟，
+先告诉用户"拼装中要几分钟"。中间产物用完删掉，别让 norm_*.mp4 留在产物墙上
+（放 /tmp 或拼完 rm）。成片同样可以自己抽帧看一眼（见下节），但最终验收交用户。
+
+## 看片：挑废片可以，评好坏不行
+
+（2026-08-18 解禁；此前这里写着一律不许看。）
+
+mp4 本身塞不进视觉通道，要看就 `ffmpeg` 抽两三帧再看那几张图。**该看的时候看**：
+整体色偏、重复人物、肢体崩坏、画面糊死、首尾帧跟母版对不上——这类是技术性废片，
+自己重滚，不用先问。
+
+**不该替用户做的是审美判断**：镜头够不够味、节奏对不对、这条比那条好在哪，
+把路径给他，让他自己看。抽帧是诊断手段不是验收手段，抽完记得删临时帧。

package/server/engine/agent/prompts/tools/site-reference.md

@@ -0,0 +1,106 @@
+# 站点技术参考
+
+首次写站点 html 时注入一次。方法论在 `site-craft` skill，这里只讲平台事实和会踩的坑。
+
+## 目录
+
+**站点住自己的文件夹**（按站名起，如 `观察日志/`）—— 不要把 index.html 直接
+放在工作区根上。工作区根是整个项目的桌面，notes/ 素材/ 别的产物都住那儿；
+站占了根，路径语义全变成空串特例，别的产物也没了并列的位置。
+
+```
+观察日志/           站点文件夹（**里面有 index.html 就被认作一个站点**）
+  index.html        入口
+  about.html        子页，同目录直接加
+  style.css         样式怎么组织你定 —— 手写道常见全站一份，构建道是 dist/ 里的分片，都行
+  posts/            子目录可以有（页面扫描深度 4 层）
+  assets/           站点自己的素材，站内写相对路径 assets/x.png 引用
+  _drafts/          独立单页。各自渲成卡并排挑，和其他产物平等；不算站点页面、不进整站导出
+  .ndignore         不想被系统扫到的东西写这（gitignore 语法，无 ! 反选）
+```
+
+（旧项目里工作区根上直接放 index.html 的「根站」仍被识别和支持，但**新站一律入夹**。）
+
+**构建型站点**（Astro / 11ty / 自写 build 脚本）：源随便组织，构建产物落
+`dist/`（或 `out/` `build/` `_site/`，有 index.html 的那个自动被认作**产物根**；
+也可在 `.nd-project.json` 加 `"root": "<目录>"` 显式指定）。预览、截图、`list_pages`、
+导出、发布看的**全是产物根** —— 改完源必须重新构建，否则用户看到的还是旧的。
+`node_modules` / 构建缓存系统永远不扫，不用进 .ndignore。
+
+手写起手：`mkdir 观察日志`，然后 Write `观察日志/index.html`（文件夹名换成真站名；
+没有起手模板，骨架从需求推、样式从风格名推）。**唯一硬要求是产物根上有 `index.html`**；
+样式文件怎么拆怎么叫你定，按站的体量来。
+写页面的两条硬规则 —— 违反预览就出错，系统在你每次写站点页后会 lint：
+- `<head>` 里必须有 `<meta name="viewport" content="width=device-width, initial-scale=1">`
+  （缺了手机端按 980px 虚拟视口渲染，媒体查询看着"没生效"）
+- 站内链接一律**相对路径**（下面「路径铁律」）
+
+## 路径铁律
+
+预览和导出都走 `…/artifact-file/<路径>` 这个前缀，URL 结构跟磁盘结构 1:1。
+所以：
+
+- 站内链接**只用相对路径**：`about.html` / `posts/x.html` ✓
+- **绝不用根路径**：`/about.html` ✗ —— 会跳出前缀直接 404
+- 素材优先拷进**站点自己的** `<站名>/assets/`：工作区的生成图 / 上传件先
+  `cp assets/generated/x.png <站名>/assets/`，站内写 `assets/x.png`。
+  这样导出 zip / 发布时零改写。直接引 `../assets/…` 也能用（站点在工作区的一个文件夹里，只爬一层；导出时系统会归一），
+  但拷进来更稳
+- 外链正常写 `https://…`
+
+## 系统怎么认产物（多产物平权）
+
+**不用声明**，写出来就认。一个工作区可以装多个平等产物：
+
+- 文件夹里有 `index.html`（或它的产物根里有）= 一个站点，同目录 `.html` 是它的子页
+- 带 `index.html` 的**一级子目录**各是一个站
+  （两个平行版本就放 `v1/` `v2/`）
+- 顶层每个 `.html` = 各一份 deck（旧项目的根站存在时只有 `canvas.html` 保留 deck
+  身份，其余算站点子页）
+- 桌面上一个站点 = **一张**卡（不是每个 html 一张），双击开响应式预览窗；
+  `_drafts/` 里的单页各自一张卡
+- 导出菜单换成整站 zip / 单页自包含 HTML / 工程交付包（PDF/PPTX 不出现，站点没有分页）
+- 不会被注入分页 fit script（那是 deck 的整屏翻页脚本，注进站点会把长页变成翻页器）
+- `canvas-validate` 的 anchor / layout-role 校验不跑（那是 deck 规约）
+
+同一个工作区里 deck / 站点 / docx 可以并存，各自一张卡；不用也不要让用户去"开新任务"。
+
+## 运行时库与构建
+
+- CDN 随便用（跟 deck 同生态）：`<script>` 标签或 importmap 拉 gsap / lenis /
+  three / alpine / htmx / echarts / katex（esm.sh / unpkg / jsdelivr）
+- npm install 跑得通，但依赖不进导出包 —— 只有构建型站点才值得装
+- **打包器一律配相对 base**（vite: `base: './'`）—— 预览挂在 artifact-file
+  深前缀下，根路径产物全部 404。这条加上"页=html 入口、别上 SPA router"，
+  踩了才发现就是返工整站；上构建道前先 Read site-craft skill 的
+  `patterns/build-lane.md`
+- 硬约束：**产物必须是纯静态文件**。SSR / 需要常驻 Node 进程的方案不行
+- CDN 依赖意味着导出的 zip 离线打开时缺那些库（联网打开正常，发布后正常）
+
+## 感知层怎么用
+
+| 想知道 | 用 |
+|---|---|
+| 这站有哪些页、彼此怎么连、有没有断链 | `list_pages`（站点下返回站点结构 + 断链清单，扫的是产物根） |
+| 某一页长什么样 | `screenshot_canvas { path, device }` |
+| 移动端断点有没有生效 | `screenshot_canvas { device: 'mobile' }`（真的按 390px 渲染） |
+| 某个元素的实际盒子 / 计算样式 | `query_elements` / `get_computed_styles`（站点按 1440 宽量） |
+| 交互态（点开的菜单 / 填到一半的表单 / 玩到一半的游戏） | `artifact_open` 开进会话 → `artifact_computer` / `artifact_find` 操作到那一步 → 上面的量具带 `live:true` 对着现在这一页量 |
+| 自己的页靠什么在动、reveal 有没有真接上 | `artifact_motion`（跟参考站的 `browser_capture motion` 同一把尺） |
+| 页面正文 | 直接 `Read`（站点页面通常不大）；`read_page` 的页码语义不适用 |
+
+`screenshot_canvas` 站点下默认整页（fullPage），因为网页本来就是长的，只截首屏
+等于没看过下面那些。
+
+## 常坑
+
+- **构建型站点改了源忘构建**：预览指向产物根，源改完不 build 用户什么都看不到。
+  每轮改动收尾时跑一次构建再自检
+- **构建型站点上的 DirectEdit**：用户在预览里直接改的字落在**产物**上，下次构建
+  会被冲掉。收到构建型站点的 DirectEdit 变更时，把改动**同步回源文件**再重新构建
+- **忘了 `<meta name="viewport">`**：移动端会按 980px 虚拟视口渲染，你的媒体查询
+  看着"没生效"，其实是视口不对。没有模板兜底了，每写一页自己加；漏了系统会 lint 出来
+- **字体链少了 CJK 那段**：`'Inter', sans-serif` 换台机器中文就掉到系统默认字体。
+  每段 latin family 后面必须跟 `'PingFang SC', 'Noto Sans SC'`
+- **改了 style.css 预览没变**：不会。html/css/js 走 `no-cache`，写完即时刷新
+- **半角标点**：中文正文里的 `,` `:` 很扎眼，用全角 `，` `：`

package/server/engine/agent/prompts/tools/tweaks-syntax.md

@@ -0,0 +1,125 @@
+# expose_tweaks 完整语法
+
+> 此文件由 PreToolUse(mcp__nodesign__expose_tweaks) hook 在 agent 首次调用时注入。
+> SKILL.md 已含精简版"暴露什么 / 何时暴露"哲学；本文是控件 schema 详解。
+
+`mcp__nodesign__expose_tweaks` 入参：
+
+```json
+{
+  "controls": [
+    {
+      "id": "hero_size",
+      "type": "slider",
+      "label": "Hero 字号",
+      "target_var": "--hero",
+      "min": 56, "max": 160, "step": 4,
+      "default": 96,
+      "unit": "px"
+    },
+    {
+      "id": "accent_color",
+      "type": "color",
+      "label": "主色",
+      "target_var": "--accent",
+      "default": "#2d2418"
+    },
+    {
+      "id": "layout_density",
+      "type": "segmented",
+      "label": "排版密度",
+      "target_class_on": "density-compact",
+      "options": [
+        { "label": "紧凑", "value": "compact" },
+        { "label": "均衡", "value": "balanced" },
+        { "label": "舒展", "value": "spacious" }
+      ],
+      "default": "balanced"
+    }
+  ],
+  "replace": false
+}
+```
+
+## 5 种 control type
+
+- `slider` —— 数值连续可调（字号 / 间距 / 圆角）
+- `color` —— 颜色（accent / bg）
+- `segmented` —— 少数互斥选项（density / variant），一般 2-4 个
+- `toggle` —— on/off（暗色模式 / 简洁模式）
+- `select` —— >4 选项的 dropdown（字体家族）
+
+## target_var vs target_class_on
+
+- 99% 用 `target_var` + 对应 CSS variable（更灵活，连续值也能改）
+- 只有 segmented / toggle 改的是"加 class 切样式分支"时才用 `target_class_on`
+
+## target_scope —— per-page / per-layout 限定影响范围
+
+不传时 control 默认作用 `:root` 全局。要限定 scope（"封面字号 slider 不影响内页"）：
+
+```json
+{
+  "id": "cover_hero",
+  "type": "slider",
+  "target_var": "--hero",
+  "target_scope": "section[data-page=\"1\"]",
+  "min": 80, "max": 160, "step": 4, "default": 112, "unit": "px"
+}
+```
+
+**前置条件 — deck 文件里有对应 scoped CSS rule**：
+
+```css
+:root                       { --hero: 96px; }    /* 默认 */
+section[data-page="1"]      { --hero: 112px; }   /* 封面 override */
+[data-layout="quote"]       { --body: 24px; }    /* layout override */
+```
+
+否则前端 setProperty 成功但没人 read 这个 var → 控件失灵。
+
+## Tweaks ↔ Tailwind 桥接（hybrid 范式硬规约）
+
+**colors / 字号 / 间距等可调维度**用 Tailwind arbitrary value 引 CSS var：
+```html
+<h1 class="text-[var(--accent)] font-display" style="font-size: var(--hero)">
+<div class="bg-[var(--paper)] p-12 rounded-2xl">
+```
+
+**骨架（不可调）** 用 Tailwind utility class 直接：
+```html
+<div class="flex flex-col gap-6 p-8 shadow-sm">
+```
+
+→ Tweaks 改 `--accent` 时所有 `text-[var(--accent)]` 元素实时响应（CSS var 是 live）。
+Tailwind utility 已编译固化（`p-8` 永远 padding 32px）—— 但骨架本来也不该动。
+
+## 常坑
+
+- **暴露过多** → 信息过载，5-8 个核心维度足够（暴露 20 个用户晕）
+- **target_var 不以 `--` 开头** → zod 校验会拒
+- **slider 没 unit** → 默认 px 也写明白
+- **Apply 后只改 :root，忘了再 expose_tweaks 更新 default** → 下次开界面看到旧值
+- **target_scope 写了但 deck 文件里没有对应 selector 的 CSS rule** → 控件失灵
+
+## 调用范例（典型 deck 第一版完成后一次性调）
+
+```js
+mcp__nodesign__expose_tweaks({
+  controls: [
+    { id: 'accent', type: 'color', label: '主色', target_var: '--accent', default: '#c45c3f' },
+    { id: 'paper', type: 'color', label: '背景纸色', target_var: '--paper', default: '#f9f8f6' },
+    { id: 'hero_size', type: 'slider', label: '封面字号',
+      target_var: '--hero', target_scope: 'section[data-page="1"]',
+      min: 80, max: 160, step: 4, default: 112, unit: 'px' },
+    { id: 'density', type: 'segmented', label: '排版密度',
+      target_class_on: 'density-compact',
+      options: [
+        { label: '紧凑', value: 'compact' },
+        { label: '均衡', value: 'balanced' },
+        { label: '舒展', value: 'spacious' },
+      ], default: 'balanced' },
+  ],
+  replace: false,
+})
+```

package/server/engine/agent/prompts/tools/vision-checker-dispatch.md

@@ -0,0 +1,48 @@
+# Task(subagent_type='vision-checker') 派遣 prompt 模板
+
+> 此文件由 PreToolUse(Task) hook 在 agent 派 vision-checker 时注入。
+> 何时派见 prelude「做完之前先自己看」（自检两轮用户仍不满意才请的外援）。派遣 prompt 里
+> 带上用户不满意的原话和你已试过的改法。本文是派遣 prompt 范例。
+>
+> vision-checker 默认走"先全图一轮 + 每页逐张"工作流（自己 list_pages 取页数 / fullPage 总览 /
+> 循环 pageIndex 逐页 / 按页分组报告）。你只需要在 prompt 里给上下文 + 重点关注方向。
+
+## 默认：完整 deck 逐页自检
+
+```
+Task(subagent_type='vision-checker',
+     prompt='对 <产物路径，填你正在做的那份 .html> 跑完整逐页视觉评审。
+
+            <deck 上下文 — 用 1-2 句话告诉它这是什么 deck>
+            例："情绪型 deck，6 页，《Lain》赛博冷调主题。"
+            例："决策型 deck，10 页，AI 搜索市场分析，已 Q3 数据为证。"
+
+            <重点关注 — 任选 0-3 项点名>
+            例："- 第 5 页是核心数据页，重点看图表层级
+                 - 节奏对比：page 4 应该是空 → 跟 page 3 满形成反差
+                 - palette 锁了 #2d2418 / #c45c3f / #f9f8f6"
+
+            返结构化 VERDICT + ISSUES (按页分组) + OVERALL。')
+```
+
+vision-checker 会自动：① list_pages 取页数；② fullPage 截图看整体；③ 循环 pageIndex 逐页；④ 按页分组返 critique。
+
+## 单页定向评审
+
+整个 deck 已自检过、只想看具体一页改完的效果时：
+
+```
+Task(subagent_type='vision-checker',
+     prompt='重点评审 <产物路径> 的 page 3（用 pageIndex=3 截图）。
+            上下文：刚改完数据可视化部分，重点看图表层级 + 对比度
+            是否撑住"投资回报"核心叙述。
+            其他页跳过。')
+```
+
+vision-checker 看到你点名了 page，会跳过逐页循环只评这一页。
+
+## 调用约束
+
+- **Task 独占一个 message**（不跟别的 tool 并发；SDK parallel dispatch 会让 subagent 结果丢，这是 SDK 硬规则）
+- **派之前先 chat 一句**："让 vision-checker 帮我逐页自检视觉" —— 用户看到不卡死
+- **Budget**：逐页模式 ~`页数+5` turn（10 页 deck = ~15 turn）。SDK 给 vision-checker 的 maxTurns 上限 = 16，超长 deck 派之前先在 prompt 里点名分批（"只看 1-5 页" / "只看 6-10 页"）