@ktvme/km-bot

安装

# 全局安装（推荐）
npm install -g @ktvme/km-bot

# 或通过 npx 直接运行
npx @ktvme/km-bot <command>

安装后建议执行 PATH 配置：

km-bot install

该命令会自动将 ~/.local/bin 加入 Shell 配置文件（.zshrc / .bashrc / config.fish）。

快速开始

# 1. 登录认证（打开浏览器完成 OAuth）
km-bot auth login

# 2. 查看认证状态
km-bot auth status

# 3. 调用业务服务
km-bot call member info '{"user_id":"123456"}'

# 4. 列出模块可用的工具
km-bot list member

命令详解

auth — 认证管理

登录、登出、状态查看，基于 OAuth 2.0 授权码流程，认证完成后会话持久化在 ~/.km/users/session.json。

# 登录（打开浏览器）
km-bot auth login

# 指定商家 / 办事处过滤
km-bot auth login --company-codes "00141,00533"
km-bot auth login --officeid 1

# 退出登录
km-bot auth logout

# 查看认证状态（默认使用 workbuddy 品类）
km-bot auth status

# 指定品类查询登录状态
km-bot auth status --category saasktv

auth status 输出示例：

✅ 已登录
   手机号        : 15005002870
   平台会员ID    : 54471408
   当前门店      : NEO · AI自助KTV (01171) [ID: 1265]
   ----------------授权管理门店列表----------------
   品牌超管 品牌ID：57
   ✅ [01171] NEO · AI自助KTV
      [01281] 厦研测试商家213
      [01337] 01015-N13系列

会话状态说明：

| 输出 | 含义 | | ------------ | --------------------------------- | | ✅ 已登录 | token 有效，已登录且已选择门店 | | 未登录 | 无本地会话记录或会话已失效 |

workbuddy — IDE 集成认证

专为 WorkBuddy / 第三方 IDE 设计，不打开浏览器，由 IDE 负责打开。

# 输出认证 URL，IDE 读取后打开浏览器，完成后自动保存会话
km-bot workbuddy auth

# 携带商家 / 办事处过滤
km-bot workbuddy auth --company-codes "00141" --officeid 1

行为约束：

• 仅输出一行完整的 https:// 认证 URL（前后空白分隔，无引号）
• 不调用系统浏览器，由 IDE 负责打开
• 启动本地回调服务器等待授权完成
• 非交互模式，适合无 TTY 环境

call — 调用业务模块

通过 JSON-RPC 协议调用任意注册的业务模块工具。

km-bot call <category> <method> [args]

| 参数 | 说明 | | ------------ | ----------------------------------------------- | | <category> | 模块名，如 member、coupon、account | | <method> | 工具方法名，如 info、gradelist、send-code | | [args] | JSON 请求参数，默认 {} |

示例：

# 查询会员信息
km-bot call member info '{"user_id":"123456"}'

# 查询等级列表
km-bot call member gradelist

# 指定账号调用
km-bot call coupon detail '{"coupon_id":"abc"}' --account openid@wechat

list — 列出模块工具

km-bot list <category>

# 示例
km-bot list member      # 列出 member 模块所有可用工具
km-bot list coupon      # 列出 coupon 模块所有可用工具

config — 配置管理

管理 MCP 服务端点配置和认证域名配置。

MCP 配置

# 查看所有 MCP 配置
km-bot config mcp get

# 获取指定 category 配置
km-bot config mcp get '{"category":"saasktv"}'

# 清除指定 category 配置（回退到环境默认）
km-bot config mcp del '{"category":"saasktv"}'

# 从文件重新加载所有 MCP 配置
km-bot config mcp reload

Auth 配置

# 查看当前 auth 配置
km-bot config auth get

# 设置 auth 域名
km-bot config auth set '{"authDomain":"https://www-test.ktvme.com","apiDomain":"https://mcp-test.ktvme.com"}'

# 删除 auth 配置（回退到环境默认）
km-bot config auth del

# 从文件重新加载 auth 配置
km-bot config auth reload

注意：config auth 和 config mcp 操作完全独立，互不影响。

账号格式

调用业务服务时可使用 --account 指定账号，支持以下格式：

| 平台 | 格式 | 示例 | | ----------- | ---------------- | ---------------- | | K米 / KMBot | user_id@km | 12345@km | | 微信 | openid@wechat | oXXXX@wechat | | 飞书 | user_id@feishu | ou_xxx@feishu | | 企微 | account@wecom | zhangsan@wecom |

