Worktrunk 如何定位性能问题：-vv 参数生成的 trace 与 diagnostic.md 完全指南

Worktrunk 如何定位性能问题-vv 参数生成的 trace 与 diagnostic.md 完全指南【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunkWorktrunk 是面向并行 AI Agent 工作流的 Git worktree 管理 CLI 工具。本文带你用-vv参数一次定位 Worktrunk 性能问题它会在.git/wt/logs/下生成trace.jsonl等追踪文件与diagnostic.md诊断报告配合wt config state logs profile就能看清时间到底花在了哪里。为什么 Worktrunk 需要专门的性能定位能力Worktrunk 的wt list等命令会对每个 worktree 并行发起大量 git 子进程。当你的仓库 worktree 数量很多时慢可能来自某个 git 命令、某个 worktree或是并行度不足。Worktrunk 为此内置了一条完整的性能观测链路核心思路是用-vv抓一次执行现场 → 用diagnostic.md/profile分析 → 用可视化时间线确认关键路径整条链路的实现位于 src/trace/ 模块日志落盘逻辑见 src/log_files.rs。一键捕获性能现场wt -vv 命令定位性能问题只需给任何 wt 命令加上-vvwt -vv list --progressive运行结束后wt 会打印类似提示Diagnostics and performance profile saved .git/wt/logs/diagnostic.md所有日志统一写入主 worktree 的 git 目录下.git/wt/logs/所有 worktree 共享同一目录。每次-vv运行会覆盖上一次的四个文件因此每次报告都对应最近一次执行。-vv 生成的四个文件文件面向对象内容trace.log人类每条命令的起始$ …与完成✓/✗ … 12.3ms、进程内 span、里程碑事件trace.jsonl机器与trace.log相同的事件流每行一个 JSON 对象供jq与 profile 命令消费subprocess.log深度排查子进程原始 stdout/stderr 全文可能达数 MBdiagnostic.mdBug 报告Markdown 诊断包内嵌性能剖析与追踪日志四个文件分工明确见 docs/src/content/docs/config.md 的日志章节trace.log有界、可直接贴进 issuetrace.jsonl供程序化分析subprocess.log只在深挖时打开。读懂 diagnostic.md一份能直接提交的诊断报告diagnostic.md由 src/diagnostic.rs 生成是为提 issue设计的 Markdown 文件结构按诊断价值从高到低排列头部— 时间戳、执行的命令、执行结果Performance profile— 对trace.jsonl的聚合视图默认展开一眼看到时间去向、并行度与冗余命令Environment— wt 版本、操作系统、git 版本、Shell 集成状态Environment variables— 精心筛选的白名单变量PAGER、TERM、LANG、RUST_LOG等Worktrees—git worktree list --porcelain原始输出Config— 用户与项目配置文件内容Trace log— 调试日志超过约 50KB 会自动截断保留末尾部分隐私边界它绝不会泄露什么这一点值得特别强调diagnostic.md永远不做全量env转储环境变量只取自固定白名单源码中的DIAGNOSTIC_ENV_VARS常量见 src/diagnostic.rs因此携带凭据的变量不可能混进报告文件内容、密钥也均不包含在内。你可以放心把它作为 issue 附件提交。聚合分析wt config state logs profile单看原始记录效率低Worktrunk 提供了聚合命令直接读取最近一次-vv的trace.jsonlwt config state logs profile它回答三个核心问题实现在 src/trace/profile.rs时间去向BY COMMAND TYPE按命令形态分组git status、git rev-list…给出次数、总时长、最大、平均BY CONTEXT按 worktree 名称分组定位哪个 worktree 拖慢了并行阶段Slowest最贵的 20 个单独任务并行度如何—parallelism子进程总时长 ÷ 墙钟跨度与peak_concurrency同时飞行的子进程峰值哪里在做无用功—CacheReport标记同一上下文被重复执行的命令即本应命中缓存却漏掉的调用还可以加--formatjson输出结构化结果方便用jq二次筛选。典型定位路径示例假设wt list明显变慢wt -vv list --progressive wt config state logs profile在 profile 输出中先看BY COMMAND TYPE找到耗时最长的命令形态如git log再看BY CONTEXT确认它集中在哪个 worktree打开subprocess.log用对应的seq编号关联该命令的完整原始输出确认是仓库本身大、还是 git 版本慢三步之内瓶颈通常就能锁定。可视化调试Chrome Trace Format 与逐条时间线对于想直观查看关键路径的读者Worktrunk 还支持两种更深入的视图1. 导出 Chrome Trace 格式src/trace/chrome.rs 可将trace.jsonl记录转换为 Chrome Trace FormatPerfetto / chrome://tracing 可加载以时间轴方式检查并行执行的临界路径。2. 逐条时间线开发工具wt-perf timeline会替你完成捕获 渲染一步到位示例见 src/trace/mod.rs 的模块说明cargo run -p wt-perf -- timeline -- list --progressive它渲染按开始时间排序的表格ts(ms) | dur | tid | kind | name实现见 src/trace/timeline.rs并在结尾汇总子进程总时长、追踪跨度与外部实测墙钟——两者之差正是进程启动/退出等未观测开销。进阶技巧让 Shell 补全也留下现场-v/-vv只能作用于你敲的命令而 Shell 补全是独立进程无法接收参数。Worktrunk 提供环境变量等价物WORKTRUNK_VERBOSE2它对所有 wt 调用包括补全生效2即生成与-vv相同的四个文件。想排查Tab 补全为什么慢时按 shell 实际调用的方式跑一次再用wt config state logs profile分析即可场景说明见 docs/src/content/docs/faq.md。常见问题排查清单 症状首选动作看哪里某条 wt 命令整体变慢wt -vv cmdlogs profileBY COMMAND TYPE / Slowestworktree 多了之后更慢同上BY CONTEXT 定位拖后腿的 worktree怀疑并行没跑满同上parallelism 与 peak_concurrency疑似重复劳动/缓存失效同上CacheReport 段需要提交 bug 报告wt -vv cmddiagnostic.md直接作为附件渲染/分页异常wt -vv config show报告中的 Environment variablesPAGER、core.pager总结Worktrunk 的性能定位不需要外部工具一条-vv就能同时产出人类可读的trace.log、机器可读的trace.jsonl、原始输出subprocess.log以及汇总成诊断 性能剖析的diagnostic.md。配合wt config state logs profile的三问框架时间去向、并行度、冗余工作与 Chrome Trace 可视化从感觉慢到锁定根因通常只需三四条命令。这套机制的完整文档还可见 docs/public/ 与基准测试说明 benches/CLAUDE.md。【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考