dsh-font-settings

DeepSeek Harness Web UI 插件：在「设置 → 通用」提供 UI 字体、代码/等宽字体与 侧边栏终端字号。选中的值是一个 CSS font-family 栈，不是枚举 id。

安装（远程）

插件以 GitHub 仓库为分发源（未发布到 npm），三种安装方式：

在 dsh 0.2.x（含 0.2.0-rc.1）上必须装 0.6.1 或更新版本。 0.6.0 及更早把 @deepseek-ai/dsh-settings 的 peer 声明为 ^0.1.7-alpha.1，会被 0.2.x 的兼容门判为不兼容： dsh plugin add 直接拒绝，已装的行在启动时被禁用（reasonIncompatibleVersion）。 0.6.1 只放宽了声明范围（lib/ 代码未变），并已在 0.2.0-rc.1 上验证。

1. 跟随默认分支（推荐）

dsh plugin --profile web add github:fuzz1og/dsh-font-settings

2. 固定到版本 tag / commit（可复现）

dsh plugin --profile web add github:fuzz1og/dsh-font-settings#v0.6.1
# 或
dsh plugin --profile web add github:fuzz1og/dsh-font-settings#<commit-sha>

3. 从 DSH STORE 市场安装

本插件对 DSH STORE 的固定源码扫描为零权限信号，上架后会自动归入 source-verified。 之后在 GUI 的 Plugins / Store 里搜索 dsh-font-settings 即可一键安装。

安装后

# 确认挂载（应出现唯一一条 - id: font-settings）
dsh --profile web --dump-config | grep -A2 font-settings

# 卸载
dsh plugin --profile web remove dsh-font-settings

• 本包声明了 dsh.bundle.patch，dsh plugin add 会自动把它加入 profile 的 dsh.profile.bundles，无需手改 patch 文件。重启 DSH 并刷新 GUI 后生效。
• 远程 / LAN 打开 GUI：偏好是 per-device 的（非 loopback 走浏览器本地存储）； Tier 2「读取本机字体」需要安全上下文（HTTPS 或 localhost），纯 HTTP 的 LAN 访问下按钮会置灰。
• 兼容性：dsh >=0.1.7-alpha.1 <0.3.0；0.2.0-rc.1 / 0.1.7-alpha.1 / 0.1.7-alpha.2 实测兼容， 0.1.6-alpha.2 及更早不兼容（无 configForms 服务）。见「兼容性与已知限制」。
• 升级 DSH 后要重装：DSH 在安装时按 peerDependencies 里的 @deepseek-ai/dsh* 项与运行版本比对， 不匹配会拒绝安装（已装则会禁用该行）。升到声明范围外的新 DSH 后， dsh plugin add 重装本插件即可。

使用

主路径 · 自由文本（所有浏览器，零权限） 输入框直接写 CSS 栈（如 'Fira Code', monospace），回车应用；清空回车恢复默认。 这条路永远可用，也是唯一一条不依赖任何浏览器能力/权限的路。

Tier 1 · 常用候选 面板内置一份常用家族（界面 / 等宽各一份），点击即用。非 Chromium 浏览器也有东西可点。

Tier 2 · 读取本机字体（可选增强，Chromium 桌面版）

• 点「读取本机字体」→ 在点击手势里调用 window.queryLocalFonts()；
• 结果按 family 归并后缓存进 localStorage，下次打开面板直接可见；
• Firefox / Safari / Chrome Android、或非安全上下文（非 HTTPS/localhost）：按钮置灰并说明原因；
• 拒绝授权：提示可在站点设置重新授权后重试；
• 读到的 postscriptName / fullName 同时用于终端 local() 别名（见下）。

设计取舍

参考 opencode 的主路径（自由文本 CSS 栈，无服务端枚举）与 mcut 的分层增强：

层	来源	可用性
主路径	任意 CSS font-family 栈	全部浏览器，零权限
Tier 1	内置常用候选	全部浏览器，零权限
Tier 2	queryLocalFonts() 本机枚举	Chromium 桌面版，权限 + 手势

