SuperAPI AI 工具集

debug

测试与质量

查看项目

更新于 10-15 20:29

技能介绍

用途:该技能用于 PostPrint 项目的 Bug 定位与 Cursor 调试模式插桩,核心流程是先定位问题所属层级,再通过日志证明或推翻假设。适用场景包括:不清楚问题出在哪一层、需要跨层复现、使用 Cursor 调试模式并依赖 applications/.cursor/debug-<sessionId>.log 中的 NDJSON、以及需要插桩验证假设。不适用于新功能开发、测试与 CI、只读猜测式排查、生产或 k8s 日志(后者见项目本地 k8s 技能)。

主要能力与原则:先定位再修复,未确定层级前不修;假设先行,明确“我认为 X 因为 Y,若成立则 Z 可观测”;一次只改一个变量;先读现有信号(DevTools、Network、Django 日志、React Query DevTools);用一句话描述 Bug;重复出现的 Bug 视为设计问题,修机制而非个例。

使用方式:按症状选择参考文档,如层级未知看 localization,后端与 Docker Compose 看对应 surface 文档,客户端、扩展、node 服务、共享包及跨层场景各有参考。插桩前先阅读调试模式提醒以获取日志路径、session ID 与 ingest 端点(仅 JS/TS),确认相关栈已运行,并定义 sessionId、runId、hypothesisId 等关联键。通用协议:先提出 3–5 个假设,再在边界处插桩(请求进出、WS 收发、Celery 入队出队),清理旧调试产物后用新 runId 复现一次,逐步最小化场景,按假设读日志并标注 CONFIRMED / REJECTED / INCONCLUSIVE,仅在日志证明后修复,修复后保留插桩验证,最后按清理清单收尾。

路径规则:Docker 后端推荐通过挂载写入 applications/.cursor/debug-<sessionId>.log;非 Docker 的 uv run 写仓库相对路径;客户端与扩展(JS/TS)使用调试模式提醒中的 fetch 模板或 @postprint/logger;容器内可用 POSTPRINT_CURSOR_DEBUG_LOG 覆盖。Python 追加 NDJSON,不要 POST 到 ingest URL;TypeScript/JavaScript 在需要会话捕获时使用提醒中的一行 fetch 模板。

限制:资料未提供具体安装命令、收费与平台信息;输出需遵循 references/output-schema.md,并在使用插桩时以假设结论与清理状态结尾。