SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cosmos-framework-docs

cosmos-framework-docs

写作与研究

查看项目

更新于 10-23 00:10

技能介绍

用途

本技能用于维护 Cosmos-Framework 的文档及其 MkDocs 文档站点。适用于修改或更新某个文档页面（包括从站点反馈的问题）、新增或移动/重命名/删除页面、调整站点导航、修改首页、Logo、配色或 MkDocs 配置、预览站点，以及修复失败的 Docs 工作流。

文档组织方式

站点由仓库中的 Markdown 通过 tools/docs/ 下的工具构建。源文件保持纯 GitHub 风格 Markdown，同时也需在 GitHub 上可读。stage.py 将文件复制到 build/docs-site/，重写其中的链接供站点使用，并写出 build/mkdocs.yml。面向人的说明见 docs/README.md。文中路径均相对仓库根目录。

查找页面对应的源文件

不要编辑 build/，它每次构建都会重新生成。先在 tools/docs/nav.yml 的 nav 中找页面的站点路径，或按站点导航标题、URL 定位：<site>/get_started/quickstart/ 对应 get_started/quickstart.md，<site>/models/ 对应 models/README.md。页面在 llms.txt 中的 Markdown URL 就是站点路径本身，如 <site>/get_started/quickstart.md。

将站点路径映射到仓库文件时，按以下顺序，首个匹配生效：

  • nav.yml 中的 sources。例如首页 index.md 是 tools/docs/site/index.md，develop/contributing.md 是 CONTRIBUTING.md。
  • skills/<path> 对应 .agents/skills/<path>。
  • 其余 <path> 对应 docs/<path>。

nav 保存站点路径；extra_pages（仅通过链接到达的页面，如 NIM 指南）、hold 和 not_on_site 保存仓库路径，后两者支持 glob。

规则

  • 不要编辑 docs/posttrain/，它从上游仓库同步（.posttrain_file_mapping.json 记录每个文件的映射），本地修改会被覆盖。应保持文件不变，在回答中给出文件、行号和替换文本，并对照 cosmos_framework/posttrain/ 校验。这些页面的问题在构建时只产生警告。
  • 链接其他仓库文件时使用相对 Markdown 链接，如 ../setup.md#cuda-variants。不要使用站点 URL（不会检查且在 GitHub 上失效），也不要使用相对原始 HTML 的 <a href>/<img src>（stage.py 会拒绝）。构建时，若目标在站点上则转为站点链接，不在站点上则转为指向 main 的 GitHub 链接，被 hold 的目标则转为纯文本。
  • 提示使用 GitHub alerts（> [!NOTE]）和 <details>，两者在站点均可渲染。仅 Material 支持的语法（如 admonitions、按钮、卡片网格）只能出现在 tools/docs/site/ 下的页面中，如首页 index.md，这些页面仅存在于站点，链接使用站点路径。
  • 每个 docs/**/*.md 必须被 nav.yml 覆盖（通过 nav 条目或其在 extra_pages、hold、not_on_site 中的仓库路径），否则 stage.py 失败。docs/posttrain/ 中未列出的文件只警告且不上站点，发布需修改 nav.yml。docs/ 之外的文件只有被 nav 或 extra_pages 列出才会被渲染。
  • 标题生成 GitHub 兼容锚点，因此 #anchor 链接在 GitHub 和站点上都可用。重命名标题会破坏指向它的链接，可用 git grep -n --untracked '#<old-anchor>' 查找。stage.py 遇到指向缺失文件的链接会失败，严格构建遇到缺失锚点会失败。
  • 不要手工编辑 <!--TOC--> 块，pre-commit 会重新生成，站点会丢弃它们。
  • 内容会发布到公开的 NVIDIA/cosmos-framework 仓库及其站点，不要添加内部主机名、/lustre/... 等集群路径、人名、内部工单或合并请求编号。
  • 每条命令、标志、默认值和数字都必须与代码或可引用的来源一致，不要从其他页面未经核对地复制。CLI 标志由 pydantic 字段经 tyro 生成：字段 checkpoint_path 对应标志 --checkpoint-path。查看入口的 main()（如 cosmos_framework/scripts/inference.py）以确定解析的模型；推理字段在 cosmos_framework/inference/args.py 和 cosmos_framework/inference/common/args.py，检查点名称与大小在 cosmos_framework/inference/args.py 的 _CHECKPOINTS 中。
  • 页面保持简短：先结论，再步骤，选择项用表格。新页面可参照 docs/get_started/quickstart.md；Markdown 页面无需 SPDX 头。除非被要求，保留页面的 H1。

