ZCode RS

ZCode 桌面端服务的 Rust 实现。不只是把 CLI 换成 Rust：Host（会话、调度、设置、扩展、终端、Git、远端连接等服务）和 agent runtime 都用 Rust 重写，并合并成一个进程。

Rust Host（apps/zcode-host/）：取代 Node Host。一个 App 只有一个 Host 进程，所有窗口接入它；runtime 在 Host 进程内运行，每个本地 workspace 一个实例，不再为每个 workspace 起 CLI 子进程。cron 与闲时任务的调度、设置写入、窗口间广播也从 Electron Main 收回到 Host。
Rust CLI（apps/zcode-cli-rust/）：agent runtime，取代 TypeScript CLI。可以单独运行（app-server --stdio、-p），也作为库嵌进 Host。
共用 crate（rust/）：两边都用的基础代码（进程树与回收、原子写、任务作用域、workspace 身份等）。

Host 与 CLI 在代码上保持隔离、可以分开编译，边界只有 App 协议（边界规格）。打包在一起的 zcode-host 二进制也能直接当 CLI 用（见下文）。

发布版的默认组合仍是 Node Host 加 TypeScript CLI。 Rust Host 只在开发构建中通过开关启用；切换默认之前要完成功能对齐、全平台验收与打包签名（规划见 rust-unified-host.md 第 12 节）。

和今天的 App 对比

整个桌面 App 的进程树（Electron Main、Renderer、GPU 与辅助进程、Host、runtime、scheduler、MCP 与工具进程），同一份 Electron 与界面的生产构建、本地 mock 模型，两种配置交错各测 3 次取中位数（2026-10-10 复测，a17ddb6，Apple M1 Max）。内存为 macOS physical footprint 合计，CPU 为单核百分比；CPU 采样时断开了测量用的调试连接。

指标	今天的 App（Node Host + TS CLI）	ZCode RS（Rust Host + 进程内 runtime）	变化
内存，空闲	939 MiB	436 MiB	−54%
内存，4 个 workspace	1.46 GiB	449 MiB	−70%
内存，8 个 workspace	2.31 GiB	515 MiB	−78%
每多一个 workspace	203 MiB	约 4 MiB	−98%
内存，4 个会话同时流式	1.73 GiB	688 MiB	−61%
CPU 合计，1 个会话流式	44.7%	37.9%	−15%
CPU 合计，4 个会话同时流式	54.8%	39.2%	−28%
冷启动到主界面可用	4.27 s	2.01 s	−53%
首条消息出现第一段	1.41 s	236 ms	−83%
新开 workspace 的第一段	977 ms	178 ms	−82%
退出（8 个 workspace，进程全部结束）	1.87 s	0.28 s	−85%

Electron 自身约 390–550 MiB，两种配置相同；差别来自 Node Host、scheduler 进程和每个 workspace 的 CLI 子进程。今天的 App 里每个 TS CLI 还各带一个约 80 MiB 的 node_repl MCP 进程，这次 Rust 一侧没有启动它；扣掉这部分，内存仍少 49–70%。
流式时 CPU 的差别全在 Host 一侧：4 个会话时 Node Host 加 TS CLI 子进程约 19 个点，Rust Host 加本地 WebSocket 经过的 network service 约 5 个点。剩下约 35 个点是两边相同的界面渲染（Renderer 与 GPU），不随 Host 变化。界面响应（长任务、切换会话延迟）没有差别。
首次测量里“流式 CPU 持平”主要是测量方式造成的：测量 harness 经调试协议连着界面时，Rust Host 的每个 WebSocket 帧都多出一条调试事件。复测在 CPU 采样时断开了它，并合入了 Rust 一侧的三项优化（同一方法下 Host 一侧再少约 2.5 个点，Rust Host 的空闲 CPU 从约 0.8% 降到约 0.1%）。
只代表开发检出（没有 ASAR 与签名）、macOS、mock 模型下的量级；测量时机器上有其他编译与磁盘扫描任务，时间类指标波动较大。方法、分进程数据、偏差与 Node Host + Rust CLI 的第三组对照见 App 级性能报告。

当前进度

