2026年11月15日 星期日

SKILL技能彙總參考資訊

📋 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 參數: