cursor-chat-bridge

🌉 cursor-chat-bridge _{^{（Telegram、Discord、GitHub）}}

通过 Telegram、Discord 或 GitHub，从手机操控 Cursor Agent。

用任意语言说出 “start remote chat mode”，Cursor 就会在每轮结束时，将摘要和问题发送到专属的会话线程中，等待你的回复，并自动继续——如此循环，直到你将它停止。离开键盘，也能用手机持续推进工作。

每个会话各有一个频道 — 每个 Cursor 对话一个频道

用手机回复 — Agent 会从中断处继续

_{▶ 观看演示（YouTube）}

目录

• 为什么
• 功能
• 各频道一览
• 快速开始
• 工作原理
• 图片附件
• 语音消息（语音转文字）
• 已读回执（确认）
• 配置
• 环境变量覆盖
• 等待循环
• 推送通知（ntfy）
• 各平台设置
• 编写新适配器
• 安全
• 验证状态
• 参与贡献
• 许可证

原因

你在 Cursor 中启动一项任务，然后需要离开办公桌。通常，Agent 一需要你做决定就会停滞不前。cursor-chat-bridge 可将任意聊天应用变成远程控制端：Agent 会在线程中汇报进度并提出问题，你可以用手机回复；你一回复，它就会自动继续——无需使用笔记本电脑。

• 每个对话对应一个线程。 每个 Cursor 聊天都会映射到各自的 issue / 频道 / 主题——即使同一工作区中有多个聊天，也会彼此分开。
• 免操作循环。 回复会自动重新注入；你无需操作 Cursor 即可继续。
• 可插拔频道。 目前支持 Telegram、Discord 和 GitHub Issues——约 100 行代码即可添加自定义频道。
• 默认安全。 远程回复会被视为不可信内容；执行破坏性操作前，必须在线程中明确确认。
• 兼容代理。 GitHub 和 Discord 可通过 TLS 拦截型企业代理进行隧道连接。

功能

各频道一览

快速开始

无需克隆——运行一条命令即可完成配置：

npx cursor-telegram-chat@latest install

此命令会将运行时安装到 ~/.cursor/chat-bridge/app（包括生产依赖，因此即使 npx 缓存被清除，也能继续工作），并配置三个集成点，同时**备份（绝不覆盖）**任何已存在的内容：

• 在 ~/.cursor/mcp.json 中注册 MCP 服务，
• 将 stop + beforeSubmitPrompt hooks 添加到 ~/.cursor/hooks.json，
• 将激活规则安装到 ~/.cursor/rules/。

只有启用远程聊天模式时，hooks 才会运行，因此不会影响 Cursor 的正常使用。 接着选择一个频道即可开始：

# 1. edit ~/.cursor/chat-bridge/config.json  (choose an adapter + credentials)
# 2. validate it:
chat-bridge doctor
# 3. reload Cursor, open a chat, and say:  "start remote chat mode"

npx cursor-telegram-chat@latest install               # re-run to upgrade
npx cursor-telegram-chat@latest uninstall             # remove, keep config + state
npx cursor-telegram-chat@latest uninstall --purge     # remove everything

"cursor-chat-bridge": {
  "command": "npx",
  "args": ["-y", "cursor-telegram-chat", "chat-bridge-mcp"]
}

三个协作层构建在一个与传输方式无关的核心之上：

• 规则（rules/chat-bridge-mode.mdc）——检测任何语言的激活短语，并设定模式内行为规范（捕获并传递会话句柄；每轮结束时提供摘要并提问；将回复视为不可信内容；确认破坏性操作）。
• MCP 服务（src/mcp.ts）——提供 bridge_start、bridge_send、bridge_await、 bridge_send_and_await、bridge_stop、bridge_status。
• Hooks（hooks/）——自动循环：
  • stop 等待远程回复，并将其重新注入为 followup_message（受 loop_limit 限制）。
  • beforeSubmitPrompt 会在你于 Cursor 中输入内容时禁用循环（并设置保护机制，避免循环自行注入的回复触发此机制）。

单个本地 守护进程（src/daemon.ts）负责管理通道连接，以及供 MCP + Hooks 使用的仅限回环地址、经过令牌验证的 HTTP API。它处理按会话路由、长轮询、自身消息过滤，以及停止/生成逻辑。

