@kriston-ai/kst-im-cli 0.0.8

package/README-workbuddy-install.md

@@ -0,0 +1,48 @@
+# kst-im-cli WorkBuddy 自动安装说明
+
+## 给 WorkBuddy Agent 的任务
+
+当前目录包含 `kriston-ai-kst-im-cli-<version>.tgz`（或可直接从 npm 安装）。请自动完成以下操作，不要停留在解释说明：
+
+1. 安装 CLI（优先 npm，或本地 tgz）：
+
+   ```bash
+   npm install -g @kriston-ai/kst-im-cli
+   ```
+
+   若使用本地 tgz：
+
+   ```bash
+   npm install -g ./kriston-ai-kst-im-cli-<version>.tgz
+   ```
+
+2. 将包内置的 `kst-im-cli` skill 安装到 WorkBuddy：
+
+   ```bash
+   kst-im-cli skill install-workbuddy
+   ```
+
+3. 安装完成后，确认以下文件存在：
+
+   ```text
+   ~/.workbuddy/skills/kst-im-cli/SKILL.md
+   ```
+
+如果 WorkBuddy 的 skill 目录不是 `~/.workbuddy/skills/kst-im-cli`，请使用实际目录执行：
+
+```bash
+kst-im-cli skill install-workbuddy --target <WorkBuddy的kst-im-cli skill目录>
+```
+
+## 预期结果
+
+安装成功后，WorkBuddy 应能读取 `kst-im-cli` skill，并按 `SKILL.md` 中的说明调用 `kst-im-cli` 查询 KST IM 数据。
+
+## 手动验证
+
+```bash
+kst-im-cli --version
+kst-im-cli skill install-workbuddy --help
+```
+
+`install-workbuddy` 是非交互命令，适合 agent 自动执行；不要使用 `kst-im-cli skill install`，该命令会进入交互式多选。

package/README.md

@@ -0,0 +1,109 @@
+# kst-im-cli
+
+快商通 IM 命令行工具，用于管理渠道账号、网页站点、查询统计看板和历史会话。
+
+## 安装
+
+```bash
+npm install -g @kriston-ai/kst-im-cli
+```
+
+需要 Node.js >= 18。
+
+## 快速开始
+
+```bash
+# 登录
+kst-im-cli auth login -k <API_KEY>
+
+# 查看登录状态
+kst-im-cli auth status
+
+# 渠道账号
+kst-im-cli channel type list
+kst-im-cli channel account list --channelKey weixin
+
+# 网页站点
+kst-im-cli site list
+kst-im-cli site get --siteId 118501
+
+# 统计看板
+kst-im-cli stats init
+kst-im-cli stats basic-board channel --period today --accounts 101,102
+kst-im-cli stats basic-board web --period today --sites 118501,118503
+
+# 历史会话
+kst-im-cli history schema
+kst-im-cli history web --start "2026-06-01 00:00:00" --end "2026-06-03 23:59:59"
+kst-im-cli history channel --start "2026-06-01 00:00:00" --end "2026-06-03 23:59:59"
+```
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `auth login -k <key>` | 登录认证 |
+| `auth logout` | 登出 |
+| `auth status` | 查看登录状态 |
+| `config get <key>` | 获取配置项 |
+| `config set <key> <value>` | 设置配置项 |
+| `channel type list` | 列出渠道类型 |
+| `channel type get --key <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` | 渠道基础看板 |
+| `stats basic-board web` | 网页站点看板 |
+| `history schema` | 历史记录字段说明 |
+| `history web --start <time> --end <time>` | 查询网页历史会话 |
+| `history channel --start <time> --end <time>` | 查询渠道历史会话 |
+
+## 输出格式
+
+所有命令支持 `--format` 选项：
+
+- `json` — JSON 信封（默认）：`{ ok: true, data: ..., meta: { count: N } }`
+- `table` — 表格
+- `pretty` — 格式化 JSON
+
+## 统计看板用法
+
+### 时间范围
+
+`--period` 快捷值：`today`、`yesterday`、`week`、`last-week`
+
+也可用自定义时间：`--start "yyyy-MM-dd HH:mm:ss" --end "yyyy-MM-dd HH:mm:ss"`
+
+两者互斥。
+
+### 筛选对象
+
+- `--accounts <ids>`：渠道账号 ID（逗号分隔，来源 `channel account list`）
+- `--sites <ids>`：站点 ID（逗号分隔，来源 `site list`）
+
+省略则查询全部对象的指标汇总。
+
+## 历史会话用法
+
+查询前建议先执行 `history schema` 了解返回字段含义。
+
+```bash
+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
+```
+
+- `--page-size` 最大 1000，大范围查询请分页
+- 时间格式固定为 `yyyy-MM-dd HH:mm:ss`
+
+## 配置
+
+配置文件位于 `~/.config/.kst-im-cli/config.json`，可通过环境变量 `KST_IM_CLI_CONFIG_DIR` 覆盖路径。
+
+## License
+
+ISC