@local/dsh-font-settings — 字体
最后实质性修改于Harness版本：0.2.1-rc.2
从系统已安装的字体里为正文字体、代码字体、终端字体各排一条多字体回退栈，用来替换 DeepSeek Harness 内置的纯文本字体输入框。设置 → 通用 中：
- 字号大小（保留内置三档字号：字号大小 / 代码字号 / 终端字号，展开按钮改名为「更多字号」）
- 字体（新增一行：折叠时只显示「默认 / 已自定义」，展开后平铺三个字体栈）
插件页显示名「字体」来自 locale/*.json 的 meta.title，与包名、条目 id 都无关。
使用
- 打开 设置 → 通用。
- 「字号大小」行与从前一致：顶层改正文号，展开改代码字号、终端字号。
- 「字体」行展开后是三段：正文字体 / 代码字体 / 终端字体。
- + 添加字体 打开可搜索的系统字体列表；
- 每个已选字体可上移、下移、移除，最多 6 个，按从上到下回退；
- 「恢复默认」清空该段 = 回到内置字体栈；
- 已选但系统里找不到的字体标!（悬停有说明）。 - 选择立即生效，不需要刷新：写入的是
ui-theme设置命名空间，内置主题呈现器把它应用到body。
可选项来自 Local Font Access API（window.queryLocalFonts()）。环境不支持或被拒绝时退化为内置常用字体清单，菜单里会说明原因。
架构：只做前端，后端交给内置插件
字体后端由 @deepseek-ai/dsh-client-ui-theme 拥有：
ui-theme 设置命名空间（Host Config，全部 volatile）
textFontFamily / codeFontFamily / terminalFontFamily
fontSize / codeFontSize / terminalFontSize
│
├─ Host 半：每次 index 渲染注入 body 引导脚本 ── 首帧即正确
├─ Client 主题服务：adopt() → publish() → theme/change
└─ ui-layout 呈现器：写到 body 的 --dsh-font-family-* / --dsh-*-font-size
本插件不拥有设置命名空间，也不注入首屏样式；index.js 只保留一个空壳 Config，不做任何接线。字体字段、首屏引导与终端字体都由内置 Host 半和主题服务负责，因此本插件不做 token 覆盖，也不注册 @font-face 别名，避免与内置字段竞争。
写入路径：
ctx.configForms.get('ui-theme').set('textFontFamily', '"Iosevka", "PingFang SC"')
→ settings.mutate（只校验字段是 volatile）
→ ThemeRuntime.adopt() → theme/change → 呈现器即时应用
字号走公开的 ctx.theme.setFontSize(role, px)。
遮蔽：整行替换，而不是隐藏子项
内置的「字号」行（settings.general.item 的 cell id font-size）展开后是：
字号大小
正文字体 / 代码字体 / 代码字号 / 终端字体 / 终端字号
三个字体行是组内硬编码 JSX，不是槽位，无法单独遮蔽。因此本插件以同一个 cell id、priority: -1 注册自己的行：
- list 槽位按
id分 cell，同 id 同 priority 会抛错，priority 最小者渲染； - 内置行仍然注册着（
priority: 0），只是active: false，被遮蔽； - 本插件只重绘三条字号行（顶层字号大小 + 展开里的代码字号/终端字号），字体选择由本插件的「字体」行承担；
- 卸载插件后内置行自动回到前台，无需清理。
结构
| 文件 | 作用 |
|---|---|
index.js |
Host 半：空壳 Config，不做任何接线 |
client.js |
Client 半：遮蔽 font-size、新增 font、三角色平铺多字体栈、系统字体枚举与搜索菜单 |
cordis.patch.yml |
bundle 挂载声明 |
locale/zh.json、locale/en.json |
插件页面的显示名与说明 |
icon.svg |
插件页面图标 |
package.json |
exports["./client"] + exports["./locale/*.json"] + dsh.client + dsh.bundle + 构建脚本 |
deps.lock.json |
运行期依赖锁定（Host 半导入 schemastery 用） |
scripts/、node_modules/、.cache/ |
依赖物化与构建校验 |
依赖与构建
Host 半 import z from '@deepseek-ai/schemastery'，而 profile 不提供这个包，所以插件自带一份真实文件（不是符号连接）。node_modules/ 是产物，由 npm run build 从 deps.lock.json 生成。
| 命令 | 作用 |
|---|---|
npm run build |
物化依赖，然后 verify |
npm run verify |
布局/依赖/清单/解析 + Host、Client、上游漂移三类契约 |
npm run rebuild |
即 build --force |
npm run clean |
删除 node_modules/ 与 .cache/ |
verify 除了既有的依赖逐字节校验、清单契约、真实文件不变量，还会：
- 在全新进程里导入 Host 半，断言它不注册 settings、不监听
index-inject； - 在 Node 的
vm里执行 Client 半（桩掉 React / DOM / 图标），断言： - 两行注册参数：
font-size@order 11, priority -1，font@order 11.25； - 写入落在
ui-theme，没有 token override，启动时不写设置； - 序列化/解析与内置
normalizeFontFamily同规则（引号、通用族、6 个上限、往返）。 - 读取本机安装的
ui-themebundle，断言 role 列表、字号范围、字段名、组内行顺序仍与插件镜像一致。上游改结构时构建期就会失败，并提示要复核哪一段。
scripts/host-contract.mjs 是本插件自己的文件（不随参考副本同步）；build.mjs、verify.mjs、lib/* 仍是参考副本的逐字节副本。本机没有 DSH 安装时，漂移检查会跳过并在报告里注明。
故障排查
设置里看不到「字体」行 / 只看到内置文本框
- 确认插件已安装：
@local/dsh-font-settings在 profile 的bundles里，且node_modules/@local/dsh-font-settings是指向本目录的link:。 npm run verify，看 Client 契约与槽位参数是否通过。- 客户端半由模块加载器热重载；若只改了
client.js仍看不到，刷新页面。
设置里改字体没反应
- 打开开发者工具看
theme/change后body上是否出现--dsh-font-family-text等变量； - 确认
~/.dsh/profiles/desktop/cordis.patch.yml的ui-theme条目下出现了textFontFamily/codeFontFamily/terminalFontFamily； - 内置「字号」行仍在数据层可用，插件只是遮蔽了它的字体输入框。
插件列表显示「已启用」但状态不是「运行中」
Host 半导入失败时就是这个表现（fiberPhase: null），最常见原因是运行期依赖缺失或被改坏：
cd <插件目录>
npm run verify
npm run build # 按 deps.lock.json 重新物化依赖
关键：Node 会永久缓存「导入失败」的结果，修好后必须重启 Host。
已知限制
- 只作用于 Web 客户端界面；终端字体由内置 xterm 消费
terminalFontFamily，插件不额外接管。 - 系统字体枚举依赖 Local Font Access API；不可用时只显示内置常用清单。
- 每个角色最多 6 个字体；空值 = 使用内置字体栈。
- 三个字体字段的类型是普通字符串，不做服务端白名单校验；插件在写入前按内置规则规范化（去引号/反斜杠/尖括号/控制字符、非通用族加引号）。
- 遮蔽依赖内置组的结构（三条字号 + 三个字体行）。
npm run verify的上游漂移检查会在升级后第一时间报警。
运行期版本契约
peerDependencies 声明 @deepseek-ai/dsh: ^0.2.1-rc.2。DSH 的版本闸门用 semver.satisfies(runtime, range, { includePrerelease: true })；不满足时会跳过该 bundle。未来大版本变化时按插件页提示用 dsh plugin allow-version 开豁免。
