1. 项目概述

如果你和我一样，是个重度依赖 Cursor AI 来写代码、审文档、甚至规划项目的开发者，那你肯定也遇到过这样的场景：正坐在沙发上刷手机，突然想到一个绝妙的代码优化思路，或者需要立刻查看某个项目的文档。这时候，你是选择爬起来走到电脑前，还是等会儿再说？等会儿可能就忘了。 CursorClaw 这个项目，就是为了解决这个“最后一米”的痛点而生的。它本质上是一个智能中继服务，让你能通过手机上的飞书、钉钉或者企业微信，直接远程操控你 Mac 电脑上的 Cursor AI。想象一下，你在通勤路上，用手机给机器人发条消息：“帮我检查一下 main.ts 文件里有没有内存泄漏的风险”，几分钟后，一份详细的分析报告就推送到了你的手机上。这不仅仅是远程控制，更是将你的 AI 助手无缝融入日常工作流，让它真正成为你的“私人战略合伙人”。

这个项目最初源于社区里一个优秀的开源项目 feishu-cursor-claw ，但原版只支持飞书。在实际使用中，我发现团队协作环境多样，有的用钉钉，有的用企业微信，单一平台支持显然不够。于是，我花了大量时间对其进行重构和扩展，最终形成了现在这个支持三平台并行、架构清晰、功能丰富的 CursorClaw 。它的核心优势在于“无感接入”——不需要你有公网 IP，也不需要复杂的端口映射，通过各 IM 平台提供的长连接机制，让你的本地服务主动“找上门”去接收消息，安全又省心。接下来，我将从设计思路到实操细节，为你完整拆解这个项目，手把手带你部署属于你自己的“移动版 Cursor 指挥部”。

1.1 核心需求与设计哲学

在动手改造之前，我首先问了自己几个问题：一个理想的、通过 IM 控制 AI 的工具应该是什么样的？第一，它必须稳定可靠，不能动不动就失联；第二，它要能理解上下文，记住我不同项目的偏好和之前的对话；第三，操作要足够简单，最好能和日常聊天一样自然；第四，它得能同时服务多个工作区，我在处理 A 项目时，突然有个 B 项目的想法，能无缝切换。

基于这些思考， CursorClaw 的设计哲学可以概括为 “连接、记忆与自动化” 。

1. 连接（Connection） ：利用飞书、钉钉、企业微信官方提供的 WebSocket 或 Stream 长连接方案，实现本地服务与云端 IM 服务器的双向通信。这种方式完美避开了需要公网 IP 或内网穿透的麻烦，是服务稳定性的基石。三个平台的服务（ feishu/ , dingtalk/ , wecom/ ）在架构上完全独立，这意味着你可以只启用你需要的，或者同时运行三个，它们通过共享的 projects.json 和记忆数据库来协同工作，互不干扰。

2. 记忆（Memory） ：这是让 AI 从“工具”升级为“合伙人”的关键。简单的会话历史恢复（ --resume ）只是基础。我设计了一套分层记忆系统：

   • 短期记忆 ：每个工作区的对话记录，以 JSONL 格式保存在 .cursor/sessions/ 下，确保单次会话的连贯性。
   • 长期记忆 ：一个名为 .cursor/MEMORY.md 的 Markdown 文件，AI 会以“日记”形式，自主地将重要的决策、你的偏好、项目关键信息摘要记录于此。同时，每天会生成一个独立的记忆文件归档。
   • 向量记忆 ：这是高级功能。通过集成向量数据库（SQLite + FTS5全文搜索），你可以对记忆进行语义搜索。比如，你可以问：“我之前关于用户认证方案是怎么考虑的？”，即使原话不精确，AI 也能通过向量相似度找到相关记录。这个功能需要配置额外的 Embedding API（如火山引擎），属于锦上添花。

3. 自动化（Automation） ：除了被动响应，AI 应该能主动做事。我实现了两个系统：

   • 定时任务（Scheduler） ：你可以直接告诉 AI “每天上午 10 点给我推送项目日报” 或 “半小时后提醒我开会”。AI 会解析你的自然语言，创建对应的 Cron 任务，写入 cron-jobs-*.json ，时间一到自动执行并将结果推送到 IM。
   • 心跳系统（Heartbeat） ：这是一个后台守护进程，定期（如每小时）触发一个特殊的“心跳”任务。这个任务会让 AI 执行一系列预设的维护动作，比如整理碎片化的记忆、检查各项目状态、甚至执行一些简单的代码仓库健康检查（如 git status ），并将状态记录在 .cursor/memory/heartbeat-state.json 中。这相当于给你的数字工作空间安排了一个定时的“保洁阿姨”。

这套组合拳下来， CursorClaw 就不再是一个简单的消息转发器，而是一个具备初步自主性和上下文感知能力的智能体环境。

1.2 技术栈选型与考量

