执行摘要

• 一句话：文档新增 Non-Causal 列支持
• 推荐动作：属于纯文档增强，可快速合并。代码中的缩进不一致问题建议在合并前或后续 cleanup PR 中修复。文档描述可采纳机器人建议稍作调整以提升清晰度。

功能与动机

鉴于 DFlash 等注意力后端开始支持非因果注意力，文档应如实记录这一能力，方便用户选型。PR body 明确说明 'Given the popularity of DFlash, we should report non-causal support in the attention backend documentation'。

实现拆解

1. 生成脚本增加字段解析（tools/pre_commit/generate_attention_backend_docs.py）：在 analyze_backend 返回字典中新增 supports_non_causal 键，值通过 check_method_overrides(class_node, "supports_non_causal") 获取，遵循与其他布尔属性一致的解析模式。
2. 生成脚本新增列定义：在 _COL_... 系列中新增 _COL_NON_CAUSAL 列，使用 bool_to_emoji 渲染为 ✅/❌，并在 _build_columns 中将其追加到标准列列表（位于 Sink 列之后）。
3. 文档 legend 更新（docs/design/attention_backends.md）：在 legend 表格中增加一行 | Non-Causal | Non-causal (bidirectional) attention support for decoder models |。
4. 文档表格自动重生成：生成脚本运行后，所有后端的现有支持状态通过 supports_non_causal 方法自动填充，文档表格内容被更新（30 行新增、29 行删除，实际为表格列数的增加和每行对应单元格的填充）。

关键文件：

• tools/pre_commit/generate_attention_backend_docs.py（模块 文档生成；类别 source；类型 core-logic；符号 analyze_backend, _COL_NON_CAUSAL, _build_columns）: 核心改动文件：在分析函数返回值中新增 supports_non_causal 字段，并新增对应表格列定义，是文档自动生成的数据源和渲染逻辑。
• docs/design/attention_backends.md（模块 文档；类别 docs；类型 documentation）: 文档目标文件：生成脚本运行后自动更新，表格新增 Non-Causal 列并填充数据，legend 增加对应说明行。

关键符号：analyze_backend, _build_columns, generate_legend

关键源码片段

tools/pre_commit/generate_attention_backend_docs.py

核心改动文件：在分析函数返回值中新增 supports_non_causal 字段，并新增对应表格列定义，是文档自动生成的数据源和渲染逻辑。

# 在 analyze_backend 返回字典中新增 supports_non_causal 键值对
return {
    "name": backend_name,
    "dtypes": parse_supported_dtypes(class_node),
    "kv_cache_dtypes": kv_cache_dtypes,
    "block_sizes": parse_block_sizes(class_node),
    "head_sizes": parse_head_sizes(class_node),
    "attn_types": parse_attention_types(class_node),
    "compute_capability": compute_cap,
    "is_mla": is_mla_backend or check_method_overrides(class_node, "is_mla"),
    "supports_sink": check_method_overrides(class_node, "supports_sink"),
    # 新增：非因果注意力支持，解析后端类中 supports_non_causal 方法
    "supports_non_causal": check_method_overrides(
        class_node, "supports_non_causal"
    ),
    "is_sparse": check_method_overrides(class_node, "is_sparse"),
    "supports_mm_prefix": check_method_overrides(class_node, "supports_mm_prefix"),
    "supports_dcp": supports_dcp,
}
​
# 新增列定义，使用 bool_to_emoji 渲染为 ✅/❌
_COL_NON_CAUSAL: TableColumn = (
    "Non-Causal",
    lambda b: bool_to_emoji(b["supports_non_causal"]),
)
​
# 在 _build_columns 中追加到标准列列表（Sink 列之后）
def _build_columns(is_mla: bool, has_versions: bool) -> list[TableColumn]:
    # ... 前置列 ...
    cols.append(_COL_SINK)
    cols.append(_COL_NON_CAUSAL) # 新增：Non-Causal 列紧跟 Sink 列
    if is_mla:
        cols.append(_COL_SPARSE)
    cols.extend([_COL_MM_PREFIX, _COL_DCP, _COL_ATTN_TYPES, _COL_COMPUTE_CAP])
    return cols

评论区精华

Gemini Code Assist 机器人提出了两条评论：

• 文档描述语义模糊：“Non-causal (bidirectional) attention support for decoder models” 可能让读者困惑，建议明确为 decoder-only 路径内的非因果注意力模式（因 decoder 模型通常是因果的）。

• Python 代码中 supports_non_causal 字典项的缩进与周围键不一致，建议对齐。
  两条评论均未被回复或 resolved，但 PR 最终获得了两名维护者（noooop, mgoin）的 approval，说明问题不严重或已被接受。

• 文档描述准确性 (documentation): 未 resolved，但 PR 被 approve，说明维护者接受当前表述或认为问题不大。

• 代码缩进一致性 (style): 未 resolved，但 PR 被 approve，缩进问题可能被容忍。

风险与影响

• 风险：风险极低。变更只涉及文档自动生成脚本和 markdown 文档，不触及任何运行时逻辑。潜在的回归风险在于生成脚本的 _build_columns 中列顺序变更可能导致表格布局错位，但本 PR 仅追加一列且位置恰当，行内代码的 check_method_overrides 已在多处使用，稳定性高。
• 影响：影响范围仅限于文档阅读者。用户现在可以在注意力后端文档中直观地看到各后端是否支持非因果注意力，有助于选择合适的后端。对系统性能、安全性无影响。
• 风险标记：文档变更

关联脉络

• PR #40815 [Attention] Move FA3→FA4 upgrade into get_flash_attn_version(): 同为注意力后端文档/代码变更，展示了 attention 模块的持续演进。