@cvtoolman/huawei-lts-cli 1.0.3 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024
+Copyright (c) 2024 cvtoolman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,6 +3,7 @@
 **简体中文** | [English](README_en.md)
 
 [![npm version](https://img.shields.io/npm/v/@cvtoolman/huawei-lts-cli.svg)](https://www.npmjs.com/package/@cvtoolman/huawei-lts-cli)
+[![CI](https://github.com/jcxy/huawei-lts-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jcxy/huawei-lts-cli/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 > 让你的 AI 编程助手（Claude Code、Cursor、Copilot、Qoder 等）通过自然语言查询华为云日志服务（LTS）。
@@ -24,11 +25,26 @@ AI 编程助手的上下文窗口很宝贵——一边要装代码库、一边
 |---|---|---|
 | **上下文开销** | **低** — skill 就一个短 markdown 文件，CLI 输出是纯文本 | **高** — 工具 schema + 快照数据常驻上下文 |
 | **AI 使用方式** | 执行 shell 命令，读取结果 | 通过协议调用结构化工具 |
-| **配置难度** | `npm install -g`、一个 skill 文件 | 服务进程、配置连线 |
+| **配置难度** | `npm install -g`、一个 skill 目录 | 服务进程、配置连线 |
 | **适用场景** | 编码过程中顺手查日志 | 长时间运行的自动化循环 |
 
 > **一句话：** 如果你想让 AI 在写代码时顺嘴帮你查日志——CLI + SKILL 是更轻、更省钱的方案。
 
+## 核心设计：先发现，再查询
+
+字段名、字段类型、是否大小写敏感、分词符——**这些全是每条日志流各自的配置**，不是 LTS 的通用事实。任何写死在文档里的字段表，换个环境就是错的，而且不会报错，只会返回空结果。
+
+所以这个工具的答案永远来自运行时：
+
+```bash
+lts-cli groups                    # 我有哪些日志组
+lts-cli streams --group <组名>     # 这个组下有哪些流
+lts-cli fields                    # 这条流有哪些字段、什么类型、大小写敏感吗
+lts-cli query --last 2h -q '...'  # 这才开始查
+```
+
+`fields` 是 2.0 新增的命令，也是 skill 敢不写任何字段表的前提。SKILL.md 里明确要求 AI：任何 `field:value` 里的字段，必须来自 `fields` 的实际输出；凭印象构造的字段查询在 LTS 上不会报错，只会返回空——然后 AI 会误判"没有这条日志"。
+
 ## 快速开始
 
 ### 1. 安装 CLI
@@ -37,208 +53,203 @@ AI 编程助手的上下文窗口很宝贵——一边要装代码库、一边
 npm install -g @cvtoolman/huawei-lts-cli
 ```
 
+需要 Node.js >= 18。
+
 ### 2. 配置凭证
 
 ```bash
 lts-cli init
 ```
 
-向导会依次询问 AK、SK、Project ID、Region，一次配好。配置存储在 `~/.lts-cli/config.json`。
+向导会依次询问 AK、SK、Project ID、Region，一次配好，只写一个文件：
 
-### 3. 安装 Skill（给 AI 工具用）
+| 文件 | 内容 | 谁读 |
+|---|---|---|
+| `~/.lts-cli/config.json` | 凭证、默认日志组/流、`traceField`（权限 0600） | 仅 CLI |
 
-**Claude Code:**
-```bash
-mkdir -p .claude/skills/huawei-lts-log-query
-curl -o .claude/skills/huawei-lts-log-query/SKILL.md \
-  https://raw.githubusercontent.com/jcxy/huawei-lts-cli/main/skills/huawei-lts-log-query/SKILL.md
-```
+**这个目录不要整个交给 AI**，里面是明文 AK/SK。要看配置用 `lts-cli config --list`（已脱敏），不需要打开文件。
 
-**Qoder:**
-```bash
-mkdir -p .qoder/skills/huawei-lts-log-query
-curl -o .qoder/skills/huawei-lts-log-query/SKILL.md \
-  https://raw.githubusercontent.com/jcxy/huawei-lts-cli/main/skills/huawei-lts-log-query/SKILL.md
-```
-
-**手动安装（任意 AI 工具）：** 将 [skills/huawei-lts-log-query/SKILL.md](skills/huawei-lts-log-query/SKILL.md) 复制到对应 AI 工具的 skills 目录下（`.claude/skills/`、`.qoder/skills/`、`.cursor/skills/` 等）。
+日志组有哪些、字段叫什么、值长什么样——这些事实全部靠 `lts-cli groups` / `streams` / `fields` 现查，仓库和配置里都不存第二份。
 
-### 4. 命令行直接使用（不依赖 AI）
+拿到控制台日志搜索页的 URL 时，可以直接导入 region / groupId / streamId：
 
 ```bash
-# 基础查询
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z
-
-# 简单关键词搜索（旧版，向后兼容）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z -k "ERROR"
-
-# 高级查询：多字段组合（推荐）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "content:error AND appName:myapp"
+lts-cli init --from-url "<控制台URL>"
+```
 
-# 复杂逻辑查询
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "(level:ERROR OR level:WARN) NOT env:test"
+### 3. 安装 Skill（给 AI 工具用）
 
-# SQL 分析查询
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "SELECT count(*) as cnt, level FROM log GROUP BY level" \
-  -f json
+用 [skills CLI](https://skills.sh) 一条命令装到对应工具的目录（支持 75+ 种 agent）：
 
-# JSON 格式输出，管道给 jq 处理
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z -f json | jq .
+```bash
+npx skills add jcxy/huawei-lts-cli -a qoder          # Qoder
+npx skills add jcxy/huawei-lts-cli -a claude-code    # Claude Code
+npx skills add jcxy/huawei-lts-cli -a cursor         # Cursor
+npx skills add jcxy/huawei-lts-cli                   # 交互式选 agent
 ```
 
-> 💡 **提示**：使用 `-q` 参数可实现与 LTS 控制台相同的多条件组合查询功能。详见 [查询语法速查表](skills/huawei-lts-log-query/references/cheatsheet.md) 和 [高级查询指南](skills/huawei-lts-log-query/references/advanced-query-guide.md)。
-
-## 命令参考
+装完重启 AI 工具：skill 在会话启动时读进上下文，已经开着的会话不会热加载。日常用 `npx skills update` 更新、`npx skills remove` 卸载。
 
-### `lts-cli query` — 查询日志
+不想用 npx 也可以手动复制（任何工具都适用）：
 
 ```bash
-lts-cli query [选项]
-
-选项:
-  -g, --group-id <groupId>      日志组 ID（可在配置中预设）
-  -s, --stream-id <streamId>    日志流 ID（可在配置中预设）
-  --start-time, --st <time>     开始时间，ISO 8601 格式（必填）
-  --end-time, --et <time>       结束时间，ISO 8601 格式（必填）
-  -k, --keyword <keyword>       简单关键词搜索（旧版，不推荐）
-  -q, --query <query>           高级查询表达式（推荐）：
-                                  - 字段查询: content:error AND appName:myapp
-                                  - 比较运算: time>60 AND region:r
-                                  - SQL语法: SELECT * FROM log WHERE ...
-                                  - 逻辑运算符: AND, OR, NOT（需空格分隔）
-  -l, --limit <limit>           每页条数（默认: 100）
-  -o, --offset <offset>         分页偏移量（默认: 0）
-  -r, --reverse                 按时间倒序
-  -f, --format <format>         输出格式: pretty、json、table（默认: pretty）
-  --no-paginate                 关闭自动翻页
+git clone --depth 1 https://github.com/jcxy/huawei-lts-cli.git /tmp/huawei-lts-cli
+cp -r /tmp/huawei-lts-cli/skills/huawei-lts-log-query <目标 skills 目录>/
 ```
 
-#### 高级查询语法示例
+> `npx skills` 默认用软链指向一份 git clone，更新时一起同步。用 `--copy`（Windows 无软链权限时的退路）或插件方式安装时，升级会整目录替换——如果你在里面放了业务词表，先备份。
 
-**字段查询：**
-```bash
-# 单字段匹配
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "content:error"
+### 4. 业务词表（可选）
 
-# 多字段组合（且关系）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "content:error AND appName:myapp AND node:server1"
+AI 不知道「订单服务」在你的日志里叫什么。两条路，都不需要配置文件：
 
-# 多字段组合（或关系）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "level:ERROR OR level:WARN"
+- **默认行为**：AI 用管道 SQL 实时枚举候选值（`* | SELECT appName, count(*) GROUP BY appName`），再问你挑哪一个。不落盘，也不会过期。
+- **想省这一步**：在 skill 的 `references/vocab.md` 里写映射。这个文件默认不存在，自己建；已被 `.gitignore` 排除，不会被误提交。
 
-# 排除条件
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "level:DEBUG NOT module:test"
+### 5. 命令行直接使用（不依赖 AI）
 
-# 数值比较
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "response_time>1000 AND status_code!=200"
+```bash
+# 最近 2 小时最新 50 条
+lts-cli query --last 2h -r -l 50
 
-# 复杂组合
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "(level:ERROR OR level:WARN) NOT env:test"
-```
+# 组合条件
+lts-cli query --last 2h --app <appName> --content timeout -r
 
-**SQL 查询：**
-```bash
-# 统计各应用错误数量
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "SELECT count(*) as cnt, appName FROM log WHERE content LIKE '%error%' GROUP BY appName"
+# 任意表达式
+lts-cli query --last 1d -q '(level:ERROR OR level:WARN) NOT env:test' -r
+
+# 管道分析：先过滤再统计
+lts-cli query --last 1d -q 'level:ERROR | SELECT count(*) AS cnt, appName GROUP BY appName' -f json
 
-# 平均响应时间
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "SELECT avg(response_time) as avg_time FROM log WHERE status_code=200"
+# 机器处理
+lts-cli query --last 1h -f json | jq '.logs[].content'
 ```
 
-> ⚠️ **注意**：AND、OR、NOT 前后必须有**空格**！
+> 💡 语法细节见 [查询语法](skills/huawei-lts-log-query/references/query-syntax.md)，命令全貌见 [CLI 参考](skills/huawei-lts-log-query/references/cli-reference.md)。
 
-详细文档请查看：
-- [查询语法速查表](skills/huawei-lts-log-query/references/cheatsheet.md)
-- [高级查询指南](skills/huawei-lts-log-query/references/advanced-query-guide.md)
-- [控制台 vs CLI 对照](skills/huawei-lts-log-query/references/query-comparison.md)
+## 命令参考
 
-### `lts-cli config` — 管理配置
+| 命令 | 作用 |
+|---|---|
+| `lts-cli groups` | 列出日志组 |
+| `lts-cli streams` | 列出日志流（`--group <组名>` 过滤） |
+| `lts-cli fields` | 读取日志流的索引配置 |
+| `lts-cli query` | 查询日志 |
+| `lts-cli trace <id>` | 按 ID 还原完整请求链路 |
+| `lts-cli context` | 查看某条日志的前后文 |
+| `lts-cli config` | 管理配置 |
+| `lts-cli init` | 配置向导 |
+| `lts-cli completion` | 生成 shell 补全 |
+
+### `lts-cli query`
 
 ```
-lts-cli config [选项]
-
-选项:
-  --set <key=value>             设置配置项
-  --get <key>                   查看配置项
-  --list                        列出所有配置
-  --unset <key>                 删除配置项
+-g, --group-id <id>       日志组 ID（可在配置中预设）
+-s, --stream-id <id>      日志流 ID（可在配置中预设）
+--last <时长>             30m / 2h / 1d / 7d，与 --st/--et 互斥
+--st, --start-time <ISO>  开始时间
+--et, --end-time <ISO>    结束时间
+-q, --query <expr>        查询表达式或管道分析
+--app <取值>              appName:"<取值>"，与 -q 用 AND 合并
+--content <关键词>        content:"<关键词>"，与 -q 用 AND 合并
+--request-id <id>         REQUEST_ID:"<id>"，按时间正序输出
+-l, --limit <n>           每页条数（默认 100），--all 时即单页大小
+-r, --reverse             最新优先
+-f, --format <fmt>        pretty（默认）/ table / json
+--all                     沿游标读到末尾（上限 10000 条）
 ```
 
-### `lts-cli init` — 配置向导
+`--app` / `--content` / `--request-id` 自动为值加双引号——含连字符的 UUID 不加引号会被分词导致匹配不到。
 
-```
-lts-cli init
+### `lts-cli trace`
 
-交互式向导，引导设置 AK、SK、Project ID、Region、endpoint，
-以及可选的默认日志组和日志流。
+```bash
+lts-cli trace <id> [--field <name>] [--last 24h] [-l 200] [-f fmt]
 ```
 
-### `lts-cli completion` — Shell 补全
-
-```
-lts-cli completion <bash|zsh|powershell>
+按时间正序拉出一条 ID 的完整链路。默认走全文检索（不依赖任何特定字段命名）；如果你的日志流有专用字段，配一次即可：
 
-生成 shell 补全脚本。
+```bash
+lts-cli config --set traceField=REQUEST_ID
 ```
 
 ## 配置说明
 
-配置存储在 `~/.lts-cli/config.json`（Linux/macOS）或 `%USERPROFILE%\.lts-cli\config.json`（Windows）。
+配置文件 `~/.lts-cli/config.json`（Windows 为 `%USERPROFILE%\.lts-cli\config.json`）：
 
 | 键 | 必填 | 说明 |
 |---|---|---|
 | `ak` | 是 | 华为云访问密钥 |
 | `sk` | 是 | 华为云私有密钥 |
 | `projectId` | 是 | 项目 ID |
-| `region` | 否 | 如 `cn-south-1` |
+| `region` | 否 | 如 `cn-north-4` |
 | `endpoint` | 否 | 需包含 `https://` |
 | `groupId` | 否 | 默认日志组 ID |
 | `streamId` | 否 | 默认日志流 ID |
+| `traceField` | 否 | `trace` 默认匹配的字段名，缺省为 `content` |
+
+`lts-cli config --list` 会把 `ak` / `sk` 脱敏输出，避免凭证进入终端滚屏、shell 历史或 AI 上下文。
 
 ### 环境变量
 
-所有配置项也支持环境变量（适用于 CI/CD）：
+所有配置项都支持环境变量（适用于 CI/CD），优先级高于配置文件：
+
+`LTS_AK` `LTS_SK` `LTS_PROJECT_ID` `LTS_REGION` `LTS_ENDPOINT` `LTS_GROUP_ID` `LTS_STREAM_ID`
 
-| 配置键 | 环境变量 |
+## 支持的区域
+
+以下是 `lts-cli init` 内置的 region → endpoint 映射：
+
+| 区域 ID | Endpoint |
 |---|---|
-| `ak` | `LTS_AK` |
-| `sk` | `LTS_SK` |
-| `projectId` | `LTS_PROJECT_ID` |
-| `region` | `LTS_REGION` |
-| `endpoint` | `LTS_ENDPOINT` |
-| `groupId` | `LTS_GROUP_ID` |
-| `streamId` | `LTS_STREAM_ID` |
+| `cn-north-1` | `lts.cn-north-1.myhuaweicloud.com` |
+| `cn-north-2` | `lts.cn-north-2.myhuaweicloud.com` |
+| `cn-north-4` | `lts.cn-north-4.myhuaweicloud.com` |
+| `cn-north-5` | `lts.cn-north-5.myhuaweicloud.com` |
+| `cn-north-9` | `lts.cn-north-9.myhuaweicloud.com` |
+| `cn-east-2` | `lts.cn-east-2.myhuaweicloud.com` |
+| `cn-east-3` | `lts.cn-east-3.myhuaweicloud.com` |
+| `cn-east-4` | `lts.cn-east-4.myhuaweicloud.com` |
+| `cn-south-1` | `lts.cn-south-1.myhuaweicloud.com` |
+| `cn-south-2` | `lts.cn-south-2.myhuaweicloud.com` |
+| `cn-south-4` | `lts.cn-south-4.myhuaweicloud.com` |
+| `cn-southwest-2` | `lts.cn-southwest-2.myhuaweicloud.com` |
+| `ap-southeast-1` | `lts.ap-southeast-1.myhuaweicloud.com` |
+| `ap-southeast-2` | `lts.ap-southeast-2.myhuaweicloud.com` |
+| `ap-southeast-3` | `lts.ap-southeast-3.myhuaweicloud.com` |
+| `af-south-1` | `lts.af-south-1.myhuaweicloud.com` |
+| `la-south-2` | `lts.la-south-2.myhuaweicloud.com` |
+| `la-north-2` | `lts.la-north-2.myhuaweicloud.com` |
+| `sa-brazil-1` | `lts.sa-brazil-1.myhuaweicloud.com` |
+| `na-mexico-1` | `lts.na-mexico-1.myhuaweicloud.com` |
+
+不在表里时用 `--set endpoint=https://...` 手动指定，或参考 [华为云 LTS 终端节点](https://support.huaweicloud.com/api-lts/lts_api_0011.html)。
+
+## 升级说明
+
+### 从 2.0 升级到 2.1
+
+| 变更 | 说明 |
+|---|---|
+| `init` 不再生成 `~/.lts-cli/profile.md` | 业务词表改为 skill 目录下的 `references/vocab.md`。旧文件可以删，留着也没影响（CLI 从来没读过它） |
+| SKILL.md 增加运行时枚举候选值 | 没有词表也能定位应用名 |
+| 新增 `npx skills` 安装方式 | 见上文「安装 Skill」 |
 
-环境变量优先级高于配置文件。
+命令行参数没有变化，脚本不需要改。
 
-## 支持的区域
+### 从 1.x 升级到 2.0
+
+2.0 修了三个会静默出错的问题，因此有破坏性变更：
 
-| 区域 ID | 区域名称 | Endpoint |
+| 变更 | 原因 | 迁移 |
 |---|---|---|
-| `cn-north-1` | 华北-北京一 | `lts.cn-north-1.myhuaweicloud.com` |
-| `cn-north-4` | 华北-北京四 | `lts.cn-north-4.myhuaweicloud.com` |
-| `cn-east-2` | 华东-上海二 | `lts.cn-east-2.myhuaweicloud.com` |
-| `cn-east-3` | 华东-上海三 | `lts.cn-east-3.myhuaweicloud.com` |
-| `cn-south-1` | 华南-广州 | `lts.cn-south-1.myhuaweicloud.com` |
-| `cn-south-4` | 华南-深圳 | `lts.cn-south-4.myhuaweicloud.com` |
-| `cn-southwest-2` | 西南-贵阳一 | `lts.cn-southwest-2.myhuaweicloud.com` |
-| `ap-southeast-1` | 亚太-新加坡 | `lts.ap-southeast-1.myhuaweicloud.com` |
-| `ap-southeast-2` | 亚太-曼谷 | `lts.ap-southeast-2.myhuaweicloud.com` |
-| `ap-southeast-3` | 亚太-雅加达 | `lts.ap-southeast-3.myhuaweicloud.com` |
-| `af-south-1` | 非洲-约翰内斯堡 | `lts.af-south-1.myhuaweicloud.com` |
-
-> 完整列表请参考 [华为云 LTS 终端节点](https://support.huaweicloud.com/api-lts/lts_api_0011.html)。
+| 删除 `--offset` | LTS 的 SDK 根本没有 offset 字段，该参数一直静默失效；`--all` 会重复拉同一页直到塞满 10000 条 | 用 `--all`，或缩小时间范围 |
+| 删除 `-k, --keyword` | 与 `-q` 行为完全等价 | 改成 `-q "<关键词>"` |
+| 删除 `--no-paginate` | 单页本来就是默认行为，该参数从未被读取 | 直接删掉 |
+| `trace` 默认字段由 `REQUEST_ID` 改为 `content` | `REQUEST_ID` 只是某类应用的命名约定，不是 LTS 通用概念 | 需要精确字段时 `lts-cli config --set traceField=REQUEST_ID` |
+| `-f json` 输出字段 `logTime` 改名为 `lineNum` | LTS 的日志记录只有 `content` / `line_num` / `labels`，没有时间戳，原名是错的 | 更新解析脚本 |
+
+此外，结果不完整时会向 stderr 输出警告（`isQueryComplete=false` 或触达 10000 条上限）。**这些警告不能忽略**——此时结果就是残缺的。
 
 ## 开发指南
 
@@ -246,16 +257,23 @@ lts-cli completion <bash|zsh|powershell>
 git clone https://github.com/jcxy/huawei-lts-cli.git
 cd huawei-lts-cli
 npm install
-npm run build
-
-# 开发模式运行（无需编译）
-npm run dev -- query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z
 
-# 本地测试
-npm link
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z
+npm run build      # 编译到 dist/
+npm run dev -- query --last 2h     # 直接从源码跑
+npm test           # node:test，覆盖纯函数与游标推进
+npm run typecheck  # tsc --noEmit
 ```
 
+测试使用 Node 内置的 `node:test` + `tsx`，不引入额外测试依赖。跑测试需要 Node >= 22——`node --test` 的通配符支持直到 22 才落地，20 上会报 `Could not find`。CLI 本身在 Node 18 上可以正常运行，CI 的 typecheck/build 覆盖 18/20/22。
+
+架构约定见 [CONTEXT.md](CONTEXT.md) 与 [docs/adr/](docs/adr/)。提交前请读 [CONTRIBUTING.md](CONTRIBUTING.md)——里面写了这个仓库唯一不能被破坏的原则：**同一个事实只允许有一个来源**。
+
+## 参与
+
+- 报告问题：[issue 模板](https://github.com/jcxy/huawei-lts-cli/issues/new/choose)（请勿贴真实凭证、日志组 ID 或内部业务名）
+- 安全问题：[SECURITY.md](SECURITY.md)，走私密通道，不要开公开 issue
+- 版本变更：[CHANGELOG.md](CHANGELOG.md)
+
 ## License
 
 [MIT](LICENSE)

package/dist/cli/commands/common.js

@@ -5,6 +5,7 @@ exports.resolveGroupStream = resolveGroupStream;
 exports.resolveTimeParams = resolveTimeParams;
 exports.buildQueryExpression = buildQueryExpression;
 exports.resolveFormat = resolveFormat;
+exports.warnIfIncomplete = warnIfIncomplete;
 exports.handleCommandError = handleCommandError;
 const config_1 = require("../../config");
 /** 加载配置并校验凭证，缺失时打印引导并退出 */
@@ -75,6 +76,17 @@ function buildQueryExpression(options) {
 function resolveFormat(value) {
     return ['json', 'table', 'pretty'].includes(value) ? value : 'pretty';
 }
+/**
+ * LTS 在时间跨度过大时会返回不完整结果（isQueryComplete=false）。
+ * 结果照样输出（残缺比没有好），但必须在 stderr 明确告警——安静地给出半个答案，
+ * 比直接报错更危险：调用方会基于残缺数据下结论。
+ */
+function warnIfIncomplete(result) {
+    if (result.isQueryComplete === false) {
+        console.error('Warning: LTS reported an incomplete result set (isQueryComplete=false). ' +
+            'Narrow the time range (e.g. --last 1h) or add a filter before trusting totals.');
+    }
+}
 /** 统一错误处理：常见错误给出友好提示 */
 function handleCommandError(error) {
     const msg = error.message || String(error);

package/dist/cli/commands/config.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createConfigCommand = createConfigCommand;
 const commander_1 = require("commander");
 const config_1 = require("../../config");
+/** 凭证类字段一律脱敏：`config --list` 会把输出留在终端滚屏、shell 历史、agent 上下文里。 */
+const SECRET_KEYS = new Set(['ak', 'sk']);
+function maskSecret(value) {
+    if (value.length <= 4)
+        return '****';
+    return `${value.slice(0, 2)}${'*'.repeat(Math.max(4, value.length - 4))}${value.slice(-2)}`;
+}
 function createConfigCommand() {
     const cmd = new commander_1.Command('config');
     cmd.description('Manage LTS CLI configuration')
@@ -24,7 +31,7 @@ function createConfigCommand() {
         else if (options.get) {
             const value = (0, config_1.getConfig)(options.get);
             if (value !== undefined) {
-                console.log(value);
+                console.log(SECRET_KEYS.has(options.get) ? maskSecret(value) : value);
             }
             else {
                 console.error(`Config key '${options.get}' not found`);
@@ -39,7 +46,7 @@ function createConfigCommand() {
             }
             else {
                 for (const [key, value] of entries) {
-                    console.log(`${key}=${value}`);
+                    console.log(`${key}=${SECRET_KEYS.has(key) ? maskSecret(value) : value}`);
                 }
             }
         }

package/dist/cli/commands/fields.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFieldsCommand = createFieldsCommand;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const client_1 = require("../../lts/client");
+const common_1 = require("./common");
+/**
+ * 输出日志流的索引配置。
+ *
+ * 存在的理由：字段名、字段类型、大小写是否敏感、分词符，全都是**每条日志流各自一份**
+ * 的配置（SDK 里是 LTSFullTextIndexInfo / LTSFieldsInfo）。任何写进文档的字段表都只对
+ * 某一条流成立，换个环境就是错的。所以答案必须在运行时从 API 取。
+ */
+function boolLabel(value) {
+    if (value === undefined)
+        return '-';
+    return value ? 'yes' : 'no';
+}
+function formatJson(index) {
+    return JSON.stringify(index, null, 2);
+}
+function formatTable(index) {
+    const lines = [];
+    const summary = new cli_table3_1.default({ head: ['Full-text index', 'Value'] });
+    summary.push(['enabled', boolLabel(index.fullText.enabled)], ['caseSensitive', boolLabel(index.fullText.caseSensitive)], ['includeChinese', boolLabel(index.fullText.includeChinese)], ['tokenizer', index.fullText.tokenizer || '-']);
+    lines.push(summary.toString());
+    if (index.fields.length === 0) {
+        lines.push('');
+        lines.push('No field index configured — only full-text search is available on this stream.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    const fields = new cli_table3_1.default({
+        head: ['Field', 'Type', 'Case-sensitive', 'Chinese', 'Tokenizer', 'Quick analysis'],
+    });
+    for (const f of index.fields) {
+        fields.push([
+            f.name,
+            f.type || '-',
+            boolLabel(f.caseSensitive),
+            boolLabel(f.includeChinese),
+            f.tokenizer || '-',
+            boolLabel(f.quickAnalysis),
+        ]);
+    }
+    lines.push(fields.toString());
+    return lines.join('\n');
+}
+function formatPretty(index) {
+    const lines = [];
+    lines.push(chalk_1.default.bold(`Stream ${index.streamId}`));
+    lines.push('');
+    lines.push(chalk_1.default.bold('Full-text index'));
+    lines.push(`  enabled:        ${boolLabel(index.fullText.enabled)}`);
+    lines.push(`  caseSensitive:  ${boolLabel(index.fullText.caseSensitive)}`);
+    lines.push(`  includeChinese: ${boolLabel(index.fullText.includeChinese)}`);
+    lines.push(`  tokenizer:      ${index.fullText.tokenizer || '-'}`);
+    lines.push('');
+    if (index.fields.length === 0) {
+        lines.push(chalk_1.default.yellow('No field index configured — only full-text search is available.'));
+        return lines.join('\n');
+    }
+    lines.push(chalk_1.default.bold(`Fields (${index.fields.length})`));
+    for (const f of index.fields) {
+        const flags = [
+            f.caseSensitive ? 'case-sensitive' : 'case-insensitive',
+            f.includeChinese ? 'chinese' : 'no-chinese',
+            f.quickAnalysis ? 'quick-analysis' : null,
+        ].filter(Boolean);
+        lines.push(`  ${chalk_1.default.cyan(f.name)}  ${chalk_1.default.gray(f.type || '-')}  ${chalk_1.default.gray(flags.join(', '))}`);
+        if (f.tokenizer) {
+            lines.push(chalk_1.default.gray(`    tokenizer: ${f.tokenizer}`));
+        }
+    }
+    return lines.join('\n');
+}
+function createFieldsCommand() {
+    const cmd = new commander_1.Command('fields');
+    cmd
+        .description('Show the index config of a log stream (fields, types, case sensitivity, tokenizer)')
+        .option('-g, --group-id <groupId>', 'Log group ID (can also be set via config)')
+        .option('-s, --stream-id <streamId>', 'Log stream ID (can also be set via config)')
+        .option('-f, --format <format>', 'Output format: json, table, pretty', 'pretty')
+        .action(async (options) => {
+        const config = (0, common_1.loadCheckedConfig)();
+        const { groupId, streamId } = (0, common_1.resolveGroupStream)(options, config);
+        const format = (0, common_1.resolveFormat)(options.format);
+        const client = new client_1.LTSClient(config);
+        try {
+            const index = await client.getStreamIndex(groupId, streamId);
+            const output = format === 'json'
+                ? formatJson(index)
+                : format === 'table'
+                    ? formatTable(index)
+                    : formatPretty(index);
+            console.log(output);
+        }
+        catch (error) {
+            (0, common_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

package/dist/cli/commands/init.js

@@ -35,13 +35,29 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createInitCommand = createInitCommand;
 const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
 const config_1 = require("../../config");
+const store_1 = require("../../config/store");
 function ask(rl, question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => resolve(answer.trim()));
     });
 }
+/**
+ * 2.0 及更早版本会在凭证目录里生成一份业务词表骨架，那是把 AI 引进
+ * 明文 AK/SK 所在目录的入口。2.1 起不再生成，业务词表改由 skill 的
+ * `references/` 承载。这里只对老用户的残留文件做一次性提示，绝不代删。
+ */
+function reportLegacyProfile() {
+    const legacy = path.join((0, store_1.getConfigDir)(), 'profile.md');
+    if (!fs.existsSync(legacy)) {
+        return;
+    }
+    console.log(`  note: ${legacy} is no longer used since 2.1 — safe to delete.`);
+    console.log('        Business vocabulary now lives in the skill: references/vocab.md');
+}
 const ENDPOINT_MAP = {
     'cn-north-1': 'lts.cn-north-1.myhuaweicloud.com',
     'cn-north-2': 'lts.cn-north-2.myhuaweicloud.com',
@@ -144,13 +160,17 @@ function createInitCommand() {
             }
             console.log('');
             console.log('✅ Configuration saved!');
+            reportLegacyProfile();
             console.log('');
             console.log('Try it out:');
             if (groupId && streamId) {
-                console.log('  lts-cli query --start-time 2024-01-01T00:00:00Z --end-time 2024-01-02T00:00:00Z');
+                console.log('  lts-cli query --last 2h');
+                console.log('  lts-cli fields');
             }
             else {
-                console.log('  lts-cli query -g <group-id> -s <stream-id> --start-time 2024-01-01T00:00:00Z --end-time 2024-01-02T00:00:00Z');
+                console.log('  lts-cli groups                       # find your log group ID');
+                console.log('  lts-cli streams --group <group-name> # find your log stream ID');
+                console.log('  lts-cli query -g <groupId> -s <streamId> --last 2h');
             }
             console.log('');
         }
@@ -203,9 +223,11 @@ function importFromConsoleUrl(raw) {
     }
     console.log('');
     console.log('✅ Configuration saved!');
+    reportLegacyProfile();
     console.log('');
     console.log('Next steps:');
     console.log('  1. Configure credentials if not done yet: lts-cli init');
-    console.log('  2. Query logs: lts-cli query --last 2h --content "error"');
+    console.log('  2. Check which fields this stream indexes: lts-cli fields');
+    console.log('  3. Query logs: lts-cli query --last 2h');
     console.log('');
 }