个性化 Agent Swarm 评测指南：Personalized Agent Swarms 增强助手 10 维评分标准全解
2026/9/14 4:51:32
Prowler 文档站点架构与本地开发实战：基于 Mintlify 的 Prowler 官方文档工程指南
【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler
本文基于 Prowler 仓库内的docs/README.md展开，讲清官方文档站点的三层内容架构（Getting Started / User Guide / Developer Guide）如何组织在docs/目录中，并覆盖文档本地预览（Mintlify CLImint dev）、发布流程、写作风格规范（docs/AGENTS.md）与常见问题排查。读完后，你将能够独立完成文档页面的新增、本地调试、导航注册与发布验证。
一、Prowler 文档站点的定位与目录布局
docs/README.md开宗明义：该目录承载的是 Prowler 开源文档站点，由 Mintlify 驱动。理解这一点的意义在于——整个docs/目录同时是内容源与站点配置，而不是单纯的 Markdown 文件夹。
从仓库实际目录结构看，docs/顶层包含：
| 路径 | 作用 |
|---|---|
| docs/docs.json | Mintlify 站点配置：主题、导航树、页眉页脚、重定向规则 |
| docs/introduction.mdx | 文档首页（H1 入口） |
| docs/getting-started/ | 入门内容：产品族、安装、基础用法、方案对比 |
| docs/user-guide/ | 用户指南：Prowler Cloud、CLI、Provider、合规 |
| docs/developer-guide/ | 开发者指南：Provider/Check 开发、测试、调试 |
| docs/security/ | 安全合规说明（加密、数据区域、网络、软件安全） |
| docs/snippets/ | 可复用 MDX 组件（VersionBadge、AppliesTo 等） |
| docs/style.css | 站点自定义样式（如侧边栏 Cloud 标记） |
| docs/images/ | 文档配图资源 |
| docs/AGENTS.md | 文档风格指南（品牌语气、命名规范、排版规则） |
| docs/.mintlifyignore | Mintlify 构建时忽略的文件（如AGENTS.md） |
README 中描述的三层结构（Getting Started / User Guide / Developer Guide）与docs.json中的navigation.tabs一一对应，但实际站点比 README 的概括更细：从 docs/docs.json 可以看到，导航树共定义了 8 个顶级 Tab——Getting Started、Guides、Developer Guide、Security、Support、Troubleshooting、Changelog，外加一个外链About Us。也就是说，README 的三段式描述是面向贡献者的"概念地图"，而真正决定页面出现在哪里的是docs.json的 Tab/Group 嵌套结构。
导航配置采用 Mintlify 的标准层级：navigation.tabs[] -> groups[] -> pages[]，pages中每个字符串对应docs/下去掉.mdx后缀的文件路径（例如"user-guide/providers/aws/authentication"对应docs/user-guide/providers/aws/authentication.mdx）。页面还可以是嵌套对象，实现无限层级的分组。
站点级配置要点
除导航外，docs/docs.json 还集中管理了若干影响全站行为的配置，值得在修改文档前了解：
- 品牌与外观：
theme: "mint"、主色#10B981（品牌绿）、明暗两套 Logo（/images/prowler-logo-black.png/prowler-logo-white.png）； - 全局横幅（
banner）：当前用于公告产品更名——"Prowler App 现更名为 Prowler Local Server，Prowler Enterprise 现更名为 Prowler Private Cloud"，并设为dismissible: false（不可关闭）； - Markdown 指令（
markdown.instructions）：向 LLM/搜索回答注入产品命名规范，确保新旧产品名的准确使用； - 反馈组件（
feedback）：开启点赞评分、"建议编辑"与"提 Issue"； - 重定向表（
redirects）：迁移历史 URL 到新路径，例如/contact -> /support、/user-guide/tutorials/prowler-app-alerts -> /user-guide/tutorials/prowler-alerts，以及一大批旧 Read the Docs 风格路径（/projects/prowler-open-source/en/latest/...）到现行结构的通配重定向（:slug*）。新增或移动页面时，应参照此模式补充重定向，避免旧链接 404。
二、本地开发：安装 CLI 并启动预览
docs/README.md给出的本地开发流程分三步，这是文档贡献者最核心的实操路径：
1. 全局安装锁定版本的 Mintlify CLI
npm install --global mint@4.2.689注意 README 特意要求安装经过审阅的具体版本（4.2.689）而非latest，目的是保证本地渲染行为与 CI/生产构建一致，避免版本漂移导致的排版差异。
2. 在文档根目录启动开发服务器
mint dev该命令必须在包含docs.json的目录（即本仓库的docs/）下执行。Mintlify 以该文件作为站点定义的入口，解析导航树、加载 MDX 页面并启动热更新服务器。
3. 访问本地预览
启动后在浏览器打开http://localhost:3000，即可看到与线上一致的文档站点，支持 MDX 修改后的即时热重载。
配套细节：.mintlifyignore与 CI 校验
- docs/.mintlifyignore 将
AGENTS.md、.claude/、docs/scripts/等目录排除在构建之外。这意味着：写给 AI 辅助工具看的风格指南（docs/AGENTS.md）不会成为线上页面，也不会被 broken-links 检查当作导航缺失项。若你在docs/下新增了非页面文件，需要考虑是否加入该忽略列表。 - 仓库 CI 中对文档目录有独立的 PR 校验：.github/workflows/docs-check-provider-cards.yml 在
docs/user-guide/providers/**/getting-started-*.mdx、docs/snippets/provider-cards.mdx或 docs/scripts/generate_provider_cards.py 发生变化时，自动校验 Provider 卡片 snippet 与源文件的一致性。这提示我们：provider 的 getting-started 页面并非纯手工内容，其卡片部分由脚本生成，修改页面时需注意与该 workflow 的约定。
三、可复用 MDX 组件：VersionBadge 与 AppliesTo
文档写作规范（见下文第四节）要求为新功能标注引入版本，其实现载体位于docs/snippets/。以 docs/snippets/version-badge.mdx 为例，VersionBadge是一个纯 MDX React 组件：接收versionprop，渲染一个指向对应 GitHub Release 的Added in: x.y.z徽章。在页面中的用法：
import { VersionBadge } from "/snippets/version-badge.mdx" ## New Feature Name <VersionBadge version="4.5.0" /> Description of the feature...规范要求：版本号使用语义化格式且不带v前缀；徽章单独成行、紧跟小节标题之后，其后空一行再写正文。
另一个常用组件AppliesTo（docs/snippets/applies-to.mdx）用于声明某篇指南适用于哪些产品（Prowler Cloud / Prowler Private Cloud / Prowler Local Server），默认覆盖全部三者，可通过productsprop 收窄范围。docs/AGENTS.md还规定了二者与"Cloud 订阅标记"（绿色云图标 SVG，经 docs/style.css 的::after规则注入侧边栏）的互斥/叠加关系：带订阅横幅的页面不需要再挂 AppliesTo；侧边栏标记通过style.css中按页面路径的li[id="..."] a span::after选择器添加。
四、写作规范：docs/AGENTS.md风格指南
docs/README.md的 "Documentation Guidelines" 一节要求贡献者遵循.claude目录中的风格指南；在当前仓库中，这份指南的实体内容位于 docs/AGENTS.md，它是一份相当完整的品牌语气与排版手册，核心规则包括：
- 产品命名（Naming Conventions）：Prowler 功能名按专有名词处理；产品分两个家族——Prowler Products（Prowler Cloud、Prowler Private Cloud、Prowler Hub、Prowler Lighthouse AI、Prowler MCP）与 Open Source 项目（Prowler CLI、Prowler Local Server、Prowler Local Dashboard、Prowler SDK）。旧名 Prowler App / Prowler Enterprise 仅允许出现在产品族映射页与全站横幅中，新文档禁止使用。
- 无偏沟通：避免性别化代词与名词（如
Businessman -> businessperson）、避免军事化措辞（kill chain -> cyberattack chain）、明确 "safety"（个体层面）与 "security"（宏观层面）的区分。 - 动词优于名词结构：优先 "The report was successfully created" 而非 "The creation of the report was successful"，更短且意图前置，也利于 SEO 关键词布局。
- 标题大小写：章节标题使用 Title Case；缩写展开形式不逐词大写（
CTI (cyber threat intelligence)，但保留AWS (Amazon Web Services)）。 - 链接与 URL：URL 中用连字符而非下划线（
this-is-an-URL），因为下划线会被视为词边界。 - 警示分级：Note（低）/ Warning（中）/ Danger（高），每个警示必须写明忽略后果并尽量给出补救路径。
- 交互动词：桌面用 Click / Double-click / Right-click，触屏用 Tap / Swipe，且给出统一术语表。
这份指南同时面向人类作者与 AI 辅助写作流程（文件名AGENTS.md即面向 Agent 的说明），配合docs.json中注入的markdown.instructions，构成对文档一致性从"写作"到"渲染"两端的双重约束。
五、发布流程与故障排查
发布（Publishing Changes）
按docs/README.md：推送到main分支的变更会通过 Mintlify 的 GitHub 集成自动部署到生产环境。对贡献者而言这意味着：
- 文档 PR 合并即上线，本地预览（
mint dev）是唯一"预检"手段，合并前务必完整走一遍预览； - 移动/重命名页面时，记得在 docs/docs.json 的
redirects数组中登记旧路径映射，沿用现有的source/destination结构（支持:slug*通配符）； - 新增页面必须同时更新
navigation中的对应pages列表，否则页面存在但不出现在侧边栏（这也正是官方 Troubleshooting 中 404 项的第二条原因）。
故障排查（Troubleshooting）
README 给出两条官方排查路径，可结合仓库结构进一步落地：
本地开发服务器起不来—— 执行
mint update更新 CLI 至最新版本后重试；若更新版本行为异常，回退到 README 指定的锁定版本4.2.689以对齐生产构建。某页面 404—— 逐项核对两点：
- 执行
mint dev的目录中是否存在合法的docs.json（即是否位于仓库的docs/下）； - 该页面的相对路径（不含
.mdx后缀）是否已正确写入docs.json的 navigation。
排查时可以 grep 导航配置确认注册状态，例如在
docs/下搜索目标页面名；若页面文件存在但未 404 也未出现在导航，基本可判定是导航未注册。- 执行
六、贡献文档的完整工作流小结
综合docs/README.md与仓库证据，一次完整的文档变更流程为：
- 定位归属：根据内容类型确定目录（入门 ->
docs/getting-started/，功能教程/Provider/合规 ->docs/user-guide/，开发 ->docs/developer-guide/，安全 ->docs/security/）； - 编写页面：使用 MDX 语法；为新功能加
VersionBadge，跨产品指南加AppliesTo；文案遵循 docs/AGENTS.md 的命名与语气规则； - 注册导航：在 docs/docs.json 的对应 Tab/Group 中加入页面路径；如需替换旧路径，追加
redirects条目； - 本地验证：
npm install --global mint@4.2.689后在docs/下mint dev，访问http://localhost:3000检查渲染、侧边栏标记与重定向； - CI 校验：涉及 provider getting-started 页面时注意 docs-check-provider-cards workflow 的卡片一致性检查；
- 合并发布：推送到
main后由 Mintlify 自动部署。
这套"README 定流程、docs.json定结构、AGENTS.md定风格、CI workflow 守一致性"的文档工程模式，是 Prowler 官方文档能长期保持多产品、多 Provider 内容规模下结构清晰的关键。
【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考