Skip to content

docs(feishu): document desktop-app upgrade wipes lark-oapi - #20190

Merged
iamwhatever merged 1 commit into
mainfrom
fix/14618-feishu-sdk-missing-not-silent
Oct 19, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/14618-feishu-sdk-missing-not-silent

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Tell desktop-app Feishu users not to install lark-oapi into 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

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.md gets 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.py passes.

Manual verification

Checked each claim against main: platform_compat_runtime.is_bundled_interpreter() (bundle under backend-dist, code-signed, wiped on update), extras.pip_install_channel_available() (False on the bundled interpreter), and feishu_settings._channel_sdk_status with the sdk_install_unsupported string (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

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated
  • No secrets, credentials, or internal references in the diff

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 14, 2026 07:39
@CrysisDeu
CrysisDeu requested a review from mbriones98 October 14, 2026 07:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Item 1 — symptom-level: the cause is that the channel guides tell users to "install into the environment that runs the gateway" without saying that on the desktop app this is the code-signed bundle. This PR fixes one of the 3 guides that say so. Grepping pip install in src/kiro_crew/docs/*.md turns up 2 unfixed siblings: whatsapp-integration.md:10-14 (neonize, "installed into the environment that runs the gateway") and teams-integration.md:42-46 (PyJWT[crypto], "in the environment that runs the gateway"). Neither mentions the desktop app or the bundle. Both channels go through the same _channel_sdk_status and pip_install_channel_available() gate the description cites.
    Clears when: the description names the WhatsApp and Teams guides as siblings left for Feishu channel: desktop-app upgrade wipes optional lark-oapi dependency, silently breaking the channel (needs reinstall every upgrade) #14618, or the change covers those two install lines.

What this change ships

Inventory (2 items) — 1 justified

Intent: 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).

  1. The Feishu guide now warns desktop users not to pip install into the app, and tells them to run their own gateway — symptom-level: 2 sibling guides carry the same advice, unfixed
  2. The Feishu Known-gaps list now has a line pointing to the desktop note — justified

[FIRST-PRINCIPLES-REVIEWED] 8da9245

Description read

[DESCRIPTION-READ] c219d982beeade5646eaed40bda52c9e0ae7cafbff92669b0ee84029a1d3d620

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 8da9245

Verdict parsed from the review's SHA-scoped output markers for commit 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8da9245

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8da9245de65e6f42ccdd1d7ce6af4d4cfc665a99: <one-sentence reason>

@CrysisDeu
CrysisDeu force-pushed the fix/14618-feishu-sdk-missing-not-silent branch 2 times, most recently from ba06581 to 9262f7a Compare October 14, 2026 08:55
@CrysisDeu CrysisDeu changed the title fix(feishu): surface sdk-missing reinstall command after desktop upgrade docs(feishu): document desktop-app upgrade wipes lark-oapi Oct 14, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision labels Oct 14, 2026
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
@iamwhatever
iamwhatever force-pushed the fix/14618-feishu-sdk-missing-not-silent branch from 9262f7a to 8da9245 Compare October 19, 2026 18:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 19, 2026
@iamwhatever

iamwhatever commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

span=c4565a92afb7

  • fixed (description): sibling guides named as out of scope

The WhatsApp and Teams guides carry the same bundled-install gap. The PR body's Not a goal now names both as siblings left for #14618; this PR stays the Feishu fix from that report.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • rebutted: Getting Started covers both non-bundled paths

getting-started.md has an install.sh managed-venv path (lines 40-50) and a "From a source checkout" section (line 54) with pip install -e and a .venv via make build, so the link lands on both paths the note names.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 19, 2026

@mbriones98 mbriones98 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checks green and readiness passed at 8da9245; no behavior change.

@iamwhatever
iamwhatever merged commit 2c1997d into main Oct 19, 2026
162 of 163 checks passed
@iamwhatever
iamwhatever deleted the fix/14618-feishu-sdk-missing-not-silent branch October 19, 2026 20:43
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 2026
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.

3 participants