企业官网建设流程全解析

先明确一件事：这篇博客的动机是什么。我最初拿到 DeepSeek Harness Desktop 这个项目时，第一反应就是——它到底跟普通的 Web 项目有什么区别？后来把dsh web跑起来，又在桌面端打开同一个界面，才发现它背后真正值钱的地方不是某个花哨功能，而是那套“同一份 UI、两种 Runtime 共存”的架构设计。今天这篇不聊理论，直接进源码，拆一拆它到底是怎么把 Web 与本地 Runtime 解耦的。

1. 项目背景：DeepSeek Harness 到底是一套什么东西

1.1 从 Harness 与 Agent 的区别说起

先纠正一个经常被搞混的概念：Harness 和 Agent 不是一回事。热词里同时出现了harness和agent区别和deepseek harness插件，说明很多人第一眼都把它理解成了“又一个 Agent 框架”。

我的理解是：Agent 强调的是自主决策——给模型一个目标，它能自己去调用工具、规划步骤、复盘结果，核心是一个“循环”。而 Harness 强调的是可组合的运行框架——它把模型、工具、技能（Skill）、执行环境（本地进程、容器、远程 API）都变成可插拔的部件，然后用一套明确的协议把它们装配在一起。说白了，Harness 更像是“给模型套上的一层外壳”，它不替模型做决策，但它保证模型想调工具的时候，工具能按预期执行。

DeepSeek Harness Desktop 就是这套思路的桌面化产物。它不只面向 DeepSeek API，也接本地模型引擎（比如 llama-server）、Codex CLI、Docker 容器，甚至可以通过 DS 的 API 协议接第三方兼容服务。上线之后你会发现，真正让它区别于同类项目的，是同一套 UI 在 Web 和桌面两种形态下都能跑，而且压缩到接口层面的 Runtime 切换对 UI 完全透明。

1.2 共享 UI 的三个运行形态

我在源码里看到的项目结构，基本上是按“三个运行形态”组织的：

• 纯 Web 形态：dsh web启动一个本地 HTTP 服务，终端会打印一个 URL，浏览器打开就能用。
• 桌面形态：用 WebView2 之类的内嵌浏览器壳承载同一套前端代码，前端文件从本地打包资源加载，而不是走网络。
• 混合/代理形态：UI 在本地桌面壳里跑，但 Runtime 可能部署在远端服务器或容器里，通过 RPC/HTTP 转发。

这三个形态有一个共同点：前端拿到的永远是同一个接口。前端代码里不会有if (isDesktop)这种到处散落的分支。差异全部被收在 Runtime 抽象层和桌面壳的桥接层里。这跟我见过的很多“伪桌面化”项目很不一样——后者通常是把 Web 页面塞进 Electron/WebView，然后接口直接请求线上的 URL，本地 Runtime 根本没有被纳入设计。

1.3 核心问题：为什么需要解耦 Web 与本地 Runtime

如果只是做一个“套壳应用”，解耦根本没意义。关键是这里存在一个现实矛盾：浏览器环境的权限和能力，跟桌面环境的完全不一样。

浏览器里，你不可能直接启动一个本地进程，也不可能随意读写文件系统、监听端口。但如果你想让 UI 能驱动“本地模型推理”“执行本地脚本”“拉起 Docker 容器”这些真实算力，就必须把 Runtime 挪到本地。而如果强行让前端通过复杂的桥接代码直接操作本地进程，那 Web 版就废了——浏览器跑不了。

所以架构上必须做分层：UI 层只关心“发送消息、接收流式输出、展示工具调用”，Runtime 层负责“模型推理、工具执行、生命周期管理”。这两者之间的通信协议一旦稳定下来，无论是 Web 还是桌面，都只是“Runtime 放在哪”的问题。这套设计，就是标题里说的“解耦”的真正含义。

2. 解耦的关键：Runtime 抽象层是怎么设计的

2.1 Runtime 接口与 Engine Protocol

解耦的核心不是 UI，而是 Runtime 抽象层。我翻了源码，整个项目的 Runtime 模块基本都收敛在一个engine/目录下，对外暴露的是统一的引擎接口。你可以把它理解成一个“端口发现 + 协议注册 + 进程管理”的中间层。

