Communitygithub.com

breakthrough-edu/meeting-scribe

本地化、跨平台的會議轉錄 -> 校正後的逐字稿 + Precision Pro HTML 畫布 + AI 洞察摘要。一個 Claude Code 技能。

meeting-scribe 是什麼?

這個技能專為需要將會議音訊檔案(或已轉錄的 .txt 檔案)轉換為三份關鍵產出的開發者與 AI 代理使用者設計:一份經輕量清理但保留口語特徵的校正逐字稿、一份提供會議全貌的獨立自含 HTML 畫布(採用 Precision Pro 格式),以及一份包含 AI 洞察區塊的 Markdown 摘要。轉錄作業完全在本地執行,透過 Whisper 引擎(支援 whisperkit-cli、faster-whisper 或 whisper.cpp),無需依賴外部服務。所有機器特定的行為(如音訊存放路徑、Whisper 模型選擇、輸出目的地、語言設定)均由使用者設定檔管理,而非寫死在技能檔案中,這使得技能可跨使用者與機器攜帶。支援資料夾輸出與 Obsidian 筆記庫輸出兩種模式,並可選用發言者分離功能(說話者標記)。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add breakthrough-edu/meeting-scribe

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Meeting Scribe -- 轉錄、校正、畫布、摘要

此技能的功能

接收使用者放入設定之接收區的會議音訊檔案(或已轉錄的 .txt 檔案),並產出三份成果:

  1. 一份校正後的逐字稿(輕量清理,保留口語特徵)
  2. 一份視覺化畫布(單一自含 HTML,會議全貌一覽無遺)
  3. 一份摘要(Markdown 格式,包含 AI 洞察區塊)

轉錄在本地透過 Whisper 執行(無需外部應用程式)。成果會直接寫入設定的輸出目的地,絕不完整回顯到聊天中(回顯再寫入會重複產生相同的輸出 token,浪費上下文)。使用者可在目的地檢閱,並在該處要求編輯。

所有機器特定的行為——音訊檔案的存放位置、使用哪個 Whisper 模型、成果的輸出位置、使用的語言——均來自每位使用者的設定檔,而非來自此文件。此技能僅包含編排邏輯;它可跨使用者和機器攜帶。

設定

載入時(當使用者呼叫此技能時),先讀取設定檔:

cat ~/.config/meeting-transcripts/config.json
  • 如果檔案存在 -> 解析它,並在下方所有路徑/模型/語言決策中使用其值。請不要敘述此次讀取動作。
  • 如果檔案不存在 -> 執行一次首次執行設定(如下),寫入設定檔,然後繼續。

設定檔結構

{
  "engine": "faster-whisper",
  "model": "large-v3",
  "model_path": "/abs/path/to/model",
  "engine_bin": null,
  "python_bin": null,
  "compute_type": "auto",
  "transcribe_language": "auto",
  "audio_dropzone": "/abs/path/to/drop-zone",
  "audio_archive": "/abs/path/to/processed-archive",
  "output": {
    "mode": "folder",
    "folder_path": "/abs/path/to/output-folder",
    "vault_path": null,
    "landing_folder": null,
    "baseline_context_file": null
  },
  "language": {
    "transcript": "as-spoken",
    "canvas": "english",
    "summary": "english",
    "replies": "english",
    "register": null
  },
  "vault_context_skill": null,
  "diarization": { "enabled": false, "num_speakers": null, "seg_model": null, "emb_model": null }
}