选型直接决定了项目的开发体验、运行效率和维护成本。这里我详细解释一下几个关键选择背后的原因：

• 运行时：Bun + TypeScript

  • 为什么是 Bun？ 对比 Node.js，Bun 的启动速度和运行时性能有显著优势，这对于需要快速响应消息的机器人服务至关重要。其内置的包管理器、测试运行器和原生对 .env 、 tsx 的支持，极大地简化了开发和部署流程。一条 bun install 命令搞定所有依赖，体验非常流畅。
  • 为什么是 TypeScript？ 项目涉及多个 IM 平台 SDK 的集成、复杂的异步消息流处理以及自定义记忆系统，类型系统能在开发阶段就捕获大量潜在的错误，提高代码的健壮性和可维护性。对于这种中间件性质的项目，TypeScript 带来的收益远大于学习成本。

• 连接层：各平台官方 SDK

  • 飞书 ：使用 @larksuiteoapi/node-sdk ，它官方支持 WebSocket 长连接模式（ receive 事件），这是实现稳定、实时通信的官方推荐方式。
  • 钉钉 ：使用 dingtalk-stream SDK。钉钉机器人的“Stream 模式”也是一种长连接，但其事件模型与飞书略有不同，需要单独适配。
  • 企业微信 ：使用 @wecom/aibot-node-sdk 。企业微信机器人的回调模式相对传统，但通过其 SDK 也能建立稳定的连接。一个值得注意的细节是，企业微信支持服务端主动向客户端推送消息（无需客户端轮询），这在某些场景下响应延迟更低。
  • 核心考量 ：坚持使用官方 SDK 而非自己封装 HTTP 回调，是为了长期稳定性和功能兼容性。官方 SDK 会跟随平台 API 更新，并且通常内置了重连、签名验证等复杂逻辑，能避免很多“坑”。

• 数据持久化：SQLite

  • 这是个人或小团队项目的绝配。无需搭建独立的数据库服务，一个文件搞定所有。我利用 SQLite 的 FTS5（全文搜索） 扩展来实现对记忆文本的快速关键字检索，同时预留了向量存储的接口（例如用 vector 扩展或单独的表），为后续的语义搜索打下基础。所有数据文件（ .sqlite , .json , .md ）都存放在项目或工作区目录下，备份和迁移极其方便。

• 进程管理：macOS launchd

  • 为了让服务能在后台稳定运行且开机自启，我选择了 macOS 原生的 launchd 。每个服务目录下的 service.sh 脚本，其核心功能就是生成并加载对应的 .plist 文件到 ~/Library/LaunchAgents/ 。这种方式比 pm2 或 forever 更“原生”，资源占用更少，与系统集成度更高。脚本也提供了 status , logs , restart 等命令，管理起来和系统服务一样简单。

这个技术栈组合，在开发效率、运行性能和系统集成度上取得了很好的平衡，也是项目能够清晰拆分为三个独立服务并共享核心模块的基础。

2. 核心模块深度解析

理解了整体设计，我们深入到各个核心模块，看看它们是如何具体工作的。这部分内容是你未来进行二次开发或深度定制的基础。

2.1 消息流处理管道

无论来自哪个平台，一条用户消息的完整处理旅程都遵循一个清晰的管道。以飞书为例，我们拆解一下 feishu/server.ts 中的核心流程：

1. 连接建立与鉴权 ：服务启动时，会读取 .env 中的 FEISHU_APP_ID 和 FEISHU_APP_SECRET ，向飞书服务器发起 WebSocket 连接请求并进行鉴权。成功后，建立一个持久的长连接通道。
2. 消息接收与解析 ：当用户在飞书聊天中 @机器人发送消息时，飞书服务器会通过 WebSocket 推送一个 im.message.receive_v1 事件。服务端监听此事件，从中提取出关键的 message_id 、 chat_id 、 content （JSON 字符串）以及发送者信息。
3. 多模态内容预处理 ：消息内容可能是纯文本、图片、语音甚至文件。这里有一个重要的 降级策略 ：
   • 语音 ：如果配置了火山引擎的 STT（语音转文字）服务，则优先使用，识别准确率高。如果未配置，则尝试调用本地的 whisper-cpp 进行识别。如果两者都不可用，则回复提示用户“暂不支持语音消息”或直接忽略。
   • 图片 ：下载图片到临时目录，然后使用 OCR 工具（如 tesseract ）或调用多模态 AI API 来识别图片中的文字，将识别结果作为文本内容继续处理。
   • 文件 ：下载文件到临时目录，根据文件类型（如 .txt , .md , .pdf 需要解析文字， .zip 需要解压）进行预处理，提取出可读的文本信息。
   • 文本 ：直接进入下一步。 这个过程在 bridge.ts 或类似的消息预处理模块中完成，确保了后续 AI 处理的是统一的文本信息。
