ALemonX WebView 架构边界
September 2, 2026 · View on GitHub
ALemonX 中“嵌入页面”不是同一种能力。系统插件页面、机器人应用页与内置浏览器是三个独立运行域；它们不能复用代理链、页面注入、SPA fallback、鉴权、路由或状态机。
三个运行域
| 运行域 | 用途 | 页面能力 | 网络模型 |
|---|---|---|---|
| 系统插件 WebView | 系统插件控制台及 webview.open({ resource }) | ALXHost、系统插件受控能力 | 插件同源静态托管；不经过浏览器 HTTP 代理 |
| 机器人应用页 | 机器人包注册的应用页 | window.__alxWebview，仅当前机器人 ./api/* | 机器人专用代理与 token；不经过系统插件或浏览器逻辑 |
| 内置浏览器 | 用户、服务预览、智能日志和插件打开 URL | 标签、历史、站点会话；不提供 ALXHost 或机器人桥 | HTTP 经浏览器专用后端代理；HTTPS 直连 |
桌面窗口外壳、无业务语义的类型和纯 URL 基元可作为基础设施共享；任何带有页面、代理、权限、注入或回退语义的代码都必须留在所属运行域。
系统插件打开页面
ALXHost.webview.open({ resource })保持系统插件 WebView：资源必须位于插件web.root，并保留主题、宿主桥接和插件窗口生命周期。ALXHost.webview.open({ url })不创建普通 iframe。宿主在内置浏览器中创建新标签；返回的id是该标签的句柄。ALXHost.webview.close(id)只能关闭同一插件通过url或resource打开的句柄。用户自行关闭标签或关闭浏览器窗口后，重复关闭是幂等操作。
URL 页面永远不获得 ALXHost、系统插件身份或机器人应用上下文。
内置浏览器 HTTP 兼容代理
HTTP 页面展示在工作台来源下，因此根绝对路径会天然逃逸到工作台，例如 src="/app.js" 会成为工作台的 /app.js。内置浏览器以三层方式处理：
- 响应转换：结构化转换 HTML、CSS、重定向和已知静态资源地址，将根绝对路径和 HTTP 跨源地址放入正确的目标代理挂载点。
- 页面运行时：在文档最早位置映射动态 API、表单、Worker、Service Worker、SSE、WebSocket 和弹窗地址，并接管链接、
location.assign()、location.replace()等文档导航；逻辑地址始终是目标站地址。 - 网关逃逸回收：在工作台 API、静态资源和 SPA fallback 之前检查有效的浏览器代理 Referer。任何逃逸到工作台的
/、/assets/...、/api/...或升级请求都回收到其原目标站，而非返回工作台首页。
未带有效浏览器代理 Referer 的请求不参与回收：工作台 / 仍是首页，工作台 API 仍按原权限与路由处理。HTTP 代理页保留同源完整 Referer 供回收层识别；HTTPS 直连页仍不发送 Referer 给外部站点。
浏览器 HTTP Cookie、localStorage、sessionStorage、IndexedDB、Cache Storage 与认证状态均按目标 HTTP 源隔离；上游收到逻辑 Origin 与 Referer，不会看到工作台代理路径。
地址补全与导航边界
地址栏保存“逻辑地址”，不会因浏览器标准 URL 自动省略 :80 或 :443。补全规则为：端口单独输入时补为 http://127.0.0.1:<port>；无协议主机按 IP/localhost 使用 HTTP 与 80、按域名使用 HTTPS 与 443；显式 :80 使用 HTTP，显式 :443 使用 HTTPS；其他显式端口按 IP 使用 HTTP、按域名使用 HTTPS；带协议但无端口时 HTTPS 补 443，其余 HTTP 补 80。
已打开站点时，地址栏还接受纯路径引用，并自动以当前标签的逻辑站点地址补全：/settings、./settings、../settings、settings/users、?page=2 和 #section 都在当前站点内访问。没有已访问站点的首页标签不会猜测目标主机，而会提示用户先输入完整站点地址；普通无斜杠文本仍作为搜索词处理。
内置浏览器窗口始终至少保留一个“首页”标签。关闭最后一个标签会回到首页；关闭窗口按钮才会关闭整个浏览器窗口。这也保证将 URL 交给系统浏览器后，内置窗口不会出现无标签的首页画面。
“同站”比较协议、主机与有效端口。以下规则只作用于页面导航（地址栏、链接、弹窗和文档导航），不改变 fetch、图片、模块、SSE、WebSocket 等子资源请求：
| 导航目标 | 去向 |
|---|---|
| 同站 HTTP 或 HTTPS | 内置浏览器；地址栏仅显示路径、查询与锚点 |
| 跨站 HTTPS | 系统默认浏览器 |
| 跨站 HTTP，内网目标 | 内置浏览器 HTTP 代理 |
| 跨站 HTTP，公网目标 | 系统默认浏览器 |
内网目标包括 localhost、私网/回环/链路本地 IP，以及 DNS 解析到任一此类 IP 的域名。工作台无法解析的域名按公网交给系统默认浏览器，让本机浏览器、VPN 和其 DNS 环境决定最终访问。系统默认浏览器由操作系统处理，实际以新标签还是新窗口由用户浏览器设置决定。
跨站 GET 表单会序列化为目标 URL 后按上述导航规则处理。跨站 POST/PUT 等携带正文的表单不会自动转交系统浏览器：外部浏览器无法安全继承内置浏览器当前表单数据与会话，宿主会阻止提交并给出明确提示，避免误提交或静默丢失数据。