AAAAd-arch/nailong-harness

Nailong Harness

Nailong Harness 是一个用于 DeepSeek Harness 的轻量级原生 Windows 启动器。

下载 Nailong Harness v0.3.0-rc3

Windows x64 · 预发布版 · 需要 .NET 10 Desktop Runtime (x64)

它处理运行官方 Harness Web UI 所涉及的桌面相关事务：启动并打开 Harness、跟踪进程归属、报告启动状态、提供托盘控制、在需要时准备兼容的 Node.js 运行时，以及向上游 Harness 版本通知用户。Harness UI 仍然是官方上游 Web UI，并在用户的默认浏览器中打开。

Nailong Harness 是一个独立的非官方项目。它与 DeepSeek 无关联，也未获得其认可，不是 DeepSeek Harness 的分支，也不重新实现或修补 Harness Web UI。

为什么选择 Nailong Harness？

DeepSeek Harness 已经可以从终端启动。Nailong 并不取代该工作流程；它为那些不希望手动管理启动命令和进程生命周期的用户提供了一个小巧的 Windows 原生控制界面。

该启动器专注于实际的桌面相关事务：

- 避免重复启动启动器和 Harness；
- 显示真实的启动和失败反馈；
- 将 Start、Open、Stop 和 Exit 操作保留在系统托盘中；
- 区分由 Nailong 启动的 Harness 进程与在别处启动的进程；
- 仅清理 Nailong 拥有的进程树；
- 在不更改用户系统配置的情况下处理 Node.js 前置依赖；
- 在 Harness 的本地端点真正就绪后再打开它；以及
- 让上游版本的可用性可见，而不静默安装任何内容。

这就是该项目所说的“轻量但实用”：更少地占用用户系统，保持与上游的小耦合，并解决具体的 Windows 桌面摩擦。

功能

- 适用于 Windows x64 的原生 C# 和 WinForms 启动器。
- 系统托盘状态以及 Open、Start、Stop、更新和 Exit 操作。
- 启动器单实例行为。
- 托管和外部 Harness 归属跟踪。
- 防止终止外部 Harness 进程。
- 针对托管 Harness 进程树的 Windows Job Object 清理。
- 环回端点身份和就绪检查。
- 启动状态、取消、重试、失败详情和浏览器打开。
- 系统优先的 Node.js 工具链选择。
- 基于同意的、应用程序私有的托管 Node.js 运行时回退。
- 分阶段运行时下载、SHA-256 验证、安全解压、工具链验证和最终提升。
- 上游 Harness 版本检查和托盘通知。
- 支持 DPI 感知的启动器对话框。

快速开始
仓库的 Releases 页面提供了预构建的 Windows x64 版本。

1. 下载你想要使用的版本对应的 NailongHarness--win-x64.zip 资源。
2. 将 ZIP 解压到一个文件夹。
3. 运行 Nailong.Harness.Launcher.exe。

当前版本依赖于框架，需要 .NET 10 Desktop Runtime (x64)。如果缺少所需的运行时，.NET 宿主会引导你前往相应的 Microsoft 下载页面。

无需手动安装 Node.js。启动时，Nailong 会检查预期的本地 Harness 端点。如果已有有效的 External Harness 在运行，Nailong 会直接打开它，而不执行任何 Node.js 设置。否则，Nailong 会查找兼容的系统 Node.js 工具链，如有必要，会提供下载私有 Managed Runtime 的选项。Harness 就绪后，其 Web UI 会在默认浏览器中打开，Nailong 会继续在系统托盘中可用。

想要从源代码构建 Nailong 的开发者可以参阅从源代码构建。

详细的运行时要求请参阅平台与要求。

目录

- 工作原理
- 平台与要求
- Node.js 运行时
- Managed 与 External Harness
- 启动、托盘与单实例行为
- Harness 更新
- 应用程序数据
- 隐私与系统安全
- 架构
- 设计原则与非目标
- 从源代码构建
- 测试
- 故障排除
- 常见问题
- 已知限制
- 核心维护不变量
- 上游兼容性
- 第三方项目
- 许可证

工作原理

Nailong 将 DeepSeek Harness 视为上游组件：

