jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
51 lines
4.2 KiB
Markdown
51 lines
4.2 KiB
Markdown
---
|
||
name: spec-ask-user
|
||
description: JSC plugins 共用「詢問使用者規範」：何時該用 AskUserQuestion（單選／多選判斷時機）、選項數量上限 4（工具限制，超過改列文字選項並支援使用者輸入 all／全部代表全選）、每組問題必須含「其他」自訂輸入、破壞性決策不得被 --yes 等自動確認旗標略過而必須真的詢問、已從其他管道得知答案時跳過詢問、絕不要求使用者把 token 或密碼貼進對話框。當其他 skill 內文引用 spec-ask-user 或 /jsc-shared:spec-ask-user、或需要決定是否／如何向使用者提問時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-ask-user — 共用詢問使用者規範
|
||
|
||
所有 JSC skills 需要向使用者提問（確認決策、多選範圍、選擇執行方式）時，一律遵守以下規範。
|
||
|
||
## 何時該用 `AskUserQuestion`（單選 vs 多選）
|
||
|
||
| 情境 | 用哪種 | 說明 |
|
||
| --- | --- | --- |
|
||
| 使用者已在參數或對話中明確給答案 | **不問**（跳過） | 見「已知答案時跳過詢問」 |
|
||
| 答案只能是其中一個（例如選一種工具、選一個要處理的目標） | **單選** | 選項間互斥 |
|
||
| 答案可以同時成立多個（例如挑選要同步的擁有者、要同步的標籤） | **多選**（`multiSelect`） | 選項間不互斥 |
|
||
| 屬於破壞性、對外且不易復原的動作（關閉議題、改寫程式語言、對齊高風險結構） | **必問**，不可省略 | 見「破壞性決策」 |
|
||
|
||
不確定答案是否互斥時，先判斷「使用者是否可能同時要好幾個」——可能就用多選，不確定就傾向多選（漏選比誤判單選更容易補救）。
|
||
|
||
## 選項數量上限 4（工具本身限制）
|
||
|
||
`AskUserQuestion` 每組問題最多只能放 **4 個選項**，這是工具本身的限制，不是建議值。
|
||
|
||
- 候選項目 ≤ 4：直接用 `AskUserQuestion` 呈現。
|
||
- 候選項目 > 4：**改用文字列出全部選項**（表格或條列，附編號），請使用者以編號或名稱回覆（多選時支援逗號或空白分隔多個），並**支援使用者輸入 `all`／`全部` 代表全選**。
|
||
- 文字列出時仍要解析使用者回覆為明確集合；無法對應的輸入回報並請使用者重選，**不臆測**。
|
||
|
||
## 每組問題必須包含「其他」
|
||
|
||
不論選項數在 4 以內用 `AskUserQuestion`、還是超過 4 改文字列出，都必須提供「其他」讓使用者自訂輸入，用於選項未涵蓋使用者實際需求的情況。不可只列預設選項就視為選項齊全。
|
||
|
||
## 破壞性決策不得被自動確認旗標略過
|
||
|
||
凡屬破壞性、對外、不易復原的決策（例如：關閉議題／專案、改寫程式語言、對齊高風險結構、覆寫既有檔案內容、刪除或搬移資源），**必須真的詢問使用者**並取得明確回覆才可執行：
|
||
|
||
- `--yes`、`--force`、`--auto` 之類的自動確認旗標**不得**用來略過這類詢問；這些旗標最多只能省略「是否繼續」這種非破壞性的確認，不能代替破壞性決策的確認。
|
||
- 未獲得使用者針對該次破壞性決策的明確回覆前，不得執行對應的寫入或不可逆動作。
|
||
- 選項至少要能區分「執行」「不執行／取消」，並視情境提供更細的選項（例如逐項確認），再加上「其他」。
|
||
|
||
## 已從其他管道得知答案時要跳過詢問
|
||
|
||
使用者已在本次對話、參數、或上游流程結果中明確給過答案時（例如已指定 `--owner`、已在對話中選定工具、已提供目標議題編號），**跳過對應詢問**，不要明知道答案還多問一次；只需驗證該答案是否有效（例如清單中確實存在），無效才回頭詢問。
|
||
|
||
## 絕不要求使用者把 token 或密碼貼進對話框
|
||
|
||
任何情況下都不得請使用者把 token、密碼、或其他機密資料貼到 `AskUserQuestion` 或一般對話輸入框中：
|
||
|
||
- 機密一律透過環境變數、設定檔或既有登入態取得並驗證可用性（見 `/jsc-shared:spec-gitea` 的 token 解析優先序）。
|
||
- 需要的機密不可用時，回報缺少什麼（例如「缺少 `GITEA_TOKEN`」）並停止，改請使用者在環境變數或設定檔中設置，而不是詢問使用者輸入機密內容。
|