# Pitfall Journal 开发过程中踩过的坑，按时间倒序排列。Agent 进入调试或遇到运行时错误时可检索本文件。 ### [PF-20260727-1322] WindowsApps bash 别名会让可用性探测挂起 - **症状**: Hook 跨平台测试在 `bash --version` 阶段长期无输出，整套测试超过超时仍不结束。 - **根因**: `shutil.which("bash")` 优先命中了 WindowsApps 的 WSL 应用执行别名；该占位 `bash.exe` 存在但不会像 Git Bash 一样快速返回版本，原探测也没有 subprocess timeout。 - **解法**: 给候选 bash 的版本探测增加短超时，捕获 `subprocess.TimeoutExpired` 后继续尝试 Git 安装目录中的 `bin/bash.exe`；Hook 子进程本身也设置超时，避免再次无限等待。 - **防御**: Windows 上不能仅凭 `which` 和文件存在判断 CLI 可用；外部工具探测必须执行带超时的无副作用命令，并把单个候选超时视为“不可用”而不是全局失败。 - **关联**: `.cursor/hooks/tests/test_check_changelog.py`、WindowsApps、WSL alias、Git Bash、subprocess timeout --- ### [PF-20260727-1129] Changelog Hook 仅凭 mtime 产生无改动误报 - **症状**: Git 工作区没有任何内容差异，`stop` Hook 却因 `.vscode/settings.json` 时间戳较新而要求创建 changelog fragment。 - **根因**: `.session-start` 缺失时 Hook 回退到旧 changelog 时间，并且只比较宽泛扫描范围内文件的 mtime，没有验证候选文件是否存在真实 Git 内容差异。 - **解法**: `.session-start` 缺失或 Git 状态不可用时 fail-open；工作区干净时立即退出；候选文件还必须被 `git status --porcelain` 判定为未提交改动。PowerShell 与 Bash 实现同步修复并添加回归测试。 - **防御**: 文件时间只能限定“本会话之后”，不能作为内容改动证据；Hook 提示写日志前必须同时满足会话时间与版本控制状态，并覆盖“仅 touch、无内容变化”的测试。 - **关联**: `.cursor/hooks/check-changelog.ps1`、`.cursor/hooks/check-changelog.sh`、`.cursor/hooks/tests/test_check_changelog.py`、Cursor stop Hook、Windows/Bash ---