企业官网建设流程全解析

data-engineering-zoomcamp 图片资产审计实战：94 处 Markdown 图片引用的盘点、分类处置与可复用方法论

【免费下载链接】data-engineering-zoomcampData Engineering Zoomcamp is a free 9-week course on building production-ready data pipelines. Join the course here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/da/data-engineering-zoomcamp

导读

本篇文章基于 />

审计范围界定：哪些 Markdown 图片引用被纳入

这次审计（rollout）的目标非常明确——覆盖指定模块目录与 cohort 目录下每一个本地 Markdown 图片引用：

• 模块目录：01-docker-terraform/**（含docker-sql）、02-workflow-orchestration/**、05-data-platforms/**、06-batch/**等历史与现行模块；
• cohort 路径：cohorts/2022、cohorts/2024、cohorts/2025、cohorts/2026，以及cohorts/2027/02-workflow-orchestration。

初始盘点结果为94 处本地引用、对应 92 个唯一源路径，图片类型覆盖四类：视频缩略图、Airflow/UI 精确截图、教学说明图（explanatory diagrams）、workshop 资产与作业证据（homework evidence）。这份范围界定本身就是一个值得复用的经验：审计的第一步不是看图，而是先用正则扫描所有 Markdown 中的图片引用，建立「引用 → 源路径」清单，之后的所有处置与验证都以该清单为唯一事实来源。

审计方法与评审门槛：从清单到处置

记录中明确了三条方法论支柱，这也是整份审计可复现的关键：

1. 来源优先（source-first）：先阅读被引用图片所在的教学文档段落，确认该图片承载的「教学点」（teaching point），再决定是否保留；
2. 确定性优先（deterministic-first）：精确的 UI、代码、URL、数字、Logo、绘图类素材保持原样或仅做确定性裁剪/锐化，绝不交给生成模型；只有「有界的概念示意图」在裁剪与人工检查后才允许使用 imagegen；
3. 保留证据（evidence retention）：所有原始图片原地保留，替换一律生成同目录下的新文件（如-cropped.png、-imagegen.png），保证任何时刻都能回滚到源头。

从仓库的兄弟审计记录（.tmp/de-2027-batch-image-rollout.md）可以看到，这套方法论被进一步固化为「插图评分规则」（rubric）：被保留的图片必须有具体的教学点、与正文/代码相关、可读、对课程有长期价值、配得上一个有用的题注；而 .tmp/de-2027-distrust-audit.md 则补上了「不信任门」（distrust gate）——凡是「通用生成、非来源忠实（not source-faithful）、且无视频/源码支撑」的插图一律删除且不编造替代内容。本次审计正是这一系列治理实践的「legacy + current」总盘点。

被接受的图片变更：三份逐条处置记录

整份审计最终只产生三类「内容变更」，每一条都有完整的来源、方法、不变量检查与替换产物：

1. 增量加载决策树：唯一一次 imagegen 替换

• 来源：incremental_loading.png
• 引用处：cohorts/2024/workshops/dlt_resources/data_ingestion_workshop.md，位于「Incremental loading」一节，讲解 append / merge 两种增量加载方式之后；
• 处置：crop/replace，评分 11/12。这棵树教学的是 append、replace、merge/upsert 三种写处置（write disposition）的选择逻辑，生成替换图完整保留了全部标签、分支方向与结局，同时让排版与线条更清晰；
• 方法：本地检查后调用内置 imagegen 编辑（imagegen edit），前后均复核，不新增人脸、摄像头画面、浏览器边框、光标、水印或额外组件；
• 必查不变量：Is it stateful data?、NO/YES分支顺序、Can you request it incrementally?，以及最终恰好三个处置分支；
• 替换产物：incremental_loading-imagegen.png。

注意这里的关键决策边界：决策树是「有界的说明图」，其标签数量有限且语义已由源码确认，所以生成风险可控；而任何带确切文本/数字的素材则被明确排除在 imagegen 之外。

2. 作业数据集证据：确定性裁剪并被三处复用

• 来源：02-workflow-orchestration/images/homework.png（2025、2027 cohort 目录下保留同一原始副本）；
• 引用处：2025、2026、2027 三年 workflow-orchestration 的作业文档（如 cohorts/2025/02-workflow-orchestration/homework.md、cohorts/2026/02-workflow-orchestration/homework.md）;
• 处置：crop/replace，评分 10/12。该截图独一无二地展示了作业要求学员摄入的 2021 年 yellow/green 数据集资产，为文字作业补充了具体文件名与大小；
• 方法：本地检查后对两侧做确定性裁剪——左栏820x750+0+25，右栏820x760+824+25，填充拼接为1640x760，即 homework-cropped.png。裁剪移除了浏览器地址栏与互动控件，精确保留了文件名、大小、日期、高亮的 2021 行与紫色教学批注；
• 不使用 imagegen 的理由：确切的 UI 文本、文件名、日期与数值大小才是事实来源（source of truth），生成模型不可信。

3. 2022 年 IAM 搜索页：唯一一次相对路径修复

• 来源：images/aws/iam.png
• 引用处：cohorts/2022/week_2_data_ingestion/transfer_service/README.md
• 处置：keep，评分 8/12。该截图直接支撑「创建访问密钥前先搜索 IAM」的操作指引，且 AWS 标签可读，因此原图保留、仅修复损坏的相对路径为../../../../images/aws/iam.png；
• 方法：保留精确来源，不做 imagegen——因为这是活 UI，其标签本身就是事实来源，且源图中不含人脸或摄像头画面。

这三条记录放在一起，恰好演示了图片治理的完整决策光谱：能确定性处理的绝不动用生成模型，能用现有资产的绝不新建资产，路径损坏的优先修复而非替换。

最终清单与处置统计

审计收口时的数字是检验治理是否「彻底」的硬指标：

• 审计94 处本地 Markdown 图片引用；
• 初始清单含92 个唯一路径字符串：91 个已存在的源文件 + 1 个损坏的 IAM 路径；修复与共享替换后，活跃引用使用91 个唯一、可解析的源路径；
• 保留 94 处，移除 0 处：没有任何图片在「教学价值 / 导航价值」硬性门槛（hard gates）上失败；
• 内容变更合计：1 处 imagegen 替换（决策树）、1 处确定性裁剪（被 3 处引用复用）、1 处相对路径修复；其余 89 处引用保持原始像素与源资产不变；
• 原始文件全部保留，包括两个重复的 homework 原始图与原始增量加载图。

这意味着本次审计的姿态是「修复与增强，而非删减」：94 张图中 89 张原样存活，只有 3 类变更，且全部有据可查。

视频缩略图清单：80 张导航图的「保留」理由

所有 80 处缩略图引用都在接触表（contact sheet）中逐张检查过。它们的处置统一为保留（keep），评分 8/12，理由是：这些是导航资产，链接到对应视频，因此演讲者头像、播放按钮和经过设计的缩略图图形是刻意为之的内容，而非不受欢迎的摄像头/录屏叠加层。周围的教学标题与所链接的视频提供了题注与上下文，无需 imagegen 或确定性重写。

清单中的路径即这些 Markdown 范围实际引用的thumbnail-*.jpg文件；未被引用的缩略图不在变更之列。顺带一提，这类自托管缩略图本身源自仓库的自动化：scripts/generate_thumbnails.py会把过去依赖外部服务（markdown-videos-api）的 YouTube 缩略图链接改为下载原图、叠加自绘播放按钮、落盘到 README 同目录的images/thumbnail-*.jpg，从而消除运行时依赖与缓存超时问题——这与本次审计「本地化、可解析、可验证」的资产治理目标一脉相承。

教学图片清单：逐张评分与决策

除了缩略图，审计还给出了 11 个教学图片条目的逐张评分与决策，构成一份可以直接照抄的「决策样板」：

一个值得注意的细节：dlt.png评分 11/12 却明确「不要交给 imagegen」——因为其中包含精确的产品 Logo 与标签，这类品牌化素材同样属于「确定性优先」的范畴。

方法总计：三类处理手段的比例

• Imagegen：仅 1 处有界说明图（决策树），生成前后均检查，所有精确标签与分支方向通过复核；
• 确定性处理：1 处精确 UI 截图裁剪，被 3 处作业引用复用；移除浏览器地址栏与互动控件，不改动文件名、日期、大小、高亮或教学批注；
• 原样保留：80 张视频缩略图 + 9 个其他教学源，以及路径修复后的 IAM 源图；
• 移除：0。每张保留图都贡献了导航价值、精确技术证据或独立的说明关系之一。

验证环节：让审计结论可被证伪

审计记录没有停留在「自认为没问题」，而是给出了三条可复现的验证手段，这也是治理文档的成熟之处：

1. 重跑清单：编辑完成后重跑源清单扫描——94 处本地引用、91 个唯一活跃路径、0 个缺失路径；
2. git 卫生检查：每个聚焦提交（focused commit）与最终审计状态均通过git diff --check；
3. 原分辨率人工检查：生成与裁剪产物均用view_image在源分辨率下检查，且原始文件未被覆盖。

这套「扫描 → 处置 → 重扫 → diff 检查」的闭环，与 .tmp/de-2027-warehouse-image-rollout.md 中「33/33 引用可解析、0 个旧.jpg引用残留、git diff --check通过」的验收口径完全一致，说明这是该仓库图片治理的一贯标准。

局限与边界：审计者主动声明的「不做」

一份好的审计文档同样要写清楚边界，本记录的四条 limitations 值得原样继承：

• 历史 UI 图不重建：Airflow 与 AWS 图片保留精确的历史 UI 标签与日期，因为这些像素本身就是教学证据；
• 作业裁剪保留教学批注：homework 裁剪保留原始紫色批注（它们解释了学员必须摄入哪些 2021 资产），只移除浏览器边框与互动控件；
• 缩略图人像是刻意内容：视频缩略图中的演讲者人像是讲师作品/导航内容的一部分，移除会破坏其「视频链接」职责；
• 生成图的白底差异：imagegen 决策树使用干净的白色背景而非源图的透明画布，但所有文本与关系保持不变。

总结：一套可复用的文档图片治理流程

纵观整份审计记录，可以把方法论提炼为五个步骤，直接套用到任何技术文档仓库：

1. 盘点：正则扫描 Markdown 图片引用，建立「引用 → 源路径 → 教学点」清单，先读文档再评图；
2. 分类：区分「精确证据（UI/代码/数字/Logo）」「有界说明图」「导航资产」三类，分别对应确定性处理、有条件的 imagegen、原样保留；
3. 处置：优先确定性裁剪/路径修复，其次生成替换（前后必须复核），永不覆盖原始文件，替换产物放在同目录并遵循-cropped/-imagegen命名；
4. 验证：重跑引用扫描确认 0 缺失，git diff --check通过，产物在源分辨率下人工复核；
5. 留痕：把每张图的来源、方法、评分、不变量检查、验证结果写进审计记录，让任何后续维护者都能还原决策依据。

data-engineering-zoomcamp 的这次 legacy/current 图片审计，最终以「94 处引用、0 移除、89 张原样、3 类变更、全部可解析」收官——它证明了高质量的技术文档资产治理不是「删图或造图」，而是为每一张图片找到它在教学体系中不可替代的职责，并用最小必要的手段让它清晰、可读、可长期存活。

【免费下载链接】data-engineering-zoomcampData Engineering Zoomcamp is a free 9-week course on building production-ready data pipelines. Join the course here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/da/data-engineering-zoomcamp