阶段	内容	状态
U0	护栏（工具链、lints、nextest、cargo-deny、cargo-shear、CI）与共用 crate	第 1、2 步完成；net / sqlite / git 的抽取与测试 harness 未开始
U1	runtime 库化：嵌入入口、显式环境、同进程重启与多实例	完成
U2	Host 结构：`services` 拆成分层 crate、任务作用域（所有任务有归属、通道有界、不持锁跨 await）、Gateway（调用顺序、有界出站队列、断开原因）	完成；服务之间的拆环与显式组装未开始
U3	Host 进程内运行 runtime；Host 与 CLI 的结构隔离与 `cli` 入口；输入队列归一；工具进程回收	完成
U4	一个 App 一个 Host：多窗口、调度移入 Host、设置经 Host 写入、App 级崩溃重启	完成，桌面 E2E 通过
U5–U8	SSH / WSL / Docker 远端、Web、手机远控、切换默认与打包	未开始

验证范围：只在 macOS（Apple Silicon）上跑过桌面 E2E；Windows 与 Linux 只做了编译检查或 CI 构建。最近一次完全合并后的桌面 E2E：进程内 runtime 32 个场景通过，子进程链路（合并二进制的 cli 入口与独立 CLI）各 8 个通过，Node Host 路径 5 个通过。

通过 npm 使用 Rust runtime

通过 @mbears/zcode-rs 启动已安装的 ZCode，无需克隆仓库或自行编译 Rust。

已安装 ZCode 3.14.3；启动器会拒绝其他 App 版本。
已安装 Node.js 22.16.0 或更高版本（含 npm / npx）。
当前 npm 版本为 0.1.0，已发布 macOS Apple Silicon（ARM64） 和 Windows x64 平台包。

先完整退出 ZCode；Windows 若有托盘图标，也需要从托盘退出。然后在终端或 PowerShell 中执行：

# 检查 App 版本和当前平台的 Rust 包
npx @mbears/zcode-rs@0.1.0 app doctor

# 使用 Rust runtime 启动 ZCode
npx @mbears/zcode-rs@0.1.0 app launch

npm 会自动选择对应平台的预编译包。app launch 使用已安装 App 的界面，并为这次启动选择本地 Rust runtime；远端 SSH/WSL runtime 不随之切换。这里只替换 CLI，Host 仍是 App 内置的 Node Host；Rust Host 目前只能在开发构建中使用（见下文）。

**恢复原版：**完整退出这次启动的 ZCode，再从原来的应用图标、桌面或开始菜单快捷方式打开，即使用原版内置 CLI。启动器没有覆盖 App 安装文件或修改原快捷方式，无需重装或卸载 npm 包；回退不会撤销使用期间产生的会话和文件改动。

当前为测试版，Rust 功能范围和已知限制见下文及启动器说明。Windows x64 已通过原生编译、公开 npm 安装、exe 执行和启动器检查，尚未覆盖真实 Windows 桌面 UI 端到端测试；详见验收记录。

环境要求

Rust：工具链由 rust-toolchain.toml 固定（1.95.0），rustup 会自动安装。检查与测试脚本还需要 cargo-nextest、cargo-deny、cargo-shear，缺失时脚本会给出安装命令。
Node.js 与 pnpm：桌面联调、集成测试与仓库脚本需要，版本以 mise.toml 为准。
macOS、Linux 或 Windows。

首次准备仓库依赖：

pnpm install
pnpm build

在桌面 App 中使用 Rust Host

先构建 Host（缺省使用 debug 构建）：

cargo build --locked --manifest-path apps/zcode-host/Cargo.toml

然后以 Rust Host 启动桌面开发版：

ZCODE_DESKTOP_HOST=rust pnpm dev:desktop

使用 release 构建时，另设 ZCODE_RUST_HOST_BINARY=$PWD/apps/zcode-host/target/release/zcode-host。
runtime 缺省在 Host 进程内运行。需要对照子进程链路时，设 ZCODE_AGENT_SERVER_COMMAND=<zcode-cli-rust 可执行文件> 与 ZCODE_AGENT_SERVER_RUNTIME=zcode-cli-rust。
打包版本不读这个开关。不设 ZCODE_DESKTOP_HOST 时是今天发布的 Node Host。

只想在 Node Host 下换用 Rust CLI（不使用 Rust Host）时：

