sdk_generate/README.md

## README.md

```markdown
# SDK Generator - AI 驱动的 SDK 代码生成器

一款基于 AI 大模型的 SDK 代码生成工具，通过上传 API 文档自动生成 Go 语言的 SDK 客户端或服务端骨架代码。

## ✨ 核心功能

- 📄 **文档精炼**：上传 API 文档（支持 .md / .txt / .doc / .docx / .pdf），自动提取接口信息
- 🚀 **代码生成**：支持两种生成模式
  - **客户端 SDK**：根据接口文档生成 Go SDK 客户端代码
  - **服务端骨架**：根据对接文档生成 Go HTTP 服务端骨架（Fiber 框架）
- 🔐 **加密算法**：集成常用加密算法（SM2/SM3/SM4、RSA、AES 等）
- 📋 **任务管理**：异步任务队列，实时查看生成进度和状态
- 📊 **用量统计**：记录每次生成的 Token 用量，支持按步骤查看详情
- 🔗 **代码仓库**：生成完成后自动推送到 Git 仓库（Gitea 等）

## 🏗️ 技术架构

### 后端
- **语言**：Go 1.26
- **Web 框架**：Fiber v2
- **AI 集成**：OpenAI 兼容 API（支持豆包、DeepSeek 等）
- **数据库**：SQLite（可扩展）
- **文件存储**：本地文件系统

### 前端
- **技术栈**：原生 HTML + CSS + JavaScript
- **交互**：Modal 弹窗、实时进度轮询、Markdown 渲染

## 📁 项目结构

```
sdk-generator/
├── cmd/
│   └── server/
│       └── main.go              # 服务启动入口
├── internal/
│   ├── call/
│   │   └── call.go              # LLM 调用封装
│   ├── config/
│   │   └── config.go            # 配置管理
│   ├── extractor/
│   │   └── extractor.go         # 代码块提取
│   ├── handler/
│   │   ├── api_handler.go       # API 路由处理
│   │   └── page_handler.go      # 页面渲染
│   ├── models/
│   │   └── task.go              # 数据模型
│   ├── postprocess/
│   │   └── postprocess.go       # 代码后处理（格式化、编译检查）
│   ├── prompts/
│   │   ├── generate.go          # 生成 Prompt 模板
│   │   └── validate.go          # 验证 Prompt 模板
│   ├── refiner/
│   │   └── refiner.go           # 文档精炼
│   ├── service/
│   │   └── generator.go         # 核心业务逻辑
│   └── validator/
│       └── validator.go         # 代码验证
├── web/
│   ├── static/
│   │   ├── css/
│   │   │   └── style.css        # 样式文件
│   │   └── js/
│   │       └── app.js           # 前端逻辑
│   └── templates/
│       └── index.html           # 主页面
├── outputs/                      # 生成的 SDK 输出目录
├── uploads/                      # 临时上传目录
├── Dockerfile
├── docker-compose.yml
├── go.mod
├── go.sum
└── README.md
```

## 🚀 快速开始

### 前置依赖

- Go 1.26+
- Docker（可选）
- 大模型 API Key（豆包/DeepSeek/OpenAI 等）

### 本地运行

```bash
# 1. 克隆项目
git clone <your-repo-url>
cd sdk-generator

# 2. 下载依赖
go mod download

# 3. 配置环境变量
export DOUBAO_API_KEY=your_api_key
export DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
export DOUBAO_MODEL=doubao-seed-evolving

# 4. 启动服务
go run cmd/server/main.go

# 5. 访问
# 浏览器打开 http://localhost:8080
```

### Docker 运行

```bash
# 1. 构建镜像
docker build -t sdk-generator .

# 2. 运行容器
docker run -d \
    -p 8080:8080 \
    -e DOUBAO_API_KEY=your_api_key \
    -e DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 \
    -e DOUBAO_MODEL=doubao-seed-evolving \
    -v $(pwd)/outputs:/app/outputs \
    --name sdk-generator \
    sdk-generator

