内容
# @kairos-sdk/core
[](https://github.com/Kruttz/kairos-sdk/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@kairos-sdk/core)
[](https://www.npmjs.com/package/@kairos-sdk/core)
**将普通英文转化为已部署的n8n工作流 — 验证、纠正和部署一步到位。**
Kairos 将普通英文工作流描述转化为已验证的可部署的n8n工作流JSON。使用它作为 **MCP服务器** （连接到Claude Code、Claude Desktop或任何MCP主机 — 您的LLM生成，Kairos验证和部署，无需Anthropic API密钥）或作为 **TypeScript SDK** 进行程序化控制（内部调用Claude并带有专用提示）。无论哪种方式，工作流都经过 **23规则结构验证器** 的验证，并带有自动纠正功能，本地工作流库使用 **混合检索** （TF-IDF +节点指纹 +结果历史记录 +集群重新排序）将过去的失败模式注入到未来的生成中。使用种子模板库，Kairos在20个基准提示中实现了 **100%的首次结构验证通过率** （这意味着生成的JSON在首次尝试时在结构上是有效的 — 运行时行为取决于您的凭证和节点配置）。
```ts
import { Kairos } from '@kairos-sdk/core'
const kairos = new Kairos({
anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
n8nBaseUrl: 'https://your-instance.app.n8n.cloud',
n8nApiKey: process.env.N8N_API_KEY!,
})
const result = await kairos.build(
'每天早上9点，向Slack的#daily-digest频道发送消息 "早上好，团队！"'
)
console.log(result.workflowId) // 已部署的工作流ID
console.log(result.credentialsNeeded) // 用户仍需配置的内容
```
### Kairos的功能和不保证的内容
| Kairos的功能 | Kairos不保证的内容（但正在努力） |
|---|---|
| 生成有效的n8n工作流JSON | 完美的业务逻辑 |
| 部署前验证结构（23条规则） | 正确的凭证 |
| 与您的实时实例同步节点类型 | 每个API的运行时成功 |
| 从以前成功构建中学习 | 每个工作流完全符合预期 |
| 通过MCP、SDK或CLI工作 | 完全取代人工审核 |
---
## 作为MCP服务器使用（无需代码）
将Kairos连接到任何与MCP兼容的主机 — Claude Code、Claude Desktop、Cursor或任何支持模型上下文协议的代理。您的主机LLM使用Kairos的专用上下文生成工作流，然后Kairos验证并部署它。无需Anthropic API密钥 — 无需双LLM调用，无需浪费令牌。Kairos自动同步您的n8n实例的节点类型，以便生成准确的工作流，以匹配您的确切设置。
### 设置
```bash
npm install -g @kairos-sdk/core
```
### Claude Code
将以下内容添加到您的Claude Code MCP配置（`~/.claude/claude_code_config.json`）：
```json
{
"mcpServers": {
"kairos": {
"command": "kairos-mcp",
"env": {
"N8N_BASE_URL": "https://your-instance.app.n8n.cloud",
"N8N_API_KEY": "your-n8n-key"
}
}
}
}
```
`N8N_BASE_URL`和`N8N_API_KEY`是所有MCP操作所需的。Kairos同步您的实例的节点类型，以生成准确的工作流，以匹配您的确切的n8n设置。
### Claude Desktop
将以下内容添加到您的Claude Desktop配置（`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS）：
```json
{
"mcpServers": {
"kairos": {
"command": "kairos-mcp",
"env": {
"N8N_BASE_URL": "https://your-instance.app.n8n.cloud",
"N8N_API_KEY": "your-n8n-key"
}
}
}
}
```
然后只需询问您的代理： *"为我创建一个工作流，用于监控Webhook并向Slack发送通知"* — 它将调用`kairos_prompt`获取上下文，生成工作流本身，使用`kairos_validate`验证，并使用`kairos_deploy`部署。
### MCP流程的工作原理
MCP服务器 **不** 调用LLM内部。相反，它为您的主机LLM提供专门的知识和防护措施，以生成n8n工作流：
1. **主机LLM调用`kairos_prompt`** — 获取n8n系统提示、节点目录、库匹配和失败模式
2. **主机LLM生成工作流JSON** 使用该上下文（无需单独的API调用）
3. **主机LLM调用`kairos_validate`** — 检查JSON的23条结构规则
4. 如果无效，主机LLM修复问题并再次验证
5. **主机LLM调用`kairos_deploy`** — 将验证后的工作流发送到n8n
这意味着Kairos与 **任何LLM** 配合使用 — Claude、GPT、Gemini、Llama或任何其他连接为MCP主机的LLM。无需Anthropic API密钥。
### 可用的MCP工具
#### 生成工具
| 工具 | 描述 |
|------|-------------|
| `kairos_prompt` | 返回给定描述的专用系统提示、节点目录、库匹配和失败模式 |
| `kairos_validate` | 验证工作流JSON的23条结构规则 — 返回错误和警告 |
| `kairos_search` | 在本地工作流库中搜索类似的过去构建 |
| `kairos_sync` | 手动刷新来自n8n实例的节点目录（在首次`kairos_prompt`调用时自动运行） |
#### 部署工具
| 工具 | 描述 |
|------|-------------|
| `kairos_deploy` | 将验证后的工作流JSON部署到n8n（部署前重新验证） |
| `kairos_list` | 列出所有已部署的工作流 |
| `kairos_get` | 通过ID获取完整的工作流JSON |
| `kairos_activate` | 激活工作流 |
| `kairos_deactivate` | 停用工作流 |
| `kairos_delete` | 删除工作流 |
| `kairos_executions` | 列出最近的执行状态 |
---
## 作为SDK使用
### 安装
```bash
npm install @kairos-sdk/core @anthropic-ai/sdk
```
`@anthropic-ai/sdk`是一个同级依赖 — 与Kairos一起安装。
---
## 要求
- Node.js 18+
- **SDK：**Anthropic API密钥 — SDK内部调用Claude
- **MCP：** 无需Anthropic密钥 — 您的主机LLM生成
- 已启用API访问的n8n实例（云或自托管）— SDK和MCP均需要（Kairos同步您的实例的节点类型以进行准确生成）
---
## 快速入门
```ts
import { Kairos } from '@kairos-sdk/core'
const kairos = new Kairos({
anthropicApiKey: 'sk-ant-...',
n8nBaseUrl: 'https://your-instance.app.n8n.cloud',
n8nApiKey: 'your-n8n-api-key',
})
// 干燥运行 — 生成并验证但不部署
const preview = await kairos.build(
'接收Webhook，调用外部API，并将结果存储在Google Sheets中',
{ dryRun: true }
)
console.log(preview.name) // 工作流名称，Claude选择
console.log(preview.generationAttempts) // 1–3（纠正循环）
console.log(preview.credentialsNeeded) // 需要配置的服务
// 实时部署
const deployed = await kairos.build(
'接收Webhook，调用外部API，并将结果存储在Google Sheets中'
)
console.log(deployed.workflowId) // 现在在n8n中上线
```
---
## 基准测试结果
针对20个不同复杂度的 工作流提示进行测试（简单的触发器，多步骤条件逻辑，带有内存的AI代理）。结果衡量 **结构验证通过率** — 生成的工作流是否通过所有23个验证器规则，而不是端到端执行正确性。
### 之前 vs 之后：模板种子库
| 指标 | 基线（无库） | 带有库（105个模板） | 增量 |
|---|---|---|---|
| **首次通过率** | 55%（11/20） | **100%（20/20）** | **+45pp** |
| 平均尝试次数 | 1.45 | **1.00** | -0.45 |
| 纠正循环使用率 | 45% | **0%** | -45pp |
| 平均生成时间 | 30.6s | **20.7s** | -32% |
| 失败次数 | 0 | 0 | — |
基线运行使用Claude和23规则验证器及纠正循环，但无库。种子运行使用相同的验证器加上包含105个工作流的库（16个有机 + 89个从n8n社区摄入）。更广泛的本地开发库现在包含286+生成/摄入的工作流。模板种子完全消除了纠正循环，并将生成时间缩短了三分之一。
> **注意：** 这些结果确认生成的工作流在结构上是有效的，可以部署到n8n。它们不验证运行时执行正确性、凭证配置或工作流输出是否与用户意图完全匹配。
---
## 工作原理
### SDK流程（内部调用Claude）
1. **搜索** — Kairos在其本地工作流库中搜索类似的过去构建。匹配的工作流及其失败模式被拉入上下文。
2. **警告** — 已知失败模式（来自库匹配和全局遥测率）被注入系统，以便Claude避免重复已知的错误。
3. **生成** — 您的描述被发送到Claude，带有详细的系统提示，强制调用`generate_workflow`工具，生成结构化的n8n工作流JSON。
4. **验证** — 工作流针对 **23条结构规则** 进行检查，涵盖节点ID、类型、版本、名称、位置、连接、 forbidden字段、触发器存在、AI连接方向、循环检测、Webhook配对和所需参数。
5. **纠正** — 如果验证失败，特定的规则违规被发送回Claude进行纠正（最多3次尝试，最后一次尝试温度更紧）。
6. **剥离** — 在部署前，剥离 forbidden的服务器分配字段（`id`、`createdAt`、`updatedAt`等）。
7. **部署** — 验证后的工作流通过REST API发布到您的n8n实例。
8. **记录** — 工作流、其元数据（生成模式、尝试次数、失败模式、所需凭证）和遥测事件被本地保存。未来的构建使用此历史记录以避免过去的错误。
### MCP流程（您的LLM生成）
1. **提示** — 您的LLM调用`kairos_prompt`，它搜索库并返回专用系统提示、节点目录、库匹配和失败模式。
2. **生成** — 您的LLM使用该上下文直接生成工作流JSON。无需单独的API调用。
3. **验证** — 您的LLM调用`kairos_validate`，它检查JSON的23条结构规则。
4. **纠正** — 如果验证失败，您的LLM修复问题并再次调用`kairos_validate`。
5. **部署** — 您的LLM调用`kairos_deploy`，它剥离forbidden字段并将工作流发布到n8n。
6. **记录** — 已部署的工作流被保存到本地库以供未来检索。
---
## 验证规则
23规则验证器是Kairos可靠性的核心。基线测试（无库）中，Claude需要纠正循环45%的时间。每个规则针对特定类型的错误：
| 规则 | 严重性 | 检查内容 |
|------|----------|----------------|
| 1 | 错误 | 工作流有一个非空名称 |
| 2 | 错误 | 至少存在一个节点 |
| 3 | 错误 | 每个节点都有一个非空ID |
| 4 | 错误 | 没有重复的节点ID |
| 5 | 错误 | 每个节点都有一个类型字符串 |
| 6 | 错误 | 每个节点都有一个有效的typeVersion |
| 7 | 错误 | 每个节点都有一个有效的[x, y]位置 |
| 8 | 错误 | 每个节点都有一个非空名称 |
| 9 | 错误 | connections是一个普通对象 |
| 10 | 错误 | 每个连接目标都存在于节点中 |
| 11 | 警告 | 非触发器节点有传入连接 |
| 12 | 错误 | 没有forbidden的服务器分配字段 |
| 13 | 错误 | settings是一个有效的对象 |
| 14 | 错误 | 至少存在一个触发器节点 |
| 15 | 错误 | 节点类型字符串匹配预期格式 |
| 16 | 错误 | 没有重复的节点名称 |
| 17 | 错误 | 凭证具有有效的id/name形状 |
| 18 | 错误 | AI连接源自子节点，而不是代理根节点 |
| 19 | 警告 | typeVersion在已知安全范围内 |
| 20 | 警告 | 没有连接循环（豁免splitInBatches循环） |
| 21 | 警告 | Webhook具有responseMode="responseNode"的respondToWebhook |
| 22 | 警告 | 已知节点类型所需的参数存在 |
| 23 | 警告 | 节点类型在注册表中被识别（未知类型可能在n8n中不存在） |
错误阻止部署。警告被记录并反馈到提示中以供未来构建。
---
## API参考
### `new Kairos(options)`
| 选项 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `anthropicApiKey` | `string` | ✓ | Anthropic API密钥 |
| `n8nBaseUrl` | `string` | ✓ | 您的n8n实例的基准URL |
| `n8nApiKey` | `string` | ✓ | n8n API密钥 |
| `model` | `string` | | 使用的Claude模型（默认：`claude-sonnet-4-6`) |
| `logger` | `ILogger` | | 自定义日志记录器（默认：静默） |
| `telemetry` | `boolean \| string` | | 启用JSONL遥测日志记录（`true`为默认目录，或路径） |
| `library` | `IWorkflowLibrary` | | 用于学习循环的工作流库（默认：`NullLibrary`，CLI使用`FileLibrary`） |
---
### `kairos.build(description, options?)`
从纯英文描述中生成并可选地部署工作流。
```ts
const result = await kairos.build(description, {
dryRun: false, // 设置为true以跳过部署
name: '我的工作流', // 覆盖生成的工作流名称
})
```
**返回 `BuildResult`:**
```ts
{
workflowId: string | null // dry run时为null
name: string
workflow: N8nWorkflow // 生成的工作流JSON — 部署前检查
generationAttempts: number // 1–3
activationRequired: boolean // 工作流需要手动激活
credentialsNeeded: Array<{
service: string
credentialType: string
description: string
}>
dryRun: boolean
}
---
### 工作流管理
```ts
// 列出所有工作流
const workflows = await kairos.list()
// 获取特定工作流
const workflow = await kairos.get(workflowId)
// 用新的描述替换工作流
const updated = await kairos.replace(workflowId, '新描述')
// 激活/停用
await kairos.activate(workflowId)
await kairos.deactivate(workflowId)
// 删除（需要显式确认）
await kairos.delete(workflowId, { confirm: true })
```
---
### 执行
```ts
// 列出工作流的最近执行
const executions = await kairos.executions(workflowId, { limit: 20})
// 获取特定执行并获取完整详细信息
const detail = await kairos.execution(executionId)
```
---
### 标签
```ts
const tags = await kairos.listTags()
const newTag = await kairos.createTag('production')
await kairos.tag(workflowId, [newTag.id])
await kairos.untag(workflowId, [newTag.id])
```
---
## 错误处理
所有错误扩展`KairosError`，因此您可以不同级别的具体性捕获它们：
```ts
import {
KairosError,
GenerationError,
ValidationError,
ApiError,
GuardError,
} from '@kairos-sdk/core'
try {
await kairos.build('...')
} catch (err) {
if (err instanceof ValidationError,
ApiError,
GuardError,
} from '@kairos-sdk/core'
try {
await kairos.build('...')
} catch (err) {
if (err instanceof ValidationError) {
// Claude未能生成有效的工作流，尝试次数达到最大限制（携带`.attemptMetadata`和`.warnedRules`）
for (const issue of err.issues) {
console.error(`[规则 ${issue.rule}] ${issue.message}`)
}
// 尝试元数据和警告规则也可用
console.log(err.attemptMetadata) // 尝试次数计时、令牌使用情况、问题
console.log(err.warnedRules) // 哪些模式规则被警告
} else if (err instanceof GenerationError) {
// Anthropic API 调用失败（身份验证、配额、超时）
console.error(err.message, err.cause)
} else if (err instanceof ApiError) {
// n8n 返回 4xx 或 5xx（携带 `.statusCode`）
console.error(`n8n 错误 ${err.statusCode}:`, err.message)
} else if (err instanceof KairosError) {
// 其他 SDK 错误
console.error(err.message)
}
}
```
| 错误类 | 抛出时机 |
|---|---|
| `GenerationError` | Anthropic API 调用失败 |
| `ResponseParseError` | Claude 响应但未产生可用的工具调用 |
| `ValidationError` | 工作流在最大重试次数后仍未通过 23 条验证规则（携带 `.attemptMetadata` 和 `.warnedRules`） |
| `ProviderError` | 与 n8n 交互时发生网络/身份验证失败 |
| `ApiError` | n8n 返回 4xx 或 5xx（携带 `.statusCode`） |
| `GuardError` | 输入验证失败（空描述）或 `delete()` 调用时未使用 `{ confirm: true }` |
---
## CLI
通过命令行部署工作流 — 无需代码：
```bash
# 生成并部署
kairos build "每天早上9点，向Slack的#daily-updates频道发送消息"
# 仅进行干燥运行
kairos build "监控Webhook并记录有效载荷" --dry-run
# 使用n8n社区模板填充库
kairos sync-templates --max 200
# 查看模式分析
kairos patterns
kairos patterns --days 60 --json
# 管理工作流
kairos list
kairos get <workflow-id>
kairos activate <workflow-id>
kairos deactivate <workflow-id>
kairos delete <workflow-id> --confirm
```
设置您的凭证为环境变量：
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export N8N_BASE_URL=https://your-instance.app.n8n.cloud
export N8N_API_KEY=your-n8n-key
```
在干燥运行模式下，仅需 `ANTHROPIC_API_KEY` — 无需n8n设置。
---
## 遥测
启用遥测以将每次生成尝试、验证结果和令牌使用情况记录到 JSONL：
```ts
const kairos = new Kairos({
anthropicApiKey: '...',
n8nBaseUrl: '...',
n8nApiKey: '...',
telemetry: true, // 写入 ~/.kairos/telemetry/
})
```
或指定自定义目录：
```ts
telemetry: '/path/to/telemetry/dir'
```
每个事件都包含时间戳、会话ID、令牌计数、验证问题和持续时间 — 有助于基准测试和分析纠正循环。
每个事件包括时间戳、会话ID、令牌计数、验证问题和持续时间 — 有助于基准测试和分析纠正循环。
### Pattern Learning
启用遥测后，Kairos 运行一个**模式分析器**，从每次构建中学习——成功和失败。分析器生成 `patterns.json`，并将其反馈到未来的构建中：
- **综合评分** — 模式通过 `rawConfidence × impact × recency × (1 + stickinessBoost)` 进行评分，因此频繁、最近、粘性的失败优先级最高
- **粘性检测** — 在连续失败重试尝试中持续存在的规则（LLM 无法自我纠正）会获得评分提升
- **状态生命周期** — 模式从 `draft → confirmed → resolved` 进展，具有每个规则的已解决阈值（5 次干净构建）和已解决模式的 90 天 TTL
- **回归检测** — 如果已解决的规则再次开始失败，它将被标记为回归，并在提示中优先处理
- **警告有效性** — 跟踪关于规则的警告是否 действительно 防止了失败，具有每个规则的通过/失败率
- **模式迁移** — 模式数据自动跨版本迁移（目前为 v2），因此在升级过程中不会丢失累积的知识
- **规则共现** — 确定通常一起失败的规则对（例如，规则 5 和 17 总是同时出现问题）
- **会话深度分析** — 跟踪每个会话所需的尝试次数（例如，80% 的会话只需要 1 次尝试，15% 需要 2 次，5% 需要全部 3 次）
- **警告上限** — LLM 提示中的最大模式数量为 10，优先级为：回归 > 已确认 > 草稿
- **分析历史** — 每次分析运行都会将摘要追加到 `pattern-history.jsonl` 中，以便随时间推移跟踪趋势
运行 `kairos patterns` 以查看当前分析，或运行 `kairos patterns --json` 以获取原始输出。
对于 CLI 使用，在环境中设置 `KAIROS_TELEMETRY=true`。
## 工作流库和反馈循环
Kairos 包含一个基于文件的**工作流库**，它存储每次生成并将失败模式反馈到未来的构建中：
```ts
import { Kairos, FileLibrary } from '@kairos-sdk/core'
const kairos = new Kairos({
anthropicApiKey: '...',
n8nBaseUrl: '...',
n8nApiKey: '...',
library: new FileLibrary(), // 存储在 ~/.kairos/library/ 中
telemetry: true, // 启用失败率跟踪
})
```
**每项工作流存储的内容：**
- 完整的工作流 JSON 和描述
- 生成模式（`direct`、`reference` 或 `scratch`，基于库匹配质量）
- 生成尝试次数
- 失败模式 — 验证规则失败以及失败次数
- 源工作流 ID（哪些库条目影响了此次构建）
- 最高匹配分数和所需凭证
- 结果跟踪：检索次数，作为直接/参考源的使用次数，首次尝试通过率，平均尝试次数，以及作为源时失败的规则
**检索工作原理：**
Kairos 使用具有四个评分信号的**混合检索**管道，并对其进行加权和组合：
| 信号 | 权重 | 捕获内容 |
|---|---|---|
| TF-IDF 关键词 | 0.35 | 描述和存储的工作流之间的文本相似性 |
| 节点指纹 | 0.30 | 预期节点类型（从查询中提取）与存储的工作流中的实际节点之间的 Jaccard 相似性 |
| 结果历史 | 0.20 | 工作流作为源时的首次尝试通过率和平均尝试次数 — 经过验证的模板排名更高 |
| 部署频率 | 0.15 | 工作流部署的频率 — 用作有用性的代理 |
在混合评分后，结果会**按集群重新排序**：工作流按节点指纹模式分组（例如，webhook→slack，scheduleTrigger→httpRequest→gmail），集群级别的成功统计数据会提升或惩罚候选工作流。具有高失败率的集群会在特定规则上显示警告。
- 高评分匹配（>= 0.92）提供直接的结构化模板
- 中等匹配（>= 0.72）提供参考示例
- 匹配工作流的失败模式和集群级别的警告被注入 Claude 的提示中
**模板播种：** 运行 `kairos sync-templates` 以从 n8n 社区库中导入已验证的工作流。模板经过安全过滤（阻止 code/executeCommand/ssh 节点，硬编码秘密），并标记为 `sourceKind: 'n8n-template'`。在基准测试中，使用 89 个模板播种库将首次尝试通过率从 55% 提高到 100%。
CLI 自动启用库 — 无需配置。
## 自定义日志记录器
```ts
const kairos = new Kairos({
anthropicApiKey: '...',
n8nBaseUrl: '...',
n8nApiKey: '...',
logger: {
debug: (msg, meta) => console.debug(msg, meta),
info: (msg, meta) => console.info(msg, meta),
warn: (msg, meta) => console.warn(msg, meta),
error: (msg, meta) => console.error(msg, meta),
},
})
```
## 支持的 n8n 节点类型
Kairos 默认支持 60 多种 n8n 节点，包括：
- **触发器：** Webhook、计划、聊天、手动、电子邮件、GitHub、Telegram
- **核心：** HTTP 请求、设置、如果、切换、合并、代码、等待
- **应用程序：** Slack、Gmail、Google Sheets、Notion、Airtable、GitHub、Telegram
- **数据：** PostgreSQL、Redis、S3、执行 SQL
- **AI（LangChain）：** 代理、OpenAI 聊天模型、Anthropic Claude 模型、缓冲区内存、工具工作流、向量存储检索器
## 许可证
MIT — © 2026 Jordan Krutman
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器