bashkit-debug

BashKit 调试追踪分析器是一个专为开发人员构建的诊断工具，用于使用 BashKit 框架开发代理程序。通过处理代理程序执行期间生成的 JSONL 格式调试文件，此技能提供了对工具执行内部生命周期的可见性，包括从开始到结束的关联、嵌套的父子任务关系以及精确的时序指标。对于需要了解代理程序为何停滞、特定工具为何返回错误或如何优化复杂的多步骤工作流程的工程师来说，这是一个必不可少的工具。该分析器解析来自 bash、read、write、edit、glob、grep、task 和基于 web 的操作的特定工具摘要字段，以提供全面的诊断分析。

• 使用唯一的 ID 追踪自动关联工具调用事件，以链接开始、结束和错误信号。

• 计算每次工具调用的延迟和持续时间，突显超过性能阈值的缓慢操作。

• 汇总错误统计信息并识别失败模式，例如重复的 bash 退出代码、失败的文件读取或 grep 操作中的 regex 不匹配。

• 通过映射多代理执行流程中的父子关系来可视化子代理任务层级。

• 提供循序渐进的分析手册，以评估代理行为、检测无限循环并验证工具参数的输入与输出。

• 使用 BASHKIT_DEBUG=file:/path/to/trace.jsonl 作为日志的标准输入格式。

• 包含用于终端中对大型追踪文件进行摘要的辅助脚本，以便在不人工检查文件的情况下识别趋势。

• 非常适合用于调试 Vercel AI SDK 集成、本地沙盒环境和 Vercel 远程沙盒部署。

• 支持分析复杂的嵌套子代理交互和任务工具内的 Token 使用报告。

• 对于排查文件系统错误（例如编辑操作期间的“字符串未找到”）或 bash 指令执行中的“退出代码 1”失败非常有效。