ds-harness-remote-fast/docs/design/plugin/functional-design.md

120 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 | `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 选择见[兼容说明](../../compatibility.zh.md);schema 与具体限额见[协议](../../protocol.md)。
## 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、通用 attachment upload/download 和未知 endpoint。官方 `workspace/create` 可创建缺失的 Harness 工作区目录;独立 `workspace.upload.v1` 只向 Host 验证的当前会话根上传文件,不接受 Client cwd/path,详见[协议](../../protocol.md)。
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 说明](../../../apps/android/README.md)。真机与跨设备效果另行验收。
## 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 投影](../codex-session-history-projection-prompt.md)。
ACP 当前实现 Cursor、Antigravity、Pi、OpenCode 和 Claude 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](../../TODO.md)。