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

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@social-data/social-neuron-user-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.0",
+  "description": "Social Neuron user-query 能力 CLI —— 一能力一命令(social-neuron-user-query),薄客户端直达 /user-query/{op}。",
+  "bin": {
+    "social-neuron-user-query": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "manifest.json",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node bin/install-skills.js"
+  },
+  "keywords": [
+    "social-neuron",
+    "user-query",
+    "cli",
+    "ai-agent",
+    "openclaw"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/social-neuron-user-query/SKILL.md

@@ -0,0 +1,501 @@
+---
+name: 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 可能有版本错位,查不到时核对。"
+metadata:
+  openclaw:
+    requires: { bins: ['social-neuron-user-query'], skills: [] }
+---
+# social-neuron-user-query
+
+
+> ⚠️ 本技能随该能力 CLI 版本更新。若刚升级过 CLI、重装过 skill,或调用返回 426(版本过旧需升级),请**重新加载本 SKILL.md 与 manifest** 再用——以最新文件为准。
+
+> 命令为一能力一命令:`social-neuron-user-query <action> --flags`(无子命令层)。
+> **取值写法**:标量直接写(`--size 20`);**数组和对象一律写成一个 JSON 串**,与 MCP/HTTP 入参完全同形:`--platforms '["video"]'`、`--where '{...}'`。数组**不能**用逗号分隔,单个取值也要写成数组(`'["video"]'` 而不是 `video`)。
+
+## 怎么查(操作手册)
+
+用户库是"社媒账号的画像快照"——每个账号一条最新画像(昵称/地域/粉丝量/认证/标签…)。按这个顺序走:
+
+1. **定位库** —— 用户说的「抖音」「微博」是哪个 `platform`?不确定就 `list-platforms`。
+2. **查字段** —— 该库有哪些字段?`list-fields --platforms '["<库>"]'`(各库字段差异大,抖音 234、公众号 35)。
+3. **查** —— 选工具:`get-user` 按 uid 批量取画像;`search` 多条件搜账号;`aggregate` 做画像分布统计。
+
+### 一、必填参数
+
+> **写法**:数组和对象一律写成 JSON 串;数组单个取值也要写成数组。
+
+- `get-user`:`--platform`(单库)+ `--uids`(JSON 数组,一次≤10000)+ `--query-summary`
+- `search` / `aggregate`:`--platform`(单库)+ `--query-summary`;**无必填时间**(画像快照)
+
+### 二、字段命名规则:前缀即类型
+
+| 前缀 | 类型 | 可用 op | 常见字段 |
+|---|---|---|---|
+| `kw_` | keyword | `eq` `in` `exists` | `kw_uid` `kw_nickName` `kw_gender` `kw_province` `kw_tag` |
+| `text_` | text | `match` `match_phrase` | `text_description`(简介) |
+| `long_` `double_` | 数值 | `eq` `in` `gt` `gte` `lt` `lte` | `long_followerCount`(粉丝数) |
+| `date_` | date | `gt` `gte` `lt` `lte` `exists` | `date_udate`(更新) `date_idate`(入库) |
+| `bool_` | boolean | `eq` | `bool_verified`(认证) |
+
+⚠ **聚合/排序必须用 `kw_` 字段,`text_` 不可聚合/排序**:昵称聚合用 `kw_nickName`,检索用 `text_description` 配 match。
+
+### 三、选哪个工具
+
+| 用户想要 | 用 | 关键点 |
+|---|---|---|
+| "查这几个 uid 的账号情况" | `get-user` | 按主键批量取**完整画像**;uids 一次≤10000 |
+| "找粉丝百万的广东女性博主" | `search` | 多条件筛选;缺省按粉丝数降序;**不支持翻页** |
+| "各省账号数""粉丝量分档" | `aggregate` | 按 kw_ 字段 terms,粉丝量用 range 分档 |
+
+### 四、get-user:按 uid 批量取画像
+
+```bash
+social-neuron-user-query get-user --platform user_v4_douyin \
+  --query-summary '查抖音这几个账号画像' --uids '["3149452613521724","6887154593"]'
+```
+- 返回**完整画像**(不设 fields);命中与否按入参 uid 对账,出参给 `found` / `not_found` 两组。
+- uids 一次最多 10000(对齐 ES size 上限),更多分多次。
+
+### 五、search:多条件搜账号
+
+```bash
+social-neuron-user-query search --platform user_v4_douyin \
+  --query-summary '抖音广东女性粉丝过百万账号' \
+  --where '{"and":[{"field":"kw_province","op":"eq","value":"广东省"},
+                   {"field":"kw_gender","op":"eq","value":"女"},
+                   {"field":"long_followerCount","op":"gte","value":1000000}]}' \
+  --size 10
+```
+- 缺省按 `long_followerCount` 降序、精简投影(8 字段);想要别的字段/全量用 `--fields` 显式列。
+- 昵称/简介关键词搜用 `text_description` 配 `match`。
+- 按更新时间过滤:where 加 `date_udate` 的 range(无必填时间)。
+
+### 六、aggregate:画像分布
+
+```bash
+# 粉丝量分档
+social-neuron-user-query aggregate --platform user_v4_douyin \
+  --query-summary '抖音账号粉丝量分档' \
+  --group-by '[{"name":"by_fans","type":"range","field":"long_followerCount",
+                "ranges":[{"to":10000},{"from":10000,"to":100000},{"from":100000,"to":1000000},{"from":1000000}]}]' \
+  --metrics '[{"op":"count"}]'
+
+# 各省分布
+social-neuron-user-query aggregate --platform user_v4_douyin \
+  --query-summary '抖音账号地域分布' \
+  --group-by '[{"name":"by_prov","type":"terms","field":"kw_province","size":20}]' \
+  --metrics '[{"op":"count"},{"op":"avg","field":"long_followerCount"}]'
+```
+`count` 不用 field;`sum`/`avg`/`min`/`max` 须给 `long_`/`double_` 字段。⚠ group_by 的 field 必须用 kw_(text_ 不可聚合)。
+
+### 七、结果可信吗
+
+| 信号 | 含义 | 怎么办 |
+|---|---|---|
+| `truncated: true` | 还有更多命中未返回 | 加大 size 或收窄 where |
+| `sum_other_doc_count` 大 | "TOP N 占比"失真 | 先 where 收窄 |
+| `warnings` 非空 | 部分库索引缺失等 | **必须转述给用户** |
+
+`trace_id` 每次都返回;用户追问"这数怎么来的"用 get-query 回看(需等审计落库≥30 秒)。
+
+### 八、取值与边界
+
+- 系统**不翻译值**:性别/地域本就是中文明文直接传;传错值不报错、命中 0 条。
+- `search`/`get-user` 一次最多 query_max_size(1000) 条,**不支持翻页**。
+- 只读;部分账号库 helix name_en 可能与真实索引有版本错位,查不到时报索引不存在,联系管理员核对。
+
+## 示例
+
+### 先看有哪些账号库、各库规模
+
+```bash
+social-neuron-user-query describe-capability
+```
+
+> coverage.libraries 给出每个库的字段数、是否可按粉丝量排序。
+
+### 按 uid 批量取抖音账号画像
+
+```bash
+social-neuron-user-query get-user --platform user_v4_douyin \
+  --query-summary '查抖音账号画像' --uids '["3149452613521724","6887154593"]'
+```
+
+> 返回完整画像;查无的 uid 归入 not_found。
+
+### 搜粉丝过百万的广东女性博主
+
+```bash
+social-neuron-user-query search --platform user_v4_douyin \
+  --query-summary '抖音广东女性百万粉账号' \
+  --where '{"and":[{"field":"kw_province","op":"eq","value":"广东省"},
+                   {"field":"kw_gender","op":"eq","value":"女"},
+                   {"field":"long_followerCount","op":"gte","value":1000000}]}' --size 10
+```
+
+> 缺省按粉丝数降序;要别的字段用 --fields。
+
+### 账号粉丝量分档统计
+
+```bash
+social-neuron-user-query aggregate --platform user_v4_douyin \
+  --query-summary '抖音账号粉丝量分档' \
+  --group-by '[{"name":"by_fans","type":"range","field":"long_followerCount",
+                "ranges":[{"to":10000},{"from":10000,"to":100000},{"from":100000}]}]' \
+  --metrics '[{"op":"count"}]'
+```
+
+> 粉丝量用 range 分档;count 不用 field。
+
+## 命令
+
+### social-neuron-user-query aggregate
+画像分布统计:group_by 声明树 + metrics(含 min/max)。
+
+粉丝量分档 range(long_followerCount)、地域/性别 terms(kw_province/kw_gender)、认证 terms(bool_verified)。
+⚠ 聚合须用 kw_ 字段(text_ 不可聚合)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --query-summary | query_summary | string | 是 | minLen=1, maxLen=200 | 【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。 |
+| --platform | platform | string | 是 | minLen=1 | 单个账号库 name_en(用 list-platforms 查) |
+| --where | where | AndNode、OrNode、NotNode、Leaf | 否 | - | 布尔条件树(可选);时间过滤用 date_udate/date_idate |
+| --group-by | group_by | list[GroupLevel] | 是 | - | 分组声明树;顶层数组=并列聚合 |
+| --metrics | metrics | list[Metric] | 是 | - | 指标;挂在每一层 |
+
+**对象 `AndNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | - | 全部满足(编译为 bool.filter) |
+
+**对象 `GroupLevel`** —— 一层分组声明。``group_by`` 递归 = 嵌套子层;缺省 = 本层为叶子(设计 §3.1)。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| name | string | 是 | - | 本层聚合名(出参 key) |
+| type | enum(terms、range、histogram、date_histogram) | 是 | - | 聚合类型;须与字段 data_type 匹配(§3.1.1) |
+| field | string | 是 | minLen=1, maxLen=128 | 被分组字段 name_en |
+| size | integer | 否 | - | terms 桶数上限;缺省 10,≤ agg_max_size |
+| order | Order | 否 | - | terms 桶排序;缺省 count desc |
+| ranges | list[RangeBucket] | 否 | - | range 档位,左闭右开 |
+| interval | integer、number、string | 否 | - | histogram 数值间隔;date_histogram 粒度 hour\|day\|week\|month |
+| group_by | list[GroupLevel] | 否 | - | 嵌套子层(递归);缺省=本层为叶子 |
+
+**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;value 传 ES 真实值(不翻译)。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
+| op | enum(eq、in、match、match_phrase、gt、gte、lt、lte、exists) | 是 | - | 操作符;须在字段 data_type 允许集合内(§1.5) |
+| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | ES 真实值;in 传数组;exists 无需 value |
+
+**对象 `Metric`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| op | enum(count、sum、avg、min、max) | 是 | - | 聚合算子;sum/avg/min/max 需 long/double 字段(min=最小值,如最少粉丝数) |
+| field | string | 否 | - | 被聚合字段;count 无需 |
+
+**对象 `NotNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |
+
+**对象 `OrNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | - | 任一满足(编译为 bool.should + minimum_should_match:1) |
+
+**出参 `AggregateOutput`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| took_ms | integer | 是 | - | ES 耗时(毫秒) |
+| truncated | boolean | 是 | - | 任一 terms 层 sum_other_doc_count>0 |
+| warnings | list[string] | 否 | - | 部分索引不存在等提示;空=结果完整 |
+| trace_id | string | 是 | - | 查询审计标识 |
+
+示例:social-neuron-user-query aggregate --query-summary <v> --platform <v> --group-by '["a","b"]' --metrics '["a","b"]'
+
+### social-neuron-user-query describe-capability
+能力总览(agent 起点):查什么数据、有哪些账号库及各自画像、查询模型、取值约定、规模闸。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+
+**出参 `CapabilityOverview`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| data | string | 是 | - | 数据类型(用户) |
+| description | string | 是 | - | 能力一句话说明 |
+| coverage | UserCoverage | 是 | - | 覆盖范围 + 逐库画像 |
+| query_model | string | 是 | - | 查询模型说明(必填入参与 where 的关系) |
+| value_convention | string | 是 | - | 取值约定:一律传 ES 真实值,系统不翻译 |
+| limits | Limits | 是 | - | 规模闸 |
+| discovery | list[string] | 是 | - | 其余发现接口名(下钻指引) |
+| query_tools | list[string] | 是 | - | 查询工具名 |
+
+**对象 `Limits`** —— 规模闸(配置化)—— agent 据此预判边界,避免被拒后盲试。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| query_default_size | integer | 是 | - | get_user/search 默认返回条数 |
+| query_max_size | integer | 是 | - | 单次上限 |
+| where_max_depth | integer | 是 | - | where 规范化后允许的最大嵌套深度 |
+| agg_max_depth | integer | 是 | - | 聚合最大嵌套层数 |
+| agg_max_width | integer | 是 | - | 每层并列分支上限 |
+| agg_max_size | integer | 是 | - | 单层 terms.size 上限 |
+| agg_bucket_budget | integer | 是 | - | 聚合总桶数预算 |
+
+**对象 `UserCoverage`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| platforms | integer | 是 | - | 账号库数量 |
+| libraries | list[LibrarySummary] | 是 | - | 逐库画像(下钻指引) |
+
+示例:social-neuron-user-query describe-capability
+
+### social-neuron-user-query get-field-examples
+批量取字段样例值,看数据长相(如 kw_nickName / long_followerCount)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --fields | fields | list[string] | 是 | minItems=1 | 想看样例值的字段 name_en 名单(如 kw_nickName / long_followerCount) |
+
+**出参 `FieldExamples`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| items | object | 是 | - | {字段 name_en: 样例值};**只含有样例的字段**,其余见 warnings |
+| warnings | list[string] | 否 | - | 未返回样例的字段说明(字段无 example_value,或名字拼错);空=要的都给了 |
+
+示例:social-neuron-user-query get-field-examples --fields '["a","b"]'
+
+### social-neuron-user-query get-field-values
+取字段值字典 [{code, value}] —— 枚举/code 字段的全部合法取值。
+
+账号库字段多为明文;**空列表原样返回**(明文字段无字典,或该字段未配值来源)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --field | field | string | 是 | - | 字段 name_en;仅 is_enum/is_code 的字段有值字典(账号库多为明文,少数标签/类型字段有字典) |
+| --keyword | keyword | string | 否 | - | 按值/code 模糊过滤;不传=全量 |
+
+**出参 `FieldValueList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | - | 字段 name_en |
+| items | list[FieldValue] | 是 | - | 值字典 [{code, value}] |
+| total | integer | 是 | - | 总数 |
+
+**对象 `FieldValue`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| code | string | 是 | - | 值 code(enum 的 code / 知识中心的 tagCode) |
+| value | string | 是 | - | 人话(enum 的 value / 知识中心的 tagName) |
+
+示例:social-neuron-user-query get-field-values --field <v>
+
+### social-neuron-user-query get-query
+凭 trace_id 回看历史查询:原始入参、实际 DSL、命中索引与结果摘要。
+只能回看**本人**发起的查询。
+⚠ 审计异步落库,查询刚返回时通常还没写入,请至少等 30 秒再回看(否则同样返回 40426)。
+审计只保留近 3 个月(ILM),更早的 trace_id 查不到。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --trace-id | trace_id | string | 是 | - | 查询响应里返回的审计标识 trace_id(如 tr_703781746697984) |
+
+**出参 `GetQueryOutput`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| trace_id | string | 是 | - | 审计标识,与入参一致 |
+| queried_at | string | 是 | - | 查询发起时间(东八区,无偏移) |
+| capability | string | 是 | - | 能力 key |
+| tool | string | 是 | - | 查询工具:get_user / search / aggregate |
+| env | string | 是 | - | 写入环境后缀:test / prod |
+| schema_version | string | 是 | - | 审计文档结构版本 |
+| status | string | 是 | - | 当次查询结果:ok / error |
+| query_summary | string | 是 | - | 当次的中文意图概括 |
+| structured_params | object | 是 | - | 当次**原始入参**(对象)—— 回放:原样作为 get_user/search/aggregate 的入参再跑即可;历史截断文档给原始字符串 |
+| compiled_dsl | object | 是 | - | 当次实际执行的 ES DSL(对象,原文全量);历史截断文档给原始字符串 |
+| resolved_indices | list[string] | 是 | - | 实际命中的索引 |
+| missing_indices | list[string] | 是 | - | 探活缺失的模式;空 = 全覆盖 |
+| result | object | 是 | - | {total, tookMs, elapsedMs, returned, truncated};status=error 时为 null |
+| warnings | list[string] | 是 | - | 当次的告警原文 |
+| warning_kinds | list[string] | 是 | - | 告警枚举:partial_index_missing / shard_failure / timeout |
+| error | object | 是 | - | {code, msg};status=ok 时为 null |
+| result_sample | object | 是 | - | 结果头部切片(对象,结构感知截断,内置 _truncated 标记);空结果/失败为 null |
+
+示例:social-neuron-user-query get-query --trace-id <v>
+
+### social-neuron-user-query get-user
+按账号 ID 批量精确取画像:单库 + uids(一次≤10000)。
+
+不传 fields 返回画像常用字段;传 fields 只返回指定。命中与否按入参 uids 对账,给 found/not_found。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --query-summary | query_summary | string | 是 | minLen=1, maxLen=200 | 【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。 |
+| --platform | platform | string | 是 | minLen=1 | 单个账号库 name_en(用 list-platforms 查) |
+| --uids | uids | list[string] | 是 | minItems=1 | 账号 ID 列表(kw_uid 值);单个也写成数组;一次最多 get_user_max_uids(默认 10000),超了拒 |
+| --fields | fields | list[string] | 否 | - | 出参投影;不传=画像常用字段(DEFAULT_FIELDS),传则只返回指定;要全量先 list-fields 拿字段名 |
+
+**出参 `GetUserOutput`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| platform | string | 是 | - | 账号库 name_en |
+| requested | integer | 是 | - | 入参 uids 个数 |
+| found | list[object] | 是 | - | 命中账号(每条含投影字段,含 kw_uid) |
+| not_found | list[string] | 是 | - | 查无的 uid(按入参对账) |
+| took_ms | integer | 是 | - | ES 耗时(毫秒) |
+| warnings | list[string] | 否 | - | 索引缺失等提示 |
+| trace_id | string | 是 | - | 查询审计标识 |
+
+示例:social-neuron-user-query get-user --query-summary <v> --platform <v> --uids '["a","b"]'
+
+### social-neuron-user-query list-fields
+列出可用字段:中文名、类型、可用操作(不含具体值与样例)。建议按库或关键词收窄。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --platforms | platforms | list[string] | 否 | - | 账号库 name_en 名单(list_platforms 的 name_en,如 ["user_v3_douyin"]);不传/传 ["*"]=全部库。建议按库收窄(字段逐库取、各库差异大、全量较慢) |
+| --keyword | keyword | string | 否 | - | 按字段中文名/name_en 模糊过滤(如「粉丝」「认证」「地域」) |
+
+**出参 `FieldList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| items | list[Field_] | 是 | - | 字段列表(不含具体值与样例) |
+| total | integer | 是 | - | 总数 |
+
+**对象 `Field_`** —— 字段出参(不含样例值 example;样例较大,单独经 field-examples 按需取)。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| name_en | string | 是 | - | 字段标识(ES 字段名) |
+| name | string | 是 | - | 字段中文名 |
+| data_type | string | 是 | - | 语义类型:keyword/text/long/double/date/boolean/object/nested |
+| ops | list[string] | 否 | - | 可用操作(由 data_type 推导) |
+| aggregatable | boolean | 否 | - | 是否可聚合 |
+| sortable | boolean | 否 | - | 是否可排序 |
+| is_enum | boolean | 否 | - | 值来自内置枚举(value_source=enum) |
+| is_code | boolean | 否 | - | 值为 code、需经知识中心解析(value_source=kb) |
+| value_source | string | 否 | - | 值来源:none/enum/kb |
+| platforms | list[string] | 否 | - | 出现该字段的平台 name_en 列表 |
+| description | string | 否 | - | 字段描述 |
+
+示例:social-neuron-user-query list-fields
+
+### social-neuron-user-query list-platforms
+列出账号库(name_en 即 get_user/search 的 platform 入参)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+
+**出参 `PlatformList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| items | list[Platform] | 是 | - | 账号库列表(name_en 即 get_user/search 的 platform 入参) |
+| total | integer | 是 | - | 总数 |
+
+**对象 `Platform`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| name_en | string | 是 | - | 平台标识(= kw_platform 值) |
+| name | string | 是 | - | 平台中文名 |
+| description | string | 否 | - | 平台描述 |
+| index_prefix | string | 否 | - | 索引前缀(索引名解析用) |
+| time_pattern | string | 否 | - | 索引时间分片模式(如 yyyyMM) |
+
+示例:social-neuron-user-query list-platforms
+
+### social-neuron-user-query search
+多条件搜账号:单库 + where(可选);缺省按 long_followerCount 降序、精简投影。
+
+**不支持翻页**:单次最多 query_max_size 条;要更多请收窄 where,要统计用 aggregate。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --query-summary | query_summary | string | 是 | minLen=1, maxLen=200 | 【必填】用一句简短中文概括**本次查询的意图** —— 基于用户的原始诉求来总结,不是复述参数。应能让人不看 DSL 就知道在查什么:覆盖账号库、主要筛选条件、以及排序/取数口径(若有)。例:「抖音广东百万粉女性账号」「按 uid 批量查账号画像」「微博账号各省粉丝量分布」。该概况会和 trace_id 一起写入查询日志,供审计回溯,请每次如实填写。 |
+| --platform | platform | string | 是 | minLen=1 | 单个账号库 name_en(用 list-platforms 查) |
+| --where | where | AndNode、OrNode、NotNode、Leaf | 否 | - | 布尔条件树(可选);昵称/简介用 text_ match,地域/性别/认证用 kw_/bool_,粉丝数用 long_ range;时间过滤用 date_udate |
+| --sort | sort | list[SortSpec] | 否 | - | 排序;缺省 long_followerCount desc;末位自动追加 _doc |
+| --fields | fields | list[string] | 否 | - | 返回字段投影;缺省精简白名单 |
+| --size | size | integer | 否 | min=0 | 返回条数;0=只看 total;≤ query_max_size,缺省 query_default_size |
+
+**对象 `AndNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | - | 全部满足(编译为 bool.filter) |
+
+**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;value 传 ES 真实值(不翻译)。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
+| op | enum(eq、in、match、match_phrase、gt、gte、lt、lte、exists) | 是 | - | 操作符;须在字段 data_type 允许集合内(§1.5) |
+| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | ES 真实值;in 传数组;exists 无需 value |
+
+**对象 `NotNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |
+
+**对象 `OrNode`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | - | 任一满足(编译为 bool.should + minimum_should_match:1) |
+
+**对象 `SortSpec`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | - | 排序字段;须为可排序类型(keyword/long/double/date/boolean) |
+| order | enum(asc、desc) | 否 | - | 排序方向 |
+
+**出参 `SearchOutput`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| total | integer | 是 | - | 命中总数(track_total_hits:true) |
+| took_ms | integer | 是 | - | ES 耗时(毫秒) |
+| truncated | boolean | 是 | - | total > size,还有更多命中 |
+| hits | list[object] | 是 | - | 命中账号(投影字段) |
+| warnings | list[string] | 否 | - | 索引缺失等提示 |
+| trace_id | string | 是 | - | 查询审计标识 |
+
+示例:social-neuron-user-query search --query-summary <v> --platform <v>

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.