跳转到主要内容
For a detailed audit of all automations, see the Automations & Workflows Audit Report.

​
概述

文档存储库使用多个自动化系统来保持内容的最新状态，验证质量并简化工作流程：
  • GitHub Actions - 用于测试、验证和自动更新的 CI/CD 工作流
  • n8n Workflows - 用于数据获取和内容更新的外部自动化平台
  • 脚本 - 用于内容生成、数据获取和维护的命令行工具
  • 预提交钩子 - 本地验证以确保符合风格指南
Intentional Duplication: Both GitHub Actions and n8n workflows exist for the same functionality (Ghost blog, Forum, YouTube data). This is intentional to provide flexibility for future maintainers. Use whichever platform you prefer based on your needs.

​
GitHub Actions 工作流

GitHub Actions 工作流位于 .github/workflows/ 并在推送、拉取请求或计划间隔时自动运行。

​
活跃的工作流程

​
损坏的链接检查

文件： .github/workflows/broken-links.yml 目的： 验证文档中的所有链接是否正常工作 触发条件:
  • 拉取请求到 main 分支
它的作用:
  1. 安装 Mintlify CLI
  2. 运行 mintlify broken-links 查看所有链接
  3. 在工作流摘要中输出帖子建议（目前为非阻塞）
** 手动执行：** 不可用（仅限 PR） ** 所需机密：** 无 政策: ⚠️ 仅作为建议，同时正在进行旧链接清理 (continue-on-error: true)

​
文档 CI - 内容质量套件

文件: .github/workflows/test-suite.yml 目的: 运行主要的 PR 阻止内容质量检查 ** 触发:**
  • 推送到 main
  • 拉取请求到 main 或 docs-v2
** 它的作用（PR）:**
  1. 与 PR 基础分支相比，计算更改的文件
  2. 运行针对更改文件的作用域阻止检查:
    • 风格指南
    • MDX 验证
    • 拼写
    • 质量
    • 链接/导入
    • 对已更改的脚本进行脚本文档强制执行
    • 对已更改的文档页面进行严格 V2 链接审计
  3. 为路由/运行时覆盖率运行浏览器测试
  4. 将结果写入 GitHub 步骤摘要
输出: 工作流摘要表（此工作流不生成 PR 注释） ** 异常:** 对于集成 PR docs-v2 -> main, 已更改文件的静态失败被视为建议；浏览器失败仍然会阻止。

​
SDK 生成

** 文件:** .github/workflows/sdk_generation.yaml 目的: 使用 Speakeasy 从 OpenAPI 规范自动生成 SDK ** 触发条件:**
  • 每天 UTC 午夜（计划任务）
  • 从 GitHub Actions UI 手动分发
** 它的作用:**
  1. 使用 Speakeasy SDK 生成操作
  2. 为所有配置的 API 生成 SDK
  3. 创建包含生成代码的拉取请求
手动执行:
  1. 转到 操作 → SDK 生成
  2. 点击 “运行工作流”
  3. 可选设置force: true以在没有更改的情况下重新生成
必需的密钥:
  • SPEAKEASY_API_KEY - 用于 SDK 生成的 Speakeasy API 密钥

​
Docs CI - V2 浏览器扫描

文件: .github/workflows/test-v2-pages.yml 目的： 测试所有 v2 文档页面的控制台错误和渲染问题 触发条件：
  • 推送到 main
  • 拉取请求到 main 或 docs-v2
它做什么：
  1. 启动 Mintlify 开发服务器
  2. 在所有页面上运行 Puppeteer 测试
  3. 将结果作为 PR 注释发布
  4. 将详细的测试报告作为工件上传
**手动执行：**在推送/拉取请求时自动运行 必需的机密信息: 无 输出:
  • 带有测试结果的拉取请求评论
  • 工件: v2-page-test-report.json

​
更新 Livepeer 发布版本

文件： .github/workflows/update-livepeer-release.yml 目的： 自动更新全局文件中的最新 Livepeer 发布版本 触发条件：
  • 每 30 分钟（定时）
  • 从 GitHub Actions UI 手动分发
