踩坑宝典

症状 你看到什么？ 和 AI 协作做了一整套书籍架构规划（章节设计、字数分配、主题方向），会话正常结束。下次开工发现：规划文件没 commit，本地修改丢了（或被覆盖）。全部重来。 根因 真正的原因是什么？ 人的注意力在"思考规划内容"上，不在"保存规划结果"上。规划过程可能持续几十分钟到几小时，期间一直在输出和修改， …

症状 你看到什么？ 微信后台配置为「明文模式」。修复了 XML 二次包装后，日志无报错、AI 正常生成回复、cached_xml 有值——但用户手机端仍然看不到任何自动回复。表现和 XML 嵌套完全一样，给排查造成极大困扰。 根因 到底为什么出问题？ _maybe_encrypt() 函数不关心当前模式，只检查 nonce 和 timestamp 是否存在： …

症状 你看到什么？ 用 Write 工具写文件到 ~/claude-memory/pitfalls/xxx.md（或用绝对路径 /home/zhaotianbing/claude-memory/...），工具报告成功，无报错。但 ls ~/claude-memory/pitfalls/ 看不到新文件。 实际上本次会话就复现了：5 篇新踩坑用 Write 工具 …

症状 你看到什么？ 用户说"审计五件套"来审计一个 Excel 文件。这是一个数据录入项目，TRIGGERS.md 有两条路由同时命中： “审计五件套 / 跑审计” → 加载 audit-four-piece.md “数据录入项目” → …

症状 你看到什么？ 公众号推送文章草稿后，读者看到的中文全部变成 我是 这样的 Unicode 转义序列。微信后台预览正常，但推送后乱码。踩了 3 次才修好。 根因 真正的原因是什么？ requests.post(url, json=data) 内部调用 json.dumps(data) 时，默认参数 ensure_ascii=True， …

症状 你看到什么？ 用 python-docx 生成的报告，表格在页面底部被 Word 自动劈成两半——表头在上页，数据在下页。读者看到断裂的表格，专业性大打折扣。手动在 Word 里调整也调不好。 根因 真正的原因是什么？ python-docx 创建的表格行，默认没有设置 <w:cantSplit/> 属性。Word 打开文档后，按自己的分页 …

症状 你看到什么？ AstrBot 微信公众号适配器中，被动回复模式（active_send_mode=False）完全不工作： 用户发消息到公众号 → 无任何回复 日志报 TypeError: The response value returned by the view function cannot be None 调试器中 AI 回复正常，部署后就是 …

症状 你看到什么？ with open("config.txt", encoding="utf-8") as f: for line in f: if line.startswith("GITEE_TOKEN="): # ← 永远不匹配 token = …

症状 你看到什么？ 新文章 URL 可以正常访问（/posts/xxx/ 能打开），但： 分类页看不到这篇文章 首页最新文章列表没有它 所有聚合/列表页都不知道这篇文章存在 用户从分类入口进来找不到文章，以为没发布。 根因 到底为什么出问题？ Hugo 是一个全量静态站点生成器——每篇文章的交叉引用、分类聚合、列表渲染，都需要 hugo -d docs/ 重 …

症状 你看到什么？ 用 deploy_fix4.sh 部署修复到 AstrBot 后： sed 命令执行成功（exit 0） grep -q "nonce = None" 验证通过（匹配到关键字） 服务器重启后返回 500 错误 用户以为修好了，实际服务器崩了。 根因 到底为什么出问题？ 部署脚本用了 GNU sed …

症状 你看到什么？ 踩坑共享平台需要 Gitee 镜像。在 Gitee 上新建了 pitfall-knowledge-base 仓库，配置了 GitHub → Gitee 镜像同步。后来发现用户早就有 claude-memory 仓库，功能完全重叠——claude-memory 本身就是踩坑知识库。 结果： 多了一个无用仓库，要手动删除 镜像同步配置白做了 …

症状 你看到什么？ 每次 git commit 后都跑 git push origin master && git push gitee master，两条命令都成功。实际上 Gitee 那边早已配置了从 GitHub 自动镜像同步，push origin 之后 Gitee 会自动拉取。手动再 push gitee 不仅多余，还可能在极端情况 …

症状 你看到什么？ git push 到 GitHub 报错：fatal: unable to access 'https://github.com/...': SSL connection error 或 TLS handshake failed。每次 push 都失败，ping 不通 GitHub。 根因 真正的原因是什么？ Windows 环境 …

症状 你看到什么？ 用 win32com 打开 Excel 文件，批量修改了几百个单元格的值和批注，调用 wb.Save() 后无任何报错。打开文件一看——所有修改都没了，文件还是原来的样子。 # 跑了半小时的修复脚本... for row in range(2, 500): ws.Cells(row, col).Value = fix_value …

症状 你看到什么？ Cloudreve 云盘通过 Cloudflare Tunnel 暴露到公网。上传一个 15MB 的文件，浏览器进度条走得很慢，大约 2 分钟后显示"上传失败"。Cloudreve 日志里看不到明显错误。 换小文件（<5MB）上传正常。大文件必挂。 根因 到底为什么出问题？ 请求链路： 浏 览 器 → C l o …

症状 你看到什么？ AstrBot 微信公众号被动回复模式：AI 正常生成回复，日志显示 wx buffer hit on trigger 和 wx first window timeout 正常打印，cached_xml 里有值。但用户手机端永远看不到回复。无任何报错日志——微信静默丢弃了回复。 根因 到底为什么出问题？ callback 函数把 AI 结 …