踩坑宝典 on 世界一隅 | 认知能量工程

AstrBot 公众号被动回复 XML 二次包装导致微信无法解析

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

AstrBot 微信公众号被动回复模式：AI 正常生成回复，日志显示 wx buffer hit on trigger 和 wx first window timeout 正常打印，cached_xml 里有值。但用户手机端永远看不到回复。无任何报错日志——微信静默丢弃了回复。

根因

到底为什么出问题？

callback 函数把 AI 结果用 create_reply() 转成完整 XML 存入 cached_xml：

# callback 函数中
reply_xml = str(create_reply(result, msg))
state["cached_xml"].append(reply_xml)

存储的内容已经是完整 XML：

<xml>
<ToUserName><![CDATA[ofqGA2NNjQOqZL3snP_mzNQrGQLM]]></ToUserName>
<FromUserName><![CDATA[gh_bd189357a403]]></FromUserName>
<Content><![CDATA[你好，我是AI助手]]></Content>
</xml>

但 handle_callback 从 cached_xml 取出后，又用 _reply_text() 再包装一次：

def _reply_text(text: str) -> str:
    reply_obj = create_reply(text, msg)  # 把完整 XML 当作文本再包装
    ...

微信收到嵌套 XML → 无法解析 → 静默丢弃。

修复

怎么做？

Cloudreve 上传大文件超时：Cloudflare 免费版 100 秒限制

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

Cloudreve 云盘通过 Cloudflare Tunnel 暴露到公网。上传一个 15MB 的文件，浏览器进度条走得很慢，大约 2 分钟后显示"上传失败"。Cloudreve 日志里看不到明显错误。

换小文件（<5MB）上传正常。大文件必挂。

根因

到底为什么出问题？

请求链路：

Cloudflare 免费版 HTTP 代理有硬性 100 秒超时。Cloudreve 默认分块大小较大（如 25MB），在网络慢的情况下，单块上传耗时 125 秒，超过 100 秒限制后 Cloudflare 直接切断连接。

Excel COM wb.Save() 静默失败，必须用 SaveAs

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

用 win32com 打开 Excel 文件，批量修改了几百个单元格的值和批注，调用 wb.Save() 后无任何报错。打开文件一看——所有修改都没了，文件还是原来的样子。

# 跑了半小时的修复脚本...
for row in range(2, 500):
    ws.Cells(row, col).Value = fix_value
    ws.Cells(row, col).AddComment(f'原值: {old} → 修复: {fix}')

wb.Save()   # ← 静默失败，半小时白干
wb.Close()

根因

到底为什么出问题？

Excel COM 的 Save() 方法在以下情况下静默失败（不抛异常、不返回错误码）：

文件来自只读目录：微信聊天目录 D:\xwechat_files\... 下的文件，权限受限
网络路径/UNC 路径：\server\share\file.xlsx
文件被其他进程打开：Excel 自己或其他程序持有文件锁
磁盘空间不足：Save 写入失败但不报错

COM 接口的设计缺陷——Save() 不返回 HRESULT，异常被吞掉。

修复

具体步骤，能复制粘贴直接用。

import os
import win32com.client

excel = win32com.client.Dispatch("Excel.Application")
excel.Visible = False
excel.DisplayAlerts = False

wb = excel.Workbooks.Open(src_path)
ws = wb.Worksheets(1)

# ... 做你的修改 ...

# ✅ 正确做法：SaveAs 到可写目录
output = os.path.expanduser('~') + r'\Desktop\output.xlsx'
wb.SaveAs(output, FileFormat=51)   # 51 = xlOpenXMLWorkbook (.xlsx)
wb.Close(SaveChanges=False)        # 已经 SaveAs 过了，不重复保存
excel.Quit()

关键参数：

Git push GitHub SSL 握手失败

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

git push 到 GitHub 报错：fatal: unable to access 'https://github.com/...': SSL connection error 或 TLS handshake failed。每次 push 都失败，ping 不通 GitHub。

根因

真正的原因是什么？

