debug 调试技能：基于运行时证据自动化修复代码错误，提升开发效率

debug by vltansky/debug-skill

128 周安装量

10 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vltansky/debug-skill --skill debug

开发自动化调试

🇨🇳中文介绍

调试模式

基于运行时证据修复错误，而非猜测。

不要猜测 → 假设 → 插桩 → 复现 → 分析 → 修复 → 验证

何时使用

触发信号（如果你即将进行以下任何操作，请使用此技能替代）：

"打开 DevTools 控制台并检查..."
"复现这个错误并告诉我你看到了什么"
"添加 console.log 并告诉我输出结果"
"点击 X，打开 Y，检查 Z 是否出现在控制台"

应触发此技能的示例场景：

❌ 不使用技能（手动，缓慢）：
"我添加了调试日志。请：
1. 在浏览器中打开应用
2. 打开 DevTools 控制台 (F12)
3. 打开缺陷模态框并选择一个缺陷
4. 在控制台中检查 [DEBUG] 日志
5. 告诉我你看到了什么"

✅ 使用技能（自动化）：
日志在服务器端捕获 → 你直接读取 → 无需用户复制粘贴

在调试以下问题时使用：

状态/值问题（null、undefined、类型错误）
条件逻辑（执行了哪个分支）
异步时序（竞态条件、加载顺序）
用户交互流程（模态框、表单、点击）

参数

/debug /path/to/project

如果未提供路径，则使用当前工作目录。

工作流程

阶段 1：启动日志服务器

步骤 1：确保服务器正在运行（如果需要则启动，如果已在运行则无操作）：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

阶段 2：生成假设

在插桩之前，生成 3-5 个具体的假设：

假设 H1：userId 在传递给 calculateScore() 时为 null
  预期：数字（例如，5）
  实际：null
  测试：在函数入口记录 userId

假设 H2：score 是字符串而不是数字
  预期：85（数字）
  实际："85"（字符串）
  测试：记录 typeof score

每个假设必须：

具体（不是"某些地方有问题"）
可测试（可以通过日志确认/拒绝）
覆盖不同的子系统（不要集中在一个地方）

──────────

阶段 3：插桩代码

添加日志调用来测试所有假设。

JavaScript/TypeScript：

// #region debug
const SESSION_ID = 'REPLACE_WITH_SESSION_ID'; // e.g. 'fix-null-userid-a1b2c3'
const DEBUG_LOG_URL = 'http://localhost:8787/log';

const debugLog = (msg, data = {}, hypothesisId = null) => {
  const payload = JSON.stringify({
    sessionId: SESSION_ID,
    msg,
    data,
    hypothesisId,
    loc: new Error().stack?.split('\n')[2],
  });

  if (navigator.sendBeacon?.(DEBUG_LOG_URL, payload)) return;
  fetch(DEBUG_LOG_URL, { method: 'POST', body: payload }).catch(() => {});
};
// #endregion

// Usage
debugLog('Function entry', { userId, score, typeScore: typeof score }, 'H1,H2');

# #region debug
import requests, traceback
SESSION_ID = 'REPLACE_WITH_SESSION_ID'  # e.g. 'fix-null-userid-a1b2c3'
def debug_log(msg, data=None, hypothesis_id=None):
    try:
        requests.post('http://localhost:8787/log', json={
            'sessionId': SESSION_ID, 'msg': msg, 'data': data,
            'hypothesisId': hypothesis_id, 'loc': traceback.format_stack()[-2].strip()
        }, timeout=0.5)
    except: pass
# #endregion

# Usage
debug_log('Function entry', {'user_id': user_id, 'type': type(user_id)}, 'H1')

3-8 个插桩点
覆盖：入口/出口、关键操作之前/之后、分支路径
用 hypothesisId 标记每条日志
用 // #region debug ... // #endregion 包裹
高频事件（鼠标移动、滚动）：仅在状态改变时记录
记录意图和结果

──────────

阶段 4：清除日志并复现

清除日志：

: > /path/to/project/.debug/debug-$SESSION_ID.log

提供复现步骤：

<reproduction_steps>
1. 启动应用：yarn dev
2. 导航到 /users
3. 点击 "Calculate Score"
4. 观察到显示 NaN
</reproduction_steps>

用户复现错误

──────────

阶段 5：分析日志

cat /path/to/project/.debug/debug-$SESSION_ID.log

对于每个假设：

假设 H1：userId 是 null
  状态：已确认
  证据：{"msg":"Function entry","data":{"userId":null}}

