9.5 KiB
Remote Plugin 功能设计
更新时间:2026-10-27;目标项目:packages/plugin。
1. 数据面
| 领域 | Remote 接口 | Host authority |
|---|---|---|
| Harness Typert | harness.remote.* |
官方 Gateway endpoint 与事件关联 |
| CodeX | codex.app.* |
stdio App Server、Project / Thread 根目录 |
| Cursor / AGY / Pi / OpenCode / Claude / Hermes | agent.acp.* |
backend adapter、Host 会话/catalog |
| File Viewer | fileviewer.call |
provider 已授权的 root / locator |
| 开发预览 | loopback.call |
Host 本地端口白名单 |
业务都复用认证后的 Noise channel,但独立 capability、allowlist、RPC/event 和状态。 不得将 ACP 方法塞入 Harness 或 CodeX API,也不得引入平行的 Harness session/agent/workspace/permission 协议。 兼容版本和 carrier 选择见兼容说明;schema 与具体限额见协议。
2. 生命周期与模块
| 模块 | 职责 |
|---|---|
index.ts / config.ts |
Cordis 装配、配置解析、settings 兼容和热更新 |
service.ts / server-connection.ts |
Host、Control/Relay、每连接业务桥 |
identity-store.ts / server-credentials.ts |
按 Server origin/角色隔离身份、信任和凭据 |
harness-remote-bridge.ts |
官方 Harness 固定 allowlist、原生流与有界 transfer |
typert-gateway-switch.ts |
Local / Remote carrier 切换 |
client-runtime.ts / client.ts |
加密 capability、工作区类型、选择与内存 carrier |
workspace-bridge.ts / codex-workspace-bridge.ts |
有界只读文件和按会话隔离的 CodeX 工具 scope |
terminal-policy.ts |
Host 开关、设备归属、连接输入权 |
remote-terminal-controller.ts / remote-terminal-provider.ts |
CodeX / ACP 终端 owner、shell 探测、PTY、有界屏幕与订阅、retain/idle 和并发清理 |
loopback-host.ts / loopback-preview.ts |
Host 白名单请求与 Client 本机独立预览 origin |
codex/ |
App Server、authority、allowlist、虚拟 carrier、审批 |
acp/ |
后端注册表、gateway、独立工具、transfer、虚拟 carrier |
control-runtime.ts / control-route.ts / control-stream.ts |
本机设置、账号授权与 Host status SSE |
顶层 Plugin 激活不等待可选 Agent 后端。Host 捕获未经过 Remote switch 的本地 dispatcher,避免请求递归。 每条认证连接独立创建 bridge 和 pending/stream/transfer 状态,连接替换只清理其自己的旧状态。 ACP 后台初始化;关闭中清理启动进程,迟到的结果不得重新注册。
settings 通过 typeof settings.register === 'function' 分流旧注册表与新 Volatile entry 路径。
终端开关、loopback 保存和 Agent 后端配置热生效;只重载发生变化的后端,其待审批句柄和流失效,其他后端保留。
3. Harness bridge 与 Client carrier
Harness 仅使用官方 Typert invoke、stream、$events / $events/result;Host 与随包 Client 已移除 rc.2 ApiProxy。独立 VS Code 的历史兼容不属于此 Plugin carrier。
Plugin 仅负责认证、方法过滤、RPC 关联、流生命周期和传输,不读取 Harness 内部 SessionStore 或重建业务模型。
- Unary、respond、stream open/close 进入对应固定 allowlist。
- 图片 Prompt 和大 History / attachment 走已协商的有界 transfer,保持原生业务 envelope。
- 官方命令仅使用 Host 注册的目录与 handler;不允许反射任意 service。
- 官方 settings 写入限实时注册的命名空间,排除插件自身访问设置;credential 只写入有界引用,不返回秘密值。
- 禁止 native open/picker、动态 Cordis runtime/source、任意目标路径的附件访问和未知 endpoint。官方 Session 附件上传通过固定
remoteUploads/upload/fileUploads/upload处理并保留 receipt,不等同任意文件系统写入。官方workspace/create可创建缺失的 Harness 工作区目录;独立workspace.upload.v1只向 Host 验证的当前会话根上传文件,不接受 Client cwd/path,详见协议。
Client 先调用 harness.transport.describe。缺少能力发现或仅提供 ApiProxy 的 Host 被拒绝;按 capability、
版本 profile 和现有事件/history 归一化选择 carrier。不支持的组合在 mutation 或 UI target 切换前拒绝,不进行任意 wire format 翻译。
退出 Remote 才回到本地;断线结束旧流但保留所选 Host 的 authority,离线请求失败,不回落 Local。Harness 自动恢复时重新认证并通知官方 Connection 重开订阅;CodeX/ACP 虚拟工作区仍需手动重开,不重放 mutation。
4. 原生文件与终端
Harness 复用官方 workspaceFiles / officeToPdf 固定 allowlist,并保留 dsh-file-viewer 的 stat/readRange/list 桥。
CodeX codex:<threadId> 由 Host 解析成独立 Thread cwd scope,不当作 Harness agent ID。
共享工作区桥对路径、realpath、符号链接、读取大小与终端操作执行有界校验。
CodeX 工具使用原生 workspaceFiles/* / terminal/* 语义;不是放开 App Server 的 command/* 或 process/*。
ACP 工具使用独立 dsh/toolCall 与有 tool 参数的 stream,限编译期固定 endpoints;scope 必须与 backend/session 匹配。
客户端不能提交任意 cwd 来扩展工具 authority。
终端默认开启,Host 本地可立即关闭。固定设备归属与当前连接输入权;follow/retain、输出序号和关闭遵循原生语义。 断线保留可恢复的终端状态但不重放输入;领域关闭结束其进程。Host subprocess 服务可用时使用 PTY,否则回退 pipe; 共享桥由 Host xterm headless 保存有界屏幕并序列化重连快照,再跟随有序输出,不回放整段原始日志。
Android 图片最大 8 MiB、PDF 最大 16 MiB、Office 源文件最大 50 MiB;本地打包 PDF.js/xterm 渲染器,生成源文件不提交。 PDF 预览不执行脚本或打开外链,普通预览不创建明文文件缓存。Android 另有显式“保存到手机”操作,使用有界临时缓存并在完成或取消后清理,详见 Android 说明。真机与跨设备效果另行验收。
5. Loopback 预览
loopback.http-ws.v1 / loopback.call 只访问 127.0.0.1 的 Host 白名单端口;默认未授权。
Host 只出站连接,禁止 CONNECT、任意主机和通用 TCP 转发。
Desktop Client 随机本机监听端口承载独立 preview origin;Header 提供「预览服务」。
本机预览 URL 不能当作 Remote Web、Android 或 VS Code 的可用地址,复杂 HMR、Cookie/CSP 与网络条件仍需回归。
6. CodeX 与 ACP
CodeX 默认开启,通过 stdio App Server 访问固定方法。
Workspace authority 优先 project/list,缺少有效根目录才回退到 thread/list 已返回的绝对 cwd。
project/create 仅注册 Host 真实目录,realpath + 目录验证后由 App Server 返回 Project 扩展 authority。
新 Thread 子目录需词法路径与 realpath 双重校验;已有 Thread 操作也重新校验归属。
详见CodeX 投影。
ACP 当前实现 Cursor、Antigravity、Pi、OpenCode、Claude 和 Hermes adapter,不按命令名称选择后端,不对明确选中的不可用后端降级。
启用 capability 与实际 workspaceTypes.available 分离;Cursor/AGY 工作区 ID 分别生成,AGY 使用 antigravity:cwd:。
浏览器内存 carrier 只从 Host ACP 读取工作区、历史和图片,不依赖 Node、AGY 数据库或本机 transcript。
Host 的 AGY catalog/transcript 则执行项目归属、realpath、符号链接与迟到结果隔离。
AGY 图片仅 PNG/JPEG/WebP/GIF,每张 8 MiB、每次 4 张;专用 tmp 私有缓存总量 512 MiB、保留 24 小时,后续上传触发清理。 AGY 1.3.0 stream-json 接收 text,图片通过固定 add-dir 和 view_file 使用;历史只读当前会话引用且仍有效的缓存图片。 Cursor 保持文字 Prompt。AGY 模型目录来自安装 CLI,模型/effort 切换待 Host 确认,不推测默认或历史模型。 具体 capability 与选择时序见协议。
7. 身份、恢复与审批
Server membership、Host 本地信任、pinned identity、Noise transcript 与计数器校验全部通过后才开放业务桥。
凭据刷新使用跨进程目录锁,锁内重新读取凭据;握手拒绝最多刷新恢复一次。
4003 作为 CONNECTION_REPLACED 停止自动抢占;并行 Host 分别使用独立 DSH_HOME。
Harness 保持官方审批关联;CodeX / ACP 保持独立、按连接隔离的审批句柄。Remote 决策只允许单次允许或拒绝。 断线、后端关闭、撤销或替换使相关 stream、transfer、待审批状态失效,不自动重放 Prompt 或终端输入。 Android 对支持的后端重开 stream 并读取 history baseline;通用 pending call 恢复和长期稳定性仍按 TODO 跟踪。
Host status 通过本机 SSE 首帧完整快照、变化推送和空闲保活更新;旧 Host 不支持 SSE 时保留 unary status 降级。 连接建立进度与二维码登录属于独立交互流程,不等于常态 status 轮询。
8. 验证要求
测试预算用于 schema/版本、身份加密、授权、RPC、allowlist、权限隔离、事件顺序、恢复和 transport 状态机。 共享契约不在各 Client 重复测试;跨端 conformance 必须在真实目标 runtime 运行。 展示、布局、文案和静态说明以类型检查及必要人工烟测验证。 既有主链路结果与最新工具、AGY 模型选择、Windows、APK / 真机、复杂预览验收分开记录,见TODO。