# cc-web 主题架构与修改边界

## 目录

1. 代码定位顺序
2. 主题运行链路
3. CSS 分层
4. DOM 双路径
5. 资产与回归
6. 脏工作树与服务约束

## 1. 代码定位顺序

不要依赖固定行号。按符号和稳定文本定位：

1. `public/app.js`
   - `THEME_OPTIONS`
   - `normalizeTheme`
   - `applyTheme`
   - `buildThemePickerHtml` / `mountThemePicker`
   - `buildWelcomeMarkup`
2. `public/index.html`
   - CSS 加载前的主题 bootstrap
   - 静态 welcome DOM
   - CSS/JS cache-busting query
3. `public/style.css`
   - `html[data-theme='<id>']` 语义变量
   - 共享暗色 `:is(...)` completion selectors
   - 文件后部的主题专属组件层
   - 响应式与 `prefers-reduced-motion`
4. `scripts/regression.js`
   - `assertFrontend<Theme>ThemeContract`
   - `--target <theme>-theme`
   - 全量回归入口
5. `public/assets/themes/<id>/`
   - background、frames、icons、textures、manifest

先用 codebase-memory 找符号和调用关系，再用 `rg` 核对资源文本与最终位置。

## 2. 主题运行链路

```text
THEME_OPTIONS
    ├── 设置页主题候选 / label / desc / swatches
    ├── normalizeTheme() 判断持久化值是否合法
    └── applyTheme()
          ├── document.documentElement.dataset.theme
          └── localStorage['cc-web-theme']

index.html bootstrap
    └── CSS 加载前写入 data-theme，避免首屏闪烁

html[data-theme='<id>']
    └── 语义变量 → 共享组件 → 主题专属组件层
```

主题列表只维护一份。不要在设置页或其他弹层硬编码第二份主题候选。

### 新主题 ID

- 使用稳定、小写、可长期保留的 ID。
- 新主题默认新建 ID；不要借用隐藏主题、历史主题或另一个风格的 ID。
- 保留旧主题用于对比时，不修改其 label、资产和 selector。
- 如需迁移旧 ID，明确写出 `旧值 → 新值`，并增加回归断言。

## 3. CSS 分层

按以下层次组织：

1. **语义变量层**：背景、文字、边线、强调色、面板色。
2. **共享 completion 层**：只放多个暗色主题确实共用的组件补齐。
3. **基础 UI 层**：不因单个主题改变业务布局或交互。
4. **主题专属层**：背景、边框、图标、welcome、特殊响应式。

专属层应放在共享规则之后，并限定 `html[data-theme='<id>']`。当后置规则仍无效时，检查 specificity，而不是继续追加更宽泛的选择器。

### `:is()` 风险

`:is()` 的 specificity 取参数中最高值。共享规则例如：

```css
:is(
  html[data-theme='a'] .msg.assistant .msg-bubble,
  html[data-theme='b'] .msg.system .msg-bubble[data-tone='info']
) { ... }
```

可能比后面的普通主题规则更强。出现“backdrop-filter 变了但 background 没变”时，必须查看 computed style 的规则来源；必要时使用同级 specificity 或只对冲突声明使用精确 `!important`。

## 4. DOM 双路径

welcome 页面同时存在：

- `public/index.html` 的静态首屏结构。
- `public/app.js` 的 `buildWelcomeMarkup()` 动态结构。

新增图层、class、无障碍属性、文案节点或图片时必须同步两处。

动态数据必须由 JS 统一填充，例如：

- 当前项目名称来自 `cwd`。
- 当前 Agent 名称来自运行时状态。
- 当前会话标题来自 snapshot。

静态 HTML 只保留可定位的空节点或不依赖运行时的数据。回归必须断言静态模板没有写死动态名称。

### 重复视觉来源

实现主题图标前检查实际 DOM：

- 文本 `+`、`▾`、`…`。
- 内联 SVG。
- `<img>` 头像。
- 基础主题已有的 `::before` / `::after`。
- 新主题 background/mask。

同一语义只保留一个可见来源，并只在当前主题下隐藏旧来源。

## 5. 资产与回归

推荐目录：

```text
public/assets/themes/<theme-id>/
├── background.webp
├── frames/
│   ├── manifest.json
│   └── *.png
├── icons/
│   ├── manifest.json
│   └── *.png
└── textures/
    └── *.webp
```

专项回归至少覆盖：

- 主题注册、可见性和迁移策略。
- 变量块和专属组件层存在。
- 新主题加入必要共享 selectors。
- 静态/动态 welcome 同步。
- 本地资产格式、尺寸、hash 或 manifest。
- 禁止远程 URL。
- 动态组件的结构契约，例如可伸缩输入框不依赖固定伪元素。
- 响应式、reduced-motion、文字对比度。
- cache bust 与在线加载版本一致。
- 旧主题专项回归继续通过。

回归验证结构和不变量，不替代像素与构图验收。

## 6. 脏工作树与服务约束

- 实施前执行 `git status --short` 和主题相关精确 diff。
- 记录相关文件的起始状态；只修改目标区块。
- 不使用 `git reset --hard`、`git checkout --` 或整文件还原保护自己生成的改动。
- 多会话可能同时修改 `app.js`、`style.css`、`index.html` 和 `regression.js`。发现反复回写时停止覆盖，先协调写入边界。
- 修改静态文件通常不需要重启服务。需要重启 cc-web 时，严格执行仓库 `AGENTS.md` 的运行会话检查。
- 浏览器访问失败时先用 `curl http://127.0.0.1:<port>` 检查本地服务，再按 `hostname -I` 使用 `11.144.144.*` 地址排除网络命名空间问题。