@rsdoctor/docs 1.5.15 → 1.5.17

package/docs/en/config/options/_meta.json

@@ -6,6 +6,7 @@
   "features",
   "output",
   "port",
+  "server",
   "supports",
   "brief",
   "mode",

package/docs/en/config/options/options.mdx

@@ -77,6 +77,7 @@ This `Options` object is the configuration for [RsdoctorRspackPlugin](#rsdoctorr
 - [features](./features.mdx) - **Feature Toggle Configuration**: Control various analysis features of Rsdoctor, such as loader analysis, bundle analysis, rule checking, etc.
 - [output](./output.mdx) - **Output Related Configuration**: Control report output format, directory and other options, including mode, options, reportCodeType, etc.
 - [port](./port.mdx) - **Service Port Configuration**: Set the port number for the Rsdoctor development server, used for report preview during local development.
+- [server](./server.mdx) - **Report Server Configuration**: Configure the Rsdoctor report server, including `server.port` and `server.cors`.
 - [supports](./supports.mdx) - **Feature Support Configuration**: Enable compatibility support for specific build tools, such as BannerPlugin, etc.
 - [brief](./brief.mdx) - **Brief Mode Configuration**: Control the generation of brief mode reports, including HTML filename and whether to generate JSON data files.
 - [mode](./mode.mdx) - **Build Report Data Output Mode**: Select the output mode for reports, supporting normal (normal mode) and brief (brief mode).
@@ -109,6 +110,8 @@ interface RsdoctorWebpackPluginOptions<
 
   port?: number;
 
+  server?: SDK.RsdoctorServerConfig;
+
   /**
    * @deprecated Use `output.options.htmlOptions` instead
    */

package/docs/en/config/options/server.mdx

@@ -0,0 +1,124 @@
+# server
+
+- **Type:** `RsdoctorServerConfig`
+- **Optional:** `true`
+- **Default:** `{}`
+
+Configure the Rsdoctor report server.
+
+## port
+
+- **Type:** `number`
+- **Optional:** `true`
+- **Default:** `random(3000, 8999)`
+
+Configure the port for the Rsdoctor report server.
+
+If `server.port` is not set, Rsdoctor uses the top-level [`port`](./port.mdx) option. If both options are set, `server.port` takes priority.
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+## cors
+
+- **Type:** `boolean | RsdoctorServerCorsOptions`
+- **Optional:** `true`
+- **Default:** Allows local origins only.
+
+Configure CORS response headers for the Rsdoctor report server.
+
+By default, Rsdoctor allows local origins only:
+
+- `http://localhost` and `https://localhost`
+- `localhost` subdomains, such as `http://foo.localhost`
+- `http://127.0.0.1` and `https://127.0.0.1`
+- `http://[::1]` and `https://[::1]`
+
+All default local origins can include any port.
+
+### Values
+
+- `false`: Disable the CORS middleware.
+- `true`: Use the defaults from the `cors` package.
+- `object`: Pass options to the `cors` middleware. If `origin` is omitted, Rsdoctor keeps the default local-origin policy. If `origin` is set, it replaces the default local-origin policy.
+
+Rsdoctor still validates local request hosts separately. The `cors` option only controls CORS middleware behavior and response headers.
+
+### Examples
+
+Allow a custom origin:
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: {
+      origin: 'https://example.com',
+      credentials: true,
+    },
+  },
+});
+```
+
+Keep the default local-origin policy and add other CORS options:
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: {
+      credentials: true,
+      methods: ['GET', 'POST', 'OPTIONS'],
+    },
+  },
+});
+```
+
+Use the `cors` package defaults:
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: true,
+  },
+});
+```
+
+### Type definitions
+
+```ts
+interface RsdoctorServerConfig {
+  port?: number;
+  cors?: boolean | RsdoctorServerCorsOptions;
+}
+
+type RsdoctorServerCorsStaticOrigin =
+  | boolean
+  | string
+  | RegExp
+  | Array<boolean | string | RegExp>;
+
+type RsdoctorServerCorsOrigin =
+  | RsdoctorServerCorsStaticOrigin
+  | ((
+      requestOrigin: string | undefined,
+      callback: (
+        err: Error | null,
+        origin?: RsdoctorServerCorsStaticOrigin,
+      ) => void,
+    ) => void);
+
+interface RsdoctorServerCorsOptions {
+  origin?: RsdoctorServerCorsOrigin;
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+  optionsSuccessStatus?: number;
+}
+```

package/docs/en/guide/start/action.mdx

@@ -59,6 +59,8 @@ target_branch: ${{ github.event_name == 'pull_request' && github.event.pull_requ
 ```
 
 - `dispatch_target_branch`: Optional, used to specify the target branch when manually triggered (workflow_dispatch).
