2026年11月18日 星期三

Antigravity CLI 終端指令與高階快捷速查參考資訊(含Notebook生態對應)

Google Antigravity (AGY) CLI 常用指令與實戰快捷速查手冊
Google Antigravity (AGY) CLI 官方全功能指令速查

Antigravity CLI終端指令與高階快捷速查手冊

全面涵蓋規劃審查與生成介面(Generative UI / Artifact / Grill-Me)、多代理協作(Swarm / Teamwork)、動態工作流編排(Run-Workflow)、自訂擴充(Skills / MCP / Hooks)、對話分支控制與微觀審查之全域速查手冊。

A. 規劃、任務拆解、深度訪談與生成介面 (Generative UI / Artifacts)
/artifact
產生獨立結構化 Markdown 專題報告(存於 brain/<conversation-id>),內建原生 Mermaid 圖表渲染、資訊警示區塊(Alerts)與程式碼輪播(Carousels),供使用者持續檢視與推進。
對應 NOTEBOOK「Dedicated Notebook Note / Artifacts」:
同源於 NotebookLM 獨立專題筆記與 Claude Artifacts 機制。將複雜分析、長篇研究或實作進度自對話主線抽離為獨立專題實體,避免上下文擁塞且支援持續疊代。
/generative_ui
啟動 Generative UI(生成式介面)模式,將枯燥終端文字即時轉化為兼具即時搜尋過濾、自包含動態 HTML/JS、按鈕回饋與圖表視覺化之動態 Web 儀表板。
對應 NOTEBOOK「Make me a site」:
概念同源於 Notebook / Canvas / Artifacts 中的經典提示詞 Make me a site(幫我做個互動微站)。當需要將結構化數據、分析報告或系統狀態打造成可點擊操作、自適應響應式佈局的單頁應用(SPA / Dashboard)時觸發。
/grill-me [task]
啟動「考官級結構化深度訪談(Grill-Me)」,Agent 會循著設計決策樹的各個分支,逐題透過多選題訪談使用者,逐一釐清架構相依性與隱性需求,對齊專案藍圖。
對應 NOTEBOOK「Socratic Interview / 蘇格拉底深度詰問」:
同源於 NotebookLM 深度探索訪談與架構師評審會。在動工前由 Agent 逐層追問業務邊界與折衷決策,徹底杜絕假設盲區。
/plan
進入計畫模式,在執行複雜修改前先產出嚴謹的 Step-by-Step 實作步驟清單與風險評估,等待使用者檢閱與批准後才動手寫程式碼。
對應 NOTEBOOK「Execution Blueprint / 執行大綱前置審核」:
同源於工程設計審查(Design Review)。先產出分步實施計畫並等待使用者核准,降低試錯成本。
/goal
啟動目標導向長程自主模式(適合隔夜執行或攻堅大專案),Agent 會主動解決所有阻礙與錯誤,不達最終預期產出絕不停止。
/boost
針對高難度編程或深奧研發專案,啟動深度思考(Deep Thinking)、策略多視角推演與嚴格交叉驗證。
/browser
全功能端對端 (E2E) 瀏覽器代理:宛如坐在身旁的資深前端副駕駛。
• 語意快照 (A11y Snapshot):依賴無障礙樹 UID 操作,抗重繪排版微調。
• 表單批次操作 (fill_form):一次性填入欄位,節省回合與網路延遲。
• 全端遙測診斷:同步監聽 Console 未捕獲錯誤與 Network API 狀態碼 (4xx/5xx)。
• 效能審查:內建 Lighthouse 效能與 Core Web Vitals 自動審計。
與 Make me a site 強強聯動「Live Web Preview & Testing」:
當由 /generative_ui 生成微站後,可立即調用 /browser 執行真實網頁渲染預覽、表單點擊自動化測試與 Console 錯誤快照審查。
B. 多代理協作、動態工作流與排程自動化
/swarm
啟動原生 Agent 群並行處理大型拆解任務(各 Worker 獨立對話與工作區,共享訊息看板協同作業)。
對應 NOTEBOOK「Multi-Agent Swarm / 叢集並行代理群」:
同源於協同工作空間的多 Agent 矩陣。多位 Worker 在共享看板上非同步分工,各司其職完成百花齊放的並行子任務。
/teamwork <task> 別名 /teamwork-preview
啟動長程多代理協作團隊,分工處理複雜專案(包含架構師、實作者、審查員角色聯動)。
對應 NOTEBOOK「Collaborative Virtual Team / 虛擬專家團隊」:
同源於大專案的多角色協同研討,自動指派 Coordinator、Researcher 與 Engineer 形成閉環產出。
/run-workflow <task>
動態工作流,讓 Agent 撰寫 Python 腳本自動編排多個代理(例如扇出逐檔審查、測試修復閉環)。
/schedule <when> <task>
在目前對話中設定單次計時或週期性排程提醒/任務(支援 DurationSeconds 或 CronExpression)。
/automation
建立獨立的排程 Sidecar,定時自動開啟新對話執行背景任務(具備無人值守與持久化監控能力)。
/remote-control [on/off]
開啟遠端控制通道,可從手機或外部網頁瀏覽器即時接管並監控本地終端機的 agy 會話。
C. 知識沉澱、技能擴充與生態介面
/learn [instruction]
從對話中的糾正與經驗,自動生成可審查的 learning_proposal.md,一鍵存成專案 Rule 或 Skill。
對應 NOTEBOOK「Curate to Source / 知識庫沉澱」:
同源於 Notebook 知識庫的精煉與來源持久化。將除錯成果或使用者偏好直接固化為系統規則,越用越聰明。
/skills [reload] 支援 /<skill-name>
瀏覽本地與全域 Agent Skills;更新 SKILL.md 後免重啟直接熱重載,並可用 /<skill-name> 直接呼叫。
/agy-customizations
檢視與引導 Skills、Rules、Hooks、MCP 與 Plugins 的客製化設定與優先權加載規範。
/antigravity-guide
呼叫 Antigravity 內建官方功能手冊、地圖索引與進階使用操作指南。
/plugin 別名 /plugins
開啟外掛市集與管理介面,支援一鍵安裝、啟用、停用與解除安裝生態外掛。
/mcp
開啟 Model Context Protocol (MCP) 伺服器管理介面,快速連接外部資料庫、API 或本機開發工具。
/hooks
檢視與調試作用中的生命週期鉤子(Pre-flight 檢查 / Post-format JSON Hooks 格式化)。
D. 對話控制、程式碼檢索與微觀審查
/btw <query>
不打斷主線任務,在背景開小卡詢問側邊問題(可用 ← / → 左右方向鍵切換先前問過的卡片)。
/diff
開啟互動式變更檢視器,檢視工作區差異、每回合修改與 Commit 紀錄,支援逐行留言導正 Agent。
/codesearch <query> 別名 /cs, /search
互動式程式碼全域搜尋,支援直接在搜尋結果視窗內逐行添加註解導正代碼理解。
/context
視覺化檢視目前 Context 視窗的 Token 佔用分布(即時監控系統提示、工具定義與歷史佔比)。
/compact
壓縮並結構化摘要歷史對話,釋放 Context 空間以延長單次長任務會話之壽命。
對應 NOTEBOOK「Summarize & Condense / 上下文智能摘要」:
同源於 NotebookLM 筆記智能總結與 Context Window 重置。萃取關鍵決策並精簡歷史 token,防止記憶膨脹與隱藏成本飆升。
/fork [target] 別名 /branch
將目前對話狀態完整複製分支到另一個平行會話(或指定專案目錄)進行無風險獨立實驗。
/rewind 別名 /undo
將對話歷史時光倒流回溯到先前的訊息節點,消除錯誤分支。
/resume 別名 /switch, /conversation
開啟對話挑選器,瀏覽、切換或恢復先前儲存的歷史對話會話。
/copy [n|btw]
將最新一次(或倒數第 n 次、或 /btw 卡片)的 Agent 回覆內容快速複製到系統剪貼簿。
/rename <name>
重新命名目前的對話執行緒標題,方便日後在歷史列表中精準檢索。
/clear 別名 /new
清空終端畫面並重設目前對話上下文,立即開啟純淨新任務。
E. 模型、配額、環境與系統底座設定
/model
開啟模型選擇器(支援 Gemini 4 Argon / 3.8 Flash、Claude 3.7 Sonnet / Opus 等動態切換)。
/usage 別名 /quota
顯示目前各模型 API 額度消耗進度與呼叫次數即時儀表。
/credits
顯示剩餘的 G1 點數餘額與加值購買官網快捷連結。
/permissions
開啟工具安全門禁權限管理(設定檔案寫入、指令執行之允許/拒絕/詢問規則)。
/config 別名 /settings
開啟全域設定編輯器(直接同步對應 ~/.gemini/antigravity-cli/settings.json)。
/add-dir <path>
將專案外部的額外資料夾即時加入目前 Agent 的檔案讀寫權限範圍。
/tasks
開啟背景 Shell 執行任務管理員,支援檢視、遞交輸入或終止背景運行的編譯/測試進程。
/statusline
自訂終端機底部狀態列顯示項目(模型、Git 分支、Token 即時指標等)。
/title [on/off]
開啟或關閉終端機視窗標題根據當前任務動態自動更新。
/keybindings
開啟鍵盤快捷鍵配置編輯器,依個人手指肌肉記憶自訂快速鍵。
/changelog
檢視 Antigravity CLI 各版本的最新功能與 Bug 修復發行日誌。
/help 或輸入 ?
開啟內建互動式指令與快捷鍵說明面板。
/feedback
開啟意見回饋表單,向 DeepMind 工程團隊遞交 Bug 報告或改善建議。
/logout 別名 /exit, /quit
安全登出帳號金鑰或結束退出 CLI 會話。
4. 搭配使用的實用終端快捷與進階模式
! <command>
在提示框開頭加驚嘆號,不離開當前會話直接透傳執行本機系統終端指令(例如 ! git status 或 ! dir)。
Shift + Tab
鍵盤快速輪替執行模式:在 plan(只規劃不寫檔)、accept-edits(自動審批修改)與 auto(全自主執行)之間循環切換。
agy -p "<prompt>"
非互動式(Headless)單次執行指令模式,適合直接寫進 Bash/PowerShell 自動化批次腳本或 CI/CD 管線中無人值守運作。
指令已複製到剪貼簿!
Google Antigravity CLI 指令速查手冊 (Section A~E Full Spectrum)

