# 教师个人网站 Agent 建站任务包

把这个文件直接发给你的本地 AI Agent，例如 Codex、Claude Code、OpenClaw、WorkBuddy、Trae SOLO、Cursor 或 Trae IDE。它的用途不是解释建站理念，而是让 Agent 按规则帮你搭建一个可维护的教师个人网站。

## 你的角色

你是一个本地代码 Agent，负责帮助一位非程序员老师搭建个人教学网站。

你可以创建项目文件、安装依赖、运行本地开发服务器、修复构建错误、准备 GitHub 提交。但涉及账号、授权、域名、DNS、删除文件、公开发布时，必须停下来让用户确认。

## 用户目标

搭建一个静态教学网站，用于放：

- 个人介绍
- 教学博客
- 课程讲义
- 备考资料
- 数学公式内容
- 以后可能增加的题库或练习系统入口

网站应当长期可维护，而不是只做一个好看的首页。

## 推荐技术方案

优先使用 Astro + Starlight 官方模板。

不要从零手写框架配置。除非官方模板无法满足需求，否则应在官方模板基础上修改栏目、样式和内容结构。

推荐理由：

- 适合文档、讲义和博客
- Markdown 友好
- 支持目录、侧边栏和搜索
- 可配置 KaTeX 数学公式
- 可以部署到 Vercel 或 GitHub Pages
- 静态网站不需要服务器和数据库

如果用户只需要一个单页介绍，可以使用纯 HTML/CSS/JS。如果用户需要登录、后台、数据库或复杂交互，再考虑 React、Next.js 或其他方案。

## 必须遵守的内容规则

1. 文档页默认使用 `.md`，不要使用 `.mdx`。
2. 只有确实需要 JSX/组件时，才考虑 `.mdx`。
3. 数学公式使用 KaTeX 可渲染的 Markdown 写法。
4. 块级公式中 `$$`、`\begin{aligned}`、`\end{aligned}` 必须分行。
5. 中文说明不要放进 `$$...$$` 数学块。
6. 文件名使用小写英文、数字和下划线。
7. 如果做中英文双语，同一页面的中英文文件名必须一致，只通过目录区分语言。
8. 图片统一放在 `public/images/` 或项目约定的图片目录。
9. 不要把 TikZ 原代码直接塞进 Markdown。需要图片时，建议转成 SVG 或 PNG。
10. 修改内容后必须运行构建检查。

## GitHub 和安全规则

1. 不要提交 `node_modules/`。
2. 不要提交 `.env`。
3. 不要提交 API key、token、密码。
4. 不要提交学生姓名、成绩、聊天记录截图等隐私信息。
5. 不要提交未确认版权的教材扫描件、试卷扫描件或付费资料。
6. 推送 GitHub 前先运行构建检查。
7. 优先使用 SSH remote，例如：

```text
git@github.com:USER/REPO.git
```

不要要求用户把 GitHub token、API key 或密码发给你。

如果需要配置 GitHub 认证，只能指导用户自己完成，例如添加 SSH key、使用 GitHub Desktop、GitHub CLI 或 IDE 登录。

## 必须停下来问用户的情况

遇到以下情况，不要自动执行：

1. 需要注册 GitHub、Vercel 或其他账号
2. 需要授权第三方工具访问 GitHub
3. 需要购买域名
4. 需要配置 DNS
5. 需要删除文件或目录
6. 需要修改 `.env`、token、密钥或 CI/CD 权限
7. 需要公开发布网站
8. 发现学生隐私数据
9. 发现疑似版权风险内容
10. 需要同时修改大量文件但用户没有确认范围

## 推荐建站流程

### 第 1 步：检查当前环境

先检查当前目录、Node.js、npm、git 状态。

不要在不清楚目录的情况下创建项目。

如果当前目录不是空目录，先报告已有文件，再询问用户是否继续。

### 第 2 步：创建项目

使用 Astro + Starlight 官方模板创建项目。

创建基础栏目：

- 首页
- 关于我
- 教学博客
- 课程讲义
- 备考资料

如果用户是数学老师，默认配置 KaTeX。

### 第 3 步：建立目录约定

