Spaces:
Sleeping
Sleeping
Commit
·
ed6729a
1
Parent(s):
1628958
docs: update copilot instructions and project plan for improved workflow and user experience
Browse files- .github/copilot-instructions.md +36 -13
- .github/prompts/project.apply.prompt.md +42 -27
- .github/prompts/project.plan.prompt.md +29 -13
- .github/prompts/project.report.prompt.md +45 -16
- .github/prompts/project.spec.prompt.md +39 -11
- .github/prompts/project.task.prompt.md +46 -29
- spec/plan.md +70 -30
.github/copilot-instructions.md
CHANGED
|
@@ -132,27 +132,50 @@ commit 前確認以下兩點:
|
|
| 132 |
2. 根據需求類型,讀取相應的 spec 模塊(`01-*` / `02-*` / `03-*` / `04-*`)。
|
| 133 |
3. LLM 掃描現有程式碼,列出符合、缺漏、或違反的地方。
|
| 134 |
4. 產出「需要做的工作清單」。
|
| 135 |
-
5.
|
| 136 |
|
| 137 |
-
### `/project.plan
|
| 138 |
-
-
|
| 139 |
- **流程**:
|
| 140 |
-
1.
|
| 141 |
-
2.
|
| 142 |
-
3.
|
| 143 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 144 |
|
| 145 |
### 標準工作流
|
| 146 |
|
| 147 |
**當需求改變時:**
|
| 148 |
-
1. 執行 `/project.spec` 討論規格調整
|
| 149 |
-
2.
|
| 150 |
-
3. 根據清單建立 `spec/plan.md`(定義本次迭代範圍)。
|
| 151 |
|
| 152 |
**執行迭代時:**
|
| 153 |
-
|
| 154 |
-
|
| 155 |
-
|
|
|
|
| 156 |
|
| 157 |
**下次需求改變時:** 回到步驟 1。
|
| 158 |
|
|
|
|
| 132 |
2. 根據需求類型,讀取相應的 spec 模塊(`01-*` / `02-*` / `03-*` / `04-*`)。
|
| 133 |
3. LLM 掃描現有程式碼,列出符合、缺漏、或違反的地方。
|
| 134 |
4. 產出「需要做的工作清單」。
|
| 135 |
+
5. **直接更新 `spec/spec.md`** → 等待使用者確認 → 確認後同步至 `README.md` 和 `spec/plan.md`。
|
| 136 |
|
| 137 |
+
### `/project.plan`(迭代規劃時用)
|
| 138 |
+
- **目的**:生成本次 sprint 的計畫,讓使用者在 MD 上討論和調整。
|
| 139 |
- **流程**:
|
| 140 |
+
1. 產生 `spec/plan.md`(包含迭代目標、高層任務列表、風險評估等)
|
| 141 |
+
2. **暫停等待使用者確認**(用戶可直接在 MD 上編輯)
|
| 142 |
+
3. 確認後,提示執行 `/project.task` 進行詳細任務拆解
|
| 143 |
+
|
| 144 |
+
### `/project.task`(任務拆解時用)
|
| 145 |
+
- **目的**:根據確認的 `spec/plan.md`,拆解為具體的任務步驟與程式碼變更點。
|
| 146 |
+
- **流程**:
|
| 147 |
+
1. 根據 `spec/plan.md` 的高層任務列表,生成詳細任務拆解(T-001、T-002 等)
|
| 148 |
+
2. 展示每個任務的具體變更點(檔案、行號、修改內容)
|
| 149 |
+
3. **暫停等待使用者確認**(用戶可調整任務順序或內容)
|
| 150 |
+
4. 確認後,提示執行 `/project.apply` 應用程式碼變更
|
| 151 |
+
|
| 152 |
+
### `/project.apply`(程式碼應用時用)
|
| 153 |
+
- **目的**:直接應用經過確認的程式碼變更。
|
| 154 |
+
- **流程**:
|
| 155 |
+
1. 根據 `spec/task.md` 的確認任務清單,直接應用所有程式碼修改
|
| 156 |
+
2. 執行語法/編譯檢查
|
| 157 |
+
3. 更新 `spec/task.md` 標記已完成的任務([x])
|
| 158 |
+
4. **暫停並提示使用者**:「程式碼已應用,請進行手動測試」
|
| 159 |
+
|
| 160 |
+
### `/project.report`(交付與清理時用)
|
| 161 |
+
- **目的**:記錄變更並清理臨時計畫檔案。
|
| 162 |
+
- **流程**:
|
| 163 |
+
1. 根據使用者已完成的測試結果,自動更新 `changelog.md`
|
| 164 |
+
2. 清理 `spec/plan.md` 和 `spec/task.md`(下次迭代時重新生成)
|
| 165 |
+
3. 生成交付報告(品質狀態、需求對齐等)
|
| 166 |
+
4. 提示用戶本次迭代已完成,可開始新迭代
|
| 167 |
|
| 168 |
### 標準工作流
|
| 169 |
|
| 170 |
**當需求改變時:**
|
| 171 |
+
1. 執行 `/project.spec` 討論規格調整
|
| 172 |
+
2. 直接在 `spec/spec.md` 上編輯 → 確認後同步至 `README.md` 和 `spec/plan.md`
|
|
|
|
| 173 |
|
| 174 |
**執行迭代時:**
|
| 175 |
+
3. 執行 `/project.plan` 生成計畫 → 在 `spec/plan.md` 上編輯 → 確認後執行 `/project.task`
|
| 176 |
+
4. 執行 `/project.task` 拆解任務 → 在 `spec/task.md` 上編輯 → 確認後執行 `/project.apply`
|
| 177 |
+
5. 執行 `/project.apply` 直接應用程式碼 → 手動測試 → 測試完成後執行 `/project.report`
|
| 178 |
+
6. 執行 `/project.report` 記錄變更 + 自動清理 plan 和 task
|
| 179 |
|
| 180 |
**下次需求改變時:** 回到步驟 1。
|
| 181 |
|
.github/prompts/project.apply.prompt.md
CHANGED
|
@@ -1,30 +1,45 @@
|
|
| 1 |
-
# /project.apply —
|
| 2 |
|
| 3 |
目的
|
| 4 |
-
- 根據使用者在 `/project.task`
|
| 5 |
-
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
|
| 9 |
-
-
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
|
| 19 |
-
|
| 20 |
-
|
| 21 |
-
-
|
| 22 |
-
|
| 23 |
-
|
| 24 |
-
|
| 25 |
-
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
-
|
| 29 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 30 |
|
|
|
|
| 1 |
+
# /project.apply — 應用程式碼變更
|
| 2 |
|
| 3 |
目的
|
| 4 |
+
- 根據使用者在 `/project.task` 中確認的任務,直接應用具體的程式碼變更。
|
| 5 |
+
- 更新 `spec/task.md` 標記已完成的任務。
|
| 6 |
+
- 等待使用者手動測試,測試完成後執行 `/project.report`。
|
| 7 |
+
|
| 8 |
+
輸入
|
| 9 |
+
- 使用者確認的任務拆解清單(來自 `/project.task`)
|
| 10 |
+
|
| 11 |
+
流程
|
| 12 |
+
|
| 13 |
+
### 自動執行
|
| 14 |
+
|
| 15 |
+
1. **直接應用程式碼變更**
|
| 16 |
+
- 根據 `spec/task.md` 的任務清單,應用所有程式碼修改
|
| 17 |
+
- 使用 `replace_string_in_file` 或 `insert_edit_into_file` 執行變更
|
| 18 |
+
- 執行相關檢查(語法檢查、編譯檢查等,若適用)
|
| 19 |
+
|
| 20 |
+
2. **更新 `spec/task.md`**
|
| 21 |
+
- 為已完成的任務標記勾選 `[x]`
|
| 22 |
+
- 保留任務描述和驗收標準
|
| 23 |
+
|
| 24 |
+
### 暫停點:等待使用者手動測試
|
| 25 |
+
|
| 26 |
+
1. **提示使用者**:「程式碼已應用,請進行手動測試」
|
| 27 |
+
2. **等待使用者回饋**:
|
| 28 |
+
- 測試是否通過驗收標準
|
| 29 |
+
- 是否需要調整或修復
|
| 30 |
+
- 測試完成後執行 `/project.report`
|
| 31 |
+
|
| 32 |
+
### 後續步驟(由使用者執行)
|
| 33 |
+
|
| 34 |
+
使用者手動測試完成後:
|
| 35 |
+
- 執行 `/project.report` 記錄本次迭代的變更摘要
|
| 36 |
+
- `/project.report` 會自動更新 `changelog.md` 並清理 `spec/plan.md` 和 `spec/task.md`
|
| 37 |
+
|
| 38 |
+
## 守則
|
| 39 |
+
|
| 40 |
+
- **直接執行**:不需要展示階段或再次確認
|
| 41 |
+
- **精準定位**:所有變更需精確指向檔案、函式、行號
|
| 42 |
+
- **驗證變更**:應用後須檢查語法/編譯正確性
|
| 43 |
+
- **等待測試**:暫停並等待使用者手動測試結果
|
| 44 |
+
- **後續交付**:由 `/project.report` 負責記錄和清理
|
| 45 |
|
.github/prompts/project.plan.prompt.md
CHANGED
|
@@ -15,20 +15,36 @@
|
|
| 15 |
請輸出
|
| 16 |
- 產生 `spec/plan.md` 檔案,內容包含:
|
| 17 |
- **簡短前置**:需求重述與關鍵假設(若有)。
|
| 18 |
-
-
|
| 19 |
-
|
|
|
|
|
|
|
| 20 |
- **Invariants 對齊**:逐條列出是否受影響(Done/Not Impacted/At Risk),並指向 `spec/spec.md` 的相關條目。
|
| 21 |
- **風險與回滾**:主要風險、緩解、回滾方式(最小可逆)。
|
| 22 |
- **冒煙測試**:2–4 個步驟,含預期輸出要點。
|
| 23 |
-
|
| 24 |
-
|
| 25 |
-
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
-
|
| 33 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 34 |
- plan.md 的所有決策必須遵守 spec.md 的全局約束;不可違反或繞過 spec 中定義的不變條件。
|
|
|
|
| 15 |
請輸出
|
| 16 |
- 產生 `spec/plan.md` 檔案,內容包含:
|
| 17 |
- **簡短前置**:需求重述與關鍵假設(若有)。
|
| 18 |
+
- **迭代目標**:本次 sprint 要解決什麼問題或新增什麼功能。
|
| 19 |
+
- **範圍**:涉及的模組、檔案、外部依賴。
|
| 20 |
+
- **驗收標準**:本次迭代完成的定義(Definition of Done)。
|
| 21 |
+
- **高層任務列表**:要做的主要工作項(不需詳細拆解,詳細拆解由 `/project.task` 負責)。
|
| 22 |
- **Invariants 對齊**:逐條列出是否受影響(Done/Not Impacted/At Risk),並指向 `spec/spec.md` 的相關條目。
|
| 23 |
- **風險與回滾**:主要風險、緩解、回滾方式(最小可逆)。
|
| 24 |
- **冒煙測試**:2–4 個步驟,含預期輸出要點。
|
| 25 |
+
|
| 26 |
+
## ⏸️ 暫停點(重要)
|
| 27 |
+
|
| 28 |
+
**完成 `spec/plan.md` 生成後,立即停止,等待使用者確認。**
|
| 29 |
+
|
| 30 |
+
### 第一階段:討論與確認計畫(直接在 spec/plan.md 上編輯)
|
| 31 |
+
|
| 32 |
+
1. **直接生成/更新 `spec/plan.md`**
|
| 33 |
+
- 你可以直接在 MD 上進行編輯和調整
|
| 34 |
+
- 修改目標、範圍、任務優先序等
|
| 35 |
+
- 如果改錯了可以直接 discard
|
| 36 |
+
|
| 37 |
+
2. **完成編輯後**:
|
| 38 |
+
- 回覆「確認」或「核准」
|
| 39 |
+
|
| 40 |
+
### 第二階段:任務拆解(用戶確認後)
|
| 41 |
+
|
| 42 |
+
待你確認後:
|
| 43 |
+
1. **提示你執行 `/project.task`** 來進行詳細的任務拆解與驗收標準
|
| 44 |
+
|
| 45 |
+
## 守則
|
| 46 |
+
|
| 47 |
+
- **必須遵守暫停點**:產生 `spec/plan.md` 後,等待使用者確認,不進行任何進一步的操作。
|
| 48 |
+
- **允許多輪編輯**:用戶可在 `spec/plan.md` 上任意修改、調整,直到滿意為止。
|
| 49 |
+
- **可安全 discard**:用戶可隨時放棄編輯,discard 檔案變更,無副作用。
|
| 50 |
- plan.md 的所有決策必須遵守 spec.md 的全局約束;不可違反或繞過 spec 中定義的不變條件。
|
.github/prompts/project.report.prompt.md
CHANGED
|
@@ -1,18 +1,47 @@
|
|
| 1 |
-
# /project.report —
|
| 2 |
|
| 3 |
目的
|
| 4 |
-
-
|
| 5 |
-
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
|
| 9 |
-
-
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
-
|
| 17 |
-
|
| 18 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# /project.report — 交付與清理
|
| 2 |
|
| 3 |
目的
|
| 4 |
+
- 記錄本次迭代的變更摘要到 `changelog.md`
|
| 5 |
+
- 清理臨時計畫檔案(`spec/plan.md` 和 `spec/task.md`)
|
| 6 |
+
- 生成交付報告
|
| 7 |
+
|
| 8 |
+
輸入
|
| 9 |
+
- 使用者已完成手動測試(來自 `/project.apply` 後的測試階段)
|
| 10 |
+
|
| 11 |
+
自動執行
|
| 12 |
+
|
| 13 |
+
### 1. 更新 `changelog.md`
|
| 14 |
+
|
| 15 |
+
- 在 `[Unreleased]` 或最新版本下,根據 `spec/task.md` 生成變更摘要
|
| 16 |
+
- 格式:
|
| 17 |
+
```markdown
|
| 18 |
+
### Added/Changed/Fixed
|
| 19 |
+
- **功能名稱或模組**(日期)
|
| 20 |
+
- 具體變更描述(2-3 條要點)
|
| 21 |
+
- 相關檔案簡稱
|
| 22 |
+
```
|
| 23 |
+
|
| 24 |
+
### 2. 清理臨時檔案
|
| 25 |
+
|
| 26 |
+
- 刪除 `spec/plan.md`(已完成的迭代計畫)
|
| 27 |
+
- 刪除 `spec/task.md`(已完成的任務拆解)
|
| 28 |
+
- 下次迭代時會重新生成
|
| 29 |
+
|
| 30 |
+
### 3. 生成交付報告
|
| 31 |
+
|
| 32 |
+
輸出內容:
|
| 33 |
+
- **變更摘要**:對照 `spec/task.md` 的已完成任務
|
| 34 |
+
- **品質狀態**:
|
| 35 |
+
- Build/Lint 狀態
|
| 36 |
+
- 語法/編譯檢查結果
|
| 37 |
+
- I/O 契約驗證
|
| 38 |
+
- **Requirements 對齐**:對照 `spec/spec.md` 的不變條件
|
| 39 |
+
- **UX 變更檢查**:若有 UI/功能變更,提示需更新 `README.md` 的相關章節
|
| 40 |
+
- **建議的 changelog 條目**:提供文本供參考(已自動寫入)
|
| 41 |
+
|
| 42 |
+
## 守則
|
| 43 |
+
|
| 44 |
+
- **自動執行更新**:自動更新 `changelog.md` 並清理 plan 和 task 檔案
|
| 45 |
+
- **保留 spec.md**:不刪除 `spec/spec.md`(長期規格保留)
|
| 46 |
+
- **明確提示**:清楚告知已清理哪些檔案
|
| 47 |
+
- **交付完成**:提示本次迭代已交付,可開始新的迭代週期
|
.github/prompts/project.spec.prompt.md
CHANGED
|
@@ -52,17 +52,45 @@
|
|
| 52 |
- 主要風險與回滾建議
|
| 53 |
- 冒煙測試建議(2–3 個步驟驗證調整是否生效)
|
| 54 |
|
| 55 |
-
|
| 56 |
-
|
| 57 |
-
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 66 |
- 程式碼分析需精準定位(檔案、函式、行號),便於快速定位與修改。
|
| 67 |
- 工作清單應與現有的 `spec/spec.md` 章節結構對應,避免遺漏或重複。
|
| 68 |
- 若發現規格與程式碼有深層衝突,需明確標註為「需要討論」的項目。
|
|
|
|
| 52 |
- 主要風險與回滾建議
|
| 53 |
- 冒煙測試建議(2–3 個步驟驗證調整是否生效)
|
| 54 |
|
| 55 |
+
## ⏸️ 暫停點與雙向確認流程(重要)
|
| 56 |
+
|
| 57 |
+
**完成四部分分析後,立即停止,等待使用者評審與確認。**
|
| 58 |
+
|
| 59 |
+
### 第一階段:評審與確認規格變更(直接在 spec/spec.md 上編輯)
|
| 60 |
+
|
| 61 |
+
1. **直接更新 `spec/spec.md`**:
|
| 62 |
+
- 應用四部分內容的建議
|
| 63 |
+
- 新增/修改/移除規格項
|
| 64 |
+
- 用戶可直接在 MD 檔案上進行二次調整
|
| 65 |
+
|
| 66 |
+
2. **用戶進行討論與調整**(在 MD 檔案上):
|
| 67 |
+
- 直接編輯 `spec/spec.md`
|
| 68 |
+
- 調整、新增或移除規格項
|
| 69 |
+
- 修改相關描述或限制
|
| 70 |
+
- 如果改錯了可以直接 discard(無副作用)
|
| 71 |
+
|
| 72 |
+
3. **完成編輯後**:
|
| 73 |
+
- 用戶回覆「確認」或「核准」
|
| 74 |
+
|
| 75 |
+
4. **確認後繼續第二階段**
|
| 76 |
+
|
| 77 |
+
### 第二階段:相關文件同步(用戶確認後)
|
| 78 |
+
|
| 79 |
+
待用戶確認後,按順序執行:
|
| 80 |
+
1. **更新 `README.md`**:將規格調整中的**高層次設計理念、使用者情境、架構思想**同步至 README(確保即使 spec 後續重建,這些核心思想仍得到保留);細節實作內容暫不更新,待任務完成後補充
|
| 81 |
+
2. 根據「工作清單」建立 `spec/plan.md`(定義本次 sprint 範圍)
|
| 82 |
+
|
| 83 |
+
### 第三階段:後續開發(可選)
|
| 84 |
+
|
| 85 |
+
- 執行 `/project.plan` 進行任務拆解與驗收標準
|
| 86 |
+
- 開始迭代開發
|
| 87 |
+
|
| 88 |
+
## 守則
|
| 89 |
+
|
| 90 |
+
- **必須遵守暫停點**:更新 `spec/spec.md` 後,等待使用者確認,不主動修改 `README.md` 或建立 `spec/plan.md`。
|
| 91 |
+
- **允許多輪編輯**:用戶可在 `spec/spec.md` 上任意修改、調整,直到滿意為止。
|
| 92 |
+
- **可安全 discard**:用戶可隨時放棄編輯,discard 檔案變更,無副作用。
|
| 93 |
+
- 規格建議基於使用者輸入與現有 `spec/spec.md`;直接在 `spec/spec.md` 上實作,等待確認後再同步其他檔案。
|
| 94 |
- 程式碼分析需精準定位(檔案、函式、行號),便於快速定位與修改。
|
| 95 |
- 工作清單應與現有的 `spec/spec.md` 章節結構對應,避免遺漏或重複。
|
| 96 |
- 若發現規格與程式碼有深層衝突,需明確標註為「需要討論」的項目。
|
.github/prompts/project.task.prompt.md
CHANGED
|
@@ -1,34 +1,51 @@
|
|
| 1 |
-
# /project.task —
|
| 2 |
|
| 3 |
目的
|
| 4 |
-
-
|
| 5 |
-
-
|
|
|
|
|
|
|
|
|
|
| 6 |
|
| 7 |
請輸出
|
| 8 |
-
-
|
| 9 |
-
|
| 10 |
-
|
| 11 |
-
-
|
| 12 |
-
-
|
| 13 |
-
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
|
| 17 |
-
-
|
| 18 |
-
|
| 19 |
-
|
|
|
|
|
|
|
|
|
|
| 20 |
- 相關欄位/限制(若有)
|
| 21 |
-
|
| 22 |
-
|
| 23 |
-
-
|
| 24 |
-
|
| 25 |
-
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
-
|
| 33 |
-
-
|
| 34 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# /project.task — 任務拆解
|
| 2 |
|
| 3 |
目的
|
| 4 |
+
- 根據使用者確認的 `spec/plan.md`,進行詳細的任務拆解與驗收標準。
|
| 5 |
+
- 生成具體的任務步驟清單與程式碼變更點,為後續程式碼應用做準備。
|
| 6 |
+
|
| 7 |
+
輸入
|
| 8 |
+
- 使用者已確認的 `spec/plan.md`
|
| 9 |
|
| 10 |
請輸出
|
| 11 |
+
- 根據 `spec/plan.md` 的高層任務列表,生成詳細任務拆解:
|
| 12 |
+
- **編號 Task 清單**(T-001、T-002 等)
|
| 13 |
+
```
|
| 14 |
+
### T-001: <任務名稱>
|
| 15 |
+
- **描述**:詳細說明這個任務要做什麼
|
| 16 |
+
- **受影響檔案**:列出所有會被修改的檔案(相對路徑)
|
| 17 |
+
- **具體變更點**:
|
| 18 |
+
- 文件1.py (L100-150): 新增函式 xxx()
|
| 19 |
+
- 文件2.md: 更新章節 YYY
|
| 20 |
+
- **驗收標準**:如何檢驗這個任務完成
|
| 21 |
+
- **風險等級**:低/中/高
|
| 22 |
+
```
|
| 23 |
+
|
| 24 |
+
- **關鍵變更點摘要**(不貼整段程式碼):
|
| 25 |
+
- 每個變更位置、修改前後行為
|
| 26 |
- 相關欄位/限制(若有)
|
| 27 |
+
|
| 28 |
+
- **品質門檻**:
|
| 29 |
+
- 是否影響公共契約
|
| 30 |
+
- 錯誤處理與日誌覆蓋情況
|
| 31 |
+
|
| 32 |
+
## ⏸️ 暫停點
|
| 33 |
+
|
| 34 |
+
**完成任務拆解後,等待使用者確認。**
|
| 35 |
+
|
| 36 |
+
- 用戶可在本階段:
|
| 37 |
+
- 確認任務拆解是否合理
|
| 38 |
+
- 調整任務優先序或內容
|
| 39 |
+
- 修改 `spec/task.md` 後回覆「確認」
|
| 40 |
+
|
| 41 |
+
### 確認後的下一步
|
| 42 |
+
|
| 43 |
+
待用戶確認後:
|
| 44 |
+
1. **提示執行 `/project.apply`** 來應用程式碼變更
|
| 45 |
+
|
| 46 |
+
## 守則
|
| 47 |
+
|
| 48 |
+
- 不直接修改程式碼檔案,只展示變更方案。
|
| 49 |
+
- 編號(T-001 等)僅用於清單,不會寫入 spec 檔案。
|
| 50 |
+
- 若涉及公共契約變更,必須標註需先確認 `spec/spec.md`。
|
| 51 |
+
- 提供精確的檔案位置與行號,便於後續應用。
|
spec/plan.md
CHANGED
|
@@ -1,54 +1,94 @@
|
|
| 1 |
-
# 迭代計畫 (plan.md) —
|
| 2 |
|
| 3 |
-
>
|
| 4 |
-
> 完成後可拋棄;下次迭代時重新建立。
|
| 5 |
|
| 6 |
## 迭代資訊
|
| 7 |
|
| 8 |
| 項目 | 值 |
|
| 9 |
|-----|-----|
|
| 10 |
-
| Sprint 編號 |
|
| 11 |
-
| 開始日期 |
|
| 12 |
-
| 預計結束日期 |
|
| 13 |
-
| 負責人 |
|
| 14 |
|
| 15 |
## 迭代目標 (Goal)
|
| 16 |
|
| 17 |
-
|
| 18 |
|
| 19 |
-
|
| 20 |
-
-
|
| 21 |
-
-
|
| 22 |
-
- 改進 UI 地圖高度管理
|
| 23 |
|
| 24 |
## 範圍 (Scope)
|
| 25 |
|
| 26 |
-
(本次迭代涉及哪些模組、檔案、外部依賴)
|
| 27 |
-
|
| 28 |
| 模組 | 涉及檔案 | 變更類型 |
|
| 29 |
|-----|--------|---------|
|
| 30 |
-
|
|
|
|
|
| 31 |
|
| 32 |
## 驗收標準 (Acceptance Criteria)
|
| 33 |
|
| 34 |
-
|
| 35 |
-
|
| 36 |
-
- [
|
| 37 |
-
- [
|
| 38 |
-
- [
|
| 39 |
-
- [ ] 無新增 WARNING/ERROR 日誌(除非預期)
|
| 40 |
|
| 41 |
## 任務拆解 (Tasks)
|
| 42 |
|
| 43 |
-
|
| 44 |
-
|
| 45 |
-
|
| 46 |
-
-
|
| 47 |
-
-
|
| 48 |
-
-
|
| 49 |
-
-
|
| 50 |
-
|
| 51 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 52 |
- [ ] 測試通過
|
| 53 |
|
| 54 |
### 任務 2: [功能名稱]
|
|
|
|
| 1 |
+
# 迭代計畫 (plan.md) — 波形地圖自動載入改進
|
| 2 |
|
| 3 |
+
> 本次迭代優化 UI 流程,使波形地圖在應用啟動與事件切換時自動載入,提升使用體驗。
|
|
|
|
| 4 |
|
| 5 |
## 迭代資訊
|
| 6 |
|
| 7 |
| 項目 | 值 |
|
| 8 |
|-----|-----|
|
| 9 |
+
| Sprint 編號 | 001 |
|
| 10 |
+
| 開始日期 | 2025-10-26 |
|
| 11 |
+
| 預計結束日期 | 2025-10-26 |
|
| 12 |
+
| 負責人 | 使用者 |
|
| 13 |
|
| 14 |
## 迭代目標 (Goal)
|
| 15 |
|
| 16 |
+
**提升波形地圖的可用性與互動流程**
|
| 17 |
|
| 18 |
+
- 應用啟動時,自動載入預設地震事件的波形地圖(選定測站分布 + 波形圖)
|
| 19 |
+
- 使用者切換地震事件時,同步自動更新波形地圖,無需手動點擊「載入波形」按鈕
|
| 20 |
+
- 優化使用者體驗,減少操作步驟
|
|
|
|
| 21 |
|
| 22 |
## 範圍 (Scope)
|
| 23 |
|
|
|
|
|
|
|
| 24 |
| 模組 | 涉及檔案 | 變更類型 |
|
| 25 |
|-----|--------|---------|
|
| 26 |
+
| UI 工作流 | `app.py`(Gradio Blocks 事件綁定) | feature / refactor |
|
| 27 |
+
| 無規格變更 | - | N/A |
|
| 28 |
|
| 29 |
## 驗收標準 (Acceptance Criteria)
|
| 30 |
|
| 31 |
+
- [x] 應用啟動時,預設地震事件的波形地圖自動顯示
|
| 32 |
+
- [x] 選擇不同地震事件時,波形地圖同步自動更新
|
| 33 |
+
- [x] 「載入波形」按鈕保留可用,允許使用者手動重新載入
|
| 34 |
+
- [x] 實際觀測震度圖亦在事件切換時同步更新
|
| 35 |
+
- [x] 無新增 WARNING/ERROR 日誌
|
|
|
|
| 36 |
|
| 37 |
## 任務拆解 (Tasks)
|
| 38 |
|
| 39 |
+
### 任務 1: 在 Gradio 初始化時自動載入預設地震事件的波形
|
| 40 |
+
- **描述**:於 Gradio Blocks 定義後,新增 `on_load` 事件,使應用啟動時自動調用 `load_and_display_waveform()`
|
| 41 |
+
- **涉及檔案**:`app.py`(Gradio 事件綁定部分,L1310-1340)
|
| 42 |
+
- **變更**:
|
| 43 |
+
- 在 demo.load 事件中綁定預設參數(事件、時間範圍、震央位置)
|
| 44 |
+
- 自動填充波形地圖、波形圖、狀態訊息
|
| 45 |
+
- **驗收**:應用載入後,輸入測站地圖與波形圖立即顯示
|
| 46 |
+
|
| 47 |
+
### 任務 2: 地震事件切換時自動更新波形地圖
|
| 48 |
+
- **描述**:修改 `event_dropdown.change` 事件綁定,使其同時更新 **波形地圖** 與 **實際觀測圖**
|
| 49 |
+
- **涉及檔案**:`app.py`(L1331-1335)
|
| 50 |
+
- **變更**:
|
| 51 |
+
- 將 `event_dropdown.change` 的 callback 從單純的 `on_event_select` 改為同時調用波形載入邏輯
|
| 52 |
+
- 新增 callback 函數 `on_event_change()` 負責協調所有更新
|
| 53 |
+
- **驗收**:切換事件時,波形地圖、波形圖、實際觀測圖同步更新
|
| 54 |
+
|
| 55 |
+
## Invariants 對齐
|
| 56 |
+
|
| 57 |
+
| 項目 | 狀態 | 說明 |
|
| 58 |
+
|-----|------|------|
|
| 59 |
+
| 波形輸入 | Not Impacted | 時間窗長度、補零策略維持不變 |
|
| 60 |
+
| 測站限制 | Not Impacted | 最多 25 站選擇邏輯維持不變 |
|
| 61 |
+
| 推論流程 | Not Impacted | 模型推論邏輯完全不涉及 |
|
| 62 |
+
| 預設地圖高度 | Not Impacted | 仍固定 800px |
|
| 63 |
+
| 錯誤處理 | Not Impacted | 降級策略維持不變 |
|
| 64 |
+
|
| 65 |
+
## 風險與回滾
|
| 66 |
+
|
| 67 |
+
### 主要風險
|
| 68 |
+
1. **初始化順序問題**:Gradio 的 `on_load` 若在組件定義前執行,可能導致參考錯誤
|
| 69 |
+
- 緩解:確保 callback 中的所有輸出組件已定義
|
| 70 |
+
- 回滾:移除 `on_load` 事件綁定
|
| 71 |
+
|
| 72 |
+
2. **事件切換時的重複載入**:如果 callback 未正確取消前次請求,可能導致多次 load
|
| 73 |
+
- 緩解:在 callback 內正確接收新的事件參數
|
| 74 |
+
- 回滾:恢復原始的 `on_event_select` 邏輯
|
| 75 |
+
|
| 76 |
+
## 冒煙測試
|
| 77 |
+
|
| 78 |
+
1. **應用啟動測試**
|
| 79 |
+
- 啟動應用後,確認輸入測站地圖、波形圖已自動顯示
|
| 80 |
+
- 確認狀態訊息顯示「✅ 已載入波形資料」
|
| 81 |
+
- 預計結果:地圖與波形圖可見,無錯誤日誌
|
| 82 |
+
|
| 83 |
+
2. **事件切換測試**
|
| 84 |
+
- 從下拉菜單選擇另一個地震事件
|
| 85 |
+
- 確認波形地圖、波形圖、實際觀測圖自動更新
|
| 86 |
+
- 預計結果:所有視圖同步刷新,無額外操作
|
| 87 |
+
|
| 88 |
+
3. **手動重新載入測試**
|
| 89 |
+
- 修改時間滑桿,點擊「載入波形」按鈕
|
| 90 |
+
- 確認波形地圖按新參數重新生成
|
| 91 |
+
- 預計結果:地圖與波形圖更新為新時間範圍
|
| 92 |
- [ ] 測試通過
|
| 93 |
|
| 94 |
### 任務 2: [功能名稱]
|