feat: harden first-run model setup and imports

Author: wimi321

CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to Aura are documented here.  
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.2.6] — 2026-05-27
+
+### Added
+- Release validation script for Android arm64 builds, checksum output, and core regression checks
+- Tavern compatibility fixture matrix for JSON V2/V3 cards, PNG text variants, embedded worldbooks, and standalone worldbooks
+
+### Changed
+- Made first-run model setup clearer about local storage needs and retrying interrupted downloads
+- Split the import entry point into clearer paths for photo PNG cards, file cards, standalone worldbooks, and manual story-card creation
+
+### Fixed
+- Prevented resumed downloads from corrupting files when a server ignores HTTP range requests and restarts from byte zero
+
 ## [0.2.5] — 2026-05-07
 
 ### Added
@@ -108,6 +121,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 - Hardware delegate auto-selection (CoreML / GPU / CPU)
 - Context window management with heuristic summarization
 
+[0.2.6]: https://github.com/wimi321/aura/releases/tag/v0.2.6
 [0.2.5]: https://github.com/wimi321/aura/releases/tag/v0.2.5
 [0.2.4]: https://github.com/wimi321/aura/releases/tag/v0.2.4
 [0.2.3]: https://github.com/wimi321/aura/releases/tag/v0.2.3

README.md

@@ -112,6 +112,12 @@ flutter pub get
 flutter run
 ```
 
+Release validation for the Android arm64 package:
+
+```bash
+./scripts/validate_release_android_arm64.sh
+```
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed build instructions including iOS.
 
 ---

README.zh-CN.md

@@ -112,6 +112,12 @@ flutter pub get
 flutter run
 ```
 
+Android arm64 发布包验证：
+
+```bash
+./scripts/validate_release_android_arm64.sh
+```
+
 详细构建指南（含 iOS）请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ---

lib/application/providers/app_state_provider.dart

@@ -56,6 +56,7 @@ class AppStateProvider extends ChangeNotifier {
   String? _errorMessage;
   String? _downloadingModelId;
   String? _cancelledDownloadId;
+  String? _failedDownloadModelId;
   double _downloadProgress = 0;
   int _downloadReceivedBytes = 0;
   int _downloadTotalBytes = 0;
@@ -79,6 +80,7 @@ class AppStateProvider extends ChangeNotifier {
   List<ModelManifest> get availableModels => _availableModels;
   ModelManifest? get activeModel => engine.modelManager.activeModel;
   String? get downloadingModelId => _downloadingModelId;
+  String? get failedDownloadModelId => _failedDownloadModelId;
   double get downloadProgress => _downloadProgress;
   int get downloadReceivedBytes => _downloadReceivedBytes;
   int get downloadTotalBytes => _downloadTotalBytes;
@@ -759,6 +761,7 @@ class AppStateProvider extends ChangeNotifier {
 
     _errorMessage = null;
     _cancelledDownloadId = null;
+    _failedDownloadModelId = null;
     _downloadingModelId = manifest.id;
     _downloadProgress = 0;
     _downloadReceivedBytes = 0;
@@ -775,20 +778,26 @@ class AppStateProvider extends ChangeNotifier {
             snapshot.errorMessage != null &&
             _cancelledDownloadId != manifest.id) {
           _errorMessage = _presentableError(snapshot.errorMessage!);
+          _failedDownloadModelId = manifest.id;
         }
         _notifyListenersSafely();
       }
 
       await refreshModels();
-      await _attemptModelSwitch(manifest);
+      final bool switched = await _attemptModelSwitch(manifest);
+      if (switched) {
+        _failedDownloadModelId = null;
+      }
     } catch (error) {
       if (_cancelledDownloadId != manifest.id) {
         _errorMessage = _presentableError(error);
+        _failedDownloadModelId = manifest.id;
       }
       _notifyListenersSafely();
     } finally {
       if (_cancelledDownloadId == manifest.id) {
         _errorMessage = null;
+        _failedDownloadModelId = null;
       }
       _cancelledDownloadId = null;
       _downloadingModelId = null;

lib/presentation/pages/chat/chat_page.dart

@@ -1290,6 +1290,19 @@ class _ChatPageState extends State<ChatPage> with TickerProviderStateMixin {
                   ],
                 ),
               ),