它的工作原理：
  1. 从 livepeer/go-livepeer GitHub 仓库
  2. 与 snippets/automations/globals/globals.mdx
  3. 中的当前版本进行比较
  4. 提交并推送更改
手动执行:
  1. 转到操作 → 更新 Livepeer 发布版本
  2. 点击“运行工作流”
所需的密钥: 无（使用GITHUB_TOKEN) 输出文件: snippets/automations/globals/globals.mdx

​
Discord 问题接收（第一阶段）

文件: .github/workflows/discord-issue-intake.yml 目的: 从通过 repository_dispatch 触发器:
  • repository_dispatch 类型为 discord-issue-intake
它的作用是:
  1. 验证模板的分发有效负载模式和必需字段 docs_page_issue
  2. 拒绝仅包含占位符或涉及安全敏感内容的请求
  3. 使用 correlation_id 问题正文中的标记
  4. 使用模板对齐的标题和基础标签创建问题
  5. 保留动态标签映射 (area:*, classification:*, priority:*, kind:*) 到 issue-auto-label.yml
维护者注释（模式 + 兼容性）:
  • 支持 schema_version 1.0.0 和 1.1.0
  • 1.1.0 添加所需的 fields.classification 用于 docs_page_issue
  • 1.0.0 payloads 仍对向后兼容有效，并且在没有的情况下会产生问题Classification 部分（索引器会将这些标记为未分类，直到进行分类）
  • 如果您在问题表单中更改字段名称或部分标题，请更新以下内容：
    • .github/workflows/discord-issue-intake.yml（payload 验证 + 生成的正文标题）
    • .github/workflows/issue-auto-label.yml（部分解析 / 标签映射）
  • 保持问题正文标题准确（例如### Classification, ### Priority) 因为自动标签解析是基于标题的
如何安全地推出未来的模式更改：
  1. 在 “.github/workflows/discord-issue-intake.yml
  2. 保留之前的模式版本，直到所有分发发送者都升级
  3. 更新 snippets/automations/scripts/n8n/Discord-Issue-Intake.json 以发出新版本和字段
  4. 验证测试分发是否创建了预期的标题和标签
必需的机密:
  • 无（使用 repository-dispatch 调用者令牌和 GitHub Actions GITHUB_TOKEN)
相关文件:
  • snippets/automations/scripts/n8n/Discord-Issue-Intake.json
  • snippets/assets/scripts/n8n/README-discord-issue-intake-workflow.md
  • .github/workflows/issue-auto-label.yml

​
问题自动标注

文件: .github/workflows/issue-auto-label.yml 目的: 解析问题表单正文并为文档分类添加/移除管理标签。 管理标签族:
  • area:*
  • classification:* (严重性/影响)
  • priority:*（维护者安排）
  • kind:*（文档页面问题子类型）
  • scope:*
维护者备注（重要）：
  • 解析基于问题正文中的精确Markdown标题（例如### Area，### Classification，### Priority)
  • 如果在任何问题模板中重命名了标题，请更新getSection(...) 使用和 required-section 列表中的此工作流
  • 旧版问题兼容性是故意的:
    • Classification 仅在问题正文已包含### Classification 部分时才被视为必需
    • 这可以防止旧问题在重新分类编辑时被自动标记status: needs-info在重新分类编辑时
  • 工作流通过检查隐藏标记来跳过 docs-v2 顶级问题索引:
    • <!-- docs-v2-issue-indexer -->
    • 在不更新此工作流和索引器工作流的情况下，请勿删除或重命名此标记
编辑后的手动验证检查清单:
  1. 从每个受影响的模板打开一个测试问题（或编辑现有测试问题正文）
  2. 确认 classification:* 和 priority:* 标签都已应用
  3. 更改问题正文中的分类并确认旧的 classification:* 标签已被移除
  4. 确认 docs-v2 索引问题不会自动被标记为 status: needs-triage

​
Docs v2 Issue Indexer

文件: .github/workflows/docs-v2-issue-indexer.yml 目的: 维护一个滚动的顶级 GitHub 问题索引docs-v2 问题（开放 + 最近关闭） 触发条件:
  • issues事件：打开/编辑/标记/取消标记/重新打开/关闭
  • 每6小时调度一次
  • 手动分发
