dsh-n8n-plugin

dsh plugin --profile web add dsh-n8n-plugin

<div align="center">

dsh-n8n-plugin

<p align="center"><strong>把 n8n 工作流运维，装进 DeepSeek Harness。</strong><br>实例登记一次，设置页与 Agent 随处可用。</p>

<p align="center">

<a href="https://github.com/lchqi1998/dsh-n8n-plugin"><img alt="GitHub stars" src="https://img.shields.io/github/stars/lchqi1998/dsh-n8n-plugin?style=flat&logo=github&color=FFD700&label=stars"></a>

<a href="https://github.com/lchqi1998/dsh-n8n-plugin/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors-anon/lchqi1998/dsh-n8n-plugin?style=flat&logo=github&color=0969DA&label=contributors"></a>

<a href="https://www.npmjs.com/package/dsh-n8n-plugin"><img alt="npm package" src="https://img.shields.io/npm/v/dsh-n8n-plugin?style=flat&logo=npm&color=CB3837&label=npm"></a>

<a href="https://npmmirror.com/package/dsh-n8n-plugin"><img alt="npmmirror weekly downloads" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.npmmirror.com%2Fdownloads%2Fpoint%2Flast-week%2Fdsh-n8n-plugin&query=%24.downloads&style=flat&logo=npm&color=CB3837&label=npmmirror%20%E5%91%A8%E4%B8%8B%E8%BD%BD&cacheSeconds=3600"></a>

<a href="https://www.npmjs.com/package/dsh-n8n-plugin"><img alt="npm downloads" src="https://img.shields.io/npm/dt/dsh-n8n-plugin?style=flat&logo=npm&color=CB3837&label=npm%20%E4%B8%8B%E8%BD%BD%E6%80%BB%E9%87%8F"></a>

<a href="https://socket.dev/npm/package/dsh-n8n-plugin"><img alt="Socket score" src="https://badge.socket.dev/npm/package/dsh-n8n-plugin"></a>

<a href="https://dsh-plugin.org/plugins/lchqi1998/dsh-n8n-plugin"><img alt="Listed on dsh-plugin.org" src="https://dsh-plugin.org/badges/listed.svg"></a>

<img alt="Node.js" src="https://img.shields.io/badge/node-%5E22.19_%7C%7C_%3E%3D24-339933?logo=nodedotjs">

<img alt="DSH" src="https://img.shields.io/badge/DSH-%3E%3D0.2.1--rc.2-2563EB">

<img alt="n8n" src="https://img.shields.io/badge/n8n-API_v1-EA4B71?logo=n8n">

<img alt="agent tools" src="https://img.shields.io/badge/agent_tools-21-8A5CF6">

<img alt="License" src="https://img.shields.io/badge/license-MIT-3DA639">

</p>

[English](README.md) · 中文

</div>

---

<div align="center">

<img src="icon.svg" alt="dsh-n8n-plugin 图标" width="128">

</div>

✨ 为什么选它

大多数 n8n 集成方式，是把实例地址和 API Key 反复粘进对话。本插件让 n8n 成为 DeepSeek Harness 的一等公民：一个设置页、一份实例清单、21 个共享它的 Agent 工具。

一个别名，直达任意环境

实例只需在 设置 → n8n 实例 登记一次——别名（prod / staging / local…）、实例地址、API Key。所有工具按别名指定目标实例，同一段指令可以指向任何环境，无需重复粘贴凭据。

一份清单，两个界面，零漂移

设置页与 Agent 工具读取同一份存储——你在界面上配置的，就是 Agent 看到的。职责划分也是刻意的：Agent 只能读取实例清单，永远不能新增或修改——API Key 不应通过对话传递。

先离线校验，再放心发布

n8n_workflow_validate 在发送前分层检查工作流文档：结构（节点 id/name 唯一——connections 以名称为键、连接目标真实存在、webhook 配有 Respond to Webhook 响应节点）、常见节点参数（webhook 的 path/httpMethod/responseMode、scheduleTrigger 的 rule.interval、httpRequest 的 url、code 节点的代码体等）、拓扑（触发器存在且全节点可达、IF/Switch 分支接线、SplitInBatches 循环回边、AI Agent 的语言模型连接）、表达式（{{ }} 配对、= 前缀缺失警告）——全程不访问实例。

密钥不出本机

API Key 只存 ~/.dsh/dsh-n8n-plugin.json（0600）。所有响应只回显末四位，设置页从不回传完整密钥。

跟得上 n8n 的版本差异

发布走新版 POST /workflows/{id}/publish，仅在 404 时回退旧版 activate；其余版本差异，一次 n8n_api 直达。

