cicadas/dsh-bezel

DSH Bezel

English · 简体中文 · 繁體中文 · 日本語 · Français · Deutsch · Español

一个原生 macOS 外壳，将 dsh Host 自有的 Web UI 直接加载到 WKWebView 中，并恰好添加一个外壳可以合理地围绕显示内容添加的东西：选择要连接到哪个 dsh、知道显示内容何时在召唤你、像浏览器一样在页面上查找文本，以及它自己的界面语言。

完整的工程设计——通信契约、决策规则、状态模型、源码映射——都在 architecture.md 中。本 README 保留了设计的轮廓、如何使用该应用，以及它与其他方案相比如何。

设计概要

四个决策定义了整个应用：

- 页面即应用。 一个 WKWebView 加载 Host 自有的 Web UI——纯显示，零注入，零回读。dsh 界面的每一项功能都会自动跟随 Host 版本，因为该应用既不修改也不解释页面。
- 通知来自 Host API，而非页面。 一条独立的、轻量的通道——HostFeed——持有一个经 cookie 授权的 WebSocket，并偶尔拉取会话列表。完成是 running 标志的下降；召唤是一个被动监听的水瀑事件，而显示的页面保持其对响应的独占权。
- 显示内容会自我更新。 一个页面长时间打开会累积渲染器内存，因此应用会在页面存在一天后重新加载它——但仅在没有任何窗口可见时，且绝不在 Host 等待回答时。
- 一个 JSON 文件记住一切，以原子方式写入并宽容地解码；受管理的 dsh 子进程通过用户真实的 shell 环境找到、启动，并在退出时终止。

这些决策各自的详细含义，以及为何如此设计，是 architecture.md 的主题。

快速开始

swift build --disable-sandbox   # 编译（仅在 DSH harness 下需要该标志）
swift test --disable-sandbox    # 连接模型、通知通信、配置文件的单元测试
./scripts/make-app.sh           # 生成 build/DSH Bezel.app
open "build/DSH Bezel.app"

swift run dsh-bezel 也可以，但那是一个裸可执行文件：没有 bundle 时，Info.plist 中的 ATS 例外不适用，cookie/偏好设置的所有权不稳定，且 macOS 拒绝投递通知。实际使用请用 .app。

或者跳过构建：Releases 页面提供通用 DMG 和 zip（Apple 芯片和 Intel）及其 SHA-256 校验和。这些二进制文件是临时签名的，因此在没有 Developer ID 证书的机器上首次打开可能需要右键 → 打开。

首次启动指南

首次启动会打开一个简短指南，而不是主窗口。它会检测
一个 DSH 进程是否已在提供 Web UI 服务，以及该发现所允许的操作：

- 绑定正在运行的进程 —— 将本应用指向你自己启动的 dsh，粘贴其启动输出中的地址和令牌即可。
- 启动一个受管理的进程 —— 本应用运行子进程，并在退出时终止它。
自动 会查找已安装的 dsh（若未找到，则提供通过 npm 安装的选项，这需要 Node.js）；手动 会运行你提供的启动命令，只要它打印出 dsh web: http://… 启动行即可。

跳过指南会直接进入连接提示，仅一步之遥；只有删除配置文件后，指南才会再次出现。

界面语言

无论 macOS 本身设置为何种语言，界面默认均为英文。
设置 → 通用 → 语言可将其切换为简体中文、繁體中文、日本語、Français、
Deutsch 或 Español，该选择会写入下文所述的配置文件，因此重启后依然保留。

唯一无法在会话中途切换的部分是原生菜单栏：macOS 在启动时从应用包的本地化资源中绘制它。每次启动时，应用都会在构建 UI 之前将其配置的语言镜像到 AppleLanguages，并且应用包为每种受支持的语言都附带一个 .lproj，因此菜单栏会在下次启动时遵循该设置。当所选语言与菜单栏语言不一致时，设置中会为此提供一个重启按钮。

此设置仅涵盖本应用自身的界面。Host 的 Web UI 由 Host 提供，并保留其自己的语言设置。

在页面中查找

⌘F 会在页面上方打开标准的 macOS 查找栏 —— 由 AppKit 的 NSTextFinder 驱动 WebKit 自身的查找机制，与 TextEdit 和 Preview 使用的是同一个查找栏、增量搜索和匹配反馈。不会向页面注入任何内容来进行搜索。

按 Enter 或 ⌘G 跳转到下一个匹配项，按 ⇧⌘G（或 Shift-Enter）跳转到上一个；按 Esc 或查找栏的“完成”按钮将其关闭；按 ⌘E 可将选中的文本作为搜索字符串（编辑 → 查找）。查找栏左侧的一行会报告搜索找到了多少个匹配项。查找栏属于每个标签页 —— 每个标签页都保留自己的搜索 —— 而重新加载（无论是手动还是自动）都会在新页面上重新运行当前搜索。有一个浏览器习惯缺失了：切换标签页不会携带查询内容，因为 AppKit 的公开查找接口无法将查找栏中的文本传递给另一个 Web 视图。

设置

设置窗口（工具栏 Host 菜单 → 管理 Host…，或 ⌘,）有两个标签页。

Hosts —— 添加、删除和编辑书签：

