终端字体设置 HTROY/dsh-terminal-font

dsh-terminal-font

给 DeepSeek Harness（dsh）右侧边栏的终端设置字体，修正 oh-my-posh / Powerline / Nerd Font 图标显示成方块（豆腐块）的问题。

一个 dsh 插件，从设置里给侧边栏终端设置字体，让 oh-my-posh、Powerline 和 Nerd Font 字形正常渲染，而不是显示成方块。

- 设置位置：设置 → 终端（Settings → Terminal）
- 可设：启用开关、字体名（带常用 Nerd Font 建议）、字号、实时字形预览
- 已在 dsh 0.2.0-rc.2（Windows 桌面版 + PowerShell 7 + oh-my-posh）上验证
- 依赖：@deepseek-ai/dsh-client-ui-sidebar-terminal（读取其内部接缝，见下）

问题是什么

@deepseek-ai/dsh-client-ui-sidebar-terminal 创建 xterm 实例时把字体写死，且没有暴露任何配置入口：

new Terminal({
minimumContrastRatio: 4.5,
cursorBlink: true,
fontSize: 13,
fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
scrollback: /* ... */ 0
});

Windows 上这套字体栈最终落到 Consolas，而 Consolas 没有 Nerd Font 的私用区（PUA）字形，所以 oh-my-posh 的 / / 等图标就显示成方块。

安装

需要 dsh 具备 profile 管理能力（桌面版或 dsh web）。

方式一：设置界面

1. 打开 设置 → 插件 → 添加插件；
2. 填入 github:HTROY/dsh-terminal-font；
3. 确认安装（会有一项 dsh 兼容性检查），完成后插件立即生效。

方式二：命令行

dsh plugin add github:HTROY/dsh-terminal-font --profile desktop

方式三：本地源码

git clone https://github.com/HTROY/dsh-terminal-font.git
dsh plugin add /absolute/path/to/dsh-terminal-font --profile desktop

安装后可在 设置 → 插件 里看到 dsh-terminal-font（禁用/卸载同样在那里）。

使用

1. 打开 设置 → 终端。
2. 字体 留空即使用推荐字体栈（依次尝试 CaskaydiaCove Nerd Font Mono、 JetBrainsMono Nerd Font Mono、CaskaydiaMono Nerd Font Mono、Hack Nerd Font Mono、 MesloLGS NF，最后回退到内置字体栈）——只要机器上装了其中任意一款，图标就会正常显示。
3. 也可以填任意已安装的字体名，输入框的下拉列表给出常见 Nerd Font 名称。
填写的内容会作为 "<字体名>", <内置字体栈> 使用；若填写内容含逗号，则按完整的 CSS 字体列表使用。
4. 字号 用 −/+ 调整；选 自动 表示沿用终端内置字号。改字号后终端会自动重新适配列宽（xterm 网格与 PTY 一起更新）。
5. 预览 会实时显示 Powerline 分隔符与常用图标；显示为方块说明该字体未安装或名字不对。

设置保存在浏览器 localStorage（键 dsh-terminal-font.settings.v1）——它描述的是"这台机器用什么字体画终端"，属于浏览器侧偏好，而不是 Host 端配置。更改会立即作用于已打开的终端。

工作原理

终端插件把 xterm 实例存在 React 的 useRef 里：既没有全局单例，也不会在 DOM 上留下实例引用，因此插件从三个受限但完整的接缝接入（全部在 client.js，可逆且透明）：

1. window.__ModuleLoader__.load
包装懒加载块 @deepseek-ai/dsh-client-ui-sidebar-terminal/client.terminal.js 的 factory，使该 chunk 拿到的 react 模块是一个 Proxy —— 除 useRef 外所有导出原样透传。
2. useRef 代理 TerminalScreen 通过 terminal.current = xterm / fit.current = addon 保存实例；代理在赋值瞬间拿到实例，写入 xterm.options.fontFamily / xterm.options.fontSize。
3. window.ResizeObserver
终端自己的 measure() 回调会同时调整 xterm 网格与 PTY 尺寸；换字号后重放它即可正确重新适配，避免"显示变了但 shell 还以为旧列宽"的错位。

对于插件加载前就已经打开的终端，另有一条兜底路径：React 会在它渲染过的 DOM 节点上留下 fiber， TerminalScreen 的 hook 链里就有 xterm 与 FitAddon 实例，组件 props 里还有终端 model，因此插件可以照搬终端自己的 fitScreen 逻辑完成同步。

关闭开关或选择"自动"字号时，插件还原该终端原本的字体与字号（安装时记录，而非硬编码常量）。

已知限制

- 依赖 @deepseek-ai/dsh-client-ui-sidebar-terminal 的内部实现（chunk 名、useRef 用法、 ResizeObserver 回调语义、React fiber 结构）。该包升级后若这些细节变化，字体可能不再生效；届时请按上文"工作原理"的 1–3 条重新核对，并欢迎提 issue。
- 字体必须安装在运行浏览器的那台机器上（桌面版即本机）。插件不打包字体文件。
- 只影响 Web 终端渲染；dsh 的 shell 工具输出（bash/pwsh 工具卡片）不受影响。
- Host 侧只有一行占位插件，不注册任何服务、不联网、不读写文件。

开发与测试

插件是纯 JavaScript，无需构建：

dsh-terminal-font/
├─ package.json # dsh.bundle / dsh.client 清单 ├─ cordis.patch.yml # bundle 层：插入 terminal-font 插件行 ├─ index.js # Host 侧占位（apply 为空） ├─ client.js # 全部逻辑：设置页 + 三个接缝 + fiber 兜底 ├─ locale/{en,zh}.json # 插件商店展示文案 ├─ icon.svg └─ test/verify.mjs # 机制测试

测试用假的 module loader / React / ResizeObserver / xterm 实例驱动 client.js，覆盖：包注册、chunk factory 包装、useRef 捕获、字体写入、换字号后重放 fit 回调、禁用还原、以及「插件加载前已存在的终端」的 fiber 兜底（含通过 props 取回 model 完成 xterm + PTY 同步）：

node test/verify.mjs

说明：该测试验证的是插件与 dsh 内部接缝之间的机制，不代表浏览器里的最终视觉结果。

License

MIT