メニュー
当用户提到'链接检查'、'检查链接'、'断链'、'链接修复'、'fix links'、'check links'、'验证链接'、'死链'、'链接有效性'、'提交前检查'时，必须使用此技能。提供Markdown链接有效性检查与自动修复能力：本地文件引用验证、外部URL可达性检测、file:///绝对路径转相对路径、相对路径层级自动校正。不要手动查找断链——本Skill封装了缓存机制、并发检测、自动修复和dry-run预览，是提交前质量门禁的核心工具。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | link-check-cmd |
| version | 1.2.0 |
| description | 当用户提到'链接检查'、'检查链接'、'断链'、'链接修复'、'fix links'、'check links'、'验证链接'、'死链'、'链接有效性'、'提交前检查'时，必须使用此技能。提供Markdown链接有效性检查与自动修复能力：本地文件引用验证、外部URL可达性检测、file:///绝对路径转相对路径、相对路径层级自动校正。不要手动查找断链——本Skill封装了缓存机制、并发检测、自动修复和dry-run预览，是提交前质量门禁的核心工具。 |
| argument-hint | [路径] [--fix] [--check-external] [--dry-run] |
| user-invocable | true |
| paths | [".agents/scripts/check-links.py",".agents/scripts/lib/link_fixer.py"] |
| title | Link Check 链接检查与修复 Skill |
| x-toml-ref | ../../../.meta/toml/.agents/skills/link-check-cmd/SKILL.toml |
⚠️ 本Skill是脚本命令门面（L1索引层），遵循渐进式披露三层架构：
- L0：.agents/ONBOARDING.md（入口速查）
- L1：本文件（<500行，触发词+决策树+核心命令+安全清单）
- L2：脚本源码 check-links.py + link_fixer/（完整实现）
link-check-cmd
提供Markdown链接有效性检查与自动修复能力，支持两类链接、两种模式：
| 模式 | 推荐场景 | 优势 |
|---|---|---|
| 检查模式（默认） | ⭐ 提交前质量门禁、文档重构后验证 | 快速扫描，零风险，输出问题清单 |
| 修复模式（--fix） | ⭐ 文件移动/目录重构后断链修复 | 自动修复可修复问题，预览机制防误操作 |
| 外部链接检查（--check-external） | ⭐ 发布前完整验证、定期巡检 | HEAD请求+GET回退，7天缓存避免重复请求 |
核心功能：本地文件引用存在性检查 → 外部URL可达性检测 → 自动修复可修复断链（绝对路径转相对、层级校正、斜杠补全）→ 输出结构化报告。
为什么用本Skill而非手动查找？ 手动检查链接效率极低且容易遗漏——一个中型文档库可能有数百个链接，人工逐一点击不现实；外部链接检查有网络开销和频率限制问题。本Skill封装了并发检测、7天缓存、自动修复等机制，检查效率提升数十倍，且修复逻辑经过多轮验证（目录迁移场景是高频重灾区）。
当用户提到以下任何内容时触发：
check-links.py 脚本关于触发：即使没有明确说"用link-check命令"，只要涉及Markdown文档链接的有效性验证或修复，就应该使用本Skill。链接问题是文档重构后最高频的遗留问题，不要等到用户抱怨"点不开"才想起来检查。
需要检查/修复链接？
├─ 只是想看看有没有断链（不修改文件）？ → 检查模式（默认，第5.1节）
├─ 文件移动/重构后需要自动修复？ → 修复模式（先--dry-run预览，再--fix执行，第5.2节）
├─ 需要验证外部URL也能访问？ → 检查模式 + --check-external（第5.3节）
└─ 原子化拆分后的完整收尾？ → 优先使用 atomization-finalize-cmd（它内部会调用链接修复）
决策前输出CMD_START日志（session前缀 lnk-YYYYMMDD-<topic>）：
[CMD-LOG] | level=INFO | cmd=link-check | step=S0 | event=CMD_START | session=lnk-... | msg=开始链接检查：<简述> | ctx={"target_path":"...","check_external":false}
为什么决策前必须记录日志？ 链接检查可能误判（如动态生成链接），CMD_START记录检查路径和是否检查外链便于排查误报。
写操作（--fix）原则：必须先用 --dry-run 预览修复内容，确认无误再正式执行。
为什么dry-run是修复模式的强制前置步骤？ 自动修复虽然经过验证，但路径解析有边界情况（如特殊字符文件名、符号链接、跨盘符引用），直接执行可能"修复"成错误路径导致更多断链。dry-run在完全不修改文件的情况下展示所有将要执行的修改，是成本最低的防误操作手段。
脚本路径：check-links.py
cd d:\spaces\SpecWeave
# 检查整个项目的本地链接
python .agents/scripts/check-links.py
# 只检查指定目录
python .agents/scripts/check-links.py --path docs/
# 检查单个文件
python .agents/scripts/check-links.py --path README.md
# 批量检查多个目录（--paths，自动去重，与 --path 互斥）
python .agents/scripts/check-links.py --paths .agents/skills .agents/commands docs/task-summaries
# 预览将要修复的内容（不修改文件，强烈推荐先执行）
python .agents/scripts/check-links.py --fix --dry-run
# 确认无误后执行修复
python .agents/scripts/check-links.py --fix
# 只修复指定目录
python .agents/scripts/check-links.py --path docs/ --fix --dry-run
python .agents/scripts/check-links.py --path docs/ --fix
# 本地 + 外部链接完整检查（外部链接有7天缓存）
python .agents/scripts/check-links.py --check-external
# 修复模式 + 外部链接检查
python .agents/scripts/check-links.py --fix --check-external --dry-run
python .agents/scripts/check-links.py --fix --check-external
# 文件重命名后修复链接（旧名→新名）
python .agents/scripts/check-links.py --fix --rename old-name.md new-name.md
完整参数表见脚本源码
--help输出；公共参数定义在 lib/cli.py。
--fix 模式可以自动修复以下问题：
| 修复类型 | 说明 | 示例 | 幂等性 |
|---|---|---|---|
| 绝对路径转换 | file:/// 本地绝对路径 → 相对路径 | file:///d:/spaces/.../doc.md → ../doc.md | 已修复的不会重复修改 |
| 层级校正 | 文件移动后 ../ 层数错误 | ../../doc.md → ../doc.md（上移一层目录后） | 路径正确后不再改动 |
| 斜杠补全 | 目录链接尾部缺少 / | ./docs → ./docs/ | 幂等 |
| 文件名映射 | 配合 --rename 更新重命名文件引用 | old.md → new.md | 配合rename参数一次性完成 |
无法自动修复的问题会明确列出，需要人工处理：
#anchor）不存在--dry-run 预览（检查预览结果无异常）为什么外部链接需要7天缓存而非实时检查？ 外部链接检查需要发起HTTP请求，实时检查数百个外链会：1) 因频率限制被目标网站封禁IP；2) 单次检查耗时过长（30秒→5分钟）；3) 网络波动导致临时不可达的链接被误判为断链。7天缓存平衡了"结果新鲜度"和"检查效率/稳定性"——如果一个链接7天前还能访问，大概率现在也能访问；如确需最新结果可手动删除缓存文件强制刷新。
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 大量"文件不存在"误报 | 排除目录未配置 | 使用 --exclude 添加排除目录 |
| 外部链接全部超时 | 网络代理/防火墙问题 | 检查网络设置，或跳过 --check-external |
| 修复后仍有断链 | 存在无法自动修复的问题 | 查看报告中标注的"需人工处理"项 |
| 相对路径被改"错" | 跨盘符/符号链接边界 | 人工校正，提交issue给脚本维护者 |
| 缓存导致旧结果 | 外部链接缓存7天 | 删除 .agents/cache/external-links-cache.json 强制刷新 |
加
-v或--verbose参数获取详细日志；调试问题加--debug。
为什么需要Gotchas？ 错误处理记录"已知错误码及修复方式"，Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。
file:/// 开头的绝对路径转换为相对路径，但Windows盘符（如 D:、C:）有特殊处理逻辑——跨盘符引用无法可靠转换为相对路径，会被标记为"需人工处理"而非强行转换出错。../ 层数计算依赖于源文件和目标文件的目录深度差，移动文件到子目录时 ../ 层数增加，移动到上级目录时层数减少——这是最常见的断链来源，务必在文件移动后运行 --fix 修复。--check-external 参数，仅检查本地链接。[text](url) 和尖括号包裹的 <http://example.com> 格式，但不识别裸URL（即纯文本的 http://example.com 未被任何Markdown链接语法包裹），裸URL不会被检查。| 参考 | 层级 | 路径 | 何时查阅 |
|---|---|---|---|
| 脚本源码（完整参数） | L2 | check-links.py | 需要高级参数时 |
| 链接修复核心逻辑 | L2 | link_fixer/ | 理解修复算法、排查修复异常 |
| 公共CLI参数 | L2 | lib/cli.py | 通用参数（--path、--verbose、--exclude等） |
| 原子化收尾（含链接修复） | L1 | atomization-finalize-cmd | 原子化拆分后的一键收尾 |
当用户提到'CI检查'、'提交前检查'、'综合检查'、'ci-check'、'流水线检查'、'提交门禁'、'全量检查'、'跑一下CI'、'pre-commit'、'预检'、'检查所有'时，必须使用此技能。提供项目CI/CD综合检查能力，按标准流水线顺序执行10项核心检查：仓库合规→链接检查→Spec一致性→模式成熟度→文档生成→重复代码检测→阶段守卫日志→SG仪表盘→文件放置校验→.temp生命周期检查。提交前必跑，确保代码符合项目规范。不要手动逐个执行检查脚本——本Skill已按正确顺序编排，并处理了跨平台兼容（Windows用.ps1，Linux/Mac用.sh）。
当用户提到'原子化收尾'、'finalize atomization'、'文档拆分完成'、'文件移动后处理'、'断链修复导航更新'、'一键收尾'、'重构完成后整理'时，必须使用此技能。原子化/文件移动/目录重构后的一键收尾工具：自动断链修复→导航表更新→Spec看板刷新→验证摘要。不要手动逐个执行后处理步骤——本Skill封装了正确的执行顺序和dry-run预览机制，是文档原子化工作流的标准最后一步。
当用户提到'萃取'、'extraction'、'模式沉淀'、'萃取模式'、'模式入库'、'沉淀为模式'、'可复用模式'、'更新模式库'、'生成模式文档'时，必须使用此技能。提供标准化的模式萃取流程：案例收集→本质抽象→结构化模板→反模式提炼→迁移验证→入库。不要手动组织萃取流程——本Skill封装了六步标准萃取法、反模式对等原则和可迁移性验证。替代旧的pattern-extraction-cmd（v1.0.0）。
当用户提到'知识图谱'、'knowledge graph'、'概念关系可视化'、'交互式知识图谱'、'节点关系网络'、'生成知识图谱'、'可视化知识库'、'概念网络'、'knowledge graph config'时，必须使用此技能。从结构化Markdown文档集（术语表/文档索引/时间线等）自动提取节点和关系，生成交互式vis-network HTML知识图谱。支持TOML声明式配置和Python API两种方式，内置节点去重、孤立节点检测、类型筛选、可信度分级显示。不要手动拼接vis-network代码——本Skill封装了表格解析、关系构建、HTML模板渲染和自包含输出，确保产出质量可预测。
当用户提到'mermaid'、'流程图'、'时序图'、'状态图'、'画个图'、'图表'、'架构图'、'思维导图'、'ER图'、'类图'、'甘特图'、'饼图'、'UML图'、'可视化流程'、'画流程图'、'mermaid图'、'可视化'、'流程可视化'时，必须使用此技能。提供标准化的Mermaid图表创建、检查、修复流程，引导完成从设计→编码→检查→修复→验证→交付的完整闭环。不要手写Mermaid代码绕过本Skill——本Skill封装了安全编码六规则、模板选择、自动检查修复流程，确保图表质量可预测。
当用户提到'复盘'、'retrospective'、'回顾'、'总结经验'、'做个复盘'、'项目总结'、'阶段回顾'、'里程碑总结'、'事后分析'、'经验总结'时，必须使用此技能。提供标准化的项目复盘流程：收集事实→分析过程→提炼洞察→生成报告，引导完成完整的复盘闭环。不要手动组织复盘流程——本Skill已封装四步标准流程和产出物规范。