常见修改对照

  • 修改页面文字：编辑该页源文件。
  • 新增页面：在 docs/get_started/、docs/models/、docs/deploy/ 或 docs/post_training/ 中新建文件（不属这些目录则放在 docs/），添加 nav 条目，并从相关页面链接过去。
  • 重命名或移动页面：用 git mv 移动文件；若目录变化，更新其自身相对链接；更新 nav.yml 条目；更新所有入站链接（git grep -n --untracked '<old file name>'）。旧 URL 不会重定向。
  • 从站点移除页面：删除其 nav 条目；docs/ 中的页面还需将其仓库路径加入 not_on_site（链接指向 GitHub）或 hold（链接变为纯文本）。
  • 修改导航标签或顺序：只改 tools/docs/nav.yml。
  • 修改首页：tools/docs/site/index.md。
  • 修改 Agent skills 页面、llms.txt：页面文字改 tools/docs/site/agent_skills.md；llms.txt 文字由 tools/docs/stage.py 中的 write_llms_txt 生成，页面章节跟随 nav。skills 表和 llms.txt 中的技能来自各 SKILL.md 的 name 与 description，因此新增技能无需改文档。
  • 修改 Logo、配色、MkDocs 设置：tools/docs/images/、tools/docs/stylesheets/extra.css、tools/docs/mkdocs.yml（不得设置 docs_dir、site_dir、nav、not_in_nav 或 hooks）。
  • 修改构建行为：tools/docs/stage.py，并在 tools/docs/tests/ 中加测试。

构建与检查

在仓库根目录按以下顺序运行（pre-commit 可能改写文件）：

uvx pre-commit@4.5.1 run --files <changed files>
uvx pre-commit@4.5.1 run -c ci/.pre-commit-config-base.yaml --files <changed files>
uv run --project tools/docs python tools/docs/stage.py
uv run --project tools/docs mkdocs build --strict -f build/mkdocs.yml

pre-commit 会格式化 Markdown 并重新生成 TOC。保留其修改，手工修复其报告但无法自动修复的问题，并重复运行直至通过。它跳过 .agents/skills/cookbooks/ 和 .agents/skills/evaluation/，这些页面仅由 stage.py 和严格构建检查。

stage.py 会输出每条 WARNING 和 ERROR 及文件（通常附带修复方法），以 warnings: N, errors: N 结尾，有任何错误即非零退出。修复每个错误及与所改文件相关的每个警告。严格构建以退出码判断；其关于 MkDocs 2.0 的红色横幅不是警告，可用 NO_MKOCS_2_WARNING=true 隐藏（环境变量名以实际工具输出为准）。

嵌入图片会复制到页面旁。*.png 和 *.jpg 存放在 Git LFS 中：若 stage.py 报告 LFS 指针，运行它打印的 git lfs pull 命令。

若修改了 tools/docs/stage.py，还需运行：

uv run --project tools/docs pytest -c tools/docs/pyproject.toml --confcutdir=tools/docs tools/docs/tests

预览可运行 uv run --project tools/docs mkdocs serve -f build/mkdocs.yml -a 127.0.0.1:8000。页面位于 site_url 路径下，get_started/quickstart.md 的地址为 http://127.0.0.1:8000/cosmos-framework/get_started/quickstart/。若端口被占用，可能已有其他预览在运行：不要干扰它，换一个端口，并在结束后关闭自己的服务器。服务器读取的是暂存副本，每次修改源文件后需重新运行 stage.py。没有浏览器时，可在严格构建后读取 build/site/<去掉 .md 的站点路径>/index.html。

这些命令会写出被 git 忽略的输出：build/、.rumdl_cache/ 和 tools/docs/.venv/，不要提交。

完成标准：pre-commit 通过，stage.py 对所做文件无错误和警告，严格构建通过，且构建出的页面显示修改且链接可用。

适用场景与限制

适用于 Cosmos-Framework 文档仓库内的文档编辑、站点配置与构建排障，前提是具备仓库访问权限和 uv、pre-commit、Git LFS 等工具环境。它不涉及文档内容的模型/推理功能本身，不提供站点托管或发布流程之外的部署说明；收费、平台支持等资料暂未提供。