@cvtoolman/huawei-lts-cli 1.0.2 → 2.0.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

@@ -24,11 +24,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 +52,183 @@ 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 |
+| `~/.lts-cli/profile.md` | 业务词表：把「订单服务」映射到日志里的实际取值 | 仅 AI |
 
-**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
-```
+**CLI 不读 `profile.md`，AI 不读 `config.json`。** 后者含明文 AK/SK，任何让 AI 读它的设计都是错的。
+
+拿到控制台日志搜索页的 URL 时，可以直接导入 region / groupId / streamId：
 
-**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
+lts-cli init --from-url "<控制台URL>"
 ```
 
-**手动安装（任意 AI 工具）：** 将 [skills/huawei-lts-log-query/SKILL.md](skills/huawei-lts-log-query/SKILL.md) 复制到对应 AI 工具的 skills 目录下（`.claude/skills/`、`.qoder/skills/`、`.cursor/skills/` 等）。
+### 3. 安装 Skill（给 AI 工具用）
 
-### 4. 命令行直接使用（不依赖 AI）
+skill 目录含 `SKILL.md` 和 2 个参考文档，整目录复制：
 
 ```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 query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "(level:ERROR OR level:WARN) NOT env:test"
-
-# 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
+# Claude Code
+git clone --depth 1 https://github.com/jcxy/huawei-lts-cli.git /tmp/huawei-lts-cli
+mkdir -p .claude/skills/huawei-lts-log-query
+cp -r /tmp/huawei-lts-cli/skills/huawei-lts-log-query/. .claude/skills/huawei-lts-log-query/
 
-# JSON 格式输出，管道给 jq 处理
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z -f json | jq .
+# Qoder：把 .claude/skills/ 换成 .qoder/skills/
+# 其他工具：换成对应目录（.cursor/skills/ 等）
 ```
 
-> 💡 **提示**：使用 `-q` 参数可实现与 LTS 控制台相同的多条件组合查询功能。详见 [查询语法速查表](skills/huawei-lts-log-query/references/cheatsheet.md) 和 [高级查询指南](skills/huawei-lts-log-query/references/advanced-query-guide.md)。
-
-## 命令参考
-
-### `lts-cli query` — 查询日志
+Windows PowerShell：
 
-```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                 关闭自动翻页
+```powershell
+git clone --depth 1 https://github.com/jcxy/huawei-lts-cli.git $env:TEMP\huawei-lts-cli
+New-Item -ItemType Directory -Force .claude\skills\huawei-lts-log-query | Out-Null
+Copy-Item -Recurse -Force $env:TEMP\huawei-lts-cli\skills\huawei-lts-log-query\* .claude\skills\huawei-lts-log-query\
 ```
 
-#### 高级查询语法示例
+### 4. 命令行直接使用（不依赖 AI）
 
-**字段查询：**
 ```bash
-# 单字段匹配
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "content:error"
-
-# 多字段组合（且关系）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "content:error AND appName:myapp AND node:server1"
-
-# 多字段组合（或关系）
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "level:ERROR OR level:WARN"
+# 最近 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:DEBUG NOT module:test"
+# 组合条件
+lts-cli query --last 2h --app <appName> --content timeout -r
 
-# 数值比较
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "response_time>1000 AND status_code!=200"
+# 任意表达式
+lts-cli query --last 1d -q '(level:ERROR OR level:WARN) NOT env:test' -r
 
-# 复杂组合
-lts-cli query --st 2024-01-01T00:00:00Z --et 2024-01-02T00:00:00Z \
-  -q "(level:ERROR OR level:WARN) NOT env:test"
-```
-
-**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 | 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 补全
+按时间正序拉出一条 ID 的完整链路。默认走全文检索（不依赖任何特定字段命名）；如果你的日志流有专用字段，配一次即可：
 
-```
-lts-cli completion <bash|zsh|powershell>
-
-生成 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）：
+### 环境变量
 
-| 配置键 | 环境变量 |
-|---|---|
-| `ak` | `LTS_AK` |
-| `sk` | `LTS_SK` |
-| `projectId` | `LTS_PROJECT_ID` |
-| `region` | `LTS_REGION` |
-| `endpoint` | `LTS_ENDPOINT` |
-| `groupId` | `LTS_GROUP_ID` |
-| `streamId` | `LTS_STREAM_ID` |
+所有配置项都支持环境变量（适用于 CI/CD），优先级高于配置文件：
 
-环境变量优先级高于配置文件。
+`LTS_AK` `LTS_SK` `LTS_PROJECT_ID` `LTS_REGION` `LTS_ENDPOINT` `LTS_GROUP_ID` `LTS_STREAM_ID`
 
 ## 支持的区域
 
-| 区域 ID | 区域名称 | Endpoint |
+以下是 `lts-cli init` 内置的 region → endpoint 映射：
+
+| 区域 ID | Endpoint |
+|---|---|
+| `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)。
+
+## 从 1.x 升级到 2.0
+
+2.0 修了三个会静默出错的问题，因此有破坏性变更：
+
+| 变更 | 原因 | 迁移 |
 |---|---|---|
-| `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 +236,17 @@ 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 >= 20.6（`--import` 的要求）。
+
+架构约定见 [CONTEXT.md](CONTEXT.md) 与 [docs/adr/](docs/adr/)。
+
 ## License
 
 [MIT](LICENSE)

