最近不少人在群里问 DeepSeek Harness 插件开发到底怎么入门也有人把 Harness 当成装个插件就能用的工具结果想自己写一个的时候完全不知道从哪下手。我前前后后给 Harness 写过几个内部插件从提示词优化到代码回退都折腾过一遍踩了不少坑这篇文章就把整个开发链路讲清楚插件机制是什么样的、第一个插件怎么落地、内网环境怎么部署以及新手最容易翻车的那些点。内容以我自己实际使用和社区常见实践为基础部分路径和配置可能随版本略有变化但思路是通用的适合刚接触 Harness 插件开发的读者参考。1. 先把插件机制搞清楚Harness 到底在扩展什么1.1 从会用到能改的转折点DeepSeek Harness 本质上是一个 AI 编码代理壳层它把大模型接入到你的编码工作流里统一负责三件事上下文采集、模型调度、动作执行。采集指的是它自动读取你的项目结构、打开的文件、终端输出调度指的是把当前任务拆成多轮提示词发给模型并组织上下文动作执行指的是把模型给出的意图落地为文件修改、命令运行、代码检索等实际行为。你把这个壳层理解成一个导演模型是演员导演决定演员看到什么剧本、什么时候上场。Harness 的默认剧本对大多数项目够用但一旦你遇到团队规范、私有工具链、特殊工作流就希望导演在某些节点上执行你自己的逻辑。插件系统就是干这个的在不改 Harness 本身的条件下把自定义代码注入到上述三个环节里。这就是我从持续配置 Harness 的深度用户转变成Harness 插件开发者的转折点。1.2 插件和 Skill技能别混为一谈新手最容易混淆的两个概念是插件(Plugin)和技能(Skill)我在 Harness 的安装界面里也见过很多人问是不是只装技能就够了。二者定位完全不同。Skill 是静态的知识包本质是一组指令和参考文档。它告诉模型在遇到某种场景时应该按什么步骤做例如编写 Git 提交信息时必须遵循团队模板处理前后端接口联调时先检查 swagger 文档。它不执行代码只影响模型的判断。插件是动态的代码模块。它可以在事件流里拦截数据、修改提示词、调用外部 API、操作文件系统。比如自动读取 Jira 卡片并翻译成需求描述或者在大模型返回代码前自动做格式校验。你可以把 Skill 理解为给模型的操作手册把插件理解为给 Harness 的加工流水线。1.3 三个扩展点Hook、Action、UI我接触到的 Harness 插件体系主要暴露三类扩展能力理解这三类后面的开发才不会走偏。第一类是 Hook钩子它让你在事件流的不同时机插入逻辑。常见的有模型调用前可修改将要发给模型的上下文、文件写入后可对写入内容做二次处理、会话开始/结束时可初始化数据或做清理。Hook 适合做被动干预它不主动发起动作而是在某个事件发生时被唤醒。第二类是 Action动作它直接成为模型可以调用的工具。模型根据当前任务自行决定要不要调用某个 Action比如读取某个远程文档执行某段数据库查询。Action 适合做主动供给把模型自己搞不定的事情变成它可用的能力。第三类是 UI界面在 Harness 的侧边栏或面板里增加自定义视图比如展示构建状态、显示插件运行日志。对纯编码插件来说 UI 不是必须但如果你做的是团队协作类插件这一块会很加分。我用一个通俗的类比总结Hook 像流水线上的质检员只能检查经过的商品并做标记Action 像工具箱里的电钻模型需要钻孔时才会拿起来用UI 像车间外的大屏幕让路过的人看到当前状态。搞清楚这三类你再去看官方示例代码就会顺畅很多。2. 开发前的环境准备项目结构、Manifest 与调试脚手架2.1 官方脚手架与目录规范开始写代码之前先把环境搭利索。我推荐直接用官方插件脚手架不要在项目根目录手搓一堆文件因为 Harness 对插件目录结构、配置文件格式有约定差一个字段就可能导致插件列表里能看到但加载失败这种尴尬情况。以本地安装为例我一般先建一个独立目录然后用命令行工具初始化骨架pip install dh-plugin-cli dh-plugin init my-first-plugin cd my-first-plugin初始化完成后的目录结构大概是下面这样my-first-plugin/ ├── manifest.yaml ├── requirements.txt ├── plugin/ │ ├── __init__.py │ ├── hooks.py │ ├── actions.py │ └── ui.py ├── tests/ │ └── test_hooks.py └── README.md各文件职责很清晰manifest.yaml负责声明插件的身份和注册信息hooks.py放钩子逻辑actions.py放可被模型调用的工具ui.py放界面组件。Harness 在加载插件时会先读 manifest再按里面声明的内容导入对应模块所以初始化骨架时生成的文件名最好不要乱改除非你同步改 manifest 里的路径声明。2.2 Manifest 字段逐个解释Manifest 是整个插件的门面新手常见的问题就是漏了字段或者写错类型。以下面这个 YAML 为例说明name: prompt-optimizer version: 0.1.0 description: 自动把用户输入优化为结构化提示词 author: yourname runtime: python 3.10 hooks: - event: session.prompt.before handler: plugin.hooks.optimize_prompt actions: - name: read_project_glossary handler: plugin.actions.read_glossary description: 读取项目术语表内容name是插件唯一标识一旦发布不建议修改version要求遵循语义化版本号升级插件时 Harness 靠它判断是否需要重启生效runtime声明运行环境如果你的插件依赖 py 版本特性这里必须写准。hooks和actions是核心每一个注册项都包含事件名或动作名和处理函数路径。注意处理函数路径的格式是模块名.函数名Harness 加载时会按这个路径去 import。路径写错是排错时最容易发现的问题因为报错信息通常直接就是ModuleNotFoundError。2.3 本地调试把插件复制到插件目录并打开日志环境准备好之后先做一次最小加载验证确认 Harness 能识别你的插件框架再继续写逻辑。做法是在 Harness 的插件管理界面里选择从本地目录安装指向my-first-plugin根目录。如果插件能被识别界面上会出现插件卡片和版本号如果识别失败先用最低成本手段排查——打开 Harness 的日志面板插件的加载错误全在里面。我自己习惯在正式调试前先把日志级别调到 Debug因为很多插件加载失败的信息在 Info 级别不显示。Harness 的日志文件一般存放在用户主目录下的.dh/logs/目录中Windows 上也可能是 AppData 对应目录用tail -f或记事本打开也能凑合看但推荐用 grep 过滤自己的插件名效率高很多。调试循环就三步改代码、刷新/重载插件、看日志。Harness 支持插件热重载不用每次改完都重启整个应用但热重载对状态类变量不太友好如果插件里定义了全局变量重载时会重新初始化之前的内存状态会丢失这点心里有数就行。3. 第一个实战插件把提示词优化成结构化指令3.1 这个插件解决了什么真实问题选一个具体场景来练手比空谈概念有用得多。我第一个 Harness 插件做的是提示词优化背景很简单团队里不少成员用 Harness 时不写上下文直接丢一句帮我改下登录逻辑模型面对这种输入只能猜生成结果质量很不稳定。我在社区里看到的热搜词里也有提示词优化插件说明这是个普遍痛点。这个插件的目标是在模型真正调用之前把用户输入的简单诉求补全成结构化指令——补充任务背景、约束条件、验收标准。它不是把模型变聪明而是把和模型对话的方式统一成团队的水准线。这对没有提示词工程经验的同事尤其有用也是插件能直接带来价值的典型场景。3.2 实现思路在对话入口拦截前面说过 Hook 是被动干预这里正合适。Harness 会在用户输入正式进入模型上下文之前触发一个事件我们在这个事件里拿到用户原始输入经过加工后替换成优化版本的指令。思路确定后关键在于优化这一步用什么方式实现。最朴素的方式是规则拼模板比如检测到帮我写这类动词就自动补上请给出具体实现方案包含核心代码和测试用例。但这种做法的上限很低遇到复杂需求就露馅。更靠谱的方式是二次模型调用插件把原始输入作为参数调一次轻量模型生成结构化指令再把指令放回主流程。第一次调用的模型可以配置成速度快的小模型成本很低。整个流程是用户输入 → 插件转发给优化模型 → 拿回结构化文本 → 替换原输入。用户感知上只是多等了一两秒但后续主模型的输出质量会明显提升。3.3 完整代码拆解下面是我精简后的实现去掉了团队特有的配置项保留核心骨架你可以直接照着写# plugin/hooks.py import json from dh.sdk import hook, get_logger logger get_logger(prompt-optimizer) OPTIMIZATION_TEMPLATE 你是一个提示词优化助手。请把用户的需求改写成结构化指令包含任务目标、背景信息、约束条件、期望输出格式。不要回答原需求内容只输出优化后的指令。 用户需求{user_input} hook(session.prompt.before) async def optimize_prompt(context): raw context.user_input.text if len(raw) 15: # 输入太短时无脑优化容易失真这里直接放行 return context optimized await call_optimizer(raw) if optimized: context.user_input.text optimized logger.info(prompt optimized长度从 %d 变为 %d, len(raw), len(optimized)) return context async def call_optimizer(text): # 这里的 client 由 Harness 运行时注入避免自己管理密钥 client get_model_client(optimizer, timeout10) resp await client.chat(OPTIMIZATION_TEMPLATE.format(user_inputtext)) return resp.strip()这段代码里有几个关键点。第一hook(session.prompt.before)的注册方式声明了处理函数注意处理函数必须接收 context 并返回 contextHarness 靠这个返回值把改动传回主流程。第二get_model_client是运行时注入的模型客户端不要自己去配 API Key插件里只管调用即可。第三长度小于 15 的输入直接放行这是我踩坑后的经验——过度优化会让简单问题变得冗长反而降低模型响应速度。3.4 单元测试与回归验证写插件不能只靠手工在界面里点一定要给核心逻辑配上最小测试。Harness 插件的测试思路其实很朴素构造一个模拟的 context 对象调用处理函数断言返回结果是否符合预期。# tests/test_hooks.py import pytest from plugin.hooks import optimize_prompt class FakeClient: async def chat(self, prompt): return 任务目标实现登录逻辑。约束条件保持现有接口不变。 class FakeContext: class UserInput: def __init__(self, text): self.text text def __init__(self, text): self.user_input self.UserInput(text) pytest.mark.asyncio async def test_short_input_passthrough(): ctx FakeContext(帮我修复 bug) result await optimize_prompt(ctx) assert result.user_input.text 帮我修复 bug pytest.mark.asyncio async def test_long_input_optimized(monkeypatch): monkeypatch.setattr(plugin.hooks.get_model_client, lambda *a, **k: FakeClient()) ctx FakeContext(请实现用户注册功能要求密码加密存储并返回完整代码) result await optimize_prompt(ctx) assert 任务目标 in result.user_input.text测试不一定要覆盖所有分支但至少要覆盖短输入放行和长输入被改写这两条主路径。第一个测试防止你误伤简单输入第二个测试验证优化确实生效。把测试写进上面的两条分支后续加功能时回归成本会低很多。4. 进阶让插件具备记忆和设置入口并联动代码回退4.1 插件的存储机制插件开发到一定阶段就会发现纯无状态的 Hook 不够用。比如提示词优化插件可能需要一个团队禁用词表管理员改了之后插件下次要能读到。Harness 为插件提供了两种存储KV键值存储和文件存储。KV 适合存小配置项调用方式接近字典多实例同步由运行时负责from dh.sdk import kv kv.set(team_glossary_version, 3) version kv.get(team_glossary_version)文件存储适合放名单、模板等稍大的内容路径建议用运行时提供的workspace_dir不要硬编码相对路径否则插件在不同操作系统上的表现会不一致。我实际遇到过一个坑Windows 上插件默认工作目录和我想象的完全不一样硬编码相对路径导致读不到配置文件最后把所有路径替换成运行时注入的目录变量才解决。4.2 设置面板的声明式写法想让用户能在 Harness 界面里配置插件可以在 manifest 里声明一组 schema运行时自动生成设置面板。我建议把可配置项收敛到最少能用默认值解决的不要暴露给用户因为每个暴露出来的配置项都意味着你需要处理用户的错误输入。# manifest.yaml 追加片段 settings: - key: glossary_path label: 术语表路径 type: string default: ./data/glossary.md - key: enable_auto_optimize label: 开启自动优化 type: boolean default: true插件代码里通过get_setting(glossary_path)读取。字段类型要写对boolean类型的配置在界面上是开关用户误输入的概率小而string类型建议在读取时做一次合法性校验。4.3 事件订阅与代码回退的联动提到代码回退是最新网络热词里出现频率很高的功能我顺便把实现思路讲一下。Harness 默认在模型修改文件前后会记录变更历史但默认的回退粒度是整个文件版本如果你只想回退某一次插件的改动就需要自己在文件写入事件里做快照。实现方案是订阅文件写入事件在模型落盘前把原文件内容复制到插件数据目录里并记录对应的任务 ID。后续如果确认该任务产出的改动有问题可以直接从快照恢复。下面是一个最小示例from dh.sdk import hook, workspace_dir import shutil import uuid hook(fs.file.before_write) async def backup_before_write(context): file_path context.file_path task_id context.task_id backup_dir workspace_dir() / backups / str(task_id) backup_dir.mkdir(parentsTrue, exist_okTrue) backup_path backup_dir / f{uuid.uuid4().hex}_{file_path.name}.bak shutil.copy2(file_path, backup_path) context.backup_path str(backup_path) return context这里有几个细节值得注意备份用copy2保留元数据文件名里带上uuid防止同任务多次写入互相覆盖写入事件触发时机一定要验证清楚我最初是在写入完成后才做备份结果发现原文件已经被覆盖了备份等于没备份。弄清楚事件的前和后语义比代码本身更重要。5. 内网部署与离线运行局域网环境的插件分发方案5.1 离线环境下的插件仓库Harness 的一个常见使用场景是内网离线部署尤其是研发数据敏感的公司模型和工具链都必须跑在局域网内。在这种环境下插件安装不能走公网仓库需要搭建一个内网插件仓库。最简单的方案是文件共享或静态 HTTP 目录。把插件打包成压缩包放到一台内网文件服务器上在 Harness 的插件源配置里指向该地址。插件配置里的source字段改成内网地址即可。# 插件源配置示例 sources: - name: internal-repo type: http url: http://10.0.0.5:8080/plugins/注意两点一是要确认内网的 Harness 客户端能访问该地址很多内网环境有额外的防火墙策略经常出现插件源配置没问题但安装总是超时的情况二是在离线环境里插件依赖的第三方 Python 包也需要提前下载到内网否则插件加载时会因缺依赖直接失败。5.2 Skill 与插件依赖如何打包进内网Skill 是静态文件打包更直接把整个目录拷贝到内网服务器再在 Harness 的技能管理里添加本地路径即可。但如果 Skill 内部引用了插件 Action情况就复杂一点需要确保两者版本匹配。依赖处理是内网部署最烦人的环节。我一般用 pip 的离线下载功能在一台有网的机器上把requirements.txt里列出的包全部下载到本地目录再打进一个资源包带到内网pip download -r requirements.txt -d ./dh_plugin_deps/然后在 Harness 插件加载配置里增加本地依赖路径让插件解压时优先从该路径解析依赖。这样做的好处是所有依赖版本锁定不会出现内网环境里包版本不一致导致行为异常的隐性问题。5.3 接入内网或免费模型的配置方式离线局域网环境下的另一个问题是模型接入。社区里经常问Harness 可以在离线局域网使用吗可以接入免费模型吗答案是肯定的关键是把模型端点配置到插件或 Harness 的模型配置里。只要你的内网环境有可用的兼容 OpenAI 协议的模型服务配置方式基本一致。我自己的做法是在数据目录的配置文件中增加一个模型节点指向内网服务的地址models: optimizer: base_url: http://10.0.0.6:8000/v1 api_key: dummy-internal-key model_name: local-optimizer这个配置文件的路径在各版本里可能不同建议先在 Harness 的模型管理界面里手动添加一次看它生成的配置长什么样再改成内网地址。不要直接猜测字段名乱填我之前就因为在模型配置里写错了 headers 字段导致插件调用优化模型时一直 401排查了半天才发现是配置格式问题。5.4 文件权限与 setnamedsecurityinfow 报错的处理内网部署还有一个绕不开的问题文件读写权限。Windows 环境尤其容易出现一个报错setnamedsecurityinfow failed。我在热搜词里也看到有人在问这个说明踩过的人不少。这个报错通常出现在插件尝试读取或写入某个文件时本质是 Windows 对这个文件应用安全描述符ACL失败了。常见原因有三个目标文件位于需要管理员权限的目录如 Program Files文件被其他进程独占锁定文件系统本身不支持某些安全属性比如挂载的网络盘或 FAT32 格式分区。针对这个问题我的处理顺序是先检查插件的工作目录和要读取的文件路径是否在用户有完整权限的目录下路径能迁就就迁移这是最省事的方案如果必须要访问系统目录则在部署文档里明确要求 Harness 以管理员权限运行如果文件在网络盘上把插件的工作数据放到本地磁盘网络盘只做最终同步。需要注意的是这个报错并不影响所有文件操作很多时候是个别文件失败插件代码里要做异常捕获不能因为一个文件失败就让整个任务中断。我通常对文件读取包一层 try/except失败的记录到插件日志并跳过保证主流程继续这个习惯在 Windows 内网环境里能救命。6. 新手避坑清单与问题排查链路6.1 插件安装失败的三种典型原因我在社区里见到的Harness 无法安装插件问题九成以上能归结为三种原因。第一种是插件包结构不对把整个项目目录压进了压缩包的根目录导致 Harness 找不到 manifest正确做法是保证压缩包解开后第一层就是manifest.yaml。第二种是 manifest 里的 Python 版本要求和本机环境不匹配运行时报错直接抛 import 错误。第三种是依赖缺失Harness 虽然会在加载时尝试安装依赖但网络被限制时会导致超时。排查顺序建议是先看日志里插件加载的具体报错不要凭感觉去猜。日志里如果是FileNotFoundError或 manifest 解析错误基本就是打包结构问题如果是ModuleNotFoundError基本就是依赖缺失去检查 requirements.txt 是否完整。6.2 代码回退机制为什么没生效我自己最早写回退功能时遇到过明明做了快照回退后代码还是不对的诡异现象排查后发现是快照时机不对。我前面提到过务必要确认回调触发的时机是写入前还是写入后。在 Harness 的事件体系里before_write和after_write的含义截然不同前者拿到的是磁盘上的旧文件后者拿到的是已被模型改动过的新文件。如果你想回退到模型改动之前的状态必须在 before 事件里做快照如果你不小心在 after 事件里做快照那备份的其实已经是被污染的版本。这个问题看似简单但实际项目里因为多个插件同时订阅事件执行顺序会被打乱我建议在日志里记录事件触发先后顺序不要只看单个插件的代码逻辑。6.3 调试日志怎么看才高效插件出问题时我最先做的是翻日志但不会从头到尾扫而是先 grep 插件名和错误级别。Harness 日志文件通常会把每个插件的日志混在一起不加过滤直接看会淹没在大量 Harnass 自身日志里。推荐的命令是grep -iE my-plugin|ERROR|WARN ~/.dh/logs/*.log如果日志里没有关键信息说明你的日志级别可能太低或者插件代码里根本没有调用 logger。好多新手写完插件不打日志出问题全靠猜这是效率最低的排错方式。建议在插件的每个关键分支上都加上 logger 输出包括走了哪个分支、参数值是什么、结果是什么这些日志在排错时比任何调试器都好用。6.4 打包发布前最后检查一遍这五件事插件写完后我每次发布前都会过一遍清单避免在同事那里翻车。依次检查manifest 里的版本号是否有更新没更新的版本号会导致分发后客户端不提示升级依赖清单是否完整尤其是内网环境缺失的包配置文件里的任何绝对路径是否替换成了运行时注入的目录热重载后是否出现状态残留如果有则考虑插件启动时重置状态最后是文档写清楚插件的权限要求和工作目录这一步能少接好几个求助消息。如果插件是给团队用的建议先在一台干净的内网机器上做一次冷安装验证模拟普通用户的安装路径而不是在自己已经装过很多依赖的开发机上测试。我自己吃过一次亏开发机上恰好装了某个第三方库测试一切正常换到同事机器上就报缺依赖排查半天才发现把开发环境的隐式依赖当成了插件自带能力。最后再分享一个个人体会插件开发不需要一开始就追求 UI 和复杂配置一个 Hook 解决一个真实痛点就已经足够有用了。Harness 的插件体系给了很大的自由度但真正的门槛不是 API 学得有多熟而是你对自己项目工作流的理解有多深——插件只是把这种理解固化下来。我从提示词优化这个小插件起步后来逐步加了术语表联动、代码快照回退每一次都是在实际使用中发现了具体问题才去扩展的。希望这篇教程能帮你迈过第一道坎写出第一个属于自己的 Harness 插件。