sing-box-windows-android: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个基于 sing-box 核心的 Android VPN 客户端应用，使用 Kotlin 和 Jetpack Compose (Material 3) 构建。应用支持订阅管理、节点选择、流量监控和 Clash API 诊断等功能。

构建命令

# 构建 Debug 版本
./gradlew assembleDebug

# 构建 Release 版本
./gradlew assembleRelease

# 安装到连接的设备
./gradlew installDebug

# 按架构构建特定 APK (splits.abi 配置)
./gradlew assembleRelease  # 会生成 arm64-v8a, armeabi-v7a, x86, x86_64 四个独立 APK

架构概览

核心架构模式

应用采用 Clean Architecture + MVI 模式：

1. 领域层 (v2/domain): 只定义能力接口与领域模型，不含任何 Android / libbox 类型
2. 数据层 (v2/data): 全部实现（内核命令层、配置仓储、订阅仓储）
3. 功能层 (v2/feature): 页面 + MVI ViewModel，仅依赖领域接口
4. MVI 基座 (v2/core/arch): 统一 Intent / State / Effect 数据流， Intent 通过 Channel 串行消费，避免并发交错导致的重复提交

依赖方向单向：feature → domain ← data。

关键组件

1. VPN 服务层 (vpn/) — 系统边界

• AppVpnService: Android VpnService 实现，负责 VPN 接口建立与生命周期
• VpnStateStore: 全局 VPN 状态单例 (IDLE/CONNECTING/CONNECTED/ERROR)
• VpnController: 控制 VPN 服务的启动/停止
• PlatformInterfaceBridge: 实现 libbox 1.14 的 PlatformInterface； Shell / SSH / Bridge / Tailscale 等平台专属能力在 Android 上显式返回「不支持」

2. 内核命令层 (v2/data/core) — ★ 核心

• LibboxBootstrap: libbox 全局引导（SetupOptions，含 commandServerListenPort = 0）
• SingBoxEngine: 由 CommandServer 托管内核实例（1.11 起 libbox 不再暴露独立 BoxService）
• DefaultCoreGateway: 基于 CommandClient 的 CoreGateway 实现， 内含 CommandClientHandler 回调转接
• CoreCommandBridge: 进程级单例，供 DI 容器与 VPN 服务共享同一条命令通道
• CoreRuntimeCoordinator: 配置准备 + 命令通道生命周期编排
• CoreInfoStore: 内核版本（直接读 Libbox.version()）

3. 配置层 (v2/data/config)

领域模型已下沉到 v2/domain：AppSettings → v2/domain/settings， 订阅模型 → v2/domain/subscription，VpnState → v2/domain/runtime， 更新模型 → v2/domain/update。

• ConfigRepository: sing-box JSON 配置的加载、保存和迁移
• ConfigSettingsApplier: 将用户设置应用到配置 JSON
• ConfigDefaults: 默认配置模板
• SubscriptionRepository: 订阅列表 CRUD，支持远程订阅与本地节点导入
• ClashConverter: Clash YAML 配置转换为 sing-box JSON
• SettingsRepository/AppSettings: 用户设置持久化