docs/architecture.zh-TW.md

# 架構說明

## 切換價值與任務延續

只在真正的任務階段邊界路由，不因每個 Prompt 重選。Context Router 仍負責對話位置，Model Router 使用實際位置與延續理由。拒絕交接時使用保留的對話；Context-off 不代表已評估對話適合程度。兩個 Router 不更名。

先依任務選出最低足夠與建議設定，`upgrade_value` 比較這兩組。接著用 `switch_assessment` 比較同一剩餘階段中，從已觀察的目前組合切到建議組合，與維持組合的收益。即使較強候選有能力價值，仍可維持適任的目前設定。高難度階段結束後重新評估，不自動降級。

計入剩餘工作、設定、快取重用、延遲、重試、返工及交接成本。快取狀態與傳入的對話內容不同：快取未命中不會刪除歷史，新對話不是免費切換，只調強度也可能依平台規則影響快取。目前組合未知時暫緩自動切換，仍交付具體任務型建議；快取成本未知不等於零或必然失效，明確品質缺口仍可支持變更。使用者明確指定的目標優先，但不能補足宿主缺少的操作能力。

`auto` 只有值得、已授權且可驗證的變更才套用；`ask` 只確認變更與關鍵阻礙。retain／不影響工作的 defer 繼續已授權工作；只要求計畫不開始實作。路由區塊先動作、後原因，切換分數留在內部。

評估比較任務完成、品質、修正次數、返工、延遲與整體工作成本；可觀察時才納入快取用量。API 計費與訂閱用量分開，不重複計入快取處理成本，不捏造未知量測。新增切換案例是驗收素材，不代表已證明宿主行為或節省幅度。

## 設計目標

Adaptive Task Routing 用來減少不必要的 Context 與運算消耗，同時確保 Routing 建議不會超越使用者授權或宿主環境能力。

Plugin 包含一個薄型協調入口、兩個獨立決策 Skill 與一份共同執行規範：

```text
使用者任務
    │
    ▼
完成使用者要求的分析或計畫
    │
    ▼
adaptive-task-routing（載入子元件、協調順序）
    │
    ▼
task-context-router ──► Context 建議
    │                   CURRENT / HANDOFF / CLEAN
    ▼
依使用者模式＋環境能力確定 Context
    │
    ▼
research-model-router ─► 最低足夠＋建議 Model／Reasoning 組合
    │
    ▼
依授權與未決事項繼續或詢問
    │
    ▼
取得授權後執行下一階段
```

## 分工界線

| 元件 | 負責 | 不負責 |
|---|---|---|
| `adaptive-task-routing` | Gate 時機、讀取子元件、順序、合併顯示 | Context 判斷、模型判斷、第三套自治模式 |
| `task-context-router` | Context 延續、交接與隔離 | 模型選擇、主要研究 |
| `research-model-router` | 最低足夠與建議模型／強度，以及升級價值 | 建立 Context、主要研究 |
| 共同 Runtime Policy | 能力偵測、控制模式、執行者、持久化 | 各 Router 的任務判斷 |

兩者分開後，使用者可以在 Context 建立可自動執行、目前模型只能由使用者調整時，設定 `context_mode: auto` 與 `model_mode: ask`。

入口透過套件內相對連結讀取兩個子 Skill 的 `SKILL.md`；不能使用本機檔案時，改用宿主提供的 Skill 資源。協調流程內的子元件不彼此呼叫，也不回頭呼叫入口。宿主若把一般任務直接選到子元件，子元件只轉交入口一次，協調委派標記會阻止循環。明確只問 Context 或 Model 時維持單一元件範圍。子元件缺失時明確回報 Gate 未完成，不捏造結果。

## 觸發與 Gate 生命週期

