melech-debug-mode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Mode

调试模式

Treat the current task as an active debugging session. Diagnose from runtime evidence before proposing a fix.

For the intended first-use, reproduction, iteration, verification, and later-use experience, read DEVELOPER_JOURNEY_EXAMPLE.md and use it as the interaction model. For autopilot attach, read LIVE_BROWSER.md when that mode starts. Chrome setup is the official M144 auto-connect flow in CHROME_DEVTOOLS_MCP.md.

将当前任务视为一个活跃的调试会话。在提出修复方案前，先从运行时证据入手进行诊断。

关于首次使用、复现、迭代、验证及后续使用流程，请阅读DEVELOPER_JOURNEY_EXAMPLE.md并将其作为交互模型参考。若使用自动驾驶模式，请在模式启动时阅读LIVE_BROWSER.md。Chrome配置遵循CHROME_DEVTOOLS_MCP.md中官方的M144自动连接流程。

Guardrails

防护规则

Keep the collector local. Do not enable Portless
```
--tailscale
```
,
```
--funnel
```
,
```
--ngrok
```
, LAN mode, or any other remote exposure.
Never collect credentials, tokens, cookies, authorization headers, personal data, full request bodies, or unrelated application state. Prefer booleans, counts, IDs already safe for development, enum values, and narrow summaries.
Add the fewest probes that distinguish the current hypotheses. Start with at most five unless the control flow genuinely requires more.
Make probes non-blocking and failure-isolated so collector failure cannot alter product behavior.
Mark every temporary edit with
```
DEBUG_MODE:<session-id>:<probe-id>
```
and keep a list of touched files for cleanup.
Do not fix the bug before the evidence identifies a cause, unless the user explicitly asks to skip diagnosis.
Stop only this session. Never run
```
portless proxy stop
```
,
```
portless clean
```
, or broad process-kill commands.
When driving Chrome, attach only. Never
```
state save
```
cookies or tokens, never collect credentials from the page, never quit the user's Chrome, and never close tabs you did not open. Do not tunnel CDP through Portless or any remote exposure.

保持采集器本地运行。请勿启用Portless的
```
--tailscale
```
、
```
--funnel
```
、
```
--ngrok
```
参数、LAN模式或任何其他远程暴露方式。
绝不收集凭证、令牌、Cookie、授权头、个人数据、完整请求体或无关的应用状态。优先使用布尔值、计数、已确保安全的开发环境ID、枚举值和精简摘要。
仅添加能验证当前假设的最少探针。除非控制流确实需要，否则初始最多添加5个探针。
确保探针是非阻塞且故障隔离的，避免采集器故障影响产品行为。
所有临时编辑都标记为
```
DEBUG_MODE:<session-id>:<probe-id>
```
，并记录所有修改过的文件以便后续清理。
在证据明确根因前，请勿修复bug，除非用户明确要求跳过诊断步骤。
仅停止当前会话。绝不要执行
```
portless proxy stop
```
、
```
portless clean
```
或大范围进程终止命令。
操控Chrome时仅进行附加操作。绝不使用
```
state save
```
保存Cookie或令牌，绝不从页面收集凭证，绝不关闭用户的Chrome，绝不关闭非你打开的标签页。请勿通过Portless或任何远程暴露方式隧道传输CDP。

Start A Session

启动会话

Inspect the failing path, current logs, and relevant tests. State one to three concrete hypotheses and what observation would distinguish them.
Locate this installed skill directory and confirm both
```
python3
```
and
```
portless
```
are available. If Portless is missing, stop and tell the user to install the official Vercel Labs CLI with
```
npm install -g portless
```
. Do not silently substitute another tunnel or server.
Source the bundled command once so the short
```
dm
```
verb is available for the rest of this session (the shell keeps it across later calls):
bash
```
source <skill-dir>/scripts/dm.sh
```
Every launcher call below uses
```
dm
```
, which is identical to
```
python3 <skill-dir>/scripts/debug_session.py
```
. If
```
dm
```
is ever undefined in a later step (fresh shell), re-source
```
dm.sh
```
or fall back to the full path.
If this machine has not used Portless before, run
```
portless doctor
```
. Follow its local trust/setup guidance before starting the background session.
Start the bundled collector:
bash
```
dm start
```
Save the returned
```
session_dir
```
,
```
session_id
```
,
```
log_endpoint
```
,
```
events_file
```
, and
```
backend_port
```
. The launcher copies the lean server skeleton into a new temporary directory. Portless assigns a different free backend port and a unique local route for every session.
Verify the returned
```
health_url
```
before editing application code.

