{
  "openapi": "3.0.3",
  "info": {
    "title": "循古排盘 Agent API",
    "version": "1.0.0",
    "description": "循古排盘 Agent API：禄命古法、六爻、大六壬 JSON 接口，供 OpenClaw 等 AI Agent 调用。完整说明见站点 /docs/agent-api；Bearer 鉴权与老黄历等接口共用 API Key 与每日配额。"
  },
  "servers": [
    {
      "url": "https://xungufa.com",
      "description": "请替换为 config.APP_URL 所指的生产域名（含协议，无尾部斜杠）"
    }
  ],
  "paths": {
    "/api/agent/bazi": {
      "post": {
        "operationId": "agentBaziScore",
        "summary": "禄命古法：本命摘要与（授权后）当日运势",
        "description": "未携带有效 Bearer Key 时仅返回鉴权与脱敏状态，不计算或返回个人命盘，且受 IP 日限流；携带有效 Key 时计入 Key / 用户日配额并返回命盘与当日运势。",
        "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": "男"
                  },
                  "time_method": {
                    "type": "string",
                    "description": "计时方法，可选「古法」或「现代」。未传时将自动计算两者比较。",
                    "example": "古法"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bazi": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "仅鉴权成功时返回的四柱八字",
                      "example": ["甲子", "乙丑", "丙寅", "丁卯"]
                    },
                    "auth_status": { "type": "string", "enum": ["AUTHENTICATED", "UNAUTHENTICATED"] },
                    "data_scope": { "type": "string", "description": "匿名响应固定为 REDACTED" },
                    "authentication": { "type": "object", "description": "匿名响应的鉴权元数据" },
                    "natal_fortune": { "type": "object", "description": "鉴权成功时为本命分数；匿名时只含 AUTHENTICATION_REQUIRED 状态" },
                    "daily_fortune": { "type": "object", "description": "鉴权成功时为当日运势；匿名时只含 AUTHENTICATION_REQUIRED 状态" },
                    "audit_status": { "type": "object" },
                    "logic_reference": { "type": "string" }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": { "description": "参数错误" },
          "429": { "description": "IP 或 API Key 配额超限" },
          "500": { "description": "排盘失败；响应不会包含内部异常信息" }
        }
      }
    },
    "/api/agent/liuyao": {
      "post": {
        "operationId": "agentLiuyao",
        "summary": "六爻：按当前农历时间起卦",
        "description": "与站点 /liuyao/api/time_lunar 逻辑一致。须携带有效 Bearer API Key；可选 time 覆盖起卦时刻，默认服务器当前时间。",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "time": {
                    "type": "string",
                    "description": "可选，公历起卦时刻；默认当前时间",
                    "example": "2026-06-15T14:30:00"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "起卦成功，含 result、cast_time、_time_detail 等" },
          "401": { "description": "缺少或无效 Bearer token" },
          "429": { "description": "API Key 配额超限" },
          "500": { "description": "起卦失败" }
        }
      }
    },
    "/api/agent/daliuren": {
      "post": {
        "operationId": "agentDaliuren",
        "summary": "大六壬：按当前公历时间起课",
        "description": "与站点 /daliuren/api/qike（mode=time）逻辑一致。须携带有效 Bearer API Key；返回时课/日课/月课 courses。",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "time": {
                    "type": "string",
                    "description": "可选，公历起课时刻；默认当前时间",
                    "example": "2026-06-15T14:30:00"
                  },
                  "guiren_mode": {
                    "type": "integer",
                    "default": 0,
                    "description": "贵人模式，与网页端一致"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "起课成功，含 meta、courses（shi/ri/yue）、cast_time" },
          "401": { "description": "缺少或无效 Bearer token" },
          "429": { "description": "API Key 配额超限" },
          "500": { "description": "起课失败" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "与用户「我的 API Key」中生成的 Key 一致；与老黄历 JSON 等共用配额。"
      }
    }
  }
}