4. 项目路由与会话管理 ：系统会检查消息内容是否包含类似 项目名: 的前缀（如 docs: 总结一下 ）。如果有，则路由到指定的项目工作区；如果没有，则使用当前活跃的或默认的项目。确定项目后，系统会为该项目的会话创建一个唯一的会话 ID，并检查是否存在之前的会话记录（ --resume 文件）。如果存在，则在调用 Cursor CLI 时带上 --resume 参数，让 AI 恢复上下文。
5. 调用 Cursor AI ：这是核心步骤。服务会构造一个命令行调用，指向 ~/.local/bin/agent （Cursor Agent CLI）。命令大致如下：

   ~/.local/bin/agent --model auto --project /path/to/project --resume /path/to/session.jsonl -- “用户的问题”
   

   • --model auto ：让 Cursor 自动选择最优模型，有助于节省团队配额。
   • --project ：指定工作区路径，AI 可以访问该目录下的文件。
   • --resume ：提供会话历史文件，实现连续对话。
   • 消息内容作为参数传入。 这个调用是 异步 且 流式 的。CLI 会逐步输出 AI 的思考过程和最终答案。
6. 流式回复与状态推送 ：为了提供更好的体验，AI 思考的过程中，服务会通过 IM 平台的消息“更新”API，持续地向用户推送进度卡片（例如，“正在思考...”、“正在编写代码...”）。对于企业微信这种支持服务端主动推送的模式，体验会更流畅；对于飞书，则需要通过轮询更新消息卡片来实现类似效果。
7. 结果交付与记忆存储 ：当 AI 完成响应后，服务会将最终结果发送给用户。同时，本次完整的对话交互（包括用户消息和 AI 回复）会被追加到该会话的 JSONL 历史文件中，作为短期记忆。如果对话中触发了记忆存储指令（如用户说“记住这个”），或者 AI 自主判断某些信息重要，则会调用 memory-tool.ts 将信息写入长期记忆（ MEMORY.md ）或向量数据库。

实操心得 ：消息处理管道中最容易出问题的环节是 多模态预处理 和 流式回复 。对于预处理，一定要做好错误边界处理，任何一个环节失败（如下载失败、识别失败）都要有明确的降级或报错机制，避免整个管道崩溃。对于流式回复，要注意 IM 平台对消息更新频率的限制，过于频繁的更新可能会导致 API 调用被限流。我的经验是，设置一个简单的防抖（debounce）机制，比如每 2 秒或当 AI 输出积累到一定字符数时才推送一次更新。

2.2 记忆系统的实现细节

记忆系统是项目的“大脑”。它不仅仅是保存文本，更重要的是如何有效地存储和检索。我实现的记忆系统分为三层：

1. 会话层（短期记忆） ：

   • 实现 ：每个项目工作区下， .cursor/sessions/ 目录中会为每个会话创建一个 {timestamp}-{sessionId}.jsonl 文件。每行都是一条完整的消息记录（角色、内容、时间戳）。
   • 原理 ：Cursor CLI 的 --resume 参数直接读取这个文件格式。当开始新对话时，系统会基于当前时间戳和随机数生成一个新的会话 ID 和文件。当需要恢复对话时，只需将对应的文件路径传给 --resume 即可。
   • 技巧 ：为了避免会话文件无限增长，可以设置一个自动清理机制。例如，在 heartbeat.ts 中定期检查，删除超过 7 天或文件大小超过一定限制的旧会话文件。

2. 日记层（长期记忆 - 文本） ：

   • 实现 ：在记忆工作区（由 projects.json 中的 memory_workspace 指定）的 .cursor/ 目录下，维护一个 MEMORY.md 文件。同时，每天会生成一个归档文件，如 .cursor/memory/2023-10-27.md 。
   • 原理 ：AI 在对话中，可以通过调用 memory-tool.ts 暴露的工具函数，向这个文件追加内容。内容格式是结构化的 Markdown，例如：

     ## 2023-10-27 15:30:00
     *   **用户偏好**：用户表示更喜欢使用 `async/await` 而非 `.then()` 语法处理异步。
     *   **项目决策**：决定在 `myapp` 项目中采用 `Zod` 进行运行时数据验证。
     *   **代码片段**：记录了一个常用的 `debounce` 工具函数。
     

   • 检索 ：当用户提问涉及历史信息时，AI 可以指令 memory-tool.ts 去搜索 MEMORY.md 和归档文件。最初的版本是简单的文件读取和字符串匹配，后来升级为集成 SQLite 的 FTS5 进行全文搜索，速度更快。

