Superpowers插件：Photoshop效率增强工具安装与实战指南
2026/10/8 12:02:36
先说个题外话。我最近在折腾 DeepSeek Harness，从装现成插件到动手写自己的第一个插件，走了不少弯路。网上的叫法很杂，有人叫 DeepSeek Harness，有人叫 deepseek hermes，也有人直接叫 agent harness，本质上都是那一层“套在大模型外面的工程壳”。这篇教程不是官方文档的复读，更像是我把从 0 到 1 这条路上最关键的环节整理出来：为什么需要插件、插件项目长什么样、怎么一步步写一个能用的插件，以及我踩过的坑。如果你是刚接触 Harness、想给它加插件来提升 coding 体验的开发者，这篇应该能帮你少走很多弯路。
在做插件开发之前，我建议你先搞清楚一件事：Harness 到底解决的是什么问题。这决定了你写的每一个插件应该管什么事、不该管什么事。
1. 为什么建议给DeepSeek Harness做插件开发
1.1 先搞明白Harness到底是一个什么样的工程
很多人第一次听到“harness”这个词会懵，因为它直译是“马具、挽具”，在工程语境里完全不是这个意思。可以这么理解：大模型本身只是一个推理内核，像一个能力很强但缺乏经验的实习生，它有知识、能推理，但它不知道你的项目目录结构、不知道你的编码规范、不会自己去看 Git 状态、也不了解你团队的开发流程。Harness 就是套在模型外面的那层“工作台”，负责管理提示词、会话上下文、工具调用、终端命令、文件读写、插件加载这些杂活。
DeepSeek Harness 就是这个思路在 DeepSeek 生态下的一个具体实现，特点是支持本地部署、可以接入不同的模型后端、也能在局域网离线环境里跑。它和 IDE 插件、Chrome 插件不是一个层面的东西——IDEA 插件是给编辑器加能力，Chrome 插件是给浏览器加能力，而 Harness 插件是给“AI 代理”加能力。三层逻辑很像，但 Harness 插件更靠近模型的思考过程，你能干预的东西也更底层。
打个比方：模型是发动机，Harness 是整车和座舱，插件就是你往车里加的各种改装件——行车记录仪、胎压监测、自动巡航。没有插件，车也能开，但有了合适的插件，驾驶体验完全不同。
1.2 插件机制解决的三个真实痛点
我用了几天原生 Harness 之后，最大的感受是：“能用，但不够贴手。”如果你没有经历过这种感觉，可能还没意识到插件机制的真正价值。我总结下来，插件主要解决三个痛点。
第一个是默认行为不够贴合个人工作流。不同人的编码习惯差异极大。有人习惯先写测试再写实现，有人习惯先列 TODO 再逐项填，有人要求所有代码注释必须是中文，有人要求提交信息严格遵循 Conventional Commits。这些规则如果在每次会话里靠手敲提示词去维护，既啰嗦又不稳定。插件可以在消息进入模型之前自动注入项目规范，把这些规则落到统一的地方。
第二个是知识复用困难。团队里的私有 API 文档、部署手册、代码评审清单，如果都靠复制粘贴到对话里，迟早会丢。把这类知识做成 skill 塞进 Harness，它就能在需要的时候自动读取和调用，而不是你每次去翻文档。
第三个是工具链没有打通。Harness 本身能调用终端和文件系统，但要和 IDEA 的编译状态、Chrome 的页面上下文联动，就需要插件做桥接。比如我写了一个插件，在 Harness 执行可能导致大规模文件改动的操作前，自动要求 Git 创建一个标记点，出问题可以直接回退，这就是典型的工具链打通。
1.3 什么人适合自己动手写插件
我自己是 Java 程序员出身，写过 IDEA 插件，也做过浏览器插件，但一开始面对 Harness 插件开发时还是有点心虚。后来发现，门槛比想象中低很多。适合自己动手写插件的人大概有三类。
第一类是日常重度使用 Harness 的开发者，用久了觉得默认行为不够好，想定制自己的工作流。第二类是团队里负责 AI 工具建设的人，需要把编码规范、评审流程、发布检查做成统一的东西分发给同事。第三类是对插件开发有兴趣的开发者，无论之前做的是 IDEA 插件还是 Chrome 插件，迁移到这个领域的概念模型非常顺滑。
不太适合入门的人，是那种完全没写过代码、只想“装个现成插件”的同学。这部分场景更适合直接安装社区插件，而不是开发。开发插件不需要你精通底层原理，会一点 Python 或 JavaScript、能看懂 JSON/YAML 配置，就够了。
2. 插件开发前的基础准备
2.1 环境安装与基础配置
我假设你已经在用 Harness 了。如果还没有，先去官方渠道下载对应平台的安装包，Windows、macOS、Linux 都有预编译版本。装完之后，不要急着写插件，先把模型通道调通。
Harness 本身不是一个模型，它只是壳，你需要让壳能连上模型。最常用的做法是编辑配置文件，一般是~/.harness/config.yaml或config.json，具体看版本。一个典型的配置大概是这样的：
model: provider: deepseek base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat temperature: 0.2 plugin: dir: ~/.harness/plugins auto_load: true log: level: info这里有几个关键点。第一，api_key不要直接写死在文件里，用环境变量引用，否则你哪天把配置分享给同事，密钥就泄了。第二，base_url不一定是官方地址，如果你内网用 vllm 部署了 DeepSeek 模型，这里可以直接填内网地址，这也是 Harness 能离线局域网使用的基础。第三，temperature在 coding 场景建议低一点，0.1 到 0.3 之间，输出更稳定。
配置好之后，先跑一个最小会话，问它“1+1 等于几”，确认模型连通，再继续往下走。这一步跳过了，后面所有的问题你都会怀疑是模型的问题，其实是配置的问题。
装好之后，熟悉一下 Harness 自带的命令行工具。不同版本可能命令有差异，但核心的几个基本一致：harness plugin list查看已安装插件，harness plugin install <name>安装插件，harness plugin create <name>生成插件骨架，harness dev --plugin <path>启动插件开发模式，harness logs --level debug查看调试日志。开发阶段最重要的就是harness dev和harness logs这两个。
2.2 插件项目结构与核心文件说明
用harness plugin create my-plugin生成的骨架，目录结构大概是这样的：
my-plugin/ ├── plugin.json ├── main.js # 或 main.py，看你的插件模板 ├── skills/ │ └── my-skill/ │ ├── SKILL.md │ └── reference.md └── assets/最核心的是plugin.json，它相当于插件的身份证和说明书。我见过很多新手报“插件装不上”的问题，八成是这里写错了。一个最小的plugin.json长这样：
{ "name": "prompt-optimizer", "version": "0.1.0", "description": "生成前自动注入项目规范，优化提示词结构", "entry": "main.py", "min_harness_version": "0.9.0", "author": "你的名字", "license": "MIT", "permissions": [ "system_prompt.read", "system_prompt.write", "config.read" ] }解释几个容易被忽略的字段。entry是指入口脚本，路径相对于插件目录，写错就加载失败。min_harness_version是向下兼容的底线，如果你的插件用了比较新的 API，这个版本号要写高一点，否则在老版本上跑会报奇怪的错。permissions是插件要申请的权限，有点类似 Chrome 插件 manifest v3 里的权限声明，Harness 会按这个清单做沙箱限制。
skills/目录存放的是“技能”文件，也就是纯文本的提示词知识包。注意，skill 和插件是两个概念：skill 是给模型读的知识和操作流程，插件是真正执行的代码逻辑。新手最容易混，其实记住一句话就行——skill 管“知道什么”，插件管“做什么”。
2.3 插件生命周期和事件钩子
Harness 插件的运行机制是事件驱动。理解这套机制，你就理解了插件开发的一大半。
插件的生命周期分为四个阶段：加载（load）、激活（activate）、运行（运行时事件）、停用（deactivate）。在load阶段，你注册自己关心的事件回调；在activate阶段，你可以做一些初始化工作，比如读配置、建立连接；之后 Harness 每发生一个事件，就会回调你注册的函数；退出时触发deactivate做清理。用代码表示就是：
def load(ctx): ctx.register_hook("before_generation", my_handler) def my_handler(ctx): # 在这里拦截、修改、记录 return ctx关键在钩子。before_generation是模型生成之前触发的钩子，适合改系统提示词；after_generation是生成完毕之后触发，适合做结果校验和记录；on_message是用户消息进来时触发，适合做输入拦截；on_tool_call是模型调用工具之前触发，适合做权限控制和审计。
新手很容易犯一个错：不知道到底该挂哪个钩子，结果在on_message里改上下文，改了半天发现对生成结果没影响。给你一个简单判断标准：想改模型的输入，优先看before_generation；想改用户和模型的对话流，用on_message；想管工具调用，用on_tool_call。后文的实操案例会带你走一遍完整的钩子选型。
3. 实操：从0到1写一个提示词优化插件
3.1 需求拆解和插件设计
光说不练假把式。这一节我带你亲手写一个提示词优化插件——这也是社区里问得最多的插件类型之一。为什么这个需求这么普遍？因为很多人发现，直接用 Harness 跑编码任务，模型生成的代码“能跑，但风格飘忽”，结构松散，注释中英混杂，甚至有时候它完全忘了项目里约定好的命名规范。
最直接的解法当然是写一个通用的 system prompt，但问题在于，这个规范要跨会话复用、要在团队内统一，而且最好能随着不同项目自动切换。这就是插件该干的活。
我给这个插件定的功能设计很简单，只有四点：
- 从配置文件读取项目规范清单和语言偏好；
- 在
before_generation钩子里，把规范注入到 system prompt 的尾部； - 每次注入都写一条日志，方便排查“到底注入没有”；
- 支持开关，不想用的时候可以直接关掉，不用卸载。
这里有个设计决策值得说一下：为什么选择注入 system prompt，而不是改写用户消息？因为用户消息是用户的原始输入，你擅自改写会丢失信息、也会让用户困惑；而 system prompt 本身就是干这个的——给模型提供“背景设定和规则”。所以注入到 system prompt，既安全又符合语义。
3.2 核心代码实现
我用 Python 写的主逻辑，你也可以用 JavaScript，概念完全一样。完整代码如下：
import logging from datetime import datetime CONFIG = {} def load(ctx): global CONFIG CONFIG = ctx.config.get("prompt_optimizer", {}) ctx.register_hook("before_generation", rewrite_system_prompt) ctx.logger.info("prompt_optimizer loaded, enabled=%s", CONFIG.get("enabled", True)) def rewrite_system_prompt(ctx): if not CONFIG.get("enabled", True): return ctx base = ctx.system_prompt or "" rules = CONFIG.get("rules", []) language = CONFIG.get("language", "中文") output_style = CONFIG.get("output_style", "文件清单+关键改动说明") extra_lines = [ "请严格遵循以下项目约定：", ] for rule in rules: extra_lines.append(f"- {rule}") extra_lines.append(f"- 代码注释语言统一使用：{language}") extra_lines.append(f"- 输出请采用结构：{output_style}") extra_lines.append(f"- 本注入由 prompt-optimizer 插件生成，时间：{datetime.now().isoformat()}") ctx.system_prompt = base + "\n\n" + "\n".join(extra_lines) ctx.logger.info("prompt_optimizer injected %d rules", len(rules)) return ctx代码不长，但有几个细节值得抠。
第一，ctx.config.get("prompt_optimizer", {})读的是插件自己的配置段，不是全局配置。这样不同插件之间配置互不干扰，团队分发时也只需要拷贝一小段配置。第二，注入的内容里包含了时间戳，这是一个很实用的小技巧——模型看到 system prompt 里混入时间信息，会更容易感知会话时间，对涉及“当前日期”“过期时间”的任务有奇效。第三，日志记录的是“注入了多少条规则”，而不是“完整 prompt 是什么”，因为完整 prompt 可能很长，刷爆日志不划算。排查问题时，知道“次数对不对”基本就够了。
配套的插件配置段是这样挂在config.yaml里的：
prompt_optimizer: enabled: true language: 中文 output_style: 文件清单+关键改动说明 rules: - 新代码禁止使用全局变量 - 所有异常必须显式处理，禁止吞异常 - 修改数据库表结构必须同步生成迁移脚本写代码时还有一条红线：不要在钩子里调用大模型。特别是before_generation这种前置钩子，如果里面再调一次 LLM 做“提示词优化”，等于每次请求前多了一整轮模型调用，延迟爆炸不说，还有递归风险。提示词优化不要靠“模型再想一遍”，要靠规则和文本处理来搞定。这就像做菜，调味可以在下锅前完成，但你不能因为想调味而先去隔壁饭馆吃一顿。
3.3 调试、加载和验证
代码写完之后，进入调试阶段。这是整个开发过程里最容易卡住的地方，也是我踩坑最多的环节。
开发模式下推荐这样跑：先确保 Harness 处于未启动状态，然后执行：
harness dev --plugin ./prompt-optimizerharness dev的好处是支持热重载，你改了代码，插件会自动重新加载，不用反复安装。我早期不知道有这个命令，每次改代码都要卸载重装，白白浪费了很多时间。
启动后，开一个会话随便问一个编程问题，然后去查日志：
harness logs --level debug你应当能看到类似prompt_optimizer injected 4 rules的日志。如果看不到，大概率是钩子没注册成功，或者配置里enabled被关掉了。如果看到了日志，但生成结果没有变化，那就需要进一步确认注入的内容是否真的进入了 system prompt。这时候可以临时把日志级别调成 trace，看 Harness 完整渲染出来的 system prompt 文本，确认注入失效的原因。
一个非常实用的验证技巧是：故意在规则里写一条特别明显的语句，比如“请在所有代码的第一行输出插件标记注释# by prompt-optimizer”。如果生成的代码里有这个标记，说明注入链路是通的；如果没有，就去查日志、查钩子。用这种“可观测的标记”做验证，比肉眼看代码风格快得多。
验证通过后，打包分发：
harness plugin package ./prompt-optimizer会生成一个.hp后缀的插件包，其他机器上执行harness plugin install ./prompt-optimizer.hp就能装上。团队内部分发、内网离线部署，都用这个包。
4. 高频插件选型与skill部署要点
4.1 适合coding场景的插件清单
插件写多了之后，我整理了一份自己常用的“coding 插件清单”，都是从真实需求里长出来的，不是网上随便抄的。我分了四档，按场景列出来了：
| 插件类型 | 典型功能 | 适用场景 | 开发难度 |
|---|---|---|---|
| 项目规范注入 | 在生成前注入编码规范、提交规范、目录约定 | 团队协作、多项目切换 | 低 |
| Git 回退保护 | 工具调用前自动创建备份点，异常时回退 | 大范围重构、批量替换 | 中 |
| 提交信息生成 | 分析 diff 生成符合规范的 commit message | 日常提交、MR 前检查 | 中 |
| 环境检查 | 验证模型连通、检测依赖完整性、检查磁盘空间 | 内网部署、多人共用机器 | 低 |
为什么这四类最值得优先做？因为它们都是高频、重复、且规则相对明确的动作。凡是“每次都要靠人肉提醒”的事情，都值得做成插件。
尤其是 Git 回退保护，我强烈建议写一个。我实际遇到过这种情况：Harness 执行一个批量重构任务，一口气改了三十多个文件，结果跑到一半我发现思路错了，想回退已经来不及了。后来我写了一个插件，在on_tool_call钩子里拦截所有写文件类工具，调用前先让 Git 创建一个标记点，工具执行失败或用户明确说“撤销”时，自动回到标记点。从此“AI 搞砸了”的成本大大降低。
4.2 skill的正确写法和内网部署
插件是代码，skill 是知识。两者经常配合使用，但很多人部署的时候会把它们搞混，我就见过有人想把整个插件目录当成 skill 拷到内网，结果代码根本没执行。
一个标准的 skill 文件是这样写的：
--- name: code-review-checklist description: 代码评审时按此清单逐项检查 when_to_use: 用户要求评审代码、提交MR之前 --- 1. 先确认变更范围，列出改动文件列表 2. 检查命名规范、注释语言是否统一 3. 检查异常处理，是否存在吞异常 4. 检查是否有调试残留代码 5. 输出结论：通过 / 不通过 + 问题清单---之间是 YAML front-matter，name是技能名，description是给模型看的说明——模型会根据描述决定“当前任务要不要调用这个技能”，所以描述要写得具体，像“代码评审时按此清单逐项检查”就比“评审工具”好得多。when_to_use是触发条件，同样是给模型做匹配用的。
skill 的部署比插件简单，只需要把 skill 目录放到 Harness 的 skills 目录下，重启生效。但如果你要把整套东西搬到内网服务器，要注意三步：第一步，在有网的机器上把 Harness 主程序、插件、skill、依赖全部装好，最好用harness export bundle导出一个完整的离线包；第二步，拷到内网机器上，执行 import 或直接解压到对应目录；第三步，改配置，把模型地址指向内网的服务，比如内网 vllm 部署的地址，然后跑一遍harness offline-check确认没有外部网络依赖。核心原则就是“外网装好、内网拷贝、配置隔离”。
4.3 模型接入与回退方案配置
很多人关心一个问题：Harness 能不能不用官方账号、接自己的模型？答案是能，这也是这类工具的通用能力。Harness 支持通过配置base_url对接任何兼容 OpenAI 协议的接口，包括本地 vllm 部署、内网网关、以及其他服务。但我要提醒一句：接入任何模型前，先确认服务条款是否允许，企业内部自建网关通常问题不大，个人使用更要留意合规边界。不要试图用任何“破解”“越狱”类手段，那是把自己往坑里推。
配置两个模型做回退，也是一个实用技巧。做法是在配置里声明多组模型，主模型负责正常生成，备用模型在超时或报错时顶上：
model: primary: provider: deepseek base_url: https://api.deepseek.com/v1 model: deepseek-chat api_key: ${DEEPSEEK_API_KEY} fallback: provider: openai_compatible base_url: http://10.0.0.5:8000/v1 model: internal-llm api_key: ${INTERNAL_API_KEY}回退的逻辑不复杂，Harness 本身会在主模型调用失败时自动切换。但这里有个新手容易忽略的点：两个模型的能力差异可能很大，同一个 prompt 在 A 模型上效果很好，在 B 模型上可能一塌糊涂。所以不要一配了之，定期观察 fallback 场景下的输出质量，必要时针对不同模型写不同的 skill，比指望一个万能 prompt 打天下靠谱得多。
5. 常见问题与排查技巧实录
5.1 安装加载失败的典型场景
“插件装不上”是新手遇到最多的拦路虎。我汇总了几个高频场景，并配了排查思路，都是实测过的。
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
harness plugin install超时或失败 | 网络源不可达、下载超时 | 换下载源、重试，或手动下载插件包本地安装 |
插件装完但plugin list看不到 | manifest 解析失败、目录层级错误 | 检查 plugin.json 是否有语法错误，确认插件在正确的 plugins 目录下 |
加载时报entry not found | 入口路径写错、依赖未安装 | 检查 entry 字段是否对得上；Python 插件确认依赖已装、JS 插件确认 node_modules 存在 |
| 启动后卡死、响应缓慢 | 插件内做了同步远程请求 | 改成异步、延迟加载，或去掉钩子里的远程调用 |
这里最值得说的是第一个问题。很多人一看到 install 超时，第一反应是“我的网络有问题”，但更多时候是插件包版本和当前 Harness 版本不兼容，服务器上还在拉旧版本资源。我的建议是：优先看报错信息里的版本号，再做决定；确认插件官方支持当前 Harness 版本，再在网络层面找原因。安装和加载的日志都会写到本地日志文件里，排查顺序永远是“先看日志，再猜原因”。
5.2 Windows下的文件权限问题
如果你在 Windows 上跑 Harness 并加载 skill 或插件，可能会遇到一个很诡异的报错：setnamedsecurityinfow failed (win32)。我第一次看到这个错误时一脸茫然，因为信息完全没有定位价值。后来查了一圈才发现，这是 Windows 在修改文件安全描述符时失败，通常发生在插件尝试读取或写入受控目录（比如C:\Program Files下的安装目录，或者被同步盘锁定的文件夹）时。
解决办法有四个，按优先级排列。
第一，把 Harness 的数据目录、插件目录、skill 目录全部放在用户目录下，比如C:\Users\你的用户名\.harness。这能避开绝大多数系统级 ACL 限制。第二，给目录显式授予当前用户完全控制权限，管理员身份打开 CMD 执行：
icacls "C:\Users\你的用户名\.harness" /grant "%USERNAME%:(OI)(CI)F" /T第三，以管理员身份运行一次 Harness，让它初始化所有需要的目录和文件，之后再正常启动。第四，如果杀毒软件或 OneDrive 开启了文件夹保护，把这些目录加入白名单或排除列表，否则它们会静默拦截文件操作，而且不会给 Harness 报正常错误。
我自己的经验是，做到第一步之后，这个报错基本就消失了。如果你还想在D:\或者其他盘符放插件目录，记得让路径中不要带中文和空格，很多插件在解析路径时不够健壮，纯英文路径能省掉一堆莫名其妙的问题。
5.3 离线局域网使用的注意事项
DeepSeek Harness 可以在离线局域网里使用，这是它很受欢迎的原因之一。但“离线”不是简单的“不联网”，有几个细节处理不好，照样跑不起来。
第一，离线环境里安装插件最容易翻车。有网机器上安装好的插件，直接拷到内网机器可能缺依赖。Java 插件缺 jar、Python 插件缺 site-packages、Node 插件缺 node_modules，都是常见现象。靠谱的做法是导出完整的离线 bundle，而不是只拷插件目录。第二，模型层一定要走内网服务。常见方案是用 vllm 部署 DeepSeek 模型，然后配置base_url指向内网地址。命令大概长这样：
vllm serve deepseek-ai/DeepSeek-V3 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 32768配置里把模型地址指向http://内网IP:8000/v1就行。第三，跑一遍harness offline-check确认没有外部网络依赖。很多人裁在最后一步：插件里硬编码了一个公网地址，平时有网环境完全没问题，一拔网线就废。
另外，离线环境中配置里的base_url、api_key这些敏感信息，分发前记得清理和脱敏。我见过有人把公司内部网关地址直接写进配置文件然后发到群里，看着就头疼。用环境变量引用、用配置文件模板分发，是最基本的素养。
5.4 排查问题的通用套路
最后分享一套我排查 Harness 插件问题的通用套路。不管什么问题，我都按“三步走”来处理，基本能覆盖九成场景。
第一步，看日志。harness logs --level debug是万能的起点。日志会告诉你插件加载到哪一步失败的、钩子有没有被注册、有没有异常堆栈。很多人一上来就猜“是不是模型问题”，其实九成的插件 bug 在日志里一眼就能看到。第二步，最小化。禁用所有第三方插件，只留你自己的插件，如果问题消失，说明冲突了；如果问题还在，说明你插件自身的问题。逐个启用，二分定位冲突源。第三步，分层判断。一个问题，先确认是 manifest 层、入口层、权限层还是网络层——方法很简单，看报错出现在哪个阶段：加载阶段报错基本是 manifest 或入口问题，运行阶段报错多半是权限或逻辑问题，网络类报错一般会直接带 URL 或超时关键词。
还有一个我从 IDEA 插件开发那边带过来的习惯：先跑通一个“hello world”空插件，再往上叠加逻辑。空插件只要做到“加载成功、日志输出一行字”，验证整个 toolchain 是好的，之后再写业务逻辑，出问题就知道是你自己的代码问题，而不是环境的锅。这个习惯救了我很多次。
我在实际折腾里的体会是，插件开发最大的难点不是语法，也不是框架 API——那些都有文档，认真翻一翻就会。真正难的是你心里得清楚：你到底想让 AI 改变什么行为？把这件事想透了，写插件反而很快。我的做法是先写 SKILL 再写代码：先把规则用纯文本写清楚，让模型按这个规则能跑通，再把规则落进配置、用代码自动注入。先有文本，再有代码，这条路径非常稳。
最后再分享一个小技巧：开发阶段一定用harness dev --plugin ./my-plugin做热重载，别反复安装卸载，效率差好几倍。再一个就是插件版本号一定要认真维护，团队分发时版本混乱导致的“我这改了怎么你没生效”的扯皮，我见过太多次了。给每个插件写明版本、日期、改动内容，分发的时候附上配置模板，团队里用起来会省心很多。