它会做什么：
  1. 通过问题正文中的隐藏标记（“<!-- docs-v2-issue-indexer -->”) 找到索引问题
  2. 如果不存在，则创建索引问题
  3. 查询所有打开的 docs-v2 问题和最近关闭的 docs-v2 问题（默认 30 天窗口）
  4. 生成摘要统计 + 分解表 + 问题表
  5. 仅在内容更改时更新同一问题正文
维护者注释（安全操作）：
  • 隐藏标记是定位索引问题的唯一真实来源。除非您同时更新以下内容，否则请保持其稳定：
    • .github/workflows/docs-v2-issue-indexer.yml
    • .github/workflows/issue-auto-label.yml
  • 最近关闭的窗口由RECENTLY_CLOSED_DAYS 控制
  • 工作流有意地从计数/表格中排除索引问题本身，即使它具有docs-v2 标签
  • 工作流通过提前退出来跳过自我触发循环，如果触发的问题正文已经包含索引标记，则直接退出
  • 如果生成的问题正文似乎已过时，请使用操作 → 文档 v2 问题索引器 → 运行工作流
操作故障排除:
  • 重复的索引问题:
    • 确保只有一个问题包含标记<!-- docs-v2-issue-indexer -->
    • 从重复项中移除标记，然后手动运行工作流
  • 分解中的缺失标签:
    • 检查.github/workflows/issue-auto-label.yml管理的前缀和标签解析
    • 验证问题正文标题是否仍然符合解析器的预期
  • 意外的“未分类”开放问题:
    • 这些通常是遗留问题（未分类）或从较旧的 Discord 收集模式创建的问题1.0.0

​
数据获取工作流（GitHub Actions & n8n 可用）

GitHub Actions 实现使用按数据源拆分的专用工作流（update-forum-data.yml, update-ghost-blog-data.yml, 和 update-youtube-data.yml）。这些流程的 n8n 版本也得到维护，供希望使用外部自动化编排的团队使用。

​
更新论坛数据

文件: .github/workflows/update-forum-data.yml 状态: ⚠️ n8n 的替代方案 - 查看工作流文件中的说明 **目的:**从 Livepeer 论坛获取最新的论坛主题 触发条件:
  • 每天 UTC 时间午夜（计划任务）
  • 手动触发
它会做什么:
  1. 运行 .github/scripts/fetch-forum-data.js
  2. 更新 snippets/automations/forum/forumData.jsx
  3. 如果检测到更改则提交并推送
必需的密钥:
  • DOCS_V2 - 用于文档仓库访问的 GitHub 令牌
  • GHOST_CONTENT_API_KEY - Ghost 内容 API 密钥，由 .github/scripts/fetch-ghost-blog-data.js
注意： GitHub Actions 和 n8n 工作流均可用于此功能。使用您偏好的一种即可。

​
更新 Ghost 博客数据

文件： .github/workflows/update-ghost-blog-data.yml 状态： ⚠️ n8n 的替代方案 - 查看工作流文件中的说明 目的: 从 Ghost CMS 获取最新的博客文章 触发器:
  • 每天 UTC 时间午夜（计划任务）
  • 手动分发
它做什么:
  1. 运行 .github/scripts/fetch-ghost-blog-data.js
  2. 更新 snippets/automations/blog/ghostBlogData.jsx
  3. 如果检测到更改则提交并推送
所需的密钥:
  • DOCS_V2 - 用于文档仓库访问的 GitHub 令牌
注意: 此功能有两种 GitHub Actions 和 n8n 工作流。使用您喜欢的任意一种。

​
更新 YouTube 数据

文件: .github/workflows/update-youtube-data.yml 状态: ⚠️ n8n 的替代方案 - 查看工作流文件中的说明 目的: 从 Livepeer 频道获取最新的 YouTube 视频 触发器:
  • 每周日午夜 UTC（已安排）
  • 手动分发
它会做什么：
  1. 运行 .github/scripts/fetch-youtube-data.js
  2. 过滤掉短视频（≤60 秒）
  3. 更新 snippets/automations/youtube/youtubeData.jsx
  4. 如果检测到更改，则提交并推送
