Stagehand 文档站点全指南本地开发、校验与发布流程详解【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehandThe SDK For Browser Agents的官方文档站点托管在packages/docs目录下采用 Mintlify 构建同时承载 v2、v3、v4 三个版本的技术文档其中 v4 为默认版本。本文以 packages/docs/README.md 为核心脉络结合仓库中的 justfile、packages/docs/package.json、packages/docs/docs.json 与测试用例系统讲解文档站的本地开发、自动校验与发布上线的完整工作流帮助你快速搭建本地文档环境并为文档质量把关。文档站点概览一份仓库、三套版本packages/docs不只是普通 README 的堆叠而是一个由 Mintlify 驱动的完整技术文档站。其结构围绕三个平行的版本目录组织v2/对应 Stagehand v2 时代的文档包含act、extract、observe、agent四大基础能力以及 Playwright interop、iframe 处理等最佳实践v3/新增了 Python、Java、Go、Ruby 等语言 SDK 章节由 scripts/sync-sdk-docs.js 自动同步并引入 WebMCP、Evals、MCP Server 集成等内容v4/当前默认版本文档结构更精简聚焦act、extract、observe、webmcp四大原语参考文档按 SDK 对象组织stagehand、context、clipboard、page、locator、response、webmcp。版本切换、导航分组、重定向规则全部在 packages/docs/docs.json 中声明。navigation.versions数组按 v4 → v3 → v2 的顺序定义各自的分组与页面redirects字段则将旧路径如/first-steps/:slug*、/basics/act统一重定向到对应版本的新路径保证外部链接与搜索引擎收录不失效。theme为maple主色为绿色#00C851Logo 则引用 packages/docs/logo/light_logo.png 与 packages/docs/logo/dark_logo.png。v3 与 v4 的语言切换差异v3 文档通过 packages/docs/language-selector.js 实现侧边栏语言下拉切换TypeScript / Python / Java / Go / Ruby并联动代码块语言选择器与 SDK 参考页面的显隐而 v4 文档则直接使用 Mintlify 原生的Tabs组件在页面内切换语言。从源码注释可以看出该脚本只作用于isV3Page()即 URL 以/v3开头的页面所有 DOM 操作都带版本守卫避免在 v4 页面误触发。环境准备从零启动文档服务在开始之前需要先安装just命令运行器文档仓库的常用命令都封装在仓库根目录的 justfile 中。安装依赖从仓库根目录执行just install该命令内部依次执行见 justfilepnpm install安装整个 pnpm workspace 的 JavaScript/TypeScript 依赖uv --directory packages/sdk-python sync --locked锁定 Python SDK 的虚拟环境依赖go -C packages/sdk-go mod download与go -C packages/sdk-go/internal/generator mod download下载 Go SDK 及其代码生成器的模块依赖。由于packages/docs是 pnpm workspace 的一员包名为browserbasehq/stagehand-docs见 packages/docs/package.json一次pnpm install即会安装mint与mdx-js/mdx等文档构建所需的开发依赖。启动本地文档服务just docsjust docs实际执行pnpm run docs即mint dev见 packages/docs/package.json。关键特性它启动的是与仓库锁定的 Mint 开发服务器无需全局安装 Mint 或 Mintlify CLI。打开终端输出的本地地址即可预览文档并可通过右侧的版本切换器在 v2 / v3 / v4 之间跳转。路径解析的小细节packages/docs/scripts/runtimePaths.js 通过读取 JavaScript 调用栈Error.prepareStackTrace来定位调用者文件路径进而推导仓库根目录。它声明需要与packages/core/lib/v3/runtimePaths.ts、packages/evals/runtimePaths.ts保持同步并过滤掉[eval]、[eval]-wrapper帧以及getCurrentFilePath、getRepoRootDir等内部函数帧。SDK 文档同步脚本scripts/sync-sdk-docs.js正是借助getCurrentDirPath()确定输出目录的。校验一键检查文档健康度文档改完后在仓库根目录运行just checkjust check会先执行check-go-examples再依次运行 changesets 检查、changelog 合并校验、Python 版本同步校验、pnpm check覆盖 lint 与各包测试以及 Python / Go 侧的格式与静态检查见 justfile。其中与文档站直接相关的是pnpm --filter ./packages/docs run check由pnpm check触发它执行的是 packages/docs/package.json 中定义的三段式校验脚本mint validate mint broken-links --check-anchors --check-redirects --check-snippets mint a11y --skip-contrast三个环节分别解决不同问题mint validate校验 Mint 配置即docs.json与 OpenAPI 定义的合法性导航分组、版本声明、API 引用地址的格式问题都会在此暴露mint broken-links检查文档内链接、锚点--check-anchors、重定向--check-redirects与代码片段--check-snippets是否有效能提前拦截 404 链接和失效锚点mint a11y执行文档可访问性检查跳过对比度项保证文档对屏幕阅读器等辅助技术友好。单元测试SDK 参考页与源码对齐除了 Mint 自身的校验文档站还配套了一套 vitest 单元测试packages/docs/tests/sdk-reference.test.ts。该测试使用mdx-js/mdx解析 v4 参考页面的 MDX 语法树再用ast-grep/napi解析 TypeScript / Python / Go 的源码断言三者表面完全一致。其核心检查点包括方法表面一致TypeScript、Python、Go 三套 SDK 的公开可调用方法必须互相匹配且与参考页中按语言 Tab 记录的标题一一对应参考页覆盖v4/reference/下每个 SDK 对象Stagehand、BrowserContext、BrowserClipboard、Page、Locator恰好有一页response、webmcp被显式归类为补充参考页类型精确参数与返回字段的类型、可选性必须与公共 SDK 注解及 protocol schemapackages/protocol/stagehand.v4.json投影一致链接可达v4 文档中所有指向/v4/reference/*的链接和锚点都必须能解析到真实页面与标题。这意味着参考文档任何一处与 SDK 源码不符pnpm testvitest都会直接失败。文档与代码的强一致性正是这套仓库的工程化特色。发布合并即上线文档的发布无需手动执行构建命令。根据 packages/docs/README.md文档通过 Mintlify GitHub 集成部署当改动合并到仓库的默认分支后集成会自动拉取最新内容并发布到线上文档站。因此日常的文档工作流可以归纳为在分支上修改packages/docs/v2|v3|v4下的.mdx文档或docs.json导航配置本地运行just docs预览效果运行just check通过全部校验提交并合并 PR 到默认分支等待 Mintlify 集成自动发布。附SDK 文档如何保持同步v3 文档中的 Java / Python / Ruby / Go SDK 页面并非手工维护而是通过 packages/docs/scripts/sync-sdk-docs.js 从各 SDK 仓库的README.md抓取后自动生成的node scripts/sync-sdk-docs.js脚本会请求browserbase/stagehand-java、browserbase/stagehand-python、browserbase/stagehand-ruby、browserbase/stagehand-go四个仓库的main分支 README经过一系列清洗移除 badge 图片、HTML 注释、转换相对链接为绝对链接、修正 Go 文档中的代码块标签等后写入v3/sdk/*.mdx并自动追加标题与自动同步提示的 frontmatter见 scripts/sync-sdk-docs.js。该脚本可通过pnpm --filter browserbasehq/stagehand-docs sync-sdk调用见 packages/docs/package.json适合在发布前批量刷新多语言 SDK 文档。结语Stagehand 的文档站并非简单的静态页面而是一套配置化导航 多版本共存 自动化校验 集成发布的工程体系docs.json决定站点骨架just docs提供即改即预览的本地体验just check与 vitest 测试保证链接、锚点、可访问性乃至 SDK 参考页与源码的完全同步Mintlify GitHub 集成则让合并即上线成为默认路径。无论你是要新增一篇 v4 教程、修正参考文档的类型标注还是维护多语言 SDK 页面上述工作流都能让改动以高质量、低风险的方式抵达线上文档。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考