class-copilot-theme-package

name	class-copilot-theme-package
description	根据给定的视觉概念创建或扩展 Class Copilot 内置主题包，包括生成位图素材、导出运行时 WebP、定义浅色/深色 Token、注册主题、添加作用域 CSS 与可选原生图标，并验证完整接入。适用于本仓库端到端的主题包工作，不用于单独调色或小型 UI 缺陷修复。

Class Copilot 主题包

创建视觉统一、可离线使用的内置主题，并且不在业务页面中添加针对具体主题的分支。以当前代码中的主题契约为准；现有角色主题仅供参考，不应机械复制。

判断任务范围

• 仅设计或生成图片素材时，读取 references/asset-production.md。
• 接入用户提供或已经批准的素材时，读取 references/integration.md。
• 端到端制作主题包时，按上述顺序读取两份参考文档。
• 用户要求先提供初稿审核时，在约定的审核节点停止。视觉方向未经批准，不要继续开展大范围代码改动。

明确制作简报

结合用户请求和仓库现状，确定：

• 稳定的 kebab-case 主题 ID 和面向用户的主题名称；
• 主题概念来源、可识别特征、排除项及使用授权；
• 支持的 light / dark 模式，以及两种模式是否需要不同素材；
• 必需的运行时素材槽位，以及原生应用图标、托盘图标是否在范围内；
• 用户需要素材生成、代码接入，还是完整流程。

仅当缺失信息会实质改变视觉识别、授权边界或实现范围时再提问。不得自行推断用户有权发布或商业分发第三方角色素材。

遵守项目契约

• 修改前读取 AGENTS.md，并检查 src/themes/types.ts、src/themes/registry.ts、src/themes/resolveTheme.ts、一个现有预设及其作用域 CSS。
• 保持 themeId 稳定，并把它加入强类型注册表。修改显示名称不得改变已经持久化的 ID。
• 通过 AppThemeDefinition、Ant Design Token、--app-* 变量、素材槽位和 [data-app-theme='<id>'] 选择器表达主题能力。
• 仅深色模式不同的内容放入 variants.dark 和 assetOverrides.dark；消费者必须通过 getThemeAssets() 或 useAppThemeAssets() 获取素材。
• 保持成功、警告、错误、考勤、成绩和只读状态的业务语义色。主题只改变品牌表达，不改变业务含义。
• 运行时素材必须保存在本地并静态导入压缩后的 WebP；禁止导入 PNG 母版或拼接无类型约束的运行时路径。
• 不得在普通业务页面中添加 themeId === '<id>' 分支。只有现有素材契约确实不足时，才扩展共享主题消费者。
• 保留工作区中与任务无关的未提交改动。除非用户明确要求且具备必要权利，否则不要提交、发布或分发生成的角色素材。

执行流程

1. 生成素材前，先定义精简的视觉方向和 Token 色板。
2. 先生成视觉锚点，通常是 mascot-main；后续槽位以它为参考，保持轮廓、配色、材质和光照一致。
3. 检查每张生成的位图并保留 PNG 母版。只有经过批准的素材才能导出为运行时 WebP。
4. 实现主题预设、注册表条目、作用域 CSS、CSS 导入和测试；原生图标在任务范围内时再接入。
5. 运行确定性校验和相关仓库测试。遵守仓库规则：自动检查应用 UI 必须获得用户明确授权，但素材本身仍需检查。

创建或编辑位图时，使用已安装的 imagegen Skill 和图片生成工具。对于用户要求的角色或插画素材，不得用程序化绘图替代。

辅助脚本

导出已识别的 PNG 母版；默认不覆盖现有运行时文件：

node .agents/skills/class-copilot-theme-package/scripts/export-theme-assets.mjs <theme-id>
node .agents/skills/class-copilot-theme-package/scripts/export-theme-assets.mjs <theme-id> --mode dark

只有确认对应主题和模式的输出可以被替换后，才传入 --force。

验证完整主题包：

node .agents/skills/class-copilot-theme-package/scripts/validate-theme-package.mjs <theme-id>

随后至少运行：

npm run lint
npm run typecheck
npm test -- --maxWorkers=1
npm run build
git diff --check

修改 Rust 图标选择逻辑或 Tauri 配置时，再运行 cd src-tauri && cargo test。

交付说明

说明主题 ID/名称、支持模式、已生成与省略的素材槽位、Token/CSS 作用范围、注册与原生图标改动、自动化检查结果，以及仍需人工完成的视觉检查。必须明确披露授权或源素材限制。