# ui-skin-qq2006 — QQ2006 皮肤契约（子智能体必读）

把 DSH WebUI 改成 QQ2006 外观的可切换皮肤。**默认皮肤零回归是硬约束**。

## 机制（地基已完成，勿改动）

- 皮肤 = 插件自带开关（`settings.general.item`，DSH ≥ rc.7 另有
  `settings.plugin.item` 卡片）。当前上游 Appearance 行仍只渲染 light/dark/system
  （到 `dsh-v0.1.2-alpha.1`）。开启后走 `theme.overrideTokens`（新）或
  `register` + `setTheme('qq2006')`（旧），偏好持久化在 `dsh.qq2006.enabled` /
  Host settings 命名空间 `qq2006`。0.1.2 起开关文案注册到 `settings.qq2006`。
- 生效标志：`body[data-ds-skin='qq2006']`（插件镜像 + boot.tsx 提前恢复，加载页也能被皮肤）。
- 全局皮肤表：`src/styles/qq2006.css`（插件自己注入；npm 安装看不到 monorepo
  `base.css`）。含字体、滚动条、九宫格工具类、以及 **stock DSH 壳层覆盖**
  （`#root` 蓝标题栏、侧栏、输入区、`role=dialog`）。`.qq-skin-*` / `.qq-btn`
  仍留给 monorepo 组件补丁。
- 主题 token 覆盖：`QQ2006_TOKENS`（`--dsw-alias-*` 与 `--dsw-specific-*`，
  由 ui-layout 的 theme presenter 写到 body）。

## 组件级补丁规则（子智能体的主要工作）

在**组件自己的 `.module.css`** 末尾追加皮肤段，全部用祖先作用域：

```css
body[data-ds-skin='qq2006'] .localClass { … }
```

不要用全局选择器去匹配其他组件的 hash 类名；必要时给组件 TSX 加 `data-*`
属性钩子（小改动、无副作用）。所有视觉改动必须只在皮肤作用域内生效。

## 素材

- 静态资源根：`/qq2006/img/...`、`/qq2006/sound/...`（apps/web/public/qq2006/，已拷贝）。
- 头像：`/qq2006/img/avatar/NN.png`（NN ∈ 1..119 附近）。
- 版权：腾讯素材、仅供学习、勿商用（public/qq2006/README.txt 已注明）。

## 文件所有权（并行子智能体互不越界）

| 子智能体 | 可改文件 |
|---|---|
| 主面板 | packages/client/ui-sidebar/**（全部） |
| 聊天窗口 | packages/client/ui-conversation/**（全部） |
| 登录/加载页 + 通用 chrome | packages/client/web/src/AppRoot.*、ui-primitives 的 ConnectionBanner/Modal/Button 等 .module.css |
| 禁止任何人 | packages/client/ui-skin-qq2006/**、packages/client/ui-theme/**、packages/client/ui-layout/**、base.css、cordis.patch.yml、一切 package.json（pnpm-lock 只由根安装生成） |

## 构建与验证命令（仓库根）

- `pnpm --filter @deepseek-ai/dsh-client-ui-sidebar run bundle` 等（各包 `tsdown`）
- `pnpm --filter @deepseek-ai/dsh-frontend build`（vite 全量 web 构建）
- 测试：`pnpm --filter @deepseek-ai/dsh-client-<pkg> exec vitest run tests/...`
- **不要**单独跑 `pnpm install`（锁文件并发冲突）；**不要**动 `pnpm-lock.yaml`。

## 构建注意事项（重要）

- 各 ui-* 包构建：`pnpm --filter @deepseek-ai/dsh-client-<pkg> run bundle`（tsdown）。
- 类型检查用**根级** `pnpm exec tsc -b tsconfig.json`，或显式指向 tsconfig 文件：
  `pnpm exec tsc -b packages/client/<pkg>/tsconfig.json`。
- **不要**用 `tsc -b packages/client/<pkg>`（目录参数）：tsc 可能解析到错误的
  tsconfig，把 .js/.d.ts emit 写进 src/ 树（曾发生，污染 vite 的源码解析，
  表现为 `TypeError: Cannot read properties of undefined (reading 'load')`）。
  若误触发，清理 `find packages/client/<pkg>/src -name '*.js' -o -name '*.d.ts'` 产物。