關鍵運行場景

概述

本文件詳細描述 SuperPortia 五個最關鍵的運行場景，包含正常路徑（Happy Path）、異常路徑（Error Path）、Quality Gate、HITL Gate 及 Rollback 路徑。這些場景覆蓋了系統中風險最高、最需要一致性的業務流程。

Scenario 1：工單從建立到交付

WO Creation → Dispatch → Implement → Review → Approve → Deploy

參與者

Agent	信任區域	角色
夏哥 / 小克（Opus）	Zone 0 / Zone 1	WO 建立者 / 首席工程官
小克（Sonnet subagent）	Zone 2	實作執行者
PAM（Agent）	Zone 4	自動狀態管理
夏哥	Zone 0	最終批准者

正常路徑

建立 WO — 小克（Opus）呼叫 create_work_order()，填寫 title、description、priority、assignee
Dispatch — Opus 呼叫 Agent tool (model: sonnet)，傳入 WO ID + context，worktree 隔離
Accept — Sonnet subagent 呼叫 update_work_order_status(status: in_progress)；WO Lease Gate 驗證無重複 accept
Implement — Sonnet 在 worktree 撰寫程式碼、執行測試、更新 CHANGELOG.md
Review Request — Sonnet 呼叫 update_work_order_status(status: review)，附上完成摘要
Quality Review — Opus review subagent 輸出、確認 Quality Gate 通過
Submit for Approval — Opus 向夏哥提呈：完成摘要 + diff 要點 + deploy 計畫
夏哥 Approve — 夏哥呼叫 curl 或 Dashboard 核准工單（update_work_order_status 不能 approve，需用 curl）
Deploy — Opus 執行 wrangler deploy（已通過 deploy-gate.sh，帶有 HITL 批准證明）
Post-Deploy Verify — take_screenshot + list_network_requests 確認部署正確
WO Close — update_work_order_status(status: done)，UB 入庫完工記錄

異常路徑

異常	偵測點	處理
Sonnet subagent 超時（120s）	Dispatch layer	Opus 重新 dispatch，或改用 Codex exec
WO Lease 衝突（多 Agent accept）	WO API gate	API REJECT 後 1 分鐘 backoff retry
deploy-gate.sh DENY	PreToolUse Hook	Opus 確認已取得夏哥批准，再次執行
Post-Deploy test 失敗	verify 步驟	觸發 Rollback 路徑
Sonnet 輸出不通過 Quality Gate	Opus review	重新 dispatch（最多 2 次），或升級為 Opus 直接修復

Quality Gates

CHANGELOG.md 已更新（changelog-gate.sh 強制）
Lint 通過（post-edit-lint.sh 強制）
測試覆蓋率未下降
Opus review 確認 diff 邏輯正確
Pre-deploy dry-run 通過（wrangler deploy --dry-run）

HITL Gates

必須: 夏哥批准 WO 才可執行 production deploy
必須: protected files 編輯需夏哥確認

Rollback 路徑

# Cloudflare Pages — rollback to previous deployment
wrangler pages deployment rollback <deployment-id> --project-name <project>

# Workers — revert to previous version
wrangler rollback <version-id>

# Git — 記錄 rollback 原因
git revert <commit-hash> -m "Rollback: <reason>"

Scenario 2：知識從產生到可搜尋

Discovery → ingest_fragment → UB Dock → MTAAA Classify → Promote → Searchable

參與者

Agent	信任區域	角色
任何 Agent（小克/Sonnet/SRE）	Zone 1-4	知識產生者
Cloud UB Worker	Zone 4	Ingest + FTS + Vectorize
boiler_grandpa_v2.py	Zone 4	MTAAA 分類執行者
DeepSeek V3	Zone 3	分類 LLM

正常路徑

Discovery — Agent 識別到值得記錄的知識（決策、研究、事故 RCA、架構發現）
Pre-check — search_brain() 確認無重複 entry
Ingest — ingest_fragment(title, content, tags) 呼叫 Cloud UB Worker /brain/ingest
Dock Landing — Worker 寫入 entries 表（UB Dock），同步建立 entries_fts FTS 索引
即時可搜尋（文字） — FTS 索引建立後，search_brain() 可搜尋到新 entry（延遲 < 1 秒）
MTAAA 等待分類 — entry 標記為 status: pending
boiler_grandpa 排程 — 每 5 分鐘，boiler_grandpa_v2.py 拉取 pending entries
DeepSeek 分類 — LLM 從 CV 選擇 Topic + Type + Lifecycle
Promote — Worker /ub/promote 將 entry 從 Dock 複製到 classified_entries（正區）
語意搜尋可用 — Vectorize 索引建立，search_brain() 語意相似度搜尋生效

異常路徑

