English | Chinese (Simplified)

wechat-search

wechat-search turns an already logged-in Windows WeChat Search window into a CLI for PowerShell, scripts, and AI workflows. It can search public accounts and articles, then archive public articles as raw HTML, Markdown, and local images.

It is a fail-closed, Windows-only tool whose live UIA contract decides whether a runtime is safe to control. It is not an official WeChat API.

Highlights

• Exact control of the independently opened WeChat Search window through Microsoft UI Automation.
• Direct ValuePattern, InvokePattern, and validated LegacyIAccessiblePattern actions for the current WMPF provider.
• Deterministic result-category calibration with exact internal URI postconditions.
• Global public-account article search.
• Global public-account search.
• Exact account-scoped article search.
• Structured JSON on stdout and diagnostics on stderr.
• Contract-first runtime validation: release versions are evidence, not a bypass or hard gate.
• First-class article identity based on (__biz, mid, idx), with sn and optional chksm verification.
• Raw public HTML preservation.
• Purpose-built Markdown conversion for the observed WeChat article structure.
• Local image archival with MIME and content validation.
• Bounded public HTTP downloads with --jobs 1..8.
• Deterministic identity-based storage and atomic archive commits.
• No injection, hooks, internal protocol reproduction, cookie extraction, OCR, or coordinate input.
• Immediate failure when the exact UIA or article contract does not match.

Requirements

• Windows 10 or Windows 11 x86-64.
• Release-verified Weixin baseline 4.1.13.12.
• Release-verified WeChat WMPF host baseline 2.5.6.25506.
• A manually logged-in WeChat session.
• One manually opened independent WeChat Search window.
• Internet access for public article downloads.

The user performs login and opens the independent Search window. The CLI does not automate authentication and does not read WeChat or browser cookies.

Installation

Prebuilt GitHub Release

Download wechat-search-v0.2.3-x86_64-pc-windows-msvc.zip from the v0.2.3 GitHub Release, verify it with SHA256SUMS.txt, extract it, and place wechat-search.exe in a directory on PATH.

Install from the exact Git tag

cargo install --git https://github.com/hicancan/wechat-search --tag v0.2.3 --locked

Install a local checkout

git clone https://github.com/hicancan/wechat-search
Set-Location wechat-search
cargo install --path . --locked --force

The Cargo package is the Rust source package. GitHub Releases distribute the Windows binary. GitHub Packages is intentionally unused because this project does not publish a container, NuGet package, or other package-registry artifact.

Three-minute quick start

1. Log in to Windows WeChat manually.
2. Open Discover and open Search as an independent window.
3. Leave one ordinary Search home or result tab active.
4. Validate the exact runtime contract:

wechat-search doctor --pretty

5. Search public articles:

wechat-search search "artificial intelligence" --type article --limit 5 --pretty

6. Archive one or more public article URLs:

wechat-search download `
  "https://mp.weixin.qq.com/s/<public-token>" `
  --jobs 4 `
  --pretty

Runtime input and downloaded article content may use any language. The software interface and canonical documentation are English.

CLI reference

Diagnose the live UIA contract

wechat-search doctor [--pretty]

Reports the observed and release-verified WeChat/WMPF versions, compatibility policy, exact target window, active surface, browser shell, active tab lease, result-tab bounds/actions, and exposed UIA patterns.

Search articles or public accounts

wechat-search search <QUERY> `
  --type <article|account> `
  --limit <1..20> `
  [--download] `
  [--jobs <1..8>] `
  [--pretty]

--download is valid only with --type article. Search is serial. When requested, public HTTP archival begins only after the UIA lease has been released.

The WMPF provider exposes category items without semantic names, and their order can vary with the query. The CLI therefore submits one release-verified calibration query, focuses and activates exactly one verified item through UIA and its validated LegacyIAccessiblePattern, proves the selected category through the exact internal result URI, and only then submits the requested query inside that category. Every replaced WMPF element is re-acquired from the active document before it is used. The CLI never tries adjacent items or guesses from screen position.

Search inside one exact public account

wechat-search search-account-articles `
  <EXACT_ACCOUNT_NAME> `
  <QUERY> `
  --limit <1..20> `
  [--download] `
  [--jobs <1..8>] `
  [--pretty]