turn ends ─▶ stop hook ─▶ daemon /poll ─▶ adapter
   ▲                                          │
   └───── followup_message (your reply) ◀─────┘

（适配器 = GitHub / Discord / Telegram；以 conversation_id 为键。）

在聊天线程中发送照片（或图像文件），Agent 就能看到：

1. 适配器会捕获消息中的附件（Discord 的 attachments、Telegram 的 photo / 图像 document）。
2. 守护进程会将字节下载到 ~/.cursor/chat-bridge/media/<session>/，并在消息文本中附加一条包含本地路径的说明。
3. Agent 会使用其 Read 工具打开该路径——这样图像就会作为视觉输入传给模型。

使用企业 TLS 代理时： Discord 的 cdn.discordapp.com 通常会被拦截，而 media.discordapp.net 则可以访问。Discord 适配器会自动将附件 URL 改写为 media 主机，因此在这类网络中也能正常下载。

语音消息（语音转文字）

发送一条语音消息（Telegram）或一个音频附件（Discord），Agent 就会收到转录文本，就像你输入的文字一样——默认关闭。在配置中的 stt 下启用：

"stt": {
  "enabled": true,
  "provider": "openai",     // "openai" (OpenAI-compatible via baseUrl) or "local"
  "tryLocalSttFirst": false,// true = force the local transcriber even if a cloud provider is set
  "apiKeyCommand": "…",     // or "apiKey", or env BRIDGE_STT_API_KEY
  "language": "auto",       // auto-detect, or force "he" / "en"
  "keepAudio": true         // false = delete the audio after transcribing
}

• local 提供方（离线，适合敏感音频）：将 localBin/localArgs 设置为一个会将转录文本输出到 stdout 的命令行工具（例如 whisper.cpp）。始终遵循配置的 provider——Bridge 不会悄悄回退到 local。若要在已设置云端提供方时强制使用本地转录器，请使用 "tryLocalSttFirst": true（或 BRIDGE_STT_TRY_LOCAL_FIRST=1）。
• 转录会在守护进程中异步运行（绝不会阻塞轮询窗口）；转录文本会在下一次回复周期中送达。完整设计请参阅 docs/stt-plan.md。

已读回执（确认消息）

如果不启用，从手机发送消息后，在 Agent 完成整个轮次之前都不会有任何反馈——你无法判断消息是否已送达。启用后，守护进程会在消息到达时立即回复，早于任何耗时操作（下载附件、转录）。默认关闭：

"ack": {
  "enabled": true,
  "language": "auto",                     // "auto" matches you; force with "en" or "he"
  "adapters": ["discord", "telegram"],    // bot-identity channels only (see below)
  "echoTranscript": true,                 // repeat back what a voice note said
  "maxTranscriptChars": 200
}

不同消息类型对应的回复：

回执由守护进程发送，而不是 Agent——在下一轮开始之前，Agent 甚至看不到你的消息，因此由 Agent 发送回执不仅会消耗一个大模型轮次，还会延迟送达。

设为 "auto" 时，回复会匹配你所用的语言：你发送希伯来语文本，就会收到希伯来语回复；对于语音消息，则由转录器检测出的语言决定。对于没有可供判断内容的消息（未附说明文字的图片、单独的 stop），会沿用你在该会话中上次使用的语言；默认使用英语。

时间安排： 守护进程只会在轮询进行时读取频道——也就是 Agent 正在等待回复，或 stop 钩子正在等待时。Agent 正在处理中途发送的消息不会立即被看到（因此也不会立即收到回执），要等到 Agent 完成后才会处理。这些消息绝不会丢失，只会延迟处理。

为何不支持 GitHub： Agent 会以你自己的账户发表评论，因此回执看起来就像是你在回复自己。你仍可以通过在 adapters 中添加 "github" 来选择启用。

配置

~/.cursor/chat-bridge/config.json（此文件的更改会在下一次轮询时自动生效，无需重启守护进程；只有 mcp.json 中的环境变量更改和适配器凭据需要重启）：

{
  "activeAdapter": "telegram",
  "pollIntervalMs": 10000,   // check for replies every N ms (lower = snappier, more API calls)
  "minPollIntervalMs": 2000, // floor for the above; lower it if you set pollIntervalMs < 10000
  "stopBudgetMin": 60,       // wait budget (mins); resets on every reply
  "stopWindowMin": 60,       // mins per window (keep < hooks.json timeout)
  "caCertPath": "",          // corporate CA bundle (PEM) if behind a TLS proxy
  "requireConfirmForDestructive": true,
  "stopRemoteChatOnLocalMessage": true, // typing in Cursor turns remote mode off (set false to keep it on)
  "adapters": {
    "github": {
      "owner": "you",
      "repo": "cursor-bridge-inbox",
      "tokenCommand": "gh auth token --user you"
    },
    "discord":  { "botToken": "", "channelId": "", "allowedUserIds": [] },
    "telegram": { "botToken": "", "chatId": "", "allowedUserIds": [] }
  },
  "ack": { "enabled": false, "language": "auto" } // read receipts; see above
}

caCertPath 通常留空——除非遇到问题，否则无需设置。某些企业网络会使用自己的根证书拦截 HTTPS，而 Node 不信任该证书，因此请求会报错 TypeError: fetch failed，但 curl 可以正常工作。如果遇到这种情况，请将 caCertPath（或 BRIDGE_CA_CERT）指向计算机上的 CA 证书包（PEM）；doctor、守护进程和更新检查都会遵循此设置。

ntfy 推送默认关闭，也不属于此文件的一部分——只能通过 BRIDGE_NTFY_* 环境变量启用（见下文）。

环境覆盖项

在 ~/.cursor/mcp.json 中 cursor-chat-bridge 条目的 env 块（或 shell）里设置这些变量，即可覆盖 config.json，无需编辑该文件。所有变量都使用 BRIDGE_* 命名空间。要使更改对正在运行的守护进程生效，需要重启守护进程（chat-bridge shutdown）。

