wuyang/zk-data-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unify skills under repository root

Browse Source
This commit is contained in:
武阳
2026-05-08 10:54:27 +08:00
parent dcc43adaa6
commit 37fc367304
16 changed files with 967 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/elk-fetch/SKILL.md
+200
View File
@@ -0,0 +1,200 @@
---
name: elk-fetch
description: 从小米内网 ELK 按 request id 拉取日志。支持多账号 profile、多 ES 集群、多业务 preset（主 NLP / 拒识表 / 免唤醒后处理日志 / 小米汽车 OneTrack 端侧埋点）、深度 JSON 字段自动解析。绕开 Kibana CAS 登录，直接走 ES HTTP API。触发条件：用户给出 Kibana 链接、提到 requestId / request_id 查日志、想看某次请求的 NLP 日志 / 中控仲裁日志（intent_arbitrator_info / llm_agent_info / hit_rules / score_domains）/ 拒识 rejectInfo / KEY_WORD_FREE_RESTRIC / 免唤醒判决（keyword-free-log）/ 小爱端到端可用性 / 小爱全离线日志 / OneTrack 埋点 / micar tip。
when_to_use: 用户给出 Kibana 链接、request_id/requestId，或要求查询 NLP 日志、中控仲裁日志、拒识日志、免唤醒日志、小米汽车 OneTrack 埋点日志时使用。
aliases: elk, elk-query, log-fetch, request-log
allowed_tools: python_exec, python_package, read_file
---
# ELK Fetch Skill
按 request id 查小米内网 ELK。**多个 ES 集群**：`default`/`reject` 走 `akaiservice.api.es.srv:80`，`micar` 走独立的 `c3log.api.es.srv:80`。每个 profile 自带 `host`，脚本会自动选集群。
账号密码（团队共用）已 commit 进仓库的 `profiles.json`，无需配置。需要换账号时用 `ELK_FETCH_PROFILES=/abs/path/to/profiles.json` 指向自己的文件。
## 在本数据 Agent 中使用
本 skill 已安装在项目目录 `skills/elk-fetch/`。在本项目中不要用 `bash` 执行 `python elk_query.py`，也不要用 `pip` 直接安装依赖。
实际查询必须使用 `python_exec`：
```json
{
"script_path": "skills/elk-fetch/elk_query.py",
"args": ["<request_id>", "--preset", "main"],
"timeout_seconds": 90,
"max_output_chars": 20000
}
```
如果 `python_exec` 返回缺少 `elasticsearch` 或 `urllib3`，先使用 `python_package` 安装：
```json
{
"action": "install",
"packages": ["elasticsearch<8", "urllib3"],
"timeout_seconds": 120
}
```
下面所有 `python elk_query.py ...` 命令模板只表示参数选择；实际执行时都要转换为 `python_exec.script_path = "skills/elk-fetch/elk_query.py"` 和对应的 `args`。
## 关键文件
| 文件 | 用途 |
|------|------|
| `elk_query.py` | CLI 入口 |
| `INDEX_CATALOG.md` | **每张表的字段 schema reference**（顶层字段 / JSON 字符串字段内部结构） |
| `business/keyword-free.md` | 免唤醒判决 — 拒识 vs kwfree 两张表三个视角的区分 + 排查 playbook |
| `business/intent-arbitrator.md` | 中控仲裁 — `intention.intent_arbitrator_info` 子字段语义 |
| `business/micar-onetrack.md` | 小米汽车 OneTrack — 23177 端到端可用性 / 23176 全离线日志 / 34496 离线NLP结果 |
## Preset 速查
| preset | profile | 集群 | 索引 pattern | 字段名 | 时间字段 | 内置过滤 |
|--------|---------|------|-------------|--------|---------|---------|
| `main` (默认) | default | akaiservice | `arch-flat-nlp-log-f-*` | `request_id` | `timestamp` | 无 |
| `reject` | reject | akaiservice | `aiservice_duplex_rejection_lcs_log*` | **`requestId`** | **`time`** | 无 |
| `kwfree` | default | akaiservice | `nlp_post_processing_lcs-*` | `requestId` | `timestamp` | `moduleName = keyword-free-log` |
| `micar` | micar | **c3log** | `onetrack_xiaoai_micar*` | `request_id` | `timestamp` | 无（一个 rid 多条 tip） |
## 选 preset 的决策表
| 用户想看 | preset | 额外参数 | 业务深入 |
|---------|--------|---------|---------|
| query / domain / func / 设备信息 | `main` | — | — |
| **中控仲裁日志**（agent 路由 / score_domains / llm_agent_info / hit_rules） | `main` | `--json-path intention.intent_arbitrator_info` | [`business/intent-arbitrator.md`](business/intent-arbitrator.md) |
| **拒识表整体**（rejectInfo 全部 / reject_reason / 各子策略） | `reject` | 不加 `--json-path` | [`business/keyword-free.md`](business/keyword-free.md) |
| **拒识里的免唤醒**（后置拒识调到免唤醒那次的出入参） | `reject` | `--json-path rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC` | [`business/keyword-free.md`](business/keyword-free.md) |
| **后处理的免唤醒**（免唤醒模块被后处理调用时自己记的日志） | `kwfree` | — | [`business/keyword-free.md`](business/keyword-free.md) |
| **小米汽车端侧埋点**（端到端可用性 / 全离线日志 / ASR 状态等 OneTrack tip） | `micar` | **`--date YYYYMMDD` 强烈建议** | [`business/micar-onetrack.md`](business/micar-onetrack.md) |
## 从 Kibana 链接提取参数
Kibana URL 形如：
```text
...discover#/?...
filters:(...match_phrase:(moduleName:keyword-free-log))
index:d7ff4d65-... ← Kibana index pattern UUID（非 ES 索引名）
query:(language:kuery,query:'requestId : 67f41dff...')
time:(from:now-1d,to:now)
```
反推方法：
- `requestId : xxx` / `request_id : xxx` → request id
- `filters` 里的 `match_phrase:(moduleName:keyword-free-log)` → **`kwfree` preset**
- 主机 `aiservice.ak.kibana.cloud.mioffice.cn` → `default` profile；主机 `akaiservice.kibana.pt.xiaomi.com` → `reject` profile；主机 `c3log.kibana.pt.xiaomi.com` → **`micar` profile（独立集群）**；主机 `akelk.pt.ai.srv` → `default` profile + `main` preset（中控仲裁的 Kibana 前端，底层就是主表）
- index 名为 `onetrack_xiaoai_micar` 直接走 `micar` preset；filter 里有 `tip` / `tip_name` 也走 `micar`
- `time:(from:now-1d,...)` → 默认近 48 小时，`from:'2026-04-22...'` 这种具体日期 → 传 `--date YYYYMMDD`
Kibana index UUID 不能直接反查 ES 索引名；如遇未知 UUID 跑一次 preset 试，打不中再 probe。
## 命令模板
> 路径形如 `python "C:\Users\Sivan\.claude\skills\elk-fetch\elk_query.py" ...`，下方为简写。每个场景的字段语义和排查思路见 `business/` 对应文档。
### 主 NLP 日志（默认）
```bash
python elk_query.py <request_id>
```
### 中控仲裁日志（→ [`business/intent-arbitrator.md`](business/intent-arbitrator.md)）
```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
```
⚠️ 真东西在 `intention.intent_arbitrator_info`，**顶层同名字段通常 null**。
### 拒识表 / `KEY_WORD_FREE_RESTRIC`（→ [`business/keyword-free.md`](business/keyword-free.md)）
```bash
# 整个拒识 rejectInfo
python elk_query.py <rid> --preset reject
# 拒识里的免唤醒子字段
python elk_query.py <rid> --preset reject \
--json-path rejectInfo.strategy_info.reject.KEY_WORD_FREE_RESTRIC
```
同一 requestId 在此索引常有多条（多轮），按 `time` 倒序返回。
### 后处理免唤醒（→ [`business/keyword-free.md`](business/keyword-free.md)）
```bash
# 整个 message
python elk_query.py <rid> --preset kwfree --json-path message
# 是否实际处理 + 跳过原因
python elk_query.py <rid> --preset kwfree \
--fields requestId,message.process,message.skipReason,message.request.keywordFreeType
```
### 小米汽车 OneTrack（→ [`business/micar-onetrack.md`](business/micar-onetrack.md)）
⚠️ 必须传 `--date YYYYMMDD`（按日 rolling，单日 ~300GB）。
```bash
# 这个 request 上报了哪些 tip
python elk_query.py <rid> --preset micar --date 20260424 \
--fields request_id,tip,tip_name,tip_module_name,event_name
# 端到端可用性（23177）的性能时序
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）的模型 debug 输出
python elk_query.py <rid> --preset micar --date 20260424 \
--json-path response_infos.0.nlp_debug_info
```
⚠️ 23176 schema 与其他 tip 不同：负载在 `request_infos[]` / `response_infos[]`，**不在 `key_value`**。`response_infos[0]` 含 `instructions` + `nlp_debug_info` 两块，研究模型行为时都要看，别只取 nlp_debug_info。
### 指定日期 / 自定义索引
```bash
# 老请求超出 48h 窗口
python elk_query.py <rid> --date 20260422
# probe 未知索引
python elk_query.py <rid> \
--index "some-other-*" --field requestId --time-field time --profile reject
```
## 输出格式
始终单个 JSON 对象到 stdout：
```json
{
"request_id": "...",
"preset": "reject",
"profile": "reject",
"index": "aiservice_duplex_rejection_lcs_log*",
"field": "requestId",
"time_field": "time",
"date": "past-48h",
"total": 2,
"hits": [ { "...": "_source（嵌套 JSON 字符串已自动解开）" } ]
}
```
出错时 JSON 里会有 `error` 键，退出码非零。
## 常见坑
- **请求 id 过期**：默认查近 48h，老请求必须 `--date YYYYMMDD`。
- **字段名驼峰 vs 下划线**：`main` / `micar` 是 `request_id`，`reject` / `kwfree` 是 `requestId`；Kibana 界面显示的字段名不一定等于 ES 存储字段名。
- **返回大量字段刷屏**：用 `--fields` 或 `--json-path` 精简。
- **不要用 WebFetch 抓 Kibana URL**：会被 CAS 拦到登录页，永远走这个 skill。