pnpm dev:desktop:zcode-cli-rust          # release 构建
pnpm dev:desktop:zcode-cli-rust --debug  # debug 构建

需要隔离实验数据或使用 fixture 模型时加 --config /absolute/path/model.json --data-dir /absolute/path/rust-experiment。

只运行 CLI

独立的 CLI 二进制：

cargo build --locked --manifest-path apps/zcode-cli-rust/Cargo.toml
apps/zcode-cli-rust/target/debug/zcode-cli-rust app-server --stdio \
  --cwd "$PWD" \
  --data-dir "$PWD/.zcode-runtime/rust"

合并的 Host 二进制也可以当 CLI 用，参数、输出与退出码和独立 CLI 完全相同：

apps/zcode-host/target/debug/zcode-host cli --version
apps/zcode-host/target/debug/zcode-host cli app-server --stdio --cwd "$PWD"
apps/zcode-host/target/debug/zcode-host cli -p "总结这个仓库"

把它链接或复制成名为 zcode-cli-rust 的文件后直接运行，效果相同。

App Server 的 stdout 只输出协议帧，诊断信息写入 stderr。
--cwd 指定缺省工作区，请求可以指向其他工作区。
--data-dir 只放 Rust 工具缓存与进程账本，默认 ~/.zcode/rust。
会话与 Node 共用数据库，默认 ~/.zcode/cli/db/db.sqlite，路径可由存储配置覆盖；只设置 --data-dir 不会隔离会话库。
直接运行时可以用 --config /absolute/path/model.json 指定单模型配置，并在环境变量中提供配置所需的 API key。接入桌面 App 时不需要，App 会提供 Provider Registry 与账号设置。

构建形态

形态	命令	内容
合并（缺省）	`cargo build --manifest-path apps/zcode-host/Cargo.toml -p zcode-host`	Host、进程内 runtime、`cli` 入口
只有 Host	`cargo build --manifest-path apps/zcode-host/Cargo.toml -p zcode-host --no-default-features`	不链接任何 CLI 代码；需要用 `ZCODE_AGENT_SERVER_COMMAND` 指定外部 CLI
只有 CLI	`cargo build --manifest-path apps/zcode-cli-rust/Cargo.toml`	独立的 `zcode-cli-rust`

三种形态都在 pnpm check:rust 中编译与检查。

检查与测试

pnpm check:rust            # 三个 workspace 的边界与分层检查、fmt、clippy（含三种构建形态）、cargo-deny、cargo-shear
pnpm test:rust             # 共用 crate（rust/）的测试
pnpm test:zcode-cli-rust   # CLI 的 Rust 测试，以及 Node 驱动的 App 集成测试
pnpm test:rust-host        # Host 的 Rust 测试、对拍样例漂移检查、TS 客户端连接真实二进制
pnpm e2e:rust-host         # 桌面 E2E（隔离的 Electron、mock 模型）

桌面 E2E 的常用参数：--scenario <名字>（可重复，场景在 scripts/rust-host/e2e/scenarios/）、--runtime child（子进程链路）、--host node（今天发布的 Node Host 路径）、--keep（保留日志与截图）。测试用 cargo nextest run --workspace：apps/zcode-cli-rust 的根 Cargo.toml 同时是一个 package，不加 --workspace 只处理根包。

Rust runtime 的功能对齐

截至 2026-09-28，Rust runtime 的以下能力已有实现及自动化或实机验收记录；勾选只表示对应范围完成，不代表全部平台、供应商和交互组合均已验收：

剩余 TODO：

MCP OAuth、legacy SSE 自动重连、真实服务器兼容矩阵与插件商店 UI 全流程
主代理记忆、目录级规则、完整 prompt/output style，以及附件和工具的剩余兼容差分
自动任务、Cron/OffPeak、浏览器/CUA、Node REPL；子代理 transcript artifact 与子树预算聚合
超大会话按需投影、产物回收与文件恢复边界；跨窗口、多会话、远端/手机和真实供应商完整验收
Windows 桌面端到端、Linux/macOS x64/Windows ARM64 原生验收与发行、SSH/WSL 部署、完整升级回退和性能发布门槛

动态工作流不在当前迁移范围，TUI 只保留子命令入口。分项证据与剩余边界见对齐清单、共用会话库规格和 npm 启动器验收记录。默认 runtime 仍为 TypeScript。