Nailong Harness
|
| starts the official npm package when needed
v
@deepseek-ai/dsh
|
| serves the official local Harness Web UI
v
http://localhost:3080
|
| opened after readiness verification
v
Default browser

对于新的 Managed 启动，Nailong 通过经过验证的 npx.cmd 调用官方包。当前的包契约基于 @deepseek-ai/dsh@latest web --no-open，并带有显式的回环主机、端口和受信任浏览器选项。Nailong 使用 --no-open，以便它可以等待就绪状态，并控制已取消的工作流是否仍被允许打开浏览器。
受管 Harness 进程通常以当前 Windows 用户的配置文件目录作为其工作目录。包获取和执行仍保持 npm/npx 行为；Nailong 不会复制、fork 或在本地修补 Harness 包。

为什么 Web UI 在浏览器中打开

Nailong 有意将 Harness Web UI 交给用户正常的浏览器。这样可以保持启动器小巧，避免附带第二个浏览器运行时，保持官方 UI 的权威性，并减少与 Harness UI 内部实现的耦合。

这种取舍是有意为之：Harness 出现在浏览器中，而不是自包含的桌面窗口中。

平台与要求

| 用途 | 要求 |
| --- | --- |
| 支持的平台 | Windows x64 |
| 运行当前依赖框架的构建 | .NET 10 Desktop Runtime, x64 |
| 构建和测试 | .NET 10 SDK |
| Harness UI | 默认 Web 浏览器 |
| Node.js | 不一定需要预安装；参见 Node.js 运行时 |

该项目面向 net10.0-windows，并将 PlatformTarget 设置为 x64。它目前未声明自包含、单文件或基于 RuntimeIdentifier 的发布模式，因此依赖框架的构建需要安装相应的 .NET 10 Windows Desktop Runtime。

当前产品目标不支持 Windows ARM64。

Node.js 运行时

我需要安装 Node.js 吗？

不一定。仅当 Nailong 必须启动新的受管 Harness 时才需要 Node.js。仅为了打开已在运行的外部 Harness，应用启动时不会检查它。

选择流程如下：

Need to start a new Managed Harness
|
v
Compatible system Node.js toolchain?
| yes                 | no
v                     v
Use system toolchain    Valid Managed Runtime?
| yes        | no
v            v
Use private     Ask before
Runtime         downloading

系统 Node.js

Nailong 每次解析该先决条件时，都会优先使用兼容的系统工具链。当前兼容性策略遵循上游 Harness 范围：

^22.19.0 || >=24.0.0

预发布版 Node.js 版本会被拒绝。Nailong 还会验证 node、npm 和 npx 是否存在且可执行；仅找到 node.exe 不被视为完整的工具链。

受管运行时

如果没有兼容的系统工具链可用，Nailong 会查找其自身有效的应用私有运行时。如果不存在，则在下载任何内容之前会先询问用户。

当前的受管运行时是官方 Node.js v24.19.0 LTS Windows x64 二进制发行版。它是用于运行 DeepSeek Harness 的固定回退方案，不是通用 Node.js 安装，也不是多版本 Node 管理器。
固定版本使启动器行为可复现，并允许对归档文件、预期文件和版本输出进行验证。如果上游 Harness 更改其外部 Node.js 要求，Nailong 可能需要相应更新。

系统影响

托管运行时是 Nailong 私有的。Nailong 不会：

- 通过 MSI 安装 Node.js；
- 将 Node.js 添加到用户或计算机的 PATH；
- 设置持久的 NODE_HOME 或 NODE_PATH 值；
- 替换现有的 Node.js 安装；
- 更改 nvm 或其他版本管理器；或
- 为计算机全局安装 Node.js。

对于托管 Harness 启动，Nailong 仅将所选运行时目录添加到 Harness 子进程的环境中，并调用该运行时的绝对 npx.cmd 路径。此环境更改不会持久化到 Windows 中。如果在使用 Nailong 的私有运行时之前，node --version 在普通终端中无法工作，那么之后它在那里仍然无法工作。

运行时验证

Nailong 以事务方式准备回退运行时：

