LAS CLI (Go)

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

特性

• 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 安装
• Go 1.22+：仅源码构建需要
• git：从仓库安装 Skills 时需要

快速开始（人类用户）

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

提示：如果你是通过源码构建得到的二进制，把下文的 las-cli 替换为 ./bin/las-cli 即可。

1) 安装

以下两种方式任选其一：

• npm 安装（推荐）：

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

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

2) 配置

推荐优先使用环境变量/命令参数注入（避免写入磁盘）：

# 直接使用 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，继续注入 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) 构建（开发）

make build
# => bin/las-cli

说明：make build 用于本地开发调试，默认不会注入发布版本号（las-cli --version 会是 0.0.0-dev）。

或直接运行：

go run . --help

2) 初始化

./bin/las-cli init
# 或者：
./bin/las-cli config init

./bin/las-cli config show
./bin/las-cli config show --format table

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

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

3) 调用算子

./bin/las-cli operators list
./bin/las-cli operators list --format table
./bin/las-cli operators help las_asr_pro
./bin/las-cli operators help las_seed_2_0

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

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

4) 异步任务

./bin/las-cli task list
./bin/las-cli task list --format table

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

5) TOS 文件操作

# 方式 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>）
./bin/las-cli tos upload ./a.txt

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

./bin/las-cli tos ls tos://<bucket>/path/ --format table
./bin/las-cli tos presign get tos://<bucket>/path/a.txt --expires 3600
./bin/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>"
./bin/las-cli tos upload ./a.txt

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

6) 价格预估（price/inspect）

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

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

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

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

开发

更新默认算子列表

默认算子列表来自旧版 TS 源码 console/libs/las-cli/src/operators/operators.ts。

本仓库内提供脚本 tools/extract_operators_json.js 可将其导出为 JSON：

# 从旧版 operators.ts 导出为单个 JSON（临时文件）
node tools/extract_operators_json.js <path-to-operators.ts> /tmp/las-cli-operators.json

# 然后将其拆分为 internal/core/operators/specs/<operator_id>.json（每个算子一个文件）

然后重新构建即可。

发布与分发

本项目采用「npm wrapper + CDN 二进制」模式（参考 larksuite/cli）：

• npm 包：@volcengine/las-cli，提供 las-cli 命令入口 + 安装逻辑（postinstall 自动下载二进制）。
• CDN：存放各平台二进制与安装脚本。

1) 一键发布（本地，默认推荐）

默认发布方式为 scripts/release-local.sh，它会串起完整流程：

1. 计算/设置 npm 包版本（写入 package.json，不创建 git tag）
2. 校验 CHANGELOG.md 是否包含本次版本段落（例如 ## [v0.0.8] - 2026-04-20；可用 SKIP_CHANGELOG_CHECK=1 跳过）
3. 多平台交叉编译（产物输出到 dist/bin/，并写入 dist/VERSION）
4. 上传二进制 以及安装脚本 到 CDN（install-cli.sh / install-cli.ps1）
5. npm publish 发布 npm 包（postinstall 会从 CDN 下载二进制）

前置：本机已安装 Go、Node.js/npm，并具备 npm publish 权限。

执行示例：

# 参数可以是：<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git
sh ./scripts/release-local.sh patch
sh ./scripts/release-local.sh 0.0.8
sh ./scripts/release-local.sh from-git

常用环境变量（推荐显式设置 CDN_DIR / LAS_CLI_DOWNLOAD_PATH，避免路径不一致）：

• CDN_DIR：上传目录（会影响安装端下载路径，强烈建议每次发布都显式指定）
• LAS_CLI_DOWNLOAD_PATH：安装下载前缀（用于安装脚本/排障校验），格式应为 https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>
• CDN_EMAIL：CDN 上传者邮箱；如不设置会使用脚本内默认值（如需替换 uploader，请显式设置）
• CDN_TOKEN：可选
• CDN_REGION：默认 CN
• NPM_REGISTRY：默认 https://registry.npmjs.org/
• DRY_RUN=1：只打印步骤，不执行上传/发布

注意：

• from-git 依赖仓库已有 git tag（例如 v0.0.8）；若仓库没有 tag 会报错。
• 为了维护“每个版本的更新点”，建议每次发版前先补齐 CHANGELOG.md 对应版本段落（参考 larksuite/cli 的格式）。
• release-local.sh 不会自动创建/推送 git tag；建议发布后把 CHANGELOG.md + package.json 提交到主干，然后执行：sh ./scripts/tag-release.sh <version> 创建并推送 v<version> tag。

