sdk_generate/README.md at 77f26ec1932535c1d06e1d191ce9e4a187324498

7.6 KiB

Raw Blame History

README.md

# 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 运行

# 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. 添加文档实例

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

2. 生成代码

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

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	获取任务详情

生成任务请求示例

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\":\"创建订单\"}]"

查询任务状态响应示例

{
  "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）

🤝 贡献指南

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

📝 License

MIT License

📧 联系方式

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

Made with ❤️ by AI SDK Generator Team

7.6 KiB Raw Blame History Unescape Escape