beautx-cli

医美行业 MCP 网关 CLI 工具。通过 MCP 协议调用 beautx-mcp-bff 提供的业务数据查询工具。

快速开始

安装

# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install

构建

pnpm build

构建输出在 dist/ 目录，可执行文件为 dist/cli.mjs。

开发模式

# 直接运行源码
pnpm dev -- <command>

# 例如：查看帮助
pnpm dev -- --help

# 例如：列出项目
pnpm dev -- project list

命令列表

配置管理

# 查看当前环境变量配置
beautx-cli config list

项目管理

# 列出所有项目
beautx-cli project list [--keyword <关键词>]

# 查看当前激活项目
beautx-cli project current

# 切换当前项目
beautx-cli project use --project-id <项目ID>

Skill 中心

Skill 中心命令走 REST，并使用 Host 注入的沙箱双凭证鉴权。

# 按 personal / tenant / project 分组列出当前项目可见的 Skill
beautx-cli skill list [--type <personal|tenant|project>] [--project-id <项目ID>]

# 按数字 ID 下载安装包；默认项目取当前激活项目
beautx-cli skill install <Skill ID> [--project-id <项目ID>] [--dir <安装目录>]

# 上传包含 SKILL.md 的 zip；默认新建 personal Skill
beautx-cli skill upload <zip路径> [--type <personal|tenant|project>] \
  [--project-id <项目ID>] [--skill-id <已有Skill ID>] [--tags <JSON数组>]

• list 省略 --type 时按归属分组；返回的雪花 ID 始终按字符串处理。
• install 默认写入 SKILL_INSTALL_DIR，未设置时写入 /home/wuying/jvscrew/.wangai-cli/skills，并校验 SHA-256 checksum。
• upload 内部一次完成申请上传、对象存储 PUT 和服务端确认；type=project 时必须传 --project-id。
• 三个子命令均支持 --format toon|json|yaml。

顾问管理

# 列出顾问
beautx-cli consultant list [--page <页码>] [--size <每页条数>]

客户管理

# 列出客户
beautx-cli customer list [选项]
  --user-id <顾问ID>          # 过滤特定顾问的客户
  --user-name <顾问名>        # 顾问姓名模糊搜索
  --customer-name <客户名>    # 客户姓名模糊搜索
  --customer-phone <手机号>   # 客户手机号模糊搜索
  --portrait <画像关键词>     # 画像关键词模糊搜索
  --from <开始时间>           # 最后来访时间下限（yyyy-MM-dd HH:mm:ss）
  --to <结束时间>             # 最后来访时间上限（yyyy-MM-dd HH:mm:ss）
  --page <页码>               # 页码，从 1 开始
  --size <每页条数>           # 每页条数

来访管理

# 列出来访记录
beautx-cli visit list [选项]
  --customer-id <客户ID>      # wang_id
  --customer-name <客户名>    # 客户姓名模糊搜索
  --from <开始时间>           # 来访时间下限（yyyy-MM-dd HH:mm:ss）
  --to <结束时间>             # 来访时间上限（yyyy-MM-dd HH:mm:ss）
  --page <页码>
  --size <每页条数>

# 查询来访总结
beautx-cli visit summary [选项]
  --wang-id <客户ID>          # 客户 ID
  --visit-id <来访ID>         # 来访 ID（传了则 from/to 可省略）
  --question <问题>           # 模板问题精确匹配
  --from <开始时间>           # 起始来访时间（未传 visit_id 时必填）
  --to <结束时间>             # 结束来访时间（未传 visit_id 时必填）
  --page <页码>
  --size <每页条数>

客户标签

# 列出客户关注点
beautx-cli focus list [选项]
  --visit-ids <来访ID列表>    # 多个 ID 用逗号分隔
  --audio-ids <录音ID列表>    # 多个 ID 用逗号分隔
  --wang-id <客户ID>          # 单值精确匹配
  --category <一级分类>       # 一级分类模糊搜索
  --classification <二级分类> # 二级分类模糊搜索
  --from <开始时间>           # 来访时间下限
  --to <结束时间>             # 来访时间上限
  --page <页码>
  --size <每页条数>

# 列出客户抗性点
beautx-cli resistance list [选项]
  # 参数同 focus list

医美专项分析

# 查询接诊评价
beautx-cli visit-evaluate [选项]

# 查询变美计划
beautx-cli beauty-plan [选项]

# 查询成交/未成交分析
beautx-cli deal-analysis [选项]

# 查询来访画像标签
beautx-cli portrait-tags [选项]
  --dimension-name <维度名>   # 画像维度名称模糊搜索
  --speech-name <标签值>      # 画像标签值名称模糊搜索

# 通用过滤参数
  --visit-id <来访ID>
  --visit-ids <来访ID列表>
  --wang-id <客户ID>
  --wang-ids <客户ID列表>
  --beautx-customer-id <ID>
  --beautx-customer-ids <IDs>
  --from <开始时间>
  --to <结束时间>
  --page <页码>
  --size <每页条数>

