From f7ac9fe08306bb7a4aba7f4677302378a9d6f861 Mon Sep 17 00:00:00 2001 From: kanice888-max Date: Sun, 19 Jul 2026 13:51:16 +0800 Subject: [PATCH] Refine bilingual README copy --- README.en.md | 80 ++++++++++++++++++++++------------------------------ README.md | 78 ++++++++++++++++++++++---------------------------- 2 files changed, 68 insertions(+), 90 deletions(-) diff --git a/README.en.md b/README.en.md index 92e77f7..053046a 100644 --- a/README.en.md +++ b/README.en.md @@ -2,28 +2,27 @@ # LanBridge -**Safe folder synchronization between Mac and Windows on your local network.** +**Keep Mac and Windows folders in sync on a trusted local network.** -No cloud storage. No third-party relay. You stay in control of every important change. +No cloud storage. No third-party relay. You confirm every important change. [中文（默认）](README.md) · [English](README.en.md) > [!IMPORTANT] -> LanBridge uses a **Primary / Secondary + explicit return-sync** model. It is not fully automatic bidirectional sync. Changes from the Primary sync automatically to the Secondary; changes made on the Secondary affect the Primary only after the user explicitly returns them. +> LanBridge uses a **Primary / Secondary + explicit return-sync** model. Changes from the Primary sync automatically to the Secondary. Changes on the Secondary first appear as pending returns and reach the Primary only after you confirm them. It is not fully automatic bidirectional sync. -LanBridge is an open-source desktop app for synchronizing selected folders between macOS and Windows devices on the same trusted local network. It is for people who use both platforms, value privacy, and want to keep control over their files: nothing needs to be uploaded to a cloud service, and a change on the Secondary can never silently overwrite the Primary. +LanBridge is an open-source desktop app for keeping selected folders aligned between macOS and Windows devices on the same trusted local network. It is for people who want local-file convenience without handing their files to a cloud service. Its clear sync direction helps prevent accidental changes or conflicts from silently overwriting files. -## Why LanBridge +## Highlights -- **Keep data on your local network** — Discover devices on the LAN or connect by manual IP. No cloud drive or third-party relay is required. -- **A clear source of truth** — Every task has a designated Primary. New, updated, and deleted Primary content syncs automatically to the Secondary, removing ambiguity about which device is authoritative. -- **Secondary changes stay under your control** — Creates, edits, and deletes on the Secondary appear as pending return items. They reach the Primary only when you choose to return them. -- **No silent conflict overwrite** — When both sides change the same path, LanBridge asks you to decide. A confirmed overwrite first preserves the old Primary file. -- **Recoverable deletes** — Synchronized deletes and files replaced during conflict resolution go to task history before removal, so they can be restored. -- **Pair devices deliberately** — Pairing requires matching a verification code on both devices. A task root is registered only after the receiving device accepts its invitation. -- **Built for desktop folders** — File trees, sync state, transfer progress, pending returns, conflict handling, history restore, and system-tray access are included in the workflow. +- **Keep files on your local network** — Discover devices on the LAN or connect by manual IP. No cloud drive or third-party relay is required. +- **A clear sync direction** — Every task has a Primary. Creates, edits, and deletes on the Primary sync automatically to the Secondary. +- **You decide about Secondary changes** — Creates, edits, and deletes on the Secondary first appear as pending returns. They affect the Primary only after you confirm them. +- **No silent conflict overwrite** — If both sides change the same path, LanBridge asks you how to proceed and preserves the old Primary file before an overwrite. +- **Recoverable deletes** — Deleted and replaced files are kept in task history so they can be restored when needed. +- **Built for desktop folders** — File trees, sync state, transfer progress, pending returns, conflict handling, history restore, and system-tray access are part of the workflow. ## How it works @@ -33,32 +32,27 @@ Primary folder ── automatic sync ──▶ Secondary folder └──── user-approved return-sync ◀──┘ ``` -1. Pair two devices on the same trusted LAN through discovery or a manual IP address. -2. Create a task, choose its Primary, and let the receiving device choose its own local folder. -3. Primary changes transfer automatically to the Secondary. A Primary deletion moves the corresponding Secondary content to LanBridge history first. -4. Secondary changes appear in a pending-return list. Before returning them, LanBridge checks whether the Primary has changed since the last sync. -5. Conflicts require a user choice; neither restore nor overwrite silently discards an existing file. +1. Put both devices on the same trusted local network and connect through discovery or a manual IP address. +2. Create a task and choose its Primary. The receiving device accepts the task and chooses its own local folder. +3. Primary changes transfer automatically to the Secondary. Secondary changes first appear as pending returns. +4. Return Secondary changes when you choose. If a conflict occurs, you decide how to keep the files. ## Good fits - Keep work folders, creative assets, or project documents aligned between a Mac and a Windows PC. -- Use a local-network workflow without cloud storage, accounts, or continuous internet uploads. -- Keep automatic synchronization convenient while requiring an explicit decision before Secondary changes alter the Primary. +- Use a local-network workflow without cloud storage, accounts, or continuous uploads. +- Keep the convenience of automatic sync without letting Secondary changes immediately alter the Primary. -## What LanBridge is not +## Before you start -- It is not a cloud drive and does not support WAN or NAT-traversal synchronization. -- It is not fully automatic bidirectional sync. Do not treat it as a two-way replacement for Dropbox, iCloud Drive, or Syncthing. -- It does not guarantee safe live synchronization of databases, virtual-machine images, browser profiles, mail stores, dependency caches, or files continuously written by another app. -- It does not synchronize symlinks, and it does not apply synchronized deletes as immediate permanent deletion. - -## Get started - -LanBridge is currently pre-1.0. Before you begin, make sure both devices are on the same trusted local network and that the app is running on macOS and Windows. +- LanBridge does not support WAN or NAT-traversal synchronization. +- It is not a fully automatic two-way replacement for Dropbox, iCloud Drive, or Syncthing. +- It is not recommended for databases, virtual-machine images, browser profiles, mail stores, dependency caches, or files another app writes continuously. +- It does not synchronize symlinks, and synchronized deletes do not immediately and permanently delete your files. ## Download and install -Download the installer for your device and `SHA256SUMS.txt` from [GitHub Releases](https://github.com/kanice888-max/LanBridge/releases/latest): +Download the installer for your device from [GitHub Releases](https://github.com/kanice888-max/LanBridge/releases/latest): | Platform | Download | Notes | | --- | --- | --- | @@ -66,16 +60,15 @@ Download the installer for your device and `SHA256SUMS.txt` from [GitHub Release | macOS Apple Silicon | `LanBridge_0.2.0_aarch64.dmg` | For Apple M-series Macs. | | Windows x64 | `.exe` or `.msi` | Use `.exe` for a personal install or `.msi` for managed deployment. | -Verify the SHA-256 checksum after downloading. The macOS app is ad-hoc signed and not notarized: -the first launch may require Control-click **Open** or **Open Anyway** in System Settings → Privacy & -Security. Never disable Gatekeeper globally. See the [macOS installation guide](docs/release/macos-installation.md) -and [Windows installation guide](docs/release/windows-installation.md) for complete steps. +The macOS app is not notarized by Apple. If macOS blocks the first launch, Control-click LanBridge.app and choose **Open**, or select **Open Anyway** in System Settings → Privacy & Security. You do not need to disable your Mac's security protection. See the [macOS installation guide](docs/release/macos-installation.md) and [Windows installation guide](docs/release/windows-installation.md) for details. + +## Quick start -1. Open LanBridge on both devices. -2. Start pairing through LAN discovery or a manual IP address, then verify the code displayed on both devices. -3. Create a task and select the Primary folder. Accept the invitation on the receiving device and choose its target folder. -4. Create or edit a test file on the Primary and confirm it arrives on the Secondary. -5. Edit that file on the Secondary, review it in Pending Returns, and explicitly return it when ready. +1. Open LanBridge on both devices and make sure they are on the same trusted network. +2. Connect through discovery or a manual IP address, and make sure you are connecting to your own device. +3. Create a sync task, choose the Primary folder, then accept the task and choose the target folder on the other device. +4. Create or edit a test file on the Primary and confirm it appears on the Secondary. +5. Edit a file on the Secondary. Review it in Pending Returns, then return it only when you are ready. ## Run from source @@ -104,9 +97,9 @@ npm run tauri build See [validation checks](docs/validation/checks.md) for full platform validation and release requirements. -## Security and data protection +## Security boundary -LanBridge is designed for **trusted local networks**. Discovery is not trust: pair only after confirming the peer's identity. The app maintains a local device identity, task invitations need receiver approval, and every conflict requires an explicit decision. +Use LanBridge only on trusted home or office networks, and make sure you are connecting to your own device. The app stores device identity locally; the receiving device must accept a task before its folder can be used; conflicts and returns always require an explicit choice. - [Sync and data-safety invariants](docs/rules/invariants.md) - [Security policy](SECURITY.md) @@ -114,7 +107,7 @@ LanBridge is designed for **trusted local networks**. Discovery is not trust: pa Please do not disclose security issues publicly. Follow [SECURITY.md](SECURITY.md) to report them privately. -## Project layout and contributing +## Project layout ```text src/ React frontend @@ -123,11 +116,6 @@ docs/ Product, architecture, security, and workflow documentation scripts/ Project utility scripts ``` -Before contributing changes to synchronization, transfer, pairing, deletion, conflicts, or history, read the [architecture overview](docs/architecture/index.md), [data-safety invariants](docs/rules/invariants.md), and [task workflow](docs/workflows/task-flow.md). Validate the change in the worktree that owns it. - -Read the [contribution guide](CONTRIBUTING.md), [changelog](CHANGELOG.md), and [code of conduct](CODE_OF_CONDUCT.md) -before opening an issue or pull request. - ## License LanBridge is released under the [MIT License](LICENSE). diff --git a/README.md b/README.md index b773f0d..a76fd1d 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,26 @@ # LanBridge -**让 Mac 和 Windows 在局域网内安全地同步文件夹。** +**在受信任局域网内，让 Mac 与 Windows 文件夹保持同步。** -不经云端，不需要第三方存储；同步过程始终由你确认和掌控。 +不经云端，不需要第三方存储；重要变更始终由你确认。 [中文（默认）](README.md) · [English](README.en.md) > [!IMPORTANT] -> LanBridge 采用 **Primary / Secondary（主端 / 从端）+ 显式回传** 模型，不是“完全自动双向同步”。主端变更会自动同步到从端；从端变更必须由用户明确发起回传，才会影响主端。 +> LanBridge 采用 **主端 / 从端 + 显式回传** 模型。主端变更会自动同步到从端；从端变更会先进入待回传列表，只有你确认后才会写回主端。因此它不是完全自动的双向同步工具。 -LanBridge 是一款面向 macOS 和 Windows 的开源桌面应用，用于在同一受信任局域网内同步指定文件夹。它适合同时使用 Mac 与 Windows、重视隐私和文件可控性的人：文件不需要上传到云端，也不会因为从端的一次修改而悄悄覆盖主端内容。 +LanBridge 是一款面向 macOS 和 Windows 的开源桌面应用，适合希望在本地网络中同步文件、又不想把文件交给云端的人。它让同步方向保持清晰，并尽量避免误操作或冲突悄悄覆盖文件。 -## 为什么选择 LanBridge +## 核心特点 -- **文件留在本地网络**：设备直接在局域网内发现和连接，支持手动 IP 连接；不依赖云盘或第三方中转服务。 -- **同步方向清晰**：每个任务都有明确主端。主端的新建、修改和删除会自动同步到从端，避免“哪一台才是最终版本”的不确定性。 -- **从端改动由你决定**：从端的新增、修改和删除会显示为待回传项；只有你确认回传后，才会对主端生效。 -- **冲突不静默覆盖**：如果主端与从端都修改了同一路径，LanBridge 会要求选择处理方式；确认覆盖前会先备份主端旧文件。 -- **删除可恢复**：同步删除和覆盖前的文件会先进入任务历史记录，而不是立即永久删除；可从历史记录恢复。 -- **配对而非盲连**：设备配对需要双方确认验证码；任务邀请也必须由接收端接受后才能注册本地文件夹。 +- **文件留在本地网络**：设备可在局域网内发现，也支持手动输入 IP；不依赖云盘或第三方中转。 +- **同步方向清晰**：每个任务都有明确主端。主端的新建、修改和删除会自动同步到从端。 +- **从端改动由你决定**：从端的新增、修改和删除会先显示为待回传项，确认后才影响主端。 +- **冲突不会静默覆盖**：同一路径在两端都被修改时，LanBridge 会要求你选择处理方式；覆盖前会保留主端旧文件。 +- **删除可以恢复**：同步删除和覆盖前的文件会进入任务历史记录，可按需恢复。 - **为桌面文件夹而生**：提供文件树、同步状态、传输进度、待回传项、冲突处理、历史恢复和系统托盘入口。 ## 工作方式 @@ -33,32 +32,27 @@ LanBridge 是一款面向 macOS 和 Windows 的开源桌面应用，用于在同 └──── 用户确认“回传” ◀───────┘ ``` -1. 在同一受信任局域网内配对两台设备，可使用设备发现或手动 IP。 -2. 创建同步任务时选择哪一端为主端，并由接收端选择自己的本地文件夹。 -3. 主端的变更自动发送到从端；主端删除会先将从端对应内容移入 LanBridge 历史记录。 -4. 从端变更进入“待回传”列表。回传前会检查主端自上次同步后是否也发生变更。 -5. 有冲突时由用户选择保留方式；恢复或覆盖均不会静默丢弃已有文件。 +1. 将两台设备放在同一可信局域网内，通过设备发现或手动输入 IP 连接。 +2. 创建任务时指定主端；接收端接受任务后选择自己的本地文件夹。 +3. 主端变更自动传到从端；从端变更先进入待回传列表。 +4. 需要时确认回传从端变更；发生冲突时由你选择保留方式。 -## 适用场景 +## 适合什么场景 - 在 Mac 与 Windows PC 之间同步工作文件夹、照片素材或项目文档。 -- 希望避免云端存储、账号体系和持续上传的局域网工作流。 -- 希望保留自动同步的便利，同时要求从端修改必须经过明确确认。 +- 希望避开云端存储、账号体系和持续上传的局域网工作流。 +- 希望保留自动同步的便利，同时不让从端修改直接影响主端。 -## 不是它要解决的问题 +## 使用前了解 -- 不是云盘，也不支持广域网 / NAT 穿透同步。 -- 不是完全自动的双向同步；请不要把它当作 Dropbox、iCloud Drive 或 Syncthing 的双向替代品。 -- 不保证数据库、虚拟机镜像、浏览器配置、邮件存储、依赖缓存或被其他应用持续写入的文件可安全实时同步。 -- 不同步符号链接，也不会把删除操作直接永久应用到用户文件。 - -## 开始使用 - -LanBridge 当前为 pre-1.0 项目。使用前请确保两台设备处于同一受信任局域网，并分别在 macOS 与 Windows 上运行应用。 +- LanBridge 不支持广域网或 NAT 穿透同步。 +- 它不是 Dropbox、iCloud Drive 或 Syncthing 那类完全自动的双向同步替代品。 +- 不建议同步数据库、虚拟机镜像、浏览器配置、邮件存储、依赖缓存，或其他应用持续写入的文件。 +- 不同步符号链接；同步删除也不会直接永久删除你的文件。 ## 下载与安装 -从 [GitHub Releases](https://github.com/kanice888-max/LanBridge/releases/latest) 下载与自己设备匹配的安装包和 `SHA256SUMS.txt`： +从 [GitHub Releases](https://github.com/kanice888-max/LanBridge/releases/latest) 下载与你设备匹配的安装包： | 系统 | 下载内容 | 说明 | | --- | --- | --- | @@ -66,15 +60,15 @@ LanBridge 当前为 pre-1.0 项目。使用前请确保两台设备处于同一 | macOS Apple Silicon | `LanBridge_0.2.0_aarch64.dmg` | 适用于 M 系列芯片 Mac。 | | Windows x64 | `.exe` 或 `.msi` | `.exe` 适合个人安装，`.msi` 适合受管理部署。 | -请在下载后核对 SHA-256。macOS 安装包使用 ad-hoc 签名，尚未经过 Apple 公证：首次启动可能需要 -右键点按 **打开**，或在“系统设置 → 隐私与安全性”中选择“仍要打开”；请不要关闭 Gatekeeper。详细步骤见 -[macOS 安装说明](docs/release/macos-installation.md)与[Windows 安装说明](docs/release/windows-installation.md)。 +macOS 安装包尚未经过 Apple 公证。首次打开若被拦截，请在 LanBridge.app 上右键选择“打开”，或在“系统设置 → 隐私与安全性”中点击“仍要打开”；无需关闭 Mac 的安全保护。详细步骤见 [macOS 安装说明](docs/release/macos-installation.md) 与 [Windows 安装说明](docs/release/windows-installation.md)。 + +## 快速开始 -1. 在两台设备上打开 LanBridge。 -2. 通过局域网发现或手动输入 IP 发起配对，并在两端核对验证码。 -3. 创建任务，选择主端文件夹；接收端接受邀请并选择自己的目标文件夹。 +1. 在两台设备上打开 LanBridge，并确认它们位于同一可信网络。 +2. 通过设备发现或手动输入 IP 连接，并确认正在连接自己的设备。 +3. 创建同步任务，选择主端文件夹；接收端接受任务并选择目标文件夹。 4. 在主端创建或修改一个测试文件，确认它出现在从端。 -5. 在从端修改该文件，在“待回传”中检查变更后再明确执行回传。 +5. 在从端修改文件；在“待回传”中查看变更，再按需要确认回传。 ## 从源码运行 @@ -101,11 +95,11 @@ cargo test --manifest-path src-tauri/Cargo.toml npm run tauri build ``` -完整的平台验证与发布要求见[验证检查](docs/validation/checks.md)。 +完整的平台验证与发布要求见 [验证检查](docs/validation/checks.md)。 -## 安全与数据保护 +## 安全边界 -LanBridge 面向**受信任的局域网**。设备发现不代表信任；请只在确认对方身份后完成配对。应用会保存本地设备身份，任务邀请需经接收端确认，且所有冲突都需要显式决定。 +请只在可信的家庭或办公网络中使用 LanBridge，并确认正在连接的是自己的设备。应用会在本机保存设备身份；接收端需要接受任务后才能使用对应文件夹；冲突和回传均需要用户明确确认。 - [同步与数据安全不变量](docs/rules/invariants.md) - [安全策略](SECURITY.md) @@ -113,7 +107,7 @@ LanBridge 面向**受信任的局域网**。设备发现不代表信任；请只 发现安全问题时，请不要公开披露，按 [SECURITY.md](SECURITY.md) 的方式私下报告。 -## 项目结构与贡献 +## 项目结构 ```text src/ React 前端 @@ -122,10 +116,6 @@ docs/ 产品、架构、安全与工作流文档 scripts/ 项目工具脚本 ``` -提交涉及同步、传输、配对、删除、冲突或历史记录的变更前，请先阅读[架构概览](docs/architecture/index.md)、[数据安全不变量](docs/rules/invariants.md)和[任务工作流](docs/workflows/task-flow.md)，并在对应 worktree 中完成验证。 - -欢迎阅读[贡献指南](CONTRIBUTING.md)、[更新日志](CHANGELOG.md)和[行为准则](CODE_OF_CONDUCT.md)，再提交 issue 或 PR。 - ## 开源协议 本项目采用 [MIT License](LICENSE)。