36 lines
2.2 KiB
Markdown
36 lines
2.2 KiB
Markdown
# 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
|
||
|
||
---
|
||
|
||
<!--
|
||
### [PF-YYYYMMDD-HHMM] 简短标题
|
||
|
||
- **症状**:
|
||
- **根因**:
|
||
- **解法**:
|
||
- **防御**:
|
||
- **关联**:
|
||
|
||
---
|
||
-->
|