> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 站点维护指南

> 维护 Codex 完整教程站点、更新页面并发布到 Mintlify。

# 《Codex 完整教程》站点维护指南

本指南说明如何维护教程内容、更新导航并发布网站。站点使用 Mintlify 构建，内容通过 Git 推送后自动部署。

## 站点信息

| 项目          | 值                                                           |
| ----------- | ----------------------------------------------------------- |
| 线上地址        | [aicoding.cscitech.top](https://aicoding.cscitech.top/)     |
| 备用地址        | [ai-coding.mintlify.site](https://ai-coding.mintlify.site/) |
| Mintlify 组织 | `AI Coding`                                                 |
| 子域名         | `ai-coding`                                                 |
| 内容仓库        | [MAX-API-Next/docs](https://github.com/MAX-API-Next/docs)   |
| 本地仓库路径      | `E:\20260824教程网站\docs`                                      |
| Codex 参考内容  | `E:\20260824教程网站\参考\codex`                                  |

推送到 `main` 分支后，Mintlify 会自动构建并发布。通常等待 1–2 分钟即可看到更新。

## 目录结构

```text theme={null}
docs/
├── docs.json                         # 站点配置和侧边栏导航
├── index.mdx                         # 教程首页
├── 01-认识-Codex/                    # 概念、入口和代理循环
├── 02-第一次使用/                    # 安装、登录和第一个任务
├── 03-四种入口实战/                  # CLI、IDE、App、Cloud
├── 04-日常工作流/                    # 探索、修复、开发、审查
├── 05-安全与控制/                    # 沙箱、注入、隐私和恢复
├── 06-定制自己的Codex/               # AGENTS.md、config 和会话
├── 07-扩展Codex能力/                 # MCP、Skills、Subagents 等
├── 08-工程化使用/                    # Worktree、Git、CI/CD 和治理
├── 09-综合实战/                      # 从需求到发布的完整练习
├── 10-查阅手册/                      # 速查、术语、排错和迁移
├── 旧/                               # 历史 AI Coding 内容，暂不纳入主导航
├── scripts/                          # 内容转换和辅助脚本
└── 维护指南.md                       # 本文件
```

当前 Codex 教程共有 10 组页面。页面实际使用中文目录和 `.md` 文件，首页使用 `index.mdx`；`docs.json` 中的导航路径不写文件扩展名。

## 页面格式

每个新页面都应包含 `title` 和 `description`：

```markdown theme={null}
---
title: "页面标题"
description: "页面简介，说明读者看完后能完成什么。"
---

页面正文
```

编写时保持一页一个主题，先说明用途，再给出步骤、示例和验收方式。文件名可以暂时沿用现有中文命名；新增页面建议使用英文 kebab-case，避免空格和特殊符号。

## 更新页面和导航

1. 在对应章节目录中创建或编辑 `.md`/`.mdx` 页面。

2. 在 `docs.json` 的 `navigation` 中加入页面路径，否则页面不会出现在侧边栏中。

3. 导航路径使用根路径形式且不带扩展名，例如：

   ```text theme={null}
   04-日常工作流/03-修复Bug
   ```

4. 页面之间的内部链接也使用根路径、不带扩展名，例如：

   ```markdown theme={null}
   [开始第一次使用](/02-第一次使用/01-安装与登录)
   ```

删除或移动页面时，要同步修改 `docs.json` 和相关内部链接。

## 本地检查

在文档仓库根目录执行：

```powershell theme={null}
cd E:\20260824教程网站\docs
mint broken-links
mint validate
```

`mint broken-links` 检查站内链接，`mint validate` 检查配置和页面格式。旧目录 `旧/` 中可能保留历史断链；如果检查报告只涉及该目录，先确认没有影响新增 Codex 页面。

需要预览时运行：

```powershell theme={null}
mint dev
```

然后打开 [http://localhost:3000/](http://localhost:3000/)，结束预览按 `Ctrl+C`。

## 提交和发布

确认检查通过后执行：

推送时需要使用 7897 端口；提交前确认当前 Git 远端或代理配置没有绕过该端口。

```powershell theme={null}
cd E:\20260824教程网站\docs
git add -A
git commit -m "更新 Codex 教程内容"
git push origin main
```

推送完成后等待 1–2 分钟，再访问 [aicoding.cscitech.top](https://aicoding.cscitech.top/) 验证首页、侧边栏和新增页面。若自定义域名暂时不可用，可使用备用地址检查部署结果。

## 故障排查

* **侧边栏没有页面**：检查页面是否已加入 `docs.json` 的 `navigation`，并确认路径与文件名完全一致。
* **页面返回 404**：检查路径大小写、中文字符和扩展名；导航和内部链接都不要写 `.md` 或 `.mdx`。
* **推送后没有更新**：确认推送目标为 `MAX-API-Next/docs` 的 `main` 分支，并在 Mintlify 控制台查看部署状态。
* **本地预览启动失败**：先运行 `mint update` 更新 CLI，再重新执行 `mint dev`。
* **构建出现旧内容断链**：优先确认报告中的路径是否属于 `旧/`；修复新 Codex 页面产生的错误后再处理历史内容。

## 维护原则

* 章节顺序遵循“认识 → 上手 → 入口 → 工作流 → 安全 → 定制 → 扩展 → 工程化 → 实战 → 查阅”。
* 示例应可运行，涉及权限、网络、密钥和 Git 的操作要明确风险及回滚方式。
* 不直接修改 `旧/` 中的历史页面，除非任务明确要求迁移或修复。
* 每次发布尽量只包含一个主题的改动，便于审查、回滚和定位问题。

示例：
docs.json 已删除旧的“基础 / 进阶 / 提高”导航，只保留新的 Codex 教程结构。
旧/ 目录保留在仓库中，但已加入 .mintignore，不会出现在网站。
维护指南.md 已修订并加入“查阅手册”。
mint validate、mint broken-links 均通过。
已通过 7897 端口推送，远程提交：e0d58cf。
网站页面检查均返回 200：