BORG RISE CLI

BORG RISE CLI 是面向 Hermes、OpenClaw、Claude Code 等 Agent 的 BORG RISE 连接器。它不是让终端用户学习复杂命令的开发者工具，而是让 Agent 能用同一个 BORG RISE 账号提交任务、查询状态、取回结果，并让正式结果进入当前账号资产库。

本实现按《BORG RISE CLI 产品需求文档（产品简版）》V2.1 的连接器方向生成，当前支持：

• 图片生成：文生图、参考图生成，多图结果全部返回。
• 视频生成：文生视频、图生视频、参考素材视频。
• 视频分析：分析已有视频并返回结构化结果。
• PPT 1.0：根据 Word、Excel、PDF、PPT/PPTX 附件，一键生成大纲、页面 JSON、页面图片和 PPTX 文件。
• 任务状态：已提交、生成中、已完成、生成失败、需要补充信息。
• 资产库一致性：调用使用同一账号、同一额度，结果由 content-app 保存。

安装与连接

网站 CLI/API 页面首屏推荐展示：

npx --yes @borgrise/cli@latest install

上面的命令要求 @borgrise/cli 已经发布到 npm。内测或本地验证时，先在 content-app 仓库根目录打包：

npm pack ./cli --pack-destination /tmp

然后用本地 tarball 运行：

npx --yes --package /tmp/borgrise-cli-0.3.0.tgz borgrise install

install 会同时安装/暴露说明文档索引，返回 documentation.docs、documentation.readOrder 和完整读取命令。Agent 安装后无需再单独安装文档。默认情况下，install 会调用授权码接口创建浏览器授权会话并返回 authFlow；如需跳过可传 --no-auth-flow。

推荐授权方式：

1. 运行 npx --yes @borgrise/cli@latest install。
2. 打开输出里的 authFlow.verificationUriComplete。
3. 如果浏览器已登录博观，点击“授权 Agent”；未登录则先登录/注册后回到授权页。
4. 授权码 1 小时 内有效；回到 Agent/终端运行输出里的 authFlow.pollCommand，CLI 会轮询授权结果并把 Token 写入 ~/.borgrise/config.json。

也可以手动创建和轮询授权会话：

npx --yes @borgrise/cli@latest auth device
npx --yes @borgrise/cli@latest auth poll --wait

CLI 会把官网授权返回的 Token、Refresh Token 和过期时间保存到本机配置文件，用于后续主动更新 Token：

~/.borgrise/config.json

Token 更新策略：

• content-app 默认 JWT 有效期为 360 分钟（6 小时），可通过后端环境变量 ACCESS_TOKEN_EXPIRE_MINUTES 覆盖。
• 浏览器授权会保存 refreshToken，CLI 默认优先调用 POST /api/cli/auth/refresh 换取新 Token。
• 如果请求返回 401、unauthorized、token expired 等认证错误，CLI 会自动刷新一次并重试原请求。
• 手动刷新可运行 npx --yes @borgrise/cli@latest auth refresh。
• P0 不支持在 Agent 或 CLI 中输入账号密码；账号密码只在 BORG RISE 官网输入。

环境变量方式：

export BORGRISE_TOKEN=<bearer_token>
export BORGRISE_REFRESH_TOKEN=<refresh_token>
export BORGRISE_BASE_URL=https://video.borgrise.com
export BORGRISE_TOKEN_REFRESH_BEFORE_SECONDS=600

只设置 BORGRISE_TOKEN 时不会自动刷新；同时设置 BORGRISE_REFRESH_TOKEN 时可主动刷新。

检查连接：

npx --yes @borgrise/cli@latest status

说明文档已合并到 install 输出；如需单独查看或复制完整 Markdown，可继续使用兼容命令：

npx --yes @borgrise/cli@latest install
npx --yes @borgrise/cli@latest docs
npx --yes @borgrise/cli@latest docs fields --raw

仿 Higgsfield 的 CLI 页面结构

CLI/API 页面建议采用“Agent 标签 + 一键复制 + 连接状态 + 快速示例”的结构，避免把用户带进开发者参数页。