接口本身并不复杂，大概是下面这个形态（按源码里常见做法的合理还原）：

// engine/types.ts export interface EngineRuntime { id: string; // 引擎唯一标识，比如 'llama-server' health(): Promise<HealthStatus>; // 健康检查：进程活着吗、端口通吗 chat(req: ChatRequest): AsyncIterable<ChatChunk>; // 流式对话 tools(): ToolDefinition[]; // 当前引擎支持哪些工具 executeTool(name: string, args: unknown): Promise<unknown>; dispose(): Promise<void>; // 释放进程/端口 }

凡是接入 Harness 的本地 Runtime，都必须实现这四个核心方法：健康检查、对话、工具定义、工具执行。所谓 Engine Protocol，就是这套接口的线上协议版本——HTTP 端点、SSE 流式格式、工具调用消息格式都已经被固定下来。

热词里那句engine protocol runtime llama-server for，对应的就是 llama.cpp 系引擎在 Harness 里的适配层实现：把 llama-server 的 OpenAI 兼容 API 映射到统一的chat()/executeTool()接口。这样一来，UI 永远不知道它对面是 llama-server 还是 DeepSeek 官方 API，它只知道“这个 Runtime 能对话、能调工具”。

2.2 dsh web 认证链路：一次 URL 回传背后的进程模型

热词里有一条很常见的报错：dsh web authentication required; reopen the url printed by dsh web.。这条信息的背后，正好能看出 Harness 把认证也做进了 Runtime 抽象层。

具体流程是这样的：执行dsh web后，CLI 会在本机随机端口起一个 HTTP 服务，同时生成一个带一次性 token 的本地 URL 打印到终端。你打开浏览器访问这个 URL，页面会发起一轮跟远端服务的认证（类似 OAuth），拿回凭证后通过回调写回本地服务，最终落到本地配置目录的凭证文件里。

这个设计妙在：认证凭证绑定的是URL + token + 本地端口这一组合，而不是某个固定的浏览器环境。所以你在终端打开的 Web 页面能认证，桌面 WebView2 里打开http://127.0.0.1:端口也能走同一套流程。UI 完全没有感知“认证发生在哪个容器里”。

如果报出authentication required; reopen the url，基本上就是本地服务已经拿到了请求，但发现当前请求没带有效凭证，或者 token 过期、被代理改写导致匹配失败。排查思路也比较直接，后面我会专门写一节完整的排查链路。

2.3 本地优先与云端降级：Runtime 的选择策略

Runtime 抽象层里还有一个值得拎出来讲的细节：选择策略。源码里不是“非本地即云端”的二选一，而是一个带健康检查的优先级链。

默认策略大致是：

1. 看配置里有没有显式指定 runtime（比如--runtime llama-server），有就直接用。
2. 没有指定，就按顺序探测本地已注册的 Runtime：llama-server → Codex CLI → Docker 容器 → 云端 API。
3. 每个 Runtime 注册包里都带一个probe()函数，探测命令是否存在、端口是否通、模型文件是否就位。
4. 探测失败就自动降级，同时把降级原因写进日志和 UI 的状态栏里。

这个策略最大的好处体现在用户体验上：用户第一次跑的时候可能本地啥都没装，UI 也可以正常走云端 API；等他装了 llama-server、启动好模型，下次打开同一个页面，UI 不用任何修改，流量就被切到本地了。这种“无声切换”才是 Runtime 抽象层真正发挥作用的地方。

3. 共享 UI 的工程实践：一套代码、两套运行时

3.1 WebView2 Runtime 依赖的两种处理方式

桌面形态用的是 WebView2（Edge 内核），这就牵扯到热词里那句could not find the webview2 runtime。如果你把共享 UI 直接打包成桌面应用，而目标机器上没有 WebView2 Runtime，应用启动时会直接报错。

源码里对这个问题有两种处理路径，我建议你按目标用户性质选择：

• Evergreen 模式：安装包检测系统中是否已有 WebView2 Runtime，没有就静默引导下载。适合面向个人开发者、网络环境好的场景。
• Fixed Version 模式：把特定版本的 WebView2 Runtime 的完整运行时文件打包进应用目录，不依赖系统环境。适合企业内网、离线环境。

