LAS CLI (Go)

这是将原 Node/TS 版本（dp/console: las-cli-v1.5.5）迁移到 独立 Go 仓库后的实现版本；当前 npm 包名为 @volcengine/las-cli。

本 README 面向 CLI 使用者（人类用户 + AI Agent）。如果你是要本地构建源码、改代码、参与发布或维护 CHANGELOG/打 tag，请直接看 CONTRIBUTING.md。

特性

• auth：OAuth 登录与登录态管理（login / logout / status）；登录后 CLI 会自动注入临时 STS 凭证用于 tos 直连，无需手动配置 AK/SK

• api-key：在 OAuth 登录态下管理 LAS API Key（list / create / get / use）。运行算子相关命令时若未配置 API Key，CLI 会自动列出账号下可用 Key 让你选择，菜单末尾还提供「+ 创建新的 API Key」入口；账号下没有 Key 时则直接引导创建并用于本次命令；可用 api-key use [api-key] 主动切换当前生效的 Key（不带参数走交互菜单，带参数直接写入指定明文）

• operators：列出/查看/调用 LAS operators（支持 sync/async + 等待轮询）

• task：异步任务管理（list/status/wait/kill/clear）

• task create：基于 las_seed_2_0 的自然语言编排（后台执行，任务落盘，可 status 查看）

• tos：TOS 文件操作（upload/download/ls/presign）

• price：算子价格预估（信息不足时展示单价档位）

• inspect：探测媒体/PDF 基本信息（供 price 自动补齐参数）

• 配置文件：默认 ~/.las-cli/config.json（目录权限 0700，文件权限 0600）

  • 可通过 LAS_CLI_CONFIG_DIR 覆盖配置目录

• 支持无落盘配置（flags/env 覆盖，优先级：flag > env > config）：

  • flags（按命令生效，详见 --help）：
    • --api-key：覆盖 las.apiKey
    • --tos-bucket：覆盖 tos.bucket
    • --region：覆盖 volcengine.region
  • env：
    • LAS_API_KEY：覆盖 las.apiKey
    • VOLCENGINE_REGION：覆盖 volcengine.region
    • TOS_BUCKET：覆盖 tos.bucket
    • VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY / VOLCENGINE_SESSION_TOKEN：用于 las-cli tos 直连 TOS
  • TOS endpoint 将根据 volcengine.region 自动拼接为 tos-<region>.volces.com，无需通过环境变量或配置项手动设置。

• 输出契约：默认 stdout 输出 JSON envelope，stderr 输出结构化错误 envelope

安装与快速开始

环境要求

• Node.js（npm/npx）：用于 npm 安装与 Skills 安装
• git：从仓库安装 Skills 时需要

想从源码构建（需要 Go 1.22+）？请参考 CONTRIBUTING.md。

快速开始（人类用户）

Note for AI assistants: 如果你是 AI Agent 正在协助用户，请优先阅读“快速开始（AI Agent）”小节。

1) 安装

以下两种方式任选其一：

• npm 安装（推荐）：

npm i -g @volcengine/las-cli
las-cli --version

• 二进制安装脚本（适用于不走 npm 的环境）：使用仓库 scripts/install-cli.sh / scripts/install-cli.ps1，可通过 LAS_CLI_DOWNLOAD_PATH 指定下载前缀；详见 CONTRIBUTING.md → 发布与分发。

2) 配置

v0.4.1 起推荐先执行一次 las-cli auth login 完成 OAuth 登录：登录后 CLI 会自动注入临时 STS 凭证用于 tos 直连，且在调用算子时若未配置 LAS API Key，会自动列出账号下可用 Key 让你选择（菜单末尾还提供「+ 创建新的 API Key」入口），账号下没有 Key 时直接引导创建并用于本次命令——通常不再需要手工导出 LAS_API_KEY / AK/SK。

# 推荐：OAuth 登录（一次即可，登录态会持久化到系统 keychain，不可用时回退到 ~/.las-cli/auth.json）
las-cli auth login
# SSH / 容器 / 无浏览器环境改用跨设备模式：浏览器登录后从授权页复制授权码粘贴回终端
las-cli auth login --remote
las-cli auth status

# 主动管理 API Key（可选；首次调用算子时也会自动引导）
las-cli api-key list
las-cli api-key create --name my-key
# 切换当前 las.apiKey：不带参数走交互菜单，含「+ 创建新的 API Key」入口；带参数则直接写入指定明文
las-cli api-key use
las-cli api-key use sk-xxxxxxxxxxxxxxxx

