Skip to content

实现 VSCode/Cursor 快速打开文件

1. 现象和结论

本机已经打开了 Cursor,结果从外部调用 Cursor 去打开文件却要等待数秒。理论上应该很快,比如人工操作时,可以直接按下 Ctrl+P 输入文件路径,然后按下回车,文件就打开了。

结论:已有 Cursor 窗口打开文件本身很快,主要延迟发生在外部调用启动新 Cursor 进程、准备向已有实例转交请求之前。

当前普通调用路径:

→ 启动新的 Cursor.exe
→ 新进程执行一部分初始化
→ 发现已有 Cursor 实例
→ 通过本机 IPC 管道转交请求
→ 已有窗口打开文件

如果不启动新的 Cursor.exe 进程,而是直接使用 IPC 管道,则可以很快打开文件:

→ 连接已有 Cursor 的 IPC 管道
→ 调用 launch.start
→ 已有窗口打开文件

目前博客就是使用这种方式,把这种方式注册成一种协议,然后通过浏览器点击打开,打开速度极快,很香。配合点击关闭按钮隐藏到托盘,可以做到非常方便的打开和关闭。

VSCode/Cursor 快速打开文件

2. 实验条件与计时结果

2.1 环境检查

  • 已运行的 Cursor 主进程当时为 PID 28060。
  • 主进程打开的工作区为 C:\Users\34802\Desktop\WorkSpaces\blog.code-workspace。
  • 工作区包含 D:/Blog 和 D:/BlogSite。
  • Windows 的 cursor:// 协议指向同一个 Cursor 安装目录,注册命令为:
"C:\Program Files\cursor\Cursor.exe" --open-url -- "%1"
  • 博客编辑按钮是普通的 cursor://file/... 链接,没有额外的 JavaScript 等待逻辑。
  • 实验交替打开 D:\Blog\done\index.md 与 D:\Blog\done\About\1.Hi.md,没有写入文件内容。
  • 这两个路径是同一个 NTFS 文件的硬链接;交替打开它们用于观察窗口标题变化。

2.2 初始完整路径计时

下面以已有 Cursor 窗口标题切换到目标文件作为可观察终点:

调用方式 观测到的时间
Windows 唤起 cursor:// 协议 5.19、6.23、6.43 秒左右
直接运行协议处理命令 3.42、3.54 秒左右
直接运行 Cursor.exe,并指定复用窗口 3.72 秒左右
cursor --reuse-window 3.61、3.84、4.19 秒左右

这些测试都复用了原来的 blog 窗口。表中是不同批次的观测值,不能直接相减后认定 Windows 协议调用固定增加了多少时间;浏览器点击到 Windows 开始处理请求的耗时没有单独测量。

2.3 分段计时:请求转交前后分别花了多久

随后使用带日志的直接调用,并缩短窗口标题轮询间隔,取得两次有效对照:

时刻,从进程启动开始计算 第一次 第二次
准备给已有实例前台权限的日志 2.237 秒 2.240 秒
Sending env to running instance 2.245 秒 2.250 秒
Sent env to running instance 2.359 秒 2.353 秒
窗口标题切换到目标文件 2.483 秒 2.464 秒

因此,这两次实验中:

  • 发出转交请求之前,已经消耗约 2.24 秒。
  • 发出请求到窗口标题切换,仅约 0.22~0.24 秒。
  • 主要等待已经发生在已有窗口收到打开请求之前。

2.4 直接连接已有实例

实验直接连接 Cursor 已有管道,先查询进程编号,再交替发送四次打开请求:

测试 IPC 调用返回 窗口标题切换
第一次 0.0838 秒 0.1989 秒
第二次 0.1965 秒 0.4012 秒
第三次 0.1497 秒 0.2372 秒
第四次 0.1279 秒 0.2453 秒

初次连接并调用 getMainProcessId 耗时约 0.0376 秒,返回 PID 28060,与已有实例一致。

这里的四次打开测试是在 Python 已启动、管道已连接的情况下进行的,不包含 Python 启动和建立连接的全部耗时。窗口标题变化是本次实验采用的可观察终点,不等于完成了画面渲染或窗口切到最前台的验证。

3. 直接连接已有实例的原理

3.1 找到已有 Cursor 的管道

用 PowerShell 枚举 Windows 命名管道:

