AlanPai 開發進度全貌圖（dev-progress-map）
把一個多里程碑開發專案的「走到哪了」畫成一張三層式地圖＋一段白話故事。 設計給非工程背景的專案主人看：他要的是位置感（我在哪、離終點多遠），不是工項清單。
精神：三層鏡頭
一張圖同時回答三個尺度的問題，像地圖的三段縮放：
- 遠景（第 0 章橫幅）：已經整段完結的大階段，壓縮成一條綠色橫幅＋一句「產出了什麼」。 已完結的東西不需要細節，它的作用是給成就感和上下文。
- 中景（里程碑軌道）：整個開發計畫的所有里程碑排成一條軌道，每站一張小卡， 掛「你在這裡」徽章。這層回答「全程有幾站、我在第幾站」。
- 近景（放大鏡）：只把當前那一站的內部步驟展開成第二條軌道（例如九步循環、 sprint 內任務），掛「現在」徽章。這層回答「這一站裡我還差什麼」。
只放大當前站，其他站不展開——資訊量的紀律就是這張圖好讀的原因。
第一步：查資料（不憑記憶）
進度天天變，畫圖前必須先讀最新檔案，即使你自認記得：
progress.md（或專案的進度交接主檔）——目前狀態、最近大事、下一步。- 路線圖文件（常見：
docs/sdd-roadmap.md、ROADMAP.md）——里程碑的正式定義與依賴。 用 Grep 抽里程碑表格，不要憑印象寫里程碑內容；印象與正式定義的落差就是誤導的來源。 - 本次對話脈絡——今天剛完成、剛拍板的事可能還沒回寫進文件。
找不到路線圖文件時：從 progress.md、git log、README 盡力重建，並在敘事裡明講 「以下依 ×× 推斷，專案沒有正式路線圖」——寧可標注來源不足，不可假裝權威。
第二步：抽內容
- 第 0 章：已整段完結的時期（規劃期、研究期…）→ 一句話列產出物鏈（A → B → C）。
- 里程碑軌道：全部里程碑，上限約 12 站（更多就合併遠期的）。每站三行： 編號（M4）＋白話名（≤6 個字）＋狀態。白話名是關鍵——把「P0-1 地基 schema」 改寫成「帳本地基＋引擎」、「cutover」改寫成「新舊並行→切換」。改寫時保留原編號， 讓它跟正式文件對得上。
- 放大鏡：當前里程碑的內部步驟（照該專案的方法論，例如九步循環①~⑨）， 同樣格式。部分完成的步驟用「◐ 後端✅ 前端⬜」這種拆半標法。
- 驗收閘：需要外部條件才能過的關卡（設備到位、連續 N 天零差異）標成虛線框， 它們不是「做了就完成」的工項，視覺上要區分。
第三步：畫圖
狀態詞彙固定四態＋閘，圖例必附：
| 記號 | 意義 | 視覺 |
|---|---|---|
| ✅ | 完成 | 綠色邊框＋綠字 |
| ◐ | 部分完成 | 黃/琥珀字 |
| ▶ | 進行中（目前位置） | 強調色粗框＋「你在這裡」徽章 |
| ⬜ | 未開始 | 整卡淡化（opacity ~0.6） |
| 虛線框 | 驗收閘 | 虛線邊框 |
顏色紀律：只有兩組語義色（綠＝完成、強調色＝現在），其他一律中性。
主題適應：用宿主環境的 CSS 變數（--surface-*、--border、--text-*、--radius、
--font-sans/mono），不寫死背景色，深淺色主題都能看。
渲染管道（依環境擇一）：
- 有
show_widget（visualize MCP）→ 先呼叫其 read_me（diagram 模組），再用assets/widget-template.html為骨架填內容渲染。 - 沒有 widget 工具 → 產出同樣 HTML 存檔，用 Artifact 或 SendUserFile 給使用者；
都沒有就退化成 Markdown 表格＋文字軌道（
M1✅─M2✅─▶M4─M5⬜…）。
模板骨架見 assets/widget-template.html（讀它、換掉註解標記的三段內容即可）。
第四步：白話敘事（固定四段，寫在圖下方的回覆文字裡）
圖管「位置」，文字管「意義」。四段結構：
- 已經走完的路——講每段的價值（「這一章的價值是：後面每次寫程式都有依據可查」）， 不是重複工項清單。
- 現在的位置——精確到步驟；剩下的事按順序編號列出，每件一句話。
- 後面的路——每個未來里程碑一句白話（「M7 出庫線：接單→揀貨→出貨， 整個系統最複雜的一條線」）。
- 量級感——每站是天級/週級/月級、目前大約走到全程幾分之幾， 並指出「最難的部分是否已付清」這類讓人安心或警醒的判斷。
寫作紀律：對非工程背景的讀者，技術名詞第一次出現先用生活類比； 圖裡放過的內容文字不重複，文字補圖給不了的「為什麼重要」。
常見錯誤
- ❌ 憑記憶畫圖（progress 文件才是事實）
- ❌ 每一站都展開細節（只放大當前站）
- ❌ 卡片名照抄文件術語（要白話改寫、≤6 字、保留編號）
- ❌ 五顏六色（兩組語義色＋圖例）
- ❌ 圖和文字講重複的話