@ai-teacher/course

AITeacher 课程播放器组件库，提供完整的课程播放、交互式内容渲染和状态管理功能。

功能特性

• 🎯 基于 Reveal.js 的课程播放器
• 🧩 模块化的区块渲染系统
• 🎨 支持多种内容类型（文本、图片、视频、音频、交互式内容）
• 📦 完整的 TypeScript 类型支持
• 🔄 基于 XState 的状态管理
• 🎬 媒体时间轴事件支持

安装

npm install @ai-teacher/course
# 或
pnpm add @ai-teacher/course
# 或
yarn add @ai-teacher/course

使用

import { RevealCoursePlayer } from '@ai-teacher/course';

function App() {
  return (
    <RevealCoursePlayer
      course={courseData}
      onPageChange={(page) => console.log('Page changed:', page)}
    />
  );
}

版本管理

本项目遵循 语义化版本控制 (Semantic Versioning) 规范。

版本号格式

版本号格式为：主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)

• 主版本号 (MAJOR): 不兼容的 API 修改
• 次版本号 (MINOR): 向下兼容的功能性新增
• 修订号 (PATCH): 向下兼容的问题修正

版本发布流程

1. 开发阶段

在开发新功能或修复 bug 时，在对应的分支上进行开发：

# 创建功能分支
git checkout -b feat/your-feature
# 或修复分支
git checkout -b fix/your-bug

2. 构建和测试

在发布前，确保代码已构建且测试通过：

# 构建包
pnpm --filter @ai-teacher/course build

# 检查构建产物
ls -la packages/course/dist

3. 版本更新

使用 npm version 命令更新版本号：

# 进入 course 包目录
cd packages/course

# 更新修订号 (0.1.0 -> 0.1.1)
npm version patch

# 更新次版本号 (0.1.0 -> 0.2.0)
npm version minor

# 更新主版本号 (0.1.0 -> 1.0.0)
npm version major

# 预发布版本（可选）
npm version prerelease --preid=beta  # 0.1.0 -> 0.1.1-beta.0
npm version prerelease --preid=alpha # 0.1.0 -> 0.1.1-alpha.0

注意: npm version 命令会自动：

• 更新 package.json 中的版本号
• 创建一个 git commit
• 创建一个 git tag

4. 发布到 npm

4.1 检查发布配置

确保已登录 npm：

npm whoami

如果未登录，执行：

npm login

确保使用正确的 npm registry（如果是私有 registry）：

npm config get registry
# 如果需要切换
npm config set registry https://registry.npmjs.org/

4.2 发布前检查清单

• [ ] 代码已通过所有测试
• [ ] 构建成功且无错误
• [ ] 版本号已正确更新
• [ ] package.json 中的元数据完整（description, keywords, repository 等）
• [ ] dist 目录包含所有必要的构建产物
• [ ] 已更新 CHANGELOG.md（如果存在）

4.3 执行发布

# 方式一：使用 npm publish（推荐）
cd packages/course
npm publish

# 方式二：使用 pnpm publish
pnpm --filter @ai-teacher/course publish

# 发布预发布版本
npm publish --tag beta    # 发布 beta 版本
npm publish --tag alpha   # 发布 alpha 版本
npm publish --tag next    # 发布 next 版本

4.4 发布后操作

1. 推送代码和标签到远程仓库：

# 从项目根目录执行
git push origin main
git push --tags

2. 验证发布：

# 检查 npm 上的包信息
npm view @ai-teacher/course

# 检查最新版本
npm view @ai-teacher/course version

# 检查所有版本
npm view @ai-teacher/course versions

3. 创建 GitHub Release（可选）：

在 GitHub 上创建对应的 Release，包含：

• 版本号
• 变更日志
• 重要更新说明

发布脚本说明

在 package.json 中提供了以下脚本：

• build: 构建包
• clean: 清理构建产物
• version:patch: 更新修订版本并发布
• version:minor: 更新次版本并发布
• version:major: 更新主版本并发布
• prepublishOnly: 发布前自动执行的脚本（构建和检查）

包发布内容

根据 package.json 中的 files 字段，只有以下内容会被发布到 npm：

• dist/ - 构建产物目录
• package.json
• README.md
• CHANGELOG.md（如果存在）

其他文件（如源代码、测试文件、配置文件等）不会被发布。

常见问题

Q: 如何撤销已发布的版本？

A: 如果版本发布后发现问题，可以：

1. 发布补丁版本（推荐）：

   npm version patch
   npm publish

2. 撤销发布（仅在 72 小时内有效）：

   npm unpublish @ai-teacher/course@版本号

   注意：撤销发布需要谨慎，建议优先使用补丁版本修复。

Q: 如何发布预发布版本？

A: 使用预发布版本进行测试：

# 创建 beta 版本
npm version prerelease --preid=beta
npm publish --tag beta

# 安装测试
npm install @ai-teacher/course@beta

Q: 如何更新已发布的版本？

A: 已发布的版本无法修改，只能发布新版本。确保发布前充分测试。

Q: 发布时提示 "You cannot publish over the previously published versions"

A: 该版本已存在，需要更新版本号后再发布。

开发

本地开发

# 安装依赖
pnpm install

# 构建
pnpm --filter @ai-teacher/course build

# 清理
pnpm --filter @ai-teacher/course clean

项目结构

packages/course/
├── src/              # 源代码
│   ├── components/   # React 组件
│   ├── lib/          # 工具函数和库
│   └── types/        # TypeScript 类型定义
├── dist/             # 构建产物（发布到 npm）
├── package.json      # 包配置
└── tsup.config.ts    # 构建配置

许可证

[根据项目实际情况填写]

相关链接

• npm 包页面
• GitHub 仓库
• 问题反馈