feat/npm-deploy-adapters/main #36

2026-09-17T07:00:00Z

jiantw83 commented

2026-09-17 07:00:00 +00:00

摘要

把 tea-sdlc 變成裝得起來、叫得動的東西：npm i -g <git url> 裝出 tea-sdlc 指令，tea-sdlc install 把流程指令佈署到機器上偵測得到的每個 agent 平台。轉接檔裡沒有路徑，只有一句 tea-sdlc prompt --name <指令名>，正本在哪由 PATH 上的 tea-sdlc 自己回推。

需求議題

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

工作包議題

#26 — 以 npm 安裝並建立 tea-sdlc 指令入口
#27 — 以 prompt 子指令供應流程正本
#28 — 以轉接檔版本比對提示重跑佈署
#29 — 以 status 子指令回報安裝與環境現況
#17 — 以 install.js 產生並移除各平台轉接檔

#17 的轉接檔內容是「執行 tea-sdlc prompt …」，那條驗收標準要驗得過，prompt 必須先存在，所以前四張票一起交付。

變更內容

bin/tea-sdlc.js：單一入口，認 install / uninstall / prompt / status 四個子指令。
scripts/install.js：七個平台的偵測、轉接檔產生與移除，全專案唯一知道各平台目錄結構的地方。
scripts/prompt.js：把流程正本原樣印到 stdout。
scripts/status.js：版本、正本位置、是否 link 模式、環境四項與各平台轉接檔現況。
scripts/lib.js：新增 RawText 原樣輸出模式、promptsDir / packageVersion、missingBinaries / checkPluginLayout / onPath。
package.json：移除 private、新增 bin 與 files 白名單，未新增 prepare，dependencies 仍然不存在。
README 改以 npm 為唯一建議路徑，補上更新／移除指令表；既有七套 marketplace 流程原封移進附錄。AGENTS.md 模組邊界表補上指令入口與 scripts/install.js。

設計重點

轉接檔不持有路徑。 fnm 把 Node 版號寫進全域安裝路徑，寫死路徑的話升一次 Node，七個平台的轉接檔會同時指向不存在的檔案，而且使用者不會收到任何錯誤——只會發現 /sdlc-plan 不動了。

prompt 是全專案唯一輸出非 JSON 的路徑。 它的輸出要餵給模型讀；把幾百行 markdown 包進單行 JSON 再逼模型反跳脫只會增加讀錯的機率。失敗仍走 envelope——成功是內容，失敗才需要結構。

ok 與 healthy 分離。 ok 的意思一直是「這支指令跑成功了」，不兼差表達環境好壞；混用會讓呼叫端分不出「status 掛了」與「status 成功查到你環境有問題」。

裝哪些指令以 prompts/ 裡實際存在的正本為準，不是寫死的六個名字——裝出指向不存在正本的轉接檔，使用者只會看到 PROMPT_NOT_FOUND。

description 前綴在抄進轉接檔之前就檢查。 有三個平台關不掉自動觸發，全靠那句話把 description 窄到不會被誤判。

解決的問題

裝完什麼都沒有：skills/ 是空的，七套 marketplace 流程照著做不會出現任何指令；換一台機器要為七個平台各學一套安裝流程；沒有一套流程回答「放進去的檔案要指向哪個正本」。

影響的功能

新增的都是新檔案。既有十五支腳本的輸入輸出契約未變，lib.main() 只在回傳 RawText 時改走原樣輸出，其餘路徑行為不變。runScript() 的單行 JSON 斷言未被放寬。

測試結果

npm test 332 pass / 0 fail。新增 6 個測試檔（入口、prompt、status、install、README、假 plugin 根 helper）。install 與 uninstall 全部在臨時家目錄上真的寫檔刪檔再斷言剩下什麼。

與議題文字的三處偏離

轉接檔不含絕對路徑（#17 寫「路徑於產生時替換為絕對路徑」）——被 #25 的重新設計取代，已與需求提出者確認。
status 回報 platforms（#29 寫「不回報 platforms」）——#29 與 #17 一起交付，以 #17 為準。
缺 git / tea 時只警告不中止（#17 寫「印出安裝指引並中止」）——#25 明文推翻：「缺 tea 完全不影響轉接檔產生，硬擋等於逼使用者為了裝 plugin 先去裝 tea」。這一條若要改回中止，動的地方很小。

另：uninstall 是子指令而不是 #17 的 --uninstall 旗標，因為 #26 定義了四個子指令名。

🤖 Generated with Claude Code

