dsh-n8n-plugin

dsh-n8n-plugin

n8n workflow operations, built into DeepSeek Harness.
Register each n8n instance once — then drive it from the Settings page or straight from the agent.

English · 中文

✨ Why dsh-n8n-plugin

Most n8n integrations have you paste a base URL and an API key into every conversation. This plugin makes n8n a first-class citizen of DeepSeek Harness: one settings page, one instance registry, and 21 agent tools that share it.

One alias away from any environment

Instances are registered once under Settings → n8n instances — an alias (prod, staging, local, …), a base URL and an API key. Every tool call picks its target by alias, so the same instruction works against any environment without repeating credentials.

One registry, two surfaces, zero drift

The Settings page and the agent tools read one and the same store — what you configure in the GUI is exactly what the agent sees. The split of duties is deliberate: agents can list instances but can never create or edit one, because an API key must not be dictated through a conversation.

Validate offline, publish with confidence

n8n_workflow_validate checks the full workflow document in layers before anything is sent: structure (unique node ids and names — connections are keyed by name, connection targets that actually exist, webhook nodes paired with their Respond to Webhook responder), per-node parameters (webhook path/httpMethod/responseMode, scheduleTrigger rule.interval, httpRequest url, code-node bodies and more), topology (a trigger exists and every node is reachable, IF/Switch branch wiring, SplitInBatches loop-back edge, AI Agent language-model link), and expressions (balanced {{ }}, a warning for missing = prefix) — all without contacting the instance.

Keys never leave this machine

API keys live only in ~/.dsh/dsh-n8n-plugin.json with 0600 permissions. Every response masks them to the last four characters, and the Settings page never echoes a full key back.

Built for n8n's moving API

Publishing uses the modern POST /workflows/{id}/publish and falls back to the legacy activate only on a 404. Version differences beyond that are one raw n8n_api call away.

🧩 Agent tools

21 tools, every one of them alias-addressed:

Tool	Purpose
n8n_instances	List instances (alias, URL, masked key, default). Agents cannot create or edit instances
n8n_workflows	List workflows (filter by active / name / tags; cursor pagination)
n8n_workflow_get	Read a full workflow document
n8n_workflow_create	Create from JSON, optionally publishing immediately
n8n_workflow_update	Replace a workflow document, optionally changing its published state
n8n_workflow_delete	Delete a workflow (its triggers stop)
n8n_workflow_publish	Publish (activate) / unpublish (deactivate)
n8n_workflow_validate	Offline JSON validation in four layers: structure / per-node parameters / topology / expressions, no instance contacted
n8n_workflow_clone	Clone a workflow: definition + tags, unpublished by default
n8n_workflow_tags	Read or replace a workflow's tags (by tag ids or names)
n8n_executions	List executions (filter by workflow id / status)
n8n_execution_get	Read one execution as a structured view: status, duration, per-node results and error summaries
n8n_execution_cancel	Stop a running execution
n8n_wait_execution	Poll one execution until it settles (configurable timeout and interval)
n8n_webhook_call	Run a workflow on demand through its Webhook trigger; waits for completion by default and returns per-node results
n8n_tags	List tags and their ids
n8n_tag_create	Create a tag
n8n_tag_update	Rename a tag (every workflow referencing it follows)
n8n_tag_delete	Delete a tag (it is removed from every workflow)
n8n_credentials	List credential names and types (never secret values)
n8n_api	Raw /api/v1 request (path starts with /)

The workflow-JSON reference, a field-tested pitfall list and ready-made templates live in knowledge/workflow-guide.md (templates in knowledge/templates/: webhook lead capture, scheduled sync, error notify, and AI chat — tweak parameters and ship). With announceToAgent on, the prompt names that file's absolute path so the agent can read it on demand. Tool descriptions and user-facing messages are written in Chinese; tool names, parameter names and n8n protocol vocabulary (field names, node types, status enums) intentionally stay in English.

🖥️ Instance management

Settings → n8n instances → Add instance:

Field	Meaning
Alias	Starts with a letter or digit; letters, digits, ., _, - only; at most 64 chars. The target identifier for every tool
Base URL	https://n8n.example.com, http://localhost:5678, optionally with a sub-path; a trailing /api/v1 may be included and is normalized away
API key	Create it in n8n under Settings → n8n API. When editing, leave blank to keep the stored key
Description	Optional note
Default	The instance new work defaults to; only one exists, and deleting it promotes the first remaining entry