Windows 环境下，Git 不会自动走系统代理（Clash/V2Ray）。之前只在单仓库设了 http.proxy，其他仓库和全局 .gitconfig 都没设，每次在新仓库 push 都重复踩坑。

修复

具体怎么修的？

git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897

设完立刻生效，所有仓库自动走代理。当前 Clash 代理端口是 7897，如果你的代理端口不同需要改。

怎么避免

下次怎么不踩？

新机器/新系统第一件事：跑上面两行命令
用 git config --global --list | grep proxy 确认已设
别用单仓库 --local，那是坑的根源

Gitee 已配镜像还手动 push gitee，做了多余操作

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

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

更严重的是：git remote 里 gitee 的 URL 硬编码了 token（Zhaotianbibg1:cfe33...@gitee.com），每次 push 都明文传输。

根因

到底为什么出问题？

不知道镜像已配：Gitee 后台配了 GitHub → Gitee 镜像后，没有删掉本地的 gitee remote
习惯性操作：之前手动 push 两个 remote 形成习惯，没人提醒就一直做
没有"查 remote 列表 → 确认是否冗余"的检查步骤

修复

怎么做？

# 删掉 gitee remote（镜像自动同步，不需要手动 push）
git remote remove gitee

# 确认只剩下 origin
git remote -v
# origin  https://github.com/zhao818/claude-memory.git (fetch)
# origin  https://github.com/zhao818/claude-memory.git (push)

以后只推 GitHub：

Gitee 建仓库前没查已有仓库，建了重复仓库

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

踩坑共享平台需要 Gitee 镜像。在 Gitee 上新建了 pitfall-knowledge-base 仓库，配置了 GitHub → Gitee 镜像同步。后来发现用户早就有 claude-memory 仓库，功能完全重叠——claude-memory 本身就是踩坑知识库。

结果：

多了一个无用仓库，要手动删除
镜像同步配置白做了
概念混乱：哪个仓库才是真的？

根因

到底为什么出问题？

不查就建：建仓库前没跑 gh repo list zhao818 或登录 Gitee 看已有仓库
命名冲动：想了一个"好听的名字"就建了，没考虑是否和已有仓库功能重叠
平台不统一：GitHub 一个名、Gitee 一个名，镜像对不齐
没有"先确认再行动"的肌肉记忆：对平台操作的敬畏不够

修复

具体步骤。

# 1. 先查 GitHub 上已有的仓库
gh repo list zhao818 --limit 50

# 2. 再查 Gitee 上已有的仓库
# 浏览器打开 https://gitee.com/Zhaotianbibg1 → 看仓库列表

# 3. 确认没有同名/同功能仓库后，再建
# GitHub → Settings → Developer settings → Personal access tokens
# Gitee → 设置 → 私人令牌

# 4. 名称对齐：GitHub 和 Gitee 用同一个仓库名
# GitHub: zhao818/claude-memory
# Gitee:  Zhaotianbibg1/claude-memory  ← 对齐

删除多余仓库后，重新配置镜像：

GNU sed a 命令中被当字面量——假阳性验证导致以为修好实际没修

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

用 deploy_fix4.sh 部署修复到 AstrBot 后：

sed 命令执行成功（exit 0）
grep -q "nonce = None" 验证通过（匹配到关键字）
服务器重启后返回 500 错误

用户以为修好了，实际服务器崩了。

根因

到底为什么出问题？

部署脚本用了 GNU sed 的 a\（append）命令插入多行：

sed -i "/match_line/a\            nonce = None\n            timestamp = None" target.py

在 GNU sed 的 a\ 命令中，\n 被当作字面量（反斜杠 + n），而非换行符。实际写入的是：

nonce = None\n            timestamp = None   # ← 全在 1 行！Python 语法错误

但 grep -q "nonce = None" 验证仍然匹配成功 → 假阳性验证。关键字在，代码是错的。

修复

怎么做？

用 Python 做文件替换，精确控制，不用 sed 多行命令：

Hugo 手写单篇 HTML 跳过全量构建导致分类/列表页不更新

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

新文章 URL 可以正常访问（/posts/xxx/ 能打开），但：

分类页看不到这篇文章
首页最新文章列表没有它
所有聚合/列表页都不知道这篇文章存在

用户从分类入口进来找不到文章，以为没发布。

根因

到底为什么出问题？

Hugo 是一个全量静态站点生成器——每篇文章的交叉引用、分类聚合、列表渲染，都需要 hugo -d docs/ 重新计算。手写单篇 HTML 扔进 docs/ 相当于绕过了整个生成引擎：

这个错误已经犯过至少 3 次。

Python encoding='utf-8' 不能自动处理 BOM

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

with open("config.txt", encoding="utf-8") as f:
    for line in f:
        if line.startswith("GITEE_TOKEN="):  # ← 永远不匹配
            token = line.strip().split("=", 1)[1]

文件明明以 GITEE_TOKEN=cfe33... 开头，但 startswith 永远返回 False，令牌读不到。打了 print(repr(line)) 才发现行首有。

根因

真正的原因是什么？

Windows 下某些工具（记事本、PowerShell Out-File、部分 IDE）保存 UTF-8 文件时会在文件头加 BOM（Byte Order Mark，）。Python 的 encoding='utf-8' 不会自动跳过 BOM，它被当作第一个字符读进去。

修复

具体怎么修的？

# ❌ 错误
with open("config.txt", encoding="utf-8") as f:

# ✅ 正确——自动跳过 BOM
with open("config.txt", encoding="utf-8-sig") as f:

一行之差，三天之坑。

怎么避免

下次怎么不踩？

读配置文件、.env、用户输入文件时，默认用 utf-8-sig
调试编码问题第一招：print(repr(line)) 看原始字符
如果不想改 encoding，可以手动 line.lstrip('')

Python 缩进错位导致 140 行被动回复代码完全跳过

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

AstrBot 微信公众号适配器中，被动回复模式（active_send_mode=False）完全不工作：

用户发消息到公众号 → 无任何回复
日志报 TypeError: The response value returned by the view function cannot be None
调试器中 AI 回复正常，部署后就是不行
检查了所有逻辑，没发现问题——代码"看起来"都在

# handle_callback 方法的末尾
if self.active_send_mode:
    result_xml = await self.callback(msg)
    if not result_xml:
        return "success"
    ...

    # 以下 140 行被动回复代码...
    from_user = str(getattr(msg, "source", ""))
    to_user = str(getattr(msg, "target", ""))
    # ... 100+ 行逻辑 ...
    return reply_xml

# ← handle_callback 结束，但没有任何 return

根因

到底为什么出问题？

140 行被动回复代码的缩进是 12 个空格，对应 3 级缩进（4+4+4），错误地放在了 if self.active_send_mode: 块内部。

python-docx 表格跨页断开无法控制

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

用 python-docx 生成的报告，表格在页面底部被 Word 自动劈成两半——表头在上页，数据在下页。读者看到断裂的表格，专业性大打折扣。手动在 Word 里调整也调不好。

根因

真正的原因是什么？

python-docx 创建的表格行，默认没有设置 <w:cantSplit/> 属性。Word 打开文档后，按自己的分页算法决定是否断开表格——如果表格行正好落在页面底部，Word 就会把它断开。

这是 python-docx 的默认行为缺陷，不是 Word 的问题。

修复

具体怎么修的？

from docx import Document
from docx.oxml.ns import qn

doc = Document()
table = doc.add_table(rows=5, cols=3)

# 关键：给每一行设 cantSplit，禁止跨页断开
for row in table.rows:
    tr = row._tr
    trPr = tr.get_or_add_trPr()
    cant_split = OxmlElement('w:cantSplit')
    trPr.append(cant_split)

doc.save('output.docx')

这样生成的表格不会在页面中间断开，Word 会把整行推到下一页。

怎么避免

下次怎么不踩？

生成 docx 表格时，所有行显式设 cantSplit
目录（TOC）不要手动写，用 Word 域代码 TOC \o "1-3" 生成
参考 ~/claude-memory/global/tools/docx-patterns.md 的完整模式

