pr-gfm-validator

PR GFM 链接验证器

验证并自动转换拉取请求描述中的 GFM 链接，以防止出现 404 错误。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

使用此技能的时机

出现以下情况时会触发此技能：

• 从功能分支创建拉取请求
• 讨论 PR 描述或正文内容
• 提及 GFM 链接、PR 链接或链接验证
• 使用 gh pr create 或 gh pr edit

问题

PR 描述中的仓库相对链接会解析到基分支（main），而非功能分支：

PR 正文中的链接	GitHub 解析到的地址	结果
[ADR](/docs/adr/file.md)	/blob/main/docs/adr/file.md	404（文件仅存在于功能分支中）

解决方案

将仓库相对链接转换为包含正确分支的绝对 blob URL：

/docs/adr/file.md
    ↓
https://github.com/{owner}/{repo}/blob/{branch}/docs/adr/file.md

---

工作流

步骤 1：检测上下文

执行任何 PR 操作前，先收集仓库上下文：

/usr/bin/env bash << 'PREFLIGHT_EOF'
# Get repo owner and name
gh repo view --json nameWithOwner --jq '.nameWithOwner'

# Get current branch
git rev-parse --abbrev-ref HEAD

# Check if on feature branch (not main/master)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "On default branch - no conversion needed"
  exit 0
fi
PREFLIGHT_EOF

步骤 2：识别要转换的链接

扫描 PR 正文，查找符合以下模式的 GFM 链接：

转换以下模式：

• /path/to/file.md - 相对于仓库根目录
• ./relative/path.md - 相对于当前目录
• ../parent/path.md - 相对于父目录

跳过以下模式：

• https://... - 已是绝对 URL
• http://... - 已是绝对 URL
• #anchor - 页面内锚点
• mailto:... - 邮件链接

步骤 3：构造 Blob URL

对每个要转换的链接：

# Pattern
f"https://github.com/{owner}/{repo}/blob/{branch}/{path}"

# Example
owner = "example-org"
repo = "research-repo"
branch = "feat/2025-12-01-eth-block-metrics"
path = "docs/adr/2025-12-01-file.md"

# Result
"https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics/docs/adr/2025-12-01-file.md"

步骤 4：应用转换

替换 PR 正文中所有已识别的链接：

# Before

[Plugin Design](/docs/adr/2025-12-01-slug.md)

# After

[Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)

步骤 5：验证结果

转换后，确认：

1. 所有仓库相对链接均已转换为绝对 blob URL
2. 外部链接保持不变
3. 锚点链接保持不变

---

与 gh pr create 集成

创建 PR 时，自动应用此工作流：

/usr/bin/env bash << 'GIT_EOF'
# 1. Get context
REPO_INFO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
OWNER=$(echo "$REPO_INFO" | cut -d'/' -f1)
REPO=$(echo "$REPO_INFO" | cut -d'/' -f2)
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# 2. Process PR body (convert links)
# ... link conversion logic ...

# 3. Create PR with converted body
gh pr create --title "..." --body "$CONVERTED_BODY"
GIT_EOF

---

链接检测正则表达式

使用此正则表达式查找 GFM 链接：

\[([^\]]+)\]\((/[^)]+|\.\.?/[^)]+)\)

解析：

• \[([^\]]+)\] - 捕获链接文本
• \( - 左括号
• (/[^)]+|\.\.?/[^)]+) - 捕获以 /、./ 或 ../ 开头的路径
• \) - 右括号

---

示例

示例 1：简单的仓库相对链接

输入：

See the [ADR](/docs/adr/2025-12-01-eth-block-metrics.md) for details.

上下文：

• Owner：example-org
• Repo：research-repo
• Branch：feat/2025-12-01-eth-block-metrics-data-plugin

输出：

See the [ADR](https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics-data-plugin/docs/adr/2025-12-01-eth-block-metrics.md) for details.

示例 2：多个链接

输入：

## References

- [Plugin Design](/docs/adr/2025-12-01-slug.md)
- [Probe Integration](/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)

输出：

## References

- [Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)
- [Probe Integration](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)

注意：外部链接保持不变。

示例 3：凭据文件链接

输入：

**See [`.env.clickhouse`](/.env.clickhouse)** for credentials.

输出：

**See [`.env.clickhouse`](https://github.com/example-org/research-repo/blob/feat/branch/.env.clickhouse)** for credentials.

---

边缘情况

已在 main/master 分支上

• 完全跳过转换
• 仓库相对链接可以正常使用

PR 正文为空

• 无需转换
• 继续创建 PR

未找到 GFM 链接

• 无需转换
• 继续创建 PR

混合链接类型

• 仅转换仓库相对链接
• 保留外部 URL、锚点和 mailto 链接

---

修改后检查清单

修改此技能后：

1. 正则表达式模式仍能匹配预期的链接格式
2. 示例符合当前行为
3. 已记录边缘情况
4. 工作流步骤可执行

---

参考资料

• GitHub Blob URL
• GFM 链接语法
• gh CLI 文档

---

故障排查

问题	原因	解决方案
PR 合并后链接仍返回 404	文件尚未推送到分支	创建 PR 前先推送提交
正则表达式未匹配链接	内容中括号经过转义	使用原始字符串正则表达式模式
分支名称中包含斜杠	需要进行 URL 编码	构造 URL 时对分支名称进行编码
外部链接被转换	匹配模式过于宽泛	检查链接是否仅以 /、./ 或 ../ 开头
gh repo view 失败	当前目录不是 Git 仓库	在仓库根目录中运行
锚点链接失效	错误地将其纳入扫描	跳过以 # 开头的链接
检测到错误的仓库	远程仓库设置不正确	检查 git remote -v 的输出
转换重复	验证器运行了两次	转换前检查链接是否已是绝对链接

执行后的复盘

此技能完成后，在结束任务前进行复盘：

0. 确定自身位置。 — 在编辑前找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修正导致问题的指令。
2. 哪些做得比预期更好？ — 将其纳入推荐实践。
3. 有哪些偏差？ — 修正与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。 — 在演进日志中记录触发原因、修正内容和证据。

不要拖延。下一次调用会继承你留下的一切。