+              IconButton(
+                key: const ValueKey<String>('chat-history-button'),
+                tooltip: l10n?.sessionHistoryShortLabel ?? 'History',
+                onPressed: disableOverflow
+                    ? null
+                    : () => unawaited(_openSessionHistory()),
+                icon: Icon(
+                  Icons.history_rounded,
+                  color: disableOverflow
+                      ? AppTheme.textMuted
+                      : AppTheme.textSecondary,
+                ),
+              ),
               PopupMenuButton<_ChatMenuAction>(
                 key: const ValueKey<String>('chat-overflow-button'),
                 enabled: !disableOverflow,

lib/presentation/pages/model_setup/model_setup_page.dart

@@ -260,6 +260,8 @@ class _SetupModelCardState extends State<_SetupModelCard> {
     final bool isInstalled = appState.isInstalled(widget.manifest);
     final bool isActive = appState.isActive(widget.manifest);
     final bool isDownloading = appState.isDownloading(widget.manifest);
+    final bool downloadFailed =
+        appState.failedDownloadModelId == widget.manifest.id && !isInstalled;
     final bool anotherDownloadInProgress =
         appState.downloadingModelId != null &&
             appState.downloadingModelId != widget.manifest.id;
@@ -382,6 +384,12 @@ class _SetupModelCardState extends State<_SetupModelCard> {
                     ),
                 ],
               ),
+              if (!isInstalled) ...<Widget>[
+                const SizedBox(height: 14),
+                _DownloadPrepNote(
+                  text: _downloadPrepCopy(context, widget.manifest),
+                ),
+              ],
               if (isDownloading) ...<Widget>[
                 const SizedBox(height: 24),
                 ClipRRect(
@@ -444,8 +452,10 @@ class _SetupModelCardState extends State<_SetupModelCard> {
                                 : isInstalled
                                     ? (l10n?.activateEngineButton ??
                                         'Activate Core')
-                                    : (l10n?.downloadInstallButton ??
-                                        'Download & Install'),
+                                    : downloadFailed
+                                        ? _retryDownloadLabel(context)
+                                        : (l10n?.downloadInstallButton ??
+                                            'Download & Install'),
                         style: const TextStyle(fontWeight: FontWeight.w700),
                       ),
                     ),
@@ -490,6 +500,45 @@ class _SetupModelCardState extends State<_SetupModelCard> {
   }
 }
 