检查失败路径、当前日志及相关测试。提出1-3个具体假设，以及能验证这些假设的观测结果。
找到已安装的skill目录，确认
```
python3
```
和
```
portless
```
可用。若缺少Portless，请停止操作并告知用户通过
```
npm install -g portless
```
安装官方Vercel Labs CLI。请勿静默替换为其他隧道或服务器。
一次性加载捆绑命令，以便在后续会话中使用简短的
```
dm
```
命令（shell会在后续调用中保留该命令）：
bash
```
source <skill-dir>/scripts/dm.sh
```
以下所有启动器调用均使用
```
dm
```
，其功能与
```
python3 <skill-dir>/scripts/debug_session.py
```
完全一致。若后续步骤中
```
dm
```
未定义（如新开shell），请重新加载
```
dm.sh
```
或使用完整路径调用。
若该机器从未使用过Portless，请运行
```
portless doctor
```
。遵循其本地信任/设置指引后再启动后台会话。
启动捆绑的采集器：
bash
```
dm start
```
保存返回的
```
session_dir
```
、
```
session_id
```
、
```
log_endpoint
```
、
```
events_file
```
和
```
backend_port
```
。启动器会将精简的服务器框架复制到新的临时目录。Portless会为每个会话分配不同的空闲后端端口和唯一的本地路由。
在修改应用代码前，验证返回的
```
health_url
```
是否可用。

Add Dynamic Request Probes

添加动态请求探针

Place probes only where they can confirm or eliminate a hypothesis: branch entries, values immediately before a transformation, boundary inputs/outputs, and error paths. Give each a stable descriptive ID.

POST a small JSON object to the session's

log_endpoint

json

{
  "run": "run-1",
  "probe": "checkout-before-submit",
  "hypothesis": "disabled state is stale",
  "data": {
    "isDisabled": true,
    "itemCount": 2
  }
}

For browser JavaScript, use a fire-and-forget request and swallow collector errors locally:

// DEBUG_MODE:<session-id>:checkout-before-submit
void fetch("<log-endpoint>", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    run: "run-1",
    probe: "checkout-before-submit",
    hypothesis: "disabled state is stale",
    data: { isDisabled, itemCount: items.length },
  }),
}).catch(() => {});

Adapt the request idiom to the target language. Preserve the same payload shape, marker, narrow data selection, and failure isolation. Do not log whole objects when a few fields answer the question.

Run the cheapest compile, type, or syntax check needed to ensure the temporary instrumentation itself did not break the workflow.

仅在能确认或排除假设的位置放置探针：分支入口、转换前的数值、边界输入/输出及错误路径。为每个探针分配一个稳定的描述性ID。

向会话的

log_endpoint

发送一个小型JSON对象：

json

{
  "run": "run-1",
  "probe": "checkout-before-submit",
  "hypothesis": "disabled state is stale",
  "data": {
    "isDisabled": true,
    "itemCount": 2
  }
}

对于浏览器JavaScript，使用即发即弃请求并在本地捕获采集器错误：

// DEBUG_MODE:<session-id>:checkout-before-submit
void fetch("<log-endpoint>", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    run: "run-1",
    probe: "checkout-before-submit",
    hypothesis: "disabled state is stale",
    data: { isDisabled, itemCount: items.length },
  }),
}).catch(() => {});

根据目标语言调整请求方式。保留相同的负载结构、标记、精简数据选择和故障隔离机制。仅在少数字段能回答问题时，才记录完整对象。

执行最低成本的编译、类型检查或语法检查，确保临时 instrumentation 本身不会破坏工作流程。

Pick A Reproduction Mode

选择复现模式

Same collector and probes either way. Only who drives the repro changes.

Manual — the user holds the wheel. You instrument, tell them the exact clicks, then stop until they reply
```
proceed
```
.
Autopilot — you drive their already-open Chrome end-to-end with Chrome DevTools MCP
```
--autoConnect
```
(same tabs, same logins). They only enable remote debugging and click Allow. If this host is missing that MCP, you write the official config with
```
dm mcp-setup
```
and wait for a reload so the host can start the server.

Choose once, then announce it in the user-facing message:

User said they will reproduce, hold the wheel, or reply
```
proceed
```
→ manual.
User said autopilot, drive my browser, already logged in, or do it for me → autopilot.
UI bug and they did not pick → announce both modes in one short message and wait. Do not attach and do not hand them a
```
proceed
```
script until they answer.
Not a UI bug, or the tab looks like production you should not touch → manual.

Never silently attach. Before any Chrome DevTools MCP call, tell the user they are in autopilot and what they must do in Chrome.

无论选择哪种模式，采集器和探针保持不变，仅复现的操控者不同。

手动模式 — 用户操控。你负责 instrumentation，告知用户具体的点击操作，然后等待用户回复
```
proceed
```
后再继续。
自动驾驶模式 — 你通过Chrome DevTools MCP
```
--autoConnect
```
功能全程操控用户已打开的Chrome（保留相同标签页和登录状态）。用户仅需启用远程调试并点击“允许”。若当前主机缺少该MCP，你可通过
```
dm mcp-setup
```
写入官方配置，等待重载后主机即可启动服务器。

选择模式后，在面向用户的消息中明确告知：

用户表示将自行复现、操控或回复
```
proceed
```
→ 手动模式。
用户要求自动驾驶、操控浏览器、已登录或代其操作 → 自动驾驶模式。
UI bug且用户未选择模式 → 在一条简短消息中说明两种模式并等待回复。在用户答复前，请勿附加会话或提供
```
proceed
```
脚本。
非UI bug，或标签页为生产环境不应触碰 → 手动模式。

绝不要静默附加会话。在执行任何Chrome DevTools MCP调用前，告知用户当前处于自动驾驶模式及他们需在Chrome中执行的操作。

Autopilot

自动驾驶模式

Keep probes in place. Snapshots are extra evidence, not a substitute for

dm logs

. Read LIVE_BROWSER.md and CHROME_DEVTOOLS_MCP.md.

Check whether Chrome DevTools MCP tools are already available in this session. Then run the bundled setup (idempotent):
bash
```
dm mcp-setup
```
That inspects known host MCP configs, writes the official
```
chrome-devtools-mcp@latest --autoConnect
```
entry when it is missing, and prefetches the npm package. It does not inject tools into a live host; the host still has to spawn the server.
- Tools already present and
```
ready: true
```
  → continue.
- ```
reload_required: true
```
  → tell the user to reload the
```
chrome-devtools
```
  MCP server (or restart the host), then wait. Do not attach to a profile that is missing
```
--autoConnect
```
  .
- ```
ready: false
```
  → show the official snippet from the command output and switch to Manual unless they want the
```
dm browser-check
```
  fallback.
Do not silently switch to Playwright, Puppeteer, a fresh empty Chrome, a cloud browser, or a custom extension.
Before the first MCP call, tell the user verbatim:

Autopilot is on. I will drive the tab you already have open.
One-time: open chrome://inspect/#remote-debugging and enable Allow remote debugging for this browser instance (Chrome 144+).
When Chrome prompts, click Allow. A “controlled by automated test software” banner is expected. I will not quit Chrome or close other tabs.

Then wait only if they have not confirmed they can click Allow. If they already said to go, list pages and keep those steps visible.
Discover pages through Chrome DevTools MCP. Select the existing app tab. Do not open a new URL unless the repro needs a fresh navigation. Do not close Chrome or other tabs. Do not close the last tab.
Snapshot, then drive the workflow with click / fill / type on snapshot uids. If they already selected a node in the Elements panel or a request in the Network panel, start there.
If attach fails, print the inspect-page + Allow steps and switch to Manual. Use
```
dm browser-check
```
only when this host has no Chrome DevTools MCP at all.
After one reproduction attempt, read
```
dm logs
```
the same as on
```
proceed
```
. Do not claim a reproduction from a snapshot alone.