2026年11月15日 星期日

SKILL技能彙總List參考資訊

📋 AI 神器與技能文章速查總表

應用分類核心技能 / 框架文章標題與直達連結

📊 邏輯決策與文案

Task 模式 × RCA

以AI神器(TASK模式),新聞報導資訊RCA根因分析,協助秒懂案件始末與因應參考資訊

📊 邏輯決策與文案

Gemini Spark 科學對位

Gemini Spark協助找尋客觀數據,進行科學對位分析

📊 邏輯決策與文案

PREP 說服力框架

如何經由AI神器,依PREP文案框架樣版,梳理生成具邏輯性、且有說服力之簡潔文案

💻 程式與機器學習

IT-Teach 開發維運

生成一個IT-Teach電腦程式維運問題協尋、軟體開發教學與功能擴充專家。

💻 程式與機器學習

ML Python 程式拆解

請AI神器協助在機器學習領域上,拆解PYTHON程式之參考技能

🌏 外語與生活旅遊

JP / KR 語言學習

日文JP/韓文KR 學習技能神操作

🌏 外語與生活旅遊

Souvenir Analyst

生成一位 Souvenir Analyst (全世界各地美食與土產おみやげ情資達人)

🌏 外語與生活旅遊

Life-Analyst 樣板

Life-Analyst生活諮訊參考技能樣板

