如何通过本地端点注册表让外部客户端连接正在运行的 VS Code Agent Host

如何通过本地端点注册表让外部客户端连接正在运行的 VS Code Agent Host【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode如果你写了一个同机运行的本地进程工具、脚本或桥接服务希望它作为外部客户端接入正在运行的 VS Code Agent Host 并使用 Agent Host ProtocolAHPVS Code 提供了一条官方路径本地端点注册表local endpoint registry。每个本机上运行的 agent host 进程——VS Code 编辑器自己的 utility 进程、其他编辑器窗口以及独立的code agent hostCLI——都会在注册表中发布一条包含端点地址和连接令牌的条目你的客户端只需按规则读出条目、带上令牌完成 WebSocket 升级、再执行 AHP 的initialize协商即可接入。协议规范见 LOCAL_ENDPOINT.md。适用前提文档明确给出的边界外部客户端必须与 agent host 以同一用户运行端点暴露对象是“other processes running as the same user”注册表条目是可选的如果 VS Code 无法准备或发布外部端点它会记录错误并继续在内部 MessagePort 传输上运行 agent host此时注册表里读不到该编辑器实例端点形态取决于宿主类型编辑器editor发布 Unix domain socketmacOS/Linux或命名管道Windows独立 CLIstandalone发布 TCP 监听。注册表位置与条目文件格式注册表是“每个实例一个条目文件”的目录结构userDataPath/agent-host/local-endpoint/entries/identity.json其中identity是${type}\0${pid}\0${instanceId}NUL 分隔这个 UTF-8 字符串的小写 SHA-256 十六进制摘要因此文件名跨语言、路径安全且抗碰撞读取方通过枚举该目录发现所有存活的本地 agent host。userDataPath是当前 VS Code 用户数据目录其值取决于产品质量Stable/Insiders和是否传了--user-data-dir文档明确要求实现方解析当前实际使用的用户数据目录而不是假设默认的 Stable 或 Insiders 位置。每个条目文件是一个 JSON 对象当前 schema 版本为2。以下是文档中的示例示例结果字段值不要当作固定预期{ schemaVersion: 2, type: editor, pid: 12345, instanceId: base64url-instance-id, protocolVersion: 0.7.0, connectionToken: base64url-bearer-token, endpoint: { type: socket, path: \\\\.\\pipe\\vscode-agent-host-... } }各字段含义来自文档的字段表字段说明schemaVersion元数据 schema 版本。客户端必须忽略自己不理解版本的条目而不是拒绝整个文件type端点所有者进程类型editorVS Code utility 进程或standalonecode agent hostCLI。它只影响客户端的所有权/默认选择策略不是信任度指标pid端点所属进程的 PIDinstanceId随机标识用于区分同一进程的前后继端点所有者与type、pid一起构成条目身份因为 PID 可能被系统复用protocolVersionhost 支持的 AHP 版本供发现与诊断使用不能替代正常的 AHPinitialize协商connectionTokenWebSocket 升级阶段必需的随机 bearer 令牌endpoint区分联合体socket 端点为{ type: socket, path: string }编辑器当前使用TCP 端点为{ type: tcp, host: string, port: number }独立 CLI 使用quality/tunnelName可选standalone 端点的产品质量 / 隧道名不属于条目身份目录权限注册表根目录和entries/目录仅当前用户可访问POSIX 上 mode0700Windows 上是 owner-only ACL条目文件 mode0600。条目文件只在端点开始监听且协议处理器安装完成后才被原子写入。旧版构建写的是单文件数组userDataPath/agent-host/local-endpoint/metadata.json。读取方仍会只读合并该遗留文件中的有效条目使升级前启动的 host 依然可被发现新条目文件在(type, pid, instanceId)冲突时获胜遗留条目会随旧进程退出被 PID 存活检查自然清掉。用code agent endpoints一次性读出全部活跃端点手写客户端不必自己解析注册表目录Rust CLI 提供了机器可读命令code agent endpoints实现见 agent_endpoints.rs。它向 stdout 恰好输出一个 JSON 文档包含解析后的userDataPath和全部存活端点——并且完整保留connectionToken目的正是交给可信的已认证调用方例如通过 SSH 桥接进来的工具自己去拨号code agent endpoints # 如果 agent host 使用了自定义用户数据目录 code agent endpoints --user-data-dir 你的用户数据目录输出文档形状如下以下取自 CLI 测试属于文档示例{ userDataPath: 解析后的用户数据目录, endpoints: [ { schemaVersion: 2, type: standalone, pid: 42, instanceId: instance-a, protocolVersion: 0.1.0, connectionToken: 令牌, endpoint: { type: tcp, host: 127.0.0.1, port: 8080 } } ] }注意两点判定语义源码注释明确给出endpoints为空数组是合法且有意义的答案表示“当前没有 agent host 在运行”与“注册表读取失败”是两回事命令不会因为没有端点而报错。如果你的客户端是自己实现读取逻辑不走 CLI共享的解析器/模型在 agentHostEndpointRegistry.ts编辑器侧发布与读取在 localAgentHostMetadata.tsRust 侧对应实现是 agent_host_registry.rs文档要求每一处本地读取/写入都用它做一致的校验。按客户端规则校验与去重条目文档要求客户端把每个条目和每个字段都当作不可信输入处理规则如下缺失一条都会导致选到坏端点或误删有效条目逐条做结构校验坏条目单独丢弃不要让整个读取失败忽略schemaVersion不受支持的条目例如版本1的旧扁平格式当前读取方直接忽略在可以做 PID 存活检查时忽略确认已死的 PID 的条目按(type, pid, instanceId)去重永远不要自行重建endpoint值——总是原样使用发布出来的地址。端点路径规律仅供识别不能用来拼路径Windows 上编辑器的endpoint.path是\\.\pipe\vscode-agent-host-user-data-hash-instance-idmacOS/Linux 上是os.tmpdir()/vscode-ah-user-data-hash/instance-id.sock短目录是为了避开 Unix socket 路径长度限制。CLI 的活跃端点枚举list_live_endpoints在 PID 存活检查之外还会做可达性验证对 socket 端点尝试建立连接、对 TCP 端点连接host:port2 秒内未接受连接即判定不可达并过滤该条目不会删除其注册表文件。你的客户端如果要在重连期间判断哪个条目仍然可用可以参考这一思路但文档没有规定统一的客户端侧重试策略。使用令牌连接端点拿到条目后按 LOCAL_ENDPOINT.md 的“Connecting”一节操作对 socket 端点向endpoint.path发起 WebSocket 连接对 TCP 端点连接host:port后同样走 WebSocket 帧在升级请求上通过 VS Code 标准的 connection-token 查询参数携带令牌?tknconnectionTokenWebSocket 升级成功后发送正常的 AHPinitialize请求完成协商。条目里的protocolVersion只用于发现与诊断不能替代这一步协商缺少令牌或令牌错误的连接会在 WebSocket 升级阶段被以HTTP 403拒绝——这是判断令牌是否正确、端点是否要求认证的直接信号。下面的片段是把上面规则组合起来的示意变量来自条目 JSON按你读到的条目值替换ws为任意 WebSocket 客户端库// entry 是从注册表条目解析出的单个对象 const url entry.endpoint.type socket ? ws://${entry.endpoint.path.replace(/\\/g, /)}?tkn${encodeURIComponent(entry.connectionToken)} : ws://${entry.endpoint.host}:${entry.endpoint.port}?tkn${encodeURIComponent(entry.connectionToken)}; const socket new WebSocket(url); socket.onopen () { // 升级成功后发送 AHP initialize 请求完成协商字段按 AHP 规范填写 }; socket.onerror (e) { // 升级阶段被拒如 403会走到这里 };文档只规定了?tkn这一携带方式未指定具体语言绑定如果你的客户端从code agent endpoints的输出中取userDataPath还可以直接用它去启动code agent host --user-data-dir 该目录不需要自行重实现用户数据目录解析规则。验证结果与需要处理的情况接入成功WebSocket 升级未被拒绝没有 403且 AHPinitialize协商完成令牌问题升级阶段收到 HTTP 403说明缺少tkn参数或令牌与条目不符。standalone host 若以--without-connection-token启动其注册表条目中connectionToken为空此时不存在令牌校验条目缺失条目是可选的VS Code 发布外部端点失败时会继续用内部 MessagePort 运行客户端会看到缺失条目陈旧条目进程退出后其条目会被 PID 存活检查清掉读取日志中会出现Pruning stale local endpoint registry entry: type PID pid (instance instanceId) is no longer running一类信息重连健壮性文档明确要求客户端处理“条目缺失、陈旧 PID、端点关闭、注册表在重连期间发生变化”这几种情况多条目选择独立 CLI 选择器只考虑standalone条目editor条目归运行的 VS Code 窗口所有CLI 不会替用户去选、替换或杀编辑器实例多个存活 standalone 条目时选最近发布的并建议用--address消歧你自己的客户端可按type区分所有权策略但不要把它当信任等级用。可选分支没有存活 standalone host 时如何启动或替换如果注册表里只有editor条目、或你想为自己的工具准备一个专用 host可用code agent host实现见 agent_host.rs。它默认以后台守护进程方式启动 supervisor 并绑定 TCP 监听、发布 standalone 注册表条目重复执行时若已有存活 supervisor 且配置兼容只打印复用横幅含端口和?tkn令牌并不启动新进程。常用参数code agent host # 默认绑定 127.0.0.1随机端口 code agent host --host 0.0.0.0 --port 8080 code agent host --connection-token-file 文件 # 从文件读取令牌 code agent host --without-connection-token # 不启用令牌 code agent host --foreground # 前台运行日志留在终端两个注意点--replace会先杀掉现有 supervisor 进程树并删除其注册表条目再启动新实例只在确认要替换时加若请求的--host/--port/令牌配置与正在运行的 supervisor 冲突且未加--replace命令会打印冲突说明并以状态码 2 退出提示用code agent kill停止或传--replace接管。日常巡检和管理用横幅里给出的入口code agent ps与code agent kill。客户端侧的完整协议细节注册表、发布、读取、清理可以分别回到 LOCAL_ENDPOINT.md、agentHostEndpointRegistry.ts 与 agent_host_registry.rs 核对TS 与 Rust 两端的 schema、哈希编码和身份命名是刻意保持逐字节一致的字段改名或删除必须在两个语言实现间协同修改。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考