compat-doc-authoring

name	compat-doc-authoring
description	编写或更新 Paddle 与 PyTorch C++ API 兼容性文档。Use when: 添加兼容文档、补充 API 对比表、补全兼容性统计、拆分 typeid 类级文档、统一文档格式。
argument-hint	要编写的头文件或模块，例如 typeid.h、Stream.h、TensorBase.h

兼容性文档编写技能

面向 doc/ 目录的 API 兼容文档生产与维护流程，目标是输出可审阅、可追踪、可统计的对比文档。

上游调用上下文

本 skill 可被独立调用（用户直接传入头文件名按"标准模板"产出新文档）， 也可被上游驱动型 skill 在收尾阶段调用：

上游 skill	调用时机	期望传入字段	处理策略
add-compat-api	"文档归档"小节	PCAT_ROOT / 调用模式=append-to-existing / 目标文档 / 上游模板名=对齐迭代记录 / 已填段落	把已填段落原样追加到目标文档尾部；联动回填本 skill 维护的对比表、## 兼容性统计、"关键差异说明"
fix-compat-api	"文档归档"小节	PCAT_ROOT / 调用模式=append-to-existing / 目标文档 / 上游模板名=Compat 修复记录 / 已填段落	同上；额外检查"修复内容"是否涉及对比表状态符号变更（🔧 ↔ ✅），若有则同步改表

模板归属规则：

• 上游持有"对齐迭代记录" / "Compat 修复记录"模板并填好后传入。本 skill 不生成这两个模板的内容，只做"格式校验 + 原样追加 + 关联表格更新"。
• 本 skill 的"标准模板"（文件头/对比表/兼容性统计/关键差异说明/备注） 只用于独立调用场景——为新头文件起草新文档时使用。
• 在 append-to-existing 模式下，禁止改写"已填段落"内文字（除非格式非法）， 只允许在文档其他位置（对比表、统计表、关键差异说明）做关联更新。

被上游调用时，本 skill 不反向调用任何上游 skill，也不触发其他 skill。 完成归档与校验后，返回结论文字（如"对齐迭代记录已追加； 兼容性统计已回填 ✅ 12 / 🔧 3 / ❌ 1；3 个 🔧 条目均已在'关键差异说明'追加小节"）给上游。

何时使用

• 需要新增某个头文件的兼容性文档
• 需要补齐/修订已有文档的 API 对比表
• 需要给文档增加或修正“兼容性统计”
• 需要把一个大文档拆成多个类级文档（如 typeid）
• 需要统一文档格式到 TensorBase 风格

输入与产出

输入

1. 对比源文件路径（Paddle compat 与 PyTorch 原生）
2. 文档目标路径（通常在 doc/）
3. 用户的格式约束（例如“每个函数都要注释实现差异”）

产出

1. 结构化 Markdown 文档
2. API 对比表（按模块分组）
3. 兼容性统计表（✅/🔧/❌）
4. 关键差异说明与建议测试点（如用户需要）

标准模板（推荐）

1. 文件头：日期与复核说明（> YYYY-MM-DD 编制/复核：...）
2. 对比文件列表（点列表格式）
3. 状态说明段落（定义 ✅/🔧/❌/🟦 含义）
4. API 对比表（分组）（按构造、访问器、操作等分类）
5. ## 兼容性统计（简化2列表）
6. ## 关键差异说明（按序列号）
7. ## 备注（实现细节、编译依赖等）

表格标准列

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|-----------|------------------|------------|-------|------|

约定：

• paddle API 兼容性：使用符号 ✅/🔧/❌/🟦
• 测试用例状态：使用 checkbox - [ ] 或 - [x]
• 优先级：使用 P0/P1/P2/P3 标记
  • P0: 核心功能，必须支持
  • P1: 常用功能，高优先级
  • P2: 进阶功能，中优先级
  • P3: 边缘功能，低优先级

兼容性统计表

| 状态 | 数量 |
|---|---|
| ✅ 已实现 | N1 |
| 🔧 部分兼容 | N2 |
| ❌ 未实现 | N3 |

工作流程

Step 1. 先读代码再写文档

1. 读取 Paddle compat 头文件（必要时包含 .cpp）
2. 读取 PyTorch 对应头文件（必要时包含 .cpp）
3. 列出 API 清单（函数、运算符、模板、宏、类型别名）

Step 2. 建立分组与差异模型

1. 按“构造/访问/静态 helper/宏与注册/运算符”分组
2. 对每个 API 标注状态：
   • ✅：接口与语义一致
   • 🔧：接口在，但实现路径或边界行为不同
   • ❌：Torch 有、Paddle 缺失
3. 在备注中写清：
   • 实现方式是否一致
   • 语义是否一致
   • 若不同，具体如何实现

