cuberoot.me

给 /sim 加一个新魔方「模拟器」=站内 3D 渲染 + 转角动画 + 拖拽转动的新「类型」(不是一次性 HTML 页面)。当用户说"造某某魔方模拟器""给 /sim 加 X 魔方""新魔方类型""X cube simulator"时用。覆盖 SQ1/Ivy 模板契约、必改文件、Three.js 几何、拖拽转动(raycast+方向)、招式对接 solver、必踩的坑。区分:造"求解器"引擎走 skill new-substep-solver;本 skill 只管 /sim 的渲染+动画+交互集成。Triggers "造魔方模拟器", "造X魔方模拟器", "枫叶魔方模拟器", "给 /sim 加魔方", "sim 加魔方", "新魔方类型", "add puzzle to sim", "X cube simulator", "/sim 新增魔方", "魔方模拟器", "sim 拖拽转动".

Use when adding/editing user-visible text in the React client (core/packages/client). 站点只服 en + zh-Hans(简体);繁体已移除。文案统一走 tr({en,zh}) / <T en zh /> / useT() 的 t(zh,en) / t('ns.key')+en.json/zh.json。禁内联 isZh/i18n.language 文案三元(CI ratchet + PreToolUse hook 双守)。右上角 lang+theme 用 <HeaderToggles />。Triggers: "中英双语", "双语", "i18n", "translate", "翻译", "add Chinese/English", "isZh", "tr(", "useT", "LangToggle", "HeaderToggles", "主题切换", "右上角", "en.json", "zh.json", "useTranslation", new page, new user-facing string.

Use when user asks how mainstream/major sites or '业界/大厂' handle something (i18n、SEO/路由、定价、某 UX 模式、某功能) and expects AI to already know which sites to check. 按用途从下表挑 6-10 个,跨「巨头 + 本站近邻(开发者工具/SaaS/AI)」两类,然后亲自 WebFetch/WebSearch 核实再下结论,禁凭记忆。Triggers: "主流网站", "大厂", "业界怎么做", "别的网站怎么做", "对标", "benchmark", "mainstream sites", "how do big sites", "industry standard".

用户要更新 /scramble/stats(打乱难度 / 步数分布)的数据时执行本地手动增量刷新管道(按需触发,非定时)。覆盖三阶阶段难度(十字/F2L/EO/DR 等)+ 非 3x3 整解最优步数(二阶/金字塔/斜转/SQ1)+ 三阶整解最优 HTM(333 方法,cubeopt WASM,solver/333opt)三条管道。只能本地跑(三阶需 solver 34GB 表 / 333 需 cubeopt 表)。Triggers: "更新统计", "更新打乱统计", "重跑打乱统计", "更新打乱分布", "更新打乱难度", "update scramble stats", "全部刷新统计", "更新十字统计", "重跑十字统计", "跑十字管道", "更新 puzzle 统计", "更新二阶/金字塔/斜转统计", "更新 sq1 统计", "更新 SQ1 统计", "更新 sq1 分布", "刷新 sq1 精确分布", "sq1 精确分布", "sq1 精确档", "跑SQ1怪物", "跑 sq1 怪物", "啃怪物", "啃 sq1 怪物", "sq1 怪物", "grind sq1 monsters", "补 xcross 变体", "双色底 10f xcross", "backfill_xcross_variant", "pseudo_f2leo 回填", "难打乱补变体", "更新333统计", "更新 333 统计", "更新 333 整解统计", "333 整解最优", "333 HTM 分布", "333opt".

Use when user wants to fill in /code/architecture 第 11 节的日历 + 列表 — 从 JSON 最后一条日期之后开始, 把每个有 commit 的日子补上中英 1 行总结 (日历); 每个新页面/路由上线都加进 TIMELINE 数组 (列表)。Triggers: "/timeline-update", "更新 timeline", "补日历", "补 timeline", "update commit calendar".

Use when raw WCA result value (centiseconds/FMC/MBLD encoding) → display string. Single entry: utils/wca_format_result.ts. Triggers: "WCA 成绩", "成绩格式化", "formatWcaResult", "centiseconds", "FMC", "MBLD", "333mbf", "333fm", "DNF", "DNS", "0.28", "33.00", "slice(1,3)", "padStart(10", 渲染 WCA 成绩 / 纪录值 / PR / 比赛纪录.