两种模式的核心差异在于运行时文件放哪里、由谁负责更新。Evergreen 由系统自动更新，Fixed Version 跟着应用走。实现上，项目里通常会在应用启动的最早期做一次环境检查，把检查结果透传到 UI 层，让界面能直接展示“缺 WebView2 Runtime，请安装”之类的引导页，而不是白屏。

3.2 IPC 桥接层：UI 与本地 Runtime 的边界

这一节是“共享 UI”能跑起来的工程保证。在纯 Web 形态下，前端通过fetch访问本地 HTTP 服务；在桌面形态下，前端代码不能直接fetch本地 Runtime 吗？理论上可以，实际上很多教训都出在这里——桌面壳的页面是file://或http://127.0.0.1:自定义端加载的，跨域、安全策略、端口冲突都会带来不可控问题。

所以源码里在桌面壳上做了一层 IPC 桥接。核心思路是：把前端要调用的 Runtime 能力，封装成一组window.harness的方法；桌面壳收到调用后，再通过进程间通信（Native ↔ JS）转发给本地的 Harness 核心进程。

// preload.js（WebView2 注入脚本，源码逻辑的简化还原） const { ipcRenderer } = require('electron'); // 原生进程通信对象 window.harness = { chat: (payload) => ipcRenderer.invoke('runtime:chat', payload), executeTool: (name, args) => ipcRenderer.invoke('runtime:executeTool', name, args), health: () => ipcRenderer.invoke('runtime:health'), };

前端代码里统一用window.harness，Web 形态下这个对象直接指向封装好的 HTTP 客户端，桌面形态下指向 IPC 桥接。UI 层的代码完全不用改。

这个桥接层的存在，还解决了一个很实际的问题：不要把秘密留在 UI 进程里。API Key、凭证文件、本地端口号这些敏感信息都由核心进程持有，UI 拿到的只是调用结果。浏览器形态的 Web 页面即便被 XSS，也无法直接读取本地凭证文件。

3.3 与 Docker Desktop 联动的真实场景

热词里docker desktop安装教程、virtualization support not detected docker desktop failed to start because v频繁出现，说明很多人试图在容器环境里跑 Harness 或让 Harness 拉起容器。源码里确实有 Docker 这一级 Runtime，作用是在隔离环境里执行不信任的工具调用。

当用户的 Skill 需要在容器里跑 Python、跑编译任务，或者做那种“执行完就能销毁环境”的场景时，Harness 会检查 Docker Runtime 是否可用。检查项包括：

• docker version是否能正常返回客户端和服务端信息
• 当前用户是否在 docker 用户组里
• 端口映射是否冲突

如果用户在 Windows 上还没启动 Docker Desktop，或者机器没有开启虚拟化（Hyper-V/WSL2），就会直接探测失败。UI 上会展示一条“容器 Runtime 不可用，已自动降级到本地进程/云端”的提示。在这种设计下，容器的不可用不会拖垮整个应用，只会影响“需要容器环境”的那部分技能。

4. 源码关键模块拆解：会话、技能与工具调用

4.1 消息循环与 tool calls 即时响应

热词里有一条deepseek messages tool calls need immediate results。这句话其实点出了 Harness 这类框架里最容易做崩的一个环节：模型在对话中决定调用工具，但工具结果必须“即时”返回给模型，否则模型会认为工具一直没响应，可能会重复发起相同调用，甚至打乱上下文。

源码里的消息循环处理这个问题的做法是：把“模型输出 → 检测工具调用 → 执行工具 → 回填结果 → 继续请求模型”这个过程放在同一个会话线程里，并设置超时。工具执行是同步阻塞的，但每一段都预留了取消令牌（CancellationToken）。如果工具执行超过阈值，会话状态机会把该工具标记为失败，并把错误信息作为工具结果回填，而不是让线程挂死。

对应到共享 UI 上，这个机制体现为：前端能看到“正在执行工具 X”的状态卡片，但不会出现“卡住不动”的鬼样子。即使工具真的超时了，UI 也会收到一条明确的错误消息。

