@cvtoolman/huawei-lts-cli 2.0.0 → 2.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-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
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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）。
@@ -60,14 +61,15 @@ npm install -g @cvtoolman/huawei-lts-cli
 lts-cli init
 ```
 
-向导会依次询问 AK、SK、Project ID、Region，一次配好。同时会生成两个文件：
+向导会依次询问 AK、SK、Project ID、Region，一次配好，只写一个文件：
 
 | 文件 | 内容 | 谁读 |
 |---|---|---|
 | `~/.lts-cli/config.json` | 凭证、默认日志组/流、`traceField`（权限 0600） | 仅 CLI |
-| `~/.lts-cli/profile.md` | 业务词表：把「订单服务」映射到日志里的实际取值 | 仅 AI |
 
-**CLI 不读 `profile.md`，AI 不读 `config.json`。** 后者含明文 AK/SK，任何让 AI 读它的设计都是错的。
+**这个目录不要整个交给 AI**，里面是明文 AK/SK。要看配置用 `lts-cli config --list`（已脱敏），不需要打开文件。
+
+日志组有哪些、字段叫什么、值长什么样——这些事实全部靠 `lts-cli groups` / `streams` / `fields` 现查，仓库和配置里都不存第二份。
 
 拿到控制台日志搜索页的 URL 时，可以直接导入 region / groupId / streamId：
 
@@ -77,27 +79,34 @@ lts-cli init --from-url "<控制台URL>"
 
 ### 3. 安装 Skill（给 AI 工具用）
 
-skill 目录含 `SKILL.md` 和 2 个参考文档，整目录复制：
+用 [skills CLI](https://skills.sh) 一条命令装到对应工具的目录（支持 75+ 种 agent）：
 
 ```bash
-# 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/
-
-# Qoder：把 .claude/skills/ 换成 .qoder/skills/
-# 其他工具：换成对应目录（.cursor/skills/ 等）
+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
 ```
 
-Windows PowerShell：
+装完重启 AI 工具：skill 在会话启动时读进上下文，已经开着的会话不会热加载。日常用 `npx skills update` 更新、`npx skills remove` 卸载。
 
-```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\
+不想用 npx 也可以手动复制（任何工具都适用）：
+
+```bash
+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 目录>/
 ```
 
-### 4. 命令行直接使用（不依赖 AI）
+> `npx skills` 默认用软链指向一份 git clone，更新时一起同步。用 `--copy`（Windows 无软链权限时的退路）或插件方式安装时，升级会整目录替换——如果你在里面放了业务词表，先备份。
+
+### 4. 业务词表（可选）
+
+AI 不知道「订单服务」在你的日志里叫什么。两条路，都不需要配置文件：
+
+- **默认行为**：AI 用管道 SQL 实时枚举候选值（`* | SELECT appName, count(*) GROUP BY appName`），再问你挑哪一个。不落盘，也不会过期。
+- **想省这一步**：在 skill 的 `references/vocab.md` 里写映射。这个文件默认不存在，自己建；已被 `.gitignore` 排除，不会被误提交。
+
+### 5. 命令行直接使用（不依赖 AI）
 
 ```bash
 # 最近 2 小时最新 50 条
@@ -144,10 +153,10 @@ lts-cli query --last 1h -f json | jq '.logs[].content'
 --app <取值>              appName:"<取值>"，与 -q 用 AND 合并
 --content <关键词>        content:"<关键词>"，与 -q 用 AND 合并
 --request-id <id>         REQUEST_ID:"<id>"，按时间正序输出
--l, --limit <n>           每页条数（默认 100），--all 时即单页大小
+-l, --limit <n>           每页条数（默认 100，上限 5000），--all 时同时是总数上限
 -r, --reverse             最新优先
 -f, --format <fmt>        pretty（默认）/ table / json
---all                     沿游标读到末尾（上限 10000 条）
+--all                     沿游标读到末尾（默认上限 10000 条，显式 -l 则为 -l）
 ```
 
 `--app` / `--content` / `--request-id` 自动为值加双引号——含连字符的 UUID 不加引号会被分词导致匹配不到。