3. 向量层（长期记忆 - 语义） ：

   • 实现 ：这是一个可选的高级功能。在 shared/memory.ts 中，我设计了一个 VectorMemory 类。当此功能启用时（配置了 VOLC_EMBEDDING_API_KEY ），重要的记忆条目在存入日记的同时，也会通过 Embedding API 转换为向量，并连同原文一起存入 SQLite 数据库的一个特定表中。
   • 原理 ：当用户进行语义搜索时（例如，“我之前对错误处理有什么想法？”），系统会将查询语句也转换为向量，然后在数据库中进行向量相似度计算（如余弦相似度），返回最相关的几条记忆原文。
   • 混合搜索 ：在实际的 memory-tool.ts 中，我实现了 “关键词检索 (FTS5) + 语义检索 (向量)” 的混合模式 。先通过 FTS5 快速筛选出包含相关关键词的候选集，再在这个较小的候选集上进行向量相似度排序，兼顾了速度和准确性。

注意事项 ：向量记忆虽然强大，但引入外部 API 也带来了复杂性和成本。对于个人使用，如果记忆量不大，仅使用 FTS5 全文搜索的日记层已经非常够用。启用向量搜索前，务必评估 API 调用成本和响应延迟。另外，向量数据库的初始化和管理（如创建索引、定期清理过期数据）也需要在 heartbeat.ts 中考虑。

2.3 定时任务与心跳系统

这两个系统赋予了 AI 一定程度的“自主性”。

• 定时任务系统 ( shared/scheduler.ts ) ：

  • 创建 ：AI 在对话中解析用户的自然语言指令（如“每周末备份数据库”）。它会提取出任务内容、执行时间（或 Cron 表达式），然后生成一个任务对象，追加到对应的 cron-jobs-feishu.json （或钉钉、企业微信的）文件中。
  • 调度 ：每个服务的 server.ts 在启动时，会加载对应的 JSON 文件，并使用 node-cron 或类似的库来注册这些定时任务。任务到期时，调度器会模拟一个用户消息（包含预设的任务指令），调用 Cursor CLI 去执行，并将执行结果推送到指定的 IM 会话。
  • 持久化 ：任务列表以 JSON 格式保存在文件中，即使服务重启，任务也不会丢失。 /任务 指令可以让用户查看和管理这些任务。
  • 安全边界 ：非常重要！定时任务执行的 AI 指令是预先定义好的。为了避免意外，我在设计时 没有 允许 AI 在定时任务中执行任意 Shell 命令。所有任务都必须通过 Cursor CLI 来执行，这在一定程度上利用了 Cursor 自身的安全沙箱机制。

• 心跳系统 ( shared/heartbeat.ts ) ：

  • 触发 ：这是一个独立的定时任务，通常设置为每小时运行一次。它被硬编码在服务启动逻辑中，而不是由 AI 动态创建。
  • 执行内容 ：心跳任务会读取一个特殊的提示文件—— .cursor/HEARTBEAT.md 。这个文件里定义了一系列维护性指令，例如：

    请检查并整理 MEMORY.md 文件，将过时或重复的信息归档到历史文件中。
    请检查 projects.json 中所有项目的 git 状态，如果有未提交的更改，生成一个简要报告。
    请根据最近的对话，总结一下我的工作重点和待办事项。
    

  • 作用 ：你可以把心跳系统看作一个“后台守护进程”或“数字管家”。它确保记忆系统不会变得杂乱无章，并能定期给你提供一些项目状态的快照。执行结果会记录在 .cursor/memory/heartbeat-state.json 中，方便你查看。

踩坑记录 ：定时任务系统最大的坑是 “时间同步” 和 “任务去重” 。最初版本没有考虑服务器时间与用户所在时区的差异，导致任务在错误的时间执行。后来我强制所有 Cron 表达式使用 UTC 时间，并在创建任务时由 AI 明确提示用户“任务将基于 UTC 时间执行”。另外，如果用户频繁说“每天提醒我”，可能会创建多个相同的任务，需要实现简单的任务内容哈希比对来防止重复添加。

3. 从零开始部署与配置实战

理论说得再多，不如动手做一遍。下面我将以部署 飞书服务 为例，带你走一遍完整的流程。钉钉和企业微信的流程高度相似，主要区别在于后台应用的创建和 SDK 的初始化。

3.1 环境准备与基础安装

首先，确保你的开发机（通常是 macOS）满足以下条件：

1. 安装 Bun 运行时 ：这是项目的基石。打开终端，执行以下命令。如果已安装，Bun 会提示。

   curl -fsSL https://bun.sh/install | bash
   

   安装完成后，重启终端或执行 source ~/.zshrc （或 ~/.bashrc ）使 bun 命令生效。用 bun --version 验证安装。

2. 安装 Cursor 并登录 CLI ：

   • 从 cursor.com 下载并安装 Cursor IDE。
   • 打开 Cursor，完成初始设置和账号登录。
   • 关键一步 ：安装 Cursor Agent CLI。这是 Cursor 提供的命令行工具，是我们的服务与 Cursor AI 核心交互的桥梁。

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

   • 安装后，运行以下命令进行登录。这会通过浏览器完成 OAuth 认证，比手动配置 API Key 更安全方便，且能使用团队配额。

   ~/.local/bin/agent login
   

   • 验证是否成功： ~/.local/bin/agent --help 应该能显示帮助信息。

3. 获取项目代码 ：

   git clone https://github.com/keunsy/cursorclaw.git
   cd cursorclaw
   

   注意：原仓库已归档，新功能在 Cursor Remote Control ，但 CursorClaw 的稳定性和核心架构依然值得学习。我们以此为基础进行部署。

3.2 飞书后台应用创建与配置

这是连接飞书的关键步骤，需要仔细操作。

1. 进入飞书开放平台 ：访问 飞书开放平台 ，使用你的飞书账号登录（通常需要企业账号，个人账号也可创建“自建应用”）。
2. 创建企业自建应用 ：
   • 点击“创建企业自建应用”。
   • 填写应用名称，如 我的Cursor助手 ，应用描述可自定。
   • 选择应用图标（可选）。
   • 创建完成后，进入应用详情页。
3. 获取凭证 ：在“凭证与基础信息”页面，你可以看到 App ID 和 App Secret 。请立即记录下来，我们稍后会用到。
   • App ID 通常以 cli_ 开头。
   • App Secret 务必妥善保管，不要泄露。
4. 配置权限 ：在“权限管理”页面，为应用添加以下权限：
   • im:message （获取用户发给机器人的单聊消息）
   • im:message.group_at_msg （获取群聊中@机器人的消息）
   • im:resource （获取消息中的图片、文件等资源）
   • 添加权限后，记得在页面底部点击“批量申请”或“申请发布”。
5. 发布应用 ：在“版本管理与发布”页面，创建一个新版本（如 1.0.0），并提交发布申请。通常自建应用在同一个企业内可以自动通过。
6. 添加到聊天 ：发布后，在“应用发布”页面，你可以将应用添加到“我的机器人”或直接分享链接给其他成员，将其添加到群聊或单聊中。

重要提示 ： 先不要配置事件订阅 。我们需要先启动本地服务，获得服务的地址后，再回来配置。

3.3 本地服务配置与启动

现在回到我们的项目目录，配置并启动飞书服务。

1. 配置项目路由 ：这是告诉机器人你的代码项目都在哪。

   # 在 cursorclaw 根目录
   cp projects.json.example projects.json
   

   用你喜欢的编辑器（如 VSCode、Cursor）打开 projects.json ，修改内容。例如：

   {
     "projects": {
       "work": {
         "path": "/Users/你的用户名/Code/company-project",
         "description": "公司主项目"
       },
       "personal": {
         "path": "/Users/你的用户名/Code/my-side-project",
         "description": "个人学习项目"
       },
       "docs": {
         "path": "/Users/你的用户名/Documents",
         "description": "文档库"
       }
     },
     "default_project": "work",
     "memory_workspace": "work"
   }
   

   • projects : 定义你的工作区，键名（如 work ）就是你在聊天中用来路由的标识符。
   • path : 必须是绝对路径 。
   • default_project : 用户未指定项目时默认使用的工作区。
   • memory_workspace : 长期记忆（ MEMORY.md ）和向量数据库存储的位置。通常设为你最常使用的项目。

2. 配置飞书服务环境变量 ：

   cd feishu
   cp .env.example .env
   

   打开 feishu/.env 文件，填入你的飞书凭证，并做关键配置：

   # 飞书应用凭证（必须）
   FEISHU_APP_ID=cli_xxxxxx # 替换成你的 App ID
   FEISHU_APP_SECRET=xxxxxxxxxx # 替换成你的 App Secret
   
   # Cursor 配置（关键！）
   # 如果你已经用 `agent login` 登录，这里可以注释掉或留空，优先使用登录态
   # CURSOR_API_KEY=
   # 模型选择：强烈建议使用 `auto`，让 Cursor 智能选择，节省配额
   CURSOR_MODEL=auto
   
   # 可选：火山引擎语音识别（提升语音消息体验）
   # VOLC_STT_APP_ID=your_volc_app_id
   # VOLC_STT_ACCESS_TOKEN=your_volc_token
   
   # 可选：火山引擎向量嵌入（启用语义记忆搜索）
   # VOLC_EMBEDDING_API_KEY=your_embedding_key
   # VOLC_EMBEDDING_MODEL=doubao-embedding-vision-250615
   

3. 安装依赖并启动服务 ：

   bun install
   bash service.sh install
   

   service.sh install 这个命令做了几件事：安装依赖、编译 TypeScript、创建 launchd 服务配置文件 ( com.user.cursorclaw.feishu.plist )、加载并启动服务。服务会以后台进程形式运行。