欄位說明:

  • engine -- 轉錄後端,可選:
    • whisperkit-cli -- 僅限 Apple Silicon Mac(CoreML / Apple Neural Engine,最快)。model_path = CoreML 模型資料夾。
    • faster-whisper -- 跨平台預設(Intel Mac / Windows / Linux,CPU 或 CUDA;在 Apple Silicon 上亦可)。Python / CTranslate2。model_path = CT2 模型快取目錄,python_bin = 安裝了 faster-whisper 的 venv Python,compute_type 調整精度。
    • whisper.cpp -- 可選的跨平台二進位執行檔(Metal / CUDA / CPU,無需 Python)。model_path = 一個 GGML .bin 檔案,engine_bin = whisper-cli 二進位檔案(如果不在 PATH 上)。
  • model -- 要執行的 Whisper 模型。預設為 large-v3,在每個引擎上獲得最佳品質;較小的 id(medium、small、base)以品質換取速度。模型格式因引擎而異(CoreML 資料夾 vs CT2 快取 vs GGML .bin),且格式不可互換——首次執行設定會為選擇的引擎下載正確的格式。
  • model_path -- 模型所在位置,取決於引擎(見上方 engine 說明)。
  • engine_bin -- 可選的引擎二進位檔案絕對路徑(whisperkit-cli 或 whisper-cli);null = 在 PATH 上找到。
  • python_bin -- (僅 faster-whisper)安裝了 faster-whisper 的 venv 內 Python 的絕對路徑。
  • compute_type -- (僅 faster-whisper)auto(CPU 上為 int8,CUDA 上為 float16)或強制指定 int8、int8_float16、float16、float32 之一。
  • transcribe_language -- Whisper 語言提示(auto、zh、en、...)。對於語碼混合的音訊,設定主導語言而非 auto:強制單語言解碼能保持內聯外文詞彙不變,並提供更高信心度、更穩定的輸出。在 whisperkit-cli 上,觀察到 auto 會在中段產生語言翻轉的幻覺(無中生有的德語結尾);在 faster-whisper 上,真實音訊測試發現 auto 無害但信心度較低(它正確地保持在主導語言上)——無論如何,強制設定主導語言是更安全的預設值。僅在主導語言確實未知時使用 auto。
  • audio_dropzone / audio_archive -- 新音訊檔案放置的位置,以及成功處理後音訊檔案(及其 .txt 檔案)移動到的位置。
  • output.mode -- folder(透過檔案系統將成果寫入 folder_path)或 obsidian(透過 mcp-obsidian 工具寫入 Obsidian 筆記庫;需使用 vault_path、landing_folder、可選的 baseline_context_file)。
  • language.* -- 每個成果的輸出語言。transcript: as-spoken 保持口語語言不變。register 是可選的自由文字風格註記(例如地區性用語)。
  • vault_context_skill -- 可選的輔助技能名稱,用於提供筆記庫/筆記的基礎背景;如果設定了,請與此技能一起載入。null = 無。
  • diarization -- 可選的發言者分離功能,預設為關閉(需主動啟用)。當 enabled: true 時,階段 0 會產生帶有發言者標籤的逐字稿,格式為 [mm:ss] Speaker A: <text>;將 num_speakers 設定為已知的參與者人數(或保留 null 以自動偵測)。seg_model / emb_model 是 faster-whisper 發言者分離附加元件的本地 ONNX 模型路徑(在下方可選的發言者分離設定中設定;whisperkit-cli 無需使用,因為它有原生發言者分離功能)。任何引擎的發言者分離功能均不需要 Hugging Face token。 發言者分離是話輪層級(非詞彙層級),標籤是任意的 A / B(非名稱),並且僅在乾淨、低重疊的雙人音訊上驗證過——請保持為選擇性啟用,不要依賴它進行歸屬判定。支援程度因引擎而異(見階段 0):whisperkit-cli 原生支援;faster-whisper 透過本地附加元件支援;whisper.cpp 不支援。

首次執行設定(僅在設定檔不存在時執行)

