Task Delegate

Task Delegate Skill

Environment Routing（环境分流）

[!IMPORTANT] 本 skill 根据运行环境自动选择执行路径。

CC-Native 路径（仅 Claude Code 环境）

当你是 Claude Code 且任务委派目标是 Claude 模型时，直接使用原生 Agent 工具：

Agent(
  subagent_type="general-purpose",   # 或 "Explore"（只读研究）/ "Plan"（方案设计）
  prompt="...",                       # 传递 WHAT + WHERE，不传递 HOW（同下方 Step 1 原则）
  model="sonnet",                    # 可选：sonnet（默认）、opus、haiku
  isolation="worktree",              # 可选：需要隔离时使用
  run_in_background=true,            # 可选：长任务异步执行
)

CC-Native 路径遵循的原则：

• Prompt 编写原则同 Step 1（传递 WHAT + WHERE，不传递 HOW）
• Scout-Before-Execute 模式 → 先用 subagent_type="Explore" 侦察，再用 "general-purpose" 执行
• 验证原则同 Step 4（独立验证 executor 产出）
• 不需要：写 prompt.txt、tmux session、polling loop、解析 stream-json

何时仍走 tmux 流程：

• 用户明确指定非 Claude 后端（"用 Codex"、"交给 Gemini"、"DeepSeek"）
• Pipeline/headless 场景（issue_watcher 等自动化调用）
• 需要 execution_record 持久化记录或 Langfuse tracing

AG 的默认身份是 orchestrator（编排者），不是 coder。 遇到编码任务，AG 的第一反应是委派，不是自己写。

When to Trigger（AG + tmux 流程）

默认行为 = 委派。 满足任意一条即应委派：

• 任务涉及编写或修改应用代码（新功能、bug 修复、重构）
• 任务涉及多文件协调编辑
• 任务预计需要 10 分钟以上的编码工作
• 用户明确要求委派（"用 CC 写"、"交给 Codex"等）

例外 — AG 可以自己做的： 改一行配置、简单重命名/移动文件、写验证脚本、编排脚本、纯文档编辑。

判断标准：如果需要理解代码逻辑才能修改 → 委派。

Backend Selection

Scout-Before-Execute（侦察-再-执行）

[!IMPORTANT] 把 subagent 当作对代码细节非常了解的技术骨干。 AG 不理解代码，不应该自己 view_file 去读代码然后设计方案。需要代码层面的判断时，直接问 subagent。

两种模式：

Scout 任务的 prompt 模板：

# Task: Analyze {scope} for {goal}

## Objective
分析 {project} 中 {scope} 的当前实现，回答以下问题：
1. {specific question about the codebase}
2. {specific question about feasibility}
3. 你认为实现 {goal} 的最佳方案是什么？

## Context
- Project root: {path}
- Focus area: {key files/modules}

## Output
把分析结果写入 {project}/scout_report.md。不要做任何代码修改。

Scout 回来后 AG 做什么：

1. 读 scout_report.md
2. 基于 CC 的分析做编排决策（拆任务？选 backend？需要用户确认？）
3. 写精简的执行 prompt（不重复 CC 已知的细节）

判断标准： 如果 AG 写 prompt 时想要 view_file 看代码 → 不要看，发 scout 任务让 CC 看。

Step 1: Write Prompt

写 ~/.task-delegate/{task_id}/prompt.txt。

核心原则：传递 WHAT + WHERE，不传递 HOW。 Executor 有极强的代码理解和方案设计能力，AG 不要替它设计实现方案。

[!CAUTION] AG Plan ≠ CC Prompt。 implementation_plan.md 是给人审批的设计文档，可以包含技术细节。prompt.txt 是给 executor 的任务描述，只传目标和约束。绝对不能把 plan 直接复制进 prompt。

# Task: {one-line description}

## Objective
{用户的原始需求，用 AG 的理解清晰重述。说清楚「要达成什么效果」。}

