feat(runtime): add AI remote proxy plugin

apps/website-new/docs/en/plugin/plugins/_meta.json

@@ -1 +1 @@
-["index", "retry-plugin", "observability-plugin", "building-custom-retry-plugin"]
+["index", "retry-plugin", "module-federation-ai-proxy-remotes", "observability-plugin", "building-custom-retry-plugin"]

apps/website-new/docs/en/plugin/plugins/module-federation-ai-proxy-remotes.mdx

@@ -0,0 +1,133 @@
+---
+title: AI Proxy Remotes Plugin
+description: Let AI proxy Module Federation Remotes in any environment without depending on a Chrome extension environment.
+---
+
+# AI Proxy Remotes Plugin
+
+Use `module-federation-ai-proxy-remotes` to let AI debug Module Federation remotes in any environment by switching them to local manifests from a URL or a floating browser console, without depending on a Chrome extension environment.
+
+## Use Cases
+
+- Ask an AI coding agent to start a remote locally and open the host with the correct proxy rule.
+- Debug a host against one or more locally running remotes.
+- Debug H5 environments where installing or using a Chrome extension is inconvenient. Proxy rules work through the URL or in-page floating console without desktop Chrome DevTools.
+- Save and switch proxy rules from the page without opening DevTools.
+
+## Install
+
+```bash
+pnpm add -D module-federation-ai-proxy-remotes
+```
+
+## Add the Runtime Plugin
+
+Install and configure this plugin in the **host** application.
+
+Add the package name to `runtimePlugins` in the Module Federation plugin configuration:
+
+```ts title="module-federation.config.ts"
+export default {
+  name: 'host',
+  runtimePlugins: ['module-federation-ai-proxy-remotes'],
+};
+```
+
+## Enable Debugging
+
+Add `__mf_devtools` to the host URL:
+
+```text
+https://host.example.com/remote?__mf_devtools
+```
+
+The page refreshes and removes the parameter from the address bar. Debugging remains enabled for the current tab session. Use **Disable debug** in the floating console to turn it off; saved rules are retained until the tab session ends.
+
+## Debug a Remote with AI
+
+Give your AI coding agent a request such as:
+
+```text
+Start the remote remote locally, find its mf-manifest.json URL, and open
+https://host.example.com/remote with remote proxied to that local manifest.
+```
+
+### Complete Debugging URL Example
+
+Given:
+
+- Host page: `https://host.example.com/remote`;
+- Remote name: `remote`; and
+- local Manifest: `http://localhost:3001/mf-manifest.json`.
+
+The AI agent can build the complete debugging URL directly:
+
+```js
+const remoteName = 'remote';
+const localManifestUrl = 'http://localhost:3001/mf-manifest.json';
+const hostUrl = new URL('https://host.example.com/remote');
+
+hostUrl.searchParams.set(
+  '__mf_devtools',
+  JSON.stringify({
+    overrides: {
+      [remoteName]: localManifestUrl,
+    },
+  }),
+);
+
+console.log(hostUrl.href);
+```
+
+Or use the package helper:
+
+```js
+import { generateAIDebugUrl } from 'module-federation-ai-proxy-remotes';
+
+const debugUrl = generateAIDebugUrl('https://host.example.com/remote', {
+  remote: 'http://localhost:3001/mf-manifest.json',
+});
+
+console.log(debugUrl);
+```
+
+The output is:
+
+```text
+https://host.example.com/remote?__mf_devtools=%7B%22overrides%22%3A%7B%22remote%22%3A%22http%3A%2F%2Flocalhost%3A3001%2Fmf-manifest.json%22%7D%7D
+```
+
+The AI agent should then open this complete URL in the browser. After the page refreshes, the `remote` Remote in the Host uses the local Manifest. Remote names and aliases are both supported as `overrides` keys.
+
+## Proxy Domain Security
+
+By default, the plugin only accepts manifest URLs hosted on `localhost` or `127.0.0.1`. Every override URL must:
+
+- use the `http:` or `https:` protocol;
+- point to a path ending in `.json`;
+- not contain a username or password; and
+- use a default host or a hostname explicitly listed in `allowedHosts`.
+
+`allowedHosts` contains exact hostnames without a protocol, port, path, or wildcard. For example, `assets.example.com` allows URLs on that hostname, including URLs with an explicit port, but does not allow `sub.assets.example.com`.
+
+Add only trusted hosts that are required for debugging:
+
+```ts
+import { aiDebugRuntimePlugin } from 'module-federation-ai-proxy-remotes/core';
+
+export default () =>
+  aiDebugRuntimePlugin({
+    allowedHosts: ['assets.example.com', 'mf-dev.internal.example.com'],
+  });
+```
+
+The target server must also allow the host application to request the manifest according to its CORS policy. Remove temporary non-local hosts after debugging.
+
+## Options
+
+| Option | Type | Default | Usage |
+| --- | --- | --- | --- |
+| `allowedHosts` | `string[]` | `[]` | Allow additional trusted manifest hosts. |
+| `parameterName` | `string` | `__mf_devtools` | Use another activation and configuration parameter. |
+| `storageKey` | `string` | `__MF_DEVTOOLS__` | Use another session storage key for saved rules. |
+| `console` | `boolean \| AIDebugConsoleOptions` | URL-controlled | Hide or configure the floating console. |

