桌面、Web 与命令行启动方式
本页说明 ZCode 仓库中桌面端、Web 端和命令行端的启动入口、脚本编排方式及其已确认的平台边界。内容以仓库根 package.json、apps/zcode-cli/package.json 与仓库工程约束为依据；具体 Electron 窗口实现、Web 开发服务器实现和 CLI 业务入口不在本页已读取的源码范围内，因此不对未验证的内部细节作推断。
Purpose and Scope
本页覆盖三类启动方式：
- 桌面端：根脚本
dev:desktop及其test、prod、bytecode、remote-prod变体。 - Web 端：根脚本
dev:web，它并行启动@zcode/server与@zcode/web。 - 命令行端：
apps/zcode-cli工作区中的dev、cli:dev、构建和 SEA（Single Executable Application）相关脚本。
本页不展开桌面窗口生命周期、Web 路由、Agent 协议、CLI 命令实现或发布流程；这些属于各自运行时或业务模块的独立主题。仓库约束明确将 packages/desktop、packages/web、packages/server 和 apps/zcode-cli 作为不同边界，因而这里重点记录“如何启动”以及启动脚本如何把控制权交给对应包。
Overview
启动方式采用根工作区脚本作为统一入口，再转发到具体 package 或 Node 脚本：
- 根
package.json通过pnpmfilter 调度 Web server、Web client 和 desktop package。 - 桌面端先执行
scripts/dev-desktop-env.mjs，并把运行模式作为参数传入；这说明桌面开发环境准备和实际桌面包启动之间存在一个显式编排层。 - Web 端使用
concurrently -k并行运行 server 与 web 两个进程；-k表明其中一个并发命令结束时终止其他命令，避免开发环境留下孤立进程。 - CLI 端在
apps/zcode-cli内通过@zcode/clifilter 转发开发、构建与 SEA 打包操作。CLI package 声明 Node24.14.0，根仓库声明 Node>=24.0.0，因此命令行启动依赖 Node 24 系列运行时。
Architecture
架构图中的关系均来自已读取的脚本：根桌面脚本调用环境准备脚本，根 Web 脚本分别 filter 到 server 和 web，根 SEA 脚本进入 apps/zcode-cli 再 filter 到 CLI 包。当前证据没有显示 dev-desktop-env.mjs 如何创建进程，也没有显示 @zcode/cli 的具体入口文件，因此这两部分应继续通过各自 package 的源码页面调查。
启动入口总览
| 场景 | 推荐入口 | 实际编排 | 已确认的用途 |
|---|---|---|---|
| 桌面开发 | pnpm dev:desktop | node scripts/dev-desktop-env.mjs production | 使用 production 模式准备桌面开发环境 |
| 桌面测试 | pnpm dev:desktop:test | node scripts/dev-desktop-env.mjs test | 使用 test 模式准备桌面环境 |
| 桌面字节码模式 | pnpm dev:desktop:bytecode | node scripts/dev-desktop-env.mjs production --agent-bytecode | production 模式并启用 --agent-bytecode |
| 桌面远程生产模式 | pnpm dev:desktop:remote-prod | node scripts/dev-desktop-remote-prod.mjs | 交给远程生产脚本处理 |
| Web 开发 | pnpm dev:web | concurrently -k 并行启动 server 与 web | 同时运行 Web 服务端和客户端 |
| CLI 开发 | pnpm --dir apps/zcode-cli dev | 转发到 @zcode/cli dev | 启动 CLI 开发流程 |
| CLI SEA 构建 | pnpm build:sea | 进入 apps/zcode-cli 执行 build:sea | 构建 CLI 的 SEA 产物 |
桌面、Web 和 CLI 的运行时内部行为未在本次读取范围内验证；表格只记录 package script 已明确表达的调度关系。
根工作区启动编排
桌面端：模式参数由环境脚本集中处理
根脚本没有直接调用 @zcode/desktop 的 package script，而是统一进入 scripts/dev-desktop-env.mjs，再传入模式参数。这种设计把“选择运行模式”和“桌面环境准备”集中在一个 Node 编排脚本中，避免每个 shell 命令重复实现环境设置。
1"dev:desktop": "pnpm run dev:desktop:prod",
2"dev:desktop:test": "node scripts/dev-desktop-env.mjs test",
3"dev:desktop:prod": "node scripts/dev-desktop-env.mjs production",
4"dev:desktop:bytecode": "node scripts/dev-desktop-env.mjs production --agent-bytecode",
5"dev:desktop:remote-prod": "node scripts/dev-desktop-remote-prod.mjs"Source: package.json
dev:desktop 是 dev:desktop:prod 的别名，因此默认桌面启动路径最终使用 production 参数。测试、字节码和远程生产分别有独立入口；不能从已读取的 JSON 推断这些模式之间更深层的行为，例如是否使用不同端口、是否启用不同资源或是否连接远程服务。
Web 端：两个进程的并发生命周期
Web 启动脚本使用 concurrently -k，并把两个 filter 命令分别命名为 server 与 web，同时用颜色区分输出。这为本地开发提供一个单命令入口，同时保持 server 和 web 的进程边界。
"dev:web": "concurrently -k -n server,web -c blue,green \"pnpm --filter @zcode/server dev\" \"pnpm --filter @zcode/web dev\"",
"dev:server": "pnpm --filter @zcode/server dev"Source: package.json
dev:server 是只启动 server 的补充入口，适用于只需要后端开发进程的场景。dev:web 则把 server 和 web 绑定到同一个并发会话；由于使用 -k，任一进程退出时其余进程会被终止，这是开发环境的进程清理语义，而不是生产部署拓扑。
CLI 端：工作区级转发
CLI 有两层 package script。仓库根目录的 build:sea 进入 apps/zcode-cli，而 CLI 工作区再将操作 filter 到 @zcode/cli。因此从根目录和从 CLI 子目录执行的入口不同，但最终目标包相同。
"build:sea": "pnpm --dir apps/zcode-cli build:sea",
"release:cli": "pnpm --dir apps/zcode-cli run release",
"release:cli:dry": "pnpm --dir apps/zcode-cli run release:dry"Source: package.json
1"cli:dev": "pnpm --filter @zcode/cli dev",
2"dev": "pnpm --filter @zcode/cli dev",
3"cli:build": "pnpm --filter @zcode/cli build",
4"cli:upload-sea": "pnpm --filter @zcode/cli upload:sea",
5"sea": "pnpm --filter @zcode/cli sea"Source: package.json
这里的 dev 与 cli:dev 都指向同一个 @zcode/cli dev，属于同义入口；cli:build、sea 和 cli:upload-sea 则分别表达普通构建、SEA 操作和 SEA 上传操作。上传和发布的认证、产物位置及网络行为未在已读取文件中出现。
Core Flow
桌面启动流程
Sources:
这里的最后一步是仓库结构约束所支持的边界描述：packages/desktop 是 Electron main、host、renderer 所在包。但本次没有读取该包的 package.json 或脚本实现，因此“准备并启动”的具体子命令不应进一步展开。
Web 启动流程
Source: package.json
流程中的两个分支是同级并发命令，不表示 server 调用 web 或 web 调用 server；当前证据只证明它们由 concurrently 同时调度。-k 的存在意味着开发会话结束时并发组会被清理，具体退出码传播规则未在源码中验证。
CLI 启动流程
Sources:
Configuration Options
启动方式本身没有在已读取的文件中声明端口、环境变量或配置文件键。可以确认的运行前提如下：
| 项目 | 类型 | 默认/约束 | 说明 |
|---|---|---|---|
| 根包 Node 版本 | runtime constraint | >=24.0.0 | 根 package.json 的 engines 约束 |
| CLI Node 版本 | runtime constraint | 24.14.0 | apps/zcode-cli/package.json 的 engines 约束，比根包更具体 |
| 包管理器 | tool/version | pnpm@10.33.2 | 根包和 CLI package 都声明相同版本 |
| 桌面默认模式 | script alias | production | dev:desktop 转发到 dev:desktop:prod |
| Web 进程组 | process group | server + web | 由 concurrently -k 同时调度 |
根仓库的 Node 约束和包管理器声明如下：
1"engines": {
2 "node": ">=24.0.0"
3},
4"packageManager": "pnpm@10.33.2"Source: package.json
CLI package 的更具体约束如下：
1"engines": {
2 "node": "24.14.0"
3},
4"packageManager": "pnpm@10.33.2"Source: apps/zcode-cli/package.json
API Reference
本页的“API”是 package script 命令，而不是 HTTP 或 TypeScript 函数 API。已确认的命令如下：
| 命令 | 参数/输入 | 行为 | 返回/产物 |
|---|---|---|---|
pnpm dev:desktop | 无 | 转发到 dev:desktop:prod | 桌面开发会话；具体产物未验证 |
pnpm dev:desktop:test | 无 | 调用环境脚本并传入 test | 测试模式桌面会话 |
pnpm dev:desktop:bytecode | 无 | 传入 production --agent-bytecode | 字节码模式桌面会话 |
pnpm dev:web | 无 | 并发启动 server 和 web | 两个开发进程组成的会话 |
pnpm --dir apps/zcode-cli dev | 无 | 进入 CLI 工作区并运行其 dev | @zcode/cli 开发会话 |
pnpm build:sea | 无 | 进入 CLI 工作区执行 SEA 构建 | SEA 构建过程；具体文件名未验证 |
未读取到脚本实现或命令行参数解析代码，因此无法可靠列出端口、退出码、异常类型、HTTP 响应或 CLI 子命令参数。
失败模式、边界与并发注意事项
已确认的失败边界
- Node 版本不满足：根仓库要求 Node
>=24.0.0，CLI package 进一步声明24.14.0。使用更旧 Node 版本时，安装器或脚本可能拒绝执行；本页不推断实际报错文本。 - CLI 工作区路径错误：根入口依赖
--dir apps/zcode-cli。如果从不存在该目录的检出状态执行，CLI 转发自然无法成立；仓库中未提供替代路径。 - Web 并发组退出：
dev:web使用concurrently -k。server 或 web 任一开发进程退出后，并发组会结束其他进程，避免孤立开发服务，但也意味着单个子进程故障会终止整个 Web 开发会话。 - 桌面模式选择错误：桌面端的模式通过参数传给
dev-desktop-env.mjs。test、production和--agent-bytecode是脚本中明确存在的入口组合；不应把未声明的模式参数当作受支持配置。
并发与状态边界
Web 启动是进程级并发，而不是共享内存并发：server 和 web 由两个独立 filter 命令运行。仓库工程约束还要求 Desktop Main 负责窗口、原生操作、进程调度和消息转发，不承载 task/session 业务状态；因此启动方式文档不应把桌面进程调度误写成业务状态所有者。
桌面端另有一个已明确的运行时边界：Desktop 通过 stdio 与 Agent 通信，且每个窗口使用一个 window-scoped Local Host。该信息属于进程与协议层背景；具体启动后握手、重连和会话恢复机制需要阅读对应实现后再补充。
性能与运维说明
- Web 本地启动：两个服务并行启动，减少手工启动步骤；代价是日志、退出码和故障定位需要区分
server与web两个命令名。 - 桌面环境准备：所有非远程桌面模式都经过
dev-desktop-env.mjs，便于集中管理环境差异。其具体缓存、编译或资源准备成本未在本次读取范围内确认。 - CLI 打包：根脚本提供
build:sea和build:sea:all；后者会先执行pnpm install，再进入 CLI 工作区构建，适合需要确保依赖已安装的完整流程，但安装耗时与网络要求取决于 pnpm 环境。
"build:sea": "pnpm --dir apps/zcode-cli build:sea",
"build:sea:all": "pnpm install && pnpm --dir apps/zcode-cli build:sea"Source: package.json
Extension Points
新增启动模式时，优先沿用现有的“根入口 → 编排脚本或工作区 → 目标 package”结构：
- 桌面模式应增加明确的根 script，并在环境脚本中表达模式参数；不要在多个 shell 命令中复制环境准备逻辑。
- Web 侧应保留 server 与 web 的独立 package 边界；如果增加第三个进程，应明确它是否加入
concurrently -k的同一生命周期组。 - CLI 侧应同时考虑根目录转发入口和
apps/zcode-cli内的 package script，保持@zcode/cli为实际目标包。 - 涉及 Desktop、Web、本地和远程环境差异时，应遵守仓库约束要求的依赖注入和平台服务边界，而不是让 UI 直接依赖平台具体实现。
这些是基于现有脚本结构和 AGENTS.md 约束得出的扩展规则；具体新增代码仍需读取目标 package 的当前实现并补充对应测试。
测试与验证
本次读取到的文件没有包含启动方式测试文件，也没有显示统一的启动 smoke test。仓库约束要求测试入口以目标 package 的 package.json 和实际测试文件为准，因此不能据此声称桌面、Web 或 CLI 启动已经有特定测试覆盖。
在执行或修改启动脚本前，仓库约束列出的通用验证入口包括 pnpm typecheck、pnpm lint 与 pnpm architecture:check --changed；这些是工程要求，不等同于本页已执行过验证。