多角色并发调试（magic-debug）

magic-debug 是驱动调试工作台的技能：一个窗口并排 N 个隔离面板（平台 / 商户 / 买家等，各自持久登录态互不顶号），Claude 经壳内内嵌 MCP 用 role 参数并发驱动任意面板。

本页讲安装与命令用法；这个壳 APP 的产品形态与架构（多角色隔离、内嵌 MCP、项目管理窗）见调试工作台。

安装

magic-debug 是自包含技能，运行时不依赖 magic-stack、也不需要 Docker，可独立安装分发。

独立一行装（只装 magic-debug） —— 内网优先、外网兜底：

bash

# 外网(任意机器)
curl -fsSL http://maven.vv.yunku.live/repository/raw-releases/magic-debug/latest/install-bootstrap.sh | bash

# 内网(能直连 172.16.2.100,更快)
curl -fsSL --noproxy '*' http://172.16.2.100:8081/repository/raw-releases/magic-debug/latest/install-bootstrap.sh | bash

装它只做三件事：装薄 skill（SKILL.md + 薄启动器）到 ~/.claude/skills/magic-debug、从 Nexus 下载独立打包的「绿色版」（electron-builder 产物）到 ~/.magic-stack/magic-debug/app、在全局 ~/.claude/CLAUDE.md 注入受管块。装好后 magic-debug 命令全局可用；桌面壳重启后自动重连，无需手动 /mcp。

也可随 magic-skills 合集一起装（见安装整套技能）——但那会连同 magic-stack、 magic-bugfix 一并装上。只想单独给别人用 magic-debug，就走上面的独立一行装。

起壳三步

给壳「URL + 一堆角色 / 账号密码」，按三步起调试：写两个文件 → magic-debug up → 连接。两个文件都放项目根 .magic-stack/debug/ 下。

1. `debug-shell.json`（可提交）

json

{
  "project": "myproject",
  "roles": [
    { "role": "admin", "label": "管理员",   "account": "admin",       "url": "http://127.0.0.1:8080/" },
    { "role": "buyer", "label": "买家",     "account": "13800000000", "url": "http://127.0.0.1:8080/", "platform": "mobile" }
  ]
}

字段	必填	说明
`project`	是	项目 slug，一般用工作区名小写
`role`	是	英文短名，项目内唯一，后续所有工具用它定位面板
`account`	是	账号标识（通常 = 登录用户名 / 手机号），也是身份核对的期望登录名
`url`	是	该角色打开的起始页
`label`	否	面板顶栏显示名（默认 = role）
`platform`	否	`"web"`（默认，PC 宽屏）或 `"mobile"`（414px 窄宽手机外壳）

2. `credentials.json`（自动 gitignore，禁止提交）

账密的唯一存储位置，键 = 规范键 <project>-<role>-<account>：

json

{
  "myproject-admin-admin":       { "username": "admin",       "password": "<真实密码>" },
  "myproject-buyer-13800000000": { "username": "13800000000", "password": "0000" }
}

登录任一角色前先读该文件取账密，别靠记忆 / 猜；学到新账号随手写回。真实账密只落这个 gitignored 文件，绝不写进 SKILL.md / journal / 日志 / 提交。

3. `magic-debug up`

在项目根执行，起壳并写 .mcp.json（stdio 桥形态）。.mcp.json 就位后，新会话 Claude 会自动 spawn 桥连接（桥自动确保壳在跑、壳重启自动重连）；当前会话首次生成后 /mcp 或重开一次即可。

驱动面板

连接后，调用工具带 role 短名即可并发驱动对应面板：

工具	作用
`browser_navigate(role, url)`	导航
`browser_snapshot(role)`	结构快照（拿元素 ref）
`browser_click(role, ...)`	点击（uni-app `@tap` 无 ref 时用 `selector` / `text` 定位）
`browser_type(role, ...)`	输入
`browser_take_screenshot(role)`	截图
`browser_wait_for(role, ...)`	等待
`debug_journal_read` / `debug_journal_append`	读 / 续写调试手账

状态与关闭

bash

magic-debug status     # 看壳是否在跑
magic-debug down       # 关壳

人工启动器（无参 magic-debug / manager 打开的项目管理窗口）见调试工作台。

使用场景示例（用大白话跟 Claude 说）

你几乎不用碰命令和配置文件——把站点地址、各角色账号密码用一句话丢给 Claude，它自己写配置、起壳、登录、驱动面板。你只需说清楚**「这次要它做到哪一步」**。下面用一个示例电商项目贯穿演示。

先把测试账号一次性交给它（仅示例，真实账密它只会写进本机 gitignored 文件、不入库/不入文档）：

「用 magic-debug 给这个站点起调试，站点 http://127.0.0.1:8080，三个角色： 平台管理员 admin / Admin@123；商户 merchant01 / Shop@123；买家（H5 手机端，短信登录）手机号 13800000000、固定验证码 0000。」

Claude 收到后会自己建好配置、起壳、把三个角色登录到位（还会核对每个登录进去的确实是对应角色，防串号）。之后你换着法子指挥它就行：

场景 1 · 只起壳，先别测

「先把壳起起来、三个角色都登上，起好等我发指令，先别动。」

它会把工具和登录都备好，然后停下等你——不会自作主张开测。