apps/website-new/docs/zh/plugin/plugins/_meta.json

@@ -1 +1 @@
-["retry-plugin", "observability-plugin"]
+["retry-plugin", "module-federation-ai-proxy-remotes", "observability-plugin"]

apps/website-new/docs/zh/plugin/plugins/module-federation-ai-proxy-remotes.mdx

@@ -0,0 +1,133 @@
+---
+title: AI 代理远程插件
+description: 让 AI 在任何环境代理 Module Federation Remote，不依赖 Chrome 扩展环境。
+---
+
+# AI 代理远程插件
+
+使用 `module-federation-ai-proxy-remotes`，AI 可以在任何环境中通过 URL 或页面内的浮动控制台，把 Module Federation Remote 切换到本地 Manifest，不依赖 Chrome 扩展环境。
+
+## 使用场景
+
+- 让 AI 编程 Agent 在本地启动 Remote，并使用正确的代理规则打开宿主页面。
+- 使用一个或多个本地 Remote 调试宿主应用。
+- 调试不方便安装或使用 Chrome 扩展的 H5 环境。代理规则通过 URL 或页面内浮动控制台生效，不依赖桌面 Chrome DevTools。
+- 不打开 DevTools，直接在页面中保存和切换 Remote 代理规则。
+
+## 安装
+
+```bash
+pnpm add -D module-federation-ai-proxy-remotes
+```
+
+## 接入 Runtime Plugin
+
+该插件需要安装并配置在 **Host** 应用中。
+
+在 Module Federation 插件配置的 `runtimePlugins` 中填写包名：
+
+```ts title="module-federation.config.ts"
+export default {
+  name: 'host',
+  runtimePlugins: ['module-federation-ai-proxy-remotes'],
+};
+```
+
+## 开启调试
+
+在宿主 URL 中加入 `__mf_devtools`：
+
+```text
+https://host.example.com/remote?__mf_devtools
+```
+
+页面会刷新并从地址栏移除该参数。调试开关会在当前标签页会话内保留，无需再次添加参数。点击浮动控制台中的 **Disable debug** 可以关闭调试；关闭标签页后，已保存的代理规则会随会话结束而清除。
+
+## 使用 AI 调试 Remote
+
+可以向 AI 编程 Agent 提出类似下面的请求：
+
+```text
+在本地启动 remote remote，找到它的 mf-manifest.json 地址，然后打开
+https://host.example.com/remote，并把 remote 代理到这个本地 Manifest。
+```
+
+### 完整调试 URL 示例
+
+假设：
+
+- Host 页面是 `https://host.example.com/remote`；
+- Remote 名称是 `remote`；
+- 本地 Manifest 是 `http://localhost:3001/mf-manifest.json`。
+
+AI 可以直接使用下面的代码拼出完整调试 URL：
+
+```js
+const remoteName = 'remote';
+const localManifestUrl = 'http://localhost:3001/mf-manifest.json';
+const hostUrl = new URL('https://host.example.com/remote');
+
+hostUrl.searchParams.set(
+  '__mf_devtools',
+  JSON.stringify({
+    overrides: {
+      [remoteName]: localManifestUrl,
+    },
+  }),
+);
+
+console.log(hostUrl.href);
+```
+
+也可以使用包提供的辅助函数：
+
+```js
+import { generateAIDebugUrl } from 'module-federation-ai-proxy-remotes';
+
+const debugUrl = generateAIDebugUrl('https://host.example.com/remote', {
+  remote: 'http://localhost:3001/mf-manifest.json',
+});
+
+console.log(debugUrl);
+```
+
+输出结果是：
+
+```text
+https://host.example.com/remote?__mf_devtools=%7B%22overrides%22%3A%7B%22remote%22%3A%22http%3A%2F%2Flocalhost%3A3001%2Fmf-manifest.json%22%7D%7D
+```
+
+AI 最后需要在浏览器中打开这个完整 URL。页面刷新后，Host 中名为 `remote` 的 Remote 将使用本地 Manifest。Remote 的 `name` 和 `alias` 均可作为 `overrides` 的键。
+
+## 代理域名安全策略
+
+默认只允许代理到 `localhost` 或 `127.0.0.1` 上的 Manifest。每个代理地址必须满足以下条件：
+
+- 使用 `http:` 或 `https:` 协议；
+- URL 路径以 `.json` 结尾；
+- URL 不包含用户名或密码；
+- 使用默认允许的主机，或使用 `allowedHosts` 中显式配置的主机名。
+
+`allowedHosts` 使用精确主机名，不要包含协议、端口、路径或通配符。例如，`assets.example.com` 允许该主机名上的 URL，包括带端口的 URL，但不允许 `sub.assets.example.com`。
+
+只添加调试所需且可信的主机：
+
+```ts
+import { aiDebugRuntimePlugin } from 'module-federation-ai-proxy-remotes/core';
+
+export default () =>
+  aiDebugRuntimePlugin({
+    allowedHosts: ['assets.example.com', 'mf-dev.internal.example.com'],
+  });
+```
+
+目标服务器还需要通过 CORS 策略允许 Host 应用请求 Manifest。调试结束后，应删除临时添加的非本地主机。
+
+## 配置项
+
+| 配置项 | 类型 | 默认值 | 用途 |
+| --- | --- | --- | --- |
+| `allowedHosts` | `string[]` | `[]` | 允许额外的可信 Manifest 主机。 |
+| `parameterName` | `string` | `__mf_devtools` | 使用其他 URL 参数开启调试并传入配置。 |
+| `storageKey` | `string` | `__MF_DEVTOOLS__` | 使用其他 sessionStorage key 保存规则。 |
+| `console` | `boolean \| AIDebugConsoleOptions` | 由 URL 控制 | 隐藏或配置浮动控制台。 |

packages/runtime-plugins/module-federation-ai-proxy-remotes/.swcrc

@@ -0,0 +1,28 @@
+{
+  "jsc": {
+    "target": "es2017",
+    "parser": {
+      "syntax": "typescript",
+      "decorators": true,
+      "dynamicImport": true
+    },
+    "transform": {
+      "decoratorMetadata": true,
+      "legacyDecorator": true
+    },
+    "keepClassNames": true,
+    "externalHelpers": true,
+    "loose": true
+  },
+  "module": {
+    "type": "es6"
+  },
+  "sourceMaps": true,
+  "inputSourceMap": false,
+  "exclude": [
+    "jest.config.ts",
+    "./src/jest-setup.ts$",
+    "./**/jest-setup.ts$",
+    ".*.js$"
+  ]
+}

packages/runtime-plugins/module-federation-ai-proxy-remotes/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-present Zack Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.