Tutorial Writer Web

🌐 Tutorial Writer Web — Web 应用配置指南 v1.0

父技能: tutorial-writer 独立可用: ✅ 可通过 /web 或 /tutorial-writer/web 直接触发（L1 直达） 架构: L1 独立子技能 — 标准 Turbo 结构 (apps/web) 基于版本: Astro 6.3（2026年5月最新版）+ Starlight 最新版 使用频率: 🔴 高频 — 开发过程中反复迭代调用 前置依赖: 需要先使用官方工具完成项目初始化（见根路由器"🚀 项目初始化"章节 Step 1-3）

前置条件

• Monorepo 项目已初始化（含 turbo.json, pnpm-workspace.yaml） 详见根路由器 SKILL.md Step 1
• apps/web/ 已通过 Starlight 模板创建
  • 推荐命令: 在项目根目录运行 bun create astro apps/web --template starlight --install --yes
  • 该命令会自动创建 apps/web/ 目录并安装依赖
  • 详见根路由器 SKILL.md Step 3
• @repo/content 包存在且已在 package.json 中声明依赖

  { "dependencies": { "@repo/content": "workspace:*" } }
  

注意: 本子技能专注于 Astro + Starlight 配置和组件开发， 不包含项目创建逻辑。

项目初始化请参考根路由器的 "🚀 项目初始化" 章节。

Monorepo 目录结构概览

tutorial-project/
├── apps/                            ← 应用层
│   └── web/                    ← 🌐 教程网站（本技能聚焦）
│       ├── src/
│       │   ├── components/
│       │   ├── layouts/
│       │   ├── styles/
│       ├── astro.config.mjs
│       └── package.json
├── packages/                        ← 库层
│   ├── content/                     ← 📝 内容包（由 content 子技能管理）
│   │   ├── chapters/
│   │   ├── config.ts
│   │   └── package.json
│   └── book/                        ← 📖 电子书（由 book 子技能管理）
├── pnpm-workspace.yaml
└── package.json

与 Content 包的集成

// apps/web/astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  // 引用 content 包的内容目录
  contentDir: '../../packages/content',
  
  integrations: [
    starlight({
      sidebar: [
        { label: '首页', slug: 'index' },
        {
          label: '章节',
          autogenerate: { directory: 'chapters' },
        },
      ],
    }),
  ],
});

关键集成点：

🎯 职责范围

设计理念: 本技能是 Tutorial Writer 流程中调用频率最高的子技能之一，专注于 Web 包的技术实现细节。

🔧 核心配置：Astro + Starlight（Monorepo 版）

astro.config.mjs 完整示例

// apps/web/astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name/',
  trailingSlash: 'always',

  // 指向 Monorepo 中的 content 包
  contentDir: '../../packages/content',

  integrations: [
    starlight({
      title: '教程标题',
      description: '教程描述',

      social: {
        github: 'https://github.com/username/repo',
      },

      sidebar: [
        { label: '首页', slug: 'index' },
        {
          label: '章节',
          autogenerate: { directory: 'chapters' },
        },
      ],

      editLink: {
        baseUrl: 'https://github.com/username/repo/edit/main/',
      },
      lastUpdated: true,
      pagination: true,
      search: { mode: 'auto' },
    }),
  ],
});

Monorepo 特有配置项：

package.json（Workspace 依赖）

{
  "name": "@repo/web",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "enhance": "mmd2svg -i ../../packages/content/chapters -o .enhanced"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.30.0",
    "astro": "^6.3.0",
    "@repo/content": "workspace:*"
  }
}

🎨 组件开发：按功能分组

推荐的组件目录结构

