yuu1111/dsh-ui-font

dsh-ui-font

一个 DeepSeek Harness Web GUI 插件，可从 设置 → 通用 中设置界面和代码字体族。

日本語

为什么存在

DSH Web GUI 在 设置 → 通用 中提供了配色方案和对话字体大小，但没有字体族。dsh-client-ui-theme 附带的 base.css 中有两个硬编码的字体栈：

| 令牌 | 使用者 | 默认值 |
| --- | --- | --- |
| --dsw-font-family | 正文文本和界面元素 | -apple-system, BlinkMacSystemFont, "Segoe UI", ... |
| --dsw-font-mono, --ds-font-family-code | 代码块和等宽界面 | "SF Mono", "JetBrains Mono", "Fira Code", Consolas, ... |

此插件在该设置页面中添加两行，将所选字体栈存储在 $DSH_HOME/settings.yaml 中，并在不修改 DSH 安装目录内任何文件的情况下应用它们（npm 更新无法将其还原）。

安装

dsh plugin --profile web add dsh-ui-font
dsh web

dsh plugin 会将包安装到配置文件中，并自动将声明了 dsh.bundle 的依赖包追加到 dsh.profile.bundles，因此无需手动编辑补丁。

正在运行的 dsh web 在启动时只组合一次 dsh.profile.bundles，并且只监视用户补丁层（cordis.patch.yml），因此安装后请重启它——仅刷新浏览器不会加载该插件。

使用 dsh plugin --profile web remove dsh-ui-font 卸载。

配置

打开 设置 → 通用。每一行以有序标签的形式列出已保存的字体族，显示以该字体栈设置的示例行，并带有一个 添加字体 按钮：

| 行 | 设置 | 应用于 |
| --- | --- | --- |
| 正文字体 | sans | 正文文本和界面元素 |
| 代码字体 | mono | 代码块和等宽文本 |

添加字体 会打开一个可搜索的列表，其中包含本机已安装的字体族，通过浏览器的 queryLocalFonts() 读取，每个条目都以其自身的字体渲染。Chrome 首次会请求字体访问权限；已在字体栈中的条目带有对勾标记，选择一个条目会将其追加到末尾。面板保持打开状态，因此可以连续添加多个字体族。当浏览器无法列出本地字体，或你拒绝了提示时，列表会回退到一组常见的字体族并说明这一点。如果搜索词在列表中没有匹配项，会提供 Add ""，因此浏览器能解析的任何字体族都仍然可用。

每个标签带有三个按钮：前移、后移和移除。顺序即回退顺序，因此请将支持 CJK 的字体族放在拉丁字体族之后。每次更改都会立即保存，未更改的字体栈不会写入任何内容。

存储的值仍然是纯 CSS font-family 列表，因此手动编辑也可以。花括号、分号和尖括号会被清理掉，因为该值会被插值到样式表中。只有你更改的字段会被写入；其余字段保留出厂默认值：

$DSH_HOME/settings.yaml
ui-font:yaml
sans: '"JetBrains Mono", "BIZ UDPGothic", "Noto Sans JP", sans-serif'

运行中的服务器会监视该文件，因此手动编辑会在下次页面重新加载时生效。随附的默认值中完全没有 ui-font 部分：

| 设置 | 随附默认值 |
| --- | --- |
| sans | "JetBrains Mono", "BIZ UDPGothic", "Noto Sans JP", "Yu Gothic UI", Meiryo, sans-serif |
| mono | "JetBrains Mono", "SF Mono", "Fira Code", Consolas, "Liberation Mono", monospace |

JetBrains Mono 不包含 CJK 字形，因此随附的 sans 对日文文本会回退到 BIZ UDPGothic 和 Noto Sans JP。请确保在拉丁字体之后至少保留一个支持 CJK 的字体系列，否则日文会回退到浏览器所选的任意字体。

配置文件还可以设置插件的 Loader config:，它会成为已保存值之下的基础层——参见 cordis.patch.yml 中的注释示例。

仓库布局

| 路径 | 作用 |
| --- | --- |
| src/index.ts | 宿主端：注册 ui-font 设置部分，并将已保存的字体栈注入所服务的 index |
| src/client.tsx | 浏览器端：应用样式表并注册两个设置行，包括选择器 |
| src/shared.ts | 两端共享的值：命名空间、默认值、清理、字体栈解析与格式化，以及样式表构建器 |
| build.ts | Bun 构建：宿主端为 ESM，浏览器端为 CJS 并包装为模块加载器格式 |
| cordis.patch.yml | 将 ui-font 行插入配置文件树 |
| quality.config.ts、knip.ts | 质量门禁：quality-check 运行的引擎、可选规则，以及 Knip 入口点 |
| lib/ | 由 bun run build 和 prepack 生成；不被跟踪，因此仅存在于本地和已发布的 tarball 中 |
| tests/host.test.ts、tests/client.test.ts、tests/shared.test.ts | 针对构建后的 lib/ 运行的契约测试 |