| 字段 | 含义 |
| --- | --- |
| 名称 | 显示在选择器中；留空时使用地址 |
| 地址 | Host 的源，例如 http://127.0.0.1:3080 |
| 启动令牌 | 来自 dsh web 输出的 ?token=…；仅在未持有 cookie 时需要 |
| 为此 Host 启动本地 dsh | 应用会生成子进程 |
| profile | 受管理模式下的 --profile，默认为 web |
| 额外参数 | 追加到 dsh 调用中，例如 --trusted-host dsh.internal |
| 自定义启动命令 | 在托管模式下替换整个调用；必须打印 dsh web: http://… 这一行 |
| dsh 可执行文件路径 | 托管模式下运行哪个 dsh；留空表示搜索 |

通用 — 属于应用而非某个 Host 的偏好设置：

| 字段 | 含义 |
| --- | --- |
| 语言 | 界面语言：English（默认）、简体中文、繁體中文、日本語、Français、Deutsch 或 Español |
| 通知 | 针对等待中的 Host 和已完成任务的 macOS 通知；默认开启 |
| 自动刷新页面 | 页面存在一天后，在后台自行重新加载；默认开启 |
| 配置文件 | 配置的存储位置；会显示路径，选中它即可复制 |

书签和其余配置会在你编辑时写入该文件；其写入、迁移和保护方式在
architecture.md 的“What is remembered”一节中描述。

对比

每一个把 dsh Web UI 放进窗口的工具都属于三种形态之一：Host 自身页面上的
普通浏览器标签页、围绕它的通用 Web 包装应用，或重新实现线协议的
原生客户端。

| | dsh web 上的浏览器标签页 | 通用 Web 包装应用 | DSH Bezel | 原生协议重新实现 |
| --- | --- | --- | --- | --- |
| 交互 | Host Web UI | Host Web UI | 同一个 Host Web UI，位于 WebKit 视图中——零协议漂移 | 界面的原生重新实现 |
| 需要维护的协议 | 无 | 无 | 交互无需协议；仅通知使用一个狭窄、由测试固定的切片 | 整个线协议 |
| macOS 通知 | 无 | 无 | 有——任意会话中的等待和完成 | 有 |
| 书签、托管子进程、首次启动引导 | 无 | 无 | 有 | 有 |
| 界面语言 | Host 自身的 | 它自己的 | 七种，包括菜单栏 | 它自己的 |
| 页面搜索（⌘F） | 浏览器自身的 | 各不相同 | 有——WebKit 自身的查找机制，未注入任何内容 | 有 |
| 页面之外的内存占用 | 无 | 第二个捆绑的浏览器引擎 | 一个套接字 | 原生界面 |

- 对比标签页：页面完全相同——此应用从不改进它。外壳所添加的一切都
完全围绕它：书签和托管子进程让打开应用就足够，通知让等待中的 Host
不会被错过，续期让长时间亮着的显示器保持健康，以及语言处理。
- 对比通用包装器：那些应用捆绑自己的浏览器引擎——为了在装扮过的
窗口中显示同一个页面而占用一整个第二运行时的内存——并且对它们所包装
的内容一无所知。此应用使用系统 WebKit，因此页面的开销就是页面的开销，
而外壳理解它的 Host：如何找到它、启动它、监视它并重新连接。
- 对比原生重新实现：完全原生的交互是奖赏，代价是你必须自己跟踪线
协议并承担漂移。本项目有意不这样做——就交互而言。你所
点击、输入和阅读是 Host 自有的 Web UI，而本应用对此一无所知。唯一的例外是通知：HostFeed 订阅同一 API 的一小部分——会话列表、一个状态事件、两个召唤门——因为从页面中获知这些信息意味着要向页面注入脚本，并为此付出第二个渲染器的代价。这一部分正是 HostFeedWire，即由从实时 Host 录制的测试所固定的纯解析函数，因此一旦发生偏移，也只会落在一个可测试的地方。这些形态可以共存；本应用所添加的内容——通知、跟随语言的菜单栏——在不触及你如何操作页面的前提下包裹了页面。
- 代价：完成通知不再引用用户自己的提示词（会话标题改为命名任务），并且通知的传输格式在该小型测试固定表面上跟随 Host 版本。
- 前提条件：一个能够提供 Web UI 的 dsh Host（自 0.1.5-rc.1 起稳定）。通过域名访问的远程 Host 必须使用 --trusted-host 启动——dsh 的 /api 有一道浏览器信任围栏；其余内容见 architecture.md 中的“Known constraints”。

开发

swift build --disable-sandbox
swift test --disable-sandbox
swift run dsh-bezel --dump-config   # 配置文件：其路径，或其内容
swift run dsh-bezel --dump-hosts    # 仅保存的书签
swift run dsh-bezel --watch-feed "http://127.0.0.1:PORT/?token=…"
将通知通道附加到 Host
并打印它获知的每一条事实——传输
契约，实时呈现

裸可执行文件和 bundle 共享同一个配置文件，因此使用 swift run 进行的实验会使用你的真实配置，除非 BEZEL_CONFIG 指向别处。在 DSH 测试框架下构建时需要 --disable-sandbox 标志，因为该框架无法嵌套自己的沙箱。