Claudable API开发：如何构建自定义AI代理服务接口
Claudable API开发：如何构建自定义AI代理服务接口
项目地址: https://gitcode.com/gh_mirrors/cl/Claudable Claudable是一个基于Next.js的开源AI应用构建平台，它集成了Claude Code、Cursor CLI、Codex CLI、Qwen Code和GLM-4.6等多种AI代理，让开发者能够通过自然语言指令快速构建和部署Web应用。本文详细介绍如何基于Claudable的API架构构建自定义AI代理服务接口，实现智能化的应用开发流程。
📋 Claudable API架构概览
Claudable采用现代Web应用架构，基于Next.js App Router构建，提供了完整的RESTful API和WebSocket实时通信能力。项目的主要API接口位于app/api/目录下，按照功能模块进行组织：
app/api/
├── chat/ # AI聊天和指令执行接口
├── projects/ # 项目管理接口
├── github/ # GitHub集成接口
├── vercel/ # Vercel部署接口
├── supabase/ # Supabase数据库接口
├── settings/ # 系统设置接口
└── assets/ # 文件资源管理接口
核心的AI代理服务接口位于app/api/chat/[project_id]/act/route.ts，这是Claudable与各种AI CLI代理交互的核心入口点。
🛠️ 核心API接口详解
AI指令执行接口
Claudable的核心功能是通过POST /api/chat/[project_id]/act接口执行AI指令。这个接口支持多种AI代理，包括Claude Code、Cursor CLI、Codex CLI等：
// 接口请求示例
{
"instruction": "创建一个任务管理应用，包含看板和拖拽功能",
"cliPreference": "claude", // 指定AI代理
"selectedModel": "claude-3-5-sonnet", // 指定模型
"images": [ // 支持图片附件
{
"name": "设计草图",
"base64_data": "data:image/png;base64,..."
}
],
"requestId": "req_123456" // 请求追踪ID
}
接口的主要功能包括：
- 多AI代理支持：根据
cliPreference参数选择不同的AI执行器 - 图片附件处理：支持Base64编码的图片上传和文件路径引用
- 会话管理：维护AI对话上下文和项目状态
- 实时状态推送：通过WebSocket推送执行进度和结果
项目初始化接口
当用户首次描述项目需求时，系统通过POST /api/projects接口创建新项目，并调用相应的AI代理初始化器：
// 项目创建示例
{
"project_id": "task-manager-2025",
"name": "任务管理应用",
"initialPrompt": "创建一个现代化的任务管理应用，包含看板视图和拖拽功能",
"preferredCli": "claude",
"selectedModel": "claude-3-5-sonnet"
}
🔧 AI代理服务实现
Claude Code代理集成
Claudable通过lib/services/cli/claude.ts实现了与Claude Agent SDK的深度集成。该服务处理以下关键功能：
- 指令解析和执行：将自然语言指令转换为具体的开发任务
- 文件操作管理：处理文件创建、编辑、删除等操作
- 实时状态更新：通过WebSocket推送执行进度
- 错误处理和恢复：确保AI代理执行的稳定性
// Claude代理执行流程
export async function executeClaude(
projectId: string,
projectPath: string,
instruction: string,
model: string = CLAUDE_DEFAULT_MODEL,
sessionId?: string,
requestId?: string
): Promise<void> {
// 1. 验证项目和路径安全性
// 2. 准备执行环境
// 3. 调用Claude Agent SDK
// 4. 处理流式响应
// 5. 更新项目状态
}
多代理调度系统
Claudable支持多种AI代理，每种代理都有对应的服务实现：
- Claude Code：lib/services/cli/claude.ts
- Cursor CLI：lib/services/cli/cursor.ts
- Codex CLI：lib/services/cli/codex.ts
- Qwen Code：lib/services/cli/qwen.ts
- GLM-4.6：lib/services/cli/glm.ts
📊 实时通信与状态管理
WebSocket实时推送
Claudable使用WebSocket实现实时通信，当AI代理执行指令时，客户端能够实时接收进度更新：
// WebSocket消息类型
interface WebSocketMessage {
type: 'message' | 'status' | 'error' | 'connected';
data: any;
}
// 状态更新示例
streamManager.publish(projectId, {
type: 'status',
data: {
status: 'processing',
message: '正在生成组件代码...',
requestId: 'req_123456'
}
});
工具使用跟踪
Claudable能够跟踪AI代理的工具使用情况，包括文件操作、命令执行等：
// 工具元数据示例
const toolMetadata = {
toolName: 'write_file',
action: 'Created',
filePath: 'app/components/TaskBoard.tsx',
summary: '创建任务看板组件'
};
🚀 自定义API扩展指南
步骤1：创建新的API路由
在app/api/目录下创建新的路由文件，例如app/api/custom/route.ts：
// 自定义API路由示例
import { NextRequest } from 'next/server';
import { createSuccessResponse, createErrorResponse } from '@/lib/utils/api-response';
export async function POST(request: NextRequest) {
try {
const body = await request.json();
const { projectId, action, data } = body;
// 调用自定义服务逻辑
const result = await customService.execute(projectId, action, data);
return createSuccessResponse(result);
} catch (error) {
return createErrorResponse('执行失败', error.message, 500);
}
}
步骤2：集成新的AI代理
如果需要集成新的AI代理，创建对应的服务文件：
// lib/services/cli/custom-agent.ts
export async function executeCustomAgent(
projectId: string,
projectPath: string,
instruction: string,
model: string,
sessionId?: string,
requestId?: string
): Promise<void> {
// 实现自定义AI代理逻辑
// 1. 调用AI代理API
// 2. 处理响应
// 3. 更新项目状态
// 4. 发送实时通知
}
步骤3：注册到路由调度器
在app/api/chat/[project_id]/act/route.ts中注册新的代理：
// 添加新的代理支持
const executor =
cliPreference === 'custom'
? executeCustomAgent
: cliPreference === 'codex'
? applyCodexChanges
: // ... 其他代理
🔒 安全与权限控制
项目路径验证
Claudable实现了严格的项目路径安全检查，防止目录遍历攻击：
// 路径安全检查
const allowedBasePath = path.resolve(process.cwd(), process.env.PROJECTS_DIR || './data/projects');
const relativeToBase = path.relative(allowedBasePath, absoluteProjectPath);
const isWithinBase = !relativeToBase.startsWith('..') && !path.isAbsolute(relativeToBase);
if (!isWithinBase) {
throw new Error(`安全违规：项目路径必须在 ${allowedBasePath} 内`);
}
文件上传安全
所有文件上传都经过严格的验证和路径处理：
async function mirrorAssetToPublic(
projectRoot: string,
filename: string,
sourcePath: string
): Promise<{ publicPath: string | null; publicUrl: string | null }> {
// 验证文件类型
// 生成安全文件名
// 复制到安全目录
}
📈 性能优化策略
流式响应处理
Claudable使用流式响应处理大型AI响应，避免内存溢出：
// 流式处理AI响应
for await (const message of response) {
if (message.type === 'stream_event') {
// 处理流式事件
streamManager.publish(projectId, {
type: 'message',
data: createRealtimeMessage({
projectId,
content: message.content,
isStreaming: true
})
});
}
}
请求去重处理
为了避免重复处理相同的工具调用，实现了签名去重机制：
const computeToolMessageSignature = (
metadata: Record<string, unknown>,
content: string
): string => {
// 计算消息签名用于去重
return [
metadata.toolName,
metadata.filePath,
metadata.action,
content
].join('|');
};
🎯 最佳实践建议
1. 错误处理与日志记录
始终在API端点中实现完整的错误处理：
export async function POST(request: NextRequest) {
try {
// 业务逻辑
} catch (error) {
console.error('[CustomAPI] 执行失败:', error);
// 发送错误通知
streamManager.publish(projectId, {
type: 'error',
error: error.message
});
return createErrorResponse('执行失败', error.message, 500);
}
}
2. 状态管理一致性
保持项目状态的一致性更新：
// 更新项目状态
await updateProject(projectId, {
activeClaudeSessionId: sessionId,
lastActivityAt: new Date()
});
3. 实时反馈优化
为用户提供清晰的执行状态反馈：
// 发送进度更新
publishStatus('processing', '正在分析项目结构...');
publishStatus('generating', '正在生成组件代码...');
publishStatus('deploying', '正在部署到预览环境...');
🚀 部署与监控
环境配置
确保正确配置环境变量：
# AI代理配置
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000
PROJECTS_DIR=./data/projects
# 数据库配置
DATABASE_URL=file:./data/cc.db
# 预览服务配置
PREVIEW_PORT_RANGE=3001-3010
监控指标
实现关键指标的监控：
- API响应时间：监控每个端点的平均响应时间
- AI代理成功率：跟踪各AI代理的执行成功率
- 并发请求数：监控系统负载情况
- 错误率：及时发现和处理系统错误
📚 总结
Claudable的API架构为构建自定义AI代理服务提供了强大的基础框架。通过深入理解其核心接口设计、多代理调度机制和实时通信系统，开发者可以轻松扩展新的AI代理功能，创建更加智能化的应用开发体验。
无论是集成新的AI模型、添加自定义工具链，还是优化现有工作流程，Claudable的模块化设计和清晰的接口规范都为你提供了坚实的基础。开始构建你的下一代AI驱动开发平台吧！
官方文档：docs/official.md
AI功能源码：plugins/ai/
这里是“一人公司”的成长家园。我们提供从产品曝光、技术变现到法律财税的全栈内容，并连接云服务、办公空间等稀缺资源，助你专注创造，无忧运营。
更多推荐
5
0- 0
已为社区贡献7条内容
所有评论(0)