1. 从官方 Node.js HTTPS 端点将固定归档文件下载到暂存目录。
2. 根据固定的 SHA-256 值验证归档文件。
3. 在解压期间拒绝绝对路径、逃逸路径或符号链接归档条目。
4. 确认预期的 node.exe、npm.cmd、npx.cmd 和 npm 工具链文件存在。
5. 执行版本探测并要求预期的 Node.js 版本。
6. 仅在验证成功后，才将暂存目录提升到最终运行时位置。

仅当服务器提供真实的内容长度时，下载进度才会以百分比显示。否则，UI 会使用不确定状态，而不是编造百分比。

托管与外部 Harness

所有权是安全边界，而不仅仅是状态标签。

托管 Harness

托管 Harness 由 Nailong 启动。Nailong 拥有其进程生命周期，并且可以：

- 打开其 Web UI；
- 停止它；以及
- 在启动被取消或 Nailong 退出时清理所拥有的进程树。

该进程被附加到 Windows 作业对象，因此作为所拥有 Harness 树的一部分启动的后代进程也会被纳入清理范围。

外部 Harness

外部 Harness 已经独立运行，例如因为用户已在终端中启动它。Nailong 可以检测它并打开其 Web UI，但不会取得该进程的所有权。

因此：

- 外部 Harness 无法使用停止功能；
- 退出 Nailong 不会终止它；以及
- 打开它不需要 Node.js 先决条件设置。

此行为可防止启动器终止并非由它创建的进程。

端点身份

当前端点是环回地址 127.0.0.1:3080。Nailong 所做的不仅仅是检查端口是否打开：它会检查 HTTP 响应中是否存在可识别的 Harness Web UI 签名。如果无关的 HTTP 服务占用了该端口，Nailong 会报告冲突，而不是将该服务视为外部 Harness。
启动、托盘与单实例行为

启动体验

启动对话框会报告真实阶段，例如环境检查、进程启动和就绪验证。它支持：

- 取消并清理所拥有的进程；
- 在工作继续进行时将窗口隐藏到托盘；
- 失败后重试；
- 技术性失败详情；以及
- 仅在确认就绪后才打开浏览器。

启动工作不会显示虚假的百分比或预计时间。运行时下载进度是独立的，并且仅在可测量时才是确定性的。

托盘行为

托盘是启动后的主要控制界面。它显示当前 Harness 状态，并公开对该状态有效的操作，包括 Open DeepSeek Harness、Start Harness、Stop Harness、上游更新操作和 Exit Nailong Harness。

当冲突工作或关闭正在进行时，操作会被禁用。仅当 Nailong 拥有 Harness 进程时，Stop 命令才会启用。

单实例行为

Nailong 会阻止多个独立的启动器/托盘生命周期在同一 Windows 用户会话中运行。再次启动 Nailong 会请求现有实例处理激活意图，而不是创建第二个托盘和进程所有者。

Harness 更新

Nailong 会检查 npm 注册表，以发现 @deepseek-ai/dsh 新观察到的上游发布。它会存储一个小型高水位状态，以便可用的发布可以保持可见，而不会重复显示相同的通知。

更新功能仅用于感知和确认：

- 它可以显示更新菜单项和 Windows 托盘气泡；
- 打开更新操作会导航到上游 npm 包页面；
- 关闭该发布即表示确认；以及
- 确认写入失败会保留待处理状态，而不是假装已保存。

Nailong 不会自动安装 Harness 发布，也不会更新 Nailong 自身。新的 Managed 启动会请求 @deepseek-ai/dsh@latest；确切的包解析和获取行为仍由 npm 负责。当通知到达时，已在运行的 Harness 进程不会被替换或热更新。

应用程序数据

Nailong 拥有的数据存储在以下位置：

%LOCALAPPDATA%\NailongHarness\
├── runtime\
│   └── \
└── update-state.json

- runtime 包含私有 Managed Node.js Runtime 以及准备活动期间的临时安装目录。
- update-state.json 仅包含 Nailong 的 Harness 发布发现、确认和通知状态。

Nailong 目前不会创建自己的持久日志目录。
对于手动构建或便携副本，删除可执行文件或构建输出不会自动移除 Local AppData。在 Nailong 和任何 Managed Harness 停止后，删除 %LOCALAPPDATA%\NailongHarness 会移除 Nailong 的私有 Runtime 和更新状态。它不会卸载系统 Node.js、清除全局 npm 缓存，也不会移除上游 DeepSeek Harness 所拥有的数据。

