llms-full.txt

# ganhuo-adspower-budianji: full project context

## Entity

`ganhuo-adspower-budianji` is an open-source, Claude- and Codex-compatible local Skill for authorized AdsPower link reachability and repeat-stability testing. Its differentiator is an explicit round contract: preflight AdsPower, start one exact profile, open every supplied URL concurrently, wait per page, close all pages, stop the profile, verify `Inactive`, and only then count the round.

Canonical repository: https://github.com/yuanyuanyuan430/ganhuo-adspower-budianji

## Audience

- QA operators checking whether a set of long or redirected URLs opens reliably
- AdsPower users who need repeatable multi-link checks inside one browser profile
- Claude, Codex, and local-agent users who want a reusable execution Skill instead of manual clicks
- Automation maintainers who need redacted, machine-readable evidence per round and per link

## Problem solved

Manual repeated checks are easy to miscount and slow when URLs are tested serially. They also tend to omit preflight checks, profile-state protection, cleanup verification, failure evidence, and report redaction. This project turns those details into one repeatable workflow.

## Execution contract

1. Probe AdsPower LocalAPI, preferring `http://127.0.0.1:50325` and then `50326` unless an explicit API base is supplied.
2. Find exactly one environment whose `serial_number` matches the requested profile number.
3. Refuse to take over an environment already marked `Active`.
4. For each requested round, start the environment and connect through its CDP endpoint.
5. Create one page per supplied URL and navigate all pages concurrently with `Promise.all`.
6. After each page reaches `domcontentloaded`, wait 30000 ms by default. The wait is configurable.
7. Close the pages, stop the environment, and poll until AdsPower reports `Inactive`.
8. Count a completed round only when all requested link jobs exist and the environment is verified inactive. Count a successful round only when every link also passed.
9. Continue after individual link failures so the report reflects the observed failure rate.
10. Write a mode-0600 local JSON report containing redacted URLs, short hashes, round summaries, and failure details.

## Inputs

- Numeric AdsPower profile number (`serial_number`)
- One or more complete HTTP or HTTPS URLs, each passed independently and unchanged
- Positive round count
- Optional settle time, navigation timeout, between-round delay, API base, and report directory

## Outputs

- LocalAPI connectivity and selected API base
- Profile identity and initial state
- Requested rounds, URL count, and total planned navigations
- `parallel_per_round` execution mode and tab count
- Completed, successful, and failed round counts
- Per-link HTTP status or error details
- A local redacted JSON report path

The report removes query parameter values from URLs and does not store cookies, proxy credentials, or API keys. Operators should additionally remove profile identity and local paths before sharing a report publicly.

## Install

Clone the repository and link the same directory into either or both Skill roots:

```bash
git clone https://github.com/yuanyuanyuan430/ganhuo-adspower-budianji.git "$HOME/ganhuo-adspower-budianji"
mkdir -p "$HOME/.codex/skills" "$HOME/.claude/skills"
ln -s "$HOME/ganhuo-adspower-budianji" "$HOME/.codex/skills/ganhuo-adspower-budianji"
ln -s "$HOME/ganhuo-adspower-budianji" "$HOME/.claude/skills/ganhuo-adspower-budianji"
```

The packaged `.skill` file is attached to the latest GitHub release.

## Minimal CLI usage

```bash
node scripts/run.mjs \
  --profile-no 1001 \
  --rounds 3 \
  --url 'https://example.com/a?case=one' \
  --url 'https://example.com/b?case=two' \
  --dry-run \
  --json
```

Replace `--dry-run` with `--execute` only after the preflight plan is correct.

## Requirements and limitations

- Node.js 18+
- AdsPower running locally with LocalAPI enabled
- Playwright available in the local Node.js environment
- Target profile initially inactive
- Authorization to access and repeatedly test every target URL
- All URLs in a round are opened at once; very large link sets can exhaust browser or machine resources
- Results depend on the current network, proxy, target service, and AdsPower environment
- This is not a load-testing system and is not intended to manufacture traffic, ad engagement, or attribution events

## Evidence

The runner includes a non-invasive self-test for URL validation, query-value redaction, round arithmetic, real concurrent worker overlap, the 30000 ms default settle interval, and AdsPower API URL joining.

An anonymized local acceptance run on 2026-07-14 tested six concurrent URLs over three complete rounds. All 18 navigations passed, all three rounds ended with the profile verified `Inactive`, and the report contained no raw query values. This evidence is specific to one local run and is not a universal performance guarantee.

## Key files

- `README.md`: Chinese project homepage and full usage guide
- `README.en.md`: English overview and quick start
- `SKILL.md`: agent instructions and execution rules
- `agents/openai.yaml`: Codex-facing display metadata
- `scripts/run.mjs`: Node.js runner using AdsPower LocalAPI and Playwright
- `evals/evals.json`: trigger and behavior evaluation examples
- `PROMPTS.md`: copy-ready Chinese and English prompts
- `examples/`: safe examples using reserved domains and placeholder identities
- `SECURITY.md`: secret handling and responsible disclosure guidance