推荐首屏：

• 标题：BORG RISE CLI for Claude Code，切换标签为 Claude Code、Hermes、OpenClaw。
• 主命令：npx --yes @borgrise/cli@latest install。
• 主按钮：复制安装指令；Agent 从 install 输出中的 copyToAgent、agentGuide、agentPrompt 获取完整初始化文案。
• 连接区：展示浏览器授权、脱敏 Token、连接状态、退出登录入口。
• 文档区：直接读取 install 输出中的 documentation，不要求用户再次运行 docs 才能看到说明。
• 快速示例：图片生成、视频生成、视频分析三张示例卡。
• 安全提示：账号密码只在官网输入，不要把完整 Token 发送到公开群聊或公开文档。

复制给 Claude Code 的最短版本：

请安装并连接 BORG RISE CLI：
1. 每次开始使用 BORG RISE 前，先运行 npx --yes @borgrise/cli@latest install
2. 始终使用 @latest，不要复用旧的全局安装版本
3. 从 install 输出的 documentation.readOrder 读取内置说明文档
4. 从 install 输出的 agentGuide 和 agentPrompt 获取调用规范
5. 如果 install 输出 authFlow，请提醒我授权码 1 小时内有效，让我打开 authFlow.verificationUriComplete 并点击授权 Agent
6. 授权后运行 authFlow.pollCommand
7. 如果浏览器授权不可用，请让我回到 BORG RISE 网站的 CLI/API 页面重新发起授权
8. 运行 npx --yes @borgrise/cli@latest status
之后我会直接用自然语言提出图片、视频、视频分析或 PPT 生成需求。

Agent 指南

install 已合并 agent guide 和 agent prompt。首次安装只需要运行：

npx --yes @borgrise/cli@latest install

install 输出 JSON 中包含：

• copyToAgent：可直接复制给 Agent 的完整初始化文案。
• agentGuide：原 agent guide 的结构化能力、参数、示例和行为规则。
• agentPrompt：原 agent prompt --agent claude-code 的提示词文本。
• documentation：说明文档索引、读取顺序和完整 Markdown 读取命令。

agent guide 和 agent prompt 子命令保留为兼容入口，但不再是首次安装必需步骤。Agent 应遵守：

• 先判断用户是在生图、生视频、分析视频还是生成 PPT。
• 只在缺少必要素材、数量、比例或时长时补问。
• 同一个用户请求只创建一次正式任务，后续只用 taskId 查询或恢复。
• 长任务提交后先反馈 taskId 和当前状态。
• 完成后返回全部结果，并说明结果已进入当前账号资产库。
• 文件回传失败但任务成功时，返回资产链接，不能把生成任务标记为失败。

命令示例

图片生成：

npx --yes @borgrise/cli@latest image generate "给雅诗兰黛小棕瓶生成 4 张 1:1 高端棚拍图" --wait

参考图生成：

npx --yes @borgrise/cli@latest image generate "用这张商品图生成 4 张高端棚拍海报" --ref https://example.com/product.png --count 4 --ratio 1:1 --wait
npx --yes @borgrise/cli@latest image generate "用这张商品图生成 4 张高端棚拍海报" --ref-file ./product.png --count 4 --ratio 1:1 --wait

图像编辑：

npx --yes @borgrise/cli@latest image edit "把背景换成高端棚拍场景，保留商品主体" --image-file ./product.png --count 2 --wait

多图融合：

npx --yes @borgrise/cli@latest image fusion "融合商品和夏季场景，生成电商海报" --image-file ./product.png --image-file ./scene.png --count 2 --wait

上传本地素材：

npx --yes @borgrise/cli@latest upload image --file ./product.png
npx --yes @borgrise/cli@latest upload video --file ./demo.mp4
npx --yes @borgrise/cli@latest upload file --file ./report.pdf

上传命令返回 url 后，可把该 URL 作为 --ref、--image-url 或 --video-url 参数。生成命令也支持直接传本地文件，CLI 会先上传到博观 TOS，再把上传后的 URL 放入请求体。

视频生成：