The Test button calls GET /workflows?limit=1 on the spot and reports latency — or the exact failure: connection refused, DNS, timeout, TLS, 401.

All instance data lives in one file:

~/.dsh/dsh-n8n-plugin.json     # $DSH_HOME/dsh-n8n-plugin.json — file 0600 / directory 0700

Writes are atomic (temp file + rename); a corrupted file is quarantined as .corrupt-<timestamp> instead of taking the plugin down.

🚀 Quick start

# By package name, from npm or a compatible registry
dsh plugin --profile web add dsh-n8n-plugin

# Into the desktop profile (the desktop build ships its own CLI; use it when `dsh` is not on PATH)
dsh plugin --profile desktop add dsh-n8n-plugin

# From a local tarball or source directory (development / air-gapped)
dsh plugin --profile web add ./dsh-n8n-plugin-0.2.0.tgz
dsh plugin --profile web add link:<path-to-this-package>

Restart dsh web or the desktop app afterwards; a n8n instances section appears in Settings. Nothing else to set up — you only need an n8n instance with an API key.

Manual install (without dsh plugin)

• Place the package at <DSH_HOME>/profiles/<profile>/node_modules/dsh-n8n-plugin (DSH_HOME defaults to ~/.dsh) — unzip the tarball or copy the directory.

• Add the plugin row to that profile's cordis.patch.yml:

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

• Restart the app.

The bundled cordis.patch.yml is the package-level patch used when the package is listed in dsh.profile.bundles; inserting the row directly into the profile is the simpler path.

⚙️ How it works

A standard double-sided DSH package: a host half (lib/) and a browser half (client/index.js, no build step).

Settings page (browser)                        Agent (model)
  │                                              │
  ├─ GET/POST/PATCH/DELETE ───┐                  ├─ 21 × n8n_* tools
  │  /api/dsh-n8n-plugin/*    │                  │
  ▼                           ▼                  ▼
┌───────────── loopback fence (127.0.0.1 / ::1 only) ─────────────┐
│    lib/routes.js                        lib/tools.js            │
│            └───────────────┬──────────────────┘                 │
│                      lib/store.js             lib/n8n.js        │
│     ~/.dsh/dsh-n8n-plugin.json         n8n REST API v1          │
└──────────────────────────────────────────────────────────────────┘

• Host half — lib/index.js registers routes, the 21 tools and the optional prompt section from one apply(); lib/store.js owns the registry (atomic writes, 0600, corrupt-file quarantine); lib/n8n.js is the API v1 client (30 s timeout, merged abort signals, accept-encoding: identity) plus a direct webhook caller and an execution wait poller; lib/http.js enforces the loopback fence; lib/mount-once.js guarantees one mount per package and profile.
• Browser half — client/index.js renders the Settings section and talks to the same routes, so GUI and agent always agree.
• Prompt guidance — lib/guidance.js emits the system-prompt section; it renders only when n8n_* tools are visible in the session.

⚙️ Configuration

Two boolean flags live in the plugin's config inside the profile patch. Both are volatile(): an edit reaches the running instance without a restart — the loader announces the change and the plugin re-registers its surfaces in place.

- id: n8n
  name: 'dsh-n8n-plugin'
  config:
    enabled: true          # master switch: routes, tools, prompt section
    announceToAgent: true  # inject the guidance into the agent prompt

🛡️ Security model

• /api/dsh-n8n-plugin/* accepts loopback requests only, validating the socket address, Host, Origin and Sec-Fetch-Site; any request carrying X-Forwarded-For / CF-Connecting-IP is refused. Never expose this page through a reverse proxy.
• Request bodies are capped at 256 KiB, and responses are sent no-store.
• API keys are plaintext in a 0600 user-owned file — the same trust model as ~/.n8n or a n8n-api.sh environment file. Responses only carry the last four characters.
• Agents can read the instance list but cannot create or edit an instance: an API key must not be dictated through a conversation.
• An n8n API key carries that instance's API authority. Register trustworthy instances only, rotate keys, and prefer a dedicated automation user.
• Publishing immediately affects production webhook and schedule triggers; deleting a workflow stops its triggers; deleting a tag removes it from every workflow; stopping an execution aborts business processing mid-flight; execution data can contain business-sensitive payloads. The injected guidance requires the agent to confirm these operations with the user first.

🛠 Development

Requires Node.js ^22.19.0 || >=24.

npm run check             # syntax check over every source file

Layout:

lib/index.js             plugin entry (Config, apply, route/tool/prompt registration)
lib/store.js             instance store (atomic write, 0600, corrupt-file quarantine)
lib/n8n.js               n8n public API v1 client (+ direct webhook call, execution wait)
lib/routes.js            /api/dsh-n8n-plugin routes (loopback fence)
lib/tool-specs.js        21 agent tool definitions (parameters, output schema, render, execute)
lib/tools.js             the only defineTool() adapter over those definitions
lib/render.js            pure model-facing formatters used by the render hooks
lib/workflow-validate.js offline workflow validation
lib/http.js              JSON helpers + loopback fence
lib/mount-once.js        single-mount guard (one mount per package and profile)
lib/guidance.js          system-prompt text
client/index.js          browser half (settings section, no build step)
knowledge/               workflow-JSON reference

📦 Publishing

npm pack                 # writes dsh-n8n-plugin-0.2.0.tgz (lib/, client/, knowledge/, cordis.patch.yml, icon.svg, both READMEs)
npm publish              # publishes to the default registry once you are logged in

The package name appears in three places at once — package.json, the cordis row in cordis.patch.yml, and the browser module id in client/index.js. If you publish under your own scope, update all three together.

🔐 Permissions & compatibility

• Permissions: writes one JSON file under the harness home (~/.dsh / $DSH_HOME); makes outbound HTTP(S) calls to the registered n8n instances; serves a loopback-only route family through the host's web server. No command execution, no shell.
• Compatibility: DSH >= 0.2.1-rc.2 (declared as both engines.dsh and dsh.engines.dsh), Node.js ^22.19.0 || >=24, n8n public API v1 (1.x and later; publishing has a modern/legacy fallback).
• Lifecycle: no preinstall / install / postinstall scripts — install and use.
• Dependency posture: the only runtime dependency is @deepseek-ai/schemastery; every @deepseek-ai/dsh-* package and react are optional peer dependencies — the plugin never re-installs, replaces or shadows official components.

🤖 Model experience

• 21 n8n_* tools (table above); n8n_instances and n8n_workflow_validate are the safe, read-mostly entry points.
• A run loop in one chain: n8n_workflow_publish → n8n_webhook_call (trigger + wait) → n8n_execution_get to re-inspect — deploy, run, verify.
• Housekeeping is one call each: n8n_workflow_clone (copy a workflow with its tags, unpublished), n8n_workflow_tags (read/replace a workflow's tags), n8n_tag_create/update/delete, and n8n_execution_cancel for a stuck run.
• An optional system-prompt section (announceToAgent) teaches the alias convention and points at knowledge/workflow-guide.md for the full workflow-JSON rules.
• Destructive operations (publish, workflow/tag delete, execution stop) are gated by an explicit confirm-with-the-user-first rule in the guidance.

⚠️ Known limitations

• The n8n public API still has no cross-version stable "run workflow manually" endpoint; n8n_webhook_call fills that gap through the Webhook trigger — the workflow needs a Webhook node and must be published (or use mode:"test" while the editor listens for test events). Workflows without a Webhook trigger must be run in the n8n UI, then inspected with n8n_executions / n8n_execution_get.
• Public-API endpoints and fields differ across n8n versions (for example publish/unpublish alongside activate/deactivate, and updates that may want a versionId). The plugin falls back on a 404 for publishing; other differences are reachable through n8n_api.
• Tags CRUD, workflow-tag read/write and execution stop rely on the instance exposing their public-API endpoints (/tags, /workflows/{id}/tags, /executions/{id}/stop). Older n8n builds return 404 there; upgrade the instance or use n8n_api for whatever it does expose.
• n8n caps tag names at 24 characters, and its API reports an over-long name as a misleading 409 Tag already exists; n8n_tag_create / n8n_tag_update reject it before sending.
• A self-signed instance certificate is rejected by the DSH host's TLS validation; give the instance a trusted certificate or use internal HTTP.
• One mount per profile: the built-in single-instance guard deduplicates a second row for the same package.

📄 License

MIT