anywhere-labs/deepseek-harness-desktop 测试体系：从 Vite - 文章 - 开发者社区

摘要

作为维护过 Electron 应用、插件宿主与多包工作区的工程师，我认为测试最容易出现的假象是“数量很多，但没有覆盖真实失败边界”。

纯函数单测可以证明参数判断，却不能证明 Cordis Loader 真能发现打包后的插件；TypeScript 通过可以保证声明收敛，却不能证明 app.asar.unpacked 中存在 pnpm、DSH CLI 与 native 文件；开发模式页面能打开，也不能证明 headless 构建机不会因为一次 import 意外启动 Electron。

本文专门分析社区仓库 anywhere-labs/deepseek-harness-desktop 的分层测试与验证体系。它把检查分成仓库布局、构建、多 face 类型、Vitest、生产依赖闭包、Electron-backed CLI、Loader boot、Profile boot、afterPack 运行时、Windows/macOS 安装器等多个层次，每一层回答不同问题。

普通 yarn check 必须 headless-safe：CLI 的 --help/--version 不导入图形 Electron，Loader smoke 激活真实 Desktop row 与 Profile 本地第三方插件、访问 loopback 根页面并检查 client manifest，却不创建 BrowserWindow；只有 yarn dev 才显式启动图形应用。测试代码还大量使用可注入边界：fake timer 验证五秒退出栅栏，spawn harness 检查 Windows/macOS 终端 argv 与环境，临时目录模拟 Profile，deferred Promise 制造并发选择，archive lister 和 resolver 验证 ASAR 物理闭包。

我还会讨论测试 fixture 如何避免进入生产 archive、为何不能用源码 import 代替第三方 bare package 加载、怎样把一次失败定位到声明闭包、模块组合、物理产物或目标平台，以及代码评审时如何根据改动范围选择最小但足够的 gate。

本文会结合测试金字塔、命令链、fixture 和故障矩阵，解释这些层为什么不能互相替代，并给出为类似桌面插件平台设计验证体系的方法。我的重点不是宣称“测试多所以没有 bug”，而是展示怎样让每个风险都由最接近它的证据负责。

项目身份说明：本文研究的是社区仓库 anywhere-labs/deepseek-harness-desktop 的测试策略，并非 DeepSeek 官方测试规范。

picture.image

图1 可见桌面界面背后，需要验证 Host、Client、Loader、Profile、原生适配和安装包

一、先按问题而不是工具分层

验证层	要回答的问题	主要手段
仓库拓扑	上游是否仍只读、包管理器是否越界	`verify-layout.mjs`
编译契约	Host/Client/Test 类型是否一致	多个 `tsconfig`
逻辑与生命周期	状态、并发、取消、窗口参数是否正确	Vitest
生产依赖	deploy root 是否声明必需 peer	runtime closure
CLI 运行时	打包 DSH/pnpm/Node shim 是否可执行	CLI smoke
Loader 组合	真实 Cordis row 与 client manifest 是否激活	Loader smoke
Profile 集成	本地第三方插件能否消费 Desktop service	Profile smoke fixture
打包产物	ASAR/unpacked/native 文件是否完整	afterPack verifier
平台发布	NSIS/DMG/签名/公证是否成立	Windows/macOS release gate

flowchart TD
    A["Repository Layout"] --> B["Build + Typecheck"]
    B --> C["Vitest Logic/Lifecycle"]
    C --> D["Runtime Closure"]
    D --> E["CLI Artifact Smoke"]
    E --> F["Cordis Loader Smoke"]
    F --> G["Profile Integration Smoke"]
    G --> H["Packaged Runtime Verification"]
    H --> I["Platform Installer/Release"]

    classDef static fill:#2563eb,color:#fff,stroke:#1d4ed8,stroke-width:2px;
    classDef logic fill:#8b5cf6,color:#fff,stroke:#6d28d9,stroke-width:2px;
    classDef integration fill:#f59e0b,color:#111827,stroke:#d97706,stroke-width:2px;
    classDef artifact fill:#10b981,color:#fff,stroke:#047857,stroke-width:2px;
    class A,B static;
    class C,D logic;
    class E,F,G integration;
    class H,I artifact;

