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 元字符不在自己的命令行里出现）

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 升级会被覆盖，需重新应用