保留探针位置。快照是额外证据，不能替代

dm logs

。请阅读LIVE_BROWSER.md和CHROME_DEVTOOLS_MCP.md。

检查当前会话是否已具备Chrome DevTools MCP工具。然后运行捆绑的设置脚本（幂等操作）：
bash
```
dm mcp-setup
```
该脚本会检查已知的主机MCP配置，若缺少则写入官方的
```
chrome-devtools-mcp@latest --autoConnect
```
配置项，并预取npm包。它不会向活跃主机注入工具；主机仍需自行启动服务器。
- 工具已存在且
```
ready: true
```
  → 继续。
- ```
reload_required: true
```
  → 告知用户重载
```
chrome-devtools
```
  MCP服务器（或重启主机），然后等待。请勿附加到缺少
```
--autoConnect
```
  配置的配置文件。
- ```
ready: false
```
  → 显示命令输出中的官方代码片段，除非用户希望使用
```
dm browser-check
```
  降级方案，否则切换到手动模式。
绝不要静默切换到Playwright、Puppeteer、全新空白Chrome、云端浏览器或自定义扩展。
在首次MCP调用前，逐字告知用户：

自动驾驶模式已开启。我将操控你已打开的标签页。
一次性操作：打开chrome://inspect/#remote-debugging，为当前浏览器实例启用“允许远程调试”（Chrome 144+）。
当Chrome弹出提示时，点击“允许”。出现“由自动化测试软件控制”的横幅属于正常现象。我不会关闭Chrome或其他标签页。

若用户未确认可点击“允许”，则等待回复。若用户已同意执行，则列出步骤并保持可见。
通过Chrome DevTools MCP发现页面。选择已存在的应用标签页。除非复现需要全新导航，否则不要打开新URL。不要关闭Chrome或其他标签页，不要关闭最后一个标签页。
拍摄快照，然后通过快照UID执行点击/填充/输入操作来驱动工作流程。若用户已在Elements面板选择节点或在Network面板选择请求，则从该位置开始。
若附加失败，打印检查页面+允许步骤并切换到手动模式。仅当主机完全没有Chrome DevTools MCP时，才使用
```
dm browser-check
```
。
完成一次复现尝试后，读取
```
dm logs
```
，与等待
```
proceed
```
时的操作一致。不要仅通过快照就声称已复现bug。

Manual

手动模式

Use this path when the user holds the wheel, autopilot is unavailable or denied, or you should not touch the open tabs. Tell the user:

Debug mode is active in manual. They hold the wheel.
The exact workflow to perform, including any reset or starting state.
Which visible outcome identifies the bug.
To reply exactly
```
proceed
```
after one reproduction attempt.

Then stop. Do not poll the event file or claim a reproduction before the user replies.

当用户操控、自动驾驶模式不可用或被拒绝，或不应触碰已打开的标签页时，使用此模式。告知用户：

调试模式已激活，当前为手动模式，由用户操控。
需执行的具体工作流程，包括任何重置或初始状态。
能识别bug的可见结果。
完成一次复现尝试后，准确回复
```
proceed
```
。

然后停止操作。在用户回复前，不要轮询事件文件或声称已复现bug。

Inspect On

proceed

收到

proceed

后检查

After an autopilot reproduction, use this same command and the same outcomes without waiting for

proceed

Read the evidence with:

bash

dm logs <session-dir> --run run-1

Correlate event order and values against the stated hypotheses, then choose one outcome:

Reproduced and conclusive: explain the observed causal chain, implement the smallest root-cause fix, and verify it. Keep probes only if one user rerun is still needed to validate the fix.
Reproduced but inconclusive: say what the evidence ruled out, revise the hypothesis, add or move only the probes needed for
```
run-2
```
, and ask for the precise workflow again.
No application events: check session status (
```
dm status <session-dir>
```
) and send one synthetic event to distinguish collector delivery failure from an unvisited code path. Check browser CSP/CORS or environment reachability when relevant, then repair the instrumentation and retry.
Workflow did not reproduce: record that result, adjust the starting state or probe placement, increment the run ID, and retry without pretending the bug was observed.

Do not equate correlation with cause. Cite the specific probe sequence and values that support the next action.