# 或使用 docker-compose
docker-compose up -d
```

## 📖 使用指南

### 1. 添加文档实例

1. 点击「添加文档实例」
2. 上传 API 文档（支持 .md / .txt / .doc / .docx / .pdf）
3. 填写 API Key、Base URL、大模型名称
4. 点击「精炼并保存」，系统会自动提取接口信息

### 2. 生成代码

1. 在文档列表中找到目标文档
2. 点击「生成」按钮
3. 选择需要实现的接口（可多选）
4. 填写：
    - 仓库名称（如 `marketing-sdk`）
    - 生成类型（客户端 SDK / 服务端骨架）
    - API Key、Base URL、大模型名称
5. 点击「生成代码」提交任务

### 3. 查看进度

- 页面会实时显示生成进度（百分比 + 状态文字）
- 日志区域显示详细的执行步骤
- 生成完成后可通过「下载 SDK」或「查看代码仓库」获取结果

### 4. 历史任务

- 点击文档的「历史」按钮查看所有生成任务
- 点击任务可查看详情（接口列表、Token 用量等）

## 🔌 API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/refine` | POST | 精炼文档（上传 + AI 提取） |
| `/api/v1/refine/list` | POST | 获取文档实例列表 |
| `/api/v1/refine/update` | POST | 更新文档内容 |
| `/api/v1/generate` | POST | 提交代码生成任务 |
| `/api/v1/tasks/{task_id}` | GET | 查询任务状态和进度 |
| `/api/v1/tasks/{task_id}/download` | GET | 下载生成的代码包 |
| `/api/v1/tasks/list` | POST | 获取历史任务列表 |
| `/api/v1/tasks/{task_id}/detail` | GET | 获取任务详情 |

### 生成任务请求示例

```bash
curl -X POST /api/v1/generate \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "instance_id=xxx" \
  -d "llm_api_key=xxx" \
  -d "llm_base_url=https://ark.cn-beijing.volces.com/api/v3" \
  -d "llm_model=doubao-seed-evolving" \
  -d "desc=my-sdk" \
  -d "code_type=go" \
  -d "generate_type=1" \
  -d "interfaces=[{\"method\":\"POST\",\"summary\":\"创建订单\"}]"
```

### 查询任务状态响应示例

```json
{
  "code": 200,
  "data": {
    "Task": {
      "task_id": "xxx",
      "task_status": "generateCode",
      "desc": "my-sdk",
      "repo_url": "https://gitea.example.com/ai_sdk/my-sdk"
    },
    "percent": 60,
    "status_desc": "生成代码中..."
  },
  "message": "成功"
}
```

## 🔐 支持的加密算法

| 算法 | 类型 | 说明 |
|------|------|------|
| **SM2** | 非对称加密 | 国密签名/加密 |
| **SM3** | 哈希算法 | 国密摘要计算 |
| **SM4** | 对称加密 | 国密 CBC/ECB 模式 |
| **RSA** | 非对称加密 | 签名/PKCS1/PKCS8 |
| **AES** | 对称加密 | CBC/ECB 模式 |
| **HMAC-SHA256** | 哈希算法 | 签名验证 |

## 🛠️ 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `PORT` | 服务端口 | `8080` |
| `DOUBAO_API_KEY` | 大模型 API Key | - |
| `DOUBAO_BASE_URL` | API 地址 | `https://ark.cn-beijing.volces.com/api/v3` |
| `DOUBAO_MODEL` | 模型名称 | `doubao-seed-evolving` |
| `OUTPUT_DIR` | 输出目录 | `./outputs` |
| `UPLOAD_DIR` | 上传目录 | `./uploads` |
| `MAX_TOKENS` | 最大输出 Token | `65536` |

## 📦 依赖库

| 库 | 用途 |
|----|------|
| `github.com/gofiber/fiber/v2` | Web 框架 |
| `github.com/sashabaranov/go-openai` | OpenAI API 客户端 |
| `github.com/gofiber/template/html/v2` | HTML 模板引擎 |
| `github.com/google/uuid` | UUID 生成 |
| `github.com/yuin/goldmark` | Markdown 解析 |
| `github.com/tjfoc/gmsm` | 国密算法（SM2/SM3/SM4） |

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📝 License

MIT License

## 📧 联系方式

如有问题，请提交 Issue 或联系项目维护者。

---

**Made with ❤️ by AI SDK Generator Team**