# 开发与发布

## 环境

- Node.js 22+，npm。
- 使用 [锁文件](package-lock.json) 安装依赖：`npm ci --ignore-scripts`。
- Host 依赖 Schemastery `~3.18.4`，Cordis peer 为 `~4.0.4`。
- 不需要启动额外 Web 服务器，不依赖安装期构建脚本。

## 常用命令

```sh
npm run format        # 格式化源码、测试、配置和 Markdown
npm run format:check  # 检查格式
npm run build         # 类型检查和构建
npm test              # 先构建，再测试
npm run pack:check    # 构建并预览 npm 包内容，不生成安装包
npm run pack:release  # 构建并生成本地安装包
```

格式化使用固定版本 Prettier `3.6.2`。依赖、锁文件、生成文件和本地验收资料不参与手工格式化。

构建成功后会清理已无源码对应的生成 `.js`，避免旧模块混入安装包；不会删除其他本地文件，也不会跟随符号链接清理。发布仍需核对包预览。

## 文件功能索引

以下列出仓库维护的全部源码、测试和配置文件；不展开依赖、生成产物或本地历史验收资料。目录树见 [项目结构](README.md#项目结构)。

### 根目录、构建与插件元数据

| 文件                                   | 功能                                                                                      |
| -------------------------------------- | ----------------------------------------------------------------------------------------- |
| [README.md](README.md)                 | GitHub 项目主页、安装步骤、使用说明与目录树。                                             |
| [README.en.md](README.en.md)           | 英文项目主页，与 README.md 内容对应。                                                     |
| [DEVELOPMENT.md](DEVELOPMENT.md)       | 逐文件职责、模块边界、测试环境与发布清单。                                                |
| [LICENSE](LICENSE)                     | 项目的 MIT 授权条款和版权声明。                                                           |
| [package.json](package.json)           | 包标识、版本、许可、仓库地址、依赖、导出入口、DSH 注入声明、脚本与打包白名单。            |
| [package-lock.json](package-lock.json) | 锁定依赖版本和完整性，支持可复现安装。                                                    |
| [tsconfig.json](tsconfig.json)         | 严格 TypeScript 类型检查、JSX 和模块解析配置，不直接输出文件。                            |
| [cordis.patch.yml](cordis.patch.yml)   | 将包作为 Cordis bundle 插件入口插入运行时。                                               |
| [icon.svg](icon.svg)                   | 插件图标。                                                                                |
| [.gitignore](.gitignore)               | 排除依赖、生成包、截图、缓存、日志与本地环境文件。                                        |
| [.gitattributes](.gitattributes)       | 统一文本 LF 换行，指定图片和安装包为二进制。                                              |
| [.prettierrc.json](.prettierrc.json)   | 缩进、引号、分号、行宽与换行等格式规则。                                                  |
| [.prettierignore](.prettierignore)     | 排除依赖、构建产物、锁文件和历史验收资料的格式化。                                        |
| [scripts/build.mjs](scripts/build.mjs) | 递归发现源码，生成 Host ESM 和 Client ModuleLoader 工厂，处理相对路径并清理过期生成模块。 |
| [locale/zh.json](locale/zh.json)       | 插件元数据的中文名称与描述，不负责设置页文案。                                            |
| [locale/en.json](locale/en.json)       | 插件元数据的英文名称与描述，不负责设置页文案。                                            |
| [img/](img)                            | 对外文档插图（设置页、晨雾和深灰预设外观），提交前需确认不含个人对话与本机路径。          |

### 源码：入口与功能核心

| 文件                                   | 功能                                                                  |
| -------------------------------------- | --------------------------------------------------------------------- |
| [src/index.ts](src/index.ts)           | Host 兼容入口，导出 Config、apply 和服务注入声明。                    |
| [src/client.tsx](src/client.tsx)       | Client 入口，注册翻译、设置页和样式 Slot，管理主题同步及释放。        |
| [src/background.ts](src/background.ts) | 共享 API 的兼容门面，重导出模型、校验、读取与主题层，保持原公开身份。 |
| [src/contracts.ts](src/contracts.ts)   | Client 上下文、表单快照、RowFace、主题视图与组件 props 的类型契约。   |
| [src/contrast.ts](src/contrast.ts)     | 解析受支持颜色，处理透明前景，计算 WCAG 对比度及阈值状态。            |
| [src/presets.ts](src/presets.ts)       | 定义预设，推导选中状态，生成配色操作并处理保存／模式切换结果。        |
| [src/surfaces.ts](src/surfaces.ts)     | 有界的面板、背景同步、卡片、共享圆角和对话密度 CSS。                  |

### 源码：Host

| 文件                                                       | 功能                                                             |
| ---------------------------------------------------------- | ---------------------------------------------------------------- |
| [src/host/config.ts](src/host/config.ts)                   | 定义各样式字段的 Config schema、默认值及合法范围。               |
| [src/host/contracts.ts](src/host/contracts.ts)             | Host 设置描述、revision、原子 mutation 与工具注册接口的窄类型。  |
| [src/host/tool-schema.ts](src/host/tool-schema.ts)         | 生成工具输入和输出 JSON Schema，使用运行时支持的枚举与类型。     |
| [src/host/tool-validation.ts](src/host/tool-validation.ts) | 严格校验 set/reset 参数，生成设置操作；无效输入不产生写入。      |
| [src/host/tools.ts](src/host/tools.ts)                     | 注册新旧工具、读取保存值、执行带 revision 的原子写入和分组重置。 |

### 源码：共享逻辑

| 文件                                                   | 功能                                                           |
| ------------------------------------------------------ | -------------------------------------------------------------- |
| [src/shared/model.ts](src/shared/model.ts)             | 集中定义命名空间、主题令牌、字段类型、默认值、范围和密度枚举。 |
| [src/shared/colors.ts](src/shared/colors.ts)           | 校验 HEX 颜色或空值，规范化颜色文本。                          |
| [src/shared/cards.ts](src/shared/cards.ts)             | 校验卡片参数为有限、范围内整数，识别卡片字段。                 |
| [src/shared/density.ts](src/shared/density.ts)         | 严格校验紧凑、默认、宽松三种密度值。                           |
| [src/shared/fonts.ts](src/shared/fonts.ts)             | 解析逗号分隔的字体列表，限制长度与数量，拒绝不安全 CSS 输入。  |
| [src/shared/persisted.ts](src/shared/persisted.ts)     | 防御性读取保存值；旧版、缺失或无效字段安全回退。               |
| [src/shared/font-css.ts](src/shared/font-css.ts)       | 根据规范化字体配置生成覆盖 CSS，保留代码与品牌字体边界。       |
| [src/shared/theme-layer.ts](src/shared/theme-layer.ts) | 同步背景／强调色令牌，选择按钮前景，处理重入与层释放。         |

### 源码：UI 与设置行

| 文件                                                                   | 功能                                                           |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| [src/ui/StylePage.tsx](src/ui/StylePage.tsx)                           | 组合四个默认折叠分类，保留子组件挂载和草稿。                   |
| [src/ui/SurfaceStyles.tsx](src/ui/SurfaceStyles.tsx)                   | 订阅表单与主题，输出当前生效的字体和表面 CSS。                 |
| [src/ui/localization.ts](src/ui/localization.ts)                       | 设置页中英文标题、短说明、状态与错误提示。                     |
| [src/ui/row-face.ts](src/ui/row-face.ts)                               | 将 configForms 转换为行组件的保存／重置接口，衔接主题预设。    |
| [src/ui/styles.ts](src/ui/styles.ts)                                   | 设置页自身布局、输入框、按钮、分类、开关与焦点样式。           |
| [src/ui/rows/ColorRow.tsx](src/ui/rows/ColorRow.tsx)                   | 背景、面板、强调色通用行；管理双模式草稿、选择器、应用和重置。 |
| [src/ui/rows/CardRow.tsx](src/ui/rows/CardRow.tsx)                     | 卡片效果开关及保存状态、只读／等待守卫。                       |
| [src/ui/rows/CardParametersRow.tsx](src/ui/rows/CardParametersRow.tsx) | 圆角、外间距、阴影滑块与整数输入，三项原子保存。               |
| [src/ui/rows/DensityRow.tsx](src/ui/rows/DensityRow.tsx)               | 密度选择、应用与重置，处理旧 Host 缺字段情况。                 |
| [src/ui/rows/FontRow.tsx](src/ui/rows/FontRow.tsx)                     | 字体列表草稿、校验、应用、重置和失败保留。                     |
| [src/ui/rows/PresetRow.tsx](src/ui/rows/PresetRow.tsx)                 | 预设按钮、选中状态、可用性和模式切换部分失败提示。             |
| [src/ui/rows/ContrastRow.tsx](src/ui/rows/ContrastRow.tsx)             | 读取实际计算颜色，显示对比度、警告与无法测量状态，支持刷新。   |

### 测试文件

| 文件                                                                   | 覆盖内容                                                     |
| ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| [tests/background.test.mjs](tests/background.test.mjs)                 | 颜色校验、旧默认值、主题层恢复、旧工具与 Client 工厂加载。   |
| [tests/style.test.mjs](tests/style.test.mjs)                           | 面板样式、卡片开关、新旧工具、分组重置与 Client 生命周期。   |
| [tests/typography.test.mjs](tests/typography.test.mjs)                 | 字体解析与正则安全、强调色、背景同步、字体保存 UI。          |
| [tests/presets.test.mjs](tests/presets.test.mjs)                       | 配色快照、原子保存顺序、模式切换、失败守卫与按钮 UI。        |
| [tests/contrast.test.mjs](tests/contrast.test.mjs)                     | 颜色语法、透明合成、sRGB 亮度、WCAG 比值与未舍入阈值。       |
| [tests/contrast-ui.test.mjs](tests/contrast-ui.test.mjs)               | 生效颜色读取、提示不写入、异步帧取消与清理。                 |
| [tests/card-parameters.test.mjs](tests/card-parameters.test.mjs)       | 卡片范围、默认值、schema、原子写入、重置与有界几何 CSS。     |
| [tests/card-parameters-ui.test.mjs](tests/card-parameters-ui.test.mjs) | 参数 UI 保存、关闭／旧 Host／只读守卫和失败草稿保留。        |
| [tests/density.test.mjs](tests/density.test.mjs)                       | 严格密度枚举、旧配置、Config、工具写入和独立重置。           |
| [tests/density-ui.test.mjs](tests/density-ui.test.mjs)                 | 密度选择、保存、失败重置与加载／只读／旧 Host 守卫。         |
| [tests/settings-groups.test.mjs](tests/settings-groups.test.mjs)       | 导航和标题本地化、稳定 ID、默认折叠、保持挂载及控件圆角。    |
| [tests/localization.test.mjs](tests/localization.test.mjs)             | 中英文键一致、短说明长度、校验限制与必要状态提示。           |
| [tests/unified-surfaces.test.mjs](tests/unified-surfaces.test.mjs)     | 圆角变量、适配范围、关闭恢复、密度层次与默认原生间距。       |
| [tests/module-boundaries.test.mjs](tests/module-boundaries.test.mjs)   | 兼容导出与单例身份、模块产物、ESM 扩展名和无循环依赖。       |
| [tests/host-registration.test.mjs](tests/host-registration.test.mjs)   | 用真实 DSH 工具运行时验证冷启动注册与 schema；依赖安装环境。 |
| [tests/browser-surfaces.test.mjs](tests/browser-surfaces.test.mjs)     | Chromium 计算样式中的密度层次和圆角排除；使用隔离临时配置。  |
| [tests/build-release.test.mjs](tests/build-release.test.mjs)           | 构建清理旧生成模块且保留无关文件，防止旧模块混入发布包。     |

### 生成与本地目录

- `dist/`：与源码路径对应的生成 `.js`；Client 入口为 ModuleLoader 工厂，其余为 ESM。由构建维护，不手工编辑。
- `node_modules/`：npm 安装的依赖，不属于项目逐文件说明范围。
- `artifacts/`：本机历史截图和诊断资料，已忽略，不依赖其内容构建或测试，也不得作为公开文档插图（可能含个人对话、字体名与本机路径）。
- `img/`：README 引用的对外插图，属于源码提交内容。新增或替换插图前先确认画面里没有个人对话、私有路径或其他不该公开的信息。
- 根目录生成的 `.tgz`：供本地安装或 GitHub Release 上传，文件名随包版本变化，不提交到源码仓库。

## 模块边界

| 模块                                    | 职责                                             |
| --------------------------------------- | ------------------------------------------------ |
| [Host 入口](src/index.ts)               | Config、inject、apply 的兼容出口                 |
| [Client 入口](src/client.tsx)           | 翻译、主题层和 Slot 生命周期                     |
| [共享入口](src/background.ts)           | 保留原公开导出与对象身份                         |
| [模型](src/shared/model.ts)             | 字段、默认值、共享类型                           |
| [旧配置读取](src/shared/persisted.ts)   | 安全读取、缺失字段回退                           |
| [主题层](src/shared/theme-layer.ts)     | 配色令牌同步与释放                               |
| [Host 配置](src/host/config.ts)         | 配置 schema                                      |
| [工具执行](src/host/tools.ts)           | 注册工具、原子写入、分组重置                     |
| [参数校验](src/host/tool-validation.ts) | 写入前的完整严格校验                             |
| [设置布局](src/ui/StylePage.tsx)        | 默认折叠分类和行组件组合                         |
| [UI 保存适配](src/ui/row-face.ts)       | 设置表单的保存边界                               |
| [UI 文案](src/ui/localization.ts)       | 中英文标签、短说明和错误提示                     |
| [面板适配](src/surfaces.ts)             | 有界的颜色、圆角与密度 CSS                       |
| [预设](src/presets.ts)                  | 配色快照、保存和模式切换                         |
| [对比度](src/contrast.ts)               | 颜色解析与 WCAG 比值                             |
| [构建](scripts/build.mjs)               | 自动发现模块、Host ESM、Client ModuleLoader 工厂 |

新增设置时依次接入模型/校验、Host 配置与工具、[UI 契约](src/contracts.ts)、保存适配、独立行组件和双语文案，并补充测试。

共享实现不回引兼容入口，避免循环依赖。行组件管理草稿和状态，不自行注册 Slot、主题层或直接调用 Host settings。不要改变原包标识、设置命名空间和持久化字段。

## 测试环境

普通测试使用隔离夹具，不修改运行中 DSH 的用户设置。以下两项集成测试依赖本机安装：

### DSH 工具注册

[注册测试](tests/host-registration.test.mjs) 使用真实 `ToolRuntime.register` 校验 schema。Windows 默认寻找 DSH NEXT 标准安装位置；其他位置可设置 `DSH_STYLE_RUNTIME_TOOLS`，指向安装目录中的工具模块：

```powershell
$env:DSH_STYLE_RUNTIME_TOOLS = 'C:\path\to\DSH\resources\app\node_modules\@deepseek-ai\dsh-tools\lib\index.js'
npm test
```

缺少模块时测试明确跳过。工具输出 schema 使用 DSH 支持的子集，有界整数通过 `enum` 表达，不能直接替换为不支持的 `minimum` / `maximum`。

### 浏览器样式

[样式测试](tests/browser-surfaces.test.mjs) 默认寻找 Windows 标准位置的 Edge/Chrome，也可通过 `DSH_STYLE_BROWSER` 指定 Chromium 可执行文件：

```powershell
$env:DSH_STYLE_BROWSER = 'C:\path\to\chrome.exe'
npm test
```

macOS/Linux 可用 `DSH_STYLE_BROWSER=/path/to/chromium npm test`。测试使用系统临时目录中的隔离配置，不连接用户浏览器、不自动下载浏览器。缺少浏览器时明确跳过。

这些测试不等同于运行中 GUI 验收；更新后仍应重启 DSH，检查设置页与实际效果，不承诺源文件自动热更新。

## 工具与重置

`dsh_style_settings` 支持 `get`、`set`、`reset`。颜色、字体、卡片参数和密度在完整校验后通过官方设置服务原子保存。

- 重置组：`background`、`surface`、`accent`、`font`、`card`、`density`、`all`。
- `card` 只重置三项参数，不改变卡片开关。
- `density` 只恢复原生密度。
- `all` 为默认重置组，恢复全部参数并启用卡片。
- 旧工具 `dsh_background_colors` 仍只处理背景组。

## GitHub 发布清单

1. 从干净源码检出安装依赖，执行格式检查、完整测试和包预览；记录测试跳过项，不能将跳过称为通过。
2. 首次发布先执行 `git init`，再用 `git ls-files` 核对实际跟踪清单；未初始化的目录执行 `git add` 前必须先确认忽略规则生效，不要直接提交整个本地目录。
3. 检查版本：修改版本时同步 [包清单](package.json)、[锁文件](package-lock.json)、[中文 README](README.md) 与 [英文 README](README.en.md)。
4. 核对包预览只包含运行时构建产物、包元数据、Cordis 补丁、翻译、图标和发布文档；不能包含依赖目录、环境文件、个人截图或测试资料。
5. 执行 `npm run pack:release`，在 DSH 中安装生成的 `.tgz` 并重启验收。
6. 将源码提交到 GitHub；按实际版本创建标签和 Release，上传生成的 `.tgz`。本项目仍为 `private: true`，这不妨碍本地打包，但不能直接发布到 npm registry。
7. 保留 [MIT 许可证](LICENSE) 与版权声明，并核对包元数据中的许可信息；`repository`、`homepage` 和 `bugs` 必须指向真实的 GitHub 地址，不能使用虚构 URL。仓库改名或转移后同步这三项、两份 README 的 Issues 链接和打包白名单。

[忽略规则](.gitignore) 排除本地验收目录、日志、缓存和环境文件，但保留锁文件。`artifacts/` 下的历史截图可能包含个人对话或路径，不作为公共文档插图；README 使用的插图来自 `img/`，属于提交内容，被忽略时 README 图片会失效。忽略不会取消已经跟踪的文件，发布前仍需检查 Git 跟踪清单；不要直接提交整个本地目录。

[换行规则](.gitattributes) 统一文本为 LF，图片和压缩包按二进制处理。文档中的链接使用仓库相对路径，不引用作者本机目录。