2) 安装与分发方式

方式 A：npm 安装（推荐）

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

npm 包结构：

• bin 入口：scripts/run.js
• postinstall：scripts/install.js（按平台从 CDN 下载二进制到包内 bin/）

方式 B：二进制安装脚本（可选，适用于不走 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
# 或在本仓库内本地运行：
LAS_CLI_DOWNLOAD_PATH="https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>" bash scripts/install-cli.sh

示例（Windows PowerShell）：

irm https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>/install-cli.ps1 | iex
# 或从仓库本地运行：
setx LAS_CLI_DOWNLOAD_PATH "https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>"
powershell -ExecutionPolicy Bypass -File scripts\install-cli.ps1

3) 手动/CI/排障：分步构建与发布（可选）

当你需要在 CI 中拆分步骤、或排查某一步失败时，可手动执行以下脚本（release-local.sh 内部也是调用它们）：

3.1 交叉编译（发布用）

# 建议：VERSION 与 package.json version 保持一致
export VERSION=0.0.1
./scripts/build-binaries.sh
# => dist/bin/*

固定产物命名（安装/下载逻辑依赖这些名字）：

• Linux x64: dist/bin/las-cli-linux-x64
• macOS x64: dist/bin/las-cli-macos-x64
• macOS arm64: dist/bin/las-cli-macos-arm64
• Windows x64: dist/bin/las-cli-win-x64.exe

3.2 上传到 CDN

export CDN_EMAIL="[email protected]"
export CDN_DIR="<your-cdn-dir>"  # 强烈建议显式设置，需与安装端下载前缀保持一致

./scripts/upload-cdn.sh CN dist/bin/las-cli-*
./scripts/upload-cdn.sh CN scripts/install-cli.*

3.3 发布 npm 包

npm publish --registry="${NPM_REGISTRY:-https://registry.npmjs.org/}" --access public

常见问题：

• npm i -g 报 EEXIST .../bin/las-cli：说明本机已有同名命令（旧包或手工安装）。先卸载旧包或删除该文件再安装：
  • npm rm -g @las-ai/cli @volcengine/las-cli
  • 或按 npm 提示加 --force
• package.json 是 0.0.1，但 las-cli --version 不是：通常是 CDN 上的二进制未更新或下载路径不一致。
  • scripts/install.js 会用 npm 的版本号做 expected version；若发现本地二进制版本不一致，会自动删除并重新下载，并在仍不一致时输出 warning。

4) 更新点维护（CHANGELOG）

参考 larksuite/cli 的做法，本仓库提供 CHANGELOG.md 作为每个版本更新点的单一事实源（SSOT）。

• 每次发版新增一段：## [v<version>] - YYYY-MM-DD
• 在该版本下按 ### Features / ### Bug Fixes / ### Documentation 写更新点（尽量带上对应 MR 编号）

你可以用 scripts/release-local.sh <newversion> 的方式显式指定版本号，从而更容易在发版前准备好 changelog 段落。

5) 打 tag（tag-release）

发布完成并把版本相关变更提交到主干后，使用：

sh ./scripts/tag-release.sh <version>

该脚本会校验工作区干净、分支已同步到 origin/<branch>、以及 CHANGELOG.md 是否包含对应版本段落，然后创建并 push v<version> tag。

make build 报 make: go: No such file or directory 代表 本机没有安装 Go（或 go 不在 PATH）。

请先确保：

• go version 能正常输出
• Go 版本建议 >= 1.22

常见构建问题：go module 下载超时

如果你在企业网络/国内网络下遇到类似报错：

Get "https://proxy.golang.org/...": i/o timeout

说明 Go 在拉取依赖时访问 proxy.golang.org 超时。

本仓库使用 Go Modules 管理依赖（不提交 vendor/）。首次 make build / make test 会按 go.mod 拉取依赖。

如果你拉依赖遇到网络限制，建议先配置可用的 GOPROXY，然后执行 go mod download（或直接 make build/make test 会自动触发下载）：

go env -w GOPROXY=https://goproxy.cn,direct
# 如仍受限，可临时用 direct：
go env -w GOPROXY=direct

如果你需要更新依赖（例如新增/升级第三方包），使用 go get 完成变更后执行 go mod tidy。