@qs_cli/polaris-cli 0.2.3 → 0.2.4

package/README.md

@@ -1,49 +1,185 @@
 # Polaris CLI
 
-观星台命令行查询工具，无需打开网页即可查询网络请求和用户账号信息。
+观星台命令行查询工具。用飞书登录后，可以在终端查询网络请求和 Dev/QA 用户资料，不必打开网页。
+
+`polaris` 和 `polaris_cli` 是同一个程序，下面的命令把 `polaris` 换成 `polaris_cli` 即可。
 
 ## 安装
 
-要求 Node.js 18 或更高版本。默认查询线上服务 `https://polaris.yfcenter.com`。
+需要 Node.js 18 或更高版本。
 
 ```bash
 npm install -g @qs_cli/polaris-cli
+polaris --version
+polaris doctor
 ```
 
-也可以在源码目录本地安装：
+卸载只删除命令，不删除本机配置和登录凭证：
 
 ```bash
-cd polaris_cli
-./install.sh
+npm uninstall -g @qs_cli/polaris-cli
 ```
 
-卸载：
+从源码安装时，在 `polaris_cli` 目录执行 `./install.sh`；对应的卸载命令是 `./uninstall.sh`。
+
+## 第一次使用
+
+新安装后默认查询线上服务 `https://polaris.yfcenter.com`。本地和线上的登录凭证分开保存。
 
 ```bash
-./uninstall.sh
+polaris env          # 查看当前环境
+polaris login        # 浏览器完成飞书登录，等待最多 5 分钟
+polaris whoami       # 确认姓名、邮箱、角色和凭证过期时间
 ```
 
-## 快速开始
+登录成功后，凭证写入 `~/.polaris/config.json`，文件权限为 `0600`。可以用 `POLARIS_CONFIG=/其他路径` 换配置文件。
+
+`polaris logout` 只删除当前环境的本地凭证，不会影响另一个环境。凭证过期后重新执行 `polaris login`。
+
+## 全局参数
+
+这些参数对后面的查询命令都有效：
+
+| 参数 | 作用 |
+| --- | --- |
+| `--service-env <local\|online>` | 只对这一次命令切换环境，不改配置文件 |
+| `--base <url>` | 只对这一次命令指定服务地址，覆盖环境地址 |
+| `--json` | 以 JSON 输出，适合脚本处理 |
+| `-V, --version` | 显示版本 |
+| `-h, --help` | 显示帮助 |
 
 ```bash
-polaris env local              # 切换到本地服务
-polaris env online             # 切换到线上服务
-polaris login                  # 浏览器飞书授权
+polaris --json whoami
+polaris --service-env local net list --uid 24842
+polaris --base https://polaris.yfcenter.com net get 100
+```
+
+直接执行 `polaris` 或 `polaris help` 会显示总帮助。`polaris <命令> --help` 显示该命令的参数。
+
+## 环境
+
+| 环境 | 地址 | 用途 |
+| --- | --- | --- |
+| `online` | `https://polaris.yfcenter.com` | 默认环境，查询线上观星台 |
+| `local` | `http://127.0.0.1:8080` | 查询本机后端 |
+
+```bash
+polaris env                 # 查看当前环境、地址和配置文件
+polaris env online          # 切换并保存为线上
+polaris env local           # 切换并保存为本地
+polaris env use online      # 与 polaris env online 相同
+```
+
+已经保存过环境的配置文件会继续使用保存的值。只有没有配置文件，或者配置里没有合法环境时，才使用默认的 `online`。
+
+## 登录和诊断
+
+```bash
+polaris login
 polaris whoami
+polaris whoami --json
+polaris logout
 polaris doctor
-
-polaris net list --uid 123 --from '2026-11-10 00:00:00'
-polaris net get 100 --curl
-polaris user 123 --env qa
+polaris doctor --json
 ```
 
-执行 `polaris help` 或 `polaris <command> --help` 查看完整参数和示例。
+`whoami` 显示当前环境中的姓名、邮箱、角色和凭证过期时间。角色从低到高是 `viewer`、`developer`、`admin`。
+
+`doctor` 检查 CLI 版本、Node.js、配置文件、本地和线上连通性、当前环境的登录凭证，以及用户查询环境是否可用。用户查询环境不可用通常表示还没登录，或者角色低于 `developer`。
 
-配置和不同环境的登录凭证保存在 `~/.polaris/config.json`，文件权限为 `0600`。
+登录或查询返回 `401` 时先执行 `polaris login`。返回 `403` 表示当前账号权限不足。
 
