ZCode GUI:本地 Web 与官方远控浏览器派发(过渡路径)
需要减少逐步浏览器操作、封装定位/等待/回读,或评估headless与Orca接入时,读取浏览器自动化操作映射。实验驱动已实现并通过定向测试、无头草稿及已有回合读取;脚本实际新模型投递与自动续聊仍未验收,Orca专用适配器尚未实现。
1. 选择入口
用户明确选择 ZCode 桌面、GUI、本地 Web 或官方远控时使用本页。ZCode只有CLI与GUI两种模式;GUI默认localhost Web,无须先开启桌面远控,官方远控是同一模式的备选连接。控制已在桌面运行的具体会话时,继续核对原宿主/session归属,不因功能相同就把两个进程当作同一任务。沿用会话中已有授权,不为正常任务交接重复询问许可;不把派发授权扩大为账号切换、安装代理或修改全局设置。
| 入口 | 控制对象 | 派发与完成来源 |
|---|---|---|
| 独立 CLI | Orca/tmux 启动的CLI会话 | 沿CLI合同与profile合同;有真实Dispatch才用worker_done/Delivery |
| GUI本地Web | localhost网页及其本地Web服务管理的内核 | 可直接新建任务、发送和读取结果;读取共享项目/任务索引,实际运行进程由本地Web服务创建 |
| GUI官方远控 | 正在运行的桌面窗口及其会话 | 浏览器DOM派发/观察,绑定原session,真实产物由PM验收 |
“过渡路径”指MAO当前采用浏览器操作、尚无Orca GUI适配器,不表示ZCode GUI本身功能残缺。GUI不是spawn-worker.sh已实现的backend/profile枚举。zcode-gui如用于人类任务卡,只能是描述性标签,不得传作不存在的CLI参数或据此创建虚假Run/Dispatch。用户只说ZCode且已有CLI约定时保留原约定;已明确选择GUI时不再落入CLI默认桥。
zcode --web的localhost Web宿主、外部新起app-server、官方Remote Control三者不能互换:本地Web已实测能直接使用图形任务界面完成对话,不能因另起进程就排除其GUI能力;但也不因页面相似或共用数据库就自动附着桌面正在运行的内核。旧GUI代理不是本路径前置,不自动安装或启用。本地Web的桌面功能与权益采用下述用户确认;该确认不扩展到独立CLI。
1.1 能力与权益依据
2026-10-02用户明确确认:本地Web可使用全部桌面功能,包括Start Plan及150%优惠。将此记为“用户确认”,作为本用户选路和操作依据,不再写成能力未知、不再要求为同一选择重复验证或确认。希望使用这些功能或权益时选择GUI本地Web;明确选择CLI/Orca监督或接续既有CLI任务时保持CLI。
Agent实测另行记录:已验本地Web任务派发、完成、刷新、共享索引与个人Coding Plan调用;未逐项复测桌面功能或Start/150%扣费。两类证据不混写;未复测不否定用户确认,也不阻塞GUI使用。新账户、未来活动变更或实际失败出现时按现场事实更新,不把本次确认延伸为所有账户永久权益。
1.2 保存网址与固定 localhost 端口
可以在 Skill 保存无凭证的入口和启动配方。本机已核的 ~/.zcode/runtime/current/bin/zcode.mjs 默认绑定 127.0.0.1,未指定端口或传 --port 0 时,通过 listen(0) 选择空闲端口,因此重启后的端口可能变化,并非固定默认端口;同一服务运行期间不因刷新网页而换端口。指定正整数端口后使用该端口,不走自动选端口逻辑。
需要独立 localhost Web 时,可约定如下固定入口(18490 是示例约定,不是产品默认值或已运行服务的记录):
# 在目标工作目录执行;先核本机此入口支持的参数。
node "$HOME/.zcode/runtime/current/bin/zcode.mjs" --web --help
node "$HOME/.zcode/runtime/current/bin/zcode.mjs" --web --host 127.0.0.1 --port 18490 --workspace "$PWD" --no-open
# 对应无凭证基础地址:http://127.0.0.1:18490/启动前核端口占用与 owner;已存在的服务先核身份再复用,不挤占其他服务。服务停止后网址不会自行启动它;启动器打印网址也不足以证明监听成功,需确认实际页面可连接。安装路径或 CLI 版本变化时先核入口,不把该本机启动配方当作所有同名开源 CLI 的参数合同。
当前启动器的 loopback 默认不启用 token;若显式启用且未提供固定 token,会随机生成,完整授权 URL 随之可能变化。固定基础地址可进公开 Skill,真实 token 或带授权参数的完整链接只保存在本地不入库的私有位置。不要为固定网址关闭原有鉴权或扩大监听范围。
官方桌面远控的站点入口为 https://zcode.z.ai,本轮使用桌面生成的配对链接;其授权参数是否跨重启保持、何时失效尚未验证,不能断言每次都会变化或永久有效。已授权链接可私下保存并优先复用,失效时再从桌面取得当前链接;公开 Skill 仅保留站点与获取步骤。上面的固定 localhost 配方不会将独立 Web 宿主转换成桌面远控,也不继承本页此前桌面实测结论。
1.3 跨电脑连接与执行位置
官方远控可连接另一台已配对电脑;项目文件、内核、额度上下文及原生状态属于目标宿主。派发前在目标机核工作区绝对路径、Skill版本/脚本、Web入口和资源预算。同名项目或同步目录不能证明版本一致;PM本机内存与SQLite不能替代目标机证据。本页的runtime路径仅是已验本机配方,目标机缺失时先定位实际入口,不照抄启动或自动安装。
已授权且配对的Orca管理终端可辅助只读核目标机文件、预算和本任务原生状态;这不是CLI Agent派发,也不表示GUI已获得Orca监督身份。终端故障、GUI未接收、预算拒绝分别记录,不未经验证合并为同一原因。跨机实测边界见浏览器参考§2.1。
1.4 分流本机负载与项目归属
用户明确要求通过目标电脑的GUI分担负载、使用目标机额度时,优先派边界独立的审查、资料研究和隔离目录定向测试;按目标机现场能力决定工作,不因本机预算不足就停掉可在远端执行的任务。账号额度与硬件资源分别核:页面选Start Plan后,从该回合原生provider确认实际通道;选中模型不等于任务已接收或扣费倍率已核。
项目会话可选时核其workspace真实绝对路径;仅有普通任务入口时,将任务材料、允许读写范围与每次执行的cwd写成绝对路径,原生session仍如实记默认workspace。远端旧Skill或同步项目不能作为本机当前候选的替代基线;传递无凭证冻结副本并核hash,在专属目录审查/测试,PM收取并验收报告。实施类工作另冻结文件归属和回传/集成规则,不让两台机器同时写同一同步文件。
2. 派发前准备
- 在项目既有任务源记录目标、输入、允许读写范围、预算、验收方式、唯一PM及会话owner。研究任务必须有用户明确研究派发授权;过渡路径已验范围从早期的小型只读研究、交接、审查与原会话返修,扩展到工程/文档交付与远端作者直发 PR(具名已验为 PR257/PR258 链),发布合同读取 38-zcode-gui-remote-pr.md。
- 记录运行方式为GUI浏览器管理。无分支、worktree、Orca Task/Dispatch时记“不适用”,不编造。身份最低包含业务task ID、目标workspace、实际session ID、输入轮次及交付版本;发送后从原生只读记录或可见产品身份核得session ID,核不清时先核对,不续派或清理。
- 确认所选宿主可用:官方远控需桌面在运行,本地Web核专属服务监听;目标workspace已登记、当前账号/模型/套餐与任务约定一致。先核当前额度可用状态及内存余量;未知保留未知。内存拒绝不能通过GUI绕过。GUI账号沿官方界面管理,不直接套独立CLI切号脚本。
- 只读研究可新建无项目会话,再明确给出允许读取的文件;需要项目上下文时选择准确workspace。无项目仍可能加载较大上下文,不能假定低成本。已有业务会话只有在用户授权接续且确认唯一writer后才使用。
- 新worker沿用户既有授权采用该会话支持的最高可用执行权限,核实实际生效;显式较窄约定保持,不为此修改全局配置。会话模式不代替文件范围授权。GUI当前没有本Skill的机械scope/安装hook保证,不能声称已加载CLI guard。
GUI路径不调用CLI spawn/Orca资源门来制造回执。对本页明确授权的小型只读研究,采用上述具名输入、零业务写入及PM来源核查合同;不运行要求代码diff/head的implementation价值门来伪装研究交付。代码实施与发布已有具名实测:真实GUI实施worker原会话交付与返修见 浏览器参考§5,远端GUI作者直发PR(safe-push+唯一draft PR,PM只读核验)合同见 38;超出该已验链的业务操作仍须任务授权与代表性验证,不能默认宣称已受本Skill验证。
3. 连接与唯一输入
本地 Web 分支:先按§1.2核端口/owner与工作区,启动或复用属于本任务的服务,再打开固定地址;实际页面就绪后直接进行下方第3—5步,不需要官方远控链接。核本地服务、子内核及session身份,不能接管桌面已有活跃任务。模式和默认模型从当前页面读取,不照抄此前远控的默认值。
官方远控分支:
- 在桌面打开官方“移动端远程控制”,使用其当次生成的链接连接浏览器。优先复用当前任务拥有的已连接页面;一个窗口同一时间只连一个远控页面,不挤掉其他人的连接。
- 链接携带授权,只在需要的控制通道内传递;不贴聊天、任务卡、Git、公开日志或截图。桌面绑定/复制链接可用当前宿主的桌面工具,进入网页后优先用浏览器DOM定位。
- 等到配对及workspace同步完成,以最新DOM确认工作区、任务标题、模型、模式与输入框。不要硬编码历史元素编号。已登录的官方远控可直接沿现有授权使用;遇到额外身份验证按宿主规则处理,不编造验证结果。
- 新任务使用具名task ID;输入完整目标、材料范围、禁止项、预算、交付格式和PM身份。研究worker只在会话交付,由PM保存;实施类任务另行明确唯一写入范围。
- 一条业务输入只提交一次。发送后loading、空框、草稿残留、暂时没有回复都不证明失败。绑定原input/turn,先查原会话是否已接收,再决定下一动作。
输入格式可用:
任务 <task-id>;角色 <研究/审查>;PM <owner>。
目标:<一个可验收问题>。材料:<允许读取的绝对路径/已授权来源>。
范围:<允许动作及禁止动作>;其他会话也在工作,不操作它们的成果。
预算:<工具步数/时长>。交付:task ID、READY_FOR_REVIEW、结论、来源、未验项。
只在本会话交付;收到PM反馈后沿原任务修订,不另开会话或再次派工。4. 监控与恢复
使用同一浏览器页面切换具名任务,读取工作中/工具进度、权限等待、错误与最终输出。用户在GUI接管同session时暂停PM输入;浏览器连接断开不等于Agent停止。
| 层 | 可记录状态 | 不可扩大为 |
|---|---|---|
| input | admitted:持久接收;promoted:提升为消息 | 模型已运行或业务已完成 |
| input | cancelled/discarded/failed | 未执行、零副作用或自动重投授权 |
| turn | running:同回合新鲜网页/原生运行证据 | 仅进程存活、旧idle或历史DB值 |
| turn | completed/error/cancelled | PM验收通过;completed不是session_input枚举 |
| PM | accepted:独立核产物、范围与证据后接受 | worker自报READY_FOR_REVIEW |
| connection | unknown:断线且无法核当前状态 | 默认失败后重开任务 |
有本机读取能力时,可只读原生session/input/turn/tool记录和GUI任务索引作辅助,限定本任务,不搜集无关会话或reasoning。不得写数据库,不通过另起CLI resume冒充当前GUI状态。冷数据库不是实时活性权威;缺失/陈旧的running记录不能推导空闲。
断线先恢复原页面,核原session及已有消息;无身份或当前状态证据时保留unknown。终态也不自动授予重投权:先对原input/turn及副作用对账,只有确认未执行或可安全重试且任务授权覆盖时才能再发;已completed的同一输入不得重复投递。不得隐式回退CLI造成双执行。
5. 交接、审查与收口
- 从最终回复和工具/文件证据回读交付,保存到任务指定的证据位置,绑定task/session与版本;只保存必要材料,不复制授权链接或凭证。
- 独立审查任务读取冻结交付及原始来源;PM验真实工具/文件/测试,不能只采信审查者ACCEPT。材料交接沿用户授权正常进行。
- 发现问题,向原作者/原审查session发一条具体反馈,标明问题、证据、要求和修订版本。保持任务身份,不重开同题任务。回读修订后再验收。
- 将业务验收写回原任务源,分别记录已接收、已完成、PM已接受及未验范围。GUI会话没有Orca监督身份时,不要求worker_done、release或ack,也不把UI完成伪造成Delivery。需Git发布时读取 远端作者直发PR合同:作者自己safe-push并建唯一draft PR,PM只从GitHub只读核验head/base/draft/files/checks,不代发布。
- 临时试验结束:官方远控停止本轮连接并核网页断开;本地Web通过原启动终端停止本任务拥有的服务,核监听端口和已记录子进程退出。关闭自己的浏览器标签;仅关面板不等于停止。保留交付会话,不停止其他任务或按进程名kill。用户明确要求继续使用既有连接/服务时,记录保留的owner和用途;保留不等于自动监测已运行。
6. 已验与待验
2026-10-02另一台Mac官方远控3.14.4:PM浏览器实派单个只读worker,完成首轮检查与原会话交接研究,两轮原生completed、共3次工具调用,刷新重连保留结果;实际Start Plan/GLM-5.3-Flash/yolo。已验远端工作派发,不将默认workspace按绝对路径读项目冒称原生项目会话,也不将此扩展为脚本自动监督或远端localhost启动成功。前次失败及接续操作边界见浏览器参考§2.1。
2026-10-02本地Web runtime 3.14.3:在固定loopback端口打开真实页面,可见共享项目/任务、模型、自动化与插件入口;实际新建任务完成一轮GLM-5.3-Flash/个人Coding Plan对话(8.898秒、零工具),刷新保留精确回复,GUI任务索引同session已完成。实测Web服务另起自己的zcode-cli子进程,收口后监听与子进程均退出。启动读取到Start Plan有效状态,只证明套餐可见,不证明本轮用了Start;界面入口可见不证明所有功能均可用。任务证据见TASKS的ZCODE-LOCAL-WEB-PARITY。
2026-10-02本机桌面3.14.4、内核0.16.9、个人Coding Plan/GLM-5.3:已验新任务、同session续聊、浏览器刷新重连、GUI索引同ID;随后三会话串行研究/审查完成5回合、8次只读工具调用,观察到运行中读取,A/B交给C独审、C原session两次返修后PM验收,远控关闭已确认。这些是操作路径实测,不是修改本页后的无旧上下文前向验证。
历史2026-09-13官方桌面远控曾成功消耗Start/Weekend;当前本地Web完整桌面功能、Start Plan及150%权益采用§1.1的用户确认。Agent尚未独立复测这些权益,不将其冒写为本轮扣费实测。独立CLI是否具有同等权益不在该确认范围;本地Web接管桌面已有活跃session、并发吞吐、审批/业务写入的PM闭环、长程无人值守、跨PM自动唤醒、机器重启恢复及Orca监督接线仍未由本Skill验证。
维护证据由TASKS中的 ZCODE-REMOTE-BROWSER-TRIAL、ZCODE-REMOTE-RESEARCH-WAVE 两卡索引;归档不随分发可用时,只以本节有限结论为准,不要求使用者读取失效临时路径。
官方参考:Remote Control。官方描述网页控制既有桌面环境,并不承诺此处的PM自动化接口或优惠倍率。