錄音轉Obsidian筆記是做什麼的？

將一場會議或一堂課，轉換為 Obsidian 知識庫中獨立且完整連結的一部分。兩種模式共用相同的處理管線、慣例與驗證步驟；差別在於萃取的重點與筆記的形式。

	會議模式	課程模式
目的	記住決定了什麼、由誰在何時前完成什麼	隨時快速重新學習概念
中心頁	每次會議一個會議中心 + 一個系列 MOC（每場會議一條記錄）	每堂課一個 MOC
主體筆記	ADR 風格的決策記錄；持久性知識的主題筆記	重點筆記 (密集) + 原子筆記 (一個概念一則)
可追溯性	決策與行動項目附帶逐字稿時間戳記 `[00:12:34]`	PDF++ 投影片連結 `[[deck.pdf#page=5]]`；僅口頭內容附時間戳記
參考文件	`references/meeting-mode.md`	`references/lecture-mode.md`

<skill> 指的是此檔案所在的資料夾。

1. 處理管線

素材 ──► 1 設定 ──► 2 轉錄 ──► 3 選擇模式 ──► 4 筆記寫手 ──► 5 驗證 ──► 6 報告
          設定檔,      scripts/          會議或       寫入筆記      check_vault
          python       transcribe.py     課程           (一個子代理)   scan_secrets

1.1 設定

首先記錄開始時間：執行 date +%s 並記住該數字；驗證階段只檢查此時間之後寫入的筆記。

讀取 <skill>/config.toml。它設定轉錄後端/模型/語言、說話者辨識、notes.output_language、notes.default_mode 以及知識庫資料夾名稱（notes_dir、moc_dir、meetings_dir、sources_dir；下方使用預設值）。腳本的直譯器為 runtime.python；若為空則使用 ~/.local/share/recording-to-obsidian/venv/bin/python。稱之為 $PY——這只是標記：在指令中請寫出直譯器與腳本的完整字面路徑，每個指令單獨呼叫，不要使用 shell 變數或 cd … && 鏈（代理權限規則比對字面指令，變數會使檢查失效）。如果它不存在，請告知使用者執行 install.sh (README)——不要將 pip 安裝到使用者自己的 Python 環境中。

在進行任何其他操作之前，先確認以下事實（僅詢問你無法推斷的項目）：

vault — 使用者的路徑，若目前工作目錄包含 .obsidian/ 或使用者提到「這個知識庫」，則為該目錄；只能在該目錄內寫入；
materials — 每個檔案的絕對路徑；依副檔名分類：音訊/影片、字幕 (.srt/.vtt)、投影片 (.pdf/.pptx)、筆記型電腦/程式碼、圖片/照片、文件；
title, series/course, date — 來自使用者、檔名或素材；切勿憑空捏造日期或參與者清單（寫 TBD 並說明）；
output language — 使用 notes.output_language，除非使用者指定了其他語言。

1.2 轉錄

對於每個沒有對應字幕檔（相同主檔名）的錄音，執行：

$PY <skill>/scripts/transcribe.py <recording> -o <scratch>/transcripts

<scratch> 是知識庫外部的暫存資料夾（例如 $TMPDIR/recording-to-obsidian-<date>-<slug>），用於所有中間檔案。
選用選項：--model small（更快、較粗糙），--language en（跳過語言偵測），--diarize（說話者標籤；需要 install.sh --diarize 以及環境變數 diarize.hf_token_env 指定的 Hugging Face token）。首次執行會下載模型，可能需要數分鐘；它會在 stderr 輸出進度——請讓它完成。
它會寫出 <stem>.srt 和 <stem>.txt（每段一行 [HH:MM:SS] 說話者 N: 文字），並輸出一行 JSON 摘要（語言、模型、時長、說話者、清理統計、檔案路徑）。保留該摘要：語言、模型和說話者辨識資訊會放入筆記的來源段落。
來自任何工具的字幕也可以同樣方式正規化：$PY <skill>/scripts/transcribe.py talk.vtt -o <scratch>/transcripts（不涉及模型；重複循環會被摺疊，並寫出一個含時間戳記的 .txt 檔）。
長時間錄音沒有問題：該腳本可處理數小時的音訊；請勿分割檔案。

如果轉錄失敗，請回報錯誤訊息；$PY <skill>/scripts/transcribe.py --check 會顯示缺少的項目。

1.3 選擇模式

如果使用者明確指定模式（或 notes.default_mode 不是 auto），則以該模式為準。否則：

素材中包含投影片、筆記型電腦、實驗室程式碼或講義 → 課程。
否則，讀取轉錄稿的前約 5 分鐘，並瀏覽其餘部分：

會議訊號	課程訊號
多位說話者，發言時間相當	一位主要說話者進行解釋
議程、進度更新、「我們在哪裡……」	「今天我們會涵蓋……」、「上週我們看到……」
提案、權衡討論、「我們就這麼辦」、「同意」	定義、推導、範例、練習
負責人與日期：「你能在週五前處理好嗎？」	聽眾提問是為了理解，而非為了決策
專案、客戶、截止日期、風險	課程/講座編號、閱讀資料、作業