假设 H2：score 是字符串
  状态：已拒绝
  证据：{"data":{"typeScore":"number"}}

已确认：日志证明
已拒绝：日志证伪
不确定：需要更多插桩

如果全部为不确定/已拒绝：生成新的假设，添加更多日志，迭代。

──────────

仅当日志确认根本原因时才进行修复。

保持插桩处于活动状态（暂时不要移除）。

用 runId: "post-fix" 标记验证日志：

debugLog('Function entry', { userId, runId: 'post-fix' }, 'H1');

──────────

清除日志
用户复现（错误应该消失）

比较修复前/后：

Before: {"data":{"userId":null},"runId":"run1"}
After:  {"data":{"userId":5},"runId":"post-fix"}

用日志证据确认

如果仍然有问题：新的假设，更多日志，迭代。

──────────

阶段 8：五个为什么（可选）

何时运行：反复出现的错误、生产事故、安全问题或"这种情况不断发生"。

修复后，询问"为什么存在这个错误？"以找出系统性原因：

错误：API 返回 NaN

为什么 1：userId 是 null → 代码修复：空值检查
为什么 2：没有输入验证 → 添加验证
为什么 3：没有针对 null 情况的测试 → 添加测试
为什么 4：审查未发现 →（一次性，可接受）

类型	操作
代码	立即修复
测试	添加测试
流程	更新检查清单/审查
系统性	记录模式

跳过如果：简单的一次性错误，影响小，不反复出现。

──────────

仅在以下情况下移除插桩：

修复后日志证明成功
用户确认已解决

搜索 #region debug 并移除所有调试代码。

{"ts":"2024-01-03T12:00:00.000Z","msg":"Button clicked","data":{"id":5},"hypothesisId":"H1","loc":"app.js:42"}

绝不在没有运行时证据的情况下修复 - 始终先收集日志
绝不在验证前移除插桩 - 保持直到修复被确认
绝不猜测 - 如果不确定，添加更多日志
如果所有假设都被拒绝 - 从不同的子系统生成新的假设

问题	解决方案
服务器无法启动	检查端口 8787 未被占用：`lsof -i :8787`
日志为空	检查浏览器阻止（混合内容/CSP/CORS）、防火墙
错误的日志文件	验证 session ID 是否匹配
日志过多	按 hypothesisId 过滤，使用状态变更日志记录
无法复现	向用户询问确切步骤，检查环境

CORS / 混合内容解决方法

如果日志未到达，通常是以下原因之一：

混合内容：HTTPS 应用 → http://localhost:8787 被阻止。使用开发服务器代理（同源）或通过 HTTPS 提供日志端点。
CSP：connect-src 阻止了日志 URL。使用开发服务器代理或更新 CSP。
CORS 预检请求：Content-Type: application/json 触发 OPTIONS。使用"简单"请求（text/plain）或 sendBeacon。

1. sendBeacon（避免预检；发送即忘）：

const DEBUG_LOG_URL = 'http://localhost:8787/log';
const debugLog = (msg, data = {}, hypothesisId = null) => {
  const payload = JSON.stringify({ sessionId: SESSION_ID, msg, data, hypothesisId });
  if (navigator.sendBeacon?.(DEBUG_LOG_URL, payload)) return;
  fetch(DEBUG_LOG_URL, { method: 'POST', body: payload }).catch(() => {});
};

注意：仍然会被混合内容和 CSP 阻止。

2. 开发服务器代理（Vite 示例） - 同源 /__log → http://localhost:8787/log：

// vite.config.js
export default {
  server: {
    proxy: {
      '/__log': {
        target: 'http://localhost:8787',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/__log/, '/log'),
      },
    },
  },
};

// Then POST to /__log instead of localhost:8787/log

3. 最后手段（仅限本地） - 在浏览器设置中允许不安全内容 / 禁用混合内容阻止

内容脚本在具有严格 CSP 的隔离世界中运行 - 它们无法直接获取 localhost:8787。解决方案是通过后台脚本（服务工作者）中继日志。

内容脚本（发送者）：

// #region debug
const DEBUG_SESSION_ID = 'your-session-id-here';

const debugLog = (msg, data = {}, hypothesisId = null) => {
  chrome.runtime.sendMessage({
    type: 'DEBUG_LOG',
    payload: {
      sessionId: DEBUG_SESSION_ID,
      msg,
      data,
      hypothesisId,
      loc: new Error().stack?.split('\n')[2]?.trim(),
    },
  }).catch(() => {});
};
// #endregion

// Usage
debugLog('handleMouseMove', { target: target.tagName, rect }, 'H1');

