HAPI与Cursor Agent集成教程：AI代码助手远程控制实战

【免费下载链接】hapi App for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere 项目地址: https://gitcode.com/gh_mirrors/hapi6/hapi

HAPI是一款支持Claude Code、Codex、Gemini和OpenCode等AI模型的应用，能够实现随时随地的氛围编码（vibe coding）体验。本教程将详细介绍如何将HAPI与Cursor Agent集成，实现AI代码助手的远程控制，让你通过Web和手机就能轻松管理代码开发过程。

准备工作：安装Cursor Agent CLI

在开始集成HAPI与Cursor Agent之前，需要先安装Cursor Agent CLI。这是实现两者通信的基础工具，不同操作系统的安装方法如下：

• macOS/Linux系统：打开终端，输入以下命令

  curl https://cursor.com/install -fsS | bash
  

• Windows系统：在PowerShell中执行以下命令

  irm 'https://cursor.com/install?win32=true' | iex
  

安装完成后，通过以下命令验证安装是否成功：

agent --version

图：HAPI终端界面，可用于执行Cursor Agent相关命令

快速上手：HAPI集成Cursor Agent的基本命令

完成Cursor Agent CLI安装后，就可以通过HAPI命令行工具来管理Cursor Agent会话了。以下是常用的基本命令：

hapi cursor                    # 启动新的Cursor Agent会话
hapi cursor resume <chatId>    # 恢复特定的聊天会话
hapi cursor --continue         # 恢复最近的聊天会话
hapi cursor --mode plan        # 以计划模式启动
hapi cursor --mode ask         # 以询问模式启动
hapi cursor --auto-review      # 启动自动审查模式（智能自动）
hapi cursor --yolo             # 绕过批准提示（强制模式）
hapi cursor --model <model>    # 指定AI模型
hapi cursor --cursor-worktree feature-x   # 使用Cursor原生工作树
hapi cursor --cursor-add-dir ../shared    # 添加额外的工作区根目录（可重复）

这些命令涵盖了从启动新会话到恢复旧会话，从选择工作模式到指定AI模型的各种操作，满足不同场景下的开发需求。

权限模式详解：控制AI代码助手的行为

HAPI提供了多种权限模式，用于控制Cursor Agent的行为，你可以根据项目需求和安全考虑选择合适的模式：

模式	描述
default	标准代理行为
plan	计划模式 - 在编码前设计方案
ask	询问模式 - 探索代码而不进行编辑
debug	调试模式 - 假设验证和工具集成
autoReview	自动审查模式 - 使用允许列表/沙箱/分类器代替完全的YOLO模式
yolo	绕过批准提示

你可以通过--mode、--permission-mode或--auto-review参数设置模式，也可以在会话过程中通过Web UI随时更改。

图：HAPI支持多种AI Agent，包括Cursor、Claude、Codex等

高级功能：工作树和多根目录管理

HAPI与Cursor Agent集成提供了强大的工作树和多根目录管理功能，让你能够灵活组织代码项目：

• Cursor原生工作树：新建会话时，Cursor的工作树使用Cursor的--worktree（位于~/.cursor/worktrees/<repo>/<name>），而不是HAPI的兄弟目录工作树。

• 会话中管理：在会话过程中，可以通过发送以下命令来管理工作树和目录：

  • /worktree：管理工作树
  • /apply-worktree：应用工作树
  • /delete-worktree：删除工作树
  • /add-dir <path>：添加目录（独立传递）

• 命令行管理：通过CLI命令直接指定工作树和额外目录：

  hapi cursor --cursor-worktree feature-x --cursor-add-dir ../shared
  

远程控制：通过Web和手机管理Cursor会话

HAPI的一大优势是支持通过Web和手机远程控制Cursor会话。以下是远程控制的主要功能和使用方法：

远程命令传递

HAPI支持将特定命令传递给Cursor Agent，这些命令在队列中隔离并转发给代理：

/compress /summarize /compact /model /multitask /best-of-n /worktree /apply-worktree /delete-worktree /add-dir /context /fork /auto-review

注意：交互式TUI命令（如/config、/mcp、/sandbox等）不支持远程使用。

会话模式

HAPI与Cursor Agent集成提供两种会话模式：

• 本地模式：从终端运行hapi cursor，提供完整的交互式体验。

• 远程模式：当没有终端时，从Web/手机启动。新的Cursor会话使用agent acp，提供HAPI权限批准、计划/问题UI和更丰富的工具更新。在ACP迁移之前创建的旧会话可能仍会通过旧的agent -p stream-json路径临时恢复。

图：HAPI聊天界面，可远程发送命令和查看Cursor Agent响应

集成后的使用体验

一旦完成HAPI与Cursor Agent的集成，你将获得以下便利：

• 多平台监控：在HAPI Web应用和Telegram Mini App中查看Cursor会话活动
• 远程权限管理：通过手机批准代码编辑权限
• 跨设备消息同步：在本地模式下发送的消息会排队，当切换设备时仍能查看

代码查看与编辑

集成后，你可以直接在HAPI界面中查看和编辑代码文件，Cursor Agent会根据你的指令提供实时的代码建议和修改。

图：HAPI代码查看界面，可直接查看和编辑代码文件

常见问题与限制

在使用HAPI与Cursor Agent集成时，需要注意以下限制：

• 多任务UI：/multitask是基于斜杠命令的；HAPI尚未提供类似Agents Window的舰队面板。当代理发出子代理cursor/task通知时，会显示为CursorTask卡片。

• 旧会话支持：在ACP迁移之前创建的Cursor会话仍可通过stream-json临时恢复。启动新的Cursor会话以获得ACP权限、计划、待办事项和问题支持。

• 会话恢复：ACP会话通过session/load恢复。旧的stream-json session_id值无法通过ACP加载；这些会话会继续使用旧路径，直到你开始新会话。

旧版stream-json安全：AskQuestion行为

新的Cursor远程会话通过ACP进行，它通过双向cursor/ask_question扩展方法处理AskQuestion，不受以下问题影响。此处描述的拦截仅适用于通过旧的agent -p stream-json启动器恢复的旧会话。

当在--print --output-format stream-json下运行cursor-agent时，cursor-agent CLI会为AskQuestion工具返回合成的"用户跳过的问题，继续使用已有的信息"响应，因为没有IDE界面来呈现问题。代理的底层模型可能会将此解释为合法的用户同意并采取行动。

HAPI的旧事件转换器会拦截此合成响应并将其重写为明确的no_input_surface错误（status: failed），因此下游消费者（Web UI、Telegram、日志读取器）会将这种伪造显示为错误，而不是默默地传递伪造的同意。拦截会扫描原始tool_call有效负载中的文字标记文本，并限定于AskQuestion形状（和转换器回退name=unknown）的调用；合法的读/写/函数工具不受影响。

总结

通过本教程，你已经了解了如何将HAPI与Cursor Agent集成，实现AI代码助手的远程控制。从安装准备到基本命令，从权限模式到高级功能，你现在可以充分利用HAPI的远程控制能力，随时随地管理你的代码开发过程。

无论是在办公室的电脑前，还是在外出时的手机上，HAPI与Cursor Agent的集成都能让你轻松享受AI辅助编码的便利。开始尝试吧，体验远程控制AI代码助手的全新方式！

【免费下载链接】hapi App for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere 项目地址: https://gitcode.com/gh_mirrors/hapi6/hapi