所需的密钥:
  • YOUTUBE_API_KEY - YouTube Data API v3 密钥
注意: GitHub Actions 和 n8n 工作流都可用于此功能。使用您喜欢的即可。

​
n8n 自动化工作流

n8n 工作流是位于 snippets/automations/scripts/n8n/ 的 JSON 文件。这些工作流在外部 n8n 实例上运行，并可以在该实例中导入/配置。
Most n8n workflows are currently inactive ("active": false). Only active workflows are documented below. See audit report for full status.

​
活动的 n8n 工作流

​
Luma 事件到 Mintlify

文件: snippets/automations/scripts/n8n/Luma-To-Mintlify.json 状态: ✅ 活跃 用途: 获取 Luma 日历事件并更新文档 计划: 每周 它做什么：
  1. 从 Luma API 获取 iCal 数据
  2. 解析事件（即将开始和过去的）
  3. 生成 JSX 数据文件
  4. 提交到 GitHub 的 docs-v2 分支
输出: snippets/automations/luma/lumaEventsData.jsx 如何使用:
  1. 将 JSON 文件导入 n8n 实例
  2. 配置 GitHub 凭据
  3. 设置 Luma 日历 ID
  4. 激活工作流
所需凭据：
  • GitHub API 令牌（具有写入权限）
  • Luma 日历 ID：cal-X93qV3PuUH0wq0f

​
展示项目流水线

文件： snippets/automations/scripts/n8n/Showcase_To_Mintlify_Pipeline.json 状态： ✅ 活跃 用途: 处理展示项目提交、批准和更新 触发条件: Google Sheets 触发器（每小时轮询） 它做什么：
  1. 监控 Google 表格中的新项目提交
  2. 验证提交数据
  3. 发送 Discord 通知以获得批准
  4. 从 Google Drive 下载媒体文件
  5. 更新 snippets/automations/showcase/showcaseData.jsx当获得批准时
  6. 向提交者发送通知
输出: snippets/automations/showcase/showcaseData.jsx 如何使用:
  1. 将 JSON 文件导入 n8n 实例
  2. 配置 Google Sheets、Discord 和 GitHub 凭据
  3. 设置 Google 表单以接收提交
  4. 激活工作流
所需凭据:
  • Google Sheets OAuth2
  • Discord Bot API
  • GitHub API 令牌
  • Google Drive OAuth2
依赖项:
  • 用于项目提交的 Google 表单
  • 用于跟踪提交的 Google 表格
  • 用于审批流程的 Discord 服务器

​
Discord 问题接收（第一阶段）

文件： snippets/automations/scripts/n8n/Discord-Issue-Intake.json 状态： ✅ 已准备好导入（默认为非活动状态） 用途： 处理 Discord slash-command 输入（/docs-issue）并将标准化的问题有效负载中继到 GitHub Actions。 触发条件: Discord 交互 webhook (POST) 它的作用是:
  1. 验证 Discord 请求签名
  2. 强制执行频道允许列表和每用户速率限制
  3. 通过模态窗口收集长格式字段
  4. 显示带有推断标签的预览以及确认/取消按钮
  5. 发送repository_dispatch到 GitHub (discord-issue-intake)
  6. 轮询已创建的问题并发送包含问题URL的后续消息
运行手册:
  • snippets/assets/scripts/n8n/README-discord-issue-intake-workflow.md
所需的环境变量:
  • DISCORD_PUBLIC_KEY
  • ALLOWED_CHANNEL_IDS
  • GITHUB_DISPATCH_TOKEN
  • GITHUB_OWNER
  • GITHUB_REPO
  • GITHUB_DISPATCH_EVENT_TYPE
  • SECURITY_REPORT_URL
  • RATE_LIMIT_WINDOW_SEC
  • RATE_LIMIT_MAX
  • DISCORD_ISSUE_SCHEMA_VERSION
  • GITHUB_POLL_ATTEMPTS
  • GITHUB_POLL_DELAY_MS

​
额外的 n8n 工作流（GitHub Actions 的替代方案）

