插件加载后找不到工具、模型凭据散落在仓库、Web UI 构建完成却无法调用远程接口——这些问题通常不是代码量不够，而是插件边界选错了。

最快解法：先按工具、模型提供方、界面、工作流 4 类目标确定插件类型，再从单一能力的最小插件开始。 截至 2026 年 8 月 18 日，DeepSeek Harness 仍处于开发者预览阶段，官方明确提示会出现破坏兼容性的变更，因此配置、权限和兼容性测试必须和功能代码分开交付。参考官方仓库说明。

本文适合把内部脚本封装成 DeepSeek Harness 工具的 AI Agent 工程师、需要接入自定义模型端点或团队网关的平台开发者，以及负责统一远程开发环境和插件验收流程的技术负责人。

最后更新于 2026 年 8 月 18 日，数据核实自官方仓库 README、架构文档、开发指南、CONTRIBUTING.md 与 package.json。 master 分支后续若调整插件 API、Node.js 支持范围或文档路径，应重新复核本文命令。

01

本周插件开发安排

如果你本周要启动一个插件项目，建议按下面的时间表推进：

  • 第 1 天： 写清插件只解决一个扩展目标，并列出输入、输出、权限和失败方式。
  • 第 2 天： 建立最小 TypeScript 包，先验证加载、发现和卸载。
  • 第 3 天： 把配置、API Key、端点和模型目录移出代码仓库。
  • 第 4 天： 在目标 profile 中验证工具调用、远程接口或浏览器资源。
  • 第 5 天： 在干净环境执行安装、构建、最小运行和回退测试。

本周最值得先做的动作不是搭建完整套件，而是选一个可以在单次运行中证明价值的插件。例如，把“查询内部发布状态”做成一个工具插件，而不是一开始同时实现工具、Web 页面、模型路由和自动化编排。

官方架构把 DeepSeek Harness 定义为“一切皆插件”，底层由 Cordis 驱动。模型适配器、工具注册、会话记录和 agent loop 都属于可替换的插件层，而不是必须修改核心代码的固定模块。参考官方架构文档中的 Cordis 与插件说明。

02

四类扩展目标

你可以用“扩展对象是谁”来判断插件边界。

工具调用插件

适合把内部脚本、文件查询、构建任务、数据读取或受控命令封装成一个可调用能力。

这类插件的核心不是界面，而是工具契约：

  • 工具名称和用途稳定。
  • 输入字段有明确类型。
  • 输出结构可被模型继续处理。
  • 权限范围能够单独确认。
  • 失败时返回错误类型、原因和建议动作。

场景案例： 你有一个查询 CI 任务状态的脚本。最适合的第一版是一个工具插件，只接受任务标识，返回状态、最近日志摘要和失败链接。不要同时加入 Web 面板和自动重试，否则一旦加载失败，你很难判断是工具注册、远程请求还是浏览器构建出了问题。

成功信号：

  1. profile 启动时插件没有加载错误。
  2. 工具名称能出现在工具目录或模型可见的工具模式中。
  3. 传入合法参数后返回结构化结果。
  4. 传入非法参数时返回可诊断错误，而不是空字符串或未处理异常。

回退方式： 保留原始脚本命令作为独立入口。插件不可用时，先从 profile 中移除该插件，再用脚本完成任务。这样不会因为插件试验影响主流程。

模型提供方插件

模型插件的职责不同。它负责适配模型请求、流式响应、模型名称、端点和错误映射，不应该把业务工具逻辑塞进同一个包。

官方架构把模型适配器放在可组合的插件树中。你的实现应该重点确认：

  • API Key 是否来自环境变量或被忽略的本地配置。
  • 自定义 Base URL 是否支持空值回退。
  • 模型目录是否由配置管理。
  • 超时、限流和上游错误能否被区分。
  • 没有凭据时是否能在启动阶段给出明确提示。

官方开发指南给出了 DEEPSEEK_API_KEY 和可选 DEEPSEEK_BASE_URL 的环境变量方式，并明确要求不要提交真实凭据。没有 API Key 时，部分真实 API 的端到端测试会自动跳过。参考官方环境变量与凭据说明。

✅ 适合单独拆分： 团队网关适配、模型目录管理、请求重试策略。
❌ 不建议混在一起： 工具注册、页面状态、工作流 profile 和模型凭据。

界面功能插件

涉及 Web UI 时，你需要关注 Host 与 Client 的边界。官方开发指南显示，DeepSeek Harness 使用独立的 Host 与 Client TypeScript 聚合项目；普通 Client 插件会在 Client 构建阶段生成 Node loader 和浏览器资源，远程接口则存在单独的 Host 与 Client 关联。

这意味着界面插件不能只看“页面能不能打开”，还要检查：

  • Host 侧服务是否完成类型检查。
  • Client 侧资源是否能正常打包。
  • 浏览器调用的远程接口是否有对应契约。
  • 服务端错误是否能传递到界面。
  • 直接刷新页面后状态是否仍然正确。

