JefferyandClaude Opus 4.8
1378f03595
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
108 lines
4.6 KiB
JavaScript
108 lines
4.6 KiB
JavaScript
/**
|
||
* 輸出最上層的「區塊／章節」分隔標題（前綴空行 + `=== 標題 ===`）。
|
||
* 用於切分整個執行流程中彼此獨立的大段落（例如「環境檢查」「執行審查」「發布結果」），
|
||
* 讓 CI log 在視覺上分群；屬於最高層級的分隔，內部再以 step / line 等細分。
|
||
*
|
||
* @param {string} title - 區塊標題文字。
|
||
* @returns {void} 無回傳值，僅將標題寫入 stdout。
|
||
*/
|
||
export function section(title) {
|
||
console.log(`\n=== ${title} ===`);
|
||
}
|
||
|
||
/**
|
||
* 輸出某個「步驟」的標題（前綴空行 + `[步驟代號] 標題`）。
|
||
* 適合在一個 section 之下標示流程中的各個有序步驟（如 `[1] 載入設定`、`[2] 呼叫模型`），
|
||
* 之後再用 input / output / line 等細項函式描述該步驟的細節。
|
||
*
|
||
* @param {string} stepName - 步驟代號或編號，會以中括號包覆顯示。
|
||
* @param {string} title - 步驟標題文字。
|
||
* @returns {void} 無回傳值，僅將步驟標題寫入 stdout。
|
||
*/
|
||
export function step(stepName, title) {
|
||
console.log(`\n[${stepName}] ${title}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出一筆縮排的一般明細列（` - 訊息`）。
|
||
* 用於在某個 step 之下列出不帶語意成敗的中性資訊（例如逐項說明、設定值、進度敘述）；
|
||
* 若要表達輸入／輸出或成敗，請改用 input / output / result / ok 等更具語意的函式。
|
||
*
|
||
* @param {string} message - 要顯示的明細訊息。
|
||
* @returns {void} 無回傳值，僅將明細寫入 stdout。
|
||
*/
|
||
export function line(message) {
|
||
console.log(` - ${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出「階段輸入」描述（` ← 輸入：訊息`），標示目前步驟吃進了什麼資料。
|
||
* 在一個步驟開始處理前，用來明確記錄其輸入來源或內容，方便日後對照輸出（output）追蹤資料流。
|
||
*
|
||
* @param {string} message - 描述輸入內容的訊息。
|
||
* @returns {void} 無回傳值，僅將輸入描述寫入 stdout。
|
||
*/
|
||
export function input(message) {
|
||
console.log(` ← 輸入：${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出「階段輸出」描述（` → 輸出：訊息`），標示目前步驟產出了什麼結果。
|
||
* 在一個步驟處理完成後，用來記錄其產出，與 input 搭配可在 log 中清楚呈現該步驟的資料流向。
|
||
*
|
||
* @param {string} message - 描述輸出內容的訊息。
|
||
* @returns {void} 無回傳值，僅將輸出描述寫入 stdout。
|
||
*/
|
||
export function output(message) {
|
||
console.log(` → 輸出：${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出一筆檢查／把關結果列，依結果以 `✅ 成功` 或 `❌ 失敗` 為前綴（` ✅ 成功：訊息`）。
|
||
* 用於明確標示某個驗證、條件判斷或 gate 的通過與否；
|
||
* 需要由布林值決定成敗、且希望成功與失敗使用一致格式時最適合（注意：失敗仍寫入 stdout，非 stderr）。
|
||
*
|
||
* @param {boolean} passed - 結果是否通過；`true` 顯示成功、`false` 顯示失敗。
|
||
* @param {string} message - 描述該結果的訊息。
|
||
* @returns {void} 無回傳值，僅將結果寫入 stdout。
|
||
*/
|
||
export function result(passed, message) {
|
||
console.log(` ${passed ? '✅ 成功' : '❌ 失敗'}：${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出一筆成功／完成訊息（` ✓ 訊息`）。
|
||
* 用於確認某項動作已順利完成的正向回饋；當只需表達成功、無需處理失敗分支時使用，
|
||
* 若需依條件同時涵蓋成功與失敗請改用 result，需要警告或錯誤請改用 warn / error。
|
||
*
|
||
* @param {string} message - 描述成功內容的訊息。
|
||
* @returns {void} 無回傳值，僅將成功訊息寫入 stdout。
|
||
*/
|
||
export function ok(message) {
|
||
console.log(` ✓ ${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出一筆警告訊息（` ! 訊息`），透過 `console.warn` 寫入 stderr。
|
||
* 用於流程仍可繼續、但需要提醒使用者注意的非致命狀況（例如使用了預設值、跳過某項可選步驟）；
|
||
* 比 line/ok 更醒目，但比 error 輕，真正導致失敗的狀況請改用 error。
|
||
*
|
||
* @param {string} message - 要顯示的警告訊息。
|
||
* @returns {void} 無回傳值，僅將警告訊息寫入 stderr。
|
||
*/
|
||
export function warn(message) {
|
||
console.warn(` ! ${message}`);
|
||
}
|
||
|
||
/**
|
||
* 輸出一筆錯誤訊息（` x 訊息`），透過 `console.error` 寫入 stderr。
|
||
* 用於明確的失敗或例外狀況，是日誌中最高的嚴重層級；
|
||
* 適合在捕捉到錯誤或前置條件不滿足而無法繼續時使用，僅需提醒注意的非致命狀況請改用 warn。
|
||
*
|
||
* @param {string} message - 要顯示的錯誤訊息。
|
||
* @returns {void} 無回傳值，僅將錯誤訊息寫入 stderr。
|
||
*/
|
||
export function error(message) {
|
||
console.error(` x ${message}`);
|
||
}
|