-`polaris` 与 `polaris_cli` 是完全等价的命令入口，例如：
+## 查询网络请求
+
+网络请求列表和详情需要已登录。列表不返回请求头、请求体、响应头和响应体，这些内容用 `net get` 查看。
+
+### 列表
 
 ```bash
 polaris net list
-polaris_cli net list
+polaris net list --uid 24842
+polaris net list --uid 24842 --page 2 --size 50
+polaris net list --method POST --status 500
+polaris net list --success false
+polaris net list --biz-code nonzero --min-duration 1000
+polaris net list --host api-qa.yfcenter.com --keyword financial_calendar
+polaris net list --from 2026-11-10T00:00:00+08:00 --to 2026-11-11T00:00:00+08:00
+polaris net list --uid 24842 --json
 ```
+
+| 参数 | 说明 |
+| --- | --- |
+| `--id <number>` | 按记录 ID 精确查询 |
+| `--uid <string>` | 按用户 UID 查询 |
+| `--device <string>` | 按设备 ID 查询 |
+| `--method <method>` | HTTP 方法，会转成大写 |
+| `--host <string>` | 请求 Host |
+| `--keyword <string>` | 匹配 URL 的关键词 |
+| `--status <number>` | HTTP 状态码 |
+| `--success <true\|false>` | 客户端记录的请求是否成功 |
+| `--biz-code <number\|nonzero>` | 精确业务码；`nonzero` 表示业务码不为 0 |
+| `--min-duration <ms>` | 耗时大于等于该毫秒数 |
+| `--app-id <string>` | App ID，例如 `youfi` |
+| `--app-version <string>` | App 版本 |
+| `--from <time>` | 开始时间 |
+| `--to <time>` | 结束时间 |
+| `--page <number>` | 页码，从 1 开始，默认 1 |
+| `--size <number>` | 每页条数，默认 20，最大 200 |
+
+`--from` 和 `--to` 传给服务端时只接受两种格式：RFC3339，例如 `2026-11-10T00:00:00+08:00`；或者毫秒时间戳。其他写法会被忽略，时间条件不会生效。
+
+多个条件同时使用时是“并且”关系。表格按列宽截断长路径，完整 URL 在详情里。
+
+### 详情
+
+```bash
+polaris net get 1593
+polaris net get 1593 --curl
+polaris net get 1593 --resp-headers
+polaris net get 1593 --all --max-lines 200
+polaris net get 1593 --json
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `--curl` | 根据记录生成可执行的 curl |
+| `--resp-headers` | 额外显示响应头 |
+| `--all` | 同时显示响应头和 curl |
+| `--max-lines <number>` | 响应体最多显示的行数，默认 80，最大 100000 |
+
+详情包含方法、URL、状态码、耗时、业务码、设备与应用信息、Query、请求头和请求体。响应体默认折叠到 80 行。客户端上报时单个 body 大约只保留前 16KB，超长内容末尾会带 `truncated` 标记，因此详情不一定是服务端的完整响应。
+
+## 查询用户资料
+
+用户查询走 Dev 或 QA 的用户中心，不是观星台自己的用户表。调用账号至少要有 `developer` 角色。
+
+每次只能使用一种条件：UID、邮箱或手机号。
+
+```bash
+polaris user 24842
+polaris user 24842 --env qa
+polaris user --uid 1051993 --env dev
+polaris user --email user@example.com --reveal
+polaris user --mobile 13600000000 --nation-code 86 --env qa
+polaris user envs
+polaris user 24842 --json
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `[uid]` 或 `--uid <uid>` | 按正整数 UID 查询 |
+| `--env <dev\|qa>` | 用户中心环境，默认 `qa` |
+| `--email <email>` | 按邮箱反查 |
+| `--mobile <mobile>` | 按手机号反查 |
+| `--nation-code <code>` | 手机号国家或地区码，只能和 `--mobile` 一起用 |
+| `--reveal` | 显示手机号和邮箱明文；不加时会脱敏 |
+
+`polaris user envs` 查看当前后端配置了哪些用户中心环境。查不到用户时返回 404。
+
+## 常见问题
+
+- 命令提示未登录或 `401`：对当前环境执行 `polaris login`。线上和本地要分别登录。
+- `403`：账号角色不够。网络请求需要登录，用户查询需要 `developer` 或 `admin`。
+- 时间筛选没有效果：改用 RFC3339 或毫秒时间戳。
+- 详情里的响应体不完整：这是客户端上报时的长度限制，不是 CLI 再次截断。
+- 想临时查本地服务：`polaris --service-env local <命令>`。这不改变以后的默认环境。

package/dist/cli.js

@@ -6,7 +6,7 @@ import { registerEnvCommand } from './commands/env.js';
 import { registerNetCommand } from './commands/net.js';
 import { registerUserCommand } from './commands/user.js';
 import { configureHelp } from './help.js';
-const VERSION = '0.2.3';
+const VERSION = '0.2.4';
 const program = new Command();
 program
     .name('polaris')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qs_cli/polaris-cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "观星台命令行查询工具",
   "type": "module",
   "bin": {