新用户使用困惑点 | New User Confusion Points

[chzzfly]

感谢作者，项目非常棒，连接非常稳定，不掉线。但在使用中，有一些新手指引上的小问题，因为我对git操作不熟悉，所以将问题陈列如下，希望有帮助：

1. hapi gemini 卡住。
2. 本地终端全关闭了，网页上依然可以对话。
3. 以为runner是让hapi server后台运行的，结果不是。
4. hapi server缺乏作为后台常驻服务的指引。

以下为AI总结：

作为一名在 macOS 上通过 Cloudflare Tunnel 部署 HAPI 的新用户，我在进程管理和命令模式方面遇到了几次严重的困惑。目前的文档（README和安装指南）虽然在架构层面描述很深，但缺乏针对日常使用场景的直观引导和故障排除说明。

1. 困惑点：hapi gemini 与 hapi (Claude) 的行为差异

• 现象： 运行 hapi (Claude) 时，终端是双向同步的（本地输入，网页可见）；但运行 hapi gemini 时，本地终端看起来像是“卡住”或“假死”了。
• 实际情况： hapi gemini 目前似乎运行在“无头主机（Headless Host）”模式下，只接收网页端的指令，不响应本地终端的键盘输入。
• 影响： 新用户会误以为程序运行出错、死机或网络连接失败。
• 建议： 在文档中明确说明 hapi gemini 是为后台/无界面模式设计的，启动后不会响应本地终端输入。

2. 困惑点：“幽灵会话”与 runner 的角色冲突

• 现象： 我关闭了本地终端窗口，但网页端显示会话在线，且依然可以回复消息。
• 实际情况： runner 启动的是分离的后台进程。当 runner 重启或丢失上下文时，hapi runner list 会显示“没有活跃会话”，但 hapi runner status（以及系统的 ps 命令）却显示这些进程依然在后台运行。
• 影响： 产生了无法通过网页端关闭的“僵尸”AI 进程，持续占用系统资源，且用户不知道如何清理。
• 建议：
  • 在文档中解释 runner 会创建脱离终端存在的后台进程。
  • 重点推荐清理命令：在故障排除章节中加入 hapi doctor clean 的说明。这个命令对于清理失去管理的孤儿进程至关重要，但目前在文档中很难找到。

3. 困惑点：后台服务化的配置引导

• 现象： 我希望 HAPI 像服务器软件一样在后台常驻运行，而不是必须挂着一个终端窗口。
• 实际情况： 用户需要自己研究 nohup、pm2 或系统服务（如 launchd/systemd）的配置方法。
• 建议： 增加一个“以后台服务模式部署”的章节，提供简单的 nohup、pm2 或 launchd 的配置示例。

5. 现象： 在安装初期，很难分清 server、runner 和 session 之间的协作关系。

• 建议： 在 README 中增加一个简单的类比，让用户快速理解，而不需要翻看原理。

---

Summary:
As a new user setting up HAPI on macOS (with Cloudflare Tunnel), I encountered several confusing behaviors
regarding process management and command modes. The current documentation (README/Install guide) focuses
heavily on architecture but lacks clear guidance on daily usage and troubleshooting.

1. Confusion: hapi gemini vs. hapi (Claude) Behavior

• The Issue: When I run hapi (Claude), I get a bidirectional terminal session (syncs with Web). When I run
  hapi gemini, the terminal appears to hang/freeze.
• Reality: hapi gemini seems to run in a "Headless Host" mode that only listens to Web UI commands and
  ignores local terminal input.
• Impact: New users mistakenly think the application has crashed or stuck.
• Suggestion: Explicitly document that hapi gemini is intended for background/headless usage and will not
  accept terminal input.

2. Confusion: "Ghost" Sessions & The Role of runner

• The Issue: I closed my terminal, but the Web UI still showed active sessions, and they could even reply to
  messages!
• Reality: The runner spawns detached/orphaned processes. hapi runner list showed "No active sessions"
  (because the runner restarted or lost context), yet hapi runner status (and ps aux) showed the processes
  were still alive.
• Impact: I had "zombie" AI sessions consuming resources that I couldn't control via the Web UI.
• Suggestion:
  • Explain clearly that runner creates detached processes that survive terminal closure.
  • Prominently document the cleanup command: hapi doctor clean. This is currently hidden in the
    code/doctor command and is essential for fixing this state.

3. Confusion: Background Service Setup

• The Issue: I wanted to run HAPI as a background service (headless server style) without keeping a terminal
  window open. The docs don't offer a clear "Service Mode" guide.
• Reality: Users need to manually set up nohup, pm2, or system services (systemd/launchd).
• Suggestion: Add a "Deploying as a Background Service" section to the docs, providing simple snippets for
  nohup or pm2.

4. Architecture Clarity

• The Issue: The relationship between server, runner, and session is unclear during installation.
• Suggestion: A simple analogy in the README would help:
  • Server: The Dashboard/Website.
  • Runner: The Background Manager (keeps things alive).
  • Session: The actual Agent instance.

[tiann]

谢谢你的建议，这些问题客观存在。之前项目刚刚创建，主要解决的是核心功能的稳定性。
我会尽快改进和完善相关文档。

[tiann]

gemini 已经支持 local / remote 模式，与 claude code 等一致；
server 改名为 hub，避免混淆；
其余文档都已经更新。