宿主扫描已删除。浏览器本来就无法枚举字体，而宿主能枚举的只是「运行 dsh 的那台机器」—— 用远程 / LAN GUI 打开时会读到错误的机器。同时，宿主侧的 node:fs / process.env / fetch( 会触发 DSH STORE 的 files / credentials / network 权限信号，使插件无法自动上架。 唯一实质损失是「非 Chromium 没有下拉枚举」，这也是所有主流项目共同接受的现状。

持久化

• loopback：走官方 ctx.configForms.get("font-settings")，写本条目自己的 volatile Config（5 个字段；条目 id font-settings 即命名空间）。
• 非 loopback：宿主机文档属于另一台机器，偏好改为 per-device localStorage； 远端页面不再写宿主机文档。
• 自定义 HTTP 路由（/font-settings）与宿主字体扫描路由已删除。

终端字体与字号

侧边栏终端用一行写死的字体栈构造 xterm，不引用任何 dsh 字体 token，因此只能用 @font-face 别名改写 ui-monospace / SFMono-Regular / Menlo / Consolas （monospace 通用族无法遮蔽）：

@font-face{font-family:ui-monospace;src:local('Maple Mono NF CN Regular'),local('MapleMono-NF-CN-Regular');font-weight:400;font-style:normal}

local() 只匹配 FullName / PostScript 名，传家族名会静默失败。这两个字段现在来自 queryLocalFonts() 的 fullName / postscriptName，不再解析字体文件的 sfnt name 表。 没有 face 时（手输自定义栈、或未读取本机字体）只遮蔽 ui-monospace 并用家族名兜底。

终端字号通过给同一批别名加 size-adjust 生效：终端的 fontSize: 13 是写死的字面量， 只能按比例缩放。基准优先取活动终端真实渲染的字号，读不到时退回 13px 并只警告一次。 直接盖 CSS font-size 会让 xterm 的单元格测量与行渲染脱钩（实测每格漂移 ≈3.8px），故不采用。 选择器与回退基准是内部 DOM 依赖，DSH / xterm 升级后需要复核。

兼容性与已知限制

维度	声明
DSH	>=0.1.7-alpha.1 <0.3.0（逐版本见 dsh.compatibility.dshReleases）
Node.js	>=18.17.0
Profile / 平台	dsh.client.platform = web，dsh.compatibility.profiles = ["web"]
本机枚举	Chromium 桌面版 103+；Firefox / Safari / Chrome Android 无

逐版本实测（每个版本都在隔离安装 + 一次性 DSH_HOME 内跑通设置行 / LFA / 持久化）：

DSH 版本	状态	证据
0.2.0-rc.1	✅ compatible	一次性 DSH_HOME 隔离安装 → --dump-config 冷启动合成出唯一 font-settings 行 → 宿主半区冷导入 → 卸载全部通过；用该版本自带的 evaluatePluginCompatibility() 复核 peer 门（0.1.6-alpha.2 仍被拒）；远程（默认分支）安装后实机运行正常；settings.general.item 槽位、客户端 configForms、宿主 settings.configure、schemastery .volatile() 已逐一核对存在且签名不变。未逐项复跑 Tier 1 / LFA / 持久化的 GUI 用例
0.1.7-alpha.2	✅ compatible	真实 GUI E2E：设置行渲染、Tier 1、queryLocalFonts() 读到 148 个族、别名用 postscriptName、configForms 写回 profile patch、字号 size-adjust、清空恢复默认；0 console error
0.1.7-alpha.1	✅ compatible	隔离安装 @deepseek-ai/dsh@0.1.7-alpha.1 + 一次性 DSH_HOME，同样 E2E 全部通过；宿主 settings.configure 与客户端 configForms 均存在
0.1.6-alpha.2 及更早	❌ incompatible	客户端无 configForms 服务（inject 不满足、设置行不挂载），宿主无 settings.configure

DSH STORE 的兼容性策略只看官方最新 3 个 release；当前窗口为 0.2.0-rc.1 / 0.1.7-alpha.2 / 0.1.7-alpha.1， 矩阵中已有 3 个 compatible，满足 requiredCompatibleReleases: 1。

侧边终端字体的生效条件

侧边终端用写死的字体栈构造 xterm，只能靠 @font-face + local() 别名改写； 而 local() 只认 FullName / PostScript 名（Chromium 实测：family 名和 typographic family 名都不认）。 满足下面任意一条即生效：

路径	条件	典型值
直接生效（无需读取）	输入的值等于该字体的 FullName 或 PostScript 名	Consolas（family=fullName=postScript）、Cascadia Code Regular、CascadiaCode-Roman
读取后生效（推荐）	点过「读取本机字体」，且 LFA 报出的 family 与输入值一致	Hack Nerd Font、JetBrainsMono Nerd Font、Maple Mono Normal NL NF CN、NotoSansM Nerd Font Mono

为什么读取后这些 Nerd Font 都能生效：Chromium 的 FontData.family 取的是 typographic family（nameID 16）， 没有 nameID 16 时才取 nameID 1——这正是插件存的 / 你输入的那个值。本机实测（WSL Chromium）：

字体	nameID 1	nameID 16	LFA 报出的 family	local() 实际能匹配的名字
Hack Nerd Font	Hack Nerd Font	无	nameID 1	Hack Nerd Font Regular / HackNF-Regular
JetBrainsMono Nerd Font	JetBrainsMono NF	JetBrainsMono Nerd Font	nameID 16	JetBrainsMono NF Regular / JetBrainsMonoNF-Regular
Maple Mono Normal NL NF CN	Maple Mono Normal NL NF CN	无	nameID 1	… Regular / MapleMonoNormalNL-NF-CN-Regular
NotoSansM Nerd Font Mono	NotoSansM NFM	NotoSansM Nerd Font Mono	nameID 16	NotoSansM NFM Reg / NotoSansMNFM-Reg
DejaVu Sans Condensed / Candara Light / DengXian Light	… Condensed / … Light	DejaVu Sans / Candara / DengXian	nameID 16（nameID 1 的名字在 LFA 里根本不存在）	—

对照：local() 对 family / typographic family 名一律不匹配（FontFace API 直接判定）—— Cascadia Code ❌、Mononoki Nerd Font ❌、DejaVu Sans Condensed ❌； 而 Cascadia Code Regular / CascadiaCode-Roman、Mononoki Nerd Font Regular / MononokiNF-Regular ✅。

仍未生效的情况：

• 没读过本机字体，且输入的是 family / typographic family 名（最常见）。
• 字体不在浏览器可见范围：Chromium 按进程枚举字体，读取之后新装的字体、浏览器看不到的用户字体都不会出现。
• 自定义栈只看第一个 family；写成 'A', 'B' 时只按 A 找。
• 非 Chromium（Firefox / Safari / Chrome Android）没有 LFA，只能走"直接生效"那条路。
• 读取本身需要安全上下文（HTTPS / localhost）+ 手势 + 授权。

补充：界面 / 代码面的主题覆盖（--dsw-font-family / --ds-font-family-code）始终生效，与终端无关； 终端字号依附在同一套别名上，别名 face 不生效时字号缩放也不生效。

根因、候选修复（通过宿主组件实例调用 xterm 官方 term.options.fontFamily）与风险评估见 docs/terminal-font-research.md；该修复依赖 React 内部结构，并会触发 DSH STORE 的 protectedDsh 文本信号，暂不实施。

• 非 Chromium 没有下拉枚举，请用主路径或 Tier 1。
• 本机枚举需要安全上下文：纯 HTTP 的 LAN 访问下 API 不存在（按「不支持」置灰）。
• local() 别名依赖浏览器能匹配到该字体；Chrome「Limiting Access to Local Fonts」提案会进一步 限制 local()，届时别名可能失效，主路径不受影响。
• 家族名被全局改写，所以面板里那几行「以自身字体预览」的示例文字也会跟着变，属外观副作用。

上架声明

• 依赖：无运行期 dependencies / optionalDependencies / bundled 依赖，无生命周期脚本。 peer 只声明宿主已提供的 react、@deepseek-ai/dsh-settings（optional）、 @deepseek-ai/schemastery（optional）。
• 权限：文件 / 网络 / 命令 / 凭据 全无。插件不读写任何文件（偏好落盘由宿主 settings 服务完成）， 不发起任何请求，不读 process.env，不 spawn 进程。
• 外部服务：无。不访问 CDN、字体 API、Webhook 或遥测。
• 失败边界：schemastery 解析失败 → Config 导出 undefined、只警告一次、 偏好退回 per-device 存储，DSH 启动不受影响；queryLocalFonts() 不支持或拒绝 → 按钮置灰并说明原因，主路径不受影响。

因此运行期源文件（package.json、cordis.patch.yml、lib/*.js）对 DSH STORE 固定源码策略的扫描结果为零权限信号，符合 source-verified 自动上架条件； test/permission-signals.test.mjs 复刻官方正则把这条契约锁住。

验收

npm test                          # 全部回归（零信号 / 宿主形状 / 持久化 / LFA）
npm run verify:disposable-profile # 一次性 DSH_HOME：安装 → dump-config → 卸载

本地联调（独立 profile，不碰真实 web）：

dsh fontdev --from-default-profile web --dump-config   # 首次创建 profile（只合成配置，不启动）
dsh plugin --profile fontdev add "$PWD"                 # 安装本地 checkout
dsh fontdev --no-open --port 3081                       # 启动

License

MIT