npx --yes @borgrise/cli@latest video text "生成一条 10 秒、9:16 的产品展示视频" --duration 10 --ratio 9:16 --wait
npx --yes @borgrise/cli@latest video first-frame "让商品缓慢旋转，突出瓶身质感" --image-file ./product.png --duration 10 --ratio 9:16 --wait
npx --yes @borgrise/cli@latest video first-last "从包装特写转到使用场景" --first-frame-file ./start.png --last-frame-file ./end.png --duration 10 --ratio 9:16 --wait
npx --yes @borgrise/cli@latest video reference "结合商品图和参考视频生成广告片" --image-file ./product.png --video-file ./demo.mp4 --duration 10 --ratio 9:16 --wait

视频分析：

npx --yes @borgrise/cli@latest video analyze --video-url https://example.com/demo.mp4 --wait
npx --yes @borgrise/cli@latest video analyze --video-file ./demo.mp4 --wait
npx --yes @borgrise/cli@latest video analyze batch --video-file ./a.mp4 --video-file ./b.mp4 --wait

# 测试环境指定项目 108
npx --yes @borgrise/cli@latest video analyze --video-url https://example.com/demo.mp4 --project-id 108 --base-url https://test-video.borgrise.com --wait

PPT 1.0 一键生成：

npx --yes @borgrise/cli@latest ppt generate "年度营销复盘" --file ./report.pdf --style "简洁商务风" --wait --timeout 1800

也可以分阶段调用，便于 Agent 审核或修改中间结果：

npx --yes @borgrise/cli@latest ppt outline "年度营销复盘" --file-url <document_url> --wait
npx --yes @borgrise/cli@latest ppt content --project-id <id> --outline-file ./outline.md --style "简洁商务风" --wait
npx --yes @borgrise/cli@latest ppt image --project-id <id> --json-file ./content.json --wait
npx --yes @borgrise/cli@latest ppt file --project-id <id> --image-url <page_1_url> --image-url <page_2_url> --wait

查询或恢复长任务：

npx --yes @borgrise/cli@latest task status --parent-dialog-id <parent_dialog_id>
npx --yes @borgrise/cli@latest task resume --parent-dialog-id <parent_dialog_id> --timeout 600 --interval 5
npx --yes @borgrise/cli@latest task status --task-id <task_id>
npx --yes @borgrise/cli@latest task resume --task-id <task_id> --timeout 600 --interval 5

资产库：

npx --yes @borgrise/cli@latest asset list --page 0 --size 20

长时间任务与恢复

• --wait 默认前台等待 300 秒（5 分钟），轮询间隔默认 5 秒。
• 视频生成、视频分析和 PPT 建议使用 --timeout 1800 --interval 10，最多前台等待 30 分钟。
• CLI 等待超时只代表本地进程不再阻塞，后端任务仍会继续；不要重复提交同一任务。
• 超时退出码为 2，JSON 会返回 taskId、parentGenerationDialogId 和最近一次 latest 状态。
• Agent 退出后优先用 parentGenerationDialogId 恢复；如果只想找回已完成结果，用同一账号查询资产库。

恢复示例：

npx --yes @borgrise/cli@latest task resume --parent-dialog-id <parent_dialog_id> --timeout 600 --interval 5
npx --yes @borgrise/cli@latest task status --parent-dialog-id <parent_dialog_id>
npx --yes @borgrise/cli@latest asset list --page 0 --size 20

Dry Run 示例

--dry-run 不需要 Token，也不会提交任务或扣费，适合 Agent 在正式提交前展示将要调用的接口和参数。

npx --yes @borgrise/cli@latest image generate "给雅诗兰黛小棕瓶生成 4 张 1:1 高端棚拍图" --dry-run
npx --yes @borgrise/cli@latest video text "生成一条 10 秒、9:16 的产品展示视频" --dry-run
npx --yes @borgrise/cli@latest video first-frame "让商品缓慢旋转" --image-url https://example.com/product.png --dry-run
npx --yes @borgrise/cli@latest video analyze --video-url https://example.com/demo.mp4 --dry-run

批量商品图扩展示例

