提交前确认 · Pre-submission checklist
问题类别 · Category
对话 / Agent 交互 · Agent chat
涉及的 Agent 框架 · Agent framework
ZCode Agent（自研）
严重程度 · Severity
影响体验 · Major (功能可用但体验受损 / works but degraded)
复现频率 · Reproducibility
必现 · Always
问题描述 · Description
SSH 远程工作区下，子智能体"指定模型"设置不生效，静默回落为"继承默认"
环境
客户端：ZCode 桌面端（版本请见"关于"页；远端 session db schema 为 0.15.2，远端服务端 bundle 内嵌版本标识 2.1.0）
远端服务器：Linux x86_64（kernel 6.8），通过 SSH remote 连接的工作区
模型渠道：内置 bigmodel coding plan（GLM-5.2 / GLM-5.3）+ 自定义 OpenAI-API-Compatible provider（mimo-v2.5-pro）
已用对照实验排除的变量：主模型选择哪家（内置 GLM / 自定义模型均复现）、项目配置中"资源下载方式"（本地下载后上传 / 远端下载均复现）
复现步骤 · Steps to reproduce
配置一个自定义模型（如 OpenAI-API-Compatible 的 mimo-v2.5-pro）。
打开 Settings → Subagents，将 general-purpose 和 Explore 从"继承默认"改为"指定模型"，并选择该模型。
通过 SSH 远程连接打开一个项目。
在会话中让主智能体启动子智能体（Agent 工具）。
检查子智能体实际使用的模型。
期望表现 · Expected behavior
子智能体使用"指定模型"中配置的模型——与本地项目行为一致。
实际表现 · Actual behavior
子智能体运行会话当前主模型（如 builtin:bigmodel-coding-plan/GLM-5.3），即等价于"继承默认"，且 UI 无任何提示或报错。同一设置在本地项目中正常生效。
ZCode 版本 · ZCode version
v3.9.1
设备 / 系统 / 浏览器 · Device / OS / Browser
local：Windows -> ssh：Ubuntu 24.04
截图 / 录屏 / 日志 · Screenshots / Recordings / Logs
根因分析（来自远端服务端 bundle 反混淆、服务端日志与数据库取证）
该设置的持久化位置是客户端机器的 /v2/agents-state.json（builtInModelOverrides 字段；服务端 readAgentState 读取该文件，键仅接受 general-purpose / Explore）。
远端服务器进程仅在 bootstrap 时读取自己 storageRoot 下的该文件（loadZCodeAgentProfiles，全 bundle 单一调用点），不会在会话或 spawn 时重读。
SSH remote 模式下，该设置既不被写入远端的 /.zcode/v2/agents-state.json，也不随客户端 runtimeConfig 下发到服务端：
连续两天的远端服务端日志（/.zcode/cli/log/zcode-.jsonl）中，指定模型从未出现在任何 subagent.spawned 或 model.request. 上下文；
远端 ~/.zcode/cli/db/db.sqlite 的 model_usage 表显示，zcode-general-purpose / zcode-Explore 的实际路由与当次会话主模型完全同步（会话切到 mimo 时子智能体走 mimo，切回 GLM 时走 GLM）——纯继承行为；
远端 ~/.zcode/v2/ 目录下不存在 agents-state.json。
本地项目正常的原因：客户端与服务器同机，设置界面写入的文件正是服务器 bootstrap 读取的文件。
佐证线索（建议一并排查）：远端日志中每次模型切换均记录 session.model_selection.persist_failed: FOREIGN KEY constraint failed，说明该版本客户端在远程场景下的设置持久化链路存在更广泛的问题。
修复方向建议：服务端合并逻辑本身已支持客户端下发覆盖（builtInModelOverrides: {...服务端, ...客户端}），只需客户端在 SSH remote 模式下把 builtInModelOverrides 随 runtimeConfig 下发，或通过协议将 agents-state.json 同步到远端 storageRoot。
临时解决方法（已验证可用）
在远端手动创建 ~/.zcode/v2/agents-state.json：
json
{
"builtInModelOverrides": {
"general-purpose": "/",
"Explore": "/"
}
}
新开会话（触发新的服务端 bootstrap）后生效。注意：之后在客户端 UI 中再次修改该设置，仍不会同步到这个文件；远端文件需手工维护；JSON 必须合法（解析失败会静默回落为空覆盖）。
诊断信息
远端日志：/.zcode/cli/log/zcode-.jsonl（subagent.spawned 无 model 字段；model.request.completed 的 providerId / modelId 即实际路由）
远端数据库：/.zcode/cli/db/db.sqlite → model_usage 表（agent / provider_id / model_id / query_source='subagent'）
关键对照证据：本地项目同样的设置正常生效；同一远端、手工写入 agents-state.json 后立即生效
提交前确认 · Pre-submission checklist
问题类别 · Category
对话 / Agent 交互 · Agent chat
涉及的 Agent 框架 · Agent framework
ZCode Agent（自研）
严重程度 · Severity
影响体验 · Major (功能可用但体验受损 / works but degraded)
复现频率 · Reproducibility
必现 · Always
问题描述 · Description
SSH 远程工作区下，子智能体"指定模型"设置不生效，静默回落为"继承默认"
环境
客户端：ZCode 桌面端（版本请见"关于"页；远端 session db schema 为 0.15.2，远端服务端 bundle 内嵌版本标识 2.1.0）
远端服务器：Linux x86_64（kernel 6.8），通过 SSH remote 连接的工作区
模型渠道：内置 bigmodel coding plan（GLM-5.2 / GLM-5.3）+ 自定义 OpenAI-API-Compatible provider（mimo-v2.5-pro）
已用对照实验排除的变量：主模型选择哪家（内置 GLM / 自定义模型均复现）、项目配置中"资源下载方式"（本地下载后上传 / 远端下载均复现）
复现步骤 · Steps to reproduce
配置一个自定义模型（如 OpenAI-API-Compatible 的 mimo-v2.5-pro）。
打开 Settings → Subagents，将 general-purpose 和 Explore 从"继承默认"改为"指定模型"，并选择该模型。
通过 SSH 远程连接打开一个项目。
在会话中让主智能体启动子智能体（Agent 工具）。
检查子智能体实际使用的模型。
期望表现 · Expected behavior
子智能体使用"指定模型"中配置的模型——与本地项目行为一致。
实际表现 · Actual behavior
子智能体运行会话当前主模型（如 builtin:bigmodel-coding-plan/GLM-5.3），即等价于"继承默认"，且 UI 无任何提示或报错。同一设置在本地项目中正常生效。
ZCode 版本 · ZCode version
v3.9.1
设备 / 系统 / 浏览器 · Device / OS / Browser
local：Windows -> ssh：Ubuntu 24.04
截图 / 录屏 / 日志 · Screenshots / Recordings / Logs
根因分析（来自远端服务端 bundle 反混淆、服务端日志与数据库取证）
该设置的持久化位置是客户端机器的 /v2/agents-state.json（builtInModelOverrides 字段；服务端 readAgentState 读取该文件，键仅接受 general-purpose / Explore）。
远端服务器进程仅在 bootstrap 时读取自己 storageRoot 下的该文件（loadZCodeAgentProfiles，全 bundle 单一调用点），不会在会话或 spawn 时重读。
SSH remote 模式下，该设置既不被写入远端的
/.zcode/v2/agents-state.json，也不随客户端 runtimeConfig 下发到服务端：/.zcode/cli/log/zcode-.jsonl）中，指定模型从未出现在任何 subagent.spawned 或 model.request. 上下文；连续两天的远端服务端日志（
远端 ~/.zcode/cli/db/db.sqlite 的 model_usage 表显示，zcode-general-purpose / zcode-Explore 的实际路由与当次会话主模型完全同步（会话切到 mimo 时子智能体走 mimo，切回 GLM 时走 GLM）——纯继承行为；
远端 ~/.zcode/v2/ 目录下不存在 agents-state.json。
本地项目正常的原因：客户端与服务器同机，设置界面写入的文件正是服务器 bootstrap 读取的文件。
佐证线索（建议一并排查）：远端日志中每次模型切换均记录 session.model_selection.persist_failed: FOREIGN KEY constraint failed，说明该版本客户端在远程场景下的设置持久化链路存在更广泛的问题。
修复方向建议：服务端合并逻辑本身已支持客户端下发覆盖（builtInModelOverrides: {...服务端, ...客户端}），只需客户端在 SSH remote 模式下把 builtInModelOverrides 随 runtimeConfig 下发，或通过协议将 agents-state.json 同步到远端 storageRoot。
临时解决方法（已验证可用）
在远端手动创建 ~/.zcode/v2/agents-state.json：
json
{
"builtInModelOverrides": {
"general-purpose": "/",
"Explore": "/"
}
}
新开会话（触发新的服务端 bootstrap）后生效。注意：之后在客户端 UI 中再次修改该设置，仍不会同步到这个文件；远端文件需手工维护；JSON 必须合法（解析失败会静默回落为空覆盖）。
诊断信息
远端日志：
/.zcode/cli/log/zcode-.jsonl（subagent.spawned 无 model 字段；model.request.completed 的 providerId / modelId 即实际路由）/.zcode/cli/db/db.sqlite → model_usage 表（agent / provider_id / model_id / query_source='subagent'）远端数据库：
关键对照证据：本地项目同样的设置正常生效；同一远端、手工写入 agents-state.json 后立即生效