QuantSpeed CLI 调用指南

本 CLI 提供量迹后端 API 的完整调用方案，帮助 AI Agent 与后端服务交互。

快速开始

API 基础地址

https://market.quant-speed.com

所有 API 请求都通过前端代理，前端会将 /api、/admin、/static、/media、/judge、/inventory 等路径代理到后端服务。

认证方式

量迹支持两种认证方式：

MCP 必须使用 X-API-Key 认证！

认证头示例：

{
  "X-API-Key": "qsk_xxxxxxxxxxxxxx",  // MCP/Agent 使用这个
  "Authorization": "Bearer {token}",   // 网页端使用这个
  "Content-Type": "application/json"
}

API 端点参考

所有端点的基础路径为 https://market.quant-speed.com

1. 用户认证

发送验证码

POST /api/auth/send-sms/
Body: {"phone_number": "13800138000"}

手机号登录（网页端）

POST /api/auth/phone-login/
Body: {"phone_number": "13800138000", "code": "888888"}

返回：

{
  "token": "xxx",
  "user": {
    "id": 1,
    "nickname": "xxx",
    "phone_number": "13800138000"
  }
}

验证码登录并获取 API Key（推荐 MCP 使用）

POST /api/auth/sms-login-api-key/
Body: {
  "phone_number": "13800138000",
  "code": "888888",
  "force_regenerate": false
}

返回：

{
  "token": "xxx",
  "api_key": "qsk_xxxxxxxxxxxxxx",  // 永久有效，请妥善保存！
  "has_api_key": true,
  "is_new": false,
  "message": "登录成功，API Key 已生成"
}

重要：
- API Key 只在首次生成或 force_regenerate=true 时返回完整内容
- 如果 Key 已存在且未强制重新生成，返回 "api_key": "[已存在，请使用网页端显示的 Key]"
- 请在网页端「个人设置」中查看和复制已生成的 API Key

获取 API Key 状态

GET /api/auth/api-key-status/

撤销 API Key（需要登录）

POST /api/auth/revoke-api-key/

获取用户资料

GET /api/users/me/

2. 商品与订单

商品列表

GET /api/configs/
Query: ?page_size=20

商品详情

GET /api/configs/{id}/

创建订单

POST /api/orders/
Body: {
  "config": 1,           // ESP32Config 商品 ID
  "quantity": 1,
  "customer_name": "张三",
  "phone_number": "13800138000",
  "shipping_address": "北京市xxx"
}

订单列表

POST /api/orders/my_orders/
Body: {"phone_number": "13800138000", "code": "888888"}

订单详情

GET /api/orders/{id}/

取消订单

POST /api/orders/{id}/cancel/

订单支付（小程序）

POST /api/orders/{id}/prepay_miniprogram/

3. 论坛社区

帖子列表

GET /api/community/topics/
Query: ?category=discussion&page_size=20

分类选项：discussion(讨论), help(求助), share(分享), notice(公告)

帖子详情

GET /api/community/topics/{id}/

发布帖子

POST /api/community/topics/
Body: {
  "title": "标题",
  "content": "内容（支持 Markdown 格式）",
  "category": "discussion"
}

回复帖子

POST /api/community/replies/
Body: {
  "topic": 123,
  "content": "回复内容（支持 Markdown 格式）"
}

修改帖子（仅作者或管理员）

PUT /api/community/topics/{id}/
Body: {
  "title": "新标题",
  "content": "新内容",
  "category": "discussion"
}

权限说明：
- 作者本人可以修改/删除自己发布的帖子
- 管理员（is_staff=True）可以修改/删除任意帖子
- 修改后需要重新审核（状态变为 pending），审核通过后恢复 published

删除帖子（仅作者或管理员）

DELETE /api/community/topics/{id}/

4. Skill 市场

搜索 Skill

GET /api/skillhub/skills/
Query: ?search=frontend&category=ai-agent&sort=popular&page_size=20

排序选项：
- 不传 sort：默认按 sort_order 排序（Admin 设置的顺序）
- sort=popular：按下载量热门排序
- sort=newest：按创建时间最新
- sort=top-rated：按评分高评分

Skill 详情

GET /api/skillhub/skills/{id}/

下载 Skill

GET /api/skillhub/skills/{id}/download/

返回 OSS 签名 URL，重定向下载

点赞 Skill

POST /api/skillhub/skills/{id}/like/

收藏 Skill

POST /api/skillhub/skills/{id}/favorite/

获取评论

GET /api/skillhub/skills/{id}/reviews/

发表评论

POST /api/skillhub/skills/{id}/reviews/
Body: {"rating": 5, "content": "很好用！"}

获取分类

GET /api/skillhub/skills/categories/

推荐 Skill

GET /api/skillhub/skills/featured/

我发布的 Skill

GET /api/skillhub/skills/my_skills/

我收藏的 Skill

GET /api/skillhub/skills/my_favorites/

上传 Skill（需 OSS 直传）

