feat(n8n): Added MCP-based AstronRPA Community Node public framework

[bbdu3]

目的和内容

提供独立的 AstronRPA Community Node，使自托管 n8n 能够通过 HTTPS MCP 读取已发布工作流、发起执行、等待结果、查询状态和请求取消。

本次建立节点接入所需的公共执行框架，统一工作流准入、幂等恢复、持久等待和错误处理。对于响应丢失、服务重启和工作流重新发布等情况，保持已受理执行的身份，避免因调用方重试产生重复业务执行。

验证范围为单实例自托管 n8n、单个持有客户端连接的 OpenAPI 实例，以及与仓库源码一致的 Windows 客户端。工作流声明采用 supportScope: controlled-validation。

🎯 变更类型 | Change Type

• ✨ 新功能 | New Feature

变更内容

1. 新增独立 Community Node 包

在 integrations/n8n/n8n-nodes-astron-rpa/ 中提供节点、凭据类型、构建配置、依赖锁文件、测试及示例工作流。

支持以下操作：

操作行为	行为
List Workflows	分页读取授权工作流及准入摘要
Get Workflow	读取发布版本、输入 Schema、声明和准入结果
Execute / Async	返回已受理的执行标识
Execute / Wait	持久等待同一执行的结果
Execute / Sync	使用相同执行链路，等待预算上限为 30 秒
Get Execution	查询执行状态、结果及安全错误信息
Cancel Execution	请求取消指定执行，通过查询确认实际终态

节点业务操作统一使用 MCP。凭据包含 HTTPS MCP 地址、API Key 和协议版本；连接测试仅进行发现及只读检查。

2. 实现幂等执行与持久等待

• 使用 n8n 公开的 executeWorkflow 和 putExecutionToWait 接口编排子执行及等待检查点。
• 派发前保存固定请求、声明 revision 和幂等键，避免恢复时重新计算业务输入。
• 自动幂等键按实例、n8n 执行、节点、运行轮次和输入项隔离；支持显式业务键进行跨执行恢复。
• 受理响应丢失时，使用原请求和原键进行有界恢复；取得执行 ID 后持续查询原执行。
• 区分网络请求超时、调用方等待预算和 RPA 执行期限。等待预算耗尽保留执行身份，不自动取消 RPA。
• 批量等待按顺序处理，保留输入项关联；前项状态未确认时阻止后项派发。
• 唤醒回调仅触发继续观察，业务结果始终通过 MCP 查询。

3. 增加服务端声明与统一准入

新增管理员维护的 INTEGRATION_POLICY_FILE 配置及声明校验。

声明包含工作流版本、输入 Schema 摘要、能力分类、文件输入输出、GUI／人工交互要求、环境、业务副作用、风险和执行类型等信息。完整声明摘要作为公开 revision，声明内容变化会使已准备的新请求失效。

在纳入管理的用户范围内，固定 MCP、动态 MCP 和 REST 共用准入检查，拒绝未知、不完整、失效或未批准的声明，以及不支持的文件传输请求。

同时新增只读工具 astron_integration_get，提供契约版本、操作列表和客户端就绪状态。

4. 修复已受理执行的管理行为

普通重新发布工作流后，原执行仍可查询、同键恢复和请求取消。

执行管理继续检查执行所有权、当前工作流所有权、外部访问状态及 API Key。工作流删除、外部访问停用或权限撤销仍会拒绝访问；新请求仍需满足当前版本和准入要求。

5. 完善错误处理与敏感信息保护

• 增加 resultVisibility，明确秘密输入导致结果被抑制的情况。
• 使用安全 JSON 错误封装，保留 n8n 原生错误路由中的执行 ID 和关联信息。
• 为执行查询和取消增加 UUID 前置校验。
• 保持正常 TLS 校验，拒绝 URL 内凭据及重定向。
• 将传输和 MCP 错误转换为安全错误码，避免复制原始异常、请求参数或凭据。

6. 补充并统一文档

提供节点使用说明、示例工作流、验收记录和结构化验证证据。

同步修正服务端文档中的工具列表、准入说明和重新发布后的执行权限描述，清理阶段编号、过程性叙述及与当前实现不符的字段说明。

本次代码变更集中于 OpenAPI 服务和独立节点包，客户端、Engine、Java 服务及数据库结构保持不变。

测试

自动化测试覆盖

范围	主要覆盖内容
OpenAPI 声明与准入	未声明拒绝、声明完整性、Schema／revision 变化、损坏配置拒绝、共享准入入口
执行管理与授权	并发幂等、重新发布后的原执行访问、权限撤销、用户隔离及外部接口安全
节点执行	原请求恢复、已知 ID 查询、等待预算、批量阻断、输入项关联及错误中的执行身份
持久等待	检查点状态恢复、派发前保存请求、唤醒回调忽略外部结果
MCP 传输	SDK 握手与发现、错误标准化、重定向拒绝、请求超时、协议和凭据前置校验
敏感信息	秘密参数处理、结果抑制及日志和错误脱敏

实际联调覆盖

已在真实 n8n、HTTPS MCP、OpenAPI 服务和 Windows 客户端链路验证：

• 全新 n8n 数据目录中的 tarball 安装、节点发现及独立进程再次加载。
• 有效、无效和吊销凭据，空工作流列表，客户端离线与忙碌。
• Async／Wait／Sync 执行、成功结果和业务失败。
• 顺序及并发同键请求、参数冲突、受理响应丢失后的同一执行恢复。
• 取得执行 ID 前后的 n8n 重启恢复，以及批量等待中重启。
• 等待预算到期、RPA 执行期限、重复取消及旧执行取消不影响新任务。
• OpenAPI 重启后的同一执行恢复。
• 客户端完整重启后保留原执行身份及 unknown / CLIENT_RESTARTED 状态，不自动重跑。
• 工作流版本元数据变化、完整设计器发布、新版本准入及发布后原执行管理。
• 秘密输入结果抑制、重复及迟到唤醒的结果安全。

测试结果

检查结果	结果
OpenAPI 相关回归	203 项通过
节点测试	19 项通过
节点构建、类型检查、ESLint、Prettier	通过
npm pack	通过
源码包及安装目录 npm audit	0 个漏洞
修改的 Python 文件格式检查	通过
修改涉及文件的 Ruff 检查	无新增问题，保留 3 项既有问题
文档链接、JSON 证据及差异格式检查	通过

未完成的验证

全仓 make check未通过。。frontend/缺少根tsconfig.json，npx tsc --noEmit` 输出帮助后失败；停止点之后的聚合检查未执行。