8.2 KiB
8.2 KiB
name, description
| name | description |
|---|---|
| create-cc-web-theme | 为 cc-web 创建、复刻、重做或审计视觉主题，从参考图、概念图、背景图、图标板或素材板完成需求澄清、源素材归档、主题隔离、可复现切图、CSS/DOM 接入、响应式、回归和真实浏览器视觉验收。用户提到新建主题、换肤、复刻设计稿、主题高保真、主题对比、切图、图标重做、欢迎卡、输入框装饰框、消息气泡磨砂、视觉错位或主题返工时使用。 |
创建 cc-web 主题
把参考设计转成一个独立、可切换、可维护并经过真实浏览器验收的 cc-web 主题。保留设计证据和生成链路，避免只留下无法继续扩展的最终切片。
按需读取参考
- 开始定位主题系统前，读取 cc-web-theme-architecture.md。
- 收到背景、图标板、边框板或概念图时，读取 asset-workflow.md。
- 遇到“不像设计图”“改了没变化”“边框/图标/透明度/居中反复不对”时，读取 lessons-learned.md。
- 准备声明完成前，完整读取并执行 acceptance-checklist.md。
遵守硬约束
- 为新主题创建新的稳定主题 ID 和独立资产目录。除非用户明确要求，禁止覆盖、重命名或删除现有主题。
- 修改前检查工作树与相关文件差异。保留用户和其他任务的未提交改动，不格式化或重排无关大文件。
- 先归档所有源概念图、素材板和背景，再生成派生资产。保留裁剪脚本、坐标、manifest 和来源哈希。
- 把参考图当作构图与层级契约，不只提取颜色和“氛围”。先量化，再编码。
- 只使用本地主题资产。禁止让产品运行时依赖参考站点、临时附件 URL 或远程图片。
- 同步维护静态首屏 DOM 与动态渲染 DOM。动态项目名、Agent、会话标题等内容禁止写死在静态模板中。
- 只修改用户指出的层级。用户说“气泡背景”时，不得顺手重做所有卡片、工具层或布局。
- 自动化通过不等于视觉完成。没有真实浏览器对照、动态状态检查和多视口验收时，不得声明完成。
- 不删除源图、概念图、素材板、切片或提取脚本；后续功能可能需要重新切片。
- 需要重启 cc-web 时，先按仓库
AGENTS.md检查其他运行中会话；不满足条件时不重启。
执行工作流
1. 固定需求和完成标准
明确并记录：
- 新建、复刻、扩展还是修复主题。
- 主题稳定 ID、显示名、是否与旧主题并存、默认主题是否变化。
- 参考图、背景图、图标板、边框板、字体和其他输入素材的角色。
- 用户要求保留的既有视觉与明确禁止改动的区域。
- 参考图原始视口、桌面目标视口和移动端目标视口。
- 必须覆盖的动态状态：空会话、长消息、多行输入、工具调用、展开菜单、运行/停止、弹层和窄屏。
在任务资料中建立资产表和验收清单。输入素材含义不明确且会影响构图或切片时，先向用户确认。
2. 建立代码与改动基线
优先使用 codebase-memory-mcp：
- 调用
list_projects和index_status(project="home-cc-web")。 - 使用
search_graph/search_code定位主题注册、应用、静态 bootstrap、动态 welcome 和回归入口。 - 需要调用关系时使用
trace_path，需要源码时先取得qualified_name再调用get_code_snippet。 - 最后使用
rg和git diff校验文本、行号与未索引资源。
记录主题相关脏文件、既有主题 ID、缓存版本、共享选择器和任务开始时的资产清单。只在明确边界内修改。
3. 把参考图拆成可验证规格
先输出“参考区域 → 实际 DOM → 资产 → CSS 责任”的映射，再实施。
至少量化：
- 侧栏、顶栏、消息区、输入区的比例和基线。
- 主视觉安全区、文字阅读区和背景裁切/遮罩策略。
- 面板层级、透明度感知、边线宽度、阴影和切角使用范围。
- 每类控件的容器尺寸、图标视觉主体、间距和光学中心。
- 固定尺寸与动态高度组件的区别。
- 静态空页面和有内容页面的布局差异。
先处理背景与大布局，再处理容器层级、边框、图标和微交互。禁止从局部颜色微调开始掩盖结构偏差。
4. 建立可复现资产链路
把源素材复制到当前主题任务的 references/source-assets/，不要只引用会话附件路径。为每个派生资产保存：
- 源文件名和哈希。
- 源裁剪框、规格或素材板单元格。
- 输出尺寸、格式和用途。
- alpha/颜色分离方法和必要的光学校正。
- 生成脚本与 manifest。
按用途选择实现：
- 背景保留构图和清晰度，遮罩只服务可读性。
- 主交互小图标优先使用干净 mask 或对应尺寸切片；多色状态、头像和装饰图标保留原色。
- 非对称图标按 alpha 加权重心校正，不按透明画布机械居中。
- 固定尺寸框可使用完整切片；动态高度框优先使用
border-image/九宫格或拆分稳定边角，禁止把固定比例整图放在伪元素上随内容拉伸。
具体方法见 asset-workflow.md。
5. 分层、隔离地接入主题
按以下顺序实现：
- 在
THEME_OPTIONS新增主题元数据，保持单一数据源。 - 检查首屏 bootstrap、
normalizeTheme()、applyTheme()和本地持久化是否接受新 ID。 - 在
html[data-theme='<id>']变量块中先定义语义 token。 - 把新暗色主题加入确实需要复用的共享 completion selector。
- 把高风险视觉放在文件后部的主题专属组件层，所有选择器都限定主题 ID。
- 把资产放入
public/assets/themes/<id>/，避免根目录同名覆盖。 - 同步静态
index.html和动态构建函数中的 welcome/装饰 DOM。 - 检查真实 DOM 内原生文字、SVG、图片和主题伪元素，防止加号、头像、图标或边框重复。
- 更新 CSS/JS cache bust，并同步回归契约。
不要为了视觉方便复制第二套业务逻辑、主题列表或交互组件。
6. 用真实浏览器形成短反馈环
先按参考图原始尺寸验收，再检查常规桌面和窄屏。每轮只解决一个明确层级，并记录修改前后证据。
遇到异常时按顺序排查：
- 浏览器是否实际加载了最新缓存版本和资源。
- 选择器是否命中真实 DOM，伪元素或原生子节点是否重复。
- computed style 的最终来源和 specificity，特别检查
:is()与旧!important。 - 外层看似透明时，内层工具块、标题层或伪元素是否仍不透明。
- 动态高度、文字换行、菜单展开和运行状态是否改变真实尺寸。
- 几何中心、文字基线和图标 alpha 重心是否一致。
优先测量，不盲调数值。把“看着偏”转换为中心差、边距、主体 bbox、computed background 或溢出量。
7. 完成工程与视觉验收
执行 acceptance-checklist.md 的全部强制项，至少包含：
- JS 语法检查、主题专项回归、相关旧主题回归、全量回归和
git diff --check。 - 本地资产存在性、格式、尺寸、hash/manifest 与 HTTP 200。
- 参考视口、常规桌面和窄屏的真实浏览器检查。
- 空页面、长内容、多行输入、菜单、工具块、按钮状态和动态文案检查。
- 与参考图逐组件对照，确认没有多余边框、重复图标、视觉实心层或明显错位。
最后报告实际视觉证据、验证命令和保留的源资产/脚本路径。测试失败、浏览器不可用或视觉证据不足时明确说明，保持任务未完成状态。
交付要求
- 列出新增主题 ID、资产目录、源资产归档和提取脚本。
- 列出修改过的主题链路文件与隔离边界。
- 给出真实浏览器实测结果，不只写“回归通过”。
- 说明仍未覆盖的视口、状态或素材限制。
- 保留所有主题概念图、素材板、切片、manifest 和生成脚本。