初始版本

2026-04-23 16:30:57 +08:00
commit 0d0683a6e6
538 changed files with 113042 additions and 0 deletions
--- a/content/docs/getting-started/apikey.md
+++ b/content/docs/getting-started/apikey.md
@@ -0,0 +1,213 @@
+---
+title: API Key 创建与管理
+description: 在控制台创建 API Key，了解权限范围与速率限制，安全使用建议。
+category: getting-started
+order: 3
+---
+
+# API Key 创建与管理
+
+> 在控制台创建 API Key，了解权限范围与速率限制，安全使用建议。
+
+## 🔑 什么是 API Key？
+
+API Key 是调用 Websopy API 的凭证，类似于「数字身份证」，用于：
+
+- ✅ 身份认证 - 证明你是平台用户
+- ✅ 权限控制 - 控制可以访问哪些资源
+- ✅ 用量统计 - 记录 API 调用情况
+- ✅ 计费依据 - 按使用量进行计费
+
+## 📋 创建 API Key
+
+### 步骤 1：进入控制台
+
+1. 登录 [Websopy 控制台](https://console.websopy.com)
+2. 导航到 **开发者中心 → API Key**
+3. 点击 **创建新 Key**
+
+### 步骤 2：配置 Key
+
+| 配置项 | 说明 |
+|--------|------|
+| **名称** | 给 Key 取个易识别的名字，如「生产环境」「测试用」 |
+| **权限范围** | 选择 Key 允许的操作（见下文） |
+| **有效期** | 设置过期时间（可选） |
+| **IP 白名单** | 限制只有指定 IP 才能使用（可选） |
+
+### 步骤 3：保存 Key
+
+⚠️ **重要**：API Key 只显示一次，请立即：
+1. 复制保存到安全位置
+2. 设置环境变量
+
+```bash
+# Linux/macOS
+echo 'export WEBSOPY_API_KEY="ws_live_xxxxx"' >> ~/.bashrc
+source ~/.bashrc
+
+# Windows PowerShell
+[Environment]::SetEnvironmentVariable("WEBSOPY_API_KEY", "ws_live_xxxxx", "User")
+```
+
+## 🛡️ 权限范围
+
+### 可用权限
+
+| 权限 | 说明 | 适用场景 |
+|------|------|----------|
+| `user:read` | 读取用户信息 | 数据展示 |
+| `user:write` | 修改用户信息 | 用户管理 |
+| `project:read` | 读取项目 | 数据展示 |
+| `project:write` | 创建/修改/删除项目 | 项目管理 |
+| `storage:read` | 读取文件 | 文件读取 |
+| `storage:write` | 上传/删除文件 | 文件管理 |
+| `ai:agent` | 使用 AI 智能体 | AI 功能 |
+| `ai:knowledge` | 管理知识库 | 知识库管理 |
+| `payment:read` | 读取账单 | 账单查看 |
+| `admin:*` | 所有权限 | ⚠️ 仅管理员 |
+
+### 权限组合
+
+推荐按最小权限原则配置：
+
+```json
+// 只读权限（安全）
+{
+  "permissions": ["user:read", "project:read", "storage:read"]
+}
+
+// 读写权限（一般开发）
+{
+  "permissions": ["user:read", "user:write", "project:*", "storage:*"]
+}
+
+// AI 功能
+{
+  "permissions": ["ai:agent", "ai:knowledge"]
+}
+```
+
+## 🚫 IP 白名单
+
+增强安全性，限制只有指定 IP 可以使用 Key：
+
+1. 创建/编辑 Key 时开启「IP 白名单」
+2. 添加允许的 IP 地址或 CIDR 范围
+
+```text
+# 支持的格式
+203.0.113.1           # 单个 IP
+203.0.113.0/24        # IP 段
+203.0.113.1,198.51.100.0/24  # 多个，用逗号分隔
+```
+
+## ⏱️ 速率限制
+
+| 套餐 | 请求限制 |
+|------|----------|
+| 免费版 | 100 次/分钟 |
+| 专业版 | 1,000 次/分钟 |
+| 企业版 | 10,000 次/分钟 |
+
+### 查看当前用量
+
+```typescript
+const client = new WebsopyClient({
+  apiKey: process.env.WEBSOPY_API_KEY
+})
+
+// 获取当前配额
+const quota = await client.account.getQuota()
+console.log('今日剩余:', quota.remaining)
+console.log('重置时间:', quota.resetAt)
+```
+
+### 处理限流
+
+```typescript
+async function callWithRetry(fn, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (error.code === 'RATE_LIMIT_EXCEEDED') {
+        // 等待后重试
+        await sleep(error.retryAfter * 1000)
+        continue
+      }
+      throw error
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+```
+
+## 🔐 安全最佳实践
+
+### ✅ 推荐做法
+
+```typescript
+// 1. 使用环境变量，不硬编码
+const client = new WebsopyClient({
+  apiKey: process.env.WEBSOPY_API_KEY  // ✅ 正确
+})
+
+// ❌ 危险：硬编码在代码中
+const client = new WebsopyClient({
+  apiKey: 'ws_live_xxxxx'  // ❌ 危险
+})
+```
+
+```typescript
+// 2. 区分不同环境的 Key
+const client = new WebsopyClient({
+  apiKey: process.env.NODE_ENV === 'production' 
+    ? process.env.WEBSOPY_API_KEY_PROD 
+    : process.env.WEBSOPY_API_KEY_DEV
+})
+```
+
+```typescript
+// 3. 前端使用受限 Key
+const client = new WebsopyClient({
+  apiKey: process.env.WEBSOPY_API_KEY_PUBLIC,
+  // 前端 Key 应该只开只读权限
+  allowedMethods: ['user.getProfile', 'project.list']
+})
+```
+
+### ❌ 避免事项
+
+1. **不要**将 Key 提交到代码仓库
+2. **不要**在前端暴露有写权限的 Key
+3. **不要**使用同一个 Key 处理所有业务
+4. **不要**通过 URL 参数传递 Key
+
+```gitignore
+# .gitignore
+.env
+.env.*
+*.local
+```
+
+## 🔄 Key 轮换
+
+定期更换 API Key 是个好习惯：
+
+1. 在控制台创建新 Key
+2. 更新所有使用旧 Key 的地方
+3. 验证新 Key 正常工作
+4. 禁用或删除旧 Key
+
+## 📊 审计日志
+
+在控制台查看 API Key 的使用记录：
+
+- 调用时间、频率
+- 调用的接口
+- 请求来源 IP
+- 错误情况
--- a/content/docs/getting-started/quickstart.md
+++ b/content/docs/getting-started/quickstart.md
@@ -0,0 +1,130 @@
+---
+title: 5 分钟快速上手
+description: 安装 Websopy SDK、配置客户端，并发送你的第一个 API 请求。
+category: getting-started
+order: 1
+---
+
+# 5 分钟快速上手
+
+> 本教程将带你完成 Websopy SDK 的安装、配置，并发送你的第一个 API 请求。
+
+## 📋 前提条件
+
+- Node.js 16.x 或更高版本
+- npm 8.x 或 yarn 1.22+
+- 一个 Websopy 账户（[立即注册](https://websopy.com/register)）
+
+## 🚀 开始
+
+### 第一步：安装 SDK
+
+```bash
+# 使用 npm
+npm install @websopy/sdk
+
+# 或使用 yarn
+yarn add @websopy/sdk
+
+# 或使用 pnpm
+pnpm add @websopy/sdk
+```
+
+### 第二步：获取 API Key
+
+1. 登录 [Websopy 控制台](https://console.websopy.com)
+2. 进入 **开发者中心 → API Key**
+3. 点击 **创建新 Key**
+4. 选择权限范围（建议先选择「只读」权限测试）
+5. 复制生成的 Key（注意：Key 只显示一次，请妥善保存）
+
+### 第三步：初始化客户端
+
+```typescript
+import { WebsopyClient } from '@websopy/sdk'
+
+const client = new WebsopyClient({
+  apiKey: 'your-api-key-here',
+  // 可选：指定 API 端点
+  baseUrl: 'https://api.websopy.com/v1'
+})
+```
+
+### 第四步：发送第一个请求
+
+```typescript
+async function main() {
+  try {
+    // 获取用户信息
+    const user = await client.user.getProfile()
+    console.log('当前用户:', user.name)
+    
+    // 创建第一个项目
+    const project = await client.project.create({
+      name: '我的第一个项目',
+      description: '通过 API 创建'
+    })
+    console.log('项目创建成功:', project.id)
+    
+    // 获取项目列表
+    const projects = await client.project.list()
+    console.log('项目总数:', projects.total)
+  } catch (error) {
+    console.error('请求失败:', error.message)
+  }
+}
+
+main()
+```
+
+### 第五步：运行代码
+
+```bash
+npx ts-node your-script.ts
+# 或
+node your-script.js
+```
+
+**预期输出：**
+
+```
+当前用户: 张三
+项目创建成功: proj_abc123xyz
+项目总数: 5
+```
+
+## 🎉 恭喜！
+
+你已经成功发送了第一个 API 请求。接下来你可以：
+
+- 📖 继续阅读 [API Key 创建与管理](/developer/docs/getting-started/apikey)
+- 🔌 查看 [REST API 完整参考](/developer/docs/api/rest-api)
+- 🤖 尝试 [AI 智能体接入](/developer/docs/ai/agent)
+
+## ⚠️ 常见问题
+
+### Q: 报 "Invalid API Key" 错误？
+
+检查以下几点：
+1. API Key 是否正确复制（不要有空格）
+2. Key 是否已过期或被禁用
+3. Key 的权限范围是否包含当前操作
+
+### Q: 报 "Rate Limit Exceeded" 错误？
+
+免费账户默认 100 次/分钟。如需更高配额，在控制台升级套餐。
+
+### Q: 如何开启调试模式？
+
+```typescript
+const client = new WebsopyClient({
+  apiKey: 'your-api-key',
+  debug: true  // 打印详细请求日志
+})
+```
+
+## 📚 相关资源
+
+- [SDK 源码仓库](https://github.com/websopy/sdk)
+- [示例代码集合](https://github.com/websopy/examples)
+- [API 状态页](https://status.websopy.com)
--- a/content/docs/getting-started/sdk-installation.md
+++ b/content/docs/getting-started/sdk-installation.md
@@ -0,0 +1,209 @@
+---
+title: 安装 SDK 与初始化
+description: 详细指南：安装 @websopy/sdk，配置 WebsopyClient，发送第一个 API 请求。
+category: getting-started
+order: 2
+---
+
+# 安装 SDK 与初始化
+
+> 详细指南：安装 @websopy/sdk，配置 WebsopyClient，发送第一个 API 请求。
+
+## 📦 SDK 概述
+
+Websopy 提供多种语言的 SDK：
+
+| 语言 | SDK | 源码 |
+|------|-----|------|
+| JavaScript/TypeScript | `@websopy/sdk` | [GitHub](https://github.com/websopy/sdk-js) |
+| Python | `websopy-sdk` | [GitHub](https://github.com/websopy/sdk-python) |
+| Go | `github.com/websopy/sdk-go` | [GitHub](https://github.com/websopy/sdk-go) |
+| Java | `com.websopy:sdk` | [GitHub](https://github.com/websopy/sdk-java) |
+
+本教程以 JavaScript/TypeScript 为例。
+
+## 🚀 安装
+
+### npm
+
+```bash
+npm install @websopy/sdk
+```
+
+### yarn
+
+```bash
+yarn add @websopy/sdk
+```
+
+### pnpm
+
+```bash
+pnpm add @websopy/sdk
+```
+
+### CDN（浏览器端）
+
+```html
+<script src="https://unpkg.com/@websopy/sdk/dist/websopy.min.js"></script>
+```
+
+## ⚙️ 初始化配置
+
+### 基本配置
+
+```typescript
+import { WebsopyClient } from '@websopy/sdk'
+
+const client = new WebsopyClient({
+  apiKey: 'ws_live_xxxxxxxxxxxx',
+  // API 版本（可选，默认 v1）
+  version: 'v1',
+  // 超时时间（毫秒）
+  timeout: 30000,
+  // 重试次数
+  retries: 3
+})
+```
+
+### 多环境配置
+
+```typescript
+const config = {
+  // 开发环境
+  dev: {
+    apiKey: 'ws_test_xxxxx',
+    baseUrl: 'https://api-dev.websopy.com/v1'
+  },
+  // 生产环境
+  prod: {
+    apiKey: process.env.WEBSOPY_API_KEY,
+    baseUrl: 'https://api.websopy.com/v1'
+  }
+}
+
+const client = new WebsopyClient(
+  process.env.NODE_ENV === 'production' ? config.prod : config.dev
+)
+```
+
+### 环境变量
+
+创建 `.env` 文件：
+
+```env
+WEBSOPY_API_KEY=ws_live_xxxxxxxxxxxx
+WEBSOPY_BASE_URL=https://api.websopy.com/v1
+WEBSOPY_TIMEOUT=30000
+```
+
+```typescript
+import 'dotenv/config'
+import { WebsopyClient } from '@websopy/sdk'
+
+const client = new WebsopyClient({
+  apiKey: process.env.WEBSOPY_API_KEY,
+  baseUrl: process.env.WEBSOPY_BASE_URL
+})
+```
+
+## 📚 API 模块
+
+SDK 按功能模块组织：
+
+```typescript
+// 用户管理
+client.user
+
+// 项目管理
+client.project
+
+// 文件存储
+client.storage
+
+// AI 功能
+client.ai
+
+// 支付功能
+client.payment
+
+// Webhook
+client.webhook
+```
+
+## 🧪 完整示例
+
+```typescript
+import { WebsopyClient } from '@websopy/sdk'
+
+async function demo() {
+  const client = new WebsopyClient({
+    apiKey: process.env.WEBSOPY_API_KEY
+  })
+
+  // 1. 获取用户信息
+  const user = await client.user.getProfile()
+  console.log('用户:', user.name)
+
+  // 2. 列出项目
+  const { items: projects } = await client.project.list({
+    limit: 10,
+    status: 'active'
+  })
+
+  // 3. 创建项目
+  const project = await client.project.create({
+    name: '新项目',
+    description: '通过 SDK 创建'
+  })
+
+  // 4. 上传文件
+  const file = await client.storage.upload({
+    file: './demo.pdf',
+    folder: 'documents'
+  })
+
+  console.log('文件上传成功:', file.url)
+}
+
+demo().catch(console.error)
+```
+
+## 🔧 TypeScript 类型
+
+SDK 提供完整的 TypeScript 类型定义：
+
+```typescript
+import type { 
+  Project, 
+  User, 
+  CreateProjectOptions 
+} from '@websopy/sdk/types'
+
+function createProject(options: CreateProjectOptions): Promise<Project> {
+  return client.project.create(options)
+}
+```
+
+## ❓ 常见问题
+
+### Q: ESM 和 CommonJS 兼容？
+
+是的，SDK 同时支持两种模块格式：
+
+```typescript
+// ESM
+import { WebsopyClient } from '@websopy/sdk'
+
+// CommonJS
+const { WebsopyClient } = require('@websopy/sdk')
+```
+
+### Q: 如何调试？
+
+```typescript
+const client = new WebsopyClient({
+  apiKey: process.env.WEBSOPY_API_KEY,
+  debug: true  // 打印详细日志
+})
+```