隐私与系统安全

Nailong 不包含应用程序遥测。启动器在其启动工作流中也不需要拥有模型提供商的 API 密钥或凭据；提供商配置属于上游 Harness 体验。

Nailong 自身可能出于以下明确目的发起网络请求：

- 查询 npm registry 以获取上游 Harness 发布元数据；
- 在用户同意后从 nodejs.org 下载私有 Runtime；以及
- 在启动新的 Managed Harness 时调用 npm/npx。

DeepSeek Harness 以及任何已配置的模型提供商有其自身的行为、配置、数据处理和许可证。Nailong 不代表它们做出隐私承诺。

启动器将其 Harness 就绪探测限制在本地回环端点，并且不会仅仅因为另一个进程正在预期端口上监听就声称拥有所有权。

架构

架构概览

Program
├── SingleInstanceCoordinator
└── LauncherApplicationContext
├── TrayView
├── HarnessWorkflowCoordinator
│   ├── HarnessManager
│   │   ├── HarnessEndpointProbe
│   │   └── HarnessProcessController
│   ├── StartupUiCoordinator
│   └── NodeRuntimeSetupCoordinator
│       ├── NodeRuntimeResolver / NodeRuntimeProbe
│       └── ManagedNodeRuntimeInstaller
└── UpdateUiCoordinator
└── HarnessUpdateService

- Program 建立单实例行为和 WinForms 消息循环。
- LauncherApplicationContext 是组合根，并协调应用程序生命周期和关闭。
- TrayView 拥有托盘控件和呈现资源，但不拥有 Harness 或更新业务逻辑。
- HarnessWorkflowCoordinator 串行化面向用户的 Start、Open、Stop、重试、激活和 Runtime 先决条件工作流。
- HarnessManager 拥有 Harness 生命周期状态以及 Managed/External 区分。
- HarnessProcessController 启动官方包，并拥有操作系统进程和 Job Object 处理。
- StartupUiCoordinator 拥有启动对话框会话、取消、重试和过期尝试隔离。
- Runtime 层解析、探测、下载、验证并提供 Node.js 工具链，而不修改系统安装。
- NodeRuntimeSetupCoordinator 拥有同意/下载 UI 会话及其取消生命周期。
- UpdateUiCoordinator 拥有轮询和更新交互状态；HarnessUpdateService 拥有发布高水位持久化和通知决策。

项目结构

assets/                         由启动器项目嵌入的图标
src/
└── Nailong.Harness.Launcher/
├── Harness/                生命周期、端点、进程和工作流逻辑
├── Runtime/                Node.js 解析和私有 Runtime 准备
├── Startup/                启动进度 UI 和会话协调
├── Tray/                   托盘呈现和资源
└── Updates/                上游发布检查、状态和 UI 协调
tests/
└── Nailong.Harness.Launcher.Tests/
自动化行为与生命周期测试

设计原则与非目标

设计原则

- 轻量启动器，实用行为。 解决 Windows 桌面摩擦，而不重建上游产品。
- 上游保持权威。 启动官方 Harness 包，并将其 Web UI 和功能保留为上游所有。
- 先归属，后控制。 一个可发现的进程并不自动成为 Nailong 可以终止的进程。
- 系统隔离。 优先使用现有的兼容工具链；将回退方案保持为私有且限定在子进程范围内。
- 真实的 UI。 显示真实状态和可衡量的进度，而不是编造的百分比或时间估计。
- 聚焦的架构。 在归属或生命周期需要的地方添加边界，而不是仅仅因为相似的类可以共享一个通用抽象。
- Windows 原生范围。 优化当前 Windows x64 产品，而不是维护推测性的跨平台层。

非目标

Nailong 有意不打算成为：

- 替代 Harness UI 或本地 Web UI 重写；
- DeepSeek Harness 的分支或修补发行版；
- Electron 或嵌入式 WebView 外壳；
- 通用 Node.js 版本管理器；
- npm、pnpm 或 yarn 管理器；
- Docker 或通用运行时平台；或
- 推测性的跨平台抽象框架。

从源码构建

