@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.9 → 3.5.0-ultramodern.0

package/docs/zh/community/blog/v3-release-note.mdx

@@ -591,7 +591,7 @@ Modern.js 3.0 新项目默认使用 React 19，最低支持 React 18。
 
 #### Storybook Rsbuild
 
-在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rspack-contrib/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
+在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
 
 通过 Storybook Addon，我们将 Modern.js 配置转换合并为 Rsbuild 配置，并通过 Storybook Rsbuild 驱动构建，让 Storybook 调试与开发命令保持配置对齐。
 

package/docs/zh/configure/app/bff/effect.mdx

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -58,7 +59,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 ## bff.effect.entry
 
 - **类型：** `string`
-- **默认值：** `<apiDirectory>/effect/index`
+- **默认值：** `<apiDirectory>/index`
 
 用于指定 Effect HttpApi 运行时入口模块。
 
@@ -67,12 +68,22 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
 
+## bff.effect.strictEffectApproach
+
+- **类型：** `true`
+- **默认值：** `true`
+
+Effect BFF 模块必须导出严格 Effect API surface（`defineEffectBff(...)` 或
+`{ api, layer }`），原始 request handler 会被拒绝。生成的 UltraModern 应用会显式
+写入这个标记，并通过源码检查拒绝生成 API 模块中的 Hono server import、手写
+request parsing 和手写 `Response`。
+
 ## bff.effect.openapi
 
 - **类型：** `boolean | { path?: string }`
