DeepSeek Harness 最全实用 Skills / Plugins 教程：从安装到实际使用，一次掌握 AI Agent 常用插件

想从零配置 DeepSeek Harness，或判断现有插件是否真正可用？本文按准备、安装、配置、任务演练和排错展开，说明 Skills 与 Plugins 的区别及兼容性验证方法。

判断：适合想逐步搭起可验证 Agent 工作流的开发者；不适合想直接套用任意社区插件、跳过版本和权限核对的使用者。DeepSeek Harness 官方仓库给出的 Web 启动默认地址是 http://127.0.0.1:3080。先跑通最小流程，再添加扩展，能把安装问题和插件问题分开定位。我们在 2026 年 10 月 26 日核对了项目仓库及官方说明；项目仍标注为开发预览，操作前应再次核对版本和文档。官方仓库的启动与开发预览说明

想从零安装并尝试 Skills / Plugins 的开发者，可按本文步骤完成配置和验证。 已经运行 Harness、但不确定扩展是否生效的 AI Agent 用户，可重点看演练和排错。 需要评估运行环境的团队，可依据权限与验收清单判断部署方式。

开始安装前，先确认项目边界与运行条件

“插件”不是统一的安装格式。DeepSeek Harness（下称 DSH）项目仓库将其描述为基于插件架构的开源 Agent Harness，并明确提醒目前处于开发预览阶段，可能发生兼容性破坏变更。这意味着，照搬旧文章里的扩展名称、配置项或命令，不等于当前版本仍支持。官方安全说明

动手前准备这些信息，避免到中途才发现环境和权限不合适：

• 当前操作系统、终端、Node.js 是否可用；若从源码运行，还要核对仓库对包管理器的要求。
• 准备采用 npm 启动还是源码方式，并记下对应的项目版本或提交。
• 确认模型凭证从哪里取得、由谁管理；不要把密钥写进 Skill、插件配置或公开仓库。
• 明确 Agent 可以读取哪些目录、是否允许写入、执行命令或访问网络。
• 对待评估的扩展，找到其源代码、版本要求、依赖、权限和卸载方式。

运行条件影响的不只是“能不能启动”。不同启动路径依赖不同的安装步骤；插件与主程序版本不匹配会导致加载失败；工作区选错会让本地 Skill 不可见；权限开放过宽则可能把文件和凭证暴露给运行中的工具。官方安全说明特别提示，程序可能执行模型生成的代码和命令，也可能访问运行环境允许它使用的文件、网络、进程和凭证。因此，初次试用应使用低权限、可丢弃的工作区，并先读安全说明。

第一步：先跑通 DeepSeek Harness 的最小流程

官方仓库列出两条启动路径。npm 启动适合先验证 Web 界面；源码启动适合需要检查或修改项目代码的开发者。以下命令来自项目 README，应用范围分别是官方列出的 npm 启动与仓库源码启动，执行前请核对本机环境和当前文档。

npm 启动：

npx @deepseek-ai/dsh web

项目说明要求先安装 Node.js。Web UI 本地启动时默认使用 127.0.0.1:3080；通过 SSH 启动时，终端会打印地址，实际转发地址由 SSH 客户端或编辑器处理。该命令不代表已经完成模型配置或工作区授权。

从源码运行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

源码流程需在检出的项目目录执行。官方说明中，构建步骤用于准备仓库产物；pnpm dsh web 使用已构建的产物启动。不要把源码流程和 npm 快速启动混成一套，也不要在没有确认项目说明时，擅自补一个 Node.js 最低版本。

启动之后，按官方 Web UI 指南完成基础验证：在设置中配置模型和凭证，保存后选择工作区，再建立会话，提交一个只读任务，例如概括当前仓库目录。页面能打开只是第一道检查；还要确认模型可以响应、工作区是预期目录、涉及权限时界面会按当前策略请求批准。官方 Web UI 配置、工作区与任务说明

怎么选：Skill 还是 Plugin？

Skill 与 Plugin 的分工不是“简单版”和“高级版”。官方 Skill 组件文档描述的是由提供者发现指令、由注册表汇总，再由 Agent 或用户按需加载；插件包则能加入运行时能力、服务或界面。一个 Skill 的存在，不代表它能够自行读写文件或调用外部服务；一个 Plugin 已安装，也不代表其中每项能力都已启用。官方 Skill 注册表说明；官方 Plugin 管理说明

评分是按初次配置时的“可控性与核验难度”作的编辑判断，不是项目官方评级，也不表示性能优劣。任务只需要稳定的审查步骤时，先写 Skill；只有任务确实缺少运行时能力、且找得到明确兼容依据时，再考虑 Plugin。

