mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-08-02 07:09:47 +08:00
Jim Liu 宝玉
61 lines
4.7 KiB
Markdown
61 lines
4.7 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|