以下 n8n 工作流提供了 GitHub Actions 的替代实现。两者都为灵活性而维护:
  • Ghost-to-Mintlify.json - 获取 Ghost 博客文章（替代 update-ghost-blog-data.yml)
  • 论坛-到-Mintlify-最新主题.json - 获取论坛主题（替代）update-forum-data.yml)
  • YouTube-到-Mintlify.json - 获取YouTube视频（替代）update-youtube-data.yml)
  • Discord_Announce_to_Mintlify.json - 获取 Discord 公告 (仅 n8n - 没有 GitHub Action 对应项)
  • Discord-Issue-Intake.json - Discord 问题接收中继 (与 .github/workflows/discord-issue-intake.yml)
Repository Configuration: Some n8n workflows may be configured to write to DeveloperAlly/livepeer-automations instead of livepeer/docs. Before activating, verify the GitHub node is configured to write to the correct repository (livepeer/docs) and branch (docs-v2).

​
实用工作流

​
MP4 转 GIF 转换器

文件: snippets/automations/scripts/n8n/mp4-to-gif.json 目的: 通过 webhook 将 MP4 视频转换为 GIF 格式 触发: Webhook (POST 请求) 它的作用是:
  1. 接受视频 URL 或本地路径
  2. 如果提供了 URL，则下载视频
  3. 使用 FFmpeg 将其转换为 GIF
  4. 返回 GIF 文件或文件路径
如何使用：
  1. 将 JSON 文件导入 n8n 实例
  2. 配置 Webhook URL
  3. 发送包含视频 URL 或本地路径的 POST 请求
  4. 接收响应中的 GIF
参数：
  • video_url（可选）- 视频文件的URL
  • local_path（可选）- 本地文件路径
  • fps（默认：10）- 每秒帧数
  • width（默认：480）- 输出宽度
  • start_time（默认：“0”）- 视频中的开始时间
  • duration（可选）- 转换时长
  • optimize（默认：true）- 使用调色板优化
  • output_path（可选）- 输出文件路径

​
脚本

脚本根据其用途组织到几个目录中。所有脚本都使用基于 git 的仓库根检测，并回退到paths.config.json.

​
内容生成脚本

​
生成SEO元数据

文件: tools/scripts/snippets/generate-seo.js 目的: 自动为MDX文档页面生成和更新SEO元数据 用法: 
# Dry run (preview changes)
node tools/scripts/snippets/generate-seo.js --dry-run

# Process all files
node tools/scripts/snippets/generate-seo.js

# Process single file
node tools/scripts/snippets/generate-seo.js --file=v2/home/mission-control.mdx
它的作用:
  1. 扫描所有 MDX 文件v2/pages/
  2. 生成keywords 从文件路径、标题和描述
  3. 添加og:image 使用特定领域的或默认的社交预览图片
  4. 保留现有的 SEO 元数据（如果已存在则不会覆盖）
输出: 更新 MDX 文件中的 frontmatter 何时运行:
  • 在创建新的文档页面后
  • 在更新页面标题或描述时
  • 在部署前以提高 SEO

​
生成 API 文档

文件: tools/scripts/snippets/generate-api-docs.sh 目的: 从 OpenAPI 规范文件生成 Mintlify API 文档 用法: 
./tools/scripts/snippets/generate-api-docs.sh <openapi-spec> <output-dir> <api-name> [github-repo-url]
示例: 
./tools/scripts/snippets/generate-api-docs.sh \
  ai/worker/api/openapi.yaml \
  v2/pages/04_gateways/api-reference/AI-API \
  "AI API" \
  "https://github.com/livepeer/ai-worker"
它能做什么：
  1. 读取 OpenAPI 规范（YAML 或 JSON）
  2. 创建一个着陆页，其中包含 CardGroups，链接到每个端点（按标签分组）
  3. 创建individual MDX pages for each endpoint with openapi: METHOD /path frontmatter
  4. Outputs a docs.json navigation snippet ready to copy-paste
输出结构: 
output-dir/
├── ai-api.mdx           # Landing page with Base URLs + CardGroups
├── text-to-image.mdx    # openapi: post /text-to-image
├── image-to-image.mdx   # openapi: post /image-to-image
└── ...
运行后: 将输出的 JSON 片段复制到你的 docs.json 导航中.

