Meetily 0.4.1 常用 CLI 命令与工具详解

目标：把 Meetily v0.4.1 源码树里所有可执行脚本与二进制一次讲清——构建主线 build-gpu.sh、pnpm 脚本别名、GPU 探测脚本、Whisper 模型下载脚本、llama-helper/ffmpeg 两个 sidecar 的验证与内部协议。每条命令都在 Ubuntu 22.04 (x86_64)、源码目录 /root/work/meetily（v0.4.1 标签）实测，回显逐行照抄；构建安装背景与参数含义见《Ubuntu 22.04 安装 Meetily 0.4.1 指南》与《Meetily 0.4.1 配置参数详解》。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Meetily 版本：v0.4.1（源码标签 v0.4.1，2026-10-23 实查 GitHub Releases 最新稳定版）
• 源码目录：/root/work/meetily（下文相对路径均基于此目录）
• 工具链：Node.js v20.20.2 / pnpm 9.15.9 / rustc 1.99.1 / cmake 3.22.1 / ffmpeg 4.4.2（均实测）
• 应用形态：Tauri 2 桌面应用；本体无常驻 CLI，本文所述为源码树自带脚本、Tauri CLI 与 sidecar 二进制

二、工具概览

Meetily 的「命令资产」分四类，先给全景再逐个展开：

三、前置条件

1. 已按《Ubuntu 22.04 安装 Meetily 0.4.1 指南》完成工具链安装与依赖拉取（Node 20 + pnpm 9.15.9 + Rust + Tauri 系统库），本文脚本均在该基础上执行。
2. llama-helper/ffmpeg 的验证示例使用构建产物路径；未构建时可先跑第四章脚本得到产物。
3. 模型下载脚本需访问 Hugging Face，网络受限时按环境挂代理（export https_proxy=http://<代理>:<端口> 后再执行）。

四、构建与开发脚本详解

4.1 build-gpu.sh：一键构建主线（推荐入口）

位于 frontend/build-gpu.sh，内部依次完成：GPU 特性探测（调 scripts/auto-detect-gpu.js）→ 编译 llama-helper sidecar 并复制到 src-tauri/binaries/（带目标三元组命名）→ pnpm run tauri:build（Next.js 生产构建 + Rust 编译 + 打包）。无 GPU 时自动落回 CPU-only。

cd /root/work/meetily/frontend
./build-gpu.sh

实测回显（开头，CPU 环境探测与 sidecar 编译段）：

🚀 Meetily GPU-Accelerated Build Script

📦 Building Meetily...

🔍 Detecting GPU features...
💻 No GPU acceleration available - using CPU-only mode
⚠️ No specific GPU feature detected or forced

🦙 Building llama-helper sidecar (release)...
   Building in /root/work/meetily/frontend/../llama-helper with features: none

实测回显（收尾，Rust 编译与打包段；linuxdeploy 组件下载行从略）：

warning: `meetily` (lib) generated 9 warnings (run `cargo fix --lib -p meetily` to apply 5 suggestions)
    Finished `release` profile [optimized] target(s) in 1m 13s
       Built application at: /root/work/meetily/target/release/meetily
        Info Patching /root/work/meetily/target/release/meetily with bundle type information: deb
    Bundling meetily_0.4.1_amd64.deb (/root/work/meetily/target/release/bundle/deb/meetily_0.4.1_amd64.deb)
        Info Patching /root/work/meetily/target/release/meetily with bundle type information: appimage
    Bundling meetily_0.4.1_amd64.AppImage (/root/work/meetily/target/release/bundle/appimage/meetily_0.4.1_amd64.AppImage)
    Finished 2 bundles at:
        /root/work/meetily/target/release/bundle/deb/meetily_0.4.1_amd64.deb
        /root/work/meetily/target/release/bundle/appimage/meetily_0.4.1_amd64.AppImage

要点：Finished \release` profile [optimized] target(s) in 1m 13s为缓存命中后的增量时长，首次构建需数十分钟；产物落顶层target/release/bundle/（Rust 工作区共享 target 目录）；构建收尾若报 TAURI_SIGNING_PRIVATE_KEY` 缺失属更新器签名行为，不影响主产物（实测处置见安装指南 4.8）。

4.2 pnpm run 脚本别名族

frontend/package.json 的 scripts 段定义了全部快捷入口（实测查看）：

cd /root/work/meetily/frontend && node -e "console.log(JSON.stringify(require('./package.json').scripts, null, 2))"

实测回显（21 个脚本全集）：

