飞书集成Cursor AI：打造个人AI战略伙伴的远程控制与自动化工作流

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服务。这个服务是整个系统的大脑，它需要完成以下几项关键工作：

1. 消息解析与预处理：识别消息类型（文本、图片、语音、文件），对于语音消息，会调用语音识别（STT）服务转换为文本；对于图片，可能会提取其中的文字信息（如果未来集成OCR）。
2. 会话与项目管理：解析消息中是否包含project:前缀以路由到不同的工作区目录，并管理会话状态，确保同一会话的对话具有连续性（--resume参数）。
3. 指令拦截与安全审查：判断消息是否为系统指令（如/help,/model），并执行相应操作。同时，在群聊环境中拦截敏感操作（如更换API Key），确保安全。
4. 调用Cursor Agent：将处理后的纯文本指令，通过子进程调用本地的~/.local/bin/agent命令行工具。这里采用了会话级并发的设计，即不同工作区的会话可以并行执行，互不干扰，而同一会话内的请求则串行处理，避免了状态混乱。
5. 流式响应与进度反馈：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的“人格设定”。
• 稳定性高：避免了在服务端动态拼接提示词可能导致的格式错误或上下文污染。
• 性能更佳：减少了每次请求传输的数据量。

记忆系统的运作流程记忆系统分为“记忆写入”和“记忆召回”两个部分，形成了一个完整的闭环：

1. 记忆写入（Memory Flush）：在长时间对话中，AI会主动将重要的结论、决策或你的偏好，以结构化的格式追加写入.cursor/MEMORY.md或按日期生成的日志文件中。这个过程由memory-protocol.mdc规则驱动，强制AI进行“记忆防丢失”操作，防止因上下文窗口长度限制而遗忘关键信息。
2. 记忆召回（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 提供离线语音识别能力。

第二步：创建并配置飞书机器人这是连接链路中最关键的一环，请严格按照步骤操作：

1. 进入飞书开放平台：访问 https://open.feishu.cn ，使用你的飞书账号登录。点击“创建企业自建应用”。
2. 填写应用基本信息：应用名称可以随意，例如“我的AI助手”。应用描述可写“用于远程控制Cursor AI”。
3. 添加“机器人”能力：在应用功能页面，点击“添加能力”，选择“机器人”。
4. 配置权限：在“权限管理”页面，为机器人添加以下权限：
   • im:message（获取用户发给机器人的单聊消息）
   • im:message.group_at_msg（获取群聊中@机器人的消息）
   • im:resource（上传图片、文件等资源）
   • （注意：im:message.p2p_msg通常用于获取单聊消息，但根据飞书版本，im:message可能已涵盖。如果测试收不到单聊消息，可以尝试也加上im:message.p2p_msg）
5. 配置事件订阅：这是核心！
   • 在“事件订阅”页面，点击“启用事件”。
   • 在“请求地址配置”中，选择“WebSocket 模式”（长连接）。这是本项目使用的模式，它不需要你有一个公网服务器地址，非常适合本地运行。
   • 在“订阅事件”中，添加im.message.receive_v1（接收消息v1.0）这个事件。
6. 发布版本与启用：
   • 在“版本管理与发布”页面，创建一个新版本（例如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_MODEL=opus-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模型。

1. 注册并登录 火山引擎控制台 。
2. 在左上角搜索“语音技术”，进入产品页面。
3. 点击“立即开通”，通常有免费额度。
4. 开通后，进入“应用管理”创建一个新应用。
5. 在“服务管理”中，确保开通了“大模型流式语音识别”服务（资源包 ID 通常为volc.bigasr.sauc.duration）。
6. 在“密钥管理”中，你可以获取到AppID（注意不是Access Key）。Access Token需要通过调用其密钥生成API来获取，通常有SDK或简单的HTTP接口。你可以暂时在项目文档或代码中搜索相关生成脚本，或者使用火山引擎提供的测试工具获取一个临时Token进行测试。
7. 将获取到的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 基础指令与多模态交互

服务运行后，你可以在飞书中找到你创建的机器人应用，并开始私聊或拉群@它。以下是一些最常用的指令，中英文均可：

多模态输入的实际体验：

• 语音消息：直接发送飞书语音。服务会优先使用火山引擎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/目录中的文件，可以深度定制AI：

• agent-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 常见问题与解决方案速查表

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提供了一个极具想象力的范式。它的魅力不在于替代你，而在于成为你思维和能力的延伸，一个随时在线、不知疲倦的数字化伙伴。开始动手配置吧，你会发现那种“心念一动，事已办成”的流畅感，才是人机协同进化的下一个篇章。