Spaces:
Sleeping
Sleeping
| #!/usr/bin/env python3 | |
| # -*- coding: utf-8 -*- | |
| """ | |
| app_agent.py | |
| 重譯文本分析系統 AI Agent（雙 Agent 架構） | |
| ──────────────────────────────────────────── | |
| 主 Agent (LLM1): google/gemma-4-31b-it | |
| → 研究情境詢問 & 最終研究報告撰寫 | |
| 工作程序Agent(LLM2): google/gemma-4-26b-a4b-it | |
| → 文本上傳引導 / 格式驗證 / 指標計算 / 統計分析 | |
| """ | |
| # ============================================================================ | |
| # SECTION 1: Imports & Configuration | |
| # ============================================================================ | |
| import sys, io, os, re, json, uuid, shutil, warnings, functools, collections, time | |
| import threading, zipfile, traceback | |
| # 強制 UTF-8 輸出（避免 Windows cp950 編碼錯誤） | |
| if sys.platform.startswith("win"): | |
| try: | |
| sys.stdout.reconfigure(encoding="utf-8", errors="replace", line_buffering=True) | |
| sys.stderr.reconfigure(encoding="utf-8", errors="replace", line_buffering=True) | |
| except AttributeError: | |
| sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace") | |
| sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace") | |
| from pathlib import Path | |
| from datetime import datetime, timezone, timedelta | |
| # 台灣時區（UTC+8）：確保雲端（UTC 伺服器）與本地時間一致 | |
| TW_TZ = timezone(timedelta(hours=8)) | |
| def now_tw(): | |
| """回傳台灣時間（UTC+8），不受伺服器時區影響。""" | |
| return datetime.now(TW_TZ) | |
| from collections import Counter | |
| import numpy as np | |
| import pandas as pd | |
| import scipy.stats as stats | |
| import matplotlib | |
| matplotlib.use('Agg') | |
| import matplotlib.pyplot as plt | |
| import matplotlib.font_manager as fm | |
| from sklearn.ensemble import RandomForestClassifier | |
| from sklearn.model_selection import train_test_split | |
| from sklearn.metrics import accuracy_score, classification_report | |
| from sklearn.preprocessing import LabelEncoder, StandardScaler | |
| from sklearn.cluster import KMeans, AgglomerativeClustering | |
| from sklearn.decomposition import PCA | |
| from scipy.cluster.hierarchy import dendrogram, linkage | |
| from docx import Document | |
| from docx.shared import Pt, Cm, RGBColor | |
| from docx.enum.table import WD_TABLE_ALIGNMENT | |
| from docx.enum.text import WD_ALIGN_PARAGRAPH | |
| import urllib.request, urllib.error | |
| import gradio as gr | |
| warnings.filterwarnings('ignore') | |
| print = functools.partial(print, flush=True) | |
| # ── 載入 .env 環境變數 ─────────────────────────────────────────────────────── | |
| try: | |
| from dotenv import load_dotenv | |
| load_dotenv(Path(__file__).parent / ".env") | |
| except ImportError: | |
| print("[警告] 未安裝 python-dotenv，略過 .env 載入（請執行 pip install python-dotenv）") | |
| # ── 路徑常數 ──────────────────────────────────────────────────────────────── | |
| BASE_DIR = Path(__file__).parent | |
| CORPUS_INFO = BASE_DIR / "01-Corpus" / "03-Info" | |
| SESSIONS_DIR = BASE_DIR / "sessions" | |
| SESSIONS_DIR.mkdir(exist_ok=True) | |
| # ── Session 目錄自動清理（2026-08-22，見 docs/開發優化建議.md 第四節）──────── | |
| # 每個 session 資料夾含使用者上傳的原始語料與全部分析產出，先前沒有任何過期 | |
| # 清理機制，會無限期留在磁碟上（正式機部署在 Hugging Face Spaces，公開對外 | |
| # 使用後這個問題會更明顯）。這裡加一支獨立的清理工具：只依資料夾的最後修改 | |
| # 時間（mtime）判斷是否過期，不讀取、不解析任何 session 內部狀態，因此不算 | |
| # 觸碰《開發優化建議.md》第五節界定的高風險核心運算區。 | |
| SESSION_RETENTION_DAYS_DEFAULT = 7 # 保留天數，可用環境變數 SESSION_RETENTION_DAYS 覆寫 | |
| def cleanup_old_sessions(max_age_days: int = None) -> int: | |
| """刪除 SESSIONS_DIR 底下超過保留天數的舊 session 資料夾。 | |
| 以資料夾本身的最後修改時間（mtime）判斷年齡：分析運算過程中會持續寫入 | |
| 該資料夾（上傳檔案、指標 CSV、圖表、報告……），mtime 會隨之更新，因此 | |
| 不會誤刪還在使用中的 session；只有久沒被寫入、代表使用者早已離開的舊 | |
| 資料夾才會被清掉。 | |
| 回傳實際刪除的資料夾數量（供啟動 log 顯示，非必要）。 | |
| """ | |
| if max_age_days is None: | |
| max_age_days = int(os.environ.get("SESSION_RETENTION_DAYS", str(SESSION_RETENTION_DAYS_DEFAULT))) | |
| if not SESSIONS_DIR.exists(): | |
| return 0 | |
| cutoff = datetime.now(timezone.utc).timestamp() - max_age_days * 86400 | |
| deleted = 0 | |
| for entry in SESSIONS_DIR.iterdir(): | |
| if not entry.is_dir(): | |
| continue | |
| try: | |
| if entry.stat().st_mtime < cutoff: | |
| shutil.rmtree(entry, ignore_errors=True) | |
| deleted += 1 | |
| except FileNotFoundError: | |
| continue # 極少數情況下清理過程中資料夾被同時刪除，略過即可 | |
| if deleted: | |
| print(f"【Session 清理】已刪除 {deleted} 個超過 {max_age_days} 天未使用的舊 session 資料夾。") | |
| return deleted | |
| def start_session_cleanup_scheduler() -> None: | |
| """啟動一支背景 daemon 執行緒：程式啟動時先清一次，之後每 24 小時重跑一次。 | |
| 只在程序啟動時呼叫一次即可。用背景執行緒（而非只在啟動時跑一次）的原因： | |
| Hugging Face Spaces 若持續有人使用，容器可能長時間不重啟，只在啟動時清 | |
| 一次的話，長期掛著不重啟的情況下舊資料夾一樣會無限期累積。 | |
| """ | |
| def _loop(): | |
| while True: | |
| try: | |
| cleanup_old_sessions() | |
| except Exception as e: | |
| print(f"【Session 清理】背景清理發生例外（不影響主程式運作）：{e}") | |
| time.sleep(24 * 3600) | |
| threading.Thread(target=_loop, daemon=True, name="session-cleanup").start() | |
| # ── LLM 設定 ──────────────────────────────────────────────────────────────── | |
| # API 金鑰維持環境變數（本來就該是每個部署環境各自設定的機密資訊，不進版控）。 | |
| LLM1_API_KEY = os.environ.get("LLM1_API_KEY", "") | |
| LLM2_API_KEY = os.environ.get("LLM2_API_KEY", "") | |
| # 2026-08-22（業主要求：為研究結果的「可重複性」鎖定模型版本）：模型代號 | |
| # 原本是 `os.environ.get("LLM1_MODEL", "google/gemma-4-31b-it")`——可以被 | |
| # 環境變數在執行期任意覆寫，且不會留下任何紀錄。docs/開發優化建議.md 第 | |
| # 3.3／3.4 節就記錄過一次真實案例：測試環境曾被覆寫成 `openrouter/free` | |
| # 這種自動路由別名，同一個代號兩次呼叫被導去兩個不同的實際模型，耗時與 | |
| # 輸出品質都不穩定——這正是「模型版本沒鎖定」會實際發生的風險，不是假設。 | |
| # 改成固定常數：只能透過修改這裡的程式碼（進而走 git commit 留下紀錄） | |
| # 才能更換模型，執行期無法覆寫，「這次分析用的是哪個模型」才會是一個 | |
| # 可以回頭稽核、不會被悄悄改掉的事實。 | |
| LLM1_MODEL = "google/gemma-4-31b-it" | |
| LLM2_MODEL = "google/gemma-4-26b-a4b-it" | |
| # 2026-08-22（同上，可重複性設計之二：提示詞版本控制）：SYSTEM_PROMPT_BASE | |
| # 與各 SCENARIO_MODULE_* 本身已經隨這個檔案進 git 版控，但報告產出當下 | |
| # 沒有留下任何「這份報告是哪一版提示詞寫的」的紀錄——事後拿到一份舊報告， | |
| # 沒辦法回推當時的提示詞內容跟現在是否一致。這裡加一個顯式版本號，每次 | |
| # 異動 SYSTEM_PROMPT_BASE 或任一 SCENARIO_MODULE_* 的內容時手動遞增，並且 | |
| # 直接印在每份產出的報告上（見 run_report_writing()），讓版本資訊跟著 | |
| # 報告本身走，不用回頭 git blame 才查得到。 | |
| PROMPT_VERSION = "v1" | |
| # 2026-08-26（「關於本系統」面板用）：跟 PROMPT_VERSION 是兩件不同的事—— | |
| # PROMPT_VERSION 只追蹤 LLM 提示詞內容，這個追蹤的是整個系統（畫面、流程、 | |
| # 各項修正）的版本，給使用者回報問題時對照用。用日期字串（而非 v1.0 這種 | |
| # 語意化版號）是刻意的：日期比較不會忘記更新，且跟 使用說明.md 文末的 | |
| # 「文件版本」日期同一套慣例。有實質功能異動時手動更新這個日期即可。 | |
| APP_VERSION = "2026-08-26" | |
| # 2026-08-26（業主指定內容）：導覽列「關於」按鈕彈出的說明面板。版權聲明／ | |
| # 聯絡方式／Bug 回報／引用格式這四項業主明確要求「論文發表前不公開姓名或 | |
| # 信箱」，這裡不放任何真實聯絡資訊、也不留 [方括號] 這種看起來像沒填完的 | |
| # 佔位符，改寫成正式的「將於論文發表後公開」——對使用者來說是完整、有意義 | |
| # 的句子，之後論文發表了直接把這幾行換成真實資訊即可。 | |
| ABOUT_CONTENT_MD = f"""## 關於本系統 | |
| **譯彩紛呈 II 分析引擎 SpectraEngine**（TransPrism: An Analytical Framework for Retranslation II） | |
| 系統版本：{APP_VERSION} 回報問題時請附上此版本號 | |
| --- | |
| ### 免責聲明 | |
| 本系統分析結果僅供研究參考，不構成正式學術判斷；上傳內容將傳送至第三方 AI 服務進行分析，請勿上傳尚未公開發表之機密內容。 | |
| ### 姊妹工具 | |
| 文本須先經由「[語料淬鍊（CorpusRefinery）](https://github.com/minchun-git/I_CorpusRefinery)」完成斷詞後才能上傳本系統分析。 | |
| ### 開發紀錄 | |
| 系統功能與版本異動，請參見導覽列「使用說明」文末的文件版本紀錄。 | |
| ### 版權聲明 | |
| © 2026｜作者姓名／單位將於論文發表後公開 | |
| ### 聯絡方式 | |
| 將於論文發表後公開 | |
| ### Bug 回報 | |
| 聯絡窗口將於論文發表後公開 | |
| ### 引用格式 | |
| 建議引用格式將於論文發表後一併提供 | |
| """ | |
| ALPHA = 0.05 | |
| # 2026-08-22（業主提出「數據完整性檢查」的必要性，追查後確認是真實存在的 | |
| # 問題）：差異性檢定（t 檢定／ANOVA）在任一組樣本數 N<2 時，scipy 會算出 | |
| # p=NaN（沒有組內變異，這個檢定工具本來就不適用），但 `NaN < 0.05` 這類比較 | |
| # 在 Python 裡恆為 False，若不特別攔截，會一路 fallthrough 到「無顯著差異」 | |
| # 的判斷分支，跟「有算出結果、但真的沒有顯著差異」變成同一個值，讀者與 LLM | |
| # 都無法分辨「資料不足、根本沒辦法檢定」跟「檢定過、沒有差異」這兩種本質 | |
| # 不同的情況。「個體間比較」功能（見 _extract_individual_grouping）允許 | |
| # 把分組粒度細到每個檔案自己一組，N=1 per group 是實際會發生的情境，不是 | |
| # 假設的邊角案例。這裡定義一個獨立標籤，任何用到「顯著」欄位的地方都要用 | |
| # 這個常數判斷，不要漏掉、也不要各自硬寫字串。 | |
| INSUFFICIENT_DATA_LABEL = "資料不足" | |
| # 2026-08-24（業主回報：報告上出現「Cohen's d=-9028313184615308.0」這種 | |
| # 誇張數字）：跟上面 INSUFFICIENT_DATA_LABEL 是兩種不同性質的問題，不要混用 | |
| # ——INSUFFICIENT_DATA_LABEL 代表「p=NaN，檢定本身無法執行」；這個標籤代表 | |
| # 「p 值有效、檢定確實跑出顯著結果，但 Cohen's d／η² 的公式分母（組內變異） | |
| # 趨近於零，除出來的數字在數值上不穩定、失真」。兩組數值幾乎沒有組內變異卻 | |
| # 彼此不同，是統計上最乾淨俐落的一種顯著差異，不該被當成「檢定失敗」處理， | |
| # 顯著性判斷（p 值）仍然有效、正常參與統計比例；只有效果量這個數字本身 | |
| # 換成這個描述性標籤，不強行印出失真的天文數字。 | |
| EFFECT_UNSTABLE_LABEL = "效果量不穩定（組內變異趨近於零）" | |
| # 2026-08-24（業主回報：AG_05 在 MT 組標準差為 0，Welch t 檢定仍算出 | |
| # p=.047 並被 LLM 列為顯著發現，但這個結果不可靠）：這是跟上面兩種都不同 | |
| # 的第三種退化情況——Welch t 檢定公式是 t = (mean1-mean2) / sqrt(var1/n1 + | |
| # var2/n2)，只要「其中一組」變異數不是零，分母就不會退化成 0 或 NaN， | |
| # 檢定照樣算得出一個數值上正常、但統計上不可靠的 p 值；INSUFFICIENT_DATA_ | |
| # LABEL（p=NaN）跟 EFFECT_UNSTABLE_LABEL（兩組都幾乎零變異、Cohen's d 分母 | |
| # 趨近於零）都攔不到這種「只有一組零變異」的情況。這裡不動指標計算方式 | |
| # 本身（AG_05 算出來是 0 就是事實），只在檢定這一層加警示標記——p 值與 | |
| # 效果量照常計算、正常參與顯著性統計，只是額外附註「這個結果的統計穩定性 | |
| # 存疑」，供人與 LLM 判讀時謹慎看待，不當成跟其他乾淨顯著結果同等份量 | |
| # 的證據。 | |
| ZERO_VARIANCE_WARNING = "⚠️ 其中一組標準差為 0，檢定結果之統計穩定性有限，建議謹慎解讀" | |
| # 2026-08-28（業主追問「零膨脹」偵測）：上面 ZERO_VARIANCE_WARNING 只抓「整組標準差 | |
| # 趨近於 0」——通常代表該組幾乎全部樣本值相同（多半是全部掛零）。但還有一種較不極端、 | |
| # SD 判準抓不到的退化情況：某組樣本值大量集中在 0，只靠少數幾筆非零值撐出「看起來 | |
| # 正常」的變異數，平均數與檢定結果其實被那幾筆離群值主導，不能代表該組的整體特徵。 | |
| # 這裡另開一條獨立判準：任一組零值比例達到 ZERO_PROPORTION_THRESHOLD（預設 | |
| # 50%，過半數樣本為 0）就額外標記。門檻定 50% 而不是更低（如 20%、30%）的理由： | |
| # 許多語言指標（如成語、特定詞性頻率）本身就容易有不少檔案掛零，門檻太低會對 | |
| # 「只是資料偏稀疏但正常」的指標大量誤報、稀釋警示的可信度；50%（過半數）才是 | |
| # 「零值已經是這組的主流樣態」的合理起點。刻意只在該組「尚未被 SD 判準抓到」時 | |
| # 才檢查零值比例（見下方偵測邏輯），避免同一組資料被兩條規則重複描述。 | |
| ZERO_PROPORTION_THRESHOLD = 0.5 | |
| ZERO_PROPORTION_WARNING = "⚠️ 其中一組逾半數樣本值為 0，資料集中於零值，檢定結果建議謹慎解讀" | |
| # ── POS 集合（與 Prog02 相同）─────────────────────────────────────────────── | |
| Vset = ['VC','VH','VE','VJ','VA','V2','VK','VL','VD','VCL','VHC','VB','VF','VI','VAC','VG'] | |
| Nset = ['Na','Nb','Nc','Ncd','Nd','Nf','Nh','Nv'] | |
| Nhset = ['Nh'] | |
| ADVset = ['D','Da','Dfa','Dfb','Dk'] | |
| Cset = ['Caa','Cbb'] | |
| Caset = ['Caa'] | |
| Cbset = ['Cbb'] | |
| DETset = ['Neu','Nes','Nep','Neqa'] | |
| POSTset= ['Cab','Cba','Neqb','Ng'] | |
| Tset = ['I','T'] | |
| Aset = ['A'] | |
| # ── 研究情境定義 ───────────────────────────────────────────────────────────── | |
| SCENARIOS = { | |
| "1": { | |
| "title": "人工翻譯 vs 機器翻譯", | |
| "short": "人機對比", | |
| "upload_prompt": ( | |
| "1. 檔案格式：僅接受 **.txt** 純文字檔。\n" | |
| "2. 檔名規範：請以 **A_xx.txt**、**B_xx.txt** 等格式區分人工翻譯與機器翻譯。\n" | |
| "3. 斷詞要求：必須先使用 [語料淬鍊](https://github.com/minchun-git/I_CorpusRefinery) 工具完成斷詞。\n" | |
| "4. 內容格式：僅限 `詞_詞性` 或空白行。" | |
| ), | |
| "desc": "焦點在人機差異的語言特徵。", | |
| "scenario_module_key": "scenario_2", | |
| }, | |
| "2": { | |
| "title": "全譯 vs 編譯（節譯、改寫）", | |
| "short": "全譯vs編譯", | |
| "upload_prompt": ( | |
| "1. 檔案格式：僅接受 **.txt** 純文字檔。\n" | |
| "2. 檔名規範：請以 **A_xx.txt**、**B_xx.txt** 等格式區分全譯與編譯。\n" | |
| "3. 斷詞要求：必須先使用 [語料淬鍊](https://github.com/minchun-git/I_CorpusRefinery) 工具完成斷詞。\n" | |
| "4. 內容格式：僅限 `詞_詞性` 或空白行。" | |
| ), | |
| "desc": "焦點在文本完整性和改寫策略。", | |
| "scenario_module_key": "scenario_3", | |
| }, | |
| "3": { | |
| "title": "不同譯者的同期譯本", | |
| "short": "譯者風格", | |
| "upload_prompt": ( | |
| "1. 檔案格式：僅接受 **.txt** 純文字檔。\n" | |
| "2. 檔名規範：請以 **A_xx.txt**、**B_xx.txt**、**C_xx.txt** 等格式區分不同群組的譯者。\n" | |
| "3. 斷詞要求：必須先使用 [語料淬鍊](https://github.com/minchun-git/I_CorpusRefinery) 工具完成斷詞。\n" | |
| "4. 內容格式：僅限 `詞_詞性` 或空白行。" | |
| ), | |
| "desc": "焦點在個人風格差異。排除時代因素，討論譯者個人的語言偏好。", | |
| "scenario_module_key": "scenario_4", | |
| }, | |
| "4": { | |
| "title": "不同時期人工譯本", | |
| "short": "歷時重譯", | |
| "upload_prompt": ( | |
| "1. 檔案格式：僅接受 **.txt** 純文字檔。\n" | |
| "2. 檔名規範：請以 **A_xx.txt**、**B_xx.txt**、**C_xx.txt** 等格式區分不同時期的譯本。\n" | |
| "3. 斷詞要求：必須先使用 [語料淬鍊](https://github.com/minchun-git/I_CorpusRefinery) 工具完成斷詞。\n" | |
| "4. 內容格式：僅限 `詞_詞性` 或空白行。" | |
| ), | |
| "desc": "分析焦點在歷時變化、語言現代化、翻譯規範的演變。時間維度是核心變數。", | |
| "scenario_module_key": "scenario_1", | |
| }, | |
| } | |
| # ── 指標分類（同 prog03）──────────────────────────────────────────────────── | |
| INDEX_CATEGORIES = { | |
| "基礎統計": { | |
| "AA_01": "總字數", "AA_02": "相異字數", "AA_03": "總詞數", | |
| "AA_04": "相異詞數", "AA_05": "段落數", "AA_06": "總句數", | |
| }, | |
| "詞彙難易度": {"AC_01": "非常用詞比率", "AC_02": "難詞比率"}, | |
| "詞彙多樣性": {"AD_02": "MSTTR", "AD_03": "RTTR"}, | |
| "語意複雜度": { | |
| "AG_01": "詞彙密度1", "AG_02": "詞彙密度2", | |
| "AG_05": "每千詞成語數1", "AG_06": "每千詞成語數2", | |
| }, | |
| "語法複雜度": { | |
| "AH_01": "平均句長", "AH_03": "句長標準差", | |
| "AH_06": "平均小句長度", "AH_08": "小句標準差", | |
| }, | |
| "篇章連貫": { | |
| "AJ_01": "對等關聯連接詞密度", | |
| "AJ_02": "連接詞總密度", | |
| "AJ_03": "從屬連接詞密度", | |
| "AJ_04": "指示代詞密度", | |
| "AJ_05": "一般代名詞密度", | |
| "AJ_06": "指示照應代詞密度", | |
| "AJ_07": "第一人稱代詞密度", | |
| "AJ_08": "第二人稱代詞密度", | |
| "AJ_09": "第三人稱代詞密度", | |
| "AJ_10": "泛指與反身代詞密度", | |
| "AJ_11": "泛指與反身代詞密度2", | |
| }, | |
| "詞性標記": { | |
| "AF_01": "A非謂形容詞", "AF_02": "Caa對等連接詞", "AF_03": "Cab連接詞", | |
| "AF_04": "Cba連接詞", "AF_05": "Cbb關聯連接詞", "AF_06": "D副詞", | |
| "AF_07": "Da數量副詞", "AF_08": "DE的之得地", | |
| "AF_09": "Dfa動詞前程度副詞", "AF_10": "Dfb動詞後程度副詞", | |
| "AF_11": "Di時態標記", "AF_12": "Dk句副詞", "AF_14": "I感嘆詞", | |
| "AF_15": "Na普通名詞", "AF_16": "Nb專有名詞", "AF_17": "Nc地方詞", | |
| "AF_18": "Ncd位置詞", "AF_19": "Nd時間詞", "AF_20": "Nep指代定詞", | |
| "AF_21": "Neqa數量定詞", "AF_22": "Neqb後置數量定詞", | |
| "AF_23": "Nes特指定詞", "AF_24": "Neu數詞定詞", "AF_25": "Nf量詞", | |
| "AF_26": "Ng後置詞", "AF_27": "Nh代名詞", "AF_28": "Nv名物化動詞", | |
| "AF_29": "P介詞", "AF_30": "SHI是", "AF_31": "T語助詞", | |
| "AF_32": "V2有", "AF_33": "VA動作不及物動詞", "AF_34": "VAC動作使動動詞", | |
| "AF_35": "VB動作類及物動詞", "AF_36": "VC動作及物動詞", | |
| "AF_37": "VCL動作接地方賓語動詞", "AF_38": "VD雙賓動詞", | |
| "AF_39": "VE動作句賓動詞", "AF_40": "VF動作謂賓動詞", | |
| "AF_41": "VG分類動詞", "AF_42": "VH狀態不及物動詞", | |
| "AF_43": "VHC狀態使動動詞", "AF_44": "VI狀態類及物動詞", | |
| "AF_45": "VJ狀態及物動詞", "AF_46": "VK狀態句賓動詞", | |
| "AF_47": "VL狀態謂賓動詞", | |
| }, | |
| } | |
| INDEX_NAME_MAP = {} | |
| INDEX_CATEGORY_MAP = {} | |
| for _cat, _items in INDEX_CATEGORIES.items(): | |
| for _code, _name in _items.items(): | |
| INDEX_NAME_MAP[_code] = _name | |
| INDEX_CATEGORY_MAP[_code] = _cat | |
| # 2026-08-14（業主要求）：相異字數（AA_02）＋相異詞數（AA_04）＋篇章連貫 | |
| # 全類（AJ_01～AJ_11，共 11 項），合計 13 項暫時整理掉，不刪除計算本身， | |
| # 只在「結果呈現」的地方隱藏——業主拍板範圍是全面隱藏：敘述統計、差異性 | |
| # 分析、隨機森林特徵重要性、分群分析都不再拿這 13 項當特徵，LLM 報告也 | |
| # 不會提到；語言指標分析分頁的表格畫面同理濾掉。 | |
| # textIndex_calculated.csv／.xlsx（指標計算原始輸出檔＋其下載）刻意不動， | |
| # 仍保留完整 75 項，理由是業主明確說「無須刪除」——這兩個檔案是計算結果的 | |
| # 原始存檔，不算「結果呈現」，之後要復原顯示只要拿掉這個集合的套用即可， | |
| # 不用重跑指標計算。 | |
| HIDDEN_INDICATOR_CODES = {"AA_02", "AA_04"} | {f"AJ_{i:02d}" for i in range(1, 12)} | |
| def _drop_hidden_indicators(df): | |
| """回傳去掉 HIDDEN_INDICATOR_CODES 欄位後的 DataFrame（欄名為原始指標代碼）。""" | |
| cols = [c for c in HIDDEN_INDICATOR_CODES if c in df.columns] | |
| return df.drop(columns=cols) if cols else df | |
| # 2026-08-14：介面上凡是提到「系統共計算幾項語言指標」的地方，一律引用這個 | |
| # 常數，不要各自寫死數字——INDEX_NAME_MAP 是系統定義的指標總表（目前 75）， | |
| # 扣掉 HIDDEN_INDICATOR_CODES 就是使用者實際會看到的指標數（目前 62）。 | |
| # 之後隱藏清單增減，這裡跟著自動變動，不用每次巡一遍程式碼改字面數字。 | |
| TOTAL_VISIBLE_INDICATORS = len(INDEX_NAME_MAP) - len(HIDDEN_INDICATOR_CODES) | |
| # 2026-08-24（業主提供 system_prompts_v1.3_0529.md 設計稿，要求補回原始設計 | |
| # 裡有、但現行實作缺少的內容）：v1.3 在 system prompt 裡內嵌了一份完整的 | |
| # 指標代碼對照表，讓 LLM 有明確依據判斷每個代碼的意思，並規定「未列於 | |
| # 對照表的代碼視為未定義指標」（見嚴格禁令第 10 條）。這裡不手動謄寫一份 | |
| # 靜態文字（那樣容易跟 INDEX_CATEGORIES 各自走鐘、兩份對不起來），改成 | |
| # 直接從 INDEX_CATEGORIES 動態產生，且比照 HIDDEN_INDICATOR_CODES 的規則 | |
| # 排除隱藏指標——LLM 實際收到的 JSON 資料本來就已經濾掉這 13 項，對照表 | |
| # 若照樣列出它們，LLM 反而會誤以為資料裡漏了這些代碼、去猜測或杜撰。 | |
| def _build_indicator_reference_table() -> str: | |
| lines = [] | |
| for cat, items in INDEX_CATEGORIES.items(): | |
| visible = {c: n for c, n in items.items() if c not in HIDDEN_INDICATOR_CODES} | |
| if not visible: | |
| continue | |
| lines.append(f"## {cat}") | |
| for code, name in visible.items(): | |
| lines.append(f"- {code} {name}") | |
| return "\n".join(lines) | |
| INDICATOR_REFERENCE_TABLE = _build_indicator_reference_table() | |
| # ── LLM 報告用情境模組（同 prog04）───────────────────────────────────────── | |
| SCENARIO_MODULE_1 = """## 三、情境特定分析：歷時變化分析 | |
| 在陳述差異時，必須將「時間順序」作為組織軸線。 | |
| 請依照以下子項目分析： | |
| ### 3.1 語言現代化的跡象 | |
| - 詞彙難易度（AC_01, AC_02）是否隨時間呈現規律變化？ | |
| - 成語比率（AG_06）在不同時期譯本中的變化方向？ | |
| - 若出現非單調變化，明確標示此為反常模式，需進一步解釋。 | |
| ### 3.2 句式與篇章結構的演變 | |
| - 段落數、句數（AA_05, AA_06）的變化是否反映閱讀習慣的改變？ | |
| - 詞性分布中，連接詞、代詞比例的變化是否呈現顯著化或隱化趨勢？ | |
| ### 3.3 譯本間的親疏關係 | |
| - 根據分群結果，時序相鄰的譯本是否聚為一群？ | |
| - 若出現時序相隔較遠的譯本反而更相似的情況，標記為需進一步探討的現象。 | |
| ### 禁令補充 | |
| - 不得將「較新」直接等同於「較現代」或「較好」。""" | |
| SCENARIO_MODULE_2 = """## 三、情境特定分析：人機差異分析 | |
| ### 3.1 機器翻譯典型特徵的檢視 | |
| 根據量化數據檢視機器翻譯是否呈現以下已知特徵： | |
| - 詞彙多樣性是否偏低？（MSTTR, RTTR） | |
| - 句長是否較為整齊（變異數較小）？ | |
| ### 3.2 人工翻譯的差異化特徵 | |
| - 人工譯本在哪些指標上顯著偏離機器譯本？ | |
| ### 禁令補充 | |
| - 不得預設「人工一定優於機器」或反之。""" | |
| SCENARIO_MODULE_3 = """## 三、情境特定分析：改寫策略分析 | |
| 【重要限制】：本系統目前未進行原文對齊，所有關於刪減/增補的陳述必須明確標示為「推測」。 | |
| ### 3.1 規模差異的量化 | |
| - 總字數、總詞數（AA_01, AA_03）的差距幅度 | |
| ### 3.2 改寫策略的語言訊號 | |
| - 編譯本的詞彙密度是否反而較高？（可能反映資訊壓縮策略） | |
| - 編譯本的平均句長是否較短？（可能反映簡化策略） | |
| ### 禁令補充 | |
| - 嚴禁使用「忠實度」、「完整性」等規範性詞彙。""" | |
| SCENARIO_MODULE_4 = """## 三、情境特定分析：個人風格差異分析 | |
| 【前提】：所有譯本產出於相近時期，時代因素已被控制。 | |
| ### 3.1 核心風格指標的差異 | |
| - 在哪些指標上，譯者間差異達到統計顯著？ | |
| ### 3.2 風格穩定性的檢視 | |
| - 譯者內變異 vs 譯者間變異的比較""" | |
| SCENARIO_MODULES = { | |
| "scenario_1": SCENARIO_MODULE_1, | |
| "scenario_2": SCENARIO_MODULE_2, | |
| "scenario_3": SCENARIO_MODULE_3, | |
| "scenario_4": SCENARIO_MODULE_4, | |
| } | |
| SYSTEM_PROMPT_BASE = """# 角色定義 | |
| 你是一位翻譯研究的量化分析助理。你的工作是將統計數據轉化為結構化的觀察與假設，供研究者進一步驗證。 | |
| 你的角色邊界： | |
| - 你是數據的描述者與模式的辨識者，不是結論的下定者。 | |
| - 你產出的是「初步假設」，不是「研究發現」。 | |
| - 所有假設都需要研究者基於專業知識進行最終的詮釋、驗證與修正。 | |
| # 嚴格禁令 | |
| 以下禁令為絕對規則，違反任一項即為失敗輸出： | |
| 1. 僅根據本次提供的量化數據進行分析。不得引入外部知識，不得引用任何關於具體譯本、譯者、作品的已有評價、學術討論或文學史定位。 | |
| 2. 不得使用以下類型的評價性詞彙描述任何譯本：「優秀」、「忠實」、「準確」、「流暢」、「高品質」、「拙劣」、「粗糙」、「典雅」、「洗鍊」。 | |
| 3. 不得推測譯者的主觀意圖、情感、動機或翻譯理念，除非數據直接支持且標明為推論。 | |
| 4. 不得將個人風格差異與「翻譯能力」或「翻譯素養」掛鉤。語言特徵的差異僅反映選擇的不同，不代表能力的高低。 | |
| 5. 遇到數據中未涵蓋的問題，明確回答「本次數據無法回答此問題」，不得編造或外推。 | |
| 6. 所有關於統計顯著性的陳述必須基於提供的 p 值或效果量。未提供 p 值的指標差異，使用「數值上的差距」而非「顯著差異」來描述；不得自行使用「明顯」、「大幅」、「顯著」等程度副詞，除非有統計依據。 | |
| 7. 不得對翻譯品質做整體評價或排名。 | |
| 8. metadata 處理規則： | |
| a. 語料 metadata 中標示為「（未填）」或完全未提及的欄位：分析時不得對該欄位做任何推論或臆測。 | |
| b. 群組層資訊中，若某一組別完全未出現任何說明（該組別整段未列出）：視同該組別背景未知，不得杜撰其翻譯類型、方向或譯者背景。 | |
| c. 個體層資訊中，若某一檔案完全未列出對應說明：視同該檔案背景未知，不得杜撰其譯者、出版年等資訊。 | |
| d. 群組層資訊中所有組別皆未填寫「群組標籤」：在「一、語料說明」中明確標記「群組標籤未提供，以下分析僅基於數值差異，不涉及群組身份的討論」。 | |
| e. 使用者於語料 Metadata 步驟選擇略過：僅陳述「使用者未提供語料補充說明」，不得臆測或杜撰任何背景內容。 | |
| 9. metadata 僅用於框定分析範圍與數據結構關係，不得用於構建敘事性的譯者畫像或歷史背景描述。 | |
| 10. 未定義指標處理規則：若量化分析結果中出現未列於下方「指標代碼對照表」的指標代碼，不得猜測其含義、不得將其納入任何分析步驟，須在「四、待驗證事項」中標記為「未定義指標：{{代碼}}」。 | |
| 11. 跨指標邏輯連結許可：允許連結多個指標的結果進行邏輯推論，但須滿足： | |
| a. 所連結的每個指標均有明確的數據支持（數值或統計檢定結果）。 | |
| b. 連結的邏輯基礎來自下方指標代碼對照表中的定義關係，不得憑空聯想。 | |
| c. 必須在陳述中明確標示「此為跨指標推論」，以區分直接的數據觀察。 | |
| d. 不得基於外部知識進行跨指標連結。 | |
| # 指標代碼對照表 | |
| 以下對照表僅供符號辨識用，不代表任何詮釋框架。未列於此對照表的指標代碼依嚴格禁令第 10 條處理。 | |
| {indicator_reference_table} | |
| # 輸入資料結構 | |
| 【研究情境】：{scenario_type} | |
| 【譯本 metadata】：{metadata} | |
| 【量化分析結果】：（見 user message 中的 JSON 資料） | |
| 【使用者補充關注點】：{user_focus} | |
| # 格式規範（務必嚴格遵守，直接影響報告的可讀性） | |
| 1. 以下「通用輸出結構」中 `## 一、`、`## 二、`、`## 四、`、`## 五、` 這幾個章節標題，輸出時必須原樣保留 `## ` 這個 Markdown 標題語法開頭，不可改寫成「**粗體**」或其他格式。 | |
| 2. 章節內若需要子標題或小節提示語（例如「總體事實」「觀察」「結論」之類的段落標籤），一律使用 `#### ` 開頭的四級標題語法，不可用「**粗體**」取代標題。 | |
| 3. `**粗體**` 只能用於一般敘述中的強調字詞，不可整行只放一個粗體片語來充當標題。 | |
| 4. 表格請使用標準 Markdown 表格語法（`| 欄位 | 欄位 |` 搭配 `|---|---|` 分隔列）。 | |
| 5. 量化分析結果 JSON 裡的英文鍵名（例如 rf_accuracy、rf_accuracy_is_meaningful、HC_Cluster、 | |
| KM_Cluster 等）是給程式讀取用的變數名稱，敘述時一律換成中文說法（例如「隨機森林分類準確率」 | |
| 「此準確率是否具備樣本外預測意義」「階層式分群」「K-means 分群」），不得原樣把英文鍵名寫進 | |
| 報告內文；指標代碼（如 AF_36、AC_01 這類）例外，這些代碼本身就是報告的一部分，要保留。 | |
| # 通用輸出結構 | |
| 輸出必須包含以下五個區塊，缺一不可： | |
| ## 一、語料說明 | |
| 用 2-4 句話摘要上方【譯本 metadata】提供的原文資訊、群組層與個體層背景（例如原文標題、各組別的翻譯類型／方向、個別譯本的譯者或系統名稱等，視實際提供的內容而定）。 | |
| 若 metadata 顯示使用者略過未填，僅陳述「使用者未提供語料補充說明」，不得臆測或杜撰內容。這個區塊只做摘要陳述，不做任何統計分析或推論。 | |
| 【metadata 一致性檢查】摘要時若發現群組層與個體層資訊彼此矛盾（例如某組別標示為「人工翻譯」，但該組底下某檔案的譯者／系統名稱明顯是 AI 模型或翻譯系統名稱；或研究情境選的是歷時比較，但個體層完全沒有任何出版年資訊），須在本區塊結尾明確標記該矛盾之處，供使用者確認，**不得自行判斷何者為準、不得擅自修正或忽略其中一方**。若沒有發現矛盾，不需要特別聲明「一致性檢查通過」，維持原本的摘要陳述即可。 | |
| ## 二、數據事實描述 | |
| 本區塊須包含以下三類數據事實，缺一不可（量化分析結果 JSON 裡都有對應資料，不得因為篇幅省略）： | |
| 1. 差異性分析：每項陳述除了指標代碼、p 值與效果量之外，**必須明確指出各組別中平均數偏高與 | |
| 偏低的是哪一組，並附上實際平均數數值**（difference_analysis 資料裡每個組別都有一欄以該組 | |
| 名稱結尾 _M 的平均數欄位）——只寫 p 值與效果量、不寫是哪一組偏高偏低，讀者無法理解差異的 | |
| 方向與意義。 | |
| 三組以上時是用 ANOVA 檢定，效果量（η²）本身不帶方向性（不像兩組時的 Cohen's d 還有正負號 | |
| 可看出方向），更不能省略指出方向的那句話。 | |
| 【用詞規則，務必遵守】JSON 裡的 groups／difference_analysis 只會有 2 或 3 個以上的組別， | |
| 依組別數量決定用詞，不可混用： | |
| - **恰好兩組**：只能用「較高」「較低」，不可以用「最高」「最低」——只有兩個東西比較時， | |
| 沒有「最」這種在三者以上才成立的最高級語意，用「最高」「最低」邏輯上是錯的。 | |
| 範例：「總字數（AA_01）：p=0.0461，Cohen's d=-1.5621（大）；機器翻譯較高（M=60537.5）， | |
| 人工翻譯較低（M=54313.6）。」 | |
| - **三組以上**：用「最高」「最低」（是在多個組別中挑出最大最小值，最高級語意才成立）。 | |
| 範例：「總句數（AA_06）：p=0.0068，η²=0.9932（大）；2024 年組別最高（M=32.5）， | |
| 1989 年組別最低（M=18.2）。」 | |
| 區分：達統計顯著的差異（標明 p 值、效果量、方向與平均數）、未達顯著但數值差距較大的趨勢 | |
| （同樣要指出方向）、無明顯差異的指標。 | |
| 【資料完整性】若 JSON 附有「資料完整性提醒」欄位（表示部分指標因組別樣本數不足、根本無法 | |
| 進行統計檢定），這些指標一律只能陳述為「資料不足，無法檢定」，絕對不可以寫成「無顯著差異」， | |
| 也不可以把它們計入「達統計顯著」或「無明顯差異」的統計比例——這是兩種完全不同的結論，混為 | |
| 一談會誤導讀者以為系統已經檢定過、確認沒有差異。 | |
| 【效果量無法計算】若某指標的「效果大小」欄位顯示「效果量不穩定（組內變異趨近於零）」、 | |
| 「效果量」欄位為 null，代表 p 值仍然有效、該指標**確實達統計顯著**（顯著性判斷正常參與統計 | |
| 比例），只是組內變異趨近於零，Cohen's d／η² 這個公式本身除不出有意義的數字。陳述時正常 | |
| 引用 p 值與各組平均數（依上面【用詞規則】，兩組寫「較高／較低」、三組以上寫「最高／最低」）， | |
| 效果量部分改寫成「效果量因組內變異趨近於零而無法計算」，不得省略、也不得自己編造一個數字 | |
| 或寫成「效果量極大」（那是失真的浮點數，不是真的統計結論）。這跟【資料完整性】的「資料 | |
| 不足」是兩種不同情況，不要混為一談：後者連檢定都做不了，前者是檢定做了、結果確實顯著， | |
| 只是效果量這個數字算不出來。 | |
| 【資料穩定性提醒】若 JSON 附有「資料穩定性提醒」欄位（表示部分指標至少有一組出現「樣本 | |
| 標準差趨近於 0」或「半數以上樣本值為 0」之一），這些指標的 p 值與效果量正常計算、正常算入 | |
| 「達統計顯著」的統計比例，**不要**排除或改標成「資料不足」；但陳述時必須額外加一句保留 | |
| 語氣，例如「此結果統計穩定性有限，建議謹慎解讀」，不可用跟其他變異正常的顯著指標完全相同 | |
| 的肯定語氣呈現，避免讀者把統計上脆弱的單組結果誤判為跟其他證據同等可信。 | |
| 2. 監督式學習（隨機森林）：說明 feature_importance_top20 裡重要性最高的 3-5 項指標與其重要性數值。 | |
| 同時陳述「隨機森林分類準確率」的數字，並原樣附上 JSON 裡「隨機森林準確率之樣本外預測意義」 | |
| 這欄給的完整句子（那句話已經是可以直接使用的中文敘述，不必再改寫或省略）。 | |
| 3. 非監督式學習（分群）：說明 cluster_results 裡階層式分群（HC_Cluster）與 K-means 分群 | |
| （KM_Cluster）的分群結果，是否與原始分組一致，若不一致明確指出差異所在。提及「原始分組」 | |
| 時只用這個中文說法即可，不要在後面加註英文欄名。 | |
| {scenario_module} | |
| ## 四、待驗證事項 | |
| - 需研究者回到原文比對的具體項目 | |
| - 數據中的異常值或可疑模式 | |
| - 本分析無法處理的面向 | |
| ## 五、本次分析的已知限制 | |
| 明確列出：分詞系統潛在誤差、樣本量對統計檢定的影響、指標本身的理論侷限。""" | |
| # ── matplotlib 中文字型 ────────────────────────────────────────────────────── | |
| def _find_cjk_font(): | |
| candidates = ["Microsoft JhengHei","Microsoft YaHei","SimHei", | |
| "Noto Sans CJK TC","Noto Sans CJK SC"] | |
| available = {f.name for f in fm.fontManager.ttflist} | |
| for c in candidates: | |
| if c in available: | |
| return c | |
| return None | |
| _cjk = _find_cjk_font() | |
| if _cjk: | |
| plt.rcParams['font.family'] = _cjk | |
| plt.rcParams['axes.unicode_minus'] = False | |
| # ============================================================================ | |
| # SECTION 2: Resource Loading (load once at startup) | |
| # ============================================================================ | |
| _RESOURCES = {} | |
| def _load_resources(): | |
| global _RESOURCES | |
| print("【系統啟動】載入參考語料資源...") | |
| def _read(fname): | |
| p = CORPUS_INFO / fname | |
| if not p.exists(): | |
| print(f" 警告：找不到 {fname}") | |
| return [] | |
| with open(p, 'r', encoding='utf-8') as f: | |
| return [l.replace('\n','') for l in f.readlines()] | |
| _RESOURCES['T01'] = _read('T01_成語5335.txt') | |
| _RESOURCES['T01_B'] = _read('T01_成語20389.txt') | |
| _RESOURCES['T02'] = _read('T02_國小常用詞.txt') | |
| _RESOURCES['T03'] = _read('T03_國小常用詞3000.txt') | |
| _RESOURCES['T04'] = _read('T04_現代漢語3000.txt') | |
| _RESOURCES['T05'] = _read('T05_現代漢語8000.txt') | |
| _RESOURCES['T06_V500'] = _read('T06_Sinica高頻動詞前500.txt') | |
| _RESOURCES['T06_N3000'] = _read('T06_Sinica高頻詞前3000詞_常用名詞.txt') | |
| _RESOURCES['T06_A3000'] = _read('T06_Sinica高頻詞前3000詞_常用形容詞.txt') | |
| _RESOURCES['T06_D3000'] = _read('T06_Sinica高頻詞前3000詞_常用副詞.txt') | |
| _RESOURCES['T06_N8000'] = _read('T06_Sinica高頻詞前8000詞_常用名詞.txt') | |
| _RESOURCES['T06_A8000'] = _read('T06_Sinica高頻詞前8000詞_常用形容詞.txt') | |
| _RESOURCES['T06_D8000'] = _read('T06_Sinica高頻詞前8000詞_常用副詞.txt') | |
| strokes_path = CORPUS_INFO / 'strokesDictionary.json' | |
| if strokes_path.exists(): | |
| with open(strokes_path, 'r', encoding='utf-8') as f: | |
| _RESOURCES['strokes'] = json.load(f) | |
| else: | |
| _RESOURCES['strokes'] = {} | |
| print(" 警告：找不到 strokesDictionary.json") | |
| print("【系統啟動】資源載入完成。") | |
| _load_resources() | |
| # ============================================================================ | |
| # SECTION 3: LLM API Wrappers | |
| # ============================================================================ | |
| def _call_openrouter(api_key, model, system_prompt, user_prompt, max_tokens=16000, temperature=0): | |
| """通用 OpenRouter API 呼叫（同步）。 | |
| 2026-08-22（可重複性設計）：temperature 預設從 0.5 改成 0，降低同一組輸入 | |
| 在不同次呼叫間的用字差異。注意這不代表輸出保證逐字相同——OpenRouter | |
| 後端本身的浮點運算、批次處理等因素仍可能造成極小差異，temperature=0 | |
| 只是把「取樣造成的隨機性」這個變因降到最低，不是完全消除所有變因。 | |
| """ | |
| url = "https://openrouter.ai/api/v1/chat/completions" | |
| headers = { | |
| "Authorization": f"Bearer {api_key}", | |
| "Content-Type": "application/json", | |
| "HTTP-Referer": "https://retranslation-agent.local", | |
| "X-Title": "Retranslation Analysis Agent", | |
| } | |
| payload = { | |
| "model": model, | |
| "messages": [ | |
| {"role": "system", "content": system_prompt}, | |
| {"role": "user", "content": user_prompt}, | |
| ], | |
| "max_tokens": max_tokens, | |
| "temperature": temperature, | |
| } | |
| data = json.dumps(payload).encode("utf-8") | |
| req = urllib.request.Request(url, data=data, headers=headers, method="POST") | |
| try: | |
| with urllib.request.urlopen(req, timeout=180) as resp: | |
| result = json.loads(resp.read().decode("utf-8")) | |
| return result["choices"][0]["message"]["content"] | |
| except urllib.error.HTTPError as e: | |
| body = e.read().decode("utf-8") if e.fp else "" | |
| raise RuntimeError(f"OpenRouter API HTTP 錯誤 ({e.code}): {body}") | |
| except Exception as e: | |
| raise RuntimeError(f"OpenRouter API 呼叫失敗: {e}") | |
| def call_main_agent(system_prompt, user_prompt): | |
| """主 Agent (LLM1) 呼叫。""" | |
| return _call_openrouter(LLM1_API_KEY, LLM1_MODEL, system_prompt, user_prompt) | |
| def call_worker_agent(system_prompt, user_prompt): | |
| """工作程序 Agent (LLM2) 呼叫。""" | |
| return _call_openrouter(LLM2_API_KEY, LLM2_MODEL, system_prompt, user_prompt) | |
| # ============================================================================ | |
| # SECTION 4: Text Format Validation | |
| # ============================================================================ | |
| def validate_ckip_format(filepath: Path): | |
| """ | |
| 檢查檔案是否為 ckip_segmentation_sumin 工具產生的斷詞格式。 | |
| 判斷依據： | |
| 1. 非空行中，含底線（_）的 token 佔比 > 70% | |
| 2. 至少出現一個 CKIP 特徵標記（CATEGORY 系列或標準詞性碼） | |
| 返回 (is_valid: bool, reason: str) | |
| """ | |
| CKIP_SIGNATURES = re.compile( | |
| r'(PERIODCATEGORY|COMMACATEGORY|PAUSECATEGORY|SEMICOLONCATEGORY|' | |
| r'QUESTIONCATEGORY|EXCLAMATIONCATEGORY|PARENTHESISCATEGORY|' | |
| r'DASHCATEGORY|ETCCATEGORY|COLONCATEGORY|SPCHANGECATEGORY|' | |
| r'\b(?:Na|Nb|Nc|Ncd|Nd|Nf|Nh|Nv|VA|VB|VC|VD|VE|VF|VG|VH|VHC|' | |
| r'VI|VJ|VK|VL|VAC|VCL|DE|Di|SHI|FW|Caa|Cab|Cba|Cbb|' | |
| r'Neu|Nes|Nep|Neqa|Neqb|Ng|P|D|Da|Dfa|Dfb|Dk|I|T|A)\b)' | |
| ) | |
| try: | |
| with open(filepath, 'r', encoding='utf-8-sig') as f: | |
| lines = f.readlines() | |
| except Exception as e: | |
| return False, f"無法讀取檔案：{e}" | |
| total_tokens = 0 | |
| underscore_tokens = 0 | |
| has_ckip_signature = False | |
| sample_lines = [l.rstrip() for l in lines if l.strip()][:100] | |
| if not sample_lines: | |
| return False, "檔案為空。" | |
| for line in sample_lines: | |
| tokens = line.split() | |
| for tok in tokens: | |
| total_tokens += 1 | |
| if '_' in tok: | |
| underscore_tokens += 1 | |
| if not has_ckip_signature and CKIP_SIGNATURES.search(tok): | |
| has_ckip_signature = True | |
| if total_tokens == 0: | |
| return False, "檔案無有效內容。" | |
| ratio = underscore_tokens / total_tokens | |
| if ratio < 0.70: | |
| return False, ( | |
| f"token 中含底線（詞_詞性）的比例僅 {ratio:.0%}，" | |
| "不符合語料淬鍊（CorpusRefinery）的輸出格式。" | |
| ) | |
| if not has_ckip_signature: | |
| return False, "未偵測到 CKIP 詞性標記，可能非語料淬鍊（CorpusRefinery）產生的檔案。" | |
| return True, "格式符合語料淬鍊（CorpusRefinery）輸出。" | |
| # ============================================================================ | |
| # SECTION 5: Indicator Calculation (adapted from Prog02) | |
| # ============================================================================ | |
| def _text2strokes(tokens, strokes_db): | |
| words, strokes, missing = [], [], [] | |
| for tok in tokens: | |
| for char in tok: | |
| if char in strokes_db: | |
| words.append(char) | |
| strokes.append(strokes_db[char]['strokes_total']) | |
| else: | |
| missing.append(char) | |
| return words, strokes, missing | |
| def calculate_text_index(corpus_file_path: Path, resources: dict) -> dict: | |
| """ | |
| 計算單一文本的所有語言學指標。 | |
| 改寫自 Prog02_indicators_multi-v3_1150509.py 的 calculateTextIndex()。 | |
| """ | |
| fname = corpus_file_path.name | |
| with open(corpus_file_path, 'r', encoding='utf-8-sig') as xf: | |
| text0 = xf.read() | |
| text0 = text0.replace('', '') | |
| text1 = text0.split('\n') | |
| text2 = [xx.split() for xx in text1] | |
| text3_1, text3_2 = [], [] | |
| for i, row in enumerate(text2): | |
| t1, t2 = [], [] | |
| for xxi in row: | |
| parts = xxi.split('_') | |
| t1.append(parts[0]) | |
| t2.append(parts[1] if len(parts) > 1 else '') | |
| text3_1.append(t1) | |
| text3_2.append(t2) | |
| # ── 標點 / 句子統計 ─────────────────────────────────────────────────────── | |
| com1 = sum(row.count("COMMACATEGORY") for row in text3_2) | |
| ss1 = sum(row.count("PERIODCATEGORY") for row in text3_2) | |
| ss2 = sum(row.count("SEMICOLONCATEGORY") for row in text3_2) | |
| ss3 = sum(row.count("QUESTIONCATEGORY") for row in text3_2) | |
| ss4 = sum(row.count("EXCLAMATIONCATEGORY")for row in text3_2) | |
| sentenceTotal = ss1 + ss2 + ss3 + ss4 | |
| if sentenceTotal == 0: | |
| sentenceTotal = 1 # 防止除以零 | |
| A_index1 = com1 / sentenceTotal | |
| # ── 展開成一維 ───────────────────────────────────────────────────────────── | |
| text3_1_long = [t for row in text3_1 for t in row] | |
| text3_2_long = [t for row in text3_2 for t in row] | |
| sen_pos_set = ["PERIODCATEGORY","SEMICOLONCATEGORY","QUESTIONCATEGORY","EXCLAMATIONCATEGORY"] | |
| sec_pos_set = sen_pos_set + ["COMMACATEGORY","COLONCATEGORY","DASHCATEGORY"] | |
| def _calc_lengths(boundary_set): | |
| lengths, xlen = [], 0 | |
| for sss in text3_2_long: | |
| if sss in boundary_set: | |
| lengths.append(xlen); xlen = 0 | |
| elif 'CATEGORY' not in sss: | |
| xlen += 1 | |
| return lengths | |
| sen_length = _calc_lengths(sen_pos_set) | |
| sec_length = _calc_lengths(sec_pos_set) | |
| if not sen_length: sen_length = [0] | |
| if not sec_length: sec_length = [0] | |
| mean_sentenceLength = np.mean(sen_length) | |
| var_sentenceLength = np.var(sen_length) | |
| mean_sectionLength = np.mean(sec_length) | |
| var_sectionLength = np.var(sec_length) | |
| sd_sectionLength = np.sqrt(var_sectionLength) | |
| # ── 標點符號總數 ─────────────────────────────────────────────────────────── | |
| categoryTotal = sum(1 for t in text3_2_long if 'CATEGORY' in t) | |
| # ── 詞 / 詞性統計 ─────────────────────────────────────────────────────────── | |
| tokens, tokens_pos, TokenAddPos, uniTokens, uni_TokenAddPos = [], [], [], [], [] | |
| for ii, row in enumerate(text3_1): | |
| for jj in range(len(row)): | |
| if 'CATEGORY' not in text3_2[ii][jj]: | |
| w = text3_1[ii][jj] | |
| p = text3_2[ii][jj] | |
| tokens.append(w) | |
| tokens_pos.append(p) | |
| TokenAddPos.append(f"{w}-{p}") | |
| if w not in uniTokens: uniTokens.append(w) | |
| if f"{w}-{p}" not in uni_TokenAddPos: uni_TokenAddPos.append(f"{w}-{p}") | |
| tokensTotal = len(tokens) | |
| uniTokensTotal = len(uni_TokenAddPos) | |
| if tokensTotal == 0: tokensTotal = 1 | |
| wordTotal = sum(len(w) for w in tokens) | |
| words_0 = ''.join(tokens) | |
| uni_words = set(words_0) | |
| uni_words_len = len(uni_words) | |
| # 詞長 | |
| tokens_len = [len(w) for w in tokens] | |
| mean_tokens_len = np.mean(tokens_len) if tokens_len else 0 | |
| # 段落數 | |
| lineTotal = sum(1 for row in text3_1 if row) | |
| # 基礎比值 | |
| A_index2 = wordTotal / sentenceTotal | |
| A_index3 = tokensTotal / sentenceTotal | |
| A_index4 = categoryTotal / sentenceTotal | |
| A_index5 = wordTotal / max(categoryTotal, 1) | |
| A_index6 = tokensTotal / max(categoryTotal, 1) | |
| A_index7 = wordTotal / max(lineTotal, 1) | |
| A_index8 = tokensTotal / max(lineTotal, 1) | |
| # ── 詞頻比對 ────────────────────────────────────────────────────────────── | |
| R = resources | |
| elementaryTotal = sum(1 for w in tokens if w in R.get('T02', [])) | |
| elementaryTotal3 = sum(1 for w in tokens if w in R.get('T03', [])) | |
| elementaryTotal4 = sum(1 for w in tokens if w in R.get('T04', [])) | |
| elementaryTotal5 = sum(1 for w in tokens if w in R.get('T05', [])) | |
| xx = Counter(tokens) | |
| idiomTotal = sum(v for k,v in xx.items() if k in R.get('T01', [])) | |
| idiomTotal2 = sum(v for k,v in xx.items() if k in R.get('T01_B',[])) | |
| tokens_V = [tokens[i] for i in range(len(tokens)) if tokens_pos[i] in Vset] | |
| tokens_N = [tokens[i] for i in range(len(tokens)) if tokens_pos[i] in Nset] | |
| tokens_A = [tokens[i] for i in range(len(tokens)) if tokens_pos[i] in Aset] or ['XX'] | |
| tokens_ADV = [tokens[i] for i in range(len(tokens)) if tokens_pos[i] in ADVset] | |
| VelementaryTotal500 = sum(1 for w in tokens_V if w in R.get('T06_V500', [])) | |
| NelementaryTotal3000 = sum(1 for w in tokens_N if w in R.get('T06_N3000',[])) | |
| AelementaryTotal3000 = sum(1 for w in tokens_A if w in R.get('T06_A3000',[])) | |
| ADVelementaryTotal3000= sum(1 for w in tokens_ADV if w in R.get('T06_D3000',[])) | |
| NelementaryTotal8000 = sum(1 for w in tokens_N if w in R.get('T06_N8000',[])) | |
| AelementaryTotal8000 = sum(1 for w in tokens_A if w in R.get('T06_A8000',[])) | |
| ADVelementaryTotal8000= sum(1 for w in tokens_ADV if w in R.get('T06_D8000',[])) | |
| # ── 詞性計數 ───────────────────────────────────────────────────────────── | |
| pos_A_fre = tokens_pos.count("A") | |
| pos_V_fre = sum(1 for p in tokens_pos if p in Vset) | |
| pos_N_fre = sum(1 for p in tokens_pos if p in Nset) | |
| pos_Nh_fre2 = sum(1 for p in tokens_pos if p in Nhset) | |
| pos_ADV_fre = sum(1 for p in tokens_pos if p in ADVset) | |
| pos_ASP_fre = tokens_pos.count("Di") | |
| pos_C_fre = sum(1 for p in tokens_pos if p in Cset) | |
| pos_Ca_fre = sum(1 for p in tokens_pos if p in Caset) | |
| pos_Cb_fre = sum(1 for p in tokens_pos if p in Cbset) | |
| pos_DET_fre = sum(1 for p in tokens_pos if p in DETset) | |
| pos_P_fre = tokens_pos.count("P") | |
| pos_POST_fre = sum(1 for p in tokens_pos if p in POSTset) | |
| pos_T_fre = sum(1 for p in tokens_pos if p in Tset) | |
| pos_DE_fre = tokens_pos.count("DE") | |
| pos_SHI_fre = tokens_pos.count("SHI") | |
| pos_V2_fre = tokens_pos.count("V2") | |
| # 個別詞性 | |
| def _pc(p): return tokens_pos.count(p) | |
| pos_Caa_fre = _pc("Caa"); pos_Cab_fre = _pc("Cab") | |
| pos_Cba_fre = _pc("Cba"); pos_Cbb_fre = _pc("Cbb") | |
| pos_D_fre = _pc("D"); pos_Da_fre = _pc("Da") | |
| pos_Dfa_fre = _pc("Dfa"); pos_Dfb_fre = _pc("Dfb") | |
| pos_Di_fre = _pc("Di"); pos_Dk_fre = _pc("Dk") | |
| pos_I_fre = _pc("I"); pos_Na_fre = _pc("Na") | |
| pos_Nb_fre = _pc("Nb"); pos_Nc_fre = _pc("Nc") | |
| pos_Ncd_fre = _pc("Ncd"); pos_Nd_fre = _pc("Nd") | |
| pos_Nep_fre = _pc("Nep"); pos_Neqa_fre= _pc("Neqa") | |
| pos_Neqb_fre= _pc("Neqb");pos_Nes_fre = _pc("Nes") | |
| pos_Neu_fre = _pc("Neu"); pos_Nf_fre = _pc("Nf") | |
| pos_Ng_fre = _pc("Ng"); pos_Nh_fre = _pc("Nh") | |
| pos_Nv_fre = _pc("Nv") | |
| pos_VA_fre = _pc("VA"); pos_VAC_fre = _pc("VAC") | |
| pos_VB_fre = _pc("VB"); pos_VC_fre = _pc("VC") | |
| pos_VCL_fre = _pc("VCL"); pos_VD_fre = _pc("VD") | |
| pos_VE_fre = _pc("VE"); pos_VF_fre = _pc("VF") | |
| pos_VG_fre = _pc("VG"); pos_VH_fre = _pc("VH") | |
| pos_VHC_fre = _pc("VHC"); pos_VI_fre = _pc("VI") | |
| pos_VJ_fre = _pc("VJ"); pos_VK_fre = _pc("VK") | |
| pos_VL_fre = _pc("VL") | |
| # 內容詞 | |
| cont1 = pos_N_fre + pos_A_fre + pos_V_fre | |
| cont2 = cont1 + pos_ADV_fre | |
| # AJ 指標 | |
| AJ04_set = ['什麼','哪','什','甚麼','啥'] | |
| AJ05_set = ['它','牠','它們','牠們','其','之','前者','後者','兩者','二者', | |
| '以上','以下','誰','誰人','何者','什麼','甚麼','啥'] | |
| AJ06_set = ['它','牠','它們','牠們','其','之','前者','後者','兩者','二者','以上','以下'] | |
| AJ07_set = ['我','我們','我方','我倆','咱們','咱','俺','儂','咱家','咱們','予','余', | |
| '老子','我等','吾等'] | |
| AJ08_set = ['你','妳','你們','你方','妳們','妳方','你倆','妳倆'] | |
| AJ09_set = ['他','她','他們','她們','他倆'] | |
| AJ10_set = ['對方','個人','人家','各位','各自','自己','自我','本人','自身', | |
| '別人','彼此','雙方','大家','大夥兒','大眾','他人','私人','彼方'] | |
| AJ02_set = ['Caa','Cbb','Cab','Cba'] | |
| AJ03_set = ['Cbb','Cba'] | |
| pos_Nep_AJ04_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nep" and tokens[i] not in AJ04_set) | |
| pos_Nh_AJ05_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] not in AJ05_set) | |
| pos_Nh_AJ06_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] in AJ06_set) | |
| pos_Nh_AJ07_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] in AJ07_set) | |
| pos_Nh_AJ08_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] in AJ08_set) | |
| pos_Nh_AJ09_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] in AJ09_set) | |
| pos_Nh_AJ10_fre = sum(1 for i in range(len(tokens)) | |
| if tokens_pos[i]=="Nh" and tokens[i] in AJ10_set) | |
| AJ02_fre = sum(1 for p in tokens_pos if p in AJ02_set) | |
| AJ03_fre = sum(1 for p in tokens_pos if p in AJ03_set) | |
| # ── 豐富度指標 ───────────────────────────────────────────────────────────── | |
| TTR = uniTokensTotal / tokensTotal | |
| perK = 1000 | |
| kk = len(TokenAddPos) // perK | |
| kk_TTR = [] | |
| for ii in range(1, kk+1): | |
| seg = TokenAddPos[(ii-1)*1000 : ii*1000] | |
| kk_TTR.append(len(set(seg)) / perK) | |
| STD_TTR = sum(kk_TTR) / len(kk_TTR) if kk_TTR else 0 | |
| Guiraud_R = uniTokensTotal / pow(tokensTotal, 0.5) | |
| LexicalDensity1 = cont1 / tokensTotal | |
| LexicalDensity2 = cont2 / tokensTotal | |
| return { | |
| "Text": [fname], | |
| "AA_01": [wordTotal], | |
| "AA_02": [uni_words_len], | |
| "AA_03": [tokensTotal], | |
| "AA_04": [uniTokensTotal], | |
| "AA_05": [lineTotal], | |
| "AA_06": [sentenceTotal], | |
| "AC_01": [round((tokensTotal - elementaryTotal4) / tokensTotal * 1000, 4)], | |
| "AC_02": [round((tokensTotal - elementaryTotal5) / tokensTotal * 1000, 4)], | |
| "AD_02": [round(STD_TTR, 4)], | |
| "AD_03": [round(Guiraud_R, 4)], | |
| "AG_01": [round(LexicalDensity1, 4)], | |
| "AG_02": [round(LexicalDensity2, 4)], | |
| "AG_05": [round(idiomTotal / tokensTotal * 1000, 4)], | |
| "AG_06": [round(idiomTotal2 / tokensTotal * 1000, 4)], | |
| "AH_01": [round(mean_sentenceLength, 4)], | |
| "AH_03": [round(np.sqrt(var_sentenceLength), 4)], | |
| "AH_06": [round(mean_sectionLength, 4)], | |
| "AH_08": [round(sd_sectionLength, 4)], | |
| "AJ_01": [round(pos_C_fre / tokensTotal * 1000, 4)], | |
| "AJ_02": [round(AJ02_fre / tokensTotal * 1000, 4)], | |
| "AJ_03": [round(AJ03_fre / tokensTotal * 1000, 4)], | |
| "AJ_04": [round(pos_Nep_AJ04_fre / tokensTotal * 1000, 4)], | |
| "AJ_05": [round(pos_Nh_AJ05_fre / tokensTotal * 1000, 4)], | |
| "AJ_06": [round(pos_Nh_AJ06_fre / tokensTotal * 1000, 4)], | |
| "AJ_07": [round(pos_Nh_AJ07_fre / tokensTotal * 1000, 4)], | |
| "AJ_08": [round(pos_Nh_AJ08_fre / tokensTotal * 1000, 4)], | |
| "AJ_09": [round(pos_Nh_AJ09_fre / tokensTotal * 1000, 4)], | |
| "AJ_10": [round(pos_Nh_AJ10_fre / tokensTotal * 1000, 4)], | |
| "AJ_11": [round(pos_Nh_AJ10_fre / tokensTotal * 1000, 4)], | |
| "AF_01": [round(pos_A_fre / tokensTotal * 1000, 4)], | |
| "AF_02": [round(pos_Caa_fre / tokensTotal * 1000, 4)], | |
| "AF_03": [round(pos_Cab_fre / tokensTotal * 1000, 4)], | |
| "AF_04": [round(pos_Cba_fre / tokensTotal * 1000, 4)], | |
| "AF_05": [round(pos_Cbb_fre / tokensTotal * 1000, 4)], | |
| "AF_06": [round(pos_D_fre / tokensTotal * 1000, 4)], | |
| "AF_07": [round(pos_Da_fre / tokensTotal * 1000, 4)], | |
| "AF_08": [round(pos_DE_fre / tokensTotal * 1000, 4)], | |
| "AF_09": [round(pos_Dfa_fre / tokensTotal * 1000, 4)], | |
| "AF_10": [round(pos_Dfb_fre / tokensTotal * 1000, 4)], | |
| "AF_11": [round(pos_Di_fre / tokensTotal * 1000, 4)], | |
| "AF_12": [round(pos_Dk_fre / tokensTotal * 1000, 4)], | |
| "AF_14": [round(pos_I_fre / tokensTotal * 1000, 4)], | |
| "AF_15": [round(pos_Na_fre / tokensTotal * 1000, 4)], | |
| "AF_16": [round(pos_Nb_fre / tokensTotal * 1000, 4)], | |
| "AF_17": [round(pos_Nc_fre / tokensTotal * 1000, 4)], | |
| "AF_18": [round(pos_Ncd_fre / tokensTotal * 1000, 4)], | |
| "AF_19": [round(pos_Nd_fre / tokensTotal * 1000, 4)], | |
| "AF_20": [round(pos_Nep_fre / tokensTotal * 1000, 4)], | |
| "AF_21": [round(pos_Neqa_fre/ tokensTotal * 1000, 4)], | |
| "AF_22": [round(pos_Neqb_fre/ tokensTotal * 1000, 4)], | |
| "AF_23": [round(pos_Nes_fre / tokensTotal * 1000, 4)], | |
| "AF_24": [round(pos_Neu_fre / tokensTotal * 1000, 4)], | |
| "AF_25": [round(pos_Nf_fre / tokensTotal * 1000, 4)], | |
| "AF_26": [round(pos_Ng_fre / tokensTotal * 1000, 4)], | |
| "AF_27": [round(pos_Nh_fre / tokensTotal * 1000, 4)], | |
| "AF_28": [round(pos_Nv_fre / tokensTotal * 1000, 4)], | |
| "AF_29": [round(pos_P_fre / tokensTotal * 1000, 4)], | |
| "AF_30": [round(pos_SHI_fre / tokensTotal * 1000, 4)], | |
| "AF_31": [round(pos_T_fre / tokensTotal * 1000, 4)], | |
| "AF_32": [round(pos_V2_fre / tokensTotal * 1000, 4)], | |
| "AF_33": [round(pos_VA_fre / tokensTotal * 1000, 4)], | |
| "AF_34": [round(pos_VAC_fre / tokensTotal * 1000, 4)], | |
| "AF_35": [round(pos_VB_fre / tokensTotal * 1000, 4)], | |
| "AF_36": [round(pos_VC_fre / tokensTotal * 1000, 4)], | |
| "AF_37": [round(pos_VCL_fre / tokensTotal * 1000, 4)], | |
| "AF_38": [round(pos_VD_fre / tokensTotal * 1000, 4)], | |
| "AF_39": [round(pos_VE_fre / tokensTotal * 1000, 4)], | |
| "AF_40": [round(pos_VF_fre / tokensTotal * 1000, 4)], | |
| "AF_41": [round(pos_VG_fre / tokensTotal * 1000, 4)], | |
| "AF_42": [round(pos_VH_fre / tokensTotal * 1000, 4)], | |
| "AF_43": [round(pos_VHC_fre / tokensTotal * 1000, 4)], | |
| "AF_44": [round(pos_VI_fre / tokensTotal * 1000, 4)], | |
| "AF_45": [round(pos_VJ_fre / tokensTotal * 1000, 4)], | |
| "AF_46": [round(pos_VK_fre / tokensTotal * 1000, 4)], | |
| "AF_47": [round(pos_VL_fre / tokensTotal * 1000, 4)], | |
| } | |
| def run_indicator_calculation(file_paths: list, output_dir: Path, resources: dict): | |
| """ | |
| 對所有文本計算指標，儲存 xlsx + csv，回傳 (DataFrame, xlsx_path, csv_path)。 | |
| """ | |
| output_dir.mkdir(parents=True, exist_ok=True) | |
| result_df = pd.DataFrame() | |
| for fp in file_paths: | |
| try: | |
| row_dict = calculate_text_index(Path(fp), resources) | |
| result_df = pd.concat([result_df, pd.DataFrame(row_dict)], | |
| axis=0, ignore_index=True) | |
| except Exception as e: | |
| print(f" 計算 {fp} 時發生錯誤：{e}") | |
| traceback.print_exc() | |
| timestamp = now_tw().strftime("%Y%m%d%H%M%S") | |
| xlsx_path = output_dir / f"textIndex_calculated_1_{timestamp}.xlsx" | |
| csv_path = output_dir / "textIndex_calculated.csv" | |
| result_df.to_excel(str(xlsx_path), index=False) | |
| result_df.to_csv(str(csv_path), index=False, encoding='utf-8-sig') | |
| return result_df, xlsx_path, csv_path | |
| # ============================================================================ | |
| # SECTION 6: Statistical Analysis (adapted from prog03, no tkinter) | |
| # ============================================================================ | |
| def cohens_d(g1, g2): | |
| """回傳 Cohen's d；合併標準差相對於資料尺度趨近於零時回傳 None（而非硬除 | |
| 出失真的天文數字）。 | |
| 2026-08-24（業主回報：報告上出現「Cohen's d=-9028313184615308.0」這種 | |
| 誇張數字）：原本只用 `pooled != 0` 擋分母為零，但當兩組內部數值幾乎（並非 | |
| 精確）相同時，浮點運算會讓 pooled 變成一個極小但非零的數（例如 1e-13）， | |
| 這個檢查完全擋不住，除下去就爆出巨大到毫無意義的數字。改用「相對於資料 | |
| 尺度的容忍值」判斷：pooled 小於合併平均數絕對值的極小比例時，視為組內 | |
| 變異趨近於零、效果量在數值上不穩定，回傳 None。注意：這不代表兩組沒有 | |
| 差異——p 值與平均數本身仍然有效，只是 Cohen's d 這個統計量的公式在 | |
| 「組內幾乎零變異」的情況下本身就定義不良，硬算出一個數字反而失真。""" | |
| n1, n2 = len(g1), len(g2) | |
| if n1 < 2 or n2 < 2: | |
| return None | |
| var1, var2 = np.var(g1, ddof=1), np.var(g2, ddof=1) | |
| pooled = np.sqrt(((n1-1)*var1 + (n2-1)*var2) / (n1+n2-2)) | |
| scale = max(abs(np.mean(np.concatenate([g1, g2]))), 1e-12) | |
| if pooled < scale * 1e-8: | |
| return None | |
| return (np.mean(g1) - np.mean(g2)) / pooled | |
| def eta_squared(group_data): | |
| """回傳 η²；ss_total 相對於資料尺度趨近於零時回傳 None，理由同 cohens_d()。""" | |
| all_data = np.concatenate(group_data) | |
| grand_mean = all_data.mean() | |
| ss_between = sum(len(g) * (np.mean(g) - grand_mean)**2 for g in group_data) | |
| ss_total = np.sum((all_data - grand_mean)**2) | |
| scale = max(abs(grand_mean), 1e-12) | |
| if ss_total < (scale ** 2) * 1e-8: | |
| return None | |
| return ss_between / ss_total | |
| def effect_label(val, method): | |
| if method == "t-test": | |
| v = abs(val) | |
| return "大" if v>=0.8 else "中" if v>=0.5 else "小" if v>=0.2 else "極小" | |
| else: | |
| return "大" if val>=0.14 else "中" if val>=0.06 else "小" if val>=0.01 else "極小" | |
| def run_statistical_analysis(csv_path: Path, output_dir: Path, group_labels: dict = None, | |
| individual_grouping: dict = None): | |
| """ | |
| 執行完整統計分析（敘述統計、差異分析、隨機森林、分群）。 | |
| group_labels：{分組代碼: 語料說明填寫的實際標籤} 選填，只影響箱形圖的 | |
| X 軸刻度文字（見下方 boxplot 區塊），不影響任何計算結果。 | |
| individual_grouping：{檔名: 個體間比較的分組標籤} 選填，2026-08-15 | |
| 業主要求新增——「語料說明」選「個體間比較」時，用個體層資訊填的 | |
| 「譯者／系統名稱」取代預設的檔名字首分組，這個 dict 非空時會真的 | |
| 改變 Type1（見下面），因此會連動影響差異性分析、隨機森林、分群 | |
| 全部的分組依據，不像 group_labels 只是換個顯示用的名字。沒填的 | |
| 檔案自動退回用檔名字首分組（業主拍板的容錯方式）。 | |
| 回傳 dict 包含所有輸出檔路徑與摘要資訊。 | |
| """ | |
| output_dir.mkdir(parents=True, exist_ok=True) | |
| # ── 1. 讀入資料 ──────────────────────────────────────────────────────────── | |
| df = pd.read_csv(str(csv_path)) | |
| # 2026-08-14：業主要求隱藏的 13 項指標（見 HIDDEN_INDICATOR_CODES 定義處 | |
| # 註解）在這裡就濾掉，之後敘述統計／差異分析／隨機森林／分群全部從這份 | |
| # df 衍生，一次過濾即可讓下游全部不再看到這 13 項，不用每個子區塊各自擋。 | |
| df = _drop_hidden_indicators(df) | |
| df['Type1'] = df['Text'].str[0].str.upper() | |
| # 2026-08-15（業主要求「個體間比較」要有實際效果）：individual_grouping | |
| # 非空時，用它取代上面那行檔名字首分組——每個檔案若在「個體層資訊」 | |
| # 填了「譯者／系統名稱」，Type1 就改用那個值；沒填的檔案維持原本的 | |
| # 檔名字首（.map 對應不到的位置是 NaN，用 .fillna 退回原值，不是整批 | |
| # 放棄）。這一改，後面的差異性分析、隨機森林、分群全部自動跟著用新 | |
| # 分組依據算，不用另外改下游程式碼。 | |
| if individual_grouping: | |
| custom_group = df['Text'].astype(str).str.strip().map(individual_grouping) | |
| df['Type1'] = custom_group.fillna(df['Type1']) | |
| df['Type2'] = df['Type1'] | |
| GROUP_COL = 'Type1' | |
| N_CLUSTERS = max(2, len(df['Type1'].unique())) | |
| # 重新命名欄位（加中文名稱） | |
| rename_map = {} | |
| for col in df.columns: | |
| if col in INDEX_NAME_MAP: | |
| rename_map[col] = f"{col}_{INDEX_NAME_MAP[col]}" | |
| df.rename(columns=rename_map, inplace=True) | |
| numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist() | |
| # ── 2. 敘述統計（涵蓋所有計算指標，與語言指標分析一致）──────────────────── | |
| def _desc_row(cat, code, cname, rcol): | |
| s = df[rcol].dropna() | |
| if len(s) == 0: | |
| return None | |
| return { | |
| "類別": cat, "指標代碼": code, "指標名稱": cname, | |
| "文本個數": int(s.count()), | |
| "平均數": round(float(s.mean()), 4), | |
| "中位數": round(float(s.median()), 4), | |
| "標準差": round(float(s.std()), 4), | |
| "最小值": round(float(s.min()), 4), | |
| "最大值": round(float(s.max()), 4), | |
| "變異係數(%)": round(float(s.std()/s.mean()*100), 2) if s.mean()!=0 else None, | |
| } | |
| all_desc_rows = [] | |
| covered = set() | |
| # (a) 已分類指標（依分類順序呈現） | |
| for cat, items in INDEX_CATEGORIES.items(): | |
| for code, cname in items.items(): | |
| rcol = f"{code}_{cname}" | |
| if rcol not in df.columns: | |
| continue | |
| r = _desc_row(cat, code, cname, rcol) | |
| if r: | |
| all_desc_rows.append(r) | |
| covered.add(rcol) | |
| # (b) 未分類指標（如 AJ 系列），補入確保與指標計算數量一致 | |
| for rcol in numeric_cols: | |
| if rcol in covered: | |
| continue | |
| parts = rcol.split("_") | |
| code = (parts[0] + "_" + parts[1]) if len(parts) >= 2 else rcol | |
| cname = INDEX_NAME_MAP.get(code, code) | |
| r = _desc_row("其他指標", code, cname, rcol) | |
| if r: | |
| all_desc_rows.append(r) | |
| desc_df = pd.DataFrame(all_desc_rows) | |
| desc_path = output_dir / "01_descriptive_stats.csv" | |
| desc_df.to_csv(str(desc_path), index=False, encoding='utf-8-sig') | |
| # ── 3. 差異性分析 ────────────────────────────────────────────────────────── | |
| groups = df[GROUP_COL].unique() | |
| n_groups = len(groups) | |
| method_name = "Independent t-test (Welch)" if n_groups == 2 else "One-way ANOVA" | |
| diff_results = [] | |
| for col in numeric_cols: | |
| gdata = [df.loc[df[GROUP_COL]==g, col].dropna().values for g in groups] | |
| if any(len(g)==0 for g in gdata): continue | |
| row = {"指標": col} | |
| for gi, g in enumerate(groups): | |
| row[f"{g}_N"] = len(gdata[gi]) | |
| row[f"{g}_M"] = round(float(np.mean(gdata[gi])), 4) | |
| row[f"{g}_SD"] = round(float(np.std(gdata[gi], ddof=1)), 4) if len(gdata[gi])>1 else 0.0 | |
| if n_groups == 2: | |
| stat, p = stats.ttest_ind(gdata[0], gdata[1], equal_var=False) | |
| es_name = "Cohen's d"; method = "t-test" | |
| else: | |
| stat, p = stats.f_oneway(*gdata) | |
| es_name = "η²"; method = "ANOVA" | |
| row["方法"] = method | |
| # 見上方 INSUFFICIENT_DATA_LABEL 定義處的說明：p=NaN 代表這個指標在 | |
| # 目前的分組下根本無法檢定（通常是某組 N<2），不是「檢定過、沒有 | |
| # 顯著差異」。這裡明確分流，不落入下面的顯著性判斷，效果量也不計算 | |
| # ——cohens_d()/eta_squared() 各自對 N<2 有 0.0 的保底值，那是給 | |
| # 「算得出來、真的沒差異」用的，跟「根本沒算出來」不該共用同一個 | |
| # 0.0，會誤導成「效果量趨近於零」。 | |
| is_untestable = bool(np.isnan(p)) | |
| row["統計量"] = round(float(stat), 4) if not np.isnan(stat) else None | |
| row["p值"] = round(float(p), 4) if not is_untestable else None | |
| row["效果量名稱"] = es_name | |
| if is_untestable: | |
| row["顯著"] = INSUFFICIENT_DATA_LABEL | |
| row["效果量"] = None | |
| row["效果大小"] = None | |
| row["資料品質警示"] = "" # 已經整列標成「資料不足」，不用再疊加這個警示 | |
| else: | |
| es = cohens_d(gdata[0], gdata[1]) if n_groups == 2 else eta_squared(gdata) | |
| row["顯著"] = ("***" if p<0.001 else "**" if p<0.01 else "*" if p<0.05 else "ns") | |
| if es is None: | |
| # 見 EFFECT_UNSTABLE_LABEL 定義處：p 值仍然有效、正常判斷顯著性 | |
| # （上面那行不受影響），只有效果量這個數字換成描述性標籤。 | |
| row["效果量"] = None | |
| row["效果大小"] = EFFECT_UNSTABLE_LABEL | |
| else: | |
| row["效果量"] = round(float(es), 4) | |
| row["效果大小"] = effect_label(es, method) | |
| # 見 ZERO_VARIANCE_WARNING／ZERO_PROPORTION_WARNING 定義處：兩條獨立 | |
| # 判準都只看「有真的算出變異數」的情況——N<2 已經在 is_untestable 那支 | |
| # 處理過。SD 判準抓「整組幾乎沒變異」；零值比例判準抓「SD 沒有趨近於 | |
| # 零，但組內樣本值仍大量集中在 0」——後者刻意排除已被 SD 判準抓到的 | |
| # 組別（`not (... < 1e-9)`），避免同一組資料被兩條規則重複疊加描述。 | |
| # 都不影響顯著性與效果量的計算，純附註警示；兩者可同時列出（不同組別 | |
| # 各自命中不同判準時）。 | |
| _dq_warnings = [] | |
| if any(len(g) >= 2 and np.std(g, ddof=1) < 1e-9 for g in gdata): | |
| _dq_warnings.append(ZERO_VARIANCE_WARNING) | |
| if any(len(g) >= 2 and np.std(g, ddof=1) >= 1e-9 | |
| and (np.sum(g == 0) / len(g)) >= ZERO_PROPORTION_THRESHOLD | |
| for g in gdata): | |
| _dq_warnings.append(ZERO_PROPORTION_WARNING) | |
| row["資料品質警示"] = "；".join(_dq_warnings) | |
| diff_results.append(row) | |
| diff_df = pd.DataFrame(diff_results) | |
| sig_df = diff_df[~diff_df['顯著'].isin(["ns", INSUFFICIENT_DATA_LABEL])] | |
| untestable_df = diff_df[diff_df['顯著'] == INSUFFICIENT_DATA_LABEL] | |
| diff_path = output_dir / "02_difference_analysis.csv" | |
| diff_df.to_csv(str(diff_path), index=False, encoding='utf-8-sig') | |
| # boxplot（2026-08-24 起：達顯著差異的指標全部畫出，不再只取前 12 項） | |
| # 2026-08-14（業主要求）：原本取前 12 項是照指標在資料表裡的固定欄位 | |
| # 順序（基礎統計→...→詞性標記）往下數，不是「最顯著／效果量最大」的 | |
| # 12 項，改成依效果量排序。 | |
| # 2026-08-24（業主要求）：取消「只取前 12 項」的上限，達顯著差異的指標 | |
| # 全部畫出來；排序改成「先依組別、組內再依效果量」——先看哪一組在這批 | |
| # 顯著指標裡整體偏高，同一組內再依效果量絕對值由大到小排，比單純照 | |
| # 效果量從大到小混排更容易看出「兩組的差異主要往哪個方向集中」。 | |
| box_path = None | |
| if len(sig_df) > 0: | |
| sig_df_sorted = sig_df.copy() | |
| _group_order = {g: i for i, g in enumerate(groups)} | |
| sig_df_sorted['_highest_group'] = sig_df_sorted.apply( | |
| lambda row: max(groups, key=lambda g: row.get(f"{g}_M", float('-inf'))), | |
| axis=1, | |
| ) | |
| sig_df_sorted['_group_rank'] = sig_df_sorted['_highest_group'].map(_group_order) | |
| # 2026-08-24：效果量為 None（EFFECT_UNSTABLE_LABEL 情況，見該常數定義 | |
| # 處）代表組內幾乎零變異卻仍達顯著——是最乾淨俐落的一種差異，排序時 | |
| # 視為效果量無限大、排在同一組別群組的最前面，不能因為是 None 就被 | |
| # sort_values 排到最後面去（NaN 預設排序行為）。 | |
| # 2026-08-24（實測崩潰：TypeError: bad operand type for abs(): 'NoneType'）： | |
| # 當顯著指標裡有不少（甚至全部）是 EFFECT_UNSTABLE_LABEL 情況（效果量＝ | |
| # None），這欄在 pandas 眼裡可能整欄維持 object dtype（而不是像單一 | |
| # 摻雜幾個 None 的情況那樣被自動轉成 float64、None 變 NaN），直接對 | |
| # object dtype 呼叫 .abs() 會真的去對 Python None 物件呼叫內建 abs() | |
| # 而炸掉，不是 NaN 安全語意。先用 pd.to_numeric(errors='coerce') 強制 | |
| # 轉成數值（None、NaN 都會變成 NaN，非數值也不會拋例外），再 .abs() | |
| # 就穩了。 | |
| sig_df_sorted['_abs_es'] = pd.to_numeric(sig_df_sorted['效果量'], errors='coerce').abs().fillna(float('inf')) | |
| sig_df_sorted = sig_df_sorted.sort_values( | |
| by=['_group_rank', '_abs_es'], ascending=[True, False] | |
| ) | |
| sig_cols = sig_df_sorted['指標'].tolist() | |
| n_row = max(1, (len(sig_cols) + 2) // 3) | |
| fig, axes = plt.subplots(n_row, 3, figsize=(14, 4*n_row)) | |
| axes = np.array(axes).flatten() | |
| # 群組軸標籤：語料說明填過的實際標籤（如「人工翻譯」）優先於原始 | |
| # 分組代碼（A／B），group_labels 由呼叫端（run_computation_pipeline_ | |
| # streaming）從 state["group_labels"] 傳入，沒填就退回代碼本身。 | |
| group_labels = group_labels or {} | |
| group_tick_labels = [group_labels.get(g, g) for g in groups] | |
| for i, col in enumerate(sig_cols): | |
| ax = axes[i] | |
| pd_data = [df.loc[df[GROUP_COL]==g, col].dropna().values for g in groups] | |
| ax.boxplot(pd_data) | |
| ax.set_xticks(range(1, len(groups) + 1)) | |
| ax.set_xticklabels(group_tick_labels) | |
| # 2026-08-15（業主要求）：小標題原本只有 p 值，加上效果量（連同 | |
| # 名稱，例如 Cohen's d 或 η²，兩種方法的效果量單位不一樣，只寫 | |
| # 數字沒名稱會誤讀）一起顯示，一眼就能看出「差多少」不只是 | |
| # 「有沒有差」。 | |
| row = diff_df.loc[diff_df['指標']==col] | |
| pv_str = f"p={row['p值'].values[0]:.4f}" if len(row)>0 else "" | |
| _es_val = row['效果量'].values[0] if len(row)>0 else None | |
| if len(row) > 0 and _es_val is not None and not pd.isna(_es_val): | |
| es_str = f"，{row['效果量名稱'].values[0]}={_es_val:.3f}" | |
| elif len(row) > 0: | |
| # 2026-08-24：效果量為 None 時（見 EFFECT_UNSTABLE_LABEL）， | |
| # 標題別再硬套 :.3f 格式化（會直接拋例外），改顯示描述性標籤。 | |
| es_str = f"，{EFFECT_UNSTABLE_LABEL}" | |
| else: | |
| es_str = "" | |
| ax.set_title(f"{col}\n({pv_str}{es_str})", fontsize=8) | |
| for j in range(len(sig_cols), len(axes)): | |
| axes[j].set_visible(False) | |
| # 2026-08-14（業主要求）：原本「Significant Variables by Type1」直接 | |
| # 洩漏內部欄位名稱 Type1，使用者看不懂在比較什麼，改成中文標題。 | |
| # 2026-08-24（業主要求）：不再只取前 12 項，標題文字同步更新為 | |
| # 「依組別與效果量排序」，不再提「前 12 項」（已無此上限）。 | |
| plt.suptitle("顯著指標比較（依組別與效果量排序）", fontsize=11, y=1.01) | |
| plt.tight_layout() | |
| box_path = output_dir / "02_significant_boxplots.png" | |
| plt.savefig(str(box_path), dpi=150, bbox_inches='tight') | |
| plt.close() | |
| # ── 4. 隨機森林 ──────────────────────────────────────────────────────────── | |
| le = LabelEncoder() | |
| y = le.fit_transform(df[GROUP_COL]) | |
| X = df[numeric_cols].fillna(df[numeric_cols].median()) | |
| min_class = pd.Series(y).value_counts().min() | |
| test_sz = max(len(np.unique(y)), int(len(df) * 0.2)) | |
| if len(df) > 6 and min_class >= 2 and test_sz < len(df): | |
| X_train, X_test, y_train, y_test = train_test_split( | |
| X, y, test_size=test_sz, random_state=42, stratify=y) | |
| do_eval = True | |
| else: | |
| X_train, y_train = X, y | |
| X_test, y_test = X, y | |
| do_eval = False | |
| rf = RandomForestClassifier(n_estimators=500, random_state=42) | |
| rf.fit(X_train, y_train) | |
| y_pred = rf.predict(X_test) | |
| accuracy = accuracy_score(y_test, y_pred) | |
| imp_df = pd.DataFrame({"指標": numeric_cols, "重要性": rf.feature_importances_})\ | |
| .sort_values("重要性", ascending=False).reset_index(drop=True) | |
| imp_path = output_dir / "03_feature_importance.csv" | |
| imp_df.to_csv(str(imp_path), index=False, encoding='utf-8-sig') | |
| top_n = min(20, len(imp_df)) | |
| fig, ax = plt.subplots(figsize=(10, 6)) | |
| ax.barh(imp_df['指標'][:top_n][::-1], imp_df['重要性'][:top_n][::-1], color='steelblue') | |
| ax.set_xlabel("特徵重要性") | |
| ax.set_title(f"隨機森林 — 前 {top_n} 項重要特徵") | |
| plt.tight_layout() | |
| imp_fig_path = output_dir / "03_feature_importance.png" | |
| plt.savefig(str(imp_fig_path), dpi=150, bbox_inches='tight') | |
| plt.close() | |
| # ── 5. 非監督式分群 ───────────────────────────────────────────────────────── | |
| scaler = StandardScaler() | |
| X_scaled = scaler.fit_transform(X) | |
| pca = PCA(n_components=min(2, X_scaled.shape[1]), random_state=42) | |
| X_pca = pca.fit_transform(X_scaled) | |
| # 階層式分群 | |
| linkage_mat = linkage(X_scaled, method='ward') | |
| fig, ax = plt.subplots(figsize=(10, 5)) | |
| dendrogram(linkage_mat, labels=df['Text'].values, leaf_rotation=45, leaf_font_size=8, ax=ax) | |
| ax.set_title("階層式分群樹狀圖（Ward 法）") | |
| # 2026-08-15（業主問「Sample 是什麼意思」）：橫軸的每一格代表一個被 | |
| # 分群的文本樣本（下方會列出各檔名），改成中文「樣本」，不用再解釋。 | |
| ax.set_xlabel("樣本"); ax.set_ylabel("距離") | |
| plt.tight_layout() | |
| dendro_path = output_dir / "04a_dendrogram.png" | |
| plt.savefig(str(dendro_path), dpi=150, bbox_inches='tight') | |
| plt.close() | |
| hc = AgglomerativeClustering(n_clusters=N_CLUSTERS, linkage='ward') | |
| df['HC_Cluster'] = hc.fit_predict(X_scaled) | |
| # K-means + Elbow | |
| max_k = min(8, max(2, len(df)-1)) | |
| inertia = [] | |
| for k in range(1, max_k+1): | |
| km = KMeans(n_clusters=k, random_state=42, n_init=10) | |
| km.fit(X_scaled) | |
| inertia.append(km.inertia_) | |
| fig, ax = plt.subplots(figsize=(7, 4)) | |
| ax.plot(list(range(1, max_k+1)), inertia, marker='o', color='coral') | |
| ax.set_xlabel("分群數量（K）"); ax.set_ylabel("群內誤差平方和（SSE）") | |
| ax.set_title("K-means 手肘圖"); ax.set_xticks(list(range(1, max_k+1))) | |
| plt.tight_layout() | |
| elbow_path = output_dir / "04b_kmeans_elbow.png" | |
| plt.savefig(str(elbow_path), dpi=150, bbox_inches='tight') | |
| plt.close() | |
| km_final = KMeans(n_clusters=N_CLUSTERS, random_state=42, n_init=10) | |
| df['KM_Cluster'] = km_final.fit_predict(X_scaled) | |
| # PCA 2D 視覺化 | |
| fig, axes = plt.subplots(1, 2, figsize=(14, 5)) | |
| for ax, lcol, title in zip(axes, | |
| ['HC_Cluster','KM_Cluster'], | |
| ['階層式分群', f'K-means 分群（K={N_CLUSTERS}）']): | |
| ulabels = sorted(df[lcol].unique()) | |
| colors = plt.cm.tab10(np.linspace(0, 1, len(ulabels))) | |
| for idx, cl in enumerate(ulabels): | |
| mask = df[lcol] == cl | |
| ax.scatter(X_pca[mask,0], X_pca[mask,1], | |
| c=[colors[idx]], label=f"群組 {cl}", s=100, edgecolors='k') | |
| for i, txt in enumerate(df['Text']): | |
| ax.annotate(txt[:8], (X_pca[i,0], X_pca[i,1]), | |
| fontsize=7, textcoords='offset points', xytext=(5,3)) | |
| ax.set_xlabel(f"主成分一（{pca.explained_variance_ratio_[0]:.1%}）" if X_scaled.shape[1]>=2 else "主成分一") | |
| ax.set_ylabel(f"主成分二（{pca.explained_variance_ratio_[1]:.1%}）" if X_scaled.shape[1]>=2 else "主成分二") | |
| ax.set_title(title); ax.legend() | |
| plt.suptitle("分群結果（主成分分析二維投影）", fontsize=12) | |
| plt.tight_layout() | |
| cluster_fig_path = output_dir / "04c_clustering_pca2d.png" | |
| plt.savefig(str(cluster_fig_path), dpi=150, bbox_inches='tight') | |
| plt.close() | |
| # 分群結果儲存 | |
| # 2026-08-15（業主回報「分群結果表格有個看不懂的 Type1.1 欄位」，追查 | |
| # 後發現）：GROUP_COL 這個變數的值就是字串 'Type1'（見上面第 887 行）， | |
| # 這裡卻又把 'Type1' 跟 GROUP_COL 兩個都放進 result_cols，等於同一欄 | |
| # 選了兩次；df[result_cols] 選出來的 DataFrame 因此有兩欄同名 Type1， | |
| # 存成 CSV 後欄名衝突，pandas 存檔/讀回的慣例是把重複欄名的第二個 | |
| # 加上 ".1" 後綴避免衝突——「Type1.1」就是這樣長出來的，內容跟 Type1 | |
| # 一模一樣，不是新資訊，純粹是選重複欄位的 bug。拿掉重複的 GROUP_COL | |
| # 就好，Type1 本身（真正的分組欄）保留。 | |
| result_cols = ['Text','Type1','Type2','HC_Cluster','KM_Cluster'] | |
| result_cols = [c for c in result_cols if c in df.columns] | |
| cluster_csv_path = output_dir / "05_cluster_results.csv" | |
| # 2026-08-15（業主要求）：使用者下載這份 CSV 直接看到 Type1／Type2 也 | |
| # 反映同樣的看不懂問題（先前只改了畫面顯示的複本，見 _populate_tabs | |
| # 裡的同名 rename 邏輯），這次直接在存檔時就處理，下載到的檔案本身 | |
| # 就是乾淨版本，不用開了 Excel 才發現欄名還是英文技術代碼。Type2 | |
| # 拿掉（一直是 Type1 的原樣複製，無額外資訊）、Type1 改標成「原始 | |
| # 分組(A/B)」。 | |
| cluster_export_df = ( | |
| df[result_cols] | |
| .drop(columns=["Type2"], errors="ignore") | |
| .rename(columns={"Type1": "原始分組(A/B)"}) | |
| ) | |
| cluster_export_df.to_csv(str(cluster_csv_path), index=False, encoding='utf-8-sig') | |
| # ── 6. 產出 docx 技術報告 ────────────────────────────────────────────────── | |
| timestamp = now_tw().strftime("%Y%m%d_%H%M%S") | |
| report_path = output_dir / f"Final_Report-{timestamp}.docx" | |
| doc = Document() | |
| style = doc.styles['Normal'] | |
| style.font.name = '微軟正黑體' | |
| style.font.size = Pt(10) | |
| title = doc.add_heading('統計結果技術報告', level=0) | |
| title.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| doc.add_paragraph(f'報告產出時間：{now_tw().strftime("%Y-%m-%d %H:%M:%S")}（台灣時間）', | |
| style='Normal').alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| doc.add_paragraph(f'分析文本數：{df.shape[0]} 筆', | |
| style='Normal').alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 2026-09-01（業主回報）：這裡原本直接印 GROUP_COL（一律是字面上的 | |
| # "Type1"，一個內部欄位名稱，不管實際用哪種分組方式都印一樣的字， | |
| # 對讀者毫無意義）。改成依 individual_grouping 是否非空，印出真正 | |
| # 描述本次實際採用哪種分組依據的文字——邏輯對應 run_statistical_ | |
| # analysis 開頭那段「individual_grouping 非空時取代檔名字首分組」 | |
| # 的判斷（見該處註解），確保這裡顯示的說明跟實際分組行為一致。 | |
| _group_method_desc = ( | |
| '個體間比較（依「譯者／系統名稱」分組；未填寫者退回檔名字首分組）' | |
| if individual_grouping else | |
| '依檔名字首分組（A／B／C…）' | |
| ) | |
| doc.add_paragraph(f'分組方式：{_group_method_desc}', | |
| style='Normal').alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| doc.add_paragraph('') | |
| # 敘述統計 | |
| doc.add_heading('一、敘述性統計', level=1) | |
| TABLE_HEADERS = ["指標代碼","指標名稱","文本個數","平均數","中位數","標準差","最小值","最大值","變異係數(%)"] | |
| for cat, items in INDEX_CATEGORIES.items(): | |
| cat_data = desc_df[desc_df['類別'] == cat] | |
| if cat_data.empty: continue | |
| doc.add_heading(f'（{cat}）', level=2) | |
| tbl = doc.add_table(rows=1+len(cat_data), cols=len(TABLE_HEADERS)) | |
| tbl.style = 'Light Shading Accent 1' | |
| for j, h in enumerate(TABLE_HEADERS): | |
| cell = tbl.rows[0].cells[j] | |
| cell.text = h | |
| for p in cell.paragraphs: | |
| p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| for r in p.runs: r.bold = True; r.font.size = Pt(8) | |
| for i, (_, row) in enumerate(cat_data.iterrows(), start=1): | |
| vals = [str(row['指標代碼']), str(row['指標名稱']), | |
| str(int(row['文本個數'])), | |
| f"{row['平均數']:.4f}", f"{row['中位數']:.4f}", | |
| f"{row['標準差']:.4f}", f"{row['最小值']:.4f}", | |
| f"{row['最大值']:.4f}", | |
| # 同下方差異性分析表格：改用 pd.isna()，避免 None 被 | |
| # pandas 建表時轉型成 NaN 後，is not None 抓不到而印出「nan」。 | |
| f"{row['變異係數(%)']:.2f}" if not pd.isna(row['變異係數(%)']) else "-"] | |
| for j, val in enumerate(vals): | |
| cell = tbl.rows[i].cells[j] | |
| cell.text = val | |
| for p in cell.paragraphs: | |
| p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| for r in p.runs: r.font.size = Pt(8) | |
| doc.add_paragraph('') | |
| # 差異性分析 | |
| doc.add_page_break() | |
| doc.add_heading('二、差異性分析', level=1) | |
| # 2026-08-15：{GROUP_COL} 原本會直接印出內部欄位名稱「Type1」，跟先前 | |
| # 修過的 Type1.1／rf_accuracy_is_meaningful 是同一種「技術變數名稱外 | |
| # 洩漏」問題，改成不點名欄位、只講語意。 | |
| doc.add_paragraph(f'分組依據：語料分組（共 {n_groups} 組）。採用 {method_name}，顯著水準 α = {ALPHA}。') | |
| _untestable_note = (f"另有 {len(untestable_df)} 個指標因組別樣本數不足（N<2），" | |
| f"無法進行統計檢定，不計入上述比例。" if len(untestable_df) > 0 else "") | |
| doc.add_paragraph(f'共 {len(diff_df)} 個指標，其中 {len(sig_df)} 個達顯著差異（p < {ALPHA}）。{_untestable_note}') | |
| # 2026-08-15（業主要求）：表格欄位裡的 N／M／SD 是統計慣用縮寫，第一次 | |
| # 看到報告的人不一定認得，加一句說明放在表格正上方。 | |
| note_p = doc.add_paragraph('表格中 N＝樣本數、M＝平均數、SD＝標準差。') | |
| note_p.runs[0].italic = True | |
| note_p.runs[0].font.size = Pt(8) | |
| group_sub_headers = [] | |
| for g in groups: | |
| group_sub_headers.extend([f"{g}\nN", f"{g}\nM", f"{g}\nSD"]) | |
| diff_headers = ["指標"] + group_sub_headers + ["方法","統計量","p值","顯著","效果量","效果大小","資料品質警示"] | |
| diff_tbl = doc.add_table(rows=1+len(diff_df), cols=len(diff_headers)) | |
| diff_tbl.style = 'Light Shading Accent 1' | |
| for j, h in enumerate(diff_headers): | |
| cell = diff_tbl.rows[0].cells[j] | |
| cell.text = h | |
| for p in cell.paragraphs: | |
| p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| for r in p.runs: r.bold = True; r.font.size = Pt(7) | |
| for i, (_, row) in enumerate(diff_df.iterrows(), start=1): | |
| vals = [str(row['指標'])] | |
| for g in groups: | |
| vals.extend([str(int(row[f"{g}_N"])), | |
| f"{row[f'{g}_M']:.4f}", | |
| f"{row[f'{g}_SD']:.4f}"]) | |
| # 2026-08-24（業主回報表格出現「nan」字樣）：diff_results 是一份 | |
| # dict list，其中某些列的「統計量」／「p值」／「效果量」是 Python | |
| # None（見 INSUFFICIENT_DATA_LABEL／EFFECT_UNSTABLE_LABEL 兩處）， | |
| # 但 `pd.DataFrame(diff_results)` 建表時，只要同一欄裡其餘列是數字， | |
| # pandas 會把整欄轉成 float64、None 也跟著被轉型成 NaN——`is not | |
| # None` 檢查完全抓不到轉型後的 NaN（NaN 不是 None 物件），因此原本 | |
| # 該顯示「-」的欄位印出了「nan」這個字面字串。改用 pd.isna()，能 | |
| # 同時抓到 None 與轉型後的 NaN 兩種情況。 | |
| _warn_text = row.get('資料品質警示', '') | |
| _warn_text = '' if pd.isna(_warn_text) else str(_warn_text) | |
| vals.extend([str(row['方法']), | |
| f"{row['統計量']:.4f}" if not pd.isna(row['統計量']) else "-", | |
| f"{row['p值']:.4f}" if not pd.isna(row['p值']) else "-", | |
| str(row['顯著']), | |
| f"{row['效果量']:.4f}" if not pd.isna(row['效果量']) else "-", | |
| str(row['效果大小']) if not pd.isna(row['效果大小']) else "-", | |
| _warn_text if _warn_text else "-"]) | |
| _is_untestable_row = row['顯著'] == INSUFFICIENT_DATA_LABEL | |
| # 2026-08-24：改用欄名查表格索引，不再用 len(vals) 往回數固定格數 | |
| # ——原本 len(vals)-4 在只有 6 個尾端欄位時其實已經對不準「顯著」 | |
| # 那一格（差一格，實際指到 p值），這次多加一欄「資料品質警示」後 | |
| # 用位置數只會更容易錯位，藉這次一起修成用欄名查，之後再加欄也不怕。 | |
| _sig_col_idx = diff_headers.index('顯著') | |
| _warn_col_idx = diff_headers.index('資料品質警示') | |
| for j, val in enumerate(vals): | |
| cell = diff_tbl.rows[i].cells[j] | |
| cell.text = val | |
| for p in cell.paragraphs: | |
| p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| for r in p.runs: | |
| r.font.size = Pt(7) | |
| # 顯著（紅字）跟資料不足（灰字）是兩種不同性質的標記， | |
| # 不能共用紅字——紅字在這份報告的視覺語言裡代表「這是 | |
| # 值得注意的發現」，「資料不足」剛好相反，是「這項不能 | |
| # 拿來當發現看」，用紅字反而會讓人誤以為它也是顯著結果。 | |
| if row['顯著'] not in ("ns", INSUFFICIENT_DATA_LABEL) and j == _sig_col_idx: | |
| r.font.color.rgb = RGBColor(0xCC, 0x00, 0x00) | |
| elif _is_untestable_row: | |
| r.font.color.rgb = RGBColor(0x88, 0x88, 0x88) | |
| r.italic = True | |
| # 見 ZERO_VARIANCE_WARNING：琥珀色，跟「顯著」的紅、 | |
| # 「資料不足」的灰都不同——這不是「無法使用」（灰）也不是 | |
| # 「重點發現」（紅），是「可用但要謹慎看待」的第三種性質。 | |
| elif j == _warn_col_idx and _warn_text: | |
| r.font.color.rgb = RGBColor(0xB4, 0x7A, 0x00) | |
| doc.add_paragraph('') | |
| if box_path and box_path.exists(): | |
| doc.add_heading('顯著指標箱形圖', level=2) | |
| doc.add_picture(str(box_path), width=Cm(16)) | |
| doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 隨機森林 | |
| doc.add_page_break() | |
| doc.add_heading('三、監督式學習 — 隨機森林特徵重要性', level=1) | |
| doc.add_paragraph(f'模型準確率（Accuracy）：{accuracy:.4f}') | |
| if imp_fig_path.exists(): | |
| doc.add_picture(str(imp_fig_path), width=Cm(15)) | |
| doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 分群 | |
| doc.add_page_break() | |
| doc.add_heading('四、非監督式學習 — 集群分析', level=1) | |
| if dendro_path.exists(): | |
| doc.add_heading('樹狀圖（階層式分群）', level=2) | |
| doc.add_picture(str(dendro_path), width=Cm(15)) | |
| doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| if elbow_path.exists(): | |
| doc.add_heading('Elbow Curve（K-means）', level=2) | |
| doc.add_picture(str(elbow_path), width=Cm(12)) | |
| doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| if cluster_fig_path.exists(): | |
| doc.add_heading('分群視覺化（PCA 2D）', level=2) | |
| doc.add_picture(str(cluster_fig_path), width=Cm(16)) | |
| doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| doc.save(str(report_path)) | |
| return { | |
| "df": df, | |
| "desc_path": desc_path, | |
| "diff_path": diff_path, | |
| "imp_path": imp_path, | |
| "imp_fig_path": imp_fig_path, | |
| "box_path": box_path, | |
| "dendro_path": dendro_path, | |
| "elbow_path": elbow_path, | |
| "cluster_fig_path": cluster_fig_path, | |
| "cluster_csv_path": cluster_csv_path, | |
| "report_path": report_path, | |
| "sig_count": len(sig_df), | |
| "untestable_count": len(untestable_df), | |
| "total_indicators": len(diff_df), | |
| "accuracy": accuracy, | |
| "do_eval": do_eval, | |
| "groups": list(groups), | |
| "n_groups": n_groups, | |
| "method_name": method_name, | |
| "GROUP_COL": GROUP_COL, | |
| "pca_ev": pca.explained_variance_ratio_.tolist(), | |
| } | |
| # ============================================================================ | |
| # SECTION 7: LLM Report Writing (adapted from prog04, uses LLM1) | |
| # ============================================================================ | |
| def load_analysis_data_for_llm(csv_path: Path, output_dir: Path, ml_summary: dict = None, | |
| group_labels: dict = None) -> dict: | |
| """讀取分析資料組成 JSON 結構。 | |
| ml_summary：{"accuracy": float, "do_eval": bool} 選填，來自 | |
| run_statistical_analysis() 的回傳值。之前這裡完全沒有把隨機森林的 | |
| 準確率數字（accuracy）跟「這次是不是真的切了測試集」（do_eval） | |
| 交給 LLM，LLM 因此連準確率是多少都不知道，等於沒有材料可以討論 | |
| 監督式學習結果——03_feature_importance.csv 只有各指標的重要性排名， | |
| 沒有整體準確率這個數字。 | |
| group_labels：{分組代碼: 語料說明填的實際標籤}，選填。2026-08-24（業主 | |
| 回報）：畫面上的差異性分析標題／箱形圖標籤早就會用語料說明填的實際 | |
| 標籤（如「人工翻譯」），但 LLM 報告內文卻一路只看得到原始代碼 A／B， | |
| 寫成「群組 A 最高」——追查後發現 difference_analysis 送給 LLM 的 JSON | |
| 欄名（{組別}_N／{組別}_M／{組別}_SD）從頭到尾都是原始代碼，從沒套用過 | |
| 這組標籤，等於畫面跟報告各自套用了不同版本的分組名稱。這裡補上同一套 | |
| 轉換，讓兩邊使用同一個資料來源。""" | |
| data = {} | |
| if ml_summary: | |
| # 2026-08-15（業主回報）：原本這裡是英文鍵名 rf_accuracy／ | |
| # rf_accuracy_is_meaningful，靠 system prompt 那條「英文鍵名要 | |
| # 換成中文說法」的規則要求 LLM 自己翻譯，結果 LLM 沒穩定照辦， | |
| # 報告裡直接印出「由於 rf_accuracy_is_meaningful 為 true...」這種 | |
| # 變數名稱。改成在這裡把「是否具樣本外預測意義」直接寫成完整的 | |
| # 中文句子存進 JSON——LLM 就算照抄 JSON 內容，抄出來的也已經是 | |
| # 人看得懂的句子，不用依賴它額外做翻譯這個不保證會做到的步驟。 | |
| acc = ml_summary.get("accuracy") | |
| data["隨機森林分類準確率"] = round(acc, 4) if isinstance(acc, (int, float)) else acc | |
| data["隨機森林準確率之樣本外預測意義"] = ( | |
| "具備樣本外預測意義（本次有切分獨立的測試集）" | |
| if ml_summary.get("do_eval") | |
| else "不具備樣本外預測意義（本次樣本數過小，訓練集與測試集為同一批資料，" | |
| "此準確率僅反映模型對訓練資料本身的擬合程度）" | |
| ) | |
| if csv_path.exists(): | |
| raw = pd.read_csv(str(csv_path)) | |
| aj_cols = [c for c in raw.columns if c.startswith('AJ_')] | |
| raw.drop(columns=aj_cols, inplace=True, errors='ignore') | |
| data["texts"] = raw['Text'].tolist() | |
| data["text_count"] = len(raw) | |
| else: | |
| data["texts"] = []; data["text_count"] = 0 | |
| for fname, key in [ | |
| ("01_descriptive_stats.csv", "descriptive_stats"), | |
| ("02_difference_analysis.csv", "difference_analysis"), | |
| ("03_feature_importance.csv", "feature_importance_top20"), | |
| ("05_cluster_results.csv", "cluster_results"), | |
| ]: | |
| p = output_dir / fname | |
| if p.exists(): | |
| d = pd.read_csv(str(p)) | |
| if key == "difference_analysis" and group_labels: | |
| group_codes = [c[:-2] for c in d.columns if c.endswith('_N')] | |
| rename_map = {} | |
| for g in group_codes: | |
| label = group_labels.get(g) | |
| if label and label != g: | |
| rename_map[f"{g}_N"] = f"{label}_N" | |
| rename_map[f"{g}_M"] = f"{label}_M" | |
| rename_map[f"{g}_SD"] = f"{label}_SD" | |
| if rename_map: | |
| d = d.rename(columns=rename_map) | |
| if key == "cluster_results": | |
| # 2026-08-15（業主要求）：跟 rf_accuracy_is_meaningful 同一個 | |
| # 教訓——原本這裡的欄名是 Type1，LLM 直接照抄，報告寫成 | |
| # 「原始分組（Type1）」。改成在資料層就把 Type1 換成「原始 | |
| # 分組」這個中文欄名，Type2 拿掉（一直是 Type1 的原樣複製， | |
| # 沒有額外資訊，見 run_statistical_analysis 那行 df['Type2'] | |
| # = df['Type1'] 的註解），LLM 照抄 JSON 內容時自然就只會 | |
| # 寫「原始分組」，不會再冒出 Type1 這個技術欄名。 | |
| d = d.drop(columns=["Type2"], errors="ignore") \ | |
| .rename(columns={"Type1": "原始分組"}) | |
| if key == "feature_importance_top20": | |
| data[key] = d.head(20).to_dict(orient='records') | |
| else: | |
| data[key] = d.to_dict(orient='records') | |
| if key == "difference_analysis": | |
| if '顯著' in d.columns: | |
| sig = d[~d['顯著'].isin(['ns', INSUFFICIENT_DATA_LABEL])] | |
| untestable = d[d['顯著'] == INSUFFICIENT_DATA_LABEL] | |
| else: | |
| sig = pd.DataFrame(); untestable = pd.DataFrame() | |
| data["significant_indicators"] = sig.to_dict(orient='records') | |
| data["significant_count"] = len(sig) | |
| data["total_indicators"] = len(d) | |
| # 2026-08-22：跟資料層預先中文化同一個原則（見 | |
| # rf_accuracy_is_meaningful／cluster Type1 的前例）——與其在 | |
| # system prompt 裡要求 LLM「自己判斷哪些指標資料不足」， | |
| # 這裡直接把清單跟現成的中文說明準備好，LLM 只要照抄，不用 | |
| # 自己從一堆 JSON 欄位裡推斷「顯著＝資料不足」代表什麼。 | |
| data["untestable_indicators"] = untestable.to_dict(orient='records') | |
| data["untestable_count"] = len(untestable) | |
| data["資料完整性提醒"] = ( | |
| f"以上 difference_analysis 中有 {len(untestable)} 項指標的「顯著」欄位" | |
| f"標示為「{INSUFFICIENT_DATA_LABEL}」，代表該指標在某一組別的樣本數少於 2" | |
| "（無法計算組內變異），統計檢定本身就無法執行，p 值與效果量均為 null。" | |
| "這些指標必須明確陳述為「資料不足，無法檢定」，絕對不可以寫成「無顯著差異」" | |
| "或納入「達統計顯著」／「無明顯差異」的分類統計，兩者是完全不同的結論。" | |
| if len(untestable) > 0 else "" | |
| ) | |
| # 2026-08-24（業主回報 AG_05 案例，見 ZERO_VARIANCE_WARNING 定義 | |
| # 處）：「資料品質警示」欄位非空的指標，p 值與效果量都是有效 | |
| # 計算結果、正常參與顯著性統計，跟上面的「資料不足」是不同 | |
| # 性質，不能用同一句話說明，另外準備一段中文提醒。 | |
| if '資料品質警示' in d.columns: | |
| zero_var = d[d['資料品質警示'].fillna('') != ''] | |
| else: | |
| zero_var = pd.DataFrame() | |
| data["zero_variance_warning_indicators"] = zero_var['指標'].tolist() if len(zero_var) > 0 else [] | |
| data["zero_variance_warning_count"] = len(zero_var) | |
| data["資料穩定性提醒"] = ( | |
| f"以上 difference_analysis 中有 {len(zero_var)} 項指標的「資料品質警示」欄位非空" | |
| "（列於 zero_variance_warning_indicators），代表該指標至少有一組出現以下情況之一：" | |
| "①該組所有文本在此指標上數值完全相同，標準差趨近於 0；或 ②該組半數以上文本在" | |
| "此指標上數值為 0，樣本集中於零值，平均數可能被少數非零離群值主導。這兩種情況下 " | |
| "p 值與效果量仍是正常計算、正常算入「達統計顯著」的統計比例，不像「資料不足」那樣" | |
| "要整項排除；但陳述這些指標時，必須額外註明「此結果統計穩定性有限，建議謹慎解讀」" | |
| "這類保留語氣，不可跟其他變異正常的顯著指標用完全相同的肯定語氣陳述，避免讀者把" | |
| "統計上脆弱的結果當成跟其他乾淨顯著結果同等份量的證據。" | |
| if len(zero_var) > 0 else "" | |
| ) | |
| else: | |
| data[key] = [] | |
| if "significant_count" not in data: | |
| data["significant_count"] = 0 | |
| if "total_indicators" not in data: | |
| data["total_indicators"] = 0 | |
| return data | |
| # 2026-08-14（待辦 A1，業主拍板）：LLM 報告存成 docx 時，原本的迴圈只認 | |
| # 區塊層級語法（# 標題／- 項目符號），一行裡的 **粗體**、$LaTeX$ 這類行內 | |
| # 語法會原封不動貼成文字。這裡補一個行內語法解析： | |
| # **文字** → 粗體 run | |
| # $文字$ → 斜體 run（拆掉 $ 符號；docx 沒有內建 LaTeX 公式排版， | |
| # 真要轉成 Word 公式物件（OMML）得另外導入 latex2mathml | |
| # 之類的套件，複雜度與風險都高，業主拍板先用「斜體純文字」 | |
| # 這個較簡單、較不會转換失敗的做法） | |
| # 非貪婪 regex 一次切出 **...** 或 $...$ 區段，其餘原樣輸出；兩種語法 | |
| # 不處理巢狀（例如 **$x$** 或 $**x**$），這份報告的 LLM 輸出目前沒有 | |
| # 這種寫法，不特別處理以免過度工程化。 | |
| _INLINE_MD_RE = re.compile(r'(\*\*.+?\*\*|\$.+?\$)') | |
| def _add_inline_markdown_runs(paragraph, text: str) -> None: | |
| """把一行文字依 **粗體** / $LaTeX$ 語法拆成多個 run，加進既有段落。""" | |
| for piece in _INLINE_MD_RE.split(text): | |
| if not piece: | |
| continue | |
| if piece.startswith('**') and piece.endswith('**') and len(piece) >= 4: | |
| paragraph.add_run(piece[2:-2]).bold = True | |
| elif piece.startswith('$') and piece.endswith('$') and len(piece) >= 2: | |
| paragraph.add_run(piece[1:-1]).italic = True | |
| else: | |
| paragraph.add_run(piece) | |
| def run_report_writing(scenario_key: str, user_metadata: str, user_focus: str, | |
| csv_path: Path, output_dir: Path, ml_summary: dict = None, | |
| group_labels: dict = None) -> dict: | |
| """ | |
| 呼叫主 Agent (LLM1) 撰寫研究報告，儲存 docx + txt，回傳路徑 dict。 | |
| ml_summary：見 load_analysis_data_for_llm() 的說明。 | |
| group_labels：見 load_analysis_data_for_llm() 的說明。 | |
| """ | |
| output_dir.mkdir(parents=True, exist_ok=True) | |
| analysis_data = load_analysis_data_for_llm(csv_path, output_dir, ml_summary=ml_summary, | |
| group_labels=group_labels) | |
| scenario_info = SCENARIOS.get(scenario_key, SCENARIOS["1"]) | |
| scenario_mod_key = scenario_info.get("scenario_module_key", "scenario_1") | |
| scenario_module = SCENARIO_MODULES.get(scenario_mod_key, "") | |
| metadata_str = f"共 {analysis_data['text_count']} 個譯本\n" | |
| for i, t in enumerate(analysis_data["texts"], 1): | |
| metadata_str += f" 譯本{i}：{t}\n" | |
| if user_metadata: | |
| metadata_str += f"\n【使用者補充】：\n{user_metadata}" | |
| system_prompt = SYSTEM_PROMPT_BASE.format( | |
| scenario_type = scenario_info["title"], | |
| metadata = metadata_str, | |
| user_focus = user_focus if user_focus else "無", | |
| scenario_module = scenario_module, | |
| indicator_reference_table = INDICATOR_REFERENCE_TABLE, | |
| ) | |
| # 2026-08-26（業主要求：可重複性設計的最後一塊——目前報告只印「提示詞 | |
| # 版本 v1」這個版本號，使用者／論文口委無從查證這個版本實際規定了 | |
| # 什麼，只能回頭翻原始碼）：把這次分析實際套用（.format() 展開後、 | |
| # 已代入研究情境／metadata／指標對照表的完整版本）的 system prompt | |
| # 原文存成一份檔案，跟其他分析產出放在同一個 output_dir，隨「下載 | |
| # 全部資料」一起打包。直接從程式實際使用的字串存出來，不是另外維護 | |
| # 一份文件，未來 SYSTEM_PROMPT_BASE 異動也不會有兩邊對不起來的風險。 | |
| system_prompt_path = output_dir / "06_system_prompt.txt" | |
| with open(str(system_prompt_path), 'w', encoding='utf-8') as f: | |
| f.write(f"研究情境：{scenario_info['title']}\n") | |
| f.write(f"提示詞版本：{PROMPT_VERSION}\n") | |
| f.write(f"模型：主 Agent（LLM1）{LLM1_MODEL}\n") | |
| f.write( | |
| "\n本檔案為這次分析實際送給 LLM 的完整 system prompt 原文\n" | |
| "（已代入本次的研究情境、語料 metadata 與指標代碼對照表）。\n" | |
| ) | |
| f.write("\n---\n\n") | |
| f.write(system_prompt) | |
| user_prompt = ( | |
| f"請根據以下量化分析結果，按照 system prompt 中的輸出結構進行深度分析。\n\n" | |
| f"【量化分析資料（JSON）】：\n```json\n" | |
| f"{json.dumps(analysis_data, ensure_ascii=False, indent=2)}\n```\n\n" | |
| "請嚴格按照五個區塊（一、語料說明 / 二、數據事實描述 / " | |
| "三、情境特定分析 / 四、待驗證事項 / 五、已知限制）輸出分析報告。" | |
| ) | |
| result_text = call_main_agent(system_prompt, user_prompt) | |
| timestamp = now_tw().strftime("%Y%m%d_%H%M%S") | |
| docx_path = output_dir / f"LLM_Analysis-{timestamp}.docx" | |
| txt_path = output_dir / f"LLM_Analysis-{timestamp}.txt" | |
| # 存 docx | |
| doc = Document() | |
| style = doc.styles['Normal'] | |
| style.font.name = '微軟正黑體' | |
| style.font.size = Pt(11) | |
| heading = doc.add_heading('LLM 輔助重譯研究報告', level=0) | |
| heading.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 標題後標註使用的 LLM 模型（藍色） | |
| model_p = doc.add_paragraph() | |
| model_p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 2026-08-22（可重複性設計）：模型名稱後面補上提示詞版本號，讓每份報告 | |
| # 都留下「當時是哪一版 system prompt 產出的」這個事後可稽核的紀錄，不用 | |
| # 回頭 git blame 才查得到——PROMPT_VERSION 定義處、修改時機見該常數註解。 | |
| mr = model_p.add_run( | |
| f'本報告由主 Agent（LLM1）模型 {LLM1_MODEL} 生成（提示詞版本 {PROMPT_VERSION}）' | |
| ) | |
| mr.font.size = Pt(10) | |
| mr.font.color.rgb = RGBColor(0x0E, 0x73, 0xB8) | |
| doc.add_paragraph(f'研究情境：{scenario_info["title"]}', | |
| style='Normal').alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| doc.add_paragraph(f'報告時間：{now_tw().strftime("%Y-%m-%d %H:%M:%S")}（台灣時間）', | |
| style='Normal').alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| # 2026-08-24（業主回報：之前加過的 N/M/SD 圖例只在 Final_Report.docx | |
| # 那份技術報告的表格上方，這份 LLM 敘述報告是完全獨立的檔案，內文一樣 | |
| # 大量使用「M=...」但從沒解釋過，使用者只拿到這份報告的話完全看不懂。 | |
| # 兩份報告各自獨立、讀者不一定兩份都會看，圖例需要在各自檔案裡都出現， | |
| # 不能假設讀者一定也看過另一份。 | |
| legend_p = doc.add_paragraph( | |
| '本報告中 N＝樣本數、M＝平均數、SD＝標準差；p 為統計顯著性之機率值，' | |
| '效果量以 Cohen\'s d（二群比較）或 η²（三群以上）表示。' | |
| ) | |
| legend_p.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| legend_p.runs[0].italic = True | |
| legend_p.runs[0].font.size = Pt(9) | |
| # 2026-08-26：提示詞版本號旁邊只有一個代號（v1），讀者查不到內容本身 | |
| # 具體規定了什麼——這裡指向同一次下載包裡的完整原文檔案。 | |
| sp_note = doc.add_paragraph( | |
| f'本報告據以撰寫的完整 system prompt 原文，請見同一份下載包中的 06_system_prompt.txt。' | |
| ) | |
| sp_note.alignment = WD_ALIGN_PARAGRAPH.CENTER | |
| sp_note.runs[0].italic = True | |
| sp_note.runs[0].font.size = Pt(9) | |
| doc.add_page_break() | |
| # 2026-08-14（待辦 A1）：區塊層級語法（標題／項目符號）沿用原本判斷， | |
| # 差別是段落文字改用 _add_inline_markdown_runs() 逐段解析 **粗體**／ | |
| # $LaTeX$，不再是整行原樣塞給 add_heading()/add_paragraph()。 | |
| for line in result_text.split('\n'): | |
| stripped = line.strip() | |
| if stripped.startswith('#### '): _add_inline_markdown_runs(doc.add_heading('', level=4), stripped[5:]) | |
| elif stripped.startswith('### '): _add_inline_markdown_runs(doc.add_heading('', level=3), stripped[4:]) | |
| elif stripped.startswith('## '): _add_inline_markdown_runs(doc.add_heading('', level=2), stripped[3:]) | |
| elif stripped.startswith('# '): _add_inline_markdown_runs(doc.add_heading('', level=1), stripped[2:]) | |
| elif stripped.startswith('- '): _add_inline_markdown_runs(doc.add_paragraph(style='List Bullet'), stripped[2:]) | |
| elif stripped.startswith('* '): _add_inline_markdown_runs(doc.add_paragraph(style='List Bullet'), stripped[2:]) | |
| elif stripped: _add_inline_markdown_runs(doc.add_paragraph(), stripped) | |
| doc.save(str(docx_path)) | |
| # 存 txt（模型標註置於標題下方） | |
| with open(str(txt_path), 'w', encoding='utf-8') as f: | |
| f.write(f"研究情境：{scenario_info['title']}\n") | |
| f.write(f"時間：{now_tw().strftime('%Y-%m-%d %H:%M:%S')}（台灣時間）\n") | |
| # 2026-08-22（可重複性設計）：docx 版標題下方本來就有模型名稱標註， | |
| # txt 版之前完全沒寫，這裡補上、順便帶提示詞版本號，兩種格式的 | |
| # 稽核資訊要一致，不能只有 docx 有。 | |
| f.write(f"模型：主 Agent（LLM1）{LLM1_MODEL}（提示詞版本 {PROMPT_VERSION}）\n") | |
| # 2026-08-24（業主回報 N/M/SD 圖例只加在 Final_Report.docx，這份 LLM | |
| # 敘述報告內文一樣大量出現「M=...」卻沒有解釋，兩份報告是獨立檔案、 | |
| # 讀者不一定都看過，圖例要各自都有）： | |
| f.write( | |
| "本報告中 N＝樣本數、M＝平均數、SD＝標準差；p 為統計顯著性之機率值，" | |
| "效果量以 Cohen's d（二群比較）或 η²（三群以上）表示。\n" | |
| ) | |
| # 2026-08-26：同 docx 版，指向同一份下載包裡的完整 system prompt 原文。 | |
| f.write("本報告據以撰寫的完整 system prompt 原文，請見同一份下載包中的 06_system_prompt.txt。\n") | |
| # 2026-07-27：原本用 "="*60 當純文字分隔線，但緊接在上兩行文字正下方， | |
| # 符合 Markdown Setext 標題語法（文字正上方接一整行 = 會被解讀成 h1 | |
| # 底線），導致這兩行 metadata 被渲染成巨大無樣式標題。改成前面留空行 | |
| # 再接 "---"，變成正規的 <hr> 分隔線（已有 CSS 樣式），純文字閱讀也 | |
| # 不受影響。 | |
| f.write("\n---\n\n") | |
| f.write(result_text) | |
| return { | |
| "docx_path": docx_path, | |
| "txt_path": txt_path, | |
| "result_text": result_text, | |
| "system_prompt_path": system_prompt_path, | |
| } | |
| # ============================================================================ | |
| # SECTION 8: (Reserved) | |
| # ============================================================================ | |
| # ============================================================================ | |
| # SECTION 9: Conversation Flow & State Machine | |
| # ============================================================================ | |
| STATES = { | |
| "SCENARIO_SELECT": "研究情境選擇", | |
| "UPLOAD_GUIDE": "文本上傳說明", | |
| "UPLOAD_WAIT": "等待文本上傳", | |
| "FORMAT_CHECK": "格式檢查中", | |
| "CALCULATING": "指標計算中", | |
| "ANALYZING": "統計分析中", | |
| "REPORT_WRITING": "研究報告撰寫中", | |
| "COMPLETE": "分析完成", | |
| } | |
| def _assistant_msg(text: str): | |
| return {"role": "assistant", "content": text} | |
| def _user_msg(text: str): | |
| return {"role": "user", "content": text} | |
| def make_initial_state(session_id: str) -> dict: | |
| sess_dir = SESSIONS_DIR / session_id | |
| sess_dir.mkdir(parents=True, exist_ok=True) | |
| (sess_dir / "uploads").mkdir(exist_ok=True) | |
| (sess_dir / "output").mkdir(exist_ok=True) | |
| return { | |
| "session_id": session_id, | |
| "session_dir": str(sess_dir), | |
| "state": "SCENARIO_SELECT", | |
| "scenario": None, | |
| "uploaded_files": [], | |
| "invalid_info": {}, | |
| "cleaned_files": [], | |
| "output_files": [], | |
| # 2026-07-24：原本是 zip_path（單數），從專案第一天就只被初始化成 None、 | |
| # 從沒被賦值過。改成 dict 存四包 zip 的路徑，key 見 _ZIP_GROUPS。 | |
| "zip_paths": {}, | |
| "user_metadata": "", | |
| "user_focus": "", | |
| "group_labels": {}, # {分組代碼: 語料說明填的實際標籤}，略過或未填時維持空 dict | |
| "individual_grouping": {}, # {檔名: 個體間比較的分組標籤}，非「個體間比較」模式時維持空 dict | |
| "analysis_result": None, | |
| "done_steps": [], # 已完成步驟（1-based） | |
| "current_step": None, # 目前執行步驟 | |
| "failed_step": None, # 執行失敗時卡在哪一步（1-based），成功時維持 None | |
| # 「分析運算」步驟底下三個子階段的即時狀態，供 Canvas 內容區塊分段呈現 | |
| # （見 _build_analysis_html）。status: pending / running / done / failed； | |
| # line: 給人看的一句結果或失敗原因。由 run_computation_pipeline_streaming | |
| # 邊跑邊寫入。 | |
| "analysis": { | |
| "idx": {"status": "pending", "line": ""}, | |
| "stat": {"status": "pending", "line": ""}, | |
| "report": {"status": "pending", "line": ""}, | |
| }, | |
| # 「文本上傳」步驟底下兩個子階段的即時狀態，結構比照上面的 analysis | |
| # （3-C，2026-07-30）：供 Canvas 內容區塊分段呈現上傳進度（見 | |
| # _build_upload_html），status: pending / running / done / failed； | |
| # line: 給人看的一句結果或失敗原因。由 on_upload_confirm 邊跑邊寫入。 | |
| "upload": { | |
| "receive": {"status": "pending", "line": ""}, | |
| "validate": {"status": "pending", "line": ""}, | |
| }, | |
| # 2026-07-31（Batch E 第 7 項）：原本這裡有 "tabs_toast_shown": False， | |
| # 是 Bug 4-A 修復時為了擋「分析結果已就緒」toast 重複跳出而加的旗標 | |
| # （_populate_tabs 現在會在每個子階段剛完成時都被呼叫，不再只呼叫 | |
| # 一次）。業主要求拿掉那顆 toast 本身（見 _populate_tabs），旗標 | |
| # 跟著失去用途，一併移除，不留無作用的殘留狀態。 | |
| } | |
| # 2026-07-23 步驟列收斂：原本 8 步裡有 4 步不帶資訊——①情境選擇在 Phase 8-A | |
| # 搬去首頁後，使用者在工作區看到的是別的畫面做完的事；①② 在同一個 generator | |
| # 內連續完成，中間沒有任何使用者動作；⑦⑧ 本來就寫死在同一行一起標記（下載 | |
| # 成果不是獨立運算階段）。同時補上原本完全沒有步驟的「語料說明」表單——先前 | |
| # 格式驗證通過就直接把 current_step 設成「指標計算」，導致使用者在填表的整段 | |
| # 期間，步驟列都亮著「指標計算 進行中」的呼吸動畫，畫面在說電腦正在算，實際 | |
| # 上是在等人填表。收斂後每一步都對應一件使用者感知得到的事。 | |
| # 2026-07-24 再收斂：8→6 之後又拿掉兩步。 | |
| # ① 移除「格式驗證」：它在任何靜止狀態下都不會停留——通過時跟前一步在同一個 | |
| # generator 內連續完成、中間沒有使用者動作；失敗時步驟列退回「文本上傳 | |
| # 進行中」（要求重新上傳），也不停在格式驗證。它從來不對應一個使用者能看到 | |
| # 的畫面狀態，逐行細節仍在技術執行紀錄裡。 | |
| # ② 合併「指標計算／統計分析／報告產出」成單一「分析運算」：三段是同一個 | |
| # generator 依序跑完的運算，中間沒有任何使用者操作關卡。三段各自有失敗 | |
| # 可能，但「壞在哪一段、其他段有沒有救」這種細節，藥丸大小的步驟列講不 | |
| # 清楚，改由 Canvas 的分析運算內容區塊分段呈現（見 _build_analysis_html）。 | |
| # 2026-07-30：業主要求把情境選擇從首頁搬回工作區，成為正式的第 1 步「研究 | |
| # 選擇」（見 create_app() 的 scenario_select_row、on_start_analysis_show／ | |
| # on_scenario_pick）。原本①提到「情境選擇搬去首頁後不算步驟列一步」在此 | |
| # 已不成立，_STEPS 從 3 步變 4 步，後面三步的編號全部 +1。 | |
| _STEPS = [ | |
| (1, "情境選擇"), | |
| (2, "文本上傳"), | |
| (3, "語料說明"), | |
| (4, "分析運算"), | |
| ] | |
| # 分析運算底下的三個子階段（key 用於 state["analysis"]、內容區塊分段、入口連結） | |
| _ANALYSIS_STAGES = [ | |
| ("idx", "指標計算", "idx"), | |
| ("stat", "統計分析", "stat"), | |
| ("report", "報告撰寫", "report"), | |
| ] | |
| def _build_header_html(done_steps: list = None, current_step: int = None, | |
| failed_step: int = None) -> str: | |
| """ | |
| 產生完整標題區塊 HTML（精簡單行產品名＋動態步驟列），確定性、不依賴 LLM。 | |
| 2026-07-23 千卉回報原本三行大標題＋額外進度條佔比過高，改成單行精簡 | |
| 產品名、拿掉進度條（進度資訊本來就已經完整表達在步驟列的已完成/進行中 | |
| /失敗三種狀態上，進度條是重複資訊）。 | |
| done_steps: 已完成步驟（1-based list） | |
| current_step: 目前執行步驟（1-based int） | |
| failed_step: 執行失敗時卡住的步驟（1-based int），失敗時該步驟改用失敗樣式， | |
| 不再顯示「進行中」的呼吸動畫（原本失敗時圓點會永遠卡在動畫， | |
| 使用者容易誤以為系統還在運算而手滑刷新頁面） | |
| """ | |
| done_steps = done_steps or [] | |
| # 2026-07-24：原本全部完成後整條步驟列收起、只留產品名，理由是「把高度讓給 | |
| # 結果內容」。但那是舊的「結果堆疊往下捲」模型下的決定；7-23 改成互斥頁面 | |
| # 切換後，完成時若停在 AI 對話頁，Canvas 根本沒有結果內容，讓出來的是一片 | |
| # 空白——步驟列一消失，畫面就整片空掉（千卉實測回報「連步驟列都消失了」）。 | |
| # 改成完成後步驟列留在原地、全部標 ✓，收尾感與畫面穩定都靠這排 ✓ 維持， | |
| # Canvas 的分析運算內容區塊則負責承載完成摘要。 | |
| pills = [] | |
| for num, name in _STEPS: | |
| if num == failed_step: | |
| pills.append( | |
| f'<span class="step-pill step-pill--failed">' | |
| f'<span class="step-num">!</span>{name}</span>' | |
| ) | |
| elif num in done_steps: | |
| pills.append( | |
| f'<span class="step-pill step-pill--done">' | |
| f'<span class="step-num">✓</span>{name}</span>' | |
| ) | |
| elif num == current_step: | |
| pills.append( | |
| f'<span class="step-pill step-pill--current">' | |
| f'<span class="step-num">{num}</span>{name}</span>' | |
| ) | |
| else: | |
| pills.append( | |
| f'<span class="step-pill">' | |
| f'<span class="step-num">{num}</span>{name}</span>' | |
| ) | |
| # 2026-07-31（Batch E 第 4-b 項）：業主指定頂部列不要標題文字， | |
| # 原本的 <p class="title-line"> 整行移除，只留步驟列（四顆藥丸）。 | |
| # .title-line 這個 class 的 CSS 規則（含深色模式那份漸層文字修正） | |
| # 留著不刪：跟前四批同名 class 的踩坑記錄綁在一起，且沒有其他地方 | |
| # 在用會自動失效，不影響畫面；真的要清理屬於「順手清理死碼」， | |
| # 這批任務範圍不包含。 | |
| return ( | |
| '<div class="app-header">' | |
| f' <div class="steps">{"".join(pills)}</div>' | |
| '</div>' | |
| ) | |
| def handle_scenario_select(user_input: str, state: dict): | |
| """處理研究情境選擇輸入，回傳 (reply_text, new_state)。""" | |
| choice = user_input.strip() | |
| m = re.search(r'[1-4]', choice) | |
| if not m: | |
| return ("請輸入數字 **1、2、3 或 4** 選擇研究情境。", state) | |
| sc_num = m.group() | |
| sc_info = SCENARIOS[sc_num] | |
| state["scenario"] = sc_num | |
| # 2026-07-30：研究選擇（3-A）搬進工作區成為正式第 1 步後，選定情境＝ | |
| # 完成第 1 步，直接站上第 2 步「文本上傳」（原本情境選擇在首頁完成、 | |
| # 不算步驟列一步，_STEPS 只有 3 步；現在 _STEPS 變 4 步，步驟編號全部 +1） | |
| state["done_steps"] = [1] | |
| state["current_step"] = 2 | |
| # 固定文字，不經 LLM：確保每次措辭一致，並直接引導使用者去看上傳卡片裡的 | |
| # 格式要求，不需要另外由工作程序 Agent 生成一則重複格式細節的引導訊息 | |
| confirm_text = ( | |
| f"已確認您的研究情境為「{sc_num}. {sc_info['title']}」。" | |
| "接下來請您上傳文本檔案。" | |
| ) | |
| state["state"] = "UPLOAD_GUIDE" | |
| return (confirm_text, state) | |
| def handle_uploaded_files(files, state: dict): | |
| """ | |
| 接收 Gradio 上傳的檔案，複製到 session 目錄，回傳狀態更新與訊息。 | |
| """ | |
| if not files: | |
| return "尚未偵測到上傳檔案，請重新上傳。", state | |
| uploads_dir = Path(state["session_dir"]) / "uploads" | |
| uploads_dir.mkdir(parents=True, exist_ok=True) | |
| saved_paths = [] | |
| for f in files: | |
| src = Path(f.name) if hasattr(f, 'name') else Path(str(f)) | |
| dst = uploads_dir / src.name | |
| shutil.copy2(str(src), str(dst)) | |
| saved_paths.append(str(dst)) | |
| # 2026-08-15（業主回報「上傳5個刪除2個，語料說明跟計算卻還是用5個」， | |
| # 追查後發現）：這裡原本是跟 state["uploaded_files"] 合併，不是直接 | |
| # 覆蓋——原意是想支援「格式驗證失敗時只需補傳有問題的檔案」，但 | |
| # Gradio 的 file_input 元件送過來的 files 只反映「使用者目前選取的 | |
| # 檔案是哪些」，沒辦法分辨「這次沒選這個檔案」到底是「使用者刻意刪除 | |
| # 不要了」還是「使用者沒有要動它、單純沒重新選」——合併邏輯把兩種 | |
| # 都當成後者處理，使用者刪除的檔案因此被「復活」跟這次選的檔案合併， | |
| # 送進下游計算的數量比使用者實際想要的多。 | |
| # 改成直接覆蓋，不合併：file_input 元件本身在「格式驗證失敗、退回 | |
| # 上傳畫面」之後不會被清空（見 on_upload_confirm 的 has_errors 分支， | |
| # outputs 沒有動 file_input），使用者原本選的檔案（含通過驗證的） | |
| # 仍留在畫面上，只要把修正後的檔案加回同一次選取、不用動已經沒問題 | |
| # 的檔案，「只補傳壞掉的那幾個」這個使用情境本來就能透過 Gradio 元件 | |
| # 自身的多檔選取狀態達成，不需要在後端另外合併——後端合併反而是這次 | |
| # bug 的成因，拿掉之後「使用者當下選了什麼，就是什麼」，語意才不會 | |
| # 跟畫面上看到的檔案清單兜不起來。 | |
| state["uploaded_files"] = saved_paths | |
| state["state"] = "FORMAT_CHECK" | |
| # 工作程序 Agent 說明開始檢查 | |
| file_list_str = "\n".join([Path(p).name for p in saved_paths]) | |
| sys_p = ( | |
| "你是重譯文本分析系統的工作程序 Agent，" | |
| "請用繁體中文簡短告知使用者已收到檔案並正在進行格式檢查，50 字以內。" | |
| ) | |
| user_p = f"已接收以下 {len(saved_paths)} 個檔案：\n{file_list_str}" | |
| try: | |
| msg = call_worker_agent(sys_p, user_p) | |
| except: | |
| msg = f"已接收 **{len(saved_paths)}** 個檔案，正在進行格式檢查……" | |
| return msg, state | |
| def run_format_check(state: dict): | |
| """ | |
| 檢查所有上傳檔案是否為 ckip_segmentation_sumin 產生的格式、檔名字首是否 | |
| 合法、以及每組是否至少各有1個檔案。 | |
| 通過 → CALCULATING；不通過 → UPLOAD_WAIT（要求重新上傳）。 | |
| 返回 (reply_text, new_state, has_errors) | |
| """ | |
| scenario = state.get("scenario", "") | |
| # 情境1/2固定二群（A/B）、情境3/4可二群或三群（A/B/C），C是否用到要等 | |
| # Metadata表單才知道，所以這裡的「允許字首」比「必要字首」寬鬆一點 | |
| allowed_prefixes = {"A", "B", "C"} if scenario in ("3", "4") else {"A", "B"} | |
| required_prefixes = {"A", "B"} | |
| failed = {} | |
| for fp in state["uploaded_files"]: | |
| name = Path(fp).name | |
| prefix = name[0].upper() if name else "" | |
| if prefix not in allowed_prefixes: | |
| allowed_str = "、".join(f"{p}_xx.txt" for p in sorted(allowed_prefixes)) | |
| failed[name] = f"檔名字首不符——本情境僅接受 {allowed_str} 格式" | |
| continue | |
| ok, reason = validate_ckip_format(Path(fp)) | |
| if not ok: | |
| failed[name] = reason | |
| if not failed: | |
| present_prefixes = {Path(fp).name[0].upper() for fp in state["uploaded_files"]} | |
| missing = required_prefixes - present_prefixes | |
| if missing: | |
| present_str = "、".join(sorted(present_prefixes)) or "無" | |
| missing_str = "、".join(sorted(missing)) | |
| msg = ( | |
| f"⚠️ 請確認 {'、'.join(sorted(required_prefixes))} 兩組皆已上傳，" | |
| f"目前偵測到：{present_str}，缺少：{missing_str}。" | |
| ) | |
| state["state"] = "UPLOAD_WAIT" | |
| return msg, state, True | |
| state["state"] = "CALCULATING" | |
| state["cleaned_files"] = state["uploaded_files"] | |
| sys_p = ( | |
| "你是重譯文本分析系統的工作程序 Agent，" | |
| "請用繁體中文告知使用者所有檔案已確認為語料淬鍊（CorpusRefinery）斷詞格式，" | |
| "即將開始計算指標，30 字以內。" | |
| ) | |
| try: | |
| msg = call_worker_agent(sys_p, "所有檔案格式驗證通過。") | |
| except: | |
| msg = "[OK] 所有檔案均符合語料淬鍊（CorpusRefinery）斷詞格式，即將開始計算文本指標……" | |
| return msg, state, False | |
| # 有檔案不符（格式或字首） | |
| fail_list = "\n".join([f"- **{fn}**：{reason}" for fn, reason in failed.items()]) | |
| sys_p = ( | |
| "你是重譯文本分析系統的工作程序 Agent，請用繁體中文告知使用者：" | |
| "部分檔案不符合語料淬鍊（CorpusRefinery）斷詞工具的輸出格式，" | |
| "必須重新使用該工具斷詞後再上傳，語氣清晰，80 字以內。" | |
| "請附上工具連結：https://github.com/minchun-git/I_CorpusRefinery" | |
| ) | |
| try: | |
| msg = call_worker_agent(sys_p, f"格式不符的檔案：\n{fail_list}") | |
| msg = msg + f"\n\n{fail_list}" | |
| except: | |
| msg = ( | |
| f"⚠️ 以下檔案不符合語料淬鍊（CorpusRefinery）斷詞格式，請重新處理後再上傳：\n\n" | |
| f"{fail_list}\n\n" | |
| "請使用 [語料淬鍊（CorpusRefinery）](https://github.com/minchun-git/I_CorpusRefinery) " | |
| "工具完成斷詞後，重新上傳檔案。" | |
| ) | |
| failed_names = set(failed.keys()) | |
| state["uploaded_files"] = [fp for fp in state["uploaded_files"] if Path(fp).name not in failed_names] | |
| state["state"] = "UPLOAD_WAIT" | |
| return msg, state, True | |
| # ── 產出打包（zip）──────────────────────────────────────────────────────────── | |
| # 使用者要把成果全部帶走，原本得點進三個結果頁各按各的下載鈕（共 15 個檔案）。 | |
| # 這裡把產出分成四包，接到左側導覽列底部的下載捷徑。 | |
| # key 同時是 zip 檔名（使用者下載後看到的名字），順序即導覽列上的顯示順序。 | |
| # | |
| # 呼叫點刻意放在 _populate_tabs（結果整理）而非運算流程：結果頁提供下載的是 | |
| # 改過名的複本（TransPrism_LLM Report_*.docx）且刻意排除原始 .txt，這些重新 | |
| # 命名就發生在 _populate_tabs 裡。在那裡打包才能保證 zip 內容跟使用者在頁面上 | |
| # 看到的檔案完全一致，也不用把「哪些檔案是給使用者的」這件事寫兩遍。 | |
| _ZIP_GROUPS = [ | |
| ("idx", "指標數據"), | |
| ("stat", "統計圖表"), | |
| ("report", "研究報告"), | |
| ("all", "全部資料"), | |
| ] | |
| def _make_result_zips(output_dir: Path, grouped: dict, allow_all: bool = True) -> dict: | |
| """把各組產出打包成 zip，回傳 {group_key: zip 路徑字串}。 | |
| grouped：{group_key: [檔案路徑, ...]}，不含 "all"（由本函式自己合併）。 | |
| 只打包真實存在的檔案；某組完全沒有檔案就不產生該包（對應的下載捷徑 | |
| 也就不會出現），例如 LLM 報告失敗時「研究報告」那包不該憑空生出來。 | |
| allow_all：呼叫端還有「必然會出現、但目前尚未跑完」的組別時傳 | |
| False，即使目前已有 ≥2 組非空也先不合併「整包」——避免「完整分析 | |
| 資料」在報告撰寫階段還沒結束前，就用 idx+stat 兩組拼出一包名不副實 | |
| 的「完整」資料（2026-08-06 踩坑，見呼叫端 report_stage_done 註解）。 | |
| """ | |
| targets = {k: [f for f in v if Path(f).exists()] for k, v in grouped.items()} | |
| # 整包 = 各組去重合併。只有一組有東西時，整包跟那一組內容完全一樣， | |
| # 多給一顆按鈕只會讓人猶豫該點哪個，這種情況不另外產生整包。 | |
| if allow_all and sum(1 for v in targets.values() if v) >= 2: | |
| seen = set() | |
| targets["all"] = [f for v in targets.values() for f in v | |
| if not (f in seen or seen.add(f))] | |
| zips = {} | |
| for key, label in _ZIP_GROUPS: | |
| files = targets.get(key) or [] | |
| if not files: | |
| continue | |
| zip_path = output_dir / f"{label}.zip" | |
| try: | |
| with zipfile.ZipFile(str(zip_path), "w", zipfile.ZIP_DEFLATED) as zf: | |
| for f in files: | |
| zf.write(str(f), arcname=Path(f).name) | |
| zips[key] = str(zip_path) | |
| except Exception: | |
| # 打包失敗不該拖垮整個分析流程——各結果頁的單項下載仍然可用 | |
| traceback.print_exc() | |
| return zips | |
| def run_computation_pipeline_streaming(state: dict): | |
| """ | |
| 執行完整計算流程（指標計算 → 統計分析 → LLM 報告）， | |
| 使用 generator 逐步 yield (progress_msg, is_final, state)。 | |
| """ | |
| output_dir = Path(state["session_dir"]) / "output" | |
| output_dir.mkdir(parents=True, exist_ok=True) | |
| results_paths = [] | |
| anal = None | |
| A = state["analysis"] # 三個子階段的即時狀態，邊跑邊寫，Canvas 內容區塊據此渲染 | |
| # ── 指標計算 ───────────────────────────────────────────────────────────── | |
| A["idx"]["status"] = "running" | |
| yield "【指標計算】正在計算文本指標……", False, state | |
| try: | |
| idx_df, xlsx_path, csv_path = run_indicator_calculation( | |
| state["cleaned_files"], output_dir, _RESOURCES | |
| ) | |
| results_paths.extend([str(xlsx_path), str(csv_path)]) | |
| # 2026-08-14：這裡顯示的「N 項語言指標」是進度列上的即時字樣，跟畫面 | |
| # 其他地方一樣要扣掉隱藏指標，不能直接數 idx_df（指標計算的原始輸出， | |
| # 仍含完整 75 欄）的欄位數，否則這裡會跟其他分頁顯示的數字對不上。 | |
| _idx_display_cols = _drop_hidden_indicators(idx_df).columns | |
| n_ind = max(len(_idx_display_cols) - sum(c in _idx_display_cols for c in ("Text","Type1","Type2")), 0) | |
| A["idx"]["status"] = "done" | |
| A["idx"]["line"] = f"{len(idx_df)} 個文本 × {n_ind} 項語言指標" | |
| yield f" [OK] 指標計算完成（{len(idx_df)} 個文本）", False, state | |
| except Exception as e: | |
| A["idx"]["status"] = "failed" | |
| A["idx"]["line"] = f"計算失敗：{e}" | |
| state["state"] = "COMPLETE" | |
| state["output_files"] = results_paths | |
| yield f"[ERROR] 指標計算失敗：{e}", True, state | |
| return | |
| # ── 統計分析 ───────────────────────────────────────────────────────────── | |
| A["stat"]["status"] = "running" | |
| yield "【統計分析】正在執行統計分析……", False, state | |
| try: | |
| anal = run_statistical_analysis( | |
| csv_path, output_dir, | |
| group_labels=state.get("group_labels", {}), | |
| individual_grouping=state.get("individual_grouping", {}), | |
| ) | |
| for key in ["desc_path","diff_path","imp_path","imp_fig_path", | |
| "box_path","dendro_path","elbow_path","cluster_fig_path", | |
| "cluster_csv_path","report_path"]: | |
| p = anal.get(key) | |
| if p and Path(str(p)).exists(): | |
| results_paths.append(str(p)) | |
| state["analysis_result"] = { | |
| k: str(v) if isinstance(v, Path) else v | |
| for k, v in anal.items() if k != "df" | |
| } | |
| A["stat"]["status"] = "done" | |
| A["stat"]["line"] = ( | |
| f"{anal['sig_count']}/{anal['total_indicators']} 個顯著指標" | |
| f"（p < {ALPHA}）、分類準確率 {anal['accuracy']:.4f}" | |
| ) | |
| yield ( | |
| f" [OK] 統計分析完成（{anal['sig_count']}/{anal['total_indicators']} 個顯著指標，" | |
| f"隨機森林準確率 {anal['accuracy']:.4f}）" | |
| ), False, state | |
| except Exception as e: | |
| A["stat"]["status"] = "failed" | |
| A["stat"]["line"] = f"分析失敗：{e}" | |
| state["state"] = "COMPLETE" | |
| state["output_files"] = results_paths | |
| yield f"[ERROR] 統計分析失敗：{e}", True, state | |
| return | |
| # ── 報告撰寫 ───────────────────────────────────────────────────────────── | |
| A["report"]["status"] = "running" | |
| yield "【報告撰寫】主 Agent 正在撰寫研究報告（約需 30-90 秒）……", False, state | |
| try: | |
| rpt = run_report_writing( | |
| scenario_key = state["scenario"], | |
| user_metadata = state.get("user_metadata", ""), | |
| user_focus = state.get("user_focus", ""), | |
| csv_path = csv_path, | |
| output_dir = output_dir, | |
| ml_summary = {"accuracy": anal.get("accuracy"), "do_eval": anal.get("do_eval")}, | |
| group_labels = state.get("group_labels", {}), | |
| ) | |
| results_paths.extend([str(rpt["docx_path"]), str(rpt["txt_path"]), str(rpt["system_prompt_path"])]) | |
| A["report"]["status"] = "done" | |
| A["report"]["line"] = "研究報告已產出" | |
| yield " [OK] 研究報告撰寫完成", False, state | |
| except Exception as e: | |
| # A1（畫面說謊）：報告失敗以前只 yield 一則 WARNING 進技術執行紀錄，然後 | |
| # 照常往下走到「全部分析完成」，步驟列還標 ✓——使用者拿到一份少了報告卻 | |
| # 顯示全部完成的結果。改成明確標記 failed，讓內容區塊與頂部步驟列都據實 | |
| # 呈現；指標與統計已完成、可下載，這點也講清楚不讓人以為全毀。 | |
| A["report"]["status"] = "failed" | |
| # 千卉 2026-07-24：加一句人話但保留原始技術訊息（診斷用，不刪） | |
| A["report"]["line"] = f"報告產出失敗，請稍後再試或聯繫管理員。（技術訊息：{e}）" | |
| yield f" [WARNING] 研究報告撰寫失敗（{e}），指標與統計結果不受影響，仍可查看與下載。", False, state | |
| # ── 完成 ───────────────────────────────────────────────────────────────── | |
| state["output_files"] = results_paths | |
| state["state"] = "COMPLETE" | |
| report_ok = A["report"]["status"] == "done" | |
| sig_info = "" | |
| if anal: | |
| sig_info = ( | |
| f"顯著指標：**{anal['sig_count']}/{anal['total_indicators']}** 個（p < {ALPHA}）。\n" | |
| f"隨機森林分類準確率：**{anal['accuracy']:.4f}**。\n" | |
| ) | |
| if report_ok: | |
| summary = ( | |
| f"**分析完成！**\n\n" | |
| f"共分析 **{len(state['cleaned_files'])}** 個文本。\n" | |
| f"{sig_info}\n" | |
| f"請點選左側導覽列查看各項結果，或使用下載捷徑取回檔案。" | |
| ) | |
| else: | |
| summary = ( | |
| f"**分析完成（研究報告未產出）。**\n\n" | |
| f"共分析 **{len(state['cleaned_files'])}** 個文本。\n" | |
| f"{sig_info}\n" | |
| f"LLM 研究報告因故未能產出，但**指標與統計結果均已完成**，" | |
| f"請點選左側導覽列查看，或使用下載捷徑取回檔案。" | |
| ) | |
| yield summary, True, state | |
| # ============================================================================ | |
| # SECTION 10: Gradio Interface (Tabbed) | |
| # ============================================================================ | |
| _EMPTY_HINT = ( | |
| '<div style="text-align:center;padding:4rem 1rem 3rem;">' | |
| '<div style="width:64px;height:64px;margin:0 auto 1.25rem;border-radius:16px;' | |
| 'background:rgba(var(--c-accent-rgb),.07);border:1px solid rgba(var(--c-accent-rgb),.20);' | |
| 'display:flex;align-items:center;justify-content:center;">' | |
| '<svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" fill="none" ' | |
| 'viewBox="0 0 24 24" stroke="var(--c-accent)" stroke-width="1.5">' | |
| '<path stroke-linecap="round" stroke-linejoin="round" ' | |
| 'd="M3.75 12h16.5m-16.5 3.75h16.5M3.75 19.5h16.5M5.625 4.5h12.75a1.875 1.875 0 010 3.75H5.625a1.875 1.875 0 010-3.75z"/>' | |
| '</svg></div>' | |
| '<p style="font-size:1rem;font-weight:600;color:var(--c-text-muted);margin:0 0 .4rem;">尚未產生資料</p>' | |
| '<p style="font-size:var(--font-size-base);color:var(--c-text-subtle);margin:0;">請先於「AI對話」完成分析流程</p>' | |
| '</div>' | |
| ) | |
| # ── SVG 圖示（Phase 8：導覽/操作圖示改用線條 icon，不再用 emoji）─────────── | |
| # 手繪 Heroicons 風格（24x24 viewBox、stroke=currentColor、圓角線頭）， | |
| # 不是逐點對照官方套件，純線條輪廓、視覺重量統一，供 _icon() 組裝使用。 | |
| _ICON_PATHS = { | |
| "folder": '<path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7z"/>', | |
| "chevron-down": '<polyline points="6,9 12,15 18,9"/>', | |
| "chevron-double-left": '<polyline points="17,6 11,12 17,18"/><polyline points="11,6 5,12 11,18"/>', | |
| "bars-3": '<line x1="4" y1="7" x2="20" y2="7"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="17" x2="20" y2="17"/>', | |
| "x": '<line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/>', | |
| "home": '<path d="M3 10.5 12 3l9 7.5"/><path d="M5 9.5V20a1 1 0 0 0 1 1h4v-6h4v6h4a1 1 0 0 0 1-1V9.5"/>', | |
| "chart-bar": '<line x1="4" y1="20" x2="20" y2="20"/><rect x="5" y="12" width="3" height="8"/><rect x="10.5" y="7" width="3" height="13"/><rect x="16" y="14" width="3" height="6"/>', | |
| "trending-up": '<polyline points="4,17 9,11 13,14 20,6"/><polyline points="14,6 20,6 20,12"/>', | |
| "document": '<path d="M7 3h7l5 5v13a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1z"/><path d="M14 3v5h5"/><line x1="8.5" y1="12" x2="15.5" y2="12"/><line x1="8.5" y1="15.5" x2="15.5" y2="15.5"/>', | |
| "plus": '<line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/>', | |
| "download": '<path d="M12 3v12"/><polyline points="7,10 12,15 17,10"/><path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"/>', | |
| "moon": '<path d="M21 12.8A8.5 8.5 0 1 1 11.2 3a6.6 6.6 0 0 0 9.8 9.8z"/>', | |
| "sun": '<circle cx="12" cy="12" r="4.2"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/>', | |
| # 2026-07-30（2-B 第 3 項）：「AI對話」改用對話氣泡圖示（跟 home.svg | |
| # 同一套 Heroicons 風格手繪，path 需與 assets/icons/chat-bubble.svg | |
| # 內容保持一致，這裡是給 _icon() 行內用法的對應版本，見該函式 docstring）。 | |
| "chat-bubble": '<path d="M4 5.5h16a1 1 0 0 1 1 1V16a1 1 0 0 1-1 1H9.5L5 21v-4H4a1 1 0 0 1-1-1V6.5a1 1 0 0 1 1-1z"/><line x1="7.5" y1="10" x2="16.5" y2="10"/><line x1="7.5" y1="13.5" x2="13" y2="13.5"/>', | |
| # 2026-08-12：導覽列最底的「使用說明」下載項目（assets/icons/book-open.svg | |
| # 的行內對應版，path 內容需與該檔一致）。 | |
| # 2026-08-12 二版：初版畫得比其他導覽圖示小一圈（實際上色像素 16×15， | |
| # 其他多是 18×16——用截圖逐一量非背景像素才看得出來，肉眼只覺得「怪怪的」）。 | |
| # 這版把 path 撐到 x 3.2–20.8、y 4.5–20，上色後約 18×16，跟 folder／ | |
| # chat-bubble／table-cells 同一個視覺量體。**新增導覽圖示時記得量一次**， | |
| # 光看 viewBox 都是 24×24 不代表畫出來一樣大。 | |
| "book-open": '<path d="M12 6.6C10.3 5.2 8.1 4.5 5.3 4.5c-.8 0-1.5.06-2.1.17v13.2c.6-.11 1.3-.17 2.1-.17 2.8 0 5 .75 6.7 2.13"/><path d="M12 6.6c1.7-1.4 3.9-2.1 6.7-2.1.8 0 1.5.06 2.1.17v13.2c-.6-.11-1.3-.17-2.1-.17-2.8 0-5 .75-6.7 2.13"/><line x1="12" y1="6.6" x2="12" y2="19.83"/>', | |
| # 2026-08-12：AI 對話氣泡頭像的白色四角星（assets/icons/ai-avatar.svg 的 | |
| # 行內對應版）。頭像的紫→藍漸層圓底畫在 CSS 的 .avatar-container 上， | |
| # 不畫在 SVG 裡——avatar_images 是 Python 端參數，同一個檔案沒辦法隨 | |
| # 明暗主題換色，交給 CSS 才吃得到 --c-accent-strong/2/3 這組 token。 | |
| # 二版（業主：兩顆都改實心、再大一點）：檔案版改成 fill 實心、不描邊， | |
| # path 一併放大（大星 x3.9–17.1／y2.2–17.2、小星 x15.3–21.5／y13.6–20.7， | |
| # 幾乎撐滿 24 的框）。這裡的行內版是 _icon() 用的，走 stroke=currentColor | |
| # 的通用寫法，path 資料與檔案保持一致即可。 | |
| "sparkle": '<path d="M10.5 2.2c.75 4.3 2.3 6.6 6.6 7.5-4.3.9-5.85 3.2-6.6 7.5-.75-4.3-2.3-6.6-6.6-7.5 4.3-.9 5.85-3.2 6.6-7.5z"/><path d="M18.4 13.6c.34 2 1.08 3.1 3.1 3.55-2.02.45-2.76 1.55-3.1 3.55-.34-2-1.08-3.1-3.1-3.55 2.02-.45 2.76-1.55 3.1-3.55z"/>', | |
| } | |
| def _icon(name: str, size: int = 20) -> str: | |
| """回傳單一 SVG 圖示字串，供 gr.HTML() 內容與 gr.Button(icon=...) 檔案外的行內用法共用。""" | |
| path = _ICON_PATHS.get(name, "") | |
| return ( | |
| f'<svg xmlns="http://www.w3.org/2000/svg" width="{size}" height="{size}" ' | |
| f'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" ' | |
| f'stroke-linecap="round" stroke-linejoin="round">{path}</svg>' | |
| ) | |
| # E4（2026-08-05）：全站樣式（原 _CUSTOM_CSS 常數，約 2165 行）已抽成獨立 | |
| # 檔案 assets/app.css，改用 app.launch(css_paths=...) 載入（Gradio 6 原生 | |
| # 支援，語意與原本 gr.Blocks(css=...) 相同，Gradio 一樣會自動幫每條選擇器 | |
| # 加上 .gradio-container .contain 前綴）。要改樣式直接改那份 .css 檔。 | |
| # Gradio 會將 gr.Blocks(css=...) 內的所有選擇器自動加上 .gradio-container .contain 前綴， | |
| # 這讓 @media 區塊內的 :root 永遠無法命中（:root 不可能是任何元素的子孫）。 | |
| # 因此系統深色模式的 token 覆寫改用 launch(head=...) 注入純 <style>，繞過該轉換。 | |
| # | |
| # 這個常數後來也收留了另一個踩到的漸層文字問題（2026-07-22 千卉實機回報， | |
| # 首頁與這裡的標題都會發生，要反白選取才看得到）：這條規則原本寫成 | |
| # 「background: linear-gradient(角度, var(--x) 0%, var(--y) 55%, var(--z) | |
| # 100%) !important;」（background 簡寫），結果瀏覽器把這個簡寫展開成多個 | |
| # 子屬性時，background-image 這個子屬性解析成空值（用瀏覽器 devtools 直接 | |
| # 讀該 CSS 規則的 CSSStyleDeclaration 證實：getPropertyValue | |
| # ('background-image') 回傳空字串）——文字本身是 transparent，底下又沒有 | |
| # 漸層可畫，視覺上等於「標題消失」。這不是 Gradio 的 css= 轉換管線造成的 | |
| # （這裡本來就是繞過該管線的 head 注入 <style>，一樣會踩到），也不是 | |
| # repaint/合成層問題（試過 transform:translateZ(0) 無效）。修法：不要用 | |
| # background 簡寫，改直接寫 background-image 這個子屬性本身，跳過簡寫展開 | |
| # 的解析路徑——已用瀏覽器 devtools 直接改這條規則驗證過，改長寫法後漸層 | |
| # 立即正常顯示。首頁 .homepage-hero h1 用的是同一種 background 簡寫寫法， | |
| # 同一批修掉（見 assets/app.css 對應區塊）。 | |
| _DARK_MODE_HEAD_CSS = """ | |
| <style> | |
| .app-header .title-line { | |
| background-image: linear-gradient(130deg, var(--c-accent-strong) 0%, var(--c-accent2) 55%, var(--c-accent3) 100%) !important; | |
| -webkit-background-clip: text !important; | |
| background-clip: text !important; | |
| } | |
| @media (prefers-color-scheme: dark) { | |
| :root:not(.light) { | |
| --c-bg: #0b1424; | |
| --c-surface: #172136; | |
| --c-surface2: #1b2740; | |
| --c-surface3: #1e293b; | |
| --c-surface3-border: #334155; | |
| --c-border: rgba(14,165,233,.11); | |
| --c-border-hover: rgba(14,165,233,.30); | |
| /* 2026-08-12：新增的線條／底色 token（說明見 assets/app.css 的 :root | |
| 區塊）。這裡是「系統深色模式」那條觸發路徑，跟 app.css 的 :root | |
| 與 .dark 合計三個宣告點，任何 token 新增都要三處一起補，漏一處 | |
| 就會在某一種深色觸發方式下退回淺色值。 */ | |
| --c-border-strong: rgba(148,163,184,.28); | |
| --c-divider: rgba(148,163,184,.18); | |
| --c-bubble-border: rgba(148,163,184,.26); | |
| --c-thead-bg: #1e2a42; | |
| --c-bubble-bg: #172136; | |
| --c-accent: #0ea5e9; | |
| --c-accent-strong: #38bdf8; | |
| --c-accent2: #818cf8; | |
| --c-accent2-strong: #a5b4fc; | |
| --c-accent3: #c084fc; | |
| --c-accent-rgb: 14,165,233; | |
| --c-accent2-rgb: 129,140,248; | |
| --c-accent3-rgb: 192,132,252; | |
| --c-bg-rgb: 9,14,26; | |
| --c-text: #e2e8f0; | |
| --c-text-soft: #cbd5e1; | |
| --c-text-muted: #94a3b8; | |
| --c-text-subtle: #475569; | |
| --c-success: #34d399; | |
| --c-success-rgb: 52,211,153; | |
| --c-warn: #fbbf24; | |
| --c-user-bg: rgba(34,197,94,.18); | |
| --c-user-border: rgba(34,197,94,.42); | |
| --c-user-text: #bbf7d0; | |
| --c-code-bg: rgba(14,165,233,.12); | |
| --c-code-text: #fbbf24; | |
| --c-input-bg: #1a2540; | |
| --c-input-border: rgba(14,165,233,.15); | |
| --c-link-hover: #7dd3fc; | |
| --c-scrollbar: #1e3a5f; | |
| --c-scrollbar-hover: #334d6e; | |
| --body-background-fill: var(--c-bg) !important; | |
| --background-fill-primary: var(--c-surface) !important; | |
| --background-fill-secondary: #080f1c !important; | |
| --block-background-fill: var(--c-surface) !important; | |
| --block-border-color: var(--c-border) !important; | |
| --border-color-primary: var(--c-border) !important; | |
| --color-accent: var(--c-accent) !important; | |
| --color-accent-soft: rgba(14,165,233,.08) !important; | |
| --body-text-color: var(--c-text) !important; | |
| --block-label-text-color: var(--c-text-muted) !important; | |
| --block-title-text-color: var(--c-text-soft) !important; | |
| --input-background-fill: var(--c-input-bg) !important; | |
| --input-border-color: var(--c-input-border) !important; | |
| --button-primary-background-fill: var(--c-accent) !important; | |
| --button-primary-text-color: #fff !important; | |
| --shadow-drop: 0 1px 3px rgba(0,0,0,.5) !important; | |
| } | |
| } | |
| </style> | |
| """ | |
| # gr.Blocks(js=...) 在此版 Gradio 實測不會執行，所有需要在頁面載入後跑的 JS | |
| # 一律改用 launch(head=...) 注入 <script>，並用 readyState 判斷是否要等 | |
| # DOMContentLoaded（head 注入時機可能早於或晚於該事件）。 | |
| _APP_HEAD_SCRIPT = """ | |
| <script> | |
| (function () { | |
| function start() { | |
| document.title = '譯彩紛呈 II 分析引擎 SpectraEngine'; | |
| function fixBubbleWrap() { | |
| /* 直接鎖定 .bubble-wrap，強制 column + flex-start */ | |
| document.querySelectorAll('.main-chat .bubble-wrap, .main-chat div[role="log"]').forEach(function(el) { | |
| el.style.setProperty('flex-direction', 'column', 'important'); | |
| el.style.setProperty('justify-content', 'flex-start', 'important'); | |
| el.style.setProperty('align-items', 'flex-start', 'important'); | |
| el.style.setProperty('align-content', 'flex-start', 'important'); | |
| /* 注意：這裡原本有 el.scrollTop = 0，是舊版「最新訊息在上」設計 | |
| 遺留下來的重設。現在訊息改成新的在下（跟一般聊天介面同方向） | |
| 後，這行會在每次訊息更新（MutationObserver 觸發）時把捲動 | |
| 位置強制拉回最上面，導致使用者永遠沒辦法捲到對話視窗最下面 | |
| 看到最新內容——已移除，讓瀏覽器保留使用者原本的捲動位置。 */ | |
| }); | |
| } | |
| /* 多次觸發確保 Svelte hydration 後生效 */ | |
| [300, 800, 1500, 3000].forEach(function(t) { setTimeout(fixBubbleWrap, t); }); | |
| /* 首頁情境卡片（Phase 8）：Gradio 沒有原生卡片元件，卡片本身是 | |
| gr.HTML() 刻的純展示內容，點擊時模擬點擊對應的隱藏版原生按鈕 | |
| （sc_btn_1..4，見 create_app() 的 .sc-bridge-btn），Python 端 | |
| on_scenario_pick 的 .click() 綁定完全不用改 */ | |
| /* 2026-07-24 修正：原本是把 listener 掛在 #homepage_scenario_grid | |
| 上、用 grid._bound 防重複，並在載入後 300/800/1500/3000ms 各綁 | |
| 一次。實測發現按「開始新分析」回到首頁後，情境卡片點了完全沒 | |
| 反應，必須重新整理頁面才能再選——因為 homepage_col 被設成 | |
| visible=False 時，Svelte 是把整個子樹「銷毀」而不是加 | |
| display:none（已用 devtools 確認：進工作區後 grid 節點直接從 | |
| DOM 消失），重新顯示時是全新節點，_bound 留在已被丟棄的舊節點 | |
| 上，而綁定只在開頁後那 3 秒內跑過，之後不會再重試。這讓 Bug1 | |
| 「選錯情境無法變更」的修復等於只有一半。 | |
| 改用事件代理掛在 document 上，跟 bindResultNav() 同一套解法： | |
| 不管卡片節點被銷毀重建幾次都不用重綁。 */ | |
| document.addEventListener('click', function (e) { | |
| var card = e.target.closest && e.target.closest('.scenario-card'); | |
| if (!card) return; | |
| var btn = document.getElementById('sc_btn_' + card.getAttribute('data-scenario')); | |
| if (btn) btn.click(); | |
| }); | |
| /* 分析運算內容區塊的「查看…」入口（2026-07-24）：純畫面操作，點了 | |
| 等同點左側對應的結果導覽項目，沿用同一套 document 事件代理——內容 | |
| 區塊是 gr.HTML，會隨 gr.update 重建，掛在 document 上不用重綁。 */ | |
| document.addEventListener('click', function (e) { | |
| var entry = e.target.closest && e.target.closest('.analysis-entry'); | |
| if (!entry) return; | |
| var navBtn = document.getElementById(entry.getAttribute('data-nav')); | |
| if (navBtn) navBtn.click(); | |
| }); | |
| /* ── 明暗切換（5-F，2026-07-24）───────────────────────────────── | |
| 點了在 <html> 加 .dark / .light class 覆蓋系統預設並記進 localStorage。 | |
| CSS token 機制：:root=淺色、.dark=深色、@media(prefers dark):root:not(.light) | |
| =系統深色。所以 html.dark→強制深、html.light→強制淺（贏過系統深色的 | |
| 媒體規則）、都沒有→跟隨系統。切換鈕在 nav-col 裡（工作區才有），但 | |
| _loadTheme 在頁面一載入就套用存好的偏好，首頁也吃得到。 */ | |
| /* 圖示 SVG 直接寫在按鈕裡（見 create_app 的 theme_toggle），顯示切換 | |
| 交給 CSS 的 #theme_toggle[data-theme-icon]，這裡不再持有 SVG 字串。 */ | |
| /* 踩坑（2026-07-24，千卉回報「我自己開的 Chrome 按了沒用，你開的可以」）： | |
| 原本只在 <html> 加 .dark/.light。但**當使用者的系統是深色時，Gradio 自己 | |
| 會偵測並在它的容器（.gradio-container／body）上加 dark class**，而 CSS 自訂 | |
| 屬性是「離內容最近的祖先勝出」——html.light 蓋不過 .gradio-container.dark， | |
| 所以點了畫面完全沒變化。我的 Playwright Chrome 是淺色系統、Gradio 不會加 | |
| 那個 class，因此自動測試一直測不出來。 | |
| 修法：偏好要同時套到 html／body／.gradio-container 三處，並在輪詢裡持續 | |
| 自我修正（Gradio 重繪時會把自己的 class 加回來）。 */ | |
| function _themeTargets() { | |
| return [document.documentElement, document.body, | |
| document.querySelector('.gradio-container')].filter(Boolean); | |
| } | |
| function _savedTheme() { | |
| try { return localStorage.getItem('spectra_theme'); } catch (err) { return null; } | |
| } | |
| /* 判斷「目前畫面實際是深是淺」。踩坑：原本沒有偏好時直接問 | |
| matchMedia(prefers-color-scheme)，但 Gradio 可能因為自己的主題設定或 | |
| 系統偵測，已經在容器上掛了 dark class——此時畫面明明是深色，matchMedia | |
| 卻可能回報淺色，於是第一次點擊算出「要轉深」，使用者看到的是「按了 | |
| 沒變化」。改成先看畫面上真的有沒有 dark class，再退回問系統。 */ | |
| function _effectiveDark() { | |
| var saved = _savedTheme(); | |
| if (saved === 'dark') return true; | |
| if (saved === 'light') return false; | |
| var applied = _themeTargets().some(function (el) { | |
| return el.classList.contains('dark'); | |
| }); | |
| if (applied) return true; | |
| return window.matchMedia('(prefers-color-scheme: dark)').matches; | |
| } | |
| /* 把使用者選的偏好壓在三個層級上；沒有偏好（跟隨系統）就完全不干預， | |
| 讓 Gradio 與媒體查詢自己決定。 */ | |
| function _applyThemeClasses() { | |
| var saved = _savedTheme(); | |
| if (!saved) return; | |
| var dark = saved === 'dark'; | |
| _themeTargets().forEach(function (el) { | |
| if (el.classList.contains('dark') !== dark) el.classList.toggle('dark', dark); | |
| if (el.classList.contains('light') === dark) el.classList.toggle('light', !dark); | |
| }); | |
| } | |
| function _applyThemeIcon() { | |
| var btn = document.getElementById('theme_toggle'); | |
| if (!btn) return; | |
| var dark = _effectiveDark(); | |
| /* 踩坑（2026-07-24，千卉回報「切換鈕不能用」）：這個函式掛在 400ms | |
| 輪詢裡，原本每次 tick 都無條件重寫 innerHTML，等於每 0.4 秒把裡面 | |
| 的 <svg> 銷毀重建一次。真人點擊是 mousedown→mouseup 兩個事件， | |
| 只要中間跨到一次重建，瀏覽器就找不到「同一個元素上按下並放開」， | |
| click 事件根本不會產生——按鈕看起來完全沒反應。程式化 .click() | |
| 不經過 mousedown/mouseup，所以自動測試一直測不出來。 | |
| 修法：狀態沒變就不要動 DOM。 */ | |
| var want = dark ? 'dark' : 'light'; | |
| if (btn.dataset.themeIcon === want) return; | |
| /* 只改屬性，圖示顯示交給 CSS（#theme_toggle[data-theme-icon]）—— | |
| DOM 結構完全不動，click 不會因為子元素被重建而消失。 */ | |
| btn.dataset.themeIcon = want; | |
| btn.setAttribute('aria-label', dark ? '切換為淺色模式' : '切換為深色模式'); | |
| } | |
| function _loadTheme() { | |
| _applyThemeClasses(); | |
| _applyThemeIcon(); | |
| } | |
| document.addEventListener('click', function (e) { | |
| if (!(e.target.closest && e.target.closest('#theme_toggle'))) return; | |
| var toDark = !_effectiveDark(); | |
| try { localStorage.setItem('spectra_theme', toDark ? 'dark' : 'light'); } catch (err) {} | |
| _applyThemeClasses(); | |
| _applyThemeIcon(); | |
| }); | |
| _loadTheme(); | |
| /* 2026-07-23：頁面切換模型。nav-col 的每個項目現在是真正的 | |
| 「頁面」——結果類項目（語言指標分析／統計比較分析／LLM輔助分析／ | |
| 技術執行紀錄）點進去時互斥顯示、收起對話欄、Canvas 佔滿寬度； | |
| 「AI對話」（原「回到上傳／表單」）點進去對話欄彈回、Canvas 顯示 | |
| 上傳/表單/運算中內容。跟 8-C/8-D 的舊行為（有資料就全部堆疊、 | |
| 使用者自己往下捲）完全不同：現在同一時間只顯示使用者當前選的 | |
| 那一頁，不管其他頁有沒有資料。 | |
| 技術做法：canvas-scroll 底下 7 個直屬區塊分成 5 組頁面歸屬 | |
| （upload_zone/metadata_zone/computing_zone 屬於 chat 頁； | |
| canvas_idx/canvas_stat/canvas_report/canvas_exec 各自獨立頁）， | |
| JS 只清除或強制 inline display:none，絕不強制顯示——Python 那層 | |
| `visible=False`（資料是否存在的判斷，見 _populate_tabs）永遠 | |
| 優先，這裡只負責「同一頁的東西藏起來，不動 Python 已經決定隱藏 | |
| 的東西」（沿用 8-E 的 style.display='' / 'none' !important | |
| 技巧）。 */ | |
| var _PAGE_OWNED_IDS = { | |
| /* 3-A／3-C（2026-07-30）：新增的研究選擇區塊（scenario_select_zone） | |
| 與上傳進度說明（upload_progress_zone）都屬於「chat」頁—— | |
| 跟 upload_zone/metadata_zone/computing_zone 一樣，是進工作區後 | |
| 對話欄仍顯示、Canvas 走流程內容的那個頁面，切到結果類頁面時要 | |
| 一併藏起來，切回 AI 對話才要出現。 */ | |
| chat: ['scenario_select_zone', 'upload_zone', 'metadata_zone', | |
| 'upload_progress_zone', 'computing_zone'], | |
| idx: ['canvas_idx'], | |
| stat: ['canvas_stat'], | |
| report: ['canvas_report'], | |
| exec: ['canvas_exec'] | |
| }; | |
| /* stat 頁沒有自己的導覽列項目——2026-07-24 拿掉「統計比較分析」 | |
| 那層 Accordion 後，四個子頁是平列的獨立項目，active 要落在使用者 | |
| 實際點的那一個，不能靠 page 名稱反查。因此 applyActivePage() 多收 | |
| 一個 navId 參數，並把結果記在 .main-layout-row 的 data-nav 上： | |
| 每 400ms 跑一次的 _reapplyActivePage() 不帶 navId，靠這個記錄才 | |
| 不會每個 tick 把 active 清掉。 */ | |
| var _PAGE_NAV_IDS = { | |
| chat: 'nav_top_btn', idx: 'nav_idx_btn', | |
| report: 'nav_report_btn', exec: 'nav_exec_btn' | |
| }; | |
| var _ALL_NAV_IDS = ['nav_top_btn', 'nav_idx_btn', 'nav_report_btn', 'nav_exec_btn', | |
| 'nav_stat_sub_0', 'nav_stat_sub_1', 'nav_stat_sub_2', 'nav_stat_sub_3']; | |
| function applyActivePage(page, navId) { | |
| var mainRow = document.querySelector('.main-layout-row'); | |
| if (!mainRow) return; | |
| mainRow.setAttribute('data-page', page); | |
| mainRow.classList.toggle('chat-collapsed', page !== 'chat'); | |
| if (navId) mainRow.setAttribute('data-nav', navId); | |
| else if (_PAGE_NAV_IDS[page]) mainRow.setAttribute('data-nav', _PAGE_NAV_IDS[page]); | |
| var activeId = mainRow.getAttribute('data-nav'); | |
| Object.keys(_PAGE_OWNED_IDS).forEach(function (key) { | |
| _PAGE_OWNED_IDS[key].forEach(function (id) { | |
| var el = document.getElementById(id); | |
| if (!el) return; | |
| if (key === page) { | |
| el.style.removeProperty('display'); | |
| } else { | |
| el.style.setProperty('display', 'none', 'important'); | |
| } | |
| }); | |
| }); | |
| _ALL_NAV_IDS.forEach(function (id) { | |
| var btn = document.getElementById(id); | |
| if (btn) btn.classList.toggle('active', id === activeId); | |
| }); | |
| } | |
| function _initActivePageIfNeeded() { | |
| var mainRow = document.querySelector('.main-layout-row'); | |
| if (!mainRow || mainRow.dataset.pageInit) return; | |
| mainRow.dataset.pageInit = '1'; | |
| applyActivePage('chat'); | |
| } | |
| /* 左側結果導覽（result_nav_col）——純粹是「切換頁面＋捲動＋切換 | |
| 巢狀子分頁」的畫面操作，不牽動任何後端狀態，所以這幾顆按鈕在 | |
| Python 端完全沒有掛 .click()，改用這裡的事件代理直接處理，不用 | |
| 走 Gradio queue 來回。 | |
| 注意：result_nav_col 建構時是 visible=False（跟 sc_btn_1..4 | |
| 一度踩過的坑同一類），如果比照 bindScenarioCards() 用 | |
| setTimeout 抓固定時間點的按鈕，情境選定前按鈕還沒掛載，之後 | |
| 也不會再重試。改用事件代理綁在 document 這個從頁面一開始就 | |
| 存在的祖先節點上，不管 result_nav_col 什麼時候才真正掛載進 | |
| DOM，點擊都能正確代理處理，不用重試機制。 */ | |
| function bindResultNav() { | |
| if (window._resultNavBound) return; | |
| window._resultNavBound = true; | |
| function scrollToId(id) { | |
| var el = document.getElementById(id); | |
| if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' }); | |
| } | |
| document.addEventListener('click', function (e) { | |
| if (e.target.closest('#nav_top_btn')) { | |
| closeMobileDrawerIfOpen(); | |
| applyActivePage('chat'); | |
| var scrollBox = document.querySelector('.canvas-scroll'); | |
| if (scrollBox) scrollBox.scrollTo({ top: 0, behavior: 'smooth' }); | |
| return; | |
| } | |
| if (e.target.closest('#nav_idx_btn')) { | |
| closeMobileDrawerIfOpen(); applyActivePage('idx'); scrollToId('canvas_idx'); return; | |
| } | |
| if (e.target.closest('#nav_report_btn')) { | |
| closeMobileDrawerIfOpen(); applyActivePage('report'); scrollToId('canvas_report'); return; | |
| } | |
| if (e.target.closest('#nav_exec_btn')) { | |
| closeMobileDrawerIfOpen(); applyActivePage('exec'); scrollToId('canvas_exec'); return; | |
| } | |
| /* 2026-07-24：原本這裡還有一支處理「統計比較分析」Accordion | |
| 標題列點擊的分支，該層已移除，四個子項目自己就是入口。 */ | |
| for (var i = 0; i < 4; i++) { | |
| if (e.target.closest('#nav_stat_sub_' + i)) { | |
| closeMobileDrawerIfOpen(); | |
| applyActivePage('stat', 'nav_stat_sub_' + i); | |
| scrollToId('canvas_stat'); | |
| /* 注意：這版 Gradio 的巢狀分頁 DOM 結構是 | |
| .tabs > .tab-wrapper > .tab-container（兩個， | |
| 一個 .visually-hidden 是窄螢幕/溢出選單用的隱藏 | |
| 版本，另一個才是實際看得到、要點的），不是常見 | |
| 印象中的 .tab-nav——原本沿用 .tab-nav 的選擇器 | |
| （包含 CSS 那條，見上面 #canvas_stat 註解）在 | |
| 這版完全不會命中，只是沒人發現因為 Gradio 自己的 | |
| 預設樣式已經看起來夠好。這裡用 devtools 逐層 | |
| 確認過實際 class 後才改對。 */ | |
| var tabButtons = document.querySelectorAll( | |
| '#canvas_stat .tabs > .tab-wrapper > .tab-container:not(.visually-hidden) > button' | |
| ); | |
| if (tabButtons[i]) tabButtons[i].click(); | |
| return; | |
| } | |
| } | |
| }); | |
| } | |
| bindResultNav(); | |
| /* Phase 8-E：桌面收合 icon bar／手機漢堡抽屜。跟 bindResultNav() | |
| 同一套「事件代理綁在 document」手法，理由相同——nav-col 建構時 | |
| 在 visible=False 的 workspace_row 裡，情境選定前不存在，不能用 | |
| setTimeout 抓固定時間點的元素。 */ | |
| function setNavCollapsed(collapsed) { | |
| var navCol = document.querySelector('.nav-col'); | |
| if (!navCol) return; | |
| navCol.classList.toggle('collapsed', collapsed); | |
| var toggleBtn = document.getElementById('nav_collapse_toggle'); | |
| if (toggleBtn) { | |
| toggleBtn.setAttribute('aria-label', collapsed ? '展開導覽列' : '收合導覽列'); | |
| toggleBtn.setAttribute('aria-expanded', String(!collapsed)); | |
| } | |
| /* 收合後按鈕文字用 font-size:0 隱藏（見 CSS），accessible name | |
| 會跟著消失，改用 aria-label 補回原始文字，展開時移除即可 | |
| 讓瀏覽器繼續用按鈕原生文字內容當 accessible name。 */ | |
| ['reset_btn', 'nav_top_btn', 'nav_idx_btn', 'nav_report_btn', | |
| 'nav_guide_btn'].forEach(function (id) { | |
| /* elem_id 在 gr.Button 上這版 Gradio 是直接寫在 <button> | |
| 標籤本身，不是外層 wrapper div（跟 result_nav_col 那組 | |
| 純 gr.HTML() 按鈕、或 nav_top_btn 用 elem_id 做 CSS | |
| 選擇器點擊代理時假設的「wrapper 帶 id」不是同一種 | |
| 結構）——用 devtools 量過 outerHTML 才發現，兩者都要 | |
| 兼容。 */ | |
| var el = document.getElementById(id); | |
| var btn = el && (el.tagName === 'BUTTON' ? el : el.querySelector('button')); | |
| if (!btn) return; | |
| if (collapsed) { | |
| if (!btn.dataset.navLabel) btn.dataset.navLabel = btn.textContent.trim(); | |
| btn.setAttribute('aria-label', btn.dataset.navLabel); | |
| } else { | |
| btn.removeAttribute('aria-label'); | |
| } | |
| }); | |
| try { localStorage.setItem('spectra_nav_collapsed', collapsed ? '1' : '0'); } catch (err) {} | |
| } | |
| function setMobileDrawer(open) { | |
| var navCol = document.querySelector('.nav-col'); | |
| var backdrop = document.getElementById('nav_backdrop'); | |
| var toggle = document.getElementById('mobile_nav_toggle'); | |
| if (navCol) navCol.classList.toggle('mobile-open', open); | |
| if (backdrop) backdrop.classList.toggle('visible', open); | |
| if (toggle) toggle.setAttribute('aria-expanded', String(open)); | |
| /* 2026-07-30（2-B 驗收時發現，跟 3 行品牌字標同一批修）： | |
| mobile_nav_toggle 是 position:fixed 浮動在 top:14/left:14 | |
| 的獨立按鈕，跟 nav-col 沒有 DOM 父子關係（見上方註解：它是 | |
| workspace_row 外層的常駐元件）。抽屜展開後 nav-col 也在同一 | |
| 個左上角（position:fixed，padding 1.1rem），z-index 45 的 | |
| 漢堡鈕疊在 z-index 40 的抽屜上面，正好蓋住品牌字標。品牌字標 | |
| 還是單行「SpectraEngine」時，這顆鈕只蓋到文字最前面一小角， | |
| 不明顯；這輪改 3 行之後蓋住的範圍變成兩整行，肉眼就看得出來。 | |
| 既然抽屜已經有自己的關閉鈕（nav_drawer_close），展開時這顆 | |
| 浮動漢堡鈕本來就沒有作用，直接藏起來最單純。 */ | |
| if (toggle) toggle.classList.toggle('mobile-nav-toggle--hidden', open); | |
| } | |
| function closeMobileDrawerIfOpen() { | |
| var navCol = document.querySelector('.nav-col'); | |
| if (navCol && navCol.classList.contains('mobile-open')) setMobileDrawer(false); | |
| } | |
| function bindNavControls() { | |
| if (window._navControlsBound) return; | |
| window._navControlsBound = true; | |
| document.addEventListener('click', function (e) { | |
| if (e.target.closest('#nav_collapse_toggle')) { | |
| var navCol = document.querySelector('.nav-col'); | |
| setNavCollapsed(!(navCol && navCol.classList.contains('collapsed'))); | |
| return; | |
| } | |
| if (e.target.closest('#mobile_nav_toggle')) { | |
| var navColEl = document.querySelector('.nav-col'); | |
| setMobileDrawer(!(navColEl && navColEl.classList.contains('mobile-open'))); | |
| return; | |
| } | |
| if (e.target.closest('#nav_drawer_close') || e.target.closest('#nav_backdrop')) { | |
| setMobileDrawer(false); | |
| return; | |
| } | |
| if (e.target.closest('#reset_btn')) { | |
| /* 2026-07-24：確認框改成全螢幕置中 modal 後，原本 | |
| 「收合狀態下先自動展開 nav-col，免得彈窗擠在 60px | |
| 窄欄裡」的變通已無必要，移除；手機抽屜仍要收起， | |
| 否則對話框會被抽屜遮住一半。 | |
| 這裡不 preventDefault/stopPropagation，事件照常 | |
| 冒泡給 Gradio 原生 .click()。 */ | |
| closeMobileDrawerIfOpen(); | |
| } | |
| /* 點遮罩空白處＝取消（面板本身的點擊不算），沿用抽屜遮罩 | |
| 同一套互動慣例 */ | |
| if (e.target.id === 'reset_confirm_overlay') { | |
| var cancelBtn = document.getElementById('reset_cancel_btn'); | |
| if (cancelBtn) cancelBtn.click(); | |
| return; | |
| } | |
| if (e.target.closest('#reset_confirm_btn')) { | |
| /* 2026-07-23：真的按下「確定重新開始」才重置頁面切換 | |
| 狀態回 chat（不能在 #reset_btn 那支就做，那個只是 | |
| 打開確認彈窗，使用者還可能按取消）。.main-layout-row | |
| 這個 DOM 節點在 Gradio 重置流程中不會被銷毀重建， | |
| data-page/chat-collapsed 這些 attribute 不會自動 | |
| 清掉，若不主動重置，下一次選新情境時畫面會直接卡在 | |
| 上一次分析結束前所在的那一頁。 */ | |
| applyActivePage('chat'); | |
| } | |
| }); | |
| document.addEventListener('keydown', function (e) { | |
| if (e.key !== 'Escape') return; | |
| /* 對話框開著時 Esc 優先關對話框（modal 慣例：只關最上層的 | |
| 那一個），沒開著才輪到手機抽屜 */ | |
| /* 不能用 offsetParent !== null 判斷可見：position:fixed 的 | |
| 元素 offsetParent 永遠是 null，會判成「沒開」，Esc 就永遠 | |
| 關不到對話框（改 modal 前這個寫法是對的，改成 fixed 之後 | |
| 就不成立了）。改讀 computed display。 */ | |
| var overlay = document.getElementById('reset_confirm_overlay'); | |
| if (overlay && getComputedStyle(overlay).display !== 'none') { | |
| var cancelBtn = document.getElementById('reset_cancel_btn'); | |
| if (cancelBtn) cancelBtn.click(); | |
| return; | |
| } | |
| closeMobileDrawerIfOpen(); | |
| }); | |
| } | |
| bindNavControls(); | |
| /* 持續監聽 DOM 變化（每次訊息更新後重設） */ | |
| var mo = new MutationObserver(function(mutations) { | |
| var needsFix = mutations.some(function(m) { | |
| return m.target.closest && m.target.closest('.main-chat'); | |
| }); | |
| if (needsFix) { fixBubbleWrap(); } | |
| }); | |
| setTimeout(function() { | |
| var root = document.querySelector('.main-chat'); | |
| if (root) mo.observe(root, { childList: true, subtree: true, attributes: true }); | |
| }, 500); | |
| /* 新區塊（上傳卡片、metadata 表單）出現時自動捲入視野；消失時捲回頂部， | |
| 避免使用者看不到畫面下方新出現的操作元件（如上傳按鈕）而以為系統卡住。 | |
| 長時間運算期間 Gradio 會頻繁重新渲染畫面，元件的可見性有時會出現 | |
| 一瞬間的閃爍（不是真正的顯示/隱藏切換），若照單全收會反覆觸發 | |
| scrollIntoView，跟使用者手動往下捲動互相打架，感覺畫面卡住好久—— | |
| 改成要連續兩次（800ms）偵測到同一個新狀態才真的觸發捲動 */ | |
| var _zoneWasVisible = {}; | |
| var _zonePendingState = {}; | |
| var _zonePendingCount = {}; | |
| function _watchZone(id) { | |
| var zone = document.getElementById(id); | |
| var visible = !!(zone && zone.offsetParent !== null); | |
| var was = _zoneWasVisible[id] || false; | |
| if (visible === was) { _zonePendingCount[id] = 0; return; } | |
| if (_zonePendingState[id] === visible) { | |
| _zonePendingCount[id] = (_zonePendingCount[id] || 0) + 1; | |
| } else { | |
| _zonePendingState[id] = visible; | |
| _zonePendingCount[id] = 1; | |
| } | |
| if (_zonePendingCount[id] < 2) return; | |
| if (visible) { | |
| // 2026-08-15（業主回報「格式驗證通過切到語料說明時，畫面 | |
| // 會往下移動一下」）：behavior:'smooth' 會讓捲動變成一段 | |
| // 看得見的滑動過程，使用者感受到的正是這段移動動畫本身， | |
| // 不是位置算錯。改成 'auto'（瀏覽器原生瞬間跳轉），新區塊 | |
| // 一出現畫面就直接定在該處，不再有可感知的移動過程。 | |
| zone.scrollIntoView({ behavior: 'auto', block: 'center' }); | |
| } else { | |
| window.scrollTo({ top: 0, behavior: 'smooth' }); | |
| } | |
| _zoneWasVisible[id] = visible; | |
| _zonePendingCount[id] = 0; | |
| } | |
| /* exec-log 已改成不設內部 max-height／overflow，只靠頁面本身捲動 | |
| （見陷阱：內部捲動 + 頁面捲動疊在一起看起來像兩條捲軸），所以不再 | |
| 需要 el.scrollTop 這種內部捲到底部的邏輯，避免又跟使用者手動捲動 | |
| 搶主導權（同樣的教訓見對話視窗捲不到底那次的修正）。 */ | |
| /* Phase 8-E：mobile_nav_toggle（手機漢堡鈕）是放在 workspace_row | |
| 外層、頁面一開始就存在的元件，但它只有在 nav-col 真正掛載 | |
| （情境已選定）時才該顯示；同理，桌面收合狀態要在 nav-col 剛 | |
| 掛載那一刻套用 localStorage 記住的值，早一步做（例如 DOMContentLoaded | |
| 當下）nav-col 根本還不存在，套不上。都改成搭這裡既有的 | |
| setInterval 一起輪詢，不額外開新計時器。 */ | |
| function _syncMobileHamburger() { | |
| /* 2026-07-23：改成切換 wrapper（#mobile_nav_toggle_wrap／ | |
| #nav_backdrop_wrap）本身的 display，不是內層按鈕/遮罩自己 | |
| 的 style——wrapper 預設 display:none 才能真正零高度（見 | |
| CSS 對應註解），內層元素桌面/手機斷點的顯示邏輯完全不變， | |
| 這裡只負責「nav-col 存不存在」這個外層開關。 */ | |
| var navColExists = !!document.querySelector('.nav-col'); | |
| var toggleWrap = document.getElementById('mobile_nav_toggle_wrap'); | |
| var backdropWrap = document.getElementById('nav_backdrop_wrap'); | |
| if (toggleWrap) toggleWrap.style.display = navColExists ? 'block' : 'none'; | |
| if (backdropWrap) backdropWrap.style.display = navColExists ? 'block' : 'none'; | |
| } | |
| function _initNavCollapseIfNeeded() { | |
| var navCol = document.querySelector('.nav-col'); | |
| if (!navCol || navCol.dataset.navInit) return; | |
| navCol.dataset.navInit = '1'; | |
| var saved; | |
| try { saved = localStorage.getItem('spectra_nav_collapsed'); } catch (err) { saved = null; } | |
| if (saved === '1') setNavCollapsed(true); | |
| } | |
| function _reapplyActivePage() { | |
| /* 踩坑（2026-07-23，全新踩坑類別）：applyActivePage() 用 | |
| el.style.setProperty('display','none','important') 隱藏 | |
| 非當前頁區塊，理論上一次設定就該一直有效。但實測發現運算 | |
| 完成後（_populate_tabs 把 canvas_idx_col 等設 visible=True） | |
| canvas_idx/canvas_stat 又跑出來混進 chat 頁——代表 Gradio | |
| 的 Svelte reactivity 在元件的 visible prop 改變時，會自己 | |
| 整個重寫該元素的 style 屬性（不是「疊加」而是「覆蓋」）， | |
| 把我手動加的 inline !important 一併洗掉。這跟先前踩過的 | |
| 「Python 的 gr.update 值改變時整個重新渲染」是同一個大類， | |
| 只是這次連 inline style 都被連帶清空，不只是 min-width 那種 | |
| 單一屬性優先權的問題。修法沿用這個檔案一貫的解法：不奢求 | |
| 一次設定永久有效，改成跟 _watchZone／_syncMobileHamburger | |
| 一樣搭這裡的輪詢，每 400ms 重新套用一次目前頁面對應的 | |
| 隱藏規則，Gradio 重新渲染蓋掉的話下一個 tick 就修回來。 */ | |
| var mainRow = document.querySelector('.main-layout-row'); | |
| var page = mainRow && mainRow.getAttribute('data-page'); | |
| if (page) applyActivePage(page); | |
| } | |
| var _unloadGuardOn = false; | |
| function _onBeforeUnload(e) { | |
| e.preventDefault(); | |
| e.returnValue = ''; /* 舊版瀏覽器需要，值本身不會被顯示 */ | |
| return ''; | |
| } | |
| function _syncUnloadGuard() { | |
| /* 防手滑：目前完全沒有存檔機制（.spectra 存檔／讀檔是後續工作）， | |
| 分析跑到一半或跑完還沒下載時關掉分頁／按重新整理，整段工作直接 | |
| 歸零。這裡在工作區顯示期間掛上 beforeunload，讓瀏覽器跳原生 | |
| 確認框。判斷依據是工作區有沒有真的顯示在畫面上——還停在首頁 | |
| 沒選情境時不攔，避免只是進來看看的人也被問一次；按「開始新 | |
| 分析」重置回首頁後也會自動解除。 | |
| 兩個瀏覽器層面的限制（不是實作沒做好）：①使用者必須先與頁面 | |
| 互動過，這個確認框才會出現，這是各家瀏覽器防濫用的共同規範 | |
| ②提示文字一律由瀏覽器決定，無法自訂成「您的分析尚未下載」。 */ | |
| var row = document.querySelector('.main-layout-row'); | |
| var active = !!(row && row.offsetParent !== null); | |
| if (active === _unloadGuardOn) return; | |
| _unloadGuardOn = active; | |
| if (active) window.addEventListener('beforeunload', _onBeforeUnload); | |
| else window.removeEventListener('beforeunload', _onBeforeUnload); | |
| } | |
| setInterval(function () { | |
| _watchZone('upload_zone'); | |
| _watchZone('metadata_zone'); | |
| _syncMobileHamburger(); | |
| _initNavCollapseIfNeeded(); | |
| _initActivePageIfNeeded(); | |
| _reapplyActivePage(); | |
| _syncUnloadGuard(); | |
| /* Gradio 重繪時會把自己偵測系統主題加的 dark class 加回容器上， | |
| 這裡持續把使用者選的偏好壓回去（跟本檔其他「輪詢自我修正」同一套 | |
| 解法）。theme_toggle 在工作區才掛載，圖示也一併補正。 */ | |
| _applyThemeClasses(); | |
| _applyThemeIcon(); | |
| }, 400); | |
| } | |
| if (document.readyState === 'loading') { | |
| window.addEventListener('DOMContentLoaded', start); | |
| } else { | |
| start(); | |
| } | |
| })(); | |
| </script> | |
| """ | |
| _APP_HEAD = _DARK_MODE_HEAD_CSS + _APP_HEAD_SCRIPT | |
| def _build_scenario_cards_html(grid_id: str) -> str: | |
| """4 張研究情境卡片，資料來源 SCENARIOS 字典。 | |
| 2026-07-30（3-A）：從 _build_homepage_html() 抽出成獨立函式——情境選擇 | |
| 從首頁搬進工作區的「研究選擇」步驟後，卡片只剩工作區這一處在用，但 | |
| 仍抽成函式而不是內嵌寫死在呼叫處，避免將來又要多處共用時複製兩份 | |
| SCENARIOS 的渲染邏輯。grid_id 由呼叫端指定（原本首頁用的是 | |
| homepage_scenario_grid，這個 id 目前沒有任何 CSS/JS 依賴它，純粹方便 | |
| 肉眼辨識用途），卡片點擊事件是 document 層級的事件代理（見 | |
| _APP_HEAD_SCRIPT 的 .scenario-card 監聽器，認的是 class 不是這個 id）， | |
| grid_id 換了完全不影響既有綁定。 """ | |
| cards = [] | |
| for n in ("1", "2", "3", "4"): | |
| sc = SCENARIOS[n] | |
| cards.append( | |
| '<div class="scenario-card" role="listitem" tabindex="0" ' | |
| f'data-scenario="{n}">' | |
| f'<span class="sc-index en">{n.zfill(2)}</span>' | |
| '<span class="sc-body">' | |
| f'<span class="sc-title">{sc["title"]}</span>' | |
| f'<span class="sc-desc">{sc["desc"]}</span>' | |
| '</span></div>' | |
| ) | |
| return f'<div class="scenario-grid" id="{grid_id}" role="list">{"".join(cards)}</div>' | |
| def _build_homepage_hero_html() -> str: | |
| """首頁介紹區塊上半部（品牌名稱＋標題＋描述）。 | |
| 2026-07-30（Phase 9）：業主指定情境卡片搬去工作區的「研究選擇」步驟 | |
| （見 3-A、_build_scenario_cards_html），首頁只留介紹文字與一顆 | |
| 「開始研究分析」按鈕（1-B，見 create_app() 的 start_analysis_btn）。 | |
| 按鈕是真正的 gr.Button（需要接 Python 事件，不能用 gr.HTML() 刻）， | |
| 因此原本一整塊首頁 HTML 拆成 hero／footer 兩段（見下面 | |
| _build_homepage_footer_html），讓 create_app() 能把 gr.Button 插在 | |
| 兩段中間；兩段共用同一個 .homepage-col 外層，改由 create_app() 用 | |
| gr.Column(elem_classes=["homepage-col"]) 包起來，不是這裡自己吐一個 | |
| 大 <div>。 | |
| """ | |
| return ( | |
| '<div class="homepage-hero">' | |
| # 1-C：業主指定移除第一行「重譯文本量化分析平台」（原本的 | |
| # <span class="kicker">），下方直接從系列名稱開始。 | |
| '<p class="series-name">譯彩紛呈：重譯文本分析系統</p>' | |
| '<p class="subtitle en">TransPrism: An Analytical Framework for Retranslation</p>' | |
| '<h1><span class="en">II</span> 分析引擎 <span class="en">SpectraEngine</span></h1>' | |
| # 1-F：描述文字砍掉原本結尾「請先選擇最符合您研究設計的比較情境：」 | |
| # ——情境選擇已搬去工作區，首頁不用再提示選情境。 | |
| f'<p class="lede">上傳已斷詞的譯本文本，系統將自動計算 <span class="en">{TOTAL_VISIBLE_INDICATORS}</span> 項語言指標並進行統計分析，' | |
| '協助您完成重譯研究的量化論證。</p>' | |
| '</div>' | |
| ) | |
| def _build_homepage_footer_html() -> str: | |
| """首頁介紹區塊下半部（讀取進度佔位連結＋底部說明），接在 1-B 的 | |
| 「開始研究分析」按鈕下方。見 _build_homepage_hero_html 上方說明。 | |
| """ | |
| return ( | |
| '<div class="homepage-secondary">' | |
| f'<span class="placeholder-link">{_icon("folder", 16)}讀取進度（功能開發中）</span>' | |
| '</div>' | |
| # 1-G：底部說明文字改版，原文「選擇任一情境即開始分析」也不再適用 | |
| # （首頁不選情境了）。 | |
| '<p class="homepage-footnote">分析過程需要運算等待時間，建議一次執行一項分析，以確保運算速度。</p>' | |
| ) | |
| def create_app(): | |
| with gr.Blocks( | |
| title="譯彩紛呈 II 分析引擎 SpectraEngine", | |
| theme=gr.themes.Base( | |
| primary_hue=gr.themes.colors.sky, | |
| secondary_hue=gr.themes.colors.indigo, | |
| neutral_hue=gr.themes.colors.slate, | |
| font=[gr.themes.GoogleFont("Inter"), "Noto Sans TC", "system-ui", "sans-serif"], | |
| font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "monospace"], | |
| ), | |
| # E4：css= 移到 app.launch(css_paths=...)（見該處），Blocks 建構子不再帶樣式。 | |
| # 注意：gr.Blocks(js=...) 在目前這版 Gradio 實測不會執行（已用 | |
| # document.querySelectorAll('.main-chat .bubble-wrap')[0].getAttribute('style') | |
| # 驗證從未被寫入過 inline style），因此所有互動用 JS 都改放到 | |
| # launch(head=...) 注入的 <script>（見 _APP_HEAD_SCRIPT）。 | |
| ) as demo: | |
| session_state = gr.State(None) | |
| # ══════════════════════════════════════════════════════════════ | |
| # 主頁（Phase 8-C：不再包在 gr.Tabs()/gr.Tab() 裡，外層分頁列已拿掉） | |
| # ══════════════════════════════════════════════════════════════ | |
| # Phase 9（2026-07-30）：首頁只留品牌介紹＋一顆「開始研究分析」入口 | |
| # 按鈕（1-A／1-B）。原本住這裡的 4 張情境卡片搬去工作區的「研究 | |
| # 選擇」步驟（見下方 scenario_select_row、3-A），首頁不再展示情境 | |
| # 內容，也不需要在首頁解析使用者選了哪個情境。 | |
| # .homepage-col 這個外層改由這裡的 gr.Column 承接（elem_classes）， | |
| # 不是 _build_homepage_hero_html()/_build_homepage_footer_html() | |
| # 自己吐一個 <div class="homepage-col">——因為「開始研究分析」是 | |
| # 真正的 gr.Button（需要接 Python 事件），必須插在 hero／footer | |
| # 兩段 HTML 中間，同一個 Column 才能讓三者視覺上仍是同一塊。 | |
| with gr.Column(visible=True) as homepage_col: | |
| with gr.Column(elem_classes=["homepage-col"]): | |
| gr.HTML(_build_homepage_hero_html()) | |
| # 1-B：真正的 gr.Button，不是首頁卡片那種「HTML＋隱藏按鈕 | |
| # JS 橋接」手法——那個手法存在的理由是 Gradio 沒有原生卡片 | |
| # 元件，單顆按鈕不需要繞這一圈，直接掛 .click() 即可（見下方 | |
| # start_analysis_btn.click() wiring）。 | |
| start_analysis_btn = gr.Button( | |
| "開始研究分析", elem_id="start_analysis_btn", variant="primary", | |
| ) | |
| gr.HTML(_build_homepage_footer_html()) | |
| # 3-A：研究選擇用的 4 顆隱藏版情境按鈕（.sc-bridge-btn，JS 橋接 | |
| # 目標，見 _APP_HEAD_SCRIPT 的 document click 代理）。原本住在 | |
| # homepage_col 裡，首頁改版後 homepage_col 進工作區時會被設成 | |
| # visible=False——Gradio 對「visible=False 的容器」是整段從 DOM | |
| # 卸載（不是只用 CSS 隱藏），這幾顆按鈕會跟著被卸載，JS 就再也點 | |
| # 不到卡片。搬到這裡（跟 mobile_nav_toggle_html／nav_backdrop_html | |
| # 同一層級：最外層、一開始就 visible=True、建構時就掛進 DOM 的 | |
| # 位置），不管 homepage_col 或 workspace_row 怎麼切換可見性，這 | |
| # 幾顆按鈕永遠掛在 DOM 上，JS 永遠找得到可點的對象。.click() 綁定 | |
| # 邏輯（on_scenario_pick）完全不用改。 | |
| sc_btn_1 = gr.Button("1 人工翻譯 vs 機器翻譯", variant="secondary", | |
| elem_id="sc_btn_1", elem_classes=["sc-bridge-btn"]) | |
| sc_btn_2 = gr.Button("2 全譯 vs 編譯（節譯、改寫）", variant="secondary", | |
| elem_id="sc_btn_2", elem_classes=["sc-bridge-btn"]) | |
| sc_btn_3 = gr.Button("3 不同譯者的同期譯本", variant="secondary", | |
| elem_id="sc_btn_3", elem_classes=["sc-bridge-btn"]) | |
| sc_btn_4 = gr.Button("4 不同時期人工譯本", variant="secondary", | |
| elem_id="sc_btn_4", elem_classes=["sc-bridge-btn"]) | |
| # Phase 8-E：手機漢堡開關＋抽屜背景遮罩。跟 sc_btn_1..4 同一類坑： | |
| # 建構時 visible=False 的容器整段不掛載進 DOM，而這兩個元件要在 | |
| # nav-col（在 workspace_row 裡，情境選定前不存在）尚未掛載前就能 | |
| # 被點到，所以放在最外層、一開始就 visible=True 的位置；CSS 預設 | |
| # display:none，只在手機寬度且 workspace 啟用時由 JS 顯示（見 | |
| # _APP_HEAD_SCRIPT 的 _syncMobileHamburger()），桌面寬度／首頁 | |
| # 狀態下完全不佔版面也不可點。 | |
| # 2026-07-23 踩坑（分兩輪才修對）：這兩個元件的實際內容 | |
| # （#mobile_nav_toggle／#nav_backdrop）本身雖然預設 display:none， | |
| # 但那只是隱藏「內層」元素——Gradio 自動包在 gr.HTML() 外面的 | |
| # wrapper（.block）沒有被一併處理，仍然佔用版面高度＋跟相鄰元件的 | |
| # flex gap，變成看得到但摸不著原因的空白區塊（千卉截圖回報頂部/ | |
| # 底部有大片空白才發現）。 | |
| # 第一輪嘗試：elem_classes 掛 nav-html-bridge，CSS 設 | |
| # `display:contents`，理論上該讓 wrapper 不產生盒模型——實測 | |
| # 沒用，逐一 display:none 排查後才發現：這版 Gradio 的 | |
| # elem_classes 會同時蓋在外層 .block wrapper 跟內層 .prose | |
| # wrapper 兩層 div 上（這個踩坑本檔 8-B 就記過一次「.block.<class> | |
| # 跟.prose.<class>」的雙重疊加，這次加新元件時忘了套用同一個 | |
| # 教訓），兩層 display:contents 疊加後不知為何沒有真的清零 | |
| # flex gap 佔用的空間。 | |
| # 第二輪改用最直接可靠的做法：wrapper 用 elem_id 直接鎖定， | |
| # 預設寫死 display:none（一般 block 元素包一個 display:none 的 | |
| # 子元素，天生就是零高度，不用依賴 display:contents 這種比較 | |
| # 少人踩過的屬性），JS 改成切換這個 wrapper 本身的 display， | |
| # 內層 #mobile_nav_toggle／#nav_backdrop 自己的 CSS（桌面/手機 | |
| # 斷點判斷）完全不用動，兩層互不干擾。 | |
| mobile_nav_toggle_html = gr.HTML( | |
| f'<button type="button" id="mobile_nav_toggle" class="mobile-nav-toggle" ' | |
| f'aria-label="開啟導覽選單" aria-expanded="false">{_icon("bars-3", 22)}</button>', | |
| elem_id="mobile_nav_toggle_wrap", | |
| ) | |
| nav_backdrop_html = gr.HTML( | |
| '<div id="nav_backdrop" class="nav-backdrop"></div>', | |
| elem_id="nav_backdrop_wrap", | |
| ) | |
| # 「回首頁」確認對話框（2026-07-24 改成置中 modal，2026-07-30 | |
| # 隨按鈕改名一併調整文案）：原本是 | |
| # nav-col 裡的一張內嵌卡片，擠在 220px 窄欄裡，收合成 60px icon bar | |
| # 時更不成人形（8-E 當時還為此加了「收合狀態下點重置先自動展開 | |
| # nav-col」的變通，改成 modal 後那個理由消失，該變通已一併移除）。 | |
| # 放在 workspace_row 外層是必要的，不是順手：nav-col 在手機寬度是 | |
| # position:fixed＋transform 的抽屜，而被 transform 的祖先會讓子孫的 | |
| # position:fixed 改以該祖先為定位基準，對話框會被關在抽屜裡而不是 | |
| # 覆蓋整個視窗。 | |
| # 2026-07-30（2-B 第 4 項）：按鈕改名「回首頁」後，文案也要跟著改， | |
| # 但行為完全沒變——千卉已確認回首頁一樣是整個重置（進度會遺失）， | |
| # 不是單純切換畫面，所以文案刻意保留「遺失進度」這句，避免使用者 | |
| # 誤以為只是導覽切換。elem_id（reset_confirm_overlay/panel/ | |
| # reset_cancel_btn/reset_confirm_btn）與 on_reset_clear_workspace／ | |
| # on_reset_confirm 的 wiring 完全不動，純文案異動。 | |
| with gr.Column(visible=False, elem_id="reset_confirm_overlay", | |
| elem_classes=["reset-confirm-overlay"]) as reset_confirm_row: | |
| with gr.Column(elem_id="reset_confirm_panel", elem_classes=["reset-confirm-panel"]): | |
| gr.Markdown("確定要回首頁嗎？目前進度將會遺失，需要重新開始整個分析流程。", | |
| elem_classes=["reset-confirm-text"]) | |
| with gr.Row(elem_classes=["reset-confirm-actions"]): | |
| reset_cancel_btn = gr.Button("取消", elem_id="reset_cancel_btn", | |
| scale=1, variant="secondary") | |
| reset_confirm_btn = gr.Button("確定回首頁", elem_id="reset_confirm_btn", | |
| scale=1, variant="primary") | |
| # 2026-08-26：「關於」面板，跟上面 reset_confirm_row 同一個理由放在 | |
| # workspace_row 外層（避免被手機版 nav-col 的 transform 抽屜關住）， | |
| # 沿用同一套 overlay 機制（elem_classes 掛 reset-confirm-overlay 觸發 | |
| # 既有的置中 + display:none 控制邏輯），面板本身另開較寬的 | |
| # about-panel class（見 assets/app.css 註解）。 | |
| with gr.Column(visible=False, elem_id="about_overlay", | |
| elem_classes=["reset-confirm-overlay"]) as about_overlay: | |
| with gr.Column(elem_id="about_panel", elem_classes=["about-panel"]): | |
| gr.Markdown(ABOUT_CONTENT_MD) | |
| with gr.Row(elem_classes=["about-close-row"]): | |
| about_close_btn = gr.Button("關閉", elem_id="about_close_btn", | |
| scale=0, variant="secondary") | |
| # Phase 8-B：三欄式工作區——nav-col（窄，導覽/重置）＋chat-col | |
| # （對話視窗＋輸入框，獨立捲動）＋canvas-col（步驟列＋上傳/表單/ | |
| # 執行紀錄，獨立捲動）。手機寬度見 CSS 的 media query 改上下堆疊。 | |
| with gr.Row(elem_classes=["main-layout-row"], visible=False) as workspace_row: | |
| with gr.Column(scale=2, min_width=200, elem_classes=["nav-col"]) as nav_col: | |
| # 2026-07-30（2-B 第 1／2 項全面改版）：nav-col 這輪拆成三段式 | |
| # 結構——①這裡（頂端品牌列，固定不捲動）②下面 | |
| # nav_items_scroll（中段，flex:1 自己 overflow-y:auto）③欄位 | |
| # 收尾處的 nav_bottom_toolbar（底部工具列，固定不捲動）。原因 | |
| # 見 .nav-col CSS 規則本身的長註解：明暗切換／收合鈕這輪要移到 | |
| # 「置底＋置右」，如果整欄還是共用同一個捲動容器，內容一多， | |
| # 底部工具列就會被捲出視窗——跟 Bug 4-B（下載捷徑那組被摺行 | |
| # 裁掉）是同一類「flex 子項可以無限長大、把重要項目擠出可視 | |
| # 範圍」的問題，只是換了個受害者，這次拆結構從根本避免。 | |
| # 2026-07-31（Batch E 第 2 項）：品牌字標從 3 行改 2 行（業主 | |
| # 改主意，見 .nav-brand CSS 的同批註解），字級統一改 1.1rem； | |
| # 手機抽屜關閉鈕（nav_drawer_close）跟品牌字標一起留在這個 | |
| # 固定頂端列，抽屜開關本來就该在使用者一打開就摸得到的 | |
| # 地方，不用跟著挪。 | |
| gr.HTML( | |
| '<div class="nav-top-row">' | |
| '<div class="nav-brand">' | |
| '<span class="nav-brand-line1">譯彩紛呈 <span class="en">II</span> 分析引擎</span>' | |
| '<span class="nav-brand-line2 en">SpectraEngine</span>' | |
| '</div>' | |
| '</div>' | |
| '<div class="nav-drawer-close-row">' | |
| f'<button type="button" id="nav_drawer_close" class="nav-drawer-close" ' | |
| f'aria-label="關閉導覽選單">{_icon("x", 18)}</button>' | |
| '</div>', | |
| elem_id="nav_top_html", | |
| ) | |
| # 中段可捲動區：回首頁連結、結果導覽全部包進來，只有這個 | |
| # Column 自己 overflow-y:auto（見 .nav-items-scroll CSS）， | |
| # 不影響上下兩段固定區塊。 | |
| with gr.Column(elem_classes=["nav-items-scroll"]) as nav_items_scroll: | |
| # 「回首頁」連結與其確認彈窗：換情境／回首頁都走這一套共用 | |
| # 機制。情境是封閉式按鈕選擇，不透過對話框打字，所以「換 | |
| # 情境」也統一走這顆按鈕，不恢復文字解析路徑。 | |
| # 2026-07-30（2-B 第 3 項）：原本是置中的「開始新分析」大按鈕， | |
| # 千卉這輪改成置左的「回首頁」文字連結，圖示也跟著換成 home | |
| # （對話氣泡讓給下面的「AI對話」，語意上 home 更適合「回首頁」）。 | |
| # elem_id="reset_btn" 不動，後面所有 .click() wiring／收合狀態 | |
| # 選擇器都靠這個 id，行為完全不變（見 on_reset_confirm 附近 | |
| # 註解：仍然是整個重置，不是單純換頁面）。 | |
| reset_btn = gr.Button( | |
| "回首頁", icon=str(BASE_DIR / "assets" / "icons" / "home.svg"), | |
| elem_id="reset_btn", elem_classes=["reset-btn"], variant="secondary", | |
| ) | |
| # Phase 8-D：結果導覽——情境選定後顯示，讓使用者不用手動 | |
| # 往下捲一大段就能跳到 Canvas 對應區塊。這幾顆按鈕刻意不接 | |
| # Python .click()：純粹是「捲動＋切換巢狀子分頁」的畫面 | |
| # 操作，不牽動任何後端狀態，改用跟首頁情境卡片同一套手法 | |
| # （_APP_HEAD_SCRIPT 的 JS 監聽），完全不用走 Gradio queue | |
| # 來回，反應更快。（下載捷徑當初規劃留到下一輪補，已於 | |
| # 2026-07-24 補齊，見下方 nav_dl_* 那四顆。） | |
| with gr.Column(visible=False, elem_id="result_nav_col", elem_classes=["result-nav"]) as result_nav_col: | |
| # 2026-07-23 改名「AI對話」＋改變功能定位：原本純粹是 | |
| # 「捲回 Canvas 最上面」的畫面操作，現在身兼「切回流程頁」 | |
| # 的角色（見 applyActivePage() JS）——流程進行中（上傳/ | |
| # 表單/運算中）對話欄常駐顯示，點結果類項目才收起；點 | |
| # 這顆按鈕會讓對話欄彈回來。 | |
| # 2026-07-30（2-B 第 3 項）：圖示改用對話氣泡（chat-bubble. | |
| # svg），語意上比原本借用的 home 圖示更準確——home 這次讓給 | |
| # 上面新改名的「回首頁」連結，兩顆圖示不再共用同一個。 | |
| nav_top_btn = gr.Button( | |
| "AI對話", icon=str(BASE_DIR / "assets" / "icons" / "chat-bubble.svg"), | |
| elem_id="nav_top_btn", elem_classes=["result-nav-btn"], variant="secondary", | |
| ) | |
| # 2026-07-24（A2）：結果類導覽項目預設 interactive=False。 | |
| # 運算完成前它們就已經隨 result_nav_col 顯示，但對應的 | |
| # canvas_*_col 還是 Gradio visible=False，點下去只會切到一片 | |
| # 空白（JS 只能清 display，蓋不過 Python 的 visible=False）。 | |
| # 改成先 disable（灰階），由 _populate_tabs 依各結果是否真的 | |
| # 產出來逐一啟用——LLM 輔助分析尤其：報告失敗時它維持灰的， | |
| # 剛好是失敗訊號的第二道確認。AI 對話與技術執行紀錄不在此列 | |
| # （前者永遠可回、後者從第一秒就有內容）。 | |
| nav_idx_btn = gr.Button( | |
| "語言指標分析", icon=str(BASE_DIR / "assets" / "icons" / "trending-up.svg"), | |
| elem_id="nav_idx_btn", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False, | |
| ) | |
| # 2026-07-24 千卉決定：拿掉「統計比較分析」這層 Accordion | |
| # （標題文字與收合效果都不要），四個子頁直接跟其他導覽項目 | |
| # 平列。它原本存在的理由（2026-07-23 改 open=True 時的說法） | |
| # 是「讓人看得出底下還有四個子頁面」，但四頁攤開後這層標題 | |
| # 只剩下多一列文字跟一個不會有人去點的箭頭。 | |
| # 副作用：原本「統計比較分析」那一列兼任 stat 頁的 active | |
| # 指示器，拿掉後改由使用者實際點的那個子項目自己標 active， | |
| # 見 _APP_HEAD_SCRIPT 的 applyActivePage()。 | |
| nav_stat_sub_0 = gr.Button( | |
| "敘述統計", icon=str(BASE_DIR / "assets" / "icons" / "table-cells.svg"), | |
| elem_id="nav_stat_sub_0", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False) | |
| nav_stat_sub_1 = gr.Button( | |
| "差異性分析", icon=str(BASE_DIR / "assets" / "icons" / "scale.svg"), | |
| elem_id="nav_stat_sub_1", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False) | |
| nav_stat_sub_2 = gr.Button( | |
| "監督式學習", icon=str(BASE_DIR / "assets" / "icons" / "academic-cap.svg"), | |
| elem_id="nav_stat_sub_2", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False) | |
| nav_stat_sub_3 = gr.Button( | |
| "非監督式學習", icon=str(BASE_DIR / "assets" / "icons" / "squares-2x2.svg"), | |
| elem_id="nav_stat_sub_3", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False) | |
| nav_report_btn = gr.Button( | |
| "LLM輔助分析", icon=str(BASE_DIR / "assets" / "icons" / "document.svg"), | |
| elem_id="nav_report_btn", elem_classes=["result-nav-btn"], variant="secondary", | |
| interactive=False, | |
| ) | |
| # ── 下載捷徑（2026-07-24）──────────────────────────── | |
| # 上面四項是「去看結果」，這四顆是「把結果帶走」，性質 | |
| # 不同所以用分隔線隔開。原本使用者要拿到全部產出得點進 | |
| # 三個結果頁各按各的下載鈕（共 15 個檔案），這裡各打成 | |
| # 一包 zip。內容為空的那幾包不會產生，對應按鈕就不出現 | |
| # （例如 LLM 報告失敗時「下載研究報告」不會亮出來）。 | |
| # 分隔線與四顆按鈕整組包進 nav_dl_group：沒有任何一包 zip | |
| # 時整組隱藏（否則分隔線會孤零零留在畫面上，還跟下面技術 | |
| # 執行紀錄的分隔線貼在一起變兩條）；有 zip 時整組顯示， | |
| # 個別按鈕再依自己那包是否存在決定。群組與個別可見性都由 | |
| # _populate_tabs 設定。 | |
| with gr.Column(visible=False, elem_id="nav_dl_group", | |
| elem_classes=["result-nav-dl-group"]) as nav_dl_group: | |
| gr.HTML('<div class="result-nav-divider"></div>') | |
| nav_dl_idx_btn = gr.DownloadButton( | |
| "下載指標數據", icon=str(BASE_DIR / "assets" / "icons" / "download.svg"), | |
| visible=False, elem_id="nav_dl_idx_btn", | |
| elem_classes=["result-nav-btn", "result-nav-dl"], variant="secondary", | |
| ) | |
| nav_dl_stat_btn = gr.DownloadButton( | |
| "下載統計圖表", icon=str(BASE_DIR / "assets" / "icons" / "download.svg"), | |
| visible=False, elem_id="nav_dl_stat_btn", | |
| elem_classes=["result-nav-btn", "result-nav-dl"], variant="secondary", | |
| ) | |
| nav_dl_report_btn = gr.DownloadButton( | |
| "下載研究報告", icon=str(BASE_DIR / "assets" / "icons" / "download.svg"), | |
| visible=False, elem_id="nav_dl_report_btn", | |
| elem_classes=["result-nav-btn", "result-nav-dl"], variant="secondary", | |
| ) | |
| nav_dl_all_btn = gr.DownloadButton( | |
| "下載全部資料", icon=str(BASE_DIR / "assets" / "icons" / "download.svg"), | |
| visible=False, elem_id="nav_dl_all_btn", | |
| elem_classes=["result-nav-btn", "result-nav-dl"], variant="secondary", | |
| ) | |
| # 2026-07-23：技術執行紀錄從手風琴轉正成獨立頁面（原本 | |
| # exec_log_accordion 在 canvas-col 底部，現在跟其他三個 | |
| # 結果頁同一種待遇）。用分隔線隔開，視覺上表達「低優先度 | |
| # 診斷工具，不是主要分析結果」，避免跟上面三項混為一談。 | |
| gr.HTML('<div class="result-nav-divider"></div>') | |
| nav_exec_btn = gr.Button( | |
| "技術執行紀錄", icon=str(BASE_DIR / "assets" / "icons" / "folder.svg"), | |
| elem_id="nav_exec_btn", elem_classes=["result-nav-btn", "result-nav-btn--muted"], | |
| variant="secondary", | |
| ) | |
| # ── 使用說明（2026-08-12，業主要求）────────────────── | |
| # 刻意放在 result_nav_col **外面**、nav_items_scroll 的最後 | |
| # 一項：說明文件跟分析進度無關，選研究情境前也該拿得到。選情境 | |
| # 後它自然落在「技術執行紀錄」下方，就是業主要的「最後一個 | |
| # 項目下方」。 | |
| # 它是下載動作不是頁面，所以跟 nav_dl_* 四顆一樣，不接 | |
| # applyActivePage()、不進 _APP_HEAD_SCRIPT 的 _ALL_NAV_IDS， | |
| # 否則點下去會把 active 狀態從當前結果頁搶走。 | |
| # 樣式提醒：導覽項目的視覺掛在 `#result_nav_col | |
| # .result-nav-btn` 或 `#reset_btn` 這種帶 id 的選擇器上 | |
| # （純 class 贏不過 Gradio 的 button.svelte-xxx.secondary）， | |
| # 這顆住在 result_nav_col 外面，已比照 #reset_btn 把 | |
| # #nav_guide_btn 加進 app.css 那幾組選擇器清單。 | |
| gr.HTML('<div class="result-nav-divider"></div>') | |
| nav_guide_btn = gr.DownloadButton( | |
| "使用說明", value=str(BASE_DIR / "使用說明.docx"), | |
| icon=str(BASE_DIR / "assets" / "icons" / "book-open.svg"), | |
| elem_id="nav_guide_btn", | |
| elem_classes=["result-nav-btn", "result-nav-btn--muted"], | |
| variant="secondary", | |
| ) | |
| # ── 關於（2026-08-26，業主要求）─────────────────────── | |
| # 跟使用說明同一顆待遇：住在 result_nav_col 外面，同一份 | |
| # elem_classes（沿用 #nav_guide_btn 那組樣式選擇器，見 | |
| # assets/app.css）。這顆是彈窗不是下載，用一般 gr.Button | |
| # 搭配下面的 about_overlay 面板，toggle 顯示/隱藏。 | |
| about_btn = gr.Button( | |
| "關於", icon=str(BASE_DIR / "assets" / "icons" / "info-circle.svg"), | |
| elem_id="nav_about_btn", | |
| elem_classes=["result-nav-btn", "result-nav-btn--muted"], | |
| variant="secondary", | |
| ) | |
| # ↑ nav_items_scroll 到此結束（中段可捲動區）。 | |
| # 底部工具列（固定，不隨中段捲動）：明暗切換／收合鈕原本在頂端 | |
| # 品牌列右側，這輪千卉指定移到「置底＋置右」，上方用一條水平線 | |
| # （border-top，見 .nav-bottom-toolbar CSS）分隔。兩顆按鈕本身 | |
| # 的 id／aria-label／內部 SVG 完全沿用，只是搬了位置，_APP_HEAD_ | |
| # SCRIPT 裡靠 #theme_toggle／#nav_collapse_toggle 這兩個 id 找 | |
| # 元件的事件代理（document 層級）完全不受影響，不用動 JS。 | |
| gr.HTML( | |
| '<div class="nav-bottom-toolbar">' | |
| f'<button type="button" id="theme_toggle" class="nav-icon-btn" ' | |
| f'aria-label="切換為深色模式">' | |
| f'<span class="ico-moon">{_icon("moon", 18)}</span>' | |
| f'<span class="ico-sun">{_icon("sun", 18)}</span>' | |
| f'</button>' | |
| f'<button type="button" id="nav_collapse_toggle" class="nav-collapse-toggle" ' | |
| f'aria-label="收合導覽列" aria-expanded="true">{_icon("chevron-double-left", 18)}</button>' | |
| '</div>', | |
| elem_id="nav_bottom_toolbar", | |
| ) | |
| with gr.Column(scale=3, min_width=280, elem_classes=["chat-col"]): | |
| # main-chat 用 flex:1 1 auto 吃掉 chat-col 的全部高度（見該 | |
| # CSS 規則），下面 chat_upload_col 這輪起改成 visible=False | |
| # 常駐隱藏，對話視窗因此自然吃滿整欄高度，不用另外調 flex 比例。 | |
| # 2026-08-12（業主要求）：AI 訊息左邊加頭像，讓「這句是 AI 在 | |
| # 講話」一眼可辨。用 Gradio 原生 avatar_images，不自己造 JS | |
| # 橋接；tuple 第一格是使用者頭像，給 None 代表只有 AI 這一側 | |
| # 顯示。SVG 檔只有白色四角星，紫→藍漸層圓底畫在 CSS 的 | |
| # .avatar-container（見 app.css「AI 頭像」區塊的理由說明）。 | |
| chatbot = gr.Chatbot( | |
| show_label=False, | |
| elem_classes=["main-chat"], | |
| avatar_images=(None, str(BASE_DIR / "assets" / "icons" / "ai-avatar.svg")), | |
| ) | |
| # 2026-07-30（2-C 第 5 項）：對話輸入框這輪改成常駐隱藏 | |
| # （visible=False，不刪元件——降低風險，也保留 Phase 8 這段 | |
| # 沿革紀錄）。它本來就是「沒有真正作用的佔位元件」（見下方 | |
| # 沿革說明），千卉這輪決定乾脆藏起來，讓對話視窗吃滿整欄。 | |
| # 用 visible=False 而不是拿掉整個 gr.Column：component 仍在 | |
| # DOM 樹裡建構好，之後若要復活只要把這裡改回 True，不用重寫 | |
| # wiring；而且這是「建構當下就設定好、從未被事件動態切換過」 | |
| # 的靜態可見性，不吃本檔開頭記錄的 Gradio 6 容器卸載地雷 | |
| # （那個地雷只在「同一批訊息裡跟祖先可見性一起翻轉」時才會 | |
| # 咬人，這裡從頭到尾都是 False，沒有翻轉可言）。 | |
| # ── 以下是 Phase 8 沿革（千卉實測後回頭調整）：對話輸入框當時 | |
| # 改回「常駐顯示、不負責上傳」——業主原本設計就是用拖曳／點擊 | |
| # 上傳的卡片（見下方 upload_row），對話框目前也沒有其他打字 | |
| # 用途（全站掃過沒有任何地方會解析使用者自由輸入文字），當時 | |
| # 只留著當畫面元素，不接 sources=["upload"]，避免顯示附加 | |
| # 檔案的迴紋針卻沒有作用。（原本的 chat_upload.submit() 轉接 | |
| # 函式 on_chat_upload_submit 已於 2026-07-24 當死碼移除，之後 | |
| # 要復活直接重接 .submit() 即可，見該處註解。） | |
| with gr.Column(visible=False, elem_id="chat_upload_zone", elem_classes=["upload-zone-plain"]) as chat_upload_col: | |
| chat_upload = gr.MultimodalTextbox( | |
| file_types=[".txt"], | |
| sources=[], | |
| placeholder="對話輸入框（功能開發中）", | |
| show_label=False, | |
| lines=3, | |
| submit_btn=False, # 2026-07-24 千卉：拿掉送出鈕 | |
| interactive=True, # 2026-07-24 千卉：要可打字（雖然目前不接任何作用） | |
| ) | |
| with gr.Column(scale=7, min_width=380, elem_classes=["canvas-col"]): | |
| # 頂部步驟列＋情境標籤：原本在全頁最上方（首頁也會看到）， | |
| # Phase 8-B 搬進 Canvas 內部，只在 workspace_row 顯示後 | |
| # 才出現，首頁不再看到。 | |
| # 注意：這裡不能靠 app_header_html 自己 position:sticky | |
| # 達到「頂部固定」——它的直接 wrapper（Gradio 自動包的 | |
| # .block）高度只比它自己的內容高一點點，sticky 的可移動 | |
| # 範圍被那層 wrapper 框住，捲動一小段（wrapper 多出來的 | |
| # 高度）後就整個跟著捲走，不會真的貼在 Canvas 頂端不動 | |
| # （已實測踩坑）。正確做法：步驟列留在捲動區外面（跟著 | |
| # canvas-col 本身固定不動），下面另外包一層 | |
| # canvas-scroll 才是真正會捲動的區域，兩者高度各自獨立。 | |
| # 2-A（2026-07-30）：elem_id 給頂部列的 wrapper，讓 CSS 能鎖定它 | |
| # 只在「AI 對話」頁顯示（見 5d 區塊 .main-layout-row:not(...) | |
| # 那條規則），其他結果頁（語言指標分析／敘述統計／…／技術 | |
| # 執行紀錄）都不顯示。用 elem_id 而不是 elem_classes： | |
| # elem_classes 會同時蓋在外層 .block 與內層 .prose 兩層 div | |
| # 上（本檔多處踩過這坑），id 選擇器鎖 wrapper 比較可靠。 | |
| app_header_html = gr.HTML(_build_header_html(), elem_id="app_header_wrap") | |
| with gr.Column(elem_classes=["canvas-scroll"]): | |
| # 3-A（2026-07-30）：研究選擇區塊，工作區的第 1 步。點選 | |
| # 首頁「開始研究分析」進工作區後預設顯示（見 | |
| # on_start_analysis_show），使用者選定情境後隱藏、換 | |
| # upload_row 出現（見 on_scenario_pick 的延伸，同一份 | |
| # yield 裡把這裡設 visible=False）。卡片內容沿用 | |
| # _build_scenario_cards_html()，跟原本首頁那 4 張卡片 | |
| # 是同一份 SCENARIOS 資料，不重複刻兩份。視覺樣式沿用 | |
| # upload-zone/metadata-zone 同一批扁平卡片語彙（見 | |
| # .scenario-select-zone CSS）。 | |
| with gr.Column(visible=True, elem_id="scenario_select_zone", | |
| elem_classes=["scenario-select-zone"]) as scenario_select_row: | |
| # 標題＋說明文字沿用 metadata_row 那則 Markdown 的寫法 | |
| # （純 "### 標題\n說明文字"，不套 elem_classes），維持 | |
| # 同一批「Canvas 操作區塊」卡片的既有排版慣例。 | |
| gr.Markdown("### 情境選擇\n請選擇最符合您針對同一原文的重譯研究設計的比較情境，選定後將進入下一步「文本上傳」。") | |
| gr.HTML(_build_scenario_cards_html("workspace_scenario_grid")) | |
| # Phase 8（千卉實測後回頭調整）：這張卡片改回正式使用 | |
| # 中的上傳入口（拖曳／點擊上傳），符合業主原本設計； | |
| # Phase 7 曾經把它永久隱藏、改用對話框上傳，這次反 | |
| # 過來。程式邏輯完全沒動，只是把可見性開關從 | |
| # chat_upload_col 換回這裡。 | |
| with gr.Column(visible=False, elem_id="upload_zone", elem_classes=["upload-zone"]) as upload_row: | |
| upload_hint_md = gr.Markdown(value="", elem_classes=["upload-hint"]) | |
| file_input = gr.File( | |
| show_label=False, | |
| file_types=[".txt"], file_count="multiple", | |
| ) | |
| # 2026-07-24 千卉：拿掉「取消」。它的行為是把整個上傳區 | |
| # 隱藏＋清空檔案，使用者按了之後畫面沒有任何上傳入口、 | |
| # 等於把自己鎖在流程外，沒有實際用途。要換檔案直接在檔案 | |
| # 清單上逐一按 ×，要重來走「開始新分析」。 | |
| # 2026-07-31（Batch G 第 1 項）：業主要求在「確認上傳」 | |
| # 左邊加一顆「重新選擇研究情境」返回鈕，讓使用者選錯情境 | |
| # 後不必整個「開始新分析」重來一次。次要樣式 | |
| # （variant="secondary"），視覺權重刻意低於「確認上傳」， | |
| # 不跟主要動作搶注意力。wiring 見下方 back_to_scenario_btn | |
| # .click()。 | |
| with gr.Row(elem_classes=["upload-actions"]): | |
| back_to_scenario_btn = gr.Button("重新選擇研究情境", scale=1, variant="secondary") | |
| upload_btn = gr.Button("確認上傳", scale=1, variant="primary") | |
| # 3-C（2026-07-30）：文本上傳工作進度說明，比照「分析運算」 | |
| # 內容區塊（_build_analysis_html／computing_html）的做法， | |
| # 業主回報「上傳過程都一片白，只在對話視窗出現文字氣泡， | |
| # 用戶會不知道發生什麼事」。獨立於 upload_row 之外（不是 | |
| # 巢狀在裡面）：on_upload_confirm 的第一步就會把 upload_row | |
| # 設 visible=False（避免遮罩擋住操作），若進度說明巢狀在 | |
| # upload_row 裡會跟著一起被藏起來，等於沒有解決業主回報的 | |
| # 問題。空字串＝上傳尚未開始、不顯示，跟 computing_html | |
| # 同一種語意，見 _build_upload_html。 | |
| upload_progress_html = gr.HTML(value="", elem_id="upload_progress_zone") | |
| # ── 語料 Metadata 說明表單（上傳後、分析前）─────── | |
| with gr.Column(visible=False, elem_id="metadata_zone", elem_classes=["metadata-zone"]) as metadata_row: | |
| gr.Markdown("### 📑 語料說明\n請於正式分析前說明語料來源、範圍與比較結構，將寫入研究報告。") | |
| gr.Markdown("**原文資訊**") | |
| with gr.Row(): | |
| meta_title = gr.Textbox(label="原文標題", scale=2) | |
| meta_author = gr.Textbox(label="作者", scale=2) | |
| meta_lang = gr.Textbox(label="語言", scale=1) | |
| with gr.Row(): | |
| meta_pubyear = gr.Textbox(label="出版年", scale=1) | |
| meta_version = gr.Textbox(label="版本", scale=2) | |
| # 比較結構（僅情境 3、4 需要；情境 1、2 固定二群） | |
| # 2026-08-12：原本用 gr.Group，Gradio 會給它一條藍色 | |
| # 標題橫幅＋外框，跟旁邊「原文資訊」「群組層資訊」那種 | |
| # 純文字小標題長得完全不同（業主截圖標了要拿掉）。改用 | |
| # gr.Column：一來沒有那層裝飾，二來本專案早有定論—— | |
| # 這版 Gradio 的 gr.Group 設 visible=False 只清空內容、 | |
| # 容器本身仍是 display:flex，會留下一塊空色塊，所有 | |
| # 「要切換 visible 的容器」一律用 gr.Column（Phase 6 踩過）。 | |
| with gr.Column(visible=False, elem_id="meta_compare_group") as meta_compare_group: | |
| gr.Markdown("**比較結構**") | |
| with gr.Row(): | |
| meta_ngroups = gr.Radio( | |
| ["二群", "三群"], label="群組數量", value="二群", scale=1, | |
| ) | |
| meta_method = gr.Radio( | |
| ["群組間比較", "個體間比較"], label="比較方式", | |
| value="群組間比較", scale=1, | |
| ) | |
| # 2026-08-15（業主回報「填了語料說明但沒生效」，追查後 | |
| # 發現根因）：原本這裡是 gr.Dataframe（row_count= | |
| # (1,"dynamic")），實測編輯過一格之後，其他格子會完全 | |
| # 點不進去、無法再編輯（這版 Gradio 的 Dataframe 儲存格 | |
| # 編輯器有這個問題，換 row_count 寫法／col_count 寫法都 | |
| # 一樣）。改成三組獨立的 Textbox（最多支援三群，對應 | |
| # meta_ngroups 的「二群／三群」上限），完全避開有問題的 | |
| # Dataframe 儲存格編輯機制。三組固定宣告、依實際偵測到 | |
| # 的分組數量切換顯示（見 _show_metadata_form），標題會 | |
| # 動態顯示該組實際的分組代碼（例如「組別 A」），讓使用者 | |
| # 清楚知道自己在填哪一組——這點也順便修掉另一個問題： | |
| # 原本 Dataframe 版本的資料送進 LLM 時沒有明確標示 | |
| # 「這行屬於哪個分組代碼」，LLM 曾經因此把 A／B 的標籤 | |
| # 講反。 | |
| gr.Markdown("**群組層資訊**（共通屬性）") | |
| _META_GROUP_FIELD_LABELS = ["群組標籤", "翻譯類型", "翻譯方向", "譯者背景", "目標讀者"] | |
| meta_group_cols = [] | |
| meta_group_heads = [] | |
| meta_group_fields = [] # [[label,type,dir,bg,aud], ...] 每組一份 | |
| for _gi in range(3): | |
| with gr.Column(visible=(_gi < 2)) as _gcol: | |
| _ghead = gr.Markdown(f"組別 {_gi + 1}") | |
| with gr.Row(): | |
| _f_label = gr.Textbox(label="群組標籤", scale=1) | |
| _f_type = gr.Textbox(label="翻譯類型", scale=1) | |
| _f_dir = gr.Textbox(label="翻譯方向", scale=1) | |
| with gr.Row(): | |
| _f_bg = gr.Textbox(label="譯者背景", scale=1) | |
| _f_aud = gr.Textbox(label="目標讀者", scale=1) | |
| meta_group_cols.append(_gcol) | |
| meta_group_heads.append(_ghead) | |
| meta_group_fields.append([_f_label, _f_type, _f_dir, _f_bg, _f_aud]) | |
| # 2026-08-15（業主要求）：拿掉「後編輯程度」欄位，業主 | |
| # 認為用不到。欄位索引 0（檔案）／1（譯者／系統名稱） | |
| # 沒有移動，_extract_individual_grouping() 讀的就是 | |
| # 這兩欄，拿掉的是原本索引 4 的欄位，不用連動改那邊。 | |
| gr.Markdown("**個體層資訊**（每個譯本／檔案）") | |
| meta_indiv_df = gr.Dataframe( | |
| headers=["檔案", "譯者／系統名稱", "出版年", "譯者母語", "重譯序位"], | |
| datatype=["str"] * 5, | |
| col_count=(5, "fixed"), | |
| row_count=(1, "dynamic"), | |
| interactive=True, | |
| label="個體層", | |
| ) | |
| gr.Markdown( | |
| "以下資訊會寫入報告開頭，您也可以先略過（略過後這次分析將不會用到這些補充說明）", | |
| elem_classes=["upload-hint"], | |
| ) | |
| with gr.Row(elem_classes=["upload-actions"]): | |
| meta_cancel_btn = gr.Button("略過", scale=1, variant="secondary") | |
| meta_confirm_btn = gr.Button("確認並開始分析", scale=2, variant="primary") | |
| # 「分析運算」內容區塊（2026-07-24 由 Phase 8-D 的單行運算中 | |
| # 提示擴充而來）：運算中顯示三個子階段進度＋轉圈動畫，運算後 | |
| # 變成分段摘要（標題＋狀態＋一句結論＋查看入口）。空字串＝運算 | |
| # 尚未開始、不顯示，見 _build_analysis_html／_computing_update。 | |
| computing_html = gr.HTML(value="", elem_id="computing_zone") | |
| # Phase 8-C：結果內容從 tab2/tab3/tab6（原本 gr.Tabs() 分頁頁面）搬進 | |
| # Canvas，改成三個互斥可見性的 gr.Column，取代整頁分頁切換。三塊 | |
| # 目前皆用同一組 visible=True/False 語意（見 _populate_tabs 的 | |
| # index 20-22），分析完成後會同時顯示、垂直堆疊；哪個結果先出現在 | |
| # 畫面上由使用者往下捲決定，nav-col 的「結果導覽」切換是 8-D 待辦。 | |
| with gr.Column(visible=False, elem_id="canvas_idx", elem_classes=["canvas-result"]) as canvas_idx_col: | |
| tab_idx_md = gr.Markdown(_EMPTY_HINT) | |
| tab_idx_df = gr.Dataframe( | |
| label="指標計算結果", | |
| interactive=False, visible=False, | |
| ) | |
| # 2026-08-12（業主要求）：下載區塊移回表格下方。Phase 5 | |
| # 當初刻意把它移到頁面頂部，但其他五個結果頁（敘述統計／ | |
| # 差異性分析／監督式／非監督式／LLM 輔助分析）的下載都在 | |
| # 最下面，只有這一頁不同調。這是純宣告順序調整， | |
| # _TAB_IDX（見下方）本來就是 md/df/file 的位置對應， | |
| # 跟畫面順序無關，不用動。 | |
| tab_idx_file = gr.File( | |
| label="下載語言指標分析", | |
| file_count="multiple", interactive=False, visible=False, | |
| ) | |
| with gr.Column(visible=False, elem_id="canvas_stat", elem_classes=["canvas-result"]) as canvas_stat_col: | |
| with gr.Tabs(): | |
| # 子分頁 1：敘述統計 | |
| with gr.Tab("1. 敘述統計"): | |
| tab_desc_md = gr.Markdown(_EMPTY_HINT) | |
| tab_desc_df = gr.Dataframe( | |
| label="敘述性統計", | |
| interactive=False, visible=False, | |
| ) | |
| tab_desc_file = gr.File( | |
| label="下載敘述統計", | |
| interactive=False, visible=False, | |
| ) | |
| # 子分頁 2：差異性分析 | |
| # 2026-08-15（業主要求）：排列順序改成「表格→下載 | |
| # →箱形圖」，原本是「箱形圖→表格→下載」——把讀者 | |
| # 最先要看的原始數據放最上面，下載按鈕緊接在表格 | |
| # 後面，圖表當作視覺化補充放最後。元件本身（identity） | |
| # 沒變，只是宣告順序（等於畫面上下順序）調整，不影響 | |
| # 任何其他 wiring。 | |
| with gr.Tab("2. 差異性分析"): | |
| tab_diff_head = gr.Markdown(_EMPTY_HINT) | |
| tab_diff_df = gr.Dataframe( | |
| label="差異性分析", | |
| interactive=False, visible=False, | |
| ) | |
| tab_diff_file = gr.File( | |
| label="下載差異性分析", | |
| interactive=False, visible=False, | |
| ) | |
| tab_box_img = gr.Image(label="顯著指標箱形圖", visible=False) | |
| # 子分頁 3：監督式學習 | |
| with gr.Tab("3. 監督式學習"): | |
| tab_rf_md = gr.Markdown(_EMPTY_HINT) | |
| with gr.Row(): | |
| with gr.Column(scale=1): | |
| tab_imp_df = gr.Dataframe( | |
| label="特徵重要性 Top 20", | |
| interactive=False, visible=False, | |
| ) | |
| with gr.Column(scale=2): | |
| tab_imp_img = gr.Image(label="特徵重要性圖", visible=False) | |
| tab_imp_file = gr.File( | |
| label="下載監督式學習", | |
| interactive=False, visible=False, | |
| ) | |
| # 子分頁 4：非監督式學習 | |
| with gr.Tab("4. 非監督式學習"): | |
| tab_clust_md = gr.Markdown(_EMPTY_HINT) | |
| with gr.Row(): | |
| with gr.Column(scale=1): | |
| tab_dendro_img = gr.Image(label="層次分群樹狀圖", visible=False) | |
| with gr.Column(scale=1): | |
| tab_elbow_img = gr.Image(label="K-means Elbow Curve", visible=False) | |
| tab_pca_img = gr.Image(label="分群視覺化（PCA 2D）", visible=False) | |
| tab_cluster_df = gr.Dataframe( | |
| label="分群結果", | |
| interactive=False, visible=False, | |
| ) | |
| tab_cluster_file = gr.File( | |
| label="下載非監督式學習", | |
| interactive=False, visible=False, | |
| ) | |
| with gr.Column(visible=False, elem_id="canvas_report", elem_classes=["canvas-result"]) as canvas_report_col: | |
| # 2026-08-14（待辦 A1）：gr.Markdown 預設 latex_delimiters 只認 | |
| # $$...$$（區塊數學），LLM 報告裡常見的 $p=0.0223$ 這種行內數學 | |
| # 不會被 KaTeX 接手，原樣顯示成文字。這裡補上單一 $...$ 規則； | |
| # $$ 排在 $ 前面，避免 $$ 被拆成兩個各自不完整的單 $ 配對。 | |
| tab_rpt_md = gr.Markdown( | |
| _EMPTY_HINT, | |
| latex_delimiters=[ | |
| {"left": "$$", "right": "$$", "display": True}, | |
| {"left": "$", "right": "$", "display": False}, | |
| ], | |
| ) | |
| tab_rpt_file = gr.File( | |
| label="下載LLM輔助分析", | |
| file_count="multiple", interactive=False, visible=False, | |
| ) | |
| # 2026-07-23：技術執行紀錄從手風琴（exec_log_accordion） | |
| # 轉正成獨立頁面，跟 canvas_idx_col/canvas_stat_col/ | |
| # canvas_report_col 同一種待遇——不再需要 open/label | |
| # 收合狀態邏輯（原本靠 _accordion_update 控制），改用 | |
| # 跟其他三個結果頁一樣的 visible=True/False 語意，交給 | |
| # applyActivePage() JS 決定要不要顯示。 | |
| with gr.Column(visible=False, elem_id="canvas_exec", elem_classes=["canvas-result"]) as canvas_exec_col: | |
| # 千卉回報（2026-08-06）：這頁一直缺大標題文字。原因是 | |
| # 另外三個結果頁（語言指標分析／敘述統計／研究報告）的 | |
| # 「### 標題」都是烤進 _populate_tabs 每次重新賦值的內容 | |
| # 字串裡（一次性結果，整段換新）；但這頁是逐行往下累加 | |
| # 的執行 log（見 _log_append），不會整段重寫，所以從沒 | |
| # 機會把標題烤進 exec_log 的值裡。改成跟內容分開、獨立 | |
| # 一顆靜態 gr.Markdown，不受 log 累加邏輯影響。 | |
| gr.Markdown("### 技術執行紀錄") | |
| exec_log = gr.Markdown( | |
| value="", | |
| elem_id="exec_log", | |
| elem_classes=["exec-log"], | |
| ) | |
| # ── 結果內容輸出元件 + 3 個 Canvas 結果區塊可見性 ───────────────── | |
| # Phase 8-C：tab2/tab3/tab6（原 gr.Tab()）已改成 canvas_idx_col/ | |
| # canvas_stat_col/canvas_report_col（gr.Column()），可見性語意不變。 | |
| # | |
| # E5（2026-08-05）：這份清單是純位置對應——13 處呼叫端（_populate_tabs | |
| # 的回傳、_run_computation／on_metadata_confirm／on_metadata_skip 等 | |
| # generator 的每個 yield）都要交出跟 _TAB_OUTPUTS 完全等長、順序完全 | |
| # 一致的一份值，Gradio 只認位置、不認名字。拆成下面這些具名子清單只是 | |
| # 讓「這個 index 屬於哪個功能區塊」肉眼看得出來，**串接後的最終順序與 | |
| # 內容跟原本的單一扁平清單逐一相同，行為零改變**。真正的規則沒有變： | |
| # 子清單內部就代表最終 index 順序，新增元件只能加在對應子清單的尾端， | |
| # 不可插入中間、也不可調整子清單彼此的串接順序，否則所有呼叫端的 | |
| # index 對應會全部錯位。 | |
| _TAB_IDX = [tab_idx_md, tab_idx_df, tab_idx_file] # 語言指標分析 | |
| _TAB_DESC = [tab_desc_md, tab_desc_df, tab_desc_file] # 敘述統計（含下載） | |
| _TAB_DIFF = [tab_diff_head, tab_diff_df, tab_box_img, tab_diff_file] # 差異性分析（含下載） | |
| _TAB_SUPERVISED = [tab_rf_md, tab_imp_df, tab_imp_img] # 監督式學習 | |
| _TAB_UNSUPERVISED = [tab_clust_md, tab_dendro_img, tab_elbow_img, | |
| tab_pca_img, tab_cluster_df] # 非監督式學習 | |
| _TAB_REPORT = [tab_rpt_md, tab_rpt_file] # 研究報告 | |
| _TAB_CANVAS_VIS = [canvas_idx_col, canvas_stat_col, canvas_report_col] # 3 個 Canvas 結果區塊可見性 | |
| _TAB_EXTRA_DL = [tab_imp_file, tab_cluster_file] # 補的下載按鈕（監督式/非監督式學習） | |
| _TAB_EXEC_LOG = [canvas_exec_col] # 技術執行紀錄（2026-07-23 轉正成獨立頁面） | |
| _TAB_NAV_DL = [nav_dl_idx_btn, nav_dl_stat_btn, # 導覽列下載捷徑（2026-07-24） | |
| nav_dl_report_btn, nav_dl_all_btn, | |
| nav_dl_group] # 下載捷徑整組（分隔線+四顆）可見性 | |
| _TAB_NAV_GATES = [nav_idx_btn, nav_stat_sub_0, nav_stat_sub_1, # 結果導覽 interactive 閘門（A2） | |
| nav_stat_sub_2, nav_stat_sub_3, nav_report_btn] | |
| _TAB_OUTPUTS = ( | |
| _TAB_IDX + _TAB_DESC + _TAB_DIFF + _TAB_SUPERVISED + _TAB_UNSUPERVISED + | |
| _TAB_REPORT + _TAB_CANVAS_VIS + _TAB_EXTRA_DL + _TAB_EXEC_LOG + | |
| _TAB_NAV_DL + _TAB_NAV_GATES | |
| ) | |
| _N_TAB = len(_TAB_OUTPUTS) | |
| # ── helper ────────────────────────────────────────────────────────── | |
| def _ts(): | |
| # 台北時間 [HH:MM:SS]。2026-07-24：技術執行紀錄行首原本是 `›` 代碼 | |
| # 方框，渲染出來像可展開的按鈕但沒功能（千卉回報）；改成時間戳， | |
| # 像真的執行 log、明顯不可點，還多了「每步幾點跑的」診斷資訊。 | |
| return datetime.now(timezone(timedelta(hours=8))).strftime("[%H:%M:%S]") | |
| def _log_append(log_history, msg): | |
| # 最新訊息放最下面，跟對話視窗（新訊息在下）方向一致； | |
| # 畫面捲動由 head 注入的 JS 自動處理（見 _APP_HEAD_SCRIPT 的 exec-log 監看） | |
| prev = log_history or "" | |
| line = f"{_ts()} {msg}" | |
| return f"{prev}\n\n{line}" if prev else line | |
| def _populate_tabs(state): | |
| """streaming 結束後呼叫，讀取 output 檔案並填入各分頁。""" | |
| R = [gr.update()] * _N_TAB # 預設全部不動 | |
| if state is None: | |
| return R | |
| # 下載捷徑（26-29）與整組容器（30）是少數必須「明確設回隱藏」的 | |
| # 輸出：其他結果元件都住在 canvas_*_col 裡，重置時整個 Column 被藏 | |
| # 起來、殘值看不到；這幾顆住在 result_nav_col，而 result_nav_col 會 | |
| # 在下次選定情境時重新顯示，不主動歸零的話上一輪的 zip 會跟著冒出 | |
| # 來。結果導覽閘門（31-36）同理，每次都先設回 disable，有結果再開。 | |
| for _i in (26, 27, 28, 29): | |
| R[_i] = gr.update(visible=False, value=None) | |
| R[30] = gr.update(visible=False) # nav_dl_group（Column，無 value） | |
| for _i in (31, 32, 33, 34, 35, 36): | |
| R[_i] = gr.update(interactive=False) | |
| output_dir = Path(state["session_dir"]) / "output" | |
| uploaded = state.get("uploaded_files", []) | |
| # ── 需要 output 目錄存在 ────────────────────────────────────── | |
| if not output_dir.exists(): | |
| return R | |
| # ── 語言指標分析（index 0-2）────────────────────────────────── | |
| csv_path = output_dir / "textIndex_calculated.csv" | |
| xlsx_list = sorted(output_dir.glob("textIndex_calculated_1_*.xlsx")) | |
| if csv_path.exists(): | |
| df = pd.read_csv(str(csv_path)) | |
| # 2026-08-14：畫面上的表格與指標數統計要濾掉業主要求隱藏的 13 項 | |
| # （見 HIDDEN_INDICATOR_CODES），但下載的 CSV／XLSX 刻意用未濾過 | |
| # 的 df（textIndex_calculated 原始檔）——業主說這 13 項「無須 | |
| # 刪除」，下載檔案代表的是完整原始計算結果，只有畫面呈現要隱藏。 | |
| df_display = _drop_hidden_indicators(df) | |
| # 指標數 = 總欄位數扣除中介欄（Text/Type1/Type2） | |
| meta_cols = [c for c in ["Text", "Type1", "Type2"] if c in df_display.columns] | |
| n_indicators = len(df_display.columns) - len(meta_cols) | |
| R[0] = f"### 語言指標分析\n共 **{len(df_display)}** 個文本，**{n_indicators}** 個語言指標。" | |
| R[1] = gr.update(value=df_display, visible=True) | |
| dl = [str(csv_path)] | |
| if xlsx_list: | |
| dl.append(str(xlsx_list[-1])) | |
| R[2] = gr.update(value=dl, visible=True) | |
| # ── 統計比較分析：敘述統計 + 差異分析（index 3-7）───────────── | |
| desc_path = output_dir / "01_descriptive_stats.csv" | |
| diff_path = output_dir / "02_difference_analysis.csv" | |
| box_path = output_dir / "02_significant_boxplots.png" | |
| if desc_path.exists(): | |
| desc = pd.read_csv(str(desc_path)) | |
| R[3] = f"### 敘述統計\n共 **{len(desc)}** 個指標的敘述統計。" | |
| R[4] = gr.update(value=desc, visible=True) | |
| R[5] = gr.update(value=str(desc_path), visible=True) | |
| if diff_path.exists(): | |
| diff = pd.read_csv(str(diff_path)) | |
| if '顯著' in diff.columns: | |
| sig = diff[~diff['顯著'].isin(['ns', INSUFFICIENT_DATA_LABEL])] | |
| untestable_n = int((diff['顯著'] == INSUFFICIENT_DATA_LABEL).sum()) | |
| else: | |
| sig = pd.DataFrame(); untestable_n = 0 | |
| # sig=0 時不會產生箱形圖（見下方 box_path 判斷），若只留白使用者 | |
| # 容易誤以為系統壞掉，這裡改在標題文字附加空狀態說明 | |
| empty_note = "" if len(sig) > 0 else "\n\n本次分析未發現統計顯著的指標差異，因此未產生箱形圖。" | |
| untestable_note = ( | |
| f"\n\n⚠️ 另有 **{untestable_n}** 個指標因組別樣本數不足（N<2），" | |
| "無法進行統計檢定，不計入上述比例。" | |
| if untestable_n > 0 else "" | |
| ) | |
| # 見 ZERO_VARIANCE_WARNING／ZERO_PROPORTION_WARNING 定義處：這些 | |
| # 指標仍計入顯著／不顯著比例（p 值照常有效），只是額外提醒統計 | |
| # 穩定性存疑，跟上面「資料不足」（完全無法檢定、不計入比例）是 | |
| # 不同性質，故用不同語氣、且不寫「不計入上述比例」。這裡的句子 | |
| # 刻意不細分是哪一條判準命中——個別是哪一種，下方表格會逐列標註。 | |
| warn_n = int((diff.get('資料品質警示', pd.Series(dtype=str)).fillna('') != '').sum()) | |
| zero_var_note = ( | |
| f"\n\n⚠️ 其中 **{warn_n}** 個顯著指標的資料品質有疑慮" | |
| "（某組標準差趨近於 0，或某組半數以上樣本為 0），" | |
| "統計穩定性有限，建議謹慎解讀（詳見下方表格個別標註）。" | |
| if warn_n > 0 else "" | |
| ) | |
| # 2026-08-14（業主要求）：標題句前面加一句「以［檢定方法］比較 | |
| # ［分組］文本」，方法與分組名稱都從 diff 本身反推——分組代碼 | |
| # 是「{組別}_N」這組欄名的前綴（run_statistical_analysis 產出 | |
| # 時就是這樣命名，見該處 diff_results.append 那段），不是另外 | |
| # 寫死 A／B，之後研究情境換了分組代號也會自動跟著對。 | |
| group_codes = [c[:-2] for c in diff.columns if c.endswith('_N')] | |
| # 2026-08-14（業主要求）：如果「語料說明」有把分組代碼改寫成 | |
| # 實際標籤（例如把 A 改成「人工翻譯」），這裡要據實呈現那個 | |
| # 標籤，不是原始代碼——group_labels 沒填的組別維持顯示代碼。 | |
| group_labels_map = state.get("group_labels", {}) or {} | |
| group_names = [group_labels_map.get(g, g) for g in group_codes] | |
| if len(group_names) >= 2: | |
| group_desc = "、".join(group_names[:-1]) + f" 與 {group_names[-1]}" | |
| elif group_names: | |
| group_desc = group_names[0] | |
| else: | |
| group_desc = "" | |
| method_raw = diff['方法'].iloc[0] if len(diff) > 0 and '方法' in diff.columns else None | |
| method_zh = {"t-test": "獨立樣本 t 檢定（Welch）", | |
| "ANOVA": "單因子變異數分析（ANOVA）"}.get(method_raw, method_raw) | |
| prefix = f"以{method_zh}比較 {group_desc} 文本，" if (method_zh and group_desc) else "" | |
| # 2026-08-15（業主要求）：下面表格的欄名有 N／M／SD 這種統計 | |
| # 縮寫，加一句白話說明放在表格正上方，跟 docx 技術報告那份 | |
| # 的做法一致。 | |
| R[6] = gr.update( | |
| value=(f"### 差異性分析\n{prefix}共 **{len(diff)}** 個指標，" | |
| f"其中 **{len(sig)}** 個達顯著差異（p < {ALPHA}）。{empty_note}{untestable_note}{zero_var_note}\n\n" | |
| f"下方表格中 N＝樣本數、M＝平均數、SD＝標準差。"), | |
| visible=True, | |
| ) | |
| R[7] = gr.update(value=diff, visible=True) | |
| R[9] = gr.update(value=str(diff_path), visible=True) | |
| if box_path.exists(): | |
| R[8] = gr.update(value=str(box_path), visible=True) | |
| # ── 統計比較分析：監督式學習（index 10-12）───────────────────── | |
| imp_path = output_dir / "03_feature_importance.csv" | |
| imp_fig = output_dir / "03_feature_importance.png" | |
| anal = state.get("analysis_result") or {} | |
| if anal.get("accuracy") is not None: | |
| acc = anal["accuracy"] | |
| acc_str = f"{acc:.4f}" if isinstance(acc, float) else str(acc) | |
| R[10] = f"### 監督式學習（隨機森林分類）\n模型準確率（Accuracy）：**{acc_str}**" | |
| if imp_path.exists(): | |
| imp = pd.read_csv(str(imp_path)).head(20) | |
| R[11] = gr.update(value=imp, visible=True) | |
| if imp_fig.exists(): | |
| R[12] = gr.update(value=str(imp_fig), visible=True) | |
| imp_dl = [str(p) for p in [imp_path, imp_fig] if p.exists()] | |
| if imp_dl: | |
| R[23] = gr.update(value=imp_dl, visible=True) | |
| # ── 統計比較分析：非監督式學習（index 13-17）────────────────── | |
| dendro_path = output_dir / "04a_dendrogram.png" | |
| elbow_path = output_dir / "04b_kmeans_elbow.png" | |
| pca_fig_path = output_dir / "04c_clustering_pca2d.png" | |
| cluster_path = output_dir / "05_cluster_results.csv" | |
| pca_ev = anal.get("pca_ev", []) | |
| ev_str = "" | |
| if len(pca_ev) >= 2: | |
| ev_str = f"\n\nPCA 解釋變異量：PC1 = {pca_ev[0]:.1%}，PC2 = {pca_ev[1]:.1%}" | |
| if any(p.exists() for p in [dendro_path, elbow_path, pca_fig_path]): | |
| R[13] = f"### 非監督式學習（集群分析）{ev_str}" | |
| if dendro_path.exists(): | |
| R[14] = gr.update(value=str(dendro_path), visible=True) | |
| if elbow_path.exists(): | |
| R[15] = gr.update(value=str(elbow_path), visible=True) | |
| if pca_fig_path.exists(): | |
| R[16] = gr.update(value=str(pca_fig_path), visible=True) | |
| if cluster_path.exists(): | |
| cdf = pd.read_csv(str(cluster_path)) | |
| # 2026-08-15（業主要求）：畫面呈現時 Type1 改標成看得懂的 | |
| # 「原始分組(A/B)」，Type2 不顯示（它一直是 Type1 的原樣 | |
| # 複製，沒有額外資訊，見 run_statistical_analysis 那行 | |
| # df['Type2'] = df['Type1'] 的註解）——下載的 CSV 檔案 | |
| # 刻意不動，仍保留原始欄名／欄位，跟語言指標分析那張表同一個 | |
| # 「下載檔案給完整原始資料、畫面只呈現整理過的版本」的原則。 | |
| cdf_display = cdf.drop(columns=["Type2"], errors="ignore") \ | |
| .rename(columns={"Type1": "原始分組(A/B)"}) | |
| R[17] = gr.update(value=cdf_display, visible=True) | |
| cluster_dl = [str(p) for p in [dendro_path, elbow_path, pca_fig_path, cluster_path] if p.exists()] | |
| if cluster_dl: | |
| R[24] = gr.update(value=cluster_dl, visible=True) | |
| # ── 研究報告（index 18-19）──────────────────────────────────── | |
| txt_files = sorted(output_dir.glob("LLM_Analysis-*.txt"), reverse=True) | |
| docx_files = sorted(output_dir.glob("LLM_Analysis-*.docx"), reverse=True) | |
| final_rpts = sorted(output_dir.glob("Final_Report-*.docx"), reverse=True) | |
| if txt_files: | |
| try: | |
| with open(str(txt_files[0]), 'r', encoding='utf-8') as f: | |
| rpt_text = f.read() | |
| # 2026-08-24（業主回報畫面上模型資訊重複顯示兩次）：txt 檔本身 | |
| # 從 2026-08-22 起（可重複性設計）就會把「模型：...」這行寫進 | |
| # 檔頭，是給下載後獨立開啟 txt 檔的人看的；但畫面這裡另外又疊了 | |
| # 一行同樣內容的 model_note（有顏色樣式、給畫面用），兩者一起 | |
| # 顯示就變成重複。畫面上只保留有樣式的 model_note，rpt_text | |
| # 裡那行純文字的「模型：」拿掉，txt 檔本身仍完整保留不受影響。 | |
| rpt_text = re.sub(r'^模型：.*\n', '', rpt_text, count=1, flags=re.MULTILINE) | |
| model_note = (f"<span style='color:var(--c-accent-strong);font-weight:600'>" | |
| f"本報告由主 Agent（LLM1）模型 {LLM1_MODEL} 生成" | |
| f"（提示詞版本 {PROMPT_VERSION}）</span>") | |
| R[18] = f"### LLM 輔助分析 {model_note}\n\n{rpt_text}" | |
| except Exception: | |
| R[18] = "### LLM 輔助分析\n\n（讀取報告時發生錯誤）" | |
| # 下載清單只留敘述統計技術報告跟 LLM 輔助報告兩份，複製成使用者 | |
| # 指定的檔名（保留原始檔案不動，避免影響其他邏輯依賴原檔名）； | |
| # 原始 .txt 不提供下載，僅用於上方 R[18] 的文字顯示 | |
| # | |
| # 千卉發現的踩坑（2026-08-06）：final_rpts（敘述統計技術報告） | |
| # 是統計階段一完成就存在，早於 LLM 報告撰寫階段。若不設防， | |
| # 「報告撰寫」子階段還在跑的當下，這裡就會把只有統計報告、缺 | |
| # LLM 報告的清單當成「研究報告」打包出去——使用者這時點下載， | |
| # 拿到的檔案內容不完整。改成整段等 report 子階段真正跑到終態 | |
| # （done 或 failed，不再是 running/pending）才組清單；報告若 | |
| # 失敗，final_rpts 仍在，讓使用者至少能拿到統計報告，不會被 | |
| # 卡死拿不到任何東西。 | |
| report_stage_done = state["analysis"].get("report", {}).get("status") in ("done", "failed") | |
| dl_rpt = [] | |
| if report_stage_done: | |
| if final_rpts: | |
| ts = final_rpts[0].stem.split("Final_Report-")[-1] | |
| # 2026-09-01（業主回報）：下載檔名跟著同一輪一起從 | |
| # "TransPrism_stats_" 改成跟文件內標題（見上方 | |
| # run_statistical_analysis 的 doc.add_heading）一致的 | |
| # 「統計結果技術報告」，時間戳保留，避免多次下載互相 | |
| # 覆蓋。 | |
| stats_dst = output_dir / f"統計結果技術報告_{ts}.docx" | |
| if not stats_dst.exists(): | |
| shutil.copy(str(final_rpts[0]), str(stats_dst)) | |
| dl_rpt.append(str(stats_dst)) | |
| if docx_files: | |
| ts = docx_files[0].stem.split("LLM_Analysis-")[-1] | |
| llm_dst = output_dir / f"TransPrism_LLM Report_{ts}.docx" | |
| if not llm_dst.exists(): | |
| shutil.copy(str(docx_files[0]), str(llm_dst)) | |
| dl_rpt.append(str(llm_dst)) | |
| # 2026-08-26：這次分析實際套用的 system prompt 原文，跟報告 | |
| # 一起提供下載——固定檔名（不像上面兩份加時間戳），本來就 | |
| # 只會有一份，不需要另外複製改名。 | |
| sp_path = output_dir / "06_system_prompt.txt" | |
| if sp_path.exists(): | |
| dl_rpt.append(str(sp_path)) | |
| if dl_rpt: | |
| R[19] = gr.update(value=dl_rpt, visible=True) | |
| # ── 導覽列下載捷徑：把上面各頁的下載清單打成四包（index 26-29）─ | |
| # 刻意沿用上面已經整理好的清單變數，不另外去 output_dir 掃檔案： | |
| # 掃出來的會含 LLM_Analysis-*.txt 這種只供畫面顯示、不提供下載的 | |
| # 中間產物，也含前一次打包留下的 .zip 自己。 | |
| # | |
| # allow_all=report_stage_done：「完整分析資料」整包同理，report | |
| # 子階段還在跑時，即使 idx／stat 兩組都已完成（湊到 ≥2 組的舊 | |
| # 門檻），也不該急著把「完整」兩字掛出來卻漏掉報告——見上面 | |
| # report_stage_done 的踩坑說明。 | |
| zips = _make_result_zips(output_dir, { | |
| "idx": [str(csv_path)] + [str(p) for p in xlsx_list[-1:]], | |
| "stat": [str(p) for p in [desc_path, diff_path, box_path]] + imp_dl + cluster_dl, | |
| "report": dl_rpt, | |
| }, allow_all=report_stage_done) | |
| state["zip_paths"] = zips | |
| # 2026-08-15（業主要求）：導覽列下載捷徑只留「下載全部資料」一顆， | |
| # 「下載指標數據／統計圖表／研究報告」三顆不再顯示。刻意不刪 | |
| # nav_dl_idx_btn／nav_dl_stat_btn／nav_dl_report_btn 這三個元件 | |
| # 的宣告、也不動 _TAB_NAV_DL 清單結構——這批 _TAB_OUTPUTS 的 index | |
| # 是全站共用的固定順序（見上方「子清單內部就代表最終 index 順序」 | |
| # 的警語），砍元件會讓後面所有 index 全部錯位，風險太高。改成 | |
| # 這裡的迴圈只留 "all" 這一組，前三個按鈕沒有任何地方會把它們 | |
| # 設回 visible=True，永遠維持宣告時的初始隱藏狀態，畫面上就只 | |
| # 剩第四顆——效果一樣，但完全不影響其他 index。 | |
| for _i, _key in ((29, "all"),): | |
| if zips.get(_key): | |
| R[_i] = gr.update(value=zips[_key], visible=True) | |
| # 2026-08-15：畫面上只剩「下載全部資料」一顆按鈕，容器可見性 | |
| # 改成只看 "all" 這包在不在——原本「只要有任一包 zip 就顯示」 | |
| # 在 idx／stat／report 任一包先做出來、但 all 還沒湊齊 | |
| # （report 階段尚未跑完）時，會出現分隔線卻沒有任何按鈕的空殼 | |
| # （因為那三顆已經被拿掉），剛好是這段容器邏輯當初想避免的 | |
| # 「分隔線孤零零留在畫面上」（見上方 B3 註解）。 | |
| if zips.get("all"): | |
| R[30] = gr.update(visible=True) | |
| # ── 顯示各分頁 Tab（index 20-22）＋結果導覽閘門（31-36，A2）────── | |
| if csv_path.exists(): | |
| R[20] = gr.update(visible=True) # 語言指標分析 | |
| R[31] = gr.update(interactive=True) # nav_idx_btn | |
| stat_ready = desc_path.exists() or imp_path.exists() \ | |
| or any(p.exists() for p in [dendro_path, elbow_path, pca_fig_path]) | |
| if stat_ready: | |
| R[21] = gr.update(visible=True) # 統計比較分析 | |
| # 統計四個子頁共用同一頁，統計一產出就四個一起開 | |
| for _i in (32, 33, 34, 35): | |
| R[_i] = gr.update(interactive=True) | |
| if txt_files or docx_files: | |
| R[22] = gr.update(visible=True) # 研究報告 | |
| R[36] = gr.update(interactive=True) # nav_report_btn（報告失敗時維持 disable） | |
| # 2026-07-31（Batch E 第 7 項）：業主要求拿掉統計分析跑完後跳出的 | |
| # gr.Info toast（理由：其他階段都沒有通知，只有這裡有，不一致又 | |
| # 干擾）。原本用來擋重複 toast 的 state["tabs_toast_shown"] 旗標 | |
| # （Bug 4-A 修復時加的，因為 _populate_tabs 現在會在 idx/stat/ | |
| # report 三個子階段各自完成時＋結尾各呼叫一次，不再只呼叫一次） | |
| # 連同 any_tab_ready 這個只為了算 toast 條件而存在的區域變數 | |
| # 一併移除——拿掉 toast 之後兩者都沒有其他用途，留著是無作用的 | |
| # 殘留狀態，不是這批任務要避免的「順手重構」，是移除本項本身的 | |
| # 必要連帶清理。state["tabs_toast_shown"] 的初始化也一併從 | |
| # make_initial_state 拿掉（見該處）。 | |
| return R | |
| # ── 啟動：先顯示「啟動中」，再載入 LLM 歡迎訊息 ─────────────────── | |
| def on_load_init(): | |
| """第一步：立即顯示啟動中提示。""" | |
| sid = str(uuid.uuid4())[:8] | |
| state = make_initial_state(sid) | |
| return ( | |
| [_assistant_msg("系統啟動中...")], | |
| f"{_ts()} 系統啟動中…", | |
| state, | |
| gr.update(visible=False), | |
| gr.update(value=_build_header_html()), | |
| ) | |
| def on_load_ready(chat_history, log_history, state): | |
| """第二步：顯示固定歡迎訊息。""" | |
| # 2026-07-31（Batch E 第 4-d 項）：業主拿掉「(或下方)」——情境 | |
| # 選擇已搬進工作區右側 Canvas，對話框不再需要提示「或下方」 | |
| # 這個舊版單欄置中版面才有意義的說法。 | |
| intro = ( | |
| "歡迎使用 TransPrism II 分析引擎 SpectraEngine。\n\n" | |
| "請依照您的研究設計，點選右方最符合的研究情境開始分析：" | |
| ) | |
| return ( | |
| [_assistant_msg(intro)], | |
| f"{_ts()} 系統已就緒，等待使用者操作。", | |
| ) | |
| demo.load( | |
| fn=on_load_init, | |
| outputs=[chatbot, exec_log, session_state, upload_row, app_header_html], | |
| ).then( | |
| fn=on_load_ready, | |
| inputs=[chatbot, exec_log, session_state], | |
| outputs=[chatbot, exec_log], | |
| ) | |
| # ── 標題步驟列即時更新 helper（原本更新 todo_md，現在改更新頂部標題）─── | |
| def _todo_update(state): | |
| """根據 state 的 done_steps / current_step 回傳 app_header_html gr.update。""" | |
| if not state or not state.get("scenario"): | |
| return gr.update(value=_build_header_html()) | |
| return gr.update( | |
| value=_build_header_html( | |
| state.get("done_steps", []), | |
| state.get("current_step"), | |
| state.get("failed_step"), | |
| ) | |
| ) | |
| # ── Phase 8-D：Canvas 運算中提示（粗粒度階段文字＋轉圈動畫）───── | |
| # 只在三段運算階段顯示（2026-07-23 步驟列收斂後 key 從 5/6/7 改成 | |
| # 4/5/6，這段是當時還用數字 key 時的歷史紀錄；現在 _ANALYSIS_ENTRY | |
| # 的 key 已經是 "idx"/"stat"/"report" 字串，不是 _STEPS 的步驟編號， | |
| # 2026-07-30 新增「研究選擇」步驟、_STEPS 從 3 步變 4 步、純步驟編號 | |
| # 全部 +1，跟這個字典無關，不用一起改）， | |
| # 不新增運算邏輯；用 gr.HTML() 單一元件承載，空字串＝不顯示、不用另外 | |
| # 接一個 visibility 輸出，wiring 只多一個輸出點。 | |
| # 2026-07-24：原本這裡是「運算中…（步驟 N/3）」單行提示。它跟步驟列 | |
| # 講同一件事（哪一步）而且那個 N/3 會給錯期待（讓人以為要熬三段，實際 | |
| # 上前兩段一閃而過、時間幾乎全在報告撰寫）。改成 _build_analysis_html： | |
| # 一張分段的「分析運算」內容區塊，運算中顯示每段進度、運算後變成分段 | |
| # 摘要（標題＋狀態＋一句結論＋查看入口），空間比藥丸大得多，報告失敗時 | |
| # 也能據實說明「壞的只是報告、其他不受影響」。同一塊 HTML 從頭用到尾， | |
| # 取代舊的 computing_html 顯示內容（元件與 elem_id 沿用不變）。 | |
| # 每段「查看…」入口是純 JS 橋接（見 _APP_HEAD_SCRIPT 的 analysis-entry | |
| # 事件代理），點了等同點左側對應導覽項目，不走 Gradio queue。 | |
| # 入口標籤一律跟導覽列名稱一致（item 2）。統計分析這段的產出對應四個 | |
| # 導覽子頁，2026-07-24 千卉決定：不用「統計比較分析」這個傘狀詞（導覽列 | |
| # 裡已無此項），直接列四個查看連結（item 4）。 | |
| _ANALYSIS_ENTRY = { | |
| "idx": [("nav_idx_btn", "查看語言指標分析")], | |
| "stat": [("nav_stat_sub_0", "查看敘述統計"), | |
| ("nav_stat_sub_1", "查看差異性分析"), | |
| ("nav_stat_sub_2", "查看監督式學習"), | |
| ("nav_stat_sub_3", "查看非監督式學習")], | |
| "report": [("nav_report_btn", "查看 LLM 輔助分析")], | |
| } | |
| def _build_analysis_html(state): | |
| if not state: | |
| return "" | |
| A = state.get("analysis") or {} | |
| if not A or all(A.get(k, {}).get("status", "pending") == "pending" | |
| for k, _, _ in _ANALYSIS_STAGES): | |
| return "" # 運算還沒開始，不顯示 | |
| rows = [] | |
| for key, title, _ in _ANALYSIS_STAGES: | |
| info = A.get(key, {}) | |
| status = info.get("status", "pending") | |
| line = info.get("line", "") | |
| if status == "running": | |
| icon = '<span class="analysis-spinner" aria-hidden="true"></span>' | |
| line = line or "處理中……" | |
| elif status == "done": | |
| icon = '<span class="analysis-mark analysis-mark--done">✓</span>' | |
| elif status == "failed": | |
| icon = '<span class="analysis-mark analysis-mark--failed">!</span>' | |
| else: # pending | |
| icon = '<span class="analysis-mark analysis-mark--pending">•</span>' | |
| line = line or "等待中" | |
| entry = "" | |
| if status == "done" and key in _ANALYSIS_ENTRY: | |
| entry = "".join( | |
| f'<a class="analysis-entry" role="button" tabindex="0" ' | |
| f'data-nav="{nav_id}">{label} →</a>' | |
| for nav_id, label in _ANALYSIS_ENTRY[key] | |
| ) | |
| rows.append( | |
| '<div class="analysis-row analysis-row--' + status + '">' | |
| f'<div class="analysis-row-head">{icon}' | |
| f'<span class="analysis-row-title">{title}</span></div>' | |
| f'<div class="analysis-row-body">{line}{entry}</div>' | |
| '</div>' | |
| ) | |
| # 2026-08-05：連線一斷、後端還是會照跑完，但前端畫面收不到任何 | |
| # 更新（見「開發優化建議.md」第一節選項C討論）。系統目前沒有 | |
| # 連線中斷後恢復進度的機制，只能先用文案提醒使用者在還沒看到 | |
| # 「分析完成」前，不要把分頁切到背景或讓電腦休眠。只在還有子 | |
| # 階段「進行中」時顯示，全部 done／failed 定案後就不需要了。 | |
| any_running = any( | |
| A.get(k, {}).get("status") == "running" for k, _, _ in _ANALYSIS_STAGES | |
| ) | |
| hint = ( | |
| '<p class="analysis-panel-hint">' | |
| '⚠️ 分析運算期間請保持此分頁在前景、電腦勿休眠，直到看到「分析完成」為止，' | |
| '避免連線中斷導致畫面卡住。</p>' | |
| if any_running else "" | |
| ) | |
| return ( | |
| '<div class="analysis-panel">' | |
| '<h2 class="analysis-panel-title">分析運算</h2>' | |
| + hint + "".join(rows) + | |
| '</div>' | |
| ) | |
| def _computing_update(state): | |
| return gr.update(value=_build_analysis_html(state)) | |
| # ── 3-C（2026-07-30）：文本上傳工作進度說明 ───────────────────── | |
| # 業主回報「上傳過程都一片白，只在對話視窗出現文字氣泡，用戶會不 | |
| # 知道發生什麼事」。比照上面「分析運算」內容區塊的做法：同一組 | |
| # .analysis-panel CSS 視覺語彙（標題／狀態圖示／spinner），不另創 | |
| # 一套樣式；子階段切成「檔案接收」與「格式驗證」兩段，對應 | |
| # on_upload_confirm 現有的處理流程（接收檔案→跑 run_format_check）。 | |
| _UPLOAD_STAGES = [ | |
| ("receive", "檔案接收"), | |
| ("validate", "格式驗證"), | |
| ] | |
| def _build_upload_html(state): | |
| if not state: | |
| return "" | |
| U = state.get("upload") or {} | |
| if not U or all(U.get(k, {}).get("status", "pending") == "pending" | |
| for k, _ in _UPLOAD_STAGES): | |
| return "" # 上傳還沒開始，不顯示（同 _build_analysis_html 的語意） | |
| rows = [] | |
| for key, title in _UPLOAD_STAGES: | |
| info = U.get(key, {}) | |
| status = info.get("status", "pending") | |
| line = info.get("line", "") | |
| if status == "running": | |
| icon = '<span class="analysis-spinner" aria-hidden="true"></span>' | |
| line = line or "處理中……" | |
| elif status == "done": | |
| icon = '<span class="analysis-mark analysis-mark--done">✓</span>' | |
| elif status == "failed": | |
| icon = '<span class="analysis-mark analysis-mark--failed">!</span>' | |
| else: # pending | |
| icon = '<span class="analysis-mark analysis-mark--pending">•</span>' | |
| line = line or "等待中" | |
| rows.append( | |
| '<div class="analysis-row analysis-row--' + status + '">' | |
| f'<div class="analysis-row-head">{icon}' | |
| f'<span class="analysis-row-title">{title}</span></div>' | |
| f'<div class="analysis-row-body">{line}</div>' | |
| '</div>' | |
| ) | |
| return ( | |
| '<div class="analysis-panel">' | |
| '<h2 class="analysis-panel-title">文本上傳</h2>' | |
| + "".join(rows) + | |
| '</div>' | |
| ) | |
| def _upload_update(state): | |
| return gr.update(value=_build_upload_html(state)) | |
| # ── 1-B／3-A（2026-07-30）：「開始研究分析」進入工作區 ────────────── | |
| # 首頁改版後，homepage_col → workspace_row 的翻轉搬到這裡（原本 | |
| # 「進工作區」跟「選定情境」是同一個事件 on_scenario_pick 的第一個 | |
| # yield；現在拆成兩個獨立事件：這裡只負責「進工作區、顯示研究選擇 | |
| # 卡片」，on_scenario_pick 改成只負責「選定情境後的下一步」。 | |
| # on_scenario_pick 仍保留對 homepage_col/workspace_row 的 gr.update() | |
| # 呼叫——此時它們已經是目標值，重複賦值是 no-op，拿掉徒增對「已修好 | |
| # 的三個 bug」邏輯的改動風險，不如保留不動。 | |
| # | |
| # 4-C 回歸修復（2026-07-31，Batch G 第 0 項）：這裡曾經被拆成三個用 | |
| # .then() 串接的獨立事件（on_start_analysis_show → 補償子元件 → | |
| # 補償 nav_dl_group）。實測（DOM 輪詢量測＋螢幕截圖）證實：拆成 | |
| # 「三個獨立 Blocks 事件」跟拆成「同一個 generator 裡的三個 yield」 | |
| # 不是等價寫法——.then() 串接的每一段都是獨立送出的請求，前端要收到 | |
| # 上一段回應、畫面重繪完，才會送出下一段請求；這中間有一段肉眼可見 | |
| # 的時間差（本機量測約 100ms，正式環境網路延遲更大時會更久）。 | |
| # workspace_row 從 visible=False 翻回 True 那一刻（第一段事件）， | |
| # 只要 metadata_row／canvas_idx_col／canvas_stat_col／canvas_report_col | |
| # 曾經因為走過一次上傳確認／分析完成而被設成過 visible=True，Gradio | |
| # 6 就會在這一批訊息把它們的舊 True 值還原回來（本檔開頭記錄的地雷）； | |
| # 這個還原值會先被畫出來，直到「補償子元件」那段事件送達才會被蓋掉。 | |
| # 兩段之間的那段真空時間，使用者看到的就是「上一輪的語料說明表單 | |
| # 疊在新一輪研究選擇卡片下方」——也就是業主回報的 4-C 復發。 | |
| # | |
| # 修法：改回跟 on_scenario_pick 完全一致的做法——單一個 generator | |
| # 函式，用多個 yield 取代多個 .then() 事件。同一個 generator 的多次 | |
| # yield 走的是同一條已建立的連線（stream），前端不需要再送一次新 | |
| # 請求才能收到下一段更新，兩個 yield 之間的間隔是伺服器端逐行執行 | |
| # 的時間，量測結果從「~100ms 的網路來回」降到「同一 tick 內」，不會 | |
| # 再讓使用者看到中間的還原值。 | |
| # | |
| # 【給後續改動者】：這個「祖先容器可見性翻轉」跟「子元件補償重置」 | |
| # 的先後順序，永遠只能靠「同一個 generator 的下一個 yield」保證， | |
| # 不能靠「另一個用 .then() 串接的獨立事件」——後者在 Gradio 6 裡是 | |
| # 兩個獨立的請求/回應循環，即使邏輯上「馬上接著執行」，使用者仍然 | |
| # 會先看到一次錯誤畫面。往後如果「進工作區」的入口又搬家（就像這次 | |
| # 從 on_scenario_pick 搬到 start_analysis_btn 一樣），這三個 yield | |
| # 要整組一起搬，不要只搬第一個 yield、把後面兩個留在原地或拆成 | |
| # .then()。 | |
| def on_start_analysis_show(state): | |
| if state is None: | |
| yield ( | |
| gr.update(visible=False), gr.update(visible=True), | |
| gr.update(visible=True), gr.update(), state, | |
| gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(), gr.update(), gr.update(), | |
| ) | |
| return | |
| state["current_step"] = 1 | |
| # yield 1：workspace_row 從 visible=False 翻回 True 的那一批（祖先 | |
| # 翻轉），scenario_select_row 本來就要在這時候顯示 True。子元件的 | |
| # 補償刻意留到下一個 yield，不跟這批同時處理（理由見上方大段註解）。 | |
| # | |
| # result_nav_col／canvas_exec_col 例外：2026-08-06 千卉實測發現， | |
| # 「元件第一次從 visible=False 翻成 True（此生第一次掛進 DOM）」 | |
| # 這件事，只有在觸發它的 generator 的第一個 yield 裡設定才會真的 | |
| # 生效——on_scenario_pick 的 result_nav_col／canvas_exec_col 就是 | |
| # 這樣，在第一個 yield 就設 visible=True（見該函式），所以按鈕跟 | |
| # 內容區塊真的會出現。這裡原本學 4-C 的做法把兩者延到下一個 yield | |
| # 才設，結果變成「Python 端送出了 visible=True，前端卻從頭到尾 | |
| # 沒把這批按鈕跟內容掛進 DOM」——使用者點「開始研究分析」進入 | |
| # 研究選擇畫面後，左側導覽列只剩「回首頁」，AI對話／技術執行紀錄 | |
| # 等全部消失；就算硬點技術執行紀錄，右邊內容區塊也是一片空白 | |
| # （canvas_exec_col 同樣沒掛進 DOM，不是只缺標題文字）。4-C 的 | |
| # 「延一個 yield」技巧解的是另一種問題（曾經 True 過的元件被自動 | |
| # 還原），不適用在「這輩子第一次要 True」的元件上，兩者不能套 | |
| # 同一招。canvas_exec_col 跟著 result_nav_col 一起搬進第一個 | |
| # yield，也符合 nav_exec_btn 建構時刻意不設 interactive=False | |
| # 的原始設計意圖（見該按鈕附近註解：「技術執行紀錄……從第一秒 | |
| # 就有內容」，代表它從一開始就該是可點、有內容可看的狀態）。 | |
| yield ( | |
| gr.update(visible=False), # homepage_col | |
| gr.update(visible=True), # workspace_row | |
| gr.update(visible=True), # scenario_select_row | |
| gr.update(value=_build_header_html(current_step=1)), # app_header_html：站上第1步「研究選擇」 | |
| state, | |
| gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), # upload_row/metadata_row/canvas_idx/stat/report 留到下一個 yield | |
| gr.update(visible=True), # result_nav_col：第一次掛載必須跟祖先同一個 yield，見上方說明 | |
| gr.update(visible=True), # canvas_exec_col：同上，且從第一秒就該有內容可看 | |
| gr.update(), # nav_dl_group 留到第三個 yield | |
| ) | |
| # yield 2（4-C 補償，緊接著上一個 yield，同一個 generator/連線）： | |
| # 4-a：result_nav_col 這幾顆結果類項目本來就都是 disabled 狀態 | |
| # （要等對應結果產出才 enable，見 create_app 的 interactive=False | |
| # 與 _populate_tabs 的閘門，這批不動那個閘門邏輯），改成「進工作區 | |
| # 就顯示」只是讓使用者一開始就看得到完整的流程地圖，不是讓他們能 | |
| # 提前點。result_nav_col／canvas_exec_col 本身已在上一個 yield | |
| # 掛載完成，這裡不再重複設定（重複設 visible=True 無害，但沒必要）。 | |
| yield ( | |
| gr.update(), gr.update(), gr.update(), gr.update(), state, | |
| gr.update(visible=False), # upload_row | |
| gr.update(visible=False), # metadata_row | |
| gr.update(visible=False), # canvas_idx_col | |
| gr.update(visible=False), # canvas_stat_col | |
| gr.update(visible=False), # canvas_report_col | |
| gr.update(), # result_nav_col：已在第一個 yield 掛載完成，這裡不再重複設定 | |
| gr.update(), # canvas_exec_col：同上，這裡不再重複設定 | |
| gr.update(), # nav_dl_group 留到下一個 yield（見下方說明） | |
| ) | |
| # yield 3：nav_dl_group（下載捷徑那組分隔線＋四顆按鈕）住在 | |
| # result_nav_col 裡面，是比 result_nav_col 更深一層的子元件。 | |
| # result_nav_col 已在第一個 yield 翻成 visible=True，若 nav_dl_group | |
| # 太早跟著壓 False，會被同一種 still-mounted-snapback 蓋回舊值 | |
| # （跟 metadata_row 那組是同一條地雷，只是換了一層祖先/子元件）； | |
| # 這裡隔了兩個 yield 才動 nav_dl_group，比原本的一個 yield 間隔 | |
| # 更保守安全，之後有 zip 產出時 _populate_tabs 會自己把它翻回 | |
| # True，不受影響。 | |
| yield ( | |
| gr.update(), gr.update(), gr.update(), gr.update(), state, | |
| gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(), gr.update(), | |
| gr.update(visible=False), # nav_dl_group | |
| ) | |
| start_analysis_btn.click( | |
| fn=on_start_analysis_show, | |
| inputs=[session_state], | |
| outputs=[homepage_col, workspace_row, scenario_select_row, app_header_html, session_state, | |
| upload_row, metadata_row, canvas_idx_col, canvas_stat_col, canvas_report_col, | |
| result_nav_col, canvas_exec_col, nav_dl_group], | |
| ) | |
| # ── 文字送出（streaming generator）────────────────────────────────── | |
| # ── 研究情境選擇（封閉式固定四選一，按鈕直接觸發，不再解析打字輸入）── | |
| # Bug 4-C 補強（2026-07-30，驗證時發現）：Gradio 6 對「visible 曾經被 | |
| # 設過 True 的元件」有個比原本認知更棘手的行為——不是只有「祖先隱藏時 | |
| # 子元件的 update 被丟棄」，實測（掛 MutationObserver 追蹤 class 變化， | |
| # 確認是同一個 DOM 節點、不是重新掛載）發現：workspace_row 這個祖先 | |
| # 一旦從 visible=False 翻回 True（也就是這裡、使用者選情境的當下）， | |
| # 底下曾經被設過 True 的子元件（metadata_row／canvas_idx_col／ | |
| # canvas_stat_col／canvas_report_col——只要曾經因為真的走過一次上傳 | |
| # 確認／分析完成而被設成 visible=True）會被 Gradio 自動翻回 True， | |
| # 蓋掉 on_reset_clear_workspace 稍早設的 False，跟這次選情境的 | |
| # on_scenario_pick 本身完全無關。canvas_exec_col／result_nav_col | |
| # 不受影響，是因為下面第二個 yield 本來就會把它們重新設一次 True， | |
| # 剛好跟 Gradio 的還原值一致，看不出差異；file_input／computing_html | |
| # 也不受影響，因為它們動的是 value 不是 visible，不吃這個坑。 | |
| # 純靠 on_reset_confirm 那邊「藏起來」不夠可靠，唯一穩定的做法是在 | |
| # workspace_row 每次重新變 True 的這個時間點，主動把這四個「應該要 | |
| # 從乾淨狀態開始」的結果／表單容器重新設回 False，蓋過 Gradio 的還原 | |
| # 值，不管它是怎麼還原回來的。 | |
| def on_scenario_pick(sc_num, chat_history, log_history, state): | |
| if state is None: | |
| yield (chat_history, log_history, state, gr.update(), gr.update(), gr.update(), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update()) | |
| return | |
| sc_info = SCENARIOS[sc_num] | |
| chat_history = chat_history + [_user_msg(sc_info["title"])] | |
| log_history = _log_append(log_history, "使用者選擇研究情境中……") | |
| # 首頁一旦選定情境即隱藏，換成對話＋操作區（workspace_row）； | |
| # 結果導覽（result_nav_col）也在這時候一併顯示（雖然還沒有結果 | |
| # 可跳轉，但導覽列本身跟開始新分析按鈕一樣是常駐的操作區塊）。 | |
| # 技術執行紀錄（canvas_exec_col）跟著同一時間顯示——它從一開始 | |
| # 就有內容（這段 log 本身），不像其他三個結果頁要等運算完成才有 | |
| # 東西可看，不用透過 _populate_tabs 的檔案存在判斷來決定可見性。 | |
| # 這幾個 visibility 只需要在第一個 yield 就切換一次，後續 yield | |
| # 沿用 gr.update() 不動即可，不用每次都重複賦值。 | |
| yield (chat_history, log_history, state, gr.update(), gr.update(), gr.update(), | |
| gr.update(visible=False), gr.update(visible=True), gr.update(visible=True), | |
| gr.update(visible=True), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update()) | |
| reply, state = handle_scenario_select(sc_num, state) | |
| log_history = _log_append(log_history, "✅ 情境選擇完成") | |
| chat_history = chat_history + [_assistant_msg(reply)] | |
| # 4-C 補強：metadata_row／canvas_idx_col／canvas_stat_col／ | |
| # canvas_report_col 的重新隱藏刻意放在「跟 workspace_row 翻成 | |
| # visible=True 不同的一個 yield」，不是圖方便才分開寫。實測 | |
| # （MutationObserver 追蹤同一個 DOM 節點）發現：這幾個子元件若 | |
| # 曾經因為真的走過一次上傳確認／分析完成而被設成 visible=True， | |
| # Gradio 的前端會在 workspace_row 這個祖先「同一批訊息」翻回 | |
| # visible=True 的當下，把它們的舊 True 值蓋回來，跟這批訊息裡我們 | |
| # 自己對它們下的 visible=False 更新互相打架、我們的更新輸了。 | |
| # 等 workspace_row 的翻轉已經在前一個 yield 處理完、沉澱下來， | |
| # 這一個 yield 才不會再觸發同一種還原，我們的 False 才是最後贏家。 | |
| yield (chat_history, log_history, state, gr.update(), _todo_update(state), gr.update(), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(visible=False), gr.update(visible=False), gr.update(visible=False), | |
| gr.update(visible=False), | |
| gr.update()) | |
| # STEP 2 文本上傳（3-A：研究選擇搬進工作區成為正式第 1 步後， | |
| # 這裡的步驟編號全部 +1）：確認訊息已經導向上傳卡片的「格式要求」 | |
| # 區塊，不再另外用 LLM 生成一則重複格式細節的引導訊息，避免對話 | |
| # 視窗出現冗餘內容。這裡原本是獨立的「上傳引導」步驟，但它跟前一步 | |
| # 在同一個 generator 內連續完成、中間沒有任何使用者動作，步驟列上 | |
| # 永遠只會一起亮起，2026-07-23 併進「文本上傳」，只留等待上傳的 | |
| # 狀態切換。 | |
| state["current_step"] = 2 | |
| state["state"] = "UPLOAD_WAIT" | |
| log_history = _log_append(log_history, "⏳ 等待上傳文本……") | |
| # 情境已選定，研究選擇區塊收起、換上傳卡片出現。這個 yield 離 | |
| # workspace_row 自身的 True/False 翻轉已經隔了兩個 yield，不受 | |
| # 本函式上方記錄的 Gradio 6 still-mounted-snapback 地雷影響， | |
| # 可以放心跟其他更新同批。對話視窗自此回歸純輸出角色。格式要求 | |
| # 直接寫進上傳卡片本身（upload_hint_md），使用者不用往上捲回 | |
| # 對話視窗找 AI 剛剛說過的規則——卡片本身就要自己講清楚。 | |
| # 2026-08-22（見 docs/開發優化建議.md 第一節「研究語料傳送至第三方 | |
| # AI 服務的資料政策」）：上傳的文本內容會在報告撰寫階段組進 prompt | |
| # 送到 OpenRouter（再轉給實際供應商），先前介面完全沒有告知使用者 | |
| # 這件事。獨立成一段（不是格式要求清單的第 5 項），避免被當成單純 | |
| # 的檔案格式規定而略過不看——這是機密性提醒，性質跟前四項不同。 | |
| hint = ( | |
| f"**格式要求**\n\n{sc_info['upload_prompt']}\n\n" | |
| "---\n\n" | |
| "📢 **隱私提醒**：上傳的文本內容將傳送至第三方 AI 服務" | |
| "（OpenRouter 及其上游模型供應商）進行語言分析與報告撰寫。" | |
| "請確認語料不涉及尚未公開發表之機密內容，如有疑慮請先行確認後再上傳。" | |
| ) | |
| yield (chat_history, log_history, state, gr.update(visible=True), | |
| _todo_update(state), gr.update(value=hint), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(), gr.update(), gr.update(), gr.update(), | |
| gr.update(visible=False)) | |
| for _sc_num, _sc_btn in (("1", sc_btn_1), ("2", sc_btn_2), ("3", sc_btn_3), ("4", sc_btn_4)): | |
| _sc_btn.click( | |
| fn=functools.partial(on_scenario_pick, _sc_num), | |
| inputs=[chatbot, exec_log, session_state], | |
| outputs=[chatbot, exec_log, session_state, upload_row, app_header_html, | |
| upload_hint_md, homepage_col, workspace_row, result_nav_col, canvas_exec_col, | |
| metadata_row, canvas_idx_col, canvas_stat_col, canvas_report_col, | |
| scenario_select_row], | |
| ).then( | |
| fn=_populate_tabs, | |
| inputs=[session_state], | |
| outputs=_TAB_OUTPUTS, | |
| ) | |
| # ── 「開始新分析」：Bug1 修復——選定情境後先前完全沒有任何路徑能 | |
| # 回頭變更，使用者選錯情境後卡住。這裡補上共用的重置機制：換情境 | |
| # ＝重新開始，統一走這顆按鈕回到首頁重新選（不恢復對話框打字選 | |
| # 情境的舊路徑）──────────────────────────────────────────────── | |
| # Bug 4-C 修復（2026-07-30）：Gradio 6 的 gr.Column/Row(visible=False) | |
| # 會把子元件整段從 DOM 卸載，不只是 CSS 隱藏。原本 on_reset_confirm | |
| # 在同一個 return 裡，一邊把 workspace_row 設 visible=False，一邊又要 | |
| # 重置住在 workspace_row 內部的子元件（metadata_row/file_input/ | |
| # canvas_*_col/computing_html/result_nav_col）——這些子元件那一刻 | |
| # 已經被卸載，重置的 update 會被靜默丟棄，於是 metadata_row 帶著 | |
| # 上一輪 _show_metadata_form 設的 visible=True 回來，file_input 也還 | |
| # 留著舊檔案，就是使用者回報「重置後再進工作區，殘留上一輪畫面」的 | |
| # 根因。修法：拆成兩個串接的獨立事件。第一個事件 | |
| # （on_reset_clear_workspace）沒有 inputs，只做「藏起來／清空」， | |
| # 在 workspace_row 還可見、子元件仍掛載的當下執行，update 才會生效； | |
| # 第二個事件（沿用原名 on_reset_confirm）才把 workspace_row 本身 | |
| # 連同首頁切換一起做掉，session_state 的重建（make_initial_state） | |
| # 也留在這一支。兩支的 outputs 清單不重疊。 | |
| def on_reset_clear_workspace(): | |
| # Phase 11 回歸測試（2026-08-05）發現：情境 3/4 的語料 Metadata | |
| # 表單自由文字欄位與「群組數量」/「比較方式」單選，重置後從未被 | |
| # 清空過——因為它們是獨立於 state 之外的 Gradio 元件值， | |
| # on_reset_confirm 原本只重建 session_state，沒有任何地方碰過 | |
| # 這幾個元件。實測重現：填過一次「原文標題」、選過「三群」後 | |
| # 回首頁重新開始，下一輪（即使換了完全不同的情境／檔案數） | |
| # 這些欄位還是顯示上一輪的舊值。群組層/個體層表格不受影響， | |
| # 因為 _show_metadata_form 每次都會依當下上傳結果重新整份覆蓋。 | |
| # 清空動作放在這一支（而非 on_reset_confirm）：跟本函式其餘欄位 | |
| # 同一個理由，metadata_row 這批子元件此刻仍掛載在可見的 | |
| # workspace_row 底下，update 才會生效。 | |
| return ( | |
| gr.update(visible=False), # metadata_row | |
| gr.update(value=None), # file_input（Phase 8：upload_row 變正式入口後一併清空） | |
| gr.update(visible=False), # canvas_idx_col 語言指標分析 | |
| gr.update(visible=False), # canvas_stat_col 統計比較分析 | |
| gr.update(visible=False), # canvas_report_col LLM輔助分析 | |
| gr.update(visible=False), # canvas_exec_col 技術執行紀錄（2026-07-23 轉正後，跟其他三個結果頁一樣重置為隱藏） | |
| gr.update(value=""), # computing_html（Phase 8-D：中途重置要清掉運算中提示） | |
| gr.update(visible=False), # result_nav_col（Phase 8-D：重新開始＝回到首頁，導覽收起） | |
| gr.update(value=""), # upload_progress_html（3-C：中途重置要清掉上傳進度提示，同 computing_html） | |
| gr.update(value=""), # meta_title | |
| gr.update(value=""), # meta_author | |
| gr.update(value=""), # meta_lang | |
| gr.update(value=""), # meta_pubyear | |
| gr.update(value=""), # meta_version | |
| gr.update(value="二群"), # meta_ngroups（元件宣告時的預設值） | |
| gr.update(value="群組間比較"), # meta_method（元件宣告時的預設值） | |
| # 2026-08-12：結果導覽的 A2 閘門要一起關回去。這幾顆在 | |
| # _populate_tabs 產出結果時被打開（interactive=True），但重置 | |
| # 從來沒有關回來——實測重置後回到全新首頁，「語言指標分析」等 | |
| # 項目仍是可點狀態，點下去是一片空白的結果頁。 | |
| *([gr.update(interactive=False)] * len(_TAB_NAV_GATES)), | |
| ) | |
| def on_reset_confirm(): | |
| sid = str(uuid.uuid4())[:8] | |
| state = make_initial_state(sid) | |
| # 2026-07-31（Batch E 第 4-d 項）：同 on_load_ready，拿掉 | |
| # 「(或下方)」，兩處歡迎詞要保持一致。 | |
| intro = ( | |
| "歡迎使用 TransPrism II 分析引擎 SpectraEngine。\n\n" | |
| "請依照您的研究設計，點選右方最符合的研究情境開始分析：" | |
| ) | |
| new_log = f"{_ts()} 已重新開始分析。" | |
| return ( | |
| [_assistant_msg(intro)], # chatbot | |
| new_log, # exec_log | |
| state, # session_state | |
| gr.update(value=_build_header_html()), # app_header_html | |
| gr.update(visible=False), # upload_row（Phase 8：正式上傳入口改這張卡片） | |
| gr.update(visible=False), # reset_confirm_row（關掉確認彈窗自己） | |
| gr.update(visible=True), # homepage_col（Phase 8：重新開始＝回到首頁選情境） | |
| gr.update(visible=False), # workspace_row | |
| ) | |
| reset_btn.click(fn=lambda: gr.update(visible=True), outputs=[reset_confirm_row]) | |
| reset_cancel_btn.click(fn=lambda: gr.update(visible=False), outputs=[reset_confirm_row]) | |
| about_btn.click(fn=lambda: gr.update(visible=True), outputs=[about_overlay]) | |
| about_close_btn.click(fn=lambda: gr.update(visible=False), outputs=[about_overlay]) | |
| # 2026-08-12：reset_confirm_btn 的接線搬到檔案最後（見 create_app 結尾 | |
| # 「重置接線」那段）。原因：它需要 cancels=[分析運算那兩條事件鏈]，而 | |
| # 那兩條要等 meta_confirm_btn／meta_cancel_btn 接完才存在。Gradio 的 | |
| # 接線順序不影響行為，只有 cancels 需要拿到事件物件，所以往後搬。 | |
| # ── 檔案上傳確認（streaming generator）────────────────────────────── | |
| def on_upload_confirm(files, chat_history, log_history, state): | |
| if not files or state is None: | |
| yield chat_history, log_history, state, gr.update(visible=True), gr.update(), gr.update() | |
| return | |
| # 2026-08-22（業主回報：對話視窗兩則 AI 訊息之間沒有使用者自己的 | |
| # 發言氣泡，看起來像 AI 自問自答）：在流程真正開始處理之前，先補一則 | |
| # 使用者訊息氣泡，把「使用者上傳了哪些檔案」呈現出來，對話才有一來 | |
| # 一往的感覺。 | |
| # 2026-08-24（業主建議）：若同一情境下、前一次「確認上傳」的格式驗證 | |
| # 失敗過，這次再按確認上傳就不是「第一次上傳」，而是使用者刪掉檔案、 | |
| # 修正後重新送出——文字改成「重新上傳了」更貼近實際發生的事，讀者 | |
| # 事後看對話紀錄也更容易理解「這是一次修正後的重試」。判斷時機要在 | |
| # 下面把 state["upload"]["validate"]["status"] 覆寫成 "pending" 之前 | |
| # 讀，不然永遠讀到剛被蓋掉的新值。換情境重來（on_back_to_scenario） | |
| # 會把這個狀態重置回 "pending"，避免換情境後的第一次上傳被誤標成 | |
| # 「重新上傳」。 | |
| _is_retry = state.get("upload", {}).get("validate", {}).get("status") == "failed" | |
| _uploaded_names = [Path(f.name if hasattr(f, "name") else str(f)).name for f in files] | |
| _verb = "重新上傳了" if _is_retry else "上傳了" | |
| chat_history = chat_history + [_user_msg(f"{_verb} {len(_uploaded_names)} 個檔案：{'、'.join(_uploaded_names)}")] | |
| # 文本上傳（step 2：3-A 新增「研究選擇」為第 1 步後，這裡的步驟 | |
| # 編號全部 +1）：開始處理即關閉上傳彈窗，避免遮罩擋住操作。 | |
| # 3-C：同時把「檔案接收」子階段標成 running，寫進 upload_progress_html | |
| # ——業主回報「上傳過程都一片白，只在對話視窗出現文字氣泡，用戶會 | |
| # 不知道發生什麼事」，這裡讓內容區塊跟技術執行紀錄同步顯示進度。 | |
| state["current_step"] = 2 | |
| state["upload"]["receive"]["status"] = "running" | |
| state["upload"]["receive"]["line"] = "接收上傳檔案中……" | |
| state["upload"]["validate"]["status"] = "pending" | |
| state["upload"]["validate"]["line"] = "" | |
| log_history = _log_append(log_history, "⏳ 接收上傳檔案中……") | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), _upload_update(state)) | |
| recv_msg, state = handle_uploaded_files(files, state) | |
| chat_history = chat_history + [_assistant_msg(recv_msg)] | |
| state["upload"]["receive"]["status"] = "done" | |
| state["upload"]["receive"]["line"] = f"已接收 {len(files)} 個檔案" | |
| log_history = _log_append(log_history, f"✅ 已接收 {len(files)} 個檔案") | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), _upload_update(state)) | |
| # 格式驗證：2026-07-24 起不再是獨立步驟（見 _STEPS 註解），只是「文本 | |
| # 上傳」這一步內部的一道處理，逐行進技術執行紀錄，不動步驟列。step 2 | |
| # 在格式驗證通過後才標 done——通過前維持「進行中」，失敗時原地留著要求 | |
| # 重新上傳，畫面與步驟列不會互相矛盾。 | |
| state["upload"]["validate"]["status"] = "running" | |
| state["upload"]["validate"]["line"] = "格式驗證中……" | |
| log_history = _log_append(log_history, "⏳ 格式驗證中……") | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), _upload_update(state)) | |
| check_msg, state, has_errors = run_format_check(state) | |
| chat_history = chat_history + [_assistant_msg(check_msg)] | |
| if has_errors: | |
| state["upload"]["validate"]["status"] = "failed" | |
| state["upload"]["validate"]["line"] = "格式不符，請重新上傳" | |
| log_history = _log_append(log_history, "⚠️ 格式不符，請重新上傳") | |
| state["current_step"] = 2 | |
| yield (chat_history, log_history, state, gr.update(visible=True), | |
| _todo_update(state), _upload_update(state)) | |
| return | |
| state["upload"]["validate"]["status"] = "done" | |
| state["upload"]["validate"]["line"] = "格式驗證通過" | |
| state["done_steps"] = list(set(state.get("done_steps", []) + [2])) | |
| state["current_step"] = 3 | |
| log_history = _log_append(log_history, "✅ 格式驗證通過") | |
| # 格式通過後：顯示 metadata 說明表單（語料說明＝step 3），等使用者填寫 | |
| state["state"] = "METADATA_INPUT" | |
| meta_hint = "請填寫語料說明（原文資訊、群組層與個體層），完成後點「確認並開始分析」。" | |
| chat_history = chat_history + [_assistant_msg(meta_hint)] | |
| log_history = _log_append(log_history, "📑 請填寫語料說明") | |
| # 2026-07-31（Batch E 第 5、6 項）：業主回報「語料說明」「分析 | |
| # 運算」兩步驟畫面上還留著「文本上傳」的進度區塊（檔案接收 ✓／ | |
| # 格式驗證 ✓），流程往下推進後這塊資訊已經沒用。清空的時機點 | |
| # 選在這裡（格式驗證成功、正要進「語料說明」的這個 yield）： | |
| # 往前推進的唯一入口只有這條成功路徑，往後 metadata 表單出現時 | |
| # upload_progress_html 就已經是空字串；格式驗證失敗那條路徑 | |
| # （上面 has_errors 分支）維持呼叫 _upload_update(state)、繼續 | |
| # 停在文本上傳步驟，不會被這裡影響——那時使用者正需要看到失敗 | |
| # 在哪一段。往後「分析運算」步驟本身不會再寫這個元件的值（見 | |
| # _run_computation 的 yield 沒有 upload_progress_html），空字串 | |
| # 會一路帶到分析運算步驟，不需要在那裡另外清一次。跟 computing_html | |
| # 同一種「空字串＝不顯示」語意，直接設空字串，不用改動 state。 | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), gr.update(value="")) | |
| # ── metadata 表單 helpers ─────────────────────────────────────────── | |
| def _build_meta_tables(state): | |
| import os | |
| files = [os.path.basename(p) for p in state.get("cleaned_files", [])] | |
| groups = sorted(set(f[0].upper() for f in files if f)) | |
| # 2026-08-15：群組層改成三組獨立 Textbox 後，這裡不再需要組出 | |
| # Dataframe 的初始列資料，只需要回傳實際偵測到的分組代碼清單 | |
| # （給 _show_metadata_form 決定顯示幾組、標題寫哪個代碼）。 | |
| return groups, [[f, "", "", "", ""] for f in files] | |
| def _df_rows(dfval): | |
| try: | |
| if isinstance(dfval, pd.DataFrame): | |
| return dfval.fillna("").values.tolist() | |
| if isinstance(dfval, dict) and "data" in dfval: | |
| return dfval["data"] | |
| if isinstance(dfval, list): | |
| return dfval | |
| except Exception: | |
| pass | |
| return [] | |
| def _extract_individual_grouping(indiv_rows, method): | |
| """個體間比較模式下，把「個體層資訊」表格整理成 {檔名: 分組標籤} | |
| dict，交給 run_statistical_analysis 取代預設的檔名字首分組 | |
| （2026-08-15 業主要求：選「個體間比較」時，個體層資訊要真的 | |
| 影響分析，不能只是寫進 metadata 文字給 LLM 參考）。 | |
| method 不是「個體間比較」時一律回傳空 dict——run_statistical_ | |
| analysis 收到空 dict 等同沒收到，完全不影響現行「群組間比較」 | |
| 的行為。 | |
| 2026-08-15 二版（業主糾正）：「個體間比較」的定義是逐檔案比較， | |
| 不能因為「譯者／系統名稱」剛好打一樣（例如同一位譯者的多篇 | |
| 譯本）就把檔案合併成同一組——那樣等於又退回群組比較，跟 | |
| 「個體間」的字面意思矛盾。這裡改成：同一個名稱出現在多個檔案 | |
| 時，自動用「出版年」加註消歧義（沒填出版年就退而求其次用 | |
| 「重譯序位」，兩者都沒填則直接用檔名本身墊底）——不管怎樣都 | |
| 保證每個檔案分到獨一無二的組，絕不因為名稱撞名而合併。 | |
| 欄位索引對應目前的「個體層」表格：0=檔案、1=譯者／系統名稱、 | |
| 2=出版年、3=譯者母語、4=重譯序位（見上方 meta_indiv_df 宣告， | |
| 2026-08-15 拿掉「後編輯程度」後的新欄位順序）。""" | |
| if method != "個體間比較": | |
| return {} | |
| entries = [] # (檔名, 名稱, 出版年, 重譯序位) | |
| for row in indiv_rows: | |
| if not row or len(row) < 2: | |
| continue | |
| fname = str(row[0]).strip() | |
| name = str(row[1]).strip() | |
| year = str(row[2]).strip() if len(row) > 2 else "" | |
| seq = str(row[4]).strip() if len(row) > 4 else "" | |
| if fname and name: | |
| entries.append((fname, name, year, seq)) | |
| name_counts = {} | |
| for _, name, _, _ in entries: | |
| name_counts[name] = name_counts.get(name, 0) + 1 | |
| mapping = {} | |
| for fname, name, year, seq in entries: | |
| if name_counts[name] > 1: | |
| disambiguator = year or seq or fname | |
| mapping[fname] = f"{name}（{disambiguator}）" | |
| else: | |
| mapping[fname] = name | |
| return mapping | |
| def _compile_metadata(state, title, author, lang, pubyear, version, | |
| ngroups, method, group_field_values, indiv_df): | |
| """group_field_values：長度 15 的 list，三組 × 5 欄 | |
| （群組標籤／翻譯類型／翻譯方向／譯者背景／目標讀者）攤平排列， | |
| 對應 meta_group_fields 三個 slot、各自 5 個 Textbox 的值。""" | |
| sc = state.get("scenario", "") | |
| L = ["## 語料說明", "", | |
| "### 原文資訊", | |
| f"- 原文標題：{title or '（未填）'}", | |
| f"- 作者：{author or '（未填）'}", | |
| f"- 語言：{lang or '（未填）'}", | |
| f"- 出版年：{pubyear or '（未填）'}", | |
| f"- 版本：{version or '（未填）'}", ""] | |
| if sc in ("3", "4"): | |
| L += ["### 比較結構", | |
| f"- 群組數量：{ngroups}", | |
| f"- 比較方式：{method}", ""] | |
| gh = ["群組標籤", "翻譯類型", "翻譯方向", "譯者背景", "目標讀者"] | |
| # 2026-08-15：每組資訊前面明確標上實際分組代碼（「群組 A：...」）， | |
| # 不再只是無標籤的一條條列點——LLM 之前因為看不出這行屬於哪個 | |
| # 分組代碼，把 A／B 的標籤講反過一次（見待辦記錄），這裡從資料 | |
| # 來源端直接堵掉這個歧義。 | |
| codes = sorted(set(Path(fp).name[0].upper() | |
| for fp in state.get("cleaned_files", []) if fp)) | |
| slots = [group_field_values[i*5:(i+1)*5] for i in range(3)] | |
| L += ["### 群組層資訊"] | |
| for code, vals in zip(codes, slots): | |
| filled = [f"{h}：{str(v).strip()}" for h, v in zip(gh, vals) if str(v).strip()] | |
| if filled: | |
| L.append(f"- 群組 {code}：" + "；".join(filled)) | |
| ih = ["檔案", "譯者／系統名稱", "出版年", "譯者母語", "重譯序位"] | |
| L += ["", "### 個體層資訊"] | |
| for r in _df_rows(indiv_df): | |
| if not any(str(c).strip() for c in r): | |
| continue | |
| L.append("- " + "；".join(f"{h}：{str(v).strip()}" for h, v in zip(ih, r) if str(v).strip())) | |
| return "\n".join(L) | |
| def _extract_group_labels(state, group_field_values): | |
| """把三組群組標籤 Textbox 的值整理成 {分組代碼: 使用者填的標籤} | |
| dict，供差異性分析文字／箱形圖 X 軸使用。group_field_values 是 | |
| 長度 15 的攤平 list（見 _compile_metadata），每組取第 0 欄 | |
| （群組標籤）。 | |
| 對應規則是「位置對位置」：_show_metadata_form() 是照 | |
| sorted(群組代碼) 的順序把代碼填進每個 slot 的標題（例如 | |
| 「組別 A」），使用者在該 slot 底下的「群組標籤」欄位填的內容 | |
| 就對應那個代碼——沒填或原樣留著代碼本身的 slot 視同沒填， | |
| 呈現時退回代碼本身。""" | |
| try: | |
| codes = sorted(set(Path(fp).name[0].upper() | |
| for fp in state.get("cleaned_files", []) if fp)) | |
| slot_labels = [group_field_values[i*5] for i in range(3)] | |
| labels = {} | |
| for code, label in zip(codes, slot_labels): | |
| label = str(label or "").strip() | |
| if label and label != code: | |
| labels[code] = label | |
| return labels | |
| except Exception: | |
| return {} | |
| def _run_computation(chat_history, log_history, state): | |
| # 2026-07-23：技術執行紀錄轉正成獨立頁面後，可見性只在情境選定 | |
| # （on_scenario_pick）與重置（on_reset_confirm）時切換一次， | |
| # 這裡不用再逐步更新開合狀態／摘要標籤，改回傳 gr.update() 不動。 | |
| # 「語料說明」(step 3：2026-07-30 新增「研究選擇」為第 1 步後， | |
| # 這裡的步驟編號全部 +1) 在這裡收尾：confirm 與 skip 兩條路徑都會 | |
| # 走進 _run_computation，標記在這一處就好，不用在兩個 handler 各寫 | |
| # 一次。2026-07-24 步驟列收斂到 3 步時是語料說明＝2、分析運算＝3； | |
| # 分析運算是單一步驟，底下三個子階段的細狀態改由 state["analysis"] | |
| # 承載（見 run_computation_pipeline_streaming），這裡不再逐段搬動 | |
| # current_step，只在最後依子階段結果決定第 4 步是 done 還是 failed。 | |
| state["done_steps"] = list(set(state.get("done_steps", []) + [3])) | |
| state["current_step"] = 4 | |
| log_history = _log_append(log_history, "⏳ 分析運算開始……") | |
| # Bug 4-A 修復（2026-07-30）：報告撰寫佔掉幾乎全部等待時間 | |
| # （30-90 秒以上），原本 _populate_tabs 只掛在整段 generator 跑完 | |
| # 後的 .then()，指標計算／統計分析早就做完，使用者卻要等報告 | |
| # 撰寫也結束才看得到——內容區塊的「查看…」連結點了沒反應、左側 | |
| # 導覽也還是 disabled。改成用 _no_tab_change 當預設（大部分 yield | |
| # 不動 _TAB_OUTPUTS），只在下面偵測到某個子階段「剛轉成 done」時 | |
| # 才呼叫一次 _populate_tabs，把當下已完成的結果併進這次 yield。 | |
| _no_tab_change = [gr.update()] * _N_TAB | |
| yield (chat_history, log_history, state, _todo_update(state), | |
| gr.update(), _computing_update(state), *_no_tab_change) | |
| # 記錄每個子階段「上一次看到的狀態是不是 done」，跟目前狀態比對 | |
| # 才知道是不是「剛」轉成 done——避免同一階段已經 done 之後，後面 | |
| # 每個 yield（例如下一階段的 running/done）都重複呼叫一次 | |
| # _populate_tabs（它會讀 CSV、複製 docx、打包 zip，很浪費）。 | |
| prev_done = {k: False for k, _, _ in _ANALYSIS_STAGES} | |
| for prog_msg, is_final, state in run_computation_pipeline_streaming(state): | |
| log_history = _log_append(log_history, prog_msg) | |
| if is_final: | |
| chat_history = chat_history + [_assistant_msg(prog_msg)] | |
| # 三個子階段任一失敗 → 第 4 步標紅（頂部步驟列據實呈現， | |
| # 內容區塊講清楚壞在哪一段）；全部成功才標 ✓。 | |
| stages_failed = any( | |
| state["analysis"][k]["status"] == "failed" for k, _, _ in _ANALYSIS_STAGES | |
| ) | |
| state["current_step"] = None | |
| if stages_failed: | |
| state["failed_step"] = 4 | |
| else: | |
| state["done_steps"] = list(set(state.get("done_steps", []) + [4])) | |
| newly_done = False | |
| for k, _, _ in _ANALYSIS_STAGES: | |
| is_done = state["analysis"][k]["status"] == "done" | |
| if is_done and not prev_done[k]: | |
| newly_done = True | |
| prev_done[k] = is_done | |
| tab_updates = _populate_tabs(state) if newly_done else _no_tab_change | |
| yield (chat_history, log_history, state, _todo_update(state), | |
| gr.update(), _computing_update(state), *tab_updates) | |
| # 3（metadata_row）+ 21（3 組 × [欄位可見性, 標題, 5 個 Textbox]） | |
| # + 1（indiv_df）+ 1（compare_group 可見性） | |
| _N_META_FORM_OUTPUTS = 1 + 3 * 7 + 1 + 1 | |
| def _show_metadata_form(state): | |
| _NO = gr.update() | |
| if not state or state.get("state") != "METADATA_INPUT": | |
| return (_NO,) * _N_META_FORM_OUTPUTS | |
| groups, indiv_rows = _build_meta_tables(state) | |
| show_cmp = state.get("scenario", "") in ("3", "4") | |
| group_updates = [] | |
| for i in range(3): | |
| if i < len(groups): | |
| group_updates.append(gr.update(visible=True)) | |
| group_updates.append(gr.update(value=f"組別 {groups[i]}")) | |
| group_updates += [gr.update(value="")] * 5 # 清空上一輪可能殘留的舊值 | |
| else: | |
| group_updates.append(gr.update(visible=False)) | |
| group_updates += [_NO] * 6 # 隱藏中，標題／欄位不用動 | |
| return (gr.update(visible=True), *group_updates, | |
| gr.update(value=indiv_rows), gr.update(visible=show_cmp)) | |
| # 送出期間鎖住按鈕避免重複點擊（2026-07-24 取消鈕移除後只剩確認鈕一顆） | |
| def _lock_upload(): | |
| return gr.update(interactive=False) | |
| def _unlock_upload(): | |
| return gr.update(interactive=True) | |
| upload_btn.click( | |
| fn=_lock_upload, inputs=None, outputs=[upload_btn], | |
| ).then( | |
| fn=on_upload_confirm, | |
| inputs=[file_input, chatbot, exec_log, session_state], | |
| outputs=[chatbot, exec_log, session_state, upload_row, app_header_html, upload_progress_html], | |
| ).then( | |
| fn=_unlock_upload, inputs=None, outputs=[upload_btn], | |
| ).then( | |
| fn=_show_metadata_form, | |
| inputs=[session_state], | |
| outputs=[metadata_row, | |
| *[c for i in range(3) | |
| for c in [meta_group_cols[i], meta_group_heads[i], *meta_group_fields[i]]], | |
| meta_indiv_df, meta_compare_group], | |
| ) | |
| # 2026-07-31（Batch G 第 1 項）：「重新選擇研究情境」返回鈕。叫回 | |
| # scenario_select_row、收起 upload_row，步驟列退回「① 研究選擇 | |
| # 進行中」（done_steps 拿掉 1、current_step 設回 1）。session 不重置 | |
| # （不呼叫 make_initial_state，沿用同一個 session_id），跟「回首頁」 | |
| # 是兩件不同的事。 | |
| # | |
| # 這裡「不需要」像 on_start_analysis_show／on_reset_clear_workspace | |
| # 那樣拆成多個 yield／.then()：scenario_select_row、upload_row、 | |
| # upload_progress_html 都是「已顯示」的 workspace_row 底下的兄弟節點， | |
| # 這次改動完全沒有動到 workspace_row 本身的可見性（它從頭到尾都是 | |
| # visible=True），所以不會踩本檔開頭記錄的 Gradio 6 地雷（該地雷只在 | |
| # 「祖先容器」從 visible=False 翻回 True 那一刻才會發生）。放同一批 | |
| # gr.update() 即可，不要照抄「回首頁」那套分批模式。 | |
| # | |
| # 檔案清單清空是正確性問題，不是體驗問題：研究情境決定允許的檔名 | |
| # 字首（情境 1、2 只收 A_/B_；情境 3、4 才收 C_），使用者若在情境 3 | |
| # 傳了 C_xx.txt 後改選情境 1，那個檔案會變成不合法卻還留在清單裡。 | |
| # state["uploaded_files"]／state["cleaned_files"] 與 file_input 的 | |
| # value 都要清空，upload_progress_html 也要清成空字串（回到「尚未 | |
| # 上傳」的初始語意，跟 _build_upload_html 對空字串的既有語意一致）。 | |
| def on_back_to_scenario(state): | |
| if state is None: | |
| return (gr.update(visible=True), gr.update(visible=False), gr.update(), | |
| gr.update(value=None), gr.update(value=""), state) | |
| state["uploaded_files"] = [] | |
| state["cleaned_files"] = [] | |
| state["current_step"] = 1 | |
| state["done_steps"] = [s for s in state.get("done_steps", []) if s != 1] | |
| # 2026-08-24：換情境重來時，上一個情境若曾經格式驗證失敗過，這裡要 | |
| # 把狀態重置回初始值，不然換到新情境後的第一次上傳會被 on_upload_ | |
| # confirm 誤判成「重新上傳」（見該處 _is_retry 判斷邏輯）。 | |
| state["upload"] = { | |
| "receive": {"status": "pending", "line": ""}, | |
| "validate": {"status": "pending", "line": ""}, | |
| } | |
| return ( | |
| gr.update(visible=True), # scenario_select_row | |
| gr.update(visible=False), # upload_row | |
| gr.update(value=_build_header_html(state["done_steps"], current_step=1)), # app_header_html | |
| gr.update(value=None), # file_input：清空已選檔案 | |
| gr.update(value=""), # upload_progress_html：清掉上一輪的上傳進度卡片 | |
| state, | |
| ) | |
| back_to_scenario_btn.click( | |
| fn=on_back_to_scenario, | |
| inputs=[session_state], | |
| outputs=[scenario_select_row, upload_row, app_header_html, file_input, upload_progress_html, session_state], | |
| ) | |
| # 2026-07-24（E2）：這裡原本有 on_chat_upload_submit（Phase 7 的 | |
| # MultimodalTextbox 轉接生成器），Phase 8 對話框改回純展示後就沒有任何 | |
| # 地方呼叫它，屬死碼，已移除。之後若對話框要恢復接上傳，直接在 chat_upload | |
| # 的 .submit() 包一層拆 {"files":[...]} 丟給 on_upload_confirm 即可。 | |
| _ANALYSIS_START_MSG = ( | |
| "已收到，開始計算語言指標與統計分析，這個步驟可能需要數分鐘，請耐心等候……\n" | |
| "（可於下方「技術執行紀錄」查看執行進度）" | |
| ) | |
| def on_metadata_confirm(title, author, lang, pubyear, version, | |
| ngroups, method, | |
| g1_label, g1_type, g1_dir, g1_bg, g1_aud, | |
| g2_label, g2_type, g2_dir, g2_bg, g2_aud, | |
| g3_label, g3_type, g3_dir, g3_bg, g3_aud, | |
| indiv_df, | |
| chat_history, log_history, state): | |
| group_field_values = [g1_label, g1_type, g1_dir, g1_bg, g1_aud, | |
| g2_label, g2_type, g2_dir, g2_bg, g2_aud, | |
| g3_label, g3_type, g3_dir, g3_bg, g3_aud] | |
| # Bug 4-A 修復（2026-07-30）：outputs 併入 _TAB_OUTPUTS（見下方 | |
| # wiring），generator 的每個 yield 元素個數都要跟 outputs 長度 | |
| # 完全一致——這裡先包一份「_TAB_OUTPUTS 全部不動」的預設值， | |
| # 沒有新結果的 yield（early return／running 中）直接複用它。 | |
| _no_tabs = [gr.update()] * _N_TAB | |
| if state is None: | |
| yield (chat_history, log_history, state, gr.update(), _todo_update(state), | |
| gr.update(), gr.update(), *_no_tabs) | |
| return | |
| # 群組數量跟實際上傳分組是否一致：只有情境3/4才會顯示這個選項， | |
| # 情境1/2固定二群沒有歧義不用檢查。時序上這個檢查沒辦法併進 | |
| # run_format_check（使用者選二群/三群是在格式驗證通過之後才填）， | |
| # 所以在這裡另開一道檢查點，不一致就擋下、留在表單讓使用者確認 | |
| if state.get("scenario") in ("3", "4"): | |
| actual_prefixes = {Path(fp).name[0].upper() for fp in state.get("cleaned_files", [])} | |
| expected_count = 3 if ngroups == "三群" else 2 | |
| if len(actual_prefixes) != expected_count: | |
| warn_msg = ( | |
| f"⚠️ 您選擇「{ngroups}」，但實際上傳的檔案偵測到 " | |
| f"{len(actual_prefixes)} 組（{'、'.join(sorted(actual_prefixes)) or '無'}），" | |
| "請確認群組數量與上傳檔案是否一致後再送出。" | |
| ) | |
| chat_history = chat_history + [_assistant_msg(warn_msg)] | |
| log_history = _log_append(log_history, "⚠️ 群組數量與上傳檔案不一致") | |
| yield (chat_history, log_history, state, gr.update(visible=True), | |
| _todo_update(state), gr.update(), gr.update(), *_no_tabs) | |
| return | |
| state["user_metadata"] = _compile_metadata(state, title, author, lang, pubyear, | |
| version, ngroups, method, group_field_values, indiv_df) | |
| state["group_labels"] = _extract_group_labels(state, group_field_values) | |
| state["individual_grouping"] = _extract_individual_grouping(_df_rows(indiv_df), method) | |
| log_history = _log_append(log_history, "✅ 已記錄語料說明，開始分析") | |
| # 2026-08-22：同上傳檔案那段，補一則使用者訊息氣泡，呈現「使用者 | |
| # 填寫完語料說明並送出」這個動作，避免對話看起來像 AI 自問自答。 | |
| chat_history = chat_history + [_user_msg("已送出語料說明（原文資訊、群組層與個體層），請開始分析")] | |
| # 在主對話視窗立即顯示「開始分析」訊息，避免長時間運算期間畫面看起來像沒有反應 | |
| chat_history = chat_history + [_assistant_msg(_ANALYSIS_START_MSG)] | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), gr.update(), _computing_update(state), *_no_tabs) | |
| # _run_computation 現在也 yield _TAB_OUTPUTS 那一份（見該函式 | |
| # 2026-07-30 註解），用 *tabs 原樣轉發，不在這裡重新組裝 | |
| for ch, lh, st, todo, acc, comp, *tabs in _run_computation(chat_history, log_history, state): | |
| chat_history, log_history, state = ch, lh, st | |
| yield (chat_history, log_history, state, gr.update(visible=False), todo, acc, comp, *tabs) | |
| def _lock_meta(): | |
| return gr.update(interactive=False), gr.update(interactive=False) | |
| def _unlock_meta(): | |
| return gr.update(interactive=True), gr.update(interactive=True) | |
| confirm_run_evt = meta_confirm_btn.click( | |
| fn=_lock_meta, inputs=None, outputs=[meta_confirm_btn, meta_cancel_btn], | |
| ).then( | |
| fn=on_metadata_confirm, | |
| inputs=[meta_title, meta_author, meta_lang, meta_pubyear, meta_version, | |
| meta_ngroups, meta_method, | |
| *meta_group_fields[0], *meta_group_fields[1], *meta_group_fields[2], | |
| meta_indiv_df, | |
| chatbot, exec_log, session_state], | |
| # Bug 4-A 修復（2026-07-30）：併入 _TAB_OUTPUTS，讓 on_metadata_confirm | |
| # 能在 streaming 過程中（不用等這條 .then() 鏈跑到最後）就把已完成 | |
| # 子階段的結果 populate 進畫面。結尾這顆 _populate_tabs 仍保留， | |
| # 收尾時做一次完整填充（例如 zip 打包這種只需最後做一次的事）。 | |
| outputs=[chatbot, exec_log, session_state, metadata_row, app_header_html, | |
| canvas_exec_col, computing_html, *_TAB_OUTPUTS], | |
| ).then( | |
| fn=_unlock_meta, inputs=None, outputs=[meta_confirm_btn, meta_cancel_btn], | |
| ).then(fn=_populate_tabs, inputs=[session_state], outputs=_TAB_OUTPUTS) | |
| def on_metadata_skip(chat_history, log_history, state): | |
| # 同 on_metadata_confirm，outputs 併入 _TAB_OUTPUTS 後每個 yield | |
| # 都要補滿這份長度，見該處 2026-07-30 註解。 | |
| _no_tabs = [gr.update()] * _N_TAB | |
| if state is None: | |
| yield (chat_history, log_history, state, gr.update(), _todo_update(state), | |
| gr.update(), gr.update(), *_no_tabs) | |
| return | |
| state["user_metadata"] = state.get("user_metadata", "") or "（使用者未提供語料說明）" | |
| log_history = _log_append(log_history, "⏭️ 已略過語料說明，直接開始分析") | |
| # 2026-08-22：同 on_metadata_confirm，補使用者訊息氣泡（略過版本）。 | |
| chat_history = chat_history + [_user_msg("略過填寫，直接開始分析")] | |
| chat_history = chat_history + [_assistant_msg(_ANALYSIS_START_MSG)] | |
| yield (chat_history, log_history, state, gr.update(visible=False), | |
| _todo_update(state), gr.update(), _computing_update(state), *_no_tabs) | |
| for ch, lh, st, todo, acc, comp, *tabs in _run_computation(chat_history, log_history, state): | |
| chat_history, log_history, state = ch, lh, st | |
| yield (chat_history, log_history, state, gr.update(visible=False), todo, acc, comp, *tabs) | |
| skip_run_evt = meta_cancel_btn.click( | |
| fn=_lock_meta, inputs=None, outputs=[meta_confirm_btn, meta_cancel_btn], | |
| ).then( | |
| fn=on_metadata_skip, | |
| inputs=[chatbot, exec_log, session_state], | |
| outputs=[chatbot, exec_log, session_state, metadata_row, app_header_html, | |
| canvas_exec_col, computing_html, *_TAB_OUTPUTS], | |
| ).then( | |
| fn=_unlock_meta, inputs=None, outputs=[meta_confirm_btn, meta_cancel_btn], | |
| ).then(fn=_populate_tabs, inputs=[session_state], outputs=_TAB_OUTPUTS) | |
| # ── 重置接線（2026-08-12 從上面搬下來）────────────────────────── | |
| # 業主回報：分析運算跑到一半按「回首頁」再重新進來，畫面又冒出上一輪 | |
| # 的分析運算面板、步驟列停在舊狀態、對話還是舊訊息。 | |
| # 真因不是重置漏清（分析跑完後再重置是乾淨的，已實測），而是**重置沒有 | |
| # 中止還在跑的運算**：那條 generator 每個子階段都會 yield 一次畫面， | |
| # 重置把畫面清乾淨之後，它後續的 yield 又把舊內容一格一格畫回去， | |
| # 最後看起來就像「重置沒生效」。 | |
| # 修法用 Gradio 原生的 cancels：按下「確定回首頁」時直接中止那兩條 | |
| # 事件鏈（確認送出／略過 都會進同一支 _run_computation），generator | |
| # 停在原地就不會再有遲到的 yield。這也是這段接線必須放在 | |
| # meta_confirm_btn／meta_cancel_btn 之後的唯一理由——cancels 需要拿到 | |
| # 它們的事件物件。 | |
| reset_confirm_btn.click( | |
| fn=on_reset_clear_workspace, | |
| outputs=[metadata_row, file_input, canvas_idx_col, canvas_stat_col, | |
| canvas_report_col, canvas_exec_col, computing_html, result_nav_col, | |
| upload_progress_html, | |
| meta_title, meta_author, meta_lang, meta_pubyear, meta_version, | |
| meta_ngroups, meta_method, *_TAB_NAV_GATES], | |
| cancels=[confirm_run_evt, skip_run_evt], | |
| ).then( | |
| fn=on_reset_confirm, | |
| # 2026-07-30（2-C 第 5 項）：chat_upload 這輪常駐隱藏、不再接任何 | |
| # wiring（見 chat_upload_col 定義處註解），這裡把它從 outputs 移除。 | |
| # E3（2026-08-05）：scenario_btn_col 空 Column 已整段拿掉，一併從 | |
| # outputs 移除。回傳 tuple 的元素個數／順序已同步調整為 8 個， | |
| # 跟這份 outputs 清單一一對應。 | |
| outputs=[chatbot, exec_log, session_state, app_header_html, | |
| upload_row, | |
| reset_confirm_row, homepage_col, workspace_row], | |
| ) | |
| return demo | |
| # ============================================================================ | |
| # SECTION 11: Entry Point | |
| # ============================================================================ | |
| if __name__ == "__main__": | |
| print("=" * 60) | |
| print("重譯文本分析系統 AI Agent 啟動中……") | |
| print(f"主 Agent : {LLM1_MODEL}") | |
| print(f"工作程序 : {LLM2_MODEL}") | |
| print(f"BASE_DIR : {BASE_DIR}") | |
| print("=" * 60) | |
| start_session_cleanup_scheduler() | |
| app = create_app() | |
| # 2026-08-22：share=True 原本寫死，代表任何人在任何一台機器執行 | |
| # `python app_agent.py` 都會額外開一條公開的 *.gradio.live 通道，把本機 | |
| # 服務暴露到公開網際網路（且連著執行者自己的 OpenRouter 金鑰），沒有任何 | |
| # 存取控制（見 docs/開發優化建議.md 第六節）。正式機走的是 app.py（見該 | |
| # 檔，share=False 且已加登入畫面），這裡只影響本機開發；改成預設關閉、 | |
| # 只有明確設環境變數才臨時開啟分享連結。 | |
| app.launch( | |
| server_name="0.0.0.0", | |
| server_port=7860, | |
| share=os.environ.get("GRADIO_SHARE", "false").strip().lower() == "true", | |
| inbrowser=False, | |
| allowed_paths=[str(SESSIONS_DIR)], | |
| head=_APP_HEAD, | |
| footer_links=[], | |
| css_paths=[str(BASE_DIR / "assets" / "app.css")], # E4：原 _CUSTOM_CSS 常數 | |
| ) | |