混合情況依目的判斷：設計評審、規劃、回顧、事後檢討和一對一會議屬於會議；錄製的技術講座、培訓、研討會和教程屬於課程，即使有一些討論。

記錄選擇結果以及驅動該選擇的兩三個訊號（它們會放入報告中）。如果真的是模稜兩可且可以詢問，則詢問；否則自行選擇並說明原因。

1.4 執行模型：協調者 + 一個筆記寫手

讀取整份轉錄稿、逐頁閱讀投影片和筆記型電腦，然後寫入數十個檔案會快速填滿上下文視窗，因此拆分角色：

協調者 — 接收請求的會話。它執行 1.1–1.3（轉錄輸出保留在磁碟上；它只讀取足夠的轉錄稿以選擇模式），將寫入工作交給一個筆記寫手子代理，然後執行 1.5 的驗證並報告。
筆記寫手 — 一個子代理，在它自己的上下文中完成所選模式的整個寫入工作：閱讀所有素材、規劃、寫入、自我檢查。一場會議或一堂課可以舒適地放在一個上下文中；請勿將頁面或轉錄稿區塊拆分給多個代理（這會遺失交叉引用並產生重複筆記）。

當沒有子代理工具可用時，或當子代理無法勝任工作時（例如查看圖片、執行腳本、寫入檔案），請自行完成工作，而不是委派。在會議模式中，當會議很短（錄音少於約 15 分鐘且沒有投影片或文件），以至於簡報和實際工作一樣長時，你也可以直接寫入。課程模式始終使用筆記寫手，除非子代理不可用或無法勝任：投影片必須逐頁閱讀，這屬於寫手的上下文，而非你的。在報告中說明你選擇了哪種方式。驗證（1.5）絕不能跳過。對於多個會話，每個會話使用一個筆記寫手，當它們附加到同一個 MOC 時，依序進行。

給筆記寫手的簡報 — 它從零上下文開始，因此請提供所有資訊：

此技能的絕對路徑；模式；要遵循的檔案：references/meeting-mode.md 或 references/lecture-mode.md，加上 references/note-templates.md、references/transcript-processing.md、references/mermaid-style.md；
知識庫路徑、暫存資料夾、$PY、輸出語言、標題/系列/日期（或「推導」）、設定檔中的資料夾名稱；
每個素材和轉錄稿檔案的絕對路徑，以及轉錄摘要（語言、模型、說話者）；
現有的系列/課程 MOC 和上一場會話的中心頁/MOC（如果有的話）；使用者特別要求的任何內容；
規則：只能在知識庫內寫入；絕不能修改預先存在的筆記，除非是文件中記錄的附加內容；不得包含機密；
要回傳的內容：第 3 節的報告區塊，加上任何它無法解決的問題。

1.5 驗證（協調者）

當筆記寫手回傳時，獨立檢查其工作，而不是相信它的摘要：

$PY <skill>/scripts/check_vault.py <vault> --since <工作開始時的 epoch 秒數>
$PY <skill>/scripts/scan_secrets.py <vault>/sources

check_vault.py 必須以 issues: 0 結束；除非有正當理由（請說明），否則也應修復警告。它會像 Obsidian 一樣解析連結（依檔名或部分路徑，不區分大小寫，忽略 #heading/|alias，跳過程式碼區塊），因此它回報的斷裂連結在 Obsidian 中也是斷裂的。它檢查：斷裂的 [[links]]/嵌入/ Markdown 連結、不含 .pdf 的 PDF++ 連結、frontmatter（title、type、date_created）、中心頁覆蓋率（每個新筆記都從 MOC 或會議中心連結；每個會議中心都從 MOC 連結）、機密；對沒有連結的筆記、未設定樣式的 Mermaid 和不明確的連結發出警告。

然後檢查腳本無法檢查的項目：

沒有預先存在的筆記被更改，除了文件中記錄的附加內容（系列 MOC 條目、被取代的決策狀態、前一堂課 MOC 的「下一頁」連結）；
會議模式：每個決策都有一筆記錄，或明確標記為次要；每個行動項目都有一個負責人（或 TBD）、一個到期日（或 TBD）和一個時間戳記；
課程模式：MOC 精確列出每個新筆記一次；滿足課程自我檢查的粒度與重點目標。

直接修復小問題；較大的問題則附上確切清單送回給筆記寫手。重新執行 check_vault.py，直到報告 0 個問題。除非使用者要求保留，否則刪除暫存資料夾（它包含 wav 和頁面圖片）。

2. 共享慣例

知識庫佈局 — 筆記是扁平的；導航來自 MOC 和中心頁，而非資料夾。

