qq-music-api: Instructions file for Codex

🤖 QQ Music API - AI Agents 指南 (AGENTS.md)

本文档用于说明 qq-music-api 当前的真实项目架构、API Explorer 的模块分层，以及 AI 代理能力在本仓库中的落点与扩展方式。它既面向开发者，也面向需要理解代码结构的大语言模型（LLM）或自动化工作流。

🎯 目录

1. 项目概览
2. 项目架构
3. Explorer 架构
4. AI 代理能力定位
5. 建议的调用与扩展方式
6. 开发约束

---

项目概览

qq-music-api 是一个基于 Koa2 + TypeScript 的服务端项目，核心职责是：

• 对外暴露统一的 QQ 音乐接口。
• 在控制器层接收请求、做参数整理并调用服务层。
• 在服务层请求 QQ 音乐上游能力并返回结构化结果。
• 提供一个内置的本地 API Explorer 页面，方便开发环境调试接口。

当前仓库的主体是标准的 Koa 服务和 Explorer 调试工作台。文档中提到的 AI 代理，更适合作为“能力边界”和“扩展方向”来理解，而不是一个已经完整落地的独立运行时框架。

---

项目架构

1. 服务端主链路

当前请求链路如下：

HTTP Request
  -> Koa App (src/app.ts)
  -> Middlewares (body parser / cookie / cors / response time / logger)
  -> Router (src/routes/router.ts)
  -> Controllers (src/controllers/*)
  -> Services (src/services/*)
  -> QQ Music upstream / data parsing
  -> HTTP Response

2. 主要目录说明

qq-music-api/
├── src/
│   ├── app.ts                  # Koa 应用入口，注册中间件、Explorer 路由与静态资源
│   ├── config/                 # 服务配置、Explorer 元数据配置
│   ├── controllers/            # 控制器层，处理入参并编排服务调用
│   ├── explorer/               # Explorer 的 contracts/domain/application 逻辑
│   ├── middlewares/            # Koa 中间件
│   ├── routes/                 # 路由注册
│   ├── services/               # QQ 音乐能力封装与数据获取
│   ├── types/                  # 共享类型定义
│   └── util/                   # 公共工具，如 logger、cookie、lyricParse
├── public/
│   └── explorer/               # Explorer 静态页面资源（index.html / app.js / styles.css）
├── tests/                      # Jest + Supertest 测试
├── docs/                       # Docsify 文档与静态截图资源
└── README.md                   # 项目主说明

3. 关键模块职责

• src/app.ts
  • 启动 Koa 服务。
  • 暴露 /explorer、/explorer/index.html、/explorer/metadata。
  • 托管 public/ 下的静态资源。
  • 在开发环境中配合 AUTO_OPEN_EXPLORER 自动打开 Explorer。
• src/controllers/*
  • 负责解析查询参数与请求体。
  • 将请求转发到对应 services。
  • 封装统一的 HTTP 返回结构。
• src/services/*
  • 负责实际的数据拉取、协议拼装与结果加工。
  • 是当前最接近“数据获取代理”的能力落点。
• src/util/logger.ts
  • 统一日志出口。
  • Explorer 的服务端调试日志也通过这里输出。
• tests/*
  • 覆盖控制器、服务、Explorer 元数据、Explorer 领域逻辑与页面路由。