山海灵 · 专家技能
面向 shanhai-ai-generator（微信小程序）的维护与扩展。先读本文件的铁律与工作流，再按任务类型加载 references/ 中的专题文档，避免重复摸索。
项目铁律（不可违背）
- 永久免费：产品无会员、无内购、无广告、无额度与次数限制。任何改动都不得新增付费入口、额度提示或「剩余 N 次」文案。
- 本地优先：出图默认走本地 Canvas 引擎（
utils/generator.js），离线可用、结果可复现。AI 只是可选增强，失败必须自动回落本地，功能零折损。 - 不内置任何 Key：不写入任何服务商 API Key。Key 由用户在「我的 → 设置 → AI 生图」自行填写，只存本机 storage，也可配在云函数环境变量。
- 批量不误扣费：批量生成默认仍走本地，需用户显式开启才按张调用付费接口。
- 界面不出现付费暗示：文案保持「永久免费 / 本地免费生成 / 可选 AI」。
关键文件地图
| 路径 | 职责 |
|---|---|
app.js |
全局数据：styleTemplates（5 套风格）、shanhaiBestiary（首页推荐异兽）、aiConfig |
app.json / app.wxss |
页面注册、全局 CSS 变量（颜色 / 间距 / 圆角 / 阴影 / 过渡） |
工程内 styles/global.wxss |
全局组件层：卡片、按钮、.input-field、作品相框 .artwork-frame |
pages/index |
首页：Hero、快速入口、风格推荐、最近创作 |
pages/generate |
生成页：关键词、模式（图片 / 视频脚本 / 批量）、风格与高级参数 |
pages/result |
结果页：主图 / 脚本 / 批量展示、AI 视觉方案卡、导出分享 |
pages/library pages/profile pages/template pages/bestiary |
素材库、个人中心（含 AI 生图设置）、风格模板、异兽图谱 |
utils/generator.js |
本地出图引擎（2500+ 行，纯 Canvas 绘制，无外部依赖） |
utils/ai/vision.js utils/ai/imageApi.js |
视觉方案（本地启发式 + 云端大模型）、生图 API 配置与请求 |
utils/prompt/index.js |
提示词引擎 |
cloudfunctions/* |
13 个云函数；aiImage / aiVision 为可选 AI 通道 |
标准工作流
新增 / 修改异兽
同步三处，缺一会出现「首页有、图谱无」或「画面与典籍不符」：
1. app.js → shanhaiBestiary（首页推荐、联想词）
2. cloudfunctions/generatePrompt/index.js → beastFeatures（形象特征，决定提示词）
3. 云数据库 bestiary 集合（典籍原文、白话、文化寓意）
画面形态由 inferCreatureForm(info, keyword) 依据名称与释义推断，无需手写绘图代码；若形态不符，改释义关键词或扩展推断规则。
新增 / 修改风格
同步四处：app.js 的 styleTemplates、utils/generator.js 的 STYLE_PALETTE、cloudfunctions/generatePrompt/index.js 的 styleConfigs、云数据库 style_templates。各页面与云函数里的 STYLE_NAMES（id → 中文名）映射表也要补，分布在 pages/{index,generate,result,library,profile,bestiary,template}.js 与 cloudfunctions/{saveRecord,getLibrary,generateScript,generatePrompt,aiVision}。
调整出图效果
先加载 references/rendering-engine.md，确认改动落在哪一层（调色板 / 分层绘制 / 形态 / 构图 / 后期）。改完必须离线预览肉眼校验：
powershell -ExecutionPolicy Bypass -File .\scripts\preview_artwork.ps1 -Keyword 烛龙 -Style cartoon -Ratio 1:1
改页面视觉 / 交互
先加载 references/design-system.md，复用既有变量与全局类，不要硬编码新色值。
接入或排查 AI
先加载 references/ai-integration.md，确认「未配置 → 回落本地」链路完好。
改动后验证（必须）
powershell -ExecutionPolicy Bypass -File .\scripts\check_project.ps1—— 工程自检（未传-ProjectPath时自动向上定位工程根）- 在仿真目录运行
run.ps1—— 语法 / 静态 / 结构 / 深度交叉检查 + 运行时仿真（104 项断言） - 预览出图肉眼校验构图与配色
- 在
CHANGELOG.md追加版本条目（格式见references/change-playbook.md）
脚本
| 脚本 | 用途 |
|---|---|
scripts/check_project.ps1 |
工程自检：页面四件套、云函数引用与目录一致、JSON 合法性、JS（ESM/CJS）语法、异兽与风格三处同步、打包忽略项。发现 error 时退出码为 1 |
scripts/preview_artwork.ps1 |
离线出图预览：自动定位 node 与 sim/preview.mjs，渲染指定「关键词 / 风格 / 宽高比」并输出 PNG 路径 |
两者均为只读检查，不修改工程文件。
常见陷阱
- 原生
input必须显式给高度：只给 padding 会让文字上下被裁半（input.input-field { height: 88rpx }已处理）。 - 主图
mode="widthFix"需要height: auto：全局.artwork-frame image只约束宽度，切勿补height: 100%。 - 角标要压住渐隐层：
.scrim::before的 z-index 为 1，角标需z-index: 3。 - 卡片
overflow: hidden会裁掉子元素阴影：给内部元素加阴影无效，应提升卡片自身投影。 - 深色模式需
app.json开启darkmode: true才生效：当前未开启，@media (prefers-color-scheme: dark)仅作未来兼容。 cloudfunctions/getDailyQuota/consumeQuota/checkin是历史遗留空实现，部署可忽略，不要复活额度逻辑。- 仿真与预览目录（
sim/）不在工程内、不参与打包；改完源码需先同步到sim/app（run.ps1会自动拷贝）。 - 技能目录与 zip 通过
project.config.json的packOptions.ignore排除，不会被打进小程序包。
参考文件（按需加载）
references/architecture.md—— 工程结构、页面职责、云函数与数据集合、调试方式references/rendering-engine.md—— 本地出图引擎的管线、调色板、形态推断、构图参数与调优经验references/ai-integration.md—— AI 生图与视觉方案的配置、云函数协议、回落策略与安全边界references/design-system.md—— 设计变量、全局类、深色模式、小程序样式坑references/change-playbook.md—— 多文件同步点、CHANGELOG 规范、验证流水线、发布清单assets/*.json—— 新增异兽 / 新增风格的条目模板
