Cook Web Skills

Cook Web Skills

Layering Rules

• Keep SKILL.md for long-lived cross-page or cross-module constraints and the skill index.
• Keep skills/xxx/SKILL.md for scenario-specific triggers, execution steps, and acceptance checks.
• SKILL.md must not carry long troubleshooting playbooks; workflow-heavy content belongs in focused skills.
• Stable structural rules should go to the local AGENTS.md / CLAUDE.md first. Only workflow-oriented guidance should live in a skill.

Project-Wide Constraints

• Treat URL parameters as explicit overrides: use lessonid for lesson targeting, let listen query override learner mode when present, and fall back to course-level tts_enabled to decide whether listen mode is available while keeping read as the default. When no course-scoped course_learning_mode:* storage exists yet and there is no explicit URL override, persist the resolved default mode immediately so first-load behavior and local storage stay in sync.
• 学习页如果要新增和初始化模式有关的埋点，优先在写回 course_learning_mode:* 之前先读取并上报原始 localStorage 值，避免“首进自动补写默认值”覆盖掉用户上一次真实固定的模式。
• 当 listen=true 先以听课模式初始化、后续又因为旧课兼容或能力检查回退到阅读模式时，要基于当前模式重新同步移动端正文里的追问按钮，不要只依赖首轮数据装配结果。
• Streaming chat must use element_bid as the stable render key, with compatibility fields backfilled in the shared normalization entry point.
• When the same logic is reused by more than two files, extract it into shared utils/constants/hooks instead of duplicating it.
• 做 i18n key usage 排查时，不要把 *.test.*、*.spec.*、__tests__ 里的断言文案、namespace 字符串或拼接后的展示文本当成真实翻译 key；优先统计生产代码里的 t()、i18n.t()、Trans 和符合完整 key 结构的常量。
• 积分套餐权益文案优先以 BillingOverviewCards 里的共享 feature key 列表作为单一来源；删除某项权益时，要同时清理 billing.json、预注册翻译使用代码、相关测试数据和 i18n-keys.d.ts 残留。
• 账务/积分页面如果同一类时间展示同时出现在卡片、表格或 tooltip 中，优先抽到 src/lib/billing.ts 的共享格式化方法；涉及多语言文案时，同步更新所有支持的 locale、i18n-keys.d.ts 和对应组件测试，避免只改页面不改类型与回归用例。
• 账务/积分相关用户可见文案必须遵守产品命名边界：不要使用“充值”或 top-up / recharge 语义；覆盖套餐和积分包两种补充积分路径的正文，使用“开通订阅或购买积分”，且订阅优先；明确只指 topup 商品、订单、账本来源或 checkout 时使用“积分包”；按钮和短 CTA 保持简洁，使用“购买积分”；用户可见文案使用“账户”而不是“钱包”。内部 topup / wallet 字段、路由、枚举和 i18n key 可保留技术命名，但不得直接作为展示文案。
• 积分详情页的“积分消耗明细”表格优先复用 src/app/admin/components/AdminTableShell.tsx 和标准 Table 组件；分页走 AdminTableShell.pagination，不要在 billing 组件里另写卡片表格和独立分页外壳。
• 仅服务后台路由且依赖 src/app/admin/components/* 的 billing 组件，应放在 src/app/admin/billing/components/ 这类同路由作用域下；src/components/* 里的共享组件不要直接 import src/app/* 的 route-internal 实现，避免触发架构边界校验。
• AdminTableShell 内的表头默认保持左对齐；如果某些 body 单元格需要右对齐，只在 body 内容层处理，不要把表头也右对齐。自定义骨架屏行放进 AdminTableShell 时要禁用 hover 背景，避免加载翻页时出现整行灰色条。
• 账户余额、可用积分、侧边会员卡余额这类“积分余额”展示统一只保留整数部分；套餐赠送额度、购买额度、消耗量等非余额数字继续使用通用积分格式化方法，避免把两类数字口径混用。
• 当产品要求把套餐赠送积分数、免费体验积分和积分包额度也统一成整数展示时，优先复用 src/lib/billing.ts 的共享积分数量格式化方法，确保套餐卡、免费卡、积分包卡和对应测试口径一致。
• 积分消耗明细表格迁移到 AdminTableShell 后，列宽优先让“消耗项”占最大宽度，时间列居中偏右，数量列贴近最右侧对齐；不要在时间列保留旧版 grid 表格里的 text-right、justify-end 或 ml-auto 残留，数量列如需靠右可只在该列内容层使用 justify-end/ml-auto。加载骨架屏行需要同时禁用 tr:hover 和 td:hover 背景，避免翻页 loading 时出现整行灰色条。
• admin 侧边会员卡如果改成双层信息布局，保持整卡点击跳转 packages、底部“查看详情”独立跳转 details，并把积分余额与到期时间放在同一信息层；卡片整体内边距优先保持 py-14px / pl-16px，右侧需要贴设计微调时可收敛成 pr-12px。若设计稿要求顶部“积分 + 升级”这一整行整体左收 4px，优先给这一行的外层容器补 padding-right，不要误加到升级按钮本身；查看详情 默认不要额外补右侧内边距。头部与信息层之间优先用弱分隔线 rgba(0,0,0,0.05)，分隔线下余额行 pt-3、到期/详情行 pt-2.5，正文颜色优先复用 --base-card-foreground 和既有 text-sm typography token。
• 14px 文字旁边的 chevron 类图标，优先收敛到 h-4 w-4，并让容器使用 items-center + leading-none、文字单独保留 leading-5，避免图标因继承文本行高出现视觉不对齐。
• 同一 billing 页面如果两个 section title 需要完全一致，优先把标题 class 抽成 src/components/billing/ 下的共享常量或共享组件，再让各面板复用，不要在两个文件里各写一份近似但不一致的字号。
• 同一 billing 页面如果多个 section title 需要保持一致，除了标题字号本身，还要同步检查标题到卡片/表格主体的纵向间距；当前这类 section 优先统一为 24px，避免一个 space-y-4、一个 space-y-6 的情况。
• admin 页面里这种二选一 tabs/switch 如果产品要求“选中态和未选中态的圆角一致”，优先在具体页面同时覆写 TabsList 和 TabsTrigger 的圆角，不要只改外层容器导致内部 trigger 仍保留另一套圆角。
• admin 页面头部如果有单一主创建动作（如“新建课程”），优先复用 Button 的默认主按钮样式，保持蓝底白字；不要继续沿用 outline 让主 CTA 在信息层级上变弱。
• /admin/operations 运营模块下的页面使用面包屑导航，优先复用 src/app/admin/components/AdminBreadcrumb.tsx 和 src/app/admin/operations/AdminOperationsBreadcrumb.tsx；课程首页、数据、订单、账务等非运营 admin 页面通过 AdminTitle、tabs 或页面主体表达层级。
• /admin 课程首页顶部布局中，标题下方操作区左侧放课程筛选 tabs（如“全部/归档”），右侧放课程创建入口；OpenClaw 智能建课引导文案应放在新建课程按钮左侧，不要和标题挤在同一行。
• /admin 课程首页的 tabs 与新建课程工具行默认不要额外添加上下 padding，底部间距保持 32px；新建课程按钮默认只展示文字，不展示左侧加号图标，确保右侧操作视觉更简洁。
• /admin 课程首页课程筛选 tabs 外层使用 10px 圆角、--base-muted 背景和 3px padding；选中项使用 8px 圆角、1px 边框、白色背景、shadow-sm 变量阴影和 4px 8px padding。
• /admin 课程首页里整张课程卡片如果承担的是进入作者工作台的导航，默认使用新标签页打开，避免打断当前课程列表浏览和筛选上下文。
• /admin 课程首页课程卡片头像统一使用 28px 正方形和 8px 圆角，头像与课程名间距保持 12px 且垂直居中；无头像时背景使用 #CFCED4，占位图标使用 public/icons/logo.svg 且尺寸保持 16px x 19px，不要再使用 TrophyIcon 作为占位图标。
• /admin 课程首页课程卡片标题使用黑色、16px、500、20px line-height，描述距离头像所在标题行下方 16px，描述使用 rgba(10,10,10,0.65)、14px、400、20px line-height。
• /admin 课程首页课程卡片容器统一使用 --border-radius-rounded-xl、--base-border、--base-card 和 shadow-sm 对应 CSS 变量，不要再使用 slate border 或默认背景替代。