[System.IO.Directory]::GetFiles('\\.\pipe\') |
    Where-Object { $_ -match 'main-sock$' }

举例而言,当时找到并连接的是:

\\.\pipe\22026640-3.22.7-main-sock

这个管道名称不能写成所有机器都通用的常量;Cursor 版本或用户数据目录不同,名称也可能不同。另外,main-sock 后缀也可能出现在其他基于 VS Code 的程序中,仅靠名称筛选还不足以确认目标是 Cursor。

3.2 和 Cursor 进行通信总览

实验中使用 probe.call 和 Cursor 通信。它是实验脚本自行编写的 RPC(远程过程调用)封装。

它完成:

→ 编码请求头和参数
→ 添加传输消息头
→ 写入命名管道
→ 读取完整响应
→ 解码并匹配请求编号
→ 返回结果或抛出错误

3.3 编码请求

具体代码如下,后面进行具体解释:

def call(self, name, args):
    request_id = self.seq
    self.seq += 1

    header = [100, request_id, "launch", name]
    payload = enc(header) + enc(args)

    self.send(payload)

    response_header, response_body = self.recv()

    if response_header != [201, request_id]:
        raise RuntimeError((response_header, response_body))

    return response_body

下面进行举例解释。首先当我们知道管道之后,想先调用 getMainProcessId,确认对方是已有 Cursor。具体方法就是发送一个 RPC 请求:

probe.call("getMainProcessId", [])

结合上面的代码,相当于发送了如下的请求:

header = [100, request_id, "launch", "getMainProcessId"]
args = []
字段 含义
100 调用一个有返回结果的方法
request_id 当前调用编号,与响应匹配
launch Cursor 已注册的通道
getMainProcessId 通道上的方法
args 参数列表

Cursor 接收请求之后,会在 launch 通道对应的服务上调用 getMainProcessId 方法,并返回结果。launch 是 Cursor 已有的通道;getMainProcessId 也是它已有的方法。

再比如,我们想让 Cursor 打开文件,具体方法就是发送一个 RPC 请求,具体内容是:

probe.call(
    "start",
    [
        {
            "_": [r"D:\Blog\done\index.md"],
            "reuse-window": True,
        },
        {},
    ],
)

相当于发送了如下的请求:

header = [100, request_id, "launch", "start"]
args = [
    {
        "_": ["D:\\Blog\\done\\index.md"],
        "reuse-window": True,
    },
    {},
]

相当于 Cursor 内部调用:

launch.start(
    {
        "_": ["D:\\Blog\\done\\index.md"],
        "reuse-window": true
    },
    {}
);

第一个参数是类似命令行解析后的参数对象;_ 是文件路径列表,reuse-window 要求复用窗口。第二个参数是调用方环境变量,实验中传入空对象 {}。这两个参数由 start(args, userEnv) 的方法签名决定。

这些方法来自本机 Cursor 的 main.js,并通过 VS Code 上游的 launchMainService.ts 核对:ILaunchMainService 声明了 start(args, userEnv) 和 getMainProcessId(),后者的实现返回主进程的 process.pid。launch 通道的获取和调用流程则位于主进程 main.ts。资料来源详见第 4 节。

3.4 编码为二进制

实际传输时,需要把上面的请求头和参数分别编码,再拼接成一个消息体,即 enc(header) + enc(args)。

实验用到的类型:

标记 类型 后续内容
0 JavaScript undefined 无
1 字符串 字节长度、UTF-8 内容
4 数组 元素个数、逐项编码
5 对象 JSON 字节长度、JSON 内容
6 整数 变长整数

例如字符串 launch:

01 06 6C 61 75 6E 63 68
│  │  └── UTF-8 字节 ──┘
│  └─ 长度为 6
└─ 类型为字符串

请求头 [100, 0, "launch", "start"]:

04 04                       数组,共 4 个元素
06 64                       整数 100
06 00                       整数 0
01 06 6C 61 75 6E 63 68     字符串 launch
01 05 73 74 61 72 74        字符串 start

上面的字节使用十六进制表示,例如 64 对应十进制整数 100。长度和整数采用变长编码:每字节贡献 7 位,最高位表示后面是否还有字节;例如 100 → 64,200 → C8 01。字符串长度按 UTF-8 字节数计算,中文字符串不能直接使用字符个数作为长度。

这些规则来自 ipc.ts 中的 DataType、serialize()、deserialize() 和变长整数读写函数,详见第 4.2 节。

3.5 传输层消息头

编码后,还需要按 Cursor/VS Code 这套 IPC 实现的传输格式,在消息体前添加传输层消息头。RPC 是一种调用方式,没有统一规定所有实现都必须使用下面的格式。

┌────────┬──────────┬──────────┬────────────┬──────────┐
│ 类型   │ 消息编号 │ 确认编号 │ 内容长度   │ RPC 内容 │
│ 1 字节 │ 4 字节   │ 4 字节   │ 4 字节     │ N 字节   │
└────────┴──────────┴──────────┴────────────┴──────────┘

消息头包含一个单字节类型字段,以及三个采用大端序的 4 字节整数,合计 13 字节。“内容长度”只计算后面的 RPC 消息体,不包含这 13 字节消息头。

def send(self, payload):
    transport_header = struct.pack(
        ">BIII",       # >BIII 表示一个单字节整数和三个大端序的 32 位整数。
        1,             # 普通消息
        0,             # 传输层消息编号
        0,             # 传输层确认编号
        len(payload),
    )

    self.pipe.write(transport_header + payload)

这里有两种编号:传输头中的消息编号、确认编号,以及 RPC 请求头中的 request_id。实验采用的普通 Protocol 会把前两者填为 0;request_id 仍逐次增加,用来匹配方法调用与响应。

这个格式来自 ipc.net.ts 中的 ProtocolConstants.HeaderLength、ProtocolWriter 和 Protocol.send(),详见第 4.2 节。

3.6 读取返回结果

管道是字节流,一次读取不保证恰好得到一条完整消息,所以需要维护缓冲区:

读取字节并追加到缓冲区
        ↓
缓冲区是否已有 13 字节传输头?
        ↓
取出内容长度 N
        ↓
是否已有完整的 13 + N 字节?
        ↓
取出 RPC 内容,解码响应头和返回值

假如成功响应,则返回结果为:

[201, request_id]  # 响应头
result            # 返回值

202、203 表示错误响应,不能当作成功处理。

call() 还需要检查响应编号与当前 request_id 一致。例如 [201, 0] 表示第 0 次调用成功,后面的值才是该方法的返回结果。协议类型和响应格式可在第 4.2 节所列的 ipc.ts 中核对。

3.7 连接初始化

第一次 call() 之前,还有连接初始化步骤:

打开 Cursor 命名管道
        ↓
发送连接身份 "main"
        ↓
接收服务端初始化消息 [200]
        ↓
发送客户端初始化消息 [200]
        ↓
调用 launch.getMainProcessId,核对实例
        ↓
调用 launch.start,打开文件
        ↓
关闭管道

这里的 "main" 是通信上下文名称;[200] 中的 200 是初始化消息类型,和 HTTP 状态码没有关系。初始化消息同样使用前面的编码和 13 字节传输头,并不是把字符串 "[200]" 直接写入管道。

这个顺序依据 ipc.ts 中 IPCClient、ChannelClient 和 ChannelServer 的实现还原。实验封装只处理当前这些初始化消息和串行调用,不是通用的并发 RPC 客户端。

4. 通信机制的资料来源

4.1 第一手依据:本机安装的 Cursor 代码

安装目录中读取过的文件:

  • C:\Program Files\cursor\resources\app\package.json:确认实验时安装版本为 3.22.7。
  • C:\Program Files\cursor\resources\app\out\main.js:包含主实例管道命名、claimInstance()、launch 通道和转交请求的实现。
  • C:\Program Files\cursor\resources\app\out\cli.js:普通 CLI 会派生 Cursor 进程。
  • C:\Program Files\cursor\resources\app\bin\cursor.cmd:Windows CLI 启动包装脚本。

本机 main.js 中实际存在这些标识和日志文字:

mainIPCHandle
claimInstance
Sending some foreground love to the running instance:
Sending env to running instance...
Sent env to running instance. Terminating...

按源码语义还原,转交的关键步骤类似于:

const client = await connect(mainIPCHandle, "main");
const launch = ProxyChannel.toService(
    client.getChannel("launch"),
    { disableMarshalling: true }
);

await windowsAllowSetForegroundWindow(launch, log);
await launch.start(args, process.env);

上面是便于阅读的语义还原,不是直接复制压缩后的本机代码,也不是可以独立运行的完整 JavaScript 程序。

4.2 VS Code 上游源码:用于核对结构和协议

  1. 主进程启动与已有实例转交:main.ts

    • 创建、初始化服务后调用 claimInstance()。
    • 连接已有实例并使用 launch 通道。
    • 处理 Windows 前台窗口权限。
  2. IPC 请求、响应和序列化:ipc.ts

    • 请求类型 100,初始化与响应类型 200、201 等。
    • serialize() / deserialize()。
    • 通道名、方法名和参数的编码方式。
    • IPCClient 的连接身份与初始化行为。
  3. IPC 传输封装:ipc.net.ts

    • 13 字节消息头。
    • 普通消息的收发。
  4. Node 管道连接与命名:node/ipc.net.ts

    • Windows 命名管道连接。
    • 根据用户数据路径和版本生成静态管道名的机制。
  5. 打开文件的方法与参数:launchMainService.ts

    • ILaunchMainService 声明了 start(args, userEnv) 和 getMainProcessId()。
    • start 将文件打开请求交给窗口服务,处理 reuse-window 等参数。
    • getMainProcessId() 返回主进程编号。

这些链接指向上游 main 分支,会随时间变化。关于本机 Cursor 的判断,以当时安装代码及实际调用结果为直接依据,不能仅凭最新 VS Code 源码推断所有 Cursor 版本行为相同。

5. 实验协议封装代码

下面保留实验所用协议封装的核心逻辑,便于理解和复现。它是教学用的实验代码,不是已完成的博客修复程序。

限制:只实现实验需要的类型与普通消息;未完成自动实例发现、多窗口选择、前台权限处理和失败回退。应传入经过核对的当前 Cursor 管道名。这里把 Python None 映射到协议 undefined,并没有实现对 JSON null 的独立表示。

import ctypes
import json
import msvcrt
import struct
import time
from ctypes import wintypes


kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
kernel32.PeekNamedPipe.argtypes = [
    wintypes.HANDLE,
    ctypes.c_void_p,
    wintypes.DWORD,
    ctypes.c_void_p,
    ctypes.POINTER(wintypes.DWORD),
    ctypes.c_void_p,
]
kernel32.PeekNamedPipe.restype = wintypes.BOOL


def vql(value):
    result = bytearray()
    while value >= 128:
        result.append((value & 127) | 128)
        value >>= 7
    result.append(value)
    return bytes(result)


def enc(value):
    if value is None:
        return b"\x00"  # 实验约定:表示 undefined。
    if isinstance(value, str):
        data = value.encode("utf-8")
        return b"\x01" + vql(len(data)) + data
    if type(value) is int:
        return b"\x06" + vql(value)
    if isinstance(value, list):
        return b"\x04" + vql(len(value)) + b"".join(map(enc, value))
    data = json.dumps(value, separators=(",", ":")).encode("utf-8")
    return b"\x05" + vql(len(data)) + data


def decode(data):
    position = 0

    def number():
        nonlocal position
        value = 0
        shift = 0
        while True:
            byte = data[position]
            position += 1
            value |= (byte & 127) << shift
            if not byte & 128:
                return value
            shift += 7

    def item():
        nonlocal position
        tag = data[position]
        position += 1
        if tag == 0:
            return None
        if tag == 6:
            return number()
        if tag == 4:
            return [item() for _ in range(number())]
        size = number()
        raw = data[position:position + size]
        position += size
        if tag == 5:
            return json.loads(raw)
        if tag == 1:
            return raw.decode("utf-8")
        if tag in (2, 3):
            return raw
        raise ValueError(f"Unsupported data tag: {tag}")

    header = item()
    body = item() if position < len(data) else None
    return header, body


class Probe:
    def __init__(self, pipe_name):
        self.pipe_name = pipe_name
        self.buffer = bytearray()
        self.seq = 0

    def __enter__(self):
        self.pipe = open(self.pipe_name, "r+b", buffering=0)
        self.handle = msvcrt.get_osfhandle(self.pipe.fileno())
        try:
            self.send(enc("main"))
            header, _body = self.recv()
            if header != [200]:
                raise RuntimeError(f"Unexpected initialization: {header}")
            self.send(enc([200]) + enc(None))
            return self
        except BaseException:
            self.pipe.close()
            raise

    def __exit__(self, *_):
        self.pipe.close()

    def send(self, payload):
        header = struct.pack(">BIII", 1, 0, 0, len(payload))
        self.pipe.write(header + payload)

    def recv(self):
        deadline = time.perf_counter() + 3
        while time.perf_counter() < deadline:
            if len(self.buffer) >= 13:
                size = struct.unpack_from(">I", self.buffer, 9)[0]
                if len(self.buffer) >= 13 + size:
                    payload = bytes(self.buffer[13:13 + size])
                    del self.buffer[:13 + size]
                    return decode(payload)

            available = wintypes.DWORD()
            ok = kernel32.PeekNamedPipe(
                self.handle, None, 0, None,
                ctypes.byref(available), None,
            )
            if not ok:
                raise ctypes.WinError(ctypes.get_last_error())
            if available.value:
                self.buffer.extend(self.pipe.read(available.value))
            else:
                time.sleep(0.002)

        raise TimeoutError("IPC response timed out")

    def call(self, name, args):
        request_id = self.seq
        self.seq += 1
        self.send(enc([100, request_id, "launch", name]) + enc(args))
        header, body = self.recv()
        if header != [201, request_id]:
            raise RuntimeError((header, body))
        return body

使用示例;运行前需要核对当前管道:

pipe_name = r"\\.\pipe\22026640-3.22.7-main-sock"

with Probe(pipe_name) as probe:
    print("Cursor PID:", probe.call("getMainProcessId", []))
    probe.call(
        "start",
        [
            {"_": [r"D:\Blog\done\index.md"], "reuse-window": True},
            {},
        ],
    )

这里的 start 返回只表示 RPC 调用完成,不能把返回时刻直接作为文件已显示的时刻。原实验另行观察已有窗口标题变化,才得到第 2 节的显示时间。

Comments

本文阅读 Loading 次 本站访问 Loading 次 访客 Loading 人