Security-101 AI Agent 协作指南:面向自动化贡献者的仓库结构与开发工作流全解析

原创2026-09-17 18:45:311,868 阅读
文章标签:网络安全教程文档

Security-101 AI Agent 协作指南:面向自动化贡献者的仓库结构与开发工作流全解析

Security-101 是一个由 Microsoft 发起的初学者友好型网络安全课程仓库,其内容以 Markdown 文档为核心、通过 Docsify 渲染为静态站点,并借助 Co-op Translator 自动翻译为 50+ 种语言。本文以仓库根目录的 AGENTS.md(及其英文翻译版 translations/en/AGENTS.md)为骨架,系统梳理该仓库的模块结构、本地预览方式、自动翻译流水线、GitHub Actions 部署链路与贡献规范,并结合 .github/workflows 下的真实流水线配置进行源码级印证,帮助 AI Coding Agent 与人类贡献者快速理解如何在该仓库中安全、规范地提交内容变更。

一、项目概览:这是一个"文档即课程"的仓库

Security-101 是一套面向初学者的网络安全课程,定位是"以文档为基础的学习资源"。它不依赖任何构建工具或包管理器,核心交付物就是按模块组织的 Markdown 文件。理解这一点是后续所有操作的前提:

  • 内容载体:Markdown,课程正文全部以 .md 文件呈现;
  • 静态站点:通过 index.html 中的 Docsify 在浏览器中渲染 Markdown,index.html 中配置了 window.$docsify = { name: 'Cybersecurity for Beginners', repo: '...', relativePath: true };
  • 托管方式:GitHub Pages;
  • 多语言:Co-op Translator(Azure AI 服务)自动完成 50+ 语言翻译;
  • CI/CD:GitHub Actions 承担翻译与部署两条自动化链路。

关键技术栈与架构要点

从 AGENTS.md 的 Project Overview 与 Architecture 一节可以看到:

层次 选型 作用
内容 Markdown 课程正文,无构建依赖
渲染 Docsify 将 Markdown 渲染为静态 HTML 站点
托管 GitHub Pages 对外发布站点
翻译 Co-op Translator + Azure AI 自动产出 50+ 语言版本
自动化 GitHub Actions 翻译、部署、Jekyll 构建三条工作流

仓库的目录骨架如下(与根目录实际结构一致):

/
├── README.md                    # 课程总览与模块表(主入口)
├── index.html                   # Docsify 站点入口
├── [1-8].[1-4] *.md            # 课程模块与子课程
├── CODE_OF_CONDUCT.md          # 社区行为准则
├── SECURITY.md                 # 安全策略与漏洞上报流程
├── SUPPORT.md                  # 支持信息
├── LICENSE                     # MIT 许可
├── images/                     # 课程图片素材
├── translated_images/          # 翻译后的图片素材
├── translations/               # 50+ 语言的翻译版本
└── .github/
    ├── workflows/
    │   ├── co-op-translator.yml    # 自动翻译工作流
    │   ├── deploy.yaml             # GitHub Pages 部署
    │   └── jekyll-gh-pages.yml     # Jekyll 站点生成
    └── ISSUE_TEMPLATE/             # Issue 模板

二、8 大模块的内容编排:课程骨架与命名规范

课程的 8 个主模块按顺序组织,每个模块包含若干子课程并以"模块测验"收尾。这是仓库的核心信息架构,新增或修改内容时必须严格遵守:

模块 主题 课程范围 收尾测验
1 基础安全概念(CIA 三元组、威胁、风险管理等) 1.1–1.6 1.7
2 身份与访问管理(IAM) 2.1–2.3 2.4
3 网络安全 3.1–3.3 3.4
4 安全运营(SecOps) 4.1–4.3 4.4
5 应用安全(AppSec) 5.1–5.2 5.3
6 基础设施安全 6.1–6.2 6.3
7 数据安全 7.1–7.2 7.3
8 AI 安全 8.1–8.3 8.4

模块结构与根目录课程文件一一对应,例如 1.1 The CIA triad and other key concepts.md、1.2 Common cybersecurity threats.md 属于模块 1,而 1.7 End of module quiz.md 是模块 1 的收尾测验。

文件命名约定

  • 课程文件格式固定为 [模块号].[课时号] [标题].md,例如 1.1 The CIA triad and other key concepts.md;
  • 测验文件格式为 [模块号].[末位] End of module quiz.md,例如 2.4 End of module quiz.md;
  • 文件名使用空格(沿用仓库既有约定),不要改写为下划线或驼峰式命名。

