BashKit 调试追踪分析技能
解析 BashKit 智能体运行的 JSONL 调试追踪，快速定位错误、慢操作与异常执行模式。
该技能仅做只读分析（cat/grep/jq 读取 JSONL 追踪文件），无写入、网络或破坏性操作，_helper 脚本有 set -euo pipefail、依赖检查与文件存在性检查；追踪文件内容含用户代理会话数据（命令、文件路径、输出），技能未提示敏感数据脱敏，属数据流披露不完全。扣分：无敏感数据提示、依赖 jq/bc 未声明版本来源。
文档与脚本自洽：事件生命周期、id 关联、parent 字段、各工具 summary 字段描述一致，脚本有明确的错误反馈（缺 jq、文件不存在即退出并提示）。但静态审查无法执行：summarize-trace.sh 无对应测试（仓库测试覆盖的是缓存/上下文模块），bc 依赖未在脚本前置检查中验证，边界（空文件、单行、LAST_TS< FIRST_TS）未见处理。静态上限 10，且因边界处理薄弱扣至 10 以下不成立则保持 10？实际边界证据不足，按锚点 'happy path 可信但测试/边界薄' 给 10 上限内偏保守取 10。
触发条件明确（'debug trace'、'analyze trace'、'.l' 文件等），适用场景（调试 BashKit agent 运行）与前置条件（BASHKIT_DEBUG 生成追踪）描述清楚，非适用范围隐含但未明示（如非 BashKit 生成的 JSONL 不适用）。环境方面 jq 为硬依赖且脚本有降级提示；对中文用户无中文支持，但核心功能不依赖中国大陆不可达服务。扣分：非适用边界与输入校验描述有限。
SKILL.md 结构清晰、分层合理（格式→剧本→脚本→启用方式），仓库有 MIT LICENSE、package. 版本 0.7.2、CI（test/lint/typecheck）与 codecov。扣分：技能本身无版本号/变更记录、无 FAQ、无已知限制章节，维护责任仅能从仓库作者推断，发布者未经注册表验证。
分析剧本结构化（概览/错误/性能/模式/建议），脚本能预压缩大追踪文件以节省 token，边际价值相对手动 grep 明显。但静态审查无法验证实际输出质量与脚本在真实追踪上的可用性，超时阈值等为经验值无依据。静态上限 7，因输出直接可用性证据有限取 6。
格式定义、脚本与 README 的 BASHKIT_DEBUG 说明相互印证，仓库有真实 CI 工作流与测试套件但均未覆盖本技能关键路径（脚本、追踪解析）。无第三方执行证据，无独立可复现结论。扣分：关键路径不可复现，覆盖薄，取 4。
- 追踪文件包含完整的工具输入输出（命令、文件内容、URL），分析前应脱敏敏感信息；技能未提供脱敏指引。
- summarize-trace.sh 依赖 jq 和 bc，且 bc 未经前置检查；空文件或时间戳异常可能导致时长计算错误。
- 本评估为纯静态审查，未执行脚本或验证追踪格式与 BashKit 实际输出的匹配度。
- 发布者未经 FollowSkills 注册表验证，技能本身无版本号与变更记录，更新路径不明。
- 文档中的延迟阈值（bash>10s 等）为经验值，无数据支撑，仅供参考。
这个 Skill 能做什么，适合哪些场景？
这是一个面向 BashKit（Vercel AI SDK 智能体编码工具集）的调试分析技能。它读取通过 BASHKIT_DEBUG 环境变量生成的 JSONL 追踪文件，按事件 ID 关联工具调用的 start/end/error 事件，还原完整的执行时间线。技能内置分析手册，指导识别报错、超阈值慢操作、智能体循环重试等常见问题，并输出结构化诊断报告。对于用 BashKit 构建智能体应用、却难以回答"这次运行到底哪里出了问题"的开发者，这是现成的排障工具。
读取 .l 追踪文件，解析每行的 DebugEvent 结构；按 id 配对 start/end/error 事件，按 parent 字段还原子智能体嵌套关系；利用各工具的 summary 字段（如 bash 的 exitCode、grep 的 fileCount）提取关键指标；对照阈值（如 bash >10s、task >60s）标记慢操作；检测循环调用、无修复重试、孤儿 start 事件等模式；可调用目录内 summarize-trace.sh 预压缩大文件，最后按概述/错误/性能/模式/建议结构输出报告。
- 用 BashKit 构建智能体后运行失败，需要弄清哪个工具调用出了错
- 智能体看似卡死，想通过时长数据找出挂起的 bash 命令
- 智能体反复执行同一命令，怀疑缺少缓存或陷入循环
- 排查子智能体 token 消耗过高的性能问题
- 需要向团队汇报一次失败的智能体运行，要一份结构化诊断报告
这个 Skill 有哪些优点和局限？
- 追踪格式在 SKILL.md 中完整定义（DebugEvent 接口、各工具 summary 字段），分析规则明确可复现
- 自带阈值表和反模式清单（循环、无修复重试、孤儿事件），不是泛泛的"看看日志"
- 提供 summarize-trace.sh 压缩大追踪文件，节省分析 token
- 触发词清晰，易于模型自动识别调用时机
- 仅适用于 BashKit 生成的追踪文件，对其他框架的日志无能为力
- 追踪输出有截断限制（字符串 4000 字符、数组 20 项），可能丢失关键细节
- 技能质量缺乏独立测试或用户反馈佐证
- 需要使用者在运行时正确设置 BASHKIT_DEBUG，否则无可分析数据
如何安装这个 Skill？
将 skills/bashkit-debug/ 文件夹放入项目的 skills 目录（BashKit 的 discoverSkills 会扫描 .skills/ 与 ~/.bashkit/skills/，本地 Agent Skills 客户端可直接加载 SKILL.md）。同时需先安装 bashkit（bun add bashkit）才能产生追踪文件。
如何使用这个 Skill？
1) 运行智能体时开启追踪：BASHKIT_DEBUG=file:./trace.l node my-agent.js；2) 触发技能，例如询问"分析 bashkit 追踪"或"这次运行哪里出了问题"并指向 trace.l；3) 文件较大时可先运行 ./skills/bashkit-debug/summarize-trace.sh trace.l 生成精简时间线；4) 按报告结构查看错误、慢操作与改进建议。
这个 Skill 与同类方案有什么区别？
BashKit 本身对标 Claude Code 的内置工具集（Bash/Read/Edit/Grep/Task 等），将其移植到 Vercel AI SDK 生态；此技能则相当于为 BashKit 补上调试追踪分析层，与通用的"读日志"技能相比，其优势在于对 BashKit 专属事件格式的深度理解。