Use when the user wants to add, rewrite, or refresh a chapter of the illustrated WCA Regulations guide at /regulation (hub + one page per chapter), OR when acting on a `regulation-drift` GitHub issue / the monthly drift check (official WCA regs changed). The user typically says "更新规则" then names the chapter(s) (e.g. 第十二章 转动表示方法 / 第四章 打乱 / Article 9 Events / Appendix B 盲拧). Covers: the sync/drift system (reg:check snapshot diff + the regulation_drift CI issue), the per-chapter full-clause data layer (reg:clauses + FullClauses), locating the chapter slug, fetching + paraphrasing the official article bilingually, building the page on the shared scaffold, the visualization toolkit, and the strict zh-Hant generator recipe. Triggers: "更新规则", "更新規則", "/update-regulation", "加规则章节", "刷新规则页", "改规则页", "WCA 规则页", "regulation 章节", "第N章规则", "规则漂移", "regulation-drift", "reg:check", "reg:clauses", "完整条款", "update regulation", "add regulation chapter", "regulation page", "/regulation".

Use when writing/editing CSS color values, backgrounds, borders, text colors, or dark/light theme behavior. shadcn-style token system + color-mix derivations + dark-locked page list. Triggers: "颜色", "color", "background", "background-color", "border", "text color", "--background", "--foreground", "--muted", "--accent", "dark mode", "light mode", "theme", "主题", "暗色", "深色", "dark/light", "shadcn", "hex", "rgba", "color-mix", "#888", "#aaa", "#fff", "prefers-color-scheme", "data-theme".

用户要造一个新求解器时用。**先分流**:3x3 子阶段 / 大状态空间(需 Rust+WASM+大表+真题统计管道)= 范本 block222,完整流程 solver/VARIANT_PLAYBOOK.md;非 WCA 小状态整解(可整枚举,如枫叶 Ivy 29,160 态)= 纯 TS 全 BFS,**不碰 Rust/WASM/管道**,范本 packages/client/lib/ivy-solver.ts(见正文 §0)。Triggers: "造个 X 求解器", "新求解器", "枫叶魔方求解器", "ivy 求解器", "非 wca 求解器", "小魔方求解器", "roux s1 求解器", "eoline 求解器", "petrus 求解器", "new substep solver", "加一个 step solver", "块求解器", "新变体", "new variant solver".

Use when 改 Hono server routes (`core/packages/server/**`) 或 PG schema (ALTER/新表/新列)。GH Actions 部署,pm2 进程。Triggers: "cuberoot_db", "core-api", "deploy server", "ALTER TABLE", "pm2 restart", "server 部署", "加列", 改 server 路由.

Use when rendering country flags anywhere in UI (JSX or popup innerHTML). Single entry point: utils/flag.tsx. TW special case (WCA uses Chinese Taipei SVG not flag-icons default) is handled there — do not hand-write. Triggers: "国旗", "flag", "flag-icons", "ChineseTaipei", "台湾国旗".

