ewoooc/docs/guides/webcrumbs_shared_runtime.md

Webcrumbs 共用 UI Runtime 接入手冊

目的：讓 momo-pro 與其他專案共用同一套自架 Webcrumbs microfrontend runtime，避免每個專案各自引用官方 CDN 或複製 runtime。

定位

• Webcrumbs 在本專案只作為 microfrontend/plugin loader。
• 不把 Webcrumbs 上游 repo 整包放進 momo-pro 主服務。
• 不依賴官方 app.webcrumbs.ai 或官方 cdn.webcrumbs.dev/@latest。
• 生產環境必須走自架 runtime，並固定版本。

momo-pro 設定

.env 建議值：

WEBCRUMBS_ENABLED=true
WEBCRUMBS_BASE_URL=https://webcrumbs.wooo.work
WEBCRUMBS_RUNTIME_VERSION=@v0.1.5
WEBCRUMBS_RUNTIME_PATH=/runtime/@v0.1.5
WEBCRUMBS_RUNTIME_URL=
WEBCRUMBS_PLUGIN_BASE_URL=https://webcrumbs.wooo.work/plugins/momo-pro

若實際部署成 CDN 相容路徑，例如 https://webcrumbs.wooo.work/@v0.1.5，請改用：

WEBCRUMBS_RUNTIME_PATH=/@v0.1.5

若部署路徑完全不同，直接設定：

WEBCRUMBS_RUNTIME_URL=https://webcrumbs.wooo.work/custom/runtime.js

頁面嵌入方式

全站 runtime 由 templates/ewoooc_base.html 載入。頁面只需要放 plugin tag：

<webcrumbs-plugin uri="https://webcrumbs.wooo.work/plugins/momo-pro/price-card/v2026.05.31/"></webcrumbs-plugin>

Plugin 目錄至少應提供：

bundle.js
style.css

治理規則

• Plugin URI 必須使用自架 domain。
• Plugin 目錄必須版本化，不使用浮動 latest。
• Plugin 不得包含 secret、token、內部 API key。
• Plugin 若需要正式資料，必須讀 momo-pro 既有 API，不得自行打 DB。
• 修改 Webcrumbs runtime 本體時需注意 AGPL-3.0 授權義務。

驗收

• /webcrumbs 顯示 runtime URL、版本與 plugin base。
• ewoooc_base.html 在 WEBCRUMBS_ENABLED=true 且 runtime URL 有效時輸出 <script data-webcrumbs-runtime=...>。
• 任一試點頁嵌入 plugin 後，瀏覽器 console 不應有 MISSING_URI、STYLE_LOAD_ERROR、SCRIPT_LOAD_ERROR。