后台脚本（中继）：

// #region debug - relay logs to debug server
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'DEBUG_LOG') {
    fetch('http://localhost:8787/log', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(message.payload),
    }).catch(() => {});
    sendResponse({ ok: true });
    return true;
  }
});
// #endregion

为什么这可行：

后台脚本（服务工作者）具有宽松的 CSP，可以获取 localhost
chrome.runtime.sendMessage 是内容脚本和后台之间的桥梁
保持两个调试区域都标记以便于清理

注入脚本（主世界）： 如果调试代码通过 <script> 注入到页面上下文中，使用 window.postMessage 中继到内容脚本，然后内容脚本再中继到后台：

// In MAIN world (injected script)
window.postMessage({ type: 'DEBUG_LOG_RELAY', payload: { ... } }, '*');

// In content script
window.addEventListener('message', (e) => {
  if (e.data?.type === 'DEBUG_LOG_RELAY') {
    chrome.runtime.sendMessage({ type: 'DEBUG_LOG', payload: e.data.payload });
  }
});

服务器正在运行（已启动或已在运行）
通过 POST /session 创建会话 - 保存返回的 session_id
生成了 3-5 个假设
添加了 3-8 个日志，用 hypothesisId 标记
复现前清除了日志
提供了复现步骤
评估了每个假设（已确认/已拒绝/不确定）
仅基于证据进行修复
完成了修复前/后比较
确认后移除了插桩

🇺🇸English

Debug Mode

Fix bugs with runtime evidence , not guesses.

Don't guess → Hypothesize → Instrument → Reproduce → Analyze → Fix → Verify

When to Use