性能（只看 runtime）

只比较 runtime 本身（不含 Electron 与 Host）：2026-09-25 在同一台 Apple M1 Max 上使用本地 SSE fixture、8 回合单 Session、5 次交错测量的结果如下。Node.js 使用当次 CLI bundle，Rust 使用切换到 Node 会话库后的 release 二进制：

指标	Node.js	Rust
空闲 RSS	416 MiB	17.8 MiB
负载采样峰值 RSS	520 MiB	28.7 MiB
累计 CPU time	0.92 s	0.05 s
8 回合耗时	1.50 s	0.26 s

这组数据只代表当次本地 fixture 和构建形态，测量时机器存在其他高负载进程。大历史冷读取与驻留另有专项数据；真实供应商、MCP 工具负载、Windows/Linux 和移动远控的性能仍需单独验收。完整口径见性能报告；2026-09-23 报告保留为历史基线。

整个 App 的对比见上文“和今天的 App 对比”。Host 内嵌 runtime 与 Host 加 CLI 子进程两种链路的对比见 U3 报告。

上游同步记录

v3.14.3：同步上游 ZCode v3.14.3 更新，保留本仓库的 Rust CLI 迁移实现。

目录说明

目录	作用
`apps/zcode-cli-rust/src`	CLI 的组合根、嵌入入口与 CLI 入口
`apps/zcode-cli-rust/crates/protocol`、`core`、`core-api`、`domain`	App 协议、Session 核心与稳定接口
`apps/zcode-cli-rust/crates/model`、`tools`、`state`、`host`、`net`	模型、工具、存储、宿主与网络适配器
`apps/zcode-cli-rust/crates/app-server`、`delivery`	App Server 前端与 V4 投递
`apps/zcode-host/crates/zcode-host`、`host-core`、`gateway`	Host 二进制与入口分派、组装、连接层
`apps/zcode-host/crates/runtime-link`	Host 中唯一认识 runtime 的 crate：进程内与子进程两种链路
`apps/zcode-host/crates/base` … `remote`、`services`	分层的 Host 业务服务（分层见 rust-u2-host-structure.md）
`rust/crates/kit`、`async`、`proc`、`shared`	两边共用的基础 crate
`docs/specs/`	架构、迁移与验收规格
`docs/reports/`	验收与性能报告

整体规划与决策见 rust-unified-host.md，工程实践见 rust-engineering-practices.md，Host 与 CLI 的边界见 rust-host-cli-boundary.md，CLI 的完整能力与配置见 apps/zcode-cli-rust/README.md。

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.cargo		.cargo
.github/workflows		.github/workflows
.vscode		.vscode
apps		apps
config		config
docs		docs
harness/remote		harness/remote
packages		packages
patches		patches
public		public
rust		rust
scripts		scripts
third-party		third-party
.architecture-baseline.json		.architecture-baseline.json
.dockerignore		.dockerignore
.env.development		.env.development
.env.example		.env.example
.env.production		.env.production
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
.prettierignore		.prettierignore
.release-it.mjs		.release-it.mjs
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN.md		DESIGN.md
LICENSE		LICENSE
NOTICE.md		NOTICE.md
README.en.md		README.en.md
README.md		README.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md
architecture-policy.yaml		architecture-policy.yaml
clippy.toml		clippy.toml
deny.toml		deny.toml
knip.json		knip.json
mise.toml		mise.toml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
rust-toolchain.toml		rust-toolchain.toml
tsconfig.base.json		tsconfig.base.json

Navigation Menu

Repository navigation

About

Repository files navigation

ZCode RS

和今天的 App 对比

当前进度

通过 npm 使用 Rust runtime

环境要求

在桌面 App 中使用 Rust Host

只运行 CLI

构建形态

检查与测试

Rust runtime 的功能对齐

性能（只看 runtime）

上游同步记录

目录说明

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ZCode RS

和今天的 App 对比

当前进度

通过 npm 使用 Rust runtime

环境要求

在桌面 App 中使用 Rust Host

只运行 CLI

构建形态

检查与测试

Rust runtime 的功能对齐

性能（只看 runtime）

上游同步记录

目录说明

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages