Repository navigation
docs(feishu): document desktop-app upgrade wipes lark-oapi - #20190
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Point patch: the WhatsApp and Teams guides give the same "pip install into the gateway's environment" advice, with no desktop caveat. Not justified as shipped
What this change shipsInventory (2 items) — 1 justifiedIntent: stop desktop-app Feishu users from losing the channel on every upgrade by telling them where to install the SDK so it survives — a FIX (docs).
[FIRST-PRINCIPLES-REVIEWED] 8da9245 Description read[DESCRIPTION-READ] c219d982beeade5646eaed40bda52c9e0ae7cafbff92669b0ee84029a1d3d620 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that the Getting Started page actually covers running the gateway from a source checkout or virtualenv, since the note sends desktop users there. [DESIGN-REVIEWED] 8da9245 Description read[DESCRIPTION-READ] f095b376c3fea61709afaaad7cf8182959cf294b9891887bde0e0eb0de5953a5 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
ba06581 to
9262f7a
Compare
After a Kiro Crew desktop-app upgrade the entire backend-dist bundle is replaced, removing any user-installed Python packages including lark-oapi. The channel then silently shows 'Not connected' with no obvious cause. Add an upgrade note to the optional-dependency callout (near the quick start) and to the Known gaps list, with the exact manual reinstall command for both the arm64 and x64 embedded interpreters and a note to restart. Not in this PR: surfacing the reinstall command in the Settings panel for the bundled desktop interpreter (option 1/2 packaging calls) or persisting the package outside the replaceable bundle (option 2). Both stay open on #14618. Refs #14618
9262f7a to
8da9245
Compare
|
span=c4565a92afb7
|
|
mbriones98
left a comment
There was a problem hiding this comment.
Checks green and readiness passed at 8da9245; no behavior change.
Problem / Motivation
Goal: Tell desktop-app Feishu users not to install
lark-oapiinto the app's bundle, and point them to a gateway they run themselves, where the SDK survives app upgrades.The Feishu guide says "install it directly into the environment that runs the gateway". On the desktop app that environment is the bundled Python in
backend-dist. A pip install there writes into the code-signed bundle, and each app upgrade replaces the bundle and removes the package. Users who followed the guide lose the channel after every upgrade (#14618), and the guide never says so.Why it matters
A desktop Feishu user loses the channel after each upgrade with no doc that explains why or what to do instead. The code already refuses to suggest the bundled install (
extras.pip_install_channel_available()returns False for the bundled interpreter); the doc should say the same.Not a goal
lark-oapiinto the desktop app. That is a size and supply-surface call for maintainers; it stays open on Feishu channel: desktop-app upgrade wipes optional lark-oapi dependency, silently breaking the channel (needs reinstall every upgrade) #14618.PYTHONPATHisolation in fix: isolate bundled desktop gateway from Python overrides #13669; it stays open on Feishu channel: desktop-app upgrade wipes optional lark-oapi dependency, silently breaking the channel (needs reinstall every upgrade) #14618.whatsapp-integration.md) and Teams (teams-integration.md) guides give the same "pip install into the gateway's environment" advice with no desktop caveat. They are siblings left for Feishu channel: desktop-app upgrade wipes optional lark-oapi dependency, silently breaking the channel (needs reinstall every upgrade) #14618, so this PR stays a one-guide fix for the Feishu report.What changed (motivation → approach → change)
The doc said "install into the gateway's environment" with no desktop caveat, while the code treats the desktop bundle as off-limits. So the doc now matches the code.
feishu-integration.mdgets one desktop note under the install line. It says the install line does not apply to the desktop app, why (code-signed bundle, wiped on upgrade), that Settings shows no install command there, and the one supported path: run the gateway from a source checkout or a virtual environment and install the SDK there. The Known-gaps list gets a one-line pointer back to that note instead of a second copy.Backwards compatibility
Compatible: docs only. No API fields, config keys, or runtime behaviour changed.
Removes nothing: no fields, routes, or config keys are removed.
Tests
N/A — no code changed.
python3 scripts/docs_lint.pypasses.Manual verification
Checked each claim against main:
platform_compat_runtime.is_bundled_interpreter()(bundle underbackend-dist, code-signed, wiped on update),extras.pip_install_channel_available()(False on the bundled interpreter), andfeishu_settings._channel_sdk_statuswith thesdk_install_unsupportedstring (Settings shows no command there).Screenshots / video
Why no screenshot: No frontend code changed.
Related Issues
Part of #14618
Pattern harvest
Rule candidate: review-prompt
Pattern: before a doc tells users to pip install into "the gateway's environment", check
is_bundled_interpreter()/pip_install_channel_available(). On the desktop app that environment is the code-signed bundle, and the code already refuses to suggest writing there.Checklist