修复失效链接

jamdesk fix 用于修复 jamdesk broken-links 报告的问题。它读取相同的警告，并在找到唯一明确的正确目标时重写链接。对于存在歧义的情况，它不会改动，留待人工审查。

它可以修复两类失效的内部链接：

• 拼写错误的锚点：片段是目标页面上某个真实标题的明显拼写错误（例如 #instalation → #installation）
• 跨语言锚点漂移：翻译页面重命名了标题，但该语言中的链接仍指向旧的英文片段（例如 /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia）

步骤 1：查找失效链接

运行 jamdesk broken-links 查看需要修复的内容：

jamdesk broken-links

检查输出。jamdesk fix 会处理那些能够将可能的锚点匹配到真实标题的警告。

步骤 2：预览修复内容

使用 --dry-run 运行，查看将会更改的内容而不写入文件：

jamdesk fix --dry-run

示例输出：

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

逐一检查计划中的修复。如果某项更改看起来不对，请手动修复该链接。

步骤 3：应用修复

去掉 --dry-run 运行即可应用。CLI 会要求你确认：

jamdesk fix

Apply 1 fix(es) to local files? (y/N)

按 y 写入更改。在 CI 或脚本中可使用 -y 跳过提示：

jamdesk fix -y

命令随后会输出：

Fixed 1 file(s); 0 warning(s) left for manual review.

对于目标存在歧义的警告，jamdesk fix 会将其保留，供你手动修复。

步骤 4：检查差异并提交

提交前检查更改：

git diff

确认每个重写后的链接都指向你预期的位置。然后提交：

git add -A
git commit -m "fix(docs): auto-fix broken internal links"

配合 AI 代理使用

jamdesk fix --json 会将修复计划以单个 JSON 文档的形式输出，供 Claude Code 等编码代理使用。它不写入任何文件，也不提出问题，由代理进行编辑。需要 CLI 1.1.229 或更高版本。

jamdesk fix --json

示例输出（已截取）：

{
  "version": 1,
  "fixes": [
    {
      "type": "broken_link",
      "file": "fr/ai/overview.mdx",
      "line": 9,
      "oldText": "/fr/ai/selectors#ai-strategies",
      "newText": "/fr/ai/selectors#stratégies-ia",
      "resolvedBy": "deterministic"
    },
    {
      "type": "description",
      "file": "setup.mdx",
      "text": "How to set up the CLI.",
      "resolvedBy": "ai"
    }
  ],
  "unfixable": [
    {
      "type": "broken_link",
      "file": "quickstart.mdx",
      "line": 4,
      "link": "/missing",
      "reason": "points at a page that doesn't exist; create it or fix the link"
    }
  ],
  "notes": []
}

该文档包含三个列表：

• fixes：需要执行的编辑。对于 broken_link，将该行中的 oldText 替换为 newText。description 是 AI 为页面 frontmatter 提出的建议，因此代理应在写入前先向你展示。
• unfixable：需要手动修复的问题，每项附有原因。
• notes：本次运行的消息，例如 AI 修复被跳过的情况。

如果运行失败，输出为 {"version": 1, "error": "..."}，命令以退出码 1 结束。

开始时，可以这样对代理说："运行 jamdesk fix --json，应用链接修复，并在添加描述前向我展示。"

选项

接下来做什么？