4. 验证服务状态与获取地址 ：

   bash service.sh status
   

   如果显示 running ，说明服务已启动。现在，查看日志获取关键信息：

   bash service.sh logs | head -20
   

   在日志开头，你应该能看到类似这样的信息：

   [INFO] Feishu Cursor Claw starting...
   [INFO] WebSocket URL for Feishu Event Subscription: wss://xxxxx
   

   记下这个 WebSocket URL 。

3.4 完成飞书事件订阅配置

现在回到飞书开放平台的应用配置页面。

1. 进入“事件订阅”页面。
2. 启用长连接模式 ：在“Encrypt Key”下方，应该有一个“长连接模式”的选项，选择它。
3. 配置请求地址 ：将上一步从日志中获取的 WebSocket URL 填入“请求地址”栏。 注意 ：飞书可能需要你去掉 wss:// 前缀，只填域名和路径部分，具体以平台提示为准。如果日志中的 URL 是完整的 wss:// 开头，通常直接填入即可。
4. 订阅事件 ：在事件列表里，找到并订阅 im.message.receive_v1 （接收消息v1）这个事件。
5. 保存并启用 ：点击保存，然后启用事件订阅。

配置完成后，飞书服务器会尝试向你的 WebSocket URL 发起连接。此时查看服务日志 ( bash service.sh logs )，应该能看到飞书连接成功的消息。

3.5 首次对话测试

一切就绪，打开飞书，找到你添加了机器人的单聊或群聊。

1. @你的机器人，发送一条简单的消息，例如： @我的Cursor助手 你好，介绍一下你自己 。
2. 稍等几秒，你应该能收到一条来自机器人的回复。如果收到，恭喜你，基础通道打通了！
3. 尝试项目路由：发送 personal: 列出当前目录下的文件 。机器人应该会在你的个人项目路径下执行 ls 命令（通过 Cursor AI）。
4. 尝试记忆功能：发送 记住我最常用的编辑器是 VSCode 。然后过一会儿再问 我最喜欢用什么编辑器？ ，看 AI 是否能从记忆中找回答案。

如果测试失败，请跳转到下一章的故障排查部分。

4. 高级功能配置与使用技巧

基础功能跑通后，我们可以来探索那些让效率倍增的高级特性。

4.1 配置语音识别（飞书/钉钉）

语音消息能极大提升移动端输入的便利性。项目提供了云端（火山引擎）和本地（whisper-cpp）两套方案。

方案一：火山引擎豆包 STT（推荐，准确率高）

1. 注册并登录 火山引擎控制台 。
2. 在“语音技术”产品中，找到“大模型流式语音识别”或类似服务，开通并创建应用。
3. 获取 APP_ID 和 ACCESS_TOKEN （注意不是 Secret Key）。
4. 将这两个值填入对应服务目录下的 .env 文件：

   VOLC_STT_APP_ID=你的APP_ID
   VOLC_STT_ACCESS_TOKEN=你的ACCESS_TOKEN
   

5. 重启服务： bash service.sh restart 。
6. 现在，向机器人发送语音消息，它应该能先转成文字再交给 AI 处理。

方案二：本地 whisper-cpp（离线，隐私好）

1. 安装 whisper-cpp: brew install whisper-cpp 。
2. 下载语音模型（例如 ggml-base.bin ）到本地。你可以从 Hugging Face 等社区找到模型。
3. 在代码中（如 feishu/bridge.ts ）需要修改语音处理逻辑，将调用火山引擎 API 的部分改为调用本地 whisper-cpp 命令行工具。
   • 注意 ：原项目可能已内置降级逻辑。如果未配置火山引擎密钥，会自动尝试调用本地 whisper 命令。你需要确保 whisper 命令在系统路径中可用，且指定了正确的模型路径。
4. 本地识别速度较慢，且准确率取决于模型大小和硬件，适合对隐私要求极高、网络不便的场景。

实操心得 ：对于中文语音识别，火山引擎豆包 STT 的效果远好于开源的 whisper 模型，尤其是在带有专业术语或嘈杂环境的录音中。如果你的使用场景以中文为主，强烈建议使用方案一。成本方面，语音识别的费用通常很低，个人使用每月开销几乎可忽略不计。

4.2 配置向量记忆搜索

这是实现“模糊查找记忆”的关键。它允许你问：“我上个月关于用户登录的方案是怎么设计的？”，即使原话是“设计了基于 JWT 的登录流程”，AI 也能通过语义相似度找到答案。

1. 同样在火山引擎控制台，开通“向量数据库”或“嵌入模型”相关服务。找到提供 Embedding 的 API，获取 API_KEY 。
2. 在 .env 中配置：

   VOLC_EMBEDDING_API_KEY=你的API_KEY
   VOLC_EMBEDDING_MODEL=doubao-embedding-vision-250615 # 模型名以火山引擎文档为准
   

