05 工具链篇：Claude Code/DeepSeek/MCP、SSH/SCP、Git、VSCode 与推流

系列第 6 篇。开发工具本身的坑：Claude Code 接 DeepSeek/MIMO 模型、MCP 配置、SSH/SCP 传文件、Git/GitHub、VSCode 远程、网页推流、代码管理。共 40+ 个真实事件。

一、Claude Code + DeepSeek/MIMO 模型（"claude 链接 deepseek"时期）

1. Claude 桌面端连不上：Can't reach 127.0.0.1:15721（07-15）

  • 现象：桌面端一直连接失败，CLI 却正常。
  • 根因：端口 15721 是 CC Switch 的本地代理端口，检查发现无程序监听——CC Switch 服务没启动；CLI 直连 api.deepseek.com 不受影响。
  • 解决：启动 cc-switch.exe的路由器 再开桌面 Claude。

3. DeepSeek 模型下图片全部 [Unsupported Image]（07-17、07-21 重复）

  • 根因：DeepSeek（纯文本模型）的 Anthropic 兼容接口不支持视觉输入，sonnet/opus/haiku 全部映射到 deepseek 模型。
  • 解决：看图换 claude.ai 网页版/App；或在 AI 工具里接带视觉的 MCP（如 qwen-vl-mcp 接通义千问 DashScope，见坑 11）。

5. 当天 prompt cache miss 激增，token 消耗变大（07-22）

  • 根因：rules 目录装了 8 种语言共 45 个规则文件全塞进 system prompt，任何一个文件改动都让 system prompt hash 变化、缓存全失效；还有 100+ telemetry 失败日志和常驻 skill 浪费空间。
  • 解决：rm -rf ~/.claude/rules/{golang,kotlin,perl,php,swift,typescript}（45→18 个），删 telemetry 垃圾和无用 skill，缓存命中明显改善。

6. /compact 报 ERR_MODULE_NOT_FOUND ... omc/dist/hooks/project-memory/pre-compact.js（07-16）

  • 根因：OMC（oh-my-claudecode）插件安装不完整，dist 编译产物缺失，钩子加载失败。
  • 解决：卸载 OMC——settings.json 移除钩子（备份 .bak）+ 删除 ~/.claude/omc 目录。

二、Claude Code 配置与插件

7. settings.json 写错字段名，校验静默禁用全部设置（07-13）

  • 现象：加 "plugins": {...} 报 Settings validation failed: Unrecognized field: plugins，且该文件全部设置失效。
  • 根因：Claude Code 的 settings 没有顶层 plugins 字段，插件要注册到 known_marketplaces.json 或 extraKnownMarketplaces/enabledPlugins。
  • 解决：改用正确字段；JSON 校验失败会静默禁用整个文件，改完用脚本校验。

8. 记忆按项目目录隔离：桌面端看不到终端端的记忆（07-21）

  • 现象：桌面端问"你对我有什么了解"只读到 1 条记忆，终端项目里存着 14 条。
  • 根因：Claude Code 记忆存于 ~/.claude/projects/<项目路径>/memory/，按项目隔离；skills/agents/rules 是用户级共享。
  • 解决：把终端项目记忆文件复制到桌面项目目录，并同步 MEMORY.md 索引；新增记忆需手动同步。

9. 改了记忆文件但 MEMORY.md 索引还是旧描述（07-14）

  • 解决：手动 Edit MEMORY.md 同步索引条目。

10. 工作目录无法中途切换（07-21、07-22 重复）

  • 现象：mcp__ccd_directory__request_directory 返回 The requested directory could not be resolved。
  • 根因：Claude Code 工作目录由启动位置决定，中途改不了。
  • 解决：/cd C:\Users\Xiaodaidai（2.1.169+ 支持）或在目标目录重新启动会话。

11. MCP 没配 API key：tavily/firecrawl 从没工作过（07-16、07-30 重复）

  • 现象：工具列表里只有 skills-master，tavily 搜索 ETIMEDOUT；vision-bridge 调用 fetch failed。
  • 根因：MCP 服务 env 里没配 API key（注册服务必须 key）；vision-bridge 是服务端到外网连接失败，本机修不了。
  • 解决：删掉坏 MCP；视觉能力改用国内直连的 qwen-vl-mcp（接通义千问 DashScope，API Key 填 .env 后重启 Reasonix 可用）。