{
  "dev": "next dev -p 3118",
  "build": "next build",
  "export": "next export",
  "start": "next start -p 3118",
  "tauri": "tauri",
  "tauri:dev": "node scripts/tauri-auto.js dev",
  "tauri:build": "node scripts/tauri-auto.js build",
  "tauri:dev:cpu": "tauri dev",
  "tauri:dev:cuda": "tauri dev -- --features cuda",
  "tauri:dev:vulkan": "tauri dev -- --features vulkan",
  "tauri:dev:metal": "tauri dev -- --features metal",
  "tauri:dev:coreml": "tauri dev -- --features coreml",
  "tauri:dev:openblas": "tauri dev -- --features openblas",
  "tauri:dev:hipblas": "tauri dev -- --features hipblas",
  "tauri:build:cpu": "tauri build",
  "tauri:build:cuda": "tauri build -- --features cuda",
  "tauri:build:vulkan": "tauri build -- --features vulkan",
  "tauri:build:metal": "tauri build -- --features metal",
  "tauri:build:coreml": "tauri build -- --features coreml",
  "tauri:build:openblas": "tauri build -- --features openblas",
  "tauri:build:hipblas": "tauri build -- --features hipblas",
  "lint": "next lint"
}

速记规则：

⚠️ 注意：直接 pnpm run tauri:build 前必须保证 src-tauri/binaries/ 下已有两个 sidecar（build-gpu.sh 会自动补齐；手动补齐命令见安装指南 4.8 排障实录一/二）。

4.3 clean_build.sh：全量清理重建

frontend/clean_build.sh 用于排除缓存干扰的干净构建：清理 target/、src-tauri/target、src-tauri/gen、node_modules、.next、out 后重走安装与打包。支持日志级别参数（源码实测，取值 info/debug/trace，默认 info，非法值直接退出）：

cd /root/work/meetily/frontend
./clean_build.sh debug

关键源码行为（文件头实测摘录）：

LOG_LEVEL=${1:-info}

case $LOG_LEVEL in
    info|debug|trace)
        export RUST_LOG=$LOG_LEVEL
        ;;
    *)
        echo "Invalid log level: $LOG_LEVEL. Valid options: info, debug, trace"
        exit 1
        ;;
esac

即 RUST_LOG 由该参数注入，排障 Rust 侧逻辑用 ./clean_build.sh trace。清理动作（源码实测）：

rm -rf target/
rm -rf src-tauri/target
rm -rf src-tauri/gen
rm -rf node_modules
rm -rf .next
rm -rf out

随后自动 pnpm install → pnpm run build → pnpm run tauri build。⚠️ 两点提醒：其一，脚本内的 CMake 自检依赖 Homebrew（brew install cmake），这是 macOS 向写法，Linux 上 CMake 用 apt 维护（已装则该分支不触发，不影响执行）；其二，全量清理后首次构建回到数十分钟量级，无必要时用 build-gpu.sh 增量构建即可。

4.4 clean_run.sh：清理后进开发模式

frontend/clean_run.sh 与 4.3 的区别只在最后一步——清理重建后执行 pnpm run tauri dev（开发模式，前端热更新，devUrl http://localhost:3118），同样接受 info|debug|trace 日志级别参数。开发调试界面时用它；验证发布产物时用 4.3 或 4.1。

4.5 dev-gpu.sh：GPU 开发模式

frontend/dev-gpu.sh 是面向 GPU 机器的开发入口：Linux 上自动导出 CMAKE_CUDA_ARCHITECTURES=75、CMAKE_CUDA_STANDARD=17、CMAKE_POSITION_INDEPENDENT_CODE=ON（源码头 40 行实测），随后按 OS 探测进入开发模式。显存/算力与架构对照（算力查询命令 nvidia-smi --query-gpu=compute_cap --format=csv）见安装指南第五章。

五、GPU 能力探测脚本

auto-detect-gpu.js 是构建特性决策的事实来源（build-gpu.sh 与 tauri-auto.js 都调它），直接运行可预演探测结果：

cd /root/work/meetily/frontend && node scripts/auto-detect-gpu.js

实测回显（无 GPU SDK 的环境）：

💻 No GPU acceleration available - using CPU-only mode

探测优先级（CUDA → ROCm(hipblas) → Vulkan → OpenBLAS → CPU）与各路线前置安装见《Ubuntu 22.04 安装 Meetily 0.4.1 指南》第五章 5.1 表；不依赖探测时用 TAURI_GPU_FEATURE 环境变量强制指定（cuda/hipblas/vulkan/openblas，空串=强制 CPU）。

六、Whisper 模型管理脚本

6.1 download-ggml-model.sh 用法

backend/download-ggml-model.sh 是 whisper.cpp 血统的模型下载脚本（Meetily 应用内模型下载走 Rust 引擎内置 URL 表，见配置篇 6.1；本脚本用于命令行批量/离线场景）。无参数运行即打印用法（实测）：

