un2266 commited on
Commit
e16c550
·
1 Parent(s): 686c7cd

兩份交付文件改版:優化建議重構為四視角、需求文件同步最終實作

Browse files

開發優化建議.md:
以完整性/可用性/可維護性/機密性四個角度重新檢視,新增兩節。
第一節(機密性)研究語料經 prompt 送往 OpenRouter 與其上游供應商,
程式碼無任何資料政策或使用者告知處理,列出三項帳號層級確認事項。
第五節(可維護性)主檔 4232 行、handler 全巢狀定義在 create_app()
內無法單獨測試、零測試檔、設定散落四處,說明它如何放大其他各節的
施工風險。各節依急迫性重排。

補實測數據修正原本的錯誤結論:專案預設 Gemma 模型 reasoning_tokens
為 0、單次 21 秒,先前記錄的 reasoning 浪費與耗時偏長來自本機 .env
覆寫成 openrouter/free(同一代號兩次呼叫路由到不同模型),非專案
預設行為;原文件據此要求業主「換回付費模型」的前提有誤,改為確認
計費與勿用 :free 變體(實測 429,upstream_provider_shared_pool)。

全檔 19 處程式碼行號重抓:原文件行號停留在 aa1f341,CSS 抽出後全檔
位移近兩千行,引用的 :5846/:6124/:6372 均已超出檔案總行數。

需求彙整-UIUX改版.md:
新增「本次改版完成項目總覽」章節置於文首,以非技術語言分四類說明
本次合作實際完成的工作,供業主快速掌握;技術章節原樣保留供工程接手。

其餘就地同步為最終實作結果:5.1 首頁(情境卡片 2026-07-30 已搬回
工作區成第 1 步,首頁只留品牌介紹+單一入口)、5.2 步驟列 7 步更正
為 4 步與導覽列最終項目、6.2/6.3 版面圖(下載捷徑四顆、技術執行紀錄
轉正為獨立頁、設定/API 連結列移除、二欄改三欄)、6.4 補技術執行紀錄
頁、第八節註明存檔/讀檔未實作(首頁為「功能開發中」佔位連結)、
13.1 首頁空狀態、第十四節移除校徽識別項、第二節風險分區行號。

docs/開發優化建議.md CHANGED
@@ -1,78 +1,142 @@
1
  # SpectraEngine 開發優化建議
2
 
3
- - 文件建立日期:2026-08-05
4
  - 提出人:吳千卉(本次 UI/UX 改版執行者)
5
- - 對應 commit:`aa1f341`(分支 `redesign/ui-refresh`)
6
- - 用途:彙整本次 UI/UX 改版過程中發現、但**超出本次委託施工範圍**(純視覺/版面調整)、需要業主方工程資源評估與實作的項目。每項都附具體問題描述、程式碼位置、與建議方向,供工程端規劃排期。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7
 
8
  ## 項目總覽
9
 
10
- | 項目 | 類型 | 急迫性 | 狀態 |
 
 
11
  |---|---|---|---|
12
- | 一、持久化機制(存檔/讀取進度)| 新功能,工程 | 高——直接影響長分析的可靠性 | 需求已定案,0% 實作 |
13
- | 二、LLM API 呼叫可靠性強化 | 可靠性強化,工程 | 高——今天實測直接命中 | 新發現,未評估 |
14
- | 三、本機啟動預設開啟公開分享連結 | 安全性設定 | 中——地端測試/交接時有暴露風險 | 新發現,一行設定即可調整 |
15
- | 四、Session 輸出目錄清理機制 | 維運 | 中——長期磁碟空間問題 | 原始需求已列出,待業主拍板 |
16
- | 五、待業主決策項目(Metadata 補填/品牌識別/上傳大小上限)| 產品決策 | 低——皆非急迫 | 原始需求已列出,待業主拍板,拍板後由本次改版團隊實作 |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17
 
18
  ---
19
 
20
- ## 一、持久化機制(存檔/讀取進度)
21
 
22
- ### 為什麼現在提出
23
 
24
- 2026-08-05 實測時重現了一個問題:一次完整分析(指標計算+統計分析+報告撰寫)耗時約 3.5–4 分鐘,過程中瀏覽器分頁若失去與伺服器的即時連線,**後端會照常把運算跑完、報告與下載檔案也正常產出在磁碟上,但前端畫面永遠停在「處理中」不會更新**;此時使用者若重新整理頁面試圖恢復,畫面只會回到全新首頁,剛才的分析結果雖然還在磁碟上(`sessions/<session_id>/output/`),但介面上沒有任何入口能找回它。
25
 
26
- 追查後確認:這不是這次改版動到的邏輯造成的迴歸,而是系統從第一天架構設計起就存在的缺口——**沒有任何形式的執行狀態持久化**。這正是原始需求彙整文件(`docs/需求彙整-UIUX改版.md` 第八節)裡列為「持久化機制(方案 D)」、且從專案第一天起進度就是 0% 的項目,一般在專案溝通中稱為 **Phase 10**。
27
 
28
- ### 為什麼歸類為工程範疇、不在本次 UI/UX 改版施工範圍內
29
 
30
  需求彙整文件第二節「技術背景與限制」原本就把 `app_agent.py` 分成三個風險區,並明確界定本次改版的施工邊界:
31
 
32
  | 區域 | 風險等級 | 本次改版是否可動 |
33
  |---|---|---|
34
- | `_CUSTOM_CSS` 純樣式 | 低風險 | 可 |
35
- | `create_app()` 版面配置(勿動 `.click()`/`.change()` 綁定本身的邏輯) | 中風險 | 可(僅限版面調整) |
36
  | **`handle_*` 流程函式與核心運算函式** | **高風險** | **改版不應觸碰** |
37
 
38
- 本次改版(Phase 1-9、多輪視覺打磨)完成的項目性質上都落在前兩區——CSS、版面配置、圖示、既有 handler 裡個別 `gr.update()` 輸出值的修正。
39
 
40
- 而「存檔/讀檔」在技術上無法迴避觸碰第三區:它需要在流程中途把執行狀態完整取出、並在讀檔後把狀態「倒帶」回中斷當下,這代表要重新設計 `handle_*` 系列函式與核心運算函式的進出點介面,不是在既有邏輯外面加一層存讀檔就能做到。因此判斷這項工作應交由業主方工程資源評估與實作,本次改版團隊不會嘗試觸碰這一區,以符合原始需求文件對施工範圍的界定。
41
 
42
  ### 原始需求(2026-07-20 訪談已定案,尚未實作)
43
 
44
  摘自需求彙整文件第八節「持久化機制(方案 D:進度存檔/讀檔)」:
45
 
46
- - **不做登入、不做伺服器端多 session 儲存**。理由:無登入代表任何人拿到 session 網址都能看到他人資料,有資安疑慮;且會與現有 Gradio session 架構(見下方說明)衝突。
47
  - 防手滑(`beforeunload` 離開頁面前跳出確認):**已實作完成**(2026-07-24)。
48
  - 中途下載已產出的部分成果:**已部分實作**(左側導覽列四顆下載捷徑,任一階段完成即可下載該階段成果)。
49
  - **存檔/讀檔(核心機制,未實作)**:
50
  - 存檔內容須含**原始上傳文本**(不只中繼結果),確保讀檔後完整還原、不需重新上傳
51
- - 「讀取進度」入口在首頁,讀檔後**直接跳過首頁與情境選擇**,回到中斷當下的步驟與畫面狀態
52
  - 存檔用自訂副檔名(如 `.spectra`)、次要按鈕樣式+警語,與「成果下載」(一般格式+醒目主色按鈕)在視覺與命名上明確區分,避免非技術使用者誤認「中繼存檔=最終成果」
53
- - 多開分析:不需特別開發——開新分頁天生是獨立 session,只需在首次進站提示「建議同時只跑一個分析,以確保運算速度」
54
 
55
  需求彙整文件第十三節「錯誤狀態設計」也已預先列出一個目前完全沒有現成邏輯的案例:**讀取進度檔案毀損或格式不符**,需要設計對應錯誤訊息與復原路徑。
56
 
57
  ### 現況缺口:連「執行到一半先匯出」都做不到
58
 
59
- 上面談的「讀檔還原」是持久化機制裡最複雜的一半;但目前系統**連更基本的「單向匯出、不要求能讀回來」都不存在**,這點值得跟工程端額外說明清楚:
60
 
61
- - 現有的下載能力(左側導覽列四顆捷徑)**只在「分析運算」這個步驟裡、且至少一個子階段(指標計算/統計分析/報告撰寫)已產出結果後才會出現**(見 `_populate_tabs()` app_agent.py:5358 的觸發條件)
62
- - 在此之前的三個步驟——**研究選擇、文本上傳、語料說明**——使用者可能已經填了不少東西(尤其語料 Metadata 表單,情境 3/4 有原文資訊+群組層+個體層共十幾個欄位),但這整段完全沒有任何「先把目前已輸入的內容存個檔」的入口。連線一斷、分頁一關,這幾步全部要重來,不是「找不回結果」,是「連過程都留不住」
63
  - 這件事本質上比完整的「存檔+讀檔」小一步:**先做「匯出」,「讀回來」可以晚一點再做**,也能先驗證「把 `state` + 已上傳檔案 + 表單內容打包成一份可下載的檔案」這件事本身的可行性與格式設計,作為選項 A/C 共同的地基
64
- - 但即使只做單向匯出,仍然需要串接到 `state` 機制與各步驟當下的即時資料(含尚未提交的表單暫存值),不是單純加一顆下載按鈕就能完成,同樣建議由工程端評估排入本節整體規劃
65
 
66
- ### 現有系統架構(工程端評估前必讀)
67
 
68
- - **Session 識別**:`session_id = str(uuid.uuid4())[:8]`,在 `demo.load`(app_agent.py:5575)時產生,**純記憶體內、不寫入 cookie 或任何持久化媒介**。瀏覽器重新整理=拿到全新 `session_id`,舊的執行狀態與伺服器端連線一起消失,只有已寫入磁碟的檔案(`sessions/<session_id>/uploads/`、`sessions/<session_id>/output/`)還留著,但沒有任何介面能再指回它。
69
- - **執行狀態容器**:`state`(`gr.State`,app_agent.py:4762)是一個純 Python dict,由 `make_initial_state()`(app_agent.py:1368-1413)建立,內容包含 `scenario`/`uploaded_files`/`cleaned_files`/`user_metadata`/`done_steps`/`current_step`/`failed_step`/`analysis`(分析運算三子階段狀態)/`upload`(上傳兩子階段狀態)/`output_files`/`zip_paths` 等欄位。
70
 
71
- **這個 dict 只是狀態的一半**:對話串內容(`chatbot` 元件值)與技術執行紀錄(`exec_log` 元件值)是**獨立於 `state` 之外的 Gradio 元件值**,透過函式參數傳遞(例如 `on_scenario_pick(sc_num, chat_history, log_history, state)`,app_agent.py:5846),不在這個 dict 裡,存檔範圍必須額外涵蓋這兩者。
72
 
73
- - **畫面還原不是「把資料塞回去」就好**:目前每個階段的畫面切換(`scenario_select_row`/`upload_row`/`metadata_row`/`canvas_idx_col`/`canvas_stat_col`/`canvas_report_col`/`result_nav_col` 等十餘個容器的 `visible` 狀態)是由對應的 handler 在使用者操作當下逐步 `yield` 出來的(可參考 `on_scenario_pick` app_agent.py:5846-5900、`_run_computation` app_agent.py:6124-6177)。讀檔要做到「回到中斷當下的畫面」,等同於要能夠**不靠使用者實際操作、直接重放這些 handler 原本會產生的一系列可見性狀態**,這版 Gradio 的容器可見性切換有多個非直覺的時序限制(本次改版一路踩坑下來已累積不少記錄),讀檔還原邏輯需要對這些限制有完整掌握才不會做出「資料回來了但畫面錯亂」的結果。
74
 
75
- - **與第四節「Session 輸��目錄清理機制」高度相關**:存讀檔功能上線後,只會讓孤兒 session 目錄累積得更快(讀檔本質上就是把一個舊 session 目錄的內容接到新 session 上,舊的、沒被讀取的 session 目錄仍會一直留著)。**建議這兩項工程一併規劃**,不要分開處理。
76
 
77
  ### 實作選項與優缺點
78
 
@@ -80,34 +144,34 @@
80
 
81
  使用者手動點擊「儲存進度」,系統把 `state` + `chat_history` + `log_history` + 已上傳原始文本序列化成一個 `.spectra` 檔案供下載;之後在首頁點「讀取進度」上傳該檔案,還原上述狀態並重放對應的可見性 yield 邏輯。
82
 
83
- - 優點:不需要伺服器端多使用者儲存、不需要登入,維持原始需求「無資安疑慮」的設計初衷;部署在 Hugging Face Spaces 免費層不需要額外的資料庫或儲存服務;與需求彙整文件已定案方向一致
84
- - 缺點:`.spectra` 檔案體積可能不小,使用者要自行妥善保管檔案(研究語料外流的疑慮需要跟業主確認是否可接受);**無法解決本節重現的問題**——存檔動作本身通常也需要使用者手動觸發,若連線已經斷了,使用者根本按不到那顆按鈕;讀檔還原邏輯技術複雜度不低
85
 
