说到调试，别总想着直接改代码。
先看现象，再动手，不然容易越修越乱。
第一个坑：localhost:8765 到底是谁的？
用户说：“预览链接不对，还老是跳错项目。”
听着像配置问题，但别急着改配置。
不猜，先取证
AI 没动一行代码，先跑了个命令：
lsof -i :8765
结果吓一跳：端口 8765 上跑的根本不是我们项目的 jianfei-hyper，而是另一个叫 jianfei-upload 的服务。
根因很简单：启动脚本默认绑定 8765，但它只按 PID 文件停旧进程。
如果这个端口被别人占了，它还是傻乎乎地打印 http://localhost:8765 —— 这就是典型的 链接欺骗。
用测试固定行为
修复前，先写个测试：
“当默认端口 8765 被占用时，启动脚本不能再瞎报地址，得自动换下一个。”
测试一开始红，改完代码变绿——这才是靠谱的做法，不是靠感觉。
修复并验证
脚本现在加了三层保护：
- 自动避让：8765 被占？那就试试 8766、8767……直到找到空闲端口
- 显式报错：你非要指定 PORT=8765？行啊，但要是被占，直接告诉你谁在用
- 启动确认：后台服务起来后 2 秒内检查进程是否活着，避免输出假链接
最后实测：
python3 -m pytest tests -q → 45 passed
bash -n restart_server.sh → 语法通过
实际启动 → 自动切到 8766，HTTP 200
搞定！
回到正题：jianfei-video 为什么会“断链”？
用户反馈：“视频技能加载不了，路径找不到。”
听起来像是文件丢了？其实不是。
排查路径
一步步来：
.codex/skills/看了一眼 → 文件都在.agents/skills/同步目录 → 也正常- 往下追到
.hermes/skills/media/jianfei-video→ 哇，没了！
再翻历史记录才发现：
原来这里应该是个软链接，指向 ~/.qclaw/skills/jianfei-video。
但桥接链断了，不是技能坏了，是路标不见了。
修复动作
补上软链接就 OK：
ln -s ~/.qclaw/skills/jianfei-video ~/.hermes/skills/media/jianfei-video
验证一下：
.agent→.agents→.hermes三层都能读到同一个 SKILL.md- 可读技能数从 52 恢复到 53
- 断链列表清空 ✅
调试方法论总结
两个案例看起来不同，其实套路一样：
| 步骤 | 端口冲突 | 软链断裂 |
|---|---|---|
| 观察现象 | 链接错了 | 技能加载失败 |
| 收集证据 | lsof 看端口 | 逐层追踪路径 |
| 定位根因 | 脚本不检查占用 | 桥接软链丢了 |
| 修复验证 | TDD 测试 + 实际启动 | 补链 + 三层验证 |
| 经验归档 | 写入 LESSONS.md | 记录修复动作 |
一句话口诀记住就行：
"复现 → 隔离 → 假设 → 验证 → 归档"
每一步都不能跳。没复现就改？那是赌命。
修完不记？等于白修。
关键词：调试方法论、TDD、端口冲突、软链接、AI 编码助手、系统化排查