apps/web/src/components/
├── interactive/              ← 🎮 3D、可视化、交互式组件
│   ├── Architecture3D.tsx    # 3D 架构展示
│   ├── DataPipeline3D.tsx    # 数据流 3D 动画
│   ├── ChunkComparison3D.tsx # 分块策略对比 3D
│   └── KnowledgeGraph3D.tsx  # 知识图谱 3D
│
├── charts/                   ← 📊 图表、仪表盘、指标
│   ├── PerformanceDashboard.tsx
│   ├── MetricGauge.tsx
│   └── ComparisonChart.tsx
│
├── code/                     ← 💻 代码相关组件
│   ├── InteractiveCodeDemo.tsx  # 运行时代码沙盒
│   ├── CodeComparison.tsx      # 代码对比展示
│   └── TerminalEmulator.tsx     # 终端模拟器
│
└── ui/                        ← 🎨 通用 UI 组件
    ├── FeatureGrid.astro
    ├── DifficultyBadge.astro
    └── ReadingTime.astro

分组原则：

⚡ Islands Architecture 最佳实践

核心原则

┌─────────────────────────────────────────┐
│           HTML/CSS（零 JavaScript）        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │ Static  │  │ Static  │  │ Static  │   │
│  │ Component│  │ Component│  │ Component│   │
│  └─────────┘  └─────────┘  └─────────┘   │
│                                           │
│  ┌─────────────┐  ┌─────────────┐         │
│  │   Island    │  │   Island    │         │
│  │ ( hydrated) │  │ ( hydrated) │         │
│  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────┘

使用指南

✅ 应该使用 Islands 的场景：

• 3D 可视化（Three.js、React Three Fiber）
• 交互式图表（Chart.js、D3.js）
• 代码沙盒（CodeMirror、Monaco Editor）
• 复杂表单验证
• 实时数据更新

❌ 不应该使用 Islands 的场景：

• 纯展示性 UI（卡片、徽章）
• 导航栏、侧边栏
• 页脚、版权信息
• 静态文本内容

示例：Island vs Static 对比

---
// ✅ 正确：静态组件使用 .astro 扩展名
import FeatureGrid from '../components/ui/FeatureGrid.astro';
import DifficultyBadge from '../components/ui/DifficultyBadge.astro';

// ✅ 正确：交互组件使用 .tsx 并添加 client:* 指令
import InteractiveDemo from '../components/code/InteractiveCodeDemo.tsx';
---

<article>
  <!-- 静态渲染，零 JavaScript -->
  <FeatureGrid features={features} />
  <DifficultyBadge difficulty="intermediate" />

  <!-- 仅此部分 hydrate 为 React -->
  <InteractiveDemo client:load />
</article>

Hydration 指令选择：

🎨 样式系统

全局样式结构

apps/web/src/styles/
├── global.css              ← 全局重置和基础样式
├── variables.css            ← CSS 自定义属性（主题变量）
├── typography.css           ← 排版系统
└── responsive.css           ← 响应式断点工具类

主题变量（CSS Custom Properties）

