PicoClaw自动化：集成CapSolver API指南

# 下载适用于你平台的最新版本
# 将v0.1.1替换为发布页面上的最新版本
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
chmod +x picoclaw-linux-amd64
sudo mv picoclaw-linux-amd64 /usr/local/bin/picoclaw

# 运行交互式入门向导
picoclaw onboard

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build
make install

# 初始化配置和工作区
picoclaw onboard

export CAPSOLVER_API_KEY="CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# 安装Playwright浏览器依赖项（Ubuntu）
sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

# 在你的PicoClaw工作区中安装Playwright
cd ~/.picoclaw/workspace
npm init -y
npm install playwright
npx playwright install chromium

# 启动频道服务（Telegram、Discord等）
picoclaw gateway

# 或用于交互测试
picoclaw agent

你有哪些可用的工具？

运行：node --version

---
name: capsolver
description: "使用CapSolver REST API通过Playwright解决CAPTCHAs。支持reCAPTCHA v2、reCAPTCHA v3和Cloudflare Turnstile。在自动化表单提交或遇到CAPTCHA挑战的页面交互时使用。"
metadata: {"picoclaw":{"emoji":"🔓","always":true,"requires":{"bins":["node"],"env":["CAPSOLVER_API_KEY"]}}}
---

# CapSolver

## 重要：执行要求

当用户要求你解决CAPTCHA时，你必须立即调用工具。不要用“运行中...”或“我将开始...”或“我已经启动自动化...”这样的文本回复。

你的第一步必须是以下之一：
1. 调用`write_file`保存一个Node.js脚本，然后调用`exec`运行它
2. 调用`spawn`并提供详细的任务描述进行后台执行

如果你只用文本回复而没有工具调用，用户将看不到任何变化。始终执行。

## API端点

- **创建任务**: `POST https://api.capsolver.com/createTask`
- **获取结果**: `POST https://api.capsolver.com/getTaskResult`

## 任务类型

| CAPTCHA | 任务类型 | 站点密钥位置 |
|---|---|---|
| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | `data-sitekey`属性 |
| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | `grecaptcha.execute`调用或页面源代码 |
| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | Turnstile div上的`data-sitekey` |

企业变体：`ReCaptchaV2EnterpriseTaskProxyLess`、`ReCaptchaV3EnterpriseTaskProxyLess`。

## 工作流程

1. 使用Playwright导航到页面（无头Chromium）
2. 从DOM中提取站点密钥（`[data-sitekey]`属性）
3. 使用站点密钥和页面URL调用`createTask`
4. 每2秒轮询`getTaskResult`直到`status: "ready"`
5. 将令牌注入页面（隐藏表单字段）
6. 提交表单

## 核心代码模式

```javascript
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;

// 第1步：创建任务
const createRes = await fetch('https://api.capsolver.com/createTask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',  // 或 ReCaptchaV3TaskProxyLess, AntiTurnstileTaskProxyLess
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});
const { taskId } = await createRes.json();

// 第2步：轮询结果
let token;
while (true) {
  await new Promise(r => setTimeout(r, 2000));
  const res = await fetch('https://api.capsolver.com/getTaskResult', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId })
  });
  const result = await res.json();
  if (result.status === 'ready') { token = result.solution.gRecaptchaResponse || result.solution.token; break; }
  if (result.status === 'failed') throw new Error('解决失败');
}

// 第3步：注入令牌（reCAPTCHA）
await page.evaluate((t) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach(el => { el.value = t; el.innerHTML = t; });
}, token);
```

对于Turnstile，令牌字段通常是`input[name="cf-turnstile-response"]`，解决方案在`result.solution.token`中。

## API参考

所有任务类型都需要`type`、`websiteURL`、`websiteKey`。可选字段因类型而异：
- **reCAPTCHA v2**: `isInvisible`, `pageAction`, `enterprisePayload`, `apiDomain`
- **reCAPTCHA v3**: `pageAction` (来自 `grecaptcha.execute(key, {action: "..."})`)
- **Cloudflare Turnstile**: `metadata.action`, `metadata.cdata`

  你的消息                     PicoClaw 代理（Go，约 10MB 内存）
  ─────────────────────────────────────────────────────────────
  "前往该页面，           ──► 代理通过 MessageBus 接收
   填写表单，                  │ (pkg/bus/bus.go)
   解决 CAPTCHA，              ▼
   并提交它"             ContextBuilder 注入技能
                                   │ (pkg/agent/context.go)
                                   ▼
                              RunToolLoop 启动
                                   │ (pkg/tools/toolloop.go)
                                   ▼
                              代理编写 Node.js 脚本
                                   │ 通过 write_file 工具
                                   ▼
                              ExecTool 运行脚本
                              ┌────────────────────────────┐
                              │ pkg/tools/shell.go          │
                              │ guardCommand() → 27+ 检查 │
                              │ sh -c "node script.js"      │
                              │                             │
                              │  Headless Chromium          │
                              │  1. 导航到页面        │
                              │  2. 提取 sitekey         │
                              │  3. POST /createTask ────────── CapSolver API
                              │  4. 轮询 /getTaskResult ─────── (云)
                              │  5. 注入 token            │
                              │  6. 提交表单             │
                              │  7. 截图              │
                              └────────────────────────────┘
                                   │
                                   ▼ stdout 返回（最大 10KB）
                              代理读取输出
                                   │
                                   ▼
                              "表单提交成功！
                               验证成功！"

