# PR #19742 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Add Lychee Doc Links Check to Local and CI
- 合并时间：2026-03-25 04:48
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/19742

---

# 执行摘要
本 PR 在 sglang 仓库中引入了 Lychee 工具，用于自动化文档链接检查。通过分离本地离线检查和 CI 在线检查，在提升文档可靠性的同时避免阻塞贡献者工作流。关键变更包括新增配置文件和夜间 CI 工作流，并修复了多个文档中的 broken 链接。

# 功能与动机
此 PR 的动机是改善文档链接的可靠性，同时保持贡献者工作流程轻量级。根据 PR body，CI 将强制执行全链接检查（包括离线引用和在线外部链接），而本地 lychee 设置为仅手动运行，以避免因平台或网络问题阻塞本地提交。这跟随了 @zijiexia 之前的修复方向，旨在减少 broken 链接对用户体验的影响。

# 实现拆解
实现方案按模块拆解如下：
- **本地配置**：添加 `.github/linters/lychee.toml`，设置 `offline = true` 进行快速离线检查，排除本地端点（如 localhost）。
- **CI 配置**：添加 `.github/linters/lychee-ci.toml`，设置 `offline = false` 进行在线验证，包含重试机制和排除列表（如 Intel、OpenAI 文档等噪声端点）。
- **pre-commit 集成**：修改 `.pre-commit-config.yaml`，将 lychee 钩子设置为 `stages: [manual]`，使本地检查可选。
- **CI 工作流**：在 `.github/workflows/lint.yml` 中添加离线检查步骤；新增 `.github/workflows/nightly-link-check.yml` 夜间工作流，使用 GITHUB_TOKEN 执行在线检查。
- **文档更新**：更新 `docs/developer_guide/contribution_guide.md`，提供链接检查命令指南。
- **链接修复**：修复多个文档文件（如 `docs/basic_usage/deepseek_v3.md`、`examples/runtime/README.md`）中的过期或错误链接。

# 评论区精华
review 讨论中，最值得关注的交锋包括：
- zijiexia 建议：'imho, I think a nightly link check ci might be a better choice as the link should not change really frequently.' 这引导了将在线检查移至夜间 CI 的设计决策，避免日常 CI 延迟。
- 关于不必要更改的讨论，如 `.gitignore` 添加文件，zijiexia 评论：'Maybe we don't need to add this?' 最终作者简化了变更。
- 安全方面，zijiexia 提出：'Maybe we need to pin lychee-action to a commit SHA for supply chain safety.' 作者在后续提交中固定了版本。
- 正则表达式检查：zijiexia 询问：'Can you double check on this regex?' 作者回应并修复了 `example_image.png?raw=true` 的排除模式。

# 风险与影响
**技术风险**：
- CI 工作流变更可能引入失败风险，尤其是夜间检查依赖外部网络，排除列表需持续维护以避免误报。
- 依赖 lychee-action 存在 supply chain 风险，已通过 pin 版本缓解。
- 本地手动检查可能被忽略，导致链接问题延迟发现。

**影响分析**：
- 对贡献者：需要适应新命令，但本地提交不受阻；CI 作为最终关口，确保链接质量。
- 对系统：提升文档健壮性，减少用户访问 broken 链接的概率。
- 对团队：自动化检查降低维护成本，夜间模式平衡检查频率与资源使用。

# 关联脉络
从历史 PR 看，本 PR 与仓库近期的 CI 和文档改进趋势一致。例如：
- PR #21334 优化了 multimodal CI 以跳过文档文件变更，与本 PR 的链接检查互补，共同提升 CI 效率。
- PR #21283 涉及文档技能更新，反映团队对文档质量的重视。
- PR #20294 扩展 CI 测试套件，展示仓库在 CI 工作流上的持续投资。
这些关联表明，本 PR 是 sglang 在基础设施和文档维护方面演进的一部分，旨在构建更健壮的开发者生态系统。