openapi: 3.0.3
info:
  title: HallucC AI 幻觉检测 API
  description: |
    HallucC 提供 AI 内容幻觉检测、安全网关、Agent 验证能力。
    作为 Coze 插件使用时，可作为 Agent 内容安全校验节点。
  version: 1.0.0
  x-coze-plugin:
    name: HallucC 幻觉检测
    description: 检测 AI 生成内容中的事实性错误（幻觉），逐句标注可信度，附搜索来源链接。同时支持 Prompt 注入/越狱/有害内容检测。
    icon: https://aihcc.cloud/favicon.ico
    category: AI安全
    pricing: 按次计费（免费 2次/天，API版 ¥0.1/次）

servers:
  - url: https://aihcc.cloud/api
    description: HallucC 生产环境

security:
  - bearerAuth: []

paths:
  /detect:
    post:
      operationId: detectHallucination
      summary: 检测 AI 幻觉
      description: 对输入文本逐条提取声明，搜索验证，标注可信度
      parameters:
        - name: speed
          in: query
          schema: { type: string, enum: [fast, standard, deep], default: standard }
          description: 速度模式
        - name: domain
          in: query
          schema: { type: string, enum: [general, medical, legal, finance, education, government] }
          description: 领域模式
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, description: 待检测文本, maxLength: 50000 }
                strict: { type: boolean, description: 严格模式 }
      responses:
        '200':
          description: 检测结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectionResponse'

  /guard/check:
    post:
      operationId: checkSafety
      summary: AI 安全检测
      description: OWASP LLM Top 10 对齐的安全检测
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [output]
              properties:
                prompt: { type: string, description: 用户输入（可选） }
                output: { type: string, description: AI 响应文本 }
                check_hallucination: { type: boolean, description: 是否同时检测幻觉 }
      responses:
        '200':
          description: 安全检测结果

  /detect-agent-trajectory:
    post:
      operationId: detectAgentTrajectory
      summary: Agent 轨迹全链路检测
      description: |
        提交 Agent 执行轨迹（逐步 thought/action/action_input/observation/final_answer），
        做规则+裁判分层检测、六维评分、失败模式分类与幻觉传播 DAG。
        支持 fast/standard/deep 三档。这是「读取工作流完整执行记录」的入口——
        不再只校验最终输出，而是评估整条轨迹。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trajectory]
              properties:
                trajectory:
                  type: array
                  minItems: 1
                  maxItems: 20
                  description: Agent 轨迹步骤列表
                  items: { $ref: '#/components/schemas/TrajectoryStep' }
                task: { type: string, description: 原始任务指令（task_completion/scope_drift 裁判用） }
                tool_schemas: { type: object, description: 工具 JSON Schema 注册表（可选） }
                speed:
                  type: string
                  enum: [fast, standard, deep]
                  default: standard
                  description: 速度模式
                domain:
                  type: string
                  enum: [general, medical, legal, finance, education, government]
                  description: 领域模式
      responses:
        '200':
          description: 轨迹检测结果
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TrajectoryResponse' }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: HallucC API Key (hc_xxx)
  schemas:
    DetectionResponse:
      type: object
      properties:
        detection_id: { type: integer }
        summary:
          type: object
          properties:
            total: { type: integer }
            red: { type: integer }
            yellow: { type: integer }
            green: { type: integer }
            hallucination_risk: { type: number }
        claims:
          type: array
          items:
            type: object
            properties:
              claim: { $ref: '#/components/schemas/Claim' }
              verification: { $ref: '#/components/schemas/Verification' }
    Claim:
      type: object
      properties:
        id: { type: integer }
        text: { type: string }
        type: { type: string, enum: [factual, logical, subjective, common] }
    Verification:
      type: object
      properties:
        status: { type: string, enum: [supported, refuted, unverified] }
        confidence: { type: number }
        reason: { type: string }
        sources: { type: array, items: { type: object } }
    TrajectoryStep:
      type: object
      properties:
        step: { type: integer }
        thought: { type: string, description: 该步思考 }
        action: { type: string, description: 调用的工具名 }
        action_input: { type: string, description: 工具入参（JSON 字符串） }
        observation: { type: string, description: 工具实际输出 }
        final_answer: { type: string, description: 终答（通常仅末步有） }
    TrajectoryResponse:
      type: object
      properties:
        detection_id: { type: integer }
        summary:
          type: object
          properties:
            total_steps: { type: integer }
            hallucinated_steps: { type: integer }
            clean_steps: { type: integer }
            propagation_chains: { type: integer }
            llm_calls: { type: integer }
            search_calls: { type: integer }
            truncated: { type: boolean }
            dimensions:
              type: object
              description: 六维评分（tool_selection/parameter_validity/observation_faithfulness/reasoning_coherence/task_completion/trajectory_efficiency）
            risk_level: { type: string }
        steps:
          type: array
          items:
            type: object
            properties:
              step: { type: integer }
              action: { type: string }
              has_hallucination: { type: boolean }
              checks: { type: array, items: { type: object } }
        propagation:
          type: array
          description: 幻觉传播 DAG（from_step → to_steps，含 claim/confidence）
          items: { type: object }
        failure_modes:
          type: array
          items:
            type: object
            properties:
              code: { type: string, description: 失败模式码（如 SCHEMA_VIOLATION/CLAIM_MISMATCH/SCOPE_DRIFT） }
              step: { type: integer }
              severity: { type: string, enum: [low, medium, high] }