12. Bash 命令引号不配对 / 权限限制（07-13、07-22 重复）

  • 现象：eval: line 1: unexpected EOF while looking for matching '"'；ls in 'C:/Program Files/Git/plugin' was blocked。
  • 根因：命令里含未配对引号（Windows 路径/中文引号混入）；会话权限只允许当前工作目录。
  • 解决：用 Glob/Read 等结构化工具代替手写 bash；路径含中文/空格时注意转义。

13. 新加 Stop hook 在 /hooks 面板不显示（07-22）

  • 根因：settings watcher 只在会话启动时加载配置目录，中途新增的 hook 不热加载。
  • 解决：退出会话重进（或手动打开一次 /hooks 触发重载）；Stop hook 用 decision/reason 而非 hookSpecificOutput。

14. 全局 Stop 钩子误设成每次会话都触发 + JSON 损坏（07-22）

  • 解决：从全局 settings.json 移除 Stop 钩子，只保留项目级；JSON 修复后用脚本校验 JSON 合法性。

15. find-skills 安装器装错位置（07-16）

  • 现象：装到 ~/.claude/agents/.claude/skills/（Claude Code 不认）。
  • 解决：挪到正确的 ~/.claude/skills/find-skills，清掉误生成目录；顺带删掉 62 项无用技能。

三、Reasonix 工具

16. config.toml 启动报 TOML 解析错误（07-28 连续两天 3 次）

  • 现象：toml: line 239: expected value but found '"'；隔天 expected eight hexadecimal digits after '\U', but got "C:\\Us"。
  • 根因：① 行首用了中文左引号 "；② Windows 路径里的 \U 被 TOML 当 Unicode 转义。
  • 解决：中文引号改 ASCII；Windows 路径用单引号字面量字符串：args = ['C:\Users\...\index.js']。

17. Reasonix 更新失败：prepare update: a pending update already exists（08-02）

  • 根因：上次更新卡住，repair/pending-update.json + .lock 残留死状态。
  • 解决：退出后删 pending-update.json 与 .lock（保留 updates/ 回滚备份），重开恢复正常。

18. Reasonix 报 401：your API key is missing / 更新代理错误（07-28）

  • 解决：reasonix setup 输入 key 或写进 %AppData%\reasonix\.env；更新失败是 Go 客户端不读系统代理却拾取了坏代理 127.0.0.1:65532 → config.toml 里 [network] proxy_mode = "off" 直连。

19. Python 闭包赋值作用域陷阱：线程里赋值外层变量不生效（07-25，已沉淀技能）

  • 现象：程序启动正常但 SPI 屏永远无画面；cam_frame 始终 None。
  • 根因：嵌套函数 cam_worker() 里 cam_frame = frame 被 Python 当作函数局部变量，外层不变。
  • 解决：用可变容器 cam_frame = [None]，线程里 cam_frame[0] = frame。

四、SSH / SCP / 文件传输（板端开发最高频的坑）

20. VSCode SSH 一直要 xiaodaidai@IP 的密码，WinSCP 却正常（07-31 重复 2 次）

  • 根因：~/.ssh/config 里只有 Host/HostName/Port，没有 User root，VSCode 默认用 Windows 登录名（板子上没这个用户）。
  • 解决：config 里加 User root，重连。

21. VSCode Remote-SSH 一直"正在连接"，保存不了（07-19）

  • 解决：Ctrl+Shift+P → Remote-SSH: Kill VS Code Server on Host → 重连；或 Reload Window。

22. 本地改完代码拷到板子上不生效（07-31 全天反复 5+ 次，最耗时的坑）

  • 现象：依次出现 'WebStreamer' object has no attribute 'pop_thresh_cmd'、thresh_mask() takes from 2 to 4 positional arguments but 6 were given、SyntaxError: EOL while scanning string literal 等连环崩溃。
  • 根因：本地改了代码只拷了部分文件，板子 /userdata/ball_balancer_v2/ 里还是旧版，接口签名对不上。
  • 解决（板端开发纪律）：
    1. 改完代码整组文件一起拷（scp 目录或 WinSCP 覆盖）；
    2. rm -rf /userdata/.../__pycache__/（残留旧字节码会 import 旧模块）；
    3. 重启进程；确认 wc -l/md5sum 与本地一致。

