CodeBuddy 的后台任务机制允许你在编辑器里直接执行 shell 命令、运行测试、启动本地服务，但如果多个任务同时发起，就很容易出现命令冲突。典型表现是某个任务生成的文件被另一个任务覆盖，或者同一个端口被重复绑定，导致服务异常退出。要解决这个问题，不能只靠简单地把任务间隔拉大，而是需要从队列、锁、文件操作三个层面建立完整的管理策略。
一、命令冲突从哪来：三个最容易踩坑的场景
最常见的冲突发生在共享工作区。CodeBuddy 的后台任务默认会在当前项目根目录下执行命令，多个任务可能同时读写同一个文件。比如任务 A 正在生成构建产物 dist/bundle.js，任务 B 同时也在执行清理脚本，把 dist 目录整个删掉，结果 A 写到一半就被删掉或者出现文件不完整。这种竞争条件不会每次都复现，往往表现为偶发性的构建失败或运行时报错。
第二个高频场景是端口占用。如果你同时启动了多个本地开发服务，而它们都尝试监听 3000 端口，后启动的任务会直接报 EADDRINUSE 错误。即使改成随机端口，前端代理配置、环境变量里的 API 地址也很难同步修改，最终导致联调失败。第三个容易被忽略的触发点是环境变量污染。后台任务可能共享同一个进程环境，某个任务修改了 PATH 或者设置了全局变量，后续任务读取到的值和预期不一致，命令行为就会变得非常奇怪。
二、任务队列加锁：用简单脚本实现串行化
解决命令冲突的第一步是把任务变成串行执行。Linux 下的 flock 命令可以很方便地实现文件锁，保证同一时间只有一个 CodeBuddy 后台任务在运行。下面这个包装脚本会先获取项目根目录下的 .codebuddy.lock 文件锁，拿到锁之后再执行真正的命令，执行完毕自动释放。
#!/bin/bash
# 用法: ./serial_run.sh "npm run build"
LOCK_FILE="/tmp/codebuddy_task.lock"
exec 200>"$LOCK_FILE"
flock -n 200 || { echo "另一个任务正在执行，等待锁..."; flock 200; }
eval "$1"
flock -u 200
这段脚本的核心是 flock 的文件描述符锁。如果锁已经被占用，flock -n 会立即返回失败，此时脚本进入阻塞等待，直到上一个任务释放锁。这样可以避免两个命令同时修改同一批文件。缺点是所有任务都只能排队执行，如果某个任务执行时间很长，后面的任务就会积压。因此实际使用时，可以按任务类型分成不同的锁文件，比如构建锁、测试锁、服务启动锁，这样互相不冲突的任务仍然可以并行。
如果你用的是 Windows 环境，可以用 PowerShell 的互斥体实现类似效果。原理相同，都是通过操作系统提供的同步原语来保证临界区只有一个执行者。需要注意的是，锁文件要放在固定且可写的路径，避免任务在不同工作目录下找不到同一个锁文件导致锁失效。
三、文件写入和进程隔离：原子操作代替直接覆盖
串行队列虽然能解决并发写冲突，但如果任务内部本身就有多个步骤，或者任务之间需要共享只读资源，还需要在文件写入层面做更细的控制。一个很实用的做法是原子写入：命令先写入临时文件，写入成功后再用 rename 或 mv 一次性替换目标文件。这样即使任务中途被中断，也不会留下半成品文件，其他任务读取时要么看到旧版本，要么看到完整的新版本，不会出现内容错乱。
#!/bin/bash # 原子写入构建结果 OUTPUT="dist/bundle.js" TMP_FILE="dist/.bundle.js.tmp" npm run build -- --outfile "$TMP_FILE" mv -f "$TMP_FILE" "$OUTPUT"
这种方式的另一个好处是，如果构建过程中发现冲突，可以直接删除临时文件而不影响现有的稳定版本。配合 trap 命令清理临时文件，脚本会变得更加健壮。进程隔离同样重要，尤其是启动本地服务这类长时间运行的任务。建议通过 setsid 或 nohup 让服务脱离当前终端会话，并将进程 ID 写入独立文件，这样后续要停止服务时可以直接 kill 对应进程，而不会误杀其他任务。
针对端口冲突，可以在启动服务前先检测端口占用情况，例如用 lsof -i:3000 或 netstat -ano | findstr :3000 判断端口是否被占用，然后再决定是用新端口还是等待重试。如果是在 CI 环境里跑 CodeBuddy 任务，建议为每个任务分配独立的临时目录，并在任务结束时自动清理，这样共享工作区里就不会积累大量冲突文件。
四、在CodeBuddy中配置串行执行策略与自动重试
大部分代码助手工具都允许自定义命令包装，CodeBuddy 也可以通过修改项目配置文件来指定后台任务的默认执行方式。假设项目根目录下有一个任务配置，我们可以给所有会修改文件的命令统一加上锁包装。下面是一个示例配置，它把构建和部署命令都指向同一个串行脚本。
{
"backgroundTasks": {
"serialize": true,
"lockFile": ".codebuddy/task.lock",
"retryCount": 3,
"retryDelayMs": 2000,
"commands": {
"build": {
"cmd": "npm run build",
"waitFor": ["clean"]
},
"clean": {
"cmd": "npm run clean",
"atomic": true
}
}
}
}
这个配置里的 serialize 开关可以强制所有后台任务串行执行，retryCount 和 retryDelayMs 则定义了命令因冲突失败后的重试次数和间隔。waitFor 字段表示 build 任务必须等 clean 任务完成后才能开始，这样可以显式声明任务依赖，避免靠运气决定执行顺序。即使 CodeBuddy 本身没有内置这些字段，你也可以把类似的逻辑包装成一个自定义 shell 脚本，在编辑器里把后台任务指向这个脚本即可。
自动重试是处理偶发冲突的有效手段。很多时候命令失败并不是代码有问题，而是刚好撞上了另一个任务的修改窗口。加上重试逻辑后，第一次失败会等待一小段时间再执行，往往就能成功。重试时要注意不能无脑重复，应该检查具体错误信息，如果是端口占用可以尝试换端口，如果是文件被锁则等待后重试，如果是代码语法错误则立即停止，避免浪费资源。
五、监控与回滚：冲突发生后的兜底方案
再完善的预防措施也不能保证 100% 不冲突，所以需要给每个后台任务留好日志。建议把命令的标准输出和标准错误分别重定向到带时间戳的日志文件，这样出问题时可以快速定位是哪个任务在什么时间修改了哪些文件。日志路径要避开共享工作区，防止日志文件本身成为竞争资源。
#!/bin/bash
TASK_NAME="$1"
LOG_DIR=".codebuddy/logs"
mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/${TASK_NAME}_$(date +%Y%m%d_%H%M%S).log"
"${@:2}" > "$LOG_FILE" 2>&1
echo "任务完成，日志保存在 $LOG_FILE"
有了日志还不够，关键的生成物最好保留最近几个版本。比如每次构建前先把旧的 dist 目录重命名为 dist.bak.时间戳，构建成功后再删除旧的备份。这样一旦发现新版本有命令冲突导致的异常，可以快速回滚到上一个可用版本。对于数据库迁移这类高风险操作，更要提前备份相关表结构或数据，避免冲突造成不可逆的损失。
最后，建议定期检查后台任务列表，及时清理已经完成但未释放资源的僵尸任务。有些任务可能因为进程组没有正确回收而一直占用锁文件，导致后续任务一直等待。可以在 CodeBuddy 的任务面板里手动结束这些任务，或者写一个定时脚本清理超过一定时间没有心跳的锁文件和临时目录。通过队列、锁、原子写入、进程隔离和监控回滚这五层防护，CodeBuddy 的后台任务基本可以避免命令冲突，即使偶发失败也能快速恢复。
