claudeplus/mdTemplet/debug.md

Debug / Pitfalls

按工具 / 主题分节：## <tool> 为二级分组，具体坑用 ### YYYY-MM-DD 简述 + 症状 / 原因 / 规避 三联。同工具的坑逐步往下追加。

eza

2026-04-21 --tree 无路径参数静默空输出

• 症状: eza --tree --git-ignore --level=2 输出空, exit 0
• 原因: eza tree 模式需要显式路径参数
• 规避: 总是加 .（或其他路径）

broot

2026-04-21 无法在非交互环境使用

• 症状: broot --cmd ":pt;:q" 报 Termimad Error: IO error: No such device
• 原因: broot 需要 TTY, 设计就是交互工具
• 规避: CLI/Claude Code 场景直接用 eza + fd + rg
• 附注: 首次运行会自动 patch ~/.bashrc 和 ~/.zshrc 注入 br 函数

repomix

2026-04-21 大仓库 token 预算

• 症状: nexus4cc (203M 磁盘) 经 .gitignore 过滤后仍 144k tokens
• 原因: 前端单文件（如 Terminal.tsx 21k tokens）累积
• 规避: > 100k tokens 的仓库按子目录切片 (repomix frontend/src -o /tmp/fe.xml)

pkill / bash

2026-04-21 pkill -f 匹配自身命令行导致 shell 退出

• 症状: pkill -f cdp-proxy.mjs 后整个 Bash 块 exit 144，没有错误信息
• 原因: -f 按完整命令行匹配，Bash tool 执行 -c "pkill -f cdp-proxy.mjs ..." 时 argv 里包含 "cdp-proxy.mjs"，pkill 把自己的父 shell 一并杀了
• 规避: 用 pgrep -af <pattern> 先列出 PID 再按 PID kill；或用更窄的 regex 如 'cdp\S*proxy'（regex 元字符不在自己的命令行里出现）

lightpanda

2026-04-21 Beta 能力边界

• 症状: 多个看似标准的 CDP 操作失败：第二次 /new 返回空对象、/screenshot 报 UnknownTargetId、关闭最后一个 tab 后所有请求 BrowserContextNotLoaded
• 原因: v1.0.0-nightly.5674 当前实现受限 ——（1）只维护单 target/BrowserContext（targetId 永远是 FID-0000000001）（2）Page.captureScreenshot 未实现（3）没有 tab 自动重生机制
• 规避: 同时多目标时用 A 模式（lightpanda fetch）或多进程 serve；需要截图走 web-access 默认 Chrome 模式；避免 close 最后一个 tab（或 close 后立即 /new 重建）

2026-04-21 强反爬 SPA 被挡在 noscript 页

• 症状: 导航到 x.com 等站点，document.body.innerText 返回 <noscript> 错误页内容而不是真实页面
• 原因: lightpanda 覆盖率不足，被站点的反爬/浏览器指纹检测识别为非真浏览器
• 规避: 需要反爬能力强的场景切换到 web-access 连真 Chrome；或提前测试目标站点可行性

web-access skill

2026-04-21 cdp-proxy.mjs 硬编码 Chrome 专用 ws 路径，不兼容 lightpanda

• 症状: lightpanda serve --port 9222 起来后 check-deps.mjs 报 "连接超时"，proxy 日志循环 "连接错误: 连接失败"
• 原因: scripts/cdp-proxy.mjs getWebSocketUrl() fallback 到 /devtools/browser（Chrome 专用），而 lightpanda 的 webSocketDebuggerUrl 是 ws://host:port/（根路径）
• 规避: 端口扫描分支加入 /json/version 探测（CDP 标准 discovery endpoint），从响应的 webSocketDebuggerUrl 取 pathname。通用修复，Chrome 也受益。已本地 patch，skill 升级会被覆盖，需重新应用