官方构建顺序是先构建 Host，再生成 Client 所需的远程契约，之后构建 Client，最后构建 Web。开发指南列出的核心顺序为：

tsc -b tsconfig.host.json
tsdown --env.DSH_BUILD_FACE host
tsc -b tsconfig.client.json
tsdown --env.DSH_BUILD_FACE client
pnpm run build:web

不要把这个顺序改成“先打包页面，再补服务端类型”。这样做可能在本地出现半成品资源，但在干净环境或 CI 中暴露远程契约缺失问题。参考官方 Host 与 Client 构建说明。

工作流编排插件

当需求包含多个工具、模型提供方、权限和自动任务时，优先考虑 profile 组合，而不是复制一份完整工程。

官方架构中，profile 是保存在 Harness home 中的命名组合，负责堆叠 bundle、安装外部插件并保存自己的 cordis.patch.yml。bundle 则是 Cordis 配置行和对应代码的分发格式。配置层按顺序叠加，后面的 patch 可以替换已有配置或插入新组件。参考官方 profile、bundle 与配置覆盖层说明。

团队可以保留三类 profile：

  • 试验 profile： 只放正在开发的插件，允许快速替换。
  • 测试 profile： 固定模型、工具和权限，供验收复现。
  • 持续任务 profile： 只保留稳定插件，禁止直接修改全局配置。

这样做的优点是插件可以独立启停，问题定位更快。缺点是你必须记录 profile 使用的 bundle 顺序、配置覆盖层和插件版本，否则“同一个插件在不同人机器上表现不同”仍会发生。

03

dsh-plugin 最小目录结构

对于 dsh-plugin，不要把社区项目的目录习惯误认为官方永久 API。官方仓库目前只确认插件生态可通过 GitHub 的 dsh-plugin topic 进行发现，并提示开发者预览期存在兼容性变化。参考官方贡献指南。

在不绑定具体内部 API 的前提下，你可以先采用下面这个最小可验证结构：

my-dsh-plugin/
├── package.json
├── README.md
├── src/
│   ├── index.ts
│   └── errors.ts
├── test/
│   └── smoke.test.ts
├── tsconfig.json
└── .gitignore

其中：

  • package.json：声明包身份、运行入口和当前版本。
  • src/index.ts：保持单一注册入口，负责挂载工具、模型适配或服务。
  • src/errors.ts：统一可诊断错误，避免每个函数随意拼接字符串。
  • test/smoke.test.ts：只验证加载、发现、成功调用和失败返回。
  • README.md：写清所需环境变量、权限、profile 安装方式和已验证提交。
  • .gitignore：至少排除本地环境文件、凭据和构建产物。

插件刚开始时，目录越小越好。不要为了“未来可能需要”提前加入 Web、数据库、后台任务和多模型路由。

04

工具契约与加载信号

工具插件的最小成功标准可以压缩成三层。

第一层是可加载。启动 profile 时，插件入口能够被解析，缺少依赖或配置错误时能指出具体包名和字段。

第二层是可发现。工具注册后，工具目录、模型工具 schema 或调试输出中能看到名称、描述和输入字段。

第三层是可诊断执行。成功时返回稳定结构；失败时区分参数错误、权限拒绝、网络失败和上游服务错误。

建议你为每个工具写一份简短契约：

工具名：ci_status
输入：project、job、ref
成功输出：status、summary、updated_at
失败输出：error_code、message、retryable
权限：只读任务状态
回退：执行原始查询脚本

这里的 updated_at 只是字段示例，不代表官方工具 API。真正接入时，应以当前 master 分支的类型定义和插件文档为准。

⚠️ 经验提醒： “插件能启动”不等于“插件可用”。如果工具没有出现在模型可见的 schema 中，模型不会主动调用它；如果错误只有“failed”，你也无法判断是权限、参数还是网络问题。

05

Profile 组合与配置覆盖

把插件放入指定 profile 时，关键不在复制工程，而在 profile 的组合层。

你需要按下面步骤操作：

  1. 先确定目标 profile。 试验插件放入单独的试验 profile，稳定工具不要直接写入团队共用 profile。
  2. 确认插件的 bundle 或配置声明。 官方架构要求 bundle 和 profile 通过各自 package.json 的 dsh 字段参与组合，具体字段以当前仓库为准。
  3. 安装或挂载插件后查看实际配置树。 官方提供了以下验证命令：
dsh --profile web --dump-config
  1. 检查插件是否出现在正确层级。 如果配置被后续 patch 覆盖，不能只看插件是否安装，还要检查最终生效的配置行。
  2. 执行最小调用并记录 profile 名称。 测试记录至少包含 profile、插件提交、包版本、Node.js 版本和复核日期。
  3. 无法加载时回退到上一个 profile。 不要在同一个全局配置文件中连续修改多个插件，否则回退点无法确定。

