baoyu-skills/skills/baoyu-wechat-summary/references/setup.md

Setup & troubleshooting — wx-cli environment

Load this file when: (a) starting a run in a fresh environment where wx-cli hasn't been verified yet, or (b) any wx command fails.

Prerequisites

Before invoking the workflow, verify the environment. Run these checks in order; stop at the first failure and surface the exact next command the user needs.

1. wx-cli installed — run wx --version. If missing, tell the user to install it themselves (npm install -g @jackwener/wx-cli or use one of the alternatives at https://github.com/jackwener/wx-cli). Do NOT auto-install — this repo forbids piped/silent installs.
2. ~/.wx-cli directory owned by the current user — sudo wx init historically chowned this directory to root, which breaks every subsequent non-sudo wx call. Check:

   ls -la ~/.wx-cli/ 2>/dev/null | head -5
   

   If the directory exists but the owner is root (or anything other than $(whoami)), tell the user to repair it themselves:

   sudo chown -R $(whoami) ~/.wx-cli
   sudo rm -f ~/.wx-cli/daemon.pid ~/.wx-cli/daemon.sock
   wx daemon start
   

   The skill should NOT run sudo on the user's behalf.
3. wx-cli initialized — wx sessions should return data. If it fails with "no keys" / "init required", instruct the user to run wx init while WeChat is running (on macOS, codesign --force --deep --sign - /Applications/WeChat.app first). Prefer non-sudo init; only fall back to sudo wx init if the user's wx-cli version requires it — and warn them that they'll need step 2's chown after.
4. WeChat 4.x running and logged in — required for the daemon to find data files.

wx-cli quick reference

Command	Purpose
wx --version	Sanity-check that wx-cli is installed
wx sessions --json	List recent sessions; useful for verifying init and finding the user's own wxid
wx contacts --query "<name>" --json	Fuzzy-match contacts/groups by display name, remark, or wxid
wx history "<group>" --since DATE --until DATE -n N --json	Pull a group's messages within a date range as JSON
wx members "<group>" --json	List a group's members (rarely needed; mostly for completeness)
wx stats "<group>" --since DATE	wx-cli's built-in stats; we compute our own from wx history JSON so the format matches our digest
wx daemon status / wx daemon stop / wx daemon logs --follow	Daemon lifecycle (troubleshooting)

All wx commands accept --json for machine-readable output. Default output is YAML — only use it for human eyeballing during debugging.

Troubleshooting

When a wx command fails, diagnose by the symptom, not by retrying blindly. Common patterns:

Symptom	Cause	Fix (tell the user to run these — do NOT run sudo for them)
Operation not permitted / Access denied to ~/.wx-cli	Sandbox is on	Re-run the command with dangerouslyDisableSandbox: true. Persistent fix: /sandbox to allow ~/.wx-cli and the WeChat data dir.
无法写入 /Users/<u>/.wx-cli / Permission denied	~/.wx-cli is owned by root (legacy sudo wx init)	sudo chown -R $(whoami) ~/.wx-cli && sudo rm -f ~/.wx-cli/daemon.{pid,sock} && wx daemon start
wx history hangs / times out / returns nothing	Daemon is stuck	wx daemon stop && rm -f ~/.wx-cli/daemon.{pid,sock} && wx daemon start, then retry
no keys / init required after the daemon was working	Keys went stale (WeChat restart, version upgrade)	Make sure WeChat is running, then wx init --force (non-sudo first; only sudo if your wx-cli version requires it)
wx contacts returns zero rows for a group you know exists	Group is folded into 折叠群 or the daemon hasn't indexed it yet	wx sessions --json and search there; if missing, run wx daemon stop && wx daemon start and retry
Messages returned but --since / --until window looks wrong	Date string not in YYYY-MM-DD format, or off-by-one timezone	Confirm the dates are local-time YYYY-MM-DD. Re-filter the JSON by timestamp locally as a belt-and-suspenders step.
Empty result for a chat that should have activity	-n cap too low for a noisy group	Raise -n (e.g. to 20000) and re-fetch

Recovery order when nothing makes sense:

1. Is WeChat running?
2. Is ~/.wx-cli owned by $(whoami)?
3. Is the daemon healthy? (wx daemon status)
4. Restart the daemon (wx daemon stop && wx daemon start)
5. Last resort: wx init --force (while WeChat is running)

Never auto-retry inside the skill — every failure should produce a clear diagnostic plus the exact command the user needs to run.