HankKnowledge 经验教训

2026-07-25 项目记忆体系初期数据为空的问题

• 现象: AI_项目记忆 目录搭建完成后，8/12 个文件为空模板，从未写入过真实数据
• 根因: SKILL.md 是"人类阅读的文档"而不是"AI 执行的指令"，缺乏强制性执行步骤
• 方案: 重写 SKILL.md 为强制执行流程（识别项目 → 询问用户 → 写入文件 → 确认），每个触发词对应必须完成的写操作
• 避免: 所有 SKILL 文件必须以"这是你的执行指令"开头，明确"必须执行 Write 操作"，不得只输出建议

2026-07-25 项目记忆体系搭建

• 现象: 4 个项目需要共享 AI 记忆，需要设计统一的存储和访问方案
• 根因: 每个项目独立运行，AI 在切换项目时失去上下文
• 方案: 选择 CODEBUDDY.md 被动引用 + 共享 SKILL 主动管理，而非 Hook 自动转储（后者噪音大、缺乏判断力）
• 避免: 不追求自动化完美，MVP 优先验证核心流程是否跑通

2026-07-28 Quartz serve.bat 端口冲突 — WebSocket 端口遗漏

• 现象: serve.bat 反复因端口冲突崩溃。修复 HTTP 端口（8080→8081）后仍失败，日志显示 "Server stopped" 无明确错误
• 根因: Quartz 需要两个端口：HTTP（--port，默认 8080）和 WebSocket/HMR（--wsPort，默认 3001）。只处理了 HTTP 端口，忽略了 WebSocket 端口也在用
• 方案: serve.bat 同时扫描 HTTP 端口（8080-8089）和 WebSocket 端口（3001-3010），用 Python socket 检测可用性，使用 --wsPort 参数启动
• 避免: Quartz 的 build --serve 需要同时处理 --port 和 --wsPort 两个参数，缺一不可。排查服务端问题时应先检查完整启动命令的所有端口依赖

2026-07-28 删除 Quartz 时 content/ 目录被 Windows 进程锁定

• 现象: scripts/Quartz/ 大部分文件已删除，但 content/ 空目录被锁定，Remove-Item、rm -rf、takeown、icacls 均无法删除
• 根因: Windows Search Indexer（SearchFilterHost.exe）或防病毒实时扫描进程在索引/扫描该目录时持有了文件句柄。即使停止 WSearch 服务，句柄仍被缓存进程持有
• 方案: 空目录无害，接受保留；若需彻底删除可通过注册表 PendingFileRenameOperations 在下次重启时自动清理
• 避免: Quartz 构建产出的 content/ 目录包含大量文件，Windows Search Indexer 会对其索引锁定。删除前应先停止 WSearch 服务和所有 SearchFilterHost 进程