图2 验证阶梯：越接近发布产物，成本越高，覆盖的偶然性越少

二、布局检查保护源码所有权

根仓库是 Yarn 4 workspace，唯一成员是 dsh-plugin-desktop；deepseek-harness/ 是固定 commit 的上游 pnpm submodule。check:layout 不只是检查目录存在，它会核对 packageManager、workspace 成员、子模块 URL/commit/工作树、上游 remote、源码版本、runtime package family，以及是否出现绕过发布包边界的 workspace:、portal:、link: 或指向上游源码的 file: dependency。

for (const [name, range] of Object.entries(manifest.dependencies ?? {})) {
  if (/^(?:workspace|portal|link):/u.test(range)
    || (range.startsWith('file:') && range.includes('deepseek-harness'))) {
    fail(`${name} bypasses the published DSH package boundary`)
  }
}

这类检查防止“测试为了方便把上游源码 link 进来”，因为那会让本地绿色结果失去发布代表性。上游 note 的 hash 也被记录，避免架构决策文档和实现悄悄漂移。

三、多 Face Typecheck 的意义

Desktop 同时存在 Electron Host、浏览器 Client、Host 测试和 Client 测试。它们的全局类型、DOM/Node 环境和 package export 不同，因此包级 typecheck 分别运行主 tsconfig.json、tsconfig.client.json、tsconfig.tests.json 与 tsconfig.tests.client.json。

如果只用一个“大而全”的 tsconfig，Node 类型可能让 renderer 中非法的 API 通过，DOM 类型也可能掩盖 Host 导入错误。多 face 编译让每个模块只能看到它在真实运行环境中应该拥有的声明。

Face	典型代码	应避免的错误
Host	main、profile、pnpm、updates	无意依赖 DOM
Client	React、slots、theme	无意使用 Node/Electron
Host tests	fs、fake subprocess、temporary profile	测试声明污染生产
Client tests	layout/environment/presenter	缺少浏览器契约

四、Vitest 重点测状态与生命周期

纯逻辑测试覆盖 Profile 发现、patch 组合、window options、SemVer、下载容器、布局列计算等；更重要的是用可控 Promise 和 fake timer 测并发与 teardown。

Profile service 测试会构造 deferred persistence/restart：第一个目标正在持久化时发起第二个目标，断言第一目标获胜；持久化失败后第二目标可以继续；restart 失败后 committed target 保留，其他目标被拒绝，同目标可以只重试 restart。

Shutdown 测试则使用 fake timer：

vi.useFakeTimers()
const shutdown = createDesktopShutdown(
  () => new Promise<void>(() => {}), // 模拟永不结束的 disposer
  exit,
  25,
)

void shutdown.request(0)
await vi.advanceTimersByTimeAsync(25)
expect(exit).toHaveBeenCalledWith(1)

还会验证第二次 request 立即升级、dispose reject 阻止 relaunch、SIGINT/SIGTERM/before-quit 都进入同一协调器。这样，最难手工复现的竞态被压缩成毫秒级确定测试。

五、Spawn Harness 验证命令而不真的开终端

终端与打包脚本的风险常藏在 command、argv、cwd、env、shell 和 windowsHide 组合中。测试定义可注入 spawn，记录调用并返回 EventEmitter 伪 child，不需要真的打开 Terminal 或 Windows Terminal。

const spawn = (command, args, options) => {
  calls.push({ command, args, options })
  return fakeChild
}

const launch = openDesktopTerminal({ ...options, spawn })
expect(calls[0].options.shell).toBe(false)
expect(calls[0].options.cwd).toBe(options.profileDir)