@@ -173,4 +184,4 @@ export default defineConfig({
 
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
 
-生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。

package/docs/zh/configure/app/bff/runtime-framework.mdx

@@ -21,8 +21,10 @@ export default defineConfig({
 });
 ```
 
-- 设置为 `'effect'` 时，仅从 `api/effect/index` 运行 BFF（Effect HttpApi 运行时）。
+- 设置为 `'effect'` 时，仅从 `api/index` 运行 BFF（Effect HttpApi 运行时）。
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。
+生成的 UltraModern 应用默认使用严格 Effect API，并设置
+`bff.effect.strictEffectApproach: true`；`hono` 与 `api/lambda/**` 不是生成
+UltraModern HTTP API 的有效路径。

package/docs/zh/configure/app/experiments/source-build.mdx

@@ -21,7 +21,7 @@ export default {
 
 ### 选项
 
-`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
+`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
 
 ```ts
 export default {

package/docs/zh/configure/app/html/template-parameters.mdx

@@ -30,7 +30,7 @@ type DefaultParameters = {
 };
 ```
 
-定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的 `templateParameters` 配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/output/convert-to-rem.mdx

@@ -80,5 +80,5 @@ export default {
 };
 ```
 
-详细用法可参考 [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem)。
+详细用法可参考 [rsbuild-plugin-rem](https://github.com/rstackjs/rsbuild-plugin-rem)。
 

package/docs/zh/configure/app/security/check-syntax.mdx

@@ -70,4 +70,4 @@ error   [Syntax Checker] Find some syntax errors after production build:
 
 ### 选项
 
-`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)。
+`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax)。

package/docs/zh/configure/app/tools/html-plugin.mdx

@@ -38,7 +38,7 @@ const defaultOptions = {
 SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
 :::
 
-通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -43,6 +43,8 @@ const defaultOptions = {
 
 ## 示例
 
+### Object 类型
+
 当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
 
 ```ts
@@ -57,6 +59,23 @@ export default {
 };
 ```
 
+### Function 类型
+
+当 `tsChecker` 的值为函数时，默认配置会作为第一个参数传入。你可以直接修改配置对象，也可以返回一个对象作为最终配置。
+
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+
+> 更多详情请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)。
+
 ## TypeScript Go 默认开启
 
 类型检查默认使用 [TypeScript Go](https://github.com/microsoft/typescript-go)（`tsgo`）。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以将类型检查耗时减少约 5-10 倍。

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -59,9 +59,9 @@ Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要
 
 ## Effect 客户端自动行为
 
-使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
+使用生成的 Effect 客户端（`@api/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
 
-生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/index` 导入；直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
 
 Envelope 默认包含：
 

package/docs/zh/guides/advanced-features/bff/frameworks.mdx

@@ -7,11 +7,19 @@ title: 运行时框架
 
 Modern.js 目前支持两种 BFF 运行时框架：
 
-- `effect`（默认）：使用 `api/effect/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
+- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 - `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
 
+::::info
+本页记录通用 Modern.js 运行时能力。生成的 UltraModern workspace 始终使用
+`effect` 运行时，并设置 `bff.effect.strictEffectApproach: true`。新增或修改生成的
+UltraModern HTTP API 时，先改 `shared/api.ts`，再改 `api/index.ts`；不要在这些
+workspace 中加入 Hono/file-convention handler、原始 request parsing 或手写
+`Response`。
+::::
+
 ## 切换到 Effect 运行时
 
 ```ts title="modern.config.ts"
@@ -23,6 +31,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +43,7 @@ export default defineConfig({
 
 先在共享目录中定义 Effect HttpApi 契约（前后端共享类型）：
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +51,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-然后在 `api/effect/index.ts` 中实现 Effect BFF 入口：
+然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +71,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +97,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +107,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@api/index` 调用接口：
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
 
 import Hono from '@site-docs/components/hono';
 

package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -92,7 +92,7 @@ export default {
 };
 ```
 
-详见 [Image Compress 插件](https://github.com/rspack-contrib/rsbuild-plugin-image-compress)。
+详见 [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)。
 
 ## 代码拆包
 

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -89,4 +89,4 @@ pnpm storybook
 
 ## 示例
 
-你可以查看 [示例](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。
+你可以查看 [示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。

package/docs/zh/guides/basic-features/static-assets/json-files.mdx

@@ -38,7 +38,7 @@ import { name } from './example.json';
 
 YAML 是一种数据序列化语言，通常用于编写配置文件。
 
-你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
@@ -85,7 +85,7 @@ declare module '*.yml' {
 
 TOML 是一种语义明显、易于阅读的配置文件格式。
 
-你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';

package/docs/zh/guides/get-started/_meta.json

@@ -4,5 +4,6 @@
   "quick-start",
   "upgrade",
   "glossary",
-  "tech-stack"
+  "tech-stack",
+  "ai-coding-agents"
 ]

package/docs/zh/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,48 @@
+---
+title: AI 工具
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js 为 AI Agent 提供了一套工具套件，帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
+
+## llms.txt
+
+Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/)，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索：
+
+- 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- 全文：`https://modernjs.dev/llms-full.txt`（体积较大，按需取片段）
+
+大部分「这个 API / 配置是什么」类问题，靠 llms.txt 即可解决。让你的 Agent 按需检索它即可，不必把文档复制进项目。
+
+## Skills
+
+Skills 是按需触发的 AI 辅助能力，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。用户向 Skills：
+
+| Skill | 标识 | 说明 |
+|---|---|---|
+| 升级到 v3 | `modernjs-migrate-to-v3` | v2 应用迁移到 v3：安全改写 + 复杂项人工清单 + 迁移报告 |
+| 启用特性 | `modernjs-feature-enable` | 为 v3 应用启用 BFF / SSG / styled-components，并脚手架化 Tailwind CSS / 自定义 Web Server |
+
+> Skills 默认不强装、不隐式安装，由你显式安装。RSC、微前端等属于配置或架构决策，不是 `modernjs-feature-enable` 的一键启用项。
+
+## 安装 Skills
+
+Modern.js 的用户向 Skill 就放在仓库根 `skills/` 目录，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。推荐用标准的 `skills` CLI 直接从 GitHub 安装：
+
+```bash
+# 列出可安装的 Skills
+npx skills add web-infra-dev/modern.js --list
+
+# 安装单个 Skill 到你的 Agent 目录（--agent 可选 claude-code / codex / cursor 等）
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+
+它会把整个 Skill 目录（`SKILL.md` + `scripts/` + `references/`）安装到对应 Agent 目录，随后即可在该 Agent 里触发。
+
+> 需锁定到某个版本时，在仓库后加 `#<ref>`（ref 可为 tag / 分支 / commit），即安装该版本上的 Skill（把 `<tag>` 换成含本 Skill 的发布 tag）：
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```

package/docs/zh/guides/get-started/ultramodern.mdx

@@ -7,14 +7,14 @@ sidebar_position: 2
 
 本文对比 **UltraModern.js 3.0** 与本 fork 持续跟进的 Modern.js 3.x 版本线。这里的基线应理解为当前已合并的 Modern.js `release-v3.x` 基线，而不是固定的补丁版本快照。
 
-UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它保留有利于接入的 Modern.js 插件/运行时心智模型，但产品定位是独立框架：面向 Effect-first BFF、TanStack Router、SSR、Module Federation 与可独立部署的 Micro Verticals。
+UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它保留有利于接入的 Modern.js 插件/运行时心智模型，但产品定位是独立框架：面向 Effect HttpApi-first HTTP API、TanStack Router、SSR、Module Federation 与可独立部署的 Micro Verticals。
 
 ## 设计原则
 
 - 差异要明确、可审计。
-- 保留有价值的 Modern.js 兼容概念，但不再把 UltraModern.js 表达成“只是一个预设”。
+- 明确维护与上游 Modern.js 的合并兼容性：通用 Modern.js 运行时代码保留在其应在的位置，UltraModern 生成 surface 保持严格。
 - 仅在跨团队稳定性场景增加平台契约。
-- 保留按应用关闭和显式兼容分支的能力。
+- 保留显式 escape hatch，但它们必须位于生成 HTTP API 模块之外。
 
 ## 兼容性承诺
 
@@ -24,7 +24,7 @@ UltraModern.js 3.0 保持以下不变：
 - 既有项目结构与命令使用方式。
 - 渐进式接入路径（应用无需大规模重构）。
 
-UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支仍然存在，用于降低迁移风险，但框架方向是 Effect + TanStack + SSR + Micro Verticals。
+UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向是 Effect + TanStack + SSR + Micro Verticals，生成的 HTTP API 只走严格 Effect HttpApi surface。既有 Modern.js 应用可以渐进迁移；一旦某个 API surface 被生成为或迁移为 UltraModern HTTP API，就必须使用严格 Effect HttpApi 路径。
 
 ## 有意引入的差异（3.0 线）
 
@@ -33,7 +33,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 | 构建诊断能力 | RsDoctor 多为显式开启 | 新增一等的 `performance.rsdoctor` 配置项（按需开启；早期的默认开启行为与诊断契约产物已回退） |
 | 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`，并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
 | BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
-| BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
+| BFF 运行时选型 | 标准 request-handler BFF 路径 | 生成的 HTTP API 只走 Effect `HttpApi`，入口固定为 `api/index.ts`，共享契约固定为 `shared/api.ts`，并通过 `strictEffectApproach`、Oxlint 与生成检查拒绝原始 request handler、手写解析、手写 `Response` 和 Hono server import |
 | Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线，内置 OTLP/VictoriaMetrics，支持脱敏、批处理与背压 |
 | 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手，并补齐集成级回归保障 |
 | MF vertical 加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
@@ -46,16 +46,17 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 
 - 不再把这个 fork 隐藏在旧 Modern.js 品牌后面。
 - 当通用 Modern.js 默认值与 SuperApp 可靠性冲突时，不优先优化通用默认值。
-- 运行时保持 `effect` 与 `hono` 双模式并存，但不提供隐式回退。
+- 不为了执行 UltraModern 策略而删除通用 Modern.js 的 Hono/file-convention 运行时支持；约束应落在 UltraModern 生成器、配置、检查和生成 workspace 中。
+- 生成的 UltraModern HTTP API 只走严格 Effect HttpApi surface；原始 request handler 和 Hono/file-function API 不属于生成架构。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
 ## 迁移指南
 
-对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是“兼容感知”：保留能降低风险的部分，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，并把 UltraModern.js 3.0 作为独立框架采用。
+对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是把 API 工作迁到严格 Effect HttpApi surface，而不是保留旧的原始 handler 布局。
 
-1. 既有 React Router 应用可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，但 React Router 兼容分支仍然保留，团队可以按自己的节奏迁移。
-2. 新建或迁移中的 BFF 能力优先使用 `bff.runtimeFramework: 'effect'`，并将入口实现放在 `api/effect/index.ts`。如果当前应用已经在 `api/lambda/**` 下使用 Hono 处理函数，就继续显式使用 `bff.runtimeFramework: 'hono'`，等准备好再迁移；Hono 仍是受支持的兼容分支。
-3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
+1. 既有 Modern.js 应用在尚未进入生成 UltraModern surface 前可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，团队可以按自己的节奏迁移路由层。
+2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
+3. 在生成或已迁移的 UltraModern workspace 中，把 raw handler、`api/lambda/**`、手写 `Response` 和手写 request parsing 视为迁移缺陷。
 4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
 
 旧版生成 workspace 迁移时，以已发布的包 cohort 作为事实来源：
@@ -70,9 +71,48 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+严格生成 API 迁移要求 `3.5.0-ultramodern.0` 或更新版本。
+`3.4.0-ultramodern.20` 及更早 cohort 还没有这套完整的直接
+`api/index.ts` 生成器、生成的 `.mts` 检查和严格 Oxlint 边界规则。还不能安装该
+BleedingDev cohort 的 agent 应使用本地 Modern.js workspace 做迁移校验；否则用
+`--ultramodern-package-version` 固定 `3.5.0-ultramodern.0` 或更新版本。
+
+渐进迁移意味着尚未迁移的旧 Modern.js app 可以保留现有 runtime，直到被转换为
+UltraModern。一个 surface 一旦生成为或迁移为 UltraModern HTTP API，就只能使用
+Effect HttpApi；不要在该 UltraModern API surface 中保留 Hono、lambda handler 或原始
+request handler。
+
+迁移已经带有 Effect API 文件的生成 workspace 时，明确移动文件，不保留兼容别名：
+
+1. 将每个 vertical 服务端入口从 `verticals/<id>/api/effect/index.ts` 移到
+   `verticals/<id>/api/index.ts`。
+2. 将每个共享 API 契约从 `verticals/<id>/shared/effect/api.ts` 移到
+   `verticals/<id>/shared/api.ts`。
+3. 将生成客户端从 `verticals/<id>/src/effect/*-client.ts` 移到
+   `verticals/<id>/src/api/*-client.ts`。
+4. 将 shell API 聚合从 `apps/shell-super-app/src/effect/*` 移到
+   `apps/shell-super-app/src/api/*`。
+5. 更新 imports 和 package exports，使用 `./api`、`./api/client` 与
+   `@<workspace>/<vertical>/api/client`；删除 `./effect/client`、
+   `./shared/effect/api` 和 shared Effect API 包。
+6. 更新每个 vertical 的 `modern.config.ts`，设置
+   `bff.effect.entry: './api/index'` 和
+   `bff.effect.strictEffectApproach: true`。
+7. 更新 topology，让 API metadata 直接位于 `api` 下，并设置
+   `api.bff.strictEffectApproach: true`；不要保留 `api.effect`。
+8. 运行 `pnpm api:check`、`scripts/validate-ultramodern-workspace.mts`、
+   `pnpm check` 和 `pnpm build`。
+
+如果迁移失败，应修复归属的生成契约、topology、package exports 或 API 模块。
+不要添加 app 级 alias、原始 request handler、手写 `Response`、本地类型断言或包
+shim 来让旧布局通过。
+
+Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transport surface 增加。
+它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
+
 每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
 `--ultramodern-package-source=install`，并把精确 cohort 记录到
-`.modernjs/ultramodern-package-source.json`。`--workspace` 只用于本地 monorepo
+`.modernjs/ultramodern.json`。`--workspace` 只用于本地 monorepo
 联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本，应使用
 `--ultramodern-package-version` 固定精确 cohort。
 
@@ -82,8 +122,8 @@ Federation shim 或自定义 server wrapper。框架 BFF compiler 会把服务
 CommonJS，同时生成的 app package 继续为 Module Federation DTS 保留稳定的
 `typescript`，并使用固定的 `@typescript/native-preview` 工具链执行 TS-Go 检查。
 
-安装新 cohort 后，先运行生成的
-`scripts/validate-ultramodern-workspace.mjs` 契约校验，再接受人工改动。topology、
+安装新 cohort 后，先运行生成的 `pnpm api:check` 与
+`scripts/validate-ultramodern-workspace.mts` 契约校验，再接受人工改动。topology、
 ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
 Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆盖生成结果。
 
@@ -91,7 +131,7 @@ Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆
 
 公开的 BleedingDev create 包只有一个受支持的生成产品。默认命令会创建一个
 可上线的 UltraModern SuperApp workspace，包含 `presetUltramodern(...)`、
-SSR、TanStack Router、Tailwind CSS v4、i18n、Effect BFF、Module Federation
+SSR、TanStack Router、Tailwind CSS v4、i18n、Effect HttpApi BFF、Module Federation
 topology、生成质量 gate，以及 Cloudflare 部署基础：
 
 ```bash
@@ -115,7 +155,7 @@ mise exec -- pnpm check
 
 `--vertical` 会修改当前 workspace：创建 vertical 包，并更新 topology 元数据、
 ownership 记录、shell Module Federation、开发 overlays、包依赖、生成契约、
-端口、路由归属 i18n、CSS 隔离，以及 vertical 自己拥有的 Effect BFF/client surface。
+端口、路由归属 i18n、CSS 隔离，以及 vertical 自己拥有的 Effect HttpApi/client surface。
 
 ### 生成器自动化
 
@@ -166,9 +206,9 @@ addUltramodernVertical({
 ```
 
 公开结果包含 workspace root、包源、创建的 apps、创建路径、重写路径、分配端口、
-Module Federation 名称、Effect API 前缀、生成契约路径与 warnings。
+Module Federation 名称、API 前缀、生成契约路径与 warnings。
 MicroVertical dry-run 返回相同结构，并额外包含 `dryRun`、`selectedPort`、
-`moduleFederationRemote`、`effectApiPrefix`、`jsonMutations`、
+`moduleFederationRemote`、`apiPrefix`、`jsonMutations`、
 `shellDependencyChanges` 与 `generatedContractChanges`；CLI 会输出 JSON，且不写文件。
 
 CodeSmith 消费方可以使用 adapter subpath：
@@ -215,7 +255,7 @@ JSON-LD 是可选的路由 metadata，不会自动推断。私有路由和不可
 JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`，并使用生成的
 `src/routes/ultramodern-jsonld.ts` helper 编写常见 schema.org 结构。
 
-生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
+生成契约会在 `.modernjs/ultramodern.json` 中写入
 `cssFederation`：
 
 - `packages/shared-design-tokens` 拥有共享 token layer，并导出 `./tokens.css`。
@@ -224,7 +264,7 @@ JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`，
 - Tailwind CSS v4 通过 `@tailwindcss/postcss` 保持在每个生成应用内部；共享 base style 不应由 vertical 重复定义。
 - SSR 首屏依赖 Modern/Rspack 产出共享 token CSS 和应用自己的 CSS。Vertical CSS 通过 manifest 归属加载，不复制到 shell 源码中。
 
-版本切换必须从同一个 vertical build marker 选择 UI、Effect API、CSS、i18n JSON 与 MF manifest 证据。只切换 shell 渲染里的 UI marker 不足以证明完整版本切换。
+版本切换必须从同一个 vertical build marker 选择 UI、API、CSS、i18n JSON 与 MF manifest 证据。只切换 shell 渲染里的 UI marker 不足以证明完整版本切换。
 
 ### 校验与部署
 

package/docs/zh/guides/upgrade/config.mdx

@@ -314,7 +314,7 @@ export default {
 
 ### tools.pug
 
-**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/rspack-contrib/rsbuild-plugin-pug) 来启用支持。
+**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/rstackjs/rsbuild-plugin-pug) 来启用支持。
 
 **迁移示例**：
 

package/docs/zh/plugin/introduction.mdx

@@ -131,21 +131,21 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
 | [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react)                        | 提供对 React 的支持                                                                    | -                                                                                                                                     |
 | [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr)                          | 支持将 SVG 图片转换为一个 React 组件                                                   | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
 | [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | 用于在静态资源加载失败时自动发起重试请求                                               | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
-| [Type Check 插件](https://github.com/rspack-contrib/rsbuild-plugin-type-check)       | 用于在单独的进程中运行 TypeScript 类型检查                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
-| [Source Build 插件](https://github.com/rspack-contrib/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                     | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
-| [Check Syntax 插件](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)   | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                         | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
-| [CSS Minimizer 插件](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
-| [Rem 插件](https://github.com/rspack-contrib/rsbuild-plugin-rem)                     | 用于实现移动端页面的 rem 自适应布局                                                    | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
+| [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check)             | 用于在单独的进程中运行 TypeScript 类型检查                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
+| [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                     | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
+| [Check Syntax 插件](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                         | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
+| [CSS Minimizer 插件](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
+| [Rem 插件](https://github.com/rstackjs/rsbuild-plugin-rem)                     | 用于实现移动端页面的 rem 自适应布局                                                    | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
 
 #### 未内置的插件
 
 以下是未在 Modern.js 中内置的 Rsbuild 官方插件：
 
-- [Image Compress 插件](https://github.com/rspack-contrib/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
+- [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
 - [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
-- [UMD 插件](https://github.com/rspack-contrib/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
-- [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
-- [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。
+- [UMD 插件](https://github.com/rstackjs/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
+- [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
+- [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。
 
 import OtherPlugins from '@site-docs/components/other-plugins.mdx';
 

package/package.json

@@ -19,14 +19,14 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.4.0-ultramodern.9",
+  "version": "3.5.0-ultramodern.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.9"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.0"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.0",