前言¶
在 DeepSeek Harness（DSH）里让智能体操作 n8n，常见做法是在每次对话里重复粘贴实例地址和 API Key。实例一多、环境一分（生产、预发、本地），凭证和 URL 容易混用，设置页与对话侧也难以保持同一套配置。
下面介绍社区插件 dsh-n8n-plugin（维护者 lchqi1998）：把 n8n 注册进 DSH 的实例表，用 Settings → n8n instances 维护别名与连接信息，并通过 21 个 Agent 工具按别名调用 n8n API v1。插件归类为「工作流」，在 SkillHub 目录 与 GitHub 均可查阅；当前 npm 包版本为 0.2.0，许可证 MIT。
这是什么¶
dsh-n8n-plugin 是面向 DSH Web GUI 的 n8n 工作流运维插件：一次注册多个 n8n 实例（别名 + Base URL + API Key），设置页与 Agent 工具共用同一份存储；工具侧按别名选实例，无需在对话里反复写密钥。
运行环境要求（见仓库 README 与 package.json）：
- Node.js：
^22.19.0或>=24.0.0 - DSH：
>=0.2.1-rc.2 - 面向 n8n API v1
实例注册与安全边界¶
设置页字段¶
在 Settings → n8n instances → Add instance 中配置：
| 字段 | 含义 |
|---|---|
| Alias | 以字母或数字开头；仅含字母、数字、.、_、-；最多 64 字符；所有工具用别名指定目标 |
| Base URL | 如 https://n8n.example.com 或 http://localhost:5678；可带子路径；末尾若带 /api/v1 会被规范化去掉 |
| API Key | 在 n8n Settings → n8n API 创建；编辑时留空表示保留已存密钥 |
| Description | 可选说明 |
| Default | 新任务默认实例；全局仅一个；删除默认项时由剩余第一条接替 |
Test 按钮会对该实例执行 GET /workflows?limit=1，返回延迟或具体错误（连接拒绝、DNS、超时、TLS、401 等）。
存储与权限分工¶
实例数据写入单一文件（目录与文件权限由插件约束）：
~/.dsh/dsh-n8n-plugin.json # 亦对应 $DSH_HOME/dsh-n8n-plugin.json；文件 0600 / 目录 0700
写入采用临时文件再 rename；若文件损坏会被隔离为 .corrupt-<timestamp>，避免拖垮整个插件。响应中对 API Key 仅展示末四位；设置页不回显完整密钥。
Settings 与 Agent 读同一注册表：智能体可通过 n8n_instances 列出实例（别名、URL、掩码后的 Key、是否默认），但不能在对话中创建或修改实例，避免密钥被对话内容绑架。
Agent 工具概览¶
共 21 个工具，均以别名为目标标识。工具说明与用户面向文案为中文；工具名、参数名及 n8n 协议字段保持英文。
| 工具 | 用途 |
|---|---|
n8n_instances |
列出实例（不可创建/编辑） |
n8n_workflows |
列出工作流（可按 active / 名称 / 标签过滤；游标分页） |
n8n_workflow_get |
读取完整工作流 JSON |
n8n_workflow_create |
由 JSON 创建，可选立即发布 |
n8n_workflow_update |
替换工作流文档，可选变更发布状态 |
n8n_workflow_delete |
删除工作流（触发器随之停止） |
n8n_workflow_publish |
发布（激活）/ 取消发布（停用） |
n8n_workflow_validate |
离线校验 JSON，不访问实例 |
n8n_workflow_clone |
克隆定义与标签，默认未发布 |
n8n_workflow_tags |
读或替换工作流标签（按 id 或名称） |
n8n_executions |
列出执行记录（可按工作流 id / 状态过滤） |
n8n_execution_get |
读取单次执行的结构化视图 |
n8n_execution_cancel |
取消运行中的执行 |
n8n_wait_execution |
轮询直至执行结束（可配置超时与间隔） |
n8n_webhook_call |
经 Webhook 触发运行；默认等待完成并返回各节点结果 |
n8n_tags / n8n_tag_create / n8n_tag_update / n8n_tag_delete |
标签 CRUD |
n8n_credentials |
列出凭证名称与类型（不含 secret） |
n8n_api |
原始 /api/v1 请求（path 以 / 开头） |
发布路径优先使用 POST /workflows/{id}/publish；若返回 404 再回退旧版 activate。版本差异较大时可用 n8n_api 直接调 REST。
离线校验 n8n_workflow_validate¶
在把 JSON 推到实例前，可在本地分层检查：
- 结构：节点 id / 名称唯一；连接按名称关联且目标存在；Webhook 与
Respond to Webhook配对等。 - 节点参数：Webhook path / httpMethod / responseMode、Schedule Trigger 的
rule.interval、HTTP Request 的url、Code 节点脚本等。 - 拓扑：存在触发器、节点可达、IF/Switch 分支、SplitInBatches 回边、AI Agent 与语言模型连线等。
- 表达式：
{{ }}配对；缺少=前缀时给出警告。
仓库内 knowledge/workflow-guide.md 含工作流 JSON 说明、常见坑与模板（knowledge/templates/）；开启 announceToAgent 时，提示中会给出该文件的绝对路径供 Agent 按需读取。
安装与启用¶
通过 npm 包名安装（需 web profile，与插件 dsh.client.platform: web 一致）：
dsh plugin --profile web add dsh-n8n-plugin
安装完成后，在 DSH 设置页添加 n8n 实例并用 Test 验证连通性，再在 Agent 对话中用别名调用上述工具。
DSH 生态是「一切皆插件」；SkillHub 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。插件以当前 DSH 进程的用户与权限运行，可访问其配置目录下的 n8n API Key；安装前请自行审阅 源码与 MIT 许可证。
典型用法思路¶
- 在设置页为
prod、staging、local等环境各建一条实例，指定一个 Default。 - 让 Agent 用
n8n_workflows浏览目标别名下的工作流，用n8n_workflow_get拉取 JSON 后再改。 - 修改后用
n8n_workflow_validate做离线校验，再通过n8n_workflow_update或n8n_workflow_create写回；需要上线时调用n8n_workflow_publish。 - 调试执行链时用
n8n_webhook_call或n8n_executions+n8n_execution_get/n8n_wait_execution；异常时用n8n_execution_cancel。
同一套自然语言指令只需更换工具参数里的 alias，即可切换环境，无需重复粘贴 Base URL 与 Key。
适用场景与注意¶
适合：已在用 DSH Web GUI、需要多 n8n 实例统一登记，并希望 Agent 按别名做列表、读写工作流、查执行、调 Webhook 或走 raw API 的开发者与运维。
注意：
- 实例与密钥仅保存在本机
~/.dsh/dsh-n8n-plugin.json；备份与权限需自行管理。 - Agent 不能代管实例注册；新增或轮换 API Key 必须在设置页完成。
- 插件依赖 n8n API v1 行为；极旧实例可能需
n8n_api或关注发布接口回退逻辑。
结尾¶
dsh-n8n-plugin 把 n8n 收成 DSH 里「一个注册表、设置页与 Agent 双入口、按别名驱动」的工作流运维能力，并补上离线 JSON 校验与密钥不落对话的分工。进一步细节见 GitHub 仓库 README 与 SkillHub 插件页。
