HAPI 架构深度解析：如何在不侵入 AI Agent 的前提下实现远程控制 代码版本：基于 HAPI v0.15.2（commit eb8e749）1. 引言 当你在终端里用 Claude Code 写代码时，一切都很顺畅——直到你需要离开电脑。Agent 请求权限审批，你不在；Agent 等你输入，你在路上。这就是 HAPI 要解决的问题：如何在不替换 AI Agent 的前提下，让你从手机或浏览器远程控制它？ 📌 本文范围：聚焦 HAPI 的核心架构设计，包括三层通信架构、Local/Remote 双模式切换、四种 I/O 拦截机制、权限审批链路和安全模型。不涉及 Telegram Bot 集成和 Web UI 组件细节。1.1 文章导航 | 章节 | 内容 | 关键文件 | |------|------|---------| | §2 | 整体架构与核心概念 | cli/src/commands/registry.ts | | §3 | Local/Remote 双模式切换 | cli/src/agent/loopBase.ts | | §4 | 四种 I/O 拦截机制 | cli/src/claude/utils/ | | §5 | Hub 层：协调引擎 | hub/src/sync/syncEngine.ts | | §6 | 权限审批全链路 | cli/src/claude/utils/permissionHandler.ts | | §7 | 安全模型 | hub/src/socket/server.ts | | §8 | 设计决策与权衡 | — | | §9 | 组件生命周期与自动启动 | cli/src/utils/autoStartServer.ts | | §10 | Rust 重写可行性分析 | — |2. 整体架构与核心概念2.1 设计哲学：Local-First + 零侵入 HAPI 的核心设计原则可以用两句话概括：Local-First：Hub 运行在你自己的机器上，数据存储在本地 SQLite，relay 只转发加密流量零侵入：不 fork、不 patch AI Agent，通过标准接口（Hook、MCP、SDK）旁路监听2.2 三层架构总览graph TB subgraph local["🖥️ 本地机器"] Agent["AI Agent<br/>(Claude Code / Codex / Gemini / OpenCode)"] CLI["HAPI CLI"] Hub["HAPI Hub :3006"] HookSrv["Hook Server<br/>:随机端口"] McpSrv["MCP Server<br/>:随机端口"] end subgraph remote["📱 远程设备"] Web["Web / PWA"] Phone["手机浏览器"] end Agent -- "SDK / 子进程 stdio" --> CLI Agent -- "SessionStart Hook" --> HookSrv Agent -- "MCP 工具调用" --> McpSrv HookSrv --> CLI McpSrv --> CLI CLI -- "Socket.IO (双向)" --> Hub Hub -- "SSE (单向推送)" --> Web Hub -- "SSE (单向推送)" --> Phone Web -- "REST API" --> Hub Phone -- "REST API" --> Hub style Agent fill:#6C5CE7,stroke:#5A4BD1,color:#fff,stroke-width:2px style CLI fill:#0984E3,stroke:#0770C2,color:#fff,stroke-width:2px style Hub fill:#00B894,stroke:#009D7E,color:#fff,stroke-width:2px style HookSrv fill:#FDCB6E,stroke:#E0B050,color:#2D3436,stroke-width:1px style McpSrv fill:#FDCB6E,stroke:#E0B050,color:#2D3436,stroke-width:1px style Web fill:#E17055,stroke:#C0392B,color:#fff,stroke-width:2px style Phone fill:#E17055,stroke:#C0392B,color:#fff,stroke-width:2px style local fill:#…