異常	偵測點	處理
Ingest API 超時	Agent 呼叫層	retry 1 次，失敗後記錄 UB ID 為 null，session 結束前補錄
DeepSeek API 不可用	boiler_grandpa	fallback 策略（Task #65，尚未建置）；目前 entry 留在 Dock
CV 無匹配分類	DeepSeek LLM	回傳 `UNKNOWN`；標記 `needs_review`，不 promote
重複 entry	search_brain pre-check	Agent 中止 ingest，記錄已存在的 entry ID
text_batch_runner.py 未建置	102 筆 pending 積壓	Task #69 最高優先，建置後批次清除

Quality Gates

title 描述性、可搜尋、英文
content 自包含（讀者無需其他 context）
tags 符合 Controlled Vocabulary（lowercase, hyphenated, ≤ 8）
無重複（search_brain pre-check）

HITL Gates

無 HITL 要求；ingest 是 Zone 1-4 自主操作

Rollback 路徑

UB entry 一旦 ingest 不刪除（白帽記錄原則）。錯誤內容透過 update_entry() 修正，並附上 corrected: true 標籤。

Scenario 3：P0 事故偵測到修復

Health Monitor → SRE Alerter → Discord → Diagnose → Rollback/Hotfix → RCA

參與者

Agent	信任區域	角色
SRE Patrol（launchd）	Zone 4	自動健康巡邏
SRE Dispatch（launchd）	Zone 4	自動 WO 建立
小克（Opus）	Zone 1	事故指揮官
夏哥	Zone 0	最終決策者

正常路徑

Health Monitor — SRE patrol 每 15 分鐘執行，檢查所有服務端點健康狀態
異常偵測 — service HTTP 回應非 200，或回應時間 > 5 秒
P0 判定 — 生產服務中斷（Bridge API / UB Worker / Command Center）自動判定 P0
SRE Alerter — sre-dispatch.sh 建立 P0 WO，標題格式 [P0] <service> DOWN — <timestamp>
Discord 通知 — WO 建立觸發 webhook，通知 Discord #incidents 頻道（計畫中，G-10）
小克接單 — Opus session 接收 WO，開始診斷
Root Cause 診斷 — 查看 Worker 日誌、CF Dashboard、Git 最近 commit
Rollback 決策 — 是最近 deploy 引起？→ 立即 rollback；是外部依賴？→ hotfix
執行修復 — rollback 或 hotfix，HITL: 生產 deploy 需夏哥批准
驗證恢復 — 所有 health check 回到 200，回應時間正常
RCA 撰寫 — 完整 Root Cause Analysis 入庫 UB（tags: incident, rca, P0）
WO Close — 關閉事故 WO，附 RCA entry ID

異常路徑

異常	偵測點	處理
夏哥不在線（深夜）	HITL Gate	Opus 可執行 rollback（恢復比等待風險低）；事後補報告
多個服務同時中斷	SRE patrol	建立多個 P0 WO，Opus 按依賴順序排優先（DB → API → Frontend）
rollback 後問題仍存在	Post-rollback verify	升級為全面 hotfix，Opus 呼叫 Sonnet subagent 協助
SRE patrol 自身故障	launchd 健康檢查	手動觸發 `bash sre-patrol.sh`，修復後重啟 launchd 服務

Quality Gates

事故影響範圍已量化（影響的 API、用戶數、時間段）
Rollback/hotfix 已在 staging 驗證後才進 production
RCA 包含：Timeline、Root Cause、Impact、Fix、Prevention

HITL Gates

一般情況: Production deploy/rollback 需夏哥批准
緊急例外: 夏哥明確無法回應時，Opus 可自主 rollback，事後 24 小時內補報告

Rollback 路徑

與 Scenario 1 相同；優先使用 Cloudflare Pages/Workers 平台級 rollback（秒級恢復），不用 git revert。

Scenario 4：跨代理協作派工

Pre-Flight → Decompose → Dispatch Sonnet/Codex/Gemini → Quality Gate → Merge

參與者

Agent	信任區域	角色
小克（Opus）	Zone 1	Orchestrator — 分解、派工、Review
Sonnet subagent	Zone 2	程式碼實作
Codex CLI（gpt-5.4）	Zone 3	Code Review / 架構第二意見
Gemini CLI	Zone 3	PK 研究 / 批次草稿

正常路徑

Pre-Flight Check — Opus 評估任務複雜度（0-6 分）；≥ 3 分才值得多 Agent 協作
Decompose — Opus 將大任務拆分為可並行的子任務（確認無 shared file conflicts）
Worktree 建立 — 每個 Sonnet subagent 在獨立 git worktree 執行，避免衝突
並行 Dispatch — Opus 同時啟動多個 subagent（實務上限：3-5 個 / laptop）
Gemini PK 研究 — echo "prompt" | gemini，獲取 2026 最新實踐（免費，1000 req/day）
Codex 架構 Review — echo "review prompt" | codex exec，獲取第二意見
Subagent 完成 — 各 Sonnet subagent 回傳完成結果，更新 WO 狀態為 review
Opus Quality Gate — 逐一 review：檔案存在、大小合理、內容有具體細節、無範圍違規
Merge — 通過 review 的 worktree 合併至 main branch
整合測試 — post-merge 跑完整測試套件
Report — Opus 向夏哥匯報：完成哪些子任務、合併結果、下一步

