feat(overview-artifact): 產生可預覽總覽與截圖 fallback

This commit is contained in:
2026-09-18 15:59:34 +08:00
parent c545f11ec1
commit 867a23497f
16 changed files with 605 additions and 324 deletions
@@ -0,0 +1,18 @@
---
status: accepted
---
# 以能力描述而非工具名表達委派
流程正本在只在意結果的步驟上標記 `〔可委派〕`,並以**能力描述**說明怎麼委派——「你的環境若能把工作交給子代理,就交出去,只把結果帶回來;不能就自己做」——而不指名任何平台的子代理工具。子代理是平台專屬能力(Claude Code 與 Codex 有,Copilot/Kiro/OpenCode 不一定),而流程正本必須保持平台中立:這是 #4 已交付並打勾的驗收標準,也是 `AGENTS.md` 的模組邊界之一。能力描述對不支援的平台是自然降級,同一份正本兩邊都讀得通,不需要維護兩份。
## Considered Options
- **正本直接寫平台工具名**:最精確、agent 最不會誤判,但直接違反「流程正本不含任何平台專屬語法」,並且要為七個平台維護分歧的正本——那正是這個專案立「流程正本只有一份」時要防的事。
- **由 `install.js` 產生轉接檔時依平台注入**:轉接檔只有一行指回正本,塞不下步驟級的指示;而「哪些步驟可委派」是流程知識,搬進 `install.js` 會污染它「唯一知道各平台目錄結構」的單一職責。
## Consequences
- 這個寫法**刻意比它能做到的更模糊**。下一個讀到它的人第一反應很可能是「為什麼不直接寫工具名?」然後就把它改掉——這顆 ADR 存在的主要目的就是攔下那個修改。
- 委派的判準(四條,見 `references/delegation.md`)與正本上的標記必須靠測試綁在一起:資產測試斷言「正本上被標記的步驟集合等於判準文件列出的集合」。沒有這條雙向斷言,兩邊會漂開,而漂開時不會有任何東西報錯。
- 判準第二條(步驟中不會詢問使用者)與第四條(只產出草稿或唯讀結果,不直接寫入 Gitea 或 git)是硬排除,不是建議。前者因為子代理問不到使用者,後者因為子代理的失敗沒有人看著——備妥工作樹失敗會中止整個領取、實際提交失敗會留下半套 git 歷史,兩者都需要當場有人判斷下一步。