1. 项目概述当飞书成为你的AI遥控器作为一名长期在AI与自动化工具链中摸爬滚打的开发者我一直在寻找一种更自然、更无缝的方式将AI的思考与执行能力融入我的日常工作流。直到我遇到了feishu-cursor-claw这个项目它精准地击中了一个痛点如何随时随地、用最习惯的方式唤醒并指挥我本地的AI助手这个项目本质上是一座桥一座连接飞书或Lark即时通讯工具与你本地Cursor AI IDE的桥。它让你在手机上发一条消息就能让远在办公室的Mac电脑开始写代码、审阅文档、执行复杂的策略分析甚至管理你的知识库。想象一下这样的场景你在通勤的地铁上突然想到一个产品功能的优化点于是你在飞书里给你的AI助手发了一条语音消息。几秒钟后你的电脑开始自动修改代码并将改动摘要和潜在风险分析推送回你的手机。或者你在会议间隙用文字简单描述了一个数据分析需求你的AI助手便开始在后台运行脚本、生成图表并将结果整理成一份简洁的报告。这不再是科幻电影里的情节而是通过feishu-cursor-claw可以实现的日常。它不仅仅是一个“远程控制”更是一个个人AI战略合伙人的接入点将Cursor Agent CLI的强大能力通过你最熟悉的聊天界面释放出来。这个项目的核心价值在于其无感集成和多模态交互。你不需要配置复杂的VPN、SSH隧道甚至不需要打开浏览器。它基于WebSocket长连接确保了低延迟的实时通信。更重要的是它支持文本、图片、语音甚至文件输入让指令的传达方式无比灵活。无论是程序员想远程调试还是知识工作者需要即时分析它都能提供一个统一、便捷的入口。接下来我将深入拆解这个项目的架构、配置细节以及我在实际部署和使用中积累的经验希望能帮你彻底掌握这个提升生产力的利器。2. 核心架构与设计哲学解析2.1 整体通信链路从消息到代码执行feishu-cursor-claw的架构清晰且高效其核心是扮演一个智能消息路由与协议转换器的角色。整个数据流可以概括为飞书应用接收用户多模态输入 - 中继服务进行预处理与路由 - 调用本地Cursor Agent CLI - 执行结果流式返回飞书。具体来说当你向飞书机器人发送一条消息时飞书开放平台会通过你配置的WebSocket长连接将消息事件实时推送到你本地运行的server.ts服务。这个服务是整个系统的大脑它需要完成以下几项关键工作消息解析与预处理识别消息类型文本、图片、语音、文件对于语音消息会调用语音识别STT服务转换为文本对于图片可能会提取其中的文字信息如果未来集成OCR。会话与项目管理解析消息中是否包含project:前缀以路由到不同的工作区目录并管理会话状态确保同一会话的对话具有连续性--resume参数。指令拦截与安全审查判断消息是否为系统指令如/help,/model并执行相应操作。同时在群聊环境中拦截敏感操作如更换API Key确保安全。调用Cursor Agent将处理后的纯文本指令通过子进程调用本地的~/.local/bin/agent命令行工具。这里采用了会话级并发的设计即不同工作区的会话可以并行执行互不干扰而同一会话内的请求则串行处理避免了状态混乱。流式响应与进度反馈Cursor Agent 的执行是“思考-行动”交替的过程。中继服务会实时捕获这个过程的输出并将其转换为飞书“卡片”消息的形式分步骤、流式地推送给用户让你能清晰看到AI的“思考链”和工具调用过程而不是干等一个最终结果。这个架构的优势在于职责分离。飞书负责最擅长的IM交互Cursor Agent负责最核心的AI推理与执行而feishu-cursor-claw则优雅地连接两者并附加了会话、记忆、安全等增强功能。这种设计使得每一层都可以独立演进和优化。2.2 记忆与身份系统打造有“灵魂”的AI伙伴如果说基础的远程控制是“骨骼”那么该项目集成的记忆与身份系统就是赋予AI“灵魂”和“长期记忆”的关键。这部分设计深受OpenClaw项目启发但实现上更巧妙地利用了 Cursor 自身的规则引擎。核心机制基于文件的上下文注入与许多通过API在后台拼接冗长提示词Prompt的AI应用不同feishu-cursor-claw采用了一种更干净、更可控的方式。它在你的工作区目录下维护了一系列.mdc规则文件如soul.mdc,agent-identity.mdc。当 Cursor Agent 启动一个会话时它会自动加载这些标记了alwaysApply: true的规则文件。这意味着AI的人格、原则、你的个人信息、操作规范等在对话一开始就已经作为“已知背景”存在于其上下文中无需中继服务进行任何额外的提示词工程。这带来了几个巨大优势透明与可审计所有影响AI行为的规则都以纯文本文件形式存在你可以随时查看和修改完全掌控AI的“人格设定”。稳定性高避免了在服务端动态拼接提示词可能导致的格式错误或上下文污染。性能更佳减少了每次请求传输的数据量。记忆系统的运作流程记忆系统分为“记忆写入”和“记忆召回”两个部分形成了一个完整的闭环记忆写入Memory Flush在长时间对话中AI会主动将重要的结论、决策或你的偏好以结构化的格式追加写入.cursor/MEMORY.md或按日期生成的日志文件中。这个过程由memory-protocol.mdc规则驱动强制AI进行“记忆防丢失”操作防止因上下文窗口长度限制而遗忘关键信息。记忆召回Memory Recall当AI需要回答关于过去工作、历史决策或你个人偏好的问题时memory-protocol.mdc规则会强制它先调用内置的memory-tool.ts工具进行搜索。这个工具会同时在向量数据库用于语义搜索和全文索引用于关键词BM25搜索中进行查找并将相关记忆片段作为参考信息插入到当前上下文中。这就实现了真正意义上的“长期记忆”。身份系统的初始化出生仪式最精妙的设计之一是“首次运行仪式”。项目模板中包含一个.cursor/BOOTSTRAP.md文件。当你首次在一个新工作区启动服务并开始对话时AI会读取这个文件并引导完成一个“出生仪式”——它会给自己起一个名字、选择一个表情符号Emoji、并让你主人填写USER.md来了解你。这个过程不仅趣味性强更重要的是在互动中建立了初始的身份认知和关系设定比冷冰冰的配置文件要生动有效得多。实操心得千万不要跳过或忽视这个“出生仪式”。这是你塑造AI助手性格和互动风格的黄金机会。在它自我介绍时你可以通过对话明确你对它的期望比如“我希望你是一个严谨的代码审查者”或“我希望你是一个富有创造性的头脑风暴伙伴”这些早期互动会深刻影响后续的行为模式。3. 从零开始的完整部署与配置指南3.1 基础环境准备与飞书应用创建在开始之前请确保你的环境满足以下要求。我强烈建议使用 macOS尤其是 Apple Silicon 芯片的机型因为其与 Cursor 和本地语音识别的兼容性最好。第一步安装基础依赖# 1. 安装 Bun 运行时比 Node.js 更快更现代 # 访问 https://bun.sh 官网使用其推荐的安装命令通常如下 curl -fsSL https://bun.sh/install | bash # 2. 安装 Cursor IDE 并确保 Agent CLI 可用 # 从 https://cursor.com 下载并安装 Cursor。 # 安装后打开 Cursor在设置中启用 “Cursor Agent”。 # 通常CLI 工具会自动安装到 ~/.local/bin/agent。在终端验证 ~/.local/bin/agent --version # 如果看到版本号则说明成功。 # 3. 可选但推荐安装本地语音识别备用引擎 brew install ffmpeg whisper-cpp # ffmpeg 用于音频格式处理whisper-cpp 提供离线语音识别能力。第二步创建并配置飞书机器人这是连接链路中最关键的一环请严格按照步骤操作进入飞书开放平台访问 https://open.feishu.cn 使用你的飞书账号登录。点击“创建企业自建应用”。填写应用基本信息应用名称可以随意例如“我的AI助手”。应用描述可写“用于远程控制Cursor AI”。添加“机器人”能力在应用功能页面点击“添加能力”选择“机器人”。配置权限在“权限管理”页面为机器人添加以下权限im:message获取用户发给机器人的单聊消息im:message.group_at_msg获取群聊中机器人的消息im:resource上传图片、文件等资源注意im:message.p2p_msg通常用于获取单聊消息但根据飞书版本im:message可能已涵盖。如果测试收不到单聊消息可以尝试也加上im:message.p2p_msg配置事件订阅这是核心在“事件订阅”页面点击“启用事件”。在“请求地址配置”中选择“WebSocket 模式”长连接。这是本项目使用的模式它不需要你有一个公网服务器地址非常适合本地运行。在“订阅事件”中添加im.message.receive_v1接收消息v1.0这个事件。发布版本与启用在“版本管理与发布”页面创建一个新版本例如1.0.0并勾选上一步配置的权限和事件。提交审核。企业自建应用通常可以“自主发布”无需飞书官方审核提交后等待几分钟即可生效。生效后在“凭证与基础信息”页面你会看到App ID和App Secret。请妥善保存下一步会用到。3.2 项目部署与核心配置完成环境准备后我们就可以部署feishu-cursor-claw服务本身了。# 1. 克隆项目代码 git clone https://github.com/nongjun/feishu-cursor-claw.git cd feishu-cursor-claw # 2. 安装项目依赖 bun install # 3. 复制并编辑环境配置文件 cp .env.example .env现在用文本编辑器打开.env文件这是项目的心脏。你需要填写以下关键配置# .env 配置文件详解 CURSOR_API_KEY你的Cursor API Key # 获取方式登录 https://cursor.com/dashboard - Integrations - User API Keys - Create new key FEISHU_APP_ID你的飞书 App ID # 从上一步飞书开放平台获取 FEISHU_APP_SECRET你的飞书 App Secret # 从上一步飞书开放平台获取 CURSOR_MODELopus-4.6-thinking # 默认使用 Cursor 的 opus 模型也可改为 claude-3-5-sonnet 或 gpt-4o 等 # --- 以下为可选但强烈推荐的配置 --- VOLC_STT_APP_ID你的火山引擎 App ID VOLC_STT_ACCESS_TOKEN你的火山引擎 Access Token # 用于高质量中文语音识别配置方法见下文“语音识别专项配置” VOLC_EMBEDDING_API_KEY你的火山引擎 Embedding API Key # 用于记忆系统的向量搜索配置后记忆搜索能力大幅提升关于火山引擎语音识别STT的专项配置为了获得最佳的中文语音识别体验我强烈建议配置火山引擎的流式语音识别服务。它的准确率和速度远超本地whisper-cpp模型。注册并登录 火山引擎控制台 。在左上角搜索“语音技术”进入产品页面。点击“立即开通”通常有免费额度。开通后进入“应用管理”创建一个新应用。在“服务管理”中确保开通了“大模型流式语音识别”服务资源包 ID 通常为volc.bigasr.sauc.duration。在“密钥管理”中你可以获取到AppID注意不是Access Key。Access Token需要通过调用其密钥生成API来获取通常有SDK或简单的HTTP接口。你可以暂时在项目文档或代码中搜索相关生成脚本或者使用火山引擎提供的测试工具获取一个临时Token进行测试。将获取到的AppID和Access Token填入.env。注意事项如果暂时不想配置火山引擎完全没问题。系统会自动降级到使用本地whisper-cpp的tiny模型。只是识别准确率尤其是对中文的识别率会有明显下降。这是一个优雅的降级方案保证了基础功能的可用性。3.3 服务启动与自动化管理配置完成后你可以选择手动启动进行测试但为了持久化运行我强烈推荐使用项目提供的service.sh脚本它基于 macOS 的launchd系统提供了开机自启、崩溃重启等生产级能力。# 测试性运行前台运行方便查看日志 bun run server.ts # 如果看到“飞书长连接已启动等待消息...”说明基础连接成功。 # 安装为系统服务推荐 bash service.sh install # 这个命令会 # 1. 将服务配置为 launchd 守护进程。 # 2. 立即启动服务。 # 3. 设置日志输出到 /tmp/feishu-cursor.log。 # 检查服务状态 bash service.sh status # 应该看到 “Service is running (PID: XXXX)”。 # 查看实时日志 bash service.sh logs # 类似于 tail -f 的效果可以监控运行情况。其他常用的服务管理命令bash service.sh restart # 重启服务修改.env后通常需要重启 bash service.sh stop # 停止服务 bash service.sh uninstall # 卸载服务移除开机自启至此你的AI远程控制中枢就已经在后台默默运行了。接下来我们深入看看如何通过飞书与它进行高效互动。4. 飞书交互实操与高级功能详解4.1 基础指令与多模态交互服务运行后你可以在飞书中找到你创建的机器人应用并开始私聊或拉群它。以下是一些最常用的指令中英文均可指令示例功能说明使用场景帮我写一个Python函数计算斐波那契数列发送纯文本指令。AI会开始在你配置的默认工作区执行。最常用的交互方式适合代码生成、文档撰写、问题解答。/status或/状态查看服务状态。返回当前使用的模型、API Key状态、语音识别引擎、活跃会话等。快速检查服务是否健康确认当前配置。/model claude-3-5-sonnet或/模型 claude-3-5-sonnet动态切换AI模型。无需重启服务。根据任务需求切换不同的模型例如从opus切换到sonnet进行更复杂的推理。/apikey sk-...或/密钥 sk-...仅限私聊动态更新Cursor API Key。当Key失效或需要更换时极其方便。安全机制确保了该指令在群聊中会被拦截。/new或/新对话重置当前工作区的会话。这会清空AI的上下文但长期记忆文件不受影响。开始一个全新的、无上下文干扰的任务。project:docs: 总结一下上周的会议纪要项目路由。project:后的docs是项目别名后面跟指令。将任务定向到特定的工作区。例如docs项目指向你的文档文件夹code项目指向代码库。多模态输入的实际体验语音消息直接发送飞书语音。服务会优先使用火山引擎STT转换为文字速度快准确率高失败则降级到本地whisper。转换后的文字会作为指令执行。图片消息发送截图或文档照片。目前版本主要依赖AI模型自身的视觉能力如果模型支持如GPT-4V来解读图片内容。未来可能集成本地OCR进行预处理。文件消息发送文档如.md,.txt,.pdf,.docx。AI可以读取文件内容并基于其进行分析、总结或修改。实操心得充分利用项目路由功能来区分不同的工作上下文。我通常会配置三个项目dev代码开发、writing内容创作、ops运维脚本。这样当我发送dev: 修复登录接口的bug时AI会在代码目录下操作而发送writing: 润色这篇博客的开头时它则会在我的文稿文件夹中工作互不干扰上下文也更纯净。4.2 记忆系统的深度使用与定制记忆系统是让AI从“一次性工具”变为“长期伙伴”的核心。你需要主动引导和利用它。1. 引导AI记录记忆记忆不会自动产生需要你在对话中引导。例如“记住我更喜欢用空格缩进而不是Tab。”“将‘项目部署必须经过三步检查代码扫描、单元测试、预发验证’这个规则记录到我们的工作规范里。”“把我刚才说的关于用户画像的要点总结一下存到记忆里。”AI在收到这类指令后会根据memory-protocol.mdc规则将信息结构化地写入.cursor/MEMORY.md文件。2. 主动进行记忆搜索当你需要AI基于过去的信息进行工作时可以使用记忆搜索指令/memory 用户画像或/记忆 用户画像进行语义搜索查找所有与“用户画像”相关的记忆片段。/memory查看记忆系统的整体状态包括索引了多少条记忆等。3. 个性化你的AI伙伴编辑工作区下的.cursor/rules/目录中的文件可以深度定制AIagent-identity.mdc给你的AI起名、设定性格。例如你可以定义它叫“CodePal”性格是“热情且严谨的编程助手”。user-context.mdc填写关于你自己的信息。例如你的技术栈偏好、常用工具、工作习惯等。这能帮助AI给出更贴合你个人情况的建议。soul.mdc定义核心原则。例如“安全第一”、“在给出解决方案前先解释原理”、“对于不确定的事情要明确标出”等。tools.mdc列出AI可以访问的服务器、API、内部工具文档。这相当于扩展了AI的“知识库”和“能力集”。修改这些.mdc文件后无需重启服务。因为Cursor Agent会在每个新会话开始时重新加载它们。4.3 定时任务与心跳系统实现自动化巡检这是将AI从“响应式助手”升级为“主动式管家”的功能。定时任务Cron Jobs你可以直接告诉AI创建定时任务它会自动管理cron-jobs.json文件。创建“创建一个定时任务每天上午10点检查服务器状态并汇总报告给我。”管理/task或/任务列出所有定时任务及其状态激活/暂停。/task pause 1或/任务 暂停 1暂停ID为1的任务。/task run 1或/任务 执行 1立即手动执行一次ID为1的任务。AI创建的任务可以是一次性、固定间隔如每2小时或Cron表达式如0 10 * * *每天10点。任务到期时服务会自动执行并将结果发送到飞书。心跳系统Heartbeat心跳系统是一个后台守护进程默认每30分钟唤醒一次AI让它执行.cursor/HEARTBEAT.md文件中定义的检查清单。典型检查项AI可能会检查项目依赖是否有更新、日志文件是否过大、是否有未完成的TODO、记忆索引是否需要优化等。自主管理高级之处在于AI会自己维护这个检查清单。如果它发现某个检查项不再适用或者有新的常规工作需要加入它可以主动修改HEARTBEAT.md文件。状态追踪检查历史记录在.cursor/memory/heartbeat-state.json中避免重复执行相同的工作。你可以通过指令管理心跳/heartbeat on或/心跳 开启开启心跳。/heartbeat interval 60或/心跳 间隔 60将检查间隔改为60分钟。/heartbeat now或/心跳 执行立即触发一次心跳检查。注意事项定时任务和心跳系统都是“计划任务”它们依赖于你本地服务的持续运行。如果你关闭了电脑或停止了feishu-cursor-claw服务这些任务将不会执行。因此将其部署在一台长期开机的机器如家庭服务器、旧Mac mini上是最佳实践。5. 故障排查与性能优化经验谈即使配置再仔细在实际运行中也可能遇到问题。以下是我在长期使用中总结的常见问题及其解决方案以及一些提升稳定性和效率的技巧。5.1 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案飞书发消息机器人完全没反应。1. 服务未运行。2. WebSocket连接失败。3. 飞书应用权限或事件未正确配置。1. 运行bash service.sh status确认服务进程是否存在。2. 运行bash service.sh logs查看最新日志关注有无连接错误。3. 检查飞书开放平台应用是否已发布新版本im.message.receive_v1事件是否订阅务必使用“WebSocket模式”。服务日志显示Failed to connect to Feishu或Authentication failed。1..env中的FEISHU_APP_ID或FEISHU_APP_SECRET错误。2. 飞书应用凭证已重置。1. 核对.env文件中的飞书凭证确保无空格或换行。2. 前往飞书开放平台在“凭证与基础信息”页面确认App Secret是否已重置重置后旧密钥立即失效。AI执行任务时报错Invalid API Key。1.CURSOR_API_KEY无效或过期。2. 额度用完。1. 在飞书私聊机器人发送/apikey 你的新Key进行动态更新。2. 登录 Cursor Dashboard 检查API Key状态和用量。发送语音消息识别结果乱码或为繁体中文。火山引擎STT服务未正确配置或失效系统降级到本地whisper而本地模型对中文支持不佳。1. 检查.env中VOLC_STT_APP_ID和VOLC_STT_ACCESS_TOKEN是否正确。2. 在火山引擎控制台确认“大模型流式语音识别”服务已开通且有剩余资源。3. 尝试在飞书发送/status查看STT Engine显示的是volc还是whisper。执行/memory 搜索时无结果或报错。1. 未配置向量嵌入API。2. 记忆索引未建立或损坏。1. 配置.env中的VOLC_EMBEDDING_API_KEY以启用向量搜索。2. 执行/reindex或/整理记忆命令强制重建整个工作区的记忆索引。这个过程可能需要几分钟取决于文件数量。服务运行一段时间后自动退出。1. 内存泄漏或进程崩溃。2. 系统休眠导致网络中断。1.使用service.sh安装服务launchd会在进程退出后自动重启它。2. 检查/tmp/feishu-cursor.log日志文件看崩溃前是否有错误堆栈信息。3. 对于macOS可在“系统设置-电池”中为终端或相关应用设置“防止自动休眠”。群聊中尝试执行/apikey被拒绝。这是安全设计防止API Key在群聊中泄露。这是正常行为。如需更换Key请与机器人进行私聊操作。5.2 性能优化与最佳实践为了让feishu-cursor-claw运行得更稳定、更高效我总结了几条关键建议1. 工作区规划策略隔离上下文为不同类型的任务创建不同的“项目”通过projects.json配置。例如将代码、文档、个人笔记分开。这能保证每个会话的上下文干净减少无关文件对AI的干扰也能提升记忆搜索的准确性。精简索引范围记忆系统会索引工作区下所有文本文件。如果某个目录包含大量无关的、自动生成的如node_modules,dist,.git或二进制文件可以考虑在代码层面修改server.ts中的索引过滤逻辑或者简单地保持工作区目录的整洁。2. 模型与成本管理按需切换模型对于简单的代码补全或问答可以使用opus-4.6-thinking如果可用或gpt-4o-mini这类成本较低的模型。对于复杂的系统设计、策略分析再切换到claude-3-5-sonnet或gpt-4o。使用/model指令可以轻松切换。关注上下文长度Cursor的Agent会话会保留完整的上下文历史。非常长的对话会消耗更多Token。对于已完结的话题适时使用/new指令开启新会话可以重置上下文控制成本。3. 服务稳定性保障务必使用service.sh这是将脚本变为可靠后台服务的最简单方法。它处理了日志轮转、进程守护、开机自启等繁琐问题。监控日志定期使用bash service.sh logs或tail -f /tmp/feishu-cursor.log查看运行情况。关注是否有重复的错误信息。备用方案如果你的主力电脑需要经常携带或休眠可以考虑将feishu-cursor-claw部署在一台小型、常开的家庭服务器如树莓派、旧笔记本或云服务器上。只需确保该服务器能访问互联网用于飞书WebSocket和AI API以及你的核心工作文件可通过网络共享或Git同步。4. 安全须知保管好.env文件该文件包含所有核心密钥。切勿将其提交到Git等版本控制系统。项目自带的.gitignore文件通常已忽略.env但请再次确认。理解权限边界AI将在你配置的工作区目录下拥有读取和写入文件的权限。切勿将其指向系统关键目录如/,/etc,/Users/你的用户名/Desktop等。最好为其创建专属的工作目录。群聊安全项目已内置防护禁止在群聊中执行/apikey等敏感指令。但日常对话内容仍会暴露在群聊中。对于涉及敏感信息的任务请始终使用私聊。经过以上的详细拆解和配置你应该已经能够将一个强大的、具有记忆和人格的AI助手通过飞书这个最熟悉的界面无缝接入你的日常工作流。从简单的代码生成到复杂的项目管理和自动化巡检feishu-cursor-claw提供了一个极具想象力的范式。它的魅力不在于替代你而在于成为你思维和能力的延伸一个随时在线、不知疲倦的数字化伙伴。开始动手配置吧你会发现那种“心念一动事已办成”的流畅感才是人机协同进化的下一个篇章。