plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity

feat/overview-artifact/main #32

Merged
admin merged 8 commits from feat/overview-artifact/main into master 2026-09-17 06:24:24 +00:00
Conversation 1 Commits 8 Files Changed 9
+426 -13
jiantw83 commented 2026-09-17 06:23:22 +00:00
Member
Copy Link
Copy Source

摘要

規劃與分析各產出一份可直接投影的 HTML 總覽網頁，網址寫回議題並就地更新。

需求議題

#1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組

工作包議題

#10 — 產生圖解版總覽網頁並寫回議題

變更內容

  • templates/overview-artifact.html — 總覽網頁模板。
  • scripts/issue-update.js — 新增 --overview-url，把網址寫回議題總覽段落。
  • prompts/sdlc-plan.md、prompts/sdlc-analyze.md — 產生與寫回的步驟。
  • AGENTS.md — 寫明這份模板是「模板不含邏輯」的唯一例外。
  • 測試 226 個案例（本 PR 新增 26 個）。

設計重點

  • 樣式與內容分離。 樣式集中在單一 <style>，內文只有佔位；深色模式跟隨系統，手機寬度另有斷點。改版面不必動內容，換內容不必碰樣式。
  • 全景段落是整段佔位、獨佔一行。 規劃階段填空字串時整段乾淨消失；若把它包在寫死的 <section> 裡，規劃版就會留下一個空標題。
  • 寫回沿用 #8 的 upsertLineInSection。 連結以固定前綴獨佔總覽段落裡的一行，重跑就地更新，議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。
  • 私有提醒跟著連結走。 讀到的人多半會想轉寄給組織外的人，這句話寫在議題上比寫在文件裡有用。

解決的問題

非技術的利害關係人原本得讀完技術細節才知道一件事在做什麼。有一份可投影的網頁之後，會議上點開就能談。

影響的功能

新增。issue-update 多一個旗標，既有行為不變。

測試結果

ℹ tests 226
ℹ pass 226
ℹ fail 0

八顆 commit 逐一在獨立的 git worktree 裡跑測試，每一顆都是綠的（200／200／200／207／224／224／224／226）。

⚠ 目前 npm test 在共用工作目錄裡是紅的，因為另一個 session 正在同一個 clone 裡做 #9（wp-extract），那部分尚未完成。本 PR 的測試以 node --test $(ls test/*.test.js | grep -v wp-extract) 執行，且發佈內容只含本 PR 自己的檔案。

手動驗證：把模板填成一份完整 HTML，確認無殘留佔位；再把 {{工作包全景}} 填空字串，確認整段消失而其餘段落完好。issue-update --overview-url --dry-run 對真實議題 #1 試跑，確認寫回的那一行格式正確且未寫入。

Code review 修掉的四處

  1. 模板裡的 <script> 違反了「模板不含邏輯」。 這份是要在瀏覽器裡開的網頁，畫 mermaid 需要那段腳本。與其默默違規，把例外與理由寫進 AGENTS.md 的慣例表，並加一條測試守住例外的範圍（只能有那一段腳本，且不得夾帶網路或儲存操作）。
  2. 網址夾帶上一次寫回的整行（很常見的複製貼上手誤）會讓私有提醒在議題上出現兩次，已擋下。
  3. 修這一條時我自己造了一個 TDZ 錯誤：PRIVACY_NOTE 宣告在 main() 之後，而新的檢查在 main() 的同步段就要用到它，每次執行都以 Cannot access 'PRIVACY_NOTE' before initialization 收場。常數已移到 main() 之前。
  4. 三條驗不出東西的斷言：mermaid 那條只比對「有出現 mermaid 字樣」，而 CDN 網址裡就有這個字，整段渲染腳本刪掉照樣通過；sdlc-plan 的七條拿整份正本比對，任何一處撞到就算過。都已改成驗得出來的。

一個要你裁決的讀法

驗收標準第 1 條寫「sdlc-plan 與 sdlc-analyze 各產出一份 HTML 總覽」，第 3 條寫「重跑時原地更新同一連結，不新增第二個」。

我的實作是：兩個指令各自產生自己的網頁，但都寫回同一顆需求議題的同一行，所以跑完分析之後，議題上只看得到分析版的連結（分析版是規劃版的超集，多了工作包全景）。第 3 條的「不新增第二個」支持這個做法。

若你要的是「議題上同時掛兩個連結、規劃版與分析版各一」，那要改成兩個不同的前綴，我可以改。

🤖 Generated with Claude Code

## 摘要 規劃與分析各產出一份可直接投影的 HTML 總覽網頁，網址寫回議題並就地更新。 ## 需求議題 #1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組 ## 工作包議題 #10 — 產生圖解版總覽網頁並寫回議題 ## 變更內容 - `templates/overview-artifact.html` — 總覽網頁模板。 - `scripts/issue-update.js` — 新增 `--overview-url`，把網址寫回議題總覽段落。 - `prompts/sdlc-plan.md`、`prompts/sdlc-analyze.md` — 產生與寫回的步驟。 - `AGENTS.md` — 寫明這份模板是「模板不含邏輯」的唯一例外。 - 測試 226 個案例（本 PR 新增 26 個）。 ## 設計重點 - **樣式與內容分離。** 樣式集中在單一 `<style>`，內文只有佔位；深色模式跟隨系統，手機寬度另有斷點。改版面不必動內容，換內容不必碰樣式。 - **全景段落是整段佔位、獨佔一行。** 規劃階段填空字串時整段乾淨消失；若把它包在寫死的 `<section>` 裡，規劃版就會留下一個空標題。 - **寫回沿用 #8 的 `upsertLineInSection`。** 連結以固定前綴獨佔總覽段落裡的一行，重跑就地更新，議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。 - **私有提醒跟著連結走。** 讀到的人多半會想轉寄給組織外的人，這句話寫在議題上比寫在文件裡有用。 ## 解決的問題 非技術的利害關係人原本得讀完技術細節才知道一件事在做什麼。有一份可投影的網頁之後，會議上點開就能談。 ## 影響的功能 新增。`issue-update` 多一個旗標，既有行為不變。 ## 測試結果 ``` ℹ tests 226 ℹ pass 226 ℹ fail 0 ``` 八顆 commit 逐一在**獨立的 git worktree** 裡跑測試，每一顆都是綠的（200／200／200／207／224／224／224／226）。 > ⚠ 目前 `npm test` 在共用工作目錄裡是紅的，因為另一個 session 正在同一個 clone 裡做 #9（`wp-extract`），那部分尚未完成。本 PR 的測試以 `node --test $(ls test/*.test.js | grep -v wp-extract)` 執行，且發佈內容只含本 PR 自己的檔案。 手動驗證：把模板填成一份完整 HTML，確認無殘留佔位；再把 `{{工作包全景}}` 填空字串，確認整段消失而其餘段落完好。`issue-update --overview-url --dry-run` 對真實議題 #1 試跑，確認寫回的那一行格式正確且未寫入。 ## Code review 修掉的四處 1. **模板裡的 `<script>` 違反了「模板不含邏輯」。** 這份是要在瀏覽器裡開的網頁，畫 mermaid 需要那段腳本。與其默默違規，把例外與理由寫進 `AGENTS.md` 的慣例表，並加一條測試守住例外的範圍（只能有那一段腳本，且不得夾帶網路或儲存操作）。 2. **網址夾帶上一次寫回的整行**（很常見的複製貼上手誤）會讓私有提醒在議題上出現兩次，已擋下。 3. **修這一條時我自己造了一個 TDZ 錯誤**：`PRIVACY_NOTE` 宣告在 `main()` 之後，而新的檢查在 `main()` 的同步段就要用到它，每次執行都以 `Cannot access 'PRIVACY_NOTE' before initialization` 收場。常數已移到 `main()` 之前。 4. **三條驗不出東西的斷言**：mermaid 那條只比對「有出現 mermaid 字樣」，而 CDN 網址裡就有這個字，整段渲染腳本刪掉照樣通過；`sdlc-plan` 的七條拿整份正本比對，任何一處撞到就算過。都已改成驗得出來的。 ## 一個要你裁決的讀法 驗收標準第 1 條寫「sdlc-plan 與 sdlc-analyze **各產出一份** HTML 總覽」，第 3 條寫「重跑時原地更新同一連結，**不新增第二個**」。 我的實作是：兩個指令各自產生自己的網頁，但都寫回同一顆需求議題的同一行，所以跑完分析之後，議題上只看得到分析版的連結（分析版是規劃版的超集，多了工作包全景）。第 3 條的「不新增第二個」支持這個做法。 若你要的是「議題上同時掛兩個連結、規劃版與分析版各一」，那要改成兩個不同的前綴，我可以改。 --- 🤖 Generated with [Claude Code](https://claude.com/claude-code)
jiantw83 added 8 commits 2026-09-17 06:23:22 +00:00
feat(總覽模板): 新增圖解版總覽的 HTML 模板 ed2d08de9f 
給非技術的利害關係人在會議上直接投影用：一句話總覽、目標、流程圖，分析階段再多
一張工作包全景。

樣式全部集中在單一 style 區塊，內文只放佔位——改版面不必動內容，換內容不必碰樣式。
深色模式跟隨系統，手機寬度另有斷點，投影與傳連結兩種場合都看得清楚。

工作包全景是整段佔位、獨佔一行，規劃階段填空字串時整段會乾淨消失；若把它包在寫死
的 section 裡，規劃版就會留下一個空標題。

mermaid 由 CDN 載入並實際渲染，而不是把原始碼丟給讀者看；代價是離線開啟時圖不會出來。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
feat(issue-update): 支援 --overview-url，把總覽網址寫回議題 0e05dd2066 
沿用既有的 upsertLineInSection：連結以固定前綴獨佔總覽段落裡的一行，重跑時就地
更新，不會長出第二個連結；議題原本的 markdown 白話總覽一字不動——網頁是補充，
不是取代。

連結旁自動附上「此連結預設為私有，組織外無法開啟」。讀到的人多半會想轉寄給組織外
的人，這句話寫在議題上比寫在文件裡有用。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
feat(流程正本): 兩份正本加入產生總覽與寫回網址的步驟 6b30552ee2 
規劃版填總覽、目標、流程圖，工作包全景填空字串；分析版沿用同一份模板，額外把
工作包的相依與截止日畫成 graph TD 的全景圖。節點一樣以 12 個為上限，超過就只畫
相依鏈最長路徑上的那幾顆。

兩份都寫回同一顆需求議題的同一行，所以分析版會取代規劃版——同一顆需求議題只掛
一個總覽網址，這是預期行為，正本裡寫明免得被當成 bug。

另外交代填模板時流程圖不帶圍欄：圍欄是議題 markdown 用的，填進 HTML 會多出一段
沒有意義的字。

Closes #10

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
test(issue-update): 覆蓋總覽網址的寫回與就地更新 47529d33c2 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
test(總覽網頁): 釘住模板結構與兩份正本的規則 0aa0439061 
模板的檢查重點是「樣式與內容分離」與「全景段落能整段消失」，兩者壞掉時規劃版會
留下空標題或行內樣式散落各處，肉眼不容易發現。

順帶把 work-package 測試的 phase2 切法收斂到第三段之前——原本切到檔尾，第三段
新增的編號清單會混進段落順序的斷言裡。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs(慣例): 寫明總覽模板是「模板不含邏輯」的唯一例外 57c059b5f9 
overview-artifact.html 是一份要在瀏覽器裡開的網頁，需要一段把 mermaid 畫出來的
腳本。與其默默違反自己寫的規則，不如把例外與理由寫進慣例表——下一個人才知道
這是想過的決定，而不是漏網的。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
fix(issue-update): 網址夾帶私有提醒時擋下，並修正 TDZ 錯誤 197de62570 
把上一次寫回的整行一起複製貼上是很常見的手誤，放行的話那句提醒會在議題上出現
兩次。

順帶修掉一個自己造出來的錯：PRIVACY_NOTE 原本宣告在 main() 之後，而新的檢查在
main() 的同步段就要用到它，於是每次執行都以「Cannot access 'PRIVACY_NOTE' before
initialization」收場。常數移到 main() 之前。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
test(總覽網頁): 把三條驗不出東西的斷言改成驗得出來的 a460d7e661 
- mermaid 那條原本只比對「有出現 mermaid 字樣」，而 CDN 網址裡就有這個字，
  整段渲染腳本刪掉也照樣通過。改成驗 mermaid.initialize 真的被呼叫。
- 新增一條守住例外的範圍：模板裡只能有那一段腳本，且不得夾帶網路或儲存操作。
- sdlc-plan 的七條斷言原本拿整份正本比對，任何一處撞到就算過。改成只看第 6 步，
  與 sdlc-analyze 那邊的做法一致。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
admin approved these changes 2026-09-17 06:24:21 +00:00
admin merged commit a58d766009 into master 2026-09-17 06:24:24 +00:00
admin deleted branch feat/overview-artifact/main 2026-09-17 06:24:24 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
admin
Labels
Clear labels
ready-for-agent
規格已就緒可交由agent實作
 進行中
工作包正在實作
No labels
Milestone
No items
No Milestone
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/tea-sdlc#32