Skill: inuyashayang/worktree-agents (version 1.0.0)

--- name: worktree-agents description: > 使用 git worktree 隔离多个 Claude Code 实例，由 OpenClaw 主控器并行调度完成同一项目的不同模块。 适用场景：将一个编码项目拆分为独立子任务，让多个 Claude Code 实例并行实现，最后合并 PR。 触发条件：用户要求"多个 Agent 协作"、"并行完成项目"、"worktree 实验"、"多 Agent 编排"时激活。 --- # Worktree Agents — 多 Agent 编排技能 ## 前提条件 - Claude Code 二进制：`/mnt/c/Users/Inuyasha/.local/bin/claude.exe`（Windows 侧，可从 WSL 调用） - GitHub Token：从 `~/.openclaw/openclaw.json` 读取（`skills.entries["gh-issues"].apiKey`） - 目标 Git 仓库已存在（本地 + GitHub 远端） ## 核心工作流（5 步） ### 步骤 1：明确任务拆分 在开始前，必须确定： - **每个 Agent 的任务**（1-3 个具体函数/文件） - **文件所有权**（每个文件只允许一个 Agent 写） - **并行 or 串行**（有依赖关系的任务需串行） 详见 `references/task-decomposition.md` ### 步骤 2：创建 Worktree ```bash bash scripts/setup_worktrees.sh <repo_dir> <worktrees_base_dir> <agent-a> <agent-b> ... ``` 输出格式：`agent_name:worktree_path:branch_name`（每行一个 Agent） ### 步骤 3：并行启动 Claude Code 用 exec(background=true) 并行启动多个 Agent，每个调用： ```bash bash scripts/orchestrate.sh \ <repo_dir> \ /mnt/c/Users/Inuyasha/.local/bin/claude.exe \ <agent_name> \ <worktree_path> \ <branch> \ "<task_prompt>" \ /tmp/<agent_name>.log ``` Task prompt 模板： ``` 你是 <AgentName>，只能修改 <file1>, <file2>，不得碰其他文件。 任务：<具体实现要求，含函数签名、异常处理、docstring> 完成后执行：git add -A && git commit -m "<commit message>" 只输出 done。 ``` ### 步骤 4：监控 + 收尾 使用 `process(poll)` 等待所有 Agent 完成，然后检查： ```bash cat /tmp/<agent_name>.log | grep "AGENT_DONE" ``` 如果 Agent 没有自行 commit（常见于第一次），脚本会自动收尾。 ### 步骤 5：推送 PR + 合并 ```bash bash scripts/push_and_pr.sh \ <repo_dir> <gh_token> <owner/repo> <agent_name> <worktree_path> <branch> main ``` 验证通过后通过 GitHub API 合并： ```bash curl -s -X PUT \ -H "Authorization: Bearer $GH_TOKEN" \ -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/<owner/repo>/pulls/<pr_number>/merge" \ -d '{"merge_method": "squash"}' ``` ## 已知限制与解决方案 **WSL 写文件被沙盒阻止** → Claude Code 必须加 `--dangerously-skip-permissions` **Codex `.cmd` 在 WSL 下无法运行** → 使用 `--dangerously-skip-permissions` 的 Claude Code 替代，或在 WSL 安装原生 codex：`npm install -g @openai/codex` **主仓库 git pull 权限错误（NTFS）** → worktree 放在 WSL 本地文件系统（`~/projects/worktrees/`），不放 `/mnt/c/` **Agent 没有自行 commit** → `orchestrate.sh` 脚本会检测未提交变更并自动 commit ## 环境变量获取 ```bash CLAUDE_BIN="/mnt/c/Users/Inuyasha/.local/bin/claude.exe" GH_TOKEN=$(cat ~/.openclaw/openclaw.json | jq -r '.skills.entries["gh-issues"].apiKey') ``` ## 使用 Codex 替代 Claude Code（更便宜） Codex 已安装在 WSL，使用自建代理： ```bash export OPENAI_API_KEY="[REDACTED_SECRET]" export OPENAI_BASE_URL="http://152.53.52.170:3003/v1" CODEX_BIN="$HOME/.npm-global/bin/codex" ``` 调用方式（替换 orchestrate.sh 里的 CLAUDE_BIN 部分）： ```bash "$CODEX_BIN" exec --full-auto "$TASK_PROMPT" # 或无沙盒更快： "$CODEX_BIN" --yolo "$TASK_PROMPT" ``` 注意：`OPENAI_BASE_URL` 必须在调用前 export，否则 Codex 会尝试连官方 OpenAI。

path: references/task-decomposition.md
content: # Worktree Agents — 任务分解参考

## 文件所有权原则

多 Agent 并行时最大的风险是文件冲突。分配任务前必须明确"谁能碰哪些文件"。

**黄金规则：每个文件只有一个 Agent 拥有写权限。**

### 典型分解方式

按层分解（前后端分离项目）：
- Agent A → src/api/ (后端接口)
- Agent B → src/ui/ (前端组件)
- Agent C → tests/ (测试)

按功能分解（工具库项目）：
- Agent A → src/math_utils.py
- Agent B → src/string_utils.py
- Agent Review → 只读审查，不写代码