课程内容写作准则

  • 单课时阅读时长控制在 30–60 分钟,保持简洁聚焦;
  • 语言面向初学者,清晰易懂;
  • 课程保持厂商中立(vendor-neutral),避免针对特定厂商工具的操作指引;
  • 每个模块开头需包含学习目标(learning objectives);
  • 内容定位是教育而非宣传。

三、本地开发:无需构建的纯文档工作流

Security-101 是文档项目,没有任何依赖需要安装。查看与预览内容有以下方式:

克隆与查看

# 克隆仓库
git clone <repository-url>
cd Security-101

# 方式一:任何 Markdown 查看器均可直接阅读
# 方式二:用简单 HTTP 服务器启用 Docsify 渲染
python -m http.server 8000
# 然后浏览器访问 http://localhost:8000

本地预览的三种选择

# 方式一:Python 内置 HTTP 服务器(最推荐,零依赖)
python -m http.server 8000

# 方式二:Node.js http-server(如环境已安装 Node)
npx http-server -p 8000

# 方式三:直接用任意 Markdown 编辑器打开文件查看

结合 index.html 的配置可以看出,Docsify 通过 CDN 引入 docsify.min.js,relativePath: true 使得站点内的相对链接在渲染时能正确解析,因此本地起一个静态服务器即可获得与线上一致的浏览体验。

修改内容的步骤

  1. 直接编辑根目录下的 Markdown 文件;
  2. 遵循 [module].[lesson] [Title].md 命名约定;
  3. 新增或删除模块时同步更新 README.md 的模块表;
  4. 图片放入 images/ 目录,并在正文中用相对路径引用;
  5. 使用描述性 alt 文本,便于无障碍访问与检索。

四、多语言翻译工作流:Co-op Translator 深度解读

这是该仓库最具特色的自动化环节。翻译由 GitHub Action 全自动管理,人工不得手动编辑翻译文件(会被覆盖)。

工作流触发与产物

  • 触发条件:向 main 分支推送变更;
  • 处理对象:新增或修改的 Markdown 文件;
  • 产物位置:翻译文件写入 translations/[language_code]/,翻译图片写入 translated_images/;
  • 元数据:每个翻译文件头部保留 YAML frontmatter,例如 translations/en/AGENTS.md 顶部即包含 CO_OP_TRANSLATOR_METADATA(含 original_hash、translation_date、source_file、language_code)。

支持的 50+ 语言

从 translations/en/README.md 的语言表可以看到实际支持的语言目录包括:阿拉伯语、孟加拉语、保加利亚语、缅甸语、简体中文、繁体中文(港/澳/台)、克罗地亚语、捷克语、丹麦语、荷兰语、爱沙尼亚语、芬兰语、法语、德语、希腊语、希伯来语、印地语、匈牙利语、印度尼西亚语、意大利语、日语、卡纳达语、韩语、立陶宛语、马来语、马拉雅拉姆语、马拉地语、尼泊尔语、尼日利亚皮钦语、挪威语、波斯语、波兰语、葡萄牙语(巴西/葡萄牙)、旁遮普语、罗马尼亚语、俄语、塞尔维亚语、斯洛伐克语、斯洛文尼亚语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰米尔语、泰卢固语、泰语、土耳其语、乌克兰语、乌尔都语、越南语等。

工作流源码级剖析

.github/workflows/co-op-translator.yml 展示了完整实现:

  • 触发:push 到 main 分支;
  • 环境:ubuntu-latest,Python 3.10;
  • 安装:pip install co-op-translator;
  • 执行:translate -l "all" -y(支持按批次指定语言,文件量大时分批执行以避免超过 GitHub Runner 的 6 小时上限,如 translate -l "zh tw hk fr ja ko pt es de fa pl hi" -y 等注释示例);
  • 凭据注入:通过 GitHub Actions Secrets 注入环境变量:
    • Azure AI Service:AZURE_AI_SERVICE_API_KEY、AZURE_AI_SERVICE_ENDPOINT;
    • Azure OpenAI(可选替代):AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_MODEL_NAME、AZURE_OPENAI_CHAT_DEPLOYMENT_NAME、AZURE_OPENAI_API_VERSION;
    • OpenAI(可选替代):OPENAI_API_KEY、OPENAI_ORG_ID、OPENAI_CHAT_MODEL_ID、OPENAI_BASE_URL;
  • 提交方式:翻译完成后,用 GitHub App Token(GH_APP_ID + GH_APP_PRIVATE_KEY)通过 create-pull-request 动作自动创建标题为"🌐 Update translations via Co-op Translator"的 PR,分支为 update-translations,仅 add-paths: translations/ 与 translated_images/。

