ci: 在 PR 评论中添加 API 文档预览diff (#13)

Co-authored-by: 黎伟杰 <674416404@qq.com>

Author: RSS1102

.github/scripts/build_doc_diff_comment.dart

@@ -0,0 +1,29 @@
+#!/usr/bin/env dart
+/// CI 专用：生成 PR 文档 diff 评论 Markdown。
+///
+/// 用法（在 tdesign-flutter 根目录）:
+///   dart run <tools-repo>/.github/scripts/build_doc_diff_comment.dart \
+///     --out /path/to/doc-diff-comment.md
+import 'dart:io';
+
+import 'package:tdesign_flutter_tools/doc_diff_comment.dart';
+
+Future<void> main(List<String> args) async {
+  String? out;
+  var repo = '.';
+
+  for (var i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--out':
+        out = args[++i];
+      case '--repo':
+        repo = args[++i];
+    }
+  }
+  if (out == null) {
+    stderr.writeln('用法: build_doc_diff_comment.dart --out <file> [--repo <flutter-root>]');
+    exit(1);
+  }
+
+  await DocDiffComment(repoRoot: repo, outPath: out).write();
+}

.github/scripts/cross_platform_verify.dart

@@ -18,13 +18,11 @@ void main(List<String> args) async {
   print('Binary: $binaryAbsPath');
   print('Repo:   $componentDir');
 
-  // 验证二进制文件存在
   if (!File(binaryAbsPath).existsSync()) {
     print('ERROR: Binary not found: $binaryAbsPath');
     exit(1);
   }
 
-  // 用一个真实的 dart 文件测试 generate 命令
   final testFile = '$componentDir/lib/src/components/button/t_button.dart';
   if (!File(testFile).existsSync()) {
     print('ERROR: Test file not found: $testFile');
@@ -52,7 +50,6 @@ void main(List<String> args) async {
     exit(result.exitCode);
   }
 
-  // 验证输出文件生成
   final outputFile = File('${outputDir}button_api.md');
   if (outputFile.existsSync()) {
     print('\nSUCCESS: button_api.md generated (${outputFile.lengthSync()} bytes)');

.github/scripts/regenerate_api_for_diff.dart

@@ -0,0 +1,64 @@
+#!/usr/bin/env dart
+/// CI 专用：在克隆的 tdesign-component 工作区批量重生成 API md（供 doc-diff 对比）。
+/// 不在 bin/main.dart 暴露；tdesign-flutter 本地维护请用 generate / update。
+///
+/// 用法（在 tdesign-component 目录）:
+///   dart run <tools-repo>/.github/scripts/regenerate_api_for_diff.dart
+import 'dart:io';
+
+import 'package:path/path.dart';
+import 'package:tdesign_flutter_tools/model.dart';
+import 'package:tdesign_flutter_tools/smart_create.dart';
+
+Future<void> main(List<String> args) async {
+  final componentRoot = Directory.current.path;
+  final folders = args.isEmpty
+      ? <String>[]
+      : args.first.split(',').map((s) => s.trim()).where((s) => s.isNotEmpty).toList();
+
+  final componentsRoot = Directory(join(componentRoot, 'lib/src/components'));
+  if (!componentsRoot.existsSync()) {
+    stderr.writeln('ERROR: 请在 tdesign-component 根目录执行，且存在 lib/src/components');
+    exit(1);
+  }
+
+  print('${DateTime.now().toLocal()}  [CI] 批量生成 API 文档（仅用于 diff 预览）...');
+  var count = 0;
+  final base = componentRoot.endsWith(Platform.pathSeparator)
+      ? componentRoot
+      : '$componentRoot${Platform.pathSeparator}';
+
+  for (final entity in componentsRoot.listSync()) {
+    if (entity is! Directory) continue;
+    final folder = basename(entity.path);
+    if (folders.isNotEmpty && !folders.contains(folder)) continue;
+    if (!File(join(entity.path, 't_$folder.dart')).existsSync()) continue;
+
+    final className = _folderToMainClassName(folder);
+    final relFile = 'lib/src/components/$folder/t_$folder.dart';
+    await SmartCreator(
+      isFileMode: true,
+      onlyApi: true,
+      nameList: [className],
+      basePath: base,
+      path: relFile,
+      output: 'example/assets/api/',
+      folderName: folder,
+      commandInfo: CommandInfo()
+        ..file = relFile
+        ..folderName = folder
+        ..widgetNames = className
+        ..isOnlyApi = true,
+    ).run();
+    count++;
+  }
+  print('${DateTime.now().toLocal()}  完成，共 $count 个组件');
+}
+
+String _folderToMainClassName(String folder) {
+  final camel = folder.split('_').map((s) {
+    if (s.isEmpty) return s;
+    return '${s[0].toUpperCase()}${s.substring(1)}';
+  }).join();
+  return 'T$camel';
+}

.github/workflows/build-multi-platform.yml

@@ -2,134 +2,129 @@ name: Build Multi-Platform Binaries
 
 on:
   pull_request:
+    branches: [develop, main]
     types: [opened, synchronize, reopened]
 
+concurrency:
+  group: pr-binaries-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   build-macos-intel:
     runs-on: macos-latest
-    outputs:
-      artifact_id: ${{ steps.upload.outputs.artifact-id }}
-      artifact_url: ${{ steps.upload.outputs.artifact-url }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Setup Flutter
-        uses: subosito/flutter-action@v2
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
         with:
-          flutter-version: '3.32.0'
-      - name: Install dependencies
-        run: flutter pub get
-      - name: Build macOS Intel
-        run: dart compile exe bin/main.dart -o api_tool_macos_intel
+          flutter-version: "3.32.0"
+          channel: stable
+          cache: true
+      - run: flutter pub get
+      - run: dart compile exe bin/main.dart -o api_tool_macos_intel
       - name: Verify binary
         run: |
           git clone --depth 1 --branch develop https://github.com/Tencent/tdesign-flutter.git
           dart run .github/scripts/cross_platform_verify.dart tdesign-flutter api_tool_macos_intel
-      - name: Upload Artifact
-        id: upload
-        uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v4
         with:
           name: api_tool_macos_intel
           path: api_tool_macos_intel
 
   build-macos-arm64:
     runs-on: macos-latest
-    outputs:
-      artifact_id: ${{ steps.upload.outputs.artifact-id }}
-      artifact_url: ${{ steps.upload.outputs.artifact-url }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Setup Flutter
-        uses: subosito/flutter-action@v2
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
         with:
-          flutter-version: '3.32.0'
-      - name: Install dependencies
-        run: flutter pub get
-      - name: Build macOS ARM64
-        run: dart compile exe bin/main.dart -o api_tool_macos_arm64 --target-os=macos --target-arch=arm64
+          flutter-version: "3.32.0"
+          channel: stable
+          cache: true
+      - run: flutter pub get
+      - run: dart compile exe bin/main.dart -o api_tool_macos_arm64 --target-os=macos --target-arch=arm64
       - name: Verify binary
         run: |
           git clone --depth 1 --branch develop https://github.com/Tencent/tdesign-flutter.git
           dart run .github/scripts/cross_platform_verify.dart tdesign-flutter api_tool_macos_arm64
-      - name: Upload Artifact
-        id: upload
-        uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v4
         with:
           name: api_tool_macos_arm64
           path: api_tool_macos_arm64
 
   build-linux-x64:
     runs-on: ubuntu-latest
-    outputs:
-      artifact_id: ${{ steps.upload.outputs.artifact-id }}
-      artifact_url: ${{ steps.upload.outputs.artifact-url }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Setup Flutter
-        uses: subosito/flutter-action@v2
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
         with:
-          flutter-version: '3.32.0'
-      - name: Install dependencies
-        run: flutter pub get
-      - name: Build Linux x64
-        run: dart compile exe bin/main.dart -o api_tool_linux --target-arch=x64
+          flutter-version: "3.32.0"
+          channel: stable
+          cache: true
+      - run: flutter pub get
+      - run: dart compile exe bin/main.dart -o api_tool_linux --target-arch=x64
       - name: Verify binary
         run: |
           git clone --depth 1 --branch develop https://github.com/Tencent/tdesign-flutter.git
           dart run .github/scripts/cross_platform_verify.dart tdesign-flutter api_tool_linux
-      - name: Upload Artifact
-        id: upload
-        uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v4
         with:
           name: api_tool_linux
           path: api_tool_linux
 
   build-windows-x64:
     runs-on: windows-latest
-    outputs:
-      artifact_id: ${{ steps.upload.outputs.artifact-id }}
-      artifact_url: ${{ steps.upload.outputs.artifact-url }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Setup Flutter
-        uses: subosito/flutter-action@v2
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
         with:
-          flutter-version: '3.32.0'
-      - name: Install dependencies
-        run: flutter pub get
-      - name: Build Windows x64
-        run: dart compile exe bin/main.dart -o api_tool_windows.exe
+          flutter-version: "3.32.0"
+          channel: stable
+          cache: true
+      - run: flutter pub get
+      - run: dart compile exe bin/main.dart -o api_tool_windows.exe
       - name: Verify binary
+        shell: bash
         run: |
           git clone --depth 1 --branch develop https://github.com/Tencent/tdesign-flutter.git
           dart run .github/scripts/cross_platform_verify.dart tdesign-flutter api_tool_windows.exe
-      - name: Upload Artifact
-        id: upload
-        uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v4
         with:
           name: api_tool_windows
           path: api_tool_windows.exe
 
   comment-on-pr:
+    name: 更新二进制产物 PR 评论
     needs: [build-macos-intel, build-macos-arm64, build-linux-x64, build-windows-x64]
     runs-on: ubuntu-latest
     steps:
-      - name: Find Comment
-        id: find-comment
-        uses: peter-evans/find-comment@v3
-        with:
-          issue-number: ${{ github.event.pull_request.number }}
-          comment-author: 'github-actions[bot]'
-          body-includes: 编译完成，产物如下
-      
-      - name: Create or Update PR Comment
-        uses: peter-evans/create-or-update-comment@v4
+      - name: 组装产物下载链接
+        id: binary-comment
+        env:
+          GH_REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          base="https://github.com/${GH_REPO}/actions/runs/${RUN_ID}"
+          {
+            echo 'body<<EOF'
+            echo "✅ 编译完成，产物如下："
+            echo "- [api_tool_macos_intel](${base}/artifacts)（job: build-macos-intel）"
+            echo "- [api_tool_macos_arm64](${base}/artifacts)（job: build-macos-arm64）"
+            echo "- [api_tool_linux](${base}/artifacts)（job: build-linux-x64）"
+            echo "- [api_tool_windows](${base}/artifacts)（job: build-windows-x64）"
+            echo ""
+            echo "<!-- AUTO_BINARY_BUILD_HOOK -->"
+            echo ""
+            echo "_在 Actions 运行页 Artifacts 区域按平台名称下载。_"
+            echo 'EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: 更新 PR 评论
+        uses: TDesignOteam/workflows/actions/maintain-one-comment@main
         with:
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          body: |
-            ✅ 编译完成，产物如下：
-            - [api_tool_macos_intel](${{ needs.build-macos-intel.outputs.artifact_url }})
-            - [api_tool_macos_arm64](${{ needs.build-macos-arm64.outputs.artifact_url }}) 
-            - [api_tool_linux](${{ needs.build-linux-x64.outputs.artifact_url }})
-            - [api_tool_windows](${{ needs.build-windows-x64.outputs.artifact_url }})
-          edit-mode: replace
+          token: ${{ secrets.GITHUB_TOKEN }}
+          body: ${{ steps.binary-comment.outputs.body }}
+          number: ${{ github.event.pull_request.number }}
+          body-include: "<!-- AUTO_BINARY_BUILD_HOOK -->"