+- `AI_TOKEN`: Optional, used to enable AI-assisted bundle degradation analysis. Configure it as a GitHub Actions secret and pass it to the action step through `env`.
+- `ai_model`: Optional, AI model used for degradation analysis. The default is `claude-3-5-haiku-latest`. The provider is automatically detected from the model name prefix. Supported prefixes include `claude`, `gemini`, `deepseek`, and `qwen`; other model names use the OpenAI provider.
 
 - `on` indicates when the workflow runs, commonly set to `pull_request` and `push`, and also supports `workflow_dispatch` for manual triggering.
   - On `pull_request`, Rsdoctor Action fetches baseline and current and performs bundle diff analysis.
@@ -122,6 +124,9 @@ jobs:
 
       - name: Bundle Analysis
         uses: web-infra-dev/rsdoctor-action@main
+        env:
+          # Optional. Required only when you want AI-assisted analysis.
+          AI_TOKEN: ${{ secrets.AI_TOKEN }}
         with:
           file_path: 'dist/.rsdoctor/rsdoctor-data.json'
           # Default 'main'. If you want to use a dynamic target branch, i.e., automatically get the target branch of the current pull request instead of a fixed main branch, you can use the following configuration:
@@ -129,8 +134,40 @@ jobs:
           target_branch: 'main'
           # Target branch for manual trigger
           dispatch_target_branch: ${{ github.event.inputs.target_branch }}