明確選取協調入口後會執行完整流程。三個平台產物也加入宿主原生提醒：Codex 與 Claude Code 在 `UserPromptSubmit` 注入一段簡短指令，Gemini CLI 則於工作階段啟動時載入 Extension 的 `GEMINI.md`。Codex 與 Claude 會在符合條件的下一階段前呼叫協調入口；Gemini 則直接套用啟動 Context 內嵌的完整精簡契約，因為 CLI 0.59.0 可能向模型宣告 `activate_skill`，實際呼叫時卻回傳 `tool_not_registered`。三個平台都必須先呈現使用者要求的分析或計畫，再顯示路由建議。宿主誤選子元件時，由一次性轉交守門補回完整流程。

只要求分析或計畫時，先完成並呈現已授權交付物，再於回覆結尾為具體實質下一階段執行 Gate。已要求執行時，先呈現精簡可執行計畫，再於修改或大量執行前路由。Model `ask` 只在變更或關鍵阻礙時詢問，retain／非阻礙 defer 繼續已授權工作；Model `auto` 套用仍需能力及驗證。完整答案沒有具體實質下一階段時正常結束；後續階段改變時先呈現已完成階段的結果，再只重跑 Model Router，除非 Context 也需要重新判斷。

階段、實際 Context、偏好、模型清單與能力均未變時，重用已完成 Gate。兩個模式均 `off` 時不評估、不探測、不輸出；僅一者關閉時另一者照常。Context-off 留在目前對話；Model-off 保留目前設定。保留設定不再要求確認，是否能執行取決於原本的工作授權。

使用者在 `ask` 拒絕 Context 改變時，Model Router 評估實際的目前 Context。目的地待確認且其模型選項未知時，明確顯示 Model Gate 延後與目前可取得的設定，並在目的地開始工作前重檢。不能靜默略過第二步或把它算成完成。

## 模型結果必須可見

啟用的 Model Router 在內部記錄兩組任務設定與依據，再顯示動作、原因及有用的原生 AI 設定。精簡版省略模式與診斷資訊；確認保留時只顯示已觀察的目前 AI，其他適配設定放在詳細版。已知設定適合的 `CURRENT`，與 `assessment: unverified` 的暫時維持不同。可選模型清單不能證明目前正在使用哪個模型。未知的控制方式不能變成捏造的名稱、設定、選單或指令。

輸出 Schema 可用精簡訊息呈現。每段訊息接在任務發現或計畫之後，以 Markdown 分隔線、簡潔的 `Adaptive Task Routing` 標題，之後直接顯示動作、原因、啟用的對話去留建議及有用 AI 設定。對話路由的穩定代碼只保留在結構化證據；畫面依使用者語言直接顯示白話建議，不附英文代碼。`off` 是刻意保留的例外：不做決策也不輸出。

## 三層判斷

每次決策分開處理：

1. **使用者政策**：允許多少自動操作。
2. **環境能力**：目前介面、工具與權限實際能做什麼。
3. **Routing 建議**：下一階段最適合的工作方式。

三者都確認後才決定由誰操作。能力未知時降級為使用者操作；只有宿主確認完成後才能輸出 `applied`。

0.3.1 對每項操作分別解析能力，不把整個介面歸成單一能力。App 可能支援 AI 建立 Context，但切換目前模型與強度仍是 `user_only`；CLI 也可能只有部分能力。使用者直接要求特定操作代表授權，但不能補足缺少的能力。每項自動操作仍須可呼叫且可驗證。

## 環境生命週期

第一次執行先從宿主或使用者管理的設定區讀取能力快照，再偵測缺少或過期的操作。後續 Routing Gate 只檢查新鮮度；介面、Session、宿主／Plugin、權限、工具或操作結果改變時，重新偵測受影響能力。自動操作失敗會立即讓該項快取能力失效。

不可把已安裝 Plugin 目錄當成可變狀態儲存區，因為更新可能覆寫內容。