自动驾驶模式完成复现后，使用相同命令和结果，无需等待

proceed

。

通过以下命令读取证据：

bash

dm logs <session-dir> --run run-1

将事件顺序和数值与提出的假设关联，然后选择以下结果之一：

已复现且结论明确：解释观察到的因果链，实现最小化的根因修复并验证。仅当需要用户再次运行以验证修复时，才保留探针。
已复现但结论不明确：说明证据排除的假设，修订假设，仅添加或移动
```
run-2
```
所需的探针，并再次询问具体工作流程。
无应用事件：检查会话状态（
```
dm status <session-dir>
```
）并发送一个合成事件，以区分采集器交付失败与未访问的代码路径。若相关，检查浏览器CSP/CORS或环境可达性，然后修复 instrumentation 并重试。
工作流程未复现bug：记录结果，调整初始状态或探针位置，递增运行ID，并重试，不要假装已观察到bug。

不要将相关性等同于因果关系。引用支持下一步操作的具体探针序列和数值。

Doctor: Monitor Live Sessions

诊断工具：监控活跃会话

To inspect every debug-mode collector on the machine at once, run the live TUI:

bash

dm doctor    # or bare `dm`

It scans the temp root for all

debug-mode-*

sessions and shows, per session, a health status derived from the process state plus the collector's

/health

endpoint:

running (green): launcher and collector processes are alive and
```
/health
```
returns 200.
degraded (yellow): processes are alive but
```
/health
```
is unreachable or non-200 (hung or wedged port).
```
starting
```
means the collector metadata has not been written yet.
dead (red): the launcher or collector process is gone.

The detail pane live-tails the selected session's

events.jsonl

, auto-scrolling to the newest event, shows the live entry count, and surfaces the last error line from

runtime.log

when the collector crashed or is throwing.

Keys:

↑

↓

to move,

to kill the selected session (stops its processes and deletes its temp directory, same as

stop

; asks

first),

to force a refresh,

to quit. Killing only ever targets a validated

debug-mode-*

session directory; it never issues a broad process kill.

For scripting or when no TTY is available, use

dm doctor --once

to print a one-shot JSON snapshot of all sessions instead of launching the TUI.

要一次性检查机器上所有调试模式采集器，运行实时TUI：

bash

dm doctor    # 或直接运行 `dm`

debug-mode-*

会话，并根据进程状态和采集器的

/health

端点显示每个会话的健康状态：

运行中（绿色）：启动器和采集器进程均存活，且
```
/health
```
返回200。
降级（黄色）：进程存活但
```
/health
```
不可达或返回非200状态（端口挂起或阻塞）。
```
starting
```
表示采集器元数据尚未写入。
已终止（红色）：启动器或采集器进程已消失。

详情面板会实时跟踪所选会话的

events.jsonl

，自动滚动到最新事件，显示实时事件计数，并在采集器崩溃或抛出错误时显示

runtime.log

中的最后一条错误信息。

快捷键：

↑

↓

或

移动，

终止所选会话（停止其进程并删除临时目录，与

stop

功能相同；会先询问

确认），

强制刷新，

退出。终止操作仅针对已验证的

debug-mode-*

会话目录；绝不会执行大范围进程终止命令。

若需脚本化执行或无TTY可用，使用

dm doctor --once

打印所有会话的一次性JSON快照，而非启动TUI。

Installing

dm

persistently for the user

为用户持久化安装

dm

The skill sources

dm.sh

for its own session, but the user gets

dm

in their own terminals only after a one-time install. Offer it once per machine:

bash

sh <skill-dir>/scripts/install-dm.sh

This appends a single

source <skill-dir>/scripts/dm.sh

line to the user's shell rc (

~/.zshrc

~/.bashrc

, auto-detected; pass a path to override) and is idempotent. After reloading the shell:

```
dm
```
— open the doctor TUI
```
dm help
```
— list every command

dm start

dm status <dir>

dm logs <dir>

dm stop <dir>

dm mcp-setup

dm browser-check

— launcher subcommands

dm.sh

resolves its own location, so it keeps working wherever the skill is installed. Users who prefer not to touch their rc can call

python3 <skill-dir>/scripts/debug_session.py doctor

directly.

