feat(models): 模型自动下载(我的·模型管理) + 断点续传 + 旁路导入

实现 spec(2026-05-29-model-download-design)的模型分发功能:
- ModelManifest: 硬编码功能文件清单 + base URL https://file.myv0.com/
- FileDownloader: URLSessionDataDelegate 分块写盘,HTTP Range 断点续传 + 大小校验
  (根因修复:URL.resourceValues 会缓存文件大小,续传时先读 offset 再读 finalSize
   会拿到下载前的陈旧值导致校验误判;改用 FileManager.attributesOfItem)
- ModelDownloadService: @MainActor @Observable 编排逐文件下载,聚合进度/速度,
  支持下载全部/暂停/重试,以及旁路文件导入
- ModelStore: 新增 fileURL/localBytes/isComplete(可注入清单)/importModel(补 VL)
- ModelManagementView: 分模型卡片(状态/进度/速度) + 下载全部/暂停
  + NWPathMonitor 蜂窝提示 + 从文件导入(离线兜底)
- MeView: 模型管理卡改 NavigationLink + 动态状态(已就绪/下载中/N就绪)

测试(Swift Testing): Manifest 清单/字节数、Store 路径/校验/导入、
DownloadState、FileDownloader(URLProtocol mock:下载/Range续传/大小校验)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

康康Tests/ModelDownloadCoreTests.swift

@@ -0,0 +1,136 @@
+import Testing
+import Foundation
+@testable import 康康
+
+// MARK: - Mock 网络层
+
+/// 按 URL 注册完整响应体,startLoading 时按请求的 Range header 自动切片返回(206)或全量(200)。
+/// 每个测试用唯一 URL 注册自己的内容 → 测试间不会互相覆盖,无需依赖执行顺序或可见性。
+final class MockURLProtocol: URLProtocol, @unchecked Sendable {
+    private static let lock = NSLock()
+    private static var bodies: [String: Data] = [:]
+
+    static func register(_ url: URL, body: Data) {
+        lock.lock(); defer { lock.unlock() }
+        bodies[url.path] = body
+    }
+    static func reset() {
+        lock.lock(); defer { lock.unlock() }
+        bodies.removeAll()
+    }
+    private static func body(forPath path: String) -> Data? {
+        lock.lock(); defer { lock.unlock() }
+        return bodies[path]
+    }
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        guard let url = request.url, let full = Self.body(forPath: url.path) else {
+            client?.urlProtocol(self, didFailWithError: URLError(.fileDoesNotExist))
+            return
+        }
+        var data = full
+        var status = 200
+        var headers: [String: String] = [:]
+        if let range = request.value(forHTTPHeaderField: "Range"),
+           let start = Self.parseRangeStart(range), start <= full.count {
+            data = Data(full.suffix(from: start))
+            status = 206
+            headers["Content-Range"] = "bytes \(start)-\(full.count - 1)/\(full.count)"
+        }
+        let response = HTTPURLResponse(
+            url: url, statusCode: status, httpVersion: nil, headerFields: headers)!
+        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+        client?.urlProtocol(self, didLoad: data)
+        client?.urlProtocolDidFinishLoading(self)
+    }
+
+    override func stopLoading() {}
+
+    /// "bytes=2-" → 2
+    private static func parseRangeStart(_ s: String) -> Int? {
+        guard let eq = s.firstIndex(of: "="), let dash = s.firstIndex(of: "-") else { return nil }
+        return Int(s[s.index(after: eq)..<dash])
+    }
+}
+
+private func mockConfiguration() -> URLSessionConfiguration {
+    let config = URLSessionConfiguration.ephemeral
+    config.protocolClasses = [MockURLProtocol.self]
+    return config
+}
+
+private func tempFile() -> URL {
+    FileManager.default.temporaryDirectory
+        .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        .appendingPathComponent("a.bin")
+}
+
+private func uniqueURL() -> URL {
+    URL(string: "https://mock.test/\(UUID().uuidString).bin")!
+}
+
+// MARK: - DownloadState
+
+struct DownloadStateTests {
+    @Test func fractionZeroWhenTotalZero() {
+        let s = DownloadState(phase: .idle, receivedBytes: 0, totalBytes: 0, bytesPerSecond: 0)
+        #expect(s.fraction == 0)
+    }
+
+    @Test func fractionComputed() {
+        let s = DownloadState(phase: .downloading, receivedBytes: 50, totalBytes: 200, bytesPerSecond: 0)
+        #expect(s.fraction == 0.25)
+    }
+}
+
+// MARK: - FileDownloader
+
+/// 串行执行:这些测试共享全局 URLProtocol / URLSession 状态,并行会互相干扰。
+@Suite(.serialized)
+struct FileDownloaderTests {
+
+    @Test func downloadsFileContent() async throws {
+        let url = uniqueURL()
+        MockURLProtocol.register(url, body: Data("hello".utf8))
+        let dst = tempFile()
+        defer { try? FileManager.default.removeItem(at: dst.deletingLastPathComponent()) }
+
+        let dl = FileDownloader(configuration: mockConfiguration())
+        try await dl.download(from: url, to: dst, expectedBytes: 5)
+
+        #expect(try Data(contentsOf: dst) == Data("hello".utf8))
+        #expect(!FileManager.default.fileExists(atPath: dst.appendingPathExtension("part").path))
+    }
+
+    @Test func resumesFromPartialFile() async throws {
+        let url = uniqueURL()
+        MockURLProtocol.register(url, body: Data("hello".utf8))
+        let dst = tempFile()
+        defer { try? FileManager.default.removeItem(at: dst.deletingLastPathComponent()) }
+        // 预置已下载的一半,download 应从 offset 2 续传
+        try FileManager.default.createDirectory(
+            at: dst.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try Data("he".utf8).write(to: dst.appendingPathExtension("part"))
+
+        let dl = FileDownloader(configuration: mockConfiguration())
+        try await dl.download(from: url, to: dst, expectedBytes: 5)
+
+        #expect(try Data(contentsOf: dst) == Data("hello".utf8))
+    }
+
+    @Test func throwsOnSizeMismatch() async throws {
+        let url = uniqueURL()
+        MockURLProtocol.register(url, body: Data("hi".utf8))  // 仅 2 字节,期望 5
+        let dst = tempFile()
+        defer { try? FileManager.default.removeItem(at: dst.deletingLastPathComponent()) }
+
+        let dl = FileDownloader(configuration: mockConfiguration())
+        await #expect(throws: (any Error).self) {
+            try await dl.download(from: url, to: dst, expectedBytes: 5)
+        }
+        #expect(!FileManager.default.fileExists(atPath: dst.path))
+    }
+}

康康Tests/ModelManifestTests.swift

@@ -0,0 +1,47 @@
+import Testing
+import Foundation
+@testable import 康康
+
+struct ModelManifestTests {
+
+    @Test func llmHasNineFunctionalFiles() {
+        #expect(ModelManifest.files(for: .llm).count == 9)
+    }
+
+    @Test func vlHasElevenFunctionalFiles() {
+        #expect(ModelManifest.files(for: .vl).count == 11)
+    }
+
+    @Test func llmTotalBytesMatchesManifest() {
+        #expect(ModelManifest.totalBytes(for: .llm) == 984_013_244)
+    }
+
+    @Test func vlTotalBytesMatchesManifest() {
+        #expect(ModelManifest.totalBytes(for: .vl) == 3_089_710_883)
+    }
+
+    @Test func excludesReadmeAndGitattributes() {
+        for kind in [ModelKind.llm, .vl] {
+            let names = ModelManifest.files(for: kind).map(\.path)
+            #expect(!names.contains("README.md"))
+            #expect(!names.contains(".gitattributes"))
+        }
+    }
+
+    @Test func includesEssentialFiles() {
+        let llm = ModelManifest.files(for: .llm).map(\.path)
+        #expect(llm.contains("config.json"))
+        #expect(llm.contains("model.safetensors"))
+        #expect(llm.contains("tokenizer.json"))
+
+        let vl = ModelManifest.files(for: .vl).map(\.path)
+        #expect(vl.contains("preprocessor_config.json"))  // VL 拍照识别必需
+        #expect(vl.contains("model.safetensors"))
+    }
+
+    @Test func fileURLIsBaseSlashRepoSlashPath() {
+        let file = ModelFile(path: "config.json", bytes: 937)
+        let url = ModelManifest.fileURL(for: .llm, file: file)
+        #expect(url.absoluteString == "https://file.myv0.com/Qwen3-1.7B-4bit/config.json")
+    }
+}

康康Tests/ModelStoreDownloadSupportTests.swift

@@ -0,0 +1,92 @@
+import Testing
+import Foundation
+@testable import 康康
+
+struct ModelStoreDownloadSupportTests {
+
+    private func isolatedStore() throws -> ModelStore {
+        let temp = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        return try ModelStore(rootURL: temp)
+    }
+
+    @Test func fileURLPointsIntoModelFolder() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let url = store.fileURL(for: .llm, relativePath: "config.json")
+        #expect(url == store.localURL(for: .llm).appendingPathComponent("config.json"))
+    }
+
+    @Test func localBytesZeroWhenMissing() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        #expect(store.localBytes(for: .llm, relativePath: "config.json") == 0)
+    }
+
+    @Test func localBytesReturnsFileSize() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let folder = store.localURL(for: .llm)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        try Data(repeating: 7, count: 512).write(to: folder.appendingPathComponent("config.json"))
+        #expect(store.localBytes(for: .llm, relativePath: "config.json") == 512)
+    }
+
+    @Test func isCompleteFalseWhenFilesMissing() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let files = [ModelFile(path: "a.bin", bytes: 1024)]
+        #expect(store.isComplete(for: .llm, files: files) == false)
+    }
+
+    @Test func isCompleteTrueWhenAllFilesPresentWithExpectedSize() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let folder = store.localURL(for: .llm)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        try Data(repeating: 1, count: 1024).write(to: folder.appendingPathComponent("a.bin"))
+        let files = [ModelFile(path: "a.bin", bytes: 1024)]
+        #expect(store.isComplete(for: .llm, files: files) == true)
+    }
+
+    @Test func isCompleteFalseWhenSizeMismatch() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let folder = store.localURL(for: .llm)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        try Data(repeating: 1, count: 999).write(to: folder.appendingPathComponent("a.bin"))
+        let files = [ModelFile(path: "a.bin", bytes: 1024)]
+        #expect(store.isComplete(for: .llm, files: files) == false)
+    }
+
+    @Test func importModelCopiesFolderAndMarksReady() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+
+        let src = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        try FileManager.default.createDirectory(at: src, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: src) }
+        try "{}".write(to: src.appendingPathComponent("config.json"), atomically: true, encoding: .utf8)
+        try "x".write(to: src.appendingPathComponent("tokenizer.json"), atomically: true, encoding: .utf8)
+
+        try store.importModel(.llm, from: src)
+
+        #expect(store.isReady(.llm) == true)
+        #expect(FileManager.default.fileExists(
+            atPath: store.fileURL(for: .llm, relativePath: "tokenizer.json").path))
+    }
+
+    @Test func importModelThrowsWhenNoConfig() throws {
+        let store = try isolatedStore()
+        defer { try? FileManager.default.removeItem(at: store.rootURL) }
+        let src = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        try FileManager.default.createDirectory(at: src, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: src) }
+
+        #expect(throws: (any Error).self) {
+            try store.importModel(.llm, from: src)
+        }
+    }
+}