{
  "openapi": "3.0.3",
  "info": {
    "title": "循古排盘 Agent API",
    "version": "1.0.0",
    "description": "POST /api/agent/bazi：禄命古法本命与流日运势 JSON 接口，供 OpenClaw 等 AI Agent 调用。完整说明见站点 /docs/agent-api；Bearer 鉴权与老黄历等接口共用 API Key 与每日配额。"
  },
  "servers": [
    {
      "url": "https://example.com",
      "description": "请替换为 config.APP_URL 所指的生产域名（含协议，无尾部斜杠）"
    }
  ],
  "paths": {
    "/api/agent/bazi": {
      "post": {
        "operationId": "agentBaziScore",
        "summary": "禄命古法：本命摘要与（授权后）当日运势",
        "description": "未携带有效 Bearer Key 时仍可返回本命摘要，但 daily_fortune 为锁定态且受 IP 日限流；携带 Key 时计入 Key / 用户日配额并返回完整 daily_fortune。",
        "security": [{ "bearerAuth": [] }, {}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["birth_date"],
                "properties": {
                  "birth_date": {
                    "type": "string",
                    "description": "公历生辰",
                    "example": "1990-05-15T10:30"
                  },
                  "birth_place": {
                    "type": "string",
                    "default": "北京",
                    "description": "出生地（真太阳时等）"
                  },
                  "gender": {
                    "type": "string",
                    "description": "男/女 或 male/female / 1/0",
                    "example": "男"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "natal_fortune": { "type": "object", "description": "本命局相关分数与字段" },
                    "daily_fortune": { "type": "object", "description": "授权后为当日运势；未授权为 LOCKED 结构" },
                    "audit_status": { "type": "object" },
                    "logic_reference": { "type": "string" },
                    "SYSTEM_INSTRUCTION": { "type": "string", "description": "Agent 回复约定" }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": { "description": "参数错误" },
          "429": { "description": "IP 或 API Key 配额超限" },
          "500": { "description": "排盘失败" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "与用户「我的 API Key」中生成的 Key 一致；与老黄历 JSON 等共用配额。"
      }
    }
  }
}