DeepSeek Harness 实战手册：一切皆插件到底怎么玩？

DeepSeek Harness 是一个用于构建、运行和扩展 Agent 的开源运行环境。

它不提供模型能力本身——模型层同样是一个可替换的插件——而是解决模型之上的问题：怎么让一个大模型变成一个能干活的 Agent。

DSH 的设计理念用一句话概括：Everything is a Plugin。

系统内几乎所有能力——工具调用、权限管控、UI 呈现，甚至插件管理本身——都以插件形式存在。可以安装、可以卸载、可以替换。这种架构意味着 DSH 的内核非常薄，只负责调度和消息路由，所有业务能力都由插件层提供。

这是一个容易混淆的概念。

Skill 是面向模型的指令与资源包。它通过结构化的指令告诉模型"你应该扮演什么角色、按什么步骤工作、参考哪些资料"，本质上是在模型已有能力的基础上提供更精准的引导，但不会为系统引入新的可执行能力。

插件是可加载的程序模块。它直接为系统注入新能力：一个新的工具调用、一个新的 UI 面板、一个新的数据源接入点，甚至可以提供服务或修改系统行为。装上翻译插件，Agent 就真的能调翻译服务 API 进行专业翻译，而不只是用模型内置的翻译能力凑合。

两者的定位不同：Skill 优化模型的行为方式，插件扩展系统的能力边界。

DSH 周围已经形成了活跃的插件生态。

社区项目 SkillHub 是目前使用较多的第三方插件市场，开发者可以按场景分类浏览社区已发布的插件，一键安装到自己的实例中，也可以上传自己开发的插件与社区共享。

这套社区共建机制让 DSH 从单机工具变成了一个有生态的平台。大部分常用能力不需要自己开发，社区已经有现成方案。

部署完 DSH 之后，直接开始聊天当然可以，但体验会差不少。这里挑三个最有用的、"装完马上有感"的插件展开讲。

没有视觉插件的 DSH 处于"盲人模式"。你在对话框里贴一张截图，Agent 只能回复"我无法处理图片"。这对于日常工作中大量涉及视觉信息的场景是个硬伤。

装上视觉插件后，Agent 获得了图像理解能力。几个典型用法：把一张 UI 设计稿截图丢进去，Agent 可以分析布局结构并生成对应的前端代码骨架；把一份纸质文档的照片发过去，Agent 能识别文字并提取关键信息整理成表格；把一个报错截图发过去，Agent 能直接读懂报错内容给出排查建议。

对于产品经理、设计师、运营人员这类高频处理视觉素材的角色来说，这个插件基本上是第一优先级要装的。

当你让 Agent 去访问一个需要登录的网页——比如查看某个后台数据面板、抓取特定管理系统的信息——没有 Auth 插件时，Agent 发出请求后直接被登录页拦住，任务中断。

Auth 插件提供了登录态管理能力。配置好认证信息后，Agent 在执行涉及身份验证的操作时可以自动通过认证流程。这在需要 Agent 跨系统操作的场景中几乎是必备项：自动化后台报表拉取、定时抓取竞品公开页面数据、批量操作管理后台。

大模型调用按 Token 计费，但如果没有可视化的消耗数据，用户很容易失去对成本的感知。尤其是在处理长文档、大段代码分析这类高消耗场景时，一次对话可能消耗的 Token 数量远超预期。

Token 统计插件在每次交互后实时展示本轮消耗量和累计用量。更重要的是，它能帮用户建立起"什么操作特别费 Token"的直觉——比如把一个 5000 行的代码文件整体丢进去分析，对比只贴关键的 200 行，消耗差距可能是 10 倍。有了这个反馈循环，用户可以有意识地优化自己的使用方式。

团队协作中一个常见的痛点是：人和 AI 的交互是割裂的。你在这边跟 AI 聊完，再把结论复制到群里跟同事讨论；同事有新想法，又得重新去跟 AI 对一遍。能不能把 AI 直接拉进群聊，让它作为团队的一员实时参与讨论？

这个案例就做了这件事——基于 DSH 搭建了一个多 Agent + 真人协作的在线即时通讯系统。多个 AI 角色和真人在同一个对话流中协作，各司其职，共享上下文。

DSH 使用 .dsh 作为工作目录。在这个目录下可以创建多个 Agent 实例，每个 Agent 是一个独立的子目录，包含一份 YAML 格式的角色配置文件。

配置文件中定义了几个核心维度：

角色身份：这个 Agent 是谁、擅长什么领域、应该用什么语气回复。比如"你是一个关注性能和安全的代码审查专家，回复要具体到代码行，不要泛泛而谈"。

行为约束：什么场景下应该主动发言，什么场景下保持沉默。比如"只在被 @ 或讨论涉及数据库方案时才参与"。

工具权限：这个 Agent 被允许调用哪些工具。信息检索 Agent 只有搜索权限，不能执行代码；技术评审 Agent 可以运行静态分析工具，但不能修改源文件。

