crmdesk/modules/cli/readme.zh.md

CLI

微语通用 CLI 基础模块。

当前阶段能力：

• 不引入额外 CLI 框架，使用仓库现有 Java 体系实现命令行入口
• 同时支持文本输出和 JSON 输出，便于 agent 调用
• 提供本地配置、token 存储能力
• 已接入 auth、org、knowledge、ticket 四组真实 API 命令
• 预留 thread、message 命令组
• 运行入口类使用 com.bytedesk.cli.CliApplication

配置文件：

• 本地配置路径：~/.bytedesk/config.properties
• 当前常用键：
  • server.base-url
  • auth.token
  • auth.platform
  • auth.channel
  • auth.current-org-uid
  • auth.current-org-name
  • auth.current-user-uid
  • auth.current-user-nickname

构建与测试：

./starter/mvnw -f pom.xml -pl modules/cli -am -DskipTests compile
./starter/mvnw -f pom.xml -pl modules/cli -am -Dtest=BytedeskCliTests -Dsurefire.failIfNoSpecifiedTests=false test

运行方式：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar help
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar --version
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar --format=json version

当前命令说明：

• help：查看命令列表
• version：查看 CLI 版本
• config：查看或修改本地配置
• auth：登录、查看当前登录信息、退出登录
• org：列出组织、查看当前组织、切换组织、按 uid 查看组织
• knowledge：语义/混合检索知识库
• ticket：查询、查看、创建、关闭工单
• thread、message：当前仍为占位命令组

推荐使用流程：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth login \
  --server http://127.0.0.1:9003 \
  --username admin@email.com \
  --password your-password

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth whoami
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org list
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org switch --org your-org-uid
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar knowledge search --query "退款流程" --kb your-kb-uid --search-type MIXED --topk 5
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar ticket list --page 0 --size 10

认证命令：

• 用户名密码登录：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth login \
  --server http://127.0.0.1:9003 \
  --username admin@email.com \
  --password your-password \
  --platform BYTEDESK \
  --channel WEB

• access token 登录：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth login \
  --server http://127.0.0.1:9003 \
  --access-token your-access-token

• 登录时支持验证码参数：

  • --captcha-uid <uid>
  • --captcha-code <code>

• 查看当前登录用户：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth whoami

• 退出登录并清理本地 token：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth logout

组织命令：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org list
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org current
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org switch --org your-org-uid
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar org get --uid your-org-uid

工单命令：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar ticket list --page 0 --size 20 --status OPEN
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar ticket get --uid your-ticket-uid
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar ticket create \
  --title "支付回调失败" \
  --description "生产环境回调接口返回 500" \
  --priority HIGH \
  --type BUG
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar ticket close --uid your-ticket-uid --reason resolved

知识库命令：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar knowledge search \
  --query "退款流程" \
  --kb your-kb-uid \
  --search-type MIXED \
  --source-type FAQ \
  --topk 5

说明：

• 如果未显式传 --org，CLI 会优先读取本地缓存的 auth.current-org-uid
• 必须至少传 --kb 或 --robot 其中之一
• --format=json 适合脚本和 agent 工作流

工单创建补充说明：

• ticket create 依赖当前登录用户身份
• 请先执行 auth login 或 auth whoami，让 CLI 缓存 auth.current-user-uid 与 auth.current-user-nickname
• 如未缓存当前用户身份，CLI 会直接提示错误，而不是发送不完整请求

配置命令：

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar config list
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar config get server.base-url
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar config set server.base-url http://127.0.0.1:9003
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar config remove auth.token

JSON 输出：

• 如果给 agent、脚本或自动化流程使用，请将 --format=json 放在命令名前面

java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar --format=json auth whoami
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar --format=json knowledge search --query "退款流程" --kb your-kb-uid
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar --format=json ticket list --page 0 --size 5

当前限制：

• thread、message 还只是占位实现
• 当前 HTTP 调用默认依赖微语服务端标准返回结构：code、message、data
• 本地联调通常需要服务端先启动，常见地址是 http://127.0.0.1:9003

后续可在此基础上继续接入更多 REST API、MCP 适配层和自动化工作流。