初始版本

2026-04-23 16:30:57 +08:00
commit 0d0683a6e6
538 changed files with 113042 additions and 0 deletions
--- a/public/docs/ai-agent.md
+++ b/public/docs/ai-agent.md
@@ -0,0 +1,284 @@
+# AI 智能体接入指南
+
+> 集成 OpenClaw AI Agent，实现知识库问答、工作流触发与多模型切换。
+
+## 🧠 什么是 AI 智能体？
+
+AI 智能体（AI Agent）是 Websopy 平台的核心能力，它能：
+
+- 🤖 基于自然语言理解用户意图
+- 📚 连接你的知识库进行精准问答
+- 🔗 触发业务工作流执行自动化任务
+- 🔄 在多个 AI 模型间智能切换
+
+## 📋 前提条件
+
+- 已完成 [快速上手](./quickstart.md)
+- 已开通 AI 功能（控制台 → 开发者中心 → AI 功能）
+
+## 🚀 接入步骤
+
+### 第一步：安装 AI SDK
+
+```bash
+npm install @websopy/ai-sdk
+```
+
+### 第二步：初始化 Agent
+
+```typescript
+import { AIAgent } from '@websopy/ai-sdk'
+
+const agent = new AIAgent({
+  apiKey: process.env.WEBSOPY_API_KEY,
+  // 选择默认模型
+  defaultModel: 'gpt-4',
+  // 可用模型列表
+  models: ['gpt-4', 'claude-3', 'gemini-pro']
+})
+```
+
+### 第三步：创建会话
+
+```typescript
+// 创建新的对话会话
+const session = await agent.createSession({
+  userId: 'user-123',
+  // 关联知识库（可选）
+  knowledgeBaseId: 'kb-abc456',
+  // 会话元数据
+  metadata: {
+    source: 'website',
+    language: 'zh-CN'
+  }
+})
+
+console.log('会话 ID:', session.id)
+```
+
+### 第四步：发送消息
+
+```typescript
+// 发送用户消息
+const response = await agent.sendMessage(session.id, {
+  content: '我想了解你们的产品价格',
+  // 可选：附加参数
+  context: {
+    userPlan: 'free',
+    priority: 'normal'
+  }
+})
+
+console.log('AI 回复:', response.content)
+console.log('使用模型:', response.model)
+console.log('置信度:', response.confidence)
+```
+
+### 第五步：流式响应（SSE）
+
+对于需要实时反馈的场景，使用流式输出：
+
+```typescript
+const stream = await agent.sendMessageStream(session.id, {
+  content: '写一篇关于 AI 的博客文章'
+})
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.content)
+}
+```
+
+## 📚 知识库集成
+
+### 创建知识库
+
+```typescript
+const kb = await agent.createKnowledgeBase({
+  name: '产品文档',
+  description: '公司产品相关文档',
+  // 向量化模型
+  embeddingModel: 'text-embedding-3-small'
+})
+
+// 上传文档
+await agent.uploadDocument(kb.id, {
+  file: './docs/product-guide.pdf',
+  // 文档元数据
+  metadata: {
+    category: 'documentation',
+    version: '2.0'
+  }
+})
+```
+
+### 关联知识库问答
+
+```typescript
+const response = await agent.sendMessage(session.id, {
+  content: '你们的退款政策是什么？',
+  // 强制从知识库检索
+  retrieveFrom: 'kb-abc456',
+  // 检索参数
+  retrievalConfig: {
+    topK: 5,          // 返回前 5 条相关片段
+    scoreThreshold: 0.7  // 相似度阈值
+  }
+})
+```
+
+## 🔧 工作流触发
+
+AI Agent 可以根据对话内容自动触发业务工作流：
+
+```typescript
+// 配置意图识别和触发
+await agent.setIntentHandler(session.id, {
+  intents: [
+    {
+      name: 'create_order',
+      patterns: ['下单', '购买', '创建订单'],
+      action: 'trigger_workflow',
+      workflowId: 'wf-order-create'
+    },
+    {
+      name: 'cancel_subscription',
+      patterns: ['取消订阅', '退订'],
+      action: 'trigger_workflow', 
+      workflowId: 'wf-subscription-cancel'
+    }
+  ]
+})
+
+// 处理工作流结果
+agent.onWorkflowComplete((result) => {
+  console.log('工作流完成:', result.workflowId)
+  console.log('结果:', result.output)
+})
+```
+
+## 🔄 多模型切换
+
+### 手动切换
+
+```typescript
+// 切换到指定模型
+await agent.switchModel(session.id, 'claude-3')
+
+const response = await agent.sendMessage(session.id, {
+  content: '解释量子计算原理'
+})
+```
+
+### 自动路由
+
+根据任务类型自动选择最优模型：
+
+```typescript
+const agent = new AIAgent({
+  apiKey: process.env.WEBSOPY_API_KEY,
+  // 配置自动路由
+  autoRoute: {
+    enabled: true,
+    rules: [
+      { task: 'coding', models: ['gpt-4', 'claude-3'] },
+      { task: 'creative', models: ['gpt-4', 'gemini-pro'] },
+      { task: 'analysis', models: ['claude-3', 'gpt-4'] }
+    ]
+  }
+})
+```
+
+## 📊 高级配置
+
+### 对话上下文管理
+
+```typescript
+// 设置上下文窗口大小
+agent.setContextWindow(session.id, {
+  maxMessages: 50,      // 保留最近 50 条消息
+  maxTokens: 8000       // 最大 token 数
+})
+
+// 手动添加系统提示
+agent.addSystemPrompt(session.id, {
+  role: 'system',
+  content: '你是一个专业的客服助手，说话风格友好、专业。'
+})
+```
+
+### 错误处理与重试
+
+```typescript
+const response = await agent.sendMessage(session.id, {
+  content: '复杂问题...'
+}, {
+  // 重试配置
+  retry: {
+    maxAttempts: 3,
+    delayMs: 1000,
+    backoff: 'exponential'
+  },
+  // 超时配置（毫秒）
+  timeout: 30000
+})
+```
+
+## 🧪 完整示例
+
+```typescript
+import { AIAgent } from '@websopy/ai-sdk'
+
+async function main() {
+  const agent = new AIAgent({
+    apiKey: process.env.WEBSOPY_API_KEY,
+    defaultModel: 'gpt-4'
+  })
+
+  // 创建会话
+  const session = await agent.createSession({
+    userId: 'user-123',
+    knowledgeBaseId: 'kb-product-docs'
+  })
+
+  // 对话循环
+  const messages = [
+    '你好，我想了解一下企业版的功能',
+    '支持私有化部署吗？',
+    '好的，我想试用一下'
+  ]
+
+  for (const msg of messages) {
+    const response = await agent.sendMessage(session.id, {
+      content: msg
+    })
+    console.log(`\n👤 用户: ${msg}`)
+    console.log(`🤖 AI: ${response.content}`)
+  }
+}
+
+main()
+```
+
+## ❓ 常见问题
+
+### Q: 如何查看 API 调用量？
+
+在控制台 → 开发者中心 → AI 功能，可以查看详细的使用统计。
+
+### Q: 支持哪些 Embedding 模型？
+
+目前支持：
+- `text-embedding-3-small`（推荐，速度快）
+- `text-embedding-3-large`（高精度）
+- `text-embedding-ada-002`（兼容性）
+
+### Q: 知识库检索不到相关内容？
+
+1. 检查文档是否已成功上传和向量化
+2. 调整 `scoreThreshold` 降低阈值
+3. 尝试增加 `topK` 获取更多候选
+
+---
+
+**上一步：** [5 分钟快速上手](./quickstart.md)  
+**下一步：** [私有化部署完全指南](./deployment.md)