4.2 Skill 体系的加载与注册

Harness 里的“技能”不是普通意义上的提示词，而是带文件系统结构的可执行包。一个 Skill 目录通常包含：

• 一份声明文件（YAML/JSON），描述技能名称、描述、需要的资源
• 预置的 prompts 或 few-shot 示例
• 可执行脚本或工具定义

源码里有一个技能加载器，启动时会扫描配置目录下的 Skill 文件夹，逐个注册到运行时。登记完成后，模型在对话中就能发现“当前可用的技能有哪些”，并在适当的时候请求调用。

热词里阿里 harness creator skill出现了，说明“创建技能”本身已经被抽象成一套可被模型调用的工具。换句话说，你可以让模型帮你生成一个技能包，Harness 负责把它写入技能目录、校验格式、热加载。这套设计很自然地把“扩展 Harness 本身”这件事变成了 Harness 的日常能力。

4.3 DeepSeek API 接入层的流式处理

既然项目叫 DeepSeek Harness，那 DeepSeek API 的接入层就必然存在。这部分源码的核心工作是把 DeepSeek 兼容的 OpenAI 协议转换为内部 Runtime 格式。

流式处理有几个值得注意的点：

• 用 SSE（Server-Sent Events）接收逐 token 输出，前端 UI 也是按 token 粒度更新渲染，而不是等全部生成完才展示
• 工具调用消息在流里是结构化字段，UI 端要能识别“这一段是普通文本”还是“这一段是工具调用请求”
• 流结束时会带一个 finish_reason，状态机根据这个值决定是继续请求还是进入等待用户输入状态

这套接入层也是 Runtime 抽象的一部分。对 UI 而言，本地 llama-server 和 DeepSeek API 返回的流式数据最终都会走同一个归一化格式，所以前端组件只需要处理一种数据结构。

5. 实测踩坑：从安装到跑通的完整排查链路

5.1 “dsh web authentication required; reopen the url”排查过程

这个报错我踩过不止一次，每次都有一堆人问。完整排查链路大概是这样的：

1. 先确认本地服务真的起来了：curl -I http://127.0.0.1:<端口>，看响应头有没有透出认证要求。
2. 打开终端打印的原始 URL，不要手动改成localhost。因为 token 绑定的是127.0.0.1，你手动换成localhost，Host 头就不匹配，认证会失败。这条是最常见的坑。
3. 检查浏览器是否开了代理插件。代理在中间改写 Host 或拦截 Cookie，会导致本地服务拿不到正确的 token。热词里web安全类搜索很多，但这个问题往往跟安全软件拦本地回环流量有关。
4. 若端口被占用，CLI 会换一个新端口，此时必须重新打开终端上最新打印的 URL，而不是沿用旧链接。
5. 如果以上都正常，再检查凭证文件是否可写。认证结果要写入配置目录，如果该目录只读（比如某些 tee 环境），也会报同样的错。

这类错误本质上是“客户端身份与本地服务端口绑定”的校验失败，跟远程认证失败不是一回事。想通这一点，排查就快了。

5.2 WebView2 Runtime 的静默安装与检测

桌面版跑不起来，十有八九是 WebView2 Runtime 缺失或版本过旧。热词里webview2 runtime下载就是这个问题。

源码包里的检测逻辑我建议你直接复用这种模式：启动时读取注册表/系统目录中的 WebView2 版本号，低于某个基线版本就弹引导页，让用户一键安装或让安装程序静默补装。不要在 UI 已经加载完成之后才报错——那会让用户看到一半白屏一半错误页，体验极差。

如果是在 CI 环境里测试桌面应用，记得在镜像内预装 WebView2 Runtime。否则你会在自动化测试里反复撞到“Session 启动失败”“无法创建 WebView2 环境”这类问题。

5.3 WebGL context 创建失败：容器与虚拟化环境

热词里three.webglrenderer: a webgl context could not be created出现在这里有点微妙，但这类报错在桌面壳内嵌页面里确实常见。

共享 UI 如果用了 Three.js 或者其他 WebGL 渲染库做数据可视化，那么在纯 Web 形态下浏览器能正常创建 WebGL 上下文，但在桌面壳或 Docker 容器里可能失败。原因通常是：

