Mastra 文档编辑工作流移动、删除、重定向与验证实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 文档站点基于 Docusaurus 构建提供了完整的脚本来处理文档移动、删除、重定向管理和内容验证。本文档详细说明这套工作流的每个环节涵盖从变更准备、页面移动/删除、重定向维护到最终验证的全流程帮助开发者高效地维护开源项目文档。1. 变更准备在开始任何文档编辑之前需要完成以下准备工作对照样式指南检查源文档的准确性和写作风格。使用信息架构指南确定文档的规范归属主体canonical owner以及是否存在重叠页面。阅读目标页面、相邻页面及对应的侧边栏配置。当页面或子系统变更频繁时检查近期历史记录。必要时阅读对应的页面类型指南如 DOC.md和组件文档。Mastra 文档分为四个内容品类详见INFORMATION_ARCHITECTURE.md品类源目录用途/docsdocs/src/content/en/docsMastra 概念、能力、配置、决策及具体用法/integrationsdocs/src/content/en/integrations外部产品、供应商、框架、渠道及部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型及查阅材料/modelsdocs/src/content/en/models自动生成请勿手动编辑2. 使用脚本移动文档页面Mastra 提供了move-doc.ts脚本源码见 docs/scripts/move-doc.ts支持单文件移动和批量移动glob 模式。脚本的底层操作包括将 MDX 文件在src/content/en/family下移动更新同品类移动中对应的 Docusaurus 侧边栏文档 ID更新指向旧路由的 Markdown 和 MDX 链接向vercel.redirects.json添加重定向规则更新已有重定向使其指向新路由单文件移动从docs/目录运行pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route --dry-run pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route支持的可编辑路由品类为/docs、/integrations和/reference。/models为自动生成路由不支持移动操作。--dry-run参数可预览变更而不实际修改文件。批量移动Glob 模式使用 glob 模式移动多个匹配路径下的文档pnpm tsx scripts/move-doc.ts /docs/old/** /docs/new/** --dry-run pnpm tsx scripts/move-doc.ts /docs/old/** /docs/new/**使用 glob 模式时源和目标必须同时为 glob 模式。模式中的**通配符会按位置顺序映射到新路径。由于 shell 会展开 glob 表达式请用引号包裹。移动后的检查要点审查每一条被修改的链接确保锚文本自然且语义正确。检查 JSX 中的href和link目标是否正确更新。确认目标路由与预期内容品类匹配。确认没有残留的旧作者链接。重新生成重定向并执行生产构建来验证结果。从源码看moveDocuments函数move-doc.ts#L594是整个移动操作的核心入口它处理了从单文件到 glob 模式的各种场景。当跨品类移动时如从/docs移到/reference脚本会给出警告并提示手动更新侧边栏而非自动修改跨品类侧边栏。3. 使用脚本删除或合并文档页面delete-doc.ts脚本源码见 docs/scripts/delete-doc.ts支持删除一个文档页面并将其路由重定向到替换页面。替换页面可以是内部可编辑路由也可以是外部 HTTPS URL。从docs/目录运行pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement --dry-run pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement脚本的自动处理包括删除源 MDX 文件添加从旧路由到替换页面的重定向更新所有指向旧路由的 MDX 内部链接使其指向替换页面更新已有重定向链中的中间环节指向最终替换路径从侧边栏 JS 中移除对应的文档 ID并在嵌套分类变空时自动修剪支持替换为外部 URL例如将废弃页面重定向到 SaaS 产品页pnpm tsx scripts/delete-doc.ts /docs/old-page https://agent-builder.mastra.ai删除后的检查要点确认关键信息已整合到替换页面中。审查被重写的链接文本和锚点。如果删除子项导致空分类被移除恢复意图保留的侧边栏项。重新生成重定向并执行生产构建。从源码看deleteDocument函数delete-doc.ts#L368实现了完整的先快照、再写入、失败回滚机制操作开始前对vercel.redirects.json、侧边栏文件和所有 MDX 文件做字节级快照delete-doc.ts#L376-L417如果中途任何一步失败自动恢复所有文件到快照状态。此设计确保了文档删除操作的事务安全性。4. 维护重定向docs/vercel.redirects.json是作者维护的重定向源文件是重定向规则的唯一真实来源。docs/vercel.json由生成器自动生成不应手动编辑。重定向生成修改vercel.redirects.json后从docs/目录运行pnpm generate-vercel-redirects此命令将触发 generate-vercel-redirects.mjs 脚本其生成的逻辑如下从vercel.redirects.json读取重定向规则复制到vercel.json为符合条件的内部文档品类重定向自动生成对应的/llms.txt配套重定向在 CI 中自动重新生成并验证若文件变更未提交则将构建标记为失败生成器的校验规则生成器包含多项安全校验generate-vercel-redirects.mjs#L81-L118校验项说明拒绝重复来源Duplicate sources同一source不能出现两次拒绝重定向链Redirect chains一个重定向的destination不能同时是另一个重定向的source自动创建/llms.txt配套重定向仅为内部文档品类重定向生成排除外部 URL 和已存在的llms.txt路由从生成的 llms-txt 目标中移除片段生成的/llms.txt重定向不会保留 URL 锚点核心原则绝不能直接编辑生成的vercel.json。如果任务包含仓库变更请提交vercel.json对于未经提交的审核让两个文件保留在工作树中即可。5. 验证变更根据变更类型执行对应的最小验证检查。以下是变更类型与最低检查对应表变更类型最低检查项纯文本 MDXMDX 格式检查、Remark 检查、Vale 检查Frontmatter格式检查及pnpm validate侧边栏格式检查、pnpm validate路由或导航变更时还需构建移动或删除聚焦脚本测试、重定向检查、校验及构建重定向重定向生成器测试、生成、校验及构建MDX 组件或 llms-txt 处理器聚焦 Vitest 测试、格式检查、校验及构建主题或导航行为聚焦单元测试或 Playwright 测试及构建从docs/目录执行的常用命令pnpm format:mdx:check # MDX 文件格式检查 pnpm format:check # 整体格式检查含 oxfmt pnpm lint:remark # Remark linter 检查 pnpm lint:vale:ai # Vale AI 风格检查仅错误级别 pnpm validate # 验证 frontmatter、参考侧边栏排序、文档侧边栏和 new 标签 pnpm test # 运行 Vitest 单元测试 pnpm build # Docusaurus 生产构建优先使用聚焦的文件参数或特定的测试文件。生产构建是路由解析、MDX 编译和生成的 llms-txt 输出的最终验证。6. 审查最终差异在交付变更之前完成以下最终审查运行git diff --check检查空白错误。确认只有计划内的文件被修改。检查是否残留过期路由名称、临时文本、调试输出或生成产物。对比最终页面与原始任务和源码发现确保内容准确。如果存在无关的失败应单独说明而不应削弱或跳过检查。参考DOC.md文档页面类型指南概述、聚焦概念、配置、任务驱动等页面模板STYLEGUIDE.md详细的写作风格指南INFORMATION_ARCHITECTURE.md信息架构与内容品类归属move-doc.ts文档移动脚本及测试用例 move-doc.test.tsdelete-doc.ts文档删除脚本及测试用例 delete-doc.test.tsgenerate-vercel-redirects.mjs重定向生成器及测试用例 generate-vercel-redirects.test.ts【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考