docs: 重写 README 同步至 v20，新增 HTML 版页面

2026-10-11 21:03:53 +08:00
parent 8c1383fe4f
commit b6b1b712a4
2 changed files with 322 additions and 31 deletions
@@ -0,0 +1,227 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SmbFast 极速 SMB 客户端 · README</title>
+<style>
+  :root {
+    --bg: #070d18;
+    --bg2: #0a1424;
+    --card: rgba(255,255,255,.055);
+    --card-border: rgba(255,255,255,.13);
+    --text: #e8eef7;
+    --dim: #93a3ba;
+    --faint: #5c6b83;
+    --cyan: #22d3ee;
+    --violet: #a78bfa;
+    --pink: #f472b6;
+    --lime: #a3e635;
+    --amber: #fbbf24;
+    --grad: linear-gradient(100deg, var(--cyan), var(--violet) 55%, var(--pink));
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html { scroll-behavior: smooth; }
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font: 15px/1.75 -apple-system, "Segoe UI", "Microsoft YaHei", "PingFang SC", sans-serif;
+    overflow-x: hidden;
+  }
+  /* ---- 极光背景 ---- */
+  .aurora { position: fixed; inset: 0; z-index: -1; overflow: hidden; background: var(--bg); }
+  .blob { position: absolute; border-radius: 50%; filter: blur(90px); opacity: .5; }
+  .blob.b1 { width: 55vw; height: 55vw; left: -12vw; top: -18vw; background: radial-gradient(circle, rgba(34,211,238,.34), transparent 65%); animation: drift1 26s ease-in-out infinite alternate; }
+  .blob.b2 { width: 60vw; height: 60vw; right: -15vw; bottom: -22vw; background: radial-gradient(circle, rgba(167,139,250,.32), transparent 65%); animation: drift2 32s ease-in-out infinite alternate; }
+  .blob.b3 { width: 42vw; height: 42vw; right: 5vw; top: -12vw; background: radial-gradient(circle, rgba(244,114,182,.16), transparent 65%); animation: drift1 38s ease-in-out infinite alternate-reverse; }
+  @keyframes drift1 { to { transform: translate(9vw, 6vh) scale(1.12); } }
+  @keyframes drift2 { to { transform: translate(-8vw, -7vh) scale(.92); } }
+  @media (prefers-reduced-motion: reduce) { .blob { animation: none; } html { scroll-behavior: auto; } }
+
+  .wrap { max-width: 980px; margin: 0 auto; padding: 0 22px 90px; }
+
+  /* ---- 头部 ---- */
+  header { padding: 84px 0 42px; text-align: center; }
+  .appicon {
+    width: 84px; height: 84px; margin: 0 auto 22px; border-radius: 22px;
+    background: var(--grad); display: grid; place-items: center;
+    font-size: 40px; font-weight: 800; color: #04121e;
+    box-shadow: 0 10px 44px rgba(34,211,238,.35);
+  }
+  h1 {
+    font-size: clamp(30px, 5.5vw, 46px); font-weight: 800; letter-spacing: .5px;
+    background: var(--grad); -webkit-background-clip: text; background-clip: text; color: transparent;
+  }
+  .tagline { color: var(--dim); margin-top: 10px; font-size: 16px; }
+  .badges { display: flex; flex-wrap: wrap; gap: 9px; justify-content: center; margin-top: 20px; }
+  .badge {
+    font-size: 12px; color: var(--dim); padding: 5px 13px; border-radius: 999px;
+    background: var(--card); border: 1px solid var(--card-border);
+  }
+  .badge b { color: var(--text); font-weight: 600; }
+
+  /* ---- 区块 ---- */
+  section { margin-top: 52px; }
+  h2 {
+    display: flex; align-items: center; gap: 12px;
+    font-size: 21px; font-weight: 700; margin-bottom: 18px;
+  }
+  h2::before { content: ""; width: 26px; height: 4px; border-radius: 4px; background: var(--grad); flex: none; }
+  h3 { font-size: 16px; color: var(--cyan); margin: 20px 0 8px; font-weight: 600; }
+  p { color: var(--dim); margin: 8px 0; }
+  p strong, li strong { color: var(--text); font-weight: 600; }
+  a { color: var(--cyan); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  ul.list { list-style: none; display: grid; gap: 9px; margin-top: 12px; }
+  ul.list li { padding-left: 26px; position: relative; color: var(--dim); }
+  ul.list li::before { content: "◆"; position: absolute; left: 4px; font-size: 11px; top: 6px; background: var(--grad); -webkit-background-clip: text; background-clip: text; color: transparent; }
+
+  /* ---- 卡片 ---- */
+  .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(275px, 1fr)); gap: 14px; margin-top: 16px; }
+  .card {
+    background: var(--card); border: 1px solid var(--card-border);
+    border-radius: 16px; padding: 18px 20px;
+  }
+  .card h3 { margin: 0 0 6px; font-size: 15px; }
+  .card p { font-size: 13.5px; margin: 0; }
+  .card .ico { font-size: 20px; display: inline-grid; place-items: center; width: 38px; height: 38px; border-radius: 11px; background: var(--grad); color: #04121e; margin-bottom: 10px; }
+
+  /* ---- 表格 ---- */
+  table { width: 100%; border-collapse: collapse; margin-top: 14px; font-size: 14px; }
+  th, td { text-align: left; padding: 11px 14px; border-bottom: 1px solid rgba(255,255,255,.08); vertical-align: top; }
+  th { color: var(--cyan); font-weight: 600; font-size: 13px; white-space: nowrap; }
+  td:first-child { white-space: nowrap; color: var(--text); font-weight: 500; }
+  td { color: var(--dim); }
+  tr:hover td { background: rgba(255,255,255,.03); }
+  .tw { overflow-x: auto; }
+
+  /* ---- 代码 ---- */
+  pre {
+    background: rgba(0,0,0,.42); border: 1px solid var(--card-border);
+    border-radius: 13px; padding: 16px 18px; overflow-x: auto;
+    font: 13px/1.7 Consolas, "JetBrains Mono", monospace; color: #c9d7ea; margin: 14px 0;
+  }
+  pre .c { color: var(--faint); }
+  code {
+    font: 13px Consolas, monospace; background: rgba(34,211,238,.12);
+    color: var(--cyan); padding: 2px 7px; border-radius: 6px;
+  }
+  pre code { background: none; color: inherit; padding: 0; }
+
+  .note {
+    border-left: 3px solid var(--cyan); background: rgba(34,211,238,.07);
+    border-radius: 0 12px 12px 0; padding: 12px 16px; margin: 16px 0; color: var(--dim); font-size: 13.5px;
+  }
+  .note.warn { border-color: var(--amber); background: rgba(251,191,36,.07); }
+  .foot { margin-top: 70px; text-align: center; color: var(--faint); font-size: 12.5px; }
+  .foot .g { background: var(--grad); -webkit-background-clip: text; background-clip: text; color: transparent; font-weight: 700; }
+  section ul li { scroll-margin-top: 20px; }
+</style>
+</head>
+<body>
+<div class="aurora"><div class="blob b1"></div><div class="blob b2"></div><div class="blob b3"></div></div>
+<div class="wrap">
+
+  <header>
+    <div class="appicon">⚡</div>
+    <h1>SmbFast 极速 SMB 客户端</h1>
+    <p class="tagline">以传输速度为第一目标的安卓 SMB2/SMB3 客户端 · SMBJ + Jetpack Compose · 为局域网 NAS 而生</p>
+    <div class="badges">
+      <span class="badge">当前版本 <b>v20 · 1.18.0</b></span>
+      <span class="badge">Android <b>8.0+</b></span>
+      <span class="badge">Kotlin · Compose M3</span>
+      <span class="badge">SMBJ <b>0.15.0</b> · SMB 3.1.1</span>
+      <span class="badge">HyperOS 灵动岛</span>
+    </div>
+  </header>
+
+  <section>
+    <h2>功能总览</h2>
+    <div class="grid">
+      <div class="card"><span class="ico">🔌</span><h3>连接管理</h3><p>自动发现共享（自研 DCERPC 枚举，fnOS/群晖/Samba/Windows 实测）；<strong>多选共享批量创建连接</strong>；域账号/匿名；TCP 预探测，填错 IP 5 秒内中文报错。</p></div>
+      <div class="card"><span class="ico">📁</span><h3>文件浏览</h3><p>目录浏览、面包屑导航、新建文件夹、重命名、删除，按类型显示图标；连接全程池化，无重复握手。</p></div>
+      <div class="card"><span class="ico">🚀</span><h3>多流高速传输</h3><p>下载与上传均为多流条带并行（4~16 流、1~8MB 分块），轮转交错写入对机械盘友好，内置 48MB 内存护栏。</p></div>
+      <div class="card"><span class="ico">🌙</span><h3>后台不断连</h3><p>前台服务（dataSync）+ WiFi 低延迟锁 + CPU 唤醒锁；通知栏进度/速度/全部停止；退后台、熄屏照常满速。</p></div>
+      <div class="card"><span class="ico">🏝️</span><h3>HyperOS 灵动岛</h3><p>小米焦点通知/超级岛适配（miui.focus.param 双轨协议），传输进度上岛；其他品牌自动忽略，零副作用。</p></div>
+      <div class="card"><span class="ico">🛡️</span><h3>安全与健壮</h3><p>凭据 AndroidKeyStore AES/GCM 加密存储；失败自动重试一次 + 一键重试；下载前磁盘空间预检；上传自动改名防覆盖。</p></div>
+    </div>
+  </section>
+
+  <section>
+    <h2>为什么快</h2>
+    <div class="tw">
+      <table>
+        <tr><th>手段</th><th>说明</th></tr>
+        <tr><td>SMB 3.1.1 协商</td><td>优先协商 SMB3 大 MTU，单请求 MaxRead/MaxWrite 可达 8MB（SMB2 仅 1MB）</td></tr>
+        <tr><td>多流条带并行</td><td>大文件切条带，每条带独立 SMB 句柄并行读写，靠 credits 在单 TCP 连接上流水线并发</td></tr>
+        <tr><td>轮转交错写入</td><td>各条带按块轮转推进，写入聚在 ~8MB 连续窗口整体前移——机械盘不再来回寻道，速度稳</td></tr>
+        <tr><td>大分块</td><td>请求粒度默认 1MB、可调 8MB，自动按服务器协商值截断，减少 RTT 往返</td></tr>
+        <tr><td>连接复用</td><td>Connection / Session / Share 全程池化，浏览与传输无重复握手</td></tr>
+        <tr><td>关闭签名/加密</td><td>默认不做 SMB 签名与加密以换取吞吐（服务器强制时自动回退协商）</td></tr>
+        <tr><td>零拷贝拼装</td><td>FileChannel 定位写 + pread 并发读，多协程安全</td></tr>
+        <tr><td>内存护栏</td><td>条带缓冲合计上限 48MB，配置拉满也不堆溢出闪退</td></tr>
+      </table>
+    </div>
+    <div class="note">实测建议：手机连 <strong>5GHz Wi-Fi</strong>、靠近路由器，NAS 开 SMB3。千兆内网理论 ~110MB/s，手机无线一般可跑 <strong>50~80MB/s</strong>。机械盘 NAS 求稳把并行流数调到 2~4，固态盘 4~6。</div>
+  </section>
+
+  <section>
+    <h2>构建</h2>
+    <p>要求 JDK 17+、Android SDK（platform 35 / build-tools 34+）。Gradle 走阿里云镜像（<code>settings.gradle.kts</code>），国内无需代理。</p>
+<pre><code>./gradlew :app:assembleDebug        <span class="c"># 调试包</span>
+./gradlew :app:assembleRelease      <span class="c"># 签名 release（密钥库 smbfast.keystore 已含在仓库）</span>
+./gradlew :app:testReleaseUnitTest  <span class="c"># 单元测试（含 fnOS 真实响应回归样本）</span></code></pre>
+    <div class="note warn">⚠️ 仓库内含签名密钥与密码（克隆即可构建同签名 APK，升级不冲突）。<strong>若要公开仓库，请先把密钥移出 git 历史并更换密码。</strong></div>
+  </section>
+
+  <section>
+    <h2>使用</h2>
+    <ul class="list">
+      <li>首页点 <strong>＋</strong> 添加连接：填 NAS 的 IP、用户名密码（或匿名）</li>
+      <li>点「<strong>自动发现共享</strong>」枚举全部共享，连点多个胶囊批量勾选，「测试并连接（N 个）」一次建多条连接</li>
+      <li>浏览目录，文件菜单选择<strong>下载 / 下载并打开</strong>，工具栏可上传本机文件（远端同名自动改名，不覆盖）</li>
+      <li>「传输」页查看实时速度与峰值，失败任务点 <strong>↻</strong> 重试</li>
+      <li>设置页可调并行流数 / 分块大小，查看下载目录与<strong>错误日志</strong>（闪退、传输失败都自动记录）</li>
+    </ul>
+    <h3>局域网分发</h3>
+    <p>电脑在 <code>dist/</code> 目录起 <code>python -m http.server 8080</code>，手机浏览器访问 <code>http://电脑IP:8080/SmbFast-release-v20.apk</code> 直接安装——聊天工具传 APK 常被截断，导致「解析软件包出现问题 (33)」。</p>
+  </section>
+
+  <section>
+    <h2>版本历程</h2>
+    <div class="tw">
+      <table>
+        <tr><th>版本</th><th>主要变化</th></tr>
+        <tr><td>1.0 ~ 1.8</td><td>基础功能、Compose 界面、多流下载、崩溃日志体系、DCERPC 共享枚举字节级攻坚（fnOS 实测）</td></tr>
+        <tr><td>1.9.0 (v11)</td><td>连接编辑改为全屏分区页面，视觉全面华丽化</td></tr>
+        <tr><td>1.10.0 (v12)</td><td>共享多选、批量建连；整体 UI 缩小一号</td></tr>
+        <tr><td>1.11.0 (v13)</td><td>前台服务保活 + WiFi/CPU 锁，修复后台传输被系统断连</td></tr>
+        <tr><td>1.12.0 (v14)</td><td>上传多流条带化；修复条带句柄互相截断的 bug</td></tr>
+        <tr><td>1.13 ~ 1.14</td><td>HyperOS 焦点通知/超级岛适配；修复横幅轰炸与双轨协议（v15/v16）</td></tr>
+        <tr><td>1.15.0 (v17)</td><td>TCP 预探测 + 异常链穿透翻译：填错 IP 5 秒内中文报错</td></tr>
+        <tr><td>1.16.0 (v18)</td><td>编辑模式同样支持多选共享</td></tr>
+        <tr><td>1.17.0 (v19)</td><td>内存护栏、自动重试、空间预检、上传防覆盖、凭据加密、通知「全部停止」</td></tr>
+        <tr><td>1.18.0 (v20)</td><td>全局单层极光背景，修复切页闪烁</td></tr>
+      </table>
+    </div>
+  </section>
+
+  <section>
+    <h2>已知限制</h2>
+    <ul class="list">
+      <li>SMBJ 不支持 SMB3 Multichannel（多网卡聚合），多流并行在同一 TCP 连接上实现</li>
+      <li>暂不支持 SMB over QUIC / 直连 TLS，未做流媒体边下边播</li>
+      <li>下载断点续传未实现（失败重试为从头重传，已在路线图）</li>
+      <li>HyperOS 岛能否点亮取决于系统侧「焦点通知」权限，个别固件对侧载应用收紧</li>
+    </ul>
+  </section>
+
+  <section>
+    <h2>技术栈</h2>
+    <p><code>Kotlin</code> <code>Jetpack Compose · Material 3</code> <code>SMBJ 0.15.0</code> <code>BouncyCastle</code> <code>Coroutines</code> <code>Gson</code> <code>AndroidKeyStore</code></p>
+  </section>
+
+  <div class="foot">SmbFast · 个人项目，仅供学习交流 · <span class="g">极光玻璃 UI · 极速 SMB</span></div>
+</div>
+</body>
+</html>
@@ -1,55 +1,119 @@
-# SMB 极速 (SmbFast)
+# SmbFast 极速 SMB 客户端

-一个以**传输速度为第一目标**的安卓 SMB 客户端，基于 SMB2/SMB3 协议（SMBJ 库）+ Jetpack Compose。
+一个以**传输速度为第一目标**的安卓 SMB 客户端，基于 SMB2/SMB3 协议（SMBJ 库）+ Jetpack Compose Material3，专为局域网 NAS 场景打造。当前版本 **v20（1.18.0）**。

-## 功能
+[English](#english) · 极光玻璃界面 · 后台不断连 · HyperOS 灵动岛

- **连接管理**：添加/编辑/删除 NAS、Windows 共享连接，支持域账号、匿名登录，连接前可测试
- **文件浏览**：共享目录浏览（面包屑导航）、新建文件夹、重命名、删除、按类型显示图标
- **高速下载**：多流分块并行下载（默认 4 流、1MB 分块，可调至 16 流 / 8MB）
- **上传**：系统文件选择器上传（顺序流）；本地文件多流并行上传
- **传输管理**：实时进度、实时速度（EMA 平滑）、取消、完成后直接打开
- **设置**：并行流数、分块大小、下载目录
+---

-## 为什么快
+## ✨ 功能总览
+
+- **连接管理**：添加/编辑/删除连接，支持域账号与匿名登录；「自动发现共享」一键枚举服务器上全部共享（自研 DCERPC srvsvc 枚举，fnOS/群晖/Samba/Windows 实测可用），**支持多选共享批量创建连接**
+- **文件浏览**：目录浏览、面包屑导航、新建文件夹、重命名、删除、按类型显示图标
+- **高速下载/上传**：下载与上传均为**多流条带并行**（默认 4 流、1MB 分块，可调 16 流 / 8MB），交错式写入对机械盘友好
+- **后台传输**：前台服务（dataSync）+ WiFi 低延迟锁 + CPU 唤醒锁，退后台/熄屏不断连；通知栏显示进度与速度，可「全部停止」
+- **HyperOS 灵动岛**：小米 HyperOS 2 焦点通知 / HyperOS 3 超级岛适配，传输进度上岛（其他品牌自动忽略、零副作用）
+- **传输中心**：实时速度仪表（EMA 平滑）、会话峰值、失败任务一键重试、下载失败自动重试一次
+- **健壮性**：填错 IP 5 秒内给出中文原因（TCP 预探测 + 异常链穿透翻译）；下载前磁盘空间预检；上传自动改名防覆盖远端文件
+- **安全**：NAS 凭据使用 AndroidKeyStore AES/GCM 加密存储；独立签名密钥
+- **诊断**：崩溃与传输错误自动写入日志，设置页可查看/复制
+
+## 🚀 为什么快

 | 手段 | 说明 |
 | --- | --- |
 | SMB 3.1.1 协商 | 优先协商 SMB3（大 MTU），单请求 MaxRead/MaxWrite 可达 8MB（SMB2 仅 1MB） |
-| 多流并行 | 大文件切成条带，每条带独立打开 SMB 句柄并行读取，靠 credits 在单连接上流水线并发 |
-| 大分块 | 减少 RTT 往返次数，请求粒度默认 1MB、可调 8MB（自动按服务器协商值截断） |
-| 连接复用 | Connection/Session/Share 全程池化，浏览无重复握手开销 |
-| 关闭签名/加密 | 默认不做 SMB 签名与加密以换取吞吐（服务器强制时自动回退协商） |
-| 本地零拷贝拼装 | FileChannel 定位写 + 预分配，各流直接写入自己的偏移 |
+| 多流条带并行 | 大文件切成条带，每条带独立打开 SMB 句柄并行读写，靠 credits 在单 TCP 连接上流水线并发 |
+| 轮转交错写入 | 各条带按块轮转推进，任意时刻写入聚在一个 ~8MB 连续窗口内整体前移——机械盘不再来回寻道，速度稳 |
+| 大分块 | 减少 RTT 往返，请求粒度默认 1MB、可调 8MB（自动按服务器协商值截断） |
+| 连接复用 | Connection / Session / Share 全程池化，浏览与续传无重复握手开销 |
+| 关闭签名/加密 | 默认不做 SMB 签名与加密以换取吞吐（服务器强制时自动回退） |
+| 本地零拷贝拼装 | FileChannel 定位写 + positioned read（pread），多协程并发安全 |
+| 内存护栏 | 全部条带缓冲合计硬性上限 48MB，配置拉满也不会堆溢出闪退 |

-> 实测建议：手机连 5GHz Wi-Fi，NAS 开 SMB3（Windows 8+/Server 2012+ 默认开启）。千兆内网理论 110MB/s 左右，多流可基本跑满；百兆/2.5G 环境收益更明显（单流顺序读通常只能到 30~60MB/s）。
+> 实测建议：手机连 **5GHz Wi-Fi**、靠近路由器；NAS 开 SMB3（Windows 8+/Server 2012+ 默认开启）。千兆内网理论 ~110MB/s；手机无线一般可跑到 50~80MB/s。机械盘 NAS 追求稳定可把并行流数调到 2~4，固态盘 4~6。

-## 构建
+## 📡 后台传输与灵动岛

-要求：JDK 17+，Android SDK（platform 35、build-tools 34+）。
+- 传输任务自动拉起前台服务（`foregroundServiceType="dataSync"`），通知栏常驻进度（任务名、总进度条、速度），支持「全部停止」；任务结束服务自动退出
+- 持有 `PARTIAL_WAKE_LOCK` + `WIFI_MODE_FULL_LOW_LATENCY`，熄屏不断流
+- 小米 HyperOS：客户端本地上岛协议 `miui.focus.param`（`param` 双轨根节点兼容 HyperOS 2 / `param_v2` 兼容 HyperOS 3），首次上岛自动展开大岛，之后静默更新小岛；若系统未授予「焦点通知」权限则退回普通通知
+- Android 14+ 对 dataSync 前台服务有单日累计 6 小时政策上限，常规传输足够
+
+## 🛠 构建
+
+要求：JDK 17+，Android SDK（platform 35、build-tools 34+）。Gradle 仓库默认走阿里云镜像（`settings.gradle.kts`），国内环境无需代理。

 ```bash
-./gradlew :app:assembleDebug    # 产物: app/build/outputs/apk/debug/app-debug.apk
-./gradlew :app:assembleRelease  # 需要签名配置
+./gradlew :app:assembleDebug     # 产物: app/build/outputs/apk/debug/app-debug.apk
+./gradlew :app:assembleRelease   # 签名 release（密钥库 smbfast.keystore 已含在仓库）
+./gradlew :app:testReleaseUnitTest   # 单元测试
 ```

-`local.properties` 中配置 `sdk.dir`。Gradle 仓库默认走阿里云镜像（`settings.gradle.kts`），国内环境无需代理。
+`local.properties` 配置 `sdk.dir`。签名配置见 `app/build.gradle.kts`（store: `smbfast.keystore`）。

-## 使用
+> ⚠️ 仓库内含签名密钥与密码，便于克隆后构建同签名 APK（升级不冲突）。**若要公开仓库，请先把密钥移出 git 历史并更换密码。**

-1. 首页点 **+** 添加连接：填服务器 IP（如 `192.168.1.10`）、共享名称（如 `share`）、用户名密码（或勾选匿名）
-2. 点「测试」确认可用，然后「连接」
-3. 浏览目录，点文件右侧菜单选择 **下载** / **下载并打开**
-4. 「传输」页查看实时速度；设置页可调并行流数与分块大小
+## 📖 使用

-下载保存位置：优先 `Download/SMBFast/`，受限存储设备回退到应用私有目录（设置页可见实际路径）。
+1. 首页点 **+** 添加连接：填服务器 IP（如 `192.168.31.10`）、用户名密码（或勾选匿名）
+2. 点「自动发现共享」枚举全部共享 → **可连点多个胶囊批量勾选** → 「测试并连接（N 个）」一次建多条连接
+3. 浏览目录，点文件操作菜单选择 **下载 / 下载并打开**；工具栏可上传本机文件
+4. 「传输」页看实时速度与峰值；失败任务点 ↻ 重试
+5. 设置页可调并行流数、分块大小、查看下载目录与错误日志

-## 已知限制
+下载保存位置：优先 `Download/SMBFast/`，受限存储回退应用私有目录。
+
+### 局域网分发
+
+电脑（如 `192.168.31.3`）在 `dist/` 目录起 `python -m http.server 8080`，手机浏览器访问 `http://192.168.31.3:8080/SmbFast-release-v20.apk` 直接安装，避免聊天工具传输截断（「解析软件包出现问题 33」多为此因）。
+
+## 🧪 测试
+
+- `ShareParseTest`：用真实 fnOS 服务器抓取的 NetShareEnumAll 响应（884 字节样本）做回归，锁定 DCERPC 解析正确性
+- `PathsTest`：SMB 路径工具（拼接/父路径/文件名）回归
+
+## 📁 项目结构
+
+```
+app/src/main/java/com/smbfast/app/
+├── smb/          # SMBJ 封装：连接池、错误翻译、自研 DCERPC 共享枚举、多流传输引擎
+├── transfer/     # 传输管理器（任务队列/进度/重试）+ 前台服务（保活/通知/灵动岛）
+├── ui/           # Compose 界面：极光组件库、全屏连接编辑器、浏览/传输/设置页
+├── data/         # 连接配置与设置（AndroidKeyStore 加密持久化）
+└── util/         # 崩溃日志、文件工具
+```
+
+## 📜 版本历程
+
+| 版本 | 主要变化 |
+| --- | --- |
+| 1.0 ~ 1.8 | 基础功能、Compose 界面、多流下载、崩溃日志体系、DCERPC 共享枚举字节级攻坚（fnOS 实测） |
+| 1.9.0 (v11) | 连接编辑改为全屏分区页面，视觉全面华丽化 |
+| 1.10.0 (v12) | 共享多选、批量建连；整体 UI 缩小一号 |
+| 1.11.0 (v13) | 前台服务保活 + WiFi/CPU 锁，修复后台传输被系统断连 |
+| 1.12.0 (v14) | 上传多流条带化；修复条带句柄互相截断的 bug |
+| 1.13 ~ 1.14 (v15/v16) | HyperOS 焦点通知/超级岛适配；修复横幅轰炸（islandFirstFloat 只在首条生效）与双轨协议 |
+| 1.15.0 (v17) | TCP 预探测 + 异常链穿透翻译：填错 IP 5 秒内中文报错 |
+| 1.16.0 (v18) | 编辑模式同样支持多选共享（当前连接用第一个，其余新建） |
+| 1.17.0 (v19) | 内存护栏、下载自动重试、空间预检、上传防覆盖、凭据加密、通知「全部停止」 |
+| 1.18.0 (v20) | 全局单层极光背景，修复切页闪烁 |
+
+## ⚠️ 已知限制

 - SMBJ 不支持 SMB3 Multichannel（多网卡聚合），多流并行在同一 TCP 连接上实现
- 密码明文保存在应用私有 SharedPreferences（未加密）
 - 暂不支持 SMB over QUIC / 直连 TLS，未做流媒体边下边播
+- 下载断点续传未实现（失败重试为从头重传，已在路线图）
+- HyperOS 岛能否点亮最终取决于系统侧「焦点通知」权限，个别固件对侧载应用收紧

-## 技术栈
+## <a id="english"></a>English

-Kotlin · Jetpack Compose (Material 3) · SMBJ 0.15.0 (SMB2/SMB3) · BouncyCastle · Gson · Coroutines
+SmbFast is a speed-first SMB2/SMB3 client for Android (SMBJ + Jetpack Compose). Highlights: multi-stream striping transfers with rotationally-interleaved writes, persistent foreground service with WiFi/CPU wakelocks for background transfers, Xiaomi HyperOS Focus-Notification/"Super Island" integration, batch share discovery & multi-select connection creation (hand-rolled DCERPC srvsvc enumeration), AndroidKeyStore-encrypted credentials, and a glitch-free single global aurora UI. Build with JDK 17 + Android SDK 35: `./gradlew :app:assembleRelease`.
+
+## 🧰 技术栈
+
+Kotlin · Jetpack Compose (Material 3) · SMBJ 0.15.0 (SMB2/SMB3) · BouncyCastle · Gson · Coroutines · AndroidKeyStore
+
+## 📄 许可
+
+个人项目，仅供学习交流。请遵守所在网络环境的服务条款，勿用于未授权的文件访问。