​
更新组件库

文件: tools/scripts/snippets/update-component-library.sh 目的: 从当前snippets/components/ 文件夹结构 用法: 
./tools/scripts/snippets/update-component-library.sh
它会做:
  1. 扫描snippets/components/ 目录结构
  2. 生成一个 <Tree> 组件，包含所有文件夹和文件
  3. 更新 snippets/snippetsWiki/componentLibrary/index.mdx
输出: 更新自动生成的部分在 snippets/snippetsWiki/componentLibrary/index.mdx 之间的 AUTO-GENERATED 注释。 何时运行:
  • 在添加新组件到 snippets/components/
  • 在重新组织组件文件夹结构后
  • 在重命名或删除组件文件后

​
数据获取脚本

​
获取 OpenAPI 规范

文件: tools/scripts/snippets/fetch-openapi-specs.sh 目的: 从 livepeer/ai-runner 仓库获取 OpenAPI 规范文件 用法: 
./tools/scripts/snippets/fetch-openapi-specs.sh
它做什么：
  1. 从外部存储库下载 OpenAPI 规范
  2. 保存到 ai/worker/api/
下载到 ai/worker/api/:
  • openapi.yaml - AI Runner API 规范
  • gateway.openapi.yaml - AI Gateway API 规范

​
获取外部文档

文件: tools/scripts/snippets/fetch-external-docs.sh 目的: 从其他 Livepeer 仓库获取外部文档文件并对其进行清理，以实现 MDX 兼容性 用法: 
./tools/scripts/snippets/fetch-external-docs.sh
它做什么：
  1. 从外部仓库下载文档
  2. 对内容进行清理以兼容 MDX
  3. 保存到 snippets/external/
下载到 snippets/external/:
  • wiki-readme.mdx - livepeer/wiki README
  • awesome-livepeer-readme.mdx - livepeer/awesome-livepeer README
  • whitepaper.mdx - Livepeer 白皮书
  • gwid-readme.mdx - videoDAC/livepeer-gateway README
  • box-additional-config.mdx - go-livepeer 箱子配置
清理包括：
  • 转义 MDX 中的花括号
  • 移除 HTML 注释
  • 将 HTML 标签转换为 Markdown 等效格式

​
获取 LPT 交易所

文件： tools/scripts/snippets/fetch-lpt-exchanges.sh 用途： 从 CoinGecko API 获取 LPT 交易所列表并更新交易所页面 ** 使用方式:** 
./tools/scripts/snippets/fetch-lpt-exchanges.sh
** 它的功能是:**
  1. 从 CoinGecko API 获取 Livepeer 代币的实时数据
  2. 生成带有交易量和信任评分的中心化交易所（CEX）表格
  3. 追加去中心化交易所（DEX）信息和合约地址
  4. 更新 v2/pages/06_delegators/token-resources/lpt-exchanges.mdx
何时运行:
  • 定期更新交易所列表
  • 在主要版本发布前确保数据最新

​
测试脚本

​
V2 浏览器扫描脚本 (test:v2-pages)

文件: tools/scripts/test-v2-pages.js 目的: 测试所有 v2 页面的控制台错误和渲染问题 用法: 
cd tools && npm run test:v2-pages
# or
node tools/scripts/test-v2-pages.js
它的作用:
  1. 提取所有 v2 页面docs.json
  2. 启动 Mintlify 开发服务器（如果未运行）
  3. 使用 Puppeteer 测试每个页面
  4. 报告控制台错误、页面错误和请求失败
  5. 生成详细的 JSON 报告
先决条件：
  • npx mintlify dev必须正在运行（或设置 MINT_BASE_URL环境变量）
  • Puppeteer 已安装（npm install）
输出：
  • 带有通过/失败状态的控制台输出
  • v2-page-test-report.json - 详细的测试结果
环境变量:
  • MINT_BASE_URL - Mintlify 开发服务器的基准 URL（默认: http://localhost:3000)

​
GitHub 脚本（由工作流使用）