🧩 Agent 工具

21 个工具，全部按别名寻址：

工具 · 作用

n8n_instances · 列出实例（别名、地址、掩码密钥、默认项）；Agent 不能创建/修改实例

n8n_workflows · 列出工作流（active / name / tags 过滤，游标分页）

n8n_workflow_get · 读取完整工作流 JSON

n8n_workflow_create · 从 JSON 创建工作流，可立即发布

n8n_workflow_update · 用完整文档更新工作流，可同时发布/取消发布

n8n_workflow_delete · 删除工作流（会停止其触发器）

n8n_workflow_publish · 发布（activate）/ 取消发布（deactivate）

n8n_workflow_validate · 离线校验工作流 JSON：结构 / 常见节点参数 / 拓扑 / 表达式四层检查，不访问实例

n8n_workflow_clone · 克隆工作流：复制定义与标签，副本默认不发布

n8n_workflow_tags · 读取或替换工作流标签（按标签 id 或名称）

n8n_executions · 列出执行记录（可按 workflowId / status 过滤）

n8n_execution_get · 读取单次执行的结构化视图：状态、耗时、逐节点结果与错误摘要

n8n_execution_cancel · 取消运行中的执行

n8n_wait_execution · 轮询等待一条执行记录结束（可设超时与轮询间隔）

n8n_webhook_call · 经 Webhook 触发器手动运行工作流，默认等待执行结束并返回逐节点结果

n8n_tags · 列出标签及 id

n8n_tag_create · 创建标签

n8n_tag_update · 重命名标签（引用它的工作流同步生效）

n8n_tag_delete · 删除标签（会从所有工作流上移除）

n8n_credentials · 列出凭证名称与类型（不含密钥值）

n8n_api · 通用 /api/v1 请求（路径需以 / 开头）

工作流 JSON 规范、实测踩坑清单与开箱模板见 [knowledge/workflow-guide.md](knowledge/workflow-guide.md)（模板在 [knowledge/templates/](knowledge/templates/) 下：webhook 线索、定时同步、错误通知、AI 对话四个模式，改参数即可用）。announceToAgent 开启时，系统提示会给 Agent 该文件的绝对路径，供其按需 read。工具描述与用户可见文案为中文；工具名、参数名与 n8n 协议词汇（字段名、节点类型、状态枚举）有意保留英文。

🖥️ 实例管理

设置 → n8n 实例 → 添加实例：

字段 · 说明

别名 · 字母或数字开头，只能含字母、数字、.、_、-，最长 64 字符；作为所有工具的目标标识

实例地址 · https://n8n.example.com、http://localhost:5678，可带子路径；末尾 /api/v1 可省略（会被自动规范化）

API Key · n8n 里 设置 → n8n API → 创建 API Key；编辑时留空表示保持原值

说明 · 可选备注

默认 · 新工作流默认使用的实例；全局只有一个，删除默认实例后自动顺延

「测试」按钮当场调用 GET /workflows?limit=1，显示延迟——或给出确切的失败原因：连接拒绝、DNS、超时、证书、401。

所有实例数据保存在一个文件：

~/.dsh/dsh-n8n-plugin.json     # $DSH_HOME/dsh-n8n-plugin.json，文件 0600 / 目录 0700

写入是原子的（临时文件 + 改名）；文件损坏时隔离为 .corrupt-<时间戳>，不会拖垮插件。

🚀 快速开始

# 按包名安装（npm 或兼容的 registry）
dsh plugin --profile web add dsh-n8n-plugin

# 安装到 desktop profile（桌面版自带 CLI，`dsh` 不在 PATH 时用它）
dsh plugin --profile desktop add dsh-n8n-plugin

# 从本地 tarball 或源码目录安装（开发/内网）
dsh plugin --profile web add ./dsh-n8n-plugin-0.2.0.tgz
dsh plugin --profile web add link:<本包所在路径>

安装后重启 dsh web 或桌面应用，设置页会出现「n8n 实例」分区。无需其他配置——只需一个启用了 API 的 n8n 实例和它的 API Key。

手动安装（不使用 dsh plugin）

1. 把包放到 <DSH_HOME>/profiles/<profile>/node_modules/dsh-n8n-plugin（DSH_HOME 默认 ~/.dsh）——解压 tarball 或复制目录都可以。

2. 确保该 profile 的 cordis.patch.yml 里有：

   - insert:
       - id: n8n
         name: 'dsh-n8n-plugin'

3. 重启应用。

包内的 cordis.patch.yml 是 bundle 补丁，只有把本包加入 dsh.profile.bundles 时才需要；直接插入 profile 补丁的方式更简单。

##

…(truncated)