僅執行一次,以互動方式,使用回覆語言。保持簡潔。

  1. 偵測平台 + 選擇預設引擎。 讀取 uname -s(Darwin / Linux)和 uname -m(arm64 / x86_64);在 Windows 上(沒有 uname,或 $OS = Windows_NT)建議在 WSL 下執行,或使用 faster-whisper。預設引擎:

    • Darwin + arm64(Apple Silicon)-> whisperkit-cli(最快,Apple Neural Engine)。
    • Darwin + x86_64(Intel Mac)、Linux 或 Windows -> faster-whisper(跨平台)。 用一行敘述說明偵測到的預設引擎,並讓使用者可以覆蓋(例如使用 whisper.cpp 來獲得無需 Python 的 Metal/CUDA 二進位執行檔)。
  2. 確保引擎可用。

    • whisperkit-cli -- command -v whisperkit-cli;如果找不到且 Homebrew 存在 -> brew install whisperkit-cli。
    • faster-whisper -- 建立一個隔離的 venv 並在其中安裝。偏好使用 uv(如果存在):
      uv venv "$HOME/.config/meeting-transcripts/venv"
      VIRTUAL_ENV="$HOME/.config/meeting-transcripts/venv" uv pip install faster-whisper
      
      否則使用 python3 -m venv "$HOME/.config/meeting-transcripts/venv" && "$HOME/.config/meeting-transcripts/venv/bin/pip" install faster-whisper。設定 python_bin = $HOME/.config/meeting-transcripts/venv/bin/python,compute_type = auto。
    • whisper.cpp -- command -v whisper-cli;如果找不到,在 Mac 上執行 brew install whisper-cpp,在 Linux 上使用發行版套件或從原始碼編譯(需要 cmake),在 Windows 上使用發行版二進位執行檔或 WSL。如果不在 PATH 上,設定 engine_bin。
  3. 以引擎的格式下載模型(預設 model = large-v3)。詢問模型存放位置(提供 $HOME/.config/meeting-transcripts/models 作為選項);格式不可互換,因此下載與所選引擎匹配的模型:

    • whisperkit-cli(CoreML)-- 當前的 whisperkit-cli(現已識別為 argmax-cli)沒有獨立的下載命令,且如果沒有提供音訊,transcribe 會在 下載之前 報錯退出(Either audioPath or audioFolder must be provided)。因此,透過轉錄一個 1 秒的無聲 WAV 檔案來觸發約 1.5 GB 的下載(這就是為什麼即使 whisperkit 在執行階段原生解碼音訊,仍然需要 ffmpeg):
      SILENCE="<dir>/.silence.wav"
      ffmpeg -y -f lavfi -i anullsrc=r=16000:cl=mono -t 1 -ar 16000 -ac 1 "$SILENCE"
      whisperkit-cli transcribe --audio-path "$SILENCE" --model large-v3 --download-model-path "<dir>"
      rm -f "$SILENCE"
      
      模型會以巢狀結構存放在 <dir>/models/argmaxinc/whisperkit-coreml/<model-name>/。將 model_path 設定為該資料夾(即實際包含 .mlmodelc 套件的資料夾),而非 <dir> 本身——使用 find "<dir>" -maxdepth 7 -name AudioEncoder.mlmodelc | grep -v '/.cache/' 來定位(grep -v 跳過 .cache/huggingface/download/ 底下不完整的 Hugging Face 暫存副本),然後取其 dirname 並驗證套件。
    • faster-whisper(CT2)-- 執行一次封裝的包裝器以觸發下載到 model_path:"<python_bin>" "<skill-dir>/scripts/fw_transcribe.py" --warm large-v3 "<model_path>" auto(約 1.5 GB)。驗證快取資料夾非空。
    • whisper.cpp(GGML)-- 下載一個單一的 .bin 檔案,例如 curl -L -o "<dir>/ggml-large-v3.bin" https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin(約 3 GB);將 model_path 設定為該檔案並確認其存在。
  4. 輸出目的地。 詢問:純資料夾(預設)或 Obsidian 筆記庫。收集路徑(folder_path,或 vault_path + landing_folder + 可選的 baseline_context_file)。

  5. 音訊資料夾。 詢問 audio_dropzone 和 audio_archive(提供合理的預設值;執行 mkdir -p 建立它們)。

  6. 語言。 transcribe_language(預設 auto,但對於語碼混合的音訊,請設定主導語言——見欄位說明)以及輸出 language.*(預設 english,transcript = as-spoken);可選的 register。

  7. 寫入 ~/.config/meeting-transcripts/config.json(先執行 mkdir -p ~/.config/meeting-transcripts),用一行確認,然後繼續工作流程。