3. 重启服务。首次启用时，服务会初始化 SQLite 数据库并创建向量存储表。
4. 使用 /记忆 关键词 指令进行测试。例如， /记忆 登录 ，AI 会返回所有语义上与“登录”相关的记忆片段。

底层原理 ：当一条信息被标记为需要长期记忆时（通过 /记录 指令或 AI 自主判断），系统会做两件事：1) 将文本摘要写入 MEMORY.md ；2) 调用 Embedding API 将文本转换为一个高维向量（一组数字），并和原文、时间戳一起存入 SQLite 的 memories 表。搜索时，将查询词也转换为向量，计算数据库中所有向量与查询向量的余弦相似度，返回相似度最高的几条。

4.3 多项目管理与切换策略

projects.json 是管理多个工作区的核心。除了静态配置，在实际对话中，有几种灵活的切换方式：

• 前缀路由 ：在消息开头使用 项目名: 。例如 docs: 总结一下上周的会议纪要 。这条消息会被路由到 docs 项目，且 不会 改变当前的默认项目。适合临时性的跨项目操作。
• 指令切换 ：发送 切换到 work 或 切换到 personal 。这会 持久地 将当前聊天会话的默认项目切换到 work 或 personal ，后续所有不带前缀的消息都会在这个新项目下执行。这个状态是保存在服务内存或某个会话状态文件中的。
• 默认项目 ：所有未指定项目的消息，都会流向 default_project 定义的项目。

最佳实践 ：将你最核心、最常用的项目设为 default_project 和 memory_workspace 。为不同的工作流创建不同的项目入口，比如 frontend , backend , research 。这样，你可以通过简单的自然语言指令，让 AI 在不同的代码上下文之间无缝跳转。

4.4 定时任务与自动化工作流

定时任务是释放生产力的利器。除了简单的提醒，你可以创建复杂的自动化工作流。

创建方式 ：直接对 AI 说自然语言。

• 简单提醒 ：“每天下午 5 点提醒我写日报。”
• 周期性任务 ：“每周一上午 9 点，帮我分析 work 项目下 src/utils/ 目录的代码复杂度，并给出优化建议。”
• 一次性任务 ：“3 小时后提醒我给客户发邮件。”
• 复杂指令 ：“每月 1 号凌晨 2 点，自动运行 work 项目下的 scripts/backup.js 脚本，并把日志发给我。”

AI 会解析这些指令，将其转换为 Cron 表达式，并写入 cron-jobs-feishu.json 。任务执行时，AI 会收到一个包含特定指令的“系统消息”，然后像处理普通用户消息一样去执行。

查看与管理 ：使用 /任务 指令可以列出所有定时任务。在飞书/钉钉的版本中，你可能还可以通过回复任务消息来进行“删除”或“立即执行”等操作（具体取决于实现）。

高级技巧 ：你可以将心跳系统 ( HEARTBEAT.md ) 与定时任务结合。例如，在 HEARTBEAT.md 中写道：“检查所有项目的 package.json ，如果有依赖过期，生成一个报告。” 这样，每小时的心跳检查就会自动为你做依赖审计。

5. 故障排查与性能优化实录

即使按照步骤操作，也难免会遇到问题。这里我汇总了部署和使用过程中最常见的“坑”及其解决方案。

5.1 服务启动与连接问题

问题现象	可能原因与排查步骤
执行 bash service.sh install 后， status 显示 not running 或 error	1. 检查 Bun 和 Cursor CLI ：确保 bun --version 和 ~/.local/bin/agent --help 都能正常执行。 2. 检查 .env 文件 ：确认 FEISHU_APP_ID 和 FEISHU_APP_SECRET 已正确填写，且没有多余的空格或换行。 3. 查看详细日志 ： bash service.sh logs 查看具体错误信息。常见错误： - Cannot find module ‘...’ ：依赖未安装，在 feishu 目录下重新运行 bun install 。 - Invalid app_id or app_secret ：飞书凭证错误，去开放平台核对。 - Error: spawn agent ENOENT ：Cursor CLI 未安装或路径不对，重新执行 curl https://cursor.com/install -fsS | bash 。
服务显示 running ，但飞书收不到消息回复	1. 检查事件订阅 ：登录飞书开放平台，确认 im.message.receive_v1 事件已订阅，且“长连接模式”已开启，请求地址配置正确。 2. 检查权限 ：确认应用已添加 im:message 等必要权限，并且 已发布版本 。 3. 检查网络 ：确保你的电脑可以访问飞书服务器。尝试在终端 ping open.feishu.cn 。 4. 查看服务端日志 ： bash service.sh logs 看是否有收到消息的事件记录。如果收到消息但处理出错，日志会有详细堆栈。
机器人回复缓慢或超时	1. 检查 Cursor 模型 ：在 .env 中，将 CURSOR_MODEL 设置为 auto 。如果设置为 opus-4.6-thinking 等大型思考模型，响应会非常慢，且容易耗尽配额。 2. 检查网络代理 ：如果你的网络需要代理才能访问 Cursor 服务，需要配置 Bun 或 Node.js 的代理环境变量。 3. 查看 AI 处理日志 ：日志中会记录调用 agent CLI 的耗时。如果耗时过长，可能是当前问题复杂，AI 需要长时间思考。