第二步：安装 Skill，并让目录和调用都可验证

官方文件系统 Skill 提供者支持从项目、用户或自定义目录发现本地 Skill。项目级默认根目录包括 .dsh/skills，兼容的用户级根目录则来自 DSH 用户配置目录；具体扫描范围应以正在使用版本的组件文档为准。官方文件系统 Skill 说明

可以在项目 Git 根目录创建一个示例 Skill：

.dsh/skills/repository-review/SKILL.md

文件使用 YAML 前置信息描述名称和触发范围，正文写实际操作规则。例如，审查 Skill 可以要求 Agent 先查看改动文件和调用方、区分确定的问题与建议、引用文件证据，并且在未获授权时不修改文件。这里写的是示例规则，不代表已在你的环境执行或验证。

配置时重点检查：

• 发现位置：项目根目录应是实际 Git 根目录；如果工作区是 monorepo 子目录，别假设 Skill 放在子包目录就一定会被找到。
• 元数据：检查 name、description 等必需字段；描述要说清适用任务，不能只写“有帮助”。
• 可调用范围：官方实现区分模型调用和用户显式调用；相关字段设为禁用后，Skill 可能不会显示在对应入口。
• 目录命名：不要只创建一个嵌套过深的 SKILL.md。文件系统提供者对目录结构有自己的发现规则，需按其说明放置。
• 调用证据：检查会话目录中的 Skill 列表、实际加载的完整内容，以及回答是否遵循规则。

官方 Skill 加载器文档说明：有可调用 Skill 且对应工具可见时，Agent 可以查看目录并加载完整指令；用户也可以通过 /名称 显式调用已允许用户调用的 Skill。目录被发现只是第一项证据，指令是否被遵循仍要从输出核对。官方模型侧 Skill 加载器说明

第三步：Plugin 按官方机制安装，别把社区扩展当内置功能

DSH 的插件体系涉及 profile、bundle 和配置层，不是看到一段网上命令就能直接执行。官方 CLI 参考文档说明，外部插件 bundle 可通过 dsh plugin --profile <配置名> add <软件包或 Git 规格> 安装；该操作经包管理器处理配置目录中的依赖。此处尖括号是占位内容，必须由经过审核、能确认兼容的名称替换，不能原样粘贴运行。官方 CLI 插件管理参考

按这个顺序操作：

1. 确认扩展属于什么。查源代码仓库及其安装说明，判断它是可安装的 bundle、普通依赖，还是仅仅带有相关话题标签的项目。
2. 核对运行版本和依赖。如果仓库未说明支持的 DSH 版本、依赖或安装入口，就把兼容性标为未知，先不装进主要工作环境。
3. 检查代码和权限。查看它能访问的文件、网络、外部服务及凭证范围。官方安全说明建议审查插件和配置，并限制运行权限；沙箱或审批也不能被视为绝对隔离。
4. 只在独立 profile 或隔离环境安装。采用官方文档给出的 profile 安装机制，记录输入的包规格、输出日志和配置改动。
5. 显式启用并检查状态。插件管理页面或 CLI 中的“已安装”不等于每项插件都在运行；按当前 profile 的管理方式检查是否启用、配置是否加载。
6. 验证后再接入真实资料。先用无敏感数据的项目测试；确认能力和权限后，再评估是否扩展到团队工作区。

若使用源码方式，官方发布插件教程要求先理解插件 bundle 和插件包各自承担的作用，并按其说明安装到 profile。未找到相应官方机制或没有可信兼容证据时，不提供猜测性 plugin add 命令。社区仓库只证明作者发布了扩展，不自动证明 DSH 官方支持或当前版本兼容。官方插件打包与安装教程

实际演练：用只读仓库审查确认 Skill 是否有效

以下流程用于验证一个本地审查 Skill，不需要安装第三方 Plugin，也不代表模型输出已经在本站实测。我们把能力边界拆开：Harness 提供会话、工作区和工具调用机制；Skill 提供审查步骤；模型负责生成回答。模型说“已执行 Skill”不能代替文件证据。

输入条件：选择一个可丢弃或只读的测试仓库，准备一个明确改动的文件，并在 Skill 说明中写明“只审查、不修改”。初次测试不要提供生产凭证、客户资料或具有副作用的服务密钥。

操作与检查：

• 在正确的项目根目录启动 DSH，并选择同一个目录作为工作区。
• 检查 Skill 是否出现在可见目录中；如果没有，先核对实际工作区和 Skill 根目录。
• 提交与描述触发条件相符的审查任务；也可使用已允许用户调用的 Skill 名称显式触发。
• 查看输出是否区分明确缺陷与待确认事项，是否引用实际文件证据，以及是否遵守“不修改文件”要求。
• 比较任务前后的工作区状态。若有未经允许的写入、命令或网络访问，立即停止并复查权限和日志。