• GPU 驱动不可用，系统回退到 SwiftShader 软渲染但权限受限
• WebView2 的硬件加速策略与当前显卡驱动冲突
• 容器里缺少 GPU 透传（比如没挂载/dev/dri）

实用解法是：给 UI 层做“检测 WebGL 可用性，不可用则自动降级为 Canvas 2D 渲染”的能力。这不是偷懒，而是桌面类和 Web 类应用都要面对的现实。很多项目在浏览器里跑得好好的，一到桌面壳就白屏，九成是这个原因。

5.4 llama-server 引擎的启动参数与端口冲突

本地 Runtime 里，llama-server 是最常被接进来的引擎之一。源码的 Runtime 注册模块里，通常会在首启时做一次端口探测，默认端口如果被占，会自动顺延到下一个可用端口，并把端口信息写进运行时状态文件。但如果你手动指定了固定端口，而那个端口已经被别的实例占用，llama-server 会启动失败且不会自动换端口。

这时 UI 上能看到“Runtime 连接失败”，但终端日志里其实是 “address already in use”。建议启动前先做一次端口检查，失败了就弹明确的提示，列出占用端口的 PID，而不是只显示一句笼统的“引擎启动失败”。

另外，llama-server 的模型路径、上下文长度（--ctx-size）、GPU 层数（--n-gpu-layers）这些参数，在 Harness 里都应该映射到 Runtime 适配层的配置结构里，让用户能在 UI 上直接改，而不是去改命令行。

6. 把这套解耦思路用在自己的项目里

6.1 共享 UI 的最小改造模板

如果你手头有一个 Web 项目，想把它改成“Web 和桌面共用一套代码”，完全可以参考 Harness 的做法。最小改造只需要三步：

1. 把所有“调用后端 API”的地方收拢到一个apiClient模块里，不要散落各处。
2. 定义一组runtime.bridge接口，包含chat()、health()、executeTool()，Web 形态实现为fetch，桌面形态实现为 IPC 调用。
3. 前端只在启动时判断一次运行环境，选择不同的 Bridge 实现注入到全局，UI 组件永远只跟 Bridge 打交道。

这套模板的收益在后期非常明显：新增一个 Runtime 时，不会动 UI；反过来，UI 改版也不会影响 Runtime 的启动、认证和进程管理。

6.2 Runtime 抽象层模式总结

源码解析到最后，你会发现这套架构的本质其实是四个模式的组合：

• 端口发现与注册：Runtime 启动后把自己注册到本地服务，UI 通过服务发现找到它，而不是硬编码端口。
• 协议归一化：任何引擎都先映射到 Engine Protocol，再决定要不要透传原始协议给 UI。
• 健康检查与降级：每个 Runtime 都带health()，探测失败自动降级，用户看不到断裂感。
• 进程生命周期托管：桌面壳负责启动、停止、重启本地 Runtime，UI 不直接接管进程。

这四个模式并排写出来很朴素，但真要在自己的代码里落地，难点其实在边界管理：哪些东西归 UI 管，哪些归 Runtime 管，哪些是共享的会话状态。Harness 的答案是，把“身份认证”“凭证存储”“进程生命周期”“会话状态机”全部下沉到 Runtime 层，UI 只保留“消息展示、指令输入、调用状态”三个职责。

我自己的体会是，很多项目从一开始就把 UI 当成了“老板”，把 Runtime 当成了“跑腿的”，于是每次加一个后端能力，前端就要改一轮。真正解耦的做法是反过来：把 Runtime 当成稳定的协议提供方，UI 只是一个可替换的终端。这样哪怕有一天你想把 WebView2 壳换成 Tauri，或者把 Web 端从 React 迁到 Vue，你都不会伤筋动骨。

最后留一个小技巧：如果你也要写类似的共享 UI 应用，强烈建议在开发期把window.harness的实现固定成“Mock + 日志”模式——也就是让 UI 在没有真实 Runtime 的时候也能跑起来，只是所有调用都落到控制台。这会在联调阶段帮你省下大把时间，我就是这么把 Web 端和桌面端之间的隐性耦合一个一个揪出来的。