5.2 功能特异性问题

问题现象	可能原因与排查步骤
语音消息识别为乱码或失败	1. 确认配置 ：检查 .env 中 VOLC_STT_* 配置是否正确。 2. 检查配额 ：登录火山引擎控制台，确认语音识别服务有余量。 3. 降级测试 ：注释掉火山引擎配置，测试本地 whisper-cpp 是否工作。安装 whisper-cpp : brew install whisper-cpp ，并确保模型文件已下载。 4. 格式支持 ：确认飞书/钉钉发送的语音格式（如 silk, amr）在代码的音频处理模块中有对应的解码逻辑。
/记忆 搜索返回空或错误	1. 确认向量搜索已启用 ：检查 .env 中 VOLC_EMBEDDING_API_KEY 是否配置。 2. 检查数据库 ：查看记忆工作区目录下是否生成了 .memory.sqlite 文件。 3. 初始化问题 ：首次启用向量搜索，需要 AI 执行一次记忆写入操作来初始化表结构。尝试先发送 /记录 这是一条测试记忆 ，然后再搜索。 4. 纯文本搜索 ：如果未配置向量， /记忆 指令会退回到 FTS5 全文搜索，只匹配精确关键词。
定时任务没有按时执行	1. 时区问题 ：Cron 表达式使用的是 UTC 时间 。确认你创建任务时 AI 提示的时间是 UTC，并计算与你本地时间的偏移（例如，北京时间 UTC+8）。 2. 服务重启 ：检查服务是否在任务预定时间点之后重启过。 launchd 服务如果崩溃重启，可能会错过一些任务。查看 bash service.sh logs 是否有异常重启记录。 3. 任务文件权限 ：确认 cron-jobs-feishu.json 文件对服务进程可写。
文件发送功能报错“文件不存在”或“大小超限”	1. 路径问题 ：确保路径是绝对路径，并且服务进程有权限读取（服务通常以你的用户身份运行，问题不大）。使用 ~ 家目录缩写是支持的。 2. 大小限制 ：飞书/钉钉对机器人发送文件有大小限制（通常为 30MB）。检查文件大小。 3. 临时目录 ：文件上传时会先保存到临时目录（如 /tmp ），确保磁盘空间充足。

5.3 性能优化与维护建议

长期稳定运行，还需要一些维护技巧。

1. 会话历史管理 ：长期运行后， .cursor/sessions/ 目录下的 JSONL 文件会越来越多。虽然单个文件不大，但数量多了也占空间。建议在 heartbeat.ts 的维护任务中，加入自动清理逻辑，例如删除超过 30 天的会话文件。
2. 日志轮转 ：服务的日志文件默认在 /tmp/feishu-cursor.log ，会不断增长。可以使用系统的 logrotate 工具来配置日志轮转，避免磁盘被撑满。一个简单的 logrotate 配置示例：

   # /etc/newsyslog.d/cursorclaw.conf
   /tmp/feishu-cursor.log /tmp/dingtalk-cursor.log /tmp/wecom-cursor.log {
       daily
       rotate 7
       compress
       delaycompress
       missingok
       notifempty
       create 644 <your_username> staff
   }
   

3. 资源监控 ：三个服务同时运行会占用一定的内存和 CPU。可以使用 bash manage-services.sh status 查看进程 ID，然后用 top -pid <PID> 或 htop 观察资源使用情况。如果发现某个服务内存持续增长（内存泄漏），可能需要检查代码中是否有未释放的资源（如数据库连接）。
4. 依赖更新 ：定期在项目根目录和各服务子目录下运行 bun update 来更新依赖包，修复潜在的安全漏洞和 Bug。
5. 配置备份 ：你的核心配置（ projects.json , 各服务的 .env 文件）都没有提交到 Git。务必定期备份这些文件。可以将它们复制到 iCloud Drive 或使用版本控制工具（如 git-crypt ）进行加密管理。

部署并熟练使用 CursorClaw 后，你会发现它极大地改变了你和 Cursor AI 的协作方式。从必须坐在电脑前，到随时随地通过熟悉的聊天工具发起复杂的编程、文档或思考任务，这种自由感是前所未有的。项目的架构设计也体现了很好的扩展性，你可以基于 shared/ 下的模块，轻松地为其他 IM 平台（如 Slack、Discord）添加支持，或者集成更多的自动化工具。记住，所有的自动化都是为了解放创造力，而不是增加负担。从解决一个小痛点开始，逐步构建你的智能工作流，这才是技术工具最大的价值。