验收至少包括“目录可见、指令可读取、输出遵守可观察约束、证据来自实际工作区”四项。若 Skill 只被加载但输出没有遵循规则，问题可能出在触发描述、指令设计或模型执行，不应误判为 Plugin 功能故障。

FAQ：把安装、兼容和验证问题分开

DeepSeek Harness 怎样安装并确认基础环境可运行？

按前文选择 npm 或源码路径，并使用官方说明中的命令。Web UI 启动后，再配置模型凭证和工作区，运行只读任务检查完整链路。系统版本和项目提交不同，依赖状态也可能不同，因此不要把别人的成功日志当作本机验收结果。

Skills 与 Plugins 分别适合什么任务？

Skill 适合可重复的自然语言流程与约束，例如代码审查步骤；Plugin 适合补充运行时代码能力、工具或外部连接。若任务只要求固定工作规范，先用 Skill；若缺少实际执行能力，再评估 Plugin 的依赖、兼容性与权限。

如何添加并启用兼容的 Plugin？

先从项目官方 CLI 或插件安装教程核对安装路径，再核对扩展自己的源代码、版本和权限说明。按 profile 安装后，确认配置层已启用、运行日志没有载入错误，并通过无副作用任务测试。社区项目的发布状态不是官方兼容承诺。

怎样确认 Skill 或 Plugin 真正完成了任务？

检查“能否发现、能否加载、能否按规则执行、结果是否有证据”这条链路。Skill 的目录和正文可见，不代表模型遵守；Plugin 的安装状态可见，不代表它已获得所需授权或正确连接外部服务。关键结果必须人工核验。

安装或调用失败时怎样排查？

保留错误日志和版本信息，依次确认依赖与版本、配置是否加载、Skill 目录或工作区是否匹配、权限是否获批，最后检查扩展自身错误。优先缩小故障范围，不要用扩大文件访问范围或关闭所有审批来“快速修复”。

排错与部署：先定位原因，再决定换环境

遇到 Skill 不显示、Plugin 加载失败或任务中断时，按下面顺序记录证据：

1. 依赖或版本不匹配：核对 DSH 版本、扩展要求和包管理器输出。开发预览版本可能发生不兼容变更，应优先按当前官方仓库和组件文档判断，而不是凭旧教程推断。
2. 配置层未启用：确认正在运行的 profile 与修改的 profile 相同，再检查插件管理状态和启动日志。不同 profile 的设置不会自动互通。
3. 工作区或 Skill 路径错误：核对会话所选目录、Git 根目录和 Skill 文件位置；若目录清单中没有条目，先排路径，不要先重装。
4. 权限不足或权限过宽：查看审批请求及被拒绝的操作。只补充当前任务必需的最小权限；不要把凭证或整个主目录开放给未审查扩展。
5. 扩展本身异常：在不含敏感资料的最小项目中复现，检查其错误日志、依赖和维护说明。若官方资料没有覆盖该社区扩展，就应把支持状态保留为未知。

部署方式也应按任务选。偶尔、交互式地使用，可先在本机验证；需要长期运行、远程访问或隔离团队工作区时，再评估单独环境、备份、凭证管理、网络暴露面和恢复流程。项目安全说明建议使用最小权限，并优先考虑可丢弃的虚拟机、容器或专用环境；这些措施能降低风险，但不能保证完全隔离。

验收清单：

• [ ] 记录 DSH 版本、安装方式和实际启动目录。
• [ ] 完成模型配置、工作区选择及一次只读任务。
• [ ] Skill 能被发现，正文内容和调用方式符合预期。
• [ ] Plugin 来源、依赖、兼容范围和权限已经过人工审查。
• [ ] 失败日志可复现，且没有把模型输出误当作插件已成功的证据。
• [ ] 持续运行时已考虑凭证保护、备份、网络访问和异常恢复。

如果当前方案是在个人电脑上临时跑任务，通常先把依赖、权限和工作区理顺，比迁移环境更重要。若长期运行受本机在线时长、团队共享隔离和远程维护限制，再评估远程环境；若工作流依赖 Apple 平台工具或物理接口，也要确认远程方案能否满足该条件。云端 Mac 不是运行 DSH 的必需条件。确有远程 Mac 开发需求时，可先查看 ZekVPS 的 Mac 环境说明；如需比较可选的 远程 Mac 使用方案，再按实际工作流决定是否租用。