测试会读取生成的 shim，检查 macOS shell quoting、Windows DisableDelayedExpansion、Electron ABI 环境、DSH home、Profile 默认值、文件权限和欢迎命令；还会触发 child error/非零 exit，确保只报告一次启动失败。

flowchart LR
    T["Test Case"] --> API["openDesktopTerminal"]
    API --> FS["临时目录中的 Shim/Welcome"]
    API --> SP["Injected Spawn Harness"]
    SP --> CALL["记录 command/argv/cwd/env"]
    SP --> EVT["模拟 error/exit"]
    FS --> ASSERT["内容/权限断言"]
    CALL --> ASSERT
    EVT --> ASSERT

    classDef test fill:#2563eb,color:#fff,stroke:#1d4ed8,stroke-width:2px;
    classDef seam fill:#8b5cf6,color:#fff,stroke:#6d28d9,stroke-width:2px;
    classDef evidence fill:#10b981,color:#fff,stroke:#047857,stroke-width:2px;
    class T,API test;
    class FS,SP,CALL,EVT seam;
    class ASSERT evidence;

图3 可注入进程边界：不弹窗口也能验证完整启动参数

六、CLI Smoke 验证 Electron-backed Node

单元测试证明 shim 字符串正确，仍不能证明 Electron executable 真能以 Node 模式执行打包 entry。verify-cli-runtime.mjs 使用安装依赖中的 Electron 路径，设置 ELECTRON_RUN_AS_NODE=1，以 shell: false 运行 Desktop DSH bootstrap 与 pnpm entry，并比较实际版本。

它还创建一个临时 lifecycle project，离线执行 pnpm install，让 install script 记录 NODE、npm_node_execpath、runtime、target 与 disturl，确认 lifecycle script 使用私有 Node shim、针对 Electron ABI，同时没有继承 ELECTRON_RUN_AS_NODE。运行前后还检查 runner-only 环境没有泄漏到 Host PATH。

CLI Smoke 断言	防止的问题
DSH `--version` 正确	bootstrap/entry 路径错误
pnpm `--version` 正确	私有 PATH shim 不可执行
lifecycle 使用 Node shim	native script 调错系统 Node
runtime/target/disturl 正确	Electron ABI 构建错误
child 中无 RunAsNode 泄漏	普通脚本被当成 Electron Node entry

七、Loader Smoke 比“能 import”更接近真实系统

插件宿主最大的集成风险不是模块能否 import，而是 Cordis Loader 能否按 bundle/patch 顺序激活 row、Web server 能否绑定、根页面与 client manifest 是否包含预期模块。

Loader smoke 使用构建后的 Desktop package和已发布 DSH Web Profile，启动 loopback Host，等待就绪后请求页面和 manifest，但不会创建 Electron BrowserWindow。

sequenceDiagram
    participant Smoke as Headless Script
    participant Loader as Cordis Loader
    participant Host as DSH Web Host
    participant HTTP as Loopback HTTP

    Smoke->>Loader: 激活构建后的 Desktop rows
    Loader->>Host: 组合 Web Profile + 第三方 fixture
    Host->>HTTP: 绑定临时端口
    Smoke->>HTTP: 请求根页面
    HTTP-->>Smoke: Web frontend
    Smoke->>HTTP: 请求 client manifest
    HTTP-->>Smoke: 上游/Desktop/第三方 modules
    Smoke->>Loader: dispose generation

图4 Headless Loader Smoke：验证真实组合，不启动图形窗口

这种 smoke 能发现 package export、Loader metadata、patch order、Web surface 和 Client module 集成问题，成本又低于完整 Electron E2E，适合进入常规 check。

八、Profile Smoke 验证第三方消费路径

tests/fixtures/desktop-host-services-smoke-plugin 是一个最小 Profile 本地包。它声明 required desktopProfiles 与 desktopPnpm，读取当前 Profile name/dir，确认 run() 与 runPlugin() 存在，但绝不真正执行包管理修改。