sh /root/work/meetily/backend/download-ggml-model.sh

实测回显：

Usage: /root/work/meetily/backend/download-ggml-model.sh <model> [models_path]

Available models:
  tiny tiny.en tiny-q5_1 tiny.en-q5_1 tiny-q8_0
  base base.en base-q5_1 base.en-q5_1 base-q8_0
  small small.en small.en-tdrz small-q5_1 small.en-q5_1 small-q8_0
  medium medium.en medium-q5_0 medium.en-q5_0 medium-q8_0
  large-v1 large-v2 large-v2-q5_0 large-v2-q8_0 large-v3 large-v3-q5_0 large-v3-turbo large-v3-turbo-q5_0 large-v3-turbo-q8_0

___________________________________________________________
.en = english-only -q5_[01] = quantized -tdrz = tinydiarize

签名：download-ggml-model.sh <model> [models_path]——model 取上方清单中的名字（比应用内 12 个模型目录更全，共 33 个变体，含英文专精 .en 与 tinydiarize 变体）；models_path 省略时下载到脚本所在目录。下载源为脚本头部定义（实测）：

src="https://huggingface.co/ggerganov/whisper.cpp"
pfx="resolve/main/ggml"

传入未知名时的行为（实测，列表回显同上，首行报错）：

sh /root/work/meetily/backend/download-ggml-model.sh list

Invalid model: list

6.2 实测下载示例

下载 74 MB 的 tiny 模型到 backend/ 目录（跨境网络挂代理后实测）：

export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897
cd /root/work/meetily/backend
sh download-ggml-model.sh tiny /root/work/meetily/backend

实测回显（进度行 + 收尾提示）：

100 74.0M  100 74.0M    0     0  10.5M      0  0:00:07  0:00:07 --:--:-- 16.6M
Done! Model 'tiny' saved in '/root/work/meetily/backend/ggml-tiny.bin'
You can now use it like this:

  $ ./build/bin/whisper-cli -m /root/work/meetily/backend/ggml-tiny.bin -f samples/jfk.wav

ls -lh /root/work/meetily/backend/ggml-tiny.bin

-rw-r--r-- 1 root root 75M Oct 23 06:54 /root/work/meetily/backend/ggml-tiny.bin

收尾提示里的 whisper-cli 用法是 whisper.cpp 通用提示（独立 whisper 工具链的用法）；Meetily 应用侧使用模型时，把 .bin 文件放入应用数据目录的模型目录即可被扫描识别（路径与命名规则见配置篇 6.1）。

七、Sidecar 外部二进制

7.1 llama-helper：本地摘要推理 sidecar

llama-helper 是 llama.cpp 的 Rust 封装（源码 llama-helper/），以「stdin/stdout 交换 JSON 报文」的协议工作，应用按需拉起、空闲 300 秒自动退出。验证二进制可用性（最小报文，ping 必须小写）：

echo '{"type":"ping"}' | /root/work/meetily/target/release/llama-helper

实测回显：

🦙 llama-helper starting (idle timeout: 300s)
{"type":"pong"}
📪 EOF received, shutting down

协议外的变体名会得到错误回包（实测，注意大小写敏感）：

❌ Failed to parse request: unknown variant `Ping`, expected one of `generate`, `ping`, `shutdown` at line 1 column 14
{"type":"error","message":"Invalid request: unknown variant `Ping`, expected one of `generate`, `ping`, `shutdown` at line 1 column 14"}

generate 请求的全部参数（prompt/max_tokens/context_size/model_path 与 temperature/top_k/top_p 等采样参数）逐项含义见《Meetily 0.4.1 配置参数详解》5.5，此处不重复。正常使用无需手工调用，它由应用在「builtin-ai」摘要时自动管理。

7.2 ffmpeg：音频解码 sidecar

ffmpeg 是音频导入/转码的外部二进制。Tauri 打包要求其以「名称-目标三元组」命名放在 src-tauri/binaries/（克隆仓库不含二进制，需从系统复制，命令见安装指南 4.8 排障实录二）。构建完成后实测核对：

ls -la /root/work/meetily/frontend/src-tauri/binaries/

实测回显：

-rwxr-xr-x  1 root root  301544 Oct 23 00:28 ffmpeg-x86_64-unknown-linux-gnu
-rwxr-xr-x  1 root root 5053656 Oct 23 06:40 llama-helper-x86_64-unknown-linux-gnu

验证 ffmpeg 自身版本（sidecar 与系统包同源，Ubuntu 22.04 实测）：

/root/work/meetily/frontend/src-tauri/binaries/ffmpeg-x86_64-unknown-linux-gnu -version | head -2

实测回显：