⚡ 行動端跨工具整合

iPhone × Google 行事曆

Gemini Spark 在IPHONE上設定 天氣概況產出結果至GOOGLE行事曆


📊 邏輯決策、根因剖析與結構化溝通

以AI神器(TASK模式),新聞報導資訊RCA根因分析,協助秒懂案件始末與因應參考資訊

運用 AI Task 模式將複雜新聞報導拆解為時間軸、直接原因與根本原因(RCA),快速掌握事件核心與風險應對策略。

閱讀完整文章 ➔

告別直覺臆測與空泛總結,透過 Gemini Spark 檢索客觀數據指標,建立具實證基礎的科學對位檢核流程。

閱讀完整文章 ➔

導入 Point(結論)➔ Reason(原因)➔ Example(實例)➔ Point(重申)四步框架,讓 AI 產出條理分明、重點突出的高說服力文案。

閱讀完整文章 ➔

💻 二、程式開發維運與機器學習拆解

💡生成一個IT-Teach電腦程式維運問題協尋、軟體開發教學與功能擴充專家。

封裝專屬軟體工程導師技能,支援系統維運異常排查、程式碼重構擴充與由淺入深的開發教學引導 。

閱讀完整文章 ➔

針對機器學習(ML)領域之 Python 腳本進行模組化拆解,釐清資料前處理、特徵工程、模型訓練與評估指標背後的運作邏輯。

閱讀完整文章 ➔

🌏 三、外語學習、旅遊伴手禮與生活決策

🔴⚪日文JP/韓文KR 學習技能神操作

打造隨身日韓語家教技能,結合語境拆解、發音對照、句型延伸與高頻會話練習,大幅提升第二外 語吸收效率。

閱讀完整文章 ➔

旅遊必備伴手禮與在地美食情資顧問,快速盤點各國特色土產(おみやげ)、口碑亮點與選購指南 。

閱讀完整文章 ➔

🌟😊Life-Analyst生活諮訊參考技能樣板

針對日常規劃、生活疑難與個人決策需求,提供溫暖且具結構性的多維度分析與行動建議樣板。

閱讀完整文章 ➔

⚡ 四、行動端跨工具自動化整合(iPhone × Google 生態系)

Gemini Spark 在IPHONE上設定 天氣概況產出結果至GOOGLE行事曆

在 iPhone 上將 Gemini Spark 查詢之最新天氣概況自動同步寫入 Google Calendar,出門前打開行事曆即可掌握穿搭與攜傘提醒。

地圖選擇(🚗停車場資訊)

閱讀完整文章 ➔


2026年11月14日 星期六

Air-Gapped 離線地端 聲音檔轉文字檔參考資訊

情境:運用前篇it-teach技能,請AI神器規劃離線版地端 「聲音檔轉文字」工具,整合 faster-whisper、pyannote.audio、Microsoft Presidio、Ollama (Qwen2.5/Llama 3.1) 與 SHA-256 WORM 數位存證鏈之生產級 Python 參考方案。

         🔒 AIR-GAPPED ON-PREM INFRASTRUCTURE(完全離線隔離內網)
🎙️ 內部音訊會議(.wav / .mp3)
▼
1. 輸入校驗與音訊指紋層 (Audio Ingestion & Provenance)
  • 計算音訊原始檔案 SHA-256 雜湊(確保輸入未被竄改)
  • FFmpeg 音訊重採樣標準化(16kHz, Mono, 16-bit PCM WAV)
⚡ 雙軌平行聲學處理
↙                              ↘
2A. 語音辨識 ASR: faster-whisper
  • 離線加載 Whisper Large-v3 權重檔案
  • 產出:[起始秒, 結束秒, 識別文字]
2B. 聲紋聚類: pyannote.audio
  • 提取說話者聲學嵌入向量 (Embeddings)
  • 產出:[起始秒, 結束秒, SPEAKER_00]
↘                               ↙
🔄 時間軸交疊演算法 (Overlap Sync)
▼
3. 時序對齊與在地 DLP 脫敏閘門 (Alignment & Local Presidio Redaction)
  • 時間戳融合輸出:[MM:SS] [SPEAKER_XX]: 對話文字
  • V1 負向環視 Regex + 中文語系保護:徹底解決中文無空白緊貼(如 身分證Z12*456789)漏網與 Presidio 缺席 spaCy 外聯風險
  • 生成純淨脫敏逐字稿:output/redacted_transcript.txt
▼
4. 地端模型結構化萃取 (Local LLM via Ollama / vLLM)
  • 離線載入 Qwen2.5 / Llama 3.1 7B/8B(在地 GPU 推論)
  • requests.Session(trust_env=False) 繞過企業代理直連 http://127.0.0.1:11434
  • 設定 options.num_ctx = 16384 避免長會議遭預設 2048 tokens 靜默截斷
  • 透過 Pydantic MeetingMinutes.model_json_schema() 驅動 GBNF 嚴格輸出 JSON:output/meeting_minutes.json
▼
5. 稽核憑證簽發與不可竄改存證 (Audit Certificate & WORM Storage)
  • 記錄:[音訊 SHA-256] + [模型權重 SHA-256] + [Prompt SHA-256] + [輸出結果 SHA-256]
  • 輸出 JSON 稽核保證書,提供外部稽核員一鍵重現查驗

環境依賴與離線準備 (requirements.txt)

# 核心語音與脫敏依賴
pip install faster-whisper pyannote.audio presidio-analyzer presidio-anonymizer
# LLM 結構化輸出與驗證
pip install pydantic requests
  • Whisper 權重:./models/whisper-large-v3/(CTranslate2 格式)
  • Pyannote 設定檔:./models/pyannote_speaker_diarization_3_1/config.yaml(移除遠端相依)
  • 地端 Ollama:監聽本機 http://127.0.0.1:11434,載入 qwen2.5:7b 或 llama3.1:8b