86
  **選項 B:伺服器端 session 儲存 + 恢復代碼/連結**
87
 
88
  執行狀態存在伺服器磁碟或資料庫,使用者拿到一組代碼或短網址,之後憑代碼接回同一個 session。
89
 
90
- - 優點:使用者體驗較友善,不需要自行保管檔案;若搭配輪詢(polling)較有機會做到「連線斷掉後自動接回」
91
- - 缺點:**這正是 2026-07-20 需求訪談時業主與執行團隊已經明確討論並否決的方向**(無登入代表任何人拿到代碼/連結就能看到他人研究資料,資安疑慮;且與現有 Gradio session 架構有衝突)。若要重新考慮,需要業主重新拍板,並額外設計存取控制
92
 
93
- **選項 C(本次實測後新增建議):先做「長任務容錯」,與完整存讀檔脫鉤分階段處理**
94
 
95
- 不等待完整的存讀檔功能,先把「分析運算」這個最耗時的階段,從**目前綁死在單一條前端-後端串流連線上的 generator 模式**,改成**後端非同步 job + 前端輪詢(polling)**:分析開始後立即回傳一個 job 識別碼,後端在背景把 job 進度寫入 session 目錄下的一個進度檔案,前端改成每隔幾秒輪詢一次進度。
96
 
97
- - 優點:**直接解決本節重現的真實痛點**——只要 `session_id` 還在瀏覽器端(例如寫進 URL query string 或 localStorage),就算分頁重新整理或連線重連,前端都能重新輪詢到目前進度;施工範圍比完整存讀檔小很多;若進度檔案格式與未來 `.spectra` 格式相容,之後銜接完整存讀檔的邊際成本會降低
98
- - 缺點:不等於完整的 Phase 10——沒有「關掉瀏覽器、隔天回來繼續」的能力;需要把 `run_computation_pipeline_streaming`(app_agent.py:1704)與 `_run_computation`(app_agent.py:6124)目前的 generator/yield 架構改成 job 佇列模式,同樣觸碰核心運算函式範圍
99
 
100
- ### 建議實作順序
101
 
102
- 1. **選項 C 優先**:風險與工作量相對可控,且直接解決今天實測到的既有問題,任何一次超過 1-2 分鐘的分析都會受益
103
- 2. **選項 A 其次**:完成需求文件已定案的「進度存檔/讀檔」
104
- 3. **選項 B 除非業主主動要求**:牽涉到已被否決過一次的資安權衡,需要重新拍板才建議投入
105
 
106
  ---
107
 
108
- ## 二、LLM API 呼叫可靠性強化
109
 
110
- 同一次 2026-08-05 實測過程中,連帶用真實 API Key 直接測試了 `_call_openrouter()`(app_agent.py:377-401)的行為,發現三個目前程式碼裡沒有處理、會直接影響分析運算穩定性與速度的問題。這三點都集中在同一個函式,建議工程端一次評估、一次修改。
111
 
112
  ```python
113
  def _call_openrouter(api_key, model, system_prompt, user_prompt, max_tokens=16000, temperature=0.5):
@@ -117,47 +181,100 @@ def _call_openrouter(api_key, model, system_prompt, user_prompt, max_tokens=1600
117
  return result["choices"][0]["message"]["content"]
118
  ```
119
 
120
- ### 2.1 完全沒有重試機制
121
 
122
- `call_main_agent()`(app_agent.py:408,LLM1 報告撰寫用)與 `call_worker_agent()`(app_agent.py:413,LLM2 上傳/格式驗證引導用)都是單次呼叫,全檔搜尋不到任何 retry/backoff 邏輯。只要遇到一次暫時性失敗(429 限流、網路瞬斷),該階段就直接標記失敗(見 `run_computation_pipeline_streaming` app_agent.py:1765 的例外處理),使用者要嘛整段報告缺失、要嘛得重新跑一次完整流程,沒有「自動重試一次就過了」的緩衝空間。
 
 
123
 
124
  **建議**:至少對 429/連線逾時/5xx 這類暫時性錯誤加上 2-3 次的重試(搭配指數退避),永久性錯誤(如 401 金鑰錯誤)才直接失敗不重試。
125
 
126
- ### 2.2 180 秒逾時實際上不是有效的總時間上限
 
 
127
 
128
- 程式碼寫 `timeout=180`,字面上看像是「最多等 3 分鐘」,但今天實測**同一次呼叫耗時約 230 秒仍然成功回應、沒有觸發逾時例外**。原因是 `urllib.request.urlopen` 的 `timeout` 參數作用在底層 socket 的個別讀寫操作上,只要伺服器持續有資料流動(不是完全靜默超過 180 秒),單次呼叫的總耗時就可能遠超過這個數字。
129
 
130
- 這代表目前程式碼裡「180 秒」給的是一種**假的安全感**——工程端若以為這個數字就是使用者最長等待時間的上限,據此設計前端提示文案或逾時重試邏輯,會與實際行為不符。
131
 
132
- **建議**:如果要有一個真正的總時間上限,需要額外用執行緒或 `signal` 搭配獨立計時器強制中斷(`urllib` 本身的 `timeout` 參數做不到),或改用支援總逾時設定的 HTTP client(例如 `httpx` 的 `timeout` 可以分別設定 connect/read/write/pool 各階段)。
133
 
134
- ### 2.3 免費模型走自動路由,行為不可預測,且「思考過程」的 token 完全被浪費
135
 
136
- `.env` 目前設定 `LLM1_MODEL=openrouter/free`、`LLM2_MODEL=openrouter/free`。這不是一個固定模型,而是 OpenRouter 的**自動路由別名**——每次呼叫可能被導去不同的免費模型。今天實測這次被導去 `nvidia/nemotron-3-ultra-550b-a55b:free`,這個模型預設會做 reasoning(回應 JSON 裡有一段獨立的 `"reasoning"` 欄位,內容是模型的思考過程文字)。
137
 
138
- 問題是:`_call_openrouter()` 的回傳只取 `result["choices"][0]["message"]["content"]`(app_agent.py:399),**`reasoning` 欄位從頭到尾沒有被讀取或使用**。也就是說,這個思考過程佔掉的生成時間(對 `max_tokens=16000` 的報告撰寫來說可能是總耗時的一大部分)**完全是純浪費,對使用者看到的報告內容沒有任何貢獻**,這很可能是報告撰寫階段耗時 3-4 分鐘的主要原因之一。
 
 
 
 
 
 
 
 
 
139
 
140
- 另外,自動路由代表每次執行分配到的模型不保證一致,回應速度、輸出品質、是否觸發 reasoning 都會隨 OpenRouter 當下的免費額度供給而變動,難以做效能調校或問題重現。
141
 
142
  **建議**:
143
- - 改用固定的免費模型代號(例如 `.env.example` 裡原本建議的 `google/gemma-4-31b-it`/`google/gemma-4-26b-a4b-it`),而不是自動路由別名,取得可預期、可重現的效能表現
144
- - 若選用的模型支援關閉 reasoning(部分 OpenRouter 模型可透過 request body 加 `reasoning: {"enabled": false}` 或類似參數關閉),應明確關閉,避免為了完全用不到的思考過程付出等待時間
145
- - 中期可考慮改用 OpenRouter 的串流(streaming)API,讓報告內容逐字回傳、前端可即時顯示部分生成內容,即使模型本身較慢,使用者體感也會從「畫面死掉 3 分鐘」變成「看得到字在跑」
 
146
 
147
- ### 2.4 正式上線前務必確認:目前是免費模型,不是最終要用的模型
148
 
149
- **這點務必提醒業主**:本次改版全程測試用的 `LLM1_MODEL`/`LLM2_MODEL`(`.env` 裡設成 `openrouter/free`)是 OpenRouter 的免費模型自動路由,僅供開發階段測試使用,**不是正式上線要用的模型設定**。2.3 節列出的路由不穩定、思考過程浪費時間等問題,很大一部分本來就是免費模型的固有限制,換成正式付費模型後這些問題會自然改善或消失。
150
 
151
- 正式上線前請業主/工程端確認:
152
- - `.env` 的 `LLM1_MODEL`/`LLM2_MODEL` 改成正式要用的付費模型代號
153
- - 對應的 OpenRouter API Key 額度/付款方式已設定好,避免上線後才發現免費額度用罄而全面中斷服務
154
- - 換成正式模型後,2.1-2.3 節提到的重試機制、逾時處理,仍建議一併補上——正式模型一樣會遇到網路瞬斷或短暫限流,只是頻率比免費模型低很多,不是換了付費模型就完全不需要這些防護
155
 
156
  ---
157
 
158
- ## 三、本機啟動預設開啟公開分享連結
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
159
 
160
- `app_agent.py` 最後的進入點(app_agent.py:6372-6380):
 
 
 
 
 
 
 
 
 
 
 
 
161
 
162
  ```python
163
  app.launch(
@@ -168,74 +285,75 @@ app.launch(
168
  )
169
  ```
170
 
171
- `share=True` 是寫死的,不受任何環境變數控制。這代表**任何人只要執行 `python app_agent.py`**(例如工程交接時的地端測試、除錯),Gradio 都會自動額外開一條公開的 `https://xxxx.gradio.live` 通道,把當下這台機器上跑的服務(可能還在除錯、可能連著測試用的 API 金鑰)暴露到公開網際網路上,且這條連結預設可存活達 7 天,沒有任何存取控制。
172
-
173
- 正式部署在 Hugging Face Spaces 上時,`share=True` 本身是多餘的(Spaces 平台自己就是公開存取),問題主要在**地端執行**的情境。今天測試時就實際觀察到這個行為(啟動 log 會印出 `* Running on public URL: https://xxx.gradio.live`)。
174
 
175
- **建議**:改成依環境變數控制(例如 `share=os.environ.get("GRADIO_SHARE", "false").lower() == "true"`),預設關閉,只有明確需要臨時對外展示時才手動開啟。
176
 
177
- ---
178
-
179
- ## 四、Session 輸出目錄清理機制
180
 
181
- 原始需求彙整文件第十四節「待業主確認的範圍清單」第 3 項已列出:**Session 輸出目錄的清理機制(維運層面,非 UI/UX 範圍,但影響 Hugging Face Space 長期磁碟空間)**。`sessions/`(`SESSIONS_DIR`,app_agent.py:71-72)目前沒有任何過期清理邏輯,每次分析都會留下一個含原始上傳文本與全部產出檔案的資料夾,長期執行下磁碟用量只會持續增加。
 
 
182
 
183
- 如本文件第一節所述,這項工程與「持久化機制」高度相關——存讀檔上線後只會讓孤兒目錄累積得更快,建議兩者一併規劃排期,不要分開處理。
184
 
185
  ---
186
 
187
- ## 五、待業主決策項目(拍板後由本次改版團隊實作,非工程範疇)
188
-
189
- 以下三項原始需求彙整文件第十四節「待業主確認的範圍清單」就已列出、當時業主尚未拍板,本次改版也都還沒做。跟第一至四節不同,這幾項**不需要業主的工程資源**,是產品/內容面的決定,拍板後回到本次改版團隊(吳千卉)施工即可,一併列在此處供業主後續思考。
190
 
191
- ### 5.1 語料 Metadata「略過」後可否事後補填
192
 
193
- 目前使用者在語料 Metadata 說明表單點「略過」後,系統標記為「使用者未提供」並**永久跳過,沒有任何入口可以事後回來編輯**。2026-07-20 訪談時的決定是「本次不做,只調整文案誠實告知略過的後果」(略過文案:「以下資訊會寫入報告開頭,您也可以先略過(略過後這次分析將不會用到這些補充說明)」)。若業主認為使用者略過後常常想回頭補,可以再評估是否要開一個「編輯語料說明」的入口+重新觸發報告生成,屬於全新功能,需要另外估工。
194
 
195
- ### 5.2 是否加入致理科技大學品牌/校徽識別
196
 
197
- 目前系統畫面上只有 `SpectraEngine` 自身的產品品牌,沒有委託單位(致理科技大學應日系)的識別。是否要加、加在哪裡(例如首頁或報告文件封面)、有沒有現成的校徽電子檔案可用,需要業主決定。
198
 
199
- ### 5.3 是否設定上傳檔案大小上限
200
 
201
- 目前系統對上傳檔案**沒有任何大小限制**,異常巨大的檔案可能拖慢運算或超出 Gradio 本身的上傳限制。2026-07-20 訪談時判斷「不急迫,可延後決定」。若要做,可以與既有的檔名字首合法性、每組檔案數下限檢查(`run_format_check()`,app_agent.py:1579)合併在同一關驗證,實作成本不高。
202
 
203
  ---
204
 
205
- ## 附錄:關鍵程式碼位置對照(截至 commit `aa1f341`)
 
 
206
 
207
  | 項目 | 位置 |
208
  |---|---|
