除錯模式
僅在使用者明確呼叫 debug-mode、$debug-mode、debug mode 或儀器化除錯後，才使用此技能。
如果使用者未明確選擇加入，請正常除錯。僅在暫時性執行時期儀器化能實質幫助時，才提及此技能。
核心循環
執行假設驅動的除錯循環：
- 閱讀相關程式碼、重現細節和現有日誌。
- 列出 2-5 個排序的假設，並帶有 ID，例如
H1、H2和H3。 每個假設必須預測執行時期探針將會顯示的結果。 - 啟動或重複使用迴路收集器（收集器合約）。
- 新增 3-8 個目標探針來區分這些假設。使用傳送至
DEBUG_URL + "/log"的結構化事件，絕不使用 stdout/stderr。遵循下方的事件形狀、區域標記和輔助程式。 - 在人工檢查點停止。傳送檢查點範本。在使用者回覆
A、B或C之前，不要分析、修復或移除探針。 - 在
A之後，檢查列印出的LOG_FILE，將每個假設分類為CONFIRMED、REJECTED或INCONCLUSIVE，並且僅在日誌解釋了根本原因時，進行最小的修復。遵循下方的證據摘要。 - 讓探針在一次標記為
runId: "post-fix"的修復後運行中保持啟用。 - 在使用者對修復後檢查點回覆
B後，移除所有儀器化並執行相關檢查。遵循下方的清除清單。
嚴格規則
- 絕不要在新增探針後跳過手動重現檢查點。
- 絕不要在此技能啟用時憑猜測進行修復。
- 絕不要在使用者確認修復後檢查之前移除探針。
- 絕不要提交除錯日誌或暫時性儀器化。
- 絕不要記錄機密、令牌、Cookie、授權標頭、API 金鑰、原始請求主體、可能包含私人資料的原始回應，或不必要的個人資料。
收集器合約
隨附的收集器特意設計為小巧：
GET /health檢查現有收集器是否可重複使用。POST /log接受一個 JSON 物件，並以非同步方式附加一行 NDJSON。 驗證後回傳200；該行在背景寫入。- 不同工作階段會寫入具有獨立佇列的個別檔案，因此寫入可以跨工作階段並行進行。
- 日誌預設存放在作業系統暫存目錄下，位於工作空間之外。
--ensure會列印DEBUG_URL、SESSION_ID、LOG_DIR、LOG_FILE和HEALTH_URL。- 收集器在第一個事件時建立
LOG_FILE。不要在重現後對其執行touch、預先建立、截斷或清除。 - 收集器僅限迴路模式。不要將其綁定到
0.0.0.0或任何公開介面。
使用以下方式啟動或重複使用：
node <skill-dir>/scripts/log-server.mjs --ensure --session <session_id> --host 127.0.0.1 --port 0
在封鎖本機連接埠監聽器的受管沙箱中，在首次嘗試時請求代理的正常核准。將原因限定為啟動或重複使用此僅限迴路的除錯收集器。
檢查點範本
新增探針後，停止並傳送此形狀，並使用實際的工作階段詳細資料：
我已新增除錯模式探針，收集器正在寫入：
- 工作階段：<session_id>
- 日誌檔案：<LOG_FILE>
- 除錯端點：<DEBUG_URL>/log
請手動重現錯誤，然後回覆：
A - 已重現
B - 已修復
C - 其他；請描述發生的情況
對於修復後驗證，僅更改開頭句子：
我為修復後驗證保留了除錯模式探針，收集器正在寫入：
- 工作階段：<session_id>
- 日誌檔案：<LOG_FILE>
- 除錯端點：<DEBUG_URL>/log
請手動驗證原始錯誤，然後回覆：
A - 已重現
B - 已修復
C - 其他；請描述發生的情況
將檢查點回覆視為一個小型狀態機：
- 修復前的
A：讀取 NDJSON 日誌，分類假設證據，然後僅修復已確認的原因或新增更窄的探針。 - 修復後的
A：錯誤仍然重現。讀取修復後的日誌並繼續使用更窄的假設或探針。 - 修復前的
B：非終端狀態。將其視為錯誤在儀器化下未重現的證據，並要求澄清或更窄的重現步驟。 - 修復後的
B：移除探針並執行最終檢查。 - 任何時候的
C：將使用者的文字視為證據。調整重現步驟、假設或探針。
事件形狀
使用結構化、低容量的事件。典型事件看起來像：
{
"session": "<session_id>",
"runId": "pre-fix",
"probe": "settings.beforePersist",
"hypothesis": "H1",
"file": "src/settings/save.ts",
"fn": "saveSettings",
"vars": {
"enabled": true,
"userId": "redacted"
}
}
在修復前使用 runId: "pre-fix"，在驗證時使用 runId: "post-fix"。對於高頻路徑，僅在狀態變更時記錄或積極取樣。
區域標記
包裹所有暫時性儀器化，以便清除可以機械化：
// #region DEBUG_MODE_PROBE <session_id> settings-before-persist
debugModeLog({
probe: "settings.beforePersist",
hypothesis: "H1",
file: "src/settings/save.ts",
fn: "saveSettings",
vars: { enabled, userId: "redacted" },
});
// #endregion DEBUG_MODE_PROBE <session_id>
常見的註解形式：
// #region DEBUG_MODE_PROBE <session_id> ... JavaScript、TypeScript、Java、C#、Go、Rust、C、C++
# #region DEBUG_MODE_PROBE <session_id> ... Python、Ruby、Shell、YAML
<!-- #region DEBUG_MODE_PROBE <session_id> --> HTML、Vue、Svelte
/* #region DEBUG_MODE_PROBE <session_id> */ CSS 和 C 風格區塊上下文
-- #region DEBUG_MODE_PROBE <session_id> ... SQL、Lua
輔助程式
對於瀏覽器或前端 JavaScript，使用 assets/browser-log-helper.js 作為規範輔助範本。將其複製到儀器化的模組或腳本中，取代 <session_id> 和 <DEBUG_URL>，並保留函式名稱 debugModeLog。
對於 Node.js 或伺服器端 JavaScript，使用 assets/node-log-helper.js 作為規範輔助範本。將其複製到儀器化的模組或腳本中，取代 <session_id> 和 <DEBUG_URL>，並保留函式名稱 debugModeLog。
對於沒有第三方相依性的 Python：
# #region DEBUG_MODE_PROBE <session_id> debug-log-helper
import json
import urllib.request
DEBUG_MODE_URL = "<DEBUG_URL>/log"
def debug_mode_log(event):
try:
payload = {"session": "<session_id>", **event}
data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(
DEBUG_MODE_URL,
data=data,
headers={"content-type": "application/json"},
method="POST",
)
urllib.request.urlopen(req, timeout=0.5).close()
except Exception:
pass
# #endregion DEBUG_MODE_PROBE <session_id>
證據摘要
在 A 回覆後，在編輯程式碼之前摘要證據：
H1 設定狀態在 API 呼叫前遺失
狀態：CONFIRMED
證據：settings.beforePersist 記錄了 enabled=false，而 UI 事件記錄了 enabled=true。
H2 API 拒絕該值
狀態：REJECTED
證據：此次重現中沒有進行任何 API 呼叫。
下一步：修復 onToggle 和 saveSettings 之間的本機狀態傳遞。
如果每個假設都是 REJECTED 或 INCONCLUSIVE，則從不同的子系統產生新的假設並新增更窄的探針。不要憑感覺修補。
疑難排解
- 空日誌：確認應用程式執行了儀器化的路徑、工作階段 ID 相符，且端點包含
/log。 - 瀏覽器封鎖請求：檢查混合內容、CSP
connect-src、擴充功能隔離或內容腳本上下文。 - CORS/預檢問題：收集器處理
OPTIONS；如果仍然失敗，請嘗試navigator.sendBeacon、同源開發伺服器代理程式或伺服器端儀器化。 - 主機被拒絕：使用
127.0.0.1、localhost或::1；絕不要綁定到 LAN 或公開介面。 - 沙箱封鎖監聽器：使用此迴路收集器所需的核准重試一次。如果核准被拒絕，請說明本機收集被阻擋，並僅在存在安全的基於檔案的探針路徑時才回退。
- 日誌過多：用更窄的狀態變更探針取代吵雜的探針。
- 無法重現：詢問確切步驟、環境、輸入資料或螢幕錄製；不要憑空發明修復。
清除清單
在宣告任務完成之前：
- 重新執行原始重現步驟或最接近可用的自動化檢查。
- 移除每一對標記為
DEBUG_MODE_PROBE <session_id>的區域。 - 搜尋工作階段 ID、
DEBUG_MODE_PROBE、#region DEBUG_MODE_PROBE和#endregion DEBUG_MODE_PROBE。 - 移除位於列印出的
LOG_FILE中的工作階段 NDJSON 日誌，或確認應將其保留作為本機證據。 - 僅保留產品修復和任何實用的迴歸測試。