Skip to content

Beginner-friendly post-install guide: detect & install platform deps automatically#485

Open
GGzili wants to merge 3 commits into
lsdefine:mainfrom
GGzili:feat/post-install-guide
Open

Beginner-friendly post-install guide: detect & install platform deps automatically#485
GGzili wants to merge 3 commits into
lsdefine:mainfrom
GGzili:feat/post-install-guide

Conversation

@GGzili
Copy link
Copy Markdown

@GGzili GGzili commented May 25, 2026

Summary

When a first-time user runs the official one-line installer and walks
through assets/configure_mykey.py, the wizard currently prints a hint
like:

  💡 提示:你需要安装以下依赖以使消息平台正常工作:
     pip install pycryptodome qrcode requests

…but the user still has to copy/paste it, find the right shell, and
re-run the wizard if the platform needs an interactive QR login (e.g.
WeChat iLink). New users repeatedly hit:

  ⚠ 无法导入 WxBotClient: No module named 'qrcode'

This PR closes that gap.

What changes

  1. scripts/post_install.py (new, stdlib-only)

    • Reads the freshly written mykey.py.
    • Detects which IM platforms are enabled (WeChat iLink / Telegram /
      QQ / Feishu / WeCom / DingTalk).
    • For each enabled platform, checks whether its Python packages are
      importable.
    • Offers to install missing packages with uv pip (preferred) or
      python -m pip.
    • For platforms that need interactive QR login, after installing
      deps, offers to re-launch configure_mykey.py so the user can
      scan the QR right away.
    • If no platform is enabled yet, asks the user whether they
      want to enable one and re-launches the wizard.
    • Degrades gracefully when stdin is non-interactive: prints the
      missing deps and exits 0. Never breaks the installer.
  2. assets/configure_mykey.py (small change)

    • When deps are listed at the end, hand off to
      scripts/post_install.py if it exists and stdin is interactive.
    • Falls back to the existing copy/paste hint otherwise.
  3. .github/workflows/ci.yml (new)

    • lint-python: compileall on scripts/ and assets/, plus
      ruff (warn-only).
    • lint-shell: shellcheck any scripts/*.sh shipped in the
      repo.
    • test-post-install: matrix on Ubuntu/macOS/Windows × Python
      3.11/3.12. Runs post_install.py against (a) empty mykey.py,
      (b) a mock Telegram config without the telegram package
      installed, asserting the script exits 0 and is non-interactive
      friendly.
    • smoke-developer-install: uv pip install -e . and
      import agent_loop to catch packaging regressions.

Why a separate Python script (and not just shell-side logic)?

  • The official one-line installer is split between a bash and a
    PowerShell variant, both hosted on a VPS. Putting the logic in a
    stdlib-only Python script keeps it cross-platform, in-repo, and
    reviewable.
  • Once this lands, both VPS scripts only need a one-liner:
    python scripts/post_install.py — see the companion issue I'll
    file for the VPS-side change.

Out of scope (intentionally)

  • Does not change the platform detection regex set in
    configure_mykey.py; we read the same identifiers it writes.
  • Does not introduce any new runtime dependencies.
  • Does not auto-install LLM extras (still scoped to IM platforms,
    which are the noisy ones for new users).

Test notes

  • Local: ran wizard with no platform → got "Enable a platform now?"
    prompt; with WeChat iLink enabled → got missing-dep prompt, then
    QR-rerun prompt.
  • CI matrix runs both empty and mock-config flows non-interactively.

GGzili added 3 commits May 25, 2026 19:42
Detects which IM platforms the user enabled in mykey.py, checks whether
the corresponding Python packages are importable, and offers to install
the missing ones (using `uv pip` when available, falling back to
`python -m pip`). For platforms that need interactive QR login (e.g.
WeChat iLink), offers to re-run the configure wizard so the user can
scan the QR right away.

If no platform is enabled yet, offers to (re-)launch the configure
wizard. Stdlib-only, so it runs against the uv-managed Python the
installer ships.
After mykey.py is written, call scripts/post_install.py so users do not
have to copy-paste `pip install ...` themselves. The wizard still
prints the dep list as a fallback when stdin is non-interactive or
post_install is unavailable, so existing flows remain compatible.
- lint-python: compileall on scripts/ and assets/, plus ruff (warn-only).
- lint-shell: shellcheck any scripts/*.sh shipped in the repo.
- test-post-install: matrix run on Ubuntu/macOS/Windows × Python 3.11/3.12
  to make sure post_install.py degrades gracefully in non-interactive
  contexts (no mykey.py, partial mykey.py with missing dep, etc.).
- smoke-developer-install: `uv pip install -e .` + `import agent_loop`
  to catch packaging regressions in pyproject.toml.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant