Atomcode Delegation

通过 atomcode CLI 无头模式委派独立代码任务，支持单任务/批量并发、监控、超时、续会话。

AtomCode Delegation Skill

通过 atomcode CLI 无头模式委派独立代码任务。

触发条件

当用户说以下关键词时激活：

• "用 atomcode 修..." / "atomcode 改..."
• "委派给 atomcode"
• "atomcode 任务"
• 批量代码修改任务需要并行执行

前置检查

bash

command -v atomcode >/dev/null 2>&1 || { echo "ERROR: atomcode not found in PATH"; exit 1; }
mkdir -p /tmp/atomcode-tasks /tmp/prompts

核心命令

bash

atomcode -C "<workdir>" \
  --prompt-file "<prompt_file>" \
  -y \
  --provider "<provider>" \
  --max-turns <N>

提示：优先用 --prompt-file 而非 -p "$(cat ...)"：

• 不丢失末尾换行、不触发 shell 分裂/通配符展开、不截断内容

参数速查

参数	必选	说明
-C <dir>	✅	工作目录（务必引号包裹）
--prompt-file <path>	✅	从文件读取 prompt（推荐）
-p <prompt>	✅	直接传 prompt 字符串（替代 --prompt-file）
-y	✅	跳过权限确认（后台任务必加，否则挂起）
--provider	✅	模型后端（见下方 Provider 选择）
--max-turns	✅	回合限制（简单=12，复杂=20-30）
--model	可选	覆盖 provider 中的 model 名称
--engine	可选	引擎选择：v2（默认）/ v1（legacy 回退）
-c	可选	续接上一次中断的会话
--dev	推荐	禁用自动更新（批量任务推荐）
-v	可选	stderr 显示工具调用、token 用量、回合摘要
--no-telemetry	可选	禁用本次调用的遥测
--lang <lang>	可选	设置界面语言：en / zh-CN / zh
--disable-tools <names>	可选	排除指定的工具（逗号分隔）

Provider 选择

Provider 名称来自 ~/.atomcode/config.toml 中 [providers.*] 的标识符。

Provider	模型	场景
AtomGit-deepseek-v4-flash	deepseek-v4-flash	代码修改、bug fix、重构（默认，100 万 token 窗口）
AtomGit-GLM-5.2	GLM-5.2	复杂架构设计、多文件协调（20 万 token）
AtomGit-Qwen-Qwen3-VL-8B-Instruct	Qwen/Qwen3-VL-8B-Instruct	图像理解、视觉分析任务（6.4 万 token）

标准流程

1. 准备 prompt

bash

cat > "/tmp/prompts/<task_id>.txt" << 'PROMPT'
# 任务标题
## 背景
问题描述、涉及的代码位置、预期行为 vs 实际行为。
## 修改要求
1. 先 read 相关文件，理解当前实现
2. 具体修改内容（不要只说"修复 bug"，要说明改什么、怎么改）
3. 保持现有代码风格和注释
## 约束
- 不要新增不必要的依赖
- 不要修改未在要求中列出的文件
## 验证
python3 -c "import ast; ast.parse(open('<file>').read())"
PROMPT

if [ ! -s "/tmp/prompts/<task_id>.txt" ]; then
  echo "ERROR: prompt file is empty or was not written"; exit 1
fi

Prompt 规范：

原则	说明
角色设定	prompt 开头给 agent 一个角色
先读后改	要求 agent 先 read_file 再着手修改
具体不要模糊	❌ "修复性能" → ✅ "将 list 推导替换为 generator"
约束在前	明确"不改什么"比"改什么"更重要
验证命令附后	末尾嵌可运行的验证命令
--prompt-file 优先	比 -p "$(cat ...)" 更安全（无截断风险、保留末尾换行）

2. 验证工作环境

bash

if [ ! -d "<workdir>" ]; then
  echo "ERROR: workdir <workdir> does not exist"; exit 1
fi
cd "<workdir>"
git rev-parse --git-dir >/dev/null 2>&1 || echo "WARNING: not a git repo"

3. 启动任务

bash

# 单任务 —— 保存 PID 以便监控和清理
LOG="/tmp/atomcode-tasks/<task_id>.log"
atomcode -C "<workdir>" \
  --prompt-file "/tmp/prompts/<task_id>.txt" \
  -y --dev \
  --provider AtomGit-deepseek-v4-flash \
  --max-turns 12 \
  > "$LOG" 2>&1 &
ATOMCODE_PID=$!

# 批量并行（≤4 并发保守；≤6 在 RAM ≥16GB 可尝试）
declare -A TASK_PIDS
for tid in r1 r2 r3 r4; do
  LOG="/tmp/atomcode-tasks/${tid}.log"
  atomcode -C "<workdir>" \
    --prompt-file "/tmp/prompts/${tid}.txt" \
    -y --dev \
    --provider AtomGit-deepseek-v4-flash \
    --max-turns 12 \
    > "$LOG" 2>&1 &
  TASK_PIDS[$tid]=$!
done

4. 监控完成

bash

# 单个任务
wait $ATOMCODE_PID; EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ] && grep -q "\[done\]" "$LOG" 2>/dev/null; then
  echo "✅ completed"
elif [ $EXIT_CODE -eq 0 ]; then
  echo "⚠️ exit=0 but no [done] — check git diff for partial changes"
