Security-101 AI Agent 协作指南:面向自动化贡献者的仓库结构与开发工作流全解析
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 使得站点内的相对链接在渲染时能正确解析,因此本地起一个静态服务器即可获得与线上一致的浏览体验。
修改内容的步骤
- 直接编辑根目录下的 Markdown 文件;
- 遵循
[module].[lesson] [Title].md命名约定; - 新增或删除模块时同步更新 README.md 的模块表;
- 图片放入
images/目录,并在正文中用相对路径引用; - 使用描述性 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;
- Azure AI Service:
- 提交方式:翻译完成后,用 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 与代码审查流程
提交前检查清单
- 内容审查:确保网络安全概念的准确性与清晰度;
- 格式:验证 Markdown 能正确渲染;
- 链接:测试所有内部与外部链接;
- 图片:确认图片可正常加载且带有描述性 alt 文本;
- 一致性:遵循既有内容结构与风格。
PR 标题规范
Add: [新内容描述]Update: [模块/课时] - [简要描述]Fix: [问题描述]Docs: [文档变更说明]
必检项与审查流程
- 内容准确性(人工审查);
- Markdown 格式校验;
- 链接校验;
- 合入
main分支前需确认翻译工作流完成(即翻译 PR 已就绪); - 至少一名维护者审查,重点把关安全概念的技术准确性、无障碍性与初学者友好度、以及厂商中立性。
八、测试与验证:文档项目的"测试"怎么做
作为文档项目,测试聚焦于内容质量而非代码逻辑:
- Markdown 渲染:用 Docsify 本地预览变更;
- 链接校验:手动逐条点击验证;
- 图片加载:确认所有图片正常显示;
- 翻译确认:验证文件被翻译工作流拾取(自动化);
- 无障碍:检查标题层级与 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 条准则,这也是本文的实践落脚点:
- 这是文档项目:优先保证内容质量而非代码质量;
- 不修改翻译文件:
translations/是自动生成的,改动会被覆盖; - 保留文件命名约定:文件名使用空格(如
1.1 The CIA triad and other key concepts.md); - 同步更新 README.md:增删模块时保持模块表一致;
- 提交前本地测试:确保 Markdown 渲染正常;
- 遵循既有风格:保持初学者友好、厂商中立的口吻;
- 无需构建流程:本地开发用一个简单 HTTP 服务器即可;
- 尊重模块结构:保证每个模块的编号与组织一致。
结语
Security-101 是典型的"纯文档 + 自动化流水线"型开源仓库:内容生产只依赖 Markdown,质量保障依赖命名规范与人工审查,规模化能力则来自 Co-op Translator 的自动翻译和 GitHub Pages 的静态部署。对于 AI Coding Agent 而言,只要守住"只改根目录源文件、不碰翻译产物、遵循命名与 PR 规范"三条底线,就能以极低的学习成本安全地参与这门网络安全课程的贡献;对于学习者而言,理解这套结构也能帮助你更快地按模块检索、阅读和复用它 50+ 语言版本的课程内容。