@social-data/social-neuron-user-query 0.0.0-stage → 1.0.0-beta.1

package/manifest.json

@@ -0,0 +1,1986 @@
+{
+  "revision": 9,
+  "capability": "user-query",
+  "command": "social-neuron-user-query",
+  "default_action": null,
+  "mcp_path": "/user-query/mcp",
+  "tools": [
+    {
+      "action": "aggregate",
+      "op": "aggregate",
+      "name": "user-query/aggregate",
+      "summary": "画像分布统计:group_by 声明树 + metrics(含 min/max)。",
+      "description": "画像分布统计:group_by 声明树 + metrics(含 min/max)。\n\n粉丝量分档 range(long_followerCount)、地域/性别 terms(kw_province/kw_gender)、认证 terms(bool_verified)。\n⚠ 聚合须用 kw_ 字段(text_ 不可聚合)。",
+      "input_schema": {
+        "$defs": {
+          "AndNode": {
+            "additionalProperties": false,
+            "properties": {
+              "and": {
+                "description": "全部满足(编译为 bool.filter);至少 1 个条件",
+                "items": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/$defs/AndNode"
+                    },
+                    {
+                      "$ref": "#/$defs/OrNode"
+                    },
+                    {
+                      "$ref": "#/$defs/NotNode"
+                    },
+                    {
+                      "$ref": "#/$defs/Leaf"
+                    }
+                  ]
+                },
+                "minItems": 1,
+                "title": "And",
+                "type": "array"
+              }
+            },
+            "required": [
+              "and"
+            ],
+            "title": "AndNode",
+            "type": "object"
+          },
+          "GroupLevel": {
+            "additionalProperties": false,
+            "description": "一层分组声明。``group_by`` 递归 = 嵌套子层;缺省 = 本层为叶子(设计 §3.1)。",
+            "properties": {
+              "name": {
+                "description": "本层聚合名(出参 key)",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,31}$",
+                "title": "Name",
+                "type": "string"
+              },
+              "type": {
+                "description": "聚合类型;须与字段 data_type 匹配(§3.1.1)",
+                "enum": [
+                  "terms",
+                  "range",
+                  "histogram",
+                  "date_histogram"
+                ],
+                "title": "Type",
+                "type": "string"
+              },
+              "field": {
+                "description": "被分组字段 name_en",
+                "maxLength": 128,
+                "minLength": 1,
+                "title": "Field",
+                "type": "string"
+              },
+              "size": {
+                "anyOf": [
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "terms 桶数上限;缺省 10,≤ agg_max_size",
+                "title": "Size"
+              },
+              "order": {
+                "anyOf": [
+                  {
+                    "$ref": "#/$defs/Order"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "terms 桶排序;缺省 count desc"
+              },
+              "ranges": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "$ref": "#/$defs/RangeBucket"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "range 档位,左闭右开",
+                "title": "Ranges"
+              },
+              "interval": {
+                "anyOf": [
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "histogram 数值间隔;date_histogram 粒度 hour|day|week|month",
+                "title": "Interval"
+              },
+              "group_by": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "$ref": "#/$defs/GroupLevel"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "嵌套子层(递归);缺省=本层为叶子",
+                "title": "Group By"
+              }
+            },
+            "required": [
+              "name",
+              "type",
+              "field"
+            ],
+            "title": "GroupLevel",
+            "type": "object"
+          },
+          "Leaf": {
+            "additionalProperties": false,
+            "description": "叶子条件 ``{field, op, value}``;value 传 ES 真实值(不翻译)。",
+            "properties": {
+              "field": {
+                "description": "字段 name_en",
+                "maxLength": 128,
+                "minLength": 1,
+                "title": "Field",
+                "type": "string"
+              },
+              "op": {
+                "description": "操作符;须在字段 data_type 允许集合内(§1.5)",
+                "enum": [
+                  "eq",
+                  "in",
+                  "match",
+                  "match_phrase",
+                  "gt",
+                  "gte",
+                  "lt",
+                  "lte",
+                  "exists"
+                ],
+                "title": "Op",
+                "type": "string"
+              },
+              "value": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "items": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "boolean"
+                        }
+                      ]
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "ES 真实值;in 传数组;exists 无需 value",
+                "title": "Value"
+              }
+            },
+            "required": [
+              "field",
+              "op"
+            ],
+            "title": "Leaf",
+            "type": "object"
+          },
+          "Metric": {
+            "additionalProperties": false,
+            "properties": {
+              "op": {
+                "description": "聚合算子;sum/avg/min/max 需 long/double 字段(min=最小值,如最少粉丝数)",
+                "enum": [
+                  "count",
+                  "sum",
+                  "avg",
+                  "min",
+                  "max"
+                ],
+                "title": "Op",
+                "type": "string"
+              },
+              "field": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "被聚合字段;count 无需",
+                "title": "Field"
+              }
+            },
+            "required": [
+              "op"
+            ],
+            "title": "Metric",
+            "type": "object"
+          },
+          "NotNode": {
+            "additionalProperties": false,
+            "properties": {
+              "not": {
+                "anyOf": [
+                  {
+                    "$ref": "#/$defs/AndNode"
+                  },
+                  {
+                    "$ref": "#/$defs/OrNode"
+                  },
+                  {
+                    "$ref": "#/$defs/NotNode"
+                  },
+                  {
+                    "$ref": "#/$defs/Leaf"
+                  }
+                ],
+                "description": "取反(编译为 bool.must_not)",
+                "title": "Not"
+              }
+            },
+            "required": [
+              "not"
+            ],
+            "title": "NotNode",
+            "type": "object"
+          },
+          "OrNode": {
+            "additionalProperties": false,
+            "properties": {
+              "or": {
+                "description": "任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件",
+                "items": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/$defs/AndNode"
+                    },
+                    {
+                      "$ref": "#/$defs/OrNode"
+                    },
+                    {
+                      "$ref": "#/$defs/NotNode"
+                    },
+                    {
+                      "$ref": "#/$defs/Leaf"
+                    }
+                  ]
+                },
+                "minItems": 1,
+                "title": "Or",
+                "type": "array"
+              }
+            },
+            "required": [
+              "or"
+            ],
+            "title": "OrNode",
+            "type": "object"
+          },
+          "Order": {
+            "additionalProperties": false,
+            "properties": {
+              "by": {
+                "description": "排序依据:\"count\" 或 metrics 里的某个名字(如 avg_long_followerCount)",
+                "title": "By",
+                "type": "string"
+              },
+              "direction": {
+                "default": "desc",
+                "description": "排序方向",
+                "enum": [
+                  "asc",
+                  "desc"
+                ],
+                "title": "Direction",
+                "type": "string"
+              }
+            },
+            "required": [
+              "by"
+            ],
+            "title": "Order",
+            "type": "object"
+          },
+          "RangeBucket": {
+            "additionalProperties": false,
+            "properties": {
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "下界(含);省=负无穷",
+                "title": "From"
+              },
+              "to": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "上界(不含);省=正无穷",
+                "title": "To"
+              }
+            },
+            "title": "RangeBucket",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "query_summary": {
+            "description": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。",
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Query Summary",
+            "type": "string"
+          },
+          "platform": {
+            "description": "单个账号库 name_en(用 list-platforms 查)",
+            "minLength": 1,
+            "title": "Platform",
+            "type": "string"
+          },
+          "where": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/AndNode"
+              },
+              {
+                "$ref": "#/$defs/OrNode"
+              },
+              {
+                "$ref": "#/$defs/NotNode"
+              },
+              {
+                "$ref": "#/$defs/Leaf"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "布尔条件树(可选);时间过滤用 date_udate/date_idate",
+            "title": "Where"
+          },
+          "group_by": {
+            "description": "分组声明树;顶层数组=并列聚合",
+            "items": {
+              "$ref": "#/$defs/GroupLevel"
+            },
+            "title": "Group By",
+            "type": "array"
+          },
+          "metrics": {
+            "description": "指标;挂在每一层",
+            "items": {
+              "$ref": "#/$defs/Metric"
+            },
+            "title": "Metrics",
+            "type": "array"
+          }
+        },
+        "required": [
+          "query_summary",
+          "platform",
+          "group_by",
+          "metrics"
+        ],
+        "title": "AggregateInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": true,
+        "properties": {
+          "took_ms": {
+            "description": "ES 耗时(毫秒)",
+            "title": "Took Ms",
+            "type": "integer"
+          },
+          "truncated": {
+            "description": "任一 terms 层 sum_other_doc_count>0",
+            "title": "Truncated",
+            "type": "boolean"
+          },
+          "warnings": {
+            "description": "部分索引不存在等提示;空=结果完整",
+            "items": {
+              "type": "string"
+            },
+            "title": "Warnings",
+            "type": "array"
+          },
+          "trace_id": {
+            "description": "查询审计标识",
+            "title": "Trace Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "took_ms",
+          "truncated",
+          "trace_id"
+        ],
+        "title": "AggregateOutput",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--query-summary",
+          "field": "query_summary",
+          "type": "string",
+          "required": true,
+          "desc": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。"
+        },
+        {
+          "flag": "--platform",
+          "field": "platform",
+          "type": "string",
+          "required": true,
+          "desc": "单个账号库 name_en(用 list-platforms 查)"
+        },
+        {
+          "flag": "--where",
+          "field": "where",
+          "type": "object(json)",
+          "required": false,
+          "desc": "布尔条件树(可选);时间过滤用 date_udate/date_idate"
+        },
+        {
+          "flag": "--group-by",
+          "field": "group_by",
+          "type": "list[object](json)",
+          "required": true,
+          "desc": "分组声明树;顶层数组=并列聚合"
+        },
+        {
+          "flag": "--metrics",
+          "field": "metrics",
+          "type": "list[object](json)",
+          "required": true,
+          "desc": "指标;挂在每一层"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/aggregate",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "describe-capability",
+      "op": "describe_capability",
+      "name": "user-query/describe_capability",
+      "summary": "能力总览(agent 起点):查什么数据、有哪些账号库及各自画像、查询模型、取值约定、规模闸。",
+      "description": "能力总览(agent 起点):查什么数据、有哪些账号库及各自画像、查询模型、取值约定、规模闸。",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "$defs": {
+          "LibrarySummary": {
+            "additionalProperties": false,
+            "description": "单个账号库的画像 —— 让 agent 知道\"这个库有多少字段、主键是什么、能按什么搜\"。",
+            "properties": {
+              "name_en": {
+                "description": "账号库 name_en(get_user/search 的 platform 入参,即索引名主体)",
+                "title": "Name En",
+                "type": "string"
+              },
+              "name": {
+                "description": "库中文名(如 抖音账号)",
+                "title": "Name",
+                "type": "string"
+              },
+              "field_count": {
+                "description": "该库字段数(各库差异大,抖音 234、公众号 35)",
+                "title": "Field Count",
+                "type": "integer"
+              },
+              "has_follower": {
+                "description": "是否有 long_followerCount(可按粉丝量排序/分档)",
+                "title": "Has Follower",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name_en",
+              "name",
+              "field_count",
+              "has_follower"
+            ],
+            "title": "LibrarySummary",
+            "type": "object"
+          },
+          "Limits": {
+            "additionalProperties": false,
+            "description": "规模闸(配置化)—— agent 据此预判边界,避免被拒后盲试。",
+            "properties": {
+              "query_default_size": {
+                "description": "get_user/search 默认返回条数",
+                "title": "Query Default Size",
+                "type": "integer"
+              },
+              "query_max_size": {
+                "description": "单次上限",
+                "title": "Query Max Size",
+                "type": "integer"
+              },
+              "where_max_depth": {
+                "description": "where 规范化后允许的最大嵌套深度",
+                "title": "Where Max Depth",
+                "type": "integer"
+              },
+              "agg_max_depth": {
+                "description": "聚合最大嵌套层数",
+                "title": "Agg Max Depth",
+                "type": "integer"
+              },
+              "agg_max_width": {
+                "description": "每层并列分支上限",
+                "title": "Agg Max Width",
+                "type": "integer"
+              },
+              "agg_max_size": {
+                "description": "单层 terms.size 上限",
+                "title": "Agg Max Size",
+                "type": "integer"
+              },
+              "agg_bucket_budget": {
+                "description": "聚合总桶数预算",
+                "title": "Agg Bucket Budget",
+                "type": "integer"
+              }
+            },
+            "required": [
+              "query_default_size",
+              "query_max_size",
+              "where_max_depth",
+              "agg_max_depth",
+              "agg_max_width",
+              "agg_max_size",
+              "agg_bucket_budget"
+            ],
+            "title": "Limits",
+            "type": "object"
+          },
+          "UserCoverage": {
+            "additionalProperties": false,
+            "properties": {
+              "platforms": {
+                "description": "账号库数量",
+                "title": "Platforms",
+                "type": "integer"
+              },
+              "libraries": {
+                "description": "逐库画像(下钻指引)",
+                "items": {
+                  "$ref": "#/$defs/LibrarySummary"
+                },
+                "title": "Libraries",
+                "type": "array"
+              }
+            },
+            "required": [
+              "platforms",
+              "libraries"
+            ],
+            "title": "UserCoverage",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "description": "能力总览(agent 起点):查什么数据、覆盖范围、查询模型、规模闸、下钻指引。",
+        "properties": {
+          "data": {
+            "description": "数据类型(用户)",
+            "title": "Data",
+            "type": "string"
+          },
+          "description": {
+            "description": "能力一句话说明",
+            "title": "Description",
+            "type": "string"
+          },
+          "coverage": {
+            "$ref": "#/$defs/UserCoverage",
+            "description": "覆盖范围 + 逐库画像"
+          },
+          "query_model": {
+            "description": "查询模型说明(必填入参与 where 的关系)",
+            "title": "Query Model",
+            "type": "string"
+          },
+          "value_convention": {
+            "description": "取值约定:一律传 ES 真实值,系统不翻译",
+            "title": "Value Convention",
+            "type": "string"
+          },
+          "limits": {
+            "$ref": "#/$defs/Limits",
+            "description": "规模闸"
+          },
+          "discovery": {
+            "description": "其余发现接口名(下钻指引)",
+            "items": {
+              "type": "string"
+            },
+            "title": "Discovery",
+            "type": "array"
+          },
+          "query_tools": {
+            "description": "查询工具名",
+            "items": {
+              "type": "string"
+            },
+            "title": "Query Tools",
+            "type": "array"
+          }
+        },
+        "required": [
+          "data",
+          "description",
+          "coverage",
+          "query_model",
+          "value_convention",
+          "limits",
+          "discovery",
+          "query_tools"
+        ],
+        "title": "CapabilityOverview",
+        "type": "object"
+      },
+      "flags": [],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/describe_capability",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "get-field-examples",
+      "op": "get_field_examples",
+      "name": "user-query/get_field_examples",
+      "summary": "批量取字段样例值,看数据长相(如 kw_nickName / long_followerCount)。",
+      "description": "批量取字段样例值,看数据长相(如 kw_nickName / long_followerCount)。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "fields": {
+            "description": "想看样例值的字段 name_en 名单(如 kw_nickName / long_followerCount)",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "title": "Fields",
+            "type": "array"
+          }
+        },
+        "required": [
+          "fields"
+        ],
+        "title": "FieldExamplesInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "{字段 name_en: 样例值};**只含有样例的字段**,其余见 warnings",
+            "title": "Items",
+            "type": "object"
+          },
+          "warnings": {
+            "description": "未返回样例的字段说明(字段无 example_value,或名字拼错);空=要的都给了",
+            "items": {
+              "type": "string"
+            },
+            "title": "Warnings",
+            "type": "array"
+          }
+        },
+        "required": [
+          "items"
+        ],
+        "title": "FieldExamples",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--fields",
+          "field": "fields",
+          "type": "list[str](json)",
+          "required": true,
+          "desc": "想看样例值的字段 name_en 名单(如 kw_nickName / long_followerCount)"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/get_field_examples",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "get-field-values",
+      "op": "get_field_values",
+      "name": "user-query/get_field_values",
+      "summary": "取字段值字典 [{code, value}] —— 枚举/code 字段的全部合法取值。",
+      "description": "取字段值字典 [{code, value}] —— 枚举/code 字段的全部合法取值。\n\n账号库字段多为明文;**空列表原样返回**(明文字段无字典,或该字段未配值来源)。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "field": {
+            "description": "字段 name_en;仅 is_enum/is_code 的字段有值字典(账号库多为明文,少数标签/类型字段有字典)",
+            "title": "Field",
+            "type": "string"
+          },
+          "keyword": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "按值/code 模糊过滤;不传=全量",
+            "title": "Keyword"
+          }
+        },
+        "required": [
+          "field"
+        ],
+        "title": "FieldValuesInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "$defs": {
+          "FieldValue": {
+            "additionalProperties": false,
+            "properties": {
+              "code": {
+                "description": "值 code(enum 的 code / 知识中心的 tagCode)",
+                "title": "Code",
+                "type": "string"
+              },
+              "value": {
+                "description": "人话(enum 的 value / 知识中心的 tagName)",
+                "title": "Value",
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "value"
+            ],
+            "title": "FieldValue",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "field": {
+            "description": "字段 name_en",
+            "title": "Field",
+            "type": "string"
+          },
+          "items": {
+            "description": "值字典 [{code, value}]",
+            "items": {
+              "$ref": "#/$defs/FieldValue"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "field",
+          "items",
+          "total"
+        ],
+        "title": "FieldValueList",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--field",
+          "field": "field",
+          "type": "string",
+          "required": true,
+          "desc": "字段 name_en;仅 is_enum/is_code 的字段有值字典(账号库多为明文,少数标签/类型字段有字典)"
+        },
+        {
+          "flag": "--keyword",
+          "field": "keyword",
+          "type": "string",
+          "required": false,
+          "desc": "按值/code 模糊过滤;不传=全量"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/get_field_values",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "get-query",
+      "op": "get_query",
+      "name": "user-query/get_query",
+      "summary": "凭 trace_id 回看历史查询:原始入参、实际 DSL、命中索引与结果摘要。",
+      "description": "凭 trace_id 回看历史查询:原始入参、实际 DSL、命中索引与结果摘要。\n只能回看**本人**发起的查询。\n⚠ 审计异步落库,查询刚返回时通常还没写入,请至少等 30 秒再回看(否则同样返回 40426)。\n审计只保留近 3 个月(ILM),更早的 trace_id 查不到。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "trace_id": {
+            "description": "查询响应里返回的审计标识 trace_id(如 tr_703781746697984)",
+            "pattern": "^tr_\\d{1,16}$",
+            "title": "Trace Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "trace_id"
+        ],
+        "title": "GetQueryInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": false,
+        "description": "出参即审计文档去掉请求人字段;三个 JSON 字符串在服务端解析回对象(截断过的旧文档原样给串)。",
+        "properties": {
+          "trace_id": {
+            "description": "审计标识,与入参一致",
+            "title": "Trace Id",
+            "type": "string"
+          },
+          "queried_at": {
+            "description": "查询发起时间(东八区,无偏移)",
+            "title": "Queried At",
+            "type": "string"
+          },
+          "capability": {
+            "description": "能力 key",
+            "title": "Capability",
+            "type": "string"
+          },
+          "tool": {
+            "description": "查询工具:get_user / search / aggregate",
+            "title": "Tool",
+            "type": "string"
+          },
+          "env": {
+            "description": "写入环境后缀:test / prod",
+            "title": "Env",
+            "type": "string"
+          },
+          "schema_version": {
+            "description": "审计文档结构版本",
+            "title": "Schema Version",
+            "type": "string"
+          },
+          "status": {
+            "description": "当次查询结果:ok / error",
+            "title": "Status",
+            "type": "string"
+          },
+          "query_summary": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "当次的中文意图概括",
+            "title": "Query Summary"
+          },
+          "structured_params": {
+            "description": "当次**原始入参**(对象)—— 回放:原样作为 get_user/search/aggregate 的入参再跑即可;历史截断文档给原始字符串",
+            "title": "Structured Params"
+          },
+          "compiled_dsl": {
+            "description": "当次实际执行的 ES DSL(对象,原文全量);历史截断文档给原始字符串",
+            "title": "Compiled Dsl"
+          },
+          "resolved_indices": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "实际命中的索引",
+            "title": "Resolved Indices"
+          },
+          "missing_indices": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "探活缺失的模式;空 = 全覆盖",
+            "title": "Missing Indices"
+          },
+          "result": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "{total, tookMs, elapsedMs, returned, truncated};status=error 时为 null",
+            "title": "Result"
+          },
+          "warnings": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "当次的告警原文",
+            "title": "Warnings"
+          },
+          "warning_kinds": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "告警枚举:partial_index_missing / shard_failure / timeout",
+            "title": "Warning Kinds"
+          },
+          "error": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "{code, msg};status=ok 时为 null",
+            "title": "Error"
+          },
+          "result_sample": {
+            "description": "结果头部切片(对象,结构感知截断,内置 _truncated 标记);空结果/失败为 null",
+            "title": "Result Sample"
+          }
+        },
+        "required": [
+          "trace_id",
+          "queried_at",
+          "capability",
+          "tool",
+          "env",
+          "schema_version",
+          "status",
+          "query_summary",
+          "structured_params",
+          "compiled_dsl",
+          "resolved_indices",
+          "missing_indices",
+          "result",
+          "warnings",
+          "warning_kinds",
+          "error",
+          "result_sample"
+        ],
+        "title": "GetQueryOutput",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--trace-id",
+          "field": "trace_id",
+          "type": "string",
+          "required": true,
+          "desc": "查询响应里返回的审计标识 trace_id(如 tr_703781746697984)"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/get_query",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "get-user",
+      "op": "get_user",
+      "name": "user-query/get_user",
+      "summary": "按账号 ID 批量精确取画像:单库 + uids(一次≤10000)。",
+      "description": "按账号 ID 批量精确取画像:单库 + uids(一次≤10000)。\n\n不传 fields 返回画像常用字段;传 fields 只返回指定。命中与否按入参 uids 对账,给 found/not_found。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "query_summary": {
+            "description": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。",
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Query Summary",
+            "type": "string"
+          },
+          "platform": {
+            "description": "单个账号库 name_en(用 list-platforms 查)",
+            "minLength": 1,
+            "title": "Platform",
+            "type": "string"
+          },
+          "uids": {
+            "description": "账号 ID 列表(kw_uid 值);单个也写成数组;一次最多 get_user_max_uids(默认 10000),超了拒",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "title": "Uids",
+            "type": "array"
+          },
+          "fields": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "出参投影;不传=画像常用字段(DEFAULT_FIELDS),传则只返回指定;要全量先 list-fields 拿字段名",
+            "title": "Fields"
+          }
+        },
+        "required": [
+          "query_summary",
+          "platform",
+          "uids"
+        ],
+        "title": "GetUserInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": true,
+        "properties": {
+          "platform": {
+            "description": "账号库 name_en",
+            "title": "Platform",
+            "type": "string"
+          },
+          "requested": {
+            "description": "入参 uids 个数",
+            "title": "Requested",
+            "type": "integer"
+          },
+          "found": {
+            "description": "命中账号(每条含投影字段,含 kw_uid)",
+            "items": {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            "title": "Found",
+            "type": "array"
+          },
+          "not_found": {
+            "description": "查无的 uid(按入参对账)",
+            "items": {
+              "type": "string"
+            },
+            "title": "Not Found",
+            "type": "array"
+          },
+          "took_ms": {
+            "description": "ES 耗时(毫秒)",
+            "title": "Took Ms",
+            "type": "integer"
+          },
+          "warnings": {
+            "description": "索引缺失等提示",
+            "items": {
+              "type": "string"
+            },
+            "title": "Warnings",
+            "type": "array"
+          },
+          "trace_id": {
+            "description": "查询审计标识",
+            "title": "Trace Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "platform",
+          "requested",
+          "found",
+          "not_found",
+          "took_ms",
+          "trace_id"
+        ],
+        "title": "GetUserOutput",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--query-summary",
+          "field": "query_summary",
+          "type": "string",
+          "required": true,
+          "desc": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。"
+        },
+        {
+          "flag": "--platform",
+          "field": "platform",
+          "type": "string",
+          "required": true,
+          "desc": "单个账号库 name_en(用 list-platforms 查)"
+        },
+        {
+          "flag": "--uids",
+          "field": "uids",
+          "type": "list[str](json)",
+          "required": true,
+          "desc": "账号 ID 列表(kw_uid 值);单个也写成数组;一次最多 get_user_max_uids(默认 10000),超了拒"
+        },
+        {
+          "flag": "--fields",
+          "field": "fields",
+          "type": "list[str](json)",
+          "required": false,
+          "desc": "出参投影;不传=画像常用字段(DEFAULT_FIELDS),传则只返回指定;要全量先 list-fields 拿字段名"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/get_user",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "list-fields",
+      "op": "list_fields",
+      "name": "user-query/list_fields",
+      "summary": "列出可用字段:中文名、类型、可用操作(不含具体值与样例)。建议按库或关键词收窄。",
+      "description": "列出可用字段:中文名、类型、可用操作(不含具体值与样例)。建议按库或关键词收窄。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "platforms": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "账号库 name_en 名单(list_platforms 的 name_en,如 [\"user_v3_douyin\"]);不传/传 [\"*\"]=全部库。建议按库收窄(字段逐库取、各库差异大、全量较慢)",
+            "title": "Platforms"
+          },
+          "keyword": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "按字段中文名/name_en 模糊过滤(如「粉丝」「认证」「地域」)",
+            "title": "Keyword"
+          }
+        },
+        "title": "ListFieldsInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "$defs": {
+          "Field_": {
+            "additionalProperties": false,
+            "description": "字段出参(不含样例值 example;样例较大,单独经 field-examples 按需取)。",
+            "properties": {
+              "name_en": {
+                "description": "字段标识(ES 字段名)",
+                "title": "Name En",
+                "type": "string"
+              },
+              "name": {
+                "description": "字段中文名",
+                "title": "Name",
+                "type": "string"
+              },
+              "data_type": {
+                "description": "语义类型:keyword/text/long/double/date/boolean/object/nested",
+                "title": "Data Type",
+                "type": "string"
+              },
+              "ops": {
+                "description": "可用操作(由 data_type 推导)",
+                "items": {
+                  "type": "string"
+                },
+                "title": "Ops",
+                "type": "array"
+              },
+              "aggregatable": {
+                "default": false,
+                "description": "是否可聚合",
+                "title": "Aggregatable",
+                "type": "boolean"
+              },
+              "sortable": {
+                "default": false,
+                "description": "是否可排序",
+                "title": "Sortable",
+                "type": "boolean"
+              },
+              "is_enum": {
+                "default": false,
+                "description": "值来自内置枚举(value_source=enum)",
+                "title": "Is Enum",
+                "type": "boolean"
+              },
+              "is_code": {
+                "default": false,
+                "description": "值为 code、需经知识中心解析(value_source=kb)",
+                "title": "Is Code",
+                "type": "boolean"
+              },
+              "value_source": {
+                "default": "none",
+                "description": "值来源:none/enum/kb",
+                "title": "Value Source",
+                "type": "string"
+              },
+              "platforms": {
+                "description": "出现该字段的平台 name_en 列表",
+                "items": {
+                  "type": "string"
+                },
+                "title": "Platforms",
+                "type": "array"
+              },
+              "description": {
+                "default": "",
+                "description": "字段描述",
+                "title": "Description",
+                "type": "string"
+              }
+            },
+            "required": [
+              "name_en",
+              "name",
+              "data_type"
+            ],
+            "title": "Field_",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "description": "字段列表(不含具体值与样例)",
+            "items": {
+              "$ref": "#/$defs/Field_"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "items",
+          "total"
+        ],
+        "title": "FieldList",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--platforms",
+          "field": "platforms",
+          "type": "list[str](json)",
+          "required": false,
+          "desc": "账号库 name_en 名单(list_platforms 的 name_en,如 [\"user_v3_douyin\"]);不传/传 [\"*\"]=全部库。建议按库收窄(字段逐库取、各库差异大、全量较慢)"
+        },
+        {
+          "flag": "--keyword",
+          "field": "keyword",
+          "type": "string",
+          "required": false,
+          "desc": "按字段中文名/name_en 模糊过滤(如「粉丝」「认证」「地域」)"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/list_fields",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "list-platforms",
+      "op": "list_platforms",
+      "name": "user-query/list_platforms",
+      "summary": "列出账号库(name_en 即 get_user/search 的 platform 入参)。",
+      "description": "列出账号库(name_en 即 get_user/search 的 platform 入参)。",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "$defs": {
+          "Platform": {
+            "additionalProperties": false,
+            "properties": {
+              "name_en": {
+                "description": "平台标识(= kw_platform 值)",
+                "title": "Name En",
+                "type": "string"
+              },
+              "name": {
+                "description": "平台中文名",
+                "title": "Name",
+                "type": "string"
+              },
+              "description": {
+                "default": "",
+                "description": "平台描述",
+                "title": "Description",
+                "type": "string"
+              },
+              "index_prefix": {
+                "default": "",
+                "description": "索引前缀(索引名解析用)",
+                "title": "Index Prefix",
+                "type": "string"
+              },
+              "time_pattern": {
+                "default": "",
+                "description": "索引时间分片模式(如 yyyyMM)",
+                "title": "Time Pattern",
+                "type": "string"
+              }
+            },
+            "required": [
+              "name_en",
+              "name"
+            ],
+            "title": "Platform",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "description": "账号库列表(name_en 即 get_user/search 的 platform 入参)",
+            "items": {
+              "$ref": "#/$defs/Platform"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "items",
+          "total"
+        ],
+        "title": "PlatformList",
+        "type": "object"
+      },
+      "flags": [],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/list_platforms",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "search",
+      "op": "search",
+      "name": "user-query/search",
+      "summary": "多条件搜账号:单库 + where(可选);缺省按 long_followerCount 降序、精简投影。",
+      "description": "多条件搜账号:单库 + where(可选);缺省按 long_followerCount 降序、精简投影。\n\n**不支持翻页**:单次最多 query_max_size 条;要更多请收窄 where,要统计用 aggregate。",
+      "input_schema": {
+        "$defs": {
+          "AndNode": {
+            "additionalProperties": false,
+            "properties": {
+              "and": {
+                "description": "全部满足(编译为 bool.filter);至少 1 个条件",
+                "items": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/$defs/AndNode"
+                    },
+                    {
+                      "$ref": "#/$defs/OrNode"
+                    },
+                    {
+                      "$ref": "#/$defs/NotNode"
+                    },
+                    {
+                      "$ref": "#/$defs/Leaf"
+                    }
+                  ]
+                },
+                "minItems": 1,
+                "title": "And",
+                "type": "array"
+              }
+            },
+            "required": [
+              "and"
+            ],
+            "title": "AndNode",
+            "type": "object"
+          },
+          "Leaf": {
+            "additionalProperties": false,
+            "description": "叶子条件 ``{field, op, value}``;value 传 ES 真实值(不翻译)。",
+            "properties": {
+              "field": {
+                "description": "字段 name_en",
+                "maxLength": 128,
+                "minLength": 1,
+                "title": "Field",
+                "type": "string"
+              },
+              "op": {
+                "description": "操作符;须在字段 data_type 允许集合内(§1.5)",
+                "enum": [
+                  "eq",
+                  "in",
+                  "match",
+                  "match_phrase",
+                  "gt",
+                  "gte",
+                  "lt",
+                  "lte",
+                  "exists"
+                ],
+                "title": "Op",
+                "type": "string"
+              },
+              "value": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "items": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "boolean"
+                        }
+                      ]
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "ES 真实值;in 传数组;exists 无需 value",
+                "title": "Value"
+              }
+            },
+            "required": [
+              "field",
+              "op"
+            ],
+            "title": "Leaf",
+            "type": "object"
+          },
+          "NotNode": {
+            "additionalProperties": false,
+            "properties": {
+              "not": {
+                "anyOf": [
+                  {
+                    "$ref": "#/$defs/AndNode"
+                  },
+                  {
+                    "$ref": "#/$defs/OrNode"
+                  },
+                  {
+                    "$ref": "#/$defs/NotNode"
+                  },
+                  {
+                    "$ref": "#/$defs/Leaf"
+                  }
+                ],
+                "description": "取反(编译为 bool.must_not)",
+                "title": "Not"
+              }
+            },
+            "required": [
+              "not"
+            ],
+            "title": "NotNode",
+            "type": "object"
+          },
+          "OrNode": {
+            "additionalProperties": false,
+            "properties": {
+              "or": {
+                "description": "任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件",
+                "items": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/$defs/AndNode"
+                    },
+                    {
+                      "$ref": "#/$defs/OrNode"
+                    },
+                    {
+                      "$ref": "#/$defs/NotNode"
+                    },
+                    {
+                      "$ref": "#/$defs/Leaf"
+                    }
+                  ]
+                },
+                "minItems": 1,
+                "title": "Or",
+                "type": "array"
+              }
+            },
+            "required": [
+              "or"
+            ],
+            "title": "OrNode",
+            "type": "object"
+          },
+          "SortSpec": {
+            "additionalProperties": false,
+            "properties": {
+              "field": {
+                "description": "排序字段;须为可排序类型(keyword/long/double/date/boolean)",
+                "title": "Field",
+                "type": "string"
+              },
+              "order": {
+                "default": "desc",
+                "description": "排序方向",
+                "enum": [
+                  "asc",
+                  "desc"
+                ],
+                "title": "Order",
+                "type": "string"
+              }
+            },
+            "required": [
+              "field"
+            ],
+            "title": "SortSpec",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "query_summary": {
+            "description": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。",
+            "maxLength": 200,
+            "minLength": 1,
+            "title": "Query Summary",
+            "type": "string"
+          },
+          "platform": {
+            "description": "单个账号库 name_en(用 list-platforms 查)",
+            "minLength": 1,
+            "title": "Platform",
+            "type": "string"
+          },
+          "where": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/AndNode"
+              },
+              {
+                "$ref": "#/$defs/OrNode"
+              },
+              {
+                "$ref": "#/$defs/NotNode"
+              },
+              {
+                "$ref": "#/$defs/Leaf"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "布尔条件树(可选);昵称/简介用 text_ match,地域/性别/认证用 kw_/bool_,粉丝数用 long_ range;时间过滤用 date_udate",
+            "title": "Where"
+          },
+          "sort": {
+            "anyOf": [
+              {
+                "items": {
+                  "$ref": "#/$defs/SortSpec"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "排序;缺省 long_followerCount desc;末位自动追加 _doc",
+            "title": "Sort"
+          },
+          "fields": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "返回字段投影;缺省精简白名单",
+            "title": "Fields"
+          },
+          "size": {
+            "anyOf": [
+              {
+                "minimum": 0,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "返回条数;0=只看 total;≤ query_max_size,缺省 query_default_size",
+            "title": "Size"
+          }
+        },
+        "required": [
+          "query_summary",
+          "platform"
+        ],
+        "title": "SearchInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "additionalProperties": true,
+        "properties": {
+          "total": {
+            "description": "命中总数(track_total_hits:true)",
+            "title": "Total",
+            "type": "integer"
+          },
+          "took_ms": {
+            "description": "ES 耗时(毫秒)",
+            "title": "Took Ms",
+            "type": "integer"
+          },
+          "truncated": {
+            "description": "total > size,还有更多命中",
+            "title": "Truncated",
+            "type": "boolean"
+          },
+          "hits": {
+            "description": "命中账号(投影字段)",
+            "items": {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            "title": "Hits",
+            "type": "array"
+          },
+          "warnings": {
+            "description": "索引缺失等提示",
+            "items": {
+              "type": "string"
+            },
+            "title": "Warnings",
+            "type": "array"
+          },
+          "trace_id": {
+            "description": "查询审计标识",
+            "title": "Trace Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "total",
+          "took_ms",
+          "truncated",
+          "hits",
+          "trace_id"
+        ],
+        "title": "SearchOutput",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--query-summary",
+          "field": "query_summary",
+          "type": "string",
+          "required": true,
+          "desc": "【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。"
+        },
+        {
+          "flag": "--platform",
+          "field": "platform",
+          "type": "string",
+          "required": true,
+          "desc": "单个账号库 name_en(用 list-platforms 查)"
+        },
+        {
+          "flag": "--where",
+          "field": "where",
+          "type": "object(json)",
+          "required": false,
+          "desc": "布尔条件树(可选);昵称/简介用 text_ match,地域/性别/认证用 kw_/bool_,粉丝数用 long_ range;时间过滤用 date_udate"
+        },
+        {
+          "flag": "--sort",
+          "field": "sort",
+          "type": "list[object](json)",
+          "required": false,
+          "desc": "排序;缺省 long_followerCount desc;末位自动追加 _doc"
+        },
+        {
+          "flag": "--fields",
+          "field": "fields",
+          "type": "list[str](json)",
+          "required": false,
+          "desc": "返回字段投影;缺省精简白名单"
+        },
+        {
+          "flag": "--size",
+          "field": "size",
+          "type": "integer",
+          "required": false,
+          "desc": "返回条数;0=只看 total;≤ query_max_size,缺省 query_default_size"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/user-query/search",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    }
+  ],
+  "skill": {
+    "slug": "social-neuron-user-query",
+    "description": "使用场景:社交账号画像即时查询 —— 查微博/抖音/小红书/快手/B站/知乎等平台的账号库。能力:get_user 按账号 ID 批量取完整画像、search 多条件搜账号(昵称/地域/粉丝量/认证/标签)、aggregate 做画像分布统计(粉丝量分档、地域/性别分布)、get_query 凭 trace_id 回看历史查询。查询模型:platform(必填,单个账号库 name_en)+ get_user 的 uids(批量主键,一次≤10000)或 search/aggregate 的 where 布尔树;**无必填时间**(画像快照,时间过滤用 date_udate)。取值:一律传 ES 真实值(性别/地域是中文明文),系统不翻译;聚合/排序须用 kw_ 字段(text_ 不可聚合)。边界:①只读;②不支持翻页(单次≤1000);③部分库 helix name_en 可能有版本错位,查不到时核对。",
+    "actions": [
+      "aggregate",
+      "describe-capability",
+      "get-field-examples",
+      "get-field-values",
+      "get-query",
+      "get-user",
+      "list-fields",
+      "list-platforms",
+      "search"
+    ]
+  }
+}