## Context
- Project root: {absolute path}
- Key files: {仅列出与任务直接相关的文件，附一句话说明}

## Constraints (仅列出 executor 无法自行推断的约束)
- Do NOT modify: {禁止修改的文件/模块}

## Self-Test
{exact test/build command}

AG 应该提供：用户需求和意图、项目路径和关键文件、禁止修改区域、验证命令、executor 无法自行获取的背景知识。 AG 不应该提供：具体代码修改方案、函数签名设计、实现步骤、代码风格规范（executor 自己看）、能从代码中读出的技术栈信息。

Prompt 大小基准：好的 prompt 在 1.5-3KB。超过 4KB 说明可能 over-specified。task_launch.sh 会在 >4KB 时警告，>6KB 时红色告警。

Prompt Anti-Patterns ⛔

❌ 在 prompt 中写代码片段或函数体
   → executor 自己设计实现

❌ 在 prompt 中指定函数签名 ("def foo(bar: str) -> bool")
   → executor 读代码后自行决定 API

❌ 在 prompt 中列实现步骤 ("Step 1: modify X, Step 2: add Y")
   → 只给目标，不给路径

❌ 在 prompt 中指定行号 ("修改 line 42")
   → 代码会变，行号会失效

❌ 把 implementation_plan.md 的技术方案塞进 prompt
   → plan 给人看，prompt 给 executor 看

✅ 好的 prompt: "实现 per-stock PnL 细分，关键文件 backtest_report.py"
✅ 好的 prompt: "修复 Issue #55 的 4 个 deliverable（详见 issue body）"
❌ 差的 prompt: "Rewrite cdp_type_text() to use Input.insertText, add cdp_press_key(page, key, code='', delay_ms=20)..."

Task ID 格式：YYYYMMDD_HHMM_{short_desc}

Step 2: Launch

TASK_ID="{YYYYMMDD_HHMM}_{short_desc}"
mkdir -p ~/.task-delegate/${TASK_ID}
# Write prompt.txt (use write_to_file tool, NEVER send-keys)

SKILL_DIR=$(dirname $(readlink -f $(find /home/lgj/agent-skills/task-delegate -name task_launch.sh)))
bash "$SKILL_DIR/task_launch.sh" ${TASK_ID} {project_dir} --backend cc

# Resume prior session:
bash "$SKILL_DIR/task_launch.sh" ${TASK_ID} {project_dir} --backend cc --resume-session {prior_session_id}

Backends: cc, codex, gemini, deepseek

Launcher 会创建 tmux session task-{task_id}，输出流到 live.log，完成后写 execution_record.json。

Step 3: Monitor (MANDATORY — DO NOT YIELD)

Launch 后 AG 在同一个 turn 内立刻开始 polling，不 yield 控制权。

Polling Loop（每 60-90s 执行一次，直到完成）：

bash /home/lgj/agent-skills/task-delegate/scripts/task_status.sh {task_id}

这个脚本会自动：解析 live.log 的 stream-JSON → 提取最近的 subagent 动作（文件编辑、命令执行）→ 显示最新 assistant 文本 → 检测错误和卡住 → 检查是否已完成。

AG 拿到输出后：把进度摘要直接写在对话中 + 更新 task_boundary TaskStatus，然后等 60-90s 再查一次。

输出示例：

⏳ RUNNING | log_lines=639 | last_update=12s ago
🔧 Recent actions (15 total):
   ✏️  edit_file: pipeline.py
   🔧 bash: pytest tests/ -v
   ✏️  edit_file: config.yaml
💬 Latest assistant text:
   Adding input validation to the pipeline processing function...

✅ COMPLETED | status=success | duration=331s | exit_code=0

异常处理： 输出含 ⚠️ WARNING（卡住）或 ❌ ERRORS → 用 Ctrl+C 干预：

tmux send-keys -t task-{task_id} C-c

Step 4: Verify (MANDATORY)

任务完成后 AG 立即执行：