这些脚本由 GitHub Actions 工作流使用，通常不应手动运行:
  • .github/scripts/fetch-forum-data.js - 获取论坛数据（由 “update-forum-data.yml”) 使用
  • .github/scripts/fetch-ghost-blog-data.js - 获取 Ghost 博客数据（由 “update-ghost-blog-data.yml”) 使用
  • .github/scripts/fetch-youtube-data.js - 获取 YouTube 数据（由 “update-youtube-data.yml”) 使用

​
预提交钩子

预提交钩子在您尝试提交代码时自动运行。它们强制执行风格指南合规性并验证代码质量。

​
安装

必须执行： 您必须在进行任何提交之前安装这些钩子： 
./.githooks/install.sh
或手动安装： 
cp .githooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

​
检查内容

​
风格指南合规性

预提交钩子检查:
  • ❌ ThemeData 使用 - 块已弃用 ThemeData 导入来自 themeStyles.jsx
  • ❌ 硬编码颜色 - 关于应使用 CSS 自定义属性的十六进制颜色的警告
  • ⚠️ 相对导入 - 警告关于相对路径（应使用从根目录开始的绝对路径)
  • ⚠️ @mintlify/components 导入 - 警告关于不必要的导入（组件是全局的）
  • ⚠️ React 钩子导入 - 提醒不要导入不必要的 React（钩子是全局的）

​
验证脚本

该钩子还会运行.githooks/verify.sh 用于检查：
  • ✅ MDX 语法 - 验证 frontmatter 和基本 MDX 结构
  • ✅ JSON 语法 - 验证 JSON 文件可解析
  • ✅ Shell 脚本语法 - 验证 shell 脚本 with bash -n
  • ✅ JavaScript 语法 - 验证 JS 文件 with node --check
  • ✅ Mintlify 配置 - 验证 docs.json/mint.json 语法
  • ✅ ** 导入路径** - 确保代码片段导入使用绝对路径
  • ✅ 浏览器验证 - 在无头浏览器中测试 MDX 文件（如果 “npx mintlify dev” 正在运行）

​
违反时会发生什么

如果您尝试提交违反风格指南的代码：
  1. 提交已 被阻止
  2. 您会收到一条详细的错误信息，列出所有违规内容
  3. 您必须在再次提交之前修复这些违规内容

​
浏览器验证

这些钩子包括无头浏览器验证，用于测试MDX文件在浏览器中实际是否可以渲染。这可以捕获：
  • 组件中的运行时错误
  • 导入失败
  • 控制台错误
  • 渲染失败
注意： 浏览器验证需要 npx mintlify dev正在运行。如果未运行，检查将被跳过（不会阻止提交）。

​
绕过钩子（不推荐）

**⚠️ 警告：**只有在有正当理由并且了解后果的情况下才绕过钩子。 对于人工的.allowlist编辑，请使用： 
git commit -m "Update .allowlist" --trailer "allowlist-edit=true"
这将保持所有其他预提交检查功能启用。 对于人为的有意删除文件，请使用： 
git commit -m "Remove obsolete files" --trailer "allow-deletions=true"
这也将保持所有其他预提交检查功能启用。 
# Bypass pre-commit hook
git commit --no-verify -m "message"
为什么这样做不推荐：
  • 违反样式指南合规性
  • 可能会引入破坏构建的错误
  • 使代码审查更困难
  • 可能导致其他开发人员出现问题
有关挂钩的完整详细信息，请参阅Git 挂钩文档。

​
运行自动化

​
手动执行

​
GitHub Actions

  1. 转到操作 选项卡在 GitHub 仓库中
  2. 选择要运行的工作流
  3. 点击 “运行工作流” 按钮
  4. 选择分支和任何必需的输入
  5. 点击 “运行工作流” 开始

​
脚本

大多数脚本可以直接从命令行运行： 
# From repository root
node tools/scripts/snippets/generate-seo.js
./tools/scripts/snippets/fetch-lpt-exchanges.sh
npm run test:v2-pages

​
n8n 工作流

  1. 将 JSON 文件导入 n8n 实例
  2. 配置凭据和设置
  3. 激活工作流
  4. 在 n8n 仪表板中监控执行