+          # Optional. Defaults to 'claude-3-5-haiku-latest'.
+          ai_model: 'claude-3-5-haiku-latest'
 ```
 
+## AI-assisted analysis
+
+Rsdoctor Action can use AI to summarize bundle degradation in pull requests and workflow summaries. AI-assisted analysis runs only when baseline data exists and the bundle size changes. To enable it, add an AI provider token as a repository secret and pass it to the action step:
+
+1. Open your GitHub repository, then go to `Settings` -> `Secrets and variables` -> `Actions`.
+2. Create a repository secret named `AI_TOKEN`.
+3. Pass the secret to `rsdoctor-action` with `env.AI_TOKEN`.
+4. Optionally set `ai_model` if you want to use a model other than the default `claude-3-5-haiku-latest`.
+
+```yaml
+- name: Bundle Analysis
+  uses: web-infra-dev/rsdoctor-action@main
+  env:
+    AI_TOKEN: ${{ secrets.AI_TOKEN }}
+  with:
+    file_path: 'dist/.rsdoctor/rsdoctor-data.json'
+    target_branch: 'main'
+    ai_model: 'claude-3-5-haiku-latest'
+```
+
+<div style={{ flex: '0 1 320px', maxWidth: 560, margin: 'auto' }}>
+  <img
+    src="/actions-ai-detail.png"
+    alt="AI-assisted analysis details"
+    style={{ display: 'block', width: '100%' }}
+  />
+</div>
+
+If `AI_TOKEN` is not provided, the Action still runs the regular bundle diff analysis, but AI-assisted analysis will be skipped. The token must match the provider detected from `ai_model`. For example, use an Anthropic token with `claude-*`, a Google token with `gemini-*`, a DeepSeek token with `deepseek-*`, a Qwen token with `qwen*`, or an OpenAI token with OpenAI model names such as `gpt-4o-mini`.
+
 ## View Reports
 
 After submitting the above configuration file to your repository, GitHub Actions will automatically run under the specified trigger conditions and generate Rsdoctor analysis reports. You will see bundle size change comparison prompts in GitHub CI, as shown below:
@@ -160,6 +197,14 @@ Additionally, clicking "Download Bundle Diff Report" allows you to download Rsdo
 
 - This is normal for the first run or for new repositories, because no baseline has been uploaded yet. The baseline data will be created after the first merge into the main branch.
 
+**Q: AI-assisted analysis is not shown**
+
+- Ensure the `AI_TOKEN` secret has been created in repository settings and passed to the action step through `env`.
+- Check whether the selected `ai_model` matches the provider token. The provider is detected from the model name prefix.
+- Confirm that baseline data exists and the bundle size changed in the current run.
+- For pull requests from forks, GitHub may not expose repository secrets to the workflow for security reasons.
+
 ## More Resources
 
 - [rsdoctor-action GitHub Repository](https://github.com/web-infra-dev/rsdoctor-action)
+- [Rsdoctor AI Guide](/guide/start/ai)

package/docs/zh/config/options/_meta.json

@@ -6,6 +6,7 @@
   "features",
   "output",
   "port",
+  "server",
   "supports",
   "brief",
   "mode",

package/docs/zh/config/options/options.mdx

@@ -77,6 +77,7 @@ new RsdoctorWebpackPlugin({
 - [features](./features.mdx) - **特性开关配置**：控制 Rsdoctor 的各项分析功能，如 loader 分析、bundle 分析、规则检查等
 - [output](./output.mdx) - **输出相关配置**：控制报告的输出格式、目录等选项，包括 mode、options、reportCodeType 等
 - [port](./port.mdx) - **服务端口配置**：设置 Rsdoctor 开发服务器的端口号，用于本地开发时的报告预览
+- [server](./server.mdx) - **报告服务配置**：配置 Rsdoctor 报告服务，包括 `server.port` 和 `server.cors`
 - [supports](./supports.mdx) - **特性支持配置**：启用特定构建工具的兼容性支持，如 BannerPlugin 等
 - [brief](./brief.mdx) - **Brief 模式的配置**：控制简要模式报告的生成，包括 HTML 文件名和是否生成 JSON 数据文件
 - [mode](./mode.mdx) - **构建报告数据输出模式**：选择报告的输出模式，支持 normal（普通模式）和 brief（简要模式）
@@ -108,6 +109,8 @@ interface RsdoctorWebpackPluginOptions<
 
   port?: number;
 
+  server?: SDK.RsdoctorServerConfig;
+
   /**
    * @deprecated 使用 `output.options.htmlOptions` 代替
    */

package/docs/zh/config/options/server.mdx

@@ -0,0 +1,124 @@
+# server
+
+- **类型：** `RsdoctorServerConfig`
+- **可选：** `true`
+- **默认值：** `{}`
+
+配置 Rsdoctor 报告服务。
+
+## port
+
+- **类型：** `number`
+- **可选：** `true`
+- **默认值：** `random(3000, 8999)`
+
+配置 Rsdoctor 报告服务的端口。
+
+如果没有配置 `server.port`，Rsdoctor 会使用顶层 [`port`](./port.mdx) 配置。如果两个配置同时存在，`server.port` 优先级更高。
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+## cors
+
+- **类型：** `boolean | RsdoctorServerCorsOptions`
+- **可选：** `true`
+- **默认值：** 只允许本地来源。
+
+配置 Rsdoctor 报告服务的 CORS 响应头。
+
+默认情况下，Rsdoctor 只允许以下本地来源：
+
+- `http://localhost` 和 `https://localhost`
+- `localhost` 子域名，例如 `http://foo.localhost`
+- `http://127.0.0.1` 和 `https://127.0.0.1`
+- `http://[::1]` 和 `https://[::1]`
+
+以上默认本地来源都可以携带任意端口。
+
+### 可选值
+
+- `false`：关闭 CORS 中间件。
+- `true`：使用 `cors` 包的默认配置。
+- `object`：传递给 `cors` 中间件的配置对象。如果没有配置 `origin`，Rsdoctor 会保留默认的本地来源策略。如果配置了 `origin`，它会替换默认的本地来源策略。
+
+Rsdoctor 仍然会单独校验本地请求 Host。`cors` 配置只控制 CORS 中间件行为和响应头。
+
+### 示例
+
+允许一个自定义来源：
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: {
+      origin: 'https://example.com',
+      credentials: true,
+    },
+  },
+});
+```
+
+保留默认本地来源策略，并添加其他 CORS 选项：
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: {
+      credentials: true,
+      methods: ['GET', 'POST', 'OPTIONS'],
+    },
+  },
+});
+```
+
+使用 `cors` 包的默认配置：
+
+```js
+new RsdoctorRspackPlugin({
+  server: {
+    cors: true,
+  },
+});
+```
+
+### 类型定义
+
+```ts
+interface RsdoctorServerConfig {
+  port?: number;
+  cors?: boolean | RsdoctorServerCorsOptions;
+}
+
+type RsdoctorServerCorsStaticOrigin =
+  | boolean
+  | string
+  | RegExp
+  | Array<boolean | string | RegExp>;
+
+type RsdoctorServerCorsOrigin =
+  | RsdoctorServerCorsStaticOrigin
+  | ((
+      requestOrigin: string | undefined,
+      callback: (
+        err: Error | null,
+        origin?: RsdoctorServerCorsStaticOrigin,
+      ) => void,
+    ) => void);
+
+interface RsdoctorServerCorsOptions {
+  origin?: RsdoctorServerCorsOrigin;
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+  optionsSuccessStatus?: number;
+}
+```

package/docs/zh/guide/start/action.mdx

