rtk 项目 /tech:worktree-status 命令剖析：Git Worktree 后台 Cargo Check 状态查询机制

rtk 项目 /tech:worktree-status 命令剖析Git Worktree 后台 Cargo Check 状态查询机制【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk本文以 rtk 仓库中 Claude Code 自定义斜杠命令定义文件 .claude/commands/tech/worktree-status.md 为核心讲解 rtk 项目并行开发工作流中后台 cargo check 状态查询命令的完整设计日志文件命名契约、四态状态机判定逻辑、错误信息提取方式与全部输出形态。读完后你能理解该命令如何通过/tmp下的 marker 日志文件与创建命令配对协作并能照此模式为任意后台长任务 状态轮询场景设计可复用的 CLI 工作流。一、命令定位Worktree 并行开发工作流的状态查询端rtk 仓库在.claude/commands/tech/目录下定义了一组面向 Claude Code 的 Git Worktree 生命周期命令构成创建 → 查询状态 → 清理的闭环命令定义文件职责/tech:worktree.claude/commands/tech/worktree.md创建隔离 worktree并在后台启动 cargo check同时写入日志文件/tech:worktree-status.claude/commands/tech/worktree-status.md本文主角查询指定分支后台 cargo check 的完成状态/tech:remove-worktree.claude/commands/tech/remove-worktree.md移除单个 worktree目录 git 引用 分支/tech:clean-worktrees.claude/commands/tech/clean-worktrees.md自动清理所有已合并分支的过期 worktree/tech:worktree的核心特性是约 1 秒完成创建 后台 cargo check见其文档头部 Performance 一节worktree 目录立即可用编译器校验在后台子进程中异步执行。这就产生了一个天然需求——如何在不阻塞开发的前提下随时查询后台检查进行到哪个状态了。/tech:worktree-status正是为这个需求而生的状态查询端。两个命令的文件头 frontmatter 遵循 Claude Code 命令约定--- model: haiku description: Worktree Cargo Check Status argument-hint: branch-name ---argument-hint表明该命令接受一个分支名参数如feature/new-filtermodel: haiku是 Claude Code 的命令级模型配置指定执行该命令时使用轻量模型查询状态属于低风险短任务。二、使用方法按文档 Usage 一节传入与创建时完全一致的分支名必须含斜杠分类前缀与/tech:worktree的分支命名规范一致/tech:worktree-status feature/new-filter /tech:worktree-status fix/session-bug创建命令执行成功后会在输出中直接给出下一步提示形成命令间互指 Check status: /tech:worktree-status feature/new-filter Or view log: cat /tmp/worktree-cargo-check-feature-new-filter.log即创建 → 自动告知查询命令 → 查询状态的引导链路用户无需记忆日志路径规则。三、实现机制逐行剖析/tech:worktree-status的实现是一个自包含 bash 脚本文档 Implementation 一节核心逻辑可拆解为四个环节。3.1 日志文件路径的命名契约BRANCH_NAME$ARGUMENTS LOG_FILE/tmp/worktree-cargo-check-${BRANCH_NAME//\//-}.log这是整个命令能工作的前提/tmp下的日志文件名由分支名确定性地推导出来。${BRANCH_NAME//\//-}是 bash 参数展开把分支名中的/替换为-于是分支feature/new-filter对应日志/tmp/worktree-cargo-check-feature-new-filter.log。这个契约的另一半由创建命令履行。查看 .claude/commands/tech/worktree.md 的脚本可以看到两侧命名规则严格一致# worktree.md创建端 WORKTREE_NAME${BRANCH_NAME//\//-} WORKTREE_DIR$REPO_ROOT/.worktrees/$WORKTREE_NAME LOG_FILE/tmp/worktree-cargo-check-${WORKTREE_NAME}.log即状态查询命令不持有任何状态它的全部信息都来自创建命令写到/tmp的日志文件。这是一种无守护进程、无锁、纯文件约定的进程间通信IPC方式代价是日志文件依赖/tmp的存活周期重启后会丢失此时状态命令会报找不到日志。值得注意的版本差异仓库根级旧命令 .claude/commands/worktree-status.md 使用的日志前缀是/tmp/worktree-cargocheck-*且状态标记为纯文本PASSED/FAILED而tech/目录下的新命令使用/tmp/worktree-cargo-check-*前缀与 emoji marker✅/❌/⏳。从文件对照看当前与 worktree.md 创建脚本匹配的生效版本是.claude/commands/tech/目录下的一套旧版可视为早期迭代的遗留物。3.2 日志不存在时的降级输出if [ ! -f $LOG_FILE ]; then echo ❌ No cargo check found for branch: $BRANCH_NAME echo echo Possible reasons: echo 1. Worktree was created with --fast / --no-check flag echo 2. Branch name mismatch (use exact branch name) echo 3. Cargo check hasnt started yet (wait a few seconds) echo echo Available logs: ls -1 /tmp/worktree-cargo-check-*.log 2/dev/null || echo (none) exit 1 fi找不到日志不是简单的报错退出而是给出三种可操作的排查方向这与创建命令的行为完全对应--fast/--no-check跳过了检查——创建脚本中SKIP_CHECKtrue分支不写日志文件对应 worktree.md 中的 flag 解析逻辑分支名不精确——日志名对分支名是全量映射差一个字符就定位不到检查尚未启动——后台子 shell 写第一行⏳ Cargo check started之前存在极短窗口。最后一行ls -1 /tmp/worktree-cargo-check-*.log把当前所有 worktree 的日志列出来帮助用户核对我到底该传哪个分支名这是低成本但高可用性的排障设计。3.3 基于 marker 行的四态状态机LOG_CONTENT$(head -n 1000 $LOG_FILE) if echo $LOG_CONTENT | grep -q ✅ Cargo check passed; then # 状态①通过 elif echo $LOG_CONTENT | grep -q ❌ Cargo check failed; then # 状态②失败 elif echo $LOG_CONTENT | grep -q ⏳ Cargo check started; then # 状态③仍在运行 else # 状态④未知状态 fi状态判定不依赖退出码、PID 或任何运行时状态而是依赖创建命令在日志末尾写入的确定性 marker 行。对照创建脚本可以验证 marker 的产生逻辑# worktree.md 后台子进程创建端 echo ⏳ Cargo check started at $(date %H:%M:%S) $LOG_FILE if cargo check --all-targets $LOG_FILE 21; then echo ✅ Cargo check passed at $(date %H:%M:%S) $LOG_FILE else echo ❌ Cargo check failed at $(date %H:%M:%S) $LOG_FILE fi日志写入顺序是started行覆盖写→ cargo 全部输出追加→ 终态行passed或failed二选一。因此判定优先级天然正确出现✅ Cargo check passed⇒ 任务已完成且成功否则出现❌ Cargo check failed⇒ 已完成且失败否则只有⏳ Cargo check started⇒ cargo 进程还在运行终态行尚未追加都不匹配 ⇒ 日志内容异常进入兜底分支直接cat全量日志交给人/Agent 判断而不是猜测。head -n 1000限制只扫描日志前 1000 行避免对超大编译输出做全量内存加载——cargo 失败时错误上下文可能很长而 marker 行一定在文件尾部附近的写入序列中按顺序出现扫描上限对判定结果无影响。各状态下提取的时间戳用sed s/.*at //从 marker 行截出例如✅ Cargo check passed at 14:23:45→14:23:45与创建端date %H:%M:%S的格式对应为当天 24 小时制时分秒不含日期。3.4 失败态的错误摘要提取elif echo $LOG_CONTENT | grep -q ❌ Cargo check failed; then TIMESTAMP$(echo $LOG_CONTENT | grep Cargo check failed | sed s/.*at //) echo ❌ Cargo check failed echo Completed at: $TIMESTAMP echo ERROR_COUNT$(grep -v Cargo check $LOG_FILE | grep -c ^error || echo 0) echo Errors: echo ───────────────────────────────────── grep ^error $LOG_FILE | head -20 echo ───────────────────────────────────── echo echo Full log: cat $LOG_FILE echo echo ⚠️ You can still work on the worktree - fix errors as you go.三个设计要点grep ^error锚定行首精确匹配 rustc 的标准错误行error[E0308]: ...避免误匹配 cargo 输出中引用 error 的普通文字head -20截断失败时错误可能成片摘要只展示前 20 条完整内容通过提示的cat $LOG_FILE获取——这恰好契合 rtk 项目压缩输出、降低 token 消耗的整体理念状态命令输出的是摘要 定位线索而非全量日志失败不阻断末尾明确提示You can still work on the worktree - fix errors as you go即基线编译错误不阻塞在该 worktree 上开发边改边查即可。四、完整输出示例文档 Output Examples 一节给出了三种终态/进行态的完整输出原样继承如下4.1 成功Success✅ Cargo check passed Completed at: 14:23:45 Worktree is ready for development!4.2 失败Failed❌ Cargo check failed Completed at: 14:24:12 Errors: ───────────────────────────────────── error[E0308]: mismatched types -- src/git.rs:45:12 ───────────────────────────────────── Full log: cat /tmp/worktree-cargo-check-feature-new-filter.log4.3 仍在运行Still Running⏳ Cargo check still running... Started at: 14:22:30 Current time: 14:22:45 Check again in a few seconds or view live progress: tail -f /tmp/worktree-cargo-check-feature-new-filter.log仍在运行分支会同时打印开始时间与当前date %H:%M:%S时间让调用者人或 Claude Code Agent自行判断等待时长是否合理并给出tail -f实时跟踪的逃生通道。五、在完整生命周期中的位置与配套命令/tech:worktree-status不是孤立命令它嵌在 tech/ 目录 定义的 worktree 生命周期中创建/tech:worktree feature/new-filter通过git worktree add在repo根/.worktrees/feature-new-filter建立目录分支名中/转-避免嵌套并校验.gitignore已包含.worktrees/fail-fast——当前仓库 .gitignore 中确有.worktrees/条目与脚本要求一致查询/tech:worktree-status feature/new-filter本文——非阻塞地轮询后台检查状态移除/清理/tech:remove-worktree负责单点移除含未合并分支二次确认、永不删除 main/master等安全约束/tech:clean-worktrees支持--dry-run批量清理已合并 worktree。创建端还要求 Claude Code 会话在切换 worktree 后重启/exit→cd .worktrees/{name}→claude使 Agent 的上下文与代码目录一致状态查询则无此要求可在任意会话中执行因为它只读/tmp日志。六、设计要点总结从这份命令定义可以提炼出 rtk 项目为 Agent 协作场景沉淀的一套轻量工作流模式文件即状态后台任务进度完全物化为/tmp/worktree-cargo-check-sanitized-branch.log创建端写、查询端读无需守护进程、端口或数据库天然适合终端环境与 LLM Agent 调用确定性命名 可自查的失败输出查询失败时列出全部现存日志ls -1 /tmp/worktree-cargo-check-*.log把名字对不上这一最常见错误变成可自助修复marker 行状态机 兜底全量转储三枚 emoji marker 覆盖通过/失败/进行中第四种未知状态不猜测、直接打印全量日志输出即摘要错误只取行首error前 20 条、日志只扫前 1000 行控制信息量与 token 开销与 rtk 作为压缩 CLI 输出以节省 LLM token的项目定位一脉相承命令间互指创建命令输出里直接打印/tech:worktree-status branch查询指令把工作流的下一步交给用户显式执行而非隐式等待。适用前提与限制该命令是 Claude Code 斜杠命令定义由 Agent 解释执行其中内嵌的 bash 脚本依赖 bash、git、cargo 环境且日志位于/tmp系统重启或/tmp清理后状态不可查状态判定时间戳为HH:MM:SS当天时间跨天运行不区分日期。旧版命令 .claude/commands/worktree-status.md 与tech/新版在日志前缀和 marker 格式上不兼容使用时应以.claude/commands/tech/目录下的命令集为准。【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考