n8n-as-code
让 AI 在编辑器中安全构建、验证、同步和运维 n8n 工作流。
证据显示同步操作需显式执行，promotion 提供 dry-run 和 no-push，工作区配置与机器本地密钥分离，API 密钥支持经 stdin 输入；集成测试还验证 MCP 令牌不会写入仓库配置、删除实例会移除对应密钥，因此敏感数据处理和外部效果控制证据充分。权限最小化与用户确认被扣分，因为材料未展示运行时权限声明、逐项高风险操作确认或完整授权模型；回滚主要依赖 Git、冲突解决和 promotion 绑定记录，未展示远端变更的事务性撤销。依赖安全仅有版本约束、依赖对齐检查和私密漏洞报告流程，未见锁文件、漏洞扫描、供应链固定或已知漏洞处置证据。项目独立性、作者版权和上游 n8n/community 归属说明清楚，故来源归属满分。
README、命令设计、V4 配置测试、CI 构建与生成技能一致性检查形成较强的内部一致性证据。依赖可用性被明显扣分：构建会动态获取最新稳定 n8n 内容，CI 使用 npm install 且明确说明 package-lock.json 被忽略，多个 GitHub Actions 仅固定到主版本标签，无法从静态材料保证可重复取得同一依赖。错误处理有明确的旧配置拒绝信息、缺失工作流和 API 失败路径以及生成文件漂移诊断，但所给测试助手中的不少错误仍是笼统的 API Error 或 SyncManager Error，故未满分。
材料覆盖 VS Code、Cursor、Claude Code、通用 Agent、CLI、OpenClaw、外部和本地 n8n 环境，并解释开发、同步、验证、promotion 与调试场景，因此受众、场景和环境适配证据充分。工具边界明确区分 n8nac env、workspace 与 n8n-manager，并说明独立项目及 n8n 版本兼容边界。触发精度被扣分，因为仅说明 n8n-architect 会按需处理设置、上下文、验证和同步，未提供其实际技能指令或展示代理如何区分只读、写入、激活、执行等意图。
README 的快速开始、命令分组、包职责和组件关系组织清晰，四类安装路径均有可操作命令；MIT 正文与元数据一致，故信息架构、安装和许可证满分。命名整体稳定，但 README 同时出现 n8n-as-code、n8nac、n8n-manager、Agent Skills/MCP 和多种插件形态，且根包 bin 名称与主要 CLI 名称不同，增加理解成本。示例丰富但没有内嵌 FAQ；已说明 n8n 最新稳定版兼容要求、独立项目身份和第三方工作流许可，但缺少更完整的限制清单。版本 0.2.0、发布脚本和插件版本一致性检查可见，但未提供 changelog 或兼容升级记录。维护者版权、贡献与安全报告路径明确，不过 author 字段为空、漏洞邮箱未具体列出且发布责任未细化，因此维护责任未满分。
输出可直接进入版本控制的 TypeScript 工作流，并提供转换、校验、同步、冲突解决、状态 JSON 和 dry-run 计划，静态证据显示产物具有较高可用性。相较手工维护 n8n JSON，集中提供节点知识、模板检索、类型化编辑和多环境 promotion 具有明确增量价值。成本收益被扣分，因为完整构建依赖 Node 22、多个包、动态 n8n 缓存、文档下载和生成步骤，且使用真实 n8n 的安装、升级、凭据与运维成本没有量化；537 节点和 7,700+ 模板等规模主张也未在所给文件中直接核验。
不少主张可对应到具体命令、包表、CI 检查和配置集成测试；密钥隔离、V4 配置持久化、删除清理和生成技能一致性获得跨 README、测试及 CI 的相互印证，因此交叉佐证较强。主张可追踪性被扣分，因为描述中的 537 节点、7,700+ 模板以及安全工作方式没有随附静态清单或计数证据，CI 徽章也不能在本次静态审查中证明该修订实际通过。事实与推断大体分开，并明确标注独立项目和兼容性建议，但营销性表述如 safely、full n8n development workspace 和 grounded 未给出严格定义或覆盖范围，故未满分。
- 本评估仅依据所给静态文件，未执行构建、测试、插件、CLI 或真实 n8n 操作。
- 在生产环境使用 push、promote、activate、run tests、tunnel 或实例删除前，应确认目标环境、权限范围、凭据隔离、备份和恢复步骤。
- 依赖安装缺少已提交锁文件，构建还会获取动态 n8n 内容；部署前应固定依赖与上游版本并执行漏洞和供应链审查。
- 不要仅凭 README 接受 537 个节点、7,700+ 模板或广泛安全性主张；应在目标修订中核对生成资产、清单和覆盖测试。
- 项目要求 n8n 接近最新稳定版；较旧实例可能产生生成或验证偏差，应先在隔离环境验证兼容性。
- 发布者未获 FollowAgents 企业注册表验证；这表示身份未知而非可疑，应通过仓库签名、发布来源和维护渠道另行核验。
这个 Agent 能做什么，适合哪些场景？
n8n-as-code 是一套面向 n8n 的开发与运维工具，由 VS Code/Cursor 扩展、n8nac CLI、Agent Skills、n8n-manager 和 TypeScript 转换器组成。它把代码仓库变成 n8n 工作区，让用户和 AI 助手能够读取节点知识、编辑工作流、执行验证，并在明确指令下与选定的 n8n 环境同步。工作流可以保存为可读的 .workflow.ts 文件，通过 Git 审查差异和解决冲突，再推送到远程或本地托管的 n8n 实例。环境连接信息属于仓库上下文，而 API 密钥、机器本地实例状态等敏感运行数据留在本机。它适合希望用代码审查、环境晋升和编辑器内操作管理 n8n 的团队，但要求现有 n8n 环境尽量跟随最新稳定版，以匹配项目内置的节点模式。
用户先通过 n8nac env add 定义远程 n8n URL 或 n8n-manager 托管实例，再用 n8nac env auth set 写入 API 密钥并通过 n8nac env use 选择活动环境。n8nac update-ai 生成供 AI 使用的模式、示例、节点知识和验证上下文；n8nac skills search、node-info 与 validate 分别检索模板和知识、检查节点信息及验证 .workflow.ts 文件。同步过程是显式的：n8nac list 查询工作流，pull 将指定工作流拉入仓库，push --verify 验证并推送文件，resolve 处理冲突。promote 可在 Dev、Prod 等环境的 workflowsPath 之间迁移单个或全部 TypeScript 工作流，重写目标项目元数据、映射凭据和受支持的 Execute Workflow 引用，并在 n8nac-promotion.json 中记录稳定绑定；--dry-run 只生成计划，不写文件或推送。@n8n-as-code/transformer 负责在 n8n JSON 与使用 @workflow、@node、@links 装饰器的 TypeScript 类之间转换，VS Code/Cursor 扩展则提供侧边栏、画布和 Agent Workbench。
- 使用 VS Code 或 Cursor 的自动化工程师，希望在编辑器中浏览、修改、验证并同步真实 n8n 工作流。
- 需要将 n8n 工作流纳入 Git 审查的团队，希望显式拉取和推送文件、比较差异并解决同步冲突。
- 维护 Dev 与 Prod 环境的平台团队，需要先用 --dry-run 查看创建或更新计划，再执行带凭据和子工作流引用映射的环境晋升。
- 希望 AI 助手生成可靠 n8n 配置的开发者，需要为助手提供节点模式、示例、模板和验证规则，而不是只依赖通用模型知识。
- 偏好代码式维护的 n8n 用户，希望把 JSON 转换成更便于人工与 AI 修改的 .workflow.ts 类，再转换或部署。
- 需要本地 n8n 沙箱的开发者，希望用 n8n-manager 创建、启动、停止实例并管理隧道，同时让 n8nac 保持仓库级环境状态。
这个 Agent 有哪些优点和局限？
- 覆盖 537 个节点的完整模式并提供 7,700 多个模板，可为 AI 生成和验证提供具体的 n8n 上下文。
- 同时提供编辑器扩展、CLI、可移植 Skills、OpenClaw 插件和转换器，既能服务交互式开发，也能用于终端自动化。
- 同步默认是显式操作，并提供 --verify、冲突处理和 --dry-run，便于在推送或环境晋升前审查影响。
- TypeScript 工作流使用明确的 @workflow、@node 和 @links 结构，比原始 JSON 更适合代码审查和代理编辑。
- 环境晋升不仅复制文件，还会处理目标项目元数据、凭据映射和受支持的 Execute Workflow 引用。
- 内置节点模式基于最新稳定版 n8n；较旧实例可能产生生成或验证兼容性问题，因此采用方需要维护版本同步。
- 远程环境需要网络连通性和 n8n API 密钥，本地托管模式还引入 n8n-manager 及机器级实例生命周期管理。
- Claude Code 插件仍标记为 Beta / Pending Review，不能视为已完全稳定或正式审核的集成。
- 晋升会重写元数据并映射凭据与工作流引用；尽管提供 dry-run，复杂环境仍需人工核对映射结果。
- 项目是独立社区项目，与 n8n 无隶属、背书或赞助关系；团队需自行评估支持和升级风险。
如何安装或部署这个 Agent？
编辑器路径：从 VS Code Marketplace 安装 etienne-lescot.n8n-as-code，或从 Open VSX 安装同名扩展；打开文件夹或 .code-workspace，在扩展界面中配置工作区，创建或选择 n8n environment。CLI 路径无需文档中的全局安装步骤，可直接使用 npx：
npx --yes n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev
printf '%s' "$N8N_API_KEY" | npx --yes n8nac env auth set Dev --api-key-stdin
npx --yes n8nac env use Dev
npx --yes n8nac update-ai这一路径需要可访问的 n8n URL 和 N8N_API_KEY。若使用本地托管实例，先运行 n8n-manager instance list，再执行：
npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use LocalClaude Code 集成标记为 Beta / Pending Review，安装命令为：
/plugin marketplace add https://github.com/EtienneLescot/n8n-as-code
/plugin install n8n-as-code@n8nac-marketplace如何使用这个 Agent？
先检查活动环境是否就绪：
npx --yes n8nac env status --json
npx --yes n8nac list拉取并编辑一个工作流，然后验证和推送：
npx --yes n8nac pull <workflow-id>
npx --yes n8nac skills validate workflows/dev/my-workflow.workflow.ts
npx --yes n8nac push workflows/dev/my-workflow.workflow.ts --verify在环境间晋升前先预演：
npx --yes n8nac promote --from Dev --to Prod --dry-run确认计划后去掉 --dry-run 执行默认的文件处理和推送。若需要把现有 JSON 转为 TypeScript，可运行 n8nac convert workflow.json --format typescript；目录批量转换使用 n8nac convert-batch workflows/ --format typescript。所有拉取和推送均需显式执行，工具不会自动同步。
这个 Agent 与同类方案有什么区别？
与直接在 n8n 界面中维护工作流相比，n8n-as-code 增加了仓库内的 TypeScript 表示、显式 pull/push、Git 差异审查、冲突处理和跨环境晋升。VS Code/Cursor 扩展负责可视化工作区和 Agent Workbench，n8nac 负责仓库级环境、验证与同步，n8n-manager 则只负责本地实例、Docker 生命周期、隧道及机器本地资源；两者不能互相替代为工作区状态来源。