Trigger signals (if you're about to do any of these, use this skill instead):

"Open DevTools Console and check for..."
"Reproduce the bug and tell me what you see"
"Add console.log and let me know the output"
"Click X, open Y, check if Z appears in console"

Example scenario that should trigger this skill:

❌ Without skill (manual, slow):
"I added debug logging. Please:
1. Open the app in browser
2. Open DevTools Console (F12)
3. Open the defect modal and select a defect
4. Check console for [DEBUG] logs
5. Tell me what you see"

✅ With skill (automated):
Logs are captured server-side → you read them directly → no user copy-paste needed

Use when debugging:

State/value issues (null, undefined, wrong type)
Conditional logic (which branch was taken)
Async timing (race conditions, load order)
User interaction flows (modals, forms, clicks)

Arguments

/debug /path/to/project

If no path provided, use current working directory.

Workflow

Phase 1: Start Log Server

Step 1: Ensure server is running (starts if needed, no-op if already running):

node skills/debug/scripts/debug_server.js /path/to/project &

Server outputs JSON:

{"status":"started",...} - new server started
{"status":"already_running",...} - server was already running (this is fine!)

Step 2: Create session (server generates unique ID from your description):

curl -s -X POST http://localhost:8787/session -d '{"name":"fix-null-userid"}'

Response:

{"session_id":"fix-null-userid-a1b2c3","log_file":"/path/to/project/.debug/debug-fix-null-userid-a1b2c3.log"}

Save thesession_id from the response - use it in all subsequent steps.

Server endpoints:

POST /session with {"name": "description"} → creates session, returns {session_id, log_file}
POST /log with {"sessionId": "...", "msg": "..."} → writes to log file
GET / → returns status and log directory

If port 8787 busy: lsof -ti :8787 | xargs kill -9 then restart

──────────

Phase 2: Generate Hypotheses

Before instrumenting , generate 3-5 specific hypotheses:

Hypothesis H1: userId is null when passed to calculateScore()
  Expected: number (e.g., 5)
  Actual: null
  Test: Log userId at function entry

Hypothesis H2: score is string instead of number
  Expected: 85 (number)
  Actual: "85" (string)
  Test: Log typeof score

Each hypothesis must be:

Specific (not "something is wrong")
Testable (can confirm/reject with logs)
Cover different subsystems (don't cluster)

──────────

Phase 3: Instrument Code

Add logging calls to test all hypotheses.

JavaScript/TypeScript:

// #region debug
const SESSION_ID = 'REPLACE_WITH_SESSION_ID'; // e.g. 'fix-null-userid-a1b2c3'
const DEBUG_LOG_URL = 'http://localhost:8787/log';

const debugLog = (msg, data = {}, hypothesisId = null) => {
  const payload = JSON.stringify({
    sessionId: SESSION_ID,
    msg,
    data,
    hypothesisId,
    loc: new Error().stack?.split('\n')[2],
  });

  if (navigator.sendBeacon?.(DEBUG_LOG_URL, payload)) return;
  fetch(DEBUG_LOG_URL, { method: 'POST', body: payload }).catch(() => {});
};
// #endregion

// Usage
debugLog('Function entry', { userId, score, typeScore: typeof score }, 'H1,H2');

Python:

# #region debug
import requests, traceback
SESSION_ID = 'REPLACE_WITH_SESSION_ID'  # e.g. 'fix-null-userid-a1b2c3'
def debug_log(msg, data=None, hypothesis_id=None):
    try:
        requests.post('http://localhost:8787/log', json={
            'sessionId': SESSION_ID, 'msg': msg, 'data': data,
            'hypothesisId': hypothesis_id, 'loc': traceback.format_stack()[-2].strip()
        }, timeout=0.5)
    except: pass
# #endregion

# Usage
debug_log('Function entry', {'user_id': user_id, 'type': type(user_id)}, 'H1')

Guidelines:

3-8 instrumentation points
Cover: entry/exit, before/after critical ops, branch paths
Tag each log with hypothesisId
Wrap in // #region debug ... // #endregion
High-frequency events (mousemove, scroll): log only on state change
Log both intent and result

──────────

Phase 4: Clear and Reproduce

Clear logs:

: > /path/to/project/.debug/debug-$SESSION_ID.log

Provide reproduction steps:

<reproduction_steps>
1. Start app: yarn dev
2. Navigate to /users
3. Click "Calculate Score"
4. Observe NaN displayed
</reproduction_steps>

User reproduces bug

──────────

Phase 5: Analyze Logs

Read and evaluate:

cat /path/to/project/.debug/debug-$SESSION_ID.log

For each hypothesis:

Hypothesis H1: userId is null
  Status: CONFIRMED
  Evidence: {"msg":"Function entry","data":{"userId":null}}

Hypothesis H2: score is string
  Status: REJECTED
  Evidence: {"data":{"typeScore":"number"}}

Status options:

CONFIRMED : Logs prove it
REJECTED : Logs disprove it
INCONCLUSIVE : Need more instrumentation

If all INCONCLUSIVE/REJECTED : Generate new hypotheses, add more logs, iterate.

──────────

Phase 6: Fix

Only fix when logs confirm root cause.

Keep instrumentation active (don't remove yet).

Tag verification logs with runId: "post-fix":

debugLog('Function entry', { userId, runId: 'post-fix' }, 'H1');

──────────

Phase 7: Verify

Clear logs
User reproduces (bug should be gone)

Compare before/after:

Before: {"data":{"userId":null},"runId":"run1"}
After:  {"data":{"userId":5},"runId":"post-fix"}

Confirm with log evidence

If still broken : New hypotheses, more logs, iterate.

──────────

Phase 8: Five Whys (Optional)

When to run: Recurring bug, prod incident, security issue, or "this keeps happening".

After fixing, ask "Why did this bug exist?" to find systemic causes:

Bug: API returns NaN

Why 1: userId was null → Code fix: null check
Why 2: No input validation → Add validation
Why 3: No test for null case → Add test
Why 4: Review didn't catch → (one-off, acceptable)

Categories:

Type	Action
CODE	Fix immediately
TEST	Add test
PROCESS	Update checklist/review
SYSTEMIC	Document patterns

Skip if: Simple one-off bug, low impact, not recurring.

──────────

Phase 9: Clean Up

Remove instrumentation only after:

Post-fix logs prove success
User confirms resolved

Search for #region debug and remove all debug code.

Log Format

Each line is NDJSON:

{"ts":"2024-01-03T12:00:00.000Z","msg":"Button clicked","data":{"id":5},"hypothesisId":"H1","loc":"app.js:42"}

Critical Rules

NEVER fix without runtime evidence - Always collect logs first
NEVER remove instrumentation before verification - Keep until fix confirmed
NEVER guess - If unsure, add more logs
If all hypotheses rejected - Generate new ones from different subsystems

Troubleshooting

Issue	Solution
Server won't start	Check port 8787 not in use: `lsof -i :8787`
Logs empty	Check browser blocks (mixed content/CSP/CORS), firewall
Wrong log file	Verify session ID matches
Too many logs	Filter by hypothesisId, use state-change logging
Can't reproduce	Ask user for exact steps, check environment

CORS / Mixed Content Workarounds

If logs aren't arriving, it’s usually one of:

Mixed content : HTTPS app → http://localhost:8787 is blocked. Use a dev-server proxy (same origin) or serve the log endpoint over HTTPS.
CSP : connect-src blocks the log URL. Use a dev-server proxy or update CSP.
CORS preflight : Content-Type: application/json triggers OPTIONS. Use a “simple” request (text/plain) or sendBeacon.

1.sendBeacon (avoids preflight; fire-and-forget):

const DEBUG_LOG_URL = 'http://localhost:8787/log';
const debugLog = (msg, data = {}, hypothesisId = null) => {
  const payload = JSON.stringify({ sessionId: SESSION_ID, msg, data, hypothesisId });
  if (navigator.sendBeacon?.(DEBUG_LOG_URL, payload)) return;
  fetch(DEBUG_LOG_URL, { method: 'POST', body: payload }).catch(() => {});
};

Note: still blocked by mixed content + CSP.

2. Dev server proxy (Vite example) - same-origin /__log → http://localhost:8787/log:

// vite.config.js
export default {
  server: {
    proxy: {
      '/__log': {
        target: 'http://localhost:8787',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/__log/, '/log'),
      },
    },
  },
};

// Then POST to /__log instead of localhost:8787/log

3. Last resort (local only) - allow insecure content / disable mixed-content blocking in browser settings

Chrome Extension Debugging

Content scripts run in an isolated world with strict CSP - they cannot directly fetch to localhost:8787. The solution is to relay logs through the background script (service worker).

Content Script (sender):

// #region debug
const DEBUG_SESSION_ID = 'your-session-id-here';

const debugLog = (msg, data = {}, hypothesisId = null) => {
  chrome.runtime.sendMessage({
    type: 'DEBUG_LOG',
    payload: {
      sessionId: DEBUG_SESSION_ID,
      msg,
      data,
      hypothesisId,
      loc: new Error().stack?.split('\n')[2]?.trim(),
    },
  }).catch(() => {});
};
// #endregion

// Usage
debugLog('handleMouseMove', { target: target.tagName, rect }, 'H1');

Background Script (relay):

// #region debug - relay logs to debug server
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'DEBUG_LOG') {
    fetch('http://localhost:8787/log', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(message.payload),
    }).catch(() => {});
    sendResponse({ ok: true });
    return true;
  }
});
// #endregion

