Pilot-Sim 插件市场 API 文档

本文档提供了 Pilot-Sim 插件市场的完整 API 接口说明，包括所有可用的端点、参数和示例代码。

基础信息

基础URL: https://market.nextcore.work/api
认证方式: 管理员接口需要使用管理员令牌
数据格式: JSON
字符编码: UTF-8
分页参数:
- page: 页码 (默认: 1)
- limit: 每页数量 (默认: 10, 最大: 100)
- 响应中包含 total 总数

📋 目录

公开 API
管理员 API
文件 API
错误码说明
认证说明

🌐 公开 API

1. 获取插件列表

获取所有已发布的插件列表，支持搜索和排序。

端点: GET /api/extensions

参数:

page: 页码 (默认: 1)
limit: 每页数量 (默认: 10, 最大: 100)
search: 搜索关键词 (支持插件名、描述、发布者)
sort: 排序字段 (默认: created_at)
order: 排序方向 (asc/desc, 默认: desc)

响应:

{
  "success": true,
  "data": {
    "extensions": [
      {
        "id": "uuid",
        "name": "插件名称",
        "version": "1.0.0",
        "description": "插件描述",
        "publisher": "发布者",
        "release_date": "2025-01-01T00:00:00Z",
        "changelog": "更新日志",
        "download_count": 100,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z",
        "base_id": "基础信息ID",
        "base_total_downloads": "总下载次数"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

示例:

curl "https://market.nextcore.work/api/extensions?page=1&limit=10&search=pilot"

2. 获取插件详情

获取指定插件的详细信息。

端点: GET /api/extensions/{id}

参数:

id: 插件ID (必需)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "插件名称",
    "version": "1.0.0",
    "description": "插件描述",
    "publisher": "发布者",
    "file_path": "文件路径",
    "file_size": 1024,
    "release_date": "2025-01-01T00:00:00Z",
    "changelog": "更新日志",
    "download_count": 100,
    "is_latest": true,
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

示例:

curl "https://market.nextcore.work/api/extensions/123e4567-e89b-12d3-a456-426614174000"

3. 下载插件

下载指定插件的VSIX文件。

端点: GET /api/extensions/{id}/download

参数:

id: 插件ID (必需)

响应:

文件流 (VSIX格式)

示例:

curl -O "https://market.nextcore.work/api/extensions/123e4567-e89b-12d3-a456-426614174000/download"

🔐 管理员 API

4. 获取插件列表（管理员）

获取所有插件列表，包括未激活的插件。

端点: GET /api/admin/extensions

认证: 需要管理员令牌

参数:

page: 页码 (默认: 1)
limit: 每页数量 (默认: 10, 最大: 100)
search: 搜索关键词

响应:

{
  "success": true,
  "data": {
    "extensions": [
      {
        "id": "uuid",
        "name": "插件名称",
        "version": "1.0.0",
        "description": "插件描述",
        "publisher": "发布者",
        "file_path": "文件路径",
        "file_size": 1024,
        "release_date": "2025-01-01T00:00:00Z",
        "changelog": "更新日志",
        "download_count": 100,
        "is_latest": true,
        "is_active": true,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

5. 上传新插件

上传新的VSIX插件文件。

端点: POST /api/admin/extensions

认证: 需要管理员令牌

表单数据:

file: VSIX文件 (必需)
name: 插件名称 (可选，自动从VSIX解析)
version: 版本号 (可选，自动从VSIX解析)
description: 描述 (可选，自动从VSIX解析)
publisher: 发布者 (可选，自动从VSIX解析)
changelog: 更新日志 (可选)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "插件名称",
    "version": "1.0.0",
    "description": "插件描述",
    "publisher": "发布者",
    "file_path": "文件路径",
    "file_size": 1024,
    "created_at": "2025-01-01T00:00:00Z"
  },
  "message": "插件上传成功"
}

示例:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@pilot-sim-0.5.6.vsix" \
  -F "name=pilot-sim" \
  -F "version=0.5.6" \
  "https://market.nextcore.work/api/admin/extensions"

6. 通过名称更新插件

通过插件名称更新现有插件的新版本。

端点: POST /api/admin/extensions/update-by-name

认证: 需要管理员令牌

表单数据:

file: VSIX文件 (必需)
pluginName: 插件名称 (必需)
version: 版本号 (可选，自动从VSIX解析)
description: 描述 (可选，自动从VSIX解析)
changelog: 更新日志 (可选)

响应:

{
  "success": true,
  "data": {
    "extension": {
      "id": "uuid",
      "name": "插件名称",
      "version": "1.0.0",
      "description": "插件描述",
      "publisher": "发布者",
      "file_path": "文件路径",
      "file_size": 1024,
      "created_at": "2025-01-01T00:00:00Z"
    },
    "previousVersion": "0.9.0",
    "message": "插件 "pilot-sim" 已成功从版本 0.9.0 更新到 1.0.0"
  },
  "message": "插件更新成功"
}

示例:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@pilot-sim-1.0.0.vsix" \
  -F "pluginName=pilot-sim" \
  "https://market.nextcore.work/api/admin/extensions/update-by-name"

7. 获取插件详情（管理员）

获取指定插件的详细信息，包括管理信息。

端点: GET /api/admin/extensions/{id}

认证: 需要管理员令牌

参数:

id: 插件ID (必需)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "插件名称",
    "version": "1.0.0",
    "description": "插件描述",
    "publisher": "发布者",
    "file_path": "文件路径",
    "file_size": 1024,
    "release_date": "2025-01-01T00:00:00Z",
    "changelog": "更新日志",
    "download_count": 100,
    "is_latest": true,
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

8. 更新插件信息

更新插件的基本信息。

端点: PUT /api/admin/extensions/{id}

认证: 需要管理员令牌

请求体:

{
  "name": "插件名称",
  "description": "插件描述",
  "publisher": "发布者",
  "is_active": true,
  "changelog": "更新日志"
}

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "更新后的插件名称",
    "version": "1.0.0",
    "description": "更新后的描述",
    "publisher": "更新后的发布者",
    "is_active": true,
    "updated_at": "2025-01-01T00:00:00Z"
  },
  "message": "插件信息更新成功"
}

9. 删除插件

删除指定插件（软删除）。

端点: DELETE /api/admin/extensions/{id}

认证: 需要管理员令牌

参数:

id: 插件ID (必需)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "is_active": false,
    "deleted_at": "2025-01-01T00:00:00Z"
  },
  "message": "插件删除成功"
}

📁 文件 API

10. 获取VSCode文件

获取VSCode相关的静态文件。

端点: GET /api/files/vscode/{filename}

参数:

filename: 文件名 (必需)

响应:

文件内容

示例:

curl "https://market.nextcore.work/api/files/vscode/extension.vsixmanifest"

📊 统计 API

11. 获取系统统计信息

获取插件市场的整体统计信息。

端点: GET /api/admin/stats

认证: 需要管理员令牌

响应:

{
  "success": true,
  "data": {
    "total_extensions": 100,
    "total_downloads": 10000,
    "active_extensions": 80,
    "recent_uploads": [
      {
        "id": "uuid",
        "name": "最近上传的插件",
        "version": "1.0.0",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

🔑 认证 API

12. 管理员登录

管理员登录获取访问令牌。

端点: POST /api/admin/login

请求体:

{
  "username": "用户名",
  "password": "密码"
}

响应:

{
  "success": true,
  "data": {
    "token": "JWT令牌",
    "expires_in": 3600,
    "user": {
      "id": "用户ID",
      "username": "用户名",
      "role": "admin"
    }
  },
  "message": "登录成功"
}

📁 文件管理 API

13. 获取文件列表

获取上传的文件列表。

端点: GET /api/admin/files

认证: 需要管理员令牌

参数:

page: 页码 (默认: 1)
limit: 每页数量 (默认: 10, 最大: 100)

响应:

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "uuid",
        "filename": "文件名",
        "file_path": "文件路径",
        "file_size": 1024,
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

14. 获取文件详情

获取指定文件的详细信息。

端点: GET /api/admin/files/{id}

认证: 需要管理员令牌

参数:

id: 文件ID (必需)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "filename": "文件名",
    "file_path": "文件路径",
    "file_size": 1024,
    "created_at": "2025-01-01T00:00:00Z"
  }
}

15. 删除文件

删除指定文件。

端点: DELETE /api/admin/files/{id}

认证: 需要管理员令牌

参数:

id: 文件ID (必需)

响应:

{
  "success": true,
  "data": {
    "id": "uuid",
    "deleted_at": "2025-01-01T00:00:00Z"
  },
  "message": "文件删除成功"
}

📝 错误码说明

错误码	说明
400	请求参数错误
401	未授权访问
403	禁止访问
404	资源不存在
500	服务器内部错误
23503	数据库外键约束错误
42702	数据库列引用歧义
42703	数据库语法错误

🔐 认证说明

管理员认证

所有以 /api/admin/ 开头的接口都需要管理员认证：

登录获取令牌: POST /api/admin/login
在请求头中携带令牌: Authorization: Bearer YOUR_TOKEN

认证流程

管理员登录获取JWT令牌
在后续请求的 Authorization 头中携带令牌
令牌过期时间: 1小时

🚀 快速开始

上传新插件

登录获取管理员令牌
使用 POST /api/admin/extensions 上传VSIX文件
系统会自动解析VSIX文件中的元数据
使用存储过程确保数据一致性

更新现有插件

使用 POST /api/admin/extensions/update-by-name 通过插件名称更新
系统会自动查找现有插件
版本号必须大于当前版本（防止降级）
使用存储过程确保数据一致性

📞 技术支持

文档: https://market.nextcore.work/docs