amical

环境要求

• macOS 系统（Homebrew 安装方式，需已安装 Homebrew）
• Git（克隆仓库并拉取子模块）
• Node.js 与 Corepack（本地开发需要，README 要求启用 Corepack 以使用固定版本 pnpm）
• pnpm（通过 Corepack 启用，无需单独全局安装）

安装与启动步骤

1. 1Homebrew 安装

   macOS 用户可直接用 Homebrew 的 cask 方式安装，安装完成后在启动台或应用程序目录找到 Amical。

   brew install --cask amical

   复制

2. 2或下载安装包

   非 macOS 或不想用 Homebrew，可打开 GitHub Releases 页面下载对应平台安装包（README 还提供 Android 与 Beta 入口）。

3. 3克隆仓库

   二次开发或本地运行源码时使用，务必带 --recurse-submodules，否则缺少 Whisper 源码。

   git clone --recurse-submodules https://github.com/amicalhq/amical.git

   复制

4. 4补全子模块

   如果克隆时忘记加 --recurse-submodules，进入仓库后执行此命令初始化并拉取全部子模块。

   cd amical
   git submodule update --init --recursive

   复制

5. 5启用 Corepack 并装依赖

   Corepack 会使用仓库固定的 pnpm 版本；pnpm install 会编译 Whisper 原生插件，可能耗时几分钟。

   corepack enable
   pnpm install --frozen-lockfile

   复制

6. 6下载 Node 二进制

   下载本地 Whisper worker 所使用的 Node.js 二进制文件，缺少它本地转录无法运行。

   pnpm --filter @amical/desktop download-node

   复制

7. 7运行检查

   提交 PR 前执行类型检查与测试，确认本地开发环境搭建正确、代码无回归。

   pnpm type:check
   pnpm test

   复制

如何确认成功

Homebrew 安装后能在应用程序中打开 Amical；源码方式下 pnpm type:check 与 pnpm test 均全部通过，无报错。

常见问题

注意事项

• README 未给出源码方式的启动命令，本教程只覆盖官方提供的安装、克隆、依赖安装与检查步骤。
• Amical 为本地优先应用，音频处理可在本机完成，离线也能使用。
• 提交 PR 前务必先跑 pnpm type:check 和 pnpm test。