23. 拷贝出 0 字节文件：ls -la 显示文件在但为空（08-01）

  • 现象：ModuleNotFoundError: No module named 'task_manager'，文件 0 字节。
  • 根因：scp/拖拽拷贝中断，文件在但内容没写入。
  • 解决：删掉重拷，拷完必须 ls -la 验证大小非 0；必要时 base64 传输防损坏。

24. Windows scp 传中文文件名静默失败（07-17）

  • 现象：scp 踩坑记录.md 悄悄失败没报错；WinSCP 里看不到文件；commit 里只有删除没有新增。
  • 根因：Windows scp 对中文文件名编码处理失败，传输静默丢文件。
  • 解决：换管道方式重传并验证：cat 踩坑记录.md | ssh 泰山派 'cat > /userdata/project/踩坑记录.md'。
  • 教训：操作完必须验证结果；文件一律英文名。

25. WinSCP 看不到文件（07-17）

  • 根因：WinSCP 列表不自动刷新；Linux . 开头文件默认隐藏。
  • 解决：Ctrl+R 刷新；Ctrl+Alt+H 显示隐藏文件。

26. 项目目录在工作区/桌面间移动，写权限受限（08-01）

  • 解决：用 bash mv 统一移回工作区 global-workspace/ball_balancer_v2，避免路径反复变。

五、Git 与 GitHub

27. GitHub 添加 SSH 公钥报"密钥无效"（07-17）

  • 根因：从聊天窗口复制长公钥带入了换行，GitHub 要求完整一行。
  • 解决：把公钥放进剪贴板（clip）整行粘贴。

28. git push 报"源引用规格 main 没有匹配"（07-18）

  • 根因：本地分支 master，GitHub 新建仓库默认 main。
  • 解决：先 commit 未暂存改动，git branch -M main，再 git push -u origin main。

29. git push 连环失败：仓库名错 + 用户名错 + Token 跨账号（07-25）

  • 现象：Repository not found（仓库名 steel-ball 写错）；Invalid username or token（用 xiaodaidai 的 Token 推 Li1433223 的仓库）；Token 明文贴在对话里（泄露）；板子无 curl 建仓失败。
  • 根因：电脑用户名 ≠ GitHub 用户名；Token 属于旧账号。
  • 解决：改 SSH 密钥认证（ssh-keygen -t ed25519 → 公钥贴 GitHub → git remote set-url origin git@github.com:用户名/仓库.git）；泄露的 Token 立即撤销。

30. 其他 Git 小坑（07-17 ~ 07-20）

  • git commit 不带 -m 进入 vim 卡住 → :q! 退出；-am "中文全角引号" 被 shell 当未闭合 → 用英文半角引号；
  • E325: 发现交换文件 .COMMIT_EDITMSG.swp → 上次 vim 未正常退出，按 D 删除草稿；
  • git -commit 敲错（子命令不带横杠）；
  • gh: command not found → 改用 ssh -T git@github.com 验证。

31. sed 多行替换越改越乱（07-19）

  • 根因：sed 对多行逻辑块逐个替换极易错位（旧代码没替换干净、中间变量被删）。
  • 解决：多行替换给完整代码块直接覆盖，别用 sed 逐个改；保留中间变量（直观 > 简洁）。

六、网页推流（MJPEG）

32. 推流页面自动弹 localhost:8081，其他设备打不开（07-31）

  • 根因：localhost 是本机，板子上的服务要用板子 IP 访问。
  • 解决：浏览器输 http://板子IP:8081。

33. 网页阈值按钮导致页面跳转（07-30）

  • 现象：点 /thresh/80 链接离开主页面跳转到空白页。
  • 根因：用 <a href="/thresh/80"> 链接实现。
  • 解决：改 <button onclick="fetch('/thresh/80')"> 后台请求不跳转。

