n8n-decanter

# n8n-decanter [](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml) [](https://www.npmjs.com/package/n8n-decanter) [](https://buttjer.github.io/n8n-decanter/) [](LICENSE) [](https://claude.com/claude-code) **用于构建重代码 n8n 工作流的工具包 — 以代理为优先，MCP 原生。** *代码节点作为文件* — TypeScript，共享类型和帮助程序，代码级 git 版本控制，预飞行。 **预 1.0 — 数据模型或 CLI 的重大更改可能在小版本中进行，直到 v1.0。** > **内置 AI 代理。** 该代码库的很大一部分是由 Claude Code 在人工审查下编写的。它经过测试（CI + 真实 n8n 集成套件）并正在使用，但请像版本号所暗示的那样对待预 1.0 版本。 n8n-decanter 将您的 n8n **代码节点源**放在 git 中：每个工作流一个文件夹，每个代码节点的源代码都是一个单独的 `.js` 或 `.ts` 文件，可以在您的 IDE 中编辑或由您的代理编辑，并通过 **n8n 的内置 MCP 服务器**同步回来 — 草稿优先，因此在您 `发布` 之前不会有任何内容生效。工作流 *结构* 仍然是 n8n 的工作（编辑器或 n8n 自己的 MCP 工具）；decanter 保留一个只读的 `workflow.json` 快照用于审查差异。  - **真正的版本控制** — 有意义的差异，拉取请求，责备；每次推送和拉取都会自动提交。 - **TypeScript 或类型化的 JS** — 在 TS 中编写节点（在推送时编译）；n8n 全局变量（`$input`， `$('…')`， …）在两者中都有类型。 - **代理原生** — `init` 搭建 Claude Code / Cursor / Codex 配置和验证钩子；离线 `check` 和 `node run` 为代理提供无凭证的反馈环。 - **防护栏** — 合规性防护和类型检查门控阻止损坏的推送；每个节点的漂移防护防止您覆盖在实例上编辑的代码。 - **真正的执行数据随时可用** — `executions` 将最近的运行 JSON 数据获取到一个 gitignored 临时目录中，以便代理查看实际的有效载荷形状（并构建准确的 `node run` 夹具）而不是猜测；`executions clean` 在完成后删除它。 - **预飞行 — 在发货前验证** — 整个验证表面的统一词汇：`check`（静态，离线），`simulate`（离线引擎重放）和 `test`（实例端固定运行）。两个运行时预飞行器将每个节点与实际捕获的执行进行比较，如果有差异，则退出 1，因此终端 *和* CI 都可以对此进行检查。接下来的两个项目深入探讨。 - **实例端固定测试运行** — `test` 在 **您的 n8n 实例**上运行工作流（仅草稿，从未是实时版本）：触发器/网络/凭证节点从捕获中固定，逻辑节点在实例引擎上实时执行（包括社区节点，无 Docker），每个节点与捕获进行比较 — 如果有差异，则退出 1。推荐的运行时检查。 - **引擎真实模拟** — `simulate` 在 **离线** （Docker）中使用捕获的执行作为模拟：纯节点实时运行，网络节点固定，凭证剥离。它将每个节点与捕获进行比较（如果有差异，则退出 1），并在终端中打印一个 URL 以在 n8n 网页应用中打开运行。离线模拟的 sibling：预推送验证未提交的代码，CI 无实例， `--network-none` 隔离，引擎版本排练。没有捕获数据的节点（间隙）由手动或您的 IDE 代理填充 — 在已提交的命名 [模拟场景](docs/cli/mock.md) （`mock create` / `mock check`）中，无 API 密钥或模型调用。 - **实时编辑** — `watch` 在保存时推送并自动重新加载 n8n 编辑器选项卡，通过本地代理。 - **代理防护代理** — `mcp serve` 为代理提供完整的 n8n MCP 访问权限，通过本地主机代理持有 decanter 的凭证（代理从未看到它们），同时技术上阻止代码节点（`jsCode`）写入 — 属于此存储库的文件，而不是临时 MCP 编辑。 - **共享代码和小库** — `.ts` 节点导入 `shared/` 中的帮助程序/类型和已启用的 npm 包；推送将它们捆绑到自包含的节点中，这些节点可以在任何地方运行，包括 n8n Cloud。 - **草稿优先构建** — 通过 n8n 的 MCP 服务器同步解锁公共 API 无法做的事情：每个推送都会落在工作流的 **草稿** 上，而 `publish` （或 `push --publish`）是刻意的上线步骤。每个影响实例的行为都会针对真实的 n8n 2.x 实例进行验证，并由自动集成套件验证。  📖 **完整文档： [buttjer.github.io/n8n-decanter](https://buttjer.github.io/n8n-decanter/)** ## 安装 需要 Node >= 22.18 — CLI 是 TypeScript（`.mts`），由 Node 的类型剥离原生执行；没有构建步骤。 **在较旧的 Node 上，CLI 在启动时会出现令人困惑的 `SyntaxError`** 而不是干净的版本消息：npm 的 `engines` 字段仅在安装时 **警告** （除非您设置 `engine-strict`）。如果您看到指向 `.mts` 文件的语法错误，请首先检查 `node --version`。 需要带有内置 **MCP 服务器** 的 n8n（〜2.20+）：在 n8n 中启用它一次（设置 → MCP），并在您要同步的工作流上启用 **"MCP 中可用"** （工作流卡 ⋯ 菜单，或工作流设置）— `list --remote` 和选择器显示哪些工作流仍需要它。 ```sh npm install -g n8n-decanter n8n-decanter init [dir] # 提示主机，通过浏览器中的 OAuth 连接（或粘贴 MCP 令牌），可选 API 密钥； # 编写 .env + .decanter-auth.json，复制 template/， # 搭建配置 + .gitignore ``` 从 git 检出：`npm link` （运行 `npm run build` 一次后 — 安装的 bin 是编译后的 `dist/`），或直接调用 `node n8n-decanter.mts …`，无需构建。 `init` 复制 [template/](template/) 中的所有内容；文件名 `X.example` 作为 `X` （后缀使代理配置在此存储库中保持惰性，实时在目标中）：重新运行 `init` 是安全的，并且 **修改感知**：它刷新您尚未编辑的模板文件（确认后），保留您的本地更改（将其报告为漂移），并获取新添加到模板中的文件 — 通过 `.decanter-template.json` 基线跟踪。然后将工作流 ID 添加到 `decanter.config.json` 中： ```json { "root": "./workflows", "workflows": ["0cXNQKKzmO0pXiCq"] } ``` **凭证，按优先级顺序：** - **OAuth（默认）** — `init` 打开 n8n 的同意页面，在您的浏览器中存储刷新令牌到 gitignored 的 `.decanter-auth.json` 中（自动旋转）。没有长期静态密钥；在 n8n 中撤销它随时可以。 - **MCP 令牌** — `.env` 中的 `N8N_MCP_TOKEN` ，在 n8n 中生成（设置 → MCP → API 密钥）。用于 CI 和无头设置；旋转它在 n8n 中使旧令牌失效。 - **公共 API 密钥（可选）** — `N8N_API_KEY` ，仅需要用于 MCP 无法提供的动词：`executions` 和 `data-tables`。将其范围限定为 `execution:read` ， `execution:list` ， `workflow:list` （ `init` 的连接检查）和 `dataTable:*` 读取范围。 每次成功推送 **和** 拉取后，工作流的文件夹都会自动 git-commit（作用于该文件夹；外部 git 仓库仅警告）。设置 `"commitOnPush": false` / `"commitOnPull": false` 以关闭。 `init` 还为同步目录搭建 TypeScript 工具 — `package.json` （带有 `typecheck` 脚本 + `typescript` devDep），`tsconfig.json` 和 `n8n-globals.d.ts` — 以及运行 `check` 后节点编辑的 Claude Code PostToolUse 钩子。验证路由通过 CLI，因此 `n8n-decanter` 必须位于同步目录的 PATH 上：全局安装它（ `npm i -g n8n-decanter` ），将其添加到同步目录的 `devDependencies` 中，或链接 git 检出（首先构建它 — Node 不会在 `node_modules` 下剥离 `.mts`）。动词 `check` ， `node run` ， `rename` 和 `node create` 完全离线（无凭证，无网络）。 ## 命令 ```sh n8n-decanter # 交互式选择器（终端，已初始化项目）：通过键入过滤工作流 — # 拉取绿色，未拉取远程黄色 — # 然后运行动词（未拉取：Enter 拉取）； # 停留在工作流的菜单中，Esc 退出，Esc Esc 退出 # 安装 n8n-decanter init [dir] [--force] # 交互式引导（见安装） n8n-decanter completion zsh|bash # 打印 shell 补全脚本 # 同步 n8n-decanter pull [workflow…] # 代码 + 结构快照 -> workflows/<kebab>/ n8n-decanter push [workflow…] [--force] [--publish] [--no-typecheck] # 将代码节点源推送到 **草稿** # （--publish 在之后使其生效） n8n-decanter watch [workflow] # 在保存时推送工作流的节点，仅草稿 # （+ 浏览器实时重载，选定） n8n-decanter publish [workflow…] # 使草稿生效 n8n-decanter unpublish [workflow…] # （取消发布返回仅草稿） # 工作流生命周期 n8n-decanter create "<name>" # 在 n8n 中创建空白工作流，然后拉取 n8n-decanter archive <workflow> [--force] # 在 n8n 中存档（可逆转；保留文件夹） n8n-decanter rename <workflow> "<new name>" # 在 n8n 中重命名；本地文件跟随 # 检查和测试 n8n-decanter status [workflow…] [--diff] # 漂移报告（--diff：行差异）； # 在冲突/远程漂移时退出 1； n8n-decanter check [workflow…] [--no-typecheck] # 离线布局合规性 + 类型检查 n8n-decanter executions [workflow…] [--status=success|error|waiting] [--limit=N] # 获取最近的执行数据（运行 JSON） # 到 workflows/<folder>/executions/ # （gitignored；数字参数 = 按 ID 一个） n8n-decanter executions [workflow…] clean # 删除获取的执行数据（离线） n8n-decanter data-tables [table…] [--filter='<json>'] [--search=…] [--sort=col:asc|desc] [--limit=N] [--all] # 获取数据表模式 + 行（只读） # 到一个 gitignored 顶级 `data-tables/` 目录； # 过滤/搜索/排序仅在服务器端拉取切片 n8n-decanter data-tables [table…] clean # 删除获取的数据表数据（离线） n8n-decanter test <workflow> [--execution <execution-id> | --mock <slug>] [--trigger <node>] [--json] # 在实例上固定运行（草稿；推荐的运行时检查 — # 实例引擎准确，无 Docker）； # 与捕获比较，如果有差异则退出 1 n8n-decanter simulate <workflow> [--execution <execution-id>] [--network-none] [--json] # 重放整个工作流通过一个真实的 # n8n 引擎（Docker）：纯节点实时运行， # 网络节点固定，凭证剥离； # 每个节点与捕获比较，如果有差异则退出 1。 # 在终端中，打印一个 URL 以在 n8n 中打开运行。 # 默认使用最新的捕获。 n8n-decanter simulate <workflow> --mock <slug> # 重放已提交的模拟场景 n8n-decanter simulate <workflow> --pin <execution-id> # 保存捕获的输出作为 fixtures/ n8n-decanter mock create <workflow> ["<slug>"] [--execution <id>] # 提升捕获到已提交的， # 可手动填充的 mocks/<slug>.json 场景 — # 填充没有捕获数据的节点（间隙） n8n-decanter mock check <workflow> ["<slug>"] # 结构验证模拟（离线） n8n-decanter list [--remote] [--json] # 拉取的工作流：名称，ID，文件夹 # （--remote 添加未拉取的；--json 用于工具） # 代理防护 n8n-decanter mcp serve [--port N] # localhost MCP 防护代理用于代理：完整的 n8n # MCP 访问权限，使用 decanter 的凭证， # 减去代码节点（jsCode）写入 # 节点 n8n-decanter node create <workflow> "<Node name>" [--ts] # 在 n8n 中搭建代码节点 n8n-decanter node rename <workflow> "<old node>" "<new node>" # 在 n8n 中重命名；本地文件跟随 n8n-decanter node run <node-file> [fixture.json] [--allow-env] # 离线运行节点，打印项目 `<workflow>` 是其 **ID，其工作流/文件夹名称或唯一名称前缀** — `n8n-decanter push "Order Sync"` 和 `n8n-decanter push order` 都 有效。匹配不区分大小写且永远不会提示：模糊或未知 名称会报错并显示候选列表。 `pull` 将未拉取的名称与服务器的工作流列表（MCP `search_workflows` 看到每个 工作流；选择器显示MCP不可用的红色并提供启用指南）进行解析。 没有工作流参数，所有工作流 来自配置都被处理（或在终端，选择器打开）。 **动词 位于第一位**（`n8n-decanter push wf123`）；之后的所有内容都是参数， 所以名为动词的工作流不需要特殊规则，而动词最后的错误提示 *unknown verb*。标志可能出现在任何位置。 输出仅在 **写入终端** 时才会样式化（颜色，`✓`/`!`/`✗` 字符，进度）并尊重 `NO_COLOR`/`FORCE_COLOR`；管道或重定向输出 是纯行文本，对脚本和 LLM 工具安全。交互式选择器遵循相同的规则：它仅存在于终端 — 管道的裸 `n8n-decanter` 打印纯用法文本。用于 shell 选项卡 补全动词、标志和工作流名称，追加 `eval "$(n8n-decanter completion zsh)"`（或 `bash`）到您的 shell rc。 `status` 在需要拉取或推送时会退出 1（CONFLICT，远程更改，未拉取）；本地仅待更改 退出 0 — 脚本和 CI 可以像 `check` 一样对此进行检查。 `status --diff` 显示实际的行差异，每个漂移节点下的差异，因此您可以查看推送 之前运行它。API 请求在 30 秒后超时（在 `decanter.config.json` ）。`DEBUG=1` 打印错误时的完整堆栈跟踪。`node run` 假装完整的代码节点上下文，包括 `$getWorkflowStaticData` ， 从 `workflow.json` 种子并可覆盖每个夹具。像 n8n 自己的作用域 `$env` 一样，`node run` 的 `$env` 默认情况下是 **空的** — 在夹具的 `"env"` 字段中显式设置，或传递 `--allow-env` 以继承 CLI 进程的环境（可能包括 `N8N_API_KEY` 和其他机密），因此一个打印 `$env` 的节点永远不会意外泄漏主机环境。 `executions` 针对 API 进行了只读操作，并将每个执行写入为 `workflows/<folder>/executions/<execution-id>.json` — 实际运行数据（每个节点产生的项目），用于构建 `node run` 夹具的临时参考。目录已写入自 gitignore（运行数据可能包含凭证/个人信息且永远不应进入 git）； 执行反映了 **已发布** 的工作流版本（n8n 2.x），因此将它们视为方便数据，而不是基本事实，并在完成后使用 `executions clean` 删除它们。 `data-tables` 是数据表类似物：同样针对 API 进行只读操作，它获取每个 n8n 数据表的模式（`columns.json`）和行（`rows.json`） 到一个 **顶级，gitignored** `data-tables/<table>/` 目录（数据表按项目范围划分，不属于工作流），以便您可以开发和调试 针对真实表格内容。 `--filter='<json>'` ， `--search` 和 `--sort` 仅在服务器端拉取切片； `--limit`/`--all` 控制页面大小和耗尽。 它从不写入数据表。 它由 `"dataTables"` 配置键控制（默认为开）； `data-tables clean` 删除目录（离线）。 数据表需要 n8n ≥ 2.x。 ## 对比 n8n-decanter 是 **以代码节点为核心** 的：它优化了在工作流中编写、输入、验证和部署 JavaScript/TypeScript 的循环。它建立在 **n8n 自己的 MCP 服务器和技能** 之上 —— 它们是其结构和生命周期的基础，而不是竞争对手。因此，下面的比较是针对原生编辑器和 [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) —— 一个更广泛的完整工作流创作工具包。 > **选择 [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) 如果您……** > 需要一个企业级自动化框架 —— 其中 AI 代理组装完整的工作流，多环境 Dev → Prod 管道自动处理凭证治理，全 TypeScript GitOps 确保团队间的严格审计能力。 > **选择 n8n-decanter 如果您……** 您的工作流依赖于代码节点，您希望它们作为真实文件存在 —— 类型化的 TypeScript，共享库，预飞行（离线或实例端），以及代码级别的 git 历史记录，与您的 IDE、编码代理和 n8n（甚至在云上）同步草稿。 | 功能 | 原生 n8n（浏览器） | n8n-as-code | n8n-decanter | |---|---|---|---| | **代码节点的 TypeScript** | ❌ 仅支持 JavaScript 或 Python | ❌ TS 在工作流级别，而非节点逻辑 | ✅ 代码节点为 `.ts`，编译后推送，类型化的 n8n 全局变量 | | **代码节点中的共享类型和帮助器** | ❌ 自托管 `NODE_FUNCTION_ALLOW_*` 仅限；无库 | ❌ 不是其模型的一部分 | ✅ `shared/*.ts` + npm 捆绑成自包含节点（云安全） | | **代码作为独立文件** | ❌ 无源文件（JSON blob） | 🟡 每个工作流一个 `.workflow.ts` | ✅ 每个工作流一个文件夹；每个代码节点一个 `.js`/`.ts` | | **代码级别的 git 版本控制** | 🟡 应用内历史记录（DB 快照，分级保留）；Git 源控制仅限企业版 | ✅ 工作流源的 GitOps 同步 | ✅ 真实的 git —— 差异，PR，Code 节点的 blame；每次同步自动提交（+ 只读结构快照） | | **预飞行**（`check` / `simulate` / `test`）| 🟡 重新运行过去的执行 / 固定数据，但在线在编辑器中 | 🟡 检查针对实时环境的执行 | ✅ 离线 `check` + `simulate`，实例端 `test`；每个节点与真实捕获的差异，每个节点退出状态码 1 | | **草稿优先的代码同步** | ✅ 编辑器 *保存* 与 *发布*（手动，在浏览器中） | 🟡 API 同步在推送时重新发布（无草稿专属） | ✅ 推送到 **草稿**；`publish` 是故意的上线（通过 MCP） | | **实时编辑** | ✅ 画布（基准） | 🟡 显式拉取/推送，无自动监视 | ✅ `watch`：保存时推送 + 自动重载编辑器选项卡 | | **代理原生工具** | 🟡 n8n 自己的画布 AI，不是您的代码库中的代理 | ✅ 代理工作台，技能，MCP，Claude/编辑器插件 | ✅ 为 Claude Code / Cursor / Codex 配置搭建脚手架；`mcp serve` 守护代理持有凭证；离线 `check`/`node run` 循环 | | **模型所有权** | ❌ 锁定到 n8n 自己的托管 AI；无法使用您的 Claude 订阅 | 🟡 测试版 Claude Code 插件使用您的订阅；旗舰工作台需要 Anthropic 密钥用于 Claude | ✅ 从不调用 LLM 本身 —— 您的代理/订阅 100% 驱动，无需密钥或模型配置 | | **代理工作流创建** | 🟡 AI 工作流生成器（自然语言），但云 / 计划受限 —— 积分，自托管需要设置 | ✅ 537 个节点模式 + 7,700+ 模板 + 技能 | ✅ 您的代理在 n8n 的 MCP 上构建结构（通过 `mcp serve` 守护代理）；decanter 拥有代码节点源（`create`，`node create`） | | **完整工作流创作** | ❌ | ✅ `.workflow.ts` 修饰器类（结构 + 链接） | ❌ 按设计 —— 结构保留 n8n 的（只读 `workflow.json` 快照） | | **多环境推广** | 🟡 企业源控制 / 环境 | ✅ `promote` 重新映射凭证 + 引用 Dev→Prod | 🟡 每个实例的独立同步目录，但无 `promote`（ID/凭证/引用未重新映射） | 图例：✅ 一流 · 🟡 部分或间接 · ❌ 不支持。 **总结：** 当您的工作流依赖于代码节点时，选择 n8n-decanter —— TypeScript，共享库，预飞行和代码级别的 git 历史记录，草稿优先发布。它利用 n8n 自己的 MCP 和技能进行所有结构操作，因此 n8n-as-code 仍然适用于完整工作流创作/生成和多环境操作，而原生编辑器则保留为实时可视画布，一切都同步回它。而 decanter 不会进行任何 LLM 调用 —— 您驱动它使用您已经运行的编码代理，因此 Claude Code 在 Claude 订阅上无需额外的 API 令牌。 ## 注意事项 - **MCP 底线和选择加入。** 同步路径需要带有内置 MCP 服务器的 n8n（~2.20+），MCP 访问权限在实例范围内启用，以及每个工作流的“可在 MCP 上使用”标志。没有该标志的工作流在 `list --remote` 和选择器中可见，但无法在您启用它们之前拉取 —— CLI 会告诉您开关的位置。`executions` 和 `data-tables` 仍使用公共 API 密钥（MCP 无执行读取和无数据表行读取）。复制和硬删除工作流是 n8n-UI 作业 —— API 时代的 `duplicate`/`delete` 动词被 `archive` 取代。 - **结构编辑不会从此处同步。** `workflow.json` 是只读快照：编辑它不会更改 n8n 中的任何内容， 下一次 `pull` 会覆盖它。在 n8n 本身中（或通过 n8n 自己的 MCP 工具）编排节点，改变 Code 节点的参数如 `mode`，并排列画布；decanter 动词（`rename`，`node create`，`node rename`）为您转发常见结构操作。 - **远程代码编辑被呈现，然后被覆盖。** 节点漂移保护在上次同步后实例上的 Code 节点更改时中止推送（ `--force` 覆盖）。拉取重新基准：`status --diff` 显示远程更改，`.ts` 源永远不会被触及， 下一次推送将存储库版本放回草稿 —— git 文件是代码的真实来源，按设计。 ## 节点文件的工作方式 节点源位于工作流文件夹内的 `code/` 子目录中，以 kebab-case 命名（`Parse Order` → `code/parse-order.js`）。旧版本的布局（文件夹根目录中的文件）在下一次 `pull` 时自动迁移。 - `code/<node>.js` —— 无损：拉取/推送字节相同。通过 JSDoc + `checkJs` 进行类型检查。**无 `import` 语句** —— 是的，`import` 是标准 JavaScript，但 `.js` 节点被原样推送到 n8n，其中 Code 节点无法加载模块；`check` 拒绝它。导入是 `.ts` 独有功能（推送时捆绑，下面的要点）。 - `code/<node>.ts` —— 单向：本地文件是真实来源。`push` 编译它（esbuild，注释剥离）并追加 `// @ts-n8n sha256:...` 标记行；`pull` 永远不会触及 `.ts`。要转换节点，请将 `code/<node>.js` 替换为 `code/<node>.ts` 并更改 `workflow.json` 中的 `//@file:` 占位符为 `.ts` 名称。转换回来也是如此（`.ts` → 普通 `.js` + 重新指向）；下一次推送清除远程标记 —— 再次拉取前先推送。 - `shared/*.ts` —— 帮助器和类型 **由 `.ts` 节点导入** （值和类型）；推送将导入捆绑到编译后的节点中，因此推送的代码是自包含的，可以在任何地方运行 —— 包括 n8n Cloud，无需 `NODE_FUNCTION_ALLOW_*` 设置。小 npm 包也以相同方式捆绑：在同步目录中安装它们，并在 `decanter.config.json` 中在 `"bundleDependencies"` 下列出它们（纯 JS 仅限；内置和未列出的包是编译错误，导入必须位于文件顶部）。`.js` 节点保持无导入 —— 该层按合同无字节损失。 推送拒绝覆盖自上次同步以来远程 **代码** 更改（`pull first` 或 `--force`）；远程 **结构** 更改永远不会阻止推送。拉取记录远程代码作为新的同步基准 —— 警告拉取后，推送 **将** 覆盖呈现的远程编辑，使用 `status --diff` + git 作为安全网。 推送还会运行一个 **合规保护**（独立：`check`，不需要凭证）：内联代码无 `//@file:` 占位符，占位符指向丢失/`.remote.js`/非 `.js`/`.ts` 文件或 `code/` 外的文件，`.js` 文件中的 `@ts-n8n` 标记，悬空连接源/目标，重复节点名称或 ID，无引用的孤立 `.js`/`.ts` 文件，以及悬空字面 `$('…')` 引用（在节点源和表达式参数中）都会中止推送 —— `--force` 不会绕过这些，仅限节点漂移保护。类型检查也会作为阻塞推送门控运行（ `--no-typecheck` 跳过；如果未找到 `tsconfig.json`，则自动跳过）。 **重命名节点** 通过 MCP 转发到 n8n —— `node rename <workflow> "<old>" "<new>"` 发出重命名（n8n 在服务器端重写连接和 `$('…')` 引用，节点 ID 保持稳定），重写本地 `.ts` 源，并拉取结果，以便文件和占位符跟随。 ## 浏览器实时重载（监视） 厌倦了每次推送后 ⌘R'ing n8n 编辑器？在 `decanter.config.json` 中添加 `"browserReload": "proxy"`，然后 `watch` 启动一个透明的开发代理，监听 `127.0.0.1:5679`（使用 `"proxyPort"` 覆盖）： ```json { "root": "./workflows", "workflows": ["…"], "browserReload": "proxy" } ``` 通过 **代理 URL** （`http://localhost:5679`）而不是真实端口打开 n8n 编辑器。代理将所有内容无触及地传输到您的 n8n 主机 —— 登录，资产和 n8n 的原生 `/rest/push` WebSocket —— 并将一个微小的重载客户端注入到编辑器页面。每次成功的 `watch` 推送都会为您刷新选项卡，**除非编辑器有未保存的更改**（它会拒绝重载并记录一个控制台警告，以免在浏览器中损坏任何内容）。如果端口被占用，`watch` 会警告并在没有实时重载的情况下继续同步。 基于原生 Node（无额外依赖）。它设计用于本地 HTTP n8n（`http://localhost:5678`）；指向 https/远程主机是尽力而为 —— 安全 cookie 在纯 HTTP 跳转中不会存活，因此身份验证可能无法传递。 ## 类型检查 n8n 代码节点源是一个函数体（顶级 `return` / `await`），普通 `tsc` 在 `.ts` 文件中拒绝（TS1108）。因此，`npm run typecheck` 运行 [scripts/typecheck.mts](scripts/typecheck.mts)，它在内存中将节点文件包装在一个 `async function` 中（`.decanter.json` 位于文件旁边 —— 或在 `code/` 目录的父目录中 —— 标记为节点文件），并将诊断映射回真实行号。IDE 自己的 tsserver 不应用包装器，因此它会单独标记顶级 `return` / `await`（TS1108/TS1375/TS1378）—— 这就是为什么 `init` 还会为 `decanter-ts-plugin/` 搭建一个语言服务插件，该插件在节点文件上恰好抑制这些代码，同时其他诊断保持实时。它在同步目录中通过工作区 TypeScript 加载（VS Code 提示 *使用工作区版本* 一次；JetBrains IDE 默认使用项目 TypeScript）。 CLI 自己的 `.mts` 源由 `tsc -p tsconfig.cli.json` 单独检查（严格；`npm run typecheck` 的前半部分）。该配置不是根 `tsconfig.json`，后者属于上述工作流节点文件。 *不隶属于或得到 n8n GmbH 的认可。*