209
  | `SESSIONS_DIR` 定義 | app_agent.py:71-72 |
210
  | `_call_openrouter()`(LLM API 呼叫核心)| app_agent.py:377-401 |
211
  | `call_main_agent()` / `call_worker_agent()` | app_agent.py:408 / 413 |
212
- | `make_initial_state()`(state dict 完整結構)| app_agent.py:1368-1413 |
213
- | `_STEPS`(步驟列定義)| app_agent.py:1437 起 |
 
214
  | `handle_scenario_select()` | app_agent.py:1510 |
215
  | `run_format_check()` | app_agent.py:1579 |
216
- | `run_computation_pipeline_streaming()`(指標計算/統計分析/報告撰寫三段 generator)| app_agent.py:1704 |
217
- | `run_report_writing()`(LLM1 報告撰寫)| app_agent.py:1255 |
218
- | `_populate_tabs()`(結果分頁與 zip 打包收尾)| app_agent.py:5358 |
219
- | `on_scenario_pick()`(含多段 yield 可見性切換範例)| app_agent.py:5846 |
220
- | `on_reset_confirm()` | app_agent.py:5962 |
221
- | `on_upload_confirm()` | app_agent.py:6003 |
222
- | `_run_computation()`(分析運算收尾 wrapper)| app_agent.py:6124 |
223
- | `on_back_to_scenario()` | app_agent.py:6229 |
224
- | `on_metadata_confirm()` | app_agent.py:6261 |
225
- | `app.launch(share=True, ...)` | app_agent.py:6372-6380 |
 
226
 
227
  ## 附錄:2026-08-05 問題重現紀錄
228
 
229
- - **首次觀察**:使用者於分析運算「報告撰寫」階段等候超過 180 秒,畫面持續顯示「處理中」無任何更新或錯誤訊息
230
  - **診斷過程**:
231
  1. 確認 OpenRouter API 金鑰額度正常(`usage: 0`,`limit: null`),排除額度問題
232
- 2. 直接呼叫 `.env` 設定的模型代號(`openrouter/free`)驗證為合法別名,0.5 秒內正常回應,排除模型代號無效問題,但發現該次回應路由到會做 reasoning 的模型(見第二節 2.3)
233
  3. 檢查伺服器程序當下對外連線,**無任何連往 openrouter.ai 的 established 連線**,代表 LLM 呼叫已經結束(成功或失敗),並非仍在等待 API
234
  4. 直接檢查該 session 輸出目錄,確認報告 docx/txt 與四包下載 zip **皆已完整產出**,證實後端已成功跑完整條流程,只是前端沒有反映
235
- 5. 使用者重新整理頁面後,畫面回到全新首頁(新 `session_id`),舊 session 的產出檔案「還在但找不到路回去」
236
- - **重現測試**:以本機 `.venv` + Chrome 走一次完整流程(情境 1,測試樣本 `A_01.txt`/`B_01.txt`),**全程保持分頁在前景、電腦未休眠**,分析運算(含報告撰寫)於約 3 分 48 秒後正確顯示「分析完成!」,各階段狀態即時更新,未重現卡住現象;同一次測試也實際觀察到 `share=True` 產生的公開連結(見第三節)
237
- - **結論**:長分析任務的可靠性問題與「分頁失去前景/連線中斷」高度相關,而非每次必然發生的邏輯錯誤;在目前的架構下,任何超過 1-2 分鐘的分析都暴露在同樣的風險下,這正是第一節選項 C 建議優先處理的原因
 
238
 
239
  ---
240
 
241
- *本文件為本次 UI/UX 改版團隊(吳千卉)提出的技術評估建議,非最終實作規格。實際採用的方案、優先順序與工作量估計,請業主方工程資源進一步評估後定案。*
 
1
  # SpectraEngine 開發優化建議
2
 
3
+ - 文件建立日期:2026-08-05(2026-08-06 全面改版,補入實測數據並重新校正程式碼行號)
4
  - 提出人:吳千卉(本次 UI/UX 改版執行者)
5
+ - 對應版本:commit `f8aab79`(分支 `redesign/ui-refresh`),本文件所有 `app_agent.py:行號` 均以此版本為準
6
+ - 用途:**供您後續自行規劃、排期與發包**
7
+
8
+ 這份文件整理的是我在這次 UI/UX 改版過程中發現、但超出本次委託施工範圍(純視覺/版面調整)的項目。每一項我都寫清楚具體問題、程式碼位置、影響範圍與建議方向,讓您和後續承接的工程資源可以直接依此評估,不需要再回頭問我才能動工。
9
+
10
+ > ### ⚠ 請先看這裡:我測試時換過 LLM 模型設定
11
+ >
12
+ > 我手上沒有您的 OpenRouter API Key,開發期間是用我自己申請的金鑰測試,並在本機 `.env` 把模型改成 `LLM1_MODEL=openrouter/free`/`LLM2_MODEL=openrouter/free`,**沒有使用專案預設的 `google/gemma-4-31b-it`/`google/gemma-4-26b-a4b-it`**。
13
+ >
14
+ > `.env` 已列在 `.gitignore`(第 35 行)不進版控,所以**我的設定不會隨程式碼交付,您本機與正式機的設定都不受影響**。但有兩件事請留意:
15
+ >
16
+ > 1. **本文件出現的所有耗時數據,都是在我的模型設定下量測的,不能當作正式機的效能基準**。實測差距不小:專案預設的 Gemma 模型單次回應約 21 秒,我測試用的自動路由則是 36.1 秒。
17
+ > 2. **重建環境時(Hugging Face Spaces 的 Secrets、新工程師的本機設定),請確認 `LLM1_MODEL`/`LLM2_MODEL` 填的是您要用的模型代號**,不要沿用本文件範例中出現的 `openrouter/free`。
18
+ >
19
+ > 完整實測數據見第三節。
20
+
21
+ ## 這份文件的檢視角度
22
+
23
+ 我從四個角度重新檢視了整個系統,各自帶出的項目如下。同一個項目可能同時命中多個角度,我把它歸在最主要的那一類:
24
+
25
+ | 角度 | 我問的問題 | 帶出的項目 |
26
+ |---|---|---|
27
+ | **機密性** | 使用者上傳的研究語料,會流到哪裡、留在哪裡、誰看得到? | 一、四、六 |
28
+ | **可用性** | 使用者實際操作時,會不會卡住、會不會白做工? | 二 |
29
+ | **完整性** | 該處理的錯誤情境有沒有處理完?失敗後系統會怎麼樣? | 三 |
30
+ | **可維護性** | 下一個接手的人,能不能安全地改這份程式碼? | 五 |
31
+
32
+ ---
33
 
34
  ## 項目總覽
35
 
36
+ 以下依急迫性由高而低排列,後續各節順序與此表一致:
37
+
38
+ | 項目 | 主要角度 | 急迫性 | 狀態 |
39
  |---|---|---|---|
