Project Overview

DeepSeek Harness Mobile (DshMobile) is a community-native mobile client for DeepSeek Harness. The project has completed its migration to the Kotlin Multiplatform (KMP) architecture and now ships runnable Android and iOS applications:

• shared handles the cross-platform protocol, state machines, Reducers, projections and sync logic, and is the single source of truth for shared business state.
• androidApp implements the Android product features using Kotlin, Jetpack Compose and OkHttp.
• DeepSeekHarnessMobile builds the iOS UI with SwiftUI/UIKit and connects to the shared logic via the Kotlin/Native framework.

Both platforms establish a WebSocket connection to Harness via dsh-plugin-mobile-gateway. Networking, secure storage, files, images, lifecycle and background tasks are implemented natively on each platform, while business rules are consolidated into shared/commonMain as much as possible.

Current Platform Status

Platform/Module	Current Status	Key Implementation
KMP shared	Integrated into Android and iOS	Gateway protocol, Store/Reducer, Conversation/Trajectory projection, History sync, Question/Approval, Session Control, workspace file state and code preview support
Android	Native client implemented	Jetpack Compose, OkHttp WebSocket, DataStore (non-sensitive config), Keystore (credentials), CameraX/ML Kit QR scanning, foreground service, attachment cache, file download and preview
iOS	Native client implemented	SwiftUI/UIKit, URLSession WebSocket, UserDefaults (non-sensitive config), Keychain (credentials), QR pairing, background execution, attachments and workspace files

Android and iOS use their own native UI and platform capabilities, not shared UI. Features stay aligned, but system-level behaviors may differ per platform.

Feature Highlights

• Native real-time conversation: handles incremental WebSocket events, and renders Markdown, code, thinking process, tool calls, tool results and image attachments.
• Decoupled history and real-time: paginated history loading preserves the live tail, deduplicates by sequence and event identity, preventing message duplication or regression.
• Full Agent trajectory: view User, Assistant, Tool and other events, along with call parameters, results, Schema, Token and elapsed-time information.
• Workspace and session management: browse, create and switch workspaces on the Harness host remotely; search, create, switch and archive sessions.
• Workspace files: browse remote directories on the Harness host, download files in chunks, verify integrity, preview common code files or open them with system apps.
• Interactive Agent flow: supports Human Question and tool-approval requests; you can submit, cancel, reject, or allow-once.
• Session and default settings: manage Agent presets, Provider/model, thinking level and read-only, workspace-write, danger-full-access Harness Agent permissions; these are not local file-system permissions on the phone.
• Secure device pairing: scan the WebUI QR code or manually enter pairing information; long-lived credentials are saved to platform secure storage.
• Mobile lifecycle: Android keeps the connection alive via a foreground service during Agent turn execution; iOS uses the system-granted limited background execution time to manage active tasks and does not guarantee indefinite WebSocket maintenance.
• Light and dark themes: both platforms provide native theme adaptation, preserving Harness's deep-sea, grid and whale visual language.

UI Preview

The current UI screenshots in the repository are from the iOS version; Android implements the same information architecture and core flows with Jetpack Compose.

Core Experience

工作区首页 工作区与最近会话	对话 Markdown、代码与工具结果	轨迹 时间概览与事件时间线

Default Settings

设置 部署默认值与 Gateway 状态	Agent 预设 工具、提示词与能力组合	默认模型 Provider、模型与思考等级

Workspace Ops & Trajectory Details

切换工作区 快速访问不同项目	目录选择 浏览并创建工作区	轨迹详情 摘要、Token 与内容预览

Light, Dark and Device Pairing

浅色配对 扫码或手动输入	深色配对 完整深色模式适配	深色对话 阅读、代码与输入面板

Architecture

                         DeepSeek Harness
                                │
                  dsh-plugin-mobile-gateway
                                │
                             WebSocket
                ┌───────────────┴───────────────┐
                │                               │
     Android OkHttp Transport          iOS URLSession GatewayClient
                │                               │
       KMP Gateway Runtime             Swift Router / KMP Adapter
                │                               │
                └───────────────┬───────────────┘
                                │
                    KMP shared / commonMain
            Protocol · Store · Reducer · Projection
       History Sync · Question/Approval · Workspace Files
                ┌───────────────┴───────────────┐
                │                               │
       Jetpack Compose                     SwiftUI / UIKit
          Android UI                          iOS UI

Shared Layer

• protocol/: Gateway DTOs, JSON representations and wire decoder.
• gateway/: platform transport interfaces, plus pairing, authentication, request correlation, reconnection and event backpressure strategies. Android uses the full shared Runtime, with OkHttp implementing only the underlying transport.
• domain/: Reducers for Session, Question, Approval and Session Control.
• projection/: incremental projection of Conversation and Trajectory.
• sync/: History pagination, live-tail merging and deduplication.
• facade/: coarse-grained Store, Intent and Event for the Swift/Kotlin platform layer, plus workspace paths, chunk ordering, progress and SHA-256 verification logic.

The shared layer has no dependencies on Compose, SwiftUI, the Android Framework or Apple UI Frameworks. iOS reuses the shared Store, Reducer, Projection and file state machines, but currently the Swift GatewayClient is still responsible for WebSocket, connection and reconnection, feeding events into the shared layer via an Adapter; it has not yet been integrated with the full KMP Gateway Runtime.

Android and iOS each handle secure storage, image processing, temp-file writes, system share/open and lifecycle on the platform side. The shared layer handles remote file protocol, state, chunk consistency and integrity checks, without touching the platform file system.

Project Structure

.
├── shared/                         # Kotlin Multiplatform 共享业务模块
│   └── src/
│       ├── commonMain/             # 协议、状态机、投影、同步与 facade
│       └── commonTest/             # 跨平台单元测试
├── androidApp/                     # Android 原生应用（Jetpack Compose）
│   └── src/
│       ├── main/                   # 产品代码与平台实现
│       ├── test/                   # JVM 测试
│       └── androidTest/            # 设备测试
├── DeepSeekHarnessMobile/          # iOS 原生应用（SwiftUI/UIKit）
├── DeepSeekHarnessMobileTests/     # iOS XCTest
├── DeepSeekHarnessMobile.xcodeproj
├── Docs/                           # 调研、KMP 迁移与验证文档
└── Design/                         # 设计规范与展示素材

Requirements

General

• Java 17
• DeepSeek Harness with dsh-plugin-mobile-gateway enabled
• An emulator or physical device that can reach the Mobile Gateway

Android

• Android Studio or Android SDK Command-line Tools
• Android SDK Platform 36 (compileSdk / targetSdk)
• A device or emulator running Android 7.0 (API 24) or later

iOS

• macOS and Xcode that can build for iOS 17.0+
• An iOS 17.0+ simulator or physical device
• Android SDK (the Xcode build step compiles the KMP framework via Gradle)

Running on Android

1. Configure Java 17 and make sure ANDROID_HOME or ANDROID_SDK_ROOT points to the Android SDK.

2. Build the Debug APK from the repository root:

   ./gradlew :androidApp:assembleDebug
   

3. Install it on the connected device or emulator:

   ./gradlew :androidApp:installDebug
   

4. Launch DshMobile, then scan the pairing QR code generated by the WebUI or manually enter the pairing information.

The Debug APK is located at:

androidApp/build/outputs/apk/debug/androidApp-debug.apk

When the Android Emulator needs to reach the host's 127.0.0.1:3080, you can first run:

adb reverse tcp:3080 tcp:3080

Running on iOS

1. Configure Java 17 and the Android SDK.
2. Open DeepSeekHarnessMobile.xcodeproj with Xcode.
3. Select the DeepSeekHarnessMobile scheme and target device.
4. Build and run. The Build KMP Framework phase in Xcode will automatically select and compile the corresponding Kotlin/Native framework.
5. In the app, scan the WebUI pairing QR code or manually enter the pairing information.

There is no need to build the framework manually beforehand; if you want to generate an Apple Silicon iOS Simulator framework separately, you can run:

./gradlew :shared:linkDebugFrameworkIosSimulatorArm64

Pairing

1. Install and enable dsh-plugin-mobile-gateway in DeepSeek Harness.
2. Open the WebUI's "Mobile Devices" panel and enable mobile device connection and device authentication.
3. Verify that the WebSocket address is reachable from the phone or emulator.
4. Generate a one-time pairing QR code/Token and complete authentication in the Android or iOS client.
5. Return to the home page, confirm that the Gateway status is connected, then select a workspace and session.

Typical:

Scenario	Address
iOS Simulator	ws://127.0.0.1:3080/ws/mobile
Android Emulator + adb reverse	ws://127.0.0.1:3080/ws/mobile
Physical device on the same LAN	ws://<HOST-LAN-IP>:3080/ws/mobile
Public deployment	wss://<your-domain>/ws/mobile

[!IMPORTANT] Physical devices cannot reach your computer via 127.0.0.1. The ws:// addresses in the table are for trusted local development environments only; public or untrusted networks must use wss:// with properly configured TLS and device authentication. One-time pairing Tokens must not be written into logs, Issues or chat records.

Build and Test

Run shared-layer tests, Android unit tests, Lint and the APK build:

./gradlew \
  :shared:allTests \
  :androidApp:testDebugUnitTest \
  :androidApp:lintDebug \
  :androidApp:assembleDebug

With an available Android device or emulator, you can additionally run:

./gradlew :androidApp:connectedDebugAndroidTest

iOS tests can be run from Xcode by selecting the DeepSeekHarnessMobile scheme and choosing Product → Test. The build phase automatically links the DeepSeekHarnessShared.framework for the corresponding architecture.

Related Documents

• Harness / WebUI features and protocol exploration
• Mobile design spec
• Third-party license notices

The docs below record the KMP migration and Android landing process; interim status is governed by this doc and the current code:

• KMP development notes
• Android Gateway stage 12 verification record
• Android UI stage 13 verification record

Current Status

The project is under continuous development. The KMP shared layer, the Android native app and the iOS native app are all in place, and the protocol, cross-platform consistency and mobile experience will continue to evolve along with DeepSeek Harness and the Mobile Gateway.

This project is a community client for DeepSeek Harness and does not represent an official DeepSeek release.