实用指南6 分钟阅读 · MARKDOWN ↗

门户如何构建

浏览 Astro shell、WU API 示例、React/Vue 组合，以及包含契约与 RPC 的服务示例。

项目结构

wu-docs/
├── shell/astro.config.mjs       # Astro: configuración del host
├── src/content/docs/           # Manuales del framework y CLI
│   ├── guides/
│   ├── framework/
│   └── cli/
├── src/layouts/                # Composición del documento
├── src/components/             # Controles Lit del portal
├── src/pages/                  # Rutas y generación estática
├── apps/command-lab/           # Microfrontend React
├── apps/runtime-lab/           # Microfrontend Vue
├── apps/systems-lab/           # Ejecutor e infraestructura del servicio
├── apps/api-lab/               # WU recipes with owned instances in the host document
├── apps/backend-lab/           # Implementación del proveedor RPC
├── examples/                   # SSR, IA local y relay MCP
├── packages/lab-ui/            # Controles Lit de los laboratorios
├── scripts/build-apps.mjs      # Empaquetado de los módulos ESM
├── public/microfrontends/      # Salida generada de las apps
├── packages/backend-ui/        # Cliente e interfaz de Servicios y RPC
└── dist/                       # Sitio estático compilado

Astro srcDir 从 shell/ 指向 ../src，保留明确的 shell，而不把文档内容隐藏在客户端应用中。

开发

npm ci
npm run dev

锁文件为 wu-framework 和别名 wu-framework-release 固定 npm 已发布的 WU Framework 4.0.0。首页、实验室和下载示例均使用此版本。组合及服务/RPC 保留精确 CDN URL 和相同版本的备用包。

npm run dev 编译实验室并启动 Astro。Markdown、宿主组件和样式变更经开发服务器处理。修改应用或共享 UI 后，运行 npm run build:apps 并刷新实验室。

可复现构建

npm run build
npm run preview

第一步打包应用、runners 及其 Lit 组件，再由 Astro 生成文档、搜索、API 浏览器和示例页。服务包含运行产物，普通构建不需要 Zig。提供门户所需全部内容位于 dist/。

npm 脚本构建的是本文档仓库。WU CLI 创建的 workspace 应遵循 wu build 的约定与配置。

添加章节

在 src/content/docs/ 下创建包含有效 frontmatter 的 Markdown：

---
title: Título del capítulo
description: Qué aprenderá el lector en esta página.
section: Framework
order: 20
---

使用 ## 定义可导航章节，### 定义子节。Astro 从集合生成侧栏及上一篇/下一篇链接。路由源自文件名，例如 framework/ejemplo.md 生成 /docs/framework/ejemplo/。

搜索索引包含标题、描述和全文，不需要搜索服务，也不向第三方发送查询。界面加载 /search.json 后在本地搜索。

示例路由

路由	用途
`/labs/`	八个 WU API 示例，提供可观察检查和清理
`/labs/api/`	同一示例实验室的兼容入口
`/labs/composition/`	两个 WU 宿主：React 生成器与 Vue 检查器
`/labs/backend/`	服务与 RPC：客户端、契约和提供方

如何运行示例提供阅读与实践流程。/api/ 浏览器是签名和契约参考，各示例链接相关章节。

真实组合与生命周期

shell 在客户端导入 runtime。各模块暴露 register(wu) 并定义生命周期。宿主通过 manifest 和 grants 初始化配置，再挂载到专用容器。

组合中的挂载/卸载控件调用真实 WU 生命周期。React 生成器和 Vue 检查器在同次访问中共享 docs.lab.counter、docs.lab.lastCommand 和 docs:lab:* 事件。各应用收到 scoped facade，卸载时释放监听器和框架 root。切换文档重置上下文，示例不提供远程持久化。

API 实验室在当前文档中为每个示例运行独立的 WU 实例。测试应用直接挂载到 Shadow DOM，结束后释放资源。组合示例的注册保持独立。执行回执区分断言、已确认的清理和仍待释放的资源。这里只执行文档中固定的代码。

服务与 RPC挂载 grants 不同的两个应用。客户端消费版本化契约并向提供方请求响应。服务指南解释身份、版本、取消、响应和提供方移除。

apps/systems-lab/ 保留 Worker 执行器、已编译客户程序和测试 fixtures。服务复用这些 WASM/WASI 基础设施在浏览器处理数据，公开 UI 不挂载第三个 Systems Lab 应用。这个实现选择不改变客户端消费的 WU 契约。

SSR、AI 和 MCP 示例位于 examples/。构建在 /examples/wu-server-recipes.zip 生成可移植 ZIP，包含 npm 清单和测试。静态门户不会自动启动 MCP relay。

阅读与无障碍

手册以静态 HTML 提供，导航和正文无需 JavaScript。搜索、复制按钮和实验室需要 JavaScript。

提供跳过内容链接、landmarks、当前页面状态、可见焦点和减少动画支持。窄屏中章节索引变为可滚动区域，也可通过搜索直接到达章节。

编辑原则

各章解释用途、签名、配置、示例和边界。类型中存在但公开 export 缺少的能力会明确指出。片段必须使用真实 API 并链接完整约定。

框架和 CLI 手册也与源码存放在一起。修改契约时，更新参考、示例和测试并重新生成门户。修改运行时版本前，请查阅版本与分发。

四种语言的文档

门户的主要语言是英语。切换到简体中文、葡萄牙语或西班牙语时，语言选择器保留当前章节、筛选和页面位置。语言链接无需 JavaScript 也可使用；搜索和实验室需要 JavaScript。

语言	路由前缀
英语	`/`
简体中文	`/zh-cn/`
葡萄牙语	`/pt/`
西班牙语	`/es/`

Astro 为四种语言分别生成各章节及 Markdown 下载。每页都有自己的 lang、规范 URL 和 hreflang 链接，sitemap 关联各语言版本。搜索索引包含当前语言的文本和链接。

手册与 API 条目翻译位于 src/i18n/。生成器将翻译与共用代码块组合，生成 src/content/localized/ 集合。src/views/ 的共享模板为控件和文本使用显式消息。shell 在加载 React、Vue 和 Lit 应用前设置语言，实验室 runner 也通过 URL 接收语言。

模块路径、资源和可下载 ZIP 在各语言间共享。命令、应用名称、通道、权限和示例代码的字面消息保持原值：翻译说明，但保留读者需要复制或核对的内容。因此四种语言的计数器指南下载相同可执行文件。

更新翻译时，运行 npm run i18n:extract，补全缺失键，再运行 npm run i18n:build。npm run check:i18n 检查覆盖率，并确认翻译保留代码、链接、表格和 placeholders。门户服务器运行时，npm run test:i18n 检查路由和交互流程。缺少必需翻译会使生产构建失败。