# 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`)

## sd

### 2026-04-21 捕获组引用是 $1 不是 ${$1}，字面量 $ 要写 $$
- 症状: `sd 'pat (\w+)' '${$1}' file` 输出把 `$1` 位置变成空字符串，替换结果不对
- 原因: sd replacement 里 `$1` 或 `${1}` 才是捕获组引用，`${$1}` 解析失败；字面 `$` 需要写 `$$`
- 规避: 想生成 `` `/api/users/${id}` `` 这类带字面 `${...}` 的输出，replacement 写作 `` `/api/users/$${$1}` ``（`$$` = 字面 `$`，`$1` = 捕获值）；不确定时先用 stream 模式 `sd ... < file` 预览再 in-place

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