如何使用RoboNeo CLI
Roboneo 命令行工具：与 AI Agent 对话、创建房间、发送消息、轮询结果、回复追问、上传附件、下载产物等。
环境要求
- Node.js >= 18
- npm
安装
全局安装后可在任意目录使用 roboneo：
npm install -g roboneo-cli
包名为 roboneo-cli，可执行命令为 roboneo。
本地开发可从仓库根目录执行 npm run build:pre 后使用 npm start 或 node bin/roboneo-cli.js。
配置
必需
访问令牌（与登录态一致）。优先级：环境变量 > credentials.json。
export ROBONEO_ACCESS_KEY="你的访问令牌"
也可以写入本地凭证文件（~/.roboneo/credentials.json）：
roboneo config access_token "<你的访问令牌>"
当环境变量与本地凭证文件都未配置时，依赖令牌的命令会报错。
全局选项
roboneo --help roboneo help
| 选项 | 说明 |
|---|---|
| -V, --version | 版本号 |
| -h, --help | 帮助 |
roboneo help 会输出内置的英文精简操作指引（不依赖 README 或 skill）。
命令一览
| 命令 | 说明 |
|---|---|
| config access_token <token> | 写入 access_token 到本地 credentials.json |
| config list | 查看当前 CLI 相关配置（如 access_token 脱敏展示） |
| user-info | 根据当前令牌拉取用户信息，JSON 输出到 stdout |
| create-room | 创建新房间；成功后会写入本地状态并输出 JSON |
| chat | 向房间发送消息后立刻返回；无房间时自动创建；支持 single 和 team 模式 |
| reply | 回复 AI 追问（request）或选择选项（option_request）后立刻返回 |
| history | 拉取房间历史列表，JSON 输出 |
| history-detail | 按房间 ID 拉取历史详情，支持增量拉取 |
| download | 将房间中生成的产物（图片/视频）下载到本地文件 |
使用说明
- 先用 chat 提交问题或任务
- 再用 history-detail 查看进展与结果
- 如果 next_action.action 为 recharge，展示 next_action.extra.recharge.content 并跳转 next_action.extra.recharge.url，充值后引导用户继续聊天（发起新一轮 chat）
- 如果 next_action.action 为 reply，使用 reply 继续
- 产物可直接从 artifacts 获取，并用 download 下载到本地
常用示例
查看配置（令牌脱敏）：
roboneo config list
确认令牌（可选）：
roboneo user-info
创建房间并对话：
roboneo create-room roboneo chat -p "Hello, introduce yourself."
直接对话（无房间时自动创建）：
roboneo chat -p "帮我生成奶茶海报"
创建 team 房间并对话：
roboneo create-room --mode team roboneo chat -p "帮我生成一张图片和一个视频" --mode team
指定房间对话：
roboneo chat -p "继续上次的话题" --room-id "<room_id>"
轮询任务结果：
# 全量拉取（自动识别 single/team 模式） roboneo history-detail -r "<room_id>" # 增量拉取（只返回 seq > N 的新消息） roboneo history-detail -r "<room_id>" --after-seq 3
回复 AI 追问（配合 history-detail 轮询使用）：
# 回复 request 类型 roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "回复内容" # 回复 request 类型并带附件 roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "用这张图" --image-file ./photo.png # 回复 option_request 类型（选择选项） roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "" --select-option-ids '[["opt_1"]]' # team 模式回复 roboneo reply -r "<room_id>" --mode team --task-id TASK_ID --sub-task-id SUB_TASK_ID --last-request-id BLOCK_xxx -p "回复内容"
下载产物：
# 下载房间所有产物到当前目录 roboneo download -r "<room_id>" # 指定输出目录 roboneo download -r "<room_id>" -o ./output
子命令详情
create-room
| 选项 | 说明 |
|---|---|
| --mode <mode> | single 或 team，默认 single |
chat
| 选项 | 必填 | 说明 |
|---|---|---|
| -p, --prompt <prompt> | ✅ | 发送的提示语 |
| --mode <mode> | single 或 team，默认 single | |
| --lang <lang> | 语言代码，默认 zh-Hans。支持：zh-Hans、zh-Hant、en、pt、ja、es、kor、vi、th、de | |
| --room-id <roomId> | 指定房间 ID；默认使用最近一次创建的房间；无房间时自动创建 | |
| --image-url <url...> | 图片 URL（jpg, jpeg, png）；最多 10 张，若同时传视频则最多 2 张 | |
| --image-file <path...> | 本地图片路径（jpg, jpeg, png）；单个不超过 20 MB；发送前会先上传 | |
| --video-url <url...> | 视频 URL（mp4, mov）；最多 1 个 | |
| --video-file <path...> | 本地视频路径（mp4, mov）；单个不超过 500 MB；发送前会先上传 | |
| --file-url <url...> | 文件 URL（xls, xlsx, doc, docx, txt, pdf, mp3, wav, csv, md）；最多 1 个 | |
| --file <path...> | 本地文件路径（xls, xlsx, doc, docx, txt, pdf, mp3, wav, csv, md）；文档不超过 10 MB，音频不超过 500 MB；发送前会先上传 |
reply
| 选项 | 必填 | 说明 |
|---|---|---|
| -r, --room-id <roomId> | ✅ | 房间 ID |
| --last-request-id <id> | ✅ | 上次请求 ID（BLOCK_xxx，来自 history-detail） |
| -p, --prompt <prompt> | ✅ | 回复内容（option_request 仅选择选项时可传空字符串） |
| --mode <mode> | single 或 team，默认 single | |
| --task-id <taskId> | 任务 ID（team 模式必填） | |
| --sub-task-id <subTaskId> | 子任务 ID（team 模式） | |
| --select-option-ids <json> | 选中的选项 ID，JSON 二维数组格式（如 '[["opt_1"]]' 或 '[["opt_1"],["opt_2"]]'） | |
| --lang <lang> | 语言代码，默认 zh-Hans | |
| --image-url <url...> | 图片 URL（jpg, jpeg, png） | |
| --image-file <path...> | 本地图片路径（jpg, jpeg, png） | |
| --video-url <url...> | 视频 URL（mp4, mov） | |
| --video-file <path...> | 本地视频路径（mp4, mov） | |
| --file-url <url...> | 文件 URL（xls, xlsx, doc, docx, txt, pdf, mp3, wav, csv, md） | |
| --file <path...> | 本地文件路径 |
history-detail
| 选项 | 必填 | 说明 |
|---|---|---|
| -r, --room-id <roomId> | ✅ | 房间 ID |
| --after-seq <n> | 只返回 seq > n 的消息（增量拉取） |
history-detail 常用字段：
- next_action：下一步该做什么
- poll：任务未完成，继续轮询
- recharge：命中充值引导，提示用户先充值（extra.recharge.url = WEB_URL + /home?modal=purchase，extra.recharge.content 展示文案）；充值后引导用户继续聊天（发起新一轮 chat）
- reply：需要用户回复追问/选择选项
- done：流程完成
- artifacts：生成产物列表
- items：对话与过程消息
- max_seq：用于下一次增量拉取（--after-seq）
recharge 返回示例：
{
"next_action": {
"action": "recharge",
"items": [{ "type": "guide_purchase", "content": "当前权益不足，开通会员即可继续使用" }],
"extra": {
"recharge": {
"url": "https://pre.roboneo.com/home?modal=purchase",
"content": "当前权益不足，开通会员即可继续使用"
}
}
}
}
extra.recharge.url 实际值随环境变化（由 WEB_URL 拼接）。
download
| 选项 | 必填 | 说明 |
|---|---|---|
| -r, --room-id <roomId> | ✅ | 要下载产物的房间 ID |
| -o, --output-dir <dir> | 输出目录，默认当前目录 |
附件规则
- 图片与视频可以组合使用，但最多支持 2 张图片 + 1 个视频
- 不带视频时，图片最多支持 10 张
- 文件最多支持 1 个
- 文件与图片/视频互斥
- 同一类型下可混用 URL 和本地路径
- URL 与本地路径都按扩展名判断类型
- 本地文件大小限制：图片 ≤ 20 MB，视频 ≤ 500 MB，音频 ≤ 500 MB，其他文件 ≤ 10 MB
附件示例：
roboneo chat -p "Analyze these images" \ --image-url https://example.com/a.jpg https://example.com/b.png
roboneo chat -p "Analyze these inputs" \ --image-url https://example.com/a.jpg \ --image-file ./local.png
roboneo chat -p "Analyze this video with two images" \ --video-file ./demo.mp4 \ --image-file ./a.png ./b.jpg
roboneo chat -p "Summarize this document" \ --file ./spec.pdf
推荐流程
- 设置 ROBONEO_ACCESS_KEY
- （可选）user-info 或 config list 确认令牌
- chat -p "你的问题" 进行对话（无房间时自动创建，也可手动 create-room）
- 使用 history-detail -r ROOM_ID 轮询查看结果
- 若 next_action 为 recharge，提示用户先充值；充值后引导用户继续聊天（发起新一轮 chat）
- 若 next_action 为 reply，使用 reply 回复追问或选择选项
- 对于 poll / reply 场景继续使用 history-detail 轮询直到 next_action 为 done
- 使用 download -r ROOM_ID -o ./output 将产物下载到本地
- 需要时使用 history / history-detail 查看历史记录
本地状态
create-room 或 chat（自动创建时）会在用户目录下保存房间等信息（默认路径：~/.roboneo/storage.json）。chat 默认使用最近一次创建的房间，无房间时自动创建；也可通过 --room-id 指定。