对贡献者的关键约束:translations/ 与 translated_images/ 是机器自动维护的产物目录,直接编辑会被下次流水线运行覆盖。因此贡献者应只修改根目录的源 Markdown 文件,翻译交给流水线。

五、部署流水线:GitHub Pages 的两套构建方案

仓库中存在两条部署相关的工作流,它们分工不同:

Deploy 工作流(deploy.yaml)

.github/workflows/deploy.yaml 的逻辑是:

  • 触发:推送 main 分支且 README.md 发生变化(paths: - README.md);
  • 步骤:检出仓库 → 设置 Node.js 16 → 将 README.md 通过 markdown 命令转换为内嵌的 index.html → 配置 Pages → 上传 artifact → 部署到 GitHub Pages;
  • 权限:contents: read(构建)/ pages: write + id-token: write(部署);
  • 并发控制:使用 concurrency: group: "pages", cancel-in-progress: true 取消排队中的冗余运行。

Jekyll GitHub Pages 工作流(jekyll-gh-pages.yml)

.github/workflows/jekyll-gh-pages.yml 是另一套方案:

  • 触发:推送默认分支 main,也支持 workflow_dispatch 手动触发;
  • 步骤:检出 → 配置 Pages → 用 jekyll-build-pages 以 source: ./、destination: ./_site 构建 → 上传 artifact → 部署;
  • 并发策略不同:同样使用 group: "pages",但 cancel-in-progress: false,即允许进行中的部署完成、不中途取消。

两套工作流共同展示了"文档仓库 + Pages 静态托管"的两种典型实现路径:轻量 README 直出与完整 Jekyll 站点构建。

六、Markdown 风格与内容规范

Markdown 约定

  • 使用标准 Markdown 语法;
  • 标题层级:# 主标题、## 小节、### 子节;
  • 列表:无序列表用 - 或 *,有序列表用 1.;
  • 链接:使用描述性文本;
  • 图片:存入 images/ 目录,使用描述性 alt 文本;
  • 代码块:使用三个反引号并尽可能标注语言标识。

图片引用规范

仓库内图片统一以相对路径引用。例如课程文件 1.1 The CIA triad and other key concepts.md 中引用了 images/1-1_placeholder.png 与 images/ciatriad.png。新增图片时同样放入根目录的 images/ 目录,提交内容时同步提交图片文件与课程文件。

新增课时的完整操作

# 1. 按命名规范创建新 Markdown 文件
touch "[Module].[Lesson] [Title].md"

# 2. 按模板结构补充内容
# 3. 更新 README.md 模块表,加入新条目
# 4. 更新模块概览表条目
# 5. 确保测验文件编号正确

# 6. 提交变更
git add "[Module].[Lesson] [Title].md" README.md
git commit -m "Add: [Module].[Lesson] - [Title]"
git push

更新既有内容

# 1. 编辑相关 Markdown 文件
# 2. 校验格式与链接
# 3. 使用描述性提交信息
git add "[Module].[Lesson] [Title].md"
git commit -m "Update: [Module].[Lesson] - [Brief description of changes]"
git push

七、Pull Request 与代码审查流程

提交前检查清单

  1. 内容审查:确保网络安全概念的准确性与清晰度;
  2. 格式:验证 Markdown 能正确渲染;
  3. 链接:测试所有内部与外部链接;
  4. 图片:确认图片可正常加载且带有描述性 alt 文本;
  5. 一致性:遵循既有内容结构与风格。

PR 标题规范

  • Add: [新内容描述]
  • Update: [模块/课时] - [简要描述]
  • Fix: [问题描述]
  • Docs: [文档变更说明]

必检项与审查流程

  • 内容准确性(人工审查);
  • Markdown 格式校验;
  • 链接校验;
  • 合入 main 分支前需确认翻译工作流完成(即翻译 PR 已就绪);
  • 至少一名维护者审查,重点把关安全概念的技术准确性、无障碍性与初学者友好度、以及厂商中立性。