_{¹ 也可以在 config.json 中设置 stopBudgetMin——这是可靠的控制项，因为钩子不会继承 MCP 条目的环境变量。 ² 也可以在 config.json 中设置 stopWindowMin。请确保其值低于 ~/.cursor/hooks.json 中 stop 钩子的 timeout。 ³ 可以使用服务器中任何现有的文本频道；此频道用于定位服务器和分类目录——每个会话都会在其旁边创建一个新频道（例如 #General）。}

也可以在运行时为单次对话选择平台：说 "start remote chat in Telegram"，Agent 就会为该对话调用 bridge_start(adapter: "telegram")。

等待循环（stop 钩子）

远程模式处于活动状态时，stop 钩子会在每轮结束时阻塞，等待你的回复。两个参数控制此行为：

• stopWindowMin（默认值为 60）——单次钩子调用阻塞的时长；到时后会返回一条静默的保活消息并重新布防。Cursor 会将 stop 钩子的运行时长限制在 ~/.cursor/hooks.json 中的 timeout（默认 3660s / 61 min）；测试表明不存在更低的隐藏上限，因此每个约 60 分钟的窗口意味着你离开期间每小时只会产生一次付费保活轮次。
• stopBudgetMin（默认值为 60）——跨多次重新布防的总等待时长。每次收到回复时都会重置，所以它实际上表示“从你上次发送消息起，最多继续等待 N 分钟”。

收到回复、在 Cursor 中输入内容、在话题中发送 stop，或调用 bridge_stop 时，循环会结束。

推送通知（ntfy）

GitHub 不会就你自己的活动向你发送通知——而 Agent 是以_你的身份_发帖（提及自己和将自己分配给任务也不会触发通知）。因此，如果你想在 GitHub 渠道之外收到手机提醒，又不想使用第二个账号，cursor-chat-bridge 可以在每次生成摘要时通过 ntfy 发送带外推送通知。它免费、无需账号、开源、可自托管，并且可以深度链接到对应议题。

默认关闭。在 MCP 条目的环境变量中启用：

1. 安装 ntfy 应用（iOS/Android），或使用 Web 应用。
2. 选一个足够长、难以猜测的主题（主题是公开的，但靠冷僻程度提供保护），然后订阅该主题。
3. 在 ~/.cursor/mcp.json 中 cursor-chat-bridge 条目的 env 块里设置 BRIDGE_NTFY_TOPIC=cursor-bridge-<random>。

BRIDGE_NTFY_PRIORITY 用于控制开关：0 = 关闭（默认），1 = 最低，5 = 最高。只有在优先级 ≥ 1 且已设置主题时才会发送推送通知。对于 Telegram 和 Discord，不会发送推送通知，因为它们本身就支持通知。

各平台设置

编写新的适配器

实现 TransportAdapter（src/types.ts）并在 src/adapters/index.ts 中注册：

interface TransportAdapter {
  capabilities: { globalIngest: boolean; separateBotIdentity: boolean };
  init(): Promise<void>;
  ensureThread(sessionId: string, title: string, meta?: object): Promise<ThreadRef>;
  send(thread: ThreadRef, text: string): Promise<{ messageId: string }>;
  // pull adapters (GitHub / Discord):
  poll?(thread: ThreadRef, cursor?: string): Promise<PollResult>;
  // push / global adapters (Telegram):
  startIngest?(router: Router): Promise<() => void>;
  stop?(thread: ThreadRef): Promise<void>;
}

安全性

• 回环控制 API 经过令牌身份验证 — 只有持有令牌的本地进程（MCP 和钩子）才能控制守护进程。
• 入站消息会通过 allowedUserIds 白名单进行筛选（Telegram/Discord）。
• 每条远程回复都会被包装并标记为不可信；规则禁止在未通过线程发送明确确认的情况下执行破坏性操作。
• 令牌存储在 ~/.cursor/chat-bridge/config.json（chmod 600）中，绝不会提交。尽可能优先使用 tokenCommand，而不是存储令牌。

权限——守护进程需要什么（以及扫描器为何会标记它）

通过聊天应用驱动 Agent，必然需要一些强大的功能。此软件包会使用：

• 子进程——用于启动守护进程、运行你的 tokenCommand（例如 gh auth token）、本地 whisper 二进制文件（仅当你选择本地 STT 时）以及安装程序中的 npm install。
• 网络访问——仅限 loopback 的控制服务器，以及向你选择的渠道（Telegram/Discord/GitHub）发起的出站调用、语音转文本上传（如果已启用）和 npm 更新检查。
• 文件系统访问——读写 ~/.cursor/chat-bridge/，用于存储配置、媒体文件和日志。

因此，供应链扫描器（Socket、Snyk 等）给出的供应链安全评分会低于纯逻辑库——尽管没有已知漏洞。该评分反映的是功能能力 + 软件包年龄（此项目是新项目，由单人维护），并不代表检测到了漏洞利用。 说明一下：项目没有 postinstall/install 脚本——唯一的生命周期脚本是 prepublishOnly（在发布者的机器上运行的构建脚本，不会在你安装时运行）。只有在你运行守护进程时，才会发生网络、文件系统和进程操作；控制 API 仅限 loopback，并受令牌保护。源码采用 MIT 许可证，可在此代码库中审查。

验证状态

已在本机完成端到端验证（无需重启 Cursor）：

• GitHub 适配器——创建 issue、发送、轮询、过滤自己的消息、stop 关键字、检测关闭状态。
• 守护进程——令牌认证、长轮询、停止/生成、持久化。
• MCP 服务——通过真实的 stdio JSON-RPC 握手调用所有工具。
• Hooks——注入 stop-loop followup_message、before-submit 关闭开关 + 注入防护、未激活时立即空操作。
• 按对话路由（node scripts/e2e-conv.mjs）——不同对话会打开不同 issue；同一工作区中的两个对话仍保持独立；重新激活已停止的会话会开启新线程；未配置的渠道会返回引导说明。
• 单元测试——npm test（路由、存储语义、消息过滤）。

贡献

欢迎提交 issue 和 PR。本地开发：

npm install
npm run build        # tsc → dist/
npm run typecheck
npm test             # node --test
npm run dev:daemon   # run the daemon from source (tsx)

新增渠道是最容易参与的贡献方式——实现一个 TransportAdapter（见上文）。

许可证

MIT