不指定时自动从本地会话 p_uid / pt 解析。

运行时目录

~/.km/
├── config/
│   └── config.json      # 运行配置（MCP 端点 + auth 域名）
├── users/
│   └── session.json     # 认证会话（token + p_uid + 过期时间）
└── logs/                # 运行日志

config.json 结构

{
  "mcpConfig": {
    "saasktv": { "url": "https://mcp.ktvme.com/mcp/client/call", "type": 1 },
    "data": { "url": "https://mcp.ktvme.com/mcp/tools/call", "type": 1 }
  },
  "authConfig": {
    "authDomain": "https://www.ktvme.com",
    "apiDomain": "https://mcp.ktvme.com"
  },
  "expireAt": "2026-10-01T00:00:00.000Z"
}

session.json 结构

{
  "pt": "kmbot",
  "p_uid": "9c70fe3812e20a56713fd90a97d552b7",
  "token": "1789717495:...",
  "tokenExpiresAt": "2026-09-18T09:44:55.000Z",
  "refreshToken": "1789717495:...",
  "refreshTokenExpiresAt": "2026-09-25T09:44:55.000Z",
  "savedAt": "2026-09-18T08:00:00.000Z"
}

环境变量

| 变量 | 说明 | 默认值 | 可选值 | | -------------------- | ---------------------------- | --------- | -------------------------------------- | | KM_ENV | 运行环境 | prod | dev / test / prod | | KM_MCP_API_URL | MCP API 地址（覆盖环境默认） | 按 KM_ENV | — | | KM_AUTH_URL_DOMAIN | 认证页面域名（覆盖环境默认） | 按 KM_ENV | — | | KM_ACCOUNT | 默认业务账号 | — | xxx@km / xxx@wechat / xxx@feishu | | KM_LOG_LEVEL | 日志级别 | 按 KM_ENV | debug / info / warn |

环境默认值：

| KM_ENV | authDomain | apiDomain | | ------ | ---------------------------- | ---------------------------- | | dev | http://www.dev.ktvme.com | http://mcp.dev.ktvme.com | | test | https://www-test.ktvme.com | https://mcp-test.ktvme.com | | prod | https://www.ktvme.com | https://mcp.ktvme.com |

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev -- auth status

# 构建
npm run build -- --env=test

# 类型检查
npm run check

# Lint
npm run lint

# 本地链接测试
npm run link:test     # 构建 test 版本并 npm link
km-bot auth login     # 测试命令
npm run unlink        # 取消链接

# 单元测试
npm test

脚本速查

| 命令 | 说明 | | ----------------------- | ------------------- | | npm run dev | 开发运行（tsx） | | npm run build | 生产构建（esbuild） | | npm run check | TypeScript 类型检查 | | npm run lint | ESLint 检查 | | npm run lint:fix | ESLint 自动修复 | | npm run clean | 清理 dist 目录 | | npm run rebuild | clean + build | | npm run link:dev | 开发环境 link | | npm run link:test | 测试环境 link | | npm run link:prod | 生产环境 link | | npm run unlink | 取消 npm link | | npm run pack | 打包 tgz | | npm run publish:patch | 发版（修订号 +1） | | npm test | 运行测试 |

目录结构

src/
├── api/                   # API 请求层
│   ├── configCall.ts      # config 命令处理
│   └── rpcCall.ts         # call / list 命令处理（JSON-RPC）
├── auth/
│   └── account.ts         # 账号解析、会话类型定义
├── cache/
│   ├── config.ts          # config.json 读写
│   └── session.ts         # session.json 读写
├── client/
│   ├── protocol.ts        # JSON-RPC 2.0 协议类型
│   └── transport.ts       # HTTP JSON-RPC 传输层
├── commands/
│   ├── auth.ts            # auth / workbuddy 命令组
│   ├── call.ts            # call / list / config 命令组
│   └── install-cli.ts     # install / install-cli 一键安装
├── constants/
│   ├── const.ts           # 环境配置、退出码
│   └── version.ts         # 版本号获取
├── detectors/             # 运行环境检测
├── types/
│   └── index.ts           # 全局类型定义
├── utils/
│   ├── logger.ts          # 日志工具
│   ├── mcpUtils.ts        # MCP 响应格式化
│   └── install-logger.ts  # 安装日志
└── index.ts               # CLI 入口

许可

MIT