技能：文档链接健康评估（Assess Docs Links）

目的 (Purpose)

检查文档之间的链接关系，识别坏链、孤立文档、循环与深链风险。

---

核心目标（Core Objective）

首要目标：输出一份可修复的链接健康报告。

成功标准：

1. ✅ 已构建文档链接图
2. ✅ 已识别坏链与孤立文档
3. ✅ 已识别循环引用和深链
4. ✅ 已给出修复建议
5. ✅ 已写入 docs/calibration/doc-link-health.md

---

范围边界（Scope Boundaries）

本技能负责：文档图健康。 本技能不负责：规范合规、code alignment、SSOT 审计。

---

使用场景（Use Cases）

• 发布前链接巡检
• 文档迁移后回归检查

---

行为（Behavior）

阶段 0：Norms Resolution（v1.1 新增）

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 的 §8.2 / §8.3 / §8.5 实现：读项目规范若声明了 doc-link-health artifact_type 的 path_pattern，则使用项目值；否则 fall through 到技能默认（docs/calibration/doc-link-health.md）。本技能为固定路径治理产出，只用 path_pattern 覆盖机制。

阶段 1：链接图构建与评估

1. 扫描 Markdown/Wiki 链接
2. 构建有向图
3. 检测问题（broken/orphan/cycle/depth）
4. 汇总风险等级与修复建议

---

输入与输出 (Input & Output)

输入

• docs 根路径
• 可选路径过滤
• 可选深度阈值（默认 4）

输出

• docs/calibration/doc-link-health.md

---

限制（Restrictions）

• 不修改文档文件
• 不检查外部 URL 可达性（仅标记）

---

自检（Self-Check）

• 图构建完成
• 问题分类完整
• 报告落盘完成

---

示例（Examples）

• 文档 A 指向不存在文件 -> broken link

---

附录：输出合约 (Appendix: Output Contract)

本技能产出 Doc Link Health Report：

元素	格式	必填字段	路径模式
报告主体	Markdown	front-matter；章节：摘要 / 断链 / 孤儿文档 / 循环引用 / 深链路径	docs/calibration/doc-link-health.md
断链条目	列表项	source_path / target_ref / kind（404 / anchor_missing / external_unreachable）	「断链」节
孤儿条目	列表项	doc_path / inbound_count=0 / suggested_link_target	「孤儿文档」节
机器可读块	YAML fenced yaml link_health:	broken[]、orphans[]、cycles[]、deep_chains[]	报告末尾