​
计划执行

  • GitHub Actions - 使用 schedule 通过 cron 语法触发
  • n8n Workflows - 使用定时触发器节点设置间隔或cron

​
监控

  • GitHub Actions - 在Actions选项卡中检查工作流运行和日志
  • n8n - 检查 n8n 仪表板以查看执行历史记录
  • 脚本 - 检查控制台输出和生成的文件

​
故障排除

​
GitHub Actions 未运行

问题: 工作流在推送/拉取请求时不会触发 ** 解决方案:**
  1. 检查工作流文件语法（YAML 必须有效）
  2. 验证触发条件是否与您的分支/事件匹配
  3. 检查操作选项卡中的错误信息
  4. 确保工作流文件位于 .github/workflows/ 目录

​
脚本失败

** 问题:** 脚本错误或未产生预期输出 ** 解决方案:**
  1. 检查脚本是否有执行权限: chmod +x script.sh
  2. 验证 Node.js 版本是否符合脚本要求
  3. 检查缺失的依赖项: npm install
  4. 查看脚本文档中的先决条件
  5. 如果可用，请以详细输出运行

​
预提交钩子未运行

问题: Hook 在提交时不会执行 解决方案:
  1. 验证 Hook 是否已安装: ls -la .git/hooks/pre-commit
  2. 检查 Hook 是否可执行: chmod +x .git/hooks/pre-commit
  3. 重新安装: ./.githooks/install.sh
  4. 检查 .git/hooks/pre-commit 文件存在

​
n8n 工作流问题

问题: 工作流失败或无法更新文件 解决方案:
  1. 检查 n8n 仪表板中的工作流是否处于活动状态
  2. 验证凭据配置正确
  3. 检查 n8n 中的执行日志
  4. 验证 GitHub 令牌具有写入权限
  5. 检查分支名称与工作流配置匹配

​
缺少密钥/秘密

**问题:**工作流因身份验证错误而失败 解决方案:
  1. 前往仓库设置 → 秘密和变量 → 操作
  2. 添加所需的秘密（例如：YOUTUBE_API_KEY, SPEAKEASY_API_KEY)
  3. 验证密钥名称与工作流文件完全匹配
  4. 对于 n8n，在 n8n 仪表板中配置凭据

​
最佳实践

​
何时使用什么

GitHub Actions - 用于:
  • ✅ 简单的数据获取（API 调用，文件更新）
  • ✅ 本地仓库操作（提交，拉取请求，检查）
  • ✅ CI/CD 工作流（测试，验证）
  • ✅ 仅需要 GitHub 访问权限的定时任务
  • ✅ 当你希望所有内容都在仓库中
n8n - 用于:
  • ✅ 复杂的多步骤工作流
  • ✅ 外部服务集成（Discord、Google Sheets、Google Forms）
  • ✅ 带有通知的审批流程
  • ✅ 需要用户交互的工作流
  • ✅ 当你需要更多的可视化工作流管理
脚本 - 用于:
  • ✅ 一次性任务和内容生成
  • ✅ 本地开发和测试
  • ✅ 手动数据更新
预提交钩子 - 用途:
  • ✅ 强制执行代码质量和风格指南合规性
  • ✅ 在提交前捕获错误

​
保持自动化更新

  1. 审查审计报告 - 检查 docs/PLAN/reports/ 自动化状态
  2. 部署前测试 - 在提交前在本地运行脚本
  3. 监控工作流运行 - 定期检查 GitHub Actions 和 n8n 仪表板
  4. 更新文档 - 保持此指南与自动化流程同步

​
安全注意事项

  • 永远不要提交机密信息 - 使用 GitHub Secrets 或 n8n 凭据
  • 审查自动提交 - 注意自动提交的脚本
  • 限制代币权限 - 为 API 令牌使用最小权限访问
  • 定期审计 - 定期审查自动化访问和权限

​
相关文档

​
获取帮助

如果您遇到自动化相关的问题:
  1. 查看此指南以获取故障排除步骤
  2. 查看审计报告以了解已知问题
  3. 检查工作流/脚本文档
  4. 查看执行日志（GitHub Actions 或 n8n）
  5. 在仓库或社区频道中提问
Last modified on March 1, 2026