开发要求

- Windows x64。
- .NET 10 SDK。
- Git，如果克隆仓库。

编译启动器或运行其自动化单元测试不需要系统 Node.js 安装。兼容的工具链对于真实的端到端 Harness 冒烟测试很有用；否则启动器可以执行其 Managed Runtime 同意流程。

命令

从仓库根目录：

dotnet restore nailong-harness.slnx
dotnet build nailong-harness.slnx -c Release
dotnet test nailong-harness.slnx -c Release

从构建输出运行启动器：

dotnet run --project src/Nailong.Harness.Launcher/Nailong.Harness.Launcher.csproj -c Release --no-build

该项目目前是依赖框架的。安装 .NET 10 SDK 可满足开发需求；运行依赖框架构建的用户需要适用于 Windows x64 的 .NET 10 Desktop Runtime。

测试

自动化测试套件侧重于行为与生命周期边界，而不是 WinForms 实现细节。覆盖范围包括：

- Managed 和 External Harness 归属；
- 重复启动和安全的 External Stop 行为；
- 启动取消、重试、就绪竞态以及过期尝试隔离；
- 关闭时的排空与浏览器打开取消边界；
- Job Object 与进程会话行为；
- 端点标识与端口冲突处理；
- 系统与托管 Node.js 的解析；
- 工具链验证与版本兼容性；
- 下载、SHA-256、解压路径、暂存、提升与取消行为；
- 子进程 PATH 隔离；
- 更新持久化、确认、通知与失败一致性；以及
- 托盘与高 DPI 布局行为。

使用以下命令运行测试套件：

dotnet test nailong-harness.slnx -c Release

启动器对话框使用明确的 96-DPI 设计基准。UI 变更还应在 100%、125% 和 150% 显示缩放下进行真实的 Windows 冒烟测试；以几何为重点的自动化测试并不能完全替代对渲染文本和控件的检查。

故障排除

出现“需要 Node.js”

Nailong 未找到完整且兼容的系统 node/npm/npx 工具链，也未找到有效的私有 Runtime。请选择 Download Runtime 以准备应用程序私有的回退方案，或取消并自行安装兼容的系统 Node.js 工具链。私有选项不会修改系统 PATH。

Runtime 下载失败

- 检查机器是否具有网络访问权限，以及 nodejs.org 是否可达。
- 从 Runtime 对话框重试。
- 阅读失败后显示的技术细节；哈希、解压、验证和网络失败都会被报告，而不会被静默接受。

Harness 无法启动

可能的原因包括首次 npm 包获取、网络或 npm 注册表故障、无效的 Node.js 工具链、上游 Harness 启动错误或端点冲突。请查看启动失败详情，并在解决所报告的原因后重试。

Nailong 不会尝试修复用户的全局 npm 安装或缓存。

预期端口已被占用

如果该端点自标识为 DeepSeek Harness，Nailong 会将其视为 External，并可能安全地打开它。如果该端点由其他 HTTP 服务占用，Nailong 会报告冲突，且不会抢占或终止该进程。

Stop 不可用

检测到的 Harness 可能是 External。Stop 被有意设为不可用，因为 Nailong 并未创建也不拥有该进程。请从启动它的终端或工具中停止它。

报告了新的 Harness 版本，但已打开的 UI 没有变化

版本检测不会替换正在运行的进程。在适当的时候，停止并启动由 Nailong 拥有的 Harness；新的 Managed 启动会请求上游 @latest 包，具体取决于 npm 的正常解析和网络行为。External Harness 仍由启动它的任何程序控制。

浏览器未打开

等待 Harness 进入 Running 状态，然后从托盘选择 Open DeepSeek Harness。已取消的工作流会有意抑制延迟的浏览器打开回调。
常见问题

我需要安装 Node.js 吗？

不需要。Nailong 优先使用兼容的系统工具链，但在需要启动 Managed Harness 时，可以请求许可下载一个应用私有的备用运行时。

Nailong 会全局安装 Node.js 吗？

不会。Managed Runtime 存储在 Nailong 的 Local AppData 目录下，仅作为 Harness 子进程的备用运行时存在。

Nailong 会修改 PATH 吗？