異常路徑

異常	偵測點	處理
Subagent 輸出品質不通過	Opus Quality Gate	重新 dispatch 同一任務（max 2 retry），或 Opus 直接修復
Worktree file conflict	git merge	Opus 手動 resolve，或重新分配任務邊界
Gemini 輸出有幻覺	Opus cross-check	Gemini 僅供參考，不可直接用於重要決策；用 Sonnet 交叉驗證
Codex exec 超時	Bash timeout	縮小輸入範圍，重試；或跳過 Codex review
超過 5 個並行 Agent	資源監控	等待現有任務完成後再啟動新 dispatch

Quality Gates（Opus 必須逐一確認）

輸出檔案存在於指定路徑
檔案大小合理（非空、非截斷）
內容包含具體數字/路徑/日期，無模糊描述
Wikilink 指向真實存在的 vault notes（若為 vault 內容）
無範圍違規（subagent 未修改分配外的檔案）

HITL Gates

無 HITL 要求（dispatch 是 Zone 1 自主操作）
例外：若派工結果要進 production deploy，仍需夏哥批准

Rollback 路徑

每個子任務在獨立 worktree，不影響 main branch。品質不通過直接丟棄 worktree，重新 dispatch。

Scenario 5：外部服務部署

Code Push → Dry-Run → Preview → HITL Approval → Deploy → Post-Deploy Verify

參與者

Agent	信任區域	角色
小克（Opus/Sonnet）	Zone 1/2	部署執行者
deploy-gate.sh	Zone 4	自動部署閘門
夏哥	Zone 0	生產部署批准者

正常路徑

Code Push — git push origin main（或 branch）；觸發 CI（若已設定）
Dry-Run 驗證 — wrangler deploy --dry-run（deploy-gate.sh 允許）；輸出 bundle size、routes
Preview 部署 — Cloudflare Pages 自動建立 Preview URL（每個 commit）
Preview 功能測試 — navigate_page(preview_url) + take_screenshot() + list_console_messages()
向夏哥提呈 — 摘要：改了什麼、Dry-Run 結果、Preview URL、風險評估
夏哥 HITL 批准 — 夏哥查看 Preview，確認後回覆「ok」或透過 Dashboard approve
Production Deploy — wrangler deploy 或 wrangler pages deploy（deploy-gate.sh 驗證 HITL）
Post-Deploy 驗證 — 所有關鍵路由 HTTP 200、FTS 搜尋正常、API 回應正確
CHANGELOG 更新 — 確認 CHANGELOG.md 已記錄本次部署（changelog-gate.sh 預防性檢查）
UB 入庫 — 部署記錄入庫（tags: deploy, production, <service>）

異常路徑

異常	偵測點	處理
Dry-Run 失敗	wrangler output	診斷 bundle error，修復後重新 dry-run
Preview 有 JS console error	list_console_messages	修復後重新 push，等待新 Preview
夏哥拒絕批准	HITL 回覆	記錄拒絕原因，修改後重新提呈
Production deploy 後功能異常	Post-Deploy verify	立即觸發 Scenario 3（P0 事故流程）
CF API Token 失效	wrangler error	按 infra-secrets.md 自行檢查 Dashboard，不詢問夏哥

Quality Gates

Dry-Run 無 error（只有 warning 可接受）
Preview URL 可正常訪問
Preview 所有功能路由驗證通過
CHANGELOG.md 已更新（版本、日期、變更摘要）
Post-Deploy 所有 health check 通過

HITL Gates

必須: Production deploy/publish 需夏哥明確批准
禁止: 任何繞過 deploy-gate.sh 的部署（--no-verify 等同違規）

Rollback 路徑

# Cloudflare Pages — 平台級 rollback（推薦，秒級）
wrangler pages deployment rollback <deployment-id> --project-name <project>

# Cloudflare Workers
wrangler rollback

# 緊急情況 — 回到上一個 git commit
git revert HEAD --no-edit
git push origin main
# CF Pages 自動重新部署

Rollback 後必須執行完整 Post-Deploy Verify，確認恢復成功。Rollback 記錄必須寫入 UB（tags: rollback, incident）。

關鍵運行場景

概述

Scenario 1：工單從建立到交付

參與者

正常路徑

異常路徑

Quality Gates

HITL Gates

Rollback 路徑

Scenario 2：知識從產生到可搜尋

參與者

正常路徑

異常路徑

Quality Gates

HITL Gates

Rollback 路徑

Scenario 3：P0 事故偵測到修復

參與者

正常路徑

異常路徑

Quality Gates

HITL Gates

Rollback 路徑

Scenario 4：跨代理協作派工

參與者

正常路徑

異常路徑

Quality Gates（Opus 必須逐一確認）

HITL Gates

Rollback 路徑

Scenario 5：外部服務部署

參與者

正常路徑

異常路徑

Quality Gates

HITL Gates

Rollback 路徑

指令面板

選擇主題