JefferyandClaude Opus 5
73b9cd9f75
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>
266 lines
12 KiB
Markdown
266 lines
12 KiB
Markdown
# tea-sdlc
|
||
|
||
以 [tea](https://gitea.com/gitea/tea) 與 Gitea REST API 驅動 **SDLC 全流程**的跨平台指令組。
|
||
把規劃、分析、實作、修正、整併、工時回報六個階段，固定成可重複、可被任何 coding agent 執行的流程。
|
||
|
||
- **流程正本只有一份**：平台中立 markdown 放在 `prompts/`，改規則不會出現各平台版本分歧。
|
||
- **副作用集中**：所有對 Gitea 與 git 的呼叫下沉到 `scripts/` 的零相依 Node 腳本，統一 JSON 輸入輸出。
|
||
- **產出有固定形狀**：議題、PR、報表一律套 `templates/` 的模板。
|
||
|
||
> 六個流程正本都到齊了，`tea-sdlc install` 會把它們一次佈署到偵測到的平台。
|
||
> 完整需求見[議題 #1](https://gitea.jsc.idv.tw/plugins/tea-sdlc/issues/1)，進度見其底下的工作包。
|
||
|
||
---
|
||
|
||
## 六個指令
|
||
|
||
| 指令 | 做什麼 |
|
||
| --- | --- |
|
||
| `/sdlc-plan` | 把一段口語需求變成結構化的需求議題 |
|
||
| `/sdlc-analyze` | 逐題把可行性疑點問到共識，據以產出工作包 |
|
||
| `/sdlc-feat` | 領取工作包、開分支、逐項實作並開 PR |
|
||
| `/sdlc-fix` | 處理 PR 上的留言 |
|
||
| `/sdlc-sync` | 把散落在留言裡的決策整併回議題描述 |
|
||
| `/sdlc-report` | 產出週／月／年工時報表 |
|
||
|
||
---
|
||
|
||
## 目錄結構
|
||
|
||
```
|
||
tea-sdlc/
|
||
├── prompts/ # ★ 流程正本：六個指令的平台中立 markdown
|
||
├── scripts/ # 所有 Gitea / git 副作用的唯一出口（Node，零相依）
|
||
├── templates/ # 議題、PR、報表、總覽網頁的輸出模板
|
||
├── references/ # 規則正本：實作規範、註解格式、可行性檢查清單
|
||
├── bin/tea-sdlc.js # 單一指令入口：install / uninstall / prompt / status
|
||
├── skills/ # 各助理原生 plugin 機制讀取的 skills（目前為空）
|
||
├── .claude-plugin/ # Claude Code 的 plugin / marketplace manifest
|
||
├── .codex-plugin/ # Codex 的 plugin manifest
|
||
├── .agents/plugins/ # Codex 的 marketplace manifest
|
||
├── plugin.json # Antigravity 的 plugin manifest
|
||
├── package.json # npm 打包與測試入口，無任何相依套件
|
||
├── AGENTS.md # 給 AI 助理的模組邊界與慣例
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 前置需求
|
||
|
||
安裝與佈署（`tea-sdlc install`）只需要 Node；其餘是**跑流程指令**時才需要的。
|
||
本工具一律不替你安裝任何東西。
|
||
|
||
| 需求 | 用途 | 缺了會怎樣 |
|
||
| --- | --- | --- |
|
||
| Node.js ≥ 20 | 執行 `tea-sdlc` 與 `scripts/` | 連 `tea-sdlc` 都跑不起來 |
|
||
| git | 分支與 commit 操作 | `install` 照樣把轉接檔裝好，只在輸出裡列出缺的東西；流程指令中止並印出安裝指引 |
|
||
| [`tea`](https://gitea.com/gitea/tea) 並已登入 | Gitea 議題、標籤、Milestone、留言、工時 | 同上；登入用 `tea login add` |
|
||
| 目標 repo 已開啟時間追蹤 | 工時碼錶 | 流程指令中止，並指出 Settings → Advanced Settings → Enable Time Tracker |
|
||
| 帳號對目標 repo 的 issues unit 有寫入權 | 建立與更新議題 | 流程指令中止；Gitea 的 unit 權限獨立於 push 權限 |
|
||
|
||
---
|
||
|
||
## 安裝
|
||
|
||
一行裝好，終端機就多出一個 `tea-sdlc` 指令：
|
||
|
||
```bash
|
||
npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
|
||
```
|
||
|
||
要裝特定版本就在網址後面接上 tag：`...tea-sdlc.git#v0.1.0`。不必設定任何 registry 或憑證。
|
||
|
||
> `git+` 前綴不能省。npm 只有看到 `git+https://` 才會當成 git repo；寫成 `https://….git`
|
||
> 會被當成遠端壓縮檔下載，然後以 `TAR_BAD_ARCHIVE: Unrecognized archive format` 失敗。
|
||
|
||
接著把六個流程指令佈署到你裝了的每個 agent 平台：
|
||
|
||
```bash
|
||
tea-sdlc install
|
||
```
|
||
|
||
它會列出偵測到的平台讓你勾選（預設全勾），只寫進已經存在的平台目錄，不在沒裝的平台留下孤兒目錄。
|
||
沒有終端機可問時（CI、腳本）不會停下來等輸入，直接照預設全裝。
|
||
`--platform` 直接指定安裝對象，`--dry-run` 先看會動到哪些檔案：
|
||
|
||
```bash
|
||
tea-sdlc install --platform claude,codex
|
||
tea-sdlc install --dry-run
|
||
```
|
||
|
||
| 平台 | 偵測 | 轉接檔落點 | 形式 |
|
||
| --- | --- | --- | --- |
|
||
| `claude`（Claude Code） | `~/.claude/` | `~/.claude/commands/sdlc-*.md` | command |
|
||
| `codex`（Codex） | `~/.codex/` | `~/.codex/prompts/sdlc-*.md` | command |
|
||
| `opencode`（OpenCode） | `~/.config/opencode/` | `~/.config/opencode/command/sdlc-*.md` | command |
|
||
| `oh-my-pi` | `~/.omp/` | `~/.omp/commands/sdlc-*.md` | command |
|
||
| `antigravity`（Antigravity） | `~/.gemini/` | `~/.gemini/skills/sdlc-*/SKILL.md` | skill |
|
||
| `kiro`（Kiro） | `~/.kiro/` | `~/.kiro/skills/sdlc-*/SKILL.md` | skill |
|
||
| `copilot`（GitHub Copilot） | 專案裡的 `.github/` | `.github/skills/sdlc-*/SKILL.md` | skill |
|
||
|
||
轉接檔裡**沒有路徑**，只有一句「執行 `tea-sdlc prompt --name sdlc-plan`」。正本在哪由 PATH 上的
|
||
`tea-sdlc` 自己回推——升級 Node、換版本管理器、改 npm prefix 都不會讓七個平台的轉接檔同時失效。
|
||
|
||
### 安裝完成等於驗過能用
|
||
|
||
寫完轉接檔之後，`install` 會把那條叫用鏈真的走一遍：**轉接檔 → PATH 上的 `tea-sdlc` → 流程正本**。
|
||
它實際到 PATH 上把 `tea-sdlc` 找出來執行一次、取回一份正本逐字比對，再逐一比對每個平台的轉接檔
|
||
存在且內容含正確的叫用行，結果放在輸出的 `verify` 裡，逐平台 pass/fail。**任一環不通，`install`
|
||
就回 `ok:false`。** 這段完全不碰網路，也與 Gitea 登入、時間追蹤無關。
|
||
|
||
最脆弱的是中間那一環：套件裝在某個 Node 版本底下，換個版本就找不到了，而轉接檔本身看起來完全正常——
|
||
沒有這道驗證，使用者要到第一次打 `/sdlc-plan` 才發現。
|
||
|
||
**驗不過也不會回滾**，已經寫好的轉接檔一份都不刪。回滾在升級情境下是淨損失：原本有一組能用的舊
|
||
轉接檔，覆蓋後驗證失敗再刪掉，就從「有點舊但能用」變成什麼都沒有；何況最可能的病灶是「PATH 上
|
||
找不到 `tea-sdlc`」，那不是轉接檔的問題。輸出的 `error.message` 會指出病灶與修復方式，修好之後
|
||
重跑 `tea-sdlc install` 就好。
|
||
|
||
`--dry-run` 不寫入任何轉接檔，也就沒有東西可驗，`verify` 會標成 `skipped` 並說明原因。
|
||
|
||
還沒裝 `git` 或 [`tea`](https://gitea.com/gitea/tea) 也可以先裝：轉接檔的產生不需要它們，
|
||
安裝會把缺的東西列在輸出的 `missingBinaries` 與 `warning` 裡，但不會替你安裝，也不會因此中止。
|
||
真正需要它們的是流程指令本身，跑之前補上即可。
|
||
|
||
---
|
||
|
||
## 更新 / 移除
|
||
|
||
改流程正本、腳本、模板或規則，只要重裝套件，下一次叫用就讀到新的，**不必重新佈署**；
|
||
只有指令數量或轉接檔模板本身變了，才需要再跑一次 `tea-sdlc install`（轉接檔過時時，
|
||
叫用它會在輸出最前面提醒你）。
|
||
|
||
| 想做的事 | 指令 |
|
||
| --- | --- |
|
||
| 更新到最新版 | `npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git` |
|
||
| 指令數量變了之後重新佈署 | `tea-sdlc install` |
|
||
| 查目前版本、正本位置與環境 | `tea-sdlc status` |
|
||
| 只移除轉接檔（正本不動） | `tea-sdlc uninstall` |
|
||
| 連套件一起移除 | `tea-sdlc uninstall` → `npm rm -g tea-sdlc` |
|
||
|
||
> **不要用 `npm update -g`。** 這個套件是從 git URL 裝的，`npm update -g` 認不得它的來源，
|
||
> 不會有任何更新發生，也不會報錯——重裝（上表第一行）才是更新的方式。
|
||
>
|
||
> **移除的順序不能顛倒。** 先 `npm rm -g tea-sdlc` 會把 `tea-sdlc` 指令一起帶走，
|
||
> 留在七個平台目錄裡的轉接檔就再也沒有東西能刪它們了，只能手動一個個找出來。
|
||
|
||
`tea-sdlc uninstall` 只刪自己產生的檔案：每份轉接檔裡都有產生標記，沒有標記的同名檔案一律留著，
|
||
並在輸出裡告訴你留了哪些。
|
||
|
||
---
|
||
|
||
## 給 agent 的入口
|
||
|
||
轉接檔指向的就是這一支。它把流程正本原樣印到 stdout，不包 JSON——那些內容是要給模型讀的。
|
||
|
||
```bash
|
||
tea-sdlc prompt --name sdlc-plan
|
||
```
|
||
|
||
其餘子指令與所有腳本一樣輸出單行 JSON `{ok, data, error:{code, message}}`，exit 0 或 1。
|
||
|
||
```bash
|
||
tea-sdlc status # 版本、正本位置、是否 link 模式、node/git/tea/登入、各平台轉接檔現況
|
||
```
|
||
|
||
`status` 在環境不健康時**指令本身仍算成功**（`ok` 為 `true`、`data.healthy` 為 `false`）：
|
||
「查詢失敗」與「成功查到你環境有問題」的下一步完全不同，不該由同一個旗標表示。
|
||
|
||
---
|
||
|
||
## 附錄
|
||
|
||
### 其他安裝方式（plugin / marketplace 機制）
|
||
|
||
> 這些是各助理原生的 plugin / marketplace 機制。它們目前**裝不出任何指令**——`skills/` 還是空的，
|
||
> 真正會生效的是上面 `tea-sdlc install` 產生的轉接檔。保留在這裡是因為這些機制本身有用
|
||
> （自動更新、plugin 清單），等 `skills/` 有內容時會回來。
|
||
|
||
#### Claude Code
|
||
|
||
```bash
|
||
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
|
||
claude plugin install tea-sdlc@tea-sdlc
|
||
|
||
# 更新
|
||
claude plugin marketplace update tea-sdlc
|
||
claude plugin update tea-sdlc@tea-sdlc
|
||
|
||
# 移除
|
||
claude plugin uninstall tea-sdlc@tea-sdlc
|
||
claude plugin marketplace remove tea-sdlc
|
||
```
|
||
|
||
工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
|
||
本機開發（免 push）：`claude plugin marketplace add /root/plugins/tea-sdlc`（本地路徑）後再 install。
|
||
|
||
#### Codex
|
||
|
||
```bash
|
||
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
|
||
codex plugin add tea-sdlc@tea-sdlc
|
||
|
||
# 更新（重新抓取 marketplace 的 git 快照）
|
||
codex plugin marketplace upgrade tea-sdlc
|
||
|
||
# 移除
|
||
codex plugin remove tea-sdlc@tea-sdlc
|
||
codex plugin marketplace remove tea-sdlc
|
||
```
|
||
|
||
安裝 token `tea-sdlc@tea-sdlc` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。安裝後重啟 Codex。
|
||
|
||
#### Antigravity（`agy`）
|
||
|
||
> `agy plugin install <url>` 目前只支援 github.com；Gitea 等自架 git 請先 clone 再用本地路徑安裝。
|
||
|
||
```bash
|
||
git clone https://gitea.jsc.idv.tw/plugins/tea-sdlc.git ~/plugins/tea-sdlc
|
||
agy plugin install ~/plugins/tea-sdlc
|
||
|
||
# 更新（agy 無 update 子指令 → git pull 後重裝）
|
||
git -C ~/plugins/tea-sdlc pull
|
||
agy plugin uninstall tea-sdlc
|
||
agy plugin install ~/plugins/tea-sdlc
|
||
```
|
||
|
||
#### GitHub Copilot CLI
|
||
|
||
```bash
|
||
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
|
||
copilot plugin install tea-sdlc@tea-sdlc
|
||
|
||
# 更新
|
||
copilot plugin marketplace update tea-sdlc
|
||
copilot plugin update tea-sdlc@tea-sdlc
|
||
|
||
# 移除
|
||
copilot plugin uninstall tea-sdlc@tea-sdlc
|
||
copilot plugin marketplace remove tea-sdlc
|
||
```
|
||
|
||
#### OpenCode
|
||
|
||
OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於本 repo；改用目錄安裝。
|
||
OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。
|
||
|
||
```bash
|
||
git clone https://gitea.jsc.idv.tw/plugins/tea-sdlc.git ~/plugins/tea-sdlc
|
||
mkdir -p ~/.config/opencode/skills
|
||
cp -r ~/plugins/tea-sdlc/skills/* ~/.config/opencode/skills/
|
||
```
|
||
|
||
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
|
||
|
||
---
|
||
|
||
## 開發
|
||
|
||
```bash
|
||
npm test # 等同 node --test，使用 Node 內建測試執行器，無任何外部套件
|
||
```
|
||
|
||
測試產生的暫存一律寫到 `.tmp/`（已被 git 忽略，也不會被測試探索掃到）。
|
||
模組邊界與其餘慣例見 [`AGENTS.md`](./AGENTS.md)。
|