requests json= 参数导致公众号中文乱码

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

公众号推送文章草稿后，读者看到的中文全部变成 我是 这样的 Unicode 转义序列。微信后台预览正常，但推送后乱码。踩了 3 次才修好。

根因

真正的原因是什么？

requests.post(url, json=data) 内部调用 json.dumps(data) 时，默认参数 ensure_ascii=True，会把所有非 ASCII 字符转成 \uXXXX。微信服务器收到后原样展示，不会反转义。

这不是微信的 bug，是 requests 的默认行为。

# requests 内部等价于：
body = json.dumps(data, ensure_ascii=True)  # 中文 → \uXXXX
# 发送给微信：{"content": "我是中文"}
# 微信原样展示：我是中文

修复

具体怎么修的？

# ❌ 错误——中文变乱码
requests.post(url, json=data)

# ✅ 正确
import json
headers = {'Content-Type': 'application/json; charset=utf-8'}
requests.post(url, data=json.dumps(data, ensure_ascii=False).encode('utf-8'), headers=headers)

关键三步：

ensure_ascii=False — 中文保持原样
.encode('utf-8') — 转成字节
手动设 Content-Type: application/json; charset=utf-8 — 告诉服务器编码

怎么避免

下次怎么不踩？

TRIGGERS 多场景同时命中时只读第一条，漏了后续路由

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

用户说"审计五件套"来审计一个 Excel 文件。这是一个数据录入项目，TRIGGERS.md 有两条路由同时命中：

“审计五件套 / 跑审计” → 加载 audit-four-piece.md
“数据录入项目” → 加载 audit-four-piece-data.md、excel-com-audit.md、data-cross-verify.md

但实际操作中只读了第一条（通用版），漏了数据版三条。用户提醒"我记得优化过你的记忆啊，为什么还做不到"——因为之前已经修过这个问题，但触发匹配逻辑没改彻底。

后果：跑完审计流程后，数据特有的坑（收支=明细交叉验证、实发=应发检查、Excel COM 修复模式）全部没做。

根因

到底为什么出问题？

匹配策略是"命中即停"：扫到第一个匹配行就停下来加载了，没继续往下扫
没有 OR → AND 的思维转换：多条路由匹配同一任务时，取的文件应该是并集（AND），不是第一个命中（OR）
TRIGGERS 表设计有盲区：通用路由和专用路由分开写，但加载逻辑没做合并
事后没自检：加载完文件后没问自己"用户说的是审计+Excel，我有没有读 Excel 相关的路由？"

修复

怎么做？

匹配策略改为"全量扫描 + AND 合并"：

例如用户说"审计这个 Excel"：

WSL 环境下 Claude Code Write 工具和 Bash 工具路径空间不一致

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

用 Write 工具写文件到 ~/claude-memory/pitfalls/xxx.md（或用绝对路径 /home/zhaotianbing/claude-memory/...），工具报告成功，无报错。但 ls ~/claude-memory/pitfalls/ 看不到新文件。

实际上本次会话就复现了：5 篇新踩坑用 Write 工具写完后，Bash 下全部找不到。最后用 Bash 重新写入才正确落盘。

根因

到底为什么出问题？

核心矛盾：当前会话的 $HOME 是 /c/Users/zhaot（Windows 侧），但 Write 工具把 /home/zhaotianbing/ 路径解析到了 WSL 原生 Linux 文件系统。

两个工具的路径空间不一致 → Write 写入的位置和 Bash 读写的位置不同。Read 工具走了不同的解析路径所以能读到 Write 写的文件，但 Bash 看不到。

公众号明文模式下 nonce/timestamp 非空导致回复被错误加密

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

微信后台配置为「明文模式」。修复了 XML 二次包装后，日志无报错、AI 正常生成回复、cached_xml 有值——但用户手机端仍然看不到任何自动回复。表现和 XML 嵌套完全一样，给排查造成极大困扰。

根因

到底为什么出问题？

_maybe_encrypt() 函数不关心当前模式，只检查 nonce 和 timestamp 是否存在：

