Security-101 仓库开发与协作指南:AI 编码 Agent 视角下的课程模块、自动化翻译与 CI/CD 工作流

原创2026-09-17 23:45:321,853 阅读
文章标签:网络安全教程文档

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;
  • 文件名使用空格而非下划线(沿用现有约定),且必须保持大小写精确。

修改内容的步骤

  1. 直接编辑根目录下的 Markdown 文件;
  2. 遵循 [module].[lesson] [Title].md 命名约定;
  3. 若增删模块,同步更新 README.md 中的模块表格;
  4. 新图片放入 images/ 目录;
  5. 在 Markdown 中以相对路径引用图片,例如: <a href="https://link.gitcode.com/i/da35ee90633781a255c297e8d86c6f08" target="_blank">![描述性 alt 文本](https://raw.gitcode.com/GitHub_Trending/se/Security-101/raw/b0a31ff7ebb9983d24bcdc6a38a4d008e6e89d0c/images/banner.jpg?utm_source=gitcode_repo_files)</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;
  • 提交流程:翻译完成后,通过 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 规范

提交前检查

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

PR 标题格式

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

必需检查项

  • 内容准确性(人工复核);
  • Markdown 格式校验;
  • 链接验证;
  • 翻译工作流完成(涉及 main 分支合并时)。

评审流程

  1. 至少需要一名维护者评审;
  2. 评审重点为安全概念的技术准确性;
  3. 验证可访问性与初学者友好度;
  4. 确保厂商中立性得到保持。

测试与验证策略

由于是文档项目,测试聚焦于内容正确性与渲染质量,而非单元测试:

  1. Markdown 渲染:用 Docsify 本地查看变更效果;
  2. 链接验证:手动点击所有链接;
  3. 图片加载:确认所有图片正确显示;
  4. 翻译识别:确认新文件能被翻译工作流自动拾取(自动化);
  5. 可访问性:保证标题层级合理、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 的协作框架——尊重翻译文件、保持命名与结构一致、在提交前本地验证——就能安全、高效地参与这个面向全球初学者的网络安全课程建设。

登录后查看全文
Security-101