176 lines
5.6 KiB
Markdown
176 lines
5.6 KiB
Markdown
# 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`
|
||
|
||
构建与测试：
|
||
|
||
```bash
|
||
./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
|
||
```
|
||
|
||
运行方式：
|
||
|
||
```bash
|
||
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`：当前仍为占位命令组
|
||
|
||
推荐使用流程：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
认证命令：
|
||
|
||
- 用户名密码登录：
|
||
|
||
```bash
|
||
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 登录：
|
||
|
||
```bash
|
||
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>`
|
||
|
||
- 查看当前登录用户：
|
||
|
||
```bash
|
||
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth whoami
|
||
```
|
||
|
||
- 退出登录并清理本地 token：
|
||
|
||
```bash
|
||
java -jar modules/cli/target/bytedesk-module-cli-1.9.0.jar auth logout
|
||
```
|
||
|
||
组织命令：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
工单命令：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
知识库命令：
|
||
|
||
```bash
|
||
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 会直接提示错误，而不是发送不完整请求
|
||
|
||
配置命令：
|
||
|
||
```bash
|
||
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` 放在命令名前面
|
||
|
||
```bash
|
||
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 适配层和自动化工作流。
|