scratch-modules-gallery

Imported from LuYifei2011/scratch-modules-gallery (AGENTS.md). Install upstream with npx skills add LuYifei2011/scratch-modules-gallery. Copyright stays with the author.

AI 协作速览（scratch-modules-gallery）

目标：快速理解并安全扩展本仓库。保持"单 Bun 构建脚本 + 纯静态输出"原则，禁止引入前端打包器或框架级迁移。

核心流水线

1. 入口 scripts/build.ts：读取 site.config.ts → 扫描模块(content/modules/**)→ 解析脚本/导入/变量 → 合并模块级 i18n → 逐语言生成 HTML + 搜索 JSON → 生成根跳转、sitemap、robots。
   • 开发模式(IS_DEV=1)：收集构建警告/错误至 collectedIssues，生成 /issues/ 页面；跳过 sitemap 生成节省 ~8x 时间
   • Sitemap 使用 simple-git 从提交历史提取文件修改时间（CI 需 fetch-depth: 0）
2. 数据模型 scripts/lib/schema.ts：统一字段 (id, slug, name, description, tags, contributors[], scripts[], hasDemo, variables[], notesMap, references)。任何字段变更需评估链路：schema → build → 模板 → 搜索 → 前端脚本。
   • parseContributors: 仅接受数组；数组项支持 gh/user / sc/user 自动生成链接，或普通字符串/对象
   • meta.json 中的 name / description / seoDescription 是英文基线；非英文文本放入模块 i18n/<locale>.json 覆盖，禁止用 locale map 混写
3. 模板 Eta：src/templates/layouts/{base,home,module}.eta 只做展示；上下文：config,module,t,locale,pageBase,assetBase,pagePath,locales,year,IS_DEV,langTags,buildIssues,buildIssuesSummary。
   • 禁止模板中直接调用时间或访问浏览器环境

• pageBase / assetBase 由 site.config.ts baseUrl 计算，确保多语言路径正确

4. 前端 TS：src/client/{home.ts,module.ts} 仅负责搜索索引加载、语言切换、scratchblocks 二次渲染。全局注入：window.__I18N, PAGE_BASE, ASSET_BASE, IS_DEV。
   • 异步加载 /search-index.json + /search-docs.json（按语言目录）
   • CJK 分词客户端与构建端同步（单字+双字滑窗）
5. 搜索 MiniSearch：ES 模块拷贝至 dist/vendor/；索引字段：name,id,description,tags；boost 权重：name(5) > id(4) > tags(3) > description(2)。
   • 自定义 tokenizeCJK 函数：为中文字符串生成单字+双字滑窗 token，支持子串搜索

脚本与导入机制

• 脚本文件规则：每模块必须 scripts/*.txt；文件名解析：01-main.txt → id main；无数字前缀则文件名去 .txt
  • 自然排序（numeric: true）：1-foo.txt < 2-bar.txt < 10-baz.txt
• !import 指令：行级 !import otherModuleId[:scriptIndex]（scriptIndex 为 1 基，省略则取第 1 段）
  • 顶部连续 import 折叠为 leadingImports 数组；正文/中间 import 拆成独立导入段
  • 递归展开限深度 20；循环/缺失/越界写入注释 // 导入失败: <原因>
  • 导入段结构：{ imported: true, content, fromId, fromName, fromIndex, fromTitle, fromScriptId }
• scratchblocks 翻译：构建时调用 scratchblocks.parse() → translate() → stringify()
  • 加载所有语言文件 node_modules/scratchblocks-plus/locales/*.json（启动时同步）
  • 英文环境不翻译（脚本源假设为英文）；非英文按 languageTag 映射（如 zh-cn → zh_cn）

国际化 (全局 + 模块)

• 全局语言：src/i18n/*.json 控制站点 UI、元信息 (siteName, description, keywords, languageTag)
  • 模板中通过 t 对象访问；前端通过 window.__I18N 访问
• 全局 Tags 翻译：src/i18n/tags.json 集中管理所有 tags 的多语言翻译
  • 结构：{ tagId: { en: "...", zh-cn: "...", zh-tw: "..." }, ... }
  • 构建时自动应用，模块 i18n 文件无需包含 tags 字段
  • 新增 tag：仅需在 tags.json 中添加一次翻译，所有使用该 tag 的模块自动获得本地化
• 模块局部：content/modules/<id>/i18n/<locale>.json 可覆盖：name, description, seoDescription, variables, lists, events, scriptTitles, procedures, procedureParams, comments
  • 英文基础文案统一写在 meta.json；通常不需要 i18n/en.json，避免与 meta.json 重复
  • 备注文件：content/modules/<id>/notes/<lang-code>.md；构建时按语言优先级选取，转换为 notesHtml 写入模组上下文；notesMap（原始 Markdown 映射）存储在 schema 中
  • 不再需要翻译 tags：直接在全局 tags.json 中维护
  • 变量/列表/事件：构建时计算 displayName（不改变原始 name），优先级（示例 zh-cn）：当前语言 > 同类中文变体 > 英文原名
  • 示例：fps 模块的 zh-cn.json 将 FPS 变量映射为 "帧率"
• 自定义块本地化（方案A）：
  1. 脚本源统一英文 define xxx (param :: custom-arg) ...
  2. procedures 字段：英文 pattern（_ 为参数槽）→ 本地化 pattern，如 "FPS _": "帧率 _"
  3. procedureParams 字段：参数名映射，如 "last tick30": "上次tick30"
  4. 处理顺序关键：先文本层 pattern 替换（正则匹配 _ 占位）→ 再 scratchblocks AST 翻译 + 参数名替换（translateScriptFields）- 缺失翻译检测：非英文 locale 构建时输出 [i18n-missing][locale] moduleId: fields...（开发模式）
  • 自动从英文源码提取 define 行生成 baseline procedures/params（若未手动指定）

构建/开发

• 构建：bun run build → 输出到 dist/（按语言子目录）
  • 生产构建（~6-7 秒）：包含完整 sitemap、robots.txt、favicon PNG、封面图、HTML 压缩
  • 开发构建（IS_DEV=1，~0.8 秒）：跳过 sitemap，生成 /issues/ 调试页面；仍执行封面图/favicon PNG/HTML 压缩（适合测试完整构建产物）
  • 快速构建（bun run build:fast 或 FAST_BUILD=1）：额外跳过 favicon PNG 生成（仅保留 SVG）、站点+模块封面图、HTML 压缩；无 issues 页面
  • 网站迁移构建（MIGRATION_REDIRECTS=github-pages bun run build）：为 GitHub Pages 把历史 HTML 路由替换为新站跳转文档；普通构建始终生成供 Cloudflare Pages 使用的外部 301 _redirects
  • IS_DEV=1 bun run build：开发调试页 + 完整压缩产物（两者可叠加）
• 开发服务器：bun run dev / bun run dev:https
  • 监听：content/**, src/**, public/**, site.config.ts, scripts/lib/**, scripts/build.ts
  • 自动刷新：SSE 推送 {type:'reload'}；注入 <script> 到所有 HTML
  • 重建自动启用快速模式（同时设置 IS_DEV=1 + FAST_BUILD=1），速度最快
  • HTTPS 支持：自动生成自签证书（.cert/），或指定 PEM/PFX（环境变量）
  • 模块编辑器：/__dev/editor/ 可视化编辑模块（scripts/lib/editor-api.ts 处理 API）
  • 路由回退：无扩展名路径 → 相对 index.html；目录 → index.html
• 新建模块 CLI：bun run module:new -- <id> --name "Name" --description "Description"
  • 支持缺少必填项时交互式询问；非交互环境必须传入 id/name/description
  • 默认生成与 editor 一致的最小结构：meta.json + scripts/01-main.txt
  • 可选参数：--tags a,b、--keywords a,b、--contributors "gh/user, sc/user"、--script-content "..."
• SEO 描述工具：
  • bun run check-seo：检查所有语言 seoDescription 缺失与长度异常；缺失为阻塞错误，长度异常为 warning
  • bun run seo:context -- <module-id> --locale <locale>：导出模块元信息、脚本、变量、备注等上下文，便于手动给 LLM 生成描述
  • bun run seo:generate [module-id] [--locale <locale>] [--apply]：调用 OpenAI-compatible LLM 生成缺失的 seoDescription；默认 dry-run 只预览，--apply 会重新生成并写回
  • 生成工具只处理缺失项，不覆盖已有 seoDescription；结果按 seo-checker 长度规则校验，不合规则重试一次，仍不合规则不写回
  • zh-cn / zh-tw 使用同源策略：优先从已有或本轮刚生成的兄弟中文描述等义派生，避免简繁中文独立生成导致语义漂移
• 环境变量：
  • BASE_URL：覆盖 site.config.ts baseUrl（影响 canonical / sitemap）
  • IS_DEV：传入模板与前端（window.IS_DEV）；开发服务器自动设置；控制 issues 页面与 sitemap 跳过
  • FAST_BUILD：控制耗时资源跳过（favicon PNG、封面图、HTML 压缩）；开发服务器自动设置；与 IS_DEV 独立
  • MIGRATION_REDIRECTS=github-pages：仅供旧站 GitHub Pages 部署工作流使用；本地开发和 Cloudflare Pages 普通构建不要设置
  • LLM_API_KEY / OPENAI_API_KEY、LLM_MODEL、LLM_BASE_URL：seo:generate 使用；推荐写入 .env.local 等 Bun 会自动读取的 env files；LLM_BASE_URL 默认 https://api.openai.com/v1
  • HTTPS=1 + HTTPS_KEY/HTTPS_CERT 或 HTTPS_PFX/HTTPS_PASSPHRASE：HTTPS 配置
• 依赖管理：纯 ESM（type: "module"）；CommonJS 依赖用 createRequire(import.meta.url)
  • 构建时自动复制 vendor：minisearch/dist/es/index.js → dist/vendor/minisearch.js；scratchblocks-plus/build/*.min.es.js + locales/*.json → dist/vendor/

约束与安全边界

• 禁止：引入打包器（Webpack/Vite/Rollup）、修改输出目录结构、硬编码绝对 URL、在模板直接生成当前时间、写入 dist/ 手工文件
• 必须：所有内部链接/静态资源路径通过 pageBase / assetBase 拼接（多语言部署兼容）
  • 示例：fetch(pageBase + '/search-index.json') 而非 /search-index.json
• 模板上下文：year 从构建时注入；IS_DEV 控制调试功能（编辑按钮、issues 页面）
• HTML 压缩：html-minifier-next 可选（失败回退原始 HTML）；保留引号属性（removeAttributeQuotes: false）

常见修改指南

验证清单（提交前）

1. bun run build 无异常；所有语言目录含 search-index.json / search-docs.json。
2. 任意模块页 <head>：canonical 正确、全量 hreflang + x-default。
3. 导入展开无意外 // 导入失败（除演示）。
4. 自定义块：英文源含 define ...；目标语言出现本地化标题 + 参数名称替换。
5. Tags 显示正确的多语言翻译（从 src/i18n/tags.json 应用）。
6. 首页搜索：中文子串命中（CJK 分词生效）。
7. 根 index.html 按浏览器语言/LocalStorage 跳转期望语言。
8. SEO 变更后运行 bun run check-seo；若用 LLM 写回，注意 --apply 会重新生成内容。
9. 迁移变更后分别检查普通构建的 _redirects 与 GitHub Pages 迁移构建的 HTML/404，并确认旧 .sb3 不被重定向。

易踩坑 & 提示

• 缺少 scripts/ 或空目录 → 仍构建但出现在 Issues:。
• 参数/自定义块翻译顺序错误会导致 pattern 匹配失败（务必先 pattern 后 AST 翻译）。
• 变量/列表英文名如果与局部 i18n 键不一致不会显示本地化 displayName。
• 文件名排序混用（1- vs 01-）会引发顺序意外；统一使用两位或不加前导零。
• 忘记使用 assetBase 加载搜索 JSON 会导致跨语言路径 404。
• 新增 tag 必须在 src/i18n/tags.json 中定义翻译，才能在非英文版本正确显示。

推荐阅读顺序

scripts/build.ts → scripts/lib/schema.ts → src/templates/layouts/*.eta → src/client/*.ts → 示例模块 content/modules/fps/。

若新增特性（如：额外资源类型、本地化维度、搜索字段）请在提交中同步更新此文件并列出回归验证步骤。

单元测试

• 框架：使用 bun:test，零额外依赖

• 运行：bun test tests/*.test.ts

• 文件结构：所有测试文件位于 tests/ 目录，文件名格式 <module-name>.test.ts

• CI 工作流：.github/workflows/test.yml 仅当以下路径变更时触发测试：

  • scripts/**、src/i18n/**、tests/**、package.json、bun.lock
  • 模块内容变更（content/modules/**）不触发测试工作流

• 覆盖范围：

  测试文件	被测模块	主要测试内容
  schema.test.ts	scripts/lib/schema.ts	parseContributors、buildModuleRecord（必填校验、英文基线字段）
  import-resolver.test.ts	scripts/lib/import-resolver.ts	导入解析、循环引用检测、缺失模块、越界索引
  html-utils.test.ts	scripts/lib/html-utils.ts	escapeHtml、maybeMinify、generateShareLinks
  scratch-utils.test.ts	scripts/lib/scratch-utils.ts	tokenizeCJK、CATEGORY_COLORS、analyzeBlockCategories
  i18n-loader.test.ts	scripts/lib/i18n-loader.ts	pickConfigForLocale 回退与覆盖
  i18n-engine.test.ts	scripts/lib/i18n-engine.ts	元信息本地化、变量名映射、脚本标题、tags、notes、翻译字段补全
  script-translator.test.ts	scripts/lib/script-translator.ts	AST 翻译、变量/列表/自定义块名称映射、多参数重排序
  markdown.test.ts	scripts/lib/markdown.ts	Markdown 转 HTML、scratchblocks/go-to-block 自定义扩展
  search.test.ts	scripts/lib/search.ts	MiniSearch 索引构建、CJK 内容
  logger.test.ts	scripts/lib/logger.ts	truncate、formatDuration、timeNow
  module-loader.test.ts	scripts/lib/module-loader.ts	集成测试（从磁盘加载 .test + fps 模块、翻译、notes、错误处理）
  module-creator.test.ts	scripts/lib/module-creator.ts	新建模块脚手架、ID 校验、重复模块、默认脚本

• 编写规范：

  • 使用 describe / it 组织测试
  • 测试数据尽量内联构造，避免依赖外部文件（module-loader.test.ts 除外，它使用临时 fixture 目录）
  • module-loader.test.ts 通过 before 钩子将 .test 和 fps 两个模块复制到系统临时目录，避免加载全部模块导致测试过慢
  • 新增构建模块时，在对应 *.test.ts 中补充测试

NOTE: When performing a code review, respond in Chinese.