n8n-nodes-skopon-cloud-cli

Skopon CloudCLI 是一个面向 Skopon/HiBot 工作流的 n8n 社区节点。它使用 mission 级 HiBot IAM Token 提交异步 AgentRun，随后进入 n8n Waiting 状态，直到 HiBot 的可靠回调返回最终结果。

节点不会直接登录 CloudCLI，也不会接收 CloudCLI 用户名和密码。租户、项目、成员、Agent 与 Session 身份全部由 HiBot 根据 IAM Token 和 mission 数据确定。

安装

在 n8n 社区节点设置中安装：

n8n-nodes-skopon-cloud-cli

或在 n8n 环境中执行：

npm install n8n-nodes-skopon-cloud-cli

安装后重启 n8n。

使用

节点默认与其他 Skopon 节点约定一致：

• Env：={{ $('start').item.json.env }}
• IAM Token：={{ $('start').item.json.token }}
• Request ID：={{ $('start').item.json.request_id }}
• Mission ID：={{ $('start').item.json.mission_id }}

2.x 使用一个 AgentRun JSON 参数定义完整任务：

{
  "objective": "分析输入文件并生成中文总结",
  "inputs": {
    "language": "zh-CN",
    "files": [
      {
        "url": "https://cdn.example.com/report.pdf",
        "name": "report.pdf",
        "mimeType": "application/pdf",
        "category": "document"
      }
    ]
  },
  "expected_outputs": [
    {
      "name": "summary.md",
      "type": "text/markdown"
    }
  ],
  "preferred_skill": "",
  "effort": "high"
}

顶层只允许 objective、inputs、expected_outputs、preferred_skill 和 effort。objective 必填；未知字段以及 request、mission、callback、tenant、user、project、member、agent、session 等受控字段都会被拒绝。

节点向以下地址提交请求：

POST /{dev|prod}/hibot/agent/internal/n8n/agent-runs

HiBot 返回成功的 2xx 状态后，节点进入 Waiting；响应体可以为空，非空响应体必须是 JSON 对象且不能包含显式失败标志。AgentRun 完成、失败或取消后，HiBot 回调 n8n 的 resume URL，节点输出 agent_run.terminal 事件。

API Host 默认使用 HTTPS。Allow Insecure HTTP 默认关闭；只有可信本地或私有开发网络确实需要明文 HTTP 时才应显式开启。开启后 mission IAM Token 将失去传输加密保护。

节点会对网络中断、超时和可恢复 HTTP 状态执行最多两次短暂重试。重试复用完全相同的 payload 与 callback URL，不会创建不同的 AgentRun 请求。跨 n8n 执行的重试仍受 HiBot callback URL 幂等策略限制。

Output Parser

开启 Require Specific Output Format 后，节点会显示一个 Output Parser AI 连接端口。连接 Parser 后，节点会把 Parser 的格式说明附加到发送给 HiBot 的 objective；AgentRun 成功完成时，再使用同一个 Parser 解析回调中的 summary。

解析成功后，完整原始回调会被保留，结构化结果写入 parsed_output。failed 和 cancelled 回调不会执行 Parser。缺少 Parser、completed 回调没有非空 summary，或者 Parser 解析失败时，节点会明确报错。

Structured Output Parser 负责提取 JSON 并校验结构，本身不会调用模型重写错误内容。需要自动修复格式时，应使用 Auto-fixing Output Parser 并为它连接语言模型。

远程文件

在 AgentRun JSON 的 inputs.files 中可传入最多 20 个公网 HTTP(S) 文件 URL，包括图片、音频、视频、PDF、Office 文档、压缩包、代码和数据文件。节点不会在 n8n 内下载、缓存、转码或上传文件。

{
  "objective": "总结报告",
  "inputs": {
    "files": [
      {
        "url": "https://cdn.example.com/report.pdf",
        "name": "report.pdf",
        "mimeType": "application/pdf",
        "category": "document"
      }
    ]
  }
}

远程文件必须在 AgentRun 执行期间保持有效，并能由 Agent 沙箱访问。它们是 AgentRun 可下载的文件资源，不会自动转成模型原生的图片、音频或视频 content block。签名 URL 会保存在 n8n 执行参数中，请按敏感数据处理。

节点拒绝非 HTTP(S) URL、URL 内嵌用户名密码、localhost、环回地址及明确的私网 IP。域名不会由节点预先解析；生产环境仍应通过 Agent 沙箱出口策略限制可访问域名。

从 1.x 升级

2.0.0 是破坏性升级。旧的 Objective、Inputs、Remote Files、Expected Outputs、Preferred Skill 和 Effort 参数已删除，1.x 工作流必须将这些值合并到 AgentRun JSON 后再执行。节点不会自动读取或迁移旧参数，避免错误地静默执行不完整任务。

HiBot 部署要求

• 配置 N8N_AGENT_RUN_CALLBACK_ORIGINS，包含 n8n 对外 origin。
• 生产 callback URL 必须使用 HTTPS。
• n8n 必须可被 HiBot 访问。
• 如果 E2B 开启 egress_default_deny，远程文件域名必须加入出口允许列表。

输出

completed、failed 和 cancelled 都作为正常 JSON 输出，便于使用 IF 或 Switch 节点分支：

{
  "event_id": "agent-run-...",
  "event_type": "agent_run.terminal",
  "request_id": "request-123",
  "mission_id": 456,
  "run_id": "...",
  "status": "completed",
  "summary": "...",
  "parsed_output": {
    "title": "..."
  },
  "changed_files": [],
  "usage": {},
  "error": null
}

parsed_output 仅在开启 Require Specific Output Format、状态为 completed 且 Parser 成功时出现。

提交阶段的鉴权、校验或网络错误仍会使节点失败。每次执行只接受一个输入 item。

开发

npm install
npm test
npm run lint
npm pack --dry-run

发布新版本时先提交代码并确保位于干净的 main 分支，然后运行 npm run release。推荐通过 GitHub Actions 发布以携带 npm provenance。仅需直接发布到 npmjs、且不需要 n8n Cloud 验证时，可运行 npm run publish:npm。