插件装配：不同 Agent 可以装载完全不同的插件组合。技术评审装代码分析插件 + 安全扫描插件；产品 Agent 装数据查询插件 + 竞品信息插件。

系统读取 .dsh 下所有 Agent 子目录后自动加载，每个 Agent 作为独立实体参与到群聊中。

多个真人用户通过 Web 界面进入同一个聊天室。@ 某个 Agent 就是向它提问或下达指令；Agent 回复后，其他 Agent 也可以引用这个回复继续补充。真人可以随时插入修正或追问。

所有对话——包括 Agent 之间的交互、工具调用的输入输出——统一记录在 DSH 的会话日志中。这套日志设计支持 fork 操作：在任意一个对话节点"分叉"出一条新的讨论线，类似 Git 的分支概念。

比如讨论到方案 A 和方案 B 的分歧时，可以 fork 出两条线分别深入讨论，最后对比结论再做决策，随时帮你总结群聊消息重点。

多人聊天室只是一个载体，真正验证的能力是 DSH 作为多 Agent 协作基座的可行性。同样的架构可以适配：

• 研发团队内部协作：AI 代码审查、AI 文档生成、AI 测试用例建议，人工做最终决策
• 智能客服：按专业领域拆分多个 Agent（售前咨询、技术支持、售后服务），复杂问题自动升级到人工坐席
• 在线教育：AI 导师负责知识点讲解，AI 助教负责作业批改和答疑，学生与AI及时互动
• 内容协作：AI 写手出初稿，AI 编辑负责风格校对和事实核查，人工终审定稿

前面讲的都是"装现成插件"。如果想自己造轮子，DSH 的插件开发门槛同样不高：注册一个工具 + 对接一个外部 API + 格式化输出，六步就能完成——初始化插件包、注册工具、实现搜索逻辑、本地调试验证、发布上架，通常一个下午就能封装出一个可用插件。

整个开发过程六步完成，无需修改 DSH 任何源文件。

第一步：初始化插件包。 创建一个标准的 Node.js 项目，配好 package.json 和 Cordis 元数据（名称、版本、描述等），在入口文件中导出一个 apply 函数。这是 DSH 识别和加载插件的标准接口。

第二步：理解入口签名。 apply(ctx, config) 接收两个参数——ctx 是 DSH 注入的系统上下文，通过它可以挂载工具和可选服务；config 是插件的配置项，允许用户在安装时自定义行为参数（比如 API 密钥、返回数量上限等）。

第三步：注册工具。 通过 ctx.tools.register(defineTool({ name, description, parameters, execute })) 向系统声明一个新工具。其中 description 是写给模型看的——模型根据这段描述判断何时该调用这个工具，所以表述要清晰准确，比如"根据关键词搜索动漫作品，返回作品名、评分、简介和播放链接"。

第四步：实现搜索逻辑。 在 execute 函数中编写实际业务：聚合多个动漫数据源 API、解析返回数据、将结果格式化为 Agent 能读懂且前端能渲染成卡片的结构。详情页和播放跳转走点击后的 Host API 调用，保持主流程简洁。

第五步：本地调试验证。 使用路径安装方式将插件加载到本地 web profile 中，构建后重启 Harness、刷新页面即可验证效果。开发阶段改动频繁时，这个"改代码 → 构建 → 重启 → 刷新"的循环很快，基本不影响开发节奏。

第六步：发布上架。 将插件代码推送到 GitHub 仓库，SkillHub 会自动同步收录。其他用户在插件市场中搜到后一键安装即可使用，无需手动下载或配置。

整个过程插件代码完全独立于框架代码，后续 DSH 版本升级也不会影响已有插件。这正是微内核 + 插件化架构最直接的好处。

动漫搜索只是一个垂直领域的示例。同样的开发范式——注册工具 + 对接外部 API + 格式化输出——可以在很短时间内适配到任何有数据接口的场景：

学术场景接入 arXiv 或 Semantic Scholar，输入研究方向返回相关论文列表；电商场景接入平台 API，输入商品关键词返回多平台比价结果；法律场景接入法规数据库，输入案由返回相关法条和裁判文书；企业内部场景接入 Wiki 等知识管理系统，让 Agent 具备检索公司内部知识的能力。

一个有明确 API 接口的数据源，搭配上面六个步骤，通常一个下午就能封装为一个可用的 DSH 插件。

DSH 的定位很明确：一个把控制权完全交给开发者的 Agent 运行时。内核薄到几乎只做消息路由，所有业务能力都通过插件注入。

对于想快速搭建专属 AI 助手的个人用户，路径是：部署 → 装几个好用的插件 → 开始使用。对于想构建多 Agent 协作系统的企业团队，路径是：部署 → 设计 Agent 角色分工 → 开发业务插件 → 按需组装。

想上手试试？ 

腾讯轻量云已上线 DeepSeek Harness 应用镜像，推荐 2核4G 配置。选镜像、创实例、填入 API Key，5 分钟进入工作台。部署教程详见往期推文DeepSeek Harness 云端实践：部署、场景案例与插件扩展