/* variables.css */
:root {
  /* 颜色系统 */
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-accent: #06b6d4;
  --color-background: #ffffff;
  --color-text: #1e293b;

  /* 排版 */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  --font-size-base: 16px;
  --line-height: 1.6;

  /* 间距 */
  --spacing-unit: 0.25rem;
  --container-max: 1200px;

  /* 圆角 */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

/* Dark mode */
[data-theme='dark'] {
  --color-background: #0f172a;
  --color-text: #e2e8f0;
}

响应式断点

/* responsive.css */

/* Mobile first approach */
.container {
  width: 100%;
  padding: 0 var(--spacing-4);
  margin: 0 auto;
}

/* Tablet */
@media (min-width: 768px) {
  .container {
    max-width: 720px;
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .container {
    max-width: var(--container-max);
  }
}

/* Large desktop */
@media (min-width: 1280px) {
  .grid-cols-4 {
    grid-template-columns: repeat(4, 1fr);
  }
}

断点速查表：

⚡ 内容增强管道（Build-time Enhancement）

什么是增强管道？

在构建时自动处理 Markdown 内容，注入交互组件、预渲染图表等。

核心功能 1：插槽标记系统

在 Markdown 中使用标记：

<!-- packages/content/chapters/06-retrieval-optimization.md -->

# 第六章：检索质量优化

## 分块策略对比

| 策略 | Token 数 | 召回率 |
|-------|---------|--------|
| 固定 512 | 512 | **78%** |
| 语义分块 | ~43 | **70%** |

<!-- @interactive: ChunkComparison3D -->
<!-- 同步后此处自动插入 3D 对比可视化组件 -->

## RRF 公式

$$ \text{RRF}(d) = \sum_{i=1}^{k} \frac{1}{k + r_i(d)} $$

<!-- @mermaid -->
```mermaid
flowchart LR
  A[查询] --> B[关键词检索]
  A --> C[向量检索]
  B --> D[RRF 融合]
  C --> D

**构建时处理** (`apps/web/src/scripts/enhance-content.mts`)：

```typescript
// apps/web/src/scripts/enhance-content.mts
import type { AstroConfig } from 'astro/config';

export default function enhanceContent(astroConfig: AstroConfig) {
  return {
    name: 'content-enhancer',
    hooks: {
      'astro:build:start': () => {
        console.log('🔄 开始内容增强...');
      },
      'astro:build:done': ({ dir }) => {
        console.log('✅ 内容增强完成:', dir);
      },
    },
  };
}

核心功能 2：Mermaid 预渲染

为什么需要预渲染？

• ❌ 浏览器端渲染 mermaid.js 会增加加载时间
• ✅ 构建时预渲染为 SVG，零运行时开销

实现方式：

# 安装 mermaid CLI
cd apps/web && bun add -D @mermaid-js/mermaid-cli

# 在 apps/web/package.json 中添加脚本
{
  "scripts": {
    "enhance": "mmd2svg -i ../../packages/content/chapters -o .enhanced",
    "prebuild": "bun run enhance && astro build"
  }
}

核心功能 3：组件自动注入

布局级别处理 (apps/web/src/layouts/BaseLayout.astro)：

---
// 自动检测并替换插槽标记
import ChunkComparison3D from '../components/interactive/ChunkComparison3D.tsx';
---

<!doctype html>
<html>
  <head><title>{title}</title></head>
  <body>
    <!-- 使用 slot 渲染原始内容 -->
    <slot />

    <!-- 后处理：查找并替换插槽标记为实际组件 -->
    <script define:vars={{}} is:inline>
      document.querySelectorAll('[data-enhance-slot]').forEach(el => {
        const componentName = el.dataset.enhanceSlot;
        // 动态导入并渲染对应组件
      });
    </script>
  </body>
</html>

📖 Content Collections 查询（Monorepo 版）

查询内容

---
import { getCollection } from 'astro:content';

// 获取所有章节（从 content 包）
const allChapters = await getCollection('chapters');

// 过滤：排除草稿
const publishedChapters = allChapters.filter(ch => !ch.data.draft);

// 排序：按文件名数字前缀
const sortedChapters = publishedChapters.sort((a, b) => {
  const numA = parseInt(a.slug.split('-')[0]) || 999;
  const numB = parseInt(b.slug.split('-')[0]) || 999;
  return numA - numB;
});
---

<h2>所有章节 ({sortedChapters.length})</h2>
{sortedChapters.map(chapter => (
  <article>
    <h3><a href={chapter.slug}>{chapter.data.title}</a></h3>
    <p>{chapter.data.description}</p>
    {chapter.data.difficulty && (
      <span class={`badge badge--${chapter.data.difficulty}`}>
        {chapter.data.difficulty}
      </span>
    )}
  </article>
))}

注意: Schema 定义由 packages/content/config.ts 管理，Web 包无需重复定义。

🌐 i18n 多语言配置（可选）

如果需要多语言支持：

packages/content/
├── chapters/                     ← 默认语言（如中文）
│   ├── 01-overview.md
│   └── ...
└── en/                          ← 英文版本
    ├── chapters/
    │   ├── 01-overview.md
    │   └── ...
    └── index.mdx

apps/web/astro.config.mjs：

starlight({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN',
    },
    en: {
      label: 'English',
      lang: 'en',
    },
  },
  defaultLocale: 'root',
}),

🛠️ 本地开发和调试

开发服务器启动

# 在项目根目录
bun run --filter @repo/web dev

# 或进入 web 应用目录
cd apps/web
bun run dev

访问地址: http://localhost:4321

