{
  "tools": [
    {
      "name": "res-query",
      "description": "Query records with filters, joins, aggregates, ordering, and pagination.\rThe main resource and each hasOne/hasMany relation are independent query contexts; inner/left/right are JOINs within their parent context.\rTop-level conditions / groupBy / orderBy / limit / offset apply to the main resource SQL. Each relation has its own conditions / groupBy / orderBy / limit that apply to that relation's SQL.\rIMPORTANT:\r(1) All field codes MUST come from res-schema results already in this conversation — never guess or infer field names.\r(2) Fields belonging to a hasOne/hasMany context must use object form with codeResource set to that relation's code.\r(3) Call res-schema first if the resource schema has not been fetched yet.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "conditions": {
            "type": "object",
            "properties": {
              "children": {
                "type": "array",
                "items": {
                  "$ref": "#/properties/conditions"
                },
                "title": "子条件",
                "description": "子条件节点，递归结构"
              },
              "exprs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string",
                      "title": "字段编码",
                      "description": "必须来自 res-schema 返回的字段列表，禁止猜测字段名"
                    },
                    "fieldResource": {
                      "type": "string",
                      "title": "所属资源",
                      "description": "字段所属资源标识，取值为主资源编码或当前查询上下文（conditions 所在层级）对应的 relations[].code"
                    },
                    "fieldSqlFunc": {
                      "type": "string",
                      "title": "列SQL函数",
                      "description": "对列应用 SQL 函数后再参与比较，拼接为 {func}({fieldResource}.{field}) {operator} {token}。\r\n支持 SQL-92 / SQL:1999 / SQL:2003 标准函数及数据库方言函数，如 DATE、UPPER、ROUND。\r\n需要第二参数的函数（如 ROUND、CAST）配合 fieldSqlFuncParam 使用。"
                    },
                    "fieldSqlFuncParam": {
                      "type": "string",
                      "title": "列SQL函数参数",
                      "description": "fieldSqlFunc 的附加参数，按函数类型用途不同：\r\r通用函数（有 param 时）：{func}({fieldResource}.{field}, {fieldSqlFuncParam}) {operator} {token}\r  示例：ROUND(col, 2) → fieldSqlFuncParam=\\\"2\\\"\r        SUBSTRING(col, 1, 10) → fieldSqlFuncParam=\\\"1, 10\\\""
                    },
                    "ignoreEmptyParam": {
                      "type": "boolean",
                      "title": "忽略空参数",
                      "description": "当 tokenType=param 且请求参数值为空（空字符串或 null）时，跳过该条件不生成 SQL。用于实现可选过滤项",
                      "default": false
                    },
                    "operator": {
                      "type": "string",
                      "title": "运算符",
                      "description": "标准 SQL 比较运算符：\r\n= / != / > / >= / < / <=\r\nLIKE：模糊匹配（%keyword%）\r\nIN：包含，value 逗号分隔多值\r\nIS NULL / IS NOT NULL：空值判断，无需 value\r\nREGEXP：正则匹配",
                      "default": "="
                    },
                    "token": {
                      "type": "string",
                      "title": "比较值",
                      "description": "比较目标，内容由 tokenType 决定。operator 为 IS NULL/IS NOT NULL 时可省略"
                    },
                    "tokenType": {
                      "type": "string",
                      "title": "比较值类型",
                      "description": "先选类型再填 token：\r\nstring：token 填字面量如 '2024-01-01'\r\nfunc：token 填内置函数名 UserID|UserUuid|UserRolesUuid|UserPlatform|UserSaaS\r\nparam：token 填请求参数路径如 body.status\r\nsql：token 填原始SQL如 CURRENT_DATE",
                      "default": "string",
                      "enum": [
                        "string",
                        "func"
                      ]
                    }
                  },
                  "title": "条件项",
                  "description": "单条比较表达式，生成 [{fieldSqlFunc}(]{fieldResource}.{field}[)] {operator} {token} 片段",
                  "required": [
                    "field",
                    "operator"
                  ]
                },
                "title": "条件表达式列表",
                "description": "当前层的叶子比较列表，每项生成一个 {fieldResource}.{field} {operator} {token} 片段，同层多项以 type 连接"
              },
              "type": {
                "type": "string",
                "title": "逻辑连接符",
                "description": "当前节点的逻辑运算符，将 exprs 各项与 children 各组以 AND 或 OR 连接",
                "default": "and",
                "enum": [
                  "and",
                  "or"
                ]
              }
            },
            "title": "树形查询条件",
            "description": "WHERE 条件树。\rexprs 每项生成一段比较：[{fieldSqlFunc}(]{fieldResource}.{field}[)] {operator} {token}，同层多项以 type(and/or) 连接；\rchildren 为同结构子节点，递归嵌套实现复杂过滤。",
            "required": [
              "exprs",
              "type"
            ]
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "alias": {
                  "type": "string",
                  "title": "别名",
                  "description": "输出字段别名，对应 SQL AS。isExpr=true 时必填，否则结果列无法被引用；普通字段不填则默认使用 code 值"
                },
                "code": {
                  "type": "string",
                  "title": "字段编码",
                  "description": "两种互斥用法，每个对象只能选其一：\r1. 字段编码，格式为 {Resource}.{field}，Resource 取值为主资源编码或 relations[].code，如 User.amount / Order.price，isExpr 保持默认 false\r2. 原始 SQL 表达式（如 COUNT(*) / SUM(amount)），必须同时设置 isExpr = true，且 alias 必填\r注意：SELECT 中混入聚合表达式与非聚合字段时，需配合 groupBy 使用，否则结果不符合预期\r重要：字段编码必须来自 res-schema 返回的字段列表，禁止猜测或推断字段名"
                },
                "codeResource": {
                  "type": "string",
                  "title": "所属资源",
                  "description": "字段所属的表标识，取值为主资源编码或 relations[].code"
                },
                "dataType": {
                  "type": "string",
                  "title": "数据类型",
                  "description": "指定字段的返回数据类型，影响序列化方式；不填则由资源字段定义决定",
                  "default": "string",
                  "enum": [
                    "string",
                    "bool",
                    "number",
                    "array",
                    "json",
                    "integer",
                    "float"
                  ]
                },
                "isExpr": {
                  "type": "boolean",
                  "title": "是否表达式",
                  "description": "设为 true 时，code 内容作为原始 SQL 表达式拼入 SELECT（如聚合函数 COUNT(*) / SUM(amount)），而非普通字段编码。isExpr=true 时 alias 为必填项",
                  "default": false
                }
              },
              "title": "资源字段",
              "description": "结构化字段，支持指定所属资源、输出别名、聚合表达式及数据类型",
              "required": [
                "code",
                "codeResource"
              ]
            },
            "title": "查询字段",
            "description": "SELECT 字段列表，涵盖所有查询上下文（主资源 + 所有 hasOne/hasMany），通过 codeResource 路由到对应的独立 SQL。不传则返回所有字段。\r主资源和每个 hasOne/hasMany 各是一个独立查询上下文，inner/left/right 只是其所在上下文内的 JOIN。\r仅查询聚合结果（如 COUNT(*) / SUM(amount)）时，fields 只传聚合字段，不要混入普通字段，除非同时提供 groupBy。\r重要：所有字段编码必须先通过 res-schema 确认，禁止凭名称语义猜测"
          },
          "groupBy": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "title": "字段编码",
                  "description": "格式必须为 {Resource}.{field}，如 User.status。\r{Resource} 取值为主资源编码或 relations[].code"
                },
                {
                  "type": "object",
                  "properties": {
                    "expr": {
                      "type": "string",
                      "title": "表达式",
                      "description": "type=field 时填 {Resource}.{field}（如 User.status）\rtype=sql 时填原始 SQL 表达式（如 DATE(created_at)）"
                    },
                    "type": {
                      "type": "string",
                      "title": "表达式类型",
                      "description": "field：按资源字段分组，expr 填 {Resource}.{field}，如 User.status\rsql：按原始 SQL 表达式分组，expr 填任意合法 SQL，如 DATE(created_at)",
                      "default": "sql",
                      "enum": [
                        "field",
                        "sql"
                      ]
                    }
                  },
                  "title": "分组表达式",
                  "description": "结构化分组项，type=field 用于资源字段，type=sql 用于原始 SQL 表达式",
                  "required": [
                    "expr",
                    "type"
                  ]
                }
              ]
            },
            "title": "分组规则",
            "description": "GROUP BY 列表，配合 fields 中的聚合表达式使用。\r字段必须带资源前缀（{Resource}.{field}）；聚合函数（COUNT / SUM 等）放在 fields 中，不属于此处"
          },
          "limit": {
            "type": "integer",
            "title": "每页条数",
            "description": "当前查询上下文返回的最大记录数（顶层时限制主资源结果，relations 内时限制该关联结果）",
            "default": 30
          },
          "offset": {
            "type": "integer",
            "title": "偏移量",
            "description": "主资源查询跳过的记录数，仅顶层有效，relations 内不支持",
            "default": 0
          },
          "orderBy": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "title": "字段编码",
                  "description": "格式必须为 {Resource}.{field}，如 User.created_at，默认升序（ASC）。\r需要降序或使用 SQL 表达式时使用对象形式"
                },
                {
                  "type": "object",
                  "properties": {
                    "direction": {
                      "type": "string",
                      "title": "排序方向",
                      "default": "asc",
                      "enum": [
                        "asc",
                        "desc"
                      ]
                    },
                    "expr": {
                      "type": "string",
                      "title": "表达式",
                      "description": "type=field 时填 {Resource}.{field}（如 User.created_at）；type=sql 时填原始 SQL 表达式（如 COUNT(*) / DATE(created_at)）"
                    },
                    "type": {
                      "type": "string",
                      "title": "表达式类型",
                      "description": "field：按资源字段排序，expr 填 {Resource}.{field}，如 User.created_at\rsql：按原始 SQL 表达式排序，expr 填任意合法 SQL，如 COUNT(*) / DATE(created_at)",
                      "default": "field",
                      "enum": [
                        "field",
                        "sql"
                      ]
                    }
                  },
                  "title": "排序表达式",
                  "description": "结构化排序项，type=field 用于资源字段，type=sql 用于原始 SQL 表达式",
                  "required": [
                    "type",
                    "expr"
                  ]
                }
              ]
            },
            "title": "排序规则",
            "description": "ORDER BY 列表，多项按顺序依次应用。\r字段必须带资源前缀（{Resource}.{field}）；需要降序或 SQL 表达式排序时使用对象形式"
          },
          "relations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "actuallyField": {
                  "type": "string",
                  "title": "实际资源字段",
                  "description": "目标资源（code）参与 ON 条件的字段"
                },
                "actuallyResource": {
                  "type": "string",
                  "title": "实际资源",
                  "description": "被关联的目标资源编码（相当于 SQL 表名）。JOIN 拼接为：{type} JOIN {actuallyResource} AS {code} ON {code}.{actuallyField} = {relationResource}.{relationField}"
                },
                "code": {
                  "type": "string",
                  "title": "关联标识",
                  "description": "关联唯一标识，同时作为别名：JOIN 时为表别名（AS code），子查询时为结果 JSON 字段的键名。\r通常与 actuallyResource 保持一致；仅当多个关联引用同一资源导致冲突时，才需要重命名加以区分"
                },
                "conditions": {
                  "$ref": "#/properties/conditions",
                  "description": "该关联的过滤条件，结构与顶层 conditions 相同。hasOne/hasMany 作用于子查询 WHERE；inner/left/right 作用于 JOIN ON 或主查询 WHERE"
                },
                "groupBy": {
                  "$ref": "#/properties/groupBy",
                  "description": "该关联的 GROUP BY，仅 hasOne/hasMany 子查询生效，结构与顶层 groupBy 相同"
                },
                "limit": {
                  "$ref": "#/properties/limit",
                  "description": "该关联的最大返回条数，仅 hasOne/hasMany 子查询生效，结构与顶层 limit 相同"
                },
                "name": {
                  "type": "string",
                  "title": "关联名称",
                  "description": "关联的显示名称"
                },
                "orderBy": {
                  "$ref": "#/properties/orderBy",
                  "description": "该关联的 ORDER BY，仅 hasOne/hasMany 子查询生效，结构与顶层 orderBy 相同"
                },
                "relationField": {
                  "type": "string",
                  "title": "被关联资源字段",
                  "description": "ON 条件对端资源的字段"
                },
                "relationResource": {
                  "type": "string",
                  "title": "被关联资源",
                  "description": "ON 条件对端的资源编码（通常为主资源或父关联资源）"
                },
                "type": {
                  "type": "string",
                  "title": "关联类型",
                  "description": "关联模式：\r\ninner / left / right：SQL JOIN，要求与主资源同一数据库连接，将关联字段合并到主查询行\r\nhasOne：独立子查询，支持跨库，结果聚合为单个对象（result[code] = {}）\r\nhasMany：独立子查询，支持跨库，结果聚合为对象数组（result[code] = [...]）\r\n跨数据库连接的关联必须使用 hasOne 或 hasMany",
                  "enum": [
                    "inner",
                    "left",
                    "right",
                    "hasOne",
                    "hasMany"
                  ]
                }
              },
              "required": [
                "actuallyField",
                "actuallyResource",
                "code",
                "relationField",
                "relationResource",
                "type"
              ]
            },
            "title": "资源关联",
            "description": "关联配置列表。\rinner / left / right：SQL JOIN，要求关联资源与主资源在同一数据库连接，将关联字段合并到主查询行。\rhasOne / hasMany：独立子查询，支持跨数据库连接，结果聚合为 JSON 字段（hasOne 为单对象，hasMany 为数组）。\r跨库关联必须使用 hasOne 或 hasMany，不可使用 JOIN 类型。"
          },
          "resource": {
            "type": "string",
            "title": "主资源",
            "description": "主资源编码（resource_code），作为本次查询的根上下文，relations 中的关联资源均以此为基础展开"
          }
        },
        "required": [
          "fields",
          "resource"
        ]
      },
      "annotations": {}
    }
  ]
}