Vibe Transcriber本機轉錄入庫 Agent Skill
把本機語音辨識接進 Obsidian 筆記庫：媒體來源唯讀不搬移，轉錄文字經由確定性腳本寫入 Markdown、補齊結構化摘要，並同步產出可直接閱讀分享的 HTML 頁面。
核心定義：Vibe Transcriber 將音訊與影片轉錄為可搜尋、引用與留存的 Obsidian 逐字稿，不讓文字消散在終端機或聊天對話中。
使用者指定之本機音訊/影片，經由 127.0.0.1 Sona/Vibe API 離線推論。
Markdown 逐字稿、YAML Metadata、Raw JSON、結構化摘要與 HTML 閱讀頁。
來源檔案唯讀保護；逐字稿強制標記為非受信任資料，防禦 Prompt 注入。
以 174 秒課程影片為例：產出結構化 Markdown 逐字稿與 HTML 閱讀頁
以 2026-06-11 的線性代數課程影片轉錄為例：將本機檔案透過 multipart upload 送至 http://127.0.0.1:9025，指定 verbose_json 回傳格式。Skill 建立 Obsidian 逐字稿，保留每段時間戳與原始 JSON，並由 Python helper 注入結構化摘要後渲染成 HTML。
轉錄執行數據記錄
- 來源檔案
- 本機影片
有备考明年数学的同学们吗.mp4（174 秒） - API 端點
http://127.0.0.1:9025，格式指定verbose_json- 教學主題
- 線性代數伴隨矩陣性質與
det(A) != 0前提條件 - Markdown
AI-Assets/Vibe_Transcripts/...（約 14 KB）- HTML 頁面
AI-Assets/Vibe_Pages/...（約 25 KB）
摘要遵循固定綱目
輸出包含一句話摘要、重點整理、時間線、行動項目與可引用句。格式定義在獨立 prompt 檔，非模型自由發揮。
原始時間戳完整保留
筆記完整保留 segments 時間標記與 Raw JSON。後續若摘要有疑義，可隨時回溯原音對齊檢查。
自動落盤無須人工另存
Markdown 與 HTML 自動寫入 Vault 固定目錄，立即支援 Obsidian 全庫檢索、雙向連結與外鏈分享。
誠實記錄轉錄限制
逐字稿及時標註影片中的板書推導未在口述中提及，明確提醒使用者需搭配講義畫面閱讀。
轉錄模型只是第一步：知識入庫後的格式穩定與安全防禦
語音轉文字的開源模型與工具早已成熟。但在將轉錄結果整合進個人知識庫時，往往面臨隱私、資料消散、格式漂移與安全性等工程阻礙。
機敏音訊不宜上雲
會議錄音、深度訪談與內部技術研討常包含未公開脈絡。本機推論消除了將原始音訊上傳至第三方雲端服務的資安疑慮。
終端文字難以回收
轉錄結果若只輸出在 console 或聊天視窗，後續極難檢索。直接落盤為 Obsidian 筆記，確保每份音訊都有固定的資產落點。
摘要格式容易漂移
若每次依靠隨機 prompt 提煉摘要，格式很快會失控。將摘要規範抽離為獨立 Prompt 檔案，維護單一真相來源。
語音隱含注入風險
錄音演講中可能包含惡意指令。明確將逐字稿定義為「被動資料 Payload」，嚴禁其篡改 Agent 流程或執行危險工具。
Agent 專注語意決策，檔案寫入全數交由確定性腳本
大語言模型不適合直接覆寫大檔案。Agent 擅長理解意圖與提煉結構，但不應讓它在長篇對話中直接手動覆寫數十 KB 的 Markdown 檔案。透過 Python Helper 正則定錨，確保 YAML frontmatter、原始時間戳與 JSON 零毀損。
## Summary，避免上下文視窗截斷造成檔案損毀。確認輸入源
檢驗使用者指定檔案存在，標記為唯讀來源。絕不搬移、覆寫或刪除原檔。
本機 API 串流
以 multipart upload 發送音訊串流至 Sona 端點，本機 Whisper 離線推論。
初稿寫入 Vault
將 transcript、metadata 與 Raw JSON 寫入結構化 Markdown，保證格式完整。
確定性摘要注入
Agent 依規範提煉摘要，append_summary.py 以正則定位寫入 ## Summary。
雙軌 HTML 產出
同一份筆記渲染為獨立 HTML 閱讀頁，支援瀏覽器即時預覽與跨平台分享。
Obsidian 結構化筆記
保留段落時間戳與 Raw JSON，支援全文搜尋、雙向連結與後續知識重組。
AI-Assets/Vibe_Transcripts/YYYY-MM-DD-HHMMSS-source-transcript.md
獨立 HTML 閱讀版面
經由模板引擎渲染之響應式網頁，版面典雅，適合閱讀、列印與團隊分享。
AI-Assets/Vibe_Pages/YYYY-MM-DD-HHMMSS-source-transcript.html
省去手動搬移排版：建立可重複驗證的知識資產
這項工具的價值不在於單次呼叫轉錄 API，而在於將零散的語音素材轉變為可重跑、可驗證、格式一致的知識庫資產。
具體帶來的流程改善
- 轉錄成果固定落盤每次輸出皆自動歸檔至 Obsidian 指定目錄，終結手動複製另存的零碎操作。
- 摘要結構嚴格對齊Prompt 檔案獨立版本控管，欄位與綱目調整有明確單一修改點。
- 檔案操作具確定性轉錄、摘要定錨與 HTML 渲染皆封裝為獨立 CLI 腳本，隨時可分段重跑驗證。
- 排版自動化雙軌輸出Markdown 筆記一鍵轉為美觀 HTML，徹底省去搬移至外部編輯器排版的時間。
非受信任音訊強制隔離於資料層：杜絕惡意指令越權
音訊內容不可信。本機推論消除了雲端外洩風險，但音訊內容本身仍屬於非受信任資料（Untrusted Data）。嚴格規範逐字稿只能作為被動資料處理，杜絕 Prompt Injection 劫持 Agent 執行危險工具或篡改系統行為。
本機離線推論優先
音訊與影片留在本地機器由 Sona/Whisper 推論，杜絕將機敏會議與訪談傳輸至外部伺服器。
來源檔案唯讀保護
使用者提供的外部媒體檔案僅作為唯讀輸入，Skill 絕對不搬移、不重命名、不刪除原檔。
固定路徑與命名規範
逐字稿與 HTML 嚴格限制在 AI-Assets/ 子目錄，避免在 Vault 根目錄產生隨機暫存檔。
Prompt Injection 阻斷
逐字稿內容一律為被動資料，嚴禁 Agent 將語音中提及的要求轉譯為系統指令或檔案操作。
Obsidian CLI 讀回驗證
寫檔完成後調用 Obsidian CLI 讀回筆記內容，確保語法解析正確且摘要區塊完整落盤。
決定執行穩定度的四個工程關鍵
不堆砌無意義的工具名稱，專注於解決影響管線成敗的關鍵實作細節。
Sona API 需採 Multipart 協定
Sona 轉錄端點接收 multipart/form-data 檔案串流，而非單純的 JSON 路徑。若傳輸協定宣告錯誤，請求將在進入推論前被拒絕。
Prompt-as-Code 獨立維護
摘要規則獨立封裝於 prompts/transcript-summary-prompt.md。Skill 核心檔僅專注於流程調度與安全邊界，降低耦合。
Python Helper 正則定錨演算法
透過 append_summary.py 比對 (?ms)^## Summary 錨點。Agent 無須回傳整篇筆記，杜絕上下文長度造成的內容截斷。
Windows CJK 編碼防禦
媒體檔名若包含特殊中文或符號，傳統 Windows 主控台可能引發編碼例外。腳本在入口處強制將標準輸出重組為 UTF-8 No BOM。
def insert_or_replace_summary(markdown: str, summary: str) -> tuple[str, str]:
"""
確定性正則錨點替換演算法：
1. 若筆記已存在 ## Summary 區塊，精準替換至下一個 ## 標題或文末。
2. 若不存在 Summary 但有 ## Transcript，安全插入於逐字稿之前。
3. 若無上述標題，退回附加至檔案結尾，確保 Raw JSON 與時間戳不受破壞。
"""
pattern = re.compile(r"(?ms)^## Summary\s.*?(?=^## |\Z)")
if pattern.search(markdown):
return pattern.sub(summary + "\n", markdown, count=1), "replaced"
transcript_match = re.search(r"(?m)^## Transcript\s*$", markdown)
if transcript_match:
insert_at = transcript_match.start()
return markdown[:insert_at].rstrip() + "\n\n" + summary + "\n" + markdown[insert_at:], "inserted_before_transcript"
return markdown.rstrip() + "\n\n" + summary, "appended"
多媒體知識入庫架構的通用範式
這套「非受信任多媒體輸入 ➔ 確定性腳本落盤 ➔ 雙軌輸出」模式，能直接套用到 PDF 研讀、會議紀錄彙整與線上技術演講等非結構化多媒體的知識入庫管線。
結構優先於 AI 生成
在接入大語言模型前，先確立 Markdown Schema 與輸出目錄規範。結構邊界清楚，後續自動化檢查才有準繩。
雙軌分工：決策與落盤解耦
Agent 專注於語意萃取，檔案寫入與模板渲染由專屬 Python 腳本執行。系統更易除錯，失敗點也能精準定位。
外部來源一律視為非受信任
本機環境不代表零威脅。將外部輸入視為純資料，阻斷任何潛在指令對 Agent 執行環境的干擾。
作品頁聚焦架構取捨與安全邊界；教學頁則提供完整的環境配置、Python 代碼、Prompt 模板與執行步驟。