HMR（热模块替换）

Astro 内置 HMR 支持：

• ✅ CSS 修改即时生效（无需刷新）
• ✅ Astro 组件修改即时更新
• ✅ Islands 组件状态保持（尽可能保留）
• ⚠️ astro.config.mjs 修改需重启 dev server

DevTools 调试技巧

1. Vue/React DevTools

对于 Islands 组件（React/Vue/Svelte）：

# 安装浏览器扩展
# React Developer Tools
# Vue.js devtools
# Svelte DevTools

2. Astro Dev Toolbar

Astro 6.x 内置开发工具栏：

• 显示组件边界（Component boundaries）
• 性能指标（Performance metrics）
• 可访问性检查（A11y audit）

启用方法：

// astro.config.mjs
export default defineConfig({
  devToolbar: {
    enabled: true,
  },
});

3. 构建产物分析

# 安装分析工具
cd apps/web && bun add -D rollup-plugin-visualizer

// astro.config.mjs
vite: {
  plugins: [visualizer({ open: true, gzipSize: true })],
},

运行构建后自动打开可视化报告。

🚀 构建优化

性能调优策略

1. 图片优化

---
import { Image } from 'astro:assets';
---

<!-- 自动优化：WebP/AVIF 格式转换、响应式尺寸、懒加载 -->
<Image
  src={coverImage}
  alt={title}
  widths={[400, 800, 1200]}
  loading="lazy"
/>

配置项：

2. 代码分割

// astro.config.mjs
build: {
  inlineStylesheets: 'auto',  // 小于 4KB 的 CSS 内联
},
vite: {
  build: {
    cssCodeSplit: true,       // CSS 按路由分割
    rollupOptions: {
      output: {
        manualChunks: {
          // 将第三方库分离到独立 chunk
          vendor: ['react', 'react-dom'],
          charts: ['chart.js'],
        },
      },
    },
  },
},

3. 字体优化（Astro 6.0+ Fonts API）

// astro.config.mjs
import { fontProviders } from 'astro/config';

export default defineConfig({
  fonts: [
    {
      name: 'Inter',
      cssVariable: '--font-inter',
      provider: fontProviders.fontsource(),  // 自托管（推荐）
    },
  ],
});

优势：

• ✅ 自动优化字体加载
• ✅ 支持自托管（隐私友好）
• ✅ 生成 <link rel="preload">
• ✅ 设置 1 年 HTTP 缓存

4. Lighthouse 优化目标

运行 Lighthouse：

# 方式 1：Chrome DevTools（推荐）
# 打开 DevTools → Lighthouse 标签页 → Generate report

# 方式 2：CLI
npx lighthouse http://localhost:4321 --output html --output-path ./lighthouse-report.html

📂 Monorepo 工作流示例

日常开发流程

# 1. 启动开发服务器（监听 content 和 web 的变化）
bun run --filter @repo/web dev

# 2. 编辑内容（在 packages/content/ 中）
# vim packages/content/chapters/01-overview.md

# 3. 编辑组件（在 apps/web/src/components/ 中）
# vim apps/web/src/components/ui/FeatureGrid.astro

# 4. HMR 自动刷新，无需重启

# 5. 构建验证
bun run --filter @repo/web build

# 6. 预览构建结果
bun run --filter @repo/web preview

从根目录运行命令

// package.json（根目录）
{
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "preview": "turbo run preview",
    "build:all": "turbo run build"
  }
}

常用命令速查：

🔗 与发布阶段的衔接

构建完成后，进入 发布阶段 → 调用 /github-pages

构建阶段交付物：

触发发布的条件：

# 本地验证通过后
bun run --filter @repo/web build     # ✅ 成功
bun run --filter @repo/web preview   # ✅ 预览正常

# 准备就绪，调用发布技能
→ /github-pages               # 进入 GitHub Pages 部署流程

📂 本子技能结构

skills/tutorial-writer-web/
├── SKILL.md                              ← 本文件（~700行）
└── references/
    └── astro-development.md              ← Astro 6.x 深度开发指南

📚 参考文档索引

🔗 相关资源

版本历史