@@ -59,6 +59,8 @@ target_branch: ${{ github.event_name == 'pull_request' && github.event.pull_requ
 ```
 
 - `dispatch_target_branch`：非必需，用于手动触发 (workflow_dispatch) 时指定目标分支。
+- `AI_TOKEN`：非必需，用于开启 AI 辅助的产物劣化分析。请将其配置为 GitHub Actions Secret，并通过 action step 的 `env` 传入。
+- `ai_model`：非必需，用于指定产物劣化分析使用的 AI 模型。默认值为 `claude-3-5-haiku-latest`。Action 会根据模型名称前缀自动识别 provider。支持的前缀包括 `claude`、`gemini`、`deepseek` 和 `qwen`；其他模型名称会使用 OpenAI provider。
 
 - `on` 是指 workflow 运行的时机，通常设置为 `pull_request` 和 `push`，也支持 `workflow_dispatch` 手动触发。
   - 在 `pull_request` 时，Rsdoctor Action 会拉取 baseline 和 current，进行 bundle diff 分析。
@@ -122,6 +124,9 @@ jobs:
 
       - name: Bundle Analysis
         uses: web-infra-dev/rsdoctor-action@main
+        env:
+          # 可选，仅在需要 AI 辅助分析时配置。
+          AI_TOKEN: ${{ secrets.AI_TOKEN }}
         with:
           file_path: 'dist/.rsdoctor/rsdoctor-data.json'
           # 默认 'main'，如果想用不固定的目标分支，即自动获取当前 pull request 的 target branch，则可以使用下方配置：
@@ -129,8 +134,40 @@ jobs:
           target_branch: 'main'
           # 手动触发时使用的目标分支
           dispatch_target_branch: ${{ github.event.inputs.target_branch }}
+          # 可选，默认值为 'claude-3-5-haiku-latest'。
+          ai_model: 'claude-3-5-haiku-latest'
 ```
 
+## AI 辅助分析
+
+Rsdoctor Action 可以借助 AI 在 Pull Request 评论和 workflow summary 中总结产物劣化原因。AI 辅助分析只会在存在 baseline 数据且产物体积发生变化时运行。启用方式如下：
+
+1. 打开 GitHub 仓库，进入 `Settings` -> `Secrets and variables` -> `Actions`。
+2. 创建名为 `AI_TOKEN` 的 repository secret。
+3. 通过 `env.AI_TOKEN` 将 Secret 传入 `rsdoctor-action`。
+4. 如果不想使用默认的 `claude-3-5-haiku-latest`，可以通过 `ai_model` 指定其他模型。
+
+```yaml
+- name: Bundle Analysis
+  uses: web-infra-dev/rsdoctor-action@main
+  env:
+    AI_TOKEN: ${{ secrets.AI_TOKEN }}
+  with:
+    file_path: 'dist/.rsdoctor/rsdoctor-data.json'
+    target_branch: 'main'
+    ai_model: 'claude-3-5-haiku-latest'
+```
+
+<div style={{ flex: '0 1 320px', maxWidth: 560, margin: 'auto' }}>
+  <img
+    src="/actions-ai-detail.png"
+    alt="AI 辅助分析详情"
+    style={{ display: 'block', width: '100%' }}
+  />
+</div>
+
+如果未提供 `AI_TOKEN`，Action 仍会执行常规的 bundle diff 分析，但会跳过 AI 辅助分析。`AI_TOKEN` 需要与 `ai_model` 自动识别出的 provider 匹配。例如，`claude-*` 使用 Anthropic token，`gemini-*` 使用 Google token，`deepseek-*` 使用 DeepSeek token，`qwen*` 使用 Qwen token，`gpt-4o-mini` 等 OpenAI 模型使用 OpenAI token。
+
 ## 查看报告
 
 将上述配置文件提交到你的仓库后，GitHub Actions 将在指定的触发条件下自动运行，生成 Rsdoctor 的分析报告。你将在 GitHub CI 中看到 Bundle 大小变化的对比提示，如下图：
@@ -160,6 +197,14 @@ jobs:
 
 - 这对于首次运行或新仓库是正常的，因为还没有上传 Baseline。因为基线数据将在首次合并到主分支后创建。
 
+**Q: 没有展示 AI 辅助分析**
+
+- 确保已经在仓库设置中创建 `AI_TOKEN` Secret，并通过 action step 的 `env` 传入。
+- 检查当前 `ai_model` 是否与传入的 provider token 匹配。Action 会根据模型名称前缀识别 provider。
+- 确认当前 workflow 已存在 baseline 数据，并且本次产物体积发生了变化。
+- 对于来自 fork 仓库的 Pull Request，GitHub 出于安全原因可能不会向 workflow 暴露仓库 Secrets。
+
 ## 更多资源
 
 - [rsdoctor-action GitHub 仓库](https://github.com/web-infra-dev/rsdoctor-action)
+- [Rsdoctor AI 指南](/guide/start/ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdoctor/docs",
-  "version": "1.5.15",
+  "version": "1.5.17",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/rsdoctor",
@@ -35,7 +35,7 @@
     "rspress-plugin-sitemap": "^1.2.1",
     "typescript": "^6.0.3",
     "@rsbuild/plugin-sass": "^1.5.3",
-    "@rsdoctor/types": "1.5.15"
+    "@rsdoctor/types": "1.5.17"
   },
   "dependencies": {
     "@rstack-dev/doc-ui": "1.14.3",