它不会持久性地修改用户或系统的 PATH。所选 Runtime 目录仅在新启动的 Managed Harness 进程的环境中被前置。

为什么 Harness 会在浏览器中打开？

浏览器承载的是官方上游 Harness Web UI。Nailong 有意保持为原生启动器和托盘控制器，而不是嵌入或复制该 UI。

Nailong 能停止我手动启动的 Harness 吗？

不能。它可以检测并打开该 External Harness，但该进程仍归启动它的用户或工具所有。

Nailong 会修改或修补 DeepSeek Harness 吗？

不会。它调用官方 npm 包，并依赖一小组外部启动和端点契约。

Nailong 会自动更新 Harness 吗？

不会。它会检查上游发布版本，并可以打开 npm 包页面。新的 Managed 启动会请求 @latest，但 Nailong 不会热更新或替换正在运行的 Harness 进程。

Nailong 会自我更新吗？

不会。当前项目没有 Nailong 自我更新机制。

Managed Runtime 存储在哪里？

位于 %LOCALAPPDATA%\NailongHarness\runtime 下。它与系统 Node.js 以及用户的全局 npm 缓存相互独立。

如果我之后安装了 Node.js 会怎样？

在后续的前置条件解析中，Nailong 会首先检查系统工具链。如果新的系统安装兼容且完整，即使已存在 Managed Runtime，也会优先使用它。

Nailong 会存储我的模型提供商凭据吗？

凭据录入和提供商配置属于上游 Harness UI 的职责。Nailong 的启动器工作流不需要这些凭据。

已知限制

- 仅支持 Windows x64；不支持 ARM64 及其他操作系统。
- Harness 在用户的浏览器中运行，而非嵌入式桌面界面。
- Managed Runtime 固定为一个经过验证的 Node.js LTS 构建版本，而不是跟踪任意 Node 版本。
- 首次获取 Runtime 和 npm 包可能需要互联网访问。
- 启动器目前使用一个固定的回环端点。
- 没有 Nailong 自我更新机制。
- 预构建版本以便携式 ZIP 归档形式分发；目前没有安装程序。

核心维护不变量

这些不变量定义了有意的项目边界：

1. 绝不终止 Nailong 不拥有的 Harness 进程。
2. 优先采用官方上游 Harness 行为，而非本地补丁或重新实现。
3. 绝不持久性地修改用户系统范围的 Node.js 环境。
4. 保持托管运行时对 Nailong 私有，并将其作用域限定在 Harness 子进程内。
5. 在提交运行时目录之前，验证下载、解压路径、完整工具链和版本。
6. 保留取消、关闭排空、会话身份和过期尝试隔离。
7. 仅显示真实状态和可衡量的进度。
8. 保持启动器对话框对 DPI 安全，并在常见 Windows 缩放级别下对 UI 更改进行冒烟测试。
9. 优先选择小型、聚焦的更改，而非推测性抽象。
10. 尽可能将 Harness Web UI 和内部产品行为置于启动器之外。

上游兼容性

Nailong 有意避免对 DeepSeek Harness 携带本地补丁。这减少了维护面，并保持上游 UI 和功能为权威，但这并非永久兼容性的承诺。

启动器有意依赖一小组外部契约：

- 能够通过 npm/npx 调用官方 @deepseek-ai/dsh 包；
- 该包所期望的 Node.js 兼容性要求；以及
- 安全识别并打开 Harness 所需的本地端点和就绪行为。

如果上游更改这些契约，Nailong 可能需要适配。仅限于上游 Web UI 的更改通常仍归上游所有，不需要 Nailong 复制该 UI。

第三方项目

- DeepSeek Harness 是由 Nailong 启动的上游智能体 harness 和 Web UI。
- npm 上的 @deepseek-ai/dsh 是用于托管启动和发布检查的上游包。
- Node.js 提供可选托管运行时使用的官方二进制发行版。
- .NET 提供 Nailong 自身使用的 Windows 桌面运行时和 SDK。

每个第三方项目和发行版仍受其自身许可证和条款约束。Nailong 的 MIT 许可证不会重新许可 DeepSeek Harness、Node.js、.NET 或其依赖项。

许可证

Nailong Harness 根据 MIT 许可证授权。参见 LICENSE。