项目简介
去中心化聊天应用，支持蓝牙 Mesh 离线通信和 Nostr 全球互联，无需账户与中央服务器，端到端加密保护隐私，提供基于地理位置的频道和 IRC 风格命令。
README 预览
\n\n## bitchat\n\nA decentralized peer-to-peer messaging app with dual transport architecture: local Bluetooth mesh networks for offline communication and internet-based Nostr protocol for global reach. No accounts, no phone numbers, no central servers. It's the side-groupchat.\n\n[bitchat.free](http://bitchat.free)\n\n📲 [App Store](https://apps.apple.com/us/app/bitchat-mesh/id6748219622)\n\n## License\n\nThis project is released into the public domain. See the [LICENSE](LICENSE) file for details.\n\n## Features\n\n- **Dual Transport Architecture**: Bluetooth mesh for offline + Nostr protocol for internet-based messaging\n- **Location-Based Channels**: Geographic chat rooms using geohash coordinates over global Nostr relays\n- **Intelligent Message Routing**: Automatically chooses best transport (Bluetooth → Nostr fallback)\n- **Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE\n- **Privacy First**: No accounts, no phone numbers, no persistent identifiers\n- **Private Message End-to-End Encryption**: [Noise Protocol](https://noiseprotocol.org) for mesh, NIP-17 for Nostr\n- **IRC-Style Commands**: Familiar `/slap`, `/msg`, `/who` style interface\n- **Universal App**: Native support for iOS and macOS\n- **Emergency Wipe**: Triple-tap to instantly clear all data\n- **Performance Optimizations**: LZ4 message compression, adaptive battery modes, and optimized networking\n\n## [Technical Architecture](https://deepwiki.com/permissionlesstech/bitchat)\n\nBitChat uses a **hybrid messaging architecture** with two complementary transport layers:\n\n### Bluetooth Mesh Network (Offline)\n\n- **Local Communication**: Direct peer-to-peer within Bluetooth range\n- **Multi-hop Relay**: Messages route through nearby devices (max 7 hops)\n- **No Internet Required**: Works completely offline in disaster scenarios\n- **Noise Protocol Encryption**: End-to-end encryption with forward secrecy\n- **Binary Protocol**: Compact packet format
常见问题 (4)
故障排除如何修复 bitchat macOS 在 Xcode 27 上构建失败,出现 'ambiguous use of words' 或 swift-secp256k1 插件验证错误的问题?
将锁定的 21-DOT-DEV/swift-secp256k1 依赖升级到 **0.24.0 或更高版本** —— 维护者专门发布了 0.24.0 来修复 Xcode 27 / Swift 6.4 的插件验证失败问题,然后更新 Package.resolved 并使用 xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug build 重新构建。
根本原因:锁定的 0.21.1 编译失败,因为其 UInt256.swift 中自定义的 var words 与 Swift 6.4 中的 Swift.BinaryInteger.words 冲突(报错 "ambiguous use of words"),而 0.23.2 则无法通过 xcodebuild 的插件验证,因为 SharedSourcesPlugin 使用了 Xcode 27 自带的 SwiftPM 中不可用的 @available(_PackageDescription 6.0) API。
如果无法升级,可采用变通方案:在本地 vendor swift-secp256k1 0.23.2 —— 将其复制到 localPackages/swift-secp256k1,删除 Plugins/ 目录,在其 Package.swift 中移除 .plugin(name: "SharedSourcesPlugin", capability: .buildTool()) 目标以及 P256K/ZKP 目标中的 plugins: ["SharedSourcesPlugin"](将 Sources/Shared/* 平铺到这两个目标的源码目录中),将 Package.swift 指向 .package(path: "localPackages/swift-secp256k1"),在 project.pbxproj 中用 XCLocalSwiftPackageReference 替换 XCRemoteSwiftPackageReference,并删除 Package.resolved。之后构建即可成功,错误数为 0。
故障排除如何修复 SimulatedMeshTests 偶发失败的问题：deliveredFrameCount 为 16，而不是最多 12？
该 flake 由 announce-admission 逻辑使用 wall-clock Date() 引起，而测试框架仅推进模拟时间。在负载较高的 CI runner 上，0.15 s 的 throttle 窗口可能会流逝，从而产生四个额外的 announce 帧，使 mesh.deliveredFrameCount - baseline 从 12 上升到 16。修复方法是消除模拟 mesh 对 wall-clock 的依赖：为 announce throttle 注入/使用测试的模拟时钟，或者在记录 baseline 之前将 mesh 排空至安静状态，从而将 wall-clock 驱动的 announce 流量排除在测量的 delta 之外。相关修复在 PR #1622/#1649 中跟踪，其中 #1651 在记录 baseline 之前排空 mesh 流量，并将 storm 预算限定在被测 relay 行为的范围内。
故障排除为什么从 Android 发送的大型压缩消息在 iOS 上会悄无声息地无法显示，以及 payload-size 不匹配的问题是如何修复的？
出现这种情况是因为 Android 允许解压后的有效载荷最大可达 AppConstants.Protocol.MAX_PAYLOAD_LENGTH = 10 MiB，而 iOS 会拒绝超过 FileTransferLimits.maxFramedFileBytes ≈ 1.13 MiB 的帧。因此，一条高压缩率的 Android 消息在解压后可能膨胀到 2–5 MiB，并被 iOS 静默丢弃。
修复方法：
1. 将 iOS 客户端更新到包含 PR "Accept compressed payloads up to Android's 10 MiB decompressed ceiling" 的版本，该 PR 使 iOS 的入站解压有效载荷上限与 Android 保持一致。
2. 应用编码侧的强制 PR，使其拒绝发出超过全局展开有效载荷上限的帧，从而防止发送方创建会被解码器拒绝的消息。
3. 作为临时变通方案，从 Android 向旧版 iOS 客户端发送消息时，请将未压缩/原始有效载荷保持在约 1.13 MiB 以下。
50,000:1 的压缩比防护是独立机制，无法防止这种不匹配，因为 iOS 在该防护应用之前，会根据线上声明的 originalSize 进行内存分配。
故障排除如何修复无法创建或更新 pull request 的 GitHub Actions workflow token？
默认的 workflow token 缺少创建 PR 的权限。请打开以下 compare URL，并选择 automation/georelay-data 作为源分支，手动创建 PR：
https://github.com/permissionlesstech/bitchat/compare/main...automation/georelay-data?expand=1
然后提交 PR 以进行常规审查。如果仓库仍然阻止该 token，请将未更改的分支推送到个人 fork，并针对 main 创建跨 fork 的 PR。对于自动化运行，请为 workflow token 授予 pull-requests: write 权限（以及需要时的 contents: write 权限），或者使用具有 PR 创建权限的 PAT/app token。