else
  echo "❌ FAILED (exit=$EXIT_CODE)"; tail -20 "$LOG"
fi

# 批量检查（精确 PID 匹配，避免 pgrep 子串竞态）
for tid in r1 r2 r3 r4; do
  PID=${TASK_PIDS[$tid]}
  LOG="/tmp/atomcode-tasks/${tid}.log"
  if kill -0 "$PID" 2>/dev/null; then
    echo "⏳ ${tid}: PID=$PID running ($(wc -l < "$LOG") lines)"
  else
    wait "$PID" 2>/dev/null; EC=$?
    if [ $EC -eq 0 ] && grep -q "\[done\]" "$LOG" 2>/dev/null; then
      echo "✅ ${tid}: $(grep '\[done\]' "$LOG" | tail -1)"
    elif [ $EC -eq 0 ]; then
      echo "⚠️ ${tid}: exit=0, no [done]"
    else
      echo "❌ ${tid}: exit=$EC"
    fi
  fi
done

完成检测优先级：

1. [done] marker 且 exit=0 → 确认完成
2. exit=0 但无 [done] → --max-turns 耗尽，检查 git diff
3. exit≠0 → 失败，查看日志尾部
4. 进程仍在运行 → 继续等待或触发超时

5. 超时处理

bash

TIMEOUT=300
(
  sleep $TIMEOUT
  if kill -0 $ATOMCODE_PID 2>/dev/null; then
    echo "TIMEOUT: killing PID=$ATOMCODE_PID after ${TIMEOUT}s"
    kill -TERM $ATOMCODE_PID; sleep 5
    kill -0 $ATOMCODE_PID 2>/dev/null && kill -9 $ATOMCODE_PID
  fi
) &
WATCHDOG_PID=$!
# ⚠️ 任务完成后清理: wait $ATOMCODE_PID; kill $WATCHDOG_PID 2>/dev/null

6. 验证结果

bash

cd "<workdir>"
python3 -c "
import ast, sys
for f in ['file1.py', 'file2.py']:
    try:
        ast.parse(open(f).read()); print(f'✅ {f}')
    except SyntaxError as e:
        print(f'❌ {f}: {e}'); sys.exit(1)
"
git diff --stat

失败处理

症状	原因	处理
进程卡住无输出	卡在 shell tool	kill <PID> 并重试，或加 --engine v1
无 [done] 但 exit=0	--max-turns 耗尽	检查 git diff；用 -c 续接继续
语法错误	输出不完整	手动修复或降低 --max-turns 重试
token 超限	任务太复杂或 prompt 过长	拆分为更小的子任务
v2 引擎异常	新版引擎 bug	加 --engine v1 回退 legacy
atomcode 不可用	未安装或不在 PATH	检查 command -v atomcode
prompt 为空	heredoc 写入失败	检查文件权限、磁盘空间

注意事项

• 原子化: 每个任务只改独立文件集，不互相依赖
• max-turns 必填: 防止无限循环
• -y 务必加: 后台任务无 stdin，不加 -y 会永久挂起
• --dev 推荐: 批量任务防自动更新打断
• 续会话用 -c: atomcode -C <dir> -c -y --max-turns 12 续接中断任务
• --prompt-file 优先: 比 -p "$(cat ...)" 更安全
• PID 追踪: 始终保存 $!，不用 pgrep 子串匹配
• 引号保护: 所有路径变量用双引号包裹
• 超时守护: 后台任务务必配超时
• 清理: rm -f /tmp/atomcode-tasks/<task_id>.log /tmp/prompts/<task_id>.txt

End-to-End 示例

bash

TASK_ID="fix_auth_bug"; WORKDIR="$HOME/code/my-project"
command -v atomcode >/dev/null || exit 1
mkdir -p /tmp/atomcode-tasks /tmp/prompts

cat > "/tmp/prompts/${TASK_ID}.txt" << 'PROMPT'
# 修复 auth.py token 过期判断
## 修改要求
1. read auth.py 确认当前实现
2. 修改 check_token(): 比较 current_time 与 token.expires_at
3. 输出 git diff --stat
## 验证
python3 -c "import ast; ast.parse(open('auth.py').read())"
PROMPT

[ -d "$WORKDIR" ] || exit 1
LOG="/tmp/atomcode-tasks/${TASK_ID}.log"
atomcode -C "$WORKDIR" --prompt-file "/tmp/prompts/${TASK_ID}.txt" -y --dev \
  --provider AtomGit-deepseek-v4-flash --max-turns 12 > "$LOG" 2>&1 &
PID=$!
(sleep 300; kill -TERM $PID 2>/dev/null; sleep 5; kill -9 $PID 2>/dev/null) &
WD_PID=$!
wait $PID; EXIT=$?; kill $WD_PID 2>/dev/null
if [ $EXIT -eq 0 ]; then
  echo "✅ $TASK_ID"; cd "$WORKDIR" && git diff --stat
else
  echo "❌ $TASK_ID: exit=$EXIT"; tail -10 "$LOG"
  echo "💡 续接: atomcode -C $WORKDIR -c -y --max-turns 8 --provider AtomGit-deepseek-v4-flash"
fi
rm -f "$LOG" "/tmp/prompts/${TASK_ID}.txt"