40
+ | 一、研究語料傳送至第三方 AI 服務的資料政策 | 機密性 | 高(已在正式機發生中,且資料送出不可逆)| 新發現,多數是帳號設定確認,未必需要工程 |
41
+ | 二、持久化機制(存檔/讀取進度)| 可用性 | 高(直接影響長分析的可靠性)| 需求已定案,0% 實作 |
42
+ | 三、LLM API 呼叫可靠性強化 | 完整性 | 高(這次實測直接命中)| 新發現,未評估 |
43
+ | 四、Session 輸出目錄清理機制 | 機密性/維運 | 中(付費 Spaces,磁碟累積有實際成本,且語料無限期留存)| 原始需求已列出,等您決定 |
44
+ | 五、單一檔案 4232 行、且完全沒有自動化測試 | 可維護性 | 中(不緊急,但會放大前面每一項的施工風險)| 新發現,未評估 |
45
+ | 六、本機啟動預設開啟公開分享連結 | 機密性 | 低(不影響正式機,影響工程端地端開發)| 新發現,一行設定即可調整 |
46
+ | 七、待您決策的項目 | 產品決策 | 低(皆非急迫)| 原始需求已列出,等您決定 |
47
+
48
+ ---
49
+
50
+ ## 一、研究語料傳送至第三方 AI 服務的資料政策
51
+
52
+ ### 現況
53
+
54
+ 系統的報告撰寫階段(`run_report_writing()`,app_agent.py:1255���會把使用者上傳的譯文內容組進 prompt(app_agent.py:1273-1290),透過 `_call_openrouter()`(app_agent.py:377-401)送到 OpenRouter。OpenRouter 是一個**路由層**,它會再把請求轉給上游的實際模型供應商(我實測時看到的供應商包含 Google AI Studio)。
55
+
56
+ 也就是說,使用者上傳的研究語料,實際上會經過至少兩個第三方:OpenRouter 本身,以及它背後路由到的模型供應商。
57
+
58
+ 我在程式碼中搜尋不到任何與資料政策、去識別化、或使用者告知相關的處理。
59
+
60
+ ### 為什麼我把這一項排在第一位
61
+
62
+ 這套系統的使用對象是應用日語系的師生,處理的是**尚未發表的翻譯研究語料**。這類資料有兩個特性讓它比一般應用更敏感:
63
+
64
+ - **預先揭露的風險**:研究資料在正式發表前流出,可能影響後續投稿與著作權主張
65
+ - **不可逆**:前面第二至六節的問題都可以在發現後修好,但資料一旦送出第三方,無法收回
66
+
67
+ 我要說清楚的是,**我沒有證據顯示已經發生任何外洩**。我提出來的是:這件事目前沒有任何人在管理,而管理它的成本很低。
68
+
69
+ ### 請您確認的事項
70
+
71
+ 以下多數不需要動程式碼,是帳號層級的設定確認:
72
+
73
+ 1. **OpenRouter 帳號的資料政策設定**:OpenRouter 允許使用者設定是否同意 prompt 內容被保留或用於模型訓練。部分免費模型端點會**要求**開啟較寬鬆的政策才能使用。請確認正式機使用的帳號目前是哪一種設定。
74
+ 2. **上游供應商的保留政策**:即使 OpenRouter 本身不保留,實際處理請求的供應商(如 Google AI Studio)有自己的政策。若語料機密性要求高,可考慮在 OpenRouter 的 provider routing 設定中限定供應商。
75
+ 3. **Hugging Face Space 的可見性**:正式機若設為 public,任何拿到網址的人都能上傳文本並執行分析,也就能消耗您的 API 額度。請確認 Space 目前是 public 還是 private,以及是否需要加上存取控制。
76
+
77
+ ### 建議的工程項目
78
+
79
+ 1. **在系統內對使用者揭露**:在文本上傳步驟加一段說明,告知「您上傳的內容會傳送至第三方 AI 服務進行分析」。這是成本最低、也最該做的一項,讓使用者能自己判斷哪些語料適合放進來。
80
+ 2. **若語料含個人資料**(例如受訪者、學生作業),請一併確認是否符合貴校的個資規範,必要時在上傳前加入去識別化步驟。
81
 
82
  ---
83
 
84
+ ## 二、持久化機制(存檔/讀取進度)
85
 
86
+ ### 我為什麼提出這件事
87
 
88
+ 我在 2026-08-05 實測時重現了一個問題:一次完整分析(指標計算+統計分析+報告撰寫)耗時數分鐘,過程中瀏覽器分頁若失去與伺服器的即時連線,**後端會照常把運算跑完、報告與下載檔案也正常產出在磁碟上,但前端畫面永遠停在「處理中」不會更新**。此時使用者若重新整理頁面試圖恢復,畫面只會回到全新首頁;剛才的分析結果雖然還在磁碟上(`sessions/<session_id>/output/`),但介面上沒有任何入口能找回它。
89
 
90
+ 我追查後確認,這個缺口從系統第一天架構設計起就存在,與這次改版動到的邏輯無關:系統沒有任何形式的執行狀態持久化。這正是原始需求彙整文件(`docs/需求彙整-UIUX改版.md` 第八節)裡列為「持久化機制(方案 D)」、從專案第一天起進度就是 0% 的項目。
91
 
92
+ ### 我為什麼把它歸類為工程範疇、不放進本次改版施工範圍
93
 
94
  需求彙整文件第二節「技術背景與限制」原本就把 `app_agent.py` 分成三個風險區,並明確界定本次改版的施工邊界:
95
 
96
  | 區域 | 風險等級 | 本次改版是否可動 |
97
  |---|---|---|
98
+ | 純樣式(本次改版已抽出為 `assets/app.css`)| 低風險 | 可 |
99
+ | `create_app()` 版面配置(勿動 `.click()`/`.change()` 綁定本身的邏輯)| 中風險 | 可(僅限版面調整)|
100
  | **`handle_*` 流程函式與核心運算函式** | **高風險** | **改版不應觸碰** |
101
 
102
+ 我這次改版完成的項目,性質上都落在前兩區:CSS、版面配置、圖示、既有 handler 裡個別 `gr.update()` 輸出值的修正。
103
 
104
+ 而「存檔/讀檔」在技術上無法迴避觸碰第三區。它需要在流程中途把執行狀態完整取出,並在讀檔後把狀態「倒帶」回中斷當下,這代表要重新設計 `handle_*` 系列函式與核心運算函式的進出點介面,在既有邏輯外面加一層存讀檔是做不到的。因此我建議把這項工作交給後續的工程資源評估與實作;為了守住原始需求文件界定的施工範圍,我沒有去動這一區。
105
 
106
  ### 原始需求(2026-07-20 訪談已定案,尚未實作)
107
 
108
  摘自需求彙整文件第八節「持久化機制(方案 D:進度存檔/讀檔)」:
109
 
110
+ - **不做登入、不做伺服器端多 session 儲存**。理由:無登入代表任何人拿到 session 網址都能看到他人資料,有資安疑慮;且會與現有 Gradio session 架構衝突。
111
  - 防手滑(`beforeunload` 離開頁面前跳出確認):**已實作完成**(2026-07-24)。
112
  - 中途下載已產出的部分成果:**已部分實作**(左側導覽列四顆下載捷徑,任一階段完成即可下載該階段成果)。
113
  - **存檔/讀檔(核心機制,未實作)**:
114
  - 存檔內容須含**原始上傳文本**(不只中繼結果),確保讀檔後完整還原、不需重新上傳
115
+ - 「讀取進度」入口在首頁,讀檔後**直接回到中斷當下的步驟與畫面狀態**
116
  - 存檔用自訂副檔名(如 `.spectra`)、次要按鈕樣式+警語,與「成果下載」(一般格式+醒目主色按鈕)在視覺與命名上明確區分,避免非技術使用者誤認「中繼存檔=最終成果」
117
+ - 多開分析:不需特別開發,開新分頁天生是獨立 session,只需在首次進站提示「建議同時只跑一個分析,以確保運算速度」
118
 
119
  需求彙整文件第十三節「錯誤狀態設計」也已預先列出一個目前完全沒有現成邏輯的案例:**讀取進度檔案毀損或格式不符**,需要設計對應錯誤訊息與復原路徑。
120
 
121
  ### 現況缺口:連「執行到一半先匯出」都做不到
122
 
123
+ 上面談的「讀檔還原」是持久化機制裡最複雜的一半。但目前系統**連更基本的「單向匯出、不要求能讀回來」都不存在**:
124
 
125
+ - 現有的下載能力(左側導覽列四顆捷徑)**只在「分析運算」這個步驟裡、且至少一個子階段已產出結果後才會出現**(見 `_populate_tabs()` app_agent.py:3177 的��發條件)
126
+ - 在此之前的步驟——文本上傳、語料說明——使用者可能已經填了不少東西(尤其語料 Metadata 表單有十幾個欄位),但這整段完全沒有任何「先把目前已輸入的內容存個檔」的入口。連線一斷、分頁一關,這幾步全部要重來,不只是找不回結果,是連過程都留不住
127
  - 這件事本質上比完整的「存檔+讀檔」小一步:**先做「匯出」,「讀回來」可以晚一點再做**,也能先驗證「把 `state` + 已上傳檔案 + 表單內容打包成一份可下載的檔案」這件事本身的可行性與格式設計,作為選項 A/C 共同的地基
128
+ - 但即使只做單向匯出,仍然需要串接到 `state` 機制與各步驟當下的即時資料(含尚未提交的表單暫存值),加一顆下載按鈕是不夠的
129
 
130
+ ### 現有系統架構(工程評估前建議先讀)
131
 
132
+ - **Session 識別**:`session_id = str(uuid.uuid4())[:8]`,在 `demo.load`(app_agent.py:3370)時產生,**純記憶體內、不寫入 cookie 或任何持久化媒介**。瀏覽器重新整理=拿到全新 `session_id`,舊的執行狀態與伺服器端連線一起消失,只有已寫入磁碟的檔案還留著,但沒有任何介面能再指回它。
133
+ - **執行狀態容器**:`session_state`(`gr.State`,app_agent.py:2578)是一個純 Python dict,由 `make_initial_state()`(app_agent.py:1368)建立,內容包含 `scenario`/`uploaded_files`/`cleaned_files`/`user_metadata`/`done_steps`/`current_step`/`failed_step`/`analysis`/`upload`/`output_files`/`zip_paths` 等欄位。
134
 
135
+ **這個 dict 只是狀態的一半**:對話串內容(`chatbot` 元件值)與技術執行紀錄(`exec_log` 元件值)是**獨立於 `state` 之外的 Gradio 元件值**,透過函式參數傳遞(例如 `on_scenario_pick(sc_num, chat_history, log_history, state)`,app_agent.py:3679),不在這個 dict 裡,存檔範圍必須額外涵蓋這兩者。
136
 
137
+ - **畫面還原不是「把資料塞回去」就好**:目前每個階段的畫面切換(十餘個容器的 `visible` 狀態)是由對應的 handler 在使用者操作當下逐步 `yield` 出來的(可參考 `on_scenario_pick` app_agent.py:3679、`_run_computation` app_agent.py:3975)。讀檔要做到「回到中斷當下的畫面」,等同於要能夠**不靠使用者實際操作、直接重放這些 handler 原本會產生的一系列可見性狀態**。這版 Gradio 的容器可見性切換有多個非直覺的時序限制,讀檔還原邏輯需要對這些限制有完整掌握,才不會做出「資料回來了但畫面錯亂」的結果。
138
 
139
+ - **與第四節高度相關**:存讀檔功能上線後,只會讓孤兒 session 目錄累積得更快(讀檔本質上就是把一個舊 session 目錄的內容接到新 session 上,舊的、沒被讀取的目錄仍會一直留著)。**建議這兩項一併規劃**。
140
 
141
  ### 實作選項與優缺點
142
 
 
144
 
145
  使用者手動點擊「儲存進度」,系統把 `state` + `chat_history` + `log_history` + 已上傳原始文本序列化成一個 `.spectra` 檔案供下載;之後在首頁點「讀取進度」上傳該檔案,還原上述狀態並重放對應的可見性 yield 邏輯。
146
 
147
+ - 優點:不需要伺服器端多使用者儲存、不需要登入,維持原始需求「無資安疑慮」的設計初衷;不需要在現有 Hugging Face Spaces 之外額外採購資料庫或儲存服務;與需求彙整文件已定案方向一致
148
+ - 缺點:`.spectra` 檔案內含完整原始語料,體積不小,且**使用者要自行妥善保管,這本身是一個新的機密性風險點**(見第一節);**無法解決本節重現的問題**,因為存檔動作需要使用者手動觸發,若連線已經斷了,使用者根本按不到那顆按鈕;讀檔還原邏輯技術複雜度不低
149
 
150
  **選項 B:伺服器端 session 儲存 + 恢復代碼/連結**
151
 
152
  執行狀態存在伺服器磁碟或資料庫,使用者拿到一組代碼或短網址,之後憑代碼接回同一個 session。
153
 
154
+ - 優點:使用者體驗較友善,不需要自行保管檔案;若搭配輪詢較有機會做到「連線斷掉後自動接回」
155
+ - 缺點:**這正是 2026-07-20 需求訪談時明確討論並否決的方向**(無登入代表任何人拿到代碼/連結就能看到他人研究資料)。若要重新考慮,需要重新拍板,並額外設計存取控制
156
 
157
+ **選項 C(我這次實測後新增的建議):先做「長任務容錯」,與完整存讀檔脫鉤分階段處理**
158
 
159
+ 不等待完整的存讀檔功能,先把「分析運算」這個最耗時的階段,從目前綁死在單一條前端-後端串流連線上的 generator 模式,改成**後端非同步 job + 前端輪詢**:分析開始後立即回傳一個 job 識別碼,後端在背景把進度寫入 session 目錄下的進度檔案,前端每隔幾秒輪詢一次。
160
 
161
+ - 優點:**直接解決本節重現的真實痛點**,只要 `session_id` 還在瀏覽器端(例如寫進 URL query string 或 localStorage),就算分頁重��整理或連線重連,前端都能重新輪詢到目前進度;施工範圍比完整存讀檔小很多;若進度檔案格式與未來 `.spectra` 格式相容,之後銜接完整存讀檔的邊際成本會降低
162
+ - 缺點:不等於完整的持久化機制,沒有「關掉瀏覽器、隔天回來繼續」的能力;需要把 `run_computation_pipeline_streaming`(app_agent.py:1704)與 `_run_computation`(app_agent.py:3975)目前的 generator/yield 架構改成 job 佇列模式,同樣觸碰核心運算函式範圍
163
 
164
+ ### 我建議的實作順序
165
 
166
+ 1. **選項 C 優先**:風險與工作量相對可控,且直接解決實測到的既有問題,任何一次超過 1-2 分鐘的分析都會受益
167
+ 2. **選項 A 其次**:完成需求文件已定案的「進度存檔/讀檔」,但請一併考量 `.spectra` 檔案本身的機密性
168
+ 3. **選項 B 除非主動要求**:牽涉到已被否決過一次的資安權衡,需要重新拍板才建議投入
169
 
170
  ---
171
 
172
+ ## 三、LLM API 呼叫可靠性強化
173
 
174
+ 2026-08-05 實測過程中,我用自己申請的 OpenRouter API Key 直接測試了 `_call_openrouter()`(app_agent.py:377-401)的行為,發現兩個目前程式碼裡沒有處理、會直接影響分析穩定性的問題(3.1、3.2)。這兩點集中在同一個函式,建議一次評估、一次修改。
175
 
176
  ```python
177
  def _call_openrouter(api_key, model, system_prompt, user_prompt, max_tokens=16000, temperature=0.5):
 
181
  return result["choices"][0]["message"]["content"]
182
  ```
183
 
184
+ ### 3.1 完全沒有重試機制
185
 
186
+ `call_main_agent()`(app_agent.py:408,LLM1 報告撰寫用)與 `call_worker_agent()`(app_agent.py:413,LLM2 上傳/格式驗證引導用)都是單次呼叫,全檔搜尋不到任何 retry/backoff 邏輯。只要遇到一次暫時性失敗(429 限流、網路瞬斷),該階段就直接標記失敗(見 `run_computation_pipeline_streaming` app_agent.py:1760-1783 的例外處理),使用者要嘛整段報告缺失、要嘛得重新跑一次完整流程,沒有「自動重試一次就過了」的緩衝空間。
187
+
188
+ 這一項在成本面也有意義:失敗後重跑整個流程,等於把已經付掉的 token 成本再付一次。
189
 
190
  **建議**:至少對 429/連線逾時/5xx 這類暫時性錯誤加上 2-3 次的重試(搭配指數退避),永久性錯誤(如 401 金鑰錯誤)才直接失敗不重試。
191
 
192
+ ### 3.2 180 秒逾時實際上不是有效的總時間上限
193
+
194
+ 程式碼寫 `timeout=180`,字面上看像是「最多等 3 分鐘」,但實測時**同一次呼叫耗時約 230 秒仍然成功回應、沒有觸發逾時例外**。原因是 `urllib.request.urlopen` 的 `timeout` 參數作用在底層 socket 的個別讀寫操作上,只要伺服器持續有資料流動,單次呼叫的總耗時就可能遠超過這個數字。
195
 
196
+ 這代表程式碼裡的「180 秒」只給了一種**假的安全感**。若以為這個數字就是使用者最長等待時間的上限,據此設計前端提示文案或逾時重試邏輯,會與實際行為不符。
197
 
198
+ **建議**:如果要有一個真正的總時間上限,需要額外用執行緒或 `signal` 搭配獨立計時器強制中斷(`urllib` 本身的 `timeout` 參數做不到),或改用支援總逾時設定的 HTTP client(例如 `httpx` 可分別設定 connect/read/write/pool 各階段)。
199
 
200
+ ### 3.3 未來換模型時的注意事項(我的測試環境限制,非目前設定的問題)
201
 
202
+ 先說結論:**這一節描述的現象在專案預設模型下不會發生**,我記錄下來是給未來換模型時參考的。
203
 
204
+ 我測試時把模型設成 `openrouter/free`。這個代號並非固定模型,它是 OpenRouter 的**自動路由別名**,每次呼叫可能被導去不同的免費模型。我用同一個代號連續測兩次,分別被導去 `nvidia/nemotron-3-nano-30b-a3b:free` 與 `openai/gpt-oss-20b:free`,證實路由結果確實每次不同。這兩個模型都預設會做 reasoning,回應 JSON 裡有一段獨立的 `"reasoning"` 欄位。
205
 
206
+ 而 `_call_openrouter()` 的回傳只取 `result["choices"][0]["message"]["content"]`(app_agent.py:399),**`reasoning` 欄位從頭到尾沒有被讀取或使用**,這段思考過程佔掉的生成時間對使用者看到的報告內容沒有任何貢獻。
207
+
208
+ 我用同一段測試 prompt(`max_tokens=800`)比較兩種設定:
209
+
210
+ | | 專案預設 `google/gemma-4-31b-it` | 我測試用的 `openrouter/free` |
211
+ |---|---|---|
212
+ | 實際路由模型 | 固定為指定模型 | 每次不同(實測兩次得到兩個不同模型)|
213
+ | `reasoning` 欄位 | 空(`None`)| 1056 字元 |
214
+ | `reasoning_tokens` | **0** | **239**(佔 800 個生成 token 的 30%)|
215
+ | 單次回應耗時 | **21.0 秒** | 36.1 秒 |
216
 
217
+ **專案預設的 Gemma 模型完全沒有 reasoning 浪費的問題,而且比我測試用的設定更快。** 我先前觀察到報告撰寫偏慢,有相當比例來自我自己的模型設定。
218
 
219
  **建議**:
220
+ - 專案預設模型的實際耗時,請由使用正式設定的環境重新量測一次,我這邊的數字不適合當基準
221
+ - 未來換模型時請直接指定固定的模型代號,避免使用 `openrouter/free` 這類自動路由別名
222
+ - 若換到的模型會做 reasoning,建議在 `_call_openrouter()` 明確關閉(部分模型可透過 request body 加 `reasoning: {"enabled": false}` 或類似參數)
223
+ - 若報告撰寫階段仍然偏慢,中期可考慮改用 OpenRouter 的串流 API,讓報告逐字回傳、前端即時顯示,使用者體感會從「畫面死掉好幾分鐘」變成「看得到字在跑」
224
 
225
+ ### 3.4 模型選用的兩點提醒
226
 
227
+ **第一,專案預設模型是計費的。** 我用一段 60 個 prompt token、生成 800 個 token 的測試請求呼叫 `google/gemma-4-31b-it`,OpenRouter 回報 `cost: 0.0002774`。單次成本很低,但實際報告撰寫是 `max_tokens=16000`,量級差 20 倍,且每位使用者每次分析都會呼叫。請確認 OpenRouter 帳號的額度與付款方式已設定妥當,避免額度用罄導致服務全面中斷。
228
 
229
+ **第二,請不要把模型代號改成加 `:free` 後綴的版本。** 我實測 `google/gemma-4-31b-it:free` 直接回 HTTP 429,錯誤訊息為 `is temporarily rate-limited upstream`,`limit_source` 標示為 `upstream_provider_shared_pool`,也就是這個免費端點是所有 OpenRouter 使用者共用的池子,隨時可能被限流。若為了節省成本改用 `:free` 變體,會讓分析在尖峰時段大量失敗,而目前又沒有重試機制(見 3.1),使用者會直接看到該階段失敗。
 
 
 
230
 
231
  ---
232
 
233
+ ## 四、Session 輸出目錄清理機制
234
+
235
+ 原始需求彙整文件第十四節「待業主確認的範圍清單」第 3 項已列出:**Session 輸出目錄的清理機制**。`sessions/`(`SESSIONS_DIR`,app_agent.py:71-72)目前沒有任何過期清理邏輯,每次分析都會留下一個含原始上傳文本與全部產出檔案的資料夾。
236
+
237
+ 這一項同時命中兩個角度:
238
+
239
+ - **機密性**:每一份使用者上傳過的研究語料,都會無限期留存在正式機的磁碟上,沒有任何刪除機制,也沒有告知使用者這件事。若某位老師只是想試跑一下,他的語料就永久留在那台機器上了。
240
+ - **維運成本**:正式機部署在付費的 Hugging Face Spaces 上,磁碟累積會直接反映在儲存空間的採購規格與費用上。
241
+
242
+ **建議**:先確認目前 `sessions/` 已累積的用量,再決定清理策略(例如保留 N 天後自動刪除),並在介面上告知使用者資料的保存期限。
243
+
244
+ 如同第二節所述,這項工程與持久化機制高度相關,存讀檔上線後只會讓孤兒目錄累積得更快,建議兩者一併規劃排期。
245
+
246
+ ---
247
+
248
+ ## 五、單一檔案 4232 行、且完全沒有自動化測試
249
+
250
+ 這一項不緊急,但它會放大前面每一項的施工風險,所以我把它獨立列出來。
251
+
252
+ ### 現況
253
+
254
+ - `app_agent.py` 目前 **4232 行**,UI 定義、業務邏輯、LLM 呼叫、統計運算、檔案 IO 全部集中在同一個檔案裡
255
+ - 大量事件 handler 巢狀定義在 `create_app()` 內部(`on_scenario_pick` app_agent.py:3679、`on_upload_confirm` app_agent.py:3854、`_run_computation` app_agent.py:3975、`on_metadata_confirm` app_agent.py:4112 等),這代表**它們無法被單獨匯入與測試**,只能靠實際開啟瀏覽器操作來驗證
256
+ - 專案中**沒有任何測試檔案**,也沒有 `tests/` 目錄
257
+ - 關鍵設定散落在程式碼各處而非集中管理:`max_tokens=16000`/`temperature=0.5`(app_agent.py:377)、`timeout=180`(app_agent.py:398)、`server_port=7860`(app_agent.py:4225)、`share=True`(app_agent.py:4226)
258
+
259
+ ### 為什麼這件事會影響前面每一項
260
+
261
+ 第二節的持久化機制、第三節的重試邏輯,動刀的位置都在這個檔案的核心運算區。在沒有任何自動化測試的情況下,每一次改動都只能靠人工重跑完整流程來確認沒弄壞既有功能,而完整流程本身要跑好幾分鐘。這會讓工程估時裡的「驗證」成本遠高於「實作」成本,也讓後續維護者不敢動。
262
+
263
+ 我這次改版有做兩個小幅改善,可以當作後續整理的起點:CSS 已從主檔抽出為 `assets/app.css`(commit `7b42168`),輸出清單已拆成具名子清單(commit `54e74f4`)。這兩個改動都沒有改變任何行為。
264
 
265
+ ### 建議
266
+
267
+ 1. **先加回歸測試,再談重構**。順序反過來會很危險。優先涵蓋純函式部分:格式檢查(`run_format_check()` app_agent.py:1579)、狀態建立(`make_initial_state()` app_agent.py:1368)、指標計算等不依賴 Gradio 的邏輯,這些最容易測、也最值得測。
268
+ 2. **把散落的設定集中**到檔案頂端的設定區塊或獨立的 `config.py`,讓「要調哪個數字」不需要在 4000 行裡找。
269
+ 3. **把 handler 從 `create_app()` 內部搬到模組層級**,改用參數傳遞取得所需元件。這一步能讓 handler 變成可測試的普通函式,但它會大量觸碰事件綁定,建議等測試就位後再做。
270
+
271
+ 這三步可以分次進行,不需要一次到位。
272
+
273
+ ---
274
+
275
+ ## 六、本機啟動預設開啟公開分享連結
276
+
277
+ `app_agent.py` 的進入點(app_agent.py:4223-4232):
278
 
279
  ```python
280
  app.launch(
 
285
  )
286
  ```
287
 
288
+ `share=True` 是寫死的,不受任何環境變數控制。這代表**任何人只要執行 `python app_agent.py`**,Gradio 都會自動額外開一條公開的 `https://xxxx.gradio.live` 通道,把當下這台機器上跑的服務暴露到公開網際網路上,沒有任何存取控制。我在本機測試時就實際觀察到這個行為(啟動 log 會印出 `* Running on public URL: https://xxx.gradio.live`)。
 
 
289
 
290
+ **這一項不影響您已經部署好的 Hugging Face Spaces 正式機**,Spaces 平台本身就是公開存取,多這條通道在效果上沒有差別。我提出來是針對**地端執行**的情境,也就是未來工程端接手維護時,在自己電腦上開發與除錯的那些時候:那台機器上可能跑著還沒測完的版本,也連著開發者自己的 OpenRouter 金鑰,卻在不見得會注意到的情況下對外開了一個入口(那行 log 混在一堆啟動訊息裡很容易被忽略)。
291
 
292
+ **建議**:改成依環境變數控制,預設關閉,只有明確需要臨時對外展示時才手動開啟。
 
 
293
 
294
+ ```python
295
+ share=os.environ.get("GRADIO_SHARE", "false").lower() == "true"
296
+ ```
297
 
298
+ 另外建議順手確認一次:正式機在 Hugging Face Spaces 上啟動時,log 裡是否也會印出 `gradio.live` 連結。若會,代表正式機同時存在第二條不受平台管理的對外入口,那就不只是開發環境的問題,值得一併關掉。
299
 
300
  ---
301
 
302
+ ## 七、待您決策的項目
 
 
303
 
304
+ ### 7.1 語料 Metadata「略過」後可否事後補填
305
 
306
+ 目前使用者在語料 Metadata 說明表單點「略過」後,系統標記為「使用者未提供」並**永久跳過,沒有任何入口可以事後回來編輯**。本次改版的處理方式是調整文案,誠實告知略過的後果。
307
 
308
+ 若後續希望開放事後補填,這屬於全新功能:需要新增「編輯語料說明」的入口,並處理「報告已產出後才修改 Metadata」的重新生成邏輯,需要重新規劃與估工。
309
 
310
+ ### 7.2 是否設定上傳檔案大小上限
311
 
312
+ 目前系統對上傳檔案**沒有任何大小限制**,異常巨大的檔案可能拖慢運算或超出 Gradio 本身的上傳限制。
313
 
314
+ 若要實作,可以與既有的檔名字首合法性、每組檔案數下限檢查(`run_format_check()`,app_agent.py:1579)合併在同一關驗證。
315
 
316
  ---
317
 
318
+ ## 附錄:關鍵程式碼位置對照(截至 commit `f8aab79`)
319
+
320
+ > 注意:本表行號對應 commit `f8aab79`。本專案主檔改動頻繁(例如 `7b42168` 將 CSS 抽出後,全檔行號位移近兩千行),若您手上的版本不同,請以函式名稱搜尋為準。
321
 
322
  | 項目 | 位置 |
323
  |---|---|
324
  | `SESSIONS_DIR` 定義 | app_agent.py:71-72 |
325
  | `_call_openrouter()`(LLM API 呼叫核心)| app_agent.py:377-401 |
326
  | `call_main_agent()` / `call_worker_agent()` | app_agent.py:408 / 413 |
327
+ | `run_report_writing()`(LLM1 報告撰寫,語料組進 prompt 之處)| app_agent.py:1255 |
328
+ | `make_initial_state()`(state dict 完整結構)| app_agent.py:1368 |
329
+ | `_STEPS`(步驟列定義)| app_agent.py:1437 |
330
  | `handle_scenario_select()` | app_agent.py:1510 |
331
  | `run_format_check()` | app_agent.py:1579 |
332
+ | `run_computation_pipeline_streaming()`(三段 generator)| app_agent.py:1704 |
333
+ | `session_state`(`gr.State` 宣告)| app_agent.py:2578 |
334
+ | `_populate_tabs()`(結果分頁與 zip 打包收尾)| app_agent.py:3177 |
335
+ | `demo.load`(`session_id` 產生處)| app_agent.py:3370 |
336
+ | `on_scenario_pick()`(含多段 yield 可見性切換範例)| app_agent.py:3679 |
337
+ | `on_reset_confirm()` | app_agent.py:3811 |
338
+ | `on_upload_confirm()` | app_agent.py:3854 |
339
+ | `_run_computation()`(分析運算收尾 wrapper)| app_agent.py:3975 |
340
+ | `on_back_to_scenario()` | app_agent.py:4080 |
341
+ | `on_metadata_confirm()` | app_agent.py:4112 |
342
+ | `app.launch(share=True, ...)` | app_agent.py:4223-4232 |
343
 
344
  ## 附錄:2026-08-05 問題重現紀錄
345
 
346
+ - **首次觀察**:分析運算「報告撰寫」階段等候超過 180 秒,畫面持續顯示「處理中」,沒有任何更新或錯誤訊息
347
  - **診斷過程**:
348
  1. 確認 OpenRouter API 金鑰額度正常(`usage: 0`,`limit: null`),排除額度問題
349
+ 2. 直接呼叫測試環境 `.env` 設定的模型代號(`openrouter/free`,我自行覆寫,非專案預設)驗證為合法別名,0.5 秒內正常回應,排除模型代號無效問題,但發現該次回應路由到會做 reasoning 的模型(見 3.3)
350
  3. 檢查伺服器程序當下對外連線,**無任何連往 openrouter.ai 的 established 連線**,代表 LLM 呼叫已經結束(成功或失敗),並非仍在等待 API
351
  4. 直接檢查該 session 輸出目錄,確認報告 docx/txt 與四包下載 zip **皆已完整產出**,證實後端已成功跑完整條流程,只是前端沒有反映
352
+ 5. 重新整理頁面後,畫面回到全新首頁(新 `session_id`),舊 session 的產出檔案「還在但找不到路回去」
353
+ - **重現測試**:以本機 `.venv` + Chrome 走一次完整流程,**全程保持分頁在前景、電腦未休眠**,分析運算正確完成、各階段狀態即時更新,未重現卡住現象;同一次測試也實際觀察到 `share=True` 產生的公開連結(見第六節)
354
+ - **2026-08-06 補測**:為釐清耗時來自架構還是模型設定,對四個模型代號各發一次最小請求比對,確認專案預設的 `google/gemma-4-31b-it`/`google/gemma-4-26b-a4b-it` 可正常呼叫、`reasoning_tokens` 為 0、單次回應 21 秒;`openrouter/free` 兩次呼叫路由到兩個不同模型、`reasoning_tokens` 為 239、單次回應 36.1 秒;`google/gemma-4-31b-it:free` 則直接回 HTTP 429。完整數據見 3.3、3.4
355
+ - **結論**:長分析任務的可靠性問題與「分頁失去前景/連線中斷」高度相關,並非每次必然發生的邏輯錯誤。但在目前的架構下,任何超過 1-2 分鐘的分析都暴露在同樣的風險下,這是第二節把選項 C 列為優先處理的原因。至於耗時本身,補測後確認有相當比例來自我的模型設定,不是架構問題
356
 
357
  ---
358
 
359
+ *以上是我在這次 UI/UX 改版過程中的技術評估建議,不是最終實作規格,也不包含工作量估計。實際採用哪些項目、優先順序與施工方式,請您與後續承接的工程資源評估後定案。*
docs/需求彙整-UIUX改版.md CHANGED
@@ -1,16 +1,78 @@
1
  # SpectraEngine(譯彩紛呈 II 分析引擎)UI/UX 改版需求彙整
2
 
3
  - 文件建立日期:2026-07-20
4
- - 最後更新日期:2026-07-24
5
  - 專案委託方:致理科技大學應日系鄧老師
6
  - 專案執行:吳千卉
7
- - 用途:①與 UI/UX Pro Max Skill 協作設計時的需求依據 ②向業主說明本次改版變動內容與理由的對照文件
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8
 
9
  ---
10
 
11
  ## 一、專案背景
12
 
13
- `SpectraEngine` 是一套針對重譯文本(retranslation)語言特徵的量化分析平台,技術上是 **Python + Gradio 單頁研究工具**(`app_agent.py`,約 3400 行),並非傳統前後端分離的 HTML/CSS/JS 網站,部署在 Hugging Face Spaces。系統採雙 Agent 架構:主 Agent(LLM1)負責研究情境引導與報告撰寫,工作程序 Agent(LLM2)負責上傳引導與格式驗證。
14
 
15
  本次改版目標:**優化操作流程與介面風格**,方向參考 ChatGPT/Claude 網頁版的排版與操作體驗,同時修正過程中發現的既有問題。
16
 
@@ -22,10 +84,12 @@
22
  | 本地路徑 | `500_Projects\致理應日系-譯彩紛呈分析引擎`(`origin`=fork 可推,`upstream`=業主原始repo 唯讀) |
23
  | 本機測試 | `.venv` 已建置,`python app_agent.py` 啟動於 `http://127.0.0.1:7860`;無 API key 也能看主頁畫面,LLM 對話功能需 `.env` 填 `LLM1_API_KEY`/`LLM2_API_KEY` |
24
  | 測試套件 | **無**,每次改動需手動跑過完整流程驗證,不能只憑程式碼檢查 |
25
- | 風險分區 | `_CUSTOM_CSS`(1639–2550行)純樣式、低風險;`create_app()`(2706行起)版面配置、中風險(勿動 `.click()`/`.change()` 事件綁定);`handle_*` 流程函式(1429–1620行)與核心運算函式(320–1330行)為高風險,**改版不應觸碰** |
26
  | Gradio 版本 | 6.20.0(`footer_links` 等新版 API 可用,不需 CSS hack) |
27
 
28
- ## 三、已確認的既有 Bug(本次改版應一併修正,非新功能)
 
 
29
 
30
  ### Bug 1:選定研究情境後無法變更
31
  - **位置**:`app_agent.py` 第 3170–3171 行
@@ -90,19 +154,19 @@
90
 
91
  ## 五、資訊架構設計
92
 
93
- ### 5.1 首頁(新增,取代原本「情境選擇」是對話中第一步的設計)
94
- - 單欄置中,大標題+簡短說明
95
- - **直接展示 4 個情境選項卡片**(不做「開始新分析」按鈕→再選情境的兩步驟,選了任一情境卡片即直接開始)
96
- - 每個情境卡片需附一行說明文字(原本在對話中選情境旁邊只有短標籤,搬到首頁沒有 AI 陪同引導,需要更清楚的說明避免選錯)
97
- - **卡片說明文字草稿**(基於 `SCENARIOS` 字典裡現成但目前完全未使用的 `desc` 欄位改寫,供 Skill 協作時進一步優化語氣/字數):
98
 
99
- | 情境 | 卡片說明文字草稿 |
100
  |---|---|
101
  | 1. 人工翻譯 vs 機器翻譯 | 比較人工與機器譯本在語言特徵上的差異,聚焦人機翻譯風格對比。 |
102
  | 2. 全譯 vs 編譯(節譯、改寫) | 比較完整翻譯與節譯/改寫版本,聚焦文本完整性與改寫策略。 |
103
  | 3. 不同譯者的同期譯本 | 比較同一時期不同譯者的譯本,聚焦個人風格差異(已排除時代因素)。 |
104
  | 4. 同一原文的不同時期人工譯本 | 比較同一原文在不同時期的譯本,聚焦歷時語言變化與翻譯規範演變。 |
105
- - 「讀��進度」為次要連結,入口在首頁;讀檔後**直接跳過首頁**,回到中斷當下的步驟與畫面狀態(不用再選一次情境)
106
 
107
  ### 5.2 導覽層級:頂部步驟列 vs 左側「結果導覽」
108
  兩者互補、不衝突,但視覺上要做出層級差異避免使用者誤認重複:
@@ -110,14 +174,19 @@
110
  | | 頂部步驟列 | 左側結果導覽 |
111
  |---|---|---|
112
  | 性質 | 時間軸型:進度到第幾步 | 空間型:跳著看已完成結果 |
113
- | 內容 | ①上傳引導②文本上傳③格式驗證④指標計算⑤統計分析⑥報告撰寫⑦下載成果(共 7 步,原 8 步扣掉已搬到首頁的「情境選擇」) | 🏠對話/📊語言指標分析/📈統計比較分析(展開4子項)/📝LLM輔助分析 |
114
- | 生命週期 | 全部完成(第7步)後**隱藏**,讓畫面空間交給結果內容 | 分析開始前不出現;完成後接手成為主要瀏覽方式,與步驟列隱藏的時機交接一致 |
115
 
116
- ### 5.3 情境標籤(新增,因情境選擇搬到首頁後產生的需求)
117
- - 進入工作區後需常駐顯示「目前情境」小標籤,**獨立於步驟列存在**(步驟列隱藏後仍要留著)
 
 
 
 
118
  - 格式:「情境:3. 不同譯者的同期譯本 [變更]」
119
- - 位置:右欄最上方、步驟列正上方
120
- - 「變更」連結沿用「開始新分析」的未儲存警示機制(換情境=重新開始,同一套邏輯/同一個 Bug 1 修法)
 
121
 
122
  ## 六、版面配置
123
 
@@ -125,50 +194,56 @@
125
  左欄導覽(窄)+右欄主畫面。原因:「執行進度」已在業主上一版整併進頂部步驟列,不需要獨立第三欄。
126
 
127
  ### 6.2 左側導覽列
 
 
128
  ```
129
  ┌─────────────────────┐
130
  │ 🆕 開始新分析 │
131
- │ 📂 讀取進度 │
132
  ├─────────────────────┤
133
  │ 情境:X. ○○○○ [變更] │ ← 分析開始後才出現
134
- │ 🏠 對話 │
135
  │ 📊 語言指標分析 │
136
- │ 📈 統計比較分析 ▾ │
137
- │ ├ 敘述統計 │
138
- │ ├ 差異性分析 │
139
- │ ├ 監督式學習 │
140
- │ └ 非監督式學習 │
141
  │ 📝 LLM輔助分析 │
142
- ├─────────────────────┤ ← 分隔線
143
- │ ⬇️ 下載指標數據 │ ← 指標計算一跑完即可下載,不用等全部結束
144
- │ ⬇️ 下載完整報告(假按鈕) │ ← 全案完成才出現/啟��
145
- ├─────────────────────┤
146
- │ ⚙️ 設定 🔌 API │ ← 置底,低視覺權重
 
147
  └─────────────────────┘
148
  ```
149
  - 固定窄寬 240–280px
150
- - **桌面版可收合**成 ChatGPT 式細窄 icon bar(收合後只留:新對話/讀取進度 icon + 置底設定/API icon)
151
- - **手機版**:漢堡選單/抽屜收合,預設只顯示對話主畫面,點擊展開側欄
152
- - 統計比較分析第二層 4 個子分頁用 Accordion 展開(沿用現有「技術執行紀錄」已使用過的收合元件模式,風險中低)
 
 
 
153
 
154
  ### 6.3 右欄(對話畫面)
 
 
155
  ```
156
  ┌──────────────────────────────────────────┐
157
  │ 情境:3. 不同譯者的同期譯本 [變更] │ ← 常駐情境標籤
158
- │ ① 上傳引導 ② 文本上傳 ③ 格式驗證 ④ 指標計算 ... │ ← 頂部步驟列(7步,完成後淡出)
159
  ├──────────────────────────────────────────┤
160
- │ 對話串(AI訊息左側藍線/使用者訊息右側) │
161
- │ [若目前是 Metadata 步驟 → 插入獨立表單卡片, │
162
  │ 不套用聊天泡泡左右分欄邏輯,佔滿全欄寬, │
163
- │ 對話視窗仍在其上方,同頁面往下捲動、非彈出視窗] │
164
- ├──────────────────────────────────────────┤
165
- │ ▸ 技術執行紀錄(預設收合,弱化字級,主要給技術夥伴用) │
166
  ├──────────────────────────────────────────┤
167
- │ 📎 [ 輸入文字,或附加檔案… ] 送出 → │ ← 改用 gr.MultimodalTextbox
168
  └──────────────────────────────────────────┘
169
  ```
170
- - 對話與上傳改用 `gr.MultimodalTextbox` 合併(現有 UI 對話框在上、上傳欄在下要往下滾動,使用者常找不到)
171
- - 「技術執行紀錄」判斷是給業主的工程夥伴看的,非一般使用者需求,維持現況的收合行為即可,字級再弱化
 
 
172
 
173
  ### 6.4 結果分頁排版
174
  | 分頁 | 內容 | 排版決策 |
@@ -178,7 +253,8 @@
178
  | 📈 統計-2 差異性分析 | 表格+箱形圖+下載 | 圖表在上、表格在下,先看圖抓重點 |
179
  | 📈 統計-3 監督式學習 | 特徵重要性表格+圖(現有左右並排) | 沿用;側欄縮窄後放不下則改上下堆疊 |
180
  | 📈 統計-4 非監督式學習 | 樹狀圖+Elbow並排/PCA全寬/分群表格 | 沿用現有配置 |
181
- | 📝 LLM輔助分析 | 報告文字+下載 | 舒適閱讀排版(適中行寬、寬鬆行高) |
 
182
 
183
  ## 七、語料 Metadata 說明表單
184
 
@@ -197,7 +273,7 @@
197
  |---|---|
198
  | 防手滑 | `beforeunload` 事件,離開頁面前跳出確認(2026-07-24 已實作:僅在工作區顯示期間生效,回到首頁自動解除。瀏覽器規定使用者需先與頁面互動過確認框才會出現,且提示文字由瀏覽器決定,無法自訂) |
199
  | 中途下載 | 任一步驟完成即可下載當前已產出的部分成果 |
200
- | **存檔/讀檔** | 核心機制。存檔內容**含原始上傳文本**(不只中繼結果),確保讀檔後完整還原、不用重新上傳;讀取進度入口在首頁,讀檔後直接跳過首頁回到中斷步驟 |
201
  | 檔名/格式區分 | 存檔用自訂副檔名(如 `.spectra`),次要按鈕樣式+警語;成果下載才用一般格式+醒目主色按鈕,避免非技術使用者誤認「中繼存檔=最終成果」 |
202
  | 多開分析 | 不需特別開發——開新分頁天生是獨立 session(Gradio `session_hash` 機制);僅需在首次進站提示註明「建議同時只跑一個分析,以確保運算速度」(避免多分頁同時佔用運算資源) |
203
 
@@ -268,7 +344,7 @@
268
  ### 13.1 空狀態(Empty States)
269
  | 情境 | 設計方向 |
270
  |---|---|
271
- | 首頁初訪(尚未選情境) | 單欄置中大標題+4情境卡片+讀取進度次要連結(見五之5.1) |
272
  | 結果分頁在分析尚未開始時 | 現有已有 `_EMPTY_HINT` 元件(置中圖示+提示文字,內容近似「尚未產生資料/請先於主頁完成分析流程」),**沿用現有設計**,只需適配新版面(右欄/左側結果導覽)位置 |
273
  | 左側「結果導覽」在分析未開始前 | 整段不顯示(已決定,見六之6.2) |
274
  | 讀取進度但尚無任何存檔可讀(新功能首次使用) | 需設計提示文案;使用者第一次使用本系統不會有任何存檔,按下「讀取進度」前應清楚說明這是「上傳先前下載的存檔」,不是「系統幫你保存的雲端紀錄」 |
@@ -297,8 +373,9 @@
297
  1. ~~「下載完整報告」是否要做真正的 zip 整包後端邏輯~~ → 2026-07-24 已直接實作完成,不需業主拍板(見第四節缺口 1、第九節)
298
  2. 是否要做「Metadata 略過後事後回來補填」功能(本次不做,只調整文案)
299
  3. Session 輸出目錄的清理機制(維運層面,非 UI/UX 範圍,但影響 Hugging Face Space 長期磁碟空間)
300
- 4. 是否要加入致理科技大學品牌/校徽識別(目前系統僅有 SpectraEngine 自身品牌,無委託單位識別)
301
- 5. 是否要設定上傳檔案大小上限(目前無任何限制,異常巨大檔案可能拖慢運算或超出 Gradio 上傳限制),不急迫,可延後決定
 
302
 
303
  ## 十五、更新紀錄
304
 
@@ -309,6 +386,7 @@
309
  | 2026-07-20 | 「監督式學習」「非監督式學習」補下載按鈕確認要做(移出待業主清單),命名定為「下載監督式學習」/「下載非監督式學習」;格式驗證每組檔案數下限確認為既有缺陷修正、非待業主確認事項;精簡缺口3內容;補充 Metadata 表單四種情境皆會出現、差異僅在內容的說明 |
310
  | 2026-07-20 | 開始與 UI/UX Pro Max Skill 協作視覺設計:確定風格方向(對話區參考AI-Native UI、結果分頁參考Data-Dense Dashboard)、字體(英文數字Crimson Pro+中文維持Noto Sans TC)、配色(維持業主既有雙主題系統,WCAG對比度驗算通過,不重新設計) |
311
  | 2026-07-24 | 缺口 1「整包下載」改為直接實作完成(原訂只做假按鈕交業主拍板),第九節下載機制改寫成四顆下載捷徑的實際規格,待業主確認清單第 1 項結案;持久化機制的「防手滑」(`beforeunload`)同步實作完成 |
 
312
  | 2026-07-24 | 運算階段重構:步驟列收斂為 3 步(文本上傳/語料說明/分析運算),格式驗證退為文本上傳內部處理、指標計算+統計分析+報告產出合併為「分析運算」單一步驟;分析運算改用 Canvas 內容區塊分段呈現三子階段(進度→摘要+查看入口)。Bug 3(步驟列失敗視覺狀態)與報告產出失敗的誠實呈現一併落地:報告失敗不再誤報「全部完成」,步驟列標紅、對話總結據實說明「指標與統計已完成、僅報告未產出」。結果導覽項目在對應結果產出前 disabled |
313
 
314
  ---
 
1
  # SpectraEngine(譯彩紛呈 II 分析引擎)UI/UX 改版需求彙整
2
 
3
  - 文件建立日期:2026-07-20
4
+ - 最後更新日期:2026-08-06(全文同步為最終實作結果,對應 commit `f8aab79`)
5
  - 專案委託方:致理科技大學應日系鄧老師
6
  - 專案執行:吳千卉
7
+ - 用途:①向業主說明本次改版執行了哪些工作項目 ②本次改版的需求依據與技術規格,供後續工程接手參考
8
+
9
+ ---
10
+
11
+ ## 本次改版完成項目總覽
12
+
13
+ 這一章用非技術語言說明本次合作實際完成的工作,供快速掌握改版內容。後續各章為詳細的需求規格與技術決策紀錄,供工程接手時參考。
14
+
15
+ 改版期間共 47 次程式碼提交,工作分為四類。
16
+
17
+ ### 一、修復的既有問題(6 項)
18
+
19
+ 這些是系統原本就存在、本次一併修好的問題:
20
+
21
+ | 問題 | 使用者原本會遇到的狀況 |
22
+ |---|---|
23
+ | 選定研究情境後無法變更 | 情境選錯了,畫面上沒有任何方式可以改,只能重整頁面從頭來過 |
24
+ | 格式驗證失敗後無法重新上傳 | 系統叫使用者重新上傳,但上傳欄位同時被隱藏,等於叫人做一件做不到的事 |
25
+ | 驗證失敗會清空全部檔案 | 只要一個檔案有問題,已經通過驗證的檔案也一起被清掉。改為只清除有問題的檔案 |
26
+ | 分析失敗時步驟列永遠閃爍 | 運算失敗後,該步驟的圓點會一直維持「進行中」的呼吸動畫,使用者以為系統還在跑,其實已經停了 |
27
+ | 語料說明表單章節編號跳號 | 情境 1、2 時畫面顯示「一、三、四」,中間跳過「二」 |
28
+ | 明暗主題切換在部分瀏覽器失效 | 切換按鈕按了沒反應 |
29
+
30
+ 另外也修掉了改版過程中發現的數個小問題:上傳區的「取消」按鈕按了會鎖住整個上傳入口、回到首頁重置後語料說明表單殘留上一輪內容、重置後情境卡片點了沒反應等。
31
+
32
+ ### 二、新增的功能(4 項)
33
+
34
+ | 功能 | 說明 |
35
+ |---|---|
36
+ | 四顆下載捷徑 | 原本要拿到全部產出,得逐一進入 3 個結果分頁下載 15 個檔案。現在左側導覽列直接提供「指標數據」「統計圖表」「研究報告」「完整分析資料」四個打包下載 |
37
+ | 監督式/非監督式學習下載按鈕 | 這兩個子頁原本算得出結果卻沒有下載入口,現已補上,四個統計子頁一致 |
38
+ | 離開頁面前的防手滑提示 | 分析進行中誤按上一頁或關閉分頁時,瀏覽器會跳出確認 |
39
+ | 上傳驗證強化 | 新增檔名字首合法性檢查、每組至少一個檔案的檢查,以及語料說明表單「群組數量」與實際上傳分組數的一致性比對。這些檢查攔的是會讓後續統計分析直接失敗的情況 |
40
+
41
+ ### 三、介面與流程重整(6 項)
42
+
43
+ | 項目 | 改版內容 |
44
+ |---|---|
45
+ | 首頁改版 | 新增品牌介紹首頁,單一「開始研究分析」入口 |
46
+ | 步驟列收斂 | 從原本 8 步收斂為 4 步(研究選擇/文本上傳/語料說明/分析運算)。格式驗證併入文本上傳,指標計算、統計分析、報告撰寫三段合併為「分析運算」,底下以進度區塊分段呈現 |
47
+ | 三欄式工作區 | 左側導覽/對話欄/結果內容區。結果內容從原本的分頁遷移到獨立的內容區,切換結果頁時對話欄收起、內容區佔滿寬度 |
48
+ | 左側結果導覽 | 新增,可跳著看已完成的結果。項目在對應結果產出前為不可點狀態,避免點進空白頁 |
49
+ | 導覽列收合 | 桌面版可收合成細窄圖示列;手機版改為漢堡選單抽屜 |
50
+ | 對話與上傳合併 | 改用可同時輸入文字與附加檔案的輸入框,解決原本上傳欄要往下捲才找得到的問題 |
51
+
52
+ ### 四、視覺與體驗調整
53
+
54
+ - 全站基礎字級統一為 14px,取代原本散落各處的 0.78–0.84rem 硬寫值
55
+ - 字體:英文與數字改用 Crimson Pro(學術調性),中文維持 Noto Sans TC
56
+ - 配色維持既有雙主題系統不重新設計,但完成 WCAG 對比度稽核並修正強調色的誤用場景
57
+ - 分析失敗時的訊息改為誠實呈現:報告產出失敗不再誤報「全部完成」,而是明確說明「指標與統計已完成、僅報告未產出」
58
+ - 分析運算面板加上「請保持分頁在前景、電腦勿休眠」的提醒
59
+ - 樣式從主程式抽出為獨立的 `assets/app.css`,方便後續維護
60
+
61
+ ### 五、本次未做、留給後續的項目
62
+
63
+ 以下項目經評估超出本次委託範圍(純視覺/版面調整),或需要業主決定,均整理在另一份《開發優化建議》文件中:
64
+
65
+ - **進度存檔/讀取**:首頁的「讀取進度」目前是標示「功能開發中」的佔位連結。這項功能需要改動系統的核心運算邏輯,屬於工程範疇
66
+ - **研究語料傳送至第三方 AI 服務的資料政策**:需確認帳號設定
67
+ - **LLM API 呼叫的重試機制與逾時處理**
68
+ - **Session 輸出目錄的清理機制**
69
+ - **語料說明「略過」後事後補填、上傳檔案大小上限**:需業主決定
70
 
71
  ---
72
 
73
  ## 一、專案背景
74
 
75
+ `SpectraEngine` 是一套針對重譯文本(retranslation)語言特徵的量化分析平台,技術上是 **Python + Gradio 單頁研究工具**(`app_agent.py`,4232 行;樣式已於改版期間抽出為 `assets/app.css`),並非傳統前後端分離的 HTML/CSS/JS 網站,部署在 Hugging Face Spaces。系統採雙 Agent 架構:主 Agent(LLM1)負責研究情境引導與報告撰寫,工作程序 Agent(LLM2)負責上傳引導與格式驗證。
76
 
77
  本次改版目標:**優化操作流程與介面風格**,方向參考 ChatGPT/Claude 網頁版的排版與操作體驗,同時修正過程中發現的既有問題。
78
 
 
84
  | 本地路徑 | `500_Projects\致理應日系-譯彩紛呈分析引擎`(`origin`=fork 可推,`upstream`=業主原始repo 唯讀) |
85
  | 本機測試 | `.venv` 已建置,`python app_agent.py` 啟動於 `http://127.0.0.1:7860`;無 API key 也能看主頁畫面,LLM 對話功能需 `.env` 填 `LLM1_API_KEY`/`LLM2_API_KEY` |
86
  | 測試套件 | **無**,每次改動需手動跑過完整流程驗證,不能只憑程式碼檢查 |
87
+ | 風險分區 | `assets/app.css` 純樣式、低風險(改版期間已從主檔 `_CUSTOM_CSS` 常數抽出為獨立檔案);`create_app()`(2561行起)版面配置、中風險(勿動 `.click()`/`.change()` 事件綁定);`handle_*` 流程函式(1510行起)與核心運算函式(320–1330行)為高風險,**改版不應觸碰** |
88
  | Gradio 版本 | 6.20.0(`footer_links` 等新版 API 可用,不需 CSS hack) |
89
 
90
+ ## 三、已確認的既有 Bug(本次改版已全數修正,非新功能)
91
+
92
+ > 本章各 Bug 標示的行號為**修復前**的位置,保留作為問題描述的一部分。這些 Bug 均已修復,且改版期間全檔行號已大幅位移(樣式抽出為 `assets/app.css` 後位移近兩千行),請勿直接以這些行號定位現行程式碼。
93
 
94
  ### Bug 1:選定研究情境後無法變更
95
  - **位置**:`app_agent.py` 第 3170–3171 行
 
154
 
155
  ## 五、資訊架構設計
156
 
157
+ ### 5.1 首頁(品牌介紹+單一入口)
158
+ - 單欄置中:品牌名稱+大標題+簡短說明(`_build_homepage_hero_html()`,app_agent.py:2520)
159
+ - **首頁只有一顆「開始研究分析」主按鈕**(`start_analysis_btn`,app_agent.py:2599),點擊後進入工作區
160
+ - **情境選擇不在首頁**:2026-07-30 業主要求把情境選擇從首頁搬回工作區,成為步驟列的正式第 1 步「研究選擇」。情境卡片改在工作區的 `scenario_select_row` 呈現(卡片渲染邏輯見 `_build_scenario_cards_html()`,app_agent.py:2498)
161
+ - 情境卡片說明文字(沿用 `SCENARIOS` 字典的 `desc` 欄位改寫,現於工作區第 1 步顯示):
162
 
163
+ | 情境 | 卡片說明文字 |
164
  |---|---|
165
  | 1. 人工翻譯 vs 機器翻譯 | 比較人工與機器譯本在語言特徵上的差異,聚焦人機翻譯風格對比。 |
166
  | 2. 全譯 vs 編譯(節譯、改寫) | 比較完整翻譯與節譯/改寫版本,聚焦文本完整性與改寫策略。 |
167
  | 3. 不同譯者的同期譯本 | 比較同一時期不同譯者的譯本,聚焦個人風格差異(已排除時代因素)。 |
168
  | 4. 同一原文的不同時期人工譯本 | 比較同一原文在不同時期的譯本,聚焦歷時語言變化與翻譯規範演變。 |
169
+ - 「讀取進度」目前是**首頁下方的佔位連結,標示「功能開發中」**(`_build_homepage_footer_html()`,app_agent.py:2548),尚未實作(見第八節)
170
 
171
  ### 5.2 導覽層級:頂部步驟列 vs 左側「結果導覽」
172
  兩者互補、不衝突,但視覺上要做出層級差異避免使用者誤認重複:
 
174
  | | 頂部步驟列 | 左側結果導覽 |
175
  |---|---|---|
176
  | 性質 | 時間軸型:進度到第幾步 | 空間型:跳著看已完成結果 |
177
+ | 內容 | ①研究選擇②文本上傳③語料說明④分析運算(共 4 步,見 `_STEPS` app_agent.py:1437)。「分析運算」底下再分指標計算/統計分析/報告撰寫三個子階段,以 Canvas 內容區塊分段呈現,不佔步驟列位置(見 `_ANALYSIS_STAGES` app_agent.py:1445)| AI對話/語言指標分析/敘述統計/差異性分析/監督式學習/非監督式學習/LLM輔助分析/技術執行紀錄 |
178
+ | 生命週期 | 全部完成(第4步)後**隱藏**,讓畫面空間交給結果內容 | 分析開始前不出現;完成後接手成為主要瀏覽方式,與步驟列隱藏的時機交接一致。各項目在對應結果產出前為 disabled 狀態 |
179
 
180
+ **步驟列沿革**(原始規劃 7 步 → 最終 4 步):2026-07-24 運算階段重構,格式驗證退為「文本上傳」的內部處理,指標計算+統計分析+報告撰寫合併為「分析運算」單一步驟,收斂為 3 步;2026-07-30 業主要求情境選擇從首頁搬回工作區,補回為第 1 步「研究選擇」,成為現行的 4 步。
181
+
182
+ **左側結果導覽沿革**:①「統計比較分析」父項與 Accordion 展開機制已於 2026-07-24 拿掉,四個統計子頁直接平鋪在導覽列上 ②「技術執行紀錄」已於 2026-07-23 從對話區底部的手風琴轉正為獨立頁面,成為結果導覽的第八個項目(`nav_exec_btn`,app_agent.py:2838)
183
+
184
+ ### 5.3 情境標籤
185
+ - 進入工作區後常駐顯示「目前情境」小標籤,**獨立於步驟列存在**(步驟列隱藏後仍要留著)
186
  - 格式:「情境:3. 不同譯者的同期譯本 [變更]」
187
+ - 位置:工作區右欄頂部,與步驟列同一區塊(app_agent.py:2902 起)。原規劃寫「全頁最上方」,後因首頁也會看到而改為只在工作區顯示
188
+ - 「變更」連結沿用「開始新分析」的未儲存警示機制(換情境=重新開始,同一套邏輯/同一個 Bug 1 修法,見 app_agent.py:3763)
189
+ - 註:情境選擇已於 2026-07-30 搬回工作區成為第 1 步,本標籤仍保留,作為步驟列隱藏後辨識目前情境的依據
190
 
191
  ## 六、版面配置
192
 
 
194
  左欄導覽(窄)+右欄主畫面。原因:「執行進度」已在業主上一版整併進頂部步驟列,不需要獨立第三欄。
195
 
196
  ### 6.2 左側導覽列
197
+ 最終實作結果:
198
+
199
  ```
200
  ┌─────────────────────┐
201
  │ 🆕 開始新分析 │
 
202
  ├─────────────────────┤
203
  │ 情境:X. ○○○○ [變更] │ ← 分析開始後才出現
204
+ │ 💬 AI 對話 │
205
  │ 📊 語言指標分析 │
206
+ │ 敘述統計 │ ← 四個統計子頁平鋪,
207
+ │ 差異性分析 │ 無父項、無 Accordion
208
+ │ 監督式學習 │
209
+ │ 非監督式學習 │
 
210
  │ 📝 LLM輔助分析 │
211
+ │ 📁 技術執行紀錄 │ ← 2026-07-23 從對話區
212
+ ├─────────────────────┤ 底部手風琴轉正為獨立頁
213
+ │ ⬇️ 下載指標數據 │ ← 指標計算一跑完即可下載
214
+ │ ⬇️ 下載統計圖表 │
215
+ │ ⬇️ 下載研究報告 │
216
+ │ ⬇️ 下載完整分析資料 │ ← 內容為空的那包不會出現
217
  └─────────────────────┘
218
  ```
219
  - 固定窄寬 240–280px
220
+ - **桌面版可收合**成 ChatGPT 式細窄 icon bar(`nav_collapse_toggle`,收合狀態存 localStorage)
221
+ - **手機版**:漢堡選單/抽屜收合(`mobile_nav_toggle`/`nav_drawer_close`/`nav_backdrop`),預設只顯示對話主畫面,點擊展開側欄
222
+ - **與原規劃的三處差異**:
223
+ 1. 「讀取進度」不在左側導覽,改放首頁下方(目前為「功能開發中」佔位連結)
224
+ 2. 「統計比較分析」父項與 Accordion 展開機制已於 2026-07-24 移除,四個子頁直接平鋪
225
+ 3. 置底「⚙️ 設定 🔌 API」連結列已移除(commit `d928c91`),改由 Gradio 原生 `footer_links` 處理(見第十節)
226
 
227
  ### 6.3 右欄(對話畫面)
228
+ 最終實作結果(三欄式工作區:左側導覽/對話欄/Canvas 內容區):
229
+
230
  ```
231
  ┌──────────────────────────────────────────┐
232
  │ 情境:3. 不同譯者的同期譯本 [變更] │ ← 常駐情境標籤
233
+ │ ① 研究選擇 ② 文本上傳 ③ 語料說明 ④ 分析運算 │ ← 頂部步驟列(4步,完成後淡出)
234
  ├──────────────────────────────────────────┤
235
+ │ 對話串(AI訊息左側/使用者訊息右側) │
236
+ │ [Metadata 步驟 → Canvas 區插入獨立表單卡片, │
237
  │ 不套用聊天泡泡左右分欄邏輯,佔滿全欄寬, │
238
+ │ 同頁面往下捲動、非彈出視窗] │
 
 
239
  ├──────────────────────────────────────────┤
240
+ │ 📎 [ 輸入文字,或附加檔案… ] 送出 → │ ← gr.MultimodalTextbox
241
  └──────────────────────────────────────────┘
242
  ```
243
+ - 對話與上傳採 `gr.MultimodalTextbox`(app_agent.py:2891)
244
+ - **與原規劃的兩處差異**:
245
+ 1. 「技術執行紀錄」不再是對話區底部的收合手風琴,已於 2026-07-23 轉正為左側導覽的獨立頁面(見 6.2)
246
+ 2. 版面從二欄調整為三欄(導覽/對話/Canvas):結果內容與表單卡片改在獨立的 Canvas 區呈現,切換到結果類頁面時對話欄收起、Canvas 佔滿寬度,切回「AI 對話」時對話欄彈回
247
 
248
  ### 6.4 結果分頁排版
249
  | 分頁 | 內容 | 排版決策 |
 
253
  | 📈 統計-2 差異性分析 | 表格+箱形圖+下載 | 圖表在上、表格在下,先看圖抓重點 |
254
  | 📈 統計-3 監督式學習 | 特徵重要性表格+圖(現有左右並排) | 沿用;側欄縮窄後放不下則改上下堆疊 |
255
  | 📈 統計-4 非監督式學習 | 樹狀圖+Elbow並排/PCA全寬/分群表格 | 沿用現有配置 |
256
+ | 📝 LLM輔助分析 | 報告文字+下載 | 舒適閱讀排版(適中行寬、寬鬆行高)|
257
+ | 📁 技術執行紀錄 | 逐行執行 log | 弱化字級;2026-07-23 從對話區底部手風琴轉正為獨立頁面 |
258
 
259
  ## 七、語料 Metadata 說明表單
260
 
 
273
  |---|---|
274
  | 防手滑 | `beforeunload` 事件,離開頁面前跳出確認(2026-07-24 已實作:僅在工作區顯示期間生效,回到首頁自動解除。瀏覽器規定使用者需先與頁面互動過確認框才會出現,且提示文字由瀏覽器決定,無法自訂) |
275
  | 中途下載 | 任一步驟完成即可下載當前已產出的部分成果 |
276
+ | **存檔/讀檔** | 核心機制,**本次改版未實作**。首頁下方目前是標示「功能開發中」的佔位連結(`_build_homepage_footer_html()`,app_agent.py:2548)。規格:存檔內容**含原始上傳文本**(不只中繼結果),確保讀檔後完整還原、不用重新上傳;讀取進度入口在首頁,讀檔後直接跳過首頁回到中斷步驟。技術評估與實作選項見《開發優化建議》第二節 |
277
  | 檔名/格式區分 | 存檔用自訂副檔名(如 `.spectra`),次要按鈕樣式+警語;成果下載才用一般格式+醒目主色按鈕,避免非技術使用者誤認「中繼存檔=最終成果」 |
278
  | 多開分析 | 不需特別開發——開新分頁天生是獨立 session(Gradio `session_hash` 機制);僅需在首次進站提示註明「建議同時只跑一個分析,以確保運算速度」(避免多分頁同時佔用運算資源) |
279
 
 
344
  ### 13.1 空狀態(Empty States)
345
  | 情境 | 設計方向 |
346
  |---|---|
347
+ | 首頁初訪 | 單欄置中:品牌介紹+「開始研究分析」單一入口+讀取進度佔位連結(見五之5.1)。情境卡片已搬至工作區第 1 步 |
348
  | 結果分頁在分析尚未開始時 | 現有已有 `_EMPTY_HINT` 元件(置中圖示+提示文字,內容近似「尚未產生資料/請先於主頁完成分析流程」),**沿用現有設計**,只需適配新版面(右欄/左側結果導覽)位置 |
349
  | 左側「結果導覽」在分析未開始前 | 整段不顯示(已決定,見六之6.2) |
350
  | 讀取進度但尚無任何存檔可讀(新功能首次使用) | 需設計提示文案;使用者第一次使用本系統不會有任何存檔,按下「讀取進度」前應清楚說明這是「上傳先前下載的存檔」,不是「系統幫你保存的雲端紀錄」 |
 
373
  1. ~~「下載完整報告」是否要做真正的 zip 整包後端邏輯~~ → 2026-07-24 已直接實作完成,不需業主拍板(見第四節缺口 1、第九節)
374
  2. 是否要做「Metadata 略過後事後回來補填」功能(本次不做,只調整文案)
375
  3. Session 輸出目錄的清理機制(維運層面,非 UI/UX 範圍,但影響 Hugging Face Space 長期磁碟空間)
376
+ 4. 是否要設定上傳檔案大小上限(目前無任何限制,異常巨大檔案可能拖慢運算或超出 Gradio 上傳限制),不急迫,可延後決定
377
+
378
+ 以上第 2-4 項的現況說明與建議,見《開發優化建議》第四節、第七節。
379
 
380
  ## 十五、更新紀錄
381
 
 
386
  | 2026-07-20 | 「監督式學習」「非監督式學習」補下載按鈕確認要做(移出待業主清單),命名定為「下載監督式學習」/「下載非監督式學習」;格式驗證每組檔案數下限確認為既有缺陷修正、非待業主確認事項;精簡缺口3內容;補充 Metadata 表單四種情境皆會出現、差異僅在內容的說明 |
387
  | 2026-07-20 | 開始與 UI/UX Pro Max Skill 協作視覺設計:確定風格方向(對話區參考AI-Native UI、結果分頁參考Data-Dense Dashboard)、字體(英文數字Crimson Pro+中文維持Noto Sans TC)、配色(維持業主既有雙主題系統,WCAG對比度驗算通過,不重新設計) |
388
  | 2026-07-24 | 缺口 1「整包下載」改為直接實作完成(原訂只做假按鈕交業主拍板),第九節下載機制改寫成四顆下載捷徑的實際規格,待業主確認清單第 1 項結案;持久化機制的「防手滑」(`beforeunload`)同步實作完成 |
389
+ | 2026-08-06 | **全文同步為最終實作結果**(對應 commit `f8aab79`):新增「本次改版完成項目總覽」章節;5.1 首頁改寫(情境卡片已於 2026-07-30 依業主要求搬回��作區成為第 1 步,首頁只留品牌介紹+單一入口);5.2 步驟列由 7 步更正為 4 步、補上左側導覽的最終項目與沿革;6.2/6.3 版面圖改為實作結果(下載捷徑四顆、技術執行紀錄轉正為獨立頁、置底設定/API 連結列移除、二欄改三欄);6.4 補技術執行紀錄頁;第八節註明存檔/讀檔未實作;13.1 首頁空狀態更新;第十四節移除校徽識別項(已確認不做);第二節風險分區行號更新(CSS 已抽出為 `assets/app.css`,全檔行號位移) |
390
  | 2026-07-24 | 運算階段重構:步驟列收斂為 3 步(文本上傳/語料說明/分析運算),格式驗證退為文本上傳內部處理、指標計算+統計分析+報告產出合併為「分析運算」單一步驟;分析運算改用 Canvas 內容區塊分段呈現三子階段(進度→摘要+查看入口)。Bug 3(步驟列失敗視覺狀態)與報告產出失敗的誠實呈現一併落地:報告失敗不再誤報「全部完成」,步驟列標紅、對話總結據實說明「指標與統計已完成、僅報告未產出」。結果導覽項目在對應結果產出前 disabled |
391
 
392
  ---