出海助手-Node调试 / Node Inspect Debugger

> 本技能改造自开源技能 node-inspect-debugger（来源：openclaw/openclaw，openclaw 开源技能生态）。已完整保留原始运行文件（scripts/references/assets 与 LICENSE），并新增中文出海使用说明。原始英文说明见文末「English (Original)」与同目录 SKILL.original.md。

功能说明 / Functional Overview

用 Node.js inspector 调试运行中的进程，设置断点、查看变量与调用栈。

适用场景 / Use Cases

• 线上 Node 进程排错
• 断点调试复杂逻辑
• 内存/性能问题定位

使用方法 / How to Use

1. 按原技能说明启动 inspector，技能会引导你打断点与检查状态。

示例 / Examples

• 「线上 Node 进程排错」——用自然语言把任务交给本技能即可。

限制说明 / Limitations

• 需要外部服务/凭证的技能，请先完成授权配置后使用。
• 本技能为开源技能的中文本地化版本，核心逻辑与原技能一致；如遇专业术语，正文保留英文原词（如 Shopify、SEO、GA4 等）。

English (Original) / 英文原文（完整保留）

> The section below is the original skill definition, preserved verbatim for traceability and full functionality.

Node Inspect Debugger

Use for Node.js debugging that needs inspector access: hidden locals, async hangs, flaky tests, child processes, startup races, memory growth, or CPU hot paths.

Default to node inspect first. Use Chrome DevTools Protocol only when you need scripted breakpoints, automated state capture, heap snapshots, or CPU profiles.

Quick start

• Pause on entry: node inspect path/to/script.js
• TypeScript: node --inspect-brk --import tsx path/to/script.ts
• Existing PID: kill -SIGUSR1 <pid> then node inspect -p <pid>
• Inspect target list: curl -s http://127.0.0.1:9229/json/list | jq
• OpenClaw CLI path: node --inspect-brk openclaw.mjs ...
• OpenClaw test path: OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

Debugger REPL

• Continue/step: cont, next, step, out, pause
• Breakpoints: sb('file.js', 42), sb(42), sb('functionName'), breakpoints, cb('file.js', 42)
• Inspect: bt, list(8), watch('expr'), exec expr
• Current scope: repl, then evaluate locals directly; Ctrl+C exits repl mode.
• Exit safely: cont before quitting if the process should continue; otherwise kill.

OpenClaw tips

• Prefer 127.0.0.1 inspector binds. Do not expose --inspect=0.0.0.0 unless the network is isolated.
• For Vitest, debug one file with one worker. Avoid worker pools while stepping.
• For TS source breakpoints, use --enable-source-maps when useful; node inspect can still show emitted paths.
• For child processes, NODE_OPTIONS=--inspect-brk can propagate the inspector, but each child needs its own port.
• For long-lived gateway or dev processes, attach by PID after confirming the target with /json/list.

Programmatic CDP

Install tooling outside the repo unless the project already depends on it:

mkdir -p /tmp/cdp-tools
npm --prefix /tmp/cdp-tools i chrome-remote-interface
NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs

Minimal driver:

const CDP = require("chrome-remote-interface");

(async () => {
  const client = await CDP({ port: 9229 });
  const { Debugger, Runtime } = client;

  Debugger.paused(async ({ callFrames, reason }) => {
    const top = callFrames[0];
    console.log("paused", reason, top.url, top.location.lineNumber + 1);
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: "JSON.stringify({ pid: process.pid })",
    });
    console.log(result.value ?? result.description);
    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();
  await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 });
  await Runtime.runIfWaitingForDebugger();
})();

Profiles

• CPU: enable Profiler, start, wait, stop, write /tmp/profile.cpuprofile, open in Chrome DevTools.
• Heap: enable HeapProfiler, collect addHeapSnapshotChunk, call takeHeapSnapshot, write /tmp/heap.heapsnapshot.

Pitfalls

• --inspect does not pause; use --inspect-brk when setup must happen before code runs.
• Default port is 9229; use --inspect=0 or a unique port for parallel targets.
• If a breakpoint misses, confirm file path, source map behavior, and whether execution already passed the line.
• If the process appears frozen after detaching, it may still be paused in the debugger.