Step 3. 写入文档

1. 新文档：按模板完整创建
2. 旧文档：只做必要改动，避免重排无关内容
3. 如果用户要求“每个类单独文档”：
   • 为每个类创建独立 *.md
   • 增加索引文档（如 README.md）

Step 4. 兼容性统计回填

1. 统计口径：按文档中 API 对比表逐行计数
2. 统计表固定格式：

### 兼容性统计

| 状态 | 数量 |
|---|---|
| ✅ 已实现 | N1 |
| 🔧 部分兼容 | N2 |
| ❌ 未实现 | N3 |

3. 若是索引文档：标注“汇总统计”，并说明口径来源

Step 5. 完成校验

发布前必须检查：

1. 文档中存在 ## 兼容性统计（2级标题）
2. 统计值与表格行数一致
3. 对比文件路径正确且可访问
4. 每个 🔧 条目都在"关键差异说明"中有详细说明
5. 测试用例状态全部使用 checkbox - [ ] / - [x]
6. 优先级全部使用 P0/P1/P2/P3 标记
7. 无明显过时描述（如"未接入"但代码已接入）
8. 若由上游 skill 调用：传入的"已填段落"与上游模板五段结构完全一致，未被改写
9. 若由上游 skill 调用：本次追加内容的日期标签（YYYY-MM-DD）唯一，不与历史记录冲突

决策与分支

分支 A：只有头文件差异

• 只对比 .h，备注写“仅基于声明”

分支 B：行为依赖实现文件

• 同时对比 .cpp
• 在备注明确“实现位于 .cpp”

分支 C：用户要求快速补齐统计

• 不改正文，优先补 ### 兼容性统计
• 以现有表格行为统计基准

分支 D：用户要求深度重构文档

• 先出拆分方案（目录与文件映射）
• 再分批落地，最后统一索引

分支 E：基于验证结果修复文档

触发条件：verify_api_mapping.py 验证报告发现映射表分类错误或别名映射失效。

处理流程：

1. 读取验证报告

   • 读取 doc/mapping/verification_output/mapping_correction_report.md
   • 提取需要修正的 API 列表及目标分类

2. 修复别名映射

   • 更新 doc/mapping/cpp_api_alias_mapping.json
   • 移除验证为无效的映射条目
   • 添加验证发现的新别名映射（高/中置信度）

3. 修复映射表分类

   • 更新 doc/mapping/cpp_api_mapping_cn.md
   • 从错误分类中删除条目
   • 添加到正确分类（注意避免重复）
   • 更新各分类的序号和统计数字

4. 清理差异文档

   • 删除被移除条目引用的孤儿差异文档
   • 为新增/变更分类的 API 创建或更新差异文档

5. 验证修复结果

   • 重新运行 python doc/mapping/verify_api_mapping.py --op <api> 确认
   • 检查映射表中无重复条目
   • 确认统计数字正确

常见修复场景：

场景	修复操作	涉及文件
API 实际为别名但标记为差异	移到"API 别名"，更新别名映射	cpp_api_mapping_cn.md, cpp_api_alias_mapping.json
API 别名映射无效（Paddle 无实现）	移到"功能缺失"，移除别名映射	cpp_api_mapping_cn.md, cpp_api_alias_mapping.json
API 有 kernel 但未暴露到 api.h	标记为 kernel_only，文档说明	cpp_api_mapping_cn.md
同一 API 出现在多个分类中	删除重复条目，保留正确分类	cpp_api_mapping_cn.md

质量标准

1. 可审阅：每个🔧条目都在"关键差异说明"中有详细落点
2. 可验证：统计值与表格行数一致（可逐行检查）
3. 可维护：格式统一、轻级标题稳定、优先级一致
4. 可复用：同一模板可直接用于下一个头文件（如Stream.h、TensorBase.h）

常见隐患与修复

隐患 1：优先级混用

❌ 错误：有的行用 P0，有的用 高/中/低，有的用 H/M/L ✅ 要求：全文统一用 P0/P1/P2/P3

隐患 2：测试用例状态不规范

❌ 错误：用 ✅/⚠️/❌ 或 过 / 漏 ✅ 要求：全文统一用 checkbox - [ ] 和 - [x]

隐患 3：统计表行数与表格不符

❌ 错误：表格有 15 行，但统计 ✅:9 + 🔧:4 = 13 ✅ 要求：逐行数清，再填入统计表

隐患 4：🔧 条目无备注

❌ 错误：只写 🔧 不说明差异在哪 ✅ 要求：每个 🔧 都在"关键差异说明"中有小节说明

推荐触发词示例

• “给 xxx.h 写兼容文档”
• “补齐这个文档的兼容性统计”
• “按 TensorBase 风格重写文档”
• “把 typeid 文档拆成每个类一个文件”