Wiki AI

ZCode Server 与远程工作区

3分钟阅读

ZCode 有两个分工明确的服务包：@zcode/server（HTTP/WS + 远程连接库）与 @zcode/server-cli（独立可安装守护二进制 + Supervisor/Core 双层进程）。

@zcode/server

导出入口 server/src/index.ts 仅 createHttpServer；另有 ./stdio、./remote 子入口。

HTTP 入口

  • entry-http.ts：materialize 内置 Provider Config → createLocalServices()（环境变量 PORT、ZCODE_SERVER_HOST、ZCODE_WEB_STATIC_ROOT、ZCODE_SERVER_AUTH_TOKEN）→ createHttpServer()。有 token 时启用 providerProvisioningTargetEnabled。
  • http.ts（493 行）：Hono + @hono/node-ws。关键路由：
    • GET /ws：永远是 web-remote-replayable terminal-client（忽略旧 mode header）
    • GET /ws/host：必须带 ZCODE_RPC_HOST_CAPABILITY_HEADER 且被 hostCapabilities.consume() 一次性消费，才升级为 desktop-continuous trusted relay
    • /api/server-info、POST /api/rpc-host-capability（签发一次性 capability）、POST /api/connect-remote、POST /api/bots/:provider[/:botId]（webhook 回调）、GET /ws/remote/:id
    • 静态资源 SPA fallback（resolveStaticFile 防目录穿越）
  • 鉴权 cookie zcode_lite_token，只保护 /ws* 与 /api/*。
  • setupChannelServer() 按 clientMode 建 connection scope，并对非 trusted host 屏蔽 IProviderProvisioningTargetService。

stdio 入口

  • entry-stdio.ts：stdio 模式下 stdout 只承载 RPC 帧，启动时把 console.* 全部重定向到 stderr（否则污染协议流导致远程调用永久 pending）。
  • 握手：先写 {type:"zcode-hello"}，再等 hello-ack（10s 超时，schema 校验，剩余字节 unshift 回 stdin）。
  • stdio.ts：把 process.stdin/stdout 包成 ISocket，套 SocketProtocol + ChannelServer("stdio")；创建 createZCodeAgentConnectionScope({clientMode:"desktop-continuous", role:"trusted-host-relay"})。

远程连接与部署（src/remote/，40 文件）

backend.ts / create-backend.ts、ssh-backend.ts、wsl-backend.ts、docker-backend.ts、connect.ts、handshake.ts、deploy.ts、zcodeAgentDeploy.ts / zcodeAgentDevDeploy.ts、remoteAssetCache.ts（64K）、remoteAssetInstaller.ts（44K）、remoteDeployLock.ts。

支持 SSH（pooled）、WSL（TTL + running-task protection）、Docker/Server（dedicated）。remote identity 由 packages/shared/src/remote-workspace-identity.ts 统一构造，业务代码不得手写格式。详见 architecture。

@zcode/server-cli（Supervisor / Core 双层）

bin 为 zcode。入口 main.ts → cli.ts 的 runServerCli（:75）。命令：serve / status / stop / restart / update / uninstall，未知命令委托 legacy zcode.cjs。

Supervisor（守护/父进程）

supervisor/supervisor.ts:42 的 Supervisor：

  • 持有 DataRootLock（单实例）、CrashBudget（崩溃退避）、ReleaseManager、control server（createControlServer）
  • fork core 子进程，维护 generation / release / 状态机（stopped|starting|ready|stop-failed|crash-loop-stopped）
  • 处理 ping/status/stop/restart/prepare-update/apply-update/prepare-uninstall/confirm-uninstall

Core（工作子进程）

server-core/core.ts：createLocalServices({serviceAuthorityMode:"standalone-server"}) + createCoreHttpServer，通过 process.send 向 Supervisor 上报 ready / task-activity / heartbeat。父进程断连由 parentDisconnect.ts 触发优雅退出。

  • serve --daemon 会注册 OS 服务（platform/serviceManager.ts），失败时（显式 opt-out 除外）只允许 detached fallback。
  • uninstall 双重 DELETE 确认 + validateServerInstallOwnership 归属校验 + allowlist 清理。
  • 独立远端服务核心仅接受本机回环监听地址，未提供与外部账号同等的鉴权（见 NOTICE.md）。

其余子模块：runtime/（lock、releaseManager、releaseInstaller、releaseDownload、stableLauncher、updateReadiness、startupRecovery、manifest、componentCache、installationOwnership）、ipc/（control client/server + framing）、packaging/、supervisor/crashBudget。

远程一条 sendText 的路径

Renderer（@zcode/rpc / MessagePort）
  → Window Host（远程 @zcode/rpc Service 调用 / SSH stdio 或 WebSocket）
  → zcode-server（ZCode Protocol JSON, method="v4/command" / 子进程 stdio）
  → 远端 zcode-cli（CommandInbox 裁决并执行 sendText）

同一条 V4 命令可被多次”调用”承载；命令 ≠ 调用。详见 zcode-protocol。

相关页面

关系图谱

反向链接