初始版本

public/docs/sdk-installation.md

@@ -0,0 +1,207 @@
+# 安装 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  // 打印详细日志
+})
+```
+
+---
+
+**上一步：** [5 分钟快速上手](./quickstart.md)  
+**下一步：** [API Key 创建与管理](./apikey.md)