ClaraVerse项目SDK CDN使用完全指南
2025-07-10 08:11:00作者：范靓好Udolf
前言
ClaraVerse项目提供了一个功能强大的流程执行SDK，可以通过CDN方式直接在浏览器环境中使用。本文将详细介绍如何通过CDN引入Clara Flow SDK，并展示其核心功能和使用方法。
CDN引入方式
推荐方案：使用unpkg CDN
<!-- 最新版本 -->
<script src="https://unpkg.com/clara-flow-sdk@latest/dist/clara-flow-sdk.umd.js"></script>
<!-- 指定版本 -->
<script src="https://unpkg.com/clara-flow-sdk@1.4.0/dist/clara-flow-sdk.umd.js"></script>
<!-- 压缩版本 -->
<script src="https://unpkg.com/clara-flow-sdk@latest/dist/clara-flow-sdk.umd.min.js"></script>
备选方案：使用jsDelivr CDN
<!-- 最新版本 -->
<script src="https://cdn.jsdelivr.net/npm/clara-flow-sdk@latest/dist/clara-flow-sdk.umd.js"></script>
<!-- 指定版本 -->
<script src="https://cdn.jsdelivr.net/npm/clara-flow-sdk@1.4.0/dist/clara-flow-sdk.umd.js"></script>
<!-- 压缩版本 -->
<script src="https://cdn.jsdelivr.net/npm/clara-flow-sdk@latest/dist/clara-flow-sdk.umd.min.js"></script>
核心概念解析
流程(Flow)结构
Clara Flow SDK的核心概念是"流程"，它由以下部分组成：
- 节点(Nodes)：执行特定功能的单元
- 连接(Connections)：定义节点间的数据流向
- 输入/输出：节点间的数据传递接口
节点类型详解
Clara Flow SDK提供了丰富的节点类型，涵盖多种功能场景：
输入/输出类节点
input：支持文本、JSON、数字和布尔值输入output：格式化显示结果image-input：处理Base64格式的图片pdf-input：从PDF文件中提取文本file-upload：通用文件上传，支持多种输出格式
数据处理类节点
combine-text：合并两个文本输入，可配置分隔方式json-parse：解析JSON并使用点表示法提取字段api-request：支持认证的HTTP/REST API客户端
逻辑控制类节点
if-else：基于JavaScript表达式的条件逻辑
AI功能类节点
llm：大型语言模型接口structured-llm：生成结构化JSON输出whisper-transcription：使用OpenAI Whisper进行音频转录
完整使用示例
1. 初始化SDK
<!DOCTYPE html>
<html>
<head>
<title>Clara Flow SDK示例</title>
</head>
<body>
<!-- 引入SDK -->
<script src="https://unpkg.com/clara-flow-sdk@latest/dist/clara-flow-sdk.umd.js"></script>
<script>
// 初始化流程执行器
const runner = new ClaraFlowSDK.ClaraFlowRunner({
enableLogging: true, // 启用日志
timeout: 30000 // 设置超时时间(毫秒)
});
</script>
</body>
</html>
2. 定义并执行简单流程
// 定义一个"Hello World"流程
const helloFlow = {
name: "Hello World流程",
version: "1.0.0",
nodes: [
{
id: "input-1",
type: "input",
data: {
label: "消息输入",
inputType: "string",
defaultValue: "你好"
}
},
{
id: "combine-1",
type: "combine-text",
data: {
mode: "space",
addSpaces: true
}
},
{
id: "output-1",
type: "output",
data: {
label: "结果"
}
}
],
connections: [
{
source: "input-1",
target: "combine-1",
sourceHandle: "output",
targetHandle: "text1"
},
{
source: "combine-1",
target: "output-1",
sourceHandle: "output",
targetHandle: "input"
}
]
};
// 执行流程
runner.executeFlow(helloFlow, {
"消息输入": "你好",
"combine-1": { text2: "世界!" }
})
.then(result => {
console.log('流程执行结果:', result);
})
.catch(error => {
console.error('流程执行错误:', error);
});
浏览器特有功能
文件上传处理
const fileInput = document.getElementById('file-upload');
// 处理文件上传为Base64
runner.handleFileUpload(fileInput.files[0], { outputFormat: 'base64' })
.then(base64Data => {
console.log('Base64格式文件:', base64Data);
});
// 处理文件上传为文本
runner.handleFileUpload(fileInput.files[0], { outputFormat: 'text' })
.then(textData => {
console.log('文本格式文件:', textData);
});
流程导入导出
// 导出流程为JSON文件
ClaraFlowSDK.BrowserUtils.downloadFlow(flowData, '我的流程.json');
// 从文件输入加载流程
const flowFileInput = document.getElementById('flow-file');
ClaraFlowSDK.BrowserUtils.loadFlowFromFileInput(flowFileInput)
.then(flow => {
console.log('加载的流程:', flow);
});
最佳实践建议
- 版本控制：生产环境建议使用特定版本而非latest标签
- 错误处理：始终处理Promise的reject情况
- 性能优化：复杂流程考虑分步执行
- 安全考虑：处理用户输入时进行适当验证
常见问题解答
Q: 如何判断SDK是否加载成功？ A: 检查全局ClaraFlowSDK对象是否存在：
if (typeof ClaraFlowSDK !== 'undefined') {
console.log('SDK加载成功');
}
Q: 流程执行超时怎么办？ A: 初始化时增加timeout配置：
const runner = new ClaraFlowSDK.ClaraFlowRunner({
timeout: 60000 // 60秒超时
});
Q: 如何获取浏览器环境信息？ A: 使用BrowserUtils工具：
const browserInfo = ClaraFlowSDK.BrowserUtils.getBrowserInfo();
console.log('浏览器信息:', browserInfo);
总结
通过本文，您已经了解了如何在浏览器环境中通过CDN使用ClaraVerse项目的流程执行SDK。从基础引入到复杂流程执行，Clara Flow SDK提供了强大而灵活的功能，能够满足各种自动化流程需求。建议从简单流程开始，逐步探索更复杂的使用场景。
