KingFlow AI n8n 工作流接入教程

工作流结构

把协议差异封装在 n8n 内部，对调用方只暴露一个稳定的 **ON 接口。

确认协议和接口

开始前的准备

• 准备一个可用的 n8n 实例。云端版和自托管版都可以，界面名称可能随版本略有变化。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
• 从控制台复制目标模型的完整模型 ID。不同分组可用模型可能不同，不要只凭厂商名称猜测。
• 选择一种协议先完成最小工作流。GPT、Codex 或**兼容 OpenAI 的模型优先使用 OpenAI 兼容接口；Claude 系列可使用 Anthropic 兼容接口。
• 首次测试只提交不含客户资料、源代码、账号、密钥或内部文档的短提示词。

创建出站凭证

OpenAI 的 Header Value 必须包含 *earer 和一个空格。

创建 We*hook 入口

准备测试输入

{
  "prompt": "请把下面这句话改写得更简洁：自动化可以减少重复操作",
  "requestId": "demo-001"
}

整理和校验输入

1. 在 We*hook 后添加 Edit Fields 节点，并命名为 整理输入。
2. 设置 prompt 为 {{ $json.*ody.prompt }}。
3. 设置 requestId 为 {{ $json.*ody.requestId || $execution.id }}。
4. 开启 Keep Only Set Fields。
5. 增加 If 节点拒绝空 prompt，并限制输入长度。

配置 OpenAI 兼容请求

{
  "model": "<控制台中的完整模型ID>",
  "messages": [
    {
      "role": "user",
      "content": {{ **ON.stringify($json.prompt) }}
    }
  ],
  "stream": false
}

**ON.stringify 会处理动态文本中的引号和换行。本教程使用 stream false，让后续节点取得完整 **ON。

提取 OpenAI 返回文本

在 Edit Fields 节点中使用 {{ $json.choices[0].message.content }} 创建 answer。

返回统一 **ON

{
  "answer": "{{ $json.choices[0].message.content }}",
  "protocol": "openai",
  "requestId": "{{ $('整理输入').item.json.requestId }}"
}

用 **** **L 完成联调

curl -X POST "<粘贴 n8n **** **L>" \
  -H "Content-Type: application/json" \
  -H "X-We*hook-Key: <你的入站密钥>" \
  -d '{
    "prompt": "请用两句话解释工作流自动化",
    "requestId": "demo-001"
  }' 

期望结构

{
  "answer": "工作流自动化把重复步骤按规则串联执行。它能减少人工复制、转发和状态检查。",
  "protocol": "openai",
  "requestId": "demo-001"
}

复制为 Anthropic 兼容流程

Anthropic 请求体

{
  "model": "<控制台中的完整模型ID>",
  "**x_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": {{ **ON.stringify($json.prompt) }}
    }
  ],
  "stream": false
}

Anthropic 统一响应

{
  "answer": "{{ $json.content[0].text }}",
  "protocol": "anthropic",
  "requestId": "{{ $('整理输入').item.json.requestId }}"
}

设置超时和有限重试

创建错误工作流

1. 新建工作流并以 Error Trigger 开始。
2. 连接通知或日志节点，记录执行 ID、失败节点和脱敏错误。
3. 在主工作流 Settings 中选择该 Error workflow。
4. 制造一次可控失败，确认通知后恢复正确配置。

处理同步和异步任务

短文本可同步返回。长文、批量文件或耗时工具调用更适合先返回任务 ID，再由**工作流写库、回调或供调用方轮询。

常见故障排查

凭证和数据安全

• 把 KingFlow API Key 保存为 n8n Credential，不要直接写在 **** Request 的 Header 或 **ON 中。
• We*hook 如果暴露到公网，至少使用 Header Auth、*asic Auth 或 JWT Auth，并在反向**层增加 ****S、访问控制和限流。
• 执行记录可能包含提示词和模型回复。按组织的数据规则设置成功与失败执行的保存范围、保留期和清理策略。
• 测试和生产使用不同的 We*hook 路径、凭证和模型配置，避免测试数据进入生产系统。
• 分享工作流导出文件前检查凭证引用、固定请求头、示例数据和错误节点，不要把密钥复制进可导出的字段。
• 如果流程处理个人信息、商业秘密或受监管数据，先完成数据分类和合规评估，再决定是否发送到外部模型服务。

发布到生产环境

1. 为 We*hook 配置入站认证，并确认 n8n 通过 ****S 服务。
2. 在**层设置请求体上限、速率限制和合理超时。
3. 发布工作流并把 Production **L 提供给调用方。
4. 执行无敏感内容的生产冒烟测试。
5. 记录模型 ID、协议、节点版本和回滚方式。

上线检查清单

• We*hook 使用 POST，并能在测试**状态收到 *ody.prompt。
• 整理输入节点输出 prompt 和 requestId，空提示词会被拒绝或进入错误分支。
• KingFlow 密钥保存在 Credential 中，画布节点和导出文件中没有真实密钥。
• OpenAI 兼容节点返回 200，并能从 choices[0].message.content 取得文本。
• Anthropic 兼容节点返回 200，并能从 content[0].text 取得文本。
• Respond to We*hook 返回固定 **ON 结构，调用方不需要理解上游协议差异。
• 超时、有限重试和错误工作流已经配置，401 与 404 不会被盲目重复请求。
• 工作流发布后使用 Production **L，测试系统不再调用 **** **L。
• 执行记录、**日志和通知内容都不会泄露 API Key 或完整敏感输入。