feat/sdlc-plan-requirement-issue/main #21

2026-09-17T04:45:32Z

jiantw83 commented

2026-09-17 04:45:32 +00:00

摘要

讓使用者丟進一段口語需求，最後在 Gitea 看到一顆結構完整的需求議題。本 PR 交付流程正本、輸出模板與寫入用的 issue-create 腳本。

需求議題

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

工作包議題

#4 — 以 sdlc-plan 把口語需求轉成結構化需求議題

變更內容

prompts/sdlc-plan.md — 流程正本。三種輸入來源、一次問一題、九個段落的填法、流程圖上限、標籤來源、寫入前先試跑。
templates/requirement-issue.md — 需求議題的九個段落與順序。
scripts/issue-create.js — 建立議題：標籤限既有、以標題查重、--dry-run。
scripts/lib.js — 新增 listLabels，與 labels-list 共用。
測試共 81 個案例（本 PR 新增 31 個）。

設計重點

--dry-run 不寫入，但會讀。 這是本 PR 修掉的一個實質缺陷：原本的試跑零請求，於是預覽的 body 永遠不含 labels，標籤錯字也要等實跑才爆。現在試跑會先解析標籤、先查重，因此預覽忠實反映將送出的請求；同名議題已存在時 requests 為空陣列並附上既有議題編號，如實顯示「實跑會是 no-op」。試跑不跑前置檢查——那一層擋的是寫入能力與時間追蹤，而試跑本來就不寫。
標籤錯字當場中止並列出可選項目，不悄悄少貼一個。這是「不自動建立標籤」在程式層面的落實。
模板不寫死 mermaid 圍欄。 正本允許「乾脆不畫」，圍欄若寫死在模板裡，不畫時會在議題頁留下一塊渲染失敗的空 mermaid 區塊。圍欄改由填入的內容自己帶，正本裡把兩種情形都交代清楚。
正本與模板用測試釘住。 段落順序決定下游 issue-extract 解析得到什麼，正本的平台中立性決定轉接檔能不能一份寫到底——這兩件事靠人記不牢。

解決的問題

需求寫成散文、下游每次都要人重讀一遍再口述給 agent。有了固定模板與正本，議題本身就是可機讀的輸入。

影響的功能

新增。labels-list 改用 lib.listLabels，行為不變，既有測試全數通過。

測試結果

npm test：

ℹ tests 81
ℹ suites 0
ℹ pass 81
ℹ fail 0
ℹ duration_ms 1155

六顆 commit 逐一 checkout 後跑測試，每一顆都是綠的（50／50／50／50／64／81）。

對真實 Gitea 的手動驗證（三種試跑情境，皆未寫入）：

$ node scripts/issue-create.js --repo plugins/tea-sdlc --title "試跑用的假標題"     --body-file .tmp/b.md --labels ready-for-agent --dry-run
{"ok":true,"data":{"dryRun":true,...,"requests":[{"method":"POST","path":"/repos/plugins/tea-sdlc/issues",
 "body":{"title":"試跑用的假標題","body":"...","labels":[55]}}]}}

$ node scripts/issue-create.js ... --labels needs-triage --dry-run
{"ok":false,"error":{"code":"UNKNOWN_LABEL","message":"plugins/tea-sdlc 沒有這些標籤：needs-triage。
 本工具不建立標籤，請改挑既有的：ready-for-agent"}}

$ node scripts/issue-create.js ... --title "建立需求議題的抽取契約" --dry-run
{"ok":true,"data":{"dryRun":true,...,"existing":{"number":5,...},"requests":[]}}

實跑路徑未在真實 repo 上執行——該 repo 的時間追蹤仍關著，第四層前置檢查會擋下；建立議題的行為由 stub server 測試覆蓋。

待確認

沿用上一個 PR 未回覆的兩點：讀取型腳本是否該跑滿四層前置檢查，以及直接打 REST API 而非 tea 子指令。本 PR 依既有實作繼續。

🤖 Generated with Claude Code

## 摘要讓使用者丟進一段口語需求，最後在 Gitea 看到一顆結構完整的需求議題。本 PR 交付流程正本、輸出模板與寫入用的 `issue-create` 腳本。 ## 需求議題 #1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組 ## 工作包議題 #4 — 以 sdlc-plan 把口語需求轉成結構化需求議題 ## 變更內容 - `prompts/sdlc-plan.md` — 流程正本。三種輸入來源、一次問一題、九個段落的填法、流程圖上限、標籤來源、寫入前先試跑。 - `templates/requirement-issue.md` — 需求議題的九個段落與順序。 - `scripts/issue-create.js` — 建立議題：標籤限既有、以標題查重、`--dry-run`。 - `scripts/lib.js` — 新增 `listLabels`，與 `labels-list` 共用。 - 測試共 81 個案例（本 PR 新增 31 個）。 ## 設計重點 - **`--dry-run` 不寫入，但會讀。** 這是本 PR 修掉的一個實質缺陷：原本的試跑零請求，於是預覽的 body 永遠不含 `labels`，標籤錯字也要等實跑才爆。現在試跑會先解析標籤、先查重，因此預覽忠實反映將送出的請求；同名議題已存在時 `requests` 為空陣列並附上既有議題編號，如實顯示「實跑會是 no-op」。試跑不跑前置檢查——那一層擋的是寫入能力與時間追蹤，而試跑本來就不寫。 - **標籤錯字當場中止並列出可選項目**，不悄悄少貼一個。這是「不自動建立標籤」在程式層面的落實。 - **模板不寫死 mermaid 圍欄。** 正本允許「乾脆不畫」，圍欄若寫死在模板裡，不畫時會在議題頁留下一塊渲染失敗的空 mermaid 區塊。圍欄改由填入的內容自己帶，正本裡把兩種情形都交代清楚。 - **正本與模板用測試釘住。** 段落順序決定下游 `issue-extract` 解析得到什麼，正本的平台中立性決定轉接檔能不能一份寫到底——這兩件事靠人記不牢。 ## 解決的問題需求寫成散文、下游每次都要人重讀一遍再口述給 agent。有了固定模板與正本，議題本身就是可機讀的輸入。 ## 影響的功能新增。`labels-list` 改用 `lib.listLabels`，行為不變，既有測試全數通過。 ## 測試結果 `npm test`： ``` ℹ tests 81 ℹ suites 0 ℹ pass 81 ℹ fail 0 ℹ duration_ms 1155 ``` 六顆 commit 逐一 checkout 後跑測試，每一顆都是綠的（50／50／50／50／64／81）。對真實 Gitea 的手動驗證（三種試跑情境，皆未寫入）： ``` $ node scripts/issue-create.js --repo plugins/tea-sdlc --title "試跑用的假標題" --body-file .tmp/b.md --labels ready-for-agent --dry-run {"ok":true,"data":{"dryRun":true,...,"requests":[{"method":"POST","path":"/repos/plugins/tea-sdlc/issues", "body":{"title":"試跑用的假標題","body":"...","labels":[55]}}]}} $ node scripts/issue-create.js ... --labels needs-triage --dry-run {"ok":false,"error":{"code":"UNKNOWN_LABEL","message":"plugins/tea-sdlc 沒有這些標籤：needs-triage。本工具不建立標籤，請改挑既有的：ready-for-agent"}} $ node scripts/issue-create.js ... --title "建立需求議題的抽取契約" --dry-run {"ok":true,"data":{"dryRun":true,...,"existing":{"number":5,...},"requests":[]}} ``` 實跑路徑未在真實 repo 上執行——該 repo 的時間追蹤仍關著，第四層前置檢查會擋下；建立議題的行為由 stub server 測試覆蓋。 ## 待確認沿用上一個 PR 未回覆的兩點：讀取型腳本是否該跑滿四層前置檢查，以及直接打 REST API 而非 `tea` 子指令。本 PR 依既有實作繼續。 --- 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jiantw83 added 6 commits 2026-09-17 04:45:32 +00:00

refactor(標籤): 把列標籤抽到 lib，讓要貼標籤的腳本共用 4f542d9c86

labels-list 與後續要挑標籤的腳本都要打同一個端點，抽成 lib.listLabels 之後
端點只寫在一個地方。順帶把「本專案不建立標籤，這是取得標籤的唯一途徑」寫進
函式註解，讓下一個要加功能的人先看到這條界線。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

refactor(測試): 共用假 Gitea 的啟動與環境變數 b0bd061852

每支測試各自寫一次「啟動 stub、登記 close、組環境變數」已經重複三次，抽到
helpers 之後新增測試檔只要一行。各檔仍保留自己的預設路由，因為那是該檔的
情境設定，不該共用。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

feat(sdlc-plan): 新增需求議題模板與流程正本 453cf47188

templates/requirement-issue.md 固定需求議題的九個段落與順序：總覽／背景／
目標／非目標／領域名詞表／流程圖／驗收標準／影響範圍／未決事項。段落順序即
下游 issue-extract 的解析依據，總覽段落預留總覽網頁的連結佔位。

流程圖段落只放佔位、不寫死 mermaid 圍欄：正本允許「乾脆不畫」，若圍欄寫死在
模板裡，不畫時就會在議題頁留下一塊渲染失敗的空 mermaid 區塊。圍欄改由填入的
內容自己帶。

prompts/sdlc-plan.md 是流程正本，平台中立 markdown，不含任何平台專屬語法，
description 以「僅由 /sdlc-plan 指令叫用。」起頭。正本交代：三種輸入來源、
一次問一題且不得替使用者編造、九個段落的填法、Mermaid flowchart 的 12 節點與
8 字上限、標籤只能從 labels-list 挑、寫入前先 --dry-run。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

feat(issue-create): 建立議題，標籤限既有、以標題查重 3f4e1a683b

標籤以名稱指定，送出前換成 repo 上既有標籤的 id；指到不存在的標籤即中止並列出
可選項目。本工具不具備建立標籤的能力，錯字當場講清楚，不悄悄少貼一個。

以標題查重，同名議題已存在就回傳既有那一顆並把 created 設為 false，讓中斷後
重跑不產生重複議題。先驗標籤再查重：參數打錯要立刻講。

--dry-run 不寫入，但會讀。要讓預覽忠實反映將送出的請求，就得先把標籤名稱換成
id、也得先查過重——否則預覽看起來會建一顆議題，實跑卻是 no-op，或反過來實跑
才爆標籤錯字。同名議題已存在時，預覽的 requests 為空陣列並附上既有議題編號。

body 由 --body-file 讀入後原樣送出，避免長 markdown 擠在命令列上。

Closes #4

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

test(sdlc-plan): 釘住正本與模板的結構 9e57a5db99

正本與模板是檔案而非程式，卻是本工作包實際交付的東西：模板段落順序決定下游
解析得到什麼，正本的平台中立性決定轉接檔能不能一份寫到底。以測試釘住段落
順序、佔位格式、description 前綴、平台專屬字樣的缺席、流程圖的上限，以及
模板不得寫死 mermaid 圍欄。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

test(issue-create): 覆蓋建立議題與試跑預覽的契約 9b9ab33a53

沿用既有接縫：子行程執行、stub server 錄下每一筆請求。涵蓋標籤名稱解析、
未知標籤中止、不碰 labels 的寫入端點、同標題不重建、前後空白視為同一顆，
以及寫入型腳本一樣跑滿前置檢查。

試跑的部分特別驗「預覽要忠實」：預覽的 body 必須看得出標籤會被貼上、標籤
錯字在試跑就該擋下、同名議題已存在時預覽不得預告要建立議題，且全程不發出
任何寫入請求。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

admin approved these changes 2026-09-17 04:50:59 +00:00

admin merged commit 9c3ba425e0 into master

2026-09-17 04:51:03 +00:00

admin deleted branch feat/sdlc-plan-requirement-issue/main

2026-09-17 04:51:03 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/tea-sdlc#21