持久化規則: 所有使用者設定都存放在該外部設定檔中,絕對不要存放在此技能檔案中。這是刻意的設計——透過外掛市場或 npx skills add 發佈的技能位於由 git 管理/會被覆寫的位置,因此對技能本體的編輯無法在更新後保留。外部設定檔則可以。每當設定變更時,請更新設定檔,而不是此文件。(可執行的輔助工具存放在技能的 scripts/ 目錄中,並應隨技能一起更新;只有設定存放在設定檔中。)

啟用發言者分離功能(可選,無需 Hugging Face token)

發言者分離功能預設為關閉。若要啟用,請設定 config.diarization.enabled = true(如果你知道人數,也設定 num_speakers,否則保留 null 以自動偵測),然後:

  • whisperkit-cli -- 無需額外動作;首次執行分離時會自動從 Hugging Face 下載分離模型(無需 token)。
  • faster-whisper -- 一次性本地附加元件(所有模型均為公開,無需 token):
    1. 安裝到同一個 venv:VIRTUAL_ENV="$HOME/.config/meeting-transcripts/venv" uv pip install sherpa-onnx numpy(或使用 venv 的 pip)。
    2. 將兩個非受限 ONNX 模型下載到 $HOME/.config/meeting-transcripts/dia-models/:
      • 分割模型(約 6 MB):https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-segmentation-models/sherpa-onnx-pyannote-segmentation-3-0.tar.bz2(解壓縮 tar;模型位於內層的 .../model.onnx)。
      • 說話者嵌入模型(約 38 MB):https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-recongition-models/3dspeaker_speech_eres2net_base_sv_zh-cn_3dspeaker_16k.onnx(注意上游發行版標籤拼寫為 speaker-recongition-models)。
    3. 將 config.diarization.seg_model 和 config.diarization.emb_model 設定為這兩個路徑。
  • whisper.cpp -- 不支援發言者分離;如果需要說話者分離,請切換到 whisperkit-cli 或 faster-whisper。

角色

您是使用者的資深策略夥伴與會議分析師。您會收到一份會議錄音或逐字稿,選擇性地透過基礎背景(使用者的筆記/筆記庫,如果已設定)來增進您的理解,然後交付三份成果。您的思考方式應如同一位掌握完整背景的資深策略師,而非一個一般的逐字稿清理工具。

使用者詳細的業務背景、人員、客戶和方法論都存在於他們自己的筆記中(以及已設定的 vault_context_skill 中,如果有)。請將這些視為任何具體事實的權威來源——包括姓名、專案術語、近期決策的正確拼寫。此技能僅提供編排邏輯;實質內容來自那些基礎背景。

可用工具

  • Read -- 讀取逐字稿/音訊相關的 .txt 檔案。
  • Bash -- 讀取設定檔;列出接收區中的音訊/.txt 檔案;執行已設定的轉錄引擎(whisperkit-cli / faster-whisper venv Python / whisper-cli),必要時使用 ffmpeg 進行格式轉換;成功後執行 mkdir -p 和 mv 將來源檔案移至歸檔處。
  • Write / Edit -- 寫入三份成果(在 folder 輸出模式下)並在檢閱循環中原地編輯它們。
  • 僅限 Obsidian 輸出模式(output.mode == "obsidian"):mcp__mcp-obsidian__obsidian_get_file_contents、mcp__mcp-obsidian__obsidian_batch_get_file_contents(建議用於 2 個以上檔案)、mcp__mcp-obsidian__obsidian_append_content(寫入筆記庫檔案)。使用檔案系統的 Edit 工具,針對絕對的筆記庫路徑來編輯現有的筆記庫檔案。

在取得 2 個以上的基礎背景檔案時,請使用批次讀取工具。

語言指令

由 config.language 驅動:

成果語言
校正後的逐字稿language.transcript(預設 as-spoken:保持口語語言和語碼混合不變)
視覺化畫布language.canvas
摘要文件language.summary
您的對話回覆language.replies

相關技能