Use when adding a long-form intro page under /code/* — 一件软件/语言/算法/概念“一页一篇”。全在 client (Next App Router, app/[lang]/code/*),不是退役的 Vite client。覆盖 /code/stack/* (数据驱动,3 文件)、/code/language/* + /code/algorithms/* (各自 <slug>/page.tsx 路由),结构同构 (hero / history / concepts / why / adopters / outlook / cuberoot 用法 / links)。Triggers: "/code", "/code/stack", "/code/language", "/code/algorithms", "stack_tools", "STACK_TOOLS", "加 stack 工具", "add code subpage", "新建语言介绍", "介绍 github", "介绍 curl", "介绍 vscode", "复刻 git.tsx", "复刻 ts/page.tsx".

Use when regenerating `stats/scramble/*.json` or touching `core/packages/scramble-stats-build/` / `core/packages/client/app/[lang]/scramble/stats/`. Covers CSV 列名、pair rotation 记号、WCA 配色、UI 朝向→底色。Triggers: "scramble-stats-build", "distribution.json", "打乱分布", "scramble_stats".

Use when regenerating `stats/comp_names_zh.json`, debugging Chinese comp names, or displaying comp name in new code (must go through `utils/comp_localize.ts`, never raw `c.name`). Triggers: "中国比赛中文", "localizeCompName", "comp_names_zh", "fetch_comp_names_zh", "比赛名本地化", "stripWcaPrefix", "localizeCity", "CITY_ZH".

Use when rendering WCA cuber / person names anywhere in UI (tables, cards, chips, popups, badges). WCA API returns names like "Xuanyi Geng (耿暄一)" with parenthesized Chinese — we never keep the parens. Triggers: "选手名", "cuber name", "displayCuberName", "括号中文", 渲染 person 列.

Use when adding new public/static files to the site — images, fonts, geojson, textures, WASM modules. Live site is Next.js: assets go in client/public/ (no repo-root copy, no whitelist). Shared fork/stats static lives in tools/ + stats/ served by static.cuberoot.me. Triggers: "new public asset", "404", "public/", "textures/", "加静态资源", "static asset", "public 资源".

Use when adding/changing a page's browser tab title (the `<title>` / `document.title` text shown in Chrome tab strip and history). Single entry point: `useDocumentTitle(zh, en)` hook in `utils/useDocumentTitle.ts`. Auto-flips on LangToggle, auto-cleans up on unmount. NEVER write `document.title = ...` in new code. Triggers: "tab 名", "tab 标题", "浏览器标题", "页面标题", "document.title", "document title", "tab title", "browser title", "网页标题", "useDocumentTitle".

Use when adding content under /math/* — 给数学板块补内容。两种模式:(A) 给已有长篇"书"页(如 /math/group 魔方与群论,62 节;/math/god)加新一节;(B) 加一个全新 /math 顶层主题页。全在 client (Next 16 App Router, app/[lang]/math/*)。覆盖自包含 section 文件 + dynamic 懒加载 + slug 路由 + 双语 + 手写交互 SVG。Triggers: "/math", "math/group", "math/god", "群论", "加群论章节", "加一节", "math subpage", "加数学页", "数学长文", "扩充 /math", "add math section", "new math page", "math hub", "对称群", "群论可视化".

Use when porting / forking / integrating an open-source project into this repo. Single-source credits via credits_data.json. Triggers: "复刻", "port", "fork", "vendored", "加致谢", "credit", "upstream", "credits_data.json".

写 / 改 Claude Code 拦截钩子(PreToolUse guard hook)时用 —— 写入或命令执行那一刻拦违规(裸 history、button 当导航、手写繁体、危险命令、自启浏览器等)。给出 JSON-deny 模板(pwsh + node)、scope/豁免/fail-open 约定、以及必须真触发验证的方法。本环境 auto 权限模式会静默忽略 exit 2,务必照此写。Triggers: "写 hook", "加 hook", "改 hook", "PreToolUse", "拦截钩子", "写入即拦", "guard hook", "block-button-navigation", "block-raw-history", "block-handwritten-trad", "block-next-build", "guard-browser-launch", "permissionDecision", "hook 不生效", "hook 没拦住", "settings.json hooks", "write a hook", "pretooluse hook".

改 solver/ 引擎的表(新增/删/改大小/改某分析器加载哪些表, 尤其优化 f2leo/pseudo_f2leo 加大表)后必须同步 /code/solvers 页的 TABLES 常量。该数据是硬编码快照(*.bin 在 solver/tables/ gitignored, repo/CI/线上都没有 → 无法 build/runtime 自动拉, 只能手维护)。Triggers: "solvers 页", "求解器看板", "/code/solvers", "优化 f2leo", "f2leo 性能", "pseudo_f2leo", "加大表", "新增剪枝表/移动表", "改 solver 表", "table_generator", "analyzer 加载表".

Use when rendering NxN cube state image. Single entry: `<VisualCube>` / `cubeSVG()` from `@cuberoot/visualcube`. 手写 `<rect>` SVG = bug. Triggers: "魔方图片", "cube image", "VisualCube", "MiniCube", "JcubeThumb", "F2L 图", "OLL 图", "PLL 图", "ZBLL 图", "立方体预览", "facelets", "NxN cube", "2x2 / 4x4 / 5x5 thumbnail".

Use when writing a new client-side API helper for any 'public GET + admin write' Hono route (alg_sets / wiki / ops / nav_sites 模式). 强制从 utils/admin_api 复用 authHeaders + handleApi, 不要每个新 file 再 paste 一份 getToken/authHeaders/handle. Triggers: "client api helper", "admin api", "authHeaders", "handleApi", "X-Admin-Key", "wiki_api", "alg_sets_api", "ops_api", "加新 api util".

Use when writing SQL against local wca_developer_database MySQL dump, or refreshing it from WCA developer export. Covers snake_case schema, key tables, join idioms (sub_id=1/rank<900), value encodings (DNF=-1/DNS=-2/FMC/MBLD), records markers, refresh script. Triggers: "WCA SQL", "WCA dump", "WCA schema", "results 表", "competitions 表", "event_id", "person_id", "result_attempts", "regional_single_record", "sub_id", "更新 WCA dump", "刷新 WCA", "wca export", "wca-developer-database-dump", "update_database".

渲染 WCA 项目名/图标/选择器时用。(1) 图标走 `<EventIcon>` 或 `<CubingIcon>` (内联 SVG,components/EventIcon),禁 `<span className="cubing-icon ...">` (空 span)。(2) /wca 子页选项目用 `<WcaEventSelector>` 21 图标行,不用 `<EventSelect>` 下拉。Triggers: 项目名, EventIcon, CubingIcon, cubing-icon, WcaEventSelector, 项目选择器, event picker, eventDisplayName.

Use when touching WCA competition JSON (upcoming_comps/all_past_comps), their consumers, or any comp picker/search UI. Triggers: "比赛 JSON", "upcoming_comps", "all_past_comps", "competition schema", "比赛数据源", "比赛搜索", "CompPicker", "comp picker", "搜比赛".

Use when 测/诊断/优化页面加载速度 (LCP / FCP / bundle 大 / 加载慢 / 首屏)。三件套:PageSpeed Insights API (拿 CrUX 真用户 Web Vitals) + playwright resource panel (看运行时加载) + visualizer .tmp/bundle-stats.json (jq 解析 chunk 内部)。Triggers: "页面慢", "加载慢", "测速度", "测加载", "bundle 大", "perf", "首屏", "LCP", "FCP", "Web Vitals", "PageSpeed", "WebPageTest", "chunk 太大", "lazy load", "动态 import", "瓶颈".

渲染 WCA 纪录标志(WR/CR/NR/AsR/ER/NAR/SAR/OcR/AfR/PR/cancelled 等)时用。单一入口 `<RecordBadge>`。Triggers: WR, CR, NR, AsR, ER, NAR, SAR, OcR, AfR, record badge, 纪录标志, RecordBadge, formatRecord.

Use when regenerating WCA statistics JSONs under `stats/` — 80+ SQL-driven stats (average_of, wr_metric, world_records_by_country, longest_streak_*, etc.). Covers compute.ts CLI, memory flags, registry, adding new stats, StatJson schema. Triggers: "stats-build", "compute.ts", "wr_metric", "重跑 stats", "new stat", "Statistic 基类".

Use when adding a help/info icon next to a page title that explains the page (intro / flow / engine choices). Pattern: lucide HelpCircle inside react-router Link → standalone /<page>-about route. Triggers: "标题问号", "页面问号", "help icon", "info icon", "about page", "说明页", "介绍页", "intro page", "HelpCircle", "问号按钮", "页面介绍".

Quick HTML mockup to compare 2+ UI options before deciding. Triggers: 画示意图, mockup, UI 草图, 方案对比.

Use when adding / editing 运维命令 or AI 提示词模板 to /code/ops page (db/build/deploy/backup/prompt 5 类). DB-backed:走 X-Admin-Key 端点 (`api.cuberoot.me/v1/ops/commands`),非源码改动。Triggers: "加运维命令", "ops command", "runbook 加一条", "/code/ops", "加到运维页", "OpsPage", "加提示词", "prompt 模板", "ops_commands".

Use when 改 stats-build → server PG 数据流 (新 .copy.tsv / builder 输出 / stats.yml scp 清单 / load.sql)。builder ↔ scp ↔ load.sql 三处必须一致,少一处 = 服务器表静默空。Triggers: "stats.yml", "historical_ranks_build", "wca_stats_extra_build", "load.sql", "\\copy", ".copy.tsv", "scp historical_ranks", "stats workflow scp", "加新 stat 表", "新 builder 输出".

Use when AI/脚本管理 alg DB (create/update/del/reorder/batch-validate/dedup) 免 OAuth。X-Admin-Key 通道 + 4 个 admin endpoints + 直 SQL playbook。Triggers: "alg admin", "X-Admin-Key", "reorder cases", "del alg case", "alg dup", "批量校验 alg", "AdminCaseEditor", "alg_cases SQL".

Use when building UI with cubing.js TwistyPlayer + alg input + caret-driven move sync (alg/recon/admin/training pages). Code uses `alg`, not `formula`. Triggers: "cubing.js", "TwistyPlayer", "AlgPlayer", "TwistySection", "光标同步", "caret sync", "syncPlayerToMoveCount", "AlgInput", "alg input", "输入 alg", "虚拟键盘", "CubeKeyboardSection", "动画跟随", "alg player".

Use when rendering WCA competition dates anywhere in UI (popups, cards, modal headers, day list, bin-panel). All dates must be ISO yyyy-mm-dd; cross-day ranges use compact form (2026-06-06~07) — never locale month names (May 1–3). Triggers: "比赛日期", "日期区间", "date range", "start_date end_date", "2026-06-06~07".