Why this works:

Background scripts (service workers) have relaxed CSP and can fetch to localhost
chrome.runtime.sendMessage is the bridge between content script and background
Keep both debug regions tagged for easy cleanup

Injected scripts (MAIN world): If debugging code injected via <script> into the page context, use window.postMessage to relay to content script, which then relays to background:

// In MAIN world (injected script)
window.postMessage({ type: 'DEBUG_LOG_RELAY', payload: { ... } }, '*');

// In content script
window.addEventListener('message', (e) => {
  if (e.data?.type === 'DEBUG_LOG_RELAY') {
    chrome.runtime.sendMessage({ type: 'DEBUG_LOG', payload: e.data.payload });
  }
});

Checklist

Server running (started or already_running)
Session created via POST /session - save the returned session_id
3-5 hypotheses generated
3-8 logs added, tagged with hypothesisId
Logs cleared before reproduction
Reproduction steps provided
Each hypothesis evaluated (CONFIRMED/REJECTED/INCONCLUSIVE)
Fix based on evidence only
Before/after comparison done
Instrumentation removed after confirmation

Weekly Installs

108

Repository

vltansky/debug-skill

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

opencode99

codex96

gemini-cli94

cursor94

github-copilot92

amp89

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

159,700 周安装

debug 调试技能：基于运行时证据自动化修复代码错误，提升开发效率

🇨🇳中文介绍

调试模式

何时使用

参数

工作流程

阶段 1：启动日志服务器

相关 Skills

阶段 2：生成假设

阶段 3：插桩代码

阶段 4：清除日志并复现

阶段 5：分析日志

阶段 6：修复

阶段 7：验证

阶段 8：五个为什么（可选）

阶段 9：清理

日志格式

关键规则

故障排除

CORS / 混合内容解决方法

Chrome 扩展调试

检查清单

🇺🇸English

Debug Mode

When to Use

Arguments

Workflow

Phase 1: Start Log Server

Phase 2: Generate Hypotheses

Phase 3: Instrument Code

Phase 4: Clear and Reproduce

Phase 5: Analyze Logs

Phase 6: Fix

Phase 7: Verify

Phase 8: Five Whys (Optional)

Phase 9: Clean Up

Log Format

Critical Rules

Troubleshooting

CORS / Mixed Content Workarounds

Chrome Extension Debugging

Checklist

最新 Skills