const response = await fetch('https://api.capsolver.com/createTask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});

const result = await fetch('https://api.capsolver.com/getTaskResult', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    taskId: taskId
  })
});
// result.solution.gRecaptchaResponse 包含 token

await page.evaluate((token) => {
  const textarea = document.querySelector('textarea[name="g-recaptcha-response"]');
  if (textarea) {
    textarea.value = token;
    textarea.innerHTML = token;
  }
}, captchaToken);

const { chromium } = require('playwright');
const https = require('https');

const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;
const PAGE_URL = '';

function httpsPost(url, data) {
  return new Promise((resolve, reject) => {
    const req = https.request(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    }, (res) => {
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => resolve(JSON.parse(body)));
    });
    req.on('error', reject);
    req.write(JSON.stringify(data));
    req.end();
  });
}

async function solveRecaptcha(siteKey, pageUrl) {
  console.log('创建 CapSolver 任务...');

  const createRes = await httpsPost('https://api.capsolver.com/createTask', {
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  });

  if (createRes.errorId) {
    throw new Error(`CapSolver 错误: ${createRes.errorDescription}`);
  }

  const { taskId } = createRes;
  console.log(`任务 ID: ${taskId}`);

  let token;
  while (true) {
    await new Promise(r => setTimeout(r, 2000));

    const res = await httpsPost('https://api.capsolver.com/getTaskResult', {
      clientKey: CAPSOLVER_API_KEY,
      taskId
    });

    if (res.status === 'ready') {
      token = res.solution.gRecaptchaResponse;
      console.log(`收到 token！长度: ${token.length}`);
      break;
    }
    if (res.status === 'failed') {
      throw new Error(`CapSolver 任务失败: ${res.errorDescription}`);
    }

    console.log('轮询中... 状态:', res.status);
  }

  if (!token) throw new Error('未能获取 token');
  return token;
}

async function main() {
  const browser = await chromium.launch({
    headless: true,
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });
  const page = await browser.newPage();

  try {
    await page.goto(PAGE_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
    const siteKey = await page.locator('[data-sitekey]').getAttribute('data-sitekey');
    console.log(`Sitekey: ${siteKey}`);

    const token = await solveRecaptcha(siteKey, PAGE_URL);

    await page.evaluate((t) => {
      document.querySelectorAll('textarea[name="g-recaptcha-response"]')
        .forEach(el => { el.value = t; el.innerHTML = t; });
    }, token);

    await page.locator('input[type="submit"]').click();
    await page.waitForTimeout(3000);

    const body = await page.textContent('body');
    console.log(body.includes('Success') ? 'SUCCESS!' : '结果:', body.slice(0, 200));
    await page.screenshot({ path: 'recaptcha_result.png' });
  } finally {
    await browser.close();
  }
}

main().catch(err => {
  console.error('错误:', err.message);
  process.exit(1);
});

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

在 https://example.com 解决 reCAPTCHA 并提交表单。

前往 https://example.com 并使用 CapSolver API 解决
reCAPTCHA，然后提交表单并告诉我是否成功。

前往 https://example.com/login，用
"[email protected]" 填写邮箱，用 "mypassword" 填写密码，检测并
解决页面上的任何 CAPTCHA，然后点击登录并告诉我
发生了什么。

打开 https://example.com/contact，填写姓名、邮箱和
消息字段，解决 CAPTCHA，提交表单，并告诉我
确认信息。

在后台，前往 https://example.com/register，用我的信息创建
账户，解决遇到的任何 CAPTCHA，并在完成后告诉我。

每小时检查一次 https://example.com/status —— 如果有
CAPTCHA 闸门，解决它并报告状态页面内容。

cd ~/.picoclaw/workspace && npm install playwright && npx playwright install chromium

sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

{ "tools": { "exec": { "enable_deny_patterns": false } } }

cd ~/.picoclaw/workspace && npm update playwright && npx playwright install chromium

CAPSOLVER_API_KEY=CAP-XXX node ~/.picoclaw/workspace/solve_captcha.js