The account display name must match exactly. The workflow opens the exact account, invokes its account-scoped search, extracts article results, and closes transient tabs in reverse order.

Run a serial search batch

wechat-search batch D:\Data\wechat-search\inputs\tasks.json `
  [--download] `
  [--jobs <1..8>] `
  [--pretty]

Example input:

[
  { "type": "article", "query": "example topic", "limit": 5 },
  { "type": "account", "query": "example account", "limit": 5 },
  {
    "type": "account_article",
    "account": "Exact Account Name",
    "query": "example topic",
    "limit": 5
  }
]

All UIA tasks execute serially under one global mutex. If --download is present, article URLs are collected after the batch and archived with bounded HTTP concurrency.

Download public articles

wechat-search download <URL>... [--jobs <1..8>] [--pretty]

The command accepts one or more public https://mp.weixin.qq.com/s URLs. Short and parameterized URLs are resolved from actual public HTTP evidence and deduplicated by (__biz, mid, idx). A batch with any failed article returns a non-zero exit status while retaining structured per-item results.

Archive layout

The runtime root is fixed at D:\Data\wechat-search:

D:\Data\wechat-search\
|-- inputs\
|-- runs\
|-- articles\
|   `-- <biz>\
|       `-- <mid>\
|           `-- <idx>\
|               |-- source.html
|               |-- article.md
|               `-- images\
|                   `-- 01-<sha256-prefix>.jpg
`-- .staging\

Article titles are never used as primary directory names. Writes occur in a task-specific .staging directory on the same volume. The validated directory is atomically renamed into its final identity path. Existing valid archives return existing; partial or conflicting archives fail closed.

JSON examples

Article search results expose structured resource identity:

{
  "query": "example topic",
  "type": "article",
  "wechat_version": "4.1.13.12",
  "search_host_version": "2.5.6.25506",
  "results": [
    {
      "title": "Example title",
      "account": "Example account",
      "snippet": "Example snippet",
      "published_at": "Example publication value",
      "identity": {
        "biz": "ExampleBiz==",
        "mid": "1234567890",
        "idx": 1
      },
      "verification": {
        "sn": "exampleverification"
      },
      "url": "https://mp.weixin.qq.com/s?__biz=ExampleBiz%3D%3D&mid=1234567890&idx=1&sn=exampleverification"
    }
  ]
}

Download output distinguishes successful, idempotent, and failed items:

{
  "results": [
    {
      "source_urls": ["https://mp.weixin.qq.com/s/<public-token>"],
      "identity": {
        "biz": "ExampleBiz==",
        "mid": "1234567890",
        "idx": 1
      },
      "status": "downloaded",
      "archive_dir": "D:\\Data\\wechat-search\\articles\\ExampleBiz==\\1234567890\\1",
      "html_path": "D:\\Data\\wechat-search\\articles\\ExampleBiz==\\1234567890\\1\\source.html",
      "markdown_path": "D:\\Data\\wechat-search\\articles\\ExampleBiz==\\1234567890\\1\\article.md",
      "image_count": 3,
      "source_sha256": "<lowercase-sha256>"
    }
  ],
  "summary": {
    "requested_urls": 1,
    "unique_articles": 1,
    "downloaded": 1,
    "existing": 0,
    "failed": 0,
    "jobs": 4
  }
}

Missing optional verification or publication fields are omitted. Empty strings are not used to hide unavailable data.

Why raw HTML and Markdown are both stored

source.html is the reproducible public server response. It retains the evidence needed to re-check extraction and identity without mutating image paths or adding scripts.

article.md is the compact, semantic representation for people, scripts, and AI workflows. It keeps front matter, headings, paragraphs, links, lists, quotes, tables, and local image references while excluding the interactive page shell.

images\ provides an offline asset set. Every image is downloaded from its observed public URL, size-limited, MIME-checked, content-checked, content-hashed, and referenced through a relative Markdown path. All three representations serve different purposes.

Why search is serial and downloading is parallel

The verified WMPF UIA provider exposes only one active top-level document and no semantic tab creation, background-document identity, or exact switch operation. Concurrent UIA tasks would race on one active page, so every search holds one global mutex and one exact tab lease.

After extraction, public article URLs are independent immutable inputs. The UIA lease is released before HTTP begins. Downloads use one bounded worker pool, defaulting to four jobs and limited to eight. Images are fetched inside those workers, so total HTTP work remains bounded.

Runtime compatibility

Version 0.2.3 was release-verified against:

Component	Version
Windows Weixin	4.1.13.12
WMPF WeChatAppEx.exe	2.5.6.25506

The runtime policy is contract_first. A different version is allowed to proceed only after the exact native window, process ownership, browser shell, UIA element, Pattern, transition, and result contracts pass. A successful unverified runtime emits one UNVERIFIED_RUNTIME_VERSION JSON warning on stderr while keeping the existing search JSON on stdout unchanged. doctor also reports the verified and observed version pair under compatibility.

There is no old-version compatibility branch and no version-based fallback. A UIA contract mismatch always fails closed, regardless of version number.

Errors and troubleshooting

Errors are JSON objects on stderr with a stable English code, operation, contract evidence, sanitized URL, identity when known, and relevant HTTP or UIA details.

Common codes include:

• WECHAT_NOT_RUNNING: start and log in to WeChat manually.
• SEARCH_WINDOW_NOT_FOUND: open Search as an independent window.
• CONTRACT_VIOLATION or PATTERN_UNAVAILABLE: the live UIA provider differs from the verified contract.
• SEARCH_TIMED_OUT: the expected UIA state transition did not complete within the explicit timeout.
• ANTI_BOT_PAGE: the public response was an error shell, login page, CAPTCHA, or environment-error page.
• IDENTITY_MISMATCH: the response identity or requested sn did not match.
• ASSET_FAILURE: an image status, size, MIME, or payload contract failed.
• ARCHIVE_MALFORMED or ARCHIVE_CONFLICT: an existing identity directory is partial or inconsistent.

The downloader never reads cookies and never turns an error page into a successful archive.

Security boundaries

The search control plane uses direct windows-rs COM and UI Automation calls. It does not use coordinate clicking, OCR, image recognition, SendInput, clipboard guessing, browser automation, CDP, hooks, injection, or private search-protocol reproduction.

The archival data plane sends unauthenticated requests only for explicitly supplied or explicitly resolved public article pages and their observed public image resources. It never reads chats, contacts, private account data, browser profiles, or login credentials. Session and tracking query parameters are removed before persistence and diagnostics.

CI/CD and release process

.github/workflows/ci.yml validates Windows builds on pushes and pull requests. It runs the repository language policy, formatting, Clippy, nextest, release compilation, package verification, and executable version checks. Hosted CI does not fabricate a logged-in WeChat environment and does not run live UIA or public network acceptance tests.

.github/workflows/release.yml runs the same gates for an annotated vX.Y.Z tag, verifies the tag against Cargo.toml, builds one Windows x86-64 ZIP, generates SHA256SUMS.txt, tests the extracted executable, and publishes both assets through GitHub Releases. GitHub Packages is intentionally not used.

Development and testing

Use Rust stable MSVC. The tested minimum compiler is declared by rust-version in Cargo.toml.

& 'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1' -Arch amd64 -HostArch amd64
Set-Location D:\code\github\hicancan\wechat-search

scripts\check-language.ps1
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo nextest run
cargo build --release
cargo package --locked

Unit tests use minimal synthetic English fixtures and require no network. Live UIA and public article acceptance remain local because GitHub-hosted runners do not have the verified logged-in WeChat session.

Current limitations

• The user must log in manually.
• The user must open the independent WeChat Search window manually.
• Versions other than the release-verified baseline are accepted only when the complete live contract passes and produce a structured warning.
• UIA search is intentionally serial.
• Public downloading depends on the public server continuing to return the verified article structure without authentication.
• Unsupported embedded video, audio, mini-program, and interactive elements become explicit Markdown markers rather than fabricated content.
• No local search database, daemon, HTTP API, MCP server, or generic desktop automation framework is included.
• Real article content may be Chinese or another language even though the software interface is English.

License

MIT