# 门户如何构建

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

<span id="estructura-del-proyecto"></span>

<span class="section-anchor" id="section-1"></span>

## 项目结构

```text
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，而不把文档内容隐藏在客户端应用中。

<span id="desarrollo"></span>

<span class="section-anchor" id="section-2"></span>

## 开发

```sh
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` 并刷新实验室。

<span id="build-reproducible"></span>

<span class="section-anchor" id="section-3"></span>

## 可复现构建

```sh
npm run build
npm run preview
```

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

npm 脚本构建的是本文档仓库。WU CLI 创建的 workspace 应遵循 [wu build](/zh-cn/docs/cli/build/) 的约定与配置。

<span id="añadir-un-capítulo"></span>

<span class="section-anchor" id="section-4"></span>

## 添加章节

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

```yaml
---
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` 后在本地搜索。

<span id="rutas-de-los-ejemplos"></span>

<span class="section-anchor" id="section-5"></span>

## 示例路由

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

[如何运行示例](/zh-cn/docs/guides/running-examples/)提供阅读与实践流程。`/api/` 浏览器是签名和契约参考，各示例链接相关章节。

<span id="composición-y-lifecycle-reales"></span>

<span class="section-anchor" id="section-6"></span>

## 真实组合与生命周期

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

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

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

[服务与 RPC](/zh-cn/labs/backend/)挂载 grants 不同的两个应用。客户端消费版本化契约并向提供方请求响应。[服务指南](/zh-cn/docs/guides/browser-backend/)解释身份、版本、取消、响应和提供方移除。

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

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

<span id="lectura-y-accesibilidad"></span>

<span class="section-anchor" id="section-7"></span>

## 阅读与无障碍

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

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

<span id="política-editorial"></span>

<span class="section-anchor" id="section-8"></span>

## 编辑原则

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

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

<span id="documentación-en-cuatro-idiomas"></span>

<span class="section-anchor" id="section-9"></span>

## 四种语言的文档

门户的主要语言是英语。切换到简体中文、葡萄牙语或西班牙语时，语言选择器保留当前章节、筛选和页面位置。语言链接无需 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` 检查路由和交互流程。缺少必需翻译会使生产构建失败。