可用模型清單的生命週期比能力快照短。優先使用 Runtime 資料，並在 Session 或宿主定義的短期限內快取；使用者提供的清單要標示來源，靜態備援必須有版本與有效期限。OpenAI App 無法提供 Runtime 資料時，Router 立即使用內建的官方跨介面參考產生最低足夠與建議兩組設定，不先要求使用者抄寫選單；Gemini CLI 使用獨立的穩定別名參考並保留平台原生 Reasoning 控制，沒有觀察到 `thinkingBudget` 或 `thinkingLevel` 時顯示「使用模型預設」。帳號可用性仍標為未驗證。`ask` 只為值得變更或使用者指定的目標顯示控制，有關鍵阻礙才另行詢問；`auto` 只有在切換操作可呼叫、已授權且可驗證時才套用，否則把控制列為可選操作並沿用目前設定繼續。無法讀取的目前欄位只留在結構化證據，不顯示於精簡結果。模型清單、目前執行設定、能力證據與切換能力彼此分開。

只有使用者質疑推薦或要求依目前帳號確認時，才考慮索取額外權限。Router 先說明證據與限制；只有具體途徑能讀取同一個 App 或 Session 的模型清單時，才詢問一次最小必要唯讀權限。能讀到另一個 CLI 程序不符合條件。使用者拒絕後沿用備援，直到相關環境或使用者要求改變前不再詢問。

## 跨平台策略

0.4.2 將任務需求與具體候選映射分開，並加入自動啟動提醒。探測附來源／時間／範圍／狀態；保存值及磁碟預設不填入未知即時欄位。官方描述只作能力參考，不是帳號清單或任務實測排名。[宿主指引](../shared/host-discovery.md) 按需載入；Codex 選用 helper 只做有界限的唯讀 RPC，不恢復對話、不選模型、不切換。Claude／Gemini 使用自己的 metadata 或選單指引；新 CLI 程序不等於 App 連線，讀取與寫入能力分開判斷。

根目錄 `skills/` 與 `shared/` 是唯一維護來源；Skill 名稱維持不變，frontmatter 描述與受檢查的觸發契約會區分主要協調入口和單一元件子 Router，主體與翻譯一起演進。`release.json` 統一管理版本、識別與展示資訊，建置時由 `scripts/release_lib.py` 產生平台 Manifest：

- OpenAI：根層 `plugin.json`（Agent Plugins schema；展示資料在 `extensions.com.openai.interface`）及含 `UserPromptSubmit` hook 的 `.codex-plugin/plugin.json` 相容 Manifest。
- Claude：`.claude-plugin/plugin.json` 與 `hooks/hooks.json`。
- Gemini：根層 `gemini-extension.json` 與由 `contextFileName` 指定、內容自足的 `GEMINI.md`。

`scripts/build_release.py` 建立 `dist/<平台>/adaptive-task-routing` 三個解壓目錄與三個 ZIP；ZIP 沒有外包目錄。共同文件以明確清單封裝，平台 README 來自 `packaging/<平台>/README.md`；排除建置及測試程式，唯一允許封裝的執行程式來源是選用的 Skill helper。自動啟動使用宣告式 Context 或輸出固定文字的 hook，不探測 metadata、不啟動服務，也不自行執行 Router。

沒有第四個 Marketplace ZIP，本機登錄是獨立的宿主設定步驟。驗證涵蓋相對連結、frontmatter、觸發契約、自動啟動定義、共用檔、版本、平台隔離、目錄與 ZIP 內容及 SHA-256。檔案驗證可證明提醒與兩份 Gemini 契約投影已封裝；宿主是否實際送入並遵循提醒或完成設定切換，仍須用已安裝環境測試。

## 預設值

兩個 Router 預設 ask，只在變更或關鍵阻礙時詢問。retain／非阻礙 defer 只繼續已授權工作；計畫交付不等於實作授權。模型保留不能蓋過待決定的對話交接。

## 行動優先 UX 契約

[共用 UX 契約](../shared/routing-ux.md) 定義 compact／detailed 顯示偏好，不新增路由模式。精簡版保留啟用的對話去留建議和有用的 AI 設定；詳細版增加最低足夠、任務適配與升級理由。兩組設定仍在內部計算。未知設定用暫時沿用，不假稱適合；對話交接可同時需要模型變更。Gemini 的啟動檔與協調入口附錄均內嵌同一契約。