vault/
├── notes/                         # 原子、重點、決策和主題筆記（扁平）
├── meetings/<series>/             # 會議中心："YYYY-MM-DD <title>.md"
├── moc/<series or course>/        # 系列 MOC（會議）/ 每堂課一個 MOC
└── sources/<series or course>/<YYYY-MM-DD or Lecture_NN>/
    ├── <prefix>_transcript.srt / .txt
    ├── <prefix>.pdf               # 投影片，用於 PDF++ 連結
    ├── slide_images/  whiteboard_photos/  notebooks/
    └── structured_slides.json     # 可選的逐頁閱讀記錄

複製到 sources/ 的每個檔案都加上系列/課程 + 會話前綴（Atlas_2026-11-12_transcript.srt、Optics101_L03.pdf、Optics101_L03_p08.jpg）：Obsidian 透過檔名解析連結，因此兩個都包含 transcript.srt 或 page-08.jpg 的會話會產生交叉連結。資料夾名稱使用系列/課程名稱，空格替換為 -。

檔名 — 使用人類可讀的標題，不帶 ID（會議中心是例外：它們以日期開頭以利排序）。避免 / \ : * ? " < > | # ^ [ ]；使用 — 代替 :。標題要足夠具體以獨立存在：Rate limits use a token bucket per API key.md，而不是 Rate limiting.md。

Frontmatter — 每個筆記都以 YAML frontmatter 開頭，至少包含 title、type 和 date_created。type 為 moc、meeting、decision 或 topic（會議模式）以及 moc、anchor 或 atomic（課程模式）。模式特定的欄位在 references/note-templates.md 中。標籤使用小寫英文 kebab-case：一個系列/課程標籤、2-4 個主題標籤、一個類型標籤；在發明新標籤之前，先重用知識庫中已有的標籤。

語言 — output_language = "auto" 表示：使用素材的語言撰寫（轉錄稿偵測到的語言，或投影片的語言）。當輸出語言與素材語言不同時，保留原文技術術語，並在首次出現時附上註釋——從英文會議產生的中文筆記：功能開關 (feature flag)；從德文課程產生的英文筆記：error propagation (Fehlerfortpflanzung)——然後使用讀起來自然的形式。程式碼、指令、路徑、產品和工具名稱絕不翻譯。標題遵循輸出語言。

連結 — 每個 [[wikilink]] 都必須解析為知識庫中的一個筆記或檔案。連結到現有筆記，而不是撰寫重複內容。當單純的名稱可能不明確時，使用路徑（[[sources/Atlas/2026-11-12/Atlas_2026-11-12_transcript.srt|transcript]]）。PDF++ 頁面連結始終保留 .pdf：[[Optics101_L03.pdf#page=5|Slide p.5 "Snell's law"]]。

時間戳記 — 為每個僅來自口頭陳述的決策、行動項目和主張引用轉錄稿的 [HH:MM:SS]。它們是回溯到錄音檔的稽核軌跡。

機密 — 切勿將憑證寫入知識庫。在將筆記型電腦或程式碼複製到 sources/ 之前，先在副本上執行 $PY <skill>/scripts/scan_secrets.py --redact <copy>（值會變成 <REDACTED>，變數名稱保留）。會議中口頭傳達的密碼、信用卡號碼或敏感個人資料也不應記錄——請寫「憑證已口頭分享（此處未記錄）」。

視覺化 — 在撰寫任何 Mermaid 圖表之前，先閱讀 references/mermaid-style.md：它包含調色板和確保圖表正確渲染的規則。無效語法比沒有圖表更糟。

模式輸出

會議 → references/meeting-mode.md：1 個中心頁、每個重要決策 1 筆決策記錄、0-N 個值得保留知識的主題筆記、一條附加到系列 MOC（首次使用時建立）的記錄、轉錄稿複製到 sources/。
課程 → references/lecture-mode.md：1 個 MOC、對於正常的 30+ 頁投影片有 8-15 個重點筆記、平均每個內容投影片至少有 1 個原子筆記、投影片/筆記型電腦/轉錄稿複製到 sources/。

3. 報告

會議模式：

會議 2026-11-12 — <title>  (系列: <series>)   模式: meeting (訊號: …)
  轉錄稿: 00:41:07, mlx:whisper-large-v3-turbo, 3 位說話者, en → 筆記 en
  中心頁: meetings/<series>/2026-11-12 <title>.md
  決策: 3 (記錄: 3)   行動項目: 7 (負責人 TBD: 1, 到期日 TBD: 2)
  主題筆記: 2   待解決問題: 2   風險: 1
  系列 MOC: moc/<series>/MOC — <series>.md (條目已附加)
  check_vault: issues 0, warnings 0
  未解決: <未配對到姓名的說話者、不清楚的段落、…>

課程模式：

課程 NN — <topic>   模式: lecture (訊號: …)
  投影片: 45 頁 (內容 37)   知識點: 68
  筆記: 56 個原子 + 12 個重點    原型: concept=34, practice-demo=6, …
  每個內容投影片的筆記數: 1.5    具有 ≥2 個豐富元素的重點: 12/12
  Mermaid: 14 (類型: sequence, mindmap, flowchart, …)

錄音轉Obsidian筆記