如需脱机使用或在 CI 环境运行，可改用环境变量/命令参数注入（避免写入磁盘）：

# 直接使用 las-cli 时，注入已有的 LAS_API_KEY
export LAS_API_KEY="<las-api-key>"
export VOLCENGINE_REGION="cn-beijing"   # 可选，覆盖 volcengine.region；仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)

若你在 Arkclaw/OpenClaw 环境中运行 skill，平台会自动提供所需身份，通常无需手工配置额外认证环境变量。

如需持久化，可执行：

las-cli init
# 或：las-cli config init

3) 第一次调用

las-cli operators list --format table
las-cli operators help las_asr_pro
# 按 help 提示准备 params.json 后调用
las-cli operators call las_asr_pro --params-file ./params.json
# 可选：指定调用方来源（默认 cli）：--caller cli|api|skill
# 例如：
# las-cli operators call las_asr_pro --caller skill --params-file ./params.json

（可选）如果你要使用 las-cli tos ...：

export VOLCENGINE_ACCESS_KEY="<ak>"
export VOLCENGINE_SECRET_KEY="<sk>"
export VOLCENGINE_SESSION_TOKEN="<session-token>"  # 可选
export VOLCENGINE_REGION="cn-beijing"               # 可选，覆盖 volcengine.region；仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)
export TOS_BUCKET="tos://<bucket>"                 # 可选，覆盖 tos.bucket（用于补全 <tos_key> 或 1 参数上传回退直连）

快速开始（AI Agent）

目标：在不落盘 secrets的前提下，让 Agent 能稳定调用 las-cli 并解析结构化输出。

# 1) 安装 CLI（推荐 npm wrapper）
npm i -g @volcengine/las-cli

# 2) 安装 Agent Skills（推荐，让 Agent 具备可发现的工具描述）
# 默认走 SSH；若 agent 环境不支持 SSH clone，可改用 https 仓库地址
npx skills add [email protected]:dp/las-cli.git -g -y

# 3) 注入必要凭证（任选其一）
# - 若在 Arkclaw/OpenClaw 环境中运行 skill，平台会自动提供身份
# - 在交互式开发机上：执行 `las-cli auth login` 完成 OAuth 登录（v0.4.1 推荐）；
#   SSH / 容器 / 无浏览器环境改用 `las-cli auth login --remote`（手动粘贴授权码）；
#   登录后 STS / API Key 会自动注入，无需再 export 任何 secrets
# - 在 CI / 无浏览器环境：继续注入 LAS_API_KEY
export LAS_API_KEY="<las-api-key>"

# 4) 验证可用性
las-cli --version
las-cli operators list

如需执行 las-cli tos ...，同样推荐通过 env 注入 VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY / VOLCENGINE_SESSION_TOKEN（可选），并按需使用 VOLCENGINE_REGION / TOS_BUCKET 覆盖配置（TOS endpoint 会根据 volcengine.region 自动拼接为 tos-<region>.volces.com，无需手动配置）。

Skill 认证约定：在 Arkclaw/OpenClaw 环境中，las-cli 会优先使用平台自动提供的身份发起 Operator/File API 调用；仅在未提供该身份时才回退到 LAS_API_KEY / las.apiKey。 认证流程图见 docs/skill-tip-auth-flow.md。

建议 Agent 调用规范：优先用 --params-file 传参，默认输出为 JSON envelope（stdout 是数据，stderr 是错误/提示），避免使用 --format table 破坏可机读性。

Agent Skills 安装（给 AI Agent 使用）

前置：先安装 las-cli（至少选一种方式）

• npm（推荐）：npm i -g @volcengine/las-cli
• 源码：在仓库根目录执行 make build，然后使用 ./bin/las-cli

安装 skills（参考 larksuite/cli 的做法，skills 与 CLI 解耦）：

# 安装本仓库内的 skills
npx skills add [email protected]:dp/las-cli.git -g -y

说明：如果 agent 环境不支持 SSH clone，可改用 https 仓库地址；更多参数请执行 npx skills --help。

1) 初始化

las-cli init
# 或者：
las-cli config init

las-cli config show
las-cli config show --format table

# 直接写入配置项（key 支持：volcengine.region / volcengine.accessKey / volcengine.secretKey / volcengine.sessionToken / las.apiKey / tos.bucket）
las-cli config set volcengine.region cn-beijing  # 仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)

# 清空所有本地配置（需要二次确认）
las-cli config clear
# 或跳过确认：
las-cli config clear -y