Profile smoke 把 fixture 复制到临时 Profile 的 node_modules，以普通 bare package Loader entry 加载。如果 probe 没返回正确激活 Profile 或两个方法，测试失败。这里验证的是“第三方包通过受支持 contract 加载”，而不是 Desktop 源码内部直接 import 自己。

fixture 位于 tests/，不在 npm files 或 Electron build files 中，防止测试探针意外进入生产 archive。

九、Runtime Closure 与 Packaged Runtime Gate

runtime-closure 从 deploy root 遍历生产依赖，拒绝未由根 manifest 声明的必需 peer，防止 workspace hoist 掩盖发布缺口。afterPack verifier 则读取真实 app.asar 和 app.asar.unpacked：检查 main/client/profile/pnpm/update/DSH CLI/Web frontend 等入口，Windows 还要检查 node-pty x64 prebuild。

最后，resolver 以 unpacked 根的 package.json 为锚点解析关键 specifier，结果必须留在产物根，不能回到源码 workspace。这道断言解决“构建机能 resolve，干净机器失败”的典型假阳性。

flowchart TD
    ROOT["Deploy Root Manifest"] --> RC["Runtime Closure"]
    RC --> PEER{"必需 Peer 完整？"}
    PEER -- "否" --> FAIL["打包前失败"]
    PEER -- "是" --> PACK["Electron Builder"]
    PACK --> ASAR["检查 app.asar entries"]
    PACK --> UN["检查 unpacked/native entries"]
    UN --> RES["从产物根解析 exports"]
    RES --> OUT{"路径仍在产物内？"}
    OUT -- "否" --> FAIL
    OUT -- "是" --> PASS["允许进入平台发布"]

    classDef source fill:#2563eb,color:#fff,stroke:#1d4ed8,stroke-width:2px;
    classDef decision fill:#f59e0b,color:#111827,stroke:#d97706,stroke-width:2px;
    classDef failure fill:#ef4444,color:#fff,stroke:#b91c1c,stroke-width:2px;
    classDef success fill:#10b981,color:#fff,stroke:#047857,stroke-width:2px;
    class ROOT,RC,PACK,ASAR,UN,RES source;
    class PEER,OUT decision;
    class FAIL failure;
    class PASS success;

图5 从声明闭包到物理闭包：源码绿色不等于产物完整

十、平台测试不能全部抽象掉

Windows check:win-package 可以在原生 x64 环境验证 build、type、选定测试、runtime closure、node-pty artifact 与 NSIS/PE。macOS release preflight 则检查 signing identity、公证凭据，让普通 yarn check 在无 secret 环境运行，只有 Electron Builder 签名步骤得到凭据，随后再验证 DMG。

可跨平台测试	必须目标平台验证
Profile 状态机与并发	Windows Terminal/PowerShell 发现
Window options object	Mica/vibrancy 实际外观
ACL argv adaptation	真实 Windows ACL confinement
下载容器解析	通知、安装器打开、升级
签名环境适配纯逻辑	Keychain/Authenticode/SmartScreen

抽象边界可以减少目标机测试数量，但不能让平台行为凭空变成纯函数。文章或 CI 报告应明确哪些只通过结构检查，哪些已在真实系统验证。

十一、推荐的检查顺序

git submodule update --init --recursive
corepack yarn install --immutable
corepack yarn check

日常改动优先运行最小相关 Vitest/Typecheck；修改共享 Profile、Loader、打包或 native 边界后，再扩大到完整 yarn check。需要图形验证时显式运行：

corepack yarn dev

生成目录产物使用 package:dir，但它不是正式 release；Windows/macOS installer、签名、公证与升级仍需各自 gate。

十二、为新功能选择正确测试层

纯转换、状态约束：写单元测试，不启动 Electron。
Cordis service 生命周期：挂载真实 Context，用 deferred Promise/fake timer。
文件/命令生成：临时目录 + injected spawn，断言内容、argv 与环境。
package export/Loader metadata：加入 headless Loader smoke。
Profile 第三方 contract：使用独立 fixture，不能内部直连。
ASAR/native 文件：加入 afterPack 必需清单与 resolver。
窗口材质、终端、sandbox、通知：安排目标平台 smoke。
签名、安装与升级：进入 release gate，不能由单测代替。

测试覆盖应随 blast radius 扩大。修改一个 clamp 函数不需要构建 NSIS；修改 Profile composition 或 package export 只跑单元测试则明显不足。

十三、测试体系最常见的五种反模式

第一种是只看覆盖率百分比。Profile 回滚的核心是 pending、last-known-good、mount commit 与 relaunch 的顺序，几行分支即使被随机执行，也不代表竞态语义被断言。应使用 deferred Promise 明确控制每个阶段，并验证事件顺序、Promise 身份和磁盘状态。

第二种是用内部 import 冒充插件集成测试。Desktop 源码可以直接 import profile-service.ts，但第三方包面对的是 package exports、声明文件、Loader bare resolution 和 Cordis service 注册。Profile fixture 必须像真实外部包一样位于临时 node_modules，否则无法发现 exports 或 resolver 问题。

第三种是让自动检查顺便打开 Electron 窗口。在开发机上它可能只是闪一下，在无显示构建机上会挂起、超时或污染用户 session。图形启动应是显式命令，普通 build/type/test/Loader smoke 只使用 Host 与 loopback carrier。

第四种是只验证源文件存在。Electron Builder 会改变目录、ASAR 与 unpacked 布局；开发 workspace 中的文件不能证明产物拥有它。afterPack 必须读取最终 archive、探测物理文件，并从产物根实际 resolve package exports。

第五种是把所有平台行为 mock 掉后宣称跨平台通过。Mock 适合验证 argv 和策略选择，却不能证明 Mica、Windows Terminal、ACL、Keychain、签名、公证或 SmartScreen。测试报告应把结构证据与目标机证据分开写。

反模式	产生的假信心	推荐证据
只看覆盖率	执行过但没验证顺序	deferred/fake timer 断言
内部 import fixture	忽略 exports/Loader	bare package Profile smoke
自动弹 Electron	本机可跑、CI 挂起	headless Host smoke
检查源码文件	忽略 ASAR 产物布局	afterPack archive/unpacked gate
全部平台 mock	忽略真实 OS 行为	原生机器 release smoke

十四、Fixture 与测试数据怎样保持可信

临时 Profile、临时 home 和临时 runtime directory 应由每个测试创建并在 finally/afterEach 中清理，避免前一次 lockfile、state 或 shim 影响后一次结果。测试数据要刻意包含空格、单引号、百分号、非 ASCII Profile 名、大小写不同的 Windows 环境变量和畸形状态文件，因为这些才是路径/escaping 代码真正容易失败的输入。

Fixture 应尽量小，只提供当前 contract 所需的 package manifest 与入口。Desktop Host service smoke fixture 只读取 desktopProfiles.current 并检查两个 pnpm 方法存在，不执行真实安装；真实包变更属于另一个更昂贵、需要网络/registry 控制的测试层。小 fixture 更容易判断失败来自 Loader 还是业务代码。

测试替身还应保留真实接口形状。Fake child 用 EventEmitter 发出 error/exit，fake archive lister 返回最终 entry 格式，fake resolver 接受真实 specifier；不要为了让测试好写，创造生产代码永远不会接收的简化接口。注入 seam 的目标是替换外部副作用，不是替换被测业务规则。

十五、根据改动映射最小 Gate

改动类型	最小验证	需要扩大的条件
layout clamp/theme presenter	相关 Client Vitest + Client typecheck	改 root slot/窗口 chrome
Profile state/service	Profile 单测 + Host typecheck	改 Loader composition
pnpm/terminal argv	单测 + CLI smoke	改 native ABI/packaged entry
package exports/dependencies	build + closure + Loader/Profile smoke	改 ASAR files
Electron Builder 配置	package:dir + afterPack	平台 installer/signing
Windows ACL/native patch	聚焦单测	必须 Windows 原生 smoke
更新安装交接	checker/download 单测	DMG/NSIS 真实安装升级

