@hxnnxs/opencode-voice 0.1.0

package/README.zh.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <a href="https://github.com/ihxnnxs/opencode-voice">
+    <picture>
+      <source srcset="assets/opencode-voice-dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/opencode-voice-light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/opencode-voice-light.svg" alt="opencode voice logo">
+    </picture>
+  </a>
+</p>
+<p align="center">OpenCode TUI 的本地语音转文字插件。</p>
+<p align="center">
+  <img alt="status" src="https://img.shields.io/badge/status-mvp-orange?style=flat-square" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" />
+  <img alt="opencode" src="https://img.shields.io/badge/opencode-%3E%3D1.17.4-black?style=flat-square" />
+  <img alt="stt" src="https://img.shields.io/badge/STT-local_whisper.cpp-purple?style=flat-square" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.zh.md">简体中文</a> |
+  <a href="README.es.md">Español</a>
+</p>
+
+---
+
+### 安装
+
+通过 OpenCode 一条命令安装：
+
+```bash
+opencode plugin @hxnnxs/opencode-voice
+```
+
+安装后重启 OpenCode。首次启动会自动下载 managed `whisper.cpp` engine 和你选择的模型。用户不需要手动安装 `whisper-cli`。
+
+可选 CLI 安装器。它会运行相同的 OpenCode plugin install 命令，并预下载 managed engine：
+
+```bash
+npx @hxnnxs/opencode-voice install
+```
+
+除非你要开发插件，否则不需要 clone 仓库。
+
+> [!TIP]
+> 首次启动会打开模型选择器。选择 Whisper 模型，等待下载完成，然后用 `ctrl+r` 向 prompt 听写。
+
+### 要求
+
+插件会管理 STT engine 和模型：
+
+- 从 opencode-voice GitHub Release registry 下载 `whisper.cpp`
+- 存到 `~/.cache/opencode-voice/engines/whisper.cpp/<platform>-<arch>/`
+- 首次 setup 时下载你选择的 Whisper 模型
+
+手动安装 `whisper-cli` 是可选项。如果本机已有 binary，`opencode-voice` 仍然可以导入或使用它。
+
+检查本机环境：
+
+```bash
+npx @hxnnxs/opencode-voice doctor
+```
+
+不打开 OpenCode 也可以安装 managed engine：
+
+```bash
+npx @hxnnxs/opencode-voice engine install whisper.cpp
+```
+
+### 使用
+
+命令：
+
+- `/voice` - 切换录音并插入转写文本
+- `/voice-submit` - 切换录音，插入转写文本并提交
+- `/voice-stop` - 取消当前录音或转写
+- `/voice-settings` - 打开模型、快捷键、麦克风和诊断设置
+
+默认快捷键：
+
+```txt
+ctrl+r -> 开始录音
+ctrl+r -> 停止、转写并插入文本
+```
+
+默认关闭 hold-to-talk，因为 terminal release events 在不同终端中表现不一致。你仍然可以在 `/voice-settings` 中配置 hold 快捷键。
+
+### 模型
+
+当前通过 `whisper.cpp` 可用：
+
+| 模型                 | 大小   | 说明                    |
+| -------------------- | ------ | ----------------------- |
+| Whisper Small        | 465 MB | 默认，多语言            |
+| Whisper Medium Q4_1  | 469 MB | 更高准确率              |
+| Whisper Turbo        | 1.5 GB | 大模型，比 full large 快 |
+| Whisper Large Q5_0   | 1.0 GB | 准确，但更慢            |
+
+模型下载支持断点续传、重试、进度显示和 SHA256 校验。
+
+计划中的 sidecar 模型：
+
+- Parakeet V3
+- GigaAM v3
+- Moonshine V2 Small
+
+### 平台状态
+
+| 平台    | 状态 |
+| ------- | ---- |
+| Linux   | 一条命令安装 engine/model；录音使用 `arecord`、`ffmpeg` 或 `sox` |
+| macOS   | 一条命令安装 engine/model；native recorder sidecar 发布前使用 `ffmpeg` AVFoundation |
+| Windows | engine 下载路径已准备好；录音还需要 native recorder sidecar |
+
+### 架构
+
+该包采用 OpenCode community TUI 插件使用的公共结构。
+
+- npm package 导出 `./tui`
+- 本地开发可以在 `tui.json` 中使用绝对路径
+- 发布后使用 `opencode plugin @hxnnxs/opencode-voice` 安装
+- runtime settings 存储在 OpenCode TUI plugin storage 中
+
+文件：
+
+- `index.js` - TUI 插件入口、命令、dialogs、keymap layer
+- `lib/models.js` - 模型 registry、cache paths、default settings
+- `lib/download.js` - 可续传下载和 SHA256 校验
+- `lib/engine.js` - recorder 选择和 `whisper-cli` 转写
+- `lib/engines.js` - managed native engine 下载、状态、导入和移除
+- `bin/opencode-voice.js` - install wrapper 和 diagnostics CLI
+
+语音输入需要 native audio 和 STT binaries。JS 插件负责 OpenCode UI、settings、engine/model downloads 和 prompt insertion。未来的 native sidecar 应替换 shell recorders，并加入 fast VAD 和 Handy-style models。
+
+### Roadmap
+
+- npm release 前发布 managed `whisper-cli` release assets
+- 使用 `cpal` 和 VAD 的 Rust recorder sidecar
+- 支持 Parakeet、GigaAM、SenseVoice、Canary 和 Moonshine
+- Windows recorder support
+- 更快的 streaming-style transcription
+
+### 开发
+
+运行检查：
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+此 MVP 没有 build step。
+
+从 checkout 安装开发版本：
+
+```bash
+git clone https://github.com/ihxnnxs/opencode-voice.git opencode-voice
+cd opencode-voice
+opencode plugin "$(pwd)"
+```
+
+### 项目状态
+
+这是独立的 OpenCode plugin。它不是 OpenCode 团队构建的项目，也不隶属于 OpenCode。
+
+### 鸣谢
+
+- OpenCode wordmark SVG 改编自公开的 [OpenCode repository](https://github.com/anomalyco/opencode)。`voice` 标记为本插件新增。
+- 本地转写使用 [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp)。
+- 模型下载 metadata 参考了 [Handy](https://github.com/cjpais/Handy) 的 local-first UX。
+
+---
+
+**OpenCode** [Website](https://opencode.ai) | [Docs](https://opencode.ai/docs) | [Discord](https://opencode.ai/discord)

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+The current `0.1.x` line receives security fixes while the project is actively maintained.
+
+## Reporting a Vulnerability
+
+If this repository is hosted on GitHub, use GitHub private vulnerability reporting when it is available. If private reporting is not available, contact a maintainer privately before sharing exploit details publicly.
+
+Please include:
+
+- affected version or commit;
+- operating system and Node.js version;
+- steps to reproduce;
+- expected impact;
+- any relevant logs with secrets removed.
+
+Avoid posting working exploits, downloaded model paths with private usernames, or environment variables in public issues.

package/assets/opencode-voice-dark.svg

@@ -0,0 +1,27 @@
+<svg width="396" height="42" viewBox="0 0 396 42" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title">
+  <title id="title">opencode voice</title>
+  <path d="M18 30H6V18H18V30Z" fill="#4B4646"/>
+  <path d="M18 12H6V30H18V12ZM24 36H0V6H24V36Z" fill="#B7B1B1"/>
+  <path d="M48 30H36V18H48V30Z" fill="#4B4646"/>
+  <path d="M36 30H48V12H36V30ZM54 36H36V42H30V6H54V36Z" fill="#B7B1B1"/>
+  <path d="M84 24V30H66V24H84Z" fill="#4B4646"/>
+  <path d="M84 24H66V30H84V36H60V6H84V24ZM66 18H78V12H66V18Z" fill="#B7B1B1"/>
+  <path d="M108 36H96V18H108V36Z" fill="#4B4646"/>
+  <path d="M108 12H96V36H90V6H108V12ZM114 36H108V12H114V36Z" fill="#B7B1B1"/>
+  <path d="M144 30H126V18H144V30Z" fill="#4B4646"/>
+  <path d="M144 12H126V30H144V36H120V6H144V12Z" fill="#F1ECEC"/>
+  <path d="M168 30H156V18H168V30Z" fill="#4B4646"/>
+  <path d="M168 12H156V30H168V12ZM174 36H150V6H174V36Z" fill="#F1ECEC"/>
+  <path d="M198 30H186V18H198V30Z" fill="#4B4646"/>
+  <path d="M198 12H186V30H198V12ZM204 36H180V6H198V0H204V36Z" fill="#F1ECEC"/>
+  <path d="M234 24V30H216V24H234Z" fill="#4B4646"/>
+  <path d="M216 12V18H228V12H216ZM234 24H216V30H234V36H210V6H234V24Z" fill="#F1ECEC"/>
+  <path d="M252 6H258V24H264V30H270V36H264V30H258V24H252V6ZM276 6H282V24H276V30H270V36H264V30H270V24H276V6Z" fill="#C4B5FD"/>
+  <path d="M306 30H294V18H306V30Z" fill="#6D28D9"/>
+  <path d="M306 12H294V30H306V12ZM312 36H288V6H312V36Z" fill="#C4B5FD"/>
+  <path d="M324 6H330V12H324V6ZM324 18H330V36H324V18Z" fill="#C4B5FD"/>
+  <path d="M366 30H348V18H366V30Z" fill="#6D28D9"/>
+  <path d="M366 12H348V30H366V36H342V6H366V12Z" fill="#C4B5FD"/>
+  <path d="M396 24V30H378V24H396Z" fill="#6D28D9"/>
+  <path d="M378 12V18H390V12H378ZM396 24H378V30H396V36H372V6H396V24Z" fill="#C4B5FD"/>
+</svg>

package/assets/opencode-voice-light.svg

@@ -0,0 +1,27 @@
+<svg width="396" height="42" viewBox="0 0 396 42" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title">
+  <title id="title">opencode voice</title>
+  <path d="M18 30H6V18H18V30Z" fill="#CFCECD"/>
+  <path d="M18 12H6V30H18V12ZM24 36H0V6H24V36Z" fill="#656363"/>
+  <path d="M48 30H36V18H48V30Z" fill="#CFCECD"/>
+  <path d="M36 30H48V12H36V30ZM54 36H36V42H30V6H54V36Z" fill="#656363"/>
+  <path d="M84 24V30H66V24H84Z" fill="#CFCECD"/>
+  <path d="M84 24H66V30H84V36H60V6H84V24ZM66 18H78V12H66V18Z" fill="#656363"/>
+  <path d="M108 36H96V18H108V36Z" fill="#CFCECD"/>
+  <path d="M108 12H96V36H90V6H108V12ZM114 36H108V12H114V36Z" fill="#656363"/>
+  <path d="M144 30H126V18H144V30Z" fill="#CFCECD"/>
+  <path d="M144 12H126V30H144V36H120V6H144V12Z" fill="#211E1E"/>
+  <path d="M168 30H156V18H168V30Z" fill="#CFCECD"/>
+  <path d="M168 12H156V30H168V12ZM174 36H150V6H174V36Z" fill="#211E1E"/>
+  <path d="M198 30H186V18H198V30Z" fill="#CFCECD"/>
+  <path d="M198 12H186V30H198V12ZM204 36H180V6H198V0H204V36Z" fill="#211E1E"/>
+  <path d="M234 24V30H216V24H234Z" fill="#CFCECD"/>
+  <path d="M216 12V18H228V12H216ZM234 24H216V30H234V36H210V6H234V24Z" fill="#211E1E"/>
+  <path d="M252 6H258V24H264V30H270V36H264V30H258V24H252V6ZM276 6H282V24H276V30H270V36H264V30H270V24H276V6Z" fill="#7C3AED"/>
+  <path d="M306 30H294V18H306V30Z" fill="#DDD6FE"/>
+  <path d="M306 12H294V30H306V12ZM312 36H288V6H312V36Z" fill="#7C3AED"/>
+  <path d="M324 6H330V12H324V6ZM324 18H330V36H324V18Z" fill="#7C3AED"/>
+  <path d="M366 30H348V18H366V30Z" fill="#DDD6FE"/>
+  <path d="M366 12H348V30H366V36H342V6H366V12Z" fill="#7C3AED"/>
+  <path d="M396 24V30H378V24H396Z" fill="#DDD6FE"/>
+  <path d="M378 12V18H390V12H378ZM396 24H378V30H396V36H372V6H396V24Z" fill="#7C3AED"/>
+</svg>

package/bin/opencode-voice.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const [command, ...args] = process.argv.slice(2);
+
+function hasFlag(flag) {
+  return args.includes(flag);
+}
+
+function help() {
+  console.log(`opencode-voice
+
+Usage:
+  opencode-voice install [--global] [--no-engine]
+  opencode-voice doctor [--json]
+  opencode-voice engine status whisper.cpp [--json]
+  opencode-voice engine install whisper.cpp
+  opencode-voice engine import whisper.cpp [path-to-whisper-cli]
+  opencode-voice engine remove whisper.cpp
+
+Development install from this checkout:
+  opencode plugin <path-to-this-checkout>
+`);
+}
+
+function packageName() {
+  const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  return process.env.OPENCODE_VOICE_PACKAGE || manifest.name || "opencode-voice";
+}
+
+async function runtime() {
+  const [engine, models, engines] = await Promise.all([import("../lib/engine.js"), import("../lib/models.js"), import("../lib/engines.js")]);
+  return { ...engine, ...models, ...engines };
+}
+
+async function doctor() {
+  const {
+    commandExists,
+    getAudioDir,
+    getCacheDir,
+    getEngineStatus,
+    getModelsDir,
+    listMicrophones,
+    probeEngine,
+  } = await runtime();
+
+  const engine = getEngineStatus("whisper.cpp");
+  const probe = engine.resolvedBinary ? await probeEngine("whisper.cpp", engine.resolvedBinary) : { ok: false, message: "missing binary" };
+  const payload = {
+    platform: `${process.platform}-${process.arch}`,
+    cacheDir: getCacheDir(),
+    modelsDir: getModelsDir(),
+    recordingsDir: getAudioDir(),
+    engine,
+    probe,
+    recorders: {
+      ffmpeg: commandExists("ffmpeg"),
+      arecord: commandExists("arecord"),
+      sox: commandExists("sox"),
+    },
+    microphones: listMicrophones(),
+  };
+
+  if (hasFlag("--json")) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(
+      [
+        "opencode-voice doctor",
+        "",
+        `Platform: ${payload.platform}`,
+        `Cache dir: ${payload.cacheDir}`,
+        `Models dir: ${payload.modelsDir}`,
+        `Recordings dir: ${payload.recordingsDir}`,
+        `Engine source: ${engine.source}`,
+        `Managed engine dir: ${engine.managedDir}`,
+        `whisper-cli: ${engine.resolvedBinary || "missing"}`,
+        `Probe: ${probe.ok ? "ok" : probe.message}`,
+        `Recorders: ffmpeg=${payload.recorders.ffmpeg ? "yes" : "no"}, arecord=${payload.recorders.arecord ? "yes" : "no"}, sox=${payload.recorders.sox ? "yes" : "no"}`,
+        `Microphones: ${payload.microphones.join(", ")}`,
+      ].join("\n"),
+    );
+  }
+
+  if (!engine.resolvedBinary || !probe.ok) process.exitCode = 1;
+}
+
+async function engineCommand() {
+  const [action, engineId = "whisper.cpp", maybePath] = args;
+  const { getEngineStatus, importManagedEngine, installManagedEngine, removeManagedEngine } = await runtime();
+
+  if (engineId !== "whisper.cpp") {
+    console.error(`Unsupported engine: ${engineId}`);
+    process.exit(1);
+  }
+
+  if (action === "status") {
+    const status = getEngineStatus(engineId);
+    if (hasFlag("--json")) console.log(JSON.stringify(status, null, 2));
+    else {
+      console.log(
+        [
+          `Engine: ${status.id}`,
+          `Platform: ${status.platform}`,
+          `Source: ${status.source}`,
+          `Resolved binary: ${status.resolvedBinary || "missing"}`,
+          `Managed binary: ${status.managedBinary}`,
+          `Managed installed: ${status.managedInstalled ? "yes" : "no"}`,
+          `Managed version: ${status.manifest?.version || "missing"}`,
+        ].join("\n"),
+      );
+    }
+    if (!status.resolvedBinary) process.exitCode = 1;
+    return;
+  }
+
+  if (action === "import") {
+    const status = getEngineStatus(engineId);
+    const source = maybePath || (status.source !== "managed" ? status.resolvedBinary : "");
+    const result = await importManagedEngine(engineId, source);
+    console.log(`Imported ${engineId}: ${result.managedBinary}`);
+    return;
+  }
+
+  if (action === "install") {
+    const result = await installManagedEngine(engineId, {}, {}, { onProgress: printEngineProgress, onRetry: printEngineRetry });
+    console.log(`Installed ${engineId}: ${result.managedBinary}`);
+    return;
+  }
+
+  if (action === "remove") {
+    const dir = await removeManagedEngine(engineId);
+    console.log(`Removed managed ${engineId}: ${dir}`);
+    return;
+  }
+
+  help();
+  process.exitCode = 1;
+}
+
+function printEngineProgress(progress) {
+  const label = {
+    registry: "registry",
+    downloading: "download",
+    verifying: "verify archive",
+    decompressing: "unpack",
+    "verifying-binary": "verify binary",
+    probing: "probe",
+    done: "done",
+  }[progress.state] || progress.state || "engine";
+  const percent = Number.isFinite(progress.percent) ? `${Math.round(progress.percent)}%` : "";
+  if (progress.state === "downloading" || progress.state === "done") console.log(`engine ${label} ${percent}`.trim());
+}
+
+function printEngineRetry({ error, nextAttempt, attempts }) {
+  console.warn(`engine retry ${nextAttempt}/${attempts}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+async function installCommand() {
+  const pluginArgs = args.filter((arg) => arg !== "--no-engine");
+  const result = spawnSync("opencode", ["plugin", packageName(), ...pluginArgs], { stdio: "inherit" });
+  if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+
+  if (!hasFlag("--no-engine")) {
+    const { installManagedEngine } = await runtime();
+    console.log("Installing managed voice engine...");
+    const engine = await installManagedEngine("whisper.cpp", {}, {}, { onProgress: printEngineProgress, onRetry: printEngineRetry });
+    console.log(`Managed voice engine ready: ${engine.managedBinary}`);
+  }
+}
+
+if (command === "install") await installCommand();
+else if (command === "doctor") await doctor();
+else if (command === "engine") await engineCommand();
+else help();