注意：上传 Skill 使用的是后端 OSS 签名直传机制，与 MCP API Key 认证是两个独立的体系：
- API Key：用于 MCP/CLI 调用量迹 API（如搜索、下载 Skill）
- OSS 签名：用于直接上传文件到阿里云 OSS，由后端临时签发

上传流程：

1. 获取 OSS 上传签名（需要登录，使用 Bearer Token）：

GET /api/skillhub/oss-upload-signature/
Headers: {"Authorization": "Bearer {token}"}

返回：

{
  "access_key_id": "STS.XXX",
  "policy": "eyJiZXRhIjoiXX...",
  "signature": "abc123...",
  "x_oss_signature_version": "OSS4-HMAC-SHA256",
  "x_oss_credential": "STS.XXX/20250702/cn-shanghai/oss/aliyun_v4_request",
  "x_oss_date": "20250702T120000Z",
  "host": "https://bucket.oss-cn-shanghai.aliyuncs.com",
  "dir": "skillhub/",
  "security_token": "CAISjg...",
  "callback": "eyJjYWxsYmFja..."
}

2. 前端直接上传文件到 OSS（构造表单 POST）：

POST {host}
Content-Type: multipart/form-data

Form Fields:
- key: skillhub/{skill_name}/{file_name}  // 例如: skillhub/my-skill/my-skill-v1.0.0.tar.gz
- policy: {policy}
- signature: {signature}
- OSSAccessKeyId: {access_key_id}
- x-oss-signature-version: OSS4-HMAC-SHA256
- x-oss-credential: {x_oss_credential}
- x-oss-date: {x_oss_date}
- success_action_status: 200
- file: [文件二进制内容]
- x-oss-security-token: {security_token}  (STS 模式必需)

3. 创建 Skill 记录（需要 API Key 认证）：

POST /api/skillhub/skills/
Headers: {"X-API-Key": "qsk_xxx"}
Body: {
  "name": "my-skill",
  "display_name": "我的 Skill",
  "description": "描述",
  "category": "utility",
  "skill_type": "skill",
  "version": "1.0.0",
  "tags": ["tag1", "tag2"],
  "file_url": "skillhub/my-skill/my-skill-v1.0.0.tar.gz"  // 必须与实际上传路径一致
}

MCP Tools 列表

MCP Server 暴露以下工具供 AI 调用：

用户工具

• quant_speed_get_profile - 获取当前用户资料
• quant_speed_update_profile - 更新用户资料

商品工具

• quant_speed_search_products - 搜索商品
• quant_speed_get_product - 获取商品详情

订单工具

• quant_speed_create_order - 创建订单
• quant_speed_list_orders - 订单列表
• quant_speed_get_order - 订单详情
• quant_speed_cancel_order - 取消订单

社区工具

• quant_speed_list_topics - 帖子列表
• quant_speed_get_topic - 帖子详情
• quant_speed_create_topic - 发布帖子
• quant_speed_reply_topic - 回复帖子

Skill 市场工具

• quant_speed_search_skills - 搜索 Skill
• quant_speed_get_skill - Skill 详情
• quant_speed_install_skill - 安装 Skill
• quant_speed_list_installed_skills - 已安装 Skill 列表
• quant_speed_run_skill - 运行 Skill
• quant_speed_publish_skill - 发布 Skill
• quant_speed_like_skill - 点赞
• quant_speed_favorite_skill - 收藏

错误处理

HTTP 状态码

错误响应格式

{
  "detail": "错误描述信息"
}

使用示例

示例 1：用户登录并下单

1. 发送验证码: POST https://market.quant-speed.com/api/auth/send-sms/ {"phone_number": "13800138000"}
2. 登录: POST https://market.quant-speed.com/api/auth/phone-login/ {"phone_number": "13800138000", "code": "888888"}
3. 获取商品: GET https://market.quant-speed.com/api/configs/1/
4. 创建订单: POST https://market.quant-speed.com/api/orders/ {"config": 1, "quantity": 1}

示例 2：搜索并安装 Skill

1. 搜索: GET https://market.quant-speed.com/api/skillhub/skills/?search=frontend
2. 查看详情: GET https://market.quant-speed.com/api/skillhub/skills/5/
3. 下载: GET https://market.quant-speed.com/api/skillhub/skills/5/download/
4. 收藏: POST https://market.quant-speed.com/api/skillhub/skills/5/favorite/

示例 3：发布论坛帖子

1. 登录获取 token
2. 发布: POST https://market.quant-speed.com/api/community/topics/
   {"title": "ESP32 入门", "content": "如何开始...", "category": "discussion"}
3. 回复: POST https://market.quant-speed.com/api/community/replies/
   {"topic": 123, "content": "我的经验是..."}

配置说明

环境变量

配置文件

位置：~/.quant-speed/config.yaml

django_api_url: https://market.quant-speed.com
token: your_token_here
phone_number: "13800138000"
skill_dir: ~/.quant-speed/skills

联系方式

如有问题，请联系 Quant-Speed 团队。