场景 2 · 补 / 换登录

「买家那个账号我换密码了，重新登一下。」「再帮我把商户也登上。」

它会只处理你点到的角色，已登录的自动跳过，不重复折腾。

场景 3 · 给它明确步骤照做

「用买家走一遍下单：进商品页 → 加购 → 结算，看能不能生成订单，报错就截图给我。」

它会一步步在买家这个面板上操作，边做边汇报，出错就截图、把现场记下来。

场景 4 · 没步骤，一起边看边测

「帮我看看商户后台的订单列表有没有问题。」

它会边点边跟你商量：提议怎么走 → 做一步 → 报一下看到什么 → 等你反馈，不会闷头一口气跑完。

场景 5 · 多角色联动 / 同角色多账号

「买家下一单，然后切到商户后台看这笔订单到没到。」「再加个买家 B（手机号 13900000000），让 A、B 各下一单对比一下。」

它能同时开着买家、商户两个面板来回核对（各自独立登录、互不顶号）；同一种角色要多个账号，你直接说「买家 A / 买家 B」它就分开配。

场景 6 · 复现到问题，记下来（或顺手修）

「刚才买家结算那个报错，把这个 bug 记下来。」

它会在现场把问题连同截图、页面地址、报错日志一起录成一条 bug（直传工作台看板，没接入就先存本地）。如果是你自己的项目，还可以接着说「顺手把它修了」，它会改完再验一遍。

场景 7 · 接着上次继续

「接着上次那个调试继续。」

它会先把上次的调试记录读回来，从断点续做，不用你重新交代一遍。

一句话诀窍：多说一句「做到哪一步」——只起壳 / 也登录 / 我给步骤你照做 / 一起边测边看 / 只记录别修。说得越清楚，它越不会越位、也不会缺位。

录 bug 直传工作台

调试壳里复现到问题现场后，一句话把它录成 bug 直传工作台（:17070 workbench）：

配接入串（一次性）：工作台「设置 → Owner 设置 → 项目外部录入」生成 connect 串，写进 <项目>/.magic-stack/debug/bug-upload.json（{"connect":"<接入串>"}）。该文件自动 gitignore、含明文密钥，禁止提交。
录 bug：复现到位后调 bug_report(role, title, note?, severity?)，自动带上该面板截图 + 当前 URL + console 尾部 + network 尾部 + snapshot，无需先手动截图。
未接入工作台兜底：落本地 markdown 到 <项目>/.magic-stack/debug/bugs/<日期>-<role>-<slug>.md，别让 bug 丢。

录制固定测试流程（命名流程）

反复要跑的固定流程（下单、改配置、跑一遍表单、复现某 bug 的前置步骤……）可以录一次、以后一步重放，不用每次手把手点。登录之外的任意多步流程都用它。

录：flow_record_start(role, name) → 正常点通整条流程 → flow_record_save(role)。宏存 .magic-stack/debug/flows/<role>/<name>.json，不含明文账密（填的账密自动替占位符，回放时从 credentials.json 现取）。
放：run_flow(role, name) —— 一步重放整条流程；验证码步停下交人，固定码环境传 fixedCode 自动填。
管理：list_flows(role) 列该角色已录流程；flow_record_cancel(role) 放弃当前录制。

没事先录也能存（事后保存）：常规调试时每步操作已自动进滚动历史，临时想把刚做的这段留档，直接 flow_save_recent(role, name[, count]) 存成命名流程，不用再走一遍。存前可 flow_history(role) 预览挑范围，flow_history_clear(role) 标记「从现在起重新算」。缓冲上限 50 步、壳重启即清，打码规则同录制。

你怎么跟 Claude 说：

录：「把买家下单这条流程录下来，叫 place-order：进商品页 → 加购 → 结算 → 提交。」放：「用买家跑一遍 place-order，看还通不通。」事后存：「刚才那几步操作挺好用，直接存成 place-order，别再走一遍了。」

只想跳到某个常去页（不是整条流程）：waypoint_save(role, name) 存当前页 → goto(role, name) 一步直达；list_waypoints / waypoint_delete 管理。

登录 record-replay（登录专用）

登录单独有一套（要跟「是否已登录」联动）：login_record_start(role) → 点通一次登录 → login_record_save(role)，重开面板命中登录页自动回放；ensure_logged_in(role) 已登录跳过。账密不进宏（自动替占位符，回放时从 credentials.json 现取），宏文件永不含明文；验证码步回放到该步停下交人。

多角色并发调试（magic-debug） ​

安装 ​

起壳三步 ​

1. debug-shell.json（可提交） ​

2. credentials.json（自动 gitignore，禁止提交） ​

3. magic-debug up ​

驱动面板 ​

状态与关闭 ​

使用场景示例（用大白话跟 Claude 说） ​

场景 1 · 只起壳，先别测 ​

场景 2 · 补 / 换登录 ​

场景 3 · 给它明确步骤照做 ​

场景 4 · 没步骤，一起边看边测 ​

场景 5 · 多角色联动 / 同角色多账号 ​

场景 6 · 复现到问题，记下来（或顺手修） ​

场景 7 · 接着上次继续 ​

录 bug 直传工作台 ​

录制固定测试流程（命名流程） ​

登录 record-replay（登录专用） ​