34. 推流卡顿：服务端 sleep(0.066) 是"额外再加 66ms"而非"控制到 66ms"（07-31）

  • 根因：编码+发送+66ms → 实际 ~8.6fps。
  • 解决：改用帧间隔控制（编码+发送耗时算进 66ms 预算只补剩余）；推流定案 480×180 裁中间 @15fps 质量 60。

35. 推流卡顿：平板解码瓶颈 vs 热点转发（07-31、08-01 重复 4 次）

  • 现象：电脑不卡、平板卡；降带宽仍卡。
  • 根因：平板 CPU 解码 MJPEG 跟不上（MJPEG 每帧全量解码）；手机热点 NAT 转发是 CPU 软转发（延迟 0.3-1s+）。
  • 解决：480×360 @15fps 质量 65（每帧清晰、帧率低但流畅），平板换 Chrome/Edge；录屏用平板自带录屏；可选优化：路由器替代热点 / RK3566 MPP 硬编 H.264。

36. 推流画质/布局坑（07-31）

  • 现象：网页图片只占 1/4 格；信息栏第一行糊、重叠。
  • 根因：HTML 容器 2 列 grid 把单路流挤到半格；putText 第一行 y=20 太靠上被裁；FOUND/LOST 字符串长度不一。
  • 解决：grid 改 flex 单列居中 + max-width 720px；信息栏 y=20→28；等宽补空格对齐。

37. 双路推流帧混乱（08-01）

  • 现象：网页收到两路帧（后台 5fps + 内联 30fps 重复推送）。
  • 根因：_LCDProxy 后台线程调 streamer.update_frame，同时处理线程内联也推。
  • 解决：推流只保留内联（30fps），SPI/HDMI 屏只在后台线程（5fps）。

七、代码管理与记忆（血的教训）

38. 误删代码回退：形态学被统一、标定值被覆盖（08-01）

  • 现象：下午误删很多代码，回退到前天版本；调试细节丢失，AI 也"不记得"形态学参数。
  • 根因：无版本控制 + 误操作 + 记忆只存了静态标定参数，没存代码里的调试细节。
  • 解决：
    1. 与记忆快照逐文件比对恢复；
    2. 双份备份（工作区 + 桌面 ball_balancer_v2_backup_20260801.tar.gz）；
    3. 建立"检测细节存档"类记忆（形态学/预处理链），调试确认的细节即时存档。
  • 教训：每次调试确认的参数、形态学、阈值，当场存记忆，别指望下次还记得。

39. 报告与代码数据打架（08-01）

  • 现象：写设计报告时检测耗时 15-30ms（实测 3-7ms）、ROI 420 vs config 460、形态学"开1闭1" vs 实际"开1闭2"。
  • 解决：用工具全面核对代码 ↔ 报告 ↔ 记忆，统一以 config.py 实际值为准逐项修正。

40. 摄像头 config 路径未同步到板子（07-31）

  • 现象：程序报错说打开 RYS 摄像头失败，但插的是旧 XHH 摄像头。
  • 解决：把最新 config.py 拷板子 + 清 pycache + 重启；grep CAM_PATH config.py 确认（见坑 22）。

小结：工具链篇避坑清单

  1. 板端开发纪律：整组拷贝 → 清 __pycache__ → 重启 → md5sum/ls -la 验证（最高频坑）。
  2. Claude Code 接第三方模型：BASE_URL/model/key 三件套必须落在 settings.json；视觉需求换带视觉的 MCP。
  3. 文件一律英文名（scp 中文会静默失败）。
  4. GitHub 用 SSH 密钥，Token 别贴对话里；分支名 master/main 统一。
  5. 调试细节即时存档 + 双份备份，防误删回退。
  6. 推流用帧间隔控制，别 sleep 叠加；平板解码 MJPEG 有瓶颈。

系列完结

本系列 6 篇从 07-12 到 08-10 共记录了 250+ 个真实踩坑事件，全部来自真实开发会话。如果你也在用 RK3566/类似嵌入式 Linux 板子做视觉，希望这些坑能帮你少走弯路。

感谢阅读，祝比赛顺利 🎯

# python # 开发语言 # 计算机视觉 # 网络 # 学习
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区