@volcengine/speech-cli 0.0.0-stage → 0.1.40

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @volcengine/speech-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 AI Agent 和终端工作流调用火山引擎豆包语音服务：语音合成、录音识别、Seed Audio 生成，以及独立 Skill 安装与更新。
+
+## 运行要求
+
+需要 Node.js 16 或更高版本。支持 macOS、Linux、Windows 的 x64 和 arm64。
+
+两版都使用 `speech-cli` 命令；用 `speech-cli --version` 确认当前为 `(volcengine)`。登录状态按产品隔离。
+
+npm 包只包含启动器和固定版本的下载清单。安装时从公开 TOS 地址下载当前平台的二进制，校验 ZIP 与二进制的 SHA-256 后缓存；下载不需要 TOS 凭据。禁用安装脚本时，首次运行会自动补下载。已缓存的相同版本可以离线启动，云服务调用仍需要网络和相应权限。
+
+可设置 `SPEECH_CLI_SKIP_POSTINSTALL=1` 跳过安装阶段下载；首次运行仍会按需下载。
+
+缓存默认为 `~/.cache/speech-cli`，可用 `SPEECH_CLI_CACHE_DIR` 指定可写目录。每个产品、版本和摘要独立缓存，不会跟随 `latest` 自动切换二进制。
+
+## 登录与开始使用
+
+```sh
+speech-cli auth login
+speech-cli auth status
+speech-cli tts --text '你好，欢迎使用豆包语音。' --output hello.mp3
+```
+
+无浏览器环境可执行 `speech-cli auth login --no-browser`，按返回的授权链接完成登录。也可以通过 `VOLCENGINE_SPEECH_API_KEY` 或 `--api-key-file` 提供 Speech 凭据。
+
+## 常用任务
+
+| 任务 | 命令 |
+| --- | --- |
+| 语音合成 | `speech-cli tts` |
+| 录音识别 | `speech-cli asr` |
+| 音频生成 | `speech-cli audio create` |
+| 查询 Audio 1.0 任务 | `speech-cli audio get` |
+| 安装或更新 Skill | `speech-cli skills update` |
+
+```sh
+# 转写本地录音
+speech-cli asr --audio-file meeting.wav
+
+# 使用 Speech Seed Audio 1.0 生成音效
+speech-cli audio create --model seed-audio-1.0 \
+  --prompt '清晨森林里的鸟鸣。' --output forest.wav
+
+# 使用 ARK Seed Audio 1.5；需要单独的 ARK API Key
+speech-cli audio create --model seed-audio-1.5 \
+  --ark-api-key-file /secure/ark-key \
+  --prompt '雨滴落在屋檐上。' --output rain.wav
+```
+
+TTS、ASR 和 Audio 1.0 使用 Speech 鉴权；Audio 1.5 使用 ARK 鉴权，可读取 `VOLCENGINE_ARK_API_KEY`。本地参考素材上传还需要 TOS 凭据及目标桶权限。具体参数以各命令的 `--help` 为准。
+
+## AI Agent Skills
+
+通过 CLI 管理 Seed Audio 1.5 提示词优化 Skill：
+
+```sh
+speech-cli skills update seedaudio15-pe
+```
+
+默认目录为 `~/.agents/skills`，可用 `--skills-dir` 指定其他目录。
+
+## 本地数据
+
+卸载 npm 包不会删除二进制缓存、独立安装的 Skill 或已保存的登录状态。需要退出账号时先运行 `speech-cli auth logout`。
+
+## 许可
+
+CLI 按 [Apache-2.0](./LICENSE) 许可分发，当前不公开应用源码。随 npm 包分发的安装代码版权署名为 Volcengine。云服务的使用权限与费用以适用的服务协议为准。
+
+开源组件的名称、许可证和地址见 [Third-party software notice](<./Third-party software notice.md>)，也可运行 `speech-cli licenses` 查看。

package/Third-party software notice.md