录音管理

# 列出录音
beautx-cli audio list [选项]
  --user-id-list <顾问ID列表> # 多个 ID 用逗号分隔
  --from <开始时间>
  --to <结束时间>
  --page <页码>
  --size <每页条数>

# 查看录音转写文本
beautx-cli audio text --audio-id <录音ID>

# 录音分析
beautx-cli audio analyze --audio-id <录音ID>

注意：医美业务暂未采集录音，这些命令可能返回空数据。

自然语言查询

# SQL Agent 自然语言查询（耗时较长）
beautx-cli qa <自然语言问题>

知识库

# 搜索知识库
beautx-cli kb search <查询关键词> [选项]
  --k <返回条数>              # 默认 5，最大 20
  --chunk-types <类型列表>    # chunk 类型过滤
  --doc-ids <文档ID列表>      # 限定文档
  --enable-rerank             # 启用重排
  --rerank-threshold <阈值>   # 重排阈值

# 列出知识库文档
beautx-cli kb doc list [--title <标题关键字>]

# 获取文档元数据
beautx-cli kb doc get --doc-id <文档ID>

# 获取文档全文
beautx-cli kb doc content --doc-id <文档ID> [--offset <偏移>] [--limit <字符数>]

字段配置

# 查询客户字段配置（解读 dynamic_tags 标签含义）
beautx-cli config fields [--page <页码>] [--size <每页条数>]

通用 API 调用

# 直接调用 MCP 工具（高级用法）
beautx-cli api --tool-name <工具名> --arguments <JSON参数>

环境变量

CLI 通过环境变量获取身份（由 QCA / Host 沙箱注入）。当前项目与 MCP AT 不再依赖 ESTATE_ID / REFRESH_TOKEN：

| 变量名 | 说明 | | --- | --- | | ENV | test / prod | | TENANT_ID / USER_ID | 租户、用户 | | SANDBOX_TENANT_SECRET / SANDBOX_USER_SECRET | 沙箱双 secret，用于 Token Broker 与 Skill 中心 REST 鉴权 | | XB_APP_ID | 应用 ID（aike 时禁止 project use） | | SESSION_ID | 可选；有则 MCP 请求带 X-MCP-Session-Id | | SKILL_BFF_URL | 可选；覆盖当前环境内置的 Skill BFF 地址 | | SKILL_INSTALL_DIR | 可选；覆盖 skill install 的安装根目录 |

• MCP AT：每次调用向 {callbackBaseUrl}/api/qca-wangclaw/out/v2/mcp-token 借用（进程内缓存）。
• 当前项目：GET/PUT /api/qca-wangclaw/out/v2/current-project（project current / project use）。
• config list 脱敏展示；config doctor 只检查存在性。

ESTATE_ID / ESTATE_NAME 仍可能出现在 Host 历史 env 里，但 不是 当前项目的权威来源。

架构

beautx-cli  →  MCP Gateway  →  beautx-mcp-bff  →  wangai-mcp-application (beautx 端点)
           ↘  Skill BFF REST (`/api/wc-skill/out/**`)

• beautx-cli：TypeScript CLI 工具，发送 JSON-RPC 请求
• MCP Gateway：统一网关，负责鉴权和路由
• beautx-mcp-bff：医美 BFF 服务，参数转换和工具路由
• wangai-mcp-application：业务层，调用 Doris / 内部 RPC / LangGraph

开发

项目结构

src/
├── cli.ts                 # 主入口
├── commands/              # 命令实现
│   ├── project/           # 项目管理
│   ├── consultant/        # 顾问管理
│   ├── customer/          # 客户管理
│   ├── visit/             # 来访管理
│   ├── focus/             # 关注点
│   ├── resistance/        # 抗性点
│   ├── audio/             # 录音管理
│   ├── kb/                # 知识库
│   ├── skill/             # Skill 中心
│   ├── config/            # 配置查看
│   ├── qa.ts              # SQL Agent
│   └── api.ts             # 通用 API 调用
├── core/                  # 核心功能
│   ├── mcp-client.ts      # MCP JSON-RPC 客户端
│   ├── endpoints.ts       # 环境配置（test/prod URL）
│   ├── config.ts          # 配置解析
│   ├── env-vars.ts        # 环境变量读取
│   └── ...
└── output/                # 输出格式化

添加新命令

1. 在 src/commands/ 下创建命令文件
2. 使用 defineCommand 定义命令和参数
3. 调用 mcpCall() 发送 MCP 请求
4. 在 src/cli.ts 的 subCommands 中注册

测试

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

字段命名说明

CLI 面向医美业务，命令文案统一使用“项目 / 顾问 / 客户”等医美通用表达。

ESTATE_ID、ESTATE_NAME 是 Host 历史环境变量名；当前激活项目以 QCA /out/v2/current-project 为准。

相关文档

• beautx-mcp-bff — 医美 BFF 服务
• wangai-mcp-application — 业务应用层
• MCP 协议规范

许可证

内部项目，仅供旺小宝内部使用。