@@ -158,12 +167,21 @@ lts-cli query --last 1h -f json | jq '.logs[].content'
 lts-cli trace <id> [--field <name>] [--last 24h] [-l 200] [-f fmt]
 ```
 
-按时间正序拉出一条 ID 的完整链路。默认走全文检索（不依赖任何特定字段命名）；如果你的日志流有专用字段，配一次即可：
+按时间正序拉出一条 ID 的完整链路。字段选择顺序是 `--field` → `config.traceField` → 运行时读一次流的索引配置：把 `REQUEST_ID` / `trace_id` / `span_id` 这类 ID 字段和全文检索 `content` 一起 OR 上。结构化日志的 ID 住在 labels 里，全文索引只覆盖正文，所以不能只靠 `content`。零命中时 stderr 会列出试过哪些字段。
+
+```bash
+lts-cli trace <id> --field REQUEST_ID        # 临时指定
+lts-cli config --set traceField=REQUEST_ID   # 这条流长期如此才值得配
+```
+
+### `lts-cli context`
 
 ```bash
-lts-cli config --set traceField=REQUEST_ID
+lts-cli context --line-num <lineNum> [--time <毫秒>] [--before 20] [--after 20]
 ```
 
+`--time` 可省：`line_num` 本身就是纳秒时间戳，前 13 位即毫秒，CLI 自己推。
+
 ## 配置说明
 
 配置文件 `~/.lts-cli/config.json`（Windows 为 `%USERPROFILE%\.lts-cli\config.json`）：
@@ -177,7 +195,7 @@ lts-cli config --set traceField=REQUEST_ID
 | `endpoint` | 否 | 需包含 `https://` |
 | `groupId` | 否 | 默认日志组 ID |
 | `streamId` | 否 | 默认日志流 ID |
-| `traceField` | 否 | `trace` 默认匹配的字段名，缺省为 `content` |
+| `traceField` | 否 | `trace` 的匹配字段名；不配则自动从流索引里发现 ID 字段 |
 
 `lts-cli config --list` 会把 `ak` / `sk` 脱敏输出，避免凭证进入终端滚屏、shell 历史或 AI 上下文。
 