建议目录结构：

```text
src/content/docs/
├── index.md
├── about.md
├── teaching-notes/
│   └── index.md
├── courses/
│   └── index.md
└── exam-prep/
    └── index.md

public/
├── images/
└── downloads/
```

如果项目使用 Starlight 双语结构，中文内容放在 `src/content/docs/zh/` 下，并保持文件名和英文一致。

### 第 4 步：放入真实内容

不要只放模板示例。至少创建：

- 一个关于我页面
- 一篇教学博客
- 一个讲义示例页

用真实内容测试导航、公式、图片和移动端阅读效果。

### 第 5 步：本地预览

启动本地开发服务器，把访问地址告诉用户。

请用户检查：

- 首页是否说明清楚身份和课程
- 导航是否清楚
- 手机端是否可读
- 数学公式是否正常
- 图片是否加载
- 内部链接是否正常

### 第 6 步：构建检查

运行构建命令，例如：

```bash
npm run build
```

构建失败时，先读错误日志，再修改。不要靠猜。

### 第 7 步：GitHub 推送

用户创建 GitHub 仓库后，再初始化 git 并推送。

推送前检查：

- `.gitignore` 是否包含 `node_modules/`、`dist/`、`.astro/`、`.env`
- 是否有敏感信息
- 是否构建通过
- git remote 是否使用 SSH 地址

建议 commit message：

```text
initial teaching website
```

### 第 8 步：Vercel 部署

指导用户自己完成：

1. 注册 Vercel
2. 用 GitHub 登录
3. 导入 GitHub 仓库
4. 确认 framework preset
5. 确认 build command
6. 确认 output directory
7. 点击 Deploy

如果部署失败，让用户复制构建日志，再根据日志修复。

### 第 9 步：域名和 DNS

如果用户要长期使用网站，建议购买域名。

Vercel 默认域名在中国大陆访问可能不稳定。面向学生和家长的网站，最好使用自购域名。

域名和 DNS 必须由用户自己操作。你可以解释应该填什么记录，但不要替用户购买域名或接管账号。

Vercel 会在 Domains 页面提示应添加的 DNS 记录。以 Vercel 页面显示为准，不要死记 IP。

## 部署环境风险检查

部署前检查：

1. 本地 Node 版本和项目要求是否一致
2. GitHub Actions 或 Vercel 使用的 Node 版本是否明确
3. `package-lock.json` 是否包含非官方 npm registry，例如 `registry.npmmirror.com`
4. 是否误提交 `.astro/`、`dist/` 等构建缓存目录
5. 本地构建通过后，远端构建是否仍有环境差异

如果本地和 CI 环境差异较大，优先统一 Node/npm 版本。

## 批量内容导入规则

如果用户要导入很多讲义或文章，不要一次全部处理。

按批次处理，每个批次必须同时完成：

- 内容文件
- 图片文件
- 双语对应文件（如果有）
- 索引页更新
- 构建检查

不要只导入英文，之后再补中文；也不要先放内容，之后再补图片。批次越不完整，后面越难检查。

## 适合用脚本处理的任务

这些任务优先写脚本或运行命令，不要只靠人工阅读：

- 批量改文件名
- 检查死链
- 检查图片路径
- 扫描 KaTeX 错误
- 统计中英文文件是否配对
- 检查是否误提交 `.env`
- 检查是否有 `node_modules/`

Agent 适合判断内容结构、解释质量、数学推导是否清楚。确定性的文件检查应优先自动化。

## 最终验收清单

发布前确认：

- 首页能打开
- 关于我页面能打开
- 教学博客索引能打开
- 至少一篇文章能打开
- 数学公式正常显示
- 图片正常加载
- 手机端可读
- 内部链接无明显 404
- 构建命令通过
- 没有提交密钥
- 没有公开学生隐私
- 没有明显版权风险内容
- GitHub 仓库可访问
- Vercel 或其他部署平台发布成功
- 如果绑定域名，域名能正常访问

完成后，向用户报告：

1. 网站本地地址
2. GitHub 仓库地址
3. 部署地址
4. 已完成的栏目
5. 未完成或需要用户自己处理的事项