尧图网页设计 
Agent Governance Toolkit 文档站写作规范与质量保障体系实战指南【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit导读本文档讲解 Agent Governance Toolkit 仓库中docs/文档树所对应的写作规范Coding Agent Instructions与配套质量工具链包括文档编写约定、内容边界、必需 frontmatter 元数据以及由Docs QualityCI 工作流强制执行的相对链接校验与 frontmatter 校验两个严格检查。读完本文你将掌握如何为该项目正确新增、修订文档页面如何在本地运行scripts/docs/check_links.py与scripts/docs/check_frontmatter.py并理解链接校验器、frontmatter 校验器的底层实现原理与测试覆盖从而在人工或 AI Agent 协作场景下写出可发布、可检索、不会破坏 CI 的技术文档。一、文档站定位docs/ 树承载什么在 Agent Governance Toolkit 仓库中docs/目录驱动着整个已发布文档站点其内容覆盖参考材料、教程、架构文档、威胁建模、合规内容、包页面与集成指南。按照 docs/AGENTS.md 的定义该目录是一个有机整体各子目录职责明确路径用途docs/index.md文档首页与顶层导航docs/packages/各软件包的落地页与包专属文档docs/tutorials/分步操作指南docs/integrations/外部集成指南docs/security/威胁模型、OWASP 与安全指导mkdocs.yml站点导航与构建配置站点构建基于 MkDocs Material 主题mkdocs.yml 中通过docs_dir: docs指定文档源目录并定义了完整的nav导航树涵盖 Getting Started、Packages、Tutorials、Deployment、Security、Compliance、Specifications、Architecture Decisions、Reference 等一级分区。这意味着新增文档页时除了文件本身还需要在mkdocs.yml的nav中登记才能出现在站点导航中同时也要注意exclude_docs与not_in_nav的排除规则详见后文发布范围控制一节。二、文档编写约定七条核心准则docs/AGENTS.md 明确规定了文档编写的七条约定它们是所有文档变更无论由人还是由编码 Agent 发起必须遵守的纪律准确诚实Be precise and honest除非仓库中确实包含该功能否则不得声称功能已发布。这要求写作者以源码、配置和测试为事实依据禁止把规划中的能力写成已交付能力。优先更新而非复制更倾向于更新既有页面而不是创建一个近似重复的新页面。这控制了文档膨胀避免同一概念多份文档互相漂移。使用仓库相对链接文档内链接必须是从当前文档位置出发即可工作的仓库相对路径。同时注意本文档所规定的是编辑期的相对路径书写方式在最终发布的站点上由 MkDocs 统一解析。语气统一与技术、直接、以证据为基础的既有语气保持一致不使用营销腔。名称对齐包名、CLI 命令与安装片段必须与实际仓库保持一致不得凭空杜撰命令或版本。仓库布局规范在描述仓库结构时将仓库根目录下独立的语言 SDK 视为受支持的一等模式first-party pattern。具体规范为以 agent-governance-python/ 作为 Python 包的规范路径以 agent-governance-dotnet/ 作为 .NET 的规范路径以 agent-governance-golang/ 作为对应的同级模式Go 包。 同理仓库中还存在 agent-governance-typescript/ 与 agent-governance-rust/ 等平级 SDK 目录写作时应遵守这一独立目录承载语言 SDK的约定而不是把它们描述为docs/packages/下的内嵌组件。第三方集成分类在说明第三方集成时必须讲清楚它们是示例examples、适配器adapters还是受维护的一等集成面maintained first-party surfaces不得模糊其支持层级。三、内容边界四条红线为了保证文档的可靠性与可维护性docs/AGENTS.md 划定了四条不能逾越的内容边界不引入无来源的主张不得在没有出处的情况下引入新的生态论断、基准测试数据或采用数量。这一点与事实准确与证据边界原则一致——性能数字、用户量、兼容性矩阵等都必须有仓库内或可靠公开资料支撑。翻译文档需显式请求除非被明确要求否则不新增翻译文档始终先保证英文源页面正确。仓库中已有的 i18n 目录docs/i18n/按此规则维护。不隐藏限制如果某行为是部分实现或实验性的必须明确说明禁止把半成品写成稳定功能。避免大段复制厂商文档对于第三方厂商文档应摘要并注明出处而不是成块搬运。这些边界同时约束了文档最小完备性宁可明确标注实验性也不可夸大能力这与 docs/LIMITATIONS.md 的整体立场一致。四、代码变更触发文档义务当仓库代码发生变化时docs/AGENTS.md 要求文档随之跟进具体场景包括公开 API 变更应同步更新最近的包页面或教程。例如 TypeScript SDK、Rust crate、Go module、Python 包等任一公开接口变化都应找到对应包页docs/packages/或教程docs/tutorials/进行更新。新增示例新示例通常至少应更新一次文档可发现性即在教程或包页中登记入口确保用户能找到它。安全敏感变更应复审 docs/security/ 目录及 docs/security/threat-model.md判断威胁模型是否需要同步调整。五、验证要求与必需 frontmatter5.1 通用验证要求每次文档变更提交前都应检查链接、文件路径、围栏代码块fenced code blocks是否合法有效标题与页面名称保持稳定除非是有意重命名。标题稳定性对检索和引用至关重要搜索引擎索引、外部链接、GitHub-style 锚点都依赖稳定的标题频繁改名会破坏既有引用。5.2 必需 frontmatter新建和编辑的文档页都应包含以下 YAML frontmatter 头--- title: Page Title last_reviewed: 2026-07-15 # ISO date, YYYY-MM-DD owner: agt-maintainers # team or maintainer handle ---字段语义字段含义约束title页面标题必填缺失即 CI 失败last_reviewed新鲜度信号必须为YYYY-MM-DD格式的合法 ISO-8601 日历日期凡有实质修订就应递增更新owner页面所有者团队或维护者标识如agt-maintainers其中last_reviewed是新鲜度信号freshness signal只要页面经过有意义的修订就应更新该日期帮助维护者识别长期未复审的页面。六、Docs Quality CI 工作流Docs Quality工作流.github/workflows/docs-quality.yml在每一个触及 Markdown 的 PR 上运行由三个 job 组成Job校验内容执行命令links相对链接校验严格坏链即失败python scripts/docs/check_links.py --root .frontmatterfrontmatter 校验严格缺失 title/复审日期/owner 即失败python scripts/docs/check_frontmatter.py --root . --strictunit-tests文档工具链的单元测试pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q触发条件是 PR 变更以下任一路径**/*.md、mkdocs.yml、scripts/docs/**、scripts/tests/test_docs_check_*.py、以及工作流自身文件。运行环境为ubuntu-latest Python 3.11并使用固定版本如actions/checkoutv7.0.1、actions/setup-pythonv7.0.0、pytest8.3.3以保证供应链可复现。七、链接校验器 check_links.py 原理与使用7.1 本地运行在提交 PR 之前于仓库根目录本地执行python scripts/docs/check_links.py也可以只检查特定文件、以 JSON 输出或切换校验模式# 只检查单个文档 python scripts/docs/check_links.py docs/security/threat-model.md # 以 JSON 输出机器可读报告 python scripts/docs/check_links.py --root . --json # 切换到 MkDocs 风格严格模式目录目标必须包含 index.md python scripts/docs/check_links.py --require-directory-index退出码约定0表示无坏链1表示检测到坏链2表示用法/调用错误。7.2 解析能力能识别哪些链接从 scripts/docs/check_links.py 源码看校验器具备一套严谨的 Markdown 解析管线内联链接text通过专门的正则提取并排除图片要求前面没有!。引用式链接同时支持引用定义[label]: target与引用使用[text][label]并只在使用处校验避免同一目标被重复计数。代码块剥离_strip_code_blocks会把 或 ~~~ 围栏代码块的内容替换为空白保持行号稳定这样代码示例中的链接不会被误报为坏链同时_strip_inline_code_spans处理行内代码片段两者组合后才是链接提取的输入文本。正则安全链接正则有意识地排除反斜杠歧义规避了 CodeQLpy/redos指数回溯告警适合在 CI 中高频运行。7.3 校验规则什么算坏链validate_link实现了如下判定逻辑页内锚点#anchor针对源文件自身的标题锚点校验找不到即报错。外部链接http、https、mailto、tel、ftp、ftps及//协议相对 URL不做网络校验直接跳过。仓库根限制目标解析后必须位于仓库根目录内解析到根外的目标例如../../../etc/hosts直接判定为坏链——这一设计防止了链接校验在任意运行环境下意外通过。目录目标GitHub 会把目录渲染为文件夹视图因此只要目录存在即接受若目录下有index.md则解析到该文件--require-directory-index开启后无index.md的目录目标会被判为坏链对应 MkDocs 严格模式。锚点校验目标为.md文件且带锚点时会用标题 slug 集合校验目标文件内是否存在该锚点。标题锚点的 slug 化规则_slugify_heading也值得注意小写化、去除 Markdown 格式、空格转连字符、仅保留字母数字与-/_并压缩连续连字符。因此## Approach 1: max_tool_calls in YAML对应的锚点是approach-1-max_tool_calls-in-yaml。7.4 Baseline 机制链接校验器使用基线白名单文件 scripts/docs/.linkcheck-baseline.txt 处理经过批准的迁移等例外情况。当前基线为空即任何新增坏链都会直接导致 CI 失败。关键约束禁止手工向基线添加条目只有在官方批准的大规模修复后才允许重新生成基线python scripts/docs/check_links.py --update-baseline基线条目的格式为相对源路径\t目标刻意不包含行号这样链接上方的细微编辑不会导致基线条目失效。7.5 发现范围与排除discover_markdown默认扫描docs/下所有 Markdown 以及仓库根目录的*.md并排除.git、node_modules、site、target、build、dist、.venv、venv、__pycache__等目录同时复用 scripts/docs/docs_scope.py 中的is_excluded_doc跳过发布范围外的文档详见第九节。八、frontmatter 校验器 check_frontmatter.py 原理与使用8.1 本地运行# 默认 warn 模式本地审计 python scripts/docs/check_frontmatter.py # 严格模式发现任何问题即非零退出 python scripts/docs/check_frontmatter.py --strict # 自定义必需字段默认 title、last_reviewed、owner python scripts/docs/check_frontmatter.py --required title owner8.2 实现要点从 scripts/docs/check_frontmatter.py 源码可见默认必需字段为title、last_reviewed、owner三元组DEFAULT_REQUIRED。frontmatter 解析只解析文件开头的---围栏块支持 BOM 前缀且刻意采用极简的扁平key: value解析器而非完整 YAML 依赖——CI 门槛上不引入第三方 YAML 库嵌套结构会被忽略并报为invalid scalar。带引号的值会去除首尾引号。last_reviewed校验通过datetime.date.fromisoformat验证必须是合法 ISO-8601 日期YYYY-MM-DD非法值产生形如last_reviewed must be YYYY-MM-DD, got ...的错误。报告模式默认 warn 模式下所有发现输出但退出码仍为 0--strict模式下任一发现都会令退出码为 1。Docs Quality工作流对已发布语料使用 strict 模式因为线上语料本应具备完整的 title、owner 与复审日期元数据。无 frontmatter 处理完全没有 frontmatter 块的页面会得到一条missing frontmatter block的发现有块但缺字段的每个缺失键各产生一条发现。8.3 发现范围与链接校验器一致discover_docs扫描docs/下全部 Markdown并额外排除overridesMkDocs 主题覆盖目录与stylesheets因为这两处不是用户创作的页面。九、发布范围控制docs_scope.py 与 mkdocs.yml并非docs/下所有文件都会进入发布站点。scripts/docs/docs_scope.py 中的DOCS_EXCLUDE_PATTERNS明确列出了供仓库工作流、源码历史或贡献者脚手架使用、但不面向用户的 MkDocs 页面包括AGENTS.md adr/0000-template.md adr/README.md assets/partners/README.md benchmarks/governance-overhead.md case-studies/TEMPLATE.md dependency-audits/** deployment/README.md security/tenant-isolation-checklist.md slo/** tutorials/README.md也就是说本文所讲解的 docs/AGENTS.md 本身就是一份文档的元文档——它为文档编写者与编码 Agent 提供写作规范而不作为用户可见页面发布。与之对应mkdocs.yml 的exclude_docs复刻了同一套排除列表并追加了security/audits/20*.md等not_in_nav则把i18n/**、proposals/*-DESIGN.md、proposals/*-PROPOSAL.md、package-consolidation/**、package-migration.md等排除出导航但文件仍可被链接访问。两份配置共同保证了质量检查范围与发布范围的一致避免检查工具放过、站点却不发布的文档产生漂移。十、测试覆盖文档工具链的单测文档质量工具链并非一次性脚本而是配有专门的单元测试确保解析器与校验逻辑在演进中不回退。CI 中执行pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q从 scripts/tests/test_docs_check_links.py 可以看到覆盖场景非常细致内联链接指向存在的文件 → 通过且正确计数links_checked指向缺失文件 → 报file not found外部链接https、mailto、协议相对 URL→ 跳过同文件锚点校验存在锚点通过、缺失锚点报错跨文件锚点校验b.md#section-two通过、b.md#missing报错标题锚点保留下划线标识符approach-1-max_tool_calls-in-yaml标题锚点折叠被移除的标点以及引用式链接、代码块剥离、转义字符、目录目标、--require-directory-index、baseline 读写等更多场景全文件共 362 行。这套测试使得链接校验器能够安全地收紧规则例如新增仓库根限制、锚点校验而不用担心误伤合法文档。十一、对编码 Agent 与文档贡献者的工作流建议结合上述规范与工具链为人工与 AI Agent 协作编写文档总结一份可执行的提交前自检清单主题定位先判断变更属于参考材料、教程、架构、安全还是包页面定位到docs/下对应目录优先更新既有页面而非新建近似页面。事实核查所有能力声明以仓库源码、测试、配置为准实验性能力明确标注不引入无来源的性能、采用量或生态论断。frontmatter确保title、last_reviewed合法 ISO 日期与owner齐全实质性修订后递增last_reviewed。链接检查相对路径从当前文档位置即可解析跨文件锚点用 GitHub-style slug不用../逃逸仓库根代码示例中的链接放在围栏代码块内以免误报。本地验证python scripts/docs/check_links.py python scripts/docs/check_frontmatter.py --strict pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q命名对齐包路径遵循一等 SDK 目录模式如agent-governance-python/、agent-governance-dotnet/、agent-governance-golang/CLI 命令与安装片段以仓库实际内容为准。这一规范AGENTS.md→ 工具check_links/check_frontmatter→ CIdocs-quality.yml→ 测试scripts/tests的完整闭环正是 Agent Governance Toolkit 能长期维持文档可信度、可检索性与可引用性的基础设施。无论是人类维护者还是自动化编码 Agent把文档当作一等公民、让每一次 Markdown 变更都经过同样的质量门槛才能让 docs 站点真正成为项目能力的可信镜像。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Governance Toolkit 文档站写作规范与质量保障体系实战指南
Agent Governance Toolkit 文档站写作规范与质量保障体系实战指南【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit导读本文档讲解 Agent Governance Toolkit 仓库中docs/文档树所对应的写作规范Coding Agent Instructions与配套质量工具链包括文档编写约定、内容边界、必需 frontmatter 元数据以及由Docs QualityCI 工作流强制执行的相对链接校验与 frontmatter 校验两个严格检查。读完本文你将掌握如何为该项目正确新增、修订文档页面如何在本地运行scripts/docs/check_links.py与scripts/docs/check_frontmatter.py并理解链接校验器、frontmatter 校验器的底层实现原理与测试覆盖从而在人工或 AI Agent 协作场景下写出可发布、可检索、不会破坏 CI 的技术文档。一、文档站定位docs/ 树承载什么在 Agent Governance Toolkit 仓库中docs/目录驱动着整个已发布文档站点其内容覆盖参考材料、教程、架构文档、威胁建模、合规内容、包页面与集成指南。按照 docs/AGENTS.md 的定义该目录是一个有机整体各子目录职责明确路径用途docs/index.md文档首页与顶层导航docs/packages/各软件包的落地页与包专属文档docs/tutorials/分步操作指南docs/integrations/外部集成指南docs/security/威胁模型、OWASP 与安全指导mkdocs.yml站点导航与构建配置站点构建基于 MkDocs Material 主题mkdocs.yml 中通过docs_dir: docs指定文档源目录并定义了完整的nav导航树涵盖 Getting Started、Packages、Tutorials、Deployment、Security、Compliance、Specifications、Architecture Decisions、Reference 等一级分区。这意味着新增文档页时除了文件本身还需要在mkdocs.yml的nav中登记才能出现在站点导航中同时也要注意exclude_docs与not_in_nav的排除规则详见后文发布范围控制一节。二、文档编写约定七条核心准则docs/AGENTS.md 明确规定了文档编写的七条约定它们是所有文档变更无论由人还是由编码 Agent 发起必须遵守的纪律准确诚实Be precise and honest除非仓库中确实包含该功能否则不得声称功能已发布。这要求写作者以源码、配置和测试为事实依据禁止把规划中的能力写成已交付能力。优先更新而非复制更倾向于更新既有页面而不是创建一个近似重复的新页面。这控制了文档膨胀避免同一概念多份文档互相漂移。使用仓库相对链接文档内链接必须是从当前文档位置出发即可工作的仓库相对路径。同时注意本文档所规定的是编辑期的相对路径书写方式在最终发布的站点上由 MkDocs 统一解析。语气统一与技术、直接、以证据为基础的既有语气保持一致不使用营销腔。名称对齐包名、CLI 命令与安装片段必须与实际仓库保持一致不得凭空杜撰命令或版本。仓库布局规范在描述仓库结构时将仓库根目录下独立的语言 SDK 视为受支持的一等模式first-party pattern。具体规范为以 agent-governance-python/ 作为 Python 包的规范路径以 agent-governance-dotnet/ 作为 .NET 的规范路径以 agent-governance-golang/ 作为对应的同级模式Go 包。 同理仓库中还存在 agent-governance-typescript/ 与 agent-governance-rust/ 等平级 SDK 目录写作时应遵守这一独立目录承载语言 SDK的约定而不是把它们描述为docs/packages/下的内嵌组件。第三方集成分类在说明第三方集成时必须讲清楚它们是示例examples、适配器adapters还是受维护的一等集成面maintained first-party surfaces不得模糊其支持层级。三、内容边界四条红线为了保证文档的可靠性与可维护性docs/AGENTS.md 划定了四条不能逾越的内容边界不引入无来源的主张不得在没有出处的情况下引入新的生态论断、基准测试数据或采用数量。这一点与事实准确与证据边界原则一致——性能数字、用户量、兼容性矩阵等都必须有仓库内或可靠公开资料支撑。翻译文档需显式请求除非被明确要求否则不新增翻译文档始终先保证英文源页面正确。仓库中已有的 i18n 目录docs/i18n/按此规则维护。不隐藏限制如果某行为是部分实现或实验性的必须明确说明禁止把半成品写成稳定功能。避免大段复制厂商文档对于第三方厂商文档应摘要并注明出处而不是成块搬运。这些边界同时约束了文档最小完备性宁可明确标注实验性也不可夸大能力这与 docs/LIMITATIONS.md 的整体立场一致。四、代码变更触发文档义务当仓库代码发生变化时docs/AGENTS.md 要求文档随之跟进具体场景包括公开 API 变更应同步更新最近的包页面或教程。例如 TypeScript SDK、Rust crate、Go module、Python 包等任一公开接口变化都应找到对应包页docs/packages/或教程docs/tutorials/进行更新。新增示例新示例通常至少应更新一次文档可发现性即在教程或包页中登记入口确保用户能找到它。安全敏感变更应复审 docs/security/ 目录及 docs/security/threat-model.md判断威胁模型是否需要同步调整。五、验证要求与必需 frontmatter5.1 通用验证要求每次文档变更提交前都应检查链接、文件路径、围栏代码块fenced code blocks是否合法有效标题与页面名称保持稳定除非是有意重命名。标题稳定性对检索和引用至关重要搜索引擎索引、外部链接、GitHub-style 锚点都依赖稳定的标题频繁改名会破坏既有引用。5.2 必需 frontmatter新建和编辑的文档页都应包含以下 YAML frontmatter 头--- title: Page Title last_reviewed: 2026-07-15 # ISO date, YYYY-MM-DD owner: agt-maintainers # team or maintainer handle ---字段语义字段含义约束title页面标题必填缺失即 CI 失败last_reviewed新鲜度信号必须为YYYY-MM-DD格式的合法 ISO-8601 日历日期凡有实质修订就应递增更新owner页面所有者团队或维护者标识如agt-maintainers其中last_reviewed是新鲜度信号freshness signal只要页面经过有意义的修订就应更新该日期帮助维护者识别长期未复审的页面。六、Docs Quality CI 工作流Docs Quality工作流.github/workflows/docs-quality.yml在每一个触及 Markdown 的 PR 上运行由三个 job 组成Job校验内容执行命令links相对链接校验严格坏链即失败python scripts/docs/check_links.py --root .frontmatterfrontmatter 校验严格缺失 title/复审日期/owner 即失败python scripts/docs/check_frontmatter.py --root . --strictunit-tests文档工具链的单元测试pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q触发条件是 PR 变更以下任一路径**/*.md、mkdocs.yml、scripts/docs/**、scripts/tests/test_docs_check_*.py、以及工作流自身文件。运行环境为ubuntu-latest Python 3.11并使用固定版本如actions/checkoutv7.0.1、actions/setup-pythonv7.0.0、pytest8.3.3以保证供应链可复现。七、链接校验器 check_links.py 原理与使用7.1 本地运行在提交 PR 之前于仓库根目录本地执行python scripts/docs/check_links.py也可以只检查特定文件、以 JSON 输出或切换校验模式# 只检查单个文档 python scripts/docs/check_links.py docs/security/threat-model.md # 以 JSON 输出机器可读报告 python scripts/docs/check_links.py --root . --json # 切换到 MkDocs 风格严格模式目录目标必须包含 index.md python scripts/docs/check_links.py --require-directory-index退出码约定0表示无坏链1表示检测到坏链2表示用法/调用错误。7.2 解析能力能识别哪些链接从 scripts/docs/check_links.py 源码看校验器具备一套严谨的 Markdown 解析管线内联链接text通过专门的正则提取并排除图片要求前面没有!。引用式链接同时支持引用定义[label]: target与引用使用[text][label]并只在使用处校验避免同一目标被重复计数。代码块剥离_strip_code_blocks会把 或 ~~~ 围栏代码块的内容替换为空白保持行号稳定这样代码示例中的链接不会被误报为坏链同时_strip_inline_code_spans处理行内代码片段两者组合后才是链接提取的输入文本。正则安全链接正则有意识地排除反斜杠歧义规避了 CodeQLpy/redos指数回溯告警适合在 CI 中高频运行。7.3 校验规则什么算坏链validate_link实现了如下判定逻辑页内锚点#anchor针对源文件自身的标题锚点校验找不到即报错。外部链接http、https、mailto、tel、ftp、ftps及//协议相对 URL不做网络校验直接跳过。仓库根限制目标解析后必须位于仓库根目录内解析到根外的目标例如../../../etc/hosts直接判定为坏链——这一设计防止了链接校验在任意运行环境下意外通过。目录目标GitHub 会把目录渲染为文件夹视图因此只要目录存在即接受若目录下有index.md则解析到该文件--require-directory-index开启后无index.md的目录目标会被判为坏链对应 MkDocs 严格模式。锚点校验目标为.md文件且带锚点时会用标题 slug 集合校验目标文件内是否存在该锚点。标题锚点的 slug 化规则_slugify_heading也值得注意小写化、去除 Markdown 格式、空格转连字符、仅保留字母数字与-/_并压缩连续连字符。因此## Approach 1: max_tool_calls in YAML对应的锚点是approach-1-max_tool_calls-in-yaml。7.4 Baseline 机制链接校验器使用基线白名单文件 scripts/docs/.linkcheck-baseline.txt 处理经过批准的迁移等例外情况。当前基线为空即任何新增坏链都会直接导致 CI 失败。关键约束禁止手工向基线添加条目只有在官方批准的大规模修复后才允许重新生成基线python scripts/docs/check_links.py --update-baseline基线条目的格式为相对源路径\t目标刻意不包含行号这样链接上方的细微编辑不会导致基线条目失效。7.5 发现范围与排除discover_markdown默认扫描docs/下所有 Markdown 以及仓库根目录的*.md并排除.git、node_modules、site、target、build、dist、.venv、venv、__pycache__等目录同时复用 scripts/docs/docs_scope.py 中的is_excluded_doc跳过发布范围外的文档详见第九节。八、frontmatter 校验器 check_frontmatter.py 原理与使用8.1 本地运行# 默认 warn 模式本地审计 python scripts/docs/check_frontmatter.py # 严格模式发现任何问题即非零退出 python scripts/docs/check_frontmatter.py --strict # 自定义必需字段默认 title、last_reviewed、owner python scripts/docs/check_frontmatter.py --required title owner8.2 实现要点从 scripts/docs/check_frontmatter.py 源码可见默认必需字段为title、last_reviewed、owner三元组DEFAULT_REQUIRED。frontmatter 解析只解析文件开头的---围栏块支持 BOM 前缀且刻意采用极简的扁平key: value解析器而非完整 YAML 依赖——CI 门槛上不引入第三方 YAML 库嵌套结构会被忽略并报为invalid scalar。带引号的值会去除首尾引号。last_reviewed校验通过datetime.date.fromisoformat验证必须是合法 ISO-8601 日期YYYY-MM-DD非法值产生形如last_reviewed must be YYYY-MM-DD, got ...的错误。报告模式默认 warn 模式下所有发现输出但退出码仍为 0--strict模式下任一发现都会令退出码为 1。Docs Quality工作流对已发布语料使用 strict 模式因为线上语料本应具备完整的 title、owner 与复审日期元数据。无 frontmatter 处理完全没有 frontmatter 块的页面会得到一条missing frontmatter block的发现有块但缺字段的每个缺失键各产生一条发现。8.3 发现范围与链接校验器一致discover_docs扫描docs/下全部 Markdown并额外排除overridesMkDocs 主题覆盖目录与stylesheets因为这两处不是用户创作的页面。九、发布范围控制docs_scope.py 与 mkdocs.yml并非docs/下所有文件都会进入发布站点。scripts/docs/docs_scope.py 中的DOCS_EXCLUDE_PATTERNS明确列出了供仓库工作流、源码历史或贡献者脚手架使用、但不面向用户的 MkDocs 页面包括AGENTS.md adr/0000-template.md adr/README.md assets/partners/README.md benchmarks/governance-overhead.md case-studies/TEMPLATE.md dependency-audits/** deployment/README.md security/tenant-isolation-checklist.md slo/** tutorials/README.md也就是说本文所讲解的 docs/AGENTS.md 本身就是一份文档的元文档——它为文档编写者与编码 Agent 提供写作规范而不作为用户可见页面发布。与之对应mkdocs.yml 的exclude_docs复刻了同一套排除列表并追加了security/audits/20*.md等not_in_nav则把i18n/**、proposals/*-DESIGN.md、proposals/*-PROPOSAL.md、package-consolidation/**、package-migration.md等排除出导航但文件仍可被链接访问。两份配置共同保证了质量检查范围与发布范围的一致避免检查工具放过、站点却不发布的文档产生漂移。十、测试覆盖文档工具链的单测文档质量工具链并非一次性脚本而是配有专门的单元测试确保解析器与校验逻辑在演进中不回退。CI 中执行pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q从 scripts/tests/test_docs_check_links.py 可以看到覆盖场景非常细致内联链接指向存在的文件 → 通过且正确计数links_checked指向缺失文件 → 报file not found外部链接https、mailto、协议相对 URL→ 跳过同文件锚点校验存在锚点通过、缺失锚点报错跨文件锚点校验b.md#section-two通过、b.md#missing报错标题锚点保留下划线标识符approach-1-max_tool_calls-in-yaml标题锚点折叠被移除的标点以及引用式链接、代码块剥离、转义字符、目录目标、--require-directory-index、baseline 读写等更多场景全文件共 362 行。这套测试使得链接校验器能够安全地收紧规则例如新增仓库根限制、锚点校验而不用担心误伤合法文档。十一、对编码 Agent 与文档贡献者的工作流建议结合上述规范与工具链为人工与 AI Agent 协作编写文档总结一份可执行的提交前自检清单主题定位先判断变更属于参考材料、教程、架构、安全还是包页面定位到docs/下对应目录优先更新既有页面而非新建近似页面。事实核查所有能力声明以仓库源码、测试、配置为准实验性能力明确标注不引入无来源的性能、采用量或生态论断。frontmatter确保title、last_reviewed合法 ISO 日期与owner齐全实质性修订后递增last_reviewed。链接检查相对路径从当前文档位置即可解析跨文件锚点用 GitHub-style slug不用../逃逸仓库根代码示例中的链接放在围栏代码块内以免误报。本地验证python scripts/docs/check_links.py python scripts/docs/check_frontmatter.py --strict pytest scripts/tests/test_docs_check_links.py scripts/tests/test_docs_check_frontmatter.py -q命名对齐包路径遵循一等 SDK 目录模式如agent-governance-python/、agent-governance-dotnet/、agent-governance-golang/CLI 命令与安装片段以仓库实际内容为准。这一规范AGENTS.md→ 工具check_links/check_frontmatter→ CIdocs-quality.yml→ 测试scripts/tests的完整闭环正是 Agent Governance Toolkit 能长期维持文档可信度、可检索性与可引用性的基础设施。无论是人类维护者还是自动化编码 Agent把文档当作一等公民、让每一次 Markdown 变更都经过同样的质量门槛才能让 docs 站点真正成为项目能力的可信镜像。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考