Security-101 仓库开发与协作指南:AI 编码 Agent 视角下的课程模块、自动化翻译与 CI/CD 工作流
Security-101 仓库开发与协作指南:AI 编码 Agent 视角下的课程模块、自动化翻译与 CI/CD 工作流
Security-101 是一个面向初学者的网络安全课程仓库,全部内容以 Markdown 文档形式组织,配合 Docsify 渲染为静态站点,并通过 Co-op Translator 自动维护 50+ 语言的翻译。本篇指南以仓库根目录的 AGENTS.md(及其匈牙利语译本 translations/hu/AGENTS.md)为骨架,结合真实工作流配置与目录结构,系统讲解如何理解、本地预览、修改、测试和贡献这个文档型项目,同时给出 AI 编码 Agent 在该类仓库中工作的完整行动准则。
项目概览:一个文档驱动的入门级网络安全课程
Security-101 是微软创建的网络安全入门课程,核心定位是"厂商中立(vendor-agnostic)、面向初学者、小课时可完成":
- 全部教学内容以 Markdown 文件承载,无任何编译依赖,基础内容不需要构建工具或包管理器;
- 课程按结构化模块组织,共 8 大模块,每个模块内含若干子课程(lesson);
- 每节课建议 30-60 分钟完成,并以一个"模块末测验"(End of module quiz)收尾;
- 课程不教授具体安全工具的使用、不涉及"黑客/红队"攻防内容、也不讲解特定合规标准,只聚焦底层安全概念。
从 README.md 的模块总览表可以看到完整的 8 模块设计:基础安全概念(CIA 三元组、常见威胁、风险管理、安全实践与文档、零信任、共享责任模型)、身份与访问管理(IAM)、网络安全、安全运营(SecOps)、应用安全(AppSec)、基础设施安全、数据安全、AI 安全,每个模块均以测验文件结束。
核心技术栈
| 技术 | 用途 |
|---|---|
| Markdown | 课程内容的唯一载体 |
| Docsify | 静态站点渲染(无需构建步骤) |
| GitHub Pages | 站点托管 |
| Co-op Translator | 多语言自动翻译(50+ 语言) |
| GitHub Actions | CI/CD 自动化(翻译、部署) |
根目录 index.html 中的 Docsify 配置印证了站点架构:通过 CDN 加载 docsify.min.js,站点名为 "Cybersecurity for Beginners",并开启了 relativePath: true,这正是仓库内所有 Markdown 相对链接能够跨文件解析的原因。
仓库目录结构全解析
根据 AGENTS.md 的目录树,结合当前仓库实际内容,根目录结构如下:
/
├── README.md # 主入口,课程总览与模块表
├── index.html # Docsify 站点入口
├── [1-8].[1-4] *.md # 课程模块与子课程(如 "1.1 The CIA triad...")
├── CODE_OF_CONDUCT.md # 社区行为准则
├── SECURITY.md # 安全策略(漏洞报告流程)
├── SUPPORT.md # 支持信息
├── LICENSE # MIT 许可证
├── AGENTS.md # 面向贡献者与 AI Agent 的协作指南
├── images/ # 课程插图资源
├── translated_images/ # 各语言翻译后的图片资源
├── translations/ # 50+ 语言的翻译版本
└── .github/
├── workflows/
│ ├── co-op-translator.yml # 自动翻译工作流
│ ├── deploy.yaml # GitHub Pages 部署
│ └── jekyll-gh-pages.yml # Jekyll 站点生成
└── ISSUE_TEMPLATE/ # Issue 模板
实际仓库中 translations/ 目录包含 1998 个 Markdown 文件,每个语言一个子目录(如 translations/hu/、translations/zh/),对应课程文件与 README 均有翻译版本;translated_images/ 则按"原图名 + 内容哈希 + 语言后缀"命名,例如匈牙利语版课程图 translated_images/1-1_placeholder.5743591289ea76087b78301a315f244c665d5266d895538c9d1a52b1f0d08603.hu.png。
本地环境搭建:零依赖即可开始
这是一个纯文档项目,不需要安装任何依赖或执行构建命令。准备工作只需克隆仓库并用任意方式预览:
# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/se/Security-101
cd Security-101
# 方式一:直接用任意 Markdown 阅读器查看
# 方式二:用 Python 内置 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 编辑器中直接查看源文件
由于 Docsify 通过浏览器按需加载 Markdown,index.html 是站点渲染的关键入口;只要根目录存在 index.html 且 Docsify CDN 可访问,python -m http.server 即可完成完整预览。
课程内容结构:8 大模块与命名约定
模块按顺序编号,每个模块由若干子课程和测验文件构成:
| 模块 | 主题 | 课程编号 |
|---|---|---|
| 模块 1 | 基础安全概念 | 1.1 - 1.7 |
| 模块 2 | 身份与访问管理(IAM) | 2.1 - 2.4 |
| 模块 3 | 网络安全 | 3.1 - 3.4 |
| 模块 4 | 安全运营(SecOps) | 4.1 - 4.4 |
| 模块 5 | 应用安全(AppSec) | 5.1 - 5.3 |
| 模块 6 | 基础设施安全 | 6.1 - 6.3 |
| 模块 7 | 数据安全 | 7.1 - 7.3 |
| 模块 8 | AI 安全 | 8.1 - 8.4 |
每个模块以测验文件收尾,例如 1.7 End of module quiz.md。当前仓库根目录的 30 个课程文件与 README 模块表一一对应,这也印证了"课程表与文件系统保持同步"的维护要求。
文件命名规范
- 课程文件格式:
[模块].[课号] [标题].md,例如1.1 The CIA triad and other key concepts.md; - 测验文件格式:
[模块].[末尾编号] End of module quiz.md; - 文件名使用空格而非下划线(沿用现有约定),且必须保持大小写精确。
修改内容的步骤
- 直接编辑根目录下的 Markdown 文件;
- 遵循
[module].[lesson] [Title].md命名约定; - 若增删模块,同步更新 README.md 中的模块表格;
- 新图片放入
images/目录; - 在 Markdown 中以相对路径引用图片,例如:
<a href="https://link.gitcode.com/i/da35ee90633781a255c297e8d86c6f08" target="_blank"></a>
多语言翻译工作流:Co-op Translator 的自动化机制
这是本项目最具特色的工程实践:翻译完全自动化,禁止人工编辑翻译文件。
工作流程
- 每当变更推送到
main分支,Co-op Translator GitHub Action 自动触发; - 工作流将新增/修改的 Markdown 文件翻译为 50+ 语言;
- 翻译产物存放在
translations/[language_code]/目录(如translations/hu/); - 翻译元数据以 YAML frontmatter 形式保留在文件头部。
以 translations/hu/AGENTS.md 为例,其文件头即为:
CO_OP_TRANSLATOR_METADATA:
{
"original_hash": "913da05fee7fb78699c0447cf6d8aa10",
"translation_date": "2025-10-12T09:42:57+00:00",
"source_file": "AGENTS.md",
"language_code": "hu"
}
这直接印证了 AGENTS 文档中"翻译元数据保留在 YAML frontmatter"的描述——original_hash 用于追踪源文件内容变化,是增量翻译的关键。
支持的语言
阿拉伯语、孟加拉语、保加利亚语、缅甸语、简体/繁体中文、克罗地亚语、捷克语、丹麦语、荷兰语、爱沙尼亚语、芬兰语、法语、德语、希腊语、希伯来语、印地语、匈牙利语、印尼语、意大利语、日语、韩语、立陶宛语、马来语、马拉地语、尼泊尔语、挪威语、波斯语、波兰语、葡萄牙语、旁遮普语、罗马尼亚语、俄语、塞尔维亚语、斯洛伐克语、斯洛文尼亚语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰米尔语、泰语、土耳其语、乌克兰语、乌尔都语、越南语等。README 的语言表同样罗列了这些入口(如 translations/hu/README.md)。
重要规则:不要手动编辑 translations/ 下的任何文件,它们会被自动化工作流覆盖。
GitHub Actions:三条自动化流水线
在 .github/workflows/ 目录下共有三个工作流,从源码可见其精确配置。
Co-op Translator(co-op-translator.yml)
- 触发条件:推送到
main分支; - 运行环境:
ubuntu-latest,Python 3.10; - 关键步骤:
pip install co-op-translator后执行translate -l "all" -y(默认全语言批量翻译); - 需要的环境变量(Secrets):
- Azure AI 服务凭据:
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 服务凭据:
- 提交流程:翻译完成后,通过 GitHub App Token(
GH_APP_ID、GH_APP_PRIVATE_KEY)以机器人身份自动创建 Pull Request,目标分支update-translations,仅提交translations/与translated_images/目录的变更。
工作流注释中还给出了分批翻译建议:单批超过 29 个文件时应拆批执行,因为 GitHub Runner 单次最长运行时间为 6 小时。
部署(deploy.yaml)
- 触发条件:推送到
main分支且README.md发生变更; - 核心步骤:在 Node 16 环境下,将 README.md 通过
markdown命令转换为 HTML 后写入index.html,再经actions/deploy-pages发布到 GitHub Pages; - 输出:更新 GitHub Pages 站点。
Jekyll GitHub Pages(jekyll-gh-pages.yml)
- 触发条件:推送到
main分支,并支持workflow_dispatch手动触发; - 核心步骤:使用 Jekyll 构建站点(
source: ./,输出到_site)后上传部署产物并发布; - 并发控制:同一时刻仅允许一个部署运行,且不取消进行中的生产部署。
代码风格与内容规范
Markdown 约定
- 使用标准 Markdown 语法;
- 标题层级:
#主标题、##章节、###子章节; - 列表:无序列表用
-或*,有序列表用1.; - 跨课程交叉引用使用带描述性文本的完整链接;
- 图片存放在
images/目录,必须携带描述性 alt 文本; - 代码块使用带语言标识的三反引号。
内容规范
- 课程保持聚焦与精炼(每课 30-60 分钟阅读量);
- 使用清晰、对初学者友好的语言;
- 避免厂商特定工具的操作说明——课程必须保持厂商中立;
- 每个模块开头列出学习目标;
- 内容定位是教育性而非宣传性。
新增课程的完整流程
# 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. 将图片加入 images/ 目录
cp new-image.png images/
# 2. 在 Markdown 中引用(相对路径)
# 描述性 alt 文本
# 3. 同时提交内容与图片
git add "images/new-image.png" "[Module].[Lesson] [Title].md"
git commit -m "Add: Image for [description]"
git push
注意:翻译工作流会基于 images/ 中的原图生成各语言版本到 translated_images/,图片文件名由"原图名 + 内容哈希 + 语言码"构成。
Pull Request 规范
提交前检查
- 内容审核:确保网络安全概念准确且易懂;
- 格式:确认 Markdown 渲染正常;
- 链接:测试所有内部与外部链接;
- 图片:确保所有图片可加载且有描述性 alt 文本;
- 一致性:遵循现有内容结构与风格。
PR 标题格式
Add: [新内容描述]Update: [模块/课程] - [简短描述]Fix: [问题描述]Docs: [文档变更]
必需检查项
- 内容准确性(人工复核);
- Markdown 格式校验;
- 链接验证;
- 翻译工作流完成(涉及
main分支合并时)。
评审流程
- 至少需要一名维护者评审;
- 评审重点为安全概念的技术准确性;
- 验证可访问性与初学者友好度;
- 确保厂商中立性得到保持。
测试与验证策略
由于是文档项目,测试聚焦于内容正确性与渲染质量,而非单元测试:
- Markdown 渲染:用 Docsify 本地查看变更效果;
- 链接验证:手动点击所有链接;
- 图片加载:确认所有图片正确显示;
- 翻译识别:确认新文件能被翻译工作流自动拾取(自动化);
- 可访问性:保证标题层级合理、alt 文本完整。
本地预览验证命令:
python -m http.server 8000
# 访问 http://localhost:8000
# 点击导航验证所有链接
# 检查图片是否正确加载
# 确认 Markdown 格式渲染无误
提交前自检清单
- [ ] Markdown 文件语法正确
- [ ] 所有链接有效,尽量使用 HTTPS
- [ ] 图片有描述性 alt 文本
- [ ] 内容对初学者友好且准确
- [ ] 保持厂商中立语言
- [ ] 增删模块时同步更新 README.md
- [ ] 文件名符合命名约定
安全注意事项
- 内容中严禁出现机密信息:绝不提交 API 密钥、密码或敏感数据(翻译工作流的凭据一律通过 GitHub Secrets 注入,见 co-op-translator.yml);
- 链接验证:确保所有外部链接指向可信来源;
- 图片内容:检查图片不包含敏感信息;
- 翻译工作流:Azure AI 服务须使用正确认证;
- 漏洞报告:遵循 SECURITY.md 中描述的漏洞报告流程。
常见问题与故障排查
翻译不生效
- 确认变更已推送到
main分支; - 在 GitHub Actions 页面检查工作流运行状态;
- 检查翻译工作流所需的 Secrets 是否已正确配置;
- 翻译是自动进行的,不要手动编辑翻译文件。
图片不加载
- 确认图片路径使用正斜杠:
images/filename.png; - 检查图片文件是否已提交到仓库;
- 确认图片文件名完全匹配(区分大小写);
- 使用相对路径,而非绝对 URL。
Docsify 不渲染
- 检查根目录是否存在 index.html;
- 确认 Docsify CDN 链接可访问;
- 确认 Markdown 文件使用标准语法;
- 查看浏览器控制台中的 JavaScript 错误。
链接失效
- 课程间交叉引用使用完整链接;
- 在渲染后的视图(而非原始 Markdown)中测试链接。
项目维护与版本控制
main分支受保护,所有变更必须经过 Pull Request 评审;- 常规维护任务包括:审查合并社区贡献、随安全形势更新内容、监控翻译工作流错误、回复 issue 与讨论、保持外部链接更新;
- 翻译文件为自动生成产物,禁止手动编辑;
- 使用语义清晰的 commit message。
给 AI 编码 Agent 的行动要点
AGENTS.md 专门为 AI 编码 Agent 总结了操作准则,这也是在文档型仓库中协作的最简行动清单:
- 这是文档项目——专注内容质量而非代码;
- 不要修改翻译文件——它们由工作流自动生成;
- 遵守文件命名约定——沿用现有模式使用空格分隔文件名;
- 增删模块时更新 README.md——保持模块表同步;
- 提交 PR 前本地测试——确保 Markdown 正确渲染;
- 沿用现有内容风格——保持初学者友好、厂商中立的语气;
- 无需构建流程——本地开发一个简单 HTTP 服务器即可;
- 尊重模块结构——每个模块都有一致的编号与组织方式。
对 AI Agent 而言,最核心的三条红线是:翻译文件只读、命名规范不可破坏、README 模块表必须与文件系统保持同步。
结语
Security-101 展示了文档型开源课程项目的完整工程实践:零依赖的 Docsify 渲染架构、模块化的内容组织与命名约定、基于 Co-op Translator 的全自动多语言翻译流水线,以及围绕"内容质量"构建的测试、评审与安全规范。无论是人类贡献者还是 AI 编码 Agent,只要遵循 AGENTS.md 的协作框架——尊重翻译文件、保持命名与结构一致、在提交前本地验证——就能安全、高效地参与这个面向全球初学者的网络安全课程建设。