每个教程应包含以下基本组成部分：
---
title: "教程标题"
slug: "tutorial-slug"
sequence: 1 # 教程在系列中的顺序号
description: "简短的描述，说明本节内容和学习收益"
is_published: true
estimated_minutes: 预计完成时间（分钟）
language: "zh-CN" # 或 "en"
---- 使用高质量的封面图片，突出主题
- 添加简短优美的描述，点明章节主旨
*一句话描述章节主旨*必须包含以下两部分：
## 本节概要
通过本节学习，你将学会：
- 列出3-5个具体的学习目标
- 使用动词开头，如"理解"、"掌握"、"学会"
- 确保目标具体且可衡量
💡 重点内容：
- 3-4个核心知识点
- 使用简洁的语言
- 突出实践价值- 使用有意义的语义化名称
- 采用小写字母和连字符
- 格式：
{主题}-{具体内容}.png - 示例：
linear-regression-intro.pngdata-distribution-example.pngmodel-comparison.png
-
本地生成
# 在教程目录下创建generate_images.py import matplotlib.pyplot as plt import numpy as np def generate_images(): # 1. 设置matplotlib样式 plt.style.use('seaborn') plt.rcParams['figure.figsize'] = [10, 6] plt.rcParams['font.sans-serif'] = ['Arial Unicode MS'] # 支持中文 # 2. 生成图片 fig, ax = plt.subplots() # ... 绘图代码 ... # 3. 保存到images目录 plt.savefig('images/example-plot.png', dpi=300, bbox_inches='tight', pad_inches=0.1) plt.close() if __name__ == '__main__': generate_images()
-
目录结构
ml-basics/ ├── images/ # 本地图片目录 │ ├── classification/ # 按教程分类 │ │ ├── overview.png │ │ └── logistic-regression.png │ └── linear-regression/ │ ├── intro.png │ └── comparison.png ├── generate_images.py # 图片生成脚本 └── classification.md # 教程文档 -
图片生成流程
# 1. 生成图片 cd ml-basics python generate_images.py # 2. 检查图片质量 open images/classification/*.png # 3. 上传到CDN python ../tools/upload_images_to_cdn.py classification.md
-
图片引用规范
- 在markdown中首先使用本地路径
- 上传到CDN后更新为CDN路径
-
图片更新流程
- 修改generate_images.py生成新图片
- 在本地确认图片效果
- 提交代码，包含：
- generate_images.py的修改
- 新生成的图片文件
- 教程文档的更新
- 上传到CDN并更新文档中的链接
- 再次提交文档更新
-
图片质量要求
- 分辨率：至少300dpi
- 格式：优先使用PNG格式
- 大小：单张图片不超过500KB
- 配色：使用统一的配色方案
- 字体：使用支持中文的无衬线字体
-
版本控制
- 图片文件必须纳入版本控制
- 保留generate_images.py的修改历史
- 图片更新时同时更新生成脚本
- 所有图片需上传到七牛云
- 使用语义化的文件名，保持与本地文件名一致
- CDN URL格式：
https://z1.zve.cn/tutorial/{教程名}/{filename}.png- 例如：
https://z1.zve.cn/tutorial/classification/logistic-regression.png
- 例如：
- 提供完整的可运行代码
- 包含必要的导入语句
- 添加详细的注释说明
- 展示运行结果和可视化输出
**运行结果：**
*结果说明：简要解释图表含义和关键发现*- commit message格式：
- feat: 新增内容或功能
- docs: 文档更新
- fix: 内容修复
- style: 格式调整
- 示例：
docs: 优化线性回归教程结构，添加学习概要
1. 删除冗长的目录结构
2. 添加本节概要，清晰展示学习目标
3. 突出重点内容
- 准备新图片，遵循命名规范
- 将图片放入对应的
images目录 - 更新文档中的图片引用
- 运行上传工具同步到CDN
- 提交代码，包含图片文件和文档更新
- 删除冗长的目录，用学习概要替代
- 每个概念配备实例和图示
- 使用emoji标注重点内容（如 💡）
- 保持语言简洁清晰
- 统一的命名规范
- 本地和CDN保持同步
- 图片名称要有意义
- 及时清理未使用的图片
- 完整的运行环境
- 清晰的注释说明
- 展示实际运行效果
- 解释关键输出结果
-
🎯 目标明确
- 开篇点明本章要解决的问题
- 使用"通过本章你将学会..."格式
- 列出3-5个具体可衡量的目标
-
📝 层次分明
- 从基础概念到高级应用，循序渐进
- 每个概念都有明确的前置知识链接
- 使用标题层级清晰展示内容结构
-
🔄 结构统一
- 每个章节使用统一的组织模式
- 概念解释 → 示例说明 → 实践练习
- 保持风格一致性
-
🗣 通俗易懂
- 使用生活化比喻解释专业概念
- 避免行业黑话和复杂术语
- 必要时提供术语表
-
📊 图文结合
- 使用图表说明复杂概念
- 适当使用emoji增强可读性
- 保持视觉元素的一致性
-
💡 重点突出
- 使用引用、加粗等格式突出关键信息
- 每节末尾总结核心要点
- 使用醒目的提示框标注重要内容
-
📚 由浅入深
- 从最简单的例子开始
- 逐步增加复杂度
- 每个概念配备基础和进阶示例
-
🎯 场景真实
- 使用实际工作中会遇到的案例
- 结合当前热点和技术趋势
- 提供完整的问题解决流程
-
💻 代码完整
- 提供可直接运行的代码示例
- 包含必要的环境配置说明
- 注释清晰，说明代码逻辑
-
✅ 即学即用
- 每个概念都配有实践练习
- 提供在线练习环境链接
- 设计循序渐进的任务
-
🔍 反馈闭环
- 提供评估和优化的方法
- 列出常见问题和解决方案
- 鼓励读者分享实践经验
-
📈 进阶路径
- 指明后续的学习方向
- 推荐进阶阅读材料
- 提供实战项目建议
- 内容是否符合目标受众水平
- 是否包含所有必要的前置知识链接
- 示例代码是否完整且可运行
- 图片是否清晰且主题相关
- 是否提供充分的实践机会
- 是否包含进阶学习路径
- 格式是否统一规范
- 是否进行了错别字检查
- 是否更新了相关文档链接
- 是否添加了必要的标签和元信息
## 概念名称
> 一句话描述概念的核心要点
### 基本原理
[简明扼要的原理解释，配合图示]
### 生活中的例子
[使用贴近生活的比喻]
### 代码示例
```python
# 完整的示例代码- 基础练习：[具体任务描述]
- 进阶挑战：[拓展任务描述]
💡 要点提示：[核心知识点总结]
#### 7.2 实战案例模板
```markdown
## 实战案例：[案例名称]
### 问题描述
- 背景：[项目背景]
- 目标：[具体目标]
- 挑战：[需要解决的问题]
### 解决方案
1. [步骤一]
2. [步骤二]
3. [步骤三]
### 代码实现
```python
# 完整的实现代码
[结果展示和分析]
- [改进点一]
- [改进点二]
使用对比的方式展示好坏做法：
# ❌ 不好的做法
```python
prompt = "分析这篇文章"prompt = """
任务：文章分析
要求：
1. 提取主要论点
2. 评估论证逻辑
3. 给出改进建议
"""从简单到复杂逐步展示：
### 1. 基础示例
```python
# 最简单的实现
basic_example = ...# 添加错误处理
advanced_example = ...# 生产环境可用的代码
production_example = ...每个示例应包含：
### 示例名称
#### 背景说明
- 使用场景
- 解决问题
- 技术要点
#### 代码实现
```python
# 完整代码# 输出结果- 关键点1
- 关键点2
## 实战案例：XXX
### 问题描述
- 背景：...
- 目标：...
- 挑战：...
### 解决方案
1. 步骤一
2. 步骤二
3. 步骤三
### 代码实现
```python
# 完整实现代码- 改进点1
- 改进点2
为每个实战案例提供评估标准：
metrics = {
"准确性": {
"评分标准": [
"完全符合要求：5分",
"基本符合要求：4分",
"部分符合要求：3分",
"较多偏差：2分",
"完全不符合：1分"
],
"权重": 0.4
},
"完整性": {
"评分标准": [
"覆盖所有要点：5分",
"遗漏次要点：4分",
"遗漏重要点：3分",
"严重遗漏：2分",
"基本未覆盖：1分"
],
"权重": 0.3
},
"实用性": {
"评分标准": [
"直接可用：5分",
"简单修改可用：4分",
"需要调整：3分",
"较难应用：2分",
"无法使用：1分"
],
"权重": 0.3
}
}每个章节的练习应包含：
-
基础练习
- 目标明确
- 步骤清晰
- 即学即用
-
进阶挑战
- 开放性任务
- 实战场景
- 引导思考
-
自测问题
- 概念理解
- 实践应用
- 问题排查
为练习提供完整的反馈机制：
### 练习：XXX
#### 任务描述
[具体任务]
#### 评分标准
- 完成度 (40%)
- 代码质量 (30%)
- 创新性 (30%)
#### 参考答案
```python
# 示例实现- 问题1
- 原因
- 解决方案
- 问题2
- 原因
- 解决方案
- 使用图表说明复杂概念
- 提供生活化的类比
- 突出关键信息
- 添加实践注意事项
- 完整的运行环境
- 清晰的注释说明
- 错误处理示例
- 性能优化建议
- 相关知识链接
- 推荐阅读材料
- 实战项目建议
- 深入学习方向
- 知识点完整性
- 示例实用性
- 代码可运行性
- 练习合理性
- 格式规范
- 图片质量
- 代码风格
- 文字流畅
- 学习路径清晰
- 示例易于理解
- 练习难度适中
- 反馈机制完善