ffmpeg version 4.4.2-0ubuntu0.22.04.1 Copyright (c) 2000-2021 the FFmpeg developers
built with gcc 11 (Ubuntu 11.2.0-19ubuntu1)

八、遗留脚本与归档说明

backend/ 下还有一批 Python/FastAPI 旧后端脚本（clean_start_backend.sh、start_python_backend.sh、run-docker.sh、start_whisper_server.sh 等，围绕 5167/8178 端口与 whisper-server-package 目录工作）。v0.4.1 官方在 backend/SCRIPTS_DOCUMENTATION.md 中已明确归档（原文实查）：「The legacy scripts in this directory are retained only for historical reference…Do not use them for new installs, production deployments, or contributor setup」，当前受支持的形态只有 frontend/ 下的 Tauri 应用。新装环境不要执行这批脚本；其配置文件（temp.env/set_env.sh）与端口语义见《Meetily 0.4.1 配置参数详解》第八章。

九、注意事项

1. 入口选择：日常构建一律 ./build-gpu.sh；仅当排查「缓存污染」类问题时才用 clean_build.sh 全量重建。绕过 build-gpu.sh 直接 pnpm run tauri:build 会因 sidecar 缺失失败（排障见安装指南 4.8）。
2. 日志级别：三个辅助脚本的 RUST_LOG 参数只接受 info|debug|trace，传其他值立即退出——脚本不吞错，报错行本身即实测回显（4.3）。
3. 模型脚本与应用内下载的关系：download-ggml-model.sh 面向命令行/离线场景，模型清单（33 个）比应用内（12 个）更全；应用内点击下载走 Rust 内置 URL 表，两者同源（Hugging Face ggerganov/whisper.cpp），文件通用。
4. sidecar 命名不可改：*-x86_64-unknown-linux-gnu 后缀是 Tauri externalBin 的硬性规则，手工替换二进制时必须保持命名，否则打包再次失败。
5. 产物位置：deb/AppImage 固定落顶层 /root/work/meetily/target/release/bundle/（Rust 工作区共享 target），不要去 frontend/src-tauri/target/ 下找。

十、常见问题（FAQ）

Q1：./build-gpu.sh 停在 Blocking waiting for file lock on build directory？ 有另一个 cargo 进程占着同一 target 目录（常见于上一次构建未退出或并发跑了两个构建）。等待其退出即可自动继续；确认无构建需求时 pkill -f "cargo build" 释放锁，缓存不丢。

Q2：Rust 编译阶段报 failed to run custom build command for ort-sys 且提到 cdn.pyke.io 下载超时？ ort-sys 构建脚本要从 pyke.io CDN 下载 onnxruntime 预编译包，网络受限直连超时（实测两次复现）。解决：构建会话内 export https_proxy=http://<代理>:<端口> 后重跑 ./build-gpu.sh，已编译依赖命中缓存、仅补下载（完整实录见安装指南 4.8 排障实录四）。

Q3：download-ggml-model.sh 下载慢/中断怎么办？ 脚本用 curl 直连 Hugging Face，慢时先挂代理再执行（6.2 实测 74 MB 用时 7 秒）；中断后重跑同名命令即续传/覆盖。也可以在任何能联网的环境下载后把 .bin 拷到目标机器的模型目录。

Q4：pnpm run tauri:build:cuda 报找不到特性或编译错误？ 显式特性脚本不做环境检查，对应 SDK（CUDA toolkit/Vulkan SDK/OpenBLAS 头文件）未装或环境变量（CUDA_PATH/VULKAN_SDK/BLAS_INCLUDE_DIRS）未设时会以编译错误收场。先用 node scripts/auto-detect-gpu.js 预演探测（第五章），或回退 ./build-gpu.sh 自动决策。

Q5：llama-helper 手动调用后进程一直在？ 空闲 300 秒自动退出（启动横幅标注 idle timeout: 300s，实测 7.1）；也可发送 {"type":"shutdown"} 立即结束，或直接 Ctrl-D 结束 stdin（收到 EOF 后退出，实测回显第三行）。

十一、参考链接

• 源码构建安装全流程（含全部排障实录）：《Ubuntu 22.04 安装 Meetily 0.4.1 指南》
• 配置参数与模型资产详解：《Meetily 0.4.1 配置参数详解》
• 软件定位与同类选型：《Meetily 介绍与选型指南》
• 官方仓库：https://github.com/Zackriya-Solutions/meetily （脚本源码：frontend/build-gpu.sh、frontend/scripts/tauri-auto.js、backend/download-ggml-model.sh、llama-helper/src/main.rs）
• Tauri CLI 文档（signer/build/dev 子命令）：https://tauri.app
• whisper.cpp 官方模型仓库：https://huggingface.co/ggerganov/whisper.cpp