DeepSeek Harness多端架构：共享核心与薄壳设计的工程实践

2. 为什么必须做多端而不是只做一个界面2.1 三端场景的真实差异先说结论DeepSeek Harness 选择做 CLI、Web、桌面端三端不是为了凑数而是这三个入口解决的是完全不同的使用场景。命令行端的核心场景是“脚本化、可复用、可管道化”。我在终端里执行dsh run --skill code-review --path ./src这样的命令时它必须能安静地把结果打印出来、返回正确的退出码方便我把它嵌进 CI 流水线或者 shell 脚本里。CLI 的天性是“合作用户”——它要和 grep、jq、git 等其他命令行工具配合所以它的输出必须稳定不能混入 ANSI 杂色字符破坏管道。很多 AI 编程工具做 CLI 时候的败笔就在这终端里跑得挺好看一旦| jq就整个崩了。Web 端解决的则是“低门槛访问”和“远程临时操作”。你在一台没有装任何工具的电脑上打开浏览器输入http://127.0.0.1:7939就能看到正在运行的 Harness 任务状态。Web 端的另一个价值在于“视图层天然跨平台”——手机、平板、同事的电脑只要有浏览器就能看不需要为每个平台单独适配。我实际使用中经常用 Web 端来观察多智能体的执行日志因为它能结构化地呈现任务树、调用链、token 消耗这些东西在终端里堆文本是看不清楚的。桌面端的价值在于“常驻体验”。托盘图标、全局快捷键、开机自启、系统通知——这些只有桌面应用能给。我可以设定Cmd/Ctrl Shift H随时唤起 Harness 主窗口任务跑完弹系统通知后台进程一直挂着等我的指令不用每次都在终端重新启动。桌面端本质上是一个“最重的壳”但它换来的是随时随地、零等待的交互体验。三端的用户心智模型完全不同CLI 是给“操作者”用的Web 是给“观察者”用的桌面端是给“常住居民”用的。设计多端架构的前提是承认这三种心智模型会同时存在而它们之间要共享同一份会话数据和任务状态。2.2 为什么不能三端各写一套一开始可能觉得架构很简单CLI 一个代码库、Web 一个代码库、桌面端一个代码库三个项目各做各的最后拼起来。这种做法在短期确实能快速交付但项目只要活过三个月就一定会出问题——三端功能不同步、插件在某一端失效、会话状态在 CLI 里改了 Web 端看不到。更致命的是 DeepSeek Harness 依赖插件生态插件作者不可能为三种端各写一套加载逻辑也没这个义务。所以多端架构的核心判断是核心逻辑必须下沉为一个共享层三端只做“薄壳”。任务编排、技能加载、模型调用、插件管理、会话恢复——这些都是核心逻辑必须只写一次。CLI、Web、桌面端做的事情其实非常少它们只负责“从用户那边拿到输入”和“把核心层产生的输出展示出来”。打个比方这个架构就像一家餐厅的设计核心逻辑是后厨菜怎么做、火候怎么控都发生在后厨里CLI 是外卖窗口、Web 是店内的开放厨房展示台、桌面端是正式的餐桌。食客用户虽然从三个不同的地方取餐但吃进嘴里的菜是同一个锅炒出来的。这个“单一厨房多个窗口”的设计哲学就是 DeepSeek Harness 多端架构能站稳的关键。2.3 判定一套多端架构好坏的三条标准我拆解过不少号称“全端适配”的项目最后总结出三条硬性标准用来判断一套多端架构到底是不是真的成熟。第一条是“增量状态是否一致”。在 CLI 里启动了一个任务Web 端和桌面端能否马上看到它在跑任务跑到一半换一台设备从 Web 端续看能不能直接接上Harness 把会话状态持久化到磁盘上的共享状态文件三端读写的是同一份数据所以天然满足这条。第二条是“插件是否只写一次”。插件作者只需要写一套代码就能同时在 CLI、Web、桌面端被加载。达到这一点架构里必须有稳定的插件接口规范而且这个规范不绑定任何 UI 层。Harness 把插件加载和 UI 渲染彻底解耦插件暴露的是能力和元数据至于在每个端怎么展示由壳层自己决定。第三条是“认证是否一次通过”。三端如果每端都搞一套登录体系那是灾难。Harness 的做法是核心层统一管理访问凭证CLI 首次唤起时完成认证凭证存进共享状态Web 和桌面端从这个共享状态里读取凭证不需要重复认证。这套机制背后的设计原则是——用户只应该在第一个入口验证一次身份其余入口都共享信任关系。这三条标准也是你在设计自己的多端项目时可以直接拿去用的验收清单。3. 架构核心共享状态、统一协议与本地认证的设计思路3.1 一切从“状态文件”开始的信息流设计先说 DeepSeek Harness 多端架构里最底层也是最重要的一件事会话状态是怎么被管理的。Harness 把每一次会话拆成两层数据——会话定义session definition和会话运行态session runtime state两层分开落盘。会话定义描述的是“这个任务是什么”包括任务类型、模型参数、技能清单、智能体编排拓扑会话运行态描述的是“这个任务现在跑到哪了”包括节点状态、中间输出、token 消耗、错误信息。我在实际调试中就遇到过这种情况用 CLI 启动了一个多智能体任务任务跑到一半报错我想去 Web 端看完整的时间线和调用栈。如果没有共享状态文件就只能靠日志系统重新拼上下文。Harness 的设计把运行态结构化地同步写在磁盘上打开 Web 端时直接加载这份状态文件就能完整重建任务现场。设计这个信息流的时候最关键的一个决策是“每一端都是状态的生产者同时也是消费者”。CLI 启动任务时会在状态文件里创建一个运行态节点Web 端观察时读取它桌面端可以在任务出现特定条件时修改它的状态比如标记“待人工介入”。这种“share by diskwrite by lock”的方案虽然看起来笨但胜在实现简单、行为可预测——多端同时打开时谁也没法在内存里偷偷改一份别人看不见的数据。一切的根源都在磁盘上那一份唯一的真相。3.2 统一协议让三端说同一种语言状态文件解决的是“数据在哪”的问题而三端要和核心层通信还需要“协议一致”。DeepSeek Harness 的协议设计可以总结成一句话无论 CLI 还是 WebSocket载荷都走同一个 JSON Schema。CLI 端执行dsh run时命令行的参数会被转换成一个结构化的任务请求对象这个对象与 Web 端创建的、桌面端创建的完全同构。也就是说三端产生的不是“三泡不同的数据格式”而是“同一份 JSON 结构的不同来源”。这样做的好处极其明显——任何一端实现的新功能另外两端立刻可以复用同一套数据契约不需要做格式转换。协议层还包含一个很实用的设计请求 ID 关联。每一次任务请求都会携带请求 ID这个 ID 会被写入状态文件的每个运行节点上。排查问题时你只要打开状态文件搜索请求 ID就能把一次操作的完整链路从触发到结束梳理出来。在实际排障时帮我省了特别多时间。错误信息也统一封装不会出现 CLI 报中文、Web 报英文这种扯淡情况。3.3 本地认证为什么 web 端提示“authentication required”热词里有一个特别典型的报错dsh web authentication required; reopen the url printed by dsh web.意思是“Web 端认证必须重新打开dsh web打印出来的那个 URL”。这背后的设计逻辑要从 Harness 的本地安全模型说起。Harness 的 Web 端本质是一个本地 HTTP 服务。启动时会监听127.0.0.1的一个随机可用端口并在终端打印出完整访问地址。这个地址里内置了一个单次有效的 token例如http://127.0.0.1:47935/?tokenxk2f9a...。因为服务绑定的是回环地址所以按常规理解只有本机能访问到它。但事情没那么简单——如果浏览器里跑着恶意的网页 JS它照样可以发动跨站请求打到127.0.0.1上。为了防这种 DNS rebinding 和 CSRF 风险dsh web必须校验请求头里的 token。如果你打开的是旧的、过期的、或者 token 不匹配的 URL服务端就直接回一句“authentication required”这就是那个报错最常见的来源。所以这个设计在实操上的含义是每次启动dsh web记得重新用终端打印出来的新 URL 去访问不要用浏览器历史记录里的旧地址。这个 token 是一次性且有时效的用完即焚到期作废。整个认证链路的核心目标是“做一个足够强的门把除本机以外的流量全部挡在外面”。这也提醒了所有做本地工具的人本地服务并不是天然安全你仍然需要给回环地址加一把锁Token 就是这把锁的钥匙。3.4 锁与并发三端同时操作时谁说了算多端架构一定会遇到一个问题如果 CLI 和 Web 同时触发一个写操作谁来保证状态文件不会写坏这个问题在 Harness 的设计里是通过“单写者锁”解决的。所有对状态文件的写操作都必须先获取一个文件锁。拿到锁的端可以写入拿不到的端需要在内存里排队等待。这个设计很符合“只能有一个厨房主厨”的原则——多端可以同时往系统里提交请求但真正落盘的状态更新必须串行化。我之前用过一个工具它允许同时从 Web 端和 CLI 端操作同一个任务结果状态文件经常被写成交错损坏的 JSON。Harness 的做法虽然让并发吞吐略降但换来了极强的稳定性。作为使用方这里有个实操技巧如果你是重度用户建议把“三端的操作角色”做一点区分——桌面端作为主要操作入口CLI 作为脚本化执行的通道Web 端专注于查看状态和日志。这样不仅能减少锁竞争的概率还能让你的工作流变得更有秩序。4. 三端怎么落地CLI、Web、桌面端的实现差异4.1 CLI 端Unicode、管道、退出码都要规范CLI 端作为被脚本调用最多的入口细节设计必须非常较真。第一个值得关注的点是输出规范。默认情况下 CLI 输出人类可读的文本但必须支持一个--json标志在脚本场景下输出结构化 JSON。JSON 的每个字段在文档里有严格定义字段顺序固定这能保证用jq解析时永远不出歧义。第二个关键点是退出码。CLI 在任务成功时必须返回0失败时返回非零值并且“用户中断”也要有独立码值比如130。很多脚本自动化都依赖退出码来判定任务成败一旦工具不管成功失败都返回 0流水线逻辑会瞬间失控。我见过太多工具在这方面疏忽真的很要命。第三个细节是 TTY 检测。当 CLI 运行在管道场景比如dsh run --skill daily-report | tee report.txt它必须自动关闭一切进度动画、旋转图标、颜色字符因为那些控制字符会污染管道里的数据流。反过来在交互式终端里跑任务时进度动画和实时日志流又能大幅提升体验。这个“有 TTY 时华丽、无 TTY 时朴素”的切换是 CLI 端区别于普通 Web 界面的核心素养。CLI 端的命令集我还想多说一句Harness 的命令设计是模块化的比如dsh run负责任务执行、dsh skill负责技能包管理、dsh plugin负责插件管理、dsh web负责启动 Web 服务。这种子命令组合式的设计沿用的是现代 CLI 工具的标准范式好处是每个命令的职责单一互不干扰也方便以后做 shell 补全。4.2 Web 端本地服务、WebSocket 和异步任务流Web 端做的事情比表面看起来更多它不只是“把页面弹出来”而是同时扮演了三个角色HTTP 服务、静态资源服务器、WebSocket 网关。dsh web启动后后端先要绑定一个随机端口并打印访问 URL。然后它同时开始监听两件事HTTP 请求用来访问页面和 REST 接口WebSocket 连接用来推送实时任务进度。任务执行是异步的所以 Web 前端通过 WebSocket 订阅状态变更事件后端把核心层跑出的进度流不断推送给浏览器。你看到 Web 端时页面上的任务列表、日志流、token 消耗数都是从 WebSocket 推送过来的增量数据而不是靠轮询刷出来的。这个设计保证了页面的实时性也避免了频繁轮询给本地服务造成没必要的压力。Web 端的插件加载在web boot阶段完成。你如果在启动日志里看到failed to load plugins web boot: 2 entries did not activate这行字不要慌它大概率只是说某个插件只声明了 CLI 入口没有声明web入口所以 Web 端在启动时就把这些插件条目主动忽略掉了。这不是“坏”恰恰说明架构里有一套“按端加载插件”的机制每个插件可以按需暴露出现在哪一端。想排查时可以到插件目录里看这个插件的 manifest检查entrypoints字段下有没有声明web入口。4.3 桌面端本质上是一个“带 GUI 的 Web 壳”桌面端最容易让人误以为它是一个独立的重型应用其实它和 Web 端是同一套血脉。做一个成熟的桌面端方案社区里通常有两种路线走 Electron 或者走 Tauri但两者都涉及系统 WebView 与 Node 运行时的深度联动。从 Harness 这种以 Node 生态为核心的插件架构看第一代桌面壳很自然地选择了 WebView 方案把dsh web提供的服务直接内嵌到一个原生窗口里前台窗口渲染页面后台进程承担服务逻辑。这个设计最大的赢面是“UI 只写一遍”。Web 端能用的页面桌面端直接复用Web 端新加的组件或状态展示桌面端第二天就好。桌面端真正的额外价值在于调用系统能力系统通知、全局快捷键、任务栏菜单栏图标、开机自启。这些能力由桌面壳注册到系统里然后把触发事件转换成标准请求发给本地服务由核心层统一处理。桌面端还要处理一个“单实例”问题。如果你把桌面端当作主入口就应该禁止启动两个桌面进程否则两个进程同时去抢同一个状态文件锁大概率会出问题。Harness 桌面端在这块会在启动阶段检查单实例锁重复启动时直接激活已有窗口而不是新开进程。这一点设计虽然在工程上不难但对于日常体验影响很大——试想一下你明明只点了一次图标却发现自己开了五个桌面窗口在抢同一个任务那体验真的很难受。总结一下三端实质CLI 是透明的文本管道Web 是本地的实时视图桌面端是常驻的操作门户。三者共享同一个核心只是站在不同角度和用户交互。5. 部署实操记录安装、插件配置、skill 与多智能体编排5.1 安装与目录规划能不能装到 D 盘在 Windows 上安装 DeepSeek Harness很多用户会问“能不能装到 D 盘”。答案是可以而且推荐这么做。这个工具的数据目录默认位于用户主目录下但你可以通过环境变量DSH_HOME指定到其他位置。我实际测试下来把DSH_HOMED:\tools\dsh加上之后所有配置、插件、会话状态文件都会落到 D 盘C 盘完全不占地。安装过程中最常见的失败原因有三个。第一个是 Node.js 版本过低Harness 依赖较新的运行时特性如果版本不满足会直接报一个奇怪的模块加载错误。第二个是网络环境导致包下载缓慢或超时此时把 npm 镜像源切到本地可信的镜像能大幅提升成功率。第三个是权限问题不要在C:\Program Files等需要管理员权限的目录下初始化数据目录选一个有完全读写权限的普通文件夹就好。装完以后打开终端执行dsh --version如果能看到版本号就说明基础环境没问题。接下来我建议先跑一个最小任务dsh run --skill ping hello harness验证端到端链路能通再去扩展插件和技能包。踩过坑的人都知道环境验证要一次一次来不要一次性堆几十个配置出了问题很难定位。5.2 插件系统激活失败到底在查什么热词里有一个很甜但很典型的报错——failed to load plugins web boot: 2 entries did not activate。很多人第一次看到会以为插件装坏了其实不完全是这样。Harness 的插件体系里有两个概念一个是“插件已安装”另一个是“插件已激活”。已安装只代表插件文件存在于插件目录中已激活则要求插件完成了注册、校验和入口加载且被当前端的启动场景接受。用来排查的思路很简单先看插件目录下每个插件的 manifest 文件确认entrypoints字段里定义了哪些入口。如果这个插件只写了cli入口那 Web 端启动时“跳过”它是合理的不应该视为故障。如果你确定某个插件应该在 Web 端生效但仍没激活那就要检查它的依赖是否齐全——不少插件构建后依赖共享库如果共享库没装上插件加载时会静默失败只在启动日志里留一行警告。给新手朋友的实操建议是启动时看到did not activate先不要急着删除插件先对照 manifest 看看它自己声明了哪些入口。我调试过的绝大多数“激活失败”最后原因都是“这个插件本来就不支持当前端”而不是代码坏掉了。5.3 skill 的本质与快速配置方法skill 是 Harness 里非常重要的一层抽象它把“完成某一类任务的步骤”封装成一个可复用的技能包。简单来说一个 skill 本质上就是一个带结构化元信息的 Markdown 文件文件头部的 frontmatter 描述技能的名称、描述、适用模型、参数正文内容描述具体的执行步骤和决策逻辑。在 Harness 里添加一个 skill 的操作很简单直接把 Markdown 文件丢进$DSH_HOME/skills目录或者用dsh skill add ./my-skill.md命令来导入。导入之后你就能在任务编排里像调用函数一样使用它。我之前自己写过一个“日报生成”的 skill把几个固定的数据分析步骤和输出模板写进去之后每天只需执行一条命令就能出完整日报。这个习惯强烈推荐因为你写过的 skill 会沉淀成你自己的可复用资产而不是每次都从零开始写提示词。5.4 多智能体编排从单 Agent 到任务拓扑刚才说的 skill 是“单兵作战”的工具而 Harness 真正强大的地方在于“多智能体编排”。热词里频繁出现“多个智能体 编排”说明很多人都关注这个能力。它的思路不是让多个 AI 模型“各聊各的”而是把一个复杂任务拆解成子任务拓扑每个子任务由一个智能体负责智能体之间通过明确的数据接口传递结果。我这边用过的比较典型的场景是“代码审查流水线”定义一个 orchestrator 智能体负责任务拆分和进度管理一个 reviewer 智能体做静态代码分析一个 executor 智能体按审查意见执行修复。三个智能体的工作产物以结构化 JSON 写到状态文件里从 Web 端可以完整看到每个节点的执行状况。这种编排模式在 CLI、Web、桌面端都是同一套配置核心层按拓扑调度壳层只负责呈现。配置方式上Harness 的编排描述文件一般是一个 YAML 文件里面定义节点类型、依赖关系、模型参数、技能绑定。我通常把编排文件放在项目的.harness目录下然后执行dsh run --flow .harness/review-flow.yaml来启动整条流水线。第一次编排建议从小规模开始比如先两个智能体一个“生成”、一个“校验”摸清楚执行顺序和状态传递的规律再逐步扩大节点数。盲目堆太多智能体会导致任务拓扑图非常混乱排查问题也会变得困难。6. 常见问题速查表与避坑心得6.1 按报错排查一张表覆盖高频问题把我在实测和社区里见到的高频问题整理成一张速查表方便直接对照报错/现象根因排查/解决思路dsh web authentication required; reopen the url printed by dsh web访问了旧的、过期的 URLtoken 不匹配或已失效重新执行dsh web复制终端里最新打印的 URL不要用浏览器历史记录里保存的旧地址failed to load plugins web boot: 2 entries did not activate插件的 manifest 没有声明web入口或缺失依赖打开插件目录查看该插件 manifest 的entrypoints字段确认依赖是否完整unable to locate the codex cli binary or required runtime components环境约束导致部分运行时组件未能被识别检查运行时组件的安装是否完整确认 PATH 或环境变量指向正确的二进制路径Windows 上无法安装Node 版本不满足、网络源慢或权限不足升级 Node 到支持版本切换可信 npm 镜像源把数据目录移到普通可写文件夹桌面端反复启动多个窗口未启用或误触发了单实例锁确认桌面端配置里已开启单实例模式重复启动时应唤出已有窗口而非新建进程CLI 输出在管道里出现乱码日志流的 ANSI 颜色字符污染了管道确认在非 TTY 场景下 CLI 自动降级为纯文本输出使用--json时检查输出是否严格为结构化 JSON6.2 排障时的通用思路从状态文件入手如果你遇到的是表中没有覆盖的玄学问题我强烈建议你先打开DSH_HOME下的状态文件看看。Harness 的特点是“一切状态皆落盘”所以绝大多数异常都会在状态文件里留下痕迹。打开 JSON 看最近一次运行节点检查错误信息字段、时间戳。很多“偶发失灵”其实都是上一次任务异常退出后没有正确清理运行态导致的把锁文件和运行态排除后问题往往就消失了。实际操作上我遇到 Web 端白屏但 CLI 正常的时候处理方法很简单先确认服务进程在跑再确认 WebSocket 连接建立成功。如果进程正常但页面空白打开浏览器开发者工具看 Console里面一般会告诉你某个 API 请求被拒绝或者 WebSocket 握手失败。所有 UI 类的疑案最后基本都能通过“看网络请求面板”解决。6.3 我踩过的三个坑与提醒第一个坑是“CLI 里配置的环境变量 Web 端没继承”。dsh run在终端里跑的时候它能读到终端环境变量但dsh web或以桌面端启动的服务进程可能继承的是系统级环境变量而非终端级变量。所以如果你在.zshrc里设置了DSH_HOME或模型 API Key桌面端启动时可能读不到导致桌面端的任务一直鉴权失败。解决办法是把重要变量写进 Harness 自己的配置文件而不是只依赖 shell 环境变量。第二个坑是“插件版本与核心版本不匹配”。插件在旧版本核心上运行良好升级核心后某个插件开始报did not activate这通常是插件用到了新版核心才有的 API 而旧版本里没有。所以升级核心之后记得顺手把插件也升级一遍保持核心端与插件端的版本矩阵在同一个时代。第三个坑是“多端同时长时间运行导致的状态文件膨胀”。如果你把 Harness 当常驻进程一直挂着session 状态文件会越写越大。我后来养成了定期清理历史运行态的习惯把超过两周的 session 归档出来只保留最近活跃的任务状态。这个习惯帮我避免了非常多的磁盘空间浪费和启动变慢的问题。7. 写在最后关于多端架构的一些个人体会做了这么多工具的架构拆解我用 DeepSeek Harness 这段时间最大的感受是真正好的多端架构不会让你感觉到“哪个端更好用”而是让你忘记端的存在。CLI 的时候你专注写命令Web 的时候你专注看状态桌面端的时候你聚焦在随时触达。设计的最高境界是让交互方式自然融入使用场景而不是让用户为了用某个功能去学一套新操作。最后再分享一个小技巧。我现在的日常是把桌面端当作主入口常驻设好全局快捷键任何想法都可以一秒钟唤起窗口输入任务CLI 作为脚本化入口批量任务、定时任务、流水线集成全走终端Web 端主要是远程临时查看和给同事展示任务进展。三端各司其职状态文件永远不会打架操作效率也是最高的。这个“桌面端主操作、CLI 主脚本、Web 主观察”的分工模式你可以直接拿去试实测下来相当稳定。