curve-agent-sdk

Curve Agent SDK — 用于构建 AI Agent 服务的 Node.js / NestJS 工具包，提供消息处理、SSE 流式响应、协议封装、Prompt 管理、Skill 加载、调用链追踪等开箱即用的能力。

特性

• 消息处理 — 解析聊天参数、加载 & 归一化历史消息
• SSE 流式响应 — 一行代码设置 SSE Headers，流式写入数据块
• 协议层 — 统一的数据协议，内置 FileLink / ToolCall / Progress / SMILES / ECharts / Form 等富内容类型
• Prompt 管理 — 从文件系统加载 System Prompt
• Skill 管理 — 自动发现 storage/skills 目录下的技能
• 文件工具 — 路径解析、JSON 读写、文件拷贝等常用文件操作
• Agent 模块 — 一步完成 Tracer 创建 + onChunk 包装，简化 Agent 运行时初始化
• 中间件 — Tool Call 状态通知中间件，自动向流中写入工具调用进度

安装

npm install curve-agent-sdk
# 或
pnpm add curve-agent-sdk

环境要求

• Node.js >= 22.22.0
• 可选 peer dependencies：@langchain/core >= 1.1.39, langchain >= 1.3.0（使用 agent / middleware 时需要）

快速开始

import { curve } from 'curve-agent-sdk';

const parsed = curve.message.parseChatParams({
  message_id: 'msg-1',
  context_link: 'ctx-1',
  messages: [{ role: 'user', content: 'hello' }],
});

console.log(parsed.query); // "hello"

模块概览

所有功能通过唯一的 curve 实例访问：

import { curve } from 'curve-agent-sdk';

curve.message

| 方法 | 说明 | | --- | --- | | parseChatParams(params) | 校验并解析聊天请求参数，自动提取 query | | loadMessages(messages, options?) | 加载 & 归一化历史消息，支持 maxHistoryMessages 限制 |

curve.stream

| 方法 | 说明 | | --- | --- | | setupSSEHeaders(res) | 设置 Express Response 的 SSE 响应头 | | writeChunk(res, chunk) | 写入一个 SSE 数据块 | | writeDone(res) | 发送 [DONE] 并结束响应 | | writeError(res, error) | 写入错误信息 |

curve.protocol

| 方法 | 说明 | | --- | --- | | output(chunk) | 将 StreamChunk 转换为标准 CurveChunk | | toFileLinkChunk(...) | 生成文件链接协议块 | | toToolCallChunk(...) | 生成工具调用状态协议块 | | toProgressChunk(...) | 生成进度条协议块 | | toSmilesChunk(...) | 生成 SMILES 分子式协议块 | | toEChartsChunk(options) | 生成 ECharts 图表协议块 | | toFormChunk(schema, action?, title?) | 生成表单协议块 |

curve.prompt

| 方法 | 说明 | | --- | --- | | loadPrompt(filePath) | 从指定路径加载 Prompt 文件 | | systemPrompt() | 加载 storage/prompts/system.md |

curve.skill

| 方法 | 说明 | | --- | --- | | getSkillDirs() | 返回 storage/skills 下的技能目录路径 |

curve.file

文件系统常用操作：isExist, isFile, readJsonSync, writeJson, readFileString, resolvePath, copyFileSync, ensureDir 等。

curve.utils

通用工具方法：uuidv4, delay, parseJsonSilent, paramsException, commonException 等。

curve.agent

Agent 模块，通过 init() 一步完成运行时初始化。

| 方法 / 属性 | 说明 | | --- | --- | | init(onChunk?, options?) | 创建 tracer 并包装 onChunk，返回 { tracer, onChunk } | | loadTrace(traceId) | 加载指定 traceId 的持久化追踪数据 | | Tracer | AgentTracer 类引用 | | traceEventType | TraceEventType 枚举 |

import { curve } from 'curve-agent-sdk';

// 流式场景：一步创建 tracer + 包装 onChunk
const { tracer, onChunk } = curve.agent.init(_onChunk, { query: 'user question' });

// 非流式场景：只需 tracer
const { tracer } = curve.agent.init(undefined, { query: 'user question' });

// 加载历史追踪数据
const traceData = await curve.agent.loadTrace(traceId);

追踪数据自动持久化到 storage/cache/traces/ 目录。

curve.middleware

中间件模块，提供 Agent 运行时中间件。

| 方法 | 说明 | | --- | --- | | createToolMiddleware(tools) | 创建工具调用通知中间件，自动将 Tool Call 状态写入 SSE 流 |

import { curve } from 'curve-agent-sdk';

const middleware = curve.middleware.createToolMiddleware(tools);

项目约定

SDK 默认从 process.cwd() 下读取以下目录结构：

storage/
  prompts/
    system.md
  skills/
  cache/
    traces/

License

MIT