@kriston-ai/kst-im-cli 0.0.8

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kriston-ai/kst-im-cli",
+  "version": "0.0.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "KST IM CLI 工具",
+  "type": "module",
+  "bin": {
+    "kst-im-cli": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README-workbuddy-install.md"
+  ],
+  "scripts": {
+    "release": "npm run build && npm pack",
+    "build": "tsx scripts/build.ts",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src && prettier --check src",
+    "format": "prettier --write src && eslint --fix src",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@clack/prompts": "0.9.1",
+    "@types/node": "22.10.2",
+    "@types/update-notifier": "6.0.8",
+    "axios": "1.7.9",
+    "cli-table3": "0.6.5",
+    "commander": "12.1.0",
+    "dayjs": "^1.11.20",
+    "esbuild": "0.24.2",
+    "eslint": "10.3.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-simple-import-sort": "13.0.0",
+    "prettier": "3.8.3",
+    "tsx": "4.19.2",
+    "typescript": "5.7.2",
+    "typescript-eslint": "8.59.3",
+    "update-notifier": "7.3.1",
+    "vitest": "2.1.8"
+  }
+}

package/skills/kst-im-cli/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: kst-im-cli
+description: Use when invoking kst-im-cli commands as an agent for KST IM data queries, including authentication, JSON envelope parsing, intent routing (list vs stats basic-board), channel/site/stats command syntax, basic-board channel/web subcommands, history records, schema lookup, data dependency chain, and error recovery
+---
+
+# kst-im-cli
+
+## Quick Reference
+
+| 命令                                                                        | 说明                         |
+| --------------------------------------------------------------------------- | ---------------------------- |
+| `auth login -k <key>`                                               | 登录                               |
+| `auth logout`                                                       | 退出                               |
+| `auth status`                                                       | 查看登录状态                       |
+| `config get <key>`                                                  | 读取配置项                         |
+| `config set <key> <value>`                                          | 写入配置项                         |
+| `channel type list`                                                 | 列出所有渠道类型                   |
+| `channel type get --key <渠道标识>`                                 | 查询单个渠道类型                   |
+| `channel account list [--channelKey <keys>] [--keyword <text>]`     | 列出渠道账号                       |
+| `channel account get --accountId <id>`                              | 查询单个账号                       |
+| `site list [--with-codes]`                                          | 列出网页站点                       |
+| `site get --siteId <id> [--with-codes]`                             | 查询单个站点                       |
+| `stats init`                                                        | 刷新中文字段映射缓存               |
+| `stats basic-board channel (--period \| --start/--end) [--accounts <ids>]` | 查询渠道基础看板（默认子命令） |
+| `stats basic-board web (--period \| --start/--end) [--sites <ids>]`        | 查询网页站点看板               |
+| `history schema`                                                    | 输出历史记录字段说明               |
+| `history web --start <time> --end <time> [--site-ids <ids>]`        | 查询网页站点历史会话               |
+| `history channel --start <time> --end <time> [--account-ids <ids>]` | 查询渠道账号历史会话               |
+
+所有命令支持 `-f/--format json|table|pretty`，默认 `json`；agent 模式始终用默认值。
+
+---
+
+## Overview
+
+`kst-im-cli` 是快商通 IM 数据查询 CLI。agent 使用时需先完成认证，所有命令默认输出 JSON 信封，stdout/stderr 分工严格。
+
+agent 查询历史记录前必须先调用 `history schema` 理解字段含义；不要依赖 schema 未声明的旧接口字段。
+
+---
+
+## 意图路由（优先遵守）
+
+用户问「有哪些 / 列表 / 几个」时，**一律用 `* list` 枚举**，不要用 `stats basic-board` 代替。
+
+| 用户问法 | 正确命令 | 禁止替代 |
+| -------- | -------- | -------- |
+| 有哪些渠道账号 / 渠道账号列表 | `channel account list` | ✗ `stats basic-board channel` |
+| 有哪些站点 / 网页站点列表 / 几个站点 | `site list` | ✗ `stats basic-board web` |
+| 有哪些渠道类型 | `channel type list` | — |
+| 站点今天/本周数据、对话数、开口率等指标 | `stats basic-board web` | 需 siteId 时先 `site list` |
+| 渠道账号今天/本周数据、对话数等指标 | `stats basic-board channel` | 需 accountId 时先 `channel account list` |
+
+`stats basic-board` 省略 `--accounts` / `--sites` 表示查**全部对象的统计指标**（须指定时间范围），**不是**枚举清单。看板结果虽含账号名/站点名，但缺少完整元数据（如 siteId、code），不能当作 list 使用。
+
+---
+
+## 认证（前置必须）
+
+```bash
+kst-im-cli auth login -k <API_KEY>
+```
+
+必须用 `-k` 传入 key，CLI 无法在非交互环境下提示输入。
+
+成功后 stdout：`{ "ok": true, "data": "已验证 compId=<N> customerId=<N>" }`
+
+```bash
+kst-im-cli auth status
+# stdout: { "ok": true, "data": { "key": "...", "compId": N, "customerId": N } }
+```
+
+---
+
+## 输出解析规则
+
+### 流分工
+
+| 流     | exit 0                           | exit 1                |
+| ------ | -------------------------------- | --------------------- |
+| stdout | JSON 信封（成功数据）            | **空**                |
+| stderr | 日志（`[info/warn/error]` 前缀） | 日志 + 失败 JSON 信封 |
+
+失败时：stdout 为空，stderr 输出失败 JSON 信封（`CliError` 类型）；未捕获的非 CliError 异常输出纯文本，无 JSON 信封。
+
+stderr 可能混入 npm 更新提示（非 JSON 行）。解析时按行过滤，只处理能 `JSON.parse` 的行。设置 `CI=true` 可完全抑制更新提示。
+
+### 成功 — stdout，exit 0
+
+```json
+{ "ok": true, "data": <payload>, "meta": { "count": N } }
+```
+
+`meta.count` 仅当 data 为数组时存在。`site list --with-codes` 额外有 `meta.codeCount`。
+
+### 失败 — stderr，exit 1
+
+```json
+{ "ok": false, "data": { "type": "...", "content": "..." } }
+```
+
+---
+
+## 命令参考
+
+### channel
+
+```bash
+# 列出所有渠道类型
+kst-im-cli channel type list
+# 提取: .data[].key（渠道标识）、.data[].name（渠道名称）
+
+# 查询单个渠道类型（--key 是渠道标识，不是 API Key）
+kst-im-cli channel type get --key <渠道标识>
+
+# 列出渠道账号
+kst-im-cli channel account list [--channelKey <keys>] [--keyword <text>]
+# --channelKey: 逗号分隔，来源 channel type list 的 .data[].key
+# 提取: .data[].accountId（账号 ID）、.data[].name（账号名称）
+
+# 查询单个账号
+kst-im-cli channel account get --accountId <id>
+```
+
+### site
+
+```bash
+# 列出网页站点
+kst-im-cli site list [--with-codes]
+# 提取: .data[].siteId、.data[].siteName
+# --with-codes 时还有 .data[].codes[]（含 codeId、codeName）
+
+# 查询单个站点（--siteId 来源 site list）
+kst-im-cli site get --siteId <id> [--with-codes]
+# --with-codes 时 meta.count 为 code 数量
+```
+
+### config
+
+```bash
+kst-im-cli config get <key>          # 读取配置项，输出 { key, value }
+kst-im-cli config set <key> <value>  # 写入配置项，输出 { key, value }
+```
+
+### stats init
+
+```bash
+kst-im-cli stats init
+```
+
+将服务端的 dimension/indicator 中文映射缓存到 `~/.config/.kst-im-cli/stats.json`。channel 与 web 看板共用此缓存。`stats.json` 已存在时不会自动刷新；若服务端更新了指标配置，需手动执行。
+
+### stats basic-board
+
+`basic-board` 拆为 **channel**（渠道账号维度，默认）和 **web**（网页站点维度）两个子命令。
+
+**向后兼容：** `stats basic-board --period today` 等价于 `stats basic-board channel --period today`。
+
+#### channel — 渠道基础看板
+
+```bash
+kst-im-cli stats basic-board channel \
+  (--period <period> | --start "yyyy-MM-dd HH:mm:ss" --end "yyyy-MM-dd HH:mm:ss") \
+  [--accounts <ids>]
+```
+
+#### web — 网页站点看板
+
+```bash
+kst-im-cli stats basic-board web \
+  (--period <period> | --start "yyyy-MM-dd HH:mm:ss" --end "yyyy-MM-dd HH:mm:ss") \
+  [--sites <ids>]
+```
+
+`--period` 时间范围（均为 00:00:00 ~ 23:59:59）：
+
+| 值          | 范围            |
+| ----------- | --------------- |
+| `today`     | 今天            |
+| `yesterday` | 昨天            |
+| `week`      | 本周一 ~ 今天   |
+| `last-week` | 上周一 ~ 上周日 |
+
+`--period` 与 `--start`/`--end` 互斥；`--start` 和 `--end` 必须同时指定。
+
+`--accounts`：逗号分隔，来源 `channel account list` 的 `.data[].accountId`；省略则查全部账号的**指标**（仅 channel，不是账号清单）。
+
+`--sites`：逗号分隔，来源 `site list` 的 `.data[].siteId`；省略则查全部站点的**指标**（仅 web，不是站点清单）。
+
+**输出**：
+
+```
+.data[]       ← resultlist 明细行（字段名为中文）
+.meta.count   ← 行数
+```
+
+**stats.json 依赖行为**：
+
+- **缺失**：自动调用 `stats init`（发网络请求）；init 失败则整个命令 exit 1
+- **存在但解析失败**：字段名退化为原始英文 key，stderr 输出 `[error]` + `[warn]`，命令仍成功（exit 0）
+
+### history schema
+
+```bash
+kst-im-cli history schema
+```
+
+返回历史记录字段说明，用于解释 `history web` 和 `history channel` 的 `.data[]`。查询历史记录前先调用一次。
+
+必须读取：
+
+- `.data.timeFormat`：时间格式，当前为 `yyyy-MM-dd HH:mm:ss`
+- `.data.fields[]`：字段路径、中英文名称、类型、可空性和解释
+- `.data.enums[]`：枚举或常见取值解释
+- `.data.notes[]`：脱敏、稳定字段边界等注意事项
+
+解释规则：
+
+- 只把 `.data.fields[].path` 中声明的字段当作稳定对外字段。
+- `dialogRecordList` 是当前会话内的聊天消息列表，不是会话列表。
+- `visitorInfo` 是访客维度信息。
+- `dialogInfo` 是会话维度信息。
+- `cardInfo.cardCusType` 是名片标签名称；映射缺失时可能是原始值。
+- 聊天内容、联系方式、来源 IP 等可能已脱敏，不要声称拿到了完整原文。
+
+### history web
+
+```bash
+kst-im-cli history web \
+  --start "yyyy-MM-dd HH:mm:ss" \
+  --end   "yyyy-MM-dd HH:mm:ss" \
+  [--site-ids <ids>] \
+  [--page <page>] \
+  [--page-size <size>]
+```
+
+按时间范围查询网页站点历史会话。`--site-ids` 为逗号分隔的站点 ID，来源 `site list` 的 `.data[].siteId`；省略时由服务端权限和默认查询逻辑决定范围。
+
+输出：
+
+```
+.data[]       ← 会话列表
+.meta.count   ← 当前页返回条数
+```
+
+每个会话对象可能包含：`contacted`、`visitorInfo`、`dialogInfo`、`dialogRecordList`、`adInfo`、`trackRecordList`、`cardInfo`。
+
+### history channel
+
+```bash
+kst-im-cli history channel \
+  --start "yyyy-MM-dd HH:mm:ss" \
+  --end   "yyyy-MM-dd HH:mm:ss" \
+  [--account-ids <ids>] \
+  [--page <page>] \
+  [--page-size <size>]
+```
+
+按时间范围查询渠道账号历史会话。`--account-ids` 为逗号分隔的渠道账号 ID，来源通常是 `channel account list` 的 `.data[].accountId`。
+
+渠道查询与网页查询共用历史记录结果结构。渠道专有信息优先看：
+
+- `visitorInfo.visitorNick`
+- `visitorInfo.sourceCity`
+- `visitorInfo.trafficType`
+- `visitorInfo.accountInfo`
+- `dialogInfo.dialogTag`
+
+### history 查询约束
+
+- `--start` 和 `--end` 必须同时指定。
+- 时间格式必须是 `yyyy-MM-dd HH:mm:ss`。
+- `--page` 和 `--page-size` 必须大于 0；默认分别为 `1` 和 `500`。
+- `--page-size` 不能大于 `500`；大范围查询应分页执行，不要一次请求过大页数。
+- 返回空数组表示当前条件下未查到会话，不等于 CLI 调用失败。
+- 若需要解释字段，重新调用 `history schema`，不要猜测字段含义。
+
+---
+
+## 数据依赖关系
+
+```
+channel type list → channel account list --channelKey
+channel account list → stats basic-board channel --accounts
+site list → stats basic-board web --sites
+site list → history web --site-ids
+stats init → channel / web 看板（中文字段映射，共用 stats.json）
+```
+
+---
+
+## 错误处理
+
+| type / 症状                | 原因                           | 处理                                      |
+| -------------------------- | ------------------------------ | ----------------------------------------- |
+| `auth`                     | 未登录或 token 失效            | `auth login -k <key>` 后重试              |
+| `validation`               | 参数错误                       | 修正参数后重试                            |
+| `network`                  | 网络不通                       | 检查网络连通性                            |
+| `api`                      | 服务端业务错误                 | 读 `.data.content` 查看服务端响应         |
+| `auth login` 挂起          | 未带 `-k`，进入交互模式        | 加 `-k <key>` 重试                        |
+| `basic-board` exit 1       | `stats.json` 缺失且 init 失败  | 先手动执行 `stats init`                   |
+| channel 看板 api 错误      | 未配置渠道基础看板             | 确认 OnlineRecord 看板配置                |
+| web 看板 api 错误          | 未配置网页基础看板             | 确认 OnlineRecord 网页看板配置            |
+| `站点不存在: {siteId}`     | siteId 无效                    | 重新执行 `site list` 获取有效 ID          |
+| `--key` 参数错误           | 传的是 API Key 而非渠道标识    | 传渠道标识（如 `weixin`）                 |
+| stderr 有非 JSON 行        | npm 更新提示                   | 设置 `CI=true` 抑制，或按行过滤           |
+| `basic-board` 字段名为英文 | `stats.json` 损坏              | 执行 `stats init` 刷新                    |
+| `history` 字段含义不清     | 未读取 schema                  | 先执行 `history schema`                   |
+| `history` 参数校验失败     | 时间格式、分页或必填项错误     | 按 `yyyy-MM-dd HH:mm:ss` 和正整数分页重试 |
+| `history` 返回空列表       | 条件下无数据或权限范围内无数据 | 缩小/调整时间、站点或账号条件后重试       |
+
+---
+
+## 禁止使用
+
+| 命令                    | 原因                                |
+| ----------------------- | ----------------------------------- |
+| `auth login`（无 `-k`） | 交互式，会挂起                      |
+| `skill install`         | 交互式，会挂起                      |
+| `completion`            | 生成 shell 补全脚本，agent 无需使用 |
+
+---
+
+## 典型工作流
+
+### 查询指定渠道的基础看板数据
+
+```bash
+# 1. 拿渠道 key
+kst-im-cli channel type list
+# → .data[].key 如 "weixin", "xiaohongshu"
+
+# 2. 拿 accountId
+kst-im-cli channel account list --channelKey weixin,xiaohongshu
+# → .data[].accountId 如 101, 102, 203
+
+# 3. 查看板（channel 为默认子命令，可省略子命令名）
+kst-im-cli stats basic-board channel --period today --accounts 101,102,203
+# → .data[] 明细行（字段名为中文）
+# → .meta.count 行数
+```
+
+### 查询指定站点的网页看板数据
+
+```bash
+# 1. 拿 siteId
+kst-im-cli site list
+# → .data[].siteId 如 "118501", "118503"
+
+# 2. 查网页看板
+kst-im-cli stats basic-board web --period today --sites 118501,118503
+# → .data[] 明细行（字段名为中文）
+# → .meta.count 行数
+```
+
+### 对比昨今数据（渠道）
+
+```bash
+kst-im-cli stats basic-board channel --period yesterday --accounts 101,102,203
+kst-im-cli stats basic-board channel --period today     --accounts 101,102,203
+# 对比两次 .data[] 中相同维度行的指标差值
+```
+
+### 对比昨今数据（网页站点）
+
+```bash
+kst-im-cli stats basic-board web --period yesterday --sites 118501,118503
+kst-im-cli stats basic-board web --period today     --sites 118501,118503
+# 对比两次 .data[] 中相同维度行的指标差值
+```
+
+### 自定义时间范围
+
+```bash
+kst-im-cli stats basic-board channel \
+  --start "2026-05-01 00:00:00" \
+  --end   "2026-05-27 23:59:59" \
+  --accounts 101,102
+
+kst-im-cli stats basic-board web \
+  --start "2026-05-01 00:00:00" \
+  --end   "2026-05-27 23:59:59" \
+  --sites 118501,118503
+```
+
+### 查询网页历史会话
+
+```bash
+# 1. 拿 siteId（过滤用）
+kst-im-cli site list
+# → .data[].siteId 如 "118501", "118504"
+
+# 2. 先拿字段说明
+kst-im-cli history schema
+
+# 3. 查询历史会话
+kst-im-cli history web \
+  --start "2026-06-01 00:00:00" \
+  --end   "2026-06-03 23:59:59" \
+  --site-ids 118501,118504 \
+  --page 1 \
+  --page-size 500
+
+# 4. 解释结果
+# .data[] 是会话列表
+# .data[].dialogRecordList 是当前会话内的聊天消息列表
+```
+
+### 查询渠道历史会话
+
+```bash
+# 1. 获取渠道账号 ID
+kst-im-cli channel account list --channelKey weixin
+
+# 2. 获取历史字段说明
+kst-im-cli history schema
+
+# 3. 查询渠道历史会话
+kst-im-cli history channel \
+  --start "2026-06-01 00:00:00" \
+  --end   "2026-06-03 23:59:59" \
+  --account-ids 101,102 \
+  --page 1 \
+  --page-size 500
+```