2) 调用算子

las-cli operators list
las-cli operators list --format table
las-cli operators help las_asr_pro
las-cli operators help las_seed_2_0

# 推荐：用 params file
las-cli operators call las_asr_pro --params-file ./params.json
# 可选：指定调用方来源（默认 cli）：--caller cli|api|skill
# 例如：
# las-cli operators call las_asr_pro --caller skill --params-file ./params.json

# 兼容旧版：直接传 --param（仅识别当前算子的参数定义）
las-cli operators call las_audio_convert --input_path tos://xx/a.wav --output_path tos://xx/b.wav

3) 异步任务

las-cli task list
las-cli task list --format table

las-cli task status <task_id> --operator las_asr_pro
las-cli task wait <task_id> --operator las_asr_pro
las-cli task kill <task_id>

4) TOS 文件操作

v0.4.1 起推荐先执行一次 las-cli auth login：登录后 CLI 会自动用账号 STS 发起 TOS 直连（presign / upload / download / ls 全部可用），可直接跳过下方"方式 A1) 直连 TOS（AK/SK）"。仅在 CI / 无浏览器场景或需要长期凭证时再回退到 AK/SK。

# 方式 A：通过环境变量配置（推荐，避免落盘）

## A1) 直连 TOS（AK/SK）
export VOLCENGINE_ACCESS_KEY="<ak>"
export VOLCENGINE_SECRET_KEY="<sk>"
export VOLCENGINE_SESSION_TOKEN="<session-token>"  # 可选

# region / bucket 统一从配置读取
# - region: `las-cli config set volcengine.region cn-beijing`（仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)）
# - bucket: `las-cli config set tos.bucket tos://<bucket>`

# 1 参数：若未配置 LAS_API_KEY，会自动回退为直连 TOS，并为你生成 object_key（默认 inputs/<timestamp>-<file>）
las-cli tos upload ./a.txt

# 2 参数：显式指定目标路径（只允许直连 TOS；必须 AK/SK）
las-cli tos upload ./a.txt tos://<bucket>/path/a.txt

las-cli tos ls tos://<bucket>/path/ --format table
las-cli tos presign get tos://<bucket>/path/a.txt --expires 3600
las-cli tos download tos://<bucket>/path/a.txt ./a.txt

## A2) File API（LAS_API_KEY）
# 1 参数：若配置了 LAS_API_KEY（或 config las.apiKey），会优先走 File API 上传，并返回 tos_url + presigned_url（24h）
export LAS_API_KEY="<las-api-key>"
las-cli tos upload ./a.txt

# 方式 B：通过配置文件（持久化）
las-cli config set volcengine.accessKey <ak>
las-cli config set volcengine.secretKey <sk>
las-cli config set volcengine.sessionToken <session-token>  # 可选
las-cli config set tos.bucket tos://<bucket>
las-cli tos ls tos://<bucket>/

5) 价格预估（price/inspect）

# 探测媒体信息（时长/分辨率/编码）
las-cli inspect media ./a.mp4 --format pretty

# 预估视频类算子（自动用媒体探测结果填充时长；部分算子还能补齐 codec/resolution）
las-cli price las_video_edit --media ./a.mp4 --mode simple --format pretty
las-cli price las_video_resize --media ./a.mp4 --format pretty

# 探测 PDF 页数 + 预估 PDF 解析费用
las-cli inspect pdf ./a.pdf --format pretty
las-cli price las_pdf_parse_doubao --pdf ./a.pdf --parse-mode detail --format pretty

如果缺少必要参数（例如 token 数、图片数量、或无法从媒体中探测到 codec），price 会返回 Computable=false 并展示对应单价档位。

安装方式补充

npm 安装（推荐）

npm i -g @volcengine/las-cli
las-cli --version
las-cli --help

npm 包会在 postinstall 阶段按平台从 CDN 下载二进制；命令入口为 scripts/run.js。

二进制安装脚本（不走 npm 的环境）

• macOS/Linux：scripts/install-cli.sh
• Windows：scripts/install-cli.ps1

两者都会优先读取 LAS_CLI_DOWNLOAD_PATH（形如 https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>）；若未设置则使用脚本内默认值。

# macOS/Linux
curl -fsSL https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>/install-cli.sh | bash

# Windows PowerShell
irm https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>/install-cli.ps1 | iex

各版本的更新点见 CHANGELOG.md；构建/发布/打 tag 等流程见 CONTRIBUTING.md。