一个实用策略是先运行能最快证伪当前改动的测试，再沿依赖方向扩大。例如修改 desktopPnpm 参数校验，先跑 pnpm spec 和 typecheck；若又改变打包 entry，再增加 CLI smoke、runtime closure 与 package:dir。这样既不会每改一行都构建安装器，也不会在跨模块 contract 已变化时停在局部绿色结果。

测试失败时也按层定位：layout gate 失败先修所有权；typecheck 失败先修契约；Vitest 失败看领域状态；CLI smoke 失败看 executable/env；Loader/Profile smoke 失败看组合与 package resolution；afterPack 失败看最终文件；目标机失败再查原生系统和签名。清晰的层次能让“完整 check 红了”快速变成可行动的问题。

十六、测试报告应准确写出验证边界

一份可审计的结果至少要包含实际命令、宿主平台与架构、Node/Electron 版本、通过/失败状态，以及没有运行的目标平台 gate。只说“所有测试通过”却没有执行 package:dir，不能推导安装包闭包通过；在 Linux 上通过 Window options 单测，也不能推导 Windows Mica 或 ACL confinement 已完成原生验证。

报告用语	是否准确
“Vitest 与四套 typecheck 通过”	准确，限定了层次
“Loader smoke 请求根页面和 manifest 通过”	准确，说明真实组合证据
“应用在所有平台可用”	不准确，除非有目标机证据
“Windows 安装包可正式发布”	不准确，若只有未签名 NSIS
“未运行 macOS 签名/公证”	准确披露剩余限制

失败报告也应保留最短依赖路径、Profile 名称、被检查的产物根和关键 exitCode/signal，但避免输出 secret、完整环境或用户凭据。高信号报告让下一位维护者能够复现同一层，而不是从头猜测“测试到底测了什么”。

参考资料

总结

从测试工程角度看 anywhere-labs/deepseek-harness-desktop，我认为它最有价值的不是某个测试框架，而是把不同风险分配给不同证据。

仓库拓扑由 layout verifier 守住，避免产品构建偷偷链接只读上游；Host、Client 和两类测试分别 typecheck，防止环境声明互相污染；Vitest 用可注入 adapter、deferred Promise、fake timer 和临时目录把 Profile 并发、五秒退出、终端 quoting、窗口参数与 sandbox argv 变成确定断言。

再往上，CLI smoke 真正用 Electron-backed Node 跑 DSH 与 pnpm，并执行离线 lifecycle script 检查 ABI 环境；Loader smoke 激活构建后的 Cordis rows、访问 loopback 页面与 client manifest，却保持 headless-safe；Profile fixture 则证明第三方 bare package 可以通过公开 service contract 工作，而不是 Desktop 内部自己调用自己。最后，runtime closure、ASAR/unpacked verifier 和平台 installer gate把验证推进到物理产物，拒绝 hoist、构建目录和开发缓存制造的假绿色。

小而真实的 fixture、包含特殊字符的测试数据、从最终产物根执行的 resolver，以及明确区分结构 mock 与目标机 smoke 的报告，共同让这些证据更接近用户环境。对我而言，这套体系说明测试深度不等于一味追求端到端：高质量策略应让纯逻辑快速、生命周期可控、真实组合可重复、图形启动显式、平台行为保留目标机证据；改动小时运行最小聚焦测试，跨越 Profile、Loader、package export 或 native 边界时再按影响方向扩大 gate。

以后为任何 Electron 插件宿主添加功能时，我都会先问失败最可能发生在哪一层，再选择最接近它的测试，并在结果中准确说明哪些已经实际运行、哪些仍需真实平台，而不是把所有信心都压在一条昂贵、缓慢又难定位的 E2E 上。