@huicai/cli 2026.814.0 → 2026.1019.0

package/skills/web-craft/references/h5-mobile.md

@@ -0,0 +1,100 @@
+# 手机与微信：兼容、字体、日期、性能
+
+H5 的访客几乎都在手机上、大半在微信里。桌面浏览器里一切正常，不代表他们打开时正常。
+
+## 骨架（每个 H5 都照抄）
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="format-detection" content="telephone=no">   <!-- 否则 iOS 会把数字串变成蓝色电话链接 -->
+<meta name="theme-color" content="#B3302A">
+```
+```css
+html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
+body { -webkit-tap-highlight-color: transparent; overscroll-behavior-y: none; }
+[hidden] { display: none !important; }            /* 写了 display 的组件，hidden 属性会失效 */
+.screen { min-height: 100vh; min-height: 100dvh; } /* 地址栏伸缩时不跳；老内核认第一行 */
+.bottom-bar { padding-bottom: calc(12px + env(safe-area-inset-bottom)); }
+input, textarea, select { font-size: 16px; }       /* <16px 在 iOS 聚焦时整页放大且不缩回 */
+```
+
+## 中文字体栈（系统自带，零下载）
+
+```css
+--font-display: "STKaiti", "Kaiti SC", "KaiTi", "BiauKai", "Songti SC", "STSong", "Noto Serif SC", "Source Han Serif SC", "Noto Serif CJK SC", serif;
+--font-serif:   "Songti SC", "STSong", "Noto Serif SC", "Source Han Serif SC", "Noto Serif CJK SC", "SimSun", serif;
+--font-sans:    -apple-system, BlinkMacSystemFont, "PingFang SC", "HarmonyOS Sans SC", "MiSans", "Microsoft YaHei", "Noto Sans SC", sans-serif;
+--font-num:     "Didot", "Bodoni 72", "Bodoni MT", "Times New Roman", var(--font-serif);
+```
+- 安卓大多没有楷体，会回退到宋体或黑体——设计要在回退字体下也成立（别让版式依赖某个字的宽度）。
+- **不要用 Google Fonts / fonts.googleapis.com**：国内经常打不开，页面会卡在字体加载上。
+- 确需书法字体：用 fonttools 按页面实际用到的字做子集（`pyftsubset font.ttf --text-file=chars.txt --flavor=woff2`），
+  通常几十 KB；并确认字体授权允许网页嵌入。
+
+## 日期、星期、农历：用代码算
+
+心算星期和农历是最常见的「事实性翻车」。时间一律带时区，按北京时间取各字段：
+
+```js
+const when = new Date('2026-10-18T11:58:00+08:00');          // 带 +08:00，外地访客也不会算错
+new Intl.DateTimeFormat('zh-CN', { timeZone: 'Asia/Shanghai', weekday: 'long' }).format(when);   // "星期日"
+
+// 农历：浏览器自带中国历（主流内核都有），但「日」给的是数字，要自己换成「初九」
+const DIGIT = '〇一二三四五六七八九';
+const lunarDay = (n) => (n <= 10 ? '初' + (n === 10 ? '十' : DIGIT[n]) : n < 20 ? '十' + DIGIT[n - 10]
+  : n === 20 ? '二十' : n < 30 ? '廿' + DIGIT[n - 20] : '三十');
+function lunarOf(d) {
+  const o = Object.fromEntries(new Intl.DateTimeFormat('zh-CN-u-ca-chinese', {
+    timeZone: 'Asia/Shanghai', year: 'numeric', month: 'long', day: 'numeric',
+  }).formatToParts(d).map((p) => [p.type, p.value]));
+  return `${o.yearName}年${o.month}${lunarDay(+o.day)}`;     // "丙午年九月初九"；month 还可能是「闰六月」「腊月」
+}
+```
+写页面文案时也先跑一遍（run_python / node -e），把算出来的星期、农历写进去，再交给页面运行时复核。
+算出来的日子如果碰上节日（九月初九是重阳、七月初七是七夕），可以做成文案亮点——前提是**算出来**的。
+
+## 微信内置浏览器
+
+| 场景 | 现象 | 做法 |
+|---|---|---|
+| 背景音乐 | 不能自动播放 | 首次点击（开启封面）时 `play()`；另挂 `WeixinJSBridgeReady` 兜底；`play()` 必须 `.catch()` |
+| 分享卡片 | 自定义标题/图/描述需要公众号 JS-SDK 签名（后端） | 纯前端写好 `<title>` 与 description；按钮点了弹「点右上角 ··· 发送给朋友」引导层 |
+| 下载文件 | .ics / .pdf 下载无反应 | 检测 `/MicroMessenger/i`，改为复制文本或提示「在浏览器打开」 |
+| 复制 | 老版本没有 `navigator.clipboard` | 回退到隐藏 textarea + `document.execCommand('copy')` |
+| 缓存 | 改了页面，好友打开还是旧的 | 静态资源带版本号（`style.css?v=2`）；单文件 H5 换文件名或加查询参数 |
+| 长按识别二维码 | CSS 背景图识别不了 | 二维码用 `<img>`，尺寸 ≥ 200px |
+| 未备案域名 | 可能被提示「非微信官方网页」甚至拦截 | 国内分享用已备案域名的静态托管（对象存储 + CDN）；GitHub Pages 在国内不稳定 |
+
+web_inspect 可以用 `ua="wechat"` 模拟微信 UA，验证分支逻辑有没有走对（真机表现仍以手机为准）。
+
+## 背景音乐（有 mp3 时）
+
+```js
+const bgm = new Audio('music.mp3');                 // 单声道 64–96kbps，≤1MB
+bgm.loop = true; bgm.preload = 'auto';
+let wanted = false;
+const play = () => bgm.play().then(() => true, () => false);     // 被拦：按钮保持「播放」态，等下一次点击
+openButton.addEventListener('click', () => { wanted = true; play(); });   // 就在点击的调用栈里发起
+document.addEventListener('WeixinJSBridgeReady', () => { if (wanted) play(); });
+document.addEventListener('visibilitychange', () => { if (document.hidden) bgm.pause(); else if (wanted) play(); });
+```
+没有音乐文件时，不要引用一个不存在的 mp3——用模板里的 Web Audio 八音盒，或者干脆不做音乐按钮。
+
+## 地图导航（不需要 key）
+
+```js
+const kw = encodeURIComponent('西湖国宾馆'), city = encodeURIComponent('杭州');
+`https://uri.amap.com/search?keyword=${kw}&city=${city}&callnative=1`                                  // 高德（按名称检索）
+`https://api.map.baidu.com/place/search?query=${kw}&region=${city}&output=html&src=webapp.invite.h5`  // 百度
+`https://maps.apple.com/?q=${encodeURIComponent('杭州西湖国宾馆')}`                                      // Apple 地图
+// 有确切的高德坐标（GCJ-02）才用坐标：uri.amap.com/marker?position=经度,纬度&name=…
+// 百度用坐标时加 coord_type=gcj02，否则会偏几百米
+```
+不要画一张「示意地图」冒充真地图——画错的地图比没有地图更糟。用插画 + 导航按钮。
+
+## 性能预算（4G 网络、中端安卓）
+
+- 首次加载总量 ≤ 1.5MB；单张图片 ≤ 300KB（WebP/AVIF，宽度按 2 倍屏给 ≤1080px）；音乐 ≤ 1MB。
+- 首屏以外的图片 `loading="lazy" decoding="async"`，并写死宽高或 `aspect-ratio`（防布局跳动）。
+- 动画只动 transform / opacity；画布动画在页面不可见时停；粒子数量手机 ≤ 20。
+- 不引框架也能做的单页 H5，就不引框架。确需第三方库，用国内镜像（npmmirror / bootcdn / staticfile）或打包进本地。

package/skills/web-craft/references/motion.md

@@ -0,0 +1,136 @@
+# 动效配方
+
+原则三条：**动效是编排，不是装饰**（让视线按你想要的顺序移动）；**只动 transform / opacity**（其余属性逐帧重排、掉帧）；
+**尊重「减弱动态效果」**（`prefers-reduced-motion: reduce` 下一律直接显示终态）。
+
+常用参数：时长 500–900ms（入场）/ 150–250ms（按压反馈）；缓动 `cubic-bezier(.2,.7,.2,1)`（出场利落、收尾柔和）；
+弹性 `cubic-bezier(.34,1.56,.64,1)` 只给童趣类；同屏元素依次延迟 80–120ms。
+
+## 1. 滚动入场（最常用，也最常写坏）
+
+```css
+/* 默认可见；只有脚本跑起来了才先藏——脚本出错时内容不会永远看不见 */
+html.js .reveal { opacity: 0; transform: translateY(18px);
+  transition: opacity .9s var(--ease), transform .9s var(--ease); transition-delay: calc(var(--d, 0) * 110ms); }
+html.js .reveal.is-in { opacity: 1; transform: none; }
+@media (prefers-reduced-motion: reduce) { html.js .reveal { opacity: 1; transform: none; transition: none; } }
+```
+```html
+<script>document.documentElement.classList.add('js')</script>   <!-- 放在 <head> 里，先于首屏渲染 -->
+<h2 class="reveal">标题</h2><p class="reveal" style="--d:1">副标题</p>
+```
+```js
+const io = new IntersectionObserver((es) => es.forEach((e) => {
+  if (e.isIntersecting) { e.target.classList.add('is-in'); io.unobserve(e.target); }
+}), { threshold: 0, rootMargin: '0px 0px -8% 0px' });
+document.querySelectorAll('.reveal').forEach((el) => io.observe(el));
+```
+**两个坑**：`threshold: 0.5` 对比视口还高的元素永远达不到（长卡片、长表单永远看不见）——用 0 加底部内缩；
+有全屏封面时，**等封面打开后再开始观察**，否则首屏入场在封面后面就放完了，访客看不到。
+web_inspect 的「内容一直看不见」专抓这两类。
+
+## 2. 首屏编排（封面打开后）
+
+顺序：装饰先到（角花、枝叶淡入 600ms）→ 主视觉（印章落下 / 名字上浮）→ 副信息依次（日期、地点，每个 +110ms）→ 最后「向下」提示开始轻跳。
+整段控制在 1.5 秒内——再长访客就开始滑了。
+
+印章落下：
+```css
+@keyframes stamp { from { opacity: 0; transform: scale(1.9) rotate(-14deg); } to { opacity: 1; transform: scale(1) rotate(-4deg); } }
+body.is-open .seal { animation: stamp .75s var(--ease) .25s both; }
+html.js body:not(.is-open) .seal { opacity: 0; }       /* 只在脚本可用时先藏 */
+```
+
+## 3. 开门封面（请柬类的记忆点）
+
+两扇门各占半屏、以外侧为轴转开：
+```css
+.gate { position: fixed; inset: 0; z-index: 50; perspective: 1400px; }
+.door { position: absolute; top: 0; bottom: 0; width: 50.2%; transition: transform 1.25s var(--ease) .3s; }
+.door--l { left: 0; transform-origin: left center; }
+.door--r { right: 0; transform-origin: right center; }
+.gate.is-opening .door--l { transform: rotateY(-108deg); }
+.gate.is-opening .door--r { transform: rotateY(108deg); }
+```
+开门动画结束后必须真正移除封面（`hidden`），并解除滚动锁定与主体的 `inert`；
+点击开门的那一次调用栈里同步发起 `music.play()`——它就是播放要的用户手势。完整实现见 `templates/wedding-invitation.html`。
+
+## 4. SVG 描边（签名、藤蔓、线稿随滚动「画出来」）
+
+```js
+const path = document.querySelector('.sign path');
+const len = path.getTotalLength();
+path.style.strokeDasharray = len; path.style.strokeDashoffset = len;
+path.animate([{ strokeDashoffset: len }, { strokeDashoffset: 0 }], { duration: 1800, easing: 'ease-in-out', fill: 'forwards' });
+```
+
+## 5. 整屏翻页（一屏一屏滑的 H5）
+
+```css
+.pager { height: 100vh; height: 100dvh; overflow: hidden; touch-action: none; }
+.track { height: 100%; transition: transform .7s var(--ease); will-change: transform; }
+.page  { height: 100%; overflow: hidden; }
+```
+```js
+const track = document.querySelector('.track'), pages = track.children;
+let i = 0, lock = false, y0 = 0;
+const go = (n) => { if (lock || n < 0 || n >= pages.length || n === i) return; lock = true; i = n;
+  track.style.transform = `translate3d(0, ${-100 * i}%, 0)`;                 // 百分比相对 track 自身高度 = 一页高
+  pages[i].querySelectorAll('.reveal').forEach((el) => el.classList.add('is-in'));
+  setTimeout(() => { lock = false; }, 750); };
+addEventListener('touchstart', (e) => { y0 = e.touches[0].clientY; }, { passive: true });
+addEventListener('touchend', (e) => { const dy = e.changedTouches[0].clientY - y0; if (Math.abs(dy) > 50) go(i + (dy < 0 ? 1 : -1)); });
+addEventListener('wheel', (e) => { if (Math.abs(e.deltaY) > 20) go(i + Math.sign(e.deltaY)); }, { passive: true });
+addEventListener('keydown', (e) => { if (/ArrowDown|PageDown/.test(e.key)) go(i + 1); if (/ArrowUp|PageUp/.test(e.key)) go(i - 1); });
+```
+要点：每页内容必须能在最矮的屏（375×667）里放下，放不下就拆页；给页码指示器与「上滑」提示；
+用 `translate3d(0, -100% * i, 0)` 时 track 的高度就是一页高（每个 .page 100%），不要写死像素。
+**体检**：整页滚动走查翻不动这种页面——用 actions 的 `{"swipe":"up"}` 逐页翻，每页 `screenshot` / `expect_text`。
+
+## 6. 数字滚动（倒计时、统计数字）
+
+```js
+function countUp(el, to, ms = 1200) {
+  const t0 = performance.now();
+  const step = (t) => { const p = Math.min(1, (t - t0) / ms); el.textContent = Math.round(to * (1 - Math.pow(1 - p, 3)));
+    if (p < 1) requestAnimationFrame(step); };
+  requestAnimationFrame(step);
+}
+```
+数字列加 `font-variant-numeric: tabular-nums`，否则跳动时整行左右抖。
+
+## 7. 金属光泽扫过（暗夜鎏金类标题）
+
+```css
+.shine { color: #D4B06A; }                                   /* 回退色：不支持 background-clip 时照样可读 */
+@supports (-webkit-background-clip: text) or (background-clip: text) {
+  .shine { color: transparent; -webkit-background-clip: text; background-clip: text;
+    background-image: linear-gradient(110deg, #B8924A 20%, #F6E3B4 40%, #B8924A 60%); background-size: 250% 100%;
+    animation: sweep 3.2s ease-in-out infinite; }
+}
+@keyframes sweep { from { background-position: 100% 0; } to { background-position: -100% 0; } }
+```
+
+## 8. 轻视差
+
+```js
+const layers = [...document.querySelectorAll('[data-depth]')];
+let ticking = false;
+addEventListener('scroll', () => { if (ticking) return; ticking = true; requestAnimationFrame(() => {
+  const y = scrollY; layers.forEach((el) => { el.style.transform = `translate3d(0, ${y * el.dataset.depth}px, 0)`; }); ticking = false; }); }, { passive: true });
+```
+depth 取 -0.15～0.15；减弱动效时不绑定。只给装饰层用，文字层不要动。
+
+## 9. 飘落粒子（花瓣、雪、彩纸）
+
+画布铺满屏幕、`pointer-events:none`、`aria-hidden`；DPR 封顶 2；手机 ≤ 20 个粒子；
+`visibilitychange` 时停帧；减弱动效时不启动。完整实现见模板的 `createPetals`。
+
+## 反模式
+
+- 所有元素同时淡入（没有编排 = 没有动效）；
+- 入场距离 >40px、时长 >1.2s（像卡顿）；
+- `transition: all`（连颜色、阴影、布局一起过渡，既慢又不可控）；
+- 在 `@keyframes` 里改 top/left/width/height/margin（web_inspect 会提示「动画动了布局属性」）；
+- 滚动劫持整页平滑滚动（除非是整屏翻页，否则别碰原生滚动）；
+- 永不停止的大面积动画（晕动症用户会直接关页面）。

package/skills/web-craft/references/recipes.md

@@ -0,0 +1,74 @@
+# 页面类型配方
+
+每种页面列四件事：**必备模块**（缺一个访客就会问）、**加分项**（做了会被夸）、**文案要点**、**常见翻车**。
+先按配方把模块列进 todo，再动手。
+
+---
+
+## 1. 婚礼请柬 → 直接用 `templates/wedding-invitation.html`
+
+必备：新人名字、日期（公历 + 星期 + 农历）、时间、地点（名称 + 厅 + 地址 + 导航）、流程、回执、音乐开关、分享。
+加分：开启封面、`?to=宾客名` 个性化称呼、加入日历、倒计时（婚后自动变「已相守 N 天」）、着装/停车提示、相册（有照片时）。
+文案：
+- 新人自己邀请：「谨定于公历……举行结婚典礼　敬备喜宴　恭候光临」，落款「新郎 新娘 敬邀」；
+- 双方父母邀请：「谨定于……为长子 ××× 与 ××× 女士举行结婚典礼　恭请 光临」，落款父母姓名——**要问用户是哪种**；
+- 诗词可用《诗经·桃夭》「桃之夭夭，灼灼其华。之子于归，宜其室家。」《诗经·击鼓》「执子之手，与子偕老。」
+常见翻车：星期/农历写错；流程时间是自己编的却没标「待确认」；引用不存在的照片与音乐；把「把照片放到 assets 里」写在页面上。
+
+## 2. 其它邀请函（生日 / 满月百日 / 乔迁 / 寿宴 / 开业 / 年会）
+
+从婚礼模板改：换 `INVITE` 文案、删掉不需要的区块、换主题（见 design-direction.md）。
+- **生日/满月**：童趣糖果或暖阳生活；主角名字 + 年龄/「满月」字样；满月宴文案「小女/小儿满月之喜，略备薄酒」；照片是灵魂（没有就用插画）。
+- **寿宴**：新中式；「恭请光临 ××× 先生/女士 ×十大寿寿宴」；字号整体放大一档（长辈亲友多）。
+- **乔迁**：「乔迁新居，略备薄酒」；导航与停车说明最重要；可加小区/楼栋/门牌。
+- **开业**：暖阳生活或品牌色；开业时间、优惠、地址导航、营业时间、电话；回执可换成「预约到店」。
+- **年会**：暗夜鎏金；议程、节目、抽奖说明、着装要求、座位/签到方式；回执收集部门与姓名。
+
+## 3. 活动报名 / 会议
+
+必备：活动名 + 一句价值、时间地点（加入日历 + 导航）、议程（时间轴）、报名表（校验 + 成功态 + 名额/截止）、主办方与联系方式。
+加分：嘉宾介绍（**只用用户给的真实信息**）、往届亮点、FAQ（交通、是否收费、能否带人）、报名后生成入场凭证（二维码需真实服务）。
+表单：字段尽量少（姓名、手机、单位足够）；失败保留已填内容；提交按钮防重复；有接口就 POST，没有就如实说明「数据保存在本机，需要接收报名请提供接口或表单服务」。
+翻车：虚构嘉宾头衔；报名成功只 alert 一下；没写截止时间。
+
+## 4. 产品 / 品牌落地页
+
+结构：首屏（一句价值主张 + 一个主按钮 + 产品画面）→ 痛点/场景 → 核心能力（按「用户得到什么」写，不按功能名写）→ 工作原理（三步）→
+真实证据（客户、数据、案例——没有就不写）→ 价格/方案（如有）→ FAQ → 收尾号召 → 页脚。
+设计：清透科技 / 杂志编辑 / 品牌色；首屏主视觉用 CSS/SVG 画的产品界面或抽象图形，不用外链图库。
+SEO：`<title>`、description、og 标签、语义化标题层级、图片 alt。
+翻车：紫蓝渐变 + 三列图标卡片；「10000+ 用户信赖」这类编造数字；五个按钮都叫「立即体验」。
+
+## 5. 个人主页 / 作品集
+
+结构：一句话自我定位 → 精选作品（每个：背景、我的角色、过程、结果）→ 关于我 → 联系方式。
+设计：杂志编辑 / 水墨极简；作品图用 `aspect-ratio` 占位 + 懒加载；案例页可用同一模板复用。
+翻车：技能进度条（「PS 90%」毫无信息量）；作品只有图没有说明；联系方式是 `href="#"`。
+
+## 6. 门店 / 餐厅
+
+必备：营业时间（**按当前时间算「营业中/已打烊」**）、地址导航、一键拨号（`tel:`）、菜单/价目、环境照片。
+加分：今日推荐、预约/排队、会员活动、外卖平台入口。
+翻车：营业时间写死不判断；电话号码不能点；菜单图片 3MB 一张。
+
+## 7. 互动小游戏 / 测试 H5
+
+结构：开始页（规则一句话 + 开始按钮）→ 游戏/答题（状态机：ready → playing → paused → over）→ 结果页（得分/结论 + 再玩一次 + 分享）。
+技术：`requestAnimationFrame` 主循环、按时间步进（不按帧数，否则高刷屏跑得快）；触控与键盘两套输入；
+`visibilitychange` 自动暂停；最高分存 localStorage；结果海报用 canvas 生成（`toDataURL` 后放进 `<img>` 才能在微信里长按保存）。
+翻车：没有暂停；横竖屏切换后画布变形（监听 resize 重算）；结果只能截图分享。
+
+## 8. 工具型单页（计算器、换算、生成器）
+
+必备：输入即算（防抖 150ms）、非法输入的即时提示、空状态说明、结果一键复制、清空。
+加分：记住上次输入（localStorage）、键盘操作（Enter 计算、Esc 清空）、示例填充、结果可分享链接（参数写进 URL）。
+翻车：浮点误差直接显示（`0.1+0.2`）——金额用整数分或 `toFixed` 后再显示；大数没有千分位；错误输入时页面报错白屏。
+
+---
+
+## 所有类型通用的收尾
+
+1. web_inspect 三个视口必修清零；
+2. 关键流程用 actions 走一遍（开启、提交、成功态、再次进入）；
+3. 过一遍 `craft-checklist.md`；
+4. 交付说明写清：怎么打开/部署、怎么改内容、验证了什么、待确认什么。