plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity
154 Commits 1 Branch 0 Tags
ad980fafc624cd1f921c00044824fae95cd44ac4
Commit Graph
18 Commits
Author SHA1 Message Date
JefferyandClaude Opus 5 73b9cd9f75 feat(install): 安裝完成等於驗過能用 
install 寫完轉接檔後，把叫用鏈真的走一遍：轉接檔 → PATH 上的 tea-sdlc → 流程正本。

最脆弱的是中間那一環。套件裝在某個 Node 版本底下，換個版本就找不到了，而轉接檔本身
看起來完全正常——沒有這道驗證，使用者要到第一次打 /sdlc-plan 才發現，那時他已經離開
安裝的心智狀態很久了。所以不是查檔案在不在，而是真的到 PATH 上把 tea-sdlc 找出來執行
一次，再把取回的正本跟套件裡的那一份逐字比對：找不到、叫不動、或叫到的是另一份安裝，
三種都驗得出來。轉接檔則逐一回磁碟讀，比對存在且內容含正確的叫用行。

驗證不碰網路，也與 Gitea 登入、時間追蹤無關，所以無條件執行。

驗不過回 ok:false，但已經寫好的轉接檔一份都不刪。回滾在升級情境下是淨損失：原本有一組
能用的舊轉接檔，覆蓋後驗證失敗再刪掉，使用者就從「有點舊但能用」變成什麼都沒有；何況
最可能的病灶是「PATH 上找不到 tea-sdlc」，那不是轉接檔的問題。

為此 lib 多一個 Failure：有一種失敗是事情做完了、檔案也寫出去了，只是驗不過，那時最該
交出去的正是「已經寫了哪些、哪一段不通」。envelope 形狀不變，只是 {ok:false, error}
旁邊多一個 data，只讀 error.code 的呼叫端照常運作。

--dry-run 不寫入，也就沒有東西可驗，verify 標成 skipped。

Closes #59

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:25:32 +08:00
jiantw83andClaude Opus 5 66064a751e fix(lib): 補回搬家時掉了的 rmSync，並讓 origin 檢查只有一份 
review 抓到一個沉默的失效：rollback 最後那一手「git 清不乾淨時把目錄本身也清掉」呼叫
rmSync，但把這段從 branch-prep 搬進 lib 時，import 留在了原處。那一行落在自己的
try/catch 裡，所以 ReferenceError 被吞掉——註解承諾的事從來沒發生過，而且測試全綠。
下一次重跑會撞上 WORKTREE_PATH_TAKEN，人看到的是一句與真正原因無關的錯誤。

順手收掉兩支腳本各寫一次的 origin 檢查（只有「為什麼需要它」那一句不同，由呼叫端給），
並把 lib 檔頭「負責六件事」改成七件——工作樹的一生現在整個住在這裡。

正本三處跟著改：
- 查現況那一行補上 --dry-run。pr-watch 在 PR 已終止時會順手清掉工作樹，而「我想看一下
  留言」不該把清理順便做掉——清不清理是使用者的決定。
- 拿掉「使用者堅持要繼續就繼續」：它與同一份正本的邊界（已合併或關閉時不繼續處理留言）
  直接矛盾，而在一棵該被清掉的工作樹上改東西，那些改動不會進到任何 PR 裡。
- worktree-ensure 的指令補上 --path：目標專案多半不是當前目錄，而「不必先手動 cd」
  正是這一步要解決的問題。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
jiantw83andClaude Opus 5 7196385c5e refactor(branch-prep): 建立工作樹的「算」與「做」收進 lib 
重建工作樹（下一個 commit 的 worktree-ensure）要走的是與開工時完全同一套：一樣先
git fetch 更新遠端引用，一樣不設 upstream，分支已經存在就接上去而不是長一棵空的。
兩邊各寫一份，遲早會在「起點取自哪裡」這種地方分岔——而那種分岔要等到有人的進度
不見了才會被發現。

planWorktree 多接受一種用法：不給來源分支就是「重建既有分支的工作樹」，沒有「從來源
長一支新的」那條路，走到那裡就是 BRANCH_NOT_FOUND。branch-prep 的行為完全不變。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
jiantw83andClaude Opus 5 ee474d0439 refactor(lib): 讀檔與列留言收進 lib，並讓已整併只認自己打的 +1 
「讀一個 --xxx-file 或直接失敗」原本在四支腳本各寫一份，錯誤碼還有三種拼法
（BODY_FILE_NOT_FOUND／BODY_FILE_MISSING／CONTENT_FILE_NOT_FOUND）。同一種情況要有同一個
碼，呼叫端才分辨得出是哪一步壞了。留言分頁的那段咒語也是第三份，一併收成 listIssueComments。

countUnmergedComments 原本接受任何人的 +1，而讀留言那邊只認自己的——兩端對「已整併」的
定義不一致。後果是隊友對決策留言按個讚，未處理留言數就掉到 0，analyze 與 feat 再也不提示，
那則決策永遠不會被收進描述。統一成只認自己打的：別人按讚是「我同意」，不是「已經收進去了」。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:05 +00:00
jiantw83andClaude Opus 5 617a3eef72 fix(pr-watch): 試跑的預告與實跑的守門對齊，並說出路徑被佔住這件事 
review 抓到一處落差：試跑判「終止且工作樹乾淨」就預告 git worktree remove，
但實跑多判一件事——那條路徑上的東西是不是真的一棵工作樹。別的 clone 在同一條路徑上
留下目錄時（路徑由 owner/repo/分支名 推導，不含本機 clone 的位置），試跑會預告一行
實跑必然拒絕的指令，而回報裡完全看不出原因。

判斷收進 lib 的 inspectWorktree，由它直接給出 reason（missing／foreign／dirty／
removable）：試跑與實跑、自動與手動四條路徑從此擋在同一個判斷上，worktree-remove 裡
那份重算的副本也跟著刪掉。回報多一個「是工作樹」欄位，手動出口的 NOT_A_WORKTREE
不再是使用者第一次聽到這件事。

順帶兩件同源的修正：
- 「是不是工作樹」改認 .git 為**檔案**。獨立 clone 的 .git 是目錄，先前會被當成工作樹，
  然後在 git worktree remove 那一步炸出一句原始錯誤。
- 兩支腳本的 --dry-run 請求預告收進 pr-threads 的 plannedRequests，並補上 pr-watch
  先前漏掉的那句說明（逐則 reaction 與逐個 review 的行內留言事前列不完）。預告與實際
  發出的請求分開寫，加一個端點就會有一邊忘了改。
- PR 讀不到 head 分支時給出 PULL_HEAD_MISSING，而不是拿空字串去推導一條路徑。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:06:07 +08:00
jiantw83andClaude Opus 5 9e049580bb feat(worktree-remove): 手動清掉一棵工作樹，絕不 --force 
pr-watch 會在 PR 合併或關閉時自動清理，但永遠不會被合併也不會被關閉的 PR 沒有出口
——沒有這一支，那些工作樹只能靠使用者自己記得去刪。兩條路共用 lib 的 removeWorktree，
不互相開子行程：守門的規則只有一份，自動的那條與手動的這條不該長出兩種行為。

**絕不 --force。** 清理會被自動執行，而自動執行的東西只能做可逆的事：工作樹重建得回來，
被刪掉的未提交變更救不回來。所以有東西沒提交就中止並報出路徑與檔名。只移除工作樹，
本機分支與遠端分支都留著。

輸入是 owner/repo 與分支名而不是一條路徑：要刪哪一棵由「哪顆工作包」決定，
使用者不必自己去記 12 碼的雜湊目錄名。

順手修掉一個測試抓出來的解析錯誤：git status --porcelain 的第一行前導空白會被 runGit
的 trim 修掉，固定切前三個字元會讓已修改檔案的檔名少一個字（README.md 變成 EADME.md），
人照著訊息去找會找不到。改成認「狀態欄一到兩個字元 + 空白」。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:59:30 +08:00
jiantw83andClaude Opus 5 0154cf59d4 fix(claim): 被碼錶擋下時明說停錶不會動到既有的工作樹 
議題 #38 的使用者故事第 30 條：使用者常以為停錶等於放棄那顆工作包，於是寧可
不停——工時就記到別顆議題去了。碼錶只管時間、工作樹只管檔案，兩者互不相干，
這件事要在擋下來的當下就講，不能指望使用者自己推論。

領取與起錶會撞到同一個擋路理由，訊息收進 lib 只寫一份。順手收掉 review 指出的
三處：planWorktree 沒用到的 repo 參數、與 path.resolve 同名而誤導的區域函式、
以及只有 lib 自己用得到卻對外 export 的兩支路徑函式。

回滾補上最後一道：git 清不掉時把目錄本身也刪掉。那條路徑在這次執行之前不存在
（不存在正是建立的前提），裡面不可能有使用者的東西，而留著它下一次重跑會直接
撞上 WORKTREE_PATH_TAKEN——一次失敗的建立不該讓人從此開不了工。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:29:12 +08:00
jiantw83andClaude Opus 5 5b740c236b feat(branch-prep): 一律在獨立的工作樹上開工，不在原地切換分支 
同一份 clone 上同時持有多顆工作包時，原地切分支有三種損耗，一種比一種難查：
未提交的變更擋路、建置產物跨分支混淆，以及 agent 讀到不屬於它那顆工作包的
程式碼——agent 是非同步的，它可能在分支已經被切走之後才去讀檔，而且不會察覺，
產出看起來完全合理，只是接錯了上下文。前兩種人會當場發現，第三種不會，
所以工作樹一律建立，不是「有衝突才用」。

建不起來就中止，不退回原地切分支：靜默降級會讓使用者以為自己在隔離環境裡，
其實在原地改。

分支與工作樹合併為一個原子動作（fetch 後一次 worktree add），並補上回滾——
git 在 worktree add 失敗時仍會把分支留下來，那是最難查的半成品：下一次重跑
會走到「目標分支已存在」那條路，起點從此不再是遠端的來源分支。

起點一律取自 origin/{來源分支}，遠端沒有就中止，不退回本機同名分支；
本機分支可能落後好幾天，而這件事從輸出上完全看不出來。原「來源分支在遠端
已存在時 pull 而非重建」那條，用更強的方式達成同一個目的：根本不碰本機分支，
就沒有覆蓋他人進度的可能。

不設 upstream：此刻遠端還沒有這個新分支，--track 會把 upstream 指到來源分支，
之後 git pull 會把來源分支的提交拉進來。留給第一次 push -u 自然建立。

路徑由 owner/repo/分支名 正規化後取雜湊推導（lib 的 worktreePath），不查表、
不寫狀態檔，換機器算出來一樣。取雜湊而不是把斜線攤平成 -，是因為攤平會讓
feat/a-b/main 與 feat/a/b/main 撞成同一個目錄，而現行的分支命名規則恰好讓
這種形狀有機會出現。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:27:43 +08:00
jiantw83 1c6e7f85bb fix(lib): 讓 --key=value 的值可以本身以 -- 開頭 
commit 訊息與 PR 描述裡出現 --flag 是常態，而原本的檢查對兩種寫法一視同仁：值只要以
-- 開頭就報「需要一個值」。空格分隔的寫法確實分不出「值」與「打錯的 flag」，但等號寫法
沒有這個歧義，不該一起擋掉。

這是實際撞到的：拿 commit-split 提交它自己時，--body 的內容第一行就是「--repo 與
--issue-repo 的差別」，整個 commit 因此做不出來。空格寫法的錯誤訊息現在會指路到等號寫法。
 2026-09-17 08:23:27 +00:00
jiantw83 95e6026950 refactor(lib): 開啟目標專案 git repo 的那幾行收進 lib 
「路徑不是 repo 就報 NOT_A_GIT_REPO」加上「把 cwd 綁進 runGit」原本在 branch-prep 與
commit-split 各寫一份。錯誤碼要一致，而這件事寫第三遍就該收起來了。
 2026-09-17 08:23:26 +00:00
jiantw83andClaude Opus 5 f524f17375 fix(lib): git 的進度訊息不再漏到 stderr，並讓前置檢查交回帳號 
兩件都是 branch-prep 與 claim 落地時才浮現的既有缺口：

git 把 checkout／fetch 的進度訊息全寫在 stderr，而 execFileSync 預設讓 stderr 直接
繼承給父行程。腳本的輸出契約是「stdout 一行 JSON、stderr 乾淨」，不收的話呼叫端還得
自己分辨哪幾行是雜訊。改成收進來；失敗時這些內容仍讀得到，錯誤訊息不會因此變模糊。

preflight 的第二層本來就打過 /user 問「我是誰」，卻只把答案丟掉，害呼叫端要再問一次。
改為連同 repo 資訊一起交回去。原本沒有任何呼叫端在用它的回傳值，形狀改變是安全的。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 07:06:59 +00:00
jiantw83andClaude Opus 5 17178f0c4d feat(佈署): 以 npm 裝出 tea-sdlc 指令並產生各平台轉接檔 
單一入口 bin/tea-sdlc.js 認四個子指令。第一個位置參數是子指令，其餘 argv 原樣
交出去——既有的 flag 解析拒絕位置參數，所以子指令必須在那之前就被取走。

轉接檔裡沒有路徑，只有一句 tea-sdlc prompt --name <指令名>。正本在哪由 PATH 上
的 tea-sdlc 自己回推：fnm 把 Node 版號寫進全域安裝路徑，寫死路徑的話升一次
Node，七個平台的轉接檔會同時指向不存在的檔案，而且不會有任何錯誤訊息。

prompt 是全專案唯一輸出非 JSON 的路徑，理由只有一個：它的輸出要餵給模型讀。
失敗仍走 envelope——成功是內容，失敗才需要結構。

status 的 ok 不兼差表達環境好壞，健康與否放在 data.healthy：呼叫端要分得出
「status 掛了」與「status 成功查到你環境有問題」。

install 只寫進偵測得到的平台；缺 git／tea 只警告不中止，因為那兩個完全不影響
轉接檔產生，硬擋等於逼使用者為了裝 plugin 先去裝 tea。uninstall 只刪帶產生標記
的檔案，使用者自己寫的同名檔案一律留著並在輸出裡交代。裝哪些指令以 prompts/ 裡
實際存在的正本為準，不是寫死的六個名字——裝出指向不存在正本的轉接檔，使用者只會
看到 PROMPT_NOT_FOUND。

流程正本的 description 前綴在抄進轉接檔之前就檢查：有三個平台關不掉自動觸發，
全靠那句話把 description 窄到不會被誤判，不能等使用者發現誤觸才知道漏了。

議題 #26 #27 #28 #29 #17

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:59:37 +00:00
jiantw83andClaude Opus 5 bbfa842e2a refactor(抽取): 議題讀取與留言計數收進 lib，兩支抽取腳本共用 
工作包的抽取契約（#9）要做的事與需求議題那一支有三件完全重疊：讀議題、把「不存在」
與「沒有讀取權」分成兩種錯誤碼、以 +1 reaction 數出未整併的留言則數。這三件事的規則
只該有一份，複製一份到新腳本等於日後改規則要記得改兩個地方。

fetchIssue、countUnmergedComments 與試跑時那句附註一起搬到 lib，issue-extract 改為
呼叫它們，行為不變。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:30:22 +00:00
jiantw83andClaude Opus 5 be6ceddde0 refactor(參數): parseIndex 抽到 lib，四支腳本共用 
同一段 /^[1-9]\d*$/ 與 BAD_INDEX 已經抄了四份。lib 本來就放著同性質的 parseRepo，
這一支該待在它旁邊。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:10 +00:00
jiantw83andClaude Opus 5 c8ecc39dc8 refactor(分頁): 把逐頁走訪抽成 lib.pages 
findIssueByTitle 原本自己寫了一份「翻到短頁為止、超過上限就報錯」的迴圈，
而新的留言走訪需要同一套規則。抽成非同步產生器之後，呼叫端仍能在找到目標時
提早離開，規則卻只寫一次。

錯誤碼與訊息由呼叫端指定：查重讀不完要講的是「可能重建議題」，數留言讀不完
要講的是「數不完未整併的則數」，處置不同就不該共用一句話。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:00:28 +00:00
jiantw83andClaude Opus 5 4f542d9c86 refactor(標籤): 把列標籤抽到 lib，讓要貼標籤的腳本共用 
labels-list 與後續要挑標籤的腳本都要打同一個端點，抽成 lib.listLabels 之後
端點只寫在一個地方。順帶把「本專案不建立標籤，這是取得標籤的唯一途徑」寫進
函式註解，讓下一個要加功能的人先看到這條界線。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:44:45 +00:00
jiantw83andClaude Opus 5 4ae097f1e1 fix(腳本契約): 長輸出不再被截斷，查重翻頁加上上限 
process.stdout.write 之後立刻 process.exit 會截斷輸出——stdout 接到 pipe 時
寫入是非同步的。改為等 write 的 callback 回來再退出。實測舊寫法在約 83KB 處
被切斷，新增的回歸測試以 8000 筆標籤覆蓋這條路徑。

findIssueByTitle 的翻頁原本沒有上限，Gitea 若持續回滿一頁就會無限打下去。
加上 200 頁上限，超過即以 DEDUPE_LIMIT 報錯而非無聲回 null——無聲回 null 會
讓呼叫端把既有議題再建一次，正好是冪等查重要防的事。

parseFlags 取值時不再於三元運算式內遞增迴圈變數，改為獨立敘述。

測試工具的 maxBuffer 調高到 64MB：預設 1MB 會在長輸出時砍掉子行程，那是測試
工具的限制而非腳本的問題。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:26:51 +00:00
jiantw83andClaude Opus 5 48fd69cfde feat(腳本契約): 建立共用函式庫、四層前置檢查與 labels-list 
scripts/lib.js 立起所有腳本共用的地基：具名 flag 解析、單行 JSON 輸出
{ok, data, error:{code, message}}、Gitea API 與 git 各自唯一的出口、
四層前置檢查、依標題的冪等查重。

前置檢查依序為執行環境（git/tea 在 PATH 上、plugin 目錄完整）、Gitea 登入
有效、帳號對 issues unit 的寫入權、repo 已開啟時間追蹤；任一層不通過即帶著
可區分的錯誤碼中止，訊息一律指出該去哪裡改設定，前一層沒過就不再往下打。

issues unit 的寫入權採實測而非讀 permissions.push——Gitea 的 team unit 權限
可獨立於 repo 的 push 權限。探針打在不存在的議題 index 0：有寫入權會通過權限
中介層後回 404，沒有則直接 403，兩種結果都不改動任何東西。

認證預設沿用使用者既有的 tea login（讀 tea 的 config.yml），環境變數
TEA_SDLC_API_BASE / TEA_SDLC_TOKEN 只作為測試與 CI 的覆寫出口。

labels-list 為第一支腳本，刻意只讀不寫，呼應「不自動建立 Gitea 標籤」。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:26:50 +00:00