官方文档确认，配置层会按照 profile 中 bundle 的顺序、profile 自身 patch、home 层 patch 和命令行 overlay 依次应用。这个机制适合做试验、测试和持续任务的隔离，但也意味着同一插件在不同 profile 中可能得到不同配置。

06

中部决策：单插件还是插件套件

你可以按下面的条件分支选择结构：

  • 若需求只有一个可调用能力，且输入输出可以独立定义，则选单一工具插件。
  • 若需求需要不同权限，例如只读查询和写入操作，则拆成多个可独立启停的插件。
  • 若需求同时涉及模型请求和业务工具，则模型提供方插件与工具插件分开。
  • 若需求需要浏览器页面、Host 服务和远程接口，则选界面插件结构，并单独验证 Host、Client 和 Web 构建。
  • 若需求需要多个插件共同组成运行模式，则选 profile 加 bundle，而不是复制一套代码。
  • 若插件仍处于探索阶段，且官方 API 尚未稳定，则先保留脚本回退入口，不要把它作为持续任务的唯一依赖。
  • 若多人需要同时试验不同配置，则每个人使用独立 profile；否则回退到共享测试 profile，并冻结配置文件。

这组判断的核心是降低故障半径。一个插件只承担一个扩展目标，发生破坏性变更时，其他工具、模型和界面不会一起失效。

07

开发环境与构建基线

官方开发指南目前要求 Node.js 支持 22.19+ 或 24+，CI 覆盖 Node.js 22.19、24 和 26；仓库固定使用 pnpm@11.7.0。这些不是你可以随意替换的“参考版本”，而是发布前应记录的环境基线。参考官方开发环境要求与官方 package.json。

从源码建立检查环境时，采用官方已验证流程：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run typecheck

官方 README 还给出了完整构建和启动方式：

pnpm run build
pnpm dsh web

Web UI 默认监听 http://127.0.0.1:3080。如果你是从源码运行，不要用自己习惯的脚本名称替换官方命令；预览期脚本可能随仓库变动，发布记录必须保留核验时的提交和包版本。

08

发布前验收清单

插件发布前，至少完成下面 6 项检查：

  1. 类型检查： 运行 pnpm run typecheck，确认 Host 与 Client 聚合项目都能通过。
  2. 构建检查： 涉及构建产物时运行 pnpm run build，不要只依赖编辑器没有报错。
  3. 最小运行： 在目标 profile 启动一次，确认插件加载且工具或模型能力可发现。
  4. 权限检查： 分别验证允许、拒绝和缺少权限的情况。
  5. 干净安装： 删除构建产物和本地缓存后重新安装，确认没有依赖开发机残留。
  6. 卸载回退： 移除插件后，原 profile 能否恢复启动，原始脚本或备用模型路径是否仍可使用。

如果插件包含 Web UI，还要加入浏览器刷新、远程接口失败、服务端重启和旧配置读取测试。官方 package.json 当前包含 typecheck、build、test、test:e2e、test:web、test:web:built 等脚本，但具体使用哪个脚本，应根据你改动的 Host、Client、Web 或远程接口范围选择，不能把全部命令机械地当作插件发布标准。

建议在 README 顶部记录：

验证提交：<commit>
包版本：<version>
Node.js：<version>
pnpm：<version>
目标 profile：<profile>
复核日期：2026-08-18
已知不兼容：<change>

这份记录在开发者预览期尤其重要。官方已明确项目会快速迭代，并可能出现破坏兼容性的变更。你需要把“当前能运行”变成“在哪个版本、哪个 profile、什么配置下验证过”。

09

远程 Mac 交付建议

如果你只是偶尔验证一个工具插件，本地 Mac、容器或临时虚拟机都可以。长期持续开发则要看三个条件：构建频率、测试频率和协作人数。

当前方案常见的真实缺点是：本地机器环境容易被个人配置污染；多人协作时 Node.js、pnpm 和 profile 不一致；临时云主机对 Web UI、浏览器资源和 macOS 相关验证不够稳定；开发者预览出现破坏性变更后，回退环境往往没有被完整保留。

如果你需要一台可长期保留、可随时远程接入的 Mac，且主要任务是 TypeScript 构建、插件测试、Web UI 验收和团队共享，那么可以先查看 VpsMesh 的 Mac 远程开发方案，再根据使用周期和协作人数选择配置。短期试验适合按需租赁；长期高强度持续构建、需要物理接口或必须完全控制硬件的团队，则应认真比较自购 Mac 与租赁的总运维成本。

完成最小插件后再决定是否租赁，通常比一开始购买固定设备更稳妥：你已经知道构建耗时、测试频率、profile 数量和团队并发，也更容易判断远程 Mac 是否真正解决了你的交付问题。需要具体查看周期与方案时，可参考 Mac 租赁价格与周期说明。