uzairansaruzi/hermex

Hermex 是一个原生 SwiftUI iPhone 应用，用于驱动自托管的 [hermes-webui](https://github.com/nesquena/hermes-webui) 服务器——它是为运行在**你**控制的机器上的 AI agent 打造的移动控制台。手机只是控制平面，而不是计算平面：agent、它的工具以及你的数据都保留在你自己的硬件上。 - **免费。** 没有订阅，没有应用内购买。 - **私密。** 没有分析，没有追踪，没有第三方中继——应用只与你的服务器通信。 - **原生。** 真正的 SwiftUI，为 iOS 18+ 打造，而不是一个网页套壳。 ## 功能 - **与你的 agent 聊天** —— 发送带有模型、推理力度、工作区和配置文件选项的消息；附加文件和图像；实时观看响应流，并显示思考和工具调用细节。 - **在运行中途转向或停止**。 - **会话** —— 浏览、搜索并恢复你服务器上的每一次对话；缓存的会话在离线状态下也可读。 - **选择你的模型** —— 在服务器配置的任何模型或提供商之间切换，支持最近使用和收藏。 - **配置文件与项目** —— 切换 agent 配置文件，并将会话组织到项目中。 - **任务** —— 从你的手机查看和编辑 agent 预定的 cron 作业。 - **技能** —— 浏览和搜索 agent 已安装的技能。 - **工作区浏览器** —— 从应用中探索你服务器的文件系统。 - **记忆与洞察** —— 用于 agent 记忆和使用情况分析的只读面板。 ## 快速开始 Hermex 只是一个客户端——它不提供、托管或配备后端。你需要自己搭建运行在你控制的机器上的 [hermes-webui](https://github.com/nesquena/hermes-webui) 服务器（一个第三方的、基于 MIT 许可证的开源项目）。设置大约需要 15 分钟： 1. **运行服务器。** 在 macOS、Linux 或 Windows/WSL2（Python 3.11+）上安装并启动 `hermes-webui`。设置 `HERMES_WEBUI_PASSWORD`。 2. **使其可从你的手机访问**（见下文的选项）。 3. **连接。** [下载 Hermex](https://apps.apple.com/app/hermex/id6767006319)，输入你的服务器 URL（例如 `https://hermes.yourdomain.com`）和密码，你就可以开始了。 自行托管服务器、保护其安全并保持其可访问性是你自己的责任。 ### 使服务器可访问 - **通过隧道或反向代理进行 HTTPS 访问（推荐）。** 通过 Cloudflare Tunnel 或任何在你拥有的主机名上终止真实 TLS 的反向代理来公开服务器。真正的 HTTPS 能让 iOS App Transport Security 毫无例外地满意。在公开可访问的主机名上，密码是你唯一的应用级防御手段——请设置一个强密码。 - **Tailscale。** 使用密码运行绑定到所有接口的服务器，在服务器和 iPhone 上安装 Tailscale，并连接到 `http://:8787`。应用仅允许对 Tailscale 的 `100.64.0.0/10` 设备范围使用普通 HTTP。 - **仅用于模拟器的本地测试** 可以在服务器运行在同一台 Mac 上时使用 `http://localhost:8787`。 ### 连接故障排除 如果连接测试失败，请先检查以下几点： 1. 托管 `hermes-webui` 的机器处于唤醒状态。 2. `hermes-webui` 正在运行并正常提供 `/health` 服务（`curl https:///health`）。 3. 隧道、反向代理或 Tailscale 路由已连接。 4. 服务器 URL 和密码正确无误。 ## 从源码构建 除非你正在进行开发，否则建议使用 [App Store 构建](https://apps.apple.com/app/hermex/id6767006319)。要自行构建，你需要 Xcode 26 或更高版本（iOS 18 SDK）以及运行 iOS 18+ 的 iPhone 或模拟器。 Clone 该代码仓库，打开 `HermesMobile.xcodeproj`，并在 iPhone 模拟器上运行 `HermesMobile` scheme（Xcode target 为 `HermesMobile`；应用的显示名称为 `Hermex`）。依赖项通过 Swift Package Manager 自动解析。 从命令行运行： ``` xcodebuild -project HermesMobile.xcodeproj -scheme HermesMobile -destination 'platform=iOS Simulator,name=iPhone 17' build ``` ``` xcodebuild test -project HermesMobile.xcodeproj -scheme HermesMobile -destination 'platform=iOS Simulator,name=iPhone 17' ``` 如果未安装该模拟器，请列出可用设备并选择相近的 iPhone 模拟器： ``` xcrun simctl list devices available ``` XcodeBuildMCP 用户的本地验证默认配置位于 `.xcodebuildmcp/config.yaml` 中；标准的变更后流程在 [`DEVELOPMENT.md`](DEVELOPMENT.md) 中。 ## 服务器兼容性 该应用是针对 [`UPSTREAM_TESTED_SHA`](UPSTREAM_TESTED_SHA) 中锁定的 `hermes-webui` commit 进行开发和测试的。上游目前尚未保证 API 的稳定性（其 README 声明在他们完成稳定 API 工作之前不支持版本偏差），因此较新或较旧的服务器版本可能会破坏个别功能——请在 bug 报告中附上你的服务器版本。该应用具有容错的解码能力（未知字段永远不会导致崩溃），并且 endpoint 结构是针对上游源码验证的，绝非凭空捏造；有关合约测试的方法，请参见 [`CONTRACT_TESTS.md`](CONTRACT_TESTS.md)。 ## 文档导览 - [`PROJECT_SPEC.md`](PROJECT_SPEC.md)：产品范围、API 行为、依赖项和架构决策的事实来源。 - [`PROJECT_INTENT.md`](PROJECT_INTENT.md)：简短的概述；适用于了解产品权衡，而非实现细节。 - [`DEVELOPMENT.md`](DEVELOPMENT.md)：本地开发工作流、服务器设置说明和维护者发布手册。 - [`TESTFLIGHT.md`](TESTFLIGHT.md)：仅限维护者使用的 TestFlight/App Store Connect 操作。 - [`CONTRACT_TESTS.md`](CONTRACT_TESTS.md)：上游合约测试就绪情况及版本锁定推进策略。 - [`SECURITY.md`](SECURITY.md)：如何报告漏洞。 - [`docs/agents/`](docs/agents)：代码仓库本地的 agent 工作流约定（issue、分类标签、领域说明）。 - [GitHub Issues](https://github.com/uzairansaruzi/hermex/issues)：活跃 bug、优化说明和功能请求的事实来源。 ## 许可证 MIT —— 见 [LICENSE](LICENSE)。 Hermex 是一个独立的客户端，不隶属于上游的 [hermes-webui](https://github.com/nesquena/hermes-webui) 项目。Apple、Apple logo 以及 App Store 是 Apple Inc. 的商标。

标签：iOS, SwiftUI, 客户端, 移动开发, 自托管