+class _DownloadPrepNote extends StatelessWidget {
+  const _DownloadPrepNote({required this.text});
+
+  final String text;
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      width: double.infinity,
+      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+      decoration: BoxDecoration(
+        color: AppTheme.bgElevated.withValues(alpha: 0.72),
+        borderRadius: BorderRadius.circular(16),
+        border: Border.all(color: AppTheme.borderSubtle),
+      ),
+      child: Row(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: <Widget>[
+          const Icon(
+            Icons.storage_rounded,
+            size: 18,
+            color: AppTheme.textSecondary,
+          ),
+          const SizedBox(width: 10),
+          Expanded(
+            child: Text(
+              text,
+              style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                    color: AppTheme.textSecondary,
+                    height: 1.4,
+                  ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
 class _Badge extends StatelessWidget {
   const _Badge({required this.label, required this.color});
 
@@ -592,6 +641,25 @@ String _localizedRamHint(BuildContext context, ModelManifest manifest) {
   return l10n?.modelSetupRamHint(memory) ?? 'Recommended RAM $memory';
 }
 
+String _downloadPrepCopy(BuildContext context, ModelManifest manifest) {
+  final String locale =
+      Localizations.localeOf(context).toLanguageTag().toLowerCase();
+  final String size = formatBytes(manifest.sizeBytes);
+  if (locale.startsWith('zh')) {
+    return '下载前请预留至少 $size 的可用空间。下载中断后可直接重试，Aura 会尽量接着未完成的部分继续。';
+  }
+  return 'Keep at least $size free before downloading. If the download is interrupted, tap retry and Aura will continue whenever possible.';
+}
+
+String _retryDownloadLabel(BuildContext context) {
+  final String locale =
+      Localizations.localeOf(context).toLanguageTag().toLowerCase();
+  if (locale.startsWith('zh')) {
+    return '重试下载';
+  }
+  return 'Retry Download';
+}
+
 String _localizedModelError(BuildContext context, String message) {
   final AppLocalizations? l10n = AppLocalizations.of(context);
   switch (message) {

lib/presentation/widgets/import_preview_dialog.dart

@@ -14,7 +14,7 @@ import '../../core/platform/file_selector_type_groups.dart';
 import '../../core/theme/app_theme.dart';
 import 'character_editor_dialog.dart';
 
-enum _ImportSource { photos, files }
+enum _ImportSource { photos, files, worldbook, create }
 
 class ImportPreviewDialog extends StatefulWidget {
   const ImportPreviewDialog({
@@ -102,6 +102,10 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
   }
 
   Future<void> _pickAndParseFromSource(_ImportSource source) async {
+    if (source == _ImportSource.create) {
+      await _createCharacter();
+      return;
+    }
     if (_busy || _pickingFile) {
       return;
     }
@@ -151,6 +155,37 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
       _pickingFile = false;
       _busy = true;
     });
+    if (source == _ImportSource.worldbook) {
+      try {
+        final LorebookImportPreview lorebookPreview =
+            await lorebookPreviewLoader(sourceFile);
+        if (!mounted) {
+          return;
+        }
+        setState(() {
+          _preview = null;
+          _lorebookPreview = lorebookPreview;
+          _selectedLorebookTargetCharacterId ??=
+              appState.availableCharacters.isEmpty
+                  ? null
+                  : appState.availableCharacters.first.id;
+          _busy = false;
+          _error = null;
+        });
+        return;
+      } catch (error) {
+        if (!mounted) {
+          return;
+        }
+        setState(() {
+          _busy = false;
+          _preview = null;
+          _lorebookPreview = null;
+          _error = _friendlyErrorMessage(error);
+        });
+        return;
+      }
+    }
     try {
       final CharacterImportPreview preview = await previewLoader(sourceFile);
       if (!mounted) {
@@ -212,10 +247,13 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
   }
 
   Future<_ImportSource?> _chooseImportSource() async {
-    if (!_supportsPhotoImport) {
-      return _ImportSource.files;
-    }
     final AppLocalizations? l10n = AppLocalizations.of(context);
+    final bool isZh = Localizations.localeOf(context)
+        .toLanguageTag()
+        .toLowerCase()
+        .startsWith(
+          'zh',
+        );
     return showModalBottomSheet<_ImportSource>(
       context: context,
       backgroundColor: AppTheme.cardElevated,
@@ -249,16 +287,19 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
                     ),
                   ),
                   const SizedBox(height: 16),
-                  _buildImportSourceTile(
-                    context: sheetContext,
-                    key: const ValueKey<String>('import-source-photos'),
-                    icon: Icons.photo_library_rounded,
-                    title: l10n?.importFromPhotosTitle ?? 'Import From Photos',
-                    subtitle: l10n?.importFromPhotosSubtitle ??
-                        'Pick a Tavern PNG card that is already in your photo library.',
-                    source: _ImportSource.photos,
-                  ),
-                  const SizedBox(height: 10),
+                  if (_supportsPhotoImport) ...<Widget>[
+                    _buildImportSourceTile(
+                      context: sheetContext,
+                      key: const ValueKey<String>('import-source-photos'),
+                      icon: Icons.photo_library_rounded,
+                      title:
+                          l10n?.importFromPhotosTitle ?? 'Import From Photos',
+                      subtitle: l10n?.importFromPhotosSubtitle ??
+                          'Pick a Tavern PNG card that is already in your photo library.',
+                      source: _ImportSource.photos,
+                    ),
+                    const SizedBox(height: 10),
+                  ],
                   _buildImportSourceTile(
                     context: sheetContext,
                     key: const ValueKey<String>('import-source-files'),
@@ -268,6 +309,28 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
                         'Pick a Tavern PNG card, JSON card, or standalone worldbook from Files.',
                     source: _ImportSource.files,
                   ),
+                  const SizedBox(height: 10),
+                  _buildImportSourceTile(
+                    context: sheetContext,
+                    key: const ValueKey<String>('import-source-worldbook'),
+                    icon: Icons.menu_book_rounded,
+                    title: isZh ? '导入世界书' : 'Import Worldbook',
+                    subtitle: isZh
+                        ? '选择独立世界书 JSON，并把它挂到已有剧情卡下面。'
+                        : 'Pick a standalone worldbook JSON and attach it to an existing story card.',
+                    source: _ImportSource.worldbook,
+                  ),
+                  const SizedBox(height: 10),
+                  _buildImportSourceTile(
+                    context: sheetContext,
+                    key: const ValueKey<String>('import-source-create'),
+                    icon: Icons.draw_rounded,
+                    title: l10n?.createCharacterButton ?? 'Create Character',
+                    subtitle: isZh
+                        ? '不导入文件，直接自己写一张新的剧情卡。'
+                        : 'Start from a blank story card instead of importing a file.',
+                    source: _ImportSource.create,
+                  ),
                 ],
               ),
             ),
@@ -346,6 +409,14 @@ class _ImportPreviewDialogState extends State<ImportPreviewDialog> {
               acceptedTypeGroups: characterCardImportTypeGroups,
             ));
         return picked == null ? null : File(picked.path);
+      case _ImportSource.worldbook:
+        final XFile? picked = await (widget.pickFile?.call() ??
+            openFile(
+              acceptedTypeGroups: lorebookImportTypeGroups,
+            ));
+        return picked == null ? null : File(picked.path);
+      case _ImportSource.create:
+        return null;
     }
   }
 

packages/aura_core/lib/src/infrastructure/http_resumable_model_downloader.dart

@@ -114,6 +114,14 @@ class HttpResumableModelDownloader implements ModelDownloader {
         uri: uri,
       );
     }
+    if (existingBytes > 0 && response.statusCode == HttpStatus.ok) {
+      // Some hosts ignore Range and restart from byte 0. In that case, appending
+      // would corrupt the model by duplicating the already downloaded prefix.
+      existingBytes = 0;
+      if (await partialFile.exists()) {
+        await partialFile.delete();
+      }
+    }
 
     final IOSink sink = partialFile.openWrite(
       mode: existingBytes > 0 ? FileMode.append : FileMode.writeOnly,