swain-dispatch

Agent 调度（已弃用）

此技能已弃用。 它需要使用 ANTHROPIC_API_KEY，并按令牌计费，这与 Max/Pro 订阅不兼容。请改用会话内的并行 Agent，或手动执行 spike。

通过 GitHub Issues 将 swain-design 工件调度给后台 Agent。Agent 会在 GitHub Actions 运行器上使用 anthropics/claude-code-action@v1 自主运行。

注意： 在采用 trunk+release 分支模型（ADR-013）的项目中，调度的工作会以 trunk（开发分支）为目标，而不是 release（分发分支）。

前提条件

调度功能正常运行前，必须满足以下三个条件：

1. Claude GitHub App — 已从 https://github.com/apps/claude 安装到仓库（授予 Contents、Issues、Pull Requests 读写权限）
2. 工作流文件 — .github/workflows/claude.yml（或 agent-dispatch.yml），其中包含 claude-code-action 步骤
3. ANTHROPIC_API_KEY 仓库机密 — API 密钥（不能使用 Max/Pro 订阅；必须按令牌计费）

步骤 0 — 预检

每次调度前都要运行此检查。若任何检查失败，请停止并显示设置说明。

# 1. Check gh auth
gh auth status 2>/dev/null || { echo "FAIL: gh not authenticated"; exit 1; }

# 2. Check workflow file
WORKFLOW_FILE=""
for f in .github/workflows/claude.yml .github/workflows/agent-dispatch.yml; do
  [[ -f "$f" ]] && WORKFLOW_FILE="$f" && break
done

# 3. Check API key secret
OWNER_REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
HAS_KEY=$(gh api "repos/${OWNER_REPO}/actions/secrets" --jq '.secrets[].name' 2>/dev/null | grep -c ANTHROPIC_API_KEY || true)

如果缺少工作流文件，显示：

需要设置调度功能。 未找到工作流文件。

创建 .github/workflows/claude.yml：

name: Claude Code

on:
  repository_dispatch:
    types: [agent-dispatch]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

然后提交并推送，再重试调度。

如果缺少 API 密钥机密，显示：

缺少 ANTHROPIC_API_KEY 仓库机密。

使用以下命令设置：gh secret set ANTHROPIC_API_KEY --repo {owner}/{repo}

注意：这必须是 API 密钥（按令牌计费），不能使用 Max/Pro 订阅令牌。

调度工作流

步骤 1 — 解析工件

解析用户的请求，识别工件 ID（例如 SPEC-025、SPIKE-007）。

ARTIFACT_ID="SPEC-025"  # from user input
ARTIFACT_PATH="$(find docs/ -path "*${ARTIFACT_ID}*" -name "*.md" -print -quit)"

如果未找到，请报告错误并停止。

步骤 2 — 读取工件

读取完整的工件内容。该内容将作为 issue 正文。

步骤 3 — 读取调度设置

检查 swain.settings.json 中的调度配置：

jq -r '.dispatch // {}' swain.settings.json 2>/dev/null

默认值：

• model：claude-sonnet-4-6
• maxTurns：15
• labels：["agent-dispatch", "swain"]
• autoTrigger：true

步骤 4 — 创建 GitHub Issue

gh issue create \
  --title "[dispatch] ${ARTIFACT_TITLE}" \
  --body "$(cat <<EOF
## Dispatched Artifact: ${ARTIFACT_ID}

This issue was created by `swain-dispatch` for background agent execution.

### Instructions

Implement the artifact below. Follow the acceptance criteria. Create a PR when done.

---

${ARTIFACT_CONTENT}
EOF
)" \
  --label "agent-dispatch" --label "swain"

从输出中记录 issue 编号。

步骤 5 — 触发工作流

如果 autoTrigger 为 true（默认值）：

OWNER_REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
gh api "repos/${OWNER_REPO}/dispatches" \
  -f event_type="agent-dispatch" \
  -f client_payload[artifact]="${ARTIFACT_ID}" \
  -f client_payload[issue_number]="${ISSUE_NUMBER}" \
  -f client_payload[model]="${MODEL}" \
  -f client_payload[max_turns]="${MAX_TURNS}"

步骤 6 — 报告结果

告诉用户：

已将 ${ARTIFACT_ID} 调度给后台 Agent。 Issue：${ISSUE_URL} 工作流将在下一个可用运行器上运行。 请在 issue 评论中查看进度。

手动调度

如果用户偏好手动调度（或 autoTrigger 为 false），请跳过步骤 5 并告诉他们：

已创建 issue：${ISSUE_URL} 如需触发 Agent，请在 issue 上评论 @claude。

检查调度状态

用户询问调度状态时：

gh issue list --label agent-dispatch --state open --json number,title,updatedAt

显示尚未关闭的调度 issue 及其最后更新时间。

触发时机

根据 @claude 的提及方式，Claude Code Action 工作流会在不同的 GitHub 事件触发时运行：

提及位置	事件	触发时机
创建时的 Issue 正文	issues.opened	Issue 创建后立即触发
现有 Issue 的评论	issue_comment.created	发布评论时触发

注意： 如果创建 Issue 时工作流文件尚不存在，就会错过 issues.opened 事件。此时，请添加一条包含 @claude 的后续评论，通过 issue_comment.created 触发工作流。

默认的分发工作流（步骤 4 + 步骤 5）使用 repository_dispatch，不受 @claude 提及影响。只有在以下情况下才需要注意触发时机：

• 使用手动分发（跳过步骤 5）
• 工作流依赖 issues.opened 或 issue_comment.created 事件