工作原理

- 宿主端在 ctx.inject(["settings"], ...) 内调用 settings.installSection(ctx, "ui-font", Config, config, hooks)。插件的 Loader config: 成为基础层，已保存的 settings.yaml 部分会覆盖它，而 schema 默认值则覆盖省略了某个字段的配置。
- 宿主端还会在 webserver/index-inject 上推送一行 { kind: "style" }。每次 index 渲染时都会收集这些行，并将其直接放在  之后，因此已保存的字体栈在首次绘制时即生效，并且手动编辑 settings.yaml 会在下次重新加载时显示出来，无需重启。
- 浏览器端声明 inject: ["slots", "locale", "settingsScope"]，使用 settingsScope.bind() 绑定 ui-font 命名空间，并保持一个 style[data-plugin-css="dsh-ui-font/font-family.css"] 标签与快照同步。只有一个权威方写入这些 token：两端发出相同的 :root,body{... !important} 声明，在相同特异性下，浏览器端稍后追加的标签胜出，而宿主行则在客户端加载之前覆盖窗口。
- 这些行会注册到 settings.general.item 槽位中，id 为 "dsh-ui-font-sans" / "dsh-ui-font-mono"，order 为 70 / 71，因此它们位于内置的外观和字号行之后。浏览器端附带 en、zh 和 ja 词典；其他语言区域会回退到英语。
- 每一行都会将存储的字体栈解析为字体系列，将其显示为标签，并在每次保存前用 formatFontStack() 重新格式化，因此设置文件中保存的内容始终是一个可往返转换的 CSS 列表。选择器在每次行挂载时通过 globalThis.queryLocalFonts() 读取已安装的字体系列；如果 API 缺失、结果为空或权限请求被拒绝，则会回退到内置列表，而不会让该行无法使用。
- 必须使用 !important，因为 ui-layout 呈现器会将解析后的令牌作为内联自定义属性写入 document.body，对于每个后代元素来说，其优先级都高于普通的 :root 声明。

--dsw-font-mono 并未由内置样式表声明；某些组件通过 var(--dsw-font-mono, ui-monospace, monospace) 读取它，因此该覆盖也会一并接管它。

开发
powershell
bun install
bun run check          # tsc --noEmit through @yuu1111/tsconfig/bun.json
bun run lint           # biome check .
bun run format         # biome check --write --unsafe .
bun run check:quality  # biome, tsc, knip, and the code, comment, document, and TSDoc checkers
bun run test           # builds lib/, then runs the suite against it
bun run build          # regenerates lib/

浏览器端只能 require() shell 已经注入的模块——react、react/jsx-runtime、@deepseek-ai/dsh-client-store 和 @deepseek-ai/dsh-client-ui-primitives。当出现任何其他说明符时，build.ts 会使构建失败，并固定生产 JSX 运行时，因为 shell 不会注入 react/jsx-dev-runtime。

要在不发布的情况下在实时配置文件中试用某项修改，请按路径安装此检出，并在每次更改后重新运行 bun run build：
powershell
dsh plugin --profile web add "link:$((Resolve-Path .\dsh-ui-font).Path)"

发布

提升 version，提交，然后为匹配的标签（v1.1.0 ↔ 1.1.0）发布 GitHub Release。.github/workflows/release.yml 会在 contents: read 作业中构建 tarball，根据 package.json 验证标签，并在单独的作业中使用 npm 可信发布（--provenance）发布它，因此不会存储长期有效的 npm 令牌。

已验证环境

- DSH 0.1.5-rc.2（@deepseek-ai/dsh-client-ui-settings 0.1.5-rc.2），Windows 11 / Chromium
- bun test：模块 ID、导出的插件接口、设置区段注册、索引样式行、实时源切换、作用域绑定、样式表更新、行注册、字体栈解析与格式化、选择器路径（已安装列表、回退、拒绝访问、自由文本添加）、标签移除与重新排序
- 真实浏览器检查：所提供的索引包含带有已配置字体栈的  行，设置 → 通用 显示两行，并将存储的字体系列作为标签展示，选择器列出本机已安装的字体（174 个字体系列）并通过搜索进行筛选，添加字体系列会将其追加到字体栈中，并在无需重新加载的情况下更新计算后的正文字体，移除它会恢复之前的字体栈，重新排序会移动字体系列，并且每次更改都会写入 $DSH_HOME/settings.yaml，且没有控制台错误

许可证

MIT