虽然 PDF V2.1 的 P0 主线是四类 Agent 能力，CLI 也保留了批量商品图场景，方便电商运营把结构化商品表交给 Agent。

预览数据和费用：

npx --yes @borgrise/cli@latest batch images preview --file cli/examples/products.csv --template "夏季促销" --count 3 --ratio 1:1

确认后提交：

npx --yes @borgrise/cli@latest batch images run --file cli/examples/products.csv --template "夏季促销" --count 3 --ratio 1:1 --yes --wait --out batch_result.json

只重试失败项：

npx --yes @borgrise/cli@latest batch images retry --result batch_result.json --failed-only --yes --wait --out batch_retry_result.json

content-app 接口映射

| CLI 场景 | content-app 接口 | | --- | --- | | 登录 | POST /api/auth/login | | 创建 CLI 浏览器授权 | POST /api/cli/auth/device | | 博观网页确认授权 | POST /api/cli/auth/device/{deviceCode}/approve | | CLI 轮询授权结果 | GET /api/cli/auth/device/{deviceCode} | | 主动更新 Token | 优先 POST /api/cli/auth/refresh，兜底 POST /api/auth/login | | 连接校验 | POST /api/auth/verify，失败时回退查询额度 | | 上传图片素材 | POST /api/upload-image，multipart 字段 file | | 上传视频素材 | POST /api/upload-video，multipart 字段 file | | 文生图 | POST /api/picture/text_to_image | | 参考图生成 | POST /api/picture/multi_reference_image_generation | | 图像编辑 | POST /api/picture/image_edit | | 多图融合 | POST /api/picture/multi_image_fusion | | 文生视频 | POST /api/video/text-to-video | | 首帧图生视频 | POST /api/video/image-to-video | | 首尾帧图生视频 | POST /api/video/two-image-to-video | | 全能参考模式生成视频 | POST /api/video/reference-mode-video | | 单个视频拆解 | POST /api/creative/decompose_video_to_storyboard | | 批量视频拆解 | POST /api/creative/batch_decompose_video_to_storyboard | | 任务状态 | GET /api/history/generation-dialog/by-parent/{parentDialogId} | | 资产库 | GET /api/asset/assets | | 额度 | GET /api/quota/my-quotas |

生成类请求会自动补齐额度系统请求头，例如：

{
  "modelType": "gpt-image-2",
  "billType": "2",
  "apiModelParamObj": "{\"size\":\"2K\"}",
  "duration": "4"
}

图片生成默认值：

• 用户未输入模型名称时，CLI 默认使用 gpt-image-2。
• 用户未输入图片比例时，CLI 默认使用 1:1。
• 用户未输入图片清晰度时，CLI 默认使用 2K。
• 用户未输入生成数量时，CLI 默认生成 1 张；用户提供参考图时默认走参考图生图。

视频生成默认值：

• 用户未输入模型名称时，CLI 默认使用 seedance-2.0。
• 用户未输入视频比例时，CLI 默认使用 1:1。
• 用户未输入清晰度、时长、数量和声音时，CLI 默认使用 720p、5 秒、1 条、sound=on。
• 视频生成拆成四个独立入口：video text、video first-frame、video first-last、video reference。
• video generate 仅作为 video text 的兼容别名；携带图片、视频或音频素材时会要求改用对应入口，不会自动猜测或提交。

图片上传补问话术：

• 不说“缺少参数”，要说清楚需要哪张图、用来做什么。
• 优先请用户直接上传/拖入图片；终端环境下提示也可以给本地图片路径。
• 不要求用户自己找公网 URL；拿到本地路径后，Agent 使用 --ref-file 或 --image-file 自动上传。
• 首尾帧图生视频必须让用户标清首帧图和尾帧图。

本地打包

npm pack ./cli --pack-destination /tmp
npx --yes --package /tmp/borgrise-cli-0.3.0.tgz borgrise --help
npx --yes --package /tmp/borgrise-cli-0.3.0.tgz borgrise batch images preview --file cli/examples/products.csv --template "夏季促销" --count 3 --ratio 1:1

发布到 npm：

npm publish ./cli --access public