在 R 包/pkgdown 站点或 Quarto…

当需要为 R 包或 Quarto 文档中的图表/图片添加、改进或审计 alt 文本，尤其是涉及 fig-alt、fig.alt、figure descriptions 时使用。

适用场景

解决思路

1. 先检测项目类型：在项目根目录运行 `ls _pkgdown.yml 2>/dev/null && echo "pkgdown" || echo "not pkgdown"`。
2. 如果命令输出 `pkgdown`（存在 `_pkgdown.yml`），按 pkgdown 站点处理，并读取 `references/pkgdown.md`。
3. 如果没有 `_pkgdown.yml` 且存在 `.qmd` 文件，按 Quarto 文档处理，并读取 `references/quarto.md`。
4. 如果上下文仍不明确，询问用户正在使用 pkgdown 还是 Quarto 格式。
5. 如果用户提供 `label` 参数，只处理指定的图形标签或代码块。
6. 如果用户提供 `file` 参数，只处理指定文件。
7. 利用源代码访问这一关键优势：不要只根据图片写 alt 文本，要读取生成每个图表的代码，用代码提取精确细节。
8. 从绘图代码中提取变量映射，得到坐标轴的精确变量名。
9. 从绘图代码中提取颜色/填充映射，确定颜色编码什么。
10. 从绘图代码中识别绘图类型函数，判断是散点图、直方图、折线图等。
11. 从绘图代码中识别趋势线或拟合曲线，描述叠加的统计拟合。
12. 从绘图代码中识别分面/子图，确定面板数量以及什么在变化。
13. 从绘图代码中识别颜色标度，说明编码方案是顺序、发散还是分类。
14. 从绘图代码中读取轴标签和标题，使用自定义标签。
15. 从数据生成代码中提取随机分布信息，推断预期分布形状。
16. 从数据生成代码中提取变换，说明对数据做了什么处理。
17. 从数据生成代码中提取特征工程，说明应用的预处理。
18. 从数据生成代码中提取过滤/子集操作，说明展示了哪个子集。
19. 从周围文本中提取信息：代码块前后文字解释图表的目的和关键见解。
20. 从章节上下文中判断图表意在教什么。
21. 把周围文本作为 alt 文本“关键见解”部分的最佳来源。
22. 按 Amy Cesal 公式的三部分结构写 alt 文本：第一部分用最先出现的词标明图表类型。
23. 第二部分写数据描述：坐标轴、变量、展示了什么。
24. 第三部分写关键见解：模式或要点，通常来自周围文本。
25. 先读标题（`fig-cap`、`fig.cap`），再写 alt 文本。
26. 让 alt 文本补充标题而非重复标题：如果标题已陈述见解，alt 文本侧重描述视觉结构。
27. 如果标题很笼统，alt 文本应包含关键见解。
28. 让 alt 文本和标题合起来给出完整理解。
29. 内容应包含：图表类型作为开头词。
30. 内容应包含：坐标轴标签及其代表内容。
31. 内容应包含：当代码揭示具体值/范围时写入，例如“在 25–50 之间达到峰值”。
32. 内容应包含：面板/分面数量。
33. 内容应包含：颜色/大小编码什么（如果使用）。
34. 内容应包含：支持周围论点的关键模式。
35. 内容应排除：“Image of…” 或 “Chart showing…”（屏幕阅读器会播报）。
36. 内容应排除：装饰性颜色描述，除非颜色编码数据。
37. 内容应排除：标题中已有的信息。
38. 内容应排除：实现细节（包名、函数内部）。
39. 长度按复杂度控制：简单图用 2–3 句，适用于单个 geom、无分面、模式明显。
40. 长度按复杂度控制：标准图用 3–4 句，适用于多个 geoms 或颜色编码。
41. 长度按复杂度控制：复杂图用 4–5 句，适用于分面、多个叠加、细微见解。
42. 质量检查：以图表类型开头（散点图、直方图、分面柱状图等）。
43. 质量检查：命名坐标轴变量。
44. 质量检查：在信息有用时包含来自代码的具体值/范围。
45. 质量检查：说明周围文本中的关键见解。
46. 质量检查：补充（而非重复）标题。
47. 质量检查：对看不见图像的人也能理解。
48. 质量检查：使用平实语言，避免如 `geom` 或 `aesthetic` 的术语。
49. 使用散点图模板：散点图。[X 变量] 在 x 轴，[Y 变量] 在 y 轴。[形状：线性/弯曲/聚集]。[具体模式，例如“当 X 为 25–50 时达到峰值”]。[任何叠加拟合或注释]。
50. 使用直方图模板：直方图 of [变量]。[形状：右偏/双峰/正态/均匀]。[如果做过变换：“经过 [变换] 后，分布 [结果]”]。[显著特征：离群值、缺口、多个众数]。
51. 使用柱状图模板：柱状图。[类别] 在 x 轴，[度量] 在 y 轴。[关键比较：哪个最高/最低，相对差异]。[模式：递增/递减/分组]。
52. 使用瓦片/栅格图模板：瓦片图 [或热图]。[行变量] 在 y 轴，[列变量] 在 x 轴。颜色编码 [什么值]。[模式：数值高/低出现的位置]。[如果分面：“N 个面板展示 [什么在变化]”]。
53. 使用分面图模板：分面 [图表类型] 有 [N] 个面板，每个面板对应 [分面变量]。[各面板中不变的内容]。[变化/不同的内容]。[跨面板的关键比较或见解]。
54. 使用相关性热图模板：相关性 [矩阵/热图] of [哪些变量]。[排列方式]。[总体模式：大多正/负/混合]。[显著聚类或强/弱配对]。[如果相关：与预期行为对比]。
55. 使用前后对比模板：[N] 个 [图表类型] 按 [垂直/网格] 排列。[上/左] 显示 [原始]。[下/右] 显示 [变换后]。[关键差异/相似点]。[如果叠加：“[颜色] 曲线显示 [参考]”]。
56. 使用带叠加的折线图模板：[折线/散点] 图叠加 [拟合/曲线]。[坐标轴]。[数量] 条 [线/拟合] 被展示：[列出每条代表什么]。[哪些拟合得好、哪些不好及原因]。
57. 参考原文示例：对分面直方图与绿色正态曲线叠加，alt 文本应类似“分面直方图，两个面板垂直堆叠。上面板显示原始数据，呈双峰分布。下面板显示相同数据经 z-score 标准化后，仍保留双峰形状。下面板叠加的绿色正态分布曲线明显不匹配数据，表明标准化保留分布形状，而不是制造正态性。”

适用边界 · 注意事项

• 项目不是 R 包/pkgdown 或 Quarto 文档，或无法读取图表生成代码时，本技能依赖源码提取细节的优势不适用。
• 只需为照片、图标、装饰图等非数据可视化图片写 alt 文本时，不应套用图表三部分结构和模板。
• 只有图片无法访问生成代码、数据或周围文本时，无法可靠提取坐标轴变量、分面数量、具体值范围和关键见解。