@@ -216,7 +234,19 @@ lts-cli config --set traceField=REQUEST_ID
 
 不在表里时用 `--set endpoint=https://...` 手动指定，或参考 [华为云 LTS 终端节点](https://support.huaweicloud.com/api-lts/lts_api_0011.html)。
 
-## 从 1.x 升级到 2.0
+## 升级说明
+
+### 从 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 修了三个会静默出错的问题，因此有破坏性变更：
 
@@ -243,9 +273,15 @@ npm test           # node:test，覆盖纯函数与游标推进
 npm run typecheck  # tsc --noEmit
 ```
 
-测试使用 Node 内置的 `node:test` + `tsx`，不引入额外测试依赖。跑测试需要 Node >= 20.6（`--import` 的要求）。
+测试使用 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)——里面写了这个仓库唯一不能被破坏的原则：**同一个事实只允许有一个来源**。
+
+## 参与
 
-架构约定见 [CONTEXT.md](CONTEXT.md) 与 [docs/adr/](docs/adr/)。
+- 报告问题：[issue 模板](https://github.com/jcxy/huawei-lts-cli/issues/new/choose)（请勿贴真实凭证、日志组 ID 或内部业务名）
+- 安全问题：[SECURITY.md](SECURITY.md)，走私密通道，不要开公开 issue
+- 版本变更：[CHANGELOG.md](CHANGELOG.md)
 
 ## License
 

package/dist/cli/commands/common.js

@@ -8,6 +8,7 @@ exports.resolveFormat = resolveFormat;
 exports.warnIfIncomplete = warnIfIncomplete;
 exports.handleCommandError = handleCommandError;
 const config_1 = require("../../config");
+const client_1 = require("../../lts/client");
 /** 加载配置并校验凭证，缺失时打印引导并退出 */
 function loadCheckedConfig() {
     const config = (0, config_1.loadConfig)();
@@ -39,7 +40,14 @@ function resolveGroupStream(options, config) {
     }
     return { groupId, streamId };
 }
-/** 解析时间选项：--last 与 --st/--et 互斥，至少提供一组 */
+/**
+ * 解析时间选项：`--last` 与 `--st/--et` 互斥，至少提供一组。
+ *
+ * 返回值一律是绝对区间（ISO 8601）。相对时长必须在这里就换算掉、只算一次：
+ * 若把 `last` 传下去，每翻一页都会重算一次 `Date.now()`，窗口随时间往前滑，
+ * 游标（line_num）一旦滑出 [start, end]，服务端直接报
+ * “line_num must be between them”，`--all` 会中途失败。
+ */
 function resolveTimeParams(options, defaultLast) {
     const startTime = options.startTime || options.st;
     const endTime = options.endTime || options.et;
@@ -52,7 +60,18 @@ function resolveTimeParams(options, defaultLast) {
         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 };
+    let range;
+    try {
+        range = (0, client_1.resolveTimeRange)(last ? { last } : { startTime, endTime });
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    return {
+        startTime: new Date(range.startMs).toISOString(),
+        endTime: new Date(range.endMs).toISOString(),
+    };
 }
 /** 将 -q 表达式与便捷筛选 flag 合并为一个查询表达式（AND 连接）
  *  字段值统一加双引号：含连字符等分词符的值（如 UUID）不加引号会匹配不到 */

package/dist/cli/commands/config.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskSecret = maskSecret;
+exports.displayValue = displayValue;
+exports.parseAssignment = parseAssignment;
 exports.createConfigCommand = createConfigCommand;
 const commander_1 = require("commander");
 const config_1 = require("../../config");
@@ -10,6 +13,17 @@ function maskSecret(value) {
         return '****';
     return `${value.slice(0, 2)}${'*'.repeat(Math.max(4, value.length - 4))}${value.slice(-2)}`;
 }
+/** 输出任何配置值时都经过这里：密钥只看得到首尾，其余原样。 */
+function displayValue(key, value) {
+    return SECRET_KEYS.has(key) ? maskSecret(value) : value;
+}
+/** 拆 `key=value`。值里可能含 `=`（base64 密钥、URL 参数），只切第一个等号。 */
+function parseAssignment(input) {
+    const eq = input.indexOf('=');
+    if (eq <= 0)
+        return undefined;
+    return { key: input.slice(0, eq), value: input.slice(eq + 1) };
+}
 function createConfigCommand() {
     const cmd = new commander_1.Command('config');
     cmd.description('Manage LTS CLI configuration')
@@ -19,19 +33,19 @@ function createConfigCommand() {
         .option('--unset <key>', 'Remove a configuration value')
         .action((options) => {
         if (options.set) {
-            const parts = options.set.split('=');
-            if (parts.length !== 2) {
+            const assignment = parseAssignment(options.set);
+            if (!assignment) {
                 console.error('Usage: config --set key=value');
                 process.exit(1);
             }
-            const [key, value] = parts;
+            const { key, value } = assignment;
             (0, config_1.setConfig)(key, value);
-            console.log(`Set ${key}=${value}`);
+            console.log(`Set ${key}=${displayValue(key, value)}`);
         }
         else if (options.get) {
             const value = (0, config_1.getConfig)(options.get);
             if (value !== undefined) {
-                console.log(SECRET_KEYS.has(options.get) ? maskSecret(value) : value);
+                console.log(displayValue(options.get, value));
             }
             else {
                 console.error(`Config key '${options.get}' not found`);
@@ -46,7 +60,7 @@ function createConfigCommand() {
             }
             else {
                 for (const [key, value] of entries) {
-                    console.log(`${key}=${SECRET_KEYS.has(key) ? maskSecret(value) : value}`);
+                    console.log(`${key}=${displayValue(key, value)}`);
                 }
             }
         }

package/dist/cli/commands/context.js

@@ -11,7 +11,7 @@ function createContextCommand() {
         .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('--time <time>', 'Timestamp (ms) of the anchor log entry (derived from --line-num when omitted)')
         .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')
@@ -19,12 +19,19 @@ function createContextCommand() {
         const config = (0, common_1.loadCheckedConfig)();
         const { groupId, streamId } = (0, common_1.resolveGroupStream)(options, config);
         const format = (0, common_1.resolveFormat)(options.format);
+        // line_num 本身就是纳秒时间戳，前 13 位即目标日志的毫秒时间。
+        // 让用户再抄一遍 --time 是纯粹的重复劳动，还会抄错。
+        const time = options.time ?? (0, client_1.anchorTimeFromLineNum)(options.lineNum);
+        if (!time) {
+            console.error(`Cannot derive the anchor time from line_num '${options.lineNum}'. Pass --time <ms>.`);
+            process.exit(1);
+        }
         const client = new client_1.LTSClient(config);
         const params = {
             groupId,
             streamId,
             lineNum: options.lineNum,
-            time: options.time,
+            time,
             before: options.before,
             after: options.after,
         };

package/dist/cli/commands/init.js

@@ -35,24 +35,28 @@ 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 profile_1 = require("../../config/profile");
+const store_1 = require("../../config/store");
 function ask(rl, question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => resolve(answer.trim()));
     });
 }
-/** 写 profile.md 骨架并告知路径。已存在则绝不覆盖——那是用户手写的内容。 */
-function reportProfileSkeleton() {
-    const { path, created } = (0, profile_1.writeProfileSkeleton)();
-    if (created) {
-        console.log(`  profile.md = ${path} (skeleton created)`);
-        console.log('              业务词表：把「订单服务」这类称呼映射到日志里的实际取值');
-    }
-    else {
-        console.log(`  profile.md = ${path} (existing, left untouched)`);
+/**
+ * 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',
@@ -156,7 +160,7 @@ function createInitCommand() {
             }
             console.log('');
             console.log('✅ Configuration saved!');
-            reportProfileSkeleton();
+            reportLegacyProfile();
             console.log('');
             console.log('Try it out:');
             if (groupId && streamId) {
@@ -219,7 +223,7 @@ function importFromConsoleUrl(raw) {
     }
     console.log('');
     console.log('✅ Configuration saved!');
-    reportProfileSkeleton();
+    reportLegacyProfile();
     console.log('');
     console.log('Next steps:');
     console.log('  1. Configure credentials if not done yet: lts-cli init');

package/dist/cli/commands/query.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLimitOption = parseLimitOption;
 exports.createQueryCommand = createQueryCommand;
 const commander_1 = require("commander");
 const client_1 = require("../../lts/client");
@@ -10,6 +11,17 @@ const common_1 = require("./common");
 function parseIntOption(value) {
     return parseInt(value, 10);
 }
+/** --all 读不到末尾时的止损上限 */
+const ALL_CAP = 10000;
+/** 超限的 limit 本地就拦下：服务端会回一个 LTS.1903，还要多一次往返 */
+function parseLimitOption(value) {
+    const limit = parseIntOption(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > pagination_1.MAX_PAGE_SIZE) {
+        // 用 commander 的 InvalidArgumentError：它会打印一行提示，而不是整个堆栈
+        throw new commander_1.InvalidArgumentError(`--limit must be between 1 and ${pagination_1.MAX_PAGE_SIZE}`);
+    }
+    return limit;
+}
 function createQueryCommand() {
     const cmd = new commander_1.Command('query');
     cmd.description('Query LTS logs')
@@ -28,10 +40,10 @@ function createQueryCommand() {
         .option('--app <appName>', 'Filter by appName field, merged with -q via AND')
         .option('--content <keyword>', 'Filter by log content (content:<keyword>), merged with -q via AND')
         .option('--request-id <id>', 'Filter by REQUEST_ID field; output in chronological order')
-        .option('-l, --limit <limit>', 'Page size (also the cap for --all)', parseIntOption, 100)
+        .option('-l, --limit <limit>', `Page size; with --all it also caps the total (max ${pagination_1.MAX_PAGE_SIZE})`, parseLimitOption, 100)
         .option('-r, --reverse', 'Reverse order (newest first)')
         .option('-f, --format <format>', 'Output format: json, table, pretty', 'pretty')
-        .option('--all', 'Follow the cursor to the end (up to 10000 logs; default is a single page)')
+        .option('--all', `Follow the cursor to the end (up to ${ALL_CAP} logs unless -l is given)`)
         .action(async (options) => {
         const config = (0, common_1.loadCheckedConfig)();
         const { groupId, streamId } = (0, common_1.resolveGroupStream)(options, config);
@@ -57,9 +69,11 @@ function createQueryCommand() {
                 console.log((0, output_1.formatOutput)(result, format));
             }
             else {
-                // --all：沿游标读到末尾，上限 10000 条防止失控
+                // --all：沿游标读到末尾。显式给了 -l 就以它为上限（帮助里就是这么写的），
+                // 否则用 ALL_CAP 防止失控。
+                const max = cmd.getOptionValueSource('limit') === 'cli' ? options.limit : ALL_CAP;
                 const result = await (0, pagination_1.fetchAllPages)((p) => client.queryLogs(p), params, {
-                    max: 10000,
+                    max,
                     pageSize: options.limit,
                 });
                 (0, common_1.warnIfIncomplete)(result);

package/dist/cli/commands/trace.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceCandidateFields = traceCandidateFields;
+exports.buildTraceExpression = buildTraceExpression;
 exports.createTraceCommand = createTraceCommand;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
@@ -12,20 +14,39 @@ const output_1 = require("../../output");
 const config_1 = require("../../config");
 const common_1 = require("./common");
 /**
- * 默认按全文索引检索，而不是 REQUEST_ID。
+ * 默认字段的选择顺序：`--field` → `config.traceField` → 运行时发现。
  *
- * 理由：`REQUEST_ID` 是某类应用的字段命名约定，不是 LTS 的通用概念。新用户的日志流
- * 里往往没有这个字段，写死它会让 `trace` 在正确的用法下返回空。全文检索总能命中，
- * 而用到专用字段的人可以在 config 里设一次 `traceField`。
+ * 以前第三步写死 `content`（全文检索）。实测不对：结构化日志的 ID 住在 labels 里
+ * （REQUEST_ID / trace_id …），而全文索引只覆盖正文，`content:"<uuid>"` 一条都
+ * 匹配不到——而且不报错，只是空结果。所以第三步改成读索引配置，把形如
+ * request/trace/span + id 的字段都 OR 上，再由 full-text 兜底。
  */
 const DEFAULT_TRACE_FIELD = 'content';
+/** 字段名能凭空进查询语句（不能含连字符，否则会被当成运算符） */
+const SAFE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const ID_FIELD_PATTERN = /(request|trace|span)[_-]?id$/i;
+/** 从索引配置里挑出可能装链路 ID 的字段名（运行时发现，不维护字段表） */
+function traceCandidateFields(index) {
+    const idFields = index.fields
+        .map((f) => f.name)
+        .filter((name) => SAFE_FIELD_NAME.test(name) && ID_FIELD_PATTERN.test(name));
+    // 全文索引用在两种情况下：有 ID 字段时做兜底，没有 ID 字段时是唯一手段
+    if (idFields.length === 0 || index.fullText.enabled) {
+        return [...idFields, DEFAULT_TRACE_FIELD];
+    }
+    return idFields;
+}
+/** 候选字段拼成 OR 表达式，值统一加双引号（含连字符的 UUID 不分词就匹配不到） */
+function buildTraceExpression(fields, requestId) {
+    return fields.map((field) => `${field}:"${requestId}"`).join(' OR ');
+}
 function createTraceCommand() {
     const cmd = new commander_1.Command('trace');
     cmd.description('Trace a request by ID — fetch the full request chain in chronological order')
         .argument('<requestId>', 'Value to trace (request ID, trace ID, or any search text)')
         .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('--field <name>', `Field to match. Defaults to config.traceField, then "${DEFAULT_TRACE_FIELD}"`)
+        .option('--field <name>', 'Field to match. Defaults to config.traceField, then the ID fields found in the stream index')
         .option('--last <duration>', 'Relative time range: 30m, 2h, 1d, 7d (default: 24h)')
         .option('--start-time <startTime>', 'Start time (ISO 8601)')
         .option('--end-time <endTime>', 'End time (ISO 8601)')
@@ -38,20 +59,23 @@ function createTraceCommand() {
         const { groupId, streamId } = (0, common_1.resolveGroupStream)(options, config);
         const timeParams = (0, common_1.resolveTimeParams)(options, '24h');
         const format = (0, common_1.resolveFormat)(options.format);
-        const field = options.field || (0, config_1.getConfig)('traceField') || DEFAULT_TRACE_FIELD;
-        // 值加双引号：含连字符的 UUID 不加引号会被分词导致匹配不到
-        const query = `${field}:"${requestId}"`;
+        const explicitField = options.field || (0, config_1.getConfig)('traceField');
         const client = new client_1.LTSClient(config);
+        // 链路按时间正序，且不加应用过滤：一条链路本来就会横跨多个应用
         const params = {
             groupId,
             streamId,
             ...timeParams,
-            query,
-            reverse: false, // 链路按时间正序
+            reverse: false,
         };
         try {
+            const fields = explicitField
+                ? [explicitField]
+                : await discoverTraceFields(client, groupId, streamId);
+            params.query = buildTraceExpression(fields, requestId);
             const maxTotal = options.limit || 200;
-            // 每页不超过 500：再大 LTS 会开始截断，且首屏延迟明显变差
+            // 每页 500 条：服务端单页最多 5000，但 500 的首屏延迟明显更好，
+            // 而一条链路本来就只有几十条，多跑几页也不痛不痒
             const pageSize = Math.min(maxTotal, 500);
             const result = await (0, pagination_1.fetchAllPages)((p) => client.queryLogs(p), params, {
                 max: maxTotal,
@@ -61,6 +85,10 @@ function createTraceCommand() {
             if (result.truncated) {
                 console.error(`Warning: stopped at --limit ${maxTotal}; the chain may continue. Re-run with a larger --limit.`);
             }
+            if (result.logs.length === 0) {
+                console.error(`No logs matched "${requestId}" in ${fields.join(', ')}. ` +
+                    'Widen --last, or pick the exact field with --field <name>.');
+            }
             let output = (0, output_1.formatOutput)({ logs: result.logs, total: result.total }, format);
             // pretty 格式下高亮 requestId，便于肉眼定位
             if (format === 'pretty' && result.logs.length > 0) {
@@ -74,3 +102,15 @@ function createTraceCommand() {
     });
     return cmd;
 }
+/**
+ * 读一次索引配置来决定搜哪些字段。读不到（权限/接口异常）时退回全文检索：
+ * 宁可退化成以前的行为，也不要让 trace 直接报错。
+ */
+async function discoverTraceFields(client, groupId, streamId) {
+    try {
+        return traceCandidateFields(await client.getStreamIndex(groupId, streamId));
+    }
+    catch {
+        return [DEFAULT_TRACE_FIELD];
+    }
+}