@@ -0,0 +1,39 @@
+# Third-party software notice
+
+This notice covers the Volcengine edition of Speech CLI, built with the
+`volcengine` Go build tag, for macOS, Linux and Windows. It lists the
+runtime and direct and transitive dependencies included in this edition.
+
+The npm/BNPM launcher uses Node.js built-in modules and has no third-party npm
+runtime dependencies. Build and release tooling dependencies, separately
+distributed Skills and their example dependencies are outside this notice.
+
+## Components
+
+| Component name | License name | Component address |
+| --- | --- | --- |
+| Go runtime and standard library | BSD 3-Clause License | https://go.dev/ |
+| google/uuid | BSD 3-Clause License | https://github.com/google/uuid |
+| inconshreveable/mousetrap | Apache License 2.0 | https://github.com/inconshreveable/mousetrap |
+| jmespath/go-jmespath | Apache License 2.0 | https://github.com/jmespath/go-jmespath |
+| spf13/cobra | Apache License 2.0 | https://github.com/spf13/cobra |
+| spf13/pflag | BSD 3-Clause License | https://github.com/spf13/pflag |
+| volcengine/ve-tos-golang-sdk | Apache License 2.0 | https://github.com/volcengine/ve-tos-golang-sdk |
+| golang.org/x/crypto | BSD 3-Clause License | https://github.com/golang/crypto |
+| golang.org/x/net | BSD 3-Clause License | https://github.com/golang/net |
+| golang.org/x/sync | BSD 3-Clause License | https://github.com/golang/sync |
+| golang.org/x/sys | BSD 3-Clause License | https://github.com/golang/sys |
+| golang.org/x/term | BSD 3-Clause License | https://github.com/golang/term |
+| golang.org/x/text | BSD 3-Clause License | https://github.com/golang/text |
+| go-yaml/yaml | Apache License 2.0; MIT License (libyaml-derived code) | https://github.com/go-yaml/yaml |
+| cenkalti/backoff | MIT License | https://github.com/cenkalti/backoff |
+| volcengine/volc-sdk-golang | Apache License 2.0 | https://github.com/volcengine/volc-sdk-golang |
+| volcengine/volcengine-go-sdk | Apache License 2.0 | https://github.com/volcengine/volcengine-go-sdk |
+| @user_3cc1fcfa/doubao-seeduplex (embedded Web Demo) | MIT License (declared by upstream) | https://skillhub.cn/ |
+
+`mousetrap` is used on Windows. `golang.org/x/crypto` is included through the
+Go standard library. The applicable Go toolchain version is recorded in each
+binary's build information.
+
+The embedded Web Demo is derived from the named SkillHub component. This entry
+covers the copy embedded in the CLI, not the separately distributed Skill.

package/lib/archive.js