按阶段分解（流水线）：
- Agent A 先跑完，产出 INTERFACE.md
- Agent B 读取 INTERFACE.md，再开始实现（需要串行，不适合并行）

## Claude Code 调用方式

### 非交互单次模式（推荐）

```bash
"$CLAUDE_BIN" --dangerously-skip-permissions --print -p "任务描述" > output.log 2>&1
```

- `--dangerously-skip-permissions`：允许在 WSL 路径写文件（必须加）
- `--print`：非交互输出模式
- `-p`：直接传入 prompt，不从 stdin 读

### Prompt 设计要点

1. 明确文件所有权边界：`只能修改 src/api.py 和 tests/test_api.py，不得碰其他文件`
2. 明确完成标准：`完成后执行 git add -A && git commit -m "..."，只输出 done`
3. 避免歧义：`实现 multiply(a, b) 返回乘积，divide(a, b) b=0 时抛 ValueError`

## Agent 并发数建议

| 项目规模 | 推荐并发数 | 说明 |
|---------|----------|------|
| 小型 (<5 文件) | 2 | 降低冲突风险 |
| 中型 (5-20 文件) | 3-4 | 按模块分工 |
| 大型 (>20 文件) | 4-6 | 需要严格的文件所有权规划 |

## Worktree 清理

实验完成后清理 worktree：

```bash
cd <repo_dir>
git worktree remove --force <worktree_path>
git branch -d <branch_name>
```


path: scripts/orchestrate.sh
content: #!/usr/bin/env bash
# worktree-agents/scripts/orchestrate.sh
# OpenClaw 多 Agent Worktree 编排脚本
#
# 用法:
#   orchestrate.sh <repo_dir> <claude_bin> <agent_name> <worktree_path> <branch> <task_prompt> <log_file>
#
# 本脚本由 OpenClaw 主控器为每个 Agent 单独调用（并行），执行以下操作:
#   1. 进入 worktree 目录
#   2. 以 --dangerously-skip-permissions --print 模式运行 Claude Code
#   3. 捕获输出到 log_file
#   4. 完成后 git add -A && git commit

set -euo pipefail

REPO_DIR="$1"
CLAUDE_BIN="$2"
AGENT_NAME="$3"
WORKTREE_PATH="$4"
BRANCH="$5"
TASK_PROMPT="$6"
LOG_FILE="$7"

echo "[$(date '+%H:%M:%S')] $AGENT_NAME starting in $WORKTREE_PATH" | tee "$LOG_FILE"

cd "$WORKTREE_PATH"

# 运行 Claude Code
"$CLAUDE_BIN" --dangerously-skip-permissions --print -p "$TASK_PROMPT" \
  >> "$LOG_FILE" 2>&1

EXIT_CODE=$?

echo "[$(date '+%H:%M:%S')] $AGENT_NAME claude exited with code $EXIT_CODE" | tee -a "$LOG_FILE"

# 检查是否有需要提交的文件
if git diff --quiet && git diff --staged --quiet; then
  echo "[$(date '+%H:%M:%S')] $AGENT_NAME: no changes to commit" | tee -a "$LOG_FILE"
else
  # 如果 Claude 没有自己 commit，帮它收尾
  if git status --porcelain | grep -q .; then
    git add -A
    git commit -m "feat: $AGENT_NAME task complete" --no-verify 2>&1 | tee -a "$LOG_FILE"
    echo "[$(date '+%H:%M:%S')] $AGENT_NAME: committed uncommitted changes" | tee -a "$LOG_FILE"
  fi
fi

echo "AGENT_DONE:$AGENT_NAME" | tee -a "$LOG_FILE"


path: scripts/push_and_pr.sh
content: #!/usr/bin/env bash
# worktree-agents/scripts/push_and_pr.sh
# 推送分支并在 GitHub 上创建 PR
#
# 用法: push_and_pr.sh <repo_dir> <gh_token> <github_owner_repo> <agent_name> <worktree_path> <branch> <base_branch>
# 输出: PR URL

set -euo pipefail

REPO_DIR="$1"
GH_TOKEN="$2"
OWNER_REPO="$3"
AGENT_NAME="$4"
WORKTREE_PATH="$5"
BRANCH="$6"
BASE_BRANCH="$7"

# 设置 token auth
cd "$WORKTREE_PATH"
git remote set-url origin "https://x-access-[REDACTED_SECRET]"

# 推送
GIT_ASKPASS=true git push origin "$BRANCH" 2>&1 >&2

# 开 PR
PR_BODY="## $AGENT_NAME Output\n\nGenerated by OpenClaw multi-agent worktree orchestrator.\n\nWorktree: \`$WORKTREE_PATH\`\nBranch: \`$BRANCH\`"

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/$OWNER_REPO/pulls" \
  -d "$(jq -n \
    --arg title "[$AGENT_NAME] automated task" \
    --arg head "$BRANCH" \
    --arg base "$BASE_BRANCH" \
    --arg body "$PR_BODY" \
    '{title: $title, head: $head, base: $base, body: $body}')")

echo "$RESPONSE" | jq -r '.html_url'


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal:  | SkillSpector: suspicious (CRITICAL)