Unify skills under repository root

skills/elk-fetch/business/intent-arbitrator.md

@@ -0,0 +1,60 @@
+# 中控仲裁日志
+
+> "中控"= central intent arbitrator，决定一条 query 路由到哪个 domain/agent（`controlCopilot` / `iotCopilot` / `productAgent` / 闲聊 / ...）。
+
+## 在哪查
+
+主 NLP 表 `arch-flat-nlp-log-f-*` 里的 **`intention.intent_arbitrator_info`** 嵌套对象。`main` preset 直接能读，**不需要新 preset**。
+
+⚠️ **坑**：顶层 `intent_arbitrator_info`（不带 `intention.`）通常是 `null`——同名但不同位置，别取错。
+
+> Kibana URL 形如 `akelk.pt.ai.srv/app/discover#/?...index:b0bd62cb-...&query:(...request_id:...)`，这个 Kibana 前端虽然走 akelk 域名，底层 ES 就是 akaiservice 主表。
+
+## 关键字段
+
+路径前缀 `intention.intent_arbitrator_info`：
+
+**仲裁结果**
+- `predict_result_domain` / `l2_domain` / `l2_func` / `before_final_rule_domain` — 各阶段判出的 domain
+- `single_result_domain` / `multi_result_domain` — 单轮 / 多轮结果
+- `dialog_status` — 对话状态（`FINISH` / ...）
+
+**仲裁打分**
+- `score_domains` (dict) — 各候选 domain 的 `score` + `func`，仲裁打分原始数据
+  - 例：`controlCopilot:1.0`, `soundboxControl:0.97`, `default:0.05`
+
+**仲裁等级**
+- `arbitrator_level` — 仲裁等级（如 `Agent_LLM` 表示走 LLM agent 路径）
+- `is_llm_allowed` / `is_new_agent_logic`
+
+**LLM agent 命中**
+- `llm_agent_info`：
+  - `isEffective` — 是否生效
+  - `agentType` — 类型（如 `车载控制`）
+  - `agentName` — 名称（如 `controlCopilot|iotCopilot|productAgent`）
+  - `agentSubType`
+- `hit_rules` — 命中的召回规则（如 `[agent_llm_recall_controlCopilot]`）
+
+**LLM 仲裁子流程**
+- `llm_strategy_info`：`llm_domain` / `llm_intent` / `llm_strategy_stage` / `before_llm_*`
+
+**confidence**
+- `intent_confidence_information`
+
+## 命令模板
+
+```bash
+# 整个仲裁对象
+python elk_query.py <rid> --json-path intention.intent_arbitrator_info
+
+# 命中的 agent + 召回规则 + 仲裁等级（速览）
+python elk_query.py <rid> \
+  --fields request_id,query,domain,intention.intent_arbitrator_info.llm_agent_info,intention.intent_arbitrator_info.hit_rules,intention.intent_arbitrator_info.arbitrator_level
+
+# 各候选 domain 的仲裁打分
+python elk_query.py <rid> --json-path intention.intent_arbitrator_info.score_domains
+```
+
+## 字段 schema
+
+完整 schema 见 [`../INDEX_CATALOG.md`](../INDEX_CATALOG.md) 中 `arch-flat-nlp-log-f-*` 一节。

skills/elk-fetch/business/keyword-free.md

@@ -0,0 +1,61 @@
+# 免唤醒判决日志
+
+> "免唤醒"指车机上不需要每次说"小爱同学"的免唤醒指令模式（如开/关空调、调温度）。每次请求都会经过免唤醒判决——是否让这条 query 直接执行而不是走闲聊/拒识。
+
+## 三个视角，两张表
+
+| # | 业务视角 | 日志位置 | 命令 |
+| - | ------- | ------- | ---- |
+| 1 | **拒识模块视角**：每次请求拒识模块整体输出（含所有子策略，含调用免唤醒的结果） | `aiservice_duplex_rejection_lcs_log*` 整条 `rejectInfo` | `--preset reject` |
+| 2 | **拒识里的免唤醒子字段**：拒识调免唤醒那一次的入参出参 | 同表，`rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC` | `--preset reject --json-path rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC` |
+| 3 | **免唤醒模块视角**：免唤醒模块**被后处理调到时**自己写的日志（独立的另一张表） | `nlp_post_processing_lcs-*` 中 `moduleName=keyword-free-log` | `--preset kwfree` |
+
+1 和 2 同表同条记录，2 只是取子字段；3 是完全独立的另一张表。
+
+## 关键字段
+
+### 视角 2：拒识里的免唤醒子字段
+
+路径前缀 `rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC`：
+- `process` — 是否走到免唤醒判决（true / false）
+- `skipped_reason` — 被跳过原因（如 `post_processing_takeover` 表示让后处理接管，进入视角 3）
+- `keywordFreeType`
+- `isCodeMatch`
+- `getProcessedQuery`
+- `Function List`
+
+### 视角 3：后处理免唤醒模块自身
+
+JSON 字段 `message` 顶层：
+- `process` — 是否实际走到处理
+- `skipReason` — 未处理原因（如 `rejectedByOtherStrategy` 已被其他策略先拒）
+- `route.flow` / `route.enableFullMigration` / `route.clawEnabled`
+- `request.query`
+- `request.keywordFreeType`（如 `INSTRUCTION_KEY_WORD_FREE`）
+- `request.zone`（如 `DRIVER`）
+- `request.appId` / `maskUid` / `maskDeviceId`
+- `fallback.oldRejectType` / `fallback.oldDomain`
+
+## 排查 Playbook
+
+**问题：免唤醒为什么没生效？**
+
+1. 先查视角 2，看拒识有没有调到免唤醒：
+   ```bash
+   python elk_query.py <rid> --preset reject \
+     --json-path rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC
+   ```
+   - `process=true` → 走到免唤醒判决了，看 `keywordFreeType` 等子字段
+   - `process=false` → 没走到，看 `skipped_reason`：
+     - `post_processing_takeover` → 进视角 3 看后处理免唤醒
+     - 其他原因 → 拒识自己挡了
+
+2. 视角 3——后处理免唤醒模块自身：
+   ```bash
+   python elk_query.py <rid> --preset kwfree --json-path message
+   ```
+   - `process=false` 时看 `skipReason`（`rejectedByOtherStrategy` 表示已被先拒）
+
+## 字段 schema
+
+完整 schema 见 [`../INDEX_CATALOG.md`](../INDEX_CATALOG.md) 中 `aiservice_duplex_rejection_lcs_log*` 和 `nlp_post_processing_lcs-*` 两节。

skills/elk-fetch/business/micar-onetrack.md

@@ -0,0 +1,127 @@
+# 小米汽车 OneTrack 端侧埋点
+
+> 小米汽车小爱端侧上报的全量埋点（端到端可用性、ASR 状态、全离线日志、性能指标等）。与 NLP 服务端日志正交：从车端上报的客户端事件流。
+>
+> 索引 `onetrack_xiaoai_micar*`（**c3log 独立集群**），单日 ~300GB——**必须传 `--date YYYYMMDD`**。
+
+## tip 体系
+
+一个 request_id 对应多条记录，每条对应一个 `tip` 埋点点位。先 `--fields tip,tip_name` 看一眼有哪些 tip：
+
+```bash
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --fields request_id,tip,tip_name,tip_module_name,event_name
+```
+
+主要点位：
+
+| tip | tip_name | tip_module_name | event_name | 含义 |
+| --- | -------- | --------------- | ---------- | ---- |
+| `1024.1.1.1.23177` | 小爱端到端可用性 | 性能类 | execute | 全链路时序埋点（wakeup → asr → nlp → exec） |
+| `1024.1.2.1.23176` | 小爱全离线日志 | 日志类 | execute | **离线模型相关日志** |
+| `1024.1.2.1.34496` | 离线NLP结果 | — | state | 离线 NLP 出参 |
+| `1024.4.1.1.25631` | ASR识别状态 | ASR识别 | state | ASR 中间状态 |
+| `1024.1.1.1.33610` | 第三方接口调用 | — | execute | — |
+| `1024.1.3.1.23520` / `23521` | 小爱指令开始 / 结束 | — | start / — | — |
+
+⚠️ **不同 tip 的负载 schema 不统一**：
+- 23177 → 负载在顶层 `key_value`
+- 23176 → 负载在顶层 `request_infos[]` / `response_infos[]` / `other_infos`（**不在 `key_value`**）
+- 34496 → 负载在 `key_value.instructions`
+- 25631 → `key_value` 为 null，看 `event_name` / `other_infos`
+
+---
+
+## 23177 — 端到端可用性
+
+负载在顶层 `key_value`（脚本自动解析）。常用字段：
+
+**唤醒**：`wakeup_received_event` / `wakeup_ball_appear`
+
+**ASR 时序**：`asr_first_partial` / `asr_first_text` / `asr_first_same_final` / `asr_final` / `asr_first_pack_sent`
+
+**NLP 时序**：`nlp_start_answer` / `nlp_finish_answer`
+
+**结果**：`state_result_type`（`success` / ...）/ `state_exec_result` / `state_cancel_msg`
+
+**指令统计**：`state_exec_ins_total` / `state_exec_ins_success` / `state_exec_ins_failed` / `state_exec_ins_filtered`
+
+**异常**：`state_nlp_unknown_instructions` (list) / `state_nlp_exceptions` / `state_vad_end_type`
+
+**链路**：`state_duplex` / `state_request_id` / `state_asr_final_size`
+
+```bash
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --fields request_id,tip,key_value.state_result_type,key_value.state_exec_result,key_value.wakeup_received_event,key_value.asr_final,key_value.nlp_finish_answer
+```
+
+---
+
+## 23176 — 全离线日志 ⭐ 离线模型核心
+
+⚠️ schema 与其他 tip 不同：负载在顶层 `request_infos[]` / `response_infos[]` / `other_infos`（list，长度通常为 1，但每个 list 都有大量信息），**不在 `key_value`**。
+
+### `request_infos[0]` — 送给离线引擎的入参
+
+- 引擎/模型版本：`engine_id` / `engine_model`（如 `3.2.30-claw`）/ `offline_model_ver`（如 `2026012201`）/ `miai_ver` / `app_version`
+- 请求形态：`request_type` / `request_state_type` / `is_wakeup_req` / `is_llm` / `duplex` / `origin`
+- 链路环境：`srv_env` / `network` / `network_nlp` / `network_type` / `off_asr_avail`
+- 设备：`device_id` / `car_type` / `car_config` / `is_driving` / `zone_info` / `is_login` / `has_token` / `isInternal`
+- **`context_offline`** (list) — 离线引擎拿到的全部 context payload（含 `Nlp.OfflineSession` / `Map.MapState` / `UIController.InteractionInfoList` 等 namespace）。**研究模型行为时务必看这一段**
+- 其他：`ua` / `transaction_id` / `request_id` / `timeout_reason`
+
+### `response_infos[0]` — 引擎返回的产物
+
+⚠️ 不止 `nlp_debug_info`，三块都要看：
+
+**`instructions[]`** — 引擎下发的全部指令序列。每条 `header.namespace.name` + `header.is_offline`（true/false 标识离/在线判决）+ `header.dialog_id` / `id` / `transaction_id` + `payload`。常见 namespace.name：
+- `System.Heartbeat` / `System.Abort`
+- `Offline.CloudStop`（`current_round_used_audio_duration` / `next_round_rid` / `stop_audio_duration`）
+- `SpeechRecognizer.RecognizeResult`（`is_final` / `results[].text` / `confidence` / `is_nlp_request` / `is_key_word_free_request`）
+- `Nlp.StartAnswer` / `Nlp.FinishAnswer` / `Nlp.IntentsWithRelation`（`payload.intent`）
+- `Template.Query`（`text`）
+- `Dialog.Reject`（`query` / `reject_type` 如 `NON_HUMAN`） / `Dialog.Finish`
+
+**`nlp_debug_info`** ⭐ 离线 NLP 模型自身的调试输出（模型日志打点）。研究模型决策为什么这样做的核心：
+- **`Arbitrate`** — 仲裁器决策：`query` / **`logits`** (list[float], 各类目原始打分) / `label_id` / `category`（如 `Info`）/ `predict` / `label`（如 `baike#person`）/ `domains`（候选 domain）/ `time`
+- 各阶段耗时：`Rewrite.time` / `PreTrain.time`（`bertAvailable`）/ `EdgeIntentExecutor.time` / `GeneralParse.time` / `lookAndTalk.time`
+- 候选 domain：`domain_confidence` (list) / `domain_parsers` (list)
+- 各 domain parser 子模块（如 `music` / `phonecall` / `mapApp`）：每个 parser 块下含 `time` / `score` / `parser_version` + 子模块耗时（如 `music.MusicKvParserCost` / `MusicJsgfParserCost` / `MusicIcsfModelParserCost` / `MusicGlobalCost`）
+- **`nlp_model_version`** (dict) — 各模型 checkpoint 版本（如 `arbitrator-l1: 20241205_offline` / `phonecall-icsf: 240205_offline` / `mapapp-icsf-single: 241224_offline`）
+- `nlp_edge_version` — 边端 NLP 引擎整体版本
+- `edge_track` — 上下文/能力 capability 追踪：`capabilitiesVersion` / `contexts`（用到的 context namespace list）/ `arbitrator_priority`
+- `llm_wait` — 是否等待 LLM
+
+**`other_infos`** — 其他辅助信息（list）
+
+### 命令模板
+
+```bash
+# 整条全离线日志（含 request_infos[0]、response_infos[0]、other_infos）
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --fields request_id,tip,tip_name,request_infos,response_infos,other_infos
+
+# 只看模型自身打的 debug 日志
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --json-path response_infos.0.nlp_debug_info
+
+# 模型版本 + 仲裁结果速览
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --fields request_id,tip,response_infos.0.nlp_debug_info.Arbitrate,response_infos.0.nlp_debug_info.nlp_model_version,response_infos.0.nlp_debug_info.nlp_edge_version,request_infos.0.engine_model,request_infos.0.offline_model_ver
+
+# 引擎全部指令（看 is_offline 区分离/在线）
+python elk_query.py <rid> --preset micar --date 20260424 \
+  --json-path response_infos.0.instructions
+```
+
+---
+
+## 34496 — 离线NLP结果
+
+`key_value` 顶层就是 `{instructions: [...]}`，结构和 23176 的 `response_infos[0].instructions` 一致，但**只是 NLP 部分的指令子集**（不含 SpeechRecognizer / System / Offline 等）。没有 `nlp_debug_info`、没有 `request_infos`——想看模型决策细节去 23176。
+
+---
+
+## 字段 schema
+
+完整 schema 见 [`../INDEX_CATALOG.md`](../INDEX_CATALOG.md) 中 `onetrack_xiaoai_micar*` 一节。