新版官网模板

2026-04-29 01:33:33 +08:00
commit 0d82386f8f
341 changed files with 64526 additions and 0 deletions
--- a/content/docs/ai/agent.md
+++ b/content/docs/ai/agent.md
@@ -0,0 +1,171 @@
+---
+title: AI 智能体接入
+description: 集成 AI Agent，实现知识库问答、工作流触发与多模型切换。
+category: ai
+order: 1
+---
+
+# AI 智能体接入
+
+> 集成 AI Agent，实现知识库问答、工作流触发与多模型切换。
+
+## 🧠 什么是 AI 智能体？
+
+AI 智能体（AI Agent）是 Websopy 平台的核心能力，它能：
+
+- 🤖 基于自然语言理解用户意图
+- 📚 连接你的知识库进行精准问答
+- 🔗 触发业务工作流执行自动化任务
+- 🔄 在多个 AI 模型间智能切换
+
+## 📋 前提条件
+
+- 已完成 [快速上手](/developer/docs/getting-started/quickstart)
+- 已开通 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)
+```
+
+### 第五步：流式响应（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 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
+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: 支持哪些 Embedding 模型？
+
+目前支持：
+- `text-embedding-3-small`（推荐，速度快）
+- `text-embedding-3-large`（高精度）
+- `text-embedding-ada-002`（兼容性）
+
+### Q: 知识库检索不到相关内容？
+
+1. 检查文档是否已成功上传和向量化
+2. 调整 `scoreThreshold` 降低阈值
+3. 尝试增加 `topK` 获取更多候选
--- a/content/docs/ai/rag.md
+++ b/content/docs/ai/rag.md
@@ -0,0 +1,170 @@
+---
+title: RAG 知识库搭建
+description: 上传文档、向量化存储，构建企业级知识库问答系统。
+category: ai
+order: 2
+---
+
+# RAG 知识库搭建
+
+> 上传文档、向量化存储，构建企业级知识库问答系统。
+
+## 🧠 什么是 RAG？
+
+RAG（Retrieval-Augmented Generation，检索增强生成）是一种结合「知识检索」和「AI 生成」的技术：
+
+1. **检索**：从知识库中找到相关内容
+2. **增强**：将检索结果作为上下文
+3. **生成**：让 AI 基于上下文生成答案
+
+```
+用户问题 → 检索相关文档 → 拼接到 Prompt → AI 生成回答
+```
+
+## 📋 适用场景
+
+- 📄 企业内部文档问答
+- 🎯 产品 FAQ 自动化
+- 📚 培训资料检索
+- 🔍 合同/政策查询
+- 🏥 专业知识库
+
+## 🚀 搭建步骤
+
+### 第一步：创建知识库
+
+```typescript
+const knowledgeBase = await client.ai.createKnowledgeBase({
+  name: '产品使用手册',
+  description: '公司产品相关文档',
+  embeddingModel: 'text-embedding-3-small',
+  chunking: {
+    type: 'recursive',
+    chunkSize: 1000,
+    chunkOverlap: 200
+  }
+})
+
+console.log('知识库 ID:', knowledgeBase.id)
+```
+
+### 第二步：上传文档
+
+支持格式：PDF、Word、TXT、Markdown、HTML
+
+```typescript
+// 上传单个文件
+const doc = await client.ai.uploadDocument(knowledgeBase.id, {
+  file: './docs/user-guide.pdf',
+  metadata: {
+    category: 'manual',
+    version: '2.0',
+    language: 'zh-CN'
+  }
+})
+
+// 批量上传
+const docs = await client.ai.uploadDocuments(knowledgeBase.id, [
+  { file: './docs/faq.md', metadata: { category: 'faq' } },
+  { file: './docs/api.md', metadata: { category: 'api' } },
+])
+```
+
+### 第三步：配置检索
+
+```typescript
+await client.ai.configureRetrieval(knowledgeBase.id, {
+  retrieval: {
+    topK: 5,
+    scoreThreshold: 0.7,
+    hybridSearch: true
+  },
+  rerank: {
+    enabled: true,
+    model: 'bge-reranker'
+  }
+})
+```
+
+### 第四步：问答
+
+```typescript
+const response = await client.ai.ask({
+  knowledgeBaseId: knowledgeBase.id,
+  question: '如何创建新项目？',
+  options: {
+    maxTokens: 1000,
+    temperature: 0.7,
+    includeSources: true
+  }
+})
+
+console.log('回答:', response.answer)
+console.log('引用:', response.citations)
+```
+
+### 响应示例
+
+```json
+{
+  "answer": "创建新项目的步骤如下：\n1. 点击「新建项目」按钮\n2. 填写项目名称和描述\n3. 选择项目模板\n4. 点击「创建」完成",
+  "citations": [
+    {
+      "document_id": "doc_abc123",
+      "chunk_text": "点击「新建项目」按钮，进入项目创建页面...",
+      "score": 0.95
+    }
+  ],
+  "model": "gpt-4",
+  "tokens_used": 850
+}
+```
+
+## 🧪 最佳实践
+
+### 文档准备
+
+1. ✅ 清理格式，移除无关内容
+2. ✅ 添加目录和标题结构
+3. ✅ QA 格式文档效果最好
+4. ❌ 避免过长的无结构文本
+5. ❌ 避免大量表格（难以正确分块）
+
+### 检索优化
+
+```typescript
+const optimalConfig = {
+  topK: 3,               // 不要太多，可能引入噪音
+  scoreThreshold: 0.75,  // 设置合理阈值
+  enableRerank: true     // 启用重排序
+}
+```
+
+### Prompt 工程
+
+```typescript
+const response = await client.ai.ask({
+  knowledgeBaseId: knowledgeBase.id,
+  question: '...',
+  systemPrompt: `你是一个专业客服，请基于给定的知识库内容回答用户问题。
+  - 如果知识库中没有相关内容，请如实告知
+  - 回答要简洁、专业、易懂
+  - 适当引用原文帮助用户理解`
+})
+```
+
+## ❓ 常见问题
+
+### Q: 检索不到相关内容？
+
+1. 检查文档是否处理完成（状态为 `ready`）
+2. 降低 `scoreThreshold` 阈值
+3. 尝试 `hybridSearch: true` 混合搜索
+4. 增加 `topK` 获取更多候选
+
+### Q: 回答不准确？
+
+1. 检查源文档质量
+2. 调整 `chunkSize`，太小可能丢失上下文
+3. 启用 `rerank` 提高相关性
+4. 优化 system prompt
--- a/content/docs/ai/workflow.md
+++ b/content/docs/ai/workflow.md
@@ -0,0 +1,192 @@
+---
+title: AI 工作流配置
+description: 使用工作流引擎，构建定时任务与自动化业务流。
+category: ai
+order: 3
+---
+
+# AI 工作流配置
+
+> 使用工作流引擎，构建定时任务与自动化业务流。
+
+## 🔄 什么是工作流？
+
+工作流（Workflow）是预定义的一系列自动化步骤，可以：
+
+- ⏰ **定时执行**：每天早上发送报表
+- 🔗 **事件触发**：用户注册后自动发送欢迎邮件
+- 🔁 **条件分支**：根据条件执行不同操作
+- 📊 **数据处理**：批量处理数据
+
+## 🏗️ 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **触发器 (Trigger)** | 工作流的启动条件 |
+| **节点 (Node)** | 工作流中的单个步骤 |
+| **连接 (Edge)** | 节点之间的数据流向 |
+| **变量 (Variable)** | 存储和传递数据 |
+| **执行日志** | 每次运行的记录 |
+
+## 🚀 创建第一个工作流
+
+### 代码定义
+
+```typescript
+import { WorkflowBuilder } from '@websopy/ai-sdk'
+
+const workflow = new WorkflowBuilder({
+  name: '每日数据报告',
+  description: '每天早上 9 点生成数据报告'
+})
+
+// 添加触发器：定时执行
+workflow.addTrigger({
+  type: 'schedule',
+  config: {
+    cron: '0 9 * * *',  // 每天 9:00
+    timezone: 'Asia/Shanghai'
+  }
+})
+
+// 添加节点：获取数据
+workflow.addNode('fetch-data', {
+  type: 'http-request',
+  config: {
+    url: 'https://api.analytics.com/daily-stats',
+    method: 'GET'
+  }
+})
+
+// 添加节点：生成报告
+workflow.addNode('generate-report', {
+  type: 'ai-agent',
+  config: {
+    prompt: '根据以下数据生成日报：{{fetch-data.output}}'
+  }
+})
+
+// 添加节点：发送邮件
+workflow.addNode('send-email', {
+  type: 'email',
+  config: {
+    to: ['team@company.com'],
+    subject: '📊 每日数据报告',
+    body: '{{generate-report.output}}'
+  }
+})
+
+// 节点连接
+workflow.connect('fetch-data', 'generate-report')
+workflow.connect('generate-report', 'send-email')
+
+// 保存
+const created = await client.workflow.create(workflow.toJSON())
+console.log('工作流 ID:', created.id)
+```
+
+### 可视化编辑器
+
+在控制台 → AI 功能 → 工作流，点击「新建工作流」打开可视化编辑器。
+
+## 📦 节点类型
+
+| 节点类型 | 说明 |
+|----------|------|
+| `http-request` | HTTP 请求 |
+| `ai-agent` | AI 智能体 |
+| `condition` | 条件分支 |
+| `loop` | 循环 |
+| `delay` | 等待/延迟 |
+| `webhook` | Webhook 通知 |
+| `transform` | 数据转换 |
+| `email` | 发送邮件 |
+
+## 🔔 触发器类型
+
+### 定时触发
+
+```typescript
+workflow.addTrigger({
+  type: 'schedule',
+  config: {
+    cron: '0 */4 * * *',  // 每 4 小时
+    interval: 'daily',    // daily, weekly, monthly
+    time: '09:00'
+  }
+})
+```
+
+### Webhook 触发
+
+```typescript
+workflow.addTrigger({
+  type: 'webhook',
+  config: {
+    // 创建后获得 webhook URL
+  }
+})
+```
+
+### 事件触发
+
+```typescript
+workflow.addTrigger({
+  type: 'event',
+  config: {
+    events: [
+      'user.created',
+      'order.completed',
+      'ai.task.failed'
+    ]
+  }
+})
+```
+
+## 📊 执行与监控
+
+### 手动执行
+
+```typescript
+const run = await client.workflow.run(workflowId, {
+  input: { date: '2024-01-15' }
+})
+
+console.log('执行 ID:', run.id)
+```
+
+### 查看执行日志
+
+```typescript
+const logs = await client.workflow.getRunLogs(run.id)
+
+for (const log of logs) {
+  console.log(`[${log.timestamp}] ${log.node}: ${log.status}`)
+  if (log.error) {
+    console.log('  错误:', log.error)
+  }
+}
+```
+
+## ❓ 常见问题
+
+### Q: 工作流执行失败怎么办？
+
+1. 查看执行日志定位问题节点
+2. 检查输入数据格式
+3. 查看节点配置是否正确
+4. 联系支持时提供执行 ID
+
+### Q: 可以嵌套工作流吗？
+
+是的，可以在一个工作流中调用另一个工作流：
+
+```typescript
+workflow.addNode('sub-workflow', {
+  type: 'workflow',
+  config: {
+    workflowId: 'wf-xxx',
+    input: '{{current-data}}'
+  }
+})
+```