Technical Paper v1.0· 2026-08-01作者HuiAgent Team / jsCanvas代码仓库https://github.com/jsCanvas/hui-agent项目官网https://jscanvas.github.io/hui-agent/GitHub Pages摘要AbstractHuiAgent 是一套面向知识工作者的本地桌面 AI 伴侣系统。它将透明浮层 UICompanion、Python Daemon、Model Context ProtocolMCP工具链与 Cursor IDE Agent 通过 Socket 长连接耦合实现「观察屏幕 → 理解文档 → 操作键鼠 → 中文语音反馈」的闭环。本文介绍其分层架构、双工语音Duplex边缘响应、Cursor Socket Relay 任务模型以及以读屏滚页替代后台 OCR 的主动阅读工作流。系统已在 macOS 上验证飞书文档语音阅读、Companion PTT 通话等场景。关键词桌面自动化、MCP、Cursor Agent、语音双工、屏幕理解、本地 Daemon1. 引言大模型 Agent 在 IDE 内已能高效辅助编程但用户大量工作发生在浏览器、文档与协作工具中。云端 Agent 无法直接访问本机屏幕与输入设备传统 RPA 缺乏语义理解与对话式交互。HuiAgent 的定位是hui-agent 平台的本地代理在用户桌面提供标准 MCP 接口、最小侵入的 Companion 浮层并与 Cursor 等 MCP Host 对接使「AI 大脑在 IDE、眼睛和手脚在 OS」成为可部署架构。贡献概览Companion Daemon MCP三层分离Companion 仅作入口与 TTS/STT 展示复杂推理交给 Cursor。Socket Relay:18765使 Companion 任务以 NDJSON 长连接阻塞等待 Cursor 完成避免频繁切前台。Duplex 双工本地边缘层即时 ack 与简单工具执行Cursor 异步接管完整规划。主动读屏工作流get_screenshot 视觉理解 小步mouse_scroll替代默认后台 OCR Worker。2. 相关工作方向代表方案与 HuiAgent 差异IDE AgentCursor, Copilot侧重代码库弱桌面 UIMCPAnthropic MCP 规范HuiAgent 提供桌面 Host 侧实现RPAUiPath, AutoHotkey规则驱动无统一 LLM 工具协议语音助手Siri, 智能音箱无文档读屏与 IDE 协同HuiAgent 填补MCP 桌面工具 Host 轻量 Companion UI Cursor 大脑的空白。3. 系统架构┌──────────────────┐ WebSocket/NDJSON ┌─────────────────────┐ │ Companion (Tauri)│ ◄──────────────────► │ Daemon (Python) │ │ React · VRM/TTS │ │ Capture · TTS · STT │ └────────┬─────────┘ │ Socket Bridge :18765 │ │ └──────────┬──────────┘ │ invoke │ ▼ │ rolecursor ┌──────────────────┐ MCP stdio ┌─────────▼──────────┐ │ 设置 · 托盘 │ │ cursor-socket-client│ └──────────────────┘ └─────────┬──────────┘ │ ┌────────────▼────────────┐ │ Cursor Agent MCP │ │ 22 tools: screenshot, │ │ mouse_*, keyboard_*, │ │ companion_speak, … │ └─────────────────────────┘3.1 Companion 浮层右下角透明窗口数字人肖像、PTT/文字输入、状态 overlay监听中 / 执行中。不展示长聊天日志进度通过状态与 TTS 反馈。Tauri 2 壳管理子进程、系统托盘、Socket 事件转发。3.2 Daemon 与 Socket BridgeHealthhttp://127.0.0.1:18766/health帧缓冲10fps 环形缓冲供get_recent_framesRelaycursor_relay.py维护 pending 任务等待companion_task_completeVoice/voice/*HTTP Socket 事件voice.stt.final3.3 MCP 工具集核心工具包括get_screenshot、get_screen_info、mouse_move、mouse_click、mouse_scroll、keyboard_*、activate_document_app、companion_speak、companion_task_pending、companion_task_complete、companion_socket_connect_and_wait等。自动化操作可配置automation.require_consent开发模式可关闭 Companion 确认弹窗。4. Cursor Socket Relay 任务模型4.1 连接与监听Agent 调用companion_socket_connect_and_wait或脚本connect-cursor-socket.sh。后台进程cursor-socket-client.py以rolecursor连接 Bridge默认监听 12 小时。wait_for_task轮询 Daemon pendingCompanion 显示「监听中」。4.2 任务闭环wait → task_received → companion_task_pending → [读屏 / 键鼠 / speak] → companion_task_complete (auto_waittrue) → 自动 companion_socket_wait → 下一任务auto_wait在任务提交后于同一 MCP 调用内进入下一轮监听减少 Agent 漏调 wait 的问题。4.3 UI 策略禁止activate_cursor_app/cmdtab切前台Relay 模式。文档聚焦mouse_movemouse_click点击文档区约宽 32%、高 42%。滚屏|dy| ≤ 24禁止 Page Down 连按。5. 双工语音Duplex用户 PTT 输入经 STT 变为文本后层级延迟行为边缘builtin/GGUF百 ms 级即时 ack TTS、可选get_screenshot等简单动作Cursor秒分钟级完整规划、多屏阅读、companion_speak分段播报voice_pending.duplex携带ack_text、executed_actions、defer_to_cursor: trueCursor follow-up 勿重复 ack。6. 文档阅读工作流Case Study场景飞书 Wiki 英文小说用户说「用中文阅读这篇小说」。边缘 ack 并首帧截屏。Cursormouse_scroll小步下滚多次get_screenshot理解简介与正文边界。companion_speak分段中文口播摘要。companion_task_complete提交 Markdown 摘要并auto_wait继续监听。该流程不依赖companion_doc_read_start后台 OCR降低与前台文档状态不一致的风险。7. 实现与部署客户端路径repo/client/Tauri React Python MCP依赖Rust、Node 20、Python 3.12macOS 需屏幕录制与辅助功能配置~/.hui-agent/config.jsonTTS/STT/agent/automation/doc_read启动npm run dev详细安装与权限说明见 官网使用指导 与 Companion 使用说明。8. 讨论与限制项说明平台首期 macOSWindows Tauri 可构建输入层待充分测试MCP 阻塞auto_wait长监听可能导致 MCP HTTP 超时可设timeout_sec或auto_wait: false隐私截屏与键鼠均在本机Relay 不上传屏幕到 hui-agent 云端模型默认 Cursor 云端模型可选本地 GGUF 仅用于边缘 outline/ack9. 结论HuiAgent 展示了如何将MCP 桌面工具、Companion 轻 UI与Cursor Agent组合为可复现的桌面 AI 工作流。Socket Relay 与 Duplex 设计在保持 IDE 为「大脑」的同时提供了语音入口与长时监听能力。我们开源完整客户端并在官网提供演示动画与分步指导供社区扩展与集成。参考文献与链接Anthropic.Model Context Protocol. https://modelcontextprotocol.ioCursor.Cursor IDE Documentation. https://cursor.com/docsHuiAgent 源码https://github.com/jsCanvas/hui-agentHuiAgent 官网https://jscanvas.github.io/hui-agent/项目内文档docs/prd/desktop-mcp-client.md、docs/solution/desktop-mcp-client.md附录 A快速命令gitclone https://github.com/jsCanvas/hui-agent.gitcdhui-agent/repo/clientnpmrun dev ./scripts/connect-cursor-socket.shcurl-sfhttp://127.0.0.1:18766/health|python3-mjson.tool附录 B版本信息组件版本MCP Server0.1.8论文v1.0日期2026-08-01