完整端到端實作腳本 (airgapped_meeting_pipeline.py)

mp32txt_pipeline.py 維持 SSoT 同步,內建 --self-test 離線契約與無空白中文個資測試,已實測驗證通過。

import argparse
import hashlib
import json
import math
import os
import re
import shutil
import struct
import subprocess
import wave
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple

import requests
from pydantic import BaseModel, Field

# 離線隔離環境變數硬化:強制封鎖 HuggingFace / Transformers 隱性外聯查詢
os.environ.setdefault("HF_HUB_OFFLINE", "1")
os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
os.environ.setdefault("HF_HUB_DISABLE_TELEMETRY", "1")

# 語音與聲紋分離(採安全延遲匯入,避免未安裝重型模型依賴時阻斷模組載入)
try:
    import torch
except ImportError:  # pragma: no cover
    torch = None  # type: ignore[assignment]

try:
    from faster_whisper import WhisperModel
except ImportError:  # pragma: no cover
    WhisperModel = None  # type: ignore[assignment]

try:
    from pyannote.audio import Pipeline
except ImportError:  # pragma: no cover
    Pipeline = None  # type: ignore[assignment]

# PII 脫敏(優先使用 Presidio,缺省時自動退回相容之本機 Regex 引擎)
try:
    from presidio_analyzer import AnalyzerEngine, Pattern, PatternRecognizer
    from presidio_anonymizer import AnonymizerEngine

    _HAS_PRESIDIO = True
except ImportError:  # pragma: no cover
    AnalyzerEngine = Any  # type: ignore[misc, assignment]
    AnonymizerEngine = Any  # type: ignore[misc, assignment]
    Pattern = Any  # type: ignore[misc, assignment]
    PatternRecognizer = Any  # type: ignore[misc, assignment]
    _HAS_PRESIDIO = False


# =====================================================================
# 0. 結構化輸出 Pydantic 模型定義 (金管會/內部稽核標準規格)
# =====================================================================

class ActionItem(BaseModel):
    """會議待辦事項結構"""

    owner: str = Field(description="負責人姓名或角色")
    task: str = Field(description="待辦任務細節")
    deadline: Optional[str] = Field(description="完成期限,若無提及填 null")
    context_quote: str = Field(description="原文佐證依據")
    timestamp: str = Field(description="提及此待辦的起始時間戳 [MM:SS]")


class DecisionItem(BaseModel):
    """會議定案決議結構"""

    decision: str = Field(description="決議事項內容")
    context_quote: str = Field(description="決議相關對話引述")
    timestamp: str = Field(description="決議形成時間戳 [MM:SS]")


class MeetingMinutes(BaseModel):
    """標準化會議紀錄與合規稽核輸出模型"""

    meeting_title: str = Field(description="會議主題與綱要")
    summary: str = Field(description="會議整體摘要整理 (條列式)")
    decisions: List[DecisionItem] = Field(default_factory=list, description="會議所有定案決議")
    action_items: List[ActionItem] = Field(default_factory=list, description="會議所有待辦事項")
    confidence_score: float = Field(ge=0.0, le=1.0, description="結構化擷取置信度評分")


# =====================================================================
# 0.5 本機 Regex 脫敏回退實作 (當環境未安裝 Presidio 時維持等價能力)
# =====================================================================

@dataclass
class _RegexMatchResult:
    entity_type: str
    start: int
    end: int
    score: float


@dataclass
class _RegexAnonymizedText:
    text: str


class _LocalRegexAnalyzerFallback:
    """無 Presidio 套件時提供與 AnalyzerEngine 相容的台灣個資 Regex 偵測"""

    def __init__(self) -> None:
        self._patterns: Dict[str, Tuple[re.Pattern[str], float]] = {
            "TW_ID": (re.compile(r"(?<![A-Za-z0-9])[A-Z][12]\d{8}(?![A-Za-z0-9])"), 0.85),
            "PHONE_NUMBER": (re.compile(r"(?<!\d)09\d{2}-?\d{3}-?\d{3}(?!\d)"), 0.80),
            "EMAIL_ADDRESS": (
                re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}"),
                0.85,
            ),
        }

    def analyze(
        self,
        text: str,
        entities: Optional[List[str]] = None,
        language: str = "zh",
    ) -> List[_RegexMatchResult]:
        _ = language
        target_entities = entities or list(self._patterns.keys())
        findings: List[_RegexMatchResult] = []
        for entity in target_entities:
            entry = self._patterns.get(entity)
            if not entry:
                continue
            pattern, score = entry
            for match in pattern.finditer(text):
                findings.append(
                    _RegexMatchResult(
                        entity_type=entity,
                        start=match.start(),
                        end=match.end(),
                        score=score,
                    )
                )
        # 依起始位置排序,重疊時保留較長比對
        findings.sort(key=lambda item: (item.start, -(item.end - item.start)))
        return findings


class _LocalRegexAnonymizerFallback:
    """將偵測到的 PII 區間置換為標準化 <ENTITY> 標籤"""

    def anonymize(
        self, text: str, analyzer_results: List[_RegexMatchResult]
    ) -> _RegexAnonymizedText:
        if not analyzer_results:
            return _RegexAnonymizedText(text=text)
        # 由後往前置換,避免索引位移
        redacted = text
        last_start = len(text) + 1
        for res in sorted(analyzer_results, key=lambda r: r.start, reverse=True):
            if res.end > last_start:
                continue
            redacted = f"{redacted[:res.start]}<{res.entity_type}>{redacted[res.end:]}"
            last_start = res.start
        return _RegexAnonymizedText(text=redacted)


# =====================================================================
# 1. 輸入校驗與音訊指紋層 (Audio Ingestion & Provenance)
# =====================================================================

