# 项目维护与排版规范

本文档记录了本项目的目录结构分类标准以及 `README.md` 的排版规范。在后续添加新内容或使用 AI 助手协助维护时，请严格遵循以下准则。

## 📁 1. 目录结构规范

项目根目录下的文件夹严格按照视频系列进行编号和分类，确保代码、文档与视频内容“所见即所得”。

- `01-agent-sys/`：Agent 智能体系统（最新专题置顶）
- `02-llm-core/`：大模型核心技术（包含微调、部署、RAG等核心实战代码及文档）
- `03-open-source/`：动手加入开源（包含工程化实践如 uv, ruff, pre-commit, pytest 等）
- `04-module-specials/`：模块知识专题系列（包含 kaggle, gradio, docker 等多 P 专题）
- `05-ai-projects/`：不着调的 AI 项目（脑洞大开的 AI 落地项目代码或说明）
- `06-extras/`：番外篇（如 B站抽奖脚本等杂项）
- `assets/`：存放静态资源（如 Logo 图片等）

**注意**：请勿在根目录下随意平铺新建文件夹。所有的配套代码和说明文档（`.md` 或 `.pdf`）都应归入上述对应的系列文件夹中。

## 📄 2. README 排版规范

主页 `README.md` 的设计目标是：**极简、清晰、专业**。

### 2.1 克制使用 Emoji
- 拒绝花里胡哨，**不要使用**诸如 🧠、⛰️、🎮 等过于活泼或容易引起视觉疲劳的图标。
- 仅在主标题或大章节标题处保留基础且克制的符号（如 📌、💡、🛠️、📦、🚀、🎈、📚）用于区分层级。

### 2.2 表格瘦身与高信息密度
- 避免表格在手机端或小屏幕上过宽导致左右滑动。
- **合并列**：将“视频教程”和“视频时长”合并为一列。
- **使用小徽章**：使用精巧的 B站和 YouTube 徽章代替大段文字或大图标，时长作为纯文本跟在徽章后面。
  - B站徽章请将默认的 `label=views` 替换为 `label=B%E7%AB%99`（即“B站”），以节省空间并保持语义清晰。
  - 示例格式：`[![bilibili][img_1]][ref_1] [![youtube][img_2]][ref_2] ⏱️ 26:01`

### 2.3 源码整洁（使用 Markdown 引用链接）
- 为了解决表格行源码过长、难以阅读和维护的问题，**所有图片和超链接必须使用 Markdown 引用链接格式**。
- 将冗长的 URL 统一放置在 `README.md` 的最底部 `<!-- 底部链接引用区 -->`。
- 严禁在表格内直接写出长达几百字符的 `img.shields.io` 或视频 URL。

### 2.3 长列表折叠交互
- 对于超过 5 项的长列表（如“大模型核心技术”系列），必须采用折叠交互排版。
- **默认外露**：仅展示最新更新的 3 期内容。
- **折叠往期**：使用 HTML 的 `<details>` 和 `<summary>` 标签将往期内容折叠起来。
  - 示例：`<summary><b>点击展开查看往期 1~18 期内容</b></summary>`

### 2.4 清晰的导航与置顶
- 必须在 README 顶部保留 `📑 快速导航`，使用锚点链接方便读者一键跳转。
- 最新的核心专题（如 `Agent 智能体系统`）必须置于导航和正文的**最顶部（序号 1）**，并可加上 `(New!)` 标识以吸引注意力。