package/dist/cli/commands/common.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCheckedConfig = loadCheckedConfig;
+exports.resolveGroupStream = resolveGroupStream;
+exports.resolveTimeParams = resolveTimeParams;
+exports.buildQueryExpression = buildQueryExpression;
+exports.resolveFormat = resolveFormat;
+exports.warnIfIncomplete = warnIfIncomplete;
+exports.handleCommandError = handleCommandError;
+const config_1 = require("../../config");
+/** 加载配置并校验凭证，缺失时打印引导并退出 */
+function loadCheckedConfig() {
+    const config = (0, config_1.loadConfig)();
+    if (!config.ak || !config.sk || !config.projectId) {
+        console.error('Error: Missing required credentials. Please configure them first:');
+        console.error('');
+        console.error('  Quick setup (recommended):');
+        console.error('    lts-cli init');
+        console.error('');
+        console.error('  Or set individually:');
+        console.error('    lts-cli config --set ak=<your-access-key>');
+        console.error('    lts-cli config --set sk=<your-secret-key>');
+        console.error('    lts-cli config --set projectId=<your-project-id>');
+        process.exit(1);
+    }
+    return config;
+}
+/** groupId/streamId：CLI 参数优先，其次配置默认值，都没有则报错退出 */
+function resolveGroupStream(options, config) {
+    const groupId = options.groupId || config.groupId;
+    const streamId = options.streamId || config.streamId;
+    if (!groupId || !streamId) {
+        console.error('Error: groupId and streamId are required. Provide them via:');
+        console.error('  lts-cli config --set groupId=<your-group-id>');
+        console.error('    lts-cli config --set streamId=<your-stream-id>');
+        console.error('  or use -g <groupId> -s <streamId> flags');
+        console.error('  Tip: run "lts-cli groups" / "lts-cli streams" to discover IDs');
+        process.exit(1);
+    }
+    return { groupId, streamId };
+}
+/** 解析时间选项：--last 与 --st/--et 互斥，至少提供一组 */
+function resolveTimeParams(options, defaultLast) {
+    const startTime = options.startTime || options.st;
+    const endTime = options.endTime || options.et;
+    const last = options.last || (!startTime && !endTime ? defaultLast : undefined);
+    if (last && (startTime || endTime)) {
+        console.error('Error: --last is mutually exclusive with --start-time/--end-time. Provide only one style.');
+        process.exit(1);
+    }
+    if (!last && (!startTime || !endTime)) {
+        console.error('Error: time range required. Use --last (e.g. --last 2h) or both --start-time and --end-time.');
+        process.exit(1);
+    }
+    return last ? { last } : { startTime, endTime };
+}
+/** 将 -q 表达式与便捷筛选 flag 合并为一个查询表达式（AND 连接）
+ *  字段值统一加双引号：含连字符等分词符的值（如 UUID）不加引号会匹配不到 */
+function buildQueryExpression(options) {
+    const parts = [];
+    if (options.query) {
+        parts.push(options.query);
+    }
+    if (options.app) {
+        parts.push(`appName:"${options.app}"`);
+    }
+    if (options.content) {
+        parts.push(`content:"${options.content}"`);
+    }
+    if (options.requestId) {
+        parts.push(`REQUEST_ID:"${options.requestId}"`);
+    }
+    return parts.length > 0 ? parts.join(' AND ') : undefined;
+}
+/** 解析输出格式，非法值回退 pretty */
+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);
+    if (msg.includes('Invalid URL')) {
+        console.error('Error: Invalid endpoint URL. Make sure it starts with https://');
+        console.error('  Example: https://lts.cn-south-1.myhuaweicloud.com');
+    }
+    else if (msg.includes('Authentication failed') || msg.includes('401') || msg.includes('403')) {
+        console.error('Error: Authentication failed. Please check your AK/SK credentials:');
+        console.error('  lts-cli config --list');
+    }
+    else if (msg.includes('ENOTFOUND') || msg.includes('ECONNREFUSED')) {
+        console.error('Error: Cannot reach the LTS service. Please check your endpoint and network connection.');
+    }
+    else if (msg.includes('Request failed after retries')) {
+        console.error('Error: The service is temporarily unavailable. Please try again later.');
+    }
+    else {
+        console.error('Error:', msg);
+    }
+    process.exit(1);
+}

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/context.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContextCommand = createContextCommand;
+const commander_1 = require("commander");
+const client_1 = require("../../lts/client");
+const output_1 = require("../../output");
+const common_1 = require("./common");
+function createContextCommand() {
+    const cmd = new commander_1.Command('context');
+    cmd.description('View logs before/after a specific log entry (like "View Context" in the console)')
+        .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)')
+        .requiredOption('--line-num <lineNum>', 'line_num of the anchor log entry')
+        .requiredOption('--time <time>', 'Timestamp (ms) of the anchor log entry')
+        .option('--before <count>', 'Number of logs before the anchor', (v) => parseInt(v, 10), 20)
+        .option('--after <count>', 'Number of logs after the anchor', (v) => parseInt(v, 10), 20)
+        .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);
+        const params = {
+            groupId,
+            streamId,
+            lineNum: options.lineNum,
+            time: options.time,
+            before: options.before,
+            after: options.after,
+        };
+        try {
+            const result = await client.queryContext(params);
+            console.log((0, output_1.formatOutput)(result, format));
+        }
+        catch (error) {
+            (0, common_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}