# Extract output
bash /home/lgj/agent-skills/task-delegate/scripts/task_extract.sh {task_id} \
  --output-file ~/.task-delegate/{task_id}/output.md

# Check status
cat ~/.task-delegate/{task_id}/execution_record.json

# Review changes (READ-ONLY — 只看，绝不改)
cd {project_dir} && git diff --stat

# Run self-test from prompt.txt

AG 必须读取并理解 executor 产出，独立验证，然后向用户汇报：产出摘要、验证结果、发现的问题。

[!CAUTION] 禁止破坏性 Git 操作 — HARD RULE

AG 在验证阶段（以及任何阶段）绝对禁止执行以下命令：

• git checkout -- {files} — 会删除未提交修改
• git restore {files} — 同上
• git reset --hard — 会丢失所有未提交修改
• git clean -fd — 会删除未跟踪文件
• git stash — 会隐藏他人的修改

git diff --stat 中看到的不属于当前任务的修改，是其他并行任务或用户的工作产出，不是需要清理的垃圾。AG 无权判断这些修改是否"相关"，更无权删除。

如果 AG 认为有文件需要 revert，必须向用户报告并等待指示。

Verification Anti-Patterns ⛔

❌ 看到 git diff 中有"不相关"的修改就 git checkout 掉
   → 那些修改属于其他任务，AG 无权判断和删除

❌ 用 git restore / git reset 来"清理"工作区
   → 可能抹掉其他 agent 数小时的工作

❌ 假设 git diff 中的所有修改都是当前任务的产出
   → 多任务并行时，工作区有多个来源的修改

✅ 只用 git diff --stat 查看变更概况
✅ 向用户汇报看到的所有修改，让用户决定处理方式
✅ 如果需要区分当前任务的修改，让用户确认

Step 5: Follow-up

AG 主动识别后续行动：需要进一步处理？有遗留 TODO？需要集成到其他产物？需要启动下一个任务？

AG 的工作在用户确认后续方向后才算完成。

Reference

IPC Protocol

~/.task-delegate/{task_id}/
├── prompt.txt              ← AG → Backend
├── runner.sh               ← Auto-generated
├── live.log                ← Real-time output
└── execution_record.json   ← Completion metadata

Backend CLI

CC Max（月付）用于日常开发；CC API（按量）用于批量任务，需 --api-billing + --max-budget-usd。

Extracting Output

bash /home/lgj/agent-skills/task-delegate/scripts/task_extract.sh {task_id}
bash /home/lgj/agent-skills/task-delegate/scripts/task_extract.sh {task_id} --output-file /path/to/output.md
bash /home/lgj/agent-skills/task-delegate/scripts/task_extract.sh {task_id} --result-only

live.log 包含超长 JSON 行（50K+ chars），不要用 jq 逐行解析，task_extract.sh 使用 Python json 模块。

execution_record.json

关键字段：task_id, backend, status, exit_code, duration_seconds, started_at, finished_at, prompt_bytes。 可选字段：role, source_conversation, session_id（用于 --resume-session），resumed_from。

Multi-Role Dispatch

TASK_ID="YYYYMMDD_HHMM_{desc}_{role}"
mkdir -p ~/.task-delegate/${TASK_ID}
bash /home/lgj/agent-skills/task-delegate/scripts/task_launch.sh \
  ${TASK_ID} ${PROJECT_DIR} --backend cc --role {role} --source {conversation_id} --session {session_name}

Retrospective

python3 /home/lgj/agent-skills/task-delegate/scripts/ag_retro.py             # last 7 days
python3 /home/lgj/agent-skills/task-delegate/scripts/ag_retro.py --days 3 --executor cc
python3 /home/lgj/agent-skills/task-delegate/scripts/ag_retro.py --json

Integration: panel-discussion

panel_launch.sh is a wrapper around task_launch.sh. Panel records stored in ~/.task-delegate/ with IDs like YYYYMMDD_HHMM_panel_rN_agent.

Troubleshooting