@@ -0,0 +1,80 @@
+/*!
+ * Copyright 2026 Volcengine
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBinary = extractBinary;
+const node_zlib_1 = require("node:zlib");
+// Accept the current binary + notice layout and historical binary-only ZIPs.
+// The caller verifies the archive SHA-256 before extracting anything.
+function extractBinary(archive, member, expectedSize) {
+    const notice = "Third-party software notice.md";
+    const end = archive.length - 22;
+    if (end < 0 || archive.readUInt32LE(end) !== 0x06054b50
+        || archive.readUInt16LE(end + 4) !== 0 || archive.readUInt16LE(end + 6) !== 0
+        || archive.readUInt16LE(end + 20) !== 0)
+        throw new Error("Invalid release ZIP");
+    const count = archive.readUInt16LE(end + 10);
+    if ((count !== 1 && count !== 2) || archive.readUInt16LE(end + 8) !== count)
+        throw new Error("Unexpected ZIP member count");
+    const central = archive.readUInt32LE(end + 16);
+    if (central + archive.readUInt32LE(end + 12) !== end)
+        throw new Error("Invalid ZIP directory");
+    const seen = new Set();
+    const ranges = [];
+    let cursor = central;
+    let binary;
+    for (let index = 0; index < count; index++) {
+        if (cursor + 46 > end || archive.readUInt32LE(cursor) !== 0x02014b50)
+            throw new Error("Invalid ZIP directory");
+        const flags = archive.readUInt16LE(cursor + 8);
+        const method = archive.readUInt16LE(cursor + 10);
+        const compressed = archive.readUInt32LE(cursor + 20);
+        const size = archive.readUInt32LE(cursor + 24);
+        const nameLength = archive.readUInt16LE(cursor + 28);
+        const next = cursor + 46 + nameLength + archive.readUInt16LE(cursor + 30) + archive.readUInt16LE(cursor + 32);
+        if (next > end)
+            throw new Error("Invalid ZIP directory");
+        const name = archive.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
+        const kind = (archive.readUInt32LE(cursor + 38) >>> 16) & 0xf000;
+        if (seen.has(name) || (name !== member && name !== notice) || (kind !== 0 && kind !== 0x8000)
+            || flags & 1 || (method !== 0 && method !== 8) || archive.readUInt16LE(cursor + 34) !== 0
+            || (name === member ? size !== expectedSize || size > 64 * 1024 * 1024 : size === 0 || size > 1024 * 1024))
+            throw new Error("Unexpected ZIP member");
+        seen.add(name);
+        const local = archive.readUInt32LE(cursor + 42);
+        if (local + 30 > central || archive.readUInt32LE(local) !== 0x04034b50
+            || archive.readUInt16LE(local + 6) !== flags || archive.readUInt16LE(local + 8) !== method)
+            throw new Error("Invalid ZIP member data");
+        const localNameLength = archive.readUInt16LE(local + 26);
+        const start = local + 30 + localNameLength + archive.readUInt16LE(local + 28);
+        if (start + compressed > central || archive.subarray(local + 30, local + 30 + localNameLength).toString("utf8") !== name
+            || (!(flags & 8) && (archive.readUInt32LE(local + 18) !== compressed || archive.readUInt32LE(local + 22) !== size)))
+            throw new Error("Invalid ZIP member data");
+        ranges.push({ start: local, end: start + compressed });
+        if (name === member) {
+            const data = archive.subarray(start, start + compressed);
+            binary = method === 0 ? data : (0, node_zlib_1.inflateRawSync)(data, { maxOutputLength: expectedSize });
+            if (binary.length !== expectedSize)
+                throw new Error("Unsupported or invalid ZIP compression");
+        }
+        cursor = next;
+    }
+    ranges.sort((a, b) => a.start - b.start);
+    if (cursor !== end || !binary || (ranges.length === 2 && ranges[1].start < ranges[0].end))
+        throw new Error("Invalid ZIP directory or missing binary");
+    return binary;
+}

package/lib/download.js

@@ -0,0 +1,108 @@
+/*!
+ * Copyright 2026 Volcengine
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadArchive = downloadArchive;
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+async function downloadArchive(url, expectedSize, options = {}) {
+    if (!Number.isSafeInteger(expectedSize) || expectedSize <= 0 || expectedSize > 64 * 1024 * 1024)
+        throw new Error("Invalid archive size");
+    const started = Date.now();
+    const timeoutMs = options.timeoutMs ?? 14 * 60_000;
+    const idleMs = options.idleTimeoutMs ?? 45_000;
+    let size = 0;
+    const progress = () => options.onProgress?.(size, Date.now() - started);
+    const heartbeat = setInterval(progress, 15_000);
+    const visit = (address, redirects) => new Promise((resolve, reject) => {
+        if (redirects > 5) {
+            reject(new Error("Too many download redirects"));
+            return;
+        }
+        const source = new URL(address);
+        if (source.protocol !== "https:" && source.protocol !== "http:") {
+            reject(new Error("Unsupported download protocol"));
+            return;
+        }
+        const remaining = timeoutMs - (Date.now() - started);
+        if (remaining <= 0) {
+            reject(new Error(`Binary download total deadline exceeded after ${timeoutMs}ms; received=${size}/${expectedSize} bytes`));
+            return;
+        }
+        let finished = false;
+        const fail = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(deadline);
+            reject(error);
+            request.destroy();
+        };
+        const request = (source.protocol === "https:" ? node_https_1.default : node_http_1.default).get(source, response => {
+            const status = response.statusCode ?? 0;
+            if (status >= 300 && status < 400 && response.headers.location) {
+                const next = new URL(response.headers.location, source);
+                if (next.origin !== source.origin) {
+                    fail(new Error("Download redirected to a different origin"));
+                    return;
+                }
+                finished = true;
+                clearTimeout(deadline);
+                response.destroy();
+                void visit(next.href, redirects + 1).then(resolve, reject);
+                return;
+            }
+            if (status !== 200) {
+                fail(new Error(`Binary download failed: HTTP ${status}`));
+                return;
+            }
+            const chunks = [];
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > expectedSize)
+                    fail(new Error("Downloaded archive exceeds expected size"));
+                else
+                    chunks.push(chunk);
+            });
+            response.on("error", fail);
+            response.on("end", () => {
+                if (size !== expectedSize) {
+                    fail(new Error(`Downloaded archive size mismatch; received=${size}/${expectedSize} bytes`));
+                    return;
+                }
+                if (!finished) {
+                    finished = true;
+                    clearTimeout(deadline);
+                    resolve(Buffer.concat(chunks));
+                }
+            });
+        });
+        const deadline = setTimeout(() => fail(new Error(`Binary download total deadline exceeded after ${timeoutMs}ms; received=${size}/${expectedSize} bytes`)), remaining);
+        request.setTimeout(idleMs, () => fail(new Error(`Binary download inactivity timeout after ${idleMs}ms; received=${size}/${expectedSize} bytes`)));
+        request.on("error", fail);
+    });
+    try {
+        return await visit(url, 0);
+    }
+    finally {
+        clearInterval(heartbeat);
+        progress();
+    }
+}

package/lib/install.js

@@ -0,0 +1,137 @@
+/*!
+ * Copyright 2026 Volcengine
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectBinary = selectBinary;
+exports.binaryCachePath = binaryCachePath;
+exports.ensureBinary = ensureBinary;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const archive_1 = require("./archive");
+const download_1 = require("./download");
+const json_1 = require("./json");
+function byteCount(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > 64 * 1024 * 1024)
+        throw new Error("Invalid binary size");
+    return value;
+}
+function digest(value) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
+        throw new Error("Invalid binary checksum");
+    return value;
+}
+function selectBinary(root, platform = process.platform, architecture = process.arch) {
+    const system = platform === "win32" ? "windows" : platform;
+    const arch = architecture === "x64" ? "amd64" : architecture;
+    if (!["darwin", "linux", "windows"].includes(system) || !["amd64", "arm64"].includes(arch))
+        throw new Error(`Unsupported platform: ${platform}/${architecture}`);
+    const pkg = (0, json_1.readJsonObject)(node_path_1.default.join(root, "package.json"));
+    const record = (0, json_1.readJsonObject)(node_path_1.default.join(root, "release.json"));
+    const product = record.product;
+    if (product !== "volcengine" && product !== "byteplus")
+        throw new Error("Invalid Speech CLI package identity");
+    const distribution = product === "volcengine" ? "volcengine-speech-cli" : "byteplus-speech-cli";
+    const command = "speech-cli";
+    const version = (0, json_1.stringValue)(record.version, "release version");
+    const bin = (0, json_1.objectValue)(pkg.bin, "package.bin");
+    if (pkg.version !== version || !/^\d+\.\d+\.\d+$/.test(version)
+        || Object.keys(bin).length !== 1 || bin[command] !== "lib/run.js"
+        || typeof pkg.name !== "string" || !/^@[a-z0-9-]+\/[a-z0-9-]+$/.test(pkg.name)
+        || (!pkg.name.endsWith(`/${distribution}`) && pkg.name !== `@${product}/${command}`))
+        throw new Error("Invalid Speech CLI package identity");
+    const suffix = system === "windows" ? ".exe" : "";
+    const name = `${command}-${system}-${arch}${suffix}`;
+    const raw = record.binaries;
+    if (!Array.isArray(raw))
+        throw new Error("Missing binary manifest");
+    const entries = raw;
+    const matches = entries.map(entry => (0, json_1.objectValue)(entry, "binary")).filter(entry => entry.name === name);
+    if (matches.length !== 1)
+        throw new Error("Missing or duplicate platform binary");
+    const entry = matches[0];
+    const origin = product === "volcengine" ? "https://doubao-speech.tos-cn-beijing.volces.com" : "https://dola-speech.tos-ap-southeast-1.volces.com";
+    const url = `${origin}/releases/speech-cli/v${version}/${command}_${version}_${system}_${arch}.zip`;
+    if (entry.archive_url !== url || entry.member !== `${command}${suffix}`)
+        throw new Error("Invalid versioned TOS binary URL or member");
+    return { product, command, version, name, member: entry.member, url, archiveBytes: byteCount(entry.archive_bytes),
+        archiveSha256: digest(entry.archive_sha256), bytes: byteCount(entry.binary_bytes), sha256: digest(entry.sha256) };
+}
+function binaryCachePath(asset, cacheRoot) {
+    const base = cacheRoot ?? process.env.SPEECH_CLI_CACHE_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".cache", "speech-cli");
+    return node_path_1.default.resolve(base, asset.product, asset.version, asset.sha256, asset.name);
+}
+function matches(data, bytes, sha256) {
+    return data.length === bytes && node_crypto_1.default.createHash("sha256").update(data).digest("hex") === sha256;
+}
+function cached(file, asset) {
+    try {
+        const stat = node_fs_1.default.lstatSync(file);
+        return stat.isFile() && stat.size === asset.bytes && matches(node_fs_1.default.readFileSync(file), asset.bytes, asset.sha256);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function ensureBinary(root, options = {}) {
+    const asset = selectBinary(root, options.platform, options.architecture);
+    const output = binaryCachePath(asset, options.cacheRoot);
+    if (cached(output, asset)) {
+        if (require.main === module)
+            console.error(`[speech-cli][${asset.product}@${asset.version}][${asset.name}] verified cache reused; no download`);
+        return output;
+    }
+    const download = options.download ?? download_1.downloadArchive;
+    const started = Date.now();
+    const log = (message) => console.error(`[speech-cli][${asset.product}@${asset.version}][${asset.name}][+${((Date.now() - started) / 1000).toFixed(1)}s] ${message}`);
+    log(`download started; host=${new URL(asset.url).hostname}; expected=${asset.archiveBytes} bytes`);
+    const archive = await download(asset.url, asset.archiveBytes, {
+        onProgress: (bytes, elapsedMs) => log(`received=${bytes}/${asset.archiveBytes} bytes (${(bytes / asset.archiveBytes * 100).toFixed(1)}%); average=${Math.round(bytes / Math.max(elapsedMs / 1000, 1))} B/s`),
+    });
+    if (!matches(archive, asset.archiveBytes, asset.archiveSha256))
+        throw new Error("TOS archive checksum mismatch");
+    const binary = (0, archive_1.extractBinary)(archive, asset.member, asset.bytes);
+    if (!matches(binary, asset.bytes, asset.sha256))
+        throw new Error("Binary checksum mismatch");
+    const directory = node_path_1.default.dirname(output);
+    node_fs_1.default.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = node_fs_1.default.mkdtempSync(node_path_1.default.join(directory, ".download-"));
+    try {
+        const staged = node_path_1.default.join(temporary, asset.name);
+        node_fs_1.default.writeFileSync(staged, binary, { mode: 0o755 });
+        // Another installer may have completed while this download was in flight.
+        if (!cached(output, asset))
+            node_fs_1.default.renameSync(staged, output);
+        log("installed; archive and binary SHA-256 verified");
+        return output;
+    }
+    finally {
+        node_fs_1.default.rmSync(temporary, { recursive: true, force: true });
+    }
+}
+if (require.main === module && process.env.SPEECH_CLI_SKIP_POSTINSTALL !== "1") {
+    void ensureBinary(node_path_1.default.join(__dirname, "..")).catch((error) => {
+        console.error(`[speech-cli] ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    });
+}

package/lib/json.js

@@ -0,0 +1,45 @@
+/*!
+ * Copyright 2026 Volcengine
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJson = parseJson;
+exports.objectValue = objectValue;
+exports.stringValue = stringValue;
+exports.readJsonObject = readJsonObject;
+const node_fs_1 = __importDefault(require("node:fs"));
+function parseJson(text) {
+    return JSON.parse(text);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function objectValue(value, label) {
+    if (!isObject(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function stringValue(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+function readJsonObject(filename) {
+    return objectValue(parseJson(node_fs_1.default.readFileSync(filename, "utf8")), filename);
+}

package/lib/run.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/*!
+ * Copyright 2026 Volcengine
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const install_1 = require("./install");
+async function main() {
+    const binary = await (0, install_1.ensureBinary)(node_path_1.default.join(__dirname, ".."));
+    const result = (0, node_child_process_1.spawnSync)(binary, process.argv.slice(2), { stdio: "inherit", env: process.env });
+    if (result.error)
+        throw result.error;
+    if (result.signal) {
+        process.kill(process.pid, result.signal);
+        return;
+    }
+    process.exitCode = result.status ?? 1;
+}
+if (require.main === module) {
+    void main().catch((error) => {
+        console.error(`[speech-cli] ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@volcengine/speech-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.40",
+  "description": "火山引擎豆包语音 CLI",
+  "bin": {
+    "speech-cli": "lib/run.js"
+  },
+  "files": [
+    "lib/",
+    "release.json",
+    "README.md",
+    "LICENSE",
+    "Third-party software notice.md"
+  ],
+  "scripts": {
+    "postinstall": "node lib/install.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/release.json

@@ -0,0 +1,61 @@
+{
+  "version": "0.1.40",
+  "product": "volcengine",
+  "source_commit": "97b554f2bc8689fc0e5f7b24fe10977277616934",
+  "binaries": [
+    {
+      "name": "speech-cli-darwin-amd64",
+      "member": "speech-cli",
+      "sha256": "464362d05778782062354fcbe748052ca78835e9d488e835a019b70b89d240e6",
+      "binary_bytes": 13166688,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_darwin_amd64.zip",
+      "archive_sha256": "fee6f56277bb84aa0b86c131892995a5577589d0fa08223efcbd43d89b95db23",
+      "archive_bytes": 5070442
+    },
+    {
+      "name": "speech-cli-darwin-arm64",
+      "member": "speech-cli",
+      "sha256": "0f868eacddad0f0d55902f4b4c2d2c28729bfe0388f51c266a862028568a2e75",
+      "binary_bytes": 12826738,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_darwin_arm64.zip",
+      "archive_sha256": "c76d90a2e586378d2658536c9277923a72dd79ca6de013e82363fc9040cf84ac",
+      "archive_bytes": 4867078
+    },
+    {
+      "name": "speech-cli-linux-amd64",
+      "member": "speech-cli",
+      "sha256": "5edf16f8c9800cbb08b905609ea6287776258cc612eae3bcbadf59085f3d7661",
+      "binary_bytes": 12169216,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_linux_amd64.zip",
+      "archive_sha256": "9622a667a30fe69032ce5317fbad0f39c1c9426ab7434f89dca1e717cb515dc7",
+      "archive_bytes": 4891855
+    },
+    {
+      "name": "speech-cli-linux-arm64",
+      "member": "speech-cli",
+      "sha256": "9981d1e1d930058dd69790f4b961b202e33568103900045ca33e1c82606047af",
+      "binary_bytes": 11468800,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_linux_arm64.zip",
+      "archive_sha256": "86856e63b938ebbebc7745fe7bfb296d19b52566c624eb0b7439bcdd8c87d4fd",
+      "archive_bytes": 4462399
+    },
+    {
+      "name": "speech-cli-windows-amd64.exe",
+      "member": "speech-cli.exe",
+      "sha256": "e973ec9b506753ed76484a2d9a68ccaaeb30441e726acdd5b6c2186a5d1a136e",
+      "binary_bytes": 12528640,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_windows_amd64.zip",
+      "archive_sha256": "81dc12cf2176a3fb4d8c14859ce67110ed729d174e7b1120837c7c35f1a97dc4",
+      "archive_bytes": 4994893
+    },
+    {
+      "name": "speech-cli-windows-arm64.exe",
+      "member": "speech-cli.exe",
+      "sha256": "f21df0e0894b78da73df8e2dc53242f86fb23aa6e986427a5d581afab62bd633",
+      "binary_bytes": 11726336,
+      "archive_url": "https://doubao-speech.tos-cn-beijing.volces.com/releases/speech-cli/v0.1.40/speech-cli_0.1.40_windows_arm64.zip",
+      "archive_sha256": "54f52dadf7827f89dc096fa3e1aa6d167b8bd557ae18f9a2302a3867684f4e8a",
+      "archive_bytes": 4551568
+    }
+  ]
+}