diff --git a/docs/superpowers/specs/2026-07-31-api-doc-merge-compatibility-design.md b/docs/superpowers/specs/2026-07-31-api-doc-merge-compatibility-design.md
new file mode 100644
index 0000000..1fa9c36
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-31-api-doc-merge-compatibility-design.md
@@ -0,0 +1,52 @@
+# API 文档页合并兼容设计
+
+日期：2026-07-31
+
+## 目标
+
+将 `codex/plugin-ui-refactor` 的 API 文档导出架构合并到
+`20260730-API插件继续优化`，同时保留当前分支已经完成的三个 Tab
+布局，不因解决 Git 冲突而回退 UI 或恢复旧的线程、Loading 和历史逻辑。
+
+## 保留的 UI
+
+- 保留“导出配置、导出历史、基类配置”三个 Tab。
+- 保留紧凑的模式卡片、导出进度区域和当次结果入口。
+- 保留 `.apidoc-tab-pane` 主题样式。
+
+## 接入的新架构
+
+- 导出任务由 `AsyncOperationController` 和
+  `RunApiDocExportUseCase` 执行。
+- 导出按钮仅通过 `LoadingButtonBinder` 绑定状态，不再直接修改
+  文案、图标和禁用状态。
+- 导出请求统一构造为不可变 `ApiDocExportRequest`。
+- 本地调试代理为显式选项，默认关闭。
+- 历史 Tab 使用公共 `ExportHistoryPane` 和
+  `HistoryFileCommands`，删除窗口内重复的表格单元格和文件操作代码。
+- 主题文件同时保留 Tab 样式、异步状态样式和空状态样式。
+
+## 数据流
+
+1. UI 根据当前模式构造 `ApiDocExportRequest`。
+2. `AsyncOperationController` 将请求交给
+   `RunApiDocExportUseCase`。
+3. UseCase 根据请求决定是否启动调试代理，再调用生成逻辑。
+4. 成功结果更新当次结果入口和公共历史列表。
+5. 错误由操作状态面板与日志展示，UI 恢复由状态绑定完成。
+
+## 冲突解决边界
+
+- 不直接选择 Git 的 ours 或 theirs 覆盖完整文件。
+- 以当前分支布局为外壳，以重构分支的请求、用例和状态管理为内部实现。
+- Git 评审相关文件不参与本次修改。
+- 未跟踪的审计文档和 SQL 文件保持不动。
+
+## 验证
+
+- 现有请求、代理、历史和异步状态测试必须全部通过。
+- 增加源码结构测试，防止 API 文档窗口重新出现 `new Thread`、
+  `setBtnLoading` 或直接启动隐式代理。
+- 编译并运行完整测试。
+- 执行 `git diff --check`。
+- 只读 UI 验收三个 Tab、代理默认关闭、空闲状态和历史 Tab。