八、测试与验证:文档项目的"测试"怎么做

作为文档项目,测试聚焦于内容质量而非代码逻辑:

  1. Markdown 渲染:用 Docsify 本地预览变更;
  2. 链接校验:手动逐条点击验证;
  3. 图片加载:确认所有图片正常显示;
  4. 翻译确认:验证文件被翻译工作流拾取(自动化);
  5. 无障碍:检查标题层级与 alt 文本。

提交前自检清单

  • [ ] Markdown 语法正确
  • [ ] 链接有效(尽量使用 HTTPS)
  • [ ] 图片有描述性 alt 文本
  • [ ] 内容初学者友好且准确
  • [ ] 保持厂商中立语言
  • [ ] 增删模块时同步更新 README.md
  • [ ] 文件命名符合约定

九、常见问题排查手册

AGENTS.md 提供了四类高频故障的定位路径,结合仓库源码可进一步缩小排查范围:

翻译不生效

  • 确认变更已推送到 main 分支(co-op-translator.yml 的触发条件即为 push 到 main);
  • 到 GitHub Actions 页面检查工作流运行状态;
  • 确认翻译工作流所需的 Secrets(AZURE_AI_SERVICE_API_KEY、AZURE_AI_SERVICE_ENDPOINT 等)已正确配置;
  • 牢记翻译是自动化的,不要手动编辑 translations/ 下的文件。

图片无法加载

  • 确认图片路径使用正斜杠:images/filename.png;
  • 确认图片文件已提交到仓库;
  • 文件名需精确匹配(大小写敏感);
  • 使用相对路径而非绝对 URL。

Docsify 不渲染

  • 确认根目录存在 index.html;
  • 确认 Docsify CDN 链接可访问;
  • 确认 Markdown 使用标准语法;
  • 检查浏览器控制台的 JavaScript 报错。

链接失效

  • 课程间交叉引用使用完整链接形式:https://github.com/microsoft/Security-101/blob/main/[file].md;
  • 在渲染后的视图中测试链接,而不仅是原始 Markdown 中。

十、安全注意事项与维护约定

安全红线

  • 内容中绝不出现密钥:不提交 API Key、密码或敏感数据(SECURITY.md 亦强调漏洞应通过 MSRC 流程而非公开 Issue 上报);
  • 链接验证:外部链接必须指向可信来源;
  • 图片内容:确认图片不含敏感信息;
  • 翻译凭据:翻译工作流使用 Azure AI 服务并依赖正确的认证配置(Secrets 注入,见 co-op-translator.yml)。

版本控制约定

  • main 分支受保护,所有变更须经 PR 审查;
  • 翻译文件为自动生成,禁止手动编辑;
  • 使用清晰、有意义的提交信息;
  • 定期任务包括:审查与合并社区贡献、随安全态势演进更新内容、监控翻译工作流错误、响应 Issue 与讨论、保持外部链接最新。

十一、给 AI Coding Agent 的核心操作准则

AGENTS.md 专为 AI 代理总结了操作性最强的 8 条准则,这也是本文的实践落脚点:

  1. 这是文档项目:优先保证内容质量而非代码质量;
  2. 不修改翻译文件:translations/ 是自动生成的,改动会被覆盖;
  3. 保留文件命名约定:文件名使用空格(如 1.1 The CIA triad and other key concepts.md);
  4. 同步更新 README.md:增删模块时保持模块表一致;
  5. 提交前本地测试:确保 Markdown 渲染正常;
  6. 遵循既有风格:保持初学者友好、厂商中立的口吻;
  7. 无需构建流程:本地开发用一个简单 HTTP 服务器即可;
  8. 尊重模块结构:保证每个模块的编号与组织一致。

结语

Security-101 是典型的"纯文档 + 自动化流水线"型开源仓库:内容生产只依赖 Markdown,质量保障依赖命名规范与人工审查,规模化能力则来自 Co-op Translator 的自动翻译和 GitHub Pages 的静态部署。对于 AI Coding Agent 而言,只要守住"只改根目录源文件、不碰翻译产物、遵循命名与 PR 规范"三条底线,就能以极低的学习成本安全地参与这门网络安全课程的贡献;对于学习者而言,理解这套结构也能帮助你更快地按模块检索、阅读和复用它 50+ 语言版本的课程内容。

登录后查看全文
Security-101