skill会在自身会话中加载

dm.sh

，但用户需执行一次性安装才能在自己的终端中使用

dm

。每台机器仅需提供一次安装命令：

bash

sh <skill-dir>/scripts/install-dm.sh

该脚本会在用户的shell配置文件（自动检测

~/.zshrc

或

~/.bashrc

；可传入路径覆盖）中添加一行

source <skill-dir>/scripts/dm.sh

，且操作是幂等的。重载shell后：

```
dm
```
— 打开诊断工具TUI
```
dm help
```
— 列出所有命令

dm start

dm status <dir>

dm logs <dir>

dm stop <dir>

dm mcp-setup

dm browser-check

— 启动器子命令

dm.sh

会自动解析自身位置，因此无论skill安装在何处，它都能正常工作。若用户不想修改配置文件，可直接调用

python3 <skill-dir>/scripts/debug_session.py doctor

。

Finish Or Abort

结束或中止会话

Whether the bug is fixed, the user stops, or the session fails:

Remove every
```
DEBUG_MODE:<session-id>:
```
probe and any debug-only imports, helpers, configuration, or CSP changes. Preserve the actual fix and useful regression tests.
Search the touched files for
```
DEBUG_MODE:
```
and inspect the diff to confirm no temporary instrumentation remains.
Stop issuing Chrome DevTools MCP commands. Do not close tabs you did not open, quit Chrome, or close the last tab. Remind them they can disable remote debugging at
```
chrome://inspect/#remote-debugging
```
if they no longer want local processes to attach.
Tear down only this collector and delete its temporary directory:
bash
```
dm stop <session-dir>
```
Confirm the command reports
```
removed: true
```
. If teardown fails, report the exact session directory and PID instead of using a broad kill command.

If context is interrupted, recover from the saved

session_dir

; re-source

dm.sh

if needed, then use

dm status

dm logs

, and

dm stop

, or run

dm doctor

to see and manage every live session at once.

无论bug已修复、用户停止操作或会话失败：

删除所有标记为
```
DEBUG_MODE:<session-id>:
```
的探针，以及任何仅用于调试的导入、辅助工具、配置或CSP修改。保留实际修复和有用的回归测试。
在修改过的文件中搜索
```
DEBUG_MODE:
```
，检查差异以确认无临时 instrumentation 残留。
停止执行Chrome DevTools MCP命令。不要关闭非你打开的标签页，不要退出Chrome，不要关闭最后一个标签页。提醒用户若不再希望本地进程附加，可在
```
chrome://inspect/#remote-debugging
```
中禁用远程调试。
仅终止当前采集器并删除其临时目录：
bash
```
dm stop <session-dir>
```
确认命令返回
```
removed: true
```
。若终止失败，报告确切的会话目录和PID，而非使用大范围终止命令。

若上下文中断，可从保存的

session_dir

恢复；若需重新加载

dm.sh

，然后使用

dm status

、

dm logs

和

dm stop

，或运行

dm doctor

查看并管理所有活跃会话。

melech-debug-mode

Original

Translation

Debug Mode

调试模式

Guardrails

防护规则

Start A Session

启动会话

Add Dynamic Request Probes

添加动态请求探针

Pick A Reproduction Mode

选择复现模式

Autopilot

自动驾驶模式

Manual

手动模式

Inspect On
`proceed`

收到
`proceed`
后检查

Doctor: Monitor Live Sessions

诊断工具：监控活跃会话

Installing
`dm`
persistently for the user

为用户持久化安装
`dm`

Finish Or Abort

结束或中止会话

melech-debug-mode

Original

Translation

Debug Mode

调试模式

Guardrails

防护规则

Start A Session

启动会话

Add Dynamic Request Probes

添加动态请求探针

Pick A Reproduction Mode

选择复现模式

Autopilot

自动驾驶模式

Manual

手动模式

Inspect On proceed

收到proceed后检查

Doctor: Monitor Live Sessions

诊断工具：监控活跃会话

Installing dm persistently for the user

为用户持久化安装dm

Finish Or Abort

结束或中止会话

Inspect On
`proceed`

收到
`proceed`
后检查

Installing
`dm`
persistently for the user

为用户持久化安装
`dm`