kst-scrm-cli

KST SCRM CLI 工具。

用户安装与使用（详细步骤）：（不随 npm 安装包发布，请从 GitLab 仓库或 Release 附件获取）。

安装(Agent完整提示词）

请帮我在本机完成 kst-scrm-cli（见鱼私域回访 CRM CLI）的安装与配置。

以下步骤面向 AI Agent 自动执行；部分步骤需要用户在对话中交互。请严格按 Step 0 → 6 顺序执行，每步用中文说明在做什么；遇安装弹窗或 UAC 请提示我点「是」。

## Agent 执行规则
- install / login / skill 须在「非沙盒 / 主机终端」完成；由你自行 where/version/auth 验收，通过后进入下一步。
- 禁止让我打开 CMD/PowerShell 做二次验收；禁止在沙盒 npm install -g。
- 禁止跳过 Step 0 沙盒卸载；未完成 Step 0-A 不得执行 Step 2。
- API Key 不得出现在聊天明文；优先对话掩码输入框 +【确认】。

## Prerequisites（前置条件，向用户确认，未齐则停止）
安装前确认本机已具备：
- Node.js 18+ 与 npm（Step 1 会检测；无则你代为安装 LTS）
- SCRM 账号三项（用中文逐项问我，未齐只提醒找管理员，不要继续安装）：
  1）能力包：企业/账号已开通 CLI / Open API 所需能力包
  2）API Key：已有 sk-scrm-…（没有则向 SCRM 管理员申请；不要让我把 Key 贴进聊天）
  3）角色权限：账号体系中已开通要查的菜单与数据范围
- 主机终端权限：全局安装须在非沙盒终端（本机 PowerShell 或 Agent「主机/信任终端」）；若仅能沙盒，用中文说明无法代装并给出本机命令清单，不要假称已全局装好

三项都确认「有」后进入 Step 0。

## Step 0：双环境卸载（沙盒 → 主机，必做；禁止跳过）

说明：WorkBuddy/Cursor 可能在沙盒单独装过 CLI；只卸主机不卸沙盒会导致假成功。顺序：0-A 当前对话终端（多为沙盒）→ 0-B 主机终端 → 再 Step 2。

Step 0-A — 在你当前正在执行命令的终端（沙盒）运行，并把完整输出贴到对话：

  where.exe kst-scrm-cli
  npm uninstall -g @kriston-ai/kst-scrm-cli
  where.exe kst-scrm-cli

要求：第 1 步无结果也必须执行 uninstall；第 3 步必须无任何 kst-scrm-cli 路径（仍有 .workbuddy\、.cursor\ 则重复 uninstall）。完成后回复：「Step 0-A 完成，沙盒 where 已无 CLI」。

Step 0-B — 切换到非沙盒 / 主机终端，同样执行上述三条命令，并回复：「Step 0-B 完成，主机 where：…」。

## Step 1：检查 Node.js（主机终端）

  node -v
  npm -v

若 Node 不存在或 < 18：Windows 优先 winget install OpenJS.NodeJS.LTS；Mac 优先 brew install node@20 或引导 https://nodejs.org/zh-cn 下载 LTS。装完若命令不可用，提示我重启 Agent/终端。

## Step 2：安装 CLI（仅主机终端；须 Step 0 已完成）

  npm install -g @kriston-ai/kst-scrm-cli
  where.exe kst-scrm-cli
  kst-scrm-cli --version
  npm prefix -g

通过：where 含 AppData\Roaming\npm 或 Program Files\nodejs，且不含 .workbuddy\、.cursor\。未通过则停止，勿在沙盒 install。私有源失败再问我是否有本地 .tgz。

## Step 3：安装 Agent Skill（必做；对话选平台，禁止终端交互多选）

  kst-scrm-cli skill install --list

在对话用中文表格列出 platforms（value、label），输出「Skill 平台选择」话术，让我回复 value（如 Trae 或 Trae,Cursor）。我回复前不要 install。我回复后在主机终端：

  kst-scrm-cli skill install --platform <我选的 value，逗号分隔>

用中文告知 installed 路径，并提醒我完全退出并重新打开当前 Agent。
重要：安装完成后，你必须严格执行 Skill 中定义的规则，不得偏离

## Step 4：登录（优先对话输入框）

再次确认 Prerequisites 中 API Key 已具备。不要让我在聊天粘贴 Key，不要写出 sk-scrm- 明文。

Agent 动作：
1）完整输出 user-guide 中「给用户的操作说明（Agent 标准话术 · 对话输入框版）」并唤起 API Key 掩码输入框
2）我点【确认】前：不要执行 auth status 及后续步骤
3）我点【确认】后，在主机终端（Key 从安全通道读取，勿写入聊天）：

  $env:KST_SCRM_CLI_API_KEY = '<从输入框读取>'
  kst-scrm-cli auth login
  Remove-Item Env:KST_SCRM_CLI_API_KEY -ErrorAction SilentlyContinue

若无对话输入框：改用终端备选（引导 PowerShell、auth login、◆ 掩码框，我回复「已在终端登录完成」后再继续）。

## Step 5：验证（主机终端 Verify）

  kst-scrm-cli auth status
  kst-scrm-cli skill status --platform <Step 4 所选，Claude Code 用 Claude>

用中文汇总：node/npm 版本、npm prefix -g、where 路径、CLI 版本、登录状态（Key 打码）、Skill 是否正常。全部通过则告知我可用自然语言查 SCRM 数据。

## Step 6：版本检查（装好后执行；每次新对话首次查数前也要做）

  kst-scrm-cli --version
  npm view @kriston-ai/kst-scrm-cli version

包页：https://www.npmjs.com/package/@kriston-ai/kst-scrm-cli
若当前版 < 最新版：用中文告知并询问是否升级；我同意前不要 npm install -g。我同意后：先重复 Step 0-A/0-B，再在主机 npm install -g @kriston-ai/kst-scrm-cli 并 where 验收，再 skill install --platform <平台>，提醒我重启 Agent。我回复「暂不」则跳过升级。

更多命令：kst-scrm-cli commands --json

发版（开发者）

npm run release   # 构建 + 打包，生成 kst-scrm-cli-x.x.x.tgz

快速开始

登录

kst-scrm-cli auth login

查看状态

kst-scrm-cli auth status

管理配置

kst-scrm-cli config get apiBaseUrl kst-scrm-cli config set apiBaseUrl https://my-api.example.com

用户管理（示例）

kst-scrm-cli user list --format table kst-scrm-cli user get 1 --format json

执行流程

你在终端输入一行命令并回车后，Shell 会启动 Node，把可执行路径、脚本路径、子命令名、选项和参数放进 process.argv。程序从入口开始只做一件事：解析 argv → 找到对应子命令 → 执行其 action → 把结果写到标准输出/标准错误。

下面是从「命令行」到「输出」涉及的主要代码路径（典型成功路径；出错时由入口的 catch 把结构化错误写到 stderr）。

flowchart TD
  shell([Shell 启动 Node]) --> argv["process.argv 已含本次子命令与选项"]
  argv --> entry["src/index.ts 入口"]
  entry --> chk["checkForUpdates：可选 npm 更新提示"]
  entry --> fac["createFactory：Factory 懒加载 config / http"]
  entry --> reg["registerCommands：挂载 auth / config / user / completion / meta 等"]
  entry --> parse["program.parseAsync：Commander 解析 argv"]
  parse --> action["命中命令的 .action<br/>例：src/commands/user/list.ts"]
  action --> svc["可选：src/services/*.service.ts 业务与请求"]
  svc --> core["src/core：经 Factory 读 config、走 http 客户端"]
  action --> out["src/output：formatOutput → emit / 表格 / pretty"]
  svc --> out
  out --> stdout["stdout：业务数据 JSON 或表格等"]
  action --> log["f.logger：提示类信息写 stderr"]
  action --> err["抛出 ExitError 或其它异常"]
  svc --> err
  err --> catch["src/index.ts 的 parseAsync.catch"]
  catch --> emiterr["emitError：stderr 一行 JSON 错误信封"]
  emiterr --> stderr["stderr：错误与提示"]

命令列表

| 命令 | 说明 | |---|---| | commands --json | 导出完整命令树（含 --describe / response，供 Agent 扫描） | | skill install --list | 列出可安装平台（JSON，供 Agent 在对话中展示） | | skill install --platform Trae,Cursor | 非交互安装到指定平台 | | skill install | 终端交互多选（本机手动） | | stats init | 拉取并缓存统计维度/指标中文映射 | | stats basic-board | 基础看板（支持 --period / --accounts） | | auth login | 登录认证（Open API 需先登录换取 accessToken） | | auth logout | 登出 | | auth status | 查看登录状态 | | config get <key> | 获取配置项 | | config set <key> <value> | 设置配置项 | | home-page work-board data-bulletin | 数据简报（POST Open API） | | home-page work-board data-bulletin --describe | 查看数据简报出参字段（不发 HTTP） | | user list | 列出用户（示例） | | user get <id> | 获取用户详情（示例） |

Agent 快速上手

# 1. 扫描全部命令（推荐第一步）
kst-scrm-cli commands --json

# 2. 查看某命令出参语义（无需登录）
kst-scrm-cli home-page work-board data-bulletin --describe

# 3. 调用 Open API 前先登录
kst-scrm-cli auth login

# 4. 实际请求
kst-scrm-cli home-page work-board data-bulletin --beginDate 2026-05-26 --endDate 2026-05-26

输出格式

所有命令支持 --format 选项：

• json — JSON 信封（默认）
• table — 表格
• pretty — 格式化 JSON

配置文件

配置文件位于 ~/.config/.kst-scrm-cli/config.json，统计映射缓存为同目录下的 stats.json。可通过 KST_SCRM_CLI_CONFIG_DIR 环境变量修改配置目录。

单条配置示例（仅保留一份 API Key）：

{
  "key": "sk-scrm-xxxxxxxx",
  "env": "PRD",
  "accessToken": "at_...",
  "refreshToken": "rt_...",
}

kst-scrm-cli auth login -k <你的 API Key>
kst-scrm-cli auth status         # 可查看 env 与 token 剩余有效期

开发

npm run build # esbuild 打包 npm run typecheck # TypeScript 类型检查 npm test # 运行测试 npm run dev # 开发模式（tsx 直接运行）