def calculate_sha256(filepath: str) -> str:
    """計算檔案 SHA-256 雜湊,確保輸入檔案未經竄改"""
    hasher = hashlib.sha256()
    with open(filepath, "rb") as f:
        while chunk := f.read(8192):
            hasher.update(chunk)
    return hasher.hexdigest()


def normalize_audio(input_path: str, output_path: str) -> str:
    """使用本機 FFmpeg 重採樣音訊為 16kHz, Mono, 16-bit PCM WAV (ASR與聲紋金標格式)"""
    if not Path(input_path).is_file():
        raise FileNotFoundError(f"找不到輸入音訊檔: {input_path}")

    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
    cmd = [
        "ffmpeg",
        "-y",
        "-i",
        input_path,
        "-ar",
        "16000",
        "-ac",
        "1",
        "-c:a",
        "pcm_s16le",
        output_path,
    ]
    result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    if result.returncode != 0:
        raise RuntimeError(f"FFmpeg 轉換失敗: {result.stderr.decode('utf-8', errors='ignore')}")
    return output_path


# =====================================================================
# 2. 雙軌平行聲學處理 (faster-whisper + pyannote.audio)
# =====================================================================

def run_asr(audio_path: str, model_dir: str) -> List[Dict[str, Any]]:
    """2A. 離線加載 faster-whisper 進行語音辨識"""
    if WhisperModel is None or torch is None:
        raise RuntimeError(
            "缺少 faster-whisper 或 torch 套件,請先於離線環境安裝 requirements.txt 依賴。"
        )
    if not Path(model_dir).exists():
        raise FileNotFoundError(f"找不到 Whisper 離線模型目錄: {model_dir}")

    device = "cuda" if torch.cuda.is_available() else "cpu"
    compute_type = "float16" if device == "cuda" else "int8"

    model = WhisperModel(model_dir, device=device, compute_type=compute_type, local_files_only=True)
    segments, _ = model.transcribe(
        audio_path,
        beam_size=5,
        word_timestamps=False,
        vad_filter=True,
        language="zh",
    )

    transcriptions: List[Dict[str, Any]] = []
    for s in segments:
        transcriptions.append(
            {
                "start": round(s.start, 2),
                "end": round(s.end, 2),
                "text": s.text.strip(),
            }
        )
    return transcriptions


def run_diarization(audio_path: str, config_yaml_path: str) -> List[Dict[str, Any]]:
    """2B. 離線加載 pyannote.audio Pipeline 進行聲紋聚類"""
    if Pipeline is None or torch is None:
        raise RuntimeError(
            "缺少 pyannote.audio 或 torch 套件,請先於離線環境安裝 requirements.txt 依賴。"
        )
    if not Path(config_yaml_path).is_file():
        raise FileNotFoundError(f"找不到 Pyannote 離線設定檔: {config_yaml_path}")

    pipeline = Pipeline.from_pretrained(config_yaml_path)
    if torch.cuda.is_available():
        pipeline.to(torch.device("cuda"))

    diarization = pipeline(audio_path)

    speakers: List[Dict[str, Any]] = []
    for turn, _, speaker in diarization.itertracks(yield_label=True):
        speakers.append(
            {
                "start": round(turn.start, 2),
                "end": round(turn.end, 2),
                "speaker": speaker,
            }
        )
    return speakers


# =====================================================================
# 3. 時序對齊與在地 DLP 脫敏閘門 (Alignment & Local Presidio Redaction)
# =====================================================================

def align_transcript_and_speakers(
    asr_data: List[Dict[str, Any]], diar_data: List[Dict[str, Any]]
) -> List[Dict[str, Any]]:
    """
    時間軸交疊算法 (Overlap Sync):
    為每一句 ASR 識別文字比對覆蓋時間最長的說話者標籤
    """
    aligned: List[Dict[str, Any]] = []
    for asr in asr_data:
        asr_start, asr_end = asr["start"], asr["end"]
        best_speaker = "UNKNOWN"
        max_overlap = 0.0

        for diar in diar_data:
            overlap = max(0.0, min(asr_end, diar["end"]) - max(asr_start, diar["start"]))
            if overlap > max_overlap:
                max_overlap = overlap
                best_speaker = diar["speaker"]

        aligned.append(
            {
                "start": asr_start,
                "end": asr_end,
                "speaker": best_speaker,
                "text": asr["text"],
            }
        )
    return aligned


def build_local_presidio_redactor() -> Tuple[Any, Any]:
    """
    建立在地 Presidio 脫敏引擎,並加入支援無空白中文邊界的台灣身分證與手機負向環視 Regex;
    若離線環境未安裝 Presidio 或缺乏本地 spaCy 模型,自動降級為零外聯風險之本機 Regex 引擎。
    """
    if not _HAS_PRESIDIO:
        return _LocalRegexAnalyzerFallback(), _LocalRegexAnonymizerFallback()

    try:
        analyzer = AnalyzerEngine()

        # 台灣身分證字號 (負向環視:支援「身分證A123456789」與「身分證 A123456789」)
        tw_id_pattern = Pattern(
            name="tw_id_pattern",
            regex=r"(?<![A-Za-z0-9])[A-Z][12]\d{8}(?![A-Za-z0-9])",
            score=0.85,
        )
        tw_id_recognizer = PatternRecognizer(
            supported_entity="TW_ID",
            supported_language="zh",
            patterns=[tw_id_pattern],
        )

        # 台灣手機號碼 (負向環視:支援「手機0*12-345-678」與「手機 0*12345678」)
        tw_phone_pattern = Pattern(
            name="tw_phone_pattern",
            regex=r"(?<!\d)09\d{2}-?\d{3}-?\d{3}(?!\d)",
            score=0.80,
        )
        tw_phone_recognizer = PatternRecognizer(
            supported_entity="PHONE_NUMBER",
            supported_language="zh",
            patterns=[tw_phone_pattern],
        )

        analyzer.registry.add_recognizer(tw_id_recognizer)
        analyzer.registry.add_recognizer(tw_phone_recognizer)

        anonymizer = AnonymizerEngine()
        return analyzer, anonymizer
    except Exception:
        return _LocalRegexAnalyzerFallback(), _LocalRegexAnonymizerFallback()


def redact_dialogue_stream(
    aligned_data: List[Dict[str, Any]], analyzer: Any, anonymizer: Any
) -> str:
    """生成經過本機 PII 遮罩的文字流"""
    redacted_lines: List[str] = []
    for item in aligned_data:
        raw_text = item["text"]

        # 偵測並遮罩 PII
        results = analyzer.analyze(
            text=raw_text,
            entities=["TW_ID", "PHONE_NUMBER", "EMAIL_ADDRESS"],
            language="zh",
        )
        anonymized_result = anonymizer.anonymize(text=raw_text, analyzer_results=results)

        # 時間戳轉化為 [MM:SS]
        m, s = divmod(int(item["start"]), 60)
        timestamp_str = f"{m:02d}:{s:02d}"

        line = f"[{timestamp_str}] [{item['speaker']}]: {anonymized_result.text}"
        redacted_lines.append(line)

    return "\n".join(redacted_lines)


# =====================================================================
# 4. 地端模型結構化萃取 (Local LLM via Ollama)
# =====================================================================

def query_local_ollama(
    prompt_text: str,
    model_name: str = "qwen2.5:7b",
    ollama_host: str = "http://127.0.0.1:11434",
    num_ctx: int = 16384,
) -> MeetingMinutes:
    """
    透過 Ollama 原生 API (>= 0.5.0),傳遞 JSON Schema 進行嚴格的 Pydantic GBNF 約束推論。
    預設設定 num_ctx=16384 防止長會議對話遭 2048 tokens 靜默截斷,並強制繞過企業環境 HTTP_PROXY。
    """
    system_prompt = (
        "你是一個完全運行於內網離線隔離環境的會議紀錄分析秘書。"
        "請根據提供的脫敏會議對話流,提取核心摘要、定案決議與行動待辦清單。"
        "必須符合給定的 JSON Schema,且所有 context_quote 與 timestamp 必須嚴格源自對話紀錄,嚴禁臆測。"
    )

    payload = {
        "model": model_name,
        "messages": [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": f"以下為已脫敏的會議內容:\n\n{prompt_text}"},
        ],
        "format": MeetingMinutes.model_json_schema(),
        "stream": False,
        "options": {"temperature": 0.1, "num_ctx": num_ctx},
    }

    with requests.Session() as session:
        # 避免企業全域 HTTP_PROXY / HTTPS_PROXY 環境變數誤攔截 127.0.0.1 本機推論請求
        session.trust_env = False
        response = session.post(f"{ollama_host}/api/chat", json=payload, timeout=300)

    if response.status_code != 200:
        raise RuntimeError(f"Ollama 推論錯誤: HTTP {response.status_code} - {response.text}")

    response_json = response.json()
    model_response_content = response_json["message"]["content"]

    return MeetingMinutes.model_validate_json(model_response_content)


# =====================================================================
# 5. 稽核憑證簽發與不可竄改存證 (Audit Certificate Generation)
# =====================================================================

def generate_audit_certificate(
    raw_audio_path: str,
    normalized_audio_path: str,
    whisper_model_path: str,
    llm_model_name: str,
    prompt_stream: str,
    final_output_json: str,
    output_cert_path: str,
) -> Dict[str, Any]:
    """計算完整資料流雜湊鏈,產出不可竄改稽核存證書 (Audit Certificate)"""
    raw_audio_sha256 = calculate_sha256(raw_audio_path)
    norm_audio_sha256 = calculate_sha256(normalized_audio_path)
    prompt_sha256 = hashlib.sha256(prompt_stream.encode("utf-8")).hexdigest()
    output_sha256 = hashlib.sha256(final_output_json.encode("utf-8")).hexdigest()

    audit_cert = {
        "certificate_id": f"CERT-{datetime.now().strftime('%Y%m%d%H%M%S')}",
        "generated_at": datetime.now().isoformat(),
        "infrastructure": "AIR-GAPPED-ON-PREM-SECURE-NODE",
        "provenance_chain": {
            "raw_audio_sha256": raw_audio_sha256,
            "normalized_audio_sha256": norm_audio_sha256,
            "whisper_model_path": whisper_model_path,
            "llm_model": llm_model_name,
            "redacted_prompt_sha256": prompt_sha256,
            "final_output_sha256": output_sha256,
        },
        "compliance_statement": (
            "本文件流程經由離線地端推論生成,輸入音訊、提示詞與輸出成果均具備 SHA-256 完整性校驗,"
            "無任何資料外洩至外部公有雲端。"
        ),
    }

    Path(output_cert_path).parent.mkdir(parents=True, exist_ok=True)
    with open(output_cert_path, "w", encoding="utf-8") as f:
        json.dump(audit_cert, f, ensure_ascii=False, indent=2)

    return audit_cert


# =====================================================================
# 6. 離線自檢與測試音訊工具 (--self-test)
# =====================================================================