## 摘要把 tea-sdlc 變成裝得起來、叫得動的東西：`npm i -g <git url>` 裝出 `tea-sdlc` 指令，`tea-sdlc install` 把流程指令佈署到機器上偵測得到的每個 agent 平台。轉接檔裡沒有路徑，只有一句 `tea-sdlc prompt --name <指令名>`，正本在哪由 PATH 上的 `tea-sdlc` 自己回推。 ## 需求議題 #1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組 ## 工作包議題 - #26 — 以 npm 安裝並建立 tea-sdlc 指令入口 - #27 — 以 prompt 子指令供應流程正本 - #28 — 以轉接檔版本比對提示重跑佈署 - #29 — 以 status 子指令回報安裝與環境現況 - #17 — 以 install.js 產生並移除各平台轉接檔 #17 的轉接檔內容是「執行 tea-sdlc prompt …」，那條驗收標準要驗得過，prompt 必須先存在，所以前四張票一起交付。 ## 變更內容 - `bin/tea-sdlc.js`：單一入口，認 `install` / `uninstall` / `prompt` / `status` 四個子指令。 - `scripts/install.js`：七個平台的偵測、轉接檔產生與移除，全專案唯一知道各平台目錄結構的地方。 - `scripts/prompt.js`：把流程正本原樣印到 stdout。 - `scripts/status.js`：版本、正本位置、是否 link 模式、環境四項與各平台轉接檔現況。 - `scripts/lib.js`：新增 `RawText` 原樣輸出模式、`promptsDir` / `packageVersion`、`missingBinaries` / `checkPluginLayout` / `onPath`。 - `package.json`：移除 `private`、新增 `bin` 與 `files` 白名單，未新增 `prepare`，`dependencies` 仍然不存在。 - README 改以 npm 為唯一建議路徑，補上更新／移除指令表；既有七套 marketplace 流程原封移進附錄。AGENTS.md 模組邊界表補上指令入口與 `scripts/install.js`。 ## 設計重點 **轉接檔不持有路徑。** fnm 把 Node 版號寫進全域安裝路徑，寫死路徑的話升一次 Node，七個平台的轉接檔會同時指向不存在的檔案，而且使用者不會收到任何錯誤——只會發現 `/sdlc-plan` 不動了。 **prompt 是全專案唯一輸出非 JSON 的路徑。** 它的輸出要餵給模型讀；把幾百行 markdown 包進單行 JSON 再逼模型反跳脫只會增加讀錯的機率。失敗仍走 envelope——成功是內容，失敗才需要結構。 **`ok` 與 `healthy` 分離。** `ok` 的意思一直是「這支指令跑成功了」，不兼差表達環境好壞；混用會讓呼叫端分不出「status 掛了」與「status 成功查到你環境有問題」。 **裝哪些指令以 `prompts/` 裡實際存在的正本為準**，不是寫死的六個名字——裝出指向不存在正本的轉接檔，使用者只會看到 `PROMPT_NOT_FOUND`。 **description 前綴在抄進轉接檔之前就檢查。** 有三個平台關不掉自動觸發，全靠那句話把 description 窄到不會被誤判。 ## 解決的問題裝完什麼都沒有：`skills/` 是空的，七套 marketplace 流程照著做不會出現任何指令；換一台機器要為七個平台各學一套安裝流程；沒有一套流程回答「放進去的檔案要指向哪個正本」。 ## 影響的功能新增的都是新檔案。既有十五支腳本的輸入輸出契約未變，`lib.main()` 只在回傳 `RawText` 時改走原樣輸出，其餘路徑行為不變。`runScript()` 的單行 JSON 斷言未被放寬。 ## 測試結果 `npm test` 332 pass / 0 fail。新增 6 個測試檔（入口、prompt、status、install、README、假 plugin 根 helper）。install 與 uninstall 全部在臨時家目錄上真的寫檔刪檔再斷言剩下什麼。 ## 與議題文字的三處偏離 1. **轉接檔不含絕對路徑**（#17 寫「路徑於產生時替換為絕對路徑」）——被 #25 的重新設計取代，已與需求提出者確認。 2. **`status` 回報 `platforms`**（#29 寫「不回報 platforms」）——#29 與 #17 一起交付，以 #17 為準。 3. **缺 `git` / `tea` 時只警告不中止**（#17 寫「印出安裝指引並中止」）——#25 明文推翻：「缺 tea 完全不影響轉接檔產生，硬擋等於逼使用者為了裝 plugin 先去裝 tea」。這一條若要改回中止，動的地方很小。另：`uninstall` 是子指令而不是 #17 的 `--uninstall` 旗標，因為 #26 定義了四個子指令名。 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jiantw83 added 1 commit 2026-09-17 07:00:01 +00:00

feat(佈署): 以 npm 裝出 tea-sdlc 指令並產生各平台轉接檔 17178f0c4d

單一入口 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>