def _maybe_encrypt(self, xml, nonce, timestamp):
    if xml and "<Encrypt>" not in xml and nonce and timestamp:
        return self.crypto.encrypt_message(xml, nonce, timestamp)
    return xml or "success"

微信在明文模式下的 POST 请求 URL 中仍然携带 nonce 和 timestamp 参数（用于 URL 签名验证，不是加解密），所以条件 nonce and timestamp 为真 → 执行加密 → 微信收到 <Encrypt> 标签的密文 → 明文模式下无法解析 → 静默丢弃 → 用户永远看不到回复。

修复

怎么做？

两层防护：

第一层：明文模式分支中置空 nonce/timestamp：

if not msg_signature:
    logger.info("明文模式，直接解析消息。")
    msg = parse_message(data.decode("utf-8"))
    nonce = None       # ← 置空，跳过加密
    timestamp = None   # ← 置空，跳过加密

第二层：增加类级别 _is_encrypted 标志：

长时间规划结束忘记 commit 丢失进度

Sat, 13 Jun 2026 00:00:00 +0000

症状

你看到什么？

和 AI 协作做了一整套书籍架构规划（章节设计、字数分配、主题方向），会话正常结束。下次开工发现：规划文件没 commit，本地修改丢了（或被覆盖）。全部重来。

根因

真正的原因是什么？

人的注意力在"思考规划内容"上，不在"保存规划结果"上。规划过程可能持续几十分钟到几小时，期间一直在输出和修改，但 git commit 不在意识里。会话结束时，要么忘了 commit，要么会话异常退出导致未保存的修改丢失。

本质：规划和保存是两个独立动作，大脑把"想完了"误认为"存好了"。

修复

具体怎么修的？

建立纪律：规划完成一个阶段 → 立刻 commit，10 秒的事。

# 不要等到"全部做完"，每完成一个可独立交付的片段就：
git add projects/xxx.md
git commit -m "docs: xxx 架构初版完成——章节+字数分配"

具体到 AI 协作场景：让 AI 在每次完成阶段性规划后主动 commit，不等人提醒。

怎么避免

下次怎么不踩？

铁律：规划做完立刻存仓库，不等会话结束（已写入 ~/claude-memory/global/feedback/plan-must-commit-immediately.md）
AI 协作时，要求 AI 主动 commit，不允许"等会话结束时再存"
每完成一个可独立交付的片段就 commit，把 commit 当保存键用

踩坑宝典 on 世界一隅 | 认知能量工程

AstrBot 公众号被动回复 XML 二次包装导致微信无法解析

症状

根因

修复

Cloudreve 上传大文件超时：Cloudflare 免费版 100 秒限制

症状

根因

Excel COM wb.Save() 静默失败，必须用 SaveAs

症状

根因

修复

Git push GitHub SSL 握手失败

症状

根因

修复

怎么避免

Gitee 已配镜像还手动 push gitee，做了多余操作

症状

根因

修复

Gitee 建仓库前没查已有仓库，建了重复仓库

症状

根因

修复

GNU sed a 命令中 被当字面量——假阳性验证导致以为修好实际没修

症状

根因

修复

Hugo 手写单篇 HTML 跳过全量构建导致分类/列表页不更新

症状

根因

Python encoding='utf-8' 不能自动处理 BOM

症状

根因

修复

怎么避免

Python 缩进错位导致 140 行被动回复代码完全跳过

症状

根因

python-docx 表格跨页断开无法控制

症状

根因

修复

怎么避免

requests json= 参数导致公众号中文乱码

症状

根因

修复

怎么避免

TRIGGERS 多场景同时命中时只读第一条，漏了后续路由

症状

根因

修复

WSL 环境下 Claude Code Write 工具和 Bash 工具路径空间不一致

症状

根因

公众号明文模式下 nonce/timestamp 非空导致回复被错误加密

症状

根因

修复

长时间规划结束忘记 commit 丢失进度

症状

根因

修复

怎么避免

GNU sed a 命令中被当字面量——假阳性验证导致以为修好实际没修