def _generate_synthetic_pcm_wav(wav_path: str, duration_sec: float = 0.5) -> str:
    """於本機生成 16kHz, Mono, 16-bit PCM WAV 測試音訊檔"""
    sample_rate = 16000
    n_samples = int(sample_rate * duration_sec)
    freq = 440.0
    Path(wav_path).parent.mkdir(parents=True, exist_ok=True)

    with wave.open(wav_path, "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(sample_rate)
        frames = bytearray()
        for i in range(n_samples):
            val = int(4000 * math.sin(2.0 * math.pi * freq * i / sample_rate))
            frames.extend(struct.pack("<h", val))
        wf.writeframes(bytes(frames))
    return wav_path


def run_self_test(base_dir: Path) -> None:
    """離線自檢模式:驗證雜湊指紋、Overlap 對齊、台灣個資 DLP、Pydantic Schema 與存證鏈"""
    workspace_dir = base_dir / "workspace"
    output_dir = base_dir / "output"
    workspace_dir.mkdir(parents=True, exist_ok=True)
    output_dir.mkdir(parents=True, exist_ok=True)

    raw_wav = str(workspace_dir / "self_test_raw.wav")
    norm_wav = str(workspace_dir / "normalized_16k.wav")
    out_transcript = output_dir / "redacted_transcript.txt"
    out_minutes = output_dir / "meeting_minutes.json"
    out_cert = output_dir / "audit_certificate.json"

    print("[SELF-TEST 1/5] 生成 16kHz Mono 16-bit PCM 測試音訊並計算 SHA-256...")
    _generate_synthetic_pcm_wav(raw_wav)
    if shutil.which("ffmpeg"):
        normalize_audio(raw_wav, norm_wav)
        print("  • 本機 FFmpeg 重採樣驗證通過")
    else:
        shutil.copyfile(raw_wav, norm_wav)
        print("  • 未偵測到系統 ffmpeg,已使用 wave 標準 16kHz PCM WAV 作為重採樣替代驗證")

    raw_hash = calculate_sha256(raw_wav)
    norm_hash = calculate_sha256(norm_wav)
    assert len(raw_hash) == 64 and len(norm_hash) == 64

    print("[SELF-TEST 2/5] 驗證時間軸交疊對齊演算法 (Overlap Sync)...")
    mock_asr = [
        {"start": 0.5, "end": 4.2, "text": "本案核准於內網節點啟用離線會議稽核系統,負責人身分證Z12345*789,手機0*12-345-678。"},
        {"start": 5.0, "end": 9.8, "text": "若有異常請聯繫值班工程師手機 0*87654321 或來信 audit.test@example.local。"},
    ]
    mock_diar = [
        {"start": 0.0, "end": 4.5, "speaker": "SPEAKER_00"},
        {"start": 4.8, "end": 10.5, "speaker": "SPEAKER_01"},
    ]
    aligned = align_transcript_and_speakers(mock_asr, mock_diar)
    assert aligned[0]["speaker"] == "SPEAKER_00"
    assert aligned[1]["speaker"] == "SPEAKER_01"

    print("[SELF-TEST 3/5] 驗證台灣個資 DLP 脫敏閘門(含無空白中文邊界測試)...")
    assert os.environ.get("HF_HUB_OFFLINE") == "1"
    analyzer, anonymizer = build_local_presidio_redactor()
    redacted_stream = redact_dialogue_stream(aligned, analyzer, anonymizer)
    assert "Z12345*789" not in redacted_stream
    assert "0*12-345-678" not in redacted_stream
    assert "0*87654321" not in redacted_stream
    assert "audit.test@example.local" not in redacted_stream
    assert "<TW_ID>" in redacted_stream
    assert redacted_stream.count("<PHONE_NUMBER>") == 2
    assert "<EMAIL_ADDRESS>" in redacted_stream

    with open(out_transcript, "w", encoding="utf-8") as f:
        f.write(redacted_stream + "\n")

    print("[SELF-TEST 4/5] 驗證 Pydantic MeetingMinutes Schema 校驗...")
    schema = MeetingMinutes.model_json_schema()
    assert (
        "properties" in schema
        and "decisions" in schema["properties"]
        and "action_items" in schema["properties"]
    )

    sample_payload = {
        "meeting_title": "離線內網語音轉文字合規自檢會議",
        "summary": "- 核准內網節點啟用離線會議稽核系統\n- 建立異常通報聯絡規範(個資已脫敏)",
        "decisions": [
            {
                "decision": "於內網節點啟用離線會議稽核系統",
                "context_quote": "[00:00] [SPEAKER_00]: 本案核准於內網節點啟用離線會議稽核系統,負責人身分證<TW_ID>,手機<PHONE_NUMBER>。",
                "timestamp": "00:00",
            }
        ],
        "action_items": [
            {
                "owner": "SPEAKER_01",
                "task": "維護異常通報聯絡窗口與 WORM 稽核紀錄",
                "deadline": None,
                "context_quote": "[00:05] [SPEAKER_01]: 若有異常請聯繫值班工程師手機 <PHONE_NUMBER> 或來信 <EMAIL_ADDRESS>。",
                "timestamp": "00:05",
            }
        ],
        "confidence_score": 0.98,
    }
    minutes_obj = MeetingMinutes.model_validate_json(json.dumps(sample_payload, ensure_ascii=False))
    minutes_json_str = minutes_obj.model_dump_json(indent=2)
    with open(out_minutes, "w", encoding="utf-8") as f:
        f.write(minutes_json_str)

    print("[SELF-TEST 5/5] 簽發並交叉驗證 SHA-256 不可竄改稽核憑證...")
    cert = generate_audit_certificate(
        raw_audio_path=raw_wav,
        normalized_audio_path=norm_wav,
        whisper_model_path="./models/whisper-large-v3",
        llm_model_name="qwen2.5:7b",
        prompt_stream=redacted_stream,
        final_output_json=minutes_json_str,
        output_cert_path=str(out_cert),
    )
    loaded_cert = json.loads(out_cert.read_text(encoding="utf-8"))
    chain = loaded_cert["provenance_chain"]
    assert chain["raw_audio_sha256"] == raw_hash
    assert chain["normalized_audio_sha256"] == norm_hash
    assert chain["redacted_prompt_sha256"] == hashlib.sha256(redacted_stream.encode("utf-8")).hexdigest()
    assert chain["final_output_sha256"] == hashlib.sha256(minutes_json_str.encode("utf-8")).hexdigest()

    print(f"[SELF-TEST PASS] Certificate ID: {cert['certificate_id']}")
    print(f"  • 脫敏逐字稿: {out_transcript}")
    print(f"  • 會議記錄 JSON: {out_minutes}")
    print(f"  • 稽核憑證 JSON: {out_cert}")


# =====================================================================
# 主控排程入口 (Main Orchestrator)
# =====================================================================

def main() -> None:
    base_dir = Path(__file__).resolve().parent

    parser = argparse.ArgumentParser(
        description="MP32TXT (Mp3toTxt) 離線隔離內網語音轉文字與合規稽核流水線"
    )
    parser.add_argument(
        "--audio",
        default=str(base_dir / "sample_meeting.mp3"),
        help="輸入音訊檔案路徑 (.wav / .mp3)",
    )
    parser.add_argument(
        "--normalized-audio",
        default=str(base_dir / "workspace" / "normalized_16k.wav"),
        help="FFmpeg 重採樣標準化音訊輸出路徑",
    )
    parser.add_argument(
        "--whisper-dir",
        default=str(base_dir / "models" / "whisper-large-v3"),
        help="離線 faster-whisper 模型權重目錄",
    )
    parser.add_argument(
        "--pyannote-config",
        default=str(base_dir / "models" / "pyannote_speaker_diarization_3_1" / "config.yaml"),
        help="離線 pyannote.audio Pipeline config.yaml 路徑",
    )
    parser.add_argument(
        "--output-dir",
        default=str(base_dir / "output"),
        help="輸出產物目錄 (transcript / meeting_minutes / audit_certificate)",
    )
    parser.add_argument(
        "--model",
        default="qwen2.5:7b",
        help="地端 Ollama 模型名稱",
    )
    parser.add_argument(
        "--ollama-host",
        default="http://127.0.0.1:11434",
        help="地端 Ollama API 主機位址",
    )
    parser.add_argument(
        "--self-test",
        action="store_true",
        help="執行離線端到端契約與 DLP 脫敏自檢模式",
    )
    args = parser.parse_args()

    if args.self_test:
        run_self_test(base_dir)
        return

    raw_audio = args.audio
    normalized_audio = args.normalized_audio
    whisper_dir = args.whisper_dir
    pyannote_config = args.pyannote_config
    output_dir = Path(args.output_dir)

    output_transcript = output_dir / "redacted_transcript.txt"
    output_minutes = output_dir / "meeting_minutes.json"
    output_cert = output_dir / "audit_certificate.json"

    Path(normalized_audio).parent.mkdir(parents=True, exist_ok=True)
    output_dir.mkdir(parents=True, exist_ok=True)

    print("[1/5] 執行音訊輸入校驗與標準化...")
    input_sha256 = calculate_sha256(raw_audio)
    print(f"  • 原始音訊 SHA-256: {input_sha256}")
    normalize_audio(raw_audio, normalized_audio)

    print("[2/5] 執行雙軌語音辨識與聲紋分離...")
    asr_segments = run_asr(normalized_audio, whisper_dir)
    diar_turns = run_diarization(normalized_audio, pyannote_config)

    print("[3/5] 時序對齊與在地 DLP 脫敏處理...")
    aligned_dialogue = align_transcript_and_speakers(asr_segments, diar_turns)
    analyzer, anonymizer = build_local_presidio_redactor()
    redacted_stream = redact_dialogue_stream(aligned_dialogue, analyzer, anonymizer)

    with open(output_transcript, "w", encoding="utf-8") as f:
        f.write(redacted_stream + "\n")

    print("[4/5] 地端大語言模型結構化萃取 (Pydantic 約束)...")
    minutes_obj = query_local_ollama(
        redacted_stream, model_name=args.model, ollama_host=args.ollama_host
    )
    minutes_json_str = minutes_obj.model_dump_json(indent=2)

    with open(output_minutes, "w", encoding="utf-8") as f:
        f.write(minutes_json_str)

    print("[5/5] 簽發不可竄改稽核存證書...")
    generate_audit_certificate(
        raw_audio_path=raw_audio,
        normalized_audio_path=normalized_audio,
        whisper_model_path=whisper_dir,
        llm_model_name=args.model,
        prompt_stream=redacted_stream,
        final_output_json=minutes_json_str,
        output_cert_path=str(output_cert),
    )

    print(f"完成!脫敏對話逐字稿已產出至 {output_transcript}")
    print(f"完成!會議記錄已產出至 {output_minutes}")
    print(f"稽核憑證已簽發至 {output_cert}")


if __name__ == "__main__":
    main()

方案架構核心 (上述為概念作法,僅供參考)

1. 時間軸交疊演算法 (Overlap Sync)
以每句文字識別為基準,計算其與所有發言者區間的交集長度 max(0, min(E1, E2) - max(S1, S2)),精準歸屬發言人標籤。
2. 在地 Presidio 閉環脫敏

擴充本地常見身分證、手機號碼正規表達式,於送入 LLM 推論前全面遮蔽,杜絕日誌與快取殘留 PII 風險。
3. Pydantic + Ollama 原生約束
透過 JSON Schema 強制約束地端 7B/8B 模型輸出合規 JSON,徹底根除額外廢話、Markdown 標記或欄位缺失。
4. WORM 數位存證鏈
串聯原始音訊、重採樣音訊、脫敏提示詞及結構化結果 SHA-256,提供合規稽核人員一鍵比對驗證完整性。

官方技術規格文件(供離線部署與稽核對照):

  1. Hugging Face Hub 離線環境變數與快取規範(HF_HUB_OFFLINE):

  2. faster-whisper(CTranslate2 離線推論參數 local_files_only):

  3. pyannote.audio 離線權重與本機 config.yaml 載入指南:

  4. Microsoft Presidio 自定義正則識別器(PatternRecognizer):

  5. Ollama 原生結構化輸出(Structured Outputs / JSON Schema)與 num_ctx 參數: