仓库自包含化：Docker/CI/文档/规范入库，路由分组拆分

internal/api/aigateway.go

@@ -148,6 +148,12 @@ func (h *aiGatewayHandler) logFailure(c *gin.Context, entry model.AiCallLog, req
 }
 
 // chatCompletions 是 OpenAI /ai/v1/chat/completions 端点。
+//
+// @Summary  OpenAI 兼容对话补全
+// @Tags     AI 网关
+// @Param    body body object true "OpenAI chat/completions 请求体(支持 stream)"
+// @Success  200 {object} map[string]any "OpenAI 兼容响应(流式为 SSE)"
+// @Router   /ai/v1/chat/completions [post]
 func (h *aiGatewayHandler) chatCompletions(c *gin.Context) {
 	var ir aiwire.ChatRequest
 	if err := c.ShouldBindJSON(&ir); err != nil {
@@ -191,6 +197,12 @@ func fillUsage(entry *model.AiCallLog, u *aiwire.Usage) {
 }
 
 // embeddings 是 OpenAI /ai/v1/embeddings 端点(非流式)。
+//
+// @Summary  OpenAI 兼容向量嵌入
+// @Tags     AI 网关
+// @Param    body body object true "OpenAI embeddings 请求体"
+// @Success  200 {object} map[string]any "OpenAI 兼容响应"
+// @Router   /ai/v1/embeddings [post]
 func (h *aiGatewayHandler) embeddings(c *gin.Context) {
 	var req aiwire.EmbeddingsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -280,6 +292,12 @@ func writeSSEData(c *gin.Context, v any) {
 }
 
 // messages 是 Anthropic /ai/v1/messages 端点。
+//
+// @Summary  Anthropic Messages 兼容端点
+// @Tags     AI 网关
+// @Param    body body object true "Anthropic messages 请求体(支持 stream)"
+// @Success  200 {object} map[string]any "Anthropic 兼容响应(流式为 SSE)"
+// @Router   /ai/v1/messages [post]
 func (h *aiGatewayHandler) messages(c *gin.Context) {
 	var req aiwire.MessagesRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -369,6 +387,11 @@ func writeAnthEvents(c *gin.Context, events []service.AnthEvent) {
 }
 
 // listModels 是 /ai/v1/models 端点(OpenAI 格式,从启用渠道的模型缓存聚合)。
+//
+// @Summary  可用模型列表
+// @Tags     AI 网关
+// @Success  200 {object} map[string]any "OpenAI 兼容 models 列表"
+// @Router   /ai/v1/models [get]
 func (h *aiGatewayHandler) listModels(c *gin.Context) {
 	list, err := h.gw.GatewayModels(c.Request.Context(), keyGroup(c))
 	if err != nil {
@@ -379,6 +402,12 @@ func (h *aiGatewayHandler) listModels(c *gin.Context) {
 }
 
 // responses 是 OpenAI /ai/v1/responses 端点(无状态子集)。
+//
+// @Summary  OpenAI Responses 兼容端点
+// @Tags     AI 网关
+// @Param    body body object true "OpenAI responses 请求体(支持 stream)"
+// @Success  200 {object} map[string]any "OpenAI 兼容响应(流式为 SSE)"
+// @Router   /ai/v1/responses [post]
 func (h *aiGatewayHandler) responses(c *gin.Context) {
 	var req aiwire.RespRequest
 	if err := c.ShouldBindJSON(&req); err != nil {