qwen serve HTTP 协议参考

qwen-code daemon 设计 的第一阶段。所有路由均位于 daemon 的基础 URL 下（默认为 http://127.0.0.1:4170）。

本参考文档描述了 HTTP 路由和 SSE 帧格式。请结合 类型化事件模式（用于负载契约、重新同步原因和历史锚点）、事件总线与重放指南（用于投递和背压）以及 功能与版本控制（用于现有的 v1 协议和兼容性规则）一起阅读。守护进程文档索引链接了完整的契约集。

身份验证

当 daemon 启动时指定了 --token 或 QWEN_SERVER_TOKEN —— 或者绑定到非回环地址且未指定两者（这会生成一个临时 bearer token 并在启动时打印一次）—— 除了普通回环绑定上的 /health 之外，每个常规 API 路由都必须携带：

Authorization: Bearer <token>

如果在默认回环绑定上未配置令牌，则该标头是可选的，通过主监听器到达的请求拥有完全的操作员 API 权限。工作区信任、会话所有权、X-Qwen-Client-Id、权限、功能、验证和资源检查仍然适用。令牌比较采用恒定时间算法。401 响应在 missing header / wrong scheme / wrong token 中保持一致。

--open-with-auth。 此默认关闭的 CLI 模式要求绑定到回环地址并有一个可用的 Web Shell。它复用正常的 --token-over-QWEN_SERVER_TOKEN 选择，或者在该选择为空时，在 daemon 启动前生成 32 个随机字节并以 base64url 编码。浏览器通过 #token= 接收选定的 bearer token 并按标签页存储；协议和中间件将其视为普通的已配置令牌。片段传递键基于解析后的令牌，而不是此标志：任何 --open 启动都会将解析后的 bearer token（无论是配置的还是生成的）附加到启动 URL 的 #token= 片段中（本地用户可通过 ps / /proc 看到，正如启动器警告的那样），因此带有裸 --open 的非回环绑定也会以相同方式将其生成的 bearer token 传递给浏览器；此标志的独特贡献在于回环上的令牌 生成 以及浏览器不可用环境下的手动 URL 备用方案。只有忽略 RunHandle.resolvedToken 的直接嵌入式调用者，以及从不启动浏览器的客户端，才不会收到自动凭证。浏览器不可用的环境会打印包含密钥的片段 URL 以供手动打开。回环 /health 和静态 Web Shell 资源保留下文所述的豁免；--require-auth 仍然门控 /health。

通道 webhook 入口（POST /channels/:channelName/webhooks/:source）在所有模式下都与该 bearer 契约分离。挂载时，它在 bearerAuth 之前注册，并使用其配置的 x-qwen-webhook-secret 进行身份验证；轮换 daemon bearer token 不会轮换 webhook 源密钥。

/health 豁免 (Bctum)：在回环绑定上（127.0.0.0/8 / localhost / ::1 / [::1]），/health 在 bearer 中间件之前注册，因此即使 daemon 启动时指定了 --token，Pod 内的存活探针也不需要携带令牌。非回环绑定（如 --hostname 0.0.0.0）与其他常规 API 路由一样对 /health 进行门控 — 有关理由，请参阅 GET /health 部分。

--require-auth (#4175 PR 15)。 在启动时传递此标志以将“必须具有令牌”的规则扩展到回环地址。当没有令牌源解析成功时，启动失败 — 在回环上这意味着 --token、QWEN_SERVER_TOKEN 或 --open-with-auth（后者会在启动前安装自己生成的令牌，因此 --require-auth --open-with-auth 可以启动）。快速失败仅适用于回环：如果不存在两个配置源，非回环绑定会解析其生成的临时 bearer token，这满足该标志的要求。无论哪种情况，/health 豁免都会被移除，因此 /health 也需要 Authorization: Bearer …。

当启用该标志时，全局 bearerAuth 中间件门控 每个常规 API 路由 — 包括 /health 和 /capabilities。通道 webhook 入口保持独立的共享密钥身份验证，Web Shell 文档和资源路由保持预认证状态。因此，未经身份验证的客户端无法预先探测 caps.features 以发现需要身份验证：这种情况的发现面是 401 响应体本身（根据 身份验证 部分，在 bearer 门控路由中保持一致）。require_auth 能力标签是一个 身份验证后的确认 — 一旦客户端成功身份验证并读取 /capabilities，该标签的存在确认 daemon 启动时指定了 --require-auth（有助于审计/合规 UI 以及 SDK 客户端在设置面板中显示“此部署已加固”）。严格变更路由接受受信任的回环主监听器请求、bearer 身份验证请求或配对的 Local Control 请求。不受信任的无令牌嵌入仍会收到 401 { code: "token_required", error: "…" }；使用 --require-auth 时，全局 bearer 中间件首先拒绝并返回遗留的 Unauthorized 响应体。

--allow-origin <pattern> (T2.4 #4514 )。 默认情况下，跨域访问 daemon 的浏览器客户端会被阻止 — 携带 Origin 标头的请求会返回 403 {"error":"Request denied by CORS policy"}，因为 CLI/SDK 客户端从不发送 Origin，而 daemon 将其存在视为请求来自操作员未选择加入的浏览器上下文的迹象。在非回环绑定且带有令牌的墙上有一个例外先于墙生效：同源请求（Origin 等于直接套接字方案加上规范化的 Host 权限）经过 bearer 身份验证，并且其 Origin 被剥离 在主监听器上 — 如果 bearer 有效，则遵循路由自身的状态码，如果缺失或无效 bearer，则返回 401，除了预认证的 Web Shell 文档、/assets/*、/manifest.webmanifest、/sw.js 和 /mcp-app-sandbox 路由，它们像其他所有模式一样无需凭证即可提供服务 — 只有跨域或不匹配的 Origin 值才会保留 403 信封。在启动时传递 --allow-origin <pattern>（可重复）以安装允许列表而不是墙。每个模式要么是：

• 字面量 * —— 允许任何来源。风险：当配置了 * 但未解析到 bearer token 时，启动将被拒绝。守卫读取的是 已解析 的 token —— --token、QWEN_SERVER_TOKEN、--open-with-auth 生成的回环 token，或者在非回环绑定且两个配置源均不存在时生成的临时 bearer token —— 因此此拒绝仅针对回环地址。当列表中包含 * 时，启动面包屑会在 stderr 中发出警告。建议：在回环绑定上配合使用 --require-auth，以便 /health 也受 bearer 保护 —— 默认情况下它在回环上注册于 bearer 中间件之前（因此 k8s/Compose 探针可以在没有 token 的情况下访问它），而 * 白名单使其可从任何跨域浏览器访问。--require-auth 仍然使 Web Shell 静态资源（/、/assets/*、/manifest.webmanifest、/sw.js 以及 /session/:id、/plugins、/channels、/live、/scheduled-tasks、/goals 和 /settings 文档导航）按设计在回环上保持预认证状态 —— 它们挂载在 bearer 中间件之前 —— 因此在 * 白名单下，它们仍可从任何跨域浏览器读取；--no-web 移除了该表面。在非回环绑定上，bearer 在启动时已是强制性的，且 /health 注册在其后。常规 API 路由受 bearer 保护，通道 webhook 入口保留其自身的共享密钥门控，除非 --no-web 移除它们，否则 Web Shell 静态资源（/、/assets/*、/manifest.webmanifest、/sw.js 以及 /session/:id、/plugins、/channels、/live、/scheduled-tasks、/goals 和 /settings 文档导航）保持预认证状态。
• 规范 URL 来源 —— <scheme>://<host>[:<port>]。**无尾随斜杠，无路径，无用户信息，无查询参数。**如果条目未通过往返 new URL(pattern).origin === pattern 验证，启动将以 InvalidAllowOriginPatternError 拒绝；错误消息会指明错误的模式和规范形式。严格遵循意图：静默规范化（例如修剪尾随的 /）会让拼写错误溜过并接受有歧义的输入。如果没有已解析的 token —— 生成后意味着回环绑定 —— HTTP(S) 条目仅限于回环主机；非回环浏览器来源需要 token，因为它否则可以驱动完整的操作员 API，包括以守护进程用户身份执行代码。显式浏览器扩展来源保留其现有的无 token 本地自动化路径。启动日志记录授予任何无 token 允许的浏览器来源的权限。

匹配的来源在每个请求上接收标准的 CORS 响应头：

Access-Control-Allow-Origin: <echoed origin>
Vary: Origin
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Qwen-Client-Id, Last-Event-ID, X-Qwen-Event-Epoch
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: Retry-After, X-Qwen-Event-Epoch, X-Qwen-SSE-Stream-Id

Access-Control-Allow-Origin 逐字回显请求的来源（大写/小写与浏览器发送的一致），而不是字面量 *，即使在 * 模式下也是如此 —— 浏览器缓存将响应键定于此并与 Vary: Origin 配对，回显为后续版本中添加 Access-Control-Allow-Credentials 留出了空间而无需更改架构。暴露的头允许浏览器客户端遵守重试提示，保留 SSE 纪元，并关联接受的物理流。Access-Control-Allow-Credentials 今天不发送：配置的守护进程凭据使用 bearer-in-Authorization，这在跨域时无需 credentials: 'include' 即可工作；可信回环权限不需要浏览器凭据。

OPTIONS 预检请求（带有 Access-Control-Request-Method 或 Access-Control-Request-Headers 的 OPTIONS）短路返回 204 No Content 加上上述头。这是常规的 CORS 模式且安全 —— 预检仅确认守护进程将接受哪些方法/头；实际后续请求在读取或修改任何状态之前，仍先运行 Host 门控，然后要么经过 bearer/监听器权限，要么经过通道 webhook 共享密钥门控。来自匹配来源的普通 OPTIONS 请求继续向下流动并附带 CORS 头。

不匹配白名单的来源仍然获得 403 {"error":"Request denied by CORS policy"} —— 与默认墙相同的信封，因此已经解析了墙的响应的客户端不必对部署了白名单的守护进程进行特殊处理。拒绝路径不发出任何 Access-Control-* 头（浏览器会忽略它们，并且发出这些头会通过头的存在间接泄露白名单大小）。

配置的模式列表有意不在 /capabilities 中回显 —— 浏览器客户端已经知道其自身的来源（毕竟它调用了守护进程），并且显示该列表会让 /capabilities 的未认证读者枚举每个受信任的来源（对于配置错误的部署是有用的侦察）。SDK 客户端基于 caps.features.allow_origin 标签来门控“此守护进程尊重跨域浏览器命中”，而无需知道具体是哪些来源。

回环自来源请求（例如 Web Shell 调用同一 127.0.0.1:port 处的守护进程）由一个单独的 Origin-strip shim 处理，该 shim 在 CORS 中间件之前运行，并为 127.0.0.1:port / localhost:port / [::1]:port / host.docker.internal:port 或精确绑定的回环地址和端口移除 Origin 头。它还接受浏览器为默认端口发送的方案匹配的无端口形式：端口 80 上的 http://host 和端口 443 上的 https://host。无论 --allow-origin 配置如何，这些请求都会通过 —— 操作员无需列出守护进程自己的端口即可使 Web Shell 工作。

常见错误形状

5xx 响应在存在时携带原始错误的 code 和 data（JSON-RPC 风格 —— ACP SDK 从 Agent 转发 {code, message, data}）：

{
  "error": "Internal error",
  "code": -32000,
  "data": { "reason": "model quota exceeded" }
}

请求体中的格式错误 JSON 返回：

{ "error": "Invalid JSON in request body" }

状态码为 400。

未知会话 ID 的 SessionNotFoundError 返回：

{
  "error": "No session with id \"<sid>\"",
  "sessionId": "<sid>",
  "code": "session_not_found"
}

状态码为 404。并发关闭使用 code: "session_closing"。

对于 cwd 未规范化为已注册工作区的 POST /session 的 WorkspaceMismatchError 返回 400 及：

{
  "error": "Workspace mismatch: daemon is bound to \"…\"",
  "code": "workspace_mismatch",
  "boundWorkspace": "/path/the/daemon/uses/as-primary",
  "requestedWorkspace": "/path/in/the/request"
}

使用此功能在预飞行期间检测不匹配：从 /capabilities 读取 workspaceCwd 并从 POST /session 中省略 cwd（它回退到主工作区），或者当广告了 multi_workspace_sessions 时选择 workspaces[].cwd 中的一个。

超过守护进程的 --max-sessions 上限的 POST /session 返回 503 及 Retry-After: 5 头和：

{
  "error": "Session limit reached (20)",
  "code": "session_limit_exceeded",
  "limit": 20,
  "scope": "workspace"
}

当有效的全守护进程总上限拒绝新会话时 —— --max-total-sessions，或在 limits.maxTotalSessions 下描述的默认值 —— 返回具有 "scope": "total" 的相同响应形状。

附加到现有会话不计入上限，因此即使达到容量上限，空闲守护进程的重新连接仍可正常工作。

如果在 newSession 被调度之前 ACP 通道初始化预算过期，POST /session 返回 504 及 Retry-After: 5 和：

{
  "error": "AcpSessionBridge initialize timed out after 10000ms",
  "code": "init_timeout",
  "errorKind": "init_timeout",
  "retryable": true,
  "sideEffectPossible": false,
  "phase": "channel.initialize",
  "timeoutMs": 10000
}

timeoutMs —— 以及 error 的数字后缀 —— 反映守护进程配置的 --initialize-timeout-ms 预算（上述值为默认值）。上述完整的安全重试形状仅为普通会话创建发出，其中通道初始化严格先于每个持久变更：在该路径上，sideEffectPossible: false 字段是权威的，因为初始化先于 ACP newSession 请求，理解此结构化契约的客户端可以在广告延迟后重试而不会冒着重复 Session 的风险。

携带 branch 或 worktree 的请求，以及由非单纯创建类（例如 POST /session/:id/branch 和 POST /session/:id/side-task，其中已提交的分支可能比失败的手续存活更久）的变更承载路由所暴露的初始化超时，会返回相同的 504，包含 code: "init_timeout"、phase 和 timeoutMs —— 但不包含 Retry-After、retryable 或 sideEffectPossible。对于这些情况，变更结果未知：分支和工作树准备会在通道初始化之前变更 git，而失败时尝试的回滚是尽力而为的（失败的检出回滚会使工作区停留在新分支上，重试可能会暴露分支已存在的冲突）。将所有 5xx 变更响应归类为模糊响应的客户端仍保持保守的故障关闭策略，并应对简化后的结构应用相同的策略。POST /session/:id/load 和 POST /session/:id/resume 在恢复请求分派之前（即 ensureChannel 阶段）通道初始化超时时，会暴露相同的简化 init_timeout 504；与其错误列表中记录的 session_restore_timeout 504 不同，此结构不包含 Retry-After，不包含 retryable，也不安装防护栏，因为恢复请求从未被分派。POST /session 上的 newSession 分派超时是一个例外：它返回 504，包含 code: "init_timeout"、retryable: true 和基于预算得出的 Retry-After，但不包含 phase 或 sideEffectPossible，因为创建结果是不确定的。所有其他超时标签保留通用映射。

RestoreInProgressError —— 由 POST /session/:id/load、POST /session/:id/resume 或调用方提供的 id POST /session 发出，当另一个注册已经拥有该 id 时 —— 返回 409 并包含：

{
  "error": "Session \"<sid>\" is already being restored via session/<resume|load>; retry session/<load|resume> after it completes",
  "code": "restore_in_progress",
  "reason": "restore_in_progress",
  "retryable": true,
  "sessionId": "<sid>",
  "activeAction": "load",
  "requestedAction": "resume"
}

当针对一个已有 session/resume 正在进行的 id 发出 session/load（或反之亦然），或者当调用方提供的 id 生成与任一恢复方向发生竞争时触发。请至少等待 Retry-After 秒后重试。同操作竞争（load 对 load，resume 对 resume）在恢复活动期间会合并而不是报错。

reason 区分共享此代码的两个围栏，且 Retry-After 标头跟踪它：

公共恢复请求受 limits.sessionRestoreTimeoutMs（默认 60s）控制。在 504 之后，id 保持围栏状态直到迟到的 ACP 请求和清理完成，因此以普通 5 秒节奏持续重试的客户端会在无法清除的 409 上空转 —— 请遵循随 awaiting_abandoned_cleanup 一起提供的基于预算推导出的提示。

SessionWorkspaceConflictError —— 由 POST /session/:id/load 和 POST /session/:id/resume 发出，当请求的 cwd 指向一个已注册的工作区，但同一会话 id 已由另一个运行时处于活动状态或正在恢复时 —— 返回 409 并包含：

{
  "error": "Session \"<sid>\" is already live or restoring in another workspace runtime.",
  "code": "session_workspace_conflict",
  "sessionId": "<sid>",
  "workspaceCwd": "/requested/workspace",
  "workspaceId": "requested-workspace-id",
  "liveWorkspaceCwd": "/live/owner/workspace",
  "liveWorkspaceId": "live-owner-workspace-id"
}

客户端应使用拥有者工作区重试，或在将 id 恢复到不同工作区之前等待正在进行的恢复完成。同工作区恢复竞争继续使用桥接器的 restore_in_progress / 合并行为。

当调用方尝试加载或恢复其 JSONL 位于 chats/archive/ 下的会话时，发出 SessionArchivedError：

{
  "error": "Session \"<sid>\" is archived. Unarchive it before loading.",
  "code": "session_archived",
  "sessionId": "<sid>"
}

状态为 409。

当同一 id 的会话归档或取消归档转换已在进行中时，发出 SessionArchivingError：

{
  "error": "Session \"<sid>\" is being archived or unarchived; retry later.",
  "code": "session_archiving",
  "sessionId": "<sid>"
}

状态为 409 且 Retry-After: 5。

能力

守护进程从 serve 功能注册表中通告其支持的功能标签。客户端 必须 基于 features 而非 mode 来控制 UI（根据设计 §10）。

['health', 'capabilities', 'session_create', 'session_startup_config', 'session_id_override', 'session_scope_override',
 'session_load', 'session_resume', 'session_transcript',
 'unstable_session_resume',
 'session_list', 'session_catalog_batch', 'session_info', 'session_prompt', 'session_mid_turn_message_mutation',
 'session_mid_turn_send_now',
 'session_cancel', 'session_events',
 'slow_client_warning', 'typed_event_schema',
 'session_set_model', 'client_identity', 'client_heartbeat',
 'session_permission_vote', 'permission_vote', 'workspace_mcp', 'workspace_skills',
 'workspace_skills_config_runtime',
 'workspace_providers', 'workspace_acp_preheat', 'workspace_acp_status',
 'auth_provider_install', 'workspace_memory',
 'workspace_agents', 'workspace_agent_generate', 'workspace_env',
 'workspace_preflight', 'session_context', 'session_context_usage',
 'session_supported_commands', 'session_tasks', 'scheduled_task_gate', 'autofix_pr_watches', 'session_monitor_tool_correlation', 'session_stats',
 'session_lsp', 'session_resources', 'session_status',
 'session_close', 'session_metadata', 'session_organization',
 'session_archive', 'mcp_guardrails',
 'workspace_mcp_manage', 'mcp_guardrail_events',
 'mcp_server_runtime_mutation',
 'workspace_file_read', 'workspace_file_bytes', 'workspace_file_write',
 'workspace_file_upload', 'workspace_file_delete', 'workspace_directory_create', 'workspace_directory_delete',
 'session_approval_mode_control', 'workspace_tool_toggle',
 'workspace_skill_settings_toggle', 'workspace_skill_settings_batch_toggle',
 'workspace_session_refresh',
 'extension_batch_activation_v2', 'extension_activation_explicit_refresh',
 'extension_state',
 'workspace_settings', 'workspace_init', 'workspace_mcp_restart',
 'session_recap', 'session_generation', 'session_btw', 'session_btw_stream', 'session_shell_command',
 'standalone_sessions_v1', 'standalone_session_options_v1',
 'mcp_workspace_pool', 'mcp_pool_restart',
 'require_auth', 'allow_origin', 'auth_device_flow',
 'permission_mediation', 'prompt_absolute_deadline', 'writer_idle_timeout',
 'non_blocking_prompt', 'session_language', 'user_language_sync', 'session_message_deletion', 'session_rewind',
 'workspace_hooks', 'session_hooks', 'workspace_extensions',
 'session_branch', 'rate_limit', 'workspace_reload', 'workspace_model_reload', 'channel_delivery',
 'multi_workspace_sessions', 'multi_workspace_session_rewind',
 'multi_workspace_session_shell', 'persistent_workspace_registration',
 'workspace_display_name', 'workspace_runtime_removal', 'workspace_runtime',
 'workspace_qualified_rest_core', 'workspace_qualified_voice',
 'workspace_qualified_memory', 'extension_management_v2', 'extension_git_credentials',
 'extension_local_path_install',
 'workspace_persisted_transcript',
 'workspace_session_export', 'workspace_archived_session_export',
 'workspace_session_live_state', 'workspace_session_live_state_batch',
 'client_mcp_over_ws', 'cdp_tunnel_over_ws', 'browser_automation_mcp']

条件标签仅在其部署或运行时可用性条件满足时出现（见下表）。F3 的 permission_mediation 标签始终开启，并携带 modes: ['first-responder', 'designated', 'consensus', 'local-only']，以便 SDK 客户端可以内省构建支持的功能集；运行时激活的策略位于 body.policy.permission。

session_startup_config 在普通创建和独立创建中通告可选的 startupConfig: { modelServiceId, reasoningEffort? }。务必预检此标签：较旧的普通创建路由可能会静默忽略该对象。modelServiceId 是必需的（1–256 个字符）；reasoningEffort 接受 none、default、low、medium、high、xhigh 或 max（如果所选模型支持）。省略时仅应用模型，不使用推理设置器或隐式的 default。该对象不能与遗留的顶层 modelServiceId 或显式单作用域结合使用，并意味着创建一个新线程。启动期间从不保存共享默认值；后续会话行为保持不变。

成功响应包含 modelApplied: true 和 startupConfigApplied: { modelServiceId, reasoningEffort?, effectiveReasoning? }。模型选择器是规范化的。只有显式的推理请求才包含两个推理字段；有效状态为 { state: 'disabled' }、{ state: 'provider-default' } 或 { state: 'enabled', effort? }（仅切换推理没有 effort 级别）。无效结构为 400 invalid_startup_config；被拒绝或未确认的选择为 422 startup_config_rejected。明确的独立创建拒绝会回滚其拥有的记录，并在返回前尝试丢弃空输出目录；无法确认移除的记录回滚以及瞬态启动失败会保留 standalone_creation_outcome_unknown，而失败的目录丢弃仅会被记录日志，明确的拒绝仍会返回。SDK 中成功响应体的确认失败属于协议错误，而不是采用已恢复会话的指令。

session_scope_override 是用于协商 POST /session 上每请求 sessionScope 字段的句柄（见下文）。较旧的守护进程会静默忽略该字段，因此 SDK 客户端应在发送前预检 caps.features 以确认支持此标签。

session_id_override 是用于协商 POST /session 和 ACP session/new 元数据上可选调用方提供的 sessionId 的句柄。客户端必须在发送该字段前确认 caps.features 包含此标签，因为较旧的守护进程可能会静默忽略它。

persistent_workspace_registration 通告对运行时添加的工作区的持久化注册。POST /workspaces 接受 { "cwd": "/absolute/path", "persist": true }；成功响应包含 persisted: true。注册范围限定于用户 Qwen 主目录下守护进程的规范化主工作区，并在下次守护进程启动时恢复。省略 persist 可保留进程本地注册。GET /workspace-registrations 列出存储的期望集合，DELETE /workspace-registrations/:id 会在下次重启时忘记某个条目，而不会热移除活动运行时。

workspace_display_name 通告 POST /workspaces 上的可选 displayName 输入、通过 PATCH /workspaces/:workspace 进行的工作区元数据更新，以及工作区投影中的可选显示名称字段。名称不参与查找或路由：id 和规范的 cwd 仍然是唯一的选择器，且允许重复名称。

workspace_runtime_removal 通过 DELETE /workspaces/:workspace 宣告支持同步热移除。Capability workspace 条目添加可选的 removable；仅带有 removable: true 的行可被移除。移除操作还会忘记运行时的所有持久化注册别名，但绝不会删除文件、设置、转录记录或归档。

workspace_runtime 宣告支持 GET /workspace/runtime/status、POST /workspace/runtime/ensure 及其对应的 /workspaces/:workspace/runtime/... 变体。ensure 不接受 capability 选择：它启动或复用所选受信任工作区的 ACP 运行时，并返回其生命周期状态和单调递增的运行时纪元（epoch）。主路由仅由主运行时拥有；限定路由仅解析所选的已注册运行时，绝不回退。成功的 ensure 操作会续期运行时的十分钟保活窗口。Status 是只读的，且绝不会启动子进程。并发 ensure 共享一次物理启动过程。启动进行中或失败时返回可重试的 503 runtime_still_starting 或 503 runtime_initialization_failed。即使 ensure 观察预算过期，capability 准备仍可能继续；在这种情况下，ensure 仍然返回具有非就绪 capability 状态的活跃运行时，以便进行 status 轮询。仅当所有活跃的运行时桥接提供权威的生命周期快照时，才宣告该 capability；选定的遗留注入式桥接返回 501 workspace_runtime_not_supported，而不是猜测的状态或纪元。

workspace_runtime_stop 独立宣告支持用户确认的运行时停止。GET /workspaces/runtime-stop-options 是一个只读的全局进程预览：包括已提交的子进程数量、建模的子进程上限，以及每个可见工作区的会话、阻塞原因、通道 ID、纪元、当前停止令牌和最新回执。普通加载的会话可以被显式停止；独立的 ACP 客户端、启用的计划任务、待处理的调度器/管理/启动工作、内存任务、工作线程、语音和专用运行时均被阻塞。POST /workspaces/:workspace/runtime/stop 使用严格的变更门控，且仅针对选定的受信任运行时。发送来自预览的 confirmInterruptions: true、expectedChannelId、expectedRuntimeEpoch、expectedStopToken 和精确的 expectedSessionIds。绝不回退到主运行时。预览和每个回执将运行时的活跃 ACP 通道列为 channels（channelId、runtimeEpoch、可选的 executionEngine）；一个运行时可以为每个执行引擎拥有一个通道，而停止操作涵盖所有这些通道。channelId 指定第一个列出的通道，runtimeEpoch 是最新列出的纪元，因此如果在预览之后启动了新通道，则确认信息将变为陈旧。

成功响应包含 state: "stopped"、stopped: true 和 released: true，这是在确认会话关闭以及进程注册表释放所有列出的子进程之后生成的。注册信息、文件和保存的历史记录保持不变。响应包括受影响的、中断的、已关闭的和剩余的会话 ID。陈旧或被阻塞的确认返回 HTTP 409（workspace_runtime_stop_stale / workspace_runtime_stop_blocked）；部分关闭返回 409 workspace_runtime_stop_incomplete；正在进行的拆除或未证明释放的失败拆除返回 503 workspace_runtime_stop_in_progress / workspace_runtime_stop_failed；不支持的管理操作返回 501 workspace_runtime_stop_not_supported。如果后续证明了注册表释放，不干净的拆除可能会返回带有错误警告的 200；未确认的会话刷新仍返回部分/错误结果。总观察/关闭预算为 60 秒。如果预算在会话关闭仍在进行时过期，响应将以 state: "failed" 和 503 workspace_runtime_stop_failed 结束；清理工作单独继续。所选工作区保持隔离，其子进程在实际清理完成之前仍被计入，即使调用者已经收到失败通知。只读选项可以在确认关闭并证明释放后报告 stopped，或在持久化未确认时报告 incomplete；已返回的失败快照不会改变。如果预算是在会话关闭之间耗尽的，响应将以 state: "incomplete" 和 409 workspace_runtime_stop_incomplete 结束：不再启动进一步的关闭或强制终止，停止操作的准入守卫被释放（存活的子进程照常计入），停止剩余会话需要新的预览和确认。对刷新的拒绝不能通过强制终止剩余会话来绕过。根进程退出或全局进程计数下降本身并不能确立所选子进程的释放。在 Windows 上，由于注册表不跟踪后代进程组，根进程的确定退出即为释放证据，因此 released: true 在那里并不能证明进程树已消失。

重复确认最近消费的令牌会观察到相同的操作。新的确认可以重试未完成的停止操作，轮换令牌；较早消费的令牌随后变为陈旧。如果响应丢失，请读取选项并根据工作区和停止令牌匹配最新回执，而不是停止另一个目标。在移除、信任更改或守护进程/桥接重建后，回执可能不可用；缺失意味着结果未知，且绝不授权继续执行。SDK runtimeStopOptions() 和 workspaceById(id).stopRuntime(confirmation) 即使使用 ACP 传输也采用 REST，并且绝不自动重复 POST。会话订阅者接收带有 reason: "client_close" 和 cause: "workspace_runtime_stop" 的 session_closed；与停止相关的致命退出额外标记 persistenceUnconfirmed: true。更新的 Web Shell 客户端保留保存的选择/转录记录，并等待显式的 Resume。这是一次性停止，而非持久挂起；错过事件的用户可能会再次竞争容量。

运行时状态和 ensure 响应使用此格式：

{
  "v": 1,
  "workspaceCwd": "/work/project",
  "state": "active",
  "runtimeLive": true,
  "runtimeEpoch": 4,
  "capabilities": {
    "skills": {
      "state": "ready",
      "revision": 2,
      "runtimeEpoch": 4
    }
  }
}

当工作区运行时拥有多个执行引擎时，runtimeLive 和 runtimeEpoch 描述服务于工作区控制（MCP 和 Skills）的通道：只要该通道处于活动状态，其他引擎的启动或退出不会改变它们。当该通道不活动时，state 将其报告为 cold、starting 或 stopping；active 和 idle 统计所有引擎上的工作负载。

capabilities.skills.state 是 not_started、starting、ready、stale 或 error；失败时在 capabilities.skills.error 中包含 {code, message}。Skills 目录仅在顶层和 capability runtimeEpoch 值匹配时才被视为最新。revision 在一个运行时纪元内对 Skills 准备进行排序，不得跨纪元进行比较。

workspace_skills_config_runtime 在 /workspace/{config,runtime}/skills 和 /workspaces/:workspace/{config,runtime}/skills 下宣告分离的 Skills 读取和配置变更。Web Shell 使用这些路由进行 Skills 管理，并在组合新会话时，在替换为匹配纪元的运行时目录之前，立即从配置中填充斜杠命令。当缺少该功能时，客户端必须继续使用遗留的 Skills 路由，且不得仅为 Skills 调用 runtime ensure。

session_load 和 session_resume 宣告显式恢复路由（POST /session/:id/load 和 POST /session/:id/resume）。较旧的守护进程对这些路径返回 404，因此 SDK 客户端应在调用前预检 caps.features。unstable_session_resume 仍作为弃用的别名被宣告，以兼容底层 ACP 方法命名为 connection.unstable_resumeSession 时发布的 SDK；新客户端应基于 session_resume 进行门控。

limits.sessionRestoreTimeoutMs（如果存在）是守护进程为底层 ACP loadSession / unstable_resumeSession 请求设定的挂钟时间预算。这是一个附加的 v1 字段。TypeScript SDK 给守护进程预留了 10 秒的客户端余量，而 Web Shell 看门狗预留了 15 秒；与旧版守护进程通信的客户端应分别使用 70 秒和 75 秒。

session_transcript 宣告了 GET /session/:id/transcript，这是对持久化活动会话 JSONL 的只读分页回放视图。它与 /load 分开：它不会附加客户端、初始化实时 EventBus、创建实时会话或更改实时回放窗口。当客户端需要长会话的完整磁盘转录记录时，应使用此功能，并仅在冷 UI 恢复期间继续使用 /load 进行有界实时回放。

workspace_persisted_transcript 宣告了 GET /workspaces/:workspace/session/:id/transcript，这是一个仅本地守护进程的持久化分页器，它不启动 ACP、查询桥接状态、加载设置、发现项目能力或创建遗留的持久化游标键。该标签是无条件的，因为受信任的单工作区主进程可以使用复数路由；每个工作区的信任授权仍在每次请求时进行评估。已注册的不受信任的次要工作区可以读取，而不受信任的主进程仍会被拒绝。

workspace_session_export 宣告了 GET /workspaces/:workspace/session/:id/export，这是选定工作区活动持久化会话的仅限受信任用户的完整导出。它独立于 session_export 和 workspace_qualified_rest_core：发布的守护进程可以在不实现复数路由的情况下宣告这两个较旧的标签，因此客户端必须直接预检此标签。该标签是无条件的，因为受信任的单工作区主进程可以通过 id 或 cwd 使用该路由。导出不解析实时所有者、不启动 ACP、不附加客户端，也不回退到另一个工作区。

workspace_archived_session_export 宣告了 GET /workspaces/:workspace/session/:id/archive/export，这是从选定工作区的归档持久化存储中进行的仅限受信任用户的完整导出。它独立于 workspace_session_export 和 workspace_qualified_rest_core；客户端必须直接预检此标签。不同的路由可防止旧版守护进程忽略归档意图并返回具有相同 id 的活动转录记录。

workspace_session_live_state 宣告了 GET /workspaces/:workspace/sessions/live-state，这是选定工作区运行时实时会话的仅限受信任用户、仅内存快照，以及一个告知客户端何时需要进行完整持久化目录重载的内存目录版本。它独立于 workspace_qualified_rest_core：发布的守护进程可以在不实现此路由的情况下宣告更广泛的工作区 REST 功能，因此客户端必须直接预检此标签。该标签是无条件的，因为受信任的单工作区主进程可以通过 id 或 cwd 使用该路由；每个工作区的信任检查仍然适用于每次请求，并且该路由不会将宽松的不受信任次要工作区持久化目录读取策略扩展到实时桥接状态。该标签意味着端点存在；它并不承诺每个实时项都携带可选的 updatedAt 活动水印，这取决于生命周期。

workspace_session_live_state_batch 宣告了 POST /sessions/live-state。客户端在批量轮询之前预检一次，并为旧版守护进程保留单工作区路由。批量操作使用与单工作区路由相同的受信任、仅内存快照和目录版本语义。

可选的顶层 /capabilities 字段 sessionLiveStatePollIntervalMs 以毫秒为单位宣告守护进程范围的实时状态轮询间隔。它根据启动环境变量 QWEN_SESSION_LIVE_STATE_POLL_INTERVAL_MS 解析一次，独立于工作区环境覆盖。接受从 1000 到 2147483647 的整数值；缺失或无效的值使用 5000。Web Shell 对所有工作区实时状态轮询使用此提示，并且在来自旧版或不兼容守护进程的字段缺失或无效时，也回退到 5000。此字段不会改变路由的快照语义、立即本地/可见性刷新或完整目录轮询。SDK 客户端仍需负责自己的计时器。

slow_client_warning 涵盖 SSE 背压行为：(a) 当订阅者的实时帧积压或实时序列化字节积压超过 75% 满时，守护进程发出一个 slow_client_warning 合成事件流帧，每次溢出事件发生一次（在两个测量值均降至 37.5% 以下后重新武装）；(b) GET /session/:id/events 接受一个 ?maxQueued=N 查询参数（范围 [16, 2048]），用于针对大型回放环冷重连时预分配每个订阅者的帧积压大小。序列化字节上限由守护进程拥有（默认每个订阅者 2 MiB），仅限实时，且有意没有查询参数。守护进程范围的环大小由 --event-ring-size 控制（默认 8000，参见 #3803 §02）。旧版守护进程静默地缺乏警告/查询行为——在选择加入之前预检此标签。

typed_event_schema 宣告与 SDK 的 KnownDaemonEvent 架构匹配的守护进程事件负载。旧版守护进程可能仍会流式传输兼容帧，但 SDK 客户端应在假设类型化事件覆盖之前预检此标签。

client_heartbeat 宣告了 POST /session/:id/heartbeat。旧版守护进程返回 404；在发出周期性心跳之前预检此标签。

session_close 和 session_metadata 宣告了 DELETE /session/:id 和 PATCH /session/:id/metadata。旧版守护进程返回 404；在暴露关闭或重命名功能之前预检这些标签。

session_organization 宣告自定义会话组和置顶。它添加了 GET/POST/PATCH/DELETE /workspace/:id/session-groups、PATCH /session/:id/organization 以及选择性启用的组织列表视图 GET /workspace/:id/sessions?view=organized。当同时宣告 session_organization 和 workspace_qualified_rest_core 时，工作区限定的组织变更 PATCH /workspaces/:workspace/session/:id/organization 也可用。遗留变更仍然仅限于主工作区。旧版守护进程对变更/组路由返回 404 并忽略组织视图契约，因此 WebShell/SDK 客户端必须在显示匹配的分组或置顶 UI 之前预检这些标签。

session_archive 宣告 v1 目录状态归档 API：POST /sessions/archive、POST /sessions/unarchive 和 GET /workspace/:id/sessions?archiveState=active|archived。归档会话在取消归档之前无法加载或恢复。session_archive_idle_guard 宣告附加的 requireIdle 归档选项：拥有运行时在开始关闭之前立即检查确认活动工作处于空闲状态，否则保留活动转录记录。session_storage_conflict_repair 宣告下面描述的附加 resolveConflicts 请求选项和 resolvedConflicts 响应桶。

workspace_qualified_rest_core 在 /workspaces/:workspace/... 下提供复数核心 REST 路由。选择器首先解析为精确的工作区 ID，然后解析为规范化后的 URL 编码绝对 cwd。较新的单工作区守护进程即使在 multi_workspace_sessions 缺失时也会在 workspaces[] 中包含主运行时，允许客户端发现工作区限定路由所需的 ID；对于省略该数组的旧版守护进程，客户端应回退到 capabilities.workspaceCwd。信任状态和信任请求路由可用于已注册的未受信任工作区；限定的钩子状态读取 (GET /workspaces/:workspace/hooks) 也可用于已注册的未受信任工作区，因为它报告待处理的项目钩子信任决策，与限定的批准变更匹配；文件读取路由遵循现有的文件系统读取策略。已注册的未受信任次要工作区还暴露仅持久化的会话和会话组目录：这些读取操作不会附加到会话、启动 ACP 或合并实时桥接状态。除非单独的能力文档说明了更窄的策略，否则文件写入、目录变更和其他复数核心路由需要受信任的工作区：workspace_persisted_transcript（只读），或信任授予变更，无论是否广告 workspace_trust_grant，它都接受已注册的未受信任工作区——该标签仅报告信任热重载是否已连接，因此记录的决策可以在无需重启守护进程的情况下到达运行中的运行时；它从不报告路由是否被服务。未受信任的主工作区继续从复数目录和转录路由接收 403 { code: "untrusted_workspace" }；遗留的单数主路由保持其现有的兼容性行为。此标签涵盖核心文件、状态、设置、权限、信任、生命周期、MCP 控制、工具和技能切换、内存、工作区代理 CRUD 以及会话存储表面。它不涵盖身份验证、语音、扩展、ACP/WebSocket 传输、通道工作者路由或工作区限定的会话导出；请分别预检 workspace_session_export 或 workspace_archived_session_export。工作区信任不是 ACL：持有守护进程令牌的客户端可以读取此策略允许的每个已注册工作区表面。

workspace_qualified_voice 提供由受信任工作区运行时选择的语音路由：GET 和 POST /workspaces/:workspace/voice、POST /workspaces/:workspace/voice/transcribe 以及 WS /workspaces/:workspace/voice/stream。仅当多工作区运行时和共享 ACP/语音 WebSocket 监听器均启用时才提供此功能。选择器遵循与其他复数路由相同的 ID 或编码绝对 cwd 规则。对于 REST，未知选择器返回 400 { code: "workspace_mismatch" }，未受信任选择器返回 403 { code: "untrusted_workspace" }；WebSocket 升级拒绝会暴露相应的 HTTP 400/403 状态，而不使用结构化 JSON 信封。两种传输方式都不会回退到主工作区。遗留的 /workspace/voice、/workspace/voice/transcribe 和 /voice/stream 仍然仅限主工作区。客户端对所有限定语音模式使用 workspace_qualified_voice，并让选定的运行时报告配置特定的错误。遗留的 workspace_voice、workspace_voice_transcription 和 voice_transcribe 标签仅描述绑定到主工作区的路由，且不得隐藏限定的次要配置。

workspace_qualified_memory 提供工作区限定的托管内存路由：POST /workspaces/:workspace/memory/{remember,forget,dream} 入队任务和 GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId 读回它们。仅当 ACP HTTP 和多工作区运行时均启用时才提供此功能。选择器遵循与其他复数路由相同的 ID 或编码绝对 cwd 规则。每个已注册的工作区都有自己的任务通道；主工作区的限定通道与单数 /workspace/memory 表面是同一实例，因此在一个通道上入队的任务可以在另一个通道上读取。解析严格针对选定的运行时，没有主工作区回退：未知选择器返回 400 { code: "workspace_mismatch" }，未受信任选择器返回 403 { code: "untrusted_workspace" }，非活动或正在排空的运行时返回 503 { code: "workspace_runtime_unavailable" }。读取操作永远不会分配通道，因此轮询没有任务的工作区将返回 404 { code: "<kind>_task_not_found" }。任务 ID 的范围限于其通道，并且在重新配置工作区或替换运行时后不会存活；过期的 ID 返回 404，而不是数据丢失条件。当禁用 ACP HTTP 时，不提供此标签，并且非主工作区限定请求返回不可重试的 501 { code: "workspace_memory_unavailable" }，而主工作区限定路由通过本地拥有的通道继续工作。

session_lsp 提供 GET /session/:id/lsp，即供守护进程客户端使用的只读结构化 LSP 状态快照。旧版守护进程返回 404；在公开远程 LSP 状态之前预检此标签。

session_resources 提供 GET /session/:id/resources，即根据选定实时会话的配置构建的经过净化的技能和 MCP 快照的只读对。该路由范围限于实时会话所有者：它永远不会回退到主运行时，也不会从工作区状态推断会话的资源。嵌套的 skills 和 mcp 对象重用相应的工作区状态载荷，但省略了 MCP 身份验证、池、工作区预算和工作区发现错误增强信息。选定会话的 MCP 管理器报告的状态、发现和会计信息仍然存在。旧版守护进程返回 404；在显示会话资源目录之前预检此标签。

session_status 提供 GET /session/:id/status，即按 ID 列出的单个会话的实时桥接摘要。除了 clientCount 和 hasActivePrompt 之外，实时会话还暴露 isWaitingForPermission、isWaitingForUserQuestion、pendingInteractionCount 以及在失败回合后保留的 turnError。当下一个提示实际开始时，错误会被清除。在当前桥接中已结算运行回合的实时会话也携带 updatedAt，即实时状态路由下记录的相同活动水印；因为此路由直接返回桥接摘要，所以该值不会与持久化转录修改时间合并，并且可能早于会话列表报告的值。单会话状态响应和工作区会话列表都包含 turnError 和 pendingInteractions：渲染就绪的权限操作或 ask_user_question 问题，加上现有权限投票路由所需的 requestId 和可选选项。每个用户问题都有一个 answerKey；使用 answers 进行投票，例如 { "0": "Polling" }，以该值为键。仅持久化的会话省略运行时状态，因为不存在运行时。旧版守护进程返回 404；在轮询单个会话状态而不是扫描完整会话列表之前预检此标签。

session_info 提供 GET /workspace/:id/session-info 及其 /workspaces/:workspace/session-info 对应项。响应聚合持久化的活跃和归档会话计数，而不清水合列表元数据。这是一个显式的 O(n) 磁盘扫描，不得轮询；客户端应将 truncated: true 视为下限结果。

session_approval_mode_control、workspace_tool_toggle、workspace_skill_settings_toggle、workspace_skill_settings_batch_toggle、extension_batch_activation_v2、workspace_init 和 workspace_mcp_restart 通告了下文记录的变更控制路由。审批模式控制保留其非严格兼容性门控。其他控制项受操作员权限的严格门控：可信回环主请求、Bearer 认证请求或配对的本地控制请求可通过。未携带令牌且缺乏可信回环权限的主请求在到达严格门控时返回 401 token_required；缺失或无效的配置凭据以及未配对的本地控制凭据会被 Bearer 中间件更早拒绝，返回普通的 401 Unauthorized。缺少这些路由之一的守护进程返回 404。设置特定的 Skill 标签有所不同：来自已弃用标签代次的守护进程通告 workspace_skill_toggle 和 workspace_skill_batch_toggle，并在相同路径上提供其目录验证契约。已弃用的单目标路由可返回 HTTP 404 skill_not_found 或 409 skill_not_toggleable；已弃用的批量路由返回 HTTP 200，并将目录派生的失败置于 errors[] 中。在暴露其功能前预检每个标签，不要通过探测路由可达性来推断设置特定的 Skill 契约。路由路径和请求体未发生变化。

mcp_guardrails（问题 #4175  PR 14）涵盖 MCP 预算界面：GET /workspace/mcp 上的 clientCount / clientBudget / budgetMode / budgets[] 字段、每服务器单元格上的 disabledReason 字段，以及 --mcp-client-budget / --mcp-budget-mode CLI 标志。较旧的守护进程完全省略新字段；SDK 客户端在依赖 budgets[] 语义之前需预检此标签。注册表描述符还携带 modes: ['warn', 'enforce'] 以用于未来的功能模式暴露——目前，客户端从快照的 budgetMode 字段推断模式。在 enforce 模式下，服务器拒绝由 Object.entries(mcpServers) 声明顺序确定性地决定；未来的作用域优先级层（如果 qwen-code 采用）将把此行为改为“最低优先级优先”，以镜像 claude-code 的 plugin < user < project < local 约定。

作用域由能力驱动。 使用 mcp_workspace_pool 时，同一工作区运行时内的会话共享传输池和 WorkspaceMcpBudget，快照发出 budgets[0].scope: 'workspace'。不同的工作区运行时拥有独立的池。没有该标签时，每个 ACP 会话使用其遗留的 McpClientManager，快照发出 scope: 'session'，N 个会话可能各自消耗配置的容量上限。

workspace_file_read 涵盖文本/列表/统计/glob 工作区文件路由（GET /file, GET /list, GET /glob, GET /stat）。workspace_file_bytes 涵盖 GET /file/bytes，这是后来添加的，以便客户端可以针对 PR19 时代的守护进程预检原始字节窗口支持。workspace_file_write 涵盖哈希感知的文本变更路由（POST /file/write, POST /file/edit）。write 标签意味着路由契约存在；但这并不意味着当前部署允许匿名变更。Write/edit 是严格的变更路由，需要操作员权限；无令牌的受信任回环符合条件。workspace_file_upload 涵盖 POST /file/upload，即二进制入口路由：一个上限为 MAX_UPLOAD_BYTES (50 MiB) 的 application/octet-stream 主体被写入工作区且永不覆盖——占用的名称会自动编号（name (1).ext, name (2).ext, …）。它也是一个严格的变更路由。

workspace_file_delete 仅涵盖 POST /workspaces/:workspace/file/delete；不存在遗留主 /file/delete 路由。JSON 主体为 { "path": "relative/file.txt" }，成功返回 { "kind": "file_delete", "path": "relative/file.txt" }。这个严格变更路由永久移除所选受信本地工作区中的一个常规文件。目录和符号链接被拒绝；不支持的工厂（包括 SSH）返回 422。该能力描述协议支持，而非在每个工作区删除的权限。客户端还必须预检 workspace_qualified_rest_core。

当通告 workspace_qualified_rest_core 时，相同的文件界面也可在 /workspaces/:workspace/file、/workspaces/:workspace/file/bytes、/workspaces/:workspace/stat、/workspaces/:workspace/list、/workspaces/:workspace/glob、/workspaces/:workspace/file/write、/workspaces/:workspace/file/edit、/workspaces/:workspace/file/upload 和 /workspaces/:workspace/file/delete 处获得（最后一个路由另外需要 workspace_file_delete）。

workspace_directory_create 和 workspace_directory_delete 独立通告 POST /workspaces/:workspace/directory/create 和 POST /workspaces/:workspace/directory/delete。预检操作标签以及 workspace_qualified_rest_core；较旧的合格守护进程可能缺少这些路由。两者都是由受信活动选定本地运行时拥有的严格变更，没有主回退或遗留主对应物。在现有父级下创建是排他的；删除是永久且递归的。

同一标签还在 /workspaces/:workspace/agents 和 /workspaces/:workspace/agents/:agentType 处暴露工作区限定的项目代理 CRUD。这些复数路由仅读取或变更所选工作区的项目级代理；global 和 user 作用域请求返回 400 { code: "global_scope_not_supported_for_workspace_route" }。无工作区的 /workspace/agents 路由保留其现有的主工作区行为，并且仍然是用户级代理作用域的唯一 REST 界面。

extension_management_v2 在 /extensions/* 处通告用户级扩展目录和变更界面，以及在 /workspaces/:workspace/extensions/* 处的工作区激活投影。工件是全局的；工作区路由仅暴露投影读取、精确激活覆盖和运行时刷新。读取可能针对不受信的注册工作区，而激活、刷新和工作区限定的安装需要受信目标。慢速变更使用守护进程本地操作 /extensions/operations/:operationId；存储生成而非操作历史在重启和跨守护进程中具有权威性。发布的 workspace_extensions 能力和 /workspace/extensions/* 路由保持为主工作区兼容性适配器。客户端必须预检 extension_management_v2，并且不得从守护进程模式或 workspace_qualified_rest_core 推断它。

extension_git_credentials 在 POST /workspace/extensions/install 和 POST /extensions/install 上均通告经过身份验证的 HTTPS Git 安装。客户端必须在发送 URL 用户信息或 credentialPersistence 之前预检此标签；较旧的守护进程拒绝 URL 凭据。该标签描述后端协议支持，而非密钥链的可用性：存储模式在终端操作结果中报告选定的后端。

extension_local_path_install 在 POST /workspace/extensions/install 和 POST /extensions/install 上均通告守护进程本地扩展源。source 必须是存在于守护进程主机上的绝对路径。相对路径仍然不受支持，因此守护进程工作目录不能更改源标识或遮蔽 GitHub owner/repo 简写。现有的安装操作将扩展复制到托管存储中；它不会链接源。客户端必须预检此标签，因为较旧的守护进程拒绝本地源。

extension_batch_activation_v2 添加 PUT /extensions/activation 和 PUT /workspaces/:workspace/extensions/activation。两者均接受在 extensionNames 中的 1–100 个名称，在不区分大小写的情况下对其进行去重，同时保留首次出现的顺序，在一次生成中持久化更改的目标，并返回一个 202 操作句柄。设置 enabled 或 disabled 时，目标无需已安装：其名称会创建一个期望状态声明，当安装具有该名称的 Extension 时，该声明会被保留。全局路由接受 state: "enabled" | "disabled" 并写入 V2 defaultActivation；工作区路由还接受 "inherit"，并为选定的受信任运行时应用或清除精确覆盖项。inherit 不会声明未知名称，且全部为未知名称的清除操作会报告 updated: false。

extension_activation_explicit_refresh 意味着单条和批量激活操作在持久策略提交后完成，而不会直接刷新活动会话。需要立即应用的调用方应等待激活成功，然后提交同步的主工作区 POST /workspace/extensions/refresh（直接返回刷新计数）或选定工作区的异步 POST /workspaces/:workspace/extensions/refresh（返回单独的操作句柄）。这两种形式不可互换：异步操作在其完整运行时协调完成时记录已应用的生成版本，而同步路由不记录任何内容，因此生成协调器仍会将该工作区视为待处理状态，并在下一次通过时再次刷新其会话。能够针对特定工作区的调用方应优先使用异步形式。刷新失败不会回滚或降级激活结果。不具备此功能的守护进程已在激活过程中包含运行时刷新，因此兼容性客户端不得提交第二次刷新。独立的 30 秒生成协调器保持启用状态，通常会在下一次通过时应用已提交的策略；失败的协调将由后续通过重试。

Extension Management V2 线协议契约

所有路由均使用上述守护进程 Bearer 认证规则。对于 V2 变更路由，X-Qwen-Client-Id 是可选的；如果提供，它必须标识注册到该变更的一个目标工作区运行时的客户端。:extensionId 是小写 64 位十六进制的扩展身份。:workspace 首先解析为精确的工作区 ID，否则在规范化后解析为 URL 编码的绝对当前工作目录 (cwd)。

显式 Extension 刷新

能力标签：用于可选会话选择的 workspace_session_refresh。POST /workspace/extensions/refresh（主运行时）和 POST /workspaces/:workspace/extensions/refresh（选定运行时）均接受：

{ "sessionIds": ["session-1", "session-2"] }

省略 sessionIds 可保留完整的运行时刷新。提供的数组按请求顺序去重，且 [] 不刷新任何会话或引导缓存。ID 必须是非空字符串。无效的请求格式返回 HTTP 400；未知 ID（包括属于其他工作区的会话）在工作开始前返回 HTTP 404。会话所有权仅在解析后的运行时内部检查，没有主运行时回退机制。现有的认证、严格变更、工作区信任和客户端身份门控仍然适用。

主路由仍返回带有 { refreshed, failed } 的 HTTP 200；限定路由仍返回带有操作句柄的 HTTP 202。计数描述选定的会话。带有 sessionIds 的刷新不会推进工作区范围的已应用生成版本，即使选择覆盖了每个当前会话。自动完整协调保持不变，稍后可能会刷新其他会话。选择不会创建会话范围的激活策略：共享运行时缓存可以更改，且工作区事件仍保持工作区范围。

客户端必须在提供字段之前预检 workspace_session_refresh，包括空数组；较旧的守护进程可能会静默忽略它。不带该字段的现有调用不需要新的能力检查。

工作区资源状态

独立预检 extension_state。它仅支持 Skills；不隐含 MCP 资源管理。两个路由均选择注册的工作区运行时，从不回退到主运行时。GET 遵循现有的只读信任规则；PUT 需要受信任的工作区。

{
  "skills": [
    { "name": "review", "state": "enabled" },
    { "name": "deploy", "state": "disabled" }
  ]
}

PUT 接受 1–100 个条目，包括单元素批次。它在排队前拒绝格式错误的条目、不区分大小写的重复名称和不支持的组。所有名称必须属于已安装的目标 Extension，包括当前禁用的 Skills；无效目标会导致操作失败而不进行部分写入。一次锁定存储提交合并列出的覆盖项以应用于精确规范化的工作区。未列出的 Skills 和其他工作区被保留。没有设置写入、未来名称声明或父 Extension 的隐式激活。

GET 返回 v: 1, workspaceId, workspaceCwd, extensionId, name 和 skills。每个 Skill 都有 name, defaultEnabled, 可为 null 的 workspaceEnabled, effectiveEnabled, 以及可选的 disabledReason/lockedScope。清单中可选的 skillStates 提供默认值；缺失的值默认为启用。对于活动的父级，优先级顺序为：设置硬禁用、设置显式启用、设置默认禁用、工作区内部覆盖、清单默认值。内部禁用使用 disabledReason: "default" 且从不锁定设置。禁用或移除的父级无法通过 Skill 覆盖恢复。

set_extension_state 操作返回包含有序 result.resourceStates.skills 的 status: "updated"；result.states 保留其更新检查的含义。持久化状态并不能证明每个会话都已刷新。守护进程仅针对目标运行时（包括引导和实时会话）刷新 Skills 及其命令/模型上下文，而不会重启无关的 MCP/LSP/hooks。提交后的刷新失败会产生警告，但不会回滚状态。覆盖设置在重启和 Extension 更新后依然有效，并在卸载时被移除。客户端不得回退到 Skill settings API，因为该 API 会写入更高优先级的设置。

全局目录

全局目录响应如下：

{
  "v": 1,
  "generation": 12,
  "extensions": [
    {
      "id": "<64 lowercase hex characters>",
      "name": "demo",
      "version": "1.2.3",
      "installType": "npm",
      "defaultActivation": "enabled",
      "workspaceOverrideCount": 1
    }
  ]
}

当没有安装元数据可用时，省略 installType。defaultActivation 为 enabled 或 disabled。workspaceOverrideCount 排除存储的 inherit 条目。

工作区投影响应如下：

{
  "v": 1,
  "workspaceId": "workspace-id",
  "workspaceCwd": "/absolute/workspace",
  "trusted": true,
  "desiredGeneration": 12,
  "appliedGeneration": 11,
  "extensions": [
    {
      "extensionId": "<64 lowercase hex characters>",
      "name": "demo",
      "version": "1.2.3",
      "defaultActivation": "enabled",
      "workspaceActivation": "disabled",
      "effectiveActivation": "disabled",
      "activationSource": "workspace_override"
    }
  ]
}

对于继承，workspaceActivation 为 enabled、disabled 或 null。activationSource 为 default、workspace_override、legacy_path_rule 或 cli_override。desiredGeneration 是持久存储生成号；appliedGeneration 是控制器记录为已应用于该工作区运行时的最新生成号，可能会暂时滞后。

安装需要明确同意和初始激活：

{
  "source": "@scope/demo",
  "consent": true,
  "activation": { "scope": "user" },
  "ref": "optional-git-ref",
  "autoUpdate": true,
  "allowPreRelease": false,
  "registry": "https://registry.npmjs.org"
}

对于仅限工作区的初始激活，使用 { "scope": "workspace", "workspaceId": "target-workspace-id" }；目标必须存在且受信任。守护进程安装接受 GitHub、Git 和 npm 源。当宣传 extension_local_path_install 时，它们也接受在守护进程主机上存在的绝对路径。ref 不适用于 npm，ref 和 autoUpdate 不适用于本地源，registry 仅适用于 npm。ref、autoUpdate、allowPreRelease 和 registry 是可选的。

当宣传 extension_git_credentials 时，HTTPS Git 源可以包含 userinfo，例如 https://username:token@git.example.com/org/repository.git。credentialPersistence 仅在此类源下有效。它是 stored 或 one_time，省略时默认为 one_time。存储模式通过守护进程的混合密钥存储保存凭据，并在安装元数据中仅保留干净的仓库 URL，从而使 extension 保持可更新。一次性模式既不保存仓库 URL 也不保存凭据，并创建一个不可更新的 snapshot；此模式下拒绝 autoUpdate: true。在没有 URL 凭据的情况下提供该字段、提供无效凭据，或将凭据用于 npm、archive、local、SSH 或非 Git 源，将返回 400。

带凭据的安装响应和操作暴露 credentialPersistence，并可能将 credentialStorage 暴露为 keychain 或 encrypted_file。一次性操作省略 source；存储操作可能返回干净源。快照目录/状态条目省略 source，将 credentialPersistence 设置为 one_time，并报告 not updatable。更新以 extension_not_updatable 失败；不可用的存储密钥在网络访问前以 extension_credential_unavailable 失败。

全局和工作区激活 PUT 请求使用相同的主体：

{ "state": "enabled" }

state 为 enabled 或 disabled。Update、uninstall、check-updates、clear-activation 和 refresh 请求没有必需的主体。

批量激活请求使用 Extension 名称：

{
  "extensionNames": ["formatter", "review-tools"],
  "state": "disabled"
}

工作区批量操作也接受 "state": "inherit"。终端全局结果包含 name 和 defaultActivation；工作区结果包含 name、workspaceActivation（对于 inherit 为 null）和 effectiveActivation。格式错误的名称会拒绝请求；与现有 Store 标识冲突会导致原子性失败，而不进行部分提交。未知的 inherit 目标不会被持久化，因为清除覆盖设置不得制造默认激活声明或替换后续的安装同意。

每个接受的异步变更返回：

HTTP/1.1 202 Accepted
Location: /extensions/operations/<operation-id>
Retry-After: 1
Content-Type: application/json
 
{"accepted":true,"operationId":"<operation-id>"}

限定于工作区的变更使用相同的全局 /extensions/operations/:operationId 轮询路径。操作历史是进程本地的，仅保留有限数量的终端条目，并在守护进程重启时丢失；当操作 id 消失时，客户端必须重新读取目录或工作区投影并比较生成号。

操作快照具有以下形状：

{
  "v": 1,
  "operationId": "<operation-id>",
  "operation": "install",
  "status": "running",
  "phase": "preparing",
  "createdAt": 1750000000000,
  "updatedAt": 1750000000100,
  "source": "owner/repository",
  "name": "demo"
}

status 从 queued 过渡到 running，然后过渡到 succeeded、succeeded_with_warnings 或 failed。在运行时，phase 为 preparing、committing 或 reconciling。终端成功可能包含 result，其中 status 等于 installed、enabled、disabled、updated、uninstalled、checked 或 refreshed；协调结果还可以包含 refreshed、failed 和 error，而批量激活结果包含有序的 results。更新检查返回 result.states，以扩展名为键，值如 checking for updates、update available、up to date、not updatable 或 error。凭据和授权标头绝不会作为操作字段出现。

持久提交后若清理或运行时协调未完成，则不会报告为失败的变更。它返回 succeeded_with_warnings 并保留已提交的结果：

{
  "v": 1,
  "operationId": "<operation-id>",
  "operation": "uninstall",
  "status": "succeeded_with_warnings",
  "createdAt": 1750000000000,
  "updatedAt": 1750000000200,
  "result": {
    "status": "uninstalled",
    "name": "demo",
    "refreshed": 2,
    "failed": 0
  },
  "warnings": [
    {
      "workspaceId": "workspace-id",
      "workspaceCwd": "/absolute/workspace",
      "code": "reconcile_slow",
      "error": "Runtime reconciliation took 31000ms."
    }
  ]
}

警告 workspaceId 和 code 是可选的；workspaceCwd 和 error 始终存在。客户端应显示警告，刷新其目录/投影，并且不得盲目重试持久变更。

验证和授权失败是使用 { "error": "...", "code": "..." } 的同步 HTTP 错误（当存在稳定代码时）。重要情况包括 400 invalid_extension_id、400 invalid_extension_names、400 invalid_extension_name、400 invalid_extension_activation、400 workspace_mismatch、403 untrusted_workspace、404 extension_operation_not_found 和 429 extension_queue_full。安装验证还会因无效的 source/ref/registry 选项、缺少同意或缺少/无效的初始激活而返回 400。在 202 之后失败的变更在操作历史中保留表示，带有 status: "failed"、error 和一个可选的稳定 code；常见代码包括 extension_prepare_timeout 和 extension_conflict。操作的 HTTP 404 并不意味着回滚，因为操作历史不是持久的。

daemon_status 通告 GET /daemon/status，即下文记录的合并只读操作员诊断快照。

daemon_update 通告进程全局的 GET /daemon/update, POST /daemon/update/prepare 和 POST /daemon/update/restart 表面。

scheduled_task_gate 在 POST 和 PATCH /scheduled-tasks 上通告可选的 gate，并在任务视图上通告 gate 和 gateStatus。Gate 是拥有会话在每次触发时运行的 shell 命令，独立于模型：退出码为 0 且有输出则附带该输出交付触发结果，退出码为 0 但 stdout 无内容则跳过，非零退出码仅在 gate 开始失败时报告，而不是每次触发都报告。gateStatus.lastOutcome 是 quiet, delivered, failed 或 blocked。

• Gate 需要一个重复任务：带有 recurring: false 的 POST，或者设置 gate 的一次性任务或将带 gate 的任务设为一次性任务的 PATCH，会返回 400 gate_requires_recurring；已处于该状态的任务保留其他编辑。格式错误的 gate（在 POST 上为空、仅有注释、超过 2048 个字符、包含 NUL 字符或未配对的 UTF-16 代理项、类似 bash -c '…' 的 shell 包装器，或使用 & 后台化的任何部分）返回 400 invalid_gate。& 检查是词法性的且尽力而为；在不确定的情况下会拒绝（注释中的 &、heredoc 主体或 (( … ))），如果 gate 通过了检查但在后台部分仍持有 stdout 时以 stdout 无内容退出，则报告为 failed（bwrap shell 沙箱之外，其 PID 命名空间会在命令结束时终止该部分）。在 PATCH, gate: null 或 gate: "" 上清除 gate 及其 condition。
• 由 condition 保护的遗留任务在 PATCH 中拒绝任何 gate 键并返回 409 task_legacy_unsupported，因此客户端仅在更改时才发送 gate。
• 通过这些路由写入的 gate 不会从会话获得确认。它仅在相同命令的 monitor 调用无需询问即可运行的地方无人值守运行：在保存的 Monitor(...) 或 Bash(...) 允许规则下、作为只读命令、或在 auto 或 yolo 会话中。Deny 规则在所有模式下都会阻止它，plan 模式也会阻止它；被阻止的触发最终状态为 blocked。
• 客户端不得向没有此标签的守护进程发送 gate：此类守护进程会在 POST 上丢弃它，并对仅含 gate 的 PATCH 返回 400 empty_patch。

autofix_pr_watches 通告 GET /autofix-pr/watches（主工作区）和 GET /workspaces/:workspace/autofix-pr/watches（已注册的受信任工作区）。每个工作区根据 qwen autofix-pr status 列出的顺序响应工作区克隆的 /autofix-pr watches，这些 watches 从克隆的主工作树下的 watch 文件中读取（.qwen/tmp），每个文件打开时不跟随链接且不阻塞。不获取锁，不询问 GitHub，除了找到克隆的 git worktree list 外不运行任何 git 命令。答案是 { v: 1, available, root?, now?, watches, unreadable? }：当未找到工作区的 git 仓库（或 git 无法在那里运行）时，available 为 false 且无 watches，root 是克隆的主工作树，对于同一克隆的两个工作区而言相同。Watch 携带 status（/autofix-pr 设计的第 6.10 节）的字段，但不包括 thisSession, worktreePath, pushTarget, gitTrusted 和 worktreeWork；其 session 是拥有它的会话，可能不是此守护进程的会话。停止 watch 是该技能的职责（在拥有它的会话中执行 /autofix-pr stop <n>）；这些路由不改变任何内容。

条件标签。 这些功能标签仅在其部署开关、运行时接线或可用性条件处于活动状态时才被通告。标签存在意味着文档所述行为可用；不存在意味着要么是早于该标签的旧版 daemon，要么是当前 daemon 中该条件为假。目前：

Live Voice 在所有平台上默认使用 Web Shell 端点（realtime_voice_web, WS /live/web）。原生 macOS 主机是选择加入的：只有以 QWEN_SERVE_LIVE_NATIVE_HOST=1 启动的 macOS 守护进程才会通告 realtime_voice，在启用 Live 时注册 WS /live/host 并安装主机。如果没有它，/live/setup 报告 nativeHost: false 并带有不可重试的 install 错误，且 POST /live/setup/install 和 POST /live/setup/launch 回答 409 live_native_host_unavailable。

浏览器 Host 仅在用户与页面共享屏幕时响应 host.capture_visual，页面在其 hello 消息中通过 selfChecks.screenShare 报告这一点。共享是一个单独的显式行为——模型在回合中间请求，而 getDisplayMedia 需要用户手势——因此页面保持流连接并按请求抓取一帧。如果没有共享内容，它会立即响应 success: false，而不是让请求超时。

因为页面无法写入守护进程的文件系统，所以它只发送 JPEG。守护进程忽略浏览器租约报告的任何 screenshotPath，并将图像本身存储在其选择的名称下，位于原生 Host 写入的同一私有捕获目录中。原生 Host 仍然持久化其自己的 PNG 并传递路径，如前所述。

mcp_guardrails 不在此条件表中——它是一个始终开启的标签，只要二进制文件支持新的 /workspace/mcp 预算字段就会广告，无论操作员是否配置了预算。尚未设置 --mcp-client-budget 的操作员仍会获得新字段（带有 budgetMode: 'off', budgets: []）。

mcp_guardrail_events (issue #4175  PR 14b) 广告类型化的 SSE 推送事件，这些事件无需轮询循环即可呈现 MCP 预算状态跨越。两种帧类型到达 GET /session/:id/events：

• mcp_budget_warning — 在 reservedSlots.size / clientBudget 向上跨越 75% 时触发一次。仅在比率降至 37.5% 以下后重新武装 (MCP_BUDGET_REARM_FRACTION)。镜像 PR 10 的 slow_client_warning 滞回，但在管理器级别而非每个订阅者积压级别。载荷：{ liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' | 'enforce' }。在 warn 和 enforce 模式下均触发；在 off 下从不触发。
• mcp_child_refused_batch — 在每个 discoverAllMcpTools* 通过结束时触发，当有一个或多个服务器被拒绝时，并且在 readResource 惰性生成拒绝路径上作为长度为 1 的批次触发。载荷：{ refusedServers: [{ name, transport, reason: 'budget_exhausted' }, ...], budget, liveCount, reservedCount, mode: 'enforce' }。mode 是字面量 'enforce'，因为 warn 模式从不拒绝。

这两个事件都存在于每个会话的 SSE 重放环中（它们携带一个 id），因此使用 Last-Event-ID 重连的客户端可以通过它们恢复；GET /workspace/mcp 处的快照仍然是扩展断开连接后状态的真相来源。一旦广告即始终开启——没有条件切换。SDK 缩减器状态 (DaemonSessionViewState) 暴露 mcpBudgetWarningCount, lastMcpBudgetWarning, mcpChildRefusedBatchCount, lastMcpChildRefusedBatch 供想要简单滞后式 UI 的适配器使用。

路由

客户端可以功能检测 session_turn_status 并轮询 GET /session/:id/turns/current 或 GET /session/:id/turns/:promptId。这些路由需要活动的拥有 Session，并且从不加载或扫描另一个工作区。已结算的结果是从活动分支读取的最佳努力转录记录，具有有界扫描；prompt_not_found 意味着在活动队列、64 条目终端覆盖层或有界活动窗口中未找到结果。resultText 是最后一个工具边界后的原始最终父模型答案，在可选消息重写之前，可能缺失。超过 32,768 个 UTF-16 代码单元的结果包括 resultTruncated: true 和 resultCode: "RESULT_TEXT_TRUNCATED"。

GET /health

活性探测。默认形式如果监听器启动则返回 200 {"status":"ok"} —— 便宜，无桥接访问，适合高频 k8s/Compose 活性探测。

传递 ?deep=1 (也接受 ?deep=true 或裸 ?deep) 以进行守护进程范围的探测，该探测聚合每个管理工作区运行时的桥接 计数器，包括仍在排空的工作区（仅供参考，不是真正的活性检查）：

{
  "status": "ok",
  "workspaceCount": 2,
  "sessions": 3,
  "pendingPermissions": 1,
  "activePrompts": 1,
  "activeWork": true,
  "activeWorkReporting": "full",
  "activeWorkStaleMs": 4200,
  "connectedClients": 2,
  "channelAlive": true,
  "lastActivityAt": "2026-07-15T08:30:00.000Z",
  "idleSinceMs": 120000
}

sessions, pendingPermissions 和 activePrompts 是总和。activeWork 为真，当任何运行时有一个已接受但未结算的提示（包括 FIFO 等待中的提示）、正在运行的后台 Agent、排队/进行中的 Agent 终端通知、Session 管理的后台 shell 或工作流工作，或子拥有的 Session 回合。聚合 session 持有涵盖目标和 cron 处理、历史变更以及排队或运行的 Monitor 延续；前台提示仍由守护进程拥有。运行的 Monitors、后续建议和 shell 注册表不再能跟踪的外部进程保留在字段之外。它是会话范围的：尚未附加会话的通道级工作——飞行中的生成、待处理的恢复、MCP 发现或认证——不计入，因此 activeWork 可能在守护进程仍拒绝回收该通道时读取为 false。不要将此字段读作“守护进程是可回收的”；它仅描述会话拥有的工作。activeWorkReporting 说明该布尔值实际有多少得到担保：full 当每个活动会话都被来自报告所有必需类别的子项的新鲜报告覆盖时，none 当没有会话协商报告时，以及 partial 对于介于两者之间的任何东西——包括过时的快照或省略必需类别的协商子项。比三个报告间隔更旧的快照停止计为覆盖：它不是会话空闲的报告，因此会话回到读取为保留，就像子项从未报告一样。对于协商但不完整的子项，普通自动清理也被禁用；不理解 shell 或 session 的子项不能根据完整的当前谓词安全地授权条件关闭。完全不支持的历史子项保留遗留清理行为，显式关闭、杀死、关闭和通道退出仍然是强制操作。activeWorkStaleMs 是布尔值所依赖的最旧快照的年龄 在覆盖的会话中，当没有会话被覆盖时为 0；它是诊断性的，因为新鲜度已由守护进程分级到 activeWorkReporting（只有守护进程知道每个通道的协商节奏）。等级是在每个管理运行时上计算一次，而不是每个运行时然后组合——没有会话的运行时是空洞地完整，将其视为证据会让空工作区为另一个工作区的未报告会话担保。lastActivityAt 是最新的非空工作区活动时间，idleSinceMs 源自同一快照。channelAlive 意味着至少一个管理工作区通道是活动的；它并不意味着每个工作区都是健康的。connectedClients 和可选的 rateLimitHits 仍然是守护进程范围的计数器，而不是每个工作区的总和。

重启控制器应在以下情况下将守护进程视为繁忙：

const busy =
  health.activePrompts > 0 ||
  health.activeWork ||
  health.activeWorkReporting !== 'full';

丢弃第三项使 activeWork === false 与“没有子项告诉我任何信息”无法区分，这是对其采取行动不安全的一种情况。未知响应和失败的探测也必须阻止重启。activePrompts 仍然是一个独立的兼容性信号。

这些字段是观察缓存，而不是重启租约：即使是一个新鲜的、完全分级的、空的答案也描述了采样时刻，工作可以在之后立即开始。上述规则大大降低了错误重启的风险，但并未消除它——严格的安全需要一个准备重启栅栏，停止新工作准入，确认排空，然后才关闭。

⚠️ 深度探测是信息性的，并非真正的存活验证或原子回收租约。协商后的 ACP 子进程按协商的节奏发布通道范围的活动工作快照，守护进程将其新鲜度分级为 activeWorkReporting —— 但它绝不会因缺少报告而杀死通道，因为一个会话的沉默并不能证明进程已死亡。传输层存活检测和停滞 Agent 检测是独立的机制。connectedClients 统计 REST SSE 连接数，而非每个 ACP 传输层。对于空闲回收，请使用重复采样和优雅关闭；对于传输层和每工作区诊断，请使用经过身份验证的 /daemon/status。如果任何托管运行时 getter 抛出异常，深度健康检查将以 503 {"status":"degraded","reason":"aggregation_failed"} 失败关闭，而不是返回部分总计，并且守护进程日志会标识出失败的工作区运行时。在引导期间，在运行时注册表就绪之前，它返回带有 Retry-After: 1 的 503 {"status":"degraded","reason":"bootstrap"}。对于监听器存活检测，请使用默认的 /health 而不带 ?deep。

认证： 在非回环绑定以及回环通过 --require-auth 加固时必需。在普通回环绑定（127.0.0.0/8、localhost、::1、[::1]）上，/health 在 Bearer 中间件之前注册，因此 Pod 内的 k8s/Compose 探针无需携带令牌。在非回环（如 --hostname 0.0.0.0）或加固的回环上，该路由在 Bearer 中间件之后注册，并在没有有效令牌时返回 401 —— 否则未经身份验证的调用者可以探测任意地址以确认 qwen serve 的存在，这是一种低严重性的信息泄露，与端口扫描结合使用时危害更大。即使在普通回环豁免下，CORS 拒绝 + Host 允许列表仍然适用。

GET /daemon/update, POST /daemon/update/prepare, and POST /daemon/update/restart

这些经过身份验证的路由管理守护进程的 Qwen Code 安装，独立于所选工作区。它们始终使用 REST，包括来自具有 ACP 会话传输的 SDK 客户端的请求。daemon_update 能力通告了该协议；可用性由返回的状态确定。

GET 检查发布版本而不下载或激活它们。成功的检查缓存 15 分钟，错误缓存一分钟；?refresh=true 请求一次新的检查。并发检查共享一次查找。响应包含 state（available、up-to-date、installing、ready、restarting、unavailable 或 error）、canInstall、可选的 currentVersion 和 latestVersion，以及可选的 instructions 和 message。currentVersion 标识正在运行的守护进程，包括在更新准备就绪后。不支持的安装方法可以报告 available，并附带 canInstall: false 和手动说明。

自动更新需要真实的 CLI 生命周期，具备 POSIX process.execve、独立安装或运行已发布启动器的全局 npm/pnpm/yarn/bun 安装（包含 root 所有权的 npm 前缀，因为暂存从不写入全局前缀），以及允许 general.enableAutoUpdate 的操作员设置。嵌入式服务器、Windows、不支持的 Node 运行时和开发模式报告 unavailable。仅应用全局/系统设置；工作区设置无法启用安装。连接必须使用主监听器及其守护进程运行时令牌，或使用显式信任的回环部署且无需令牌。配对的浏览器和本地控制连接报告 unavailable，因为它们的凭据或监听器在重启后不会存活；它们的更新变更返回 403 update_connection_unsupported。

两个 POST 路由都需要严格变更门控的守护进程操作员权限，并且不接受任何参数。服务器选择发布版本、目标和启动器；客户端不能提供版本或命令。

• POST /daemon/update/prepare 启动后台下载并返回带有 state: "installing" 的 202。它不会更改当前活动安装。轮询 GET 直到状态为 ready；重复的准备操作共享同一操作，已准备好的更新返回 200。如果没有可用的自动更新，则返回 409 update_unavailable。
• POST /daemon/update/restart 需要一个已准备好的更新，否则返回 409 update_not_ready。它在激活更新之前响应 202 和 state: "restarting"，优雅地关闭守护进程，并用更新后的启动器替换进程。重复点击共享一次重启。响应后，守护进程重新解析当前发布版本一次：如果它比已准备好的版本更新且一键更新涵盖它，则暂存较新的版本并丢弃已准备好的载荷，因此长期运行的守护进程会落在当前的最新版本上，而不是首次准备时的最新版本上。较新的载荷在提交到被取代的版本之前会被保留，且该丢弃是尽力而为的：失败的丢弃会泄漏磁盘空间，但绝不会孤立较新的载荷或回退到可能半删除的载荷。latestVersion 随后报告较新的目标，而 state 保持为 restarting。失败的重新解析或暂存会改为应用已准备好的版本；由于注册表故障，点击永远不会卡在运行版本上。替换过程保留 PID、工作目录、CLI 选项、绑定端口和有效的守护进程令牌，清除旧版本固定，并且不重新打开浏览器。客户端轮询 GET 直到 currentVersion 发生变化，然后重新加载在请求更新时捕获的 URL 处的文档。因为暂存在 202 之后运行且可能需要几分钟，所以客户端从持续不可达开始测量其重启截止时间，而不是从点击开始：一个仍在响应的守护进程仍在工作。一个宽松的绝对上限（20 分钟）作为后备，防止守护进程保持可达但从未离开 restarting。它位于整个暂存链之上，而不是单个超时常量之上：独立存档下载依次尝试 OSS 和 GitHub，每个预算为五分钟 each，校验和与签名获取额外增加最多两分钟，因此一次重新暂存在激活之前可能花费约十二分钟进行下载和验证；托管的 npm 子进程上限为十分钟。每条放弃路径都在屏幕上保留一个可重试的条目，因为卡住的守护进程继续报告 restarting，而控件通常不显示此状态。一旦重启得到确认，restarting 就会粘滞直到进程被替换，因此一个可达的守护进程报告任何其他状态且 currentVersion 未变，意味着替换未落到新构建上；客户端停止等待，发布该稳定状态，并报告失败，而不是永远等待版本变化。该检查仅适用于在确认后 发起 的轮询：状态和重启请求是独立的，因此较早开始的轮询可以在之后传递重启前的快照，将其读取为稳定的守护进程会报告虚假失败并抑制成功更新仍欠用户的重新加载。独立启动器验证在关闭服务之前运行；失败的检查会让守护进程保持运行。在关闭开始后或进程替换期间发生的失败不保证能恢复。

Web Shell 会在后台自动检查并准备可用的受支持更新，并在准备好的更新就绪或可用更新包含手动说明时显示其版本旁边的更新按钮。在手动说明状态下，该按钮会打开一个包含检查所得说明的弹出框，且绝不会进行准备或重启。准备工作及就绪状态可在工作区运行时重载后保留。已准备的更新会固定其目标：轮询 GET（包括 ?refresh=true）会继续报告已准备的 latestVersion 且不会重新下载，因此跨多个版本保持运行的守护进程不会在后台频繁下载。只有重启操作会重新解析目标。普通的守护进程关闭会丢弃已下载的更新。激活失败会使守护进程继续运行并报告 error；在一分钟错误缓存过期后的下一次检查可以准备新的下载以供重试。禁用自动更新会在重启开始前移除就绪状态并清理下载内容。一旦重启正在进行中，它就不会受到干扰：当状态为 restarting 时，状态、准备和重启路由均直接返回而不查询操作员设置，且关闭清理操作为空操作，因此耗时数分钟的重新暂存过程不会导致其载荷被移除。在就绪状态下点击该按钮会显式重启整个守护进程并中断其活动会话。

GET /daemon/status

只读操作员诊断信息。与 /health 不同，这是一个正常的守护进程 API：它在 Bearer 身份验证和速率限制之后注册，包括在回环绑定上。查询参数：

• detail=summary（默认）仅读取内存中的守护进程状态。
• detail=full 还包含实时会话诊断信息、ACP 连接诊断信息、认证设备流计数以及工作区状态部分。
• 任何其他 detail 返回 400 { "code": "invalid_detail" }。

summary 有意不查询工作区状态方法、不启动 ACP 子进程也不生成会话。full 独立查询每个工作区部分；超时或异常仅将该部分标记为 unavailable 并添加一个 workspace_status_unavailable 问题。

响应格式：

{
  "v": 1,
  "detail": "summary",
  "generatedAt": "2026-06-16T00:00:00.000Z",
  "status": "ok",
  "issues": [],
  "daemon": {
    "pid": 12345,
    "uptimeMs": 3600000,
    "mode": "http-bridge",
    "workspaceCwd": "/repo",
    "qwenCodeVersion": "0.18.1",
    "daemonId": "serve-..."
  },
  "security": {
    "tokenConfigured": true,
    "requireAuth": false,
    "loopbackBind": true,
    "allowOriginConfigured": false,
    "allowOriginMode": "none",
    "sessionShellCommandEnabled": false
  },
  "limits": {
    "maxRegisteredWorkspaces": 256,
    "maxChannelControlWorkspaces": 25,
    "maxSessions": 32,
    "maxTotalSessions": 800,
    "maxPendingPromptsPerSession": 5,
    "listenerMaxConnections": 256,
    "eventRingSize": 8000,
    "compactedReplayMaxBytes": 4194304,
    "promptDeadlineMs": null,
    "writerIdleTimeoutMs": null,
    "channelIdleTimeoutMs": 0,
    "sessionIdleTimeoutMs": 1800000,
    "acpConnectionCap": 64
  },
  "runtime": {
    "sessions": { "active": 0 },
    "permissions": { "pending": 0, "policy": "first-responder" },
    "channel": { "live": false },
    "channelWorker": {
      "enabled": false,
      "state": "disabled",
      "channels": []
    },
    "transport": {
      "restSseActive": 0,
      "acp": {
        "enabled": true,
        "connections": 0,
        "connectionStreams": 0,
        "sessionStreams": 0,
        "sseStreams": 0,
        "wsStreams": 0,
        "pendingClientRequests": 0
      }
    },
    "perf": {
      "eventLoop": { "meanMs": 0, "p50Ms": 0, "p99Ms": 0, "maxMs": 0 },
      "promptQueueWait": {
        "count": 0,
        "meanMs": 0,
        "maxMs": 0,
        "lastMs": null
      },
      "pipe": {
        "inbound": { "count": 0, "totalBytes": 0, "maxBytes": 0 },
        "outbound": { "count": 0, "totalBytes": 0, "maxBytes": 0 }
      }
    },
    "activity": {
      "activePrompts": 0,
      "pendingPrompts": 0,
      "queuedPrompts": 0,
      "lastActivityAt": null,
      "idleSinceMs": null
    }
  }
}

多工作区响应还包括带有 { id, cwd, displayName?, primary, trusted } 的顶层 workspaces[] 行。如果未设置，则省略可选的显示名称，并且它仅用于展示目的；状态消费者必须继续使用 id 或 cwd 来关联运行时。

runtime.perf 是可选的。存在时，它仅报告守护进程事件循环延迟、提示 FIFO 队列等待样本以及守护进程子管道字节计数器；ACP 子事件循环延迟不包含在 /daemon/status 中。

如果任何问题具有错误严重性，则 status 为 error；如果任何问题具有警告严重性，则为 warning；否则为 ok。问题代码是稳定的，包括 session_capacity_high、connection_capacity_high、pending_permissions、acp_channel_down、preflight_error、mcp_budget_warning、mcp_budget_exhausted、rate_limit_hits、channel_worker_exited、channel_worker_partial_connect、channel_restore_failed 和 workspace_status_unavailable。在监听器就绪但完整运行时挂载之前的短暂窗口期内，/daemon/status 可能报告 daemon_runtime_starting；如果异步运行时挂载失败，它会报告 daemon_runtime_failed，而非状态运行时路由返回 503。

runtime.activity 报告守护进程范围内的提示活动。activePrompts 统计包含进行中提示的会话数量。pendingPrompts 统计所有已接受但尚未完成的提示，包括正在运行的提示和 FIFO 等待中的提示。queuedPrompts 统计已接受但尚未分发的 FIFO 等待中的提示。lastActivityAt 是最后一次提示开始/结束或会话生成的 ISO 8601 时间戳；如果守护进程自启动以来从未处理过任何活动，则为 null。idleSinceMs 在生成响应时根据 lastActivityAt 计算得出。

limits.memory 是累加的，并报告守护进程解析后的内存数据：一个必需的 enforced: false、一个 childHeap 对象（mode：off、observe 或 admit；admissionEnforced，仅对受管的 admit 为 true；maxConcurrentChildren 和 perChildCeilingMb，两者在 mode: 'off' 下均为 null，该模型不模拟任何内容——并且 perChildCeilingMb 另外在 modeled.minChildHeapMb 内无法建模任何分区时 null——要么池在该层级无法覆盖任何一个子项，要么一旦上限被限制为 modeled.legacyChildCeilingMb（即 floor(available / 2)），上限就会落在下限之下，因此在低于 1024 MB 的主机上会低于下限。它永远不会为 0，并且在这些情况下 maxConcurrentChildren 为 0，因为不模拟任何分区的主机是一个计算得出的答案，而不是缺失的模型；以及 refusals，即那些会超出模拟限制的衍生进程）、configuredBudgetMb、effectiveBudgetMb（配置的值，以解析后的 cgroup/主机内存为上限）、budgetSource（flag / derived）、availableMemoryMb、availableMemorySource（constrained / host）、insufficientMemory，以及一个包含 rootReserveMb、childPoolMb、minChildHeapMb、maxChildHeapMb 和 legacyChildCeilingMb（ACP 子项当前接收的上限的保守模型，可能低于实际值）的 modeled 对象。runtime.memory 另外还报告 registeredWorkspaces（注册计数——未移除的工作区条目，包括正在排空、转换或阻塞的条目；并非活跃子项计数）、activeAcpChildren（具有活跃且非死亡通道的由守护进程管理的 ACP 子项——包括正在转换或阻塞的条目，但排除已启动终止即使子项尚未退出的工作区；不包括通道工作器、MCP 后代或未附加的衍生预留）、childRssCoverage（active_children——每个具有活跃通道的 ACP 子项，这是 activeAcpChildren 计数的集合；较旧的守护进程发送 primary_only）、如下所述的 children 对象，以及一个包含 recommendedShareAtRegisteredMb（当没有注册工作区时为 null）和 recommendedShareAtActiveMb（当没有活跃子项时为 null）的 modeled 对象。每个份额以上限为旧版子项上限为界，并且仅在上限允许时以下限为最小堆大小为界——在小型主机上，上限位于下限之下，因此份额 × 数量可能会超过子项池。将份额视为建议性信息，而非池的分区。子项堆大小调整仍然是建议性的：没有任何子项衍生参数源自这些值。选择加入的 admit 强制执行模拟的并发子项数量，而默认的 observe 仅记录本应被拒绝的情况。runtime.memory.committedAcpChildren 计数受管的 ACP 预留和附加的子项，包括直到注册表释放前的终止中子项；当受管注册表不可用时，它为 null。childHeap 模拟 modeled.childPoolMb 的固定分区——每个子项将接收相同的 perChildCeilingMb，因此模拟的总数保持在池内，而不是像每个衍生份额那样累积。仅将 refusals 解读为准入压力：计数为 0 并不意味着应用该分区是安全的，因为子项在更大的源自主机的上限上运行，因此需要比 perChildCeilingMb 更多旧空间的工作负载在此处是健康的，只有在应用分区后才会失败。非零计数不一定意味着容量压力的另外两个原因：准入决策在终止子项退出前一直对其进行计数，因此在已达到 maxConcurrentChildren 的守护进程上，每次通道替换都会在重叠窗口期间记录一次拒绝；并且在太小而无法模拟分区的主机上，maxConcurrentChildren 为 0，因此 refusals 等于总的 ACP 衍生计数，insufficientMemory 是解释这一点的字段。在 admit 中，零槽位模型会导致启动失败。面临容量耗尽的完全受管守护进程可能会回收一个最近最少使用的、没有活跃会话或待处理工作的空 ACP，等待跟踪的释放，然后在衍生之前重试一次准入。已加载的会话受到保护；工作区注册和保存的历史记录得以保留。refusals 计数器计数被拒绝的准入尝试，包括初始拒绝随后成功回收的情况，而非最终用户可见的失败。容量耗尽时返回 REST HTTP 503，带有 code: "acp_child_capacity_exhausted"、maxConcurrentChildren 和 committedAcpChildren（不包括被拒绝的预留），不带 Retry-After。ACP JSON-RPC 使用 -32603，其中 data.errorKind 携带该代码、data.httpStatus: 503 以及相同的计数器。经验证的预调度独立创建回滚保留 standalone_creation_rolled_back、其会话 ID 和可重试性，并将容量代码和计数器嵌套在 capacity 下；不确定的创建结果保留其现有的恢复语义。客户端应停止自动容量重试，并保留草稿或选定的会话以供手动重试。在正常的 runQwenServe 路径上，预算在创建引导应用程序之前解析，因此 limits.memory 在引导窗口期间已填充。仅在未解析任何预算的路径（例如绕过 runQwenServeImpl 的直接嵌入）上，它才为 null。SDK 类型允许 null，因此正确的客户端能够应对。

runtime.memory.children 在该块内是附加字段，报告 childRssCoverage 命名的子进程的聚合 RSS：rssBytes（它们自我报告的 RSS 总和），sampled（产生读数的数量），以及 oldestReadingAgeMs（总和中最早读数的年龄，以便调用者知道各部分取样的时间间隔）。sampled 的分母是同级的 activeAcpChildren，不在块内重复；当 sampled 较低时，rssBytes 是下限而非总数。采样受活跃的 SSE/WS 监视器门控，因此针对无人流式传输的守护进程的状态请求报告 sampled: 0，即使有活跃的子进程——旁边的 activeAcpChildren 使该差距可见，且与 sampled: 0 一起的 rssBytes: 0 绝不表示测量值为零。当未采样任何内容时，以及当每个贡献者都是早于该字段的桥接时，oldestReadingAgeMs 为 null，因此它绝不表示“新鲜”。将该总和同时视为高估和低估：对每个进程的 RSS 求和会重复计算子进程共享的页面，而每个子进程只报告其自身进程，因此其 MCP 后代和每个通道工作器都缺失。这不是守护进程树的内存。由于报告 primary_only 的守护进程从不发送该字段，因此该字段在 SDK 镜像中是可选的。

runtime.memory.children.heap 在该块内是累加的，并报告每个 ACP 子进程生命周期内 V8 老年代的高水位标记，聚合方式为 最大值而非总和：peakOldGenerationBytes、peakLiveSetBytes、peakTotalHeapBytes、majorGcCount、majorGcMs、unclassifiedSpaceNames 和 reported。堆内存上限适用于每个子进程，且峰值是在不同时间达到的，因此总和无法回答任何问题；每个字段都是跨所有上报子进程的独立最大值，而不是单个子进程的画像，并且针对每个轴单独判断每个子进程的上限。reported 统计了有多少个 sampled 做出了贡献，当某些子进程早于这些字段存在时，该数值会更低。每个字节数值涵盖的是 老年代 —— 即 --max-old-space-size 实际限制的部分 —— 而不仅仅是 old_space，因为子进程可能在 old_space 仅为几兆字节时就耗尽上限，而 large_object_space 包含所有内容。peakOldGenerationBytes 是已提交字节数，随着分配给子进程的上限增加而上升，因此应将其视为工作负载需求的上界，而非其确切需求；peakLiveSetBytes 是经过主要 GC 后存活下来的部分，不随上限变化，这使得它能够表明某个子进程无法容纳一个上限；应将其视为上界而非确切的活跃集，因为 GC 条目是异步到达的，且在集合与读取之间分配的任何内容都会被计入。peakLiveSetBytes 在观察到主要 GC 之前等于 0，这是一种缺失状态而非测量结果。unclassifiedSpaceNames 是所有上报子进程无法分类的堆空间的并集；V8 在不同版本间会重命名和添加空间，未知空间会从总和中丢弃，而丢弃会导致计数不足——因此非空数组意味着字节数值是不完整的，不能被视为完整测量值。当没有采样的子进程报告任何数据时，整个对象为 null，绝不会是一个清零的对象；如果没有附加 SSE/WS 监视器，则根本不会进行采样，因此这是一种常规状态而非边缘情况。所有这些都是观察性的：这里没有任何内容用于确定子进程大小、拒绝生成或使 limits.memory.enforced 脱离 false。

runtime.memory.pressure 在该块内是累加的，并报告守护进程根进程自身的内存压力：mode（off / observe）、level（normal / soft / hard / critical）、source（rss / heap / unknown）、ratio，以及比率来源的六个原始数值 — rssBytes、rssRatio、availableBytes、heapUsedBytes、heapRatio、heapLimitBytes。ratio 是 rssRatio 和 heapRatio 中的较大者，source 指明它是哪一个；平局报告为 rss。availableBytes 以字节为单位表示 limits.memory.availableMemoryMb — 特意使用检测到的 cgroup/主机数值而非 effectiveBudgetMb，因为终止进程的是真实限制，而非操作员的策略数值。source: "unknown" 意味着两个分母都无法测量，绝不能解读为健康状态；level 在这种情况下仅为 normal，因为没有可供分类的内容。这些数值仅涵盖守护进程 根进程：它们是此进程自身的 memoryUsage()，因此子进程的增长不会影响它们。runtime.memory.children 单独报告这些内容，且这两个数值都不是进程树内存。两种模式都报告整个块；只有 observe 额外将无路径的 daemon_memory_pressure 警告提升到状态汇总中，因此 off 保持顶层 status 不变。两种模式下都没有补救措施。由于在 runtime.memory 出现之前发布的守护进程发送的块不包含该字段，因此在 SDK 镜像中该字段是可选的。

limits.maxRegisteredWorkspaces 是累加的，并报告解析后的用户注册上限（默认 256，可配置范围为 1 到 256）。limits.maxChannelControlWorkspaces 报告标准守护进程上独立的控制/恢复所有者上限为 25，即使通道被禁用也是如此。自定义控制器仅在强制执行时才通告该字段。这些字段存在于引导和就绪响应中；较旧的守护进程可能会省略它们。通道控制器在构建候选工作进程之前，使用 409 channel_control_workspace_limit_reached 拒绝超过其上限的过渡性所有者联合；初始启动时的联合若超过上限，则在发布监听器之前导致启动失败，因此没有 HTTP 表面。注册容量不决定 SDK 通道超时。

limits.maxTotalSessions 是累加的。null 意味着有效的全守护进程新会话上限被禁用。当解析后的注册容量（默认 256，可通过 QWEN_SERVE_MAX_WORKSPACES 或嵌入的 maxRegisteredWorkspaces 配置）超过 25 且省略 --max-total-sessions 时，标准守护进程使用固定的总数 800，即使只有一个启动工作区。在注册容量为 25 或更少的情况下，具有有限 maxSessionsPerWorkspace 的几个启动/恢复工作区通过 maxSessionsPerWorkspace * workspaceCount 基于相同的启动加恢复计数一次性推导有效总数；一个启动或恢复的工作区保留无限默认值。显式总限制（包括禁用的值）优先。后续的动态注册不会重新计算总数。直接 createServeApp 嵌入必须提供自己的共享准入策略。设置后，它限制整个守护进程的新会话创建，并使用现有的 session_limit_exceeded 错误形状加上 scope: "total" 报告总限制失败。

runtime.channel.live 报告守护进程内的 ACP 桥接通道。它不是通道适配器工作进程。守护进程管理的通道使用 runtime.channelWorker，其 state 是 disabled、starting、running、exited、failed 或 stopped 之一。当工作进程达到 running 然后退出时，/daemon/status 使守护进程保持在线并报告警告问题代码 channel_worker_exited。

从显式 qwen serve --channel ... 启动守护进程管理的通道工作进程仍然快速失败，并优先于持久化的启动设置。无标志启动会从每个受信任的已注册工作区恢复 serve.channels，每个工作区在其自己的工作区范围设置中贡献列表。恢复的名称形成一个选择，其所有者按常规方式解析，列出名称的工作区打破其他方面模糊的所有权平局。这种启动归属持续的时间与守护进程运行的时间一样长：PUT /workspace/channel 重新启用此类名称会以启动时的方式解析它，即使选择在中间已被停止。当非主要工作区贡献的名称无法解析时，会被丢弃并记录日志以标识它，因此一个工作区的过时条目不会阻碍其他工作区；主要工作区列出的名称仍会导致整体恢复失败，无论另一个工作区是否也列出了它。all 仍然仅限主要工作区：在其他任何地方都会被忽略并报告。

引导后注册的受信任非主要工作区也会恢复其自身的 serve.channels，加载通道运行时，并在没有其他因素占用时预留通道服务租约。该恢复：

• 每次守护进程运行发生一次 — 在工作区请求任何内容时立即记录 — 因此后续的移除和重新注册，或信任的重新实体化，不会撤销在此期间停止其中一个通道的操作员的操作；
• 不在显式 --channel 选择下发生，后续注册的工作区不会扩展该选择；
• 在 DELETE /workspace/channel 停止托管后不发生，直到 PUT /workspace/channel 再次提交选择或守护进程重启；
• 保持已提交的 all 选择不变；
• 在一次变更中将该工作区的名称添加到已提交的选中项，每次仅处理一个延迟恢复。与启动时丢弃无法承载的名称并保留其余名称不同，若某个名称无法归属到工作区，则该工作区的整个列表都不会被恢复，错误会按照下文所述进行记录并报告。

注册完全不需要等待通道控制。恢复操作在通道控制队列中排队，响应写入无需等待其完成；由注册或信任变更触发的、针对守护进程已托管通道的协调操作也是如此。因此，从未就绪的工作者只会延迟其后排队的通道工作，绝不会延迟其他注册或信任协调。另一方面，来自 POST /workspaces 的 201 并不意味着该工作区的通道已启动，也不意味着它拥有的已托管通道已完成重启；请阅读 GET /workspace/channel 以了解相关信息。

如果没有显式选择、启动时的 serve.channels 恢复，或上述类似的注册，通道运行时加载将保持惰性。

存储的启动名称必须非空，没有前导或尾随空格，且不包含不安全控制字符或不可见字符。无效条目会被单独跳过并按数组索引记录日志；启动过程不会将它们修剪为其他实例名称或重写设置。工作者参数使用 --channel=<value>，保留作为名称一部分的前导连字符。

如果存在无效的启动字段，或在工作者启动之前发生验证或租约错误，则跳过自动恢复，并记录标识 serve.channels 的日志，同时无关设置仍然生效。工作者启动失败允许守护进程在清理成功后继续运行。全局运行时启动超时和未确认的工作者停止遵循现有的启动失败路径；在工作者终止未确认期间，租约保持持有状态。通道管理报告持久化的启动设置和实际运行时状态。

某些守护进程未启动的 serve.channels 名称会被报告，而不仅仅是记录日志。此类名称永远不会加入已提交的选中项，因此没有任何工作者快照包含它。有三种情况会被报告：

• 配置了启动选择但工作者启动失败的情况，发生在保持守护进程在无通道状态下服务的启动路径上；
• 启动所有权解析器在将其归属到工作区时丢弃的名称，会在每个列出该名称的工作区上进行报告；
• 它们出现在两个地方：

它们出现在两个地方：

• /daemon/status 为每个工作区报告一个 channel_restore_failed 警告，列出每个通道及其错误。这是完整的表面信息，也存在于引导响应中，这是启动记录写入期间唯一存在的响应。每个工作区最多列出 64 个通道，每个名称限制为 128 个字符，如果列表更长则显示 and <n> more；
• 该工作区的 GET /workspaces/:workspace/channels 列出带有 runtime: { state: "error", lastError } 而不是 stopped 的通道，其中 lastError 是当工作者为该通道报告错误时适配器自身的启动错误，否则是尝试的错误。此表面信息基于工作区自身的通道设置范围构建，因此只能携带该范围定义的名称——任何已注册工作区未配置的名称，或其配置位于另一个工作区的名称，在此处没有行，仅在 /daemon/status 上报告。

其他导致 serve.channels 名称未被托管的情况仅在守护进程日志中诊断：因整个列表不可读或无效而丢失的名称，因主工作区选择了 all 而被丢弃的非主工作区列表，因已提交选中项为 all 而被跳过的延迟恢复，以及远程 (SSH) 工作区列表。请检查守护进程日志以获取这些信息。

报告持续存在直到通道被托管——由该工作区或由来自另一个工作区的后续恢复——直到其工作区不再注册，或直到操作员采取行动：对通道执行 POST 启动、停止或重启，PUT/DELETE /workspace/channels/:name，或改变选中项的 PUT/DELETE /workspace/channel。PUT /workspace/channels/:name/startup 不会清除它：它重写 serve.channels 而不提及失败的尝试。报告保存在内存中：重启后的守护进程再次恢复并报告该尝试的结果。错误文本经过凭据脱敏处理，并以守护进程日志渲染的方式限制长度。

工作者达到就绪状态后，意外退出会在有界策略内由 serve 监督程序重启：在 5 分钟窗口内最多 3 次重启尝试，退避时间分别为 1s、5s 和 15s。工作者每 15s 发送 IPC 心跳；如果 45s 内未观察到心跳，监督程序将视工作者为陈旧，杀死它，记录 staleHeartbeatAt，并使用相同的重启路径。

runtime.channelWorker 可能包含附加的操作字段：requestedChannels、pid、startedAt、exitCode、signal、error、restartCount、lastExitAt、lastRestartAt、nextRestartAt、lastHeartbeatAt、staleHeartbeatAt、startupFailures 和 startupFailuresTruncated。每次启动失败都包含 channel、phase（目前为 connect）、可选的适配器提供的 code，以及经过凭证脱敏处理的 message。当前工作进程代次最多保留 64 个失败记录；截断标志表示观察到了更多失败。code 仅用于诊断，并非稳定的跨适配器分类。restartCount 是该 serve 进程在生命周期内进行的重启尝试次数；如果运行中的工作进程的 restartCount > 0 符合预期且没有其他问题，则视为健康状态。如果运行中工作进程的 requestedChannels 包含在 channels 中缺失的名称，则报告 channel_worker_partial_connect。

在多工作区守护进程（--workspace 重复出现）上，runtime 还额外包含 channelWorkers[] —— 每个拥有该资源的工作区对应一个条目，每个条目都是一个带有 workspaceId、workspaceCwd 和 primary 注释的 channelWorker 快照。为了兼容性，channelWorker 仍保持为主工作区的快照。单工作区守护进程省略 channelWorkers[]。

守护进程管理的通道控制

channel_control 能力通告运行时选择资源。尽管其兼容路径使用单数形式的 /workspace 前缀，但该资源是守护进程范围的。运行时选择不会被持久化，也不会修改守护进程启动时的 --channel 选项。

GET /workspace/channel 返回一个不可变的管理器快照：

{
  "enabled": true,
  "selection": { "mode": "names", "names": ["telegram", "feishu"] },
  "pendingSelection": { "mode": "names", "names": ["telegram"] },
  "transition": "reconciling",
  "workers": [
    {
      "workspaceId": "primary-id",
      "workspaceCwd": "/work/primary",
      "primary": true,
      "enabled": true,
      "state": "running",
      "channels": ["telegram"],
      "pid": 1234
    }
  ]
}

禁用时，selection 为 null。pendingSelection 仅在变更期间存在。transition 是 idle、starting、reconciling、stopping 或 rolling_back 之一。

PUT /workspace/channel。相等的选择让健康的工作器保持原位，但会恢复一个工作器已停止或

{ "selection": { "mode": "all" } }

{ "selection": { "mode": "names", "names": ["telegram", "feishu"] } }

名称会被修剪并去重，但不进行排序；空名称数组无效。all 仍然仅限主工作区。从禁用变为启用返回 201；幂等的 PUT 或替换操作返回 200。响应为 { changed, replaced, partial, state }。相同的选择会保留健康的工作进程，但会恢复那些工作进程已停止或失败的相同选择。

DELETE /workspace/channel 受严格门控且具有幂等性。它返回 { changed, state }；成功状态为禁用。POST /workspace/channel/reload 也受严格门控，它会重新读取设置、重新解析工作区分组，并强制协调已提交的选择。禁用时它返回 409 channel_worker_not_enabled。channel_reload 能力仅在管理器具有已提交且可重载的选择时才会动态通告。

每次启用、替换、重载、停止和守护进程关闭都会进入一个 FIFO 生命周期通道。GET 请求不会等待该通道。有序选择未发生变化的工作区分组保持在线。替换失败时会尝试停止新启动的工作进程并恢复之前已提交的选择。客户端必须检查 rolledBack、rollbackError 和 state，因为清理或恢复也可能失败。守护进程在整个事务期间保持 channel-service PID 租约，直到确认所有相关子进程退出后才释放。

一旦请求开始，断开 HTTP 客户端连接不会取消生命周期事务；客户端可以重试

• 400 invalid_channel_selection，包含 channel_workspace_mismatch 和一个可选的凭据脱敏后的 ambiguous_channel_workspace
• 403 untrusted_workspace
• 409 channel_service_conflict、channel_worker_not_enabled 或 channel_control_workspace_limit_reached
• 500 channel_worker_stop_failed
• 502 channel_worker_start_failed，附带 rolledBack 和可选的凭据脱敏 rollbackError
• 503 daemon_draining

来自无令牌的主请求的严格写入，如果在到达门控时没有可信回环权限，则在控制代码运行前返回 401 token_required。缺失或无效的配置凭证以及未配对的本地控制凭证会更早地被拒绝，并返回普通的 401 Unauthorized。具有可信回环权限的主请求正常执行。一旦请求开始，断开 HTTP 客户端连接不会取消生命周期事务；客户端可以安全地重试相同的 PUT 请求。

对于 502 channel_worker_start_failed，响应还可能包含 startupFailures[] 和 startupFailuresTruncated。每次失败都会添加所尝试工作进程的可信 workspaceCwd。这些字段描述失败的事务，而 state 描述回滚后的当前状态；后续的 GET 请求不会保留失败的尝试记录。部分连接的工作进程反而返回成功，并在其工作进程快照中暴露其失败信息。显式 --channel 启动若没有连接适配器则会导致启动失败。由设置派生的启动失败会被记录日志，并在清理成功后允许守护进程继续运行，但需遵守全局运行时启动超时限制。若无法确认清理完成，则保留正常的启动失败行为和服务租约。

不带 --daemon-url 的 qwen channel status 继续读取 pidfile 元数据；带 --daemon-url 时读取 GET /workspace/channel。在重启窗口期间，serve 拥有的 pidfile 保持预留状态，但省略了 workerPid，以免客户端显示过期的工作进程。在多工作区守护进程上，pidfile 还携带一个附加的 workers[] 数组（每个工作区的 workspaceId / workspaceCwd / channels / 实时 workerPid），同时顶层的 channels（联合集）和 workerPid（主工作区）保持填充以兼容旧版读取器；单工作区守护进程保持原始的单一工作进程结构。工作进程的 stdout/stderr 被转发到守护进程日志中，其中的 bearer 令牌、敏感的工作进程环境变量值和代理 URL 凭证均已被脱敏。

工作区 Channel 管理

channel_management 能力通告工作区范围的 Channel 配置和运行时管理。单数形式的 /workspace 路由指向主运行时。/workspaces/:workspace 解析确切的已注册可信运行时，绝不会回退到主运行时。

只读发现使用：

• GET /workspace/channel-types
• GET /workspace/channels
• GET /workspace/channels/events
• GET /workspaces/:workspace/channel-types
• GET /workspaces/:workspace/channels
• GET /workspaces/:workspace/channels/events

GET .../channels/events 返回已解析工作区的 Channel 事件日志，格式为 { "events": [...], "truncated": boolean } 并包含 Cache-Control: no-store，以及一个可选的 channelLinkMeta 成员：这是一个从 channel 实例名称到非机密链接元数据（type 和 baseUrl，仅当配置为字符串时存在；对于 GitHub channels，还包括已解析的 webOrigin——即 Web UI 客户端应直接拼接而非从 API 根路径重新推导的来源）的映射。该元数据根据 channel workers 运行时使用的合并后的系统 + 用户 + 工作区设置进行解析——作用域本地的管理列表不包含在其他作用域中配置的 channels——并且过滤掉那些已解析的 cwd 不属于所查询工作区的 channels，因此一个工作区绝不会接收到另一个工作区的 channel 元数据。这使得客户端能够关联日志行（例如，GitHub PR 或 issue 引用），即使这些 channels 是从用户或系统设置继承而来的。当没有 channel 被解析时，该成员会被完全省略，且较旧的守护进程永远不会发送它；读取设置失败会降级为缺失该成员，而不是导致日志读取失败。每个事件记录了一个 Channel 执行的操作——它接受或跳过的入站消息（附带机器可读的原因：reason_filter、mention_required、duplicate、发送者门控拒绝、github_api_error）、处理失败且将再次读取的 GitHub 线程（failed 附带 github_api_error：GitHub 错误，或者本地错误，此时 channel 无法读写其自身状态或其中一个任务未完成）、发布结果、入站任务转换或轮询结果——并且绝不携带消息文本。如果 GitHub 轮询过滤出超过 20 条通知，则单独记录前 20 条，并额外记录一行 reason_filter，其 detail.filtered 计数剩余部分，从而防止固定的轮询游标用同一批次的重复项淹没日志。在持有游标期间，轮询再次读取到的评论在每个窗口内仅作为 duplicate 或 mention_required 记录一次，失败的线程在其在该窗口内的第一次失败轮询以及每第十次失败轮询时作为 github_api_error 记录（速率限制或凭据失效：其第一次及每第十次轮询），并在被跳过时记录一次。每个窗口一次的行最多跟踪 8,192 个键；如果某行的键不再适合，则在每次轮询时都记录该行。查询参数：limit（1-500，默认 100）、type（逗号分隔的 inbound、outbound、task、poll）、channel（每个实例名称重复该参数一次）以及 since（ISO 8601）。该路由不需要操作员权限。日志读取是异步且有界的：当前日志加上每个 Channel 的一个轮换文件，每个文件 256 KiB，每个请求 4 MiB，每个请求 32 个文件，最新的在前。链接元数据另外同步读取合并设置的无副作用快照（几个小的 JSON 文件，针对运行时的有效环境进行解析）；这是尽力而为的装饰，因此任何失败都会省略该成员而不是使日志读取失败。当记录限制或任何读取边界截断结果时，包括比每个文件尾部窗口更高的日志，truncated 为 true。尚无日志的工作区返回空列表；无法读取的作用域目录返回 5xx 而不是空列表。

目录使用 manageable: true 标记此管理 API 支持的类型。实例快照包含修订版本、脱敏的机密存在性元数据、启动状态和运行时状态；绝不返回字面机密。Channel 快照使用 Cache-Control: no-store。

字段描述符可以通过 properties 暴露嵌套对象元数据。数值描述符可以使用 exclusiveMinimum 表示开放下限，使用 maximum 表示包含上限。当客户端原样重发时，超出新声明边界的存储数字仍被接受，因此声明边界不会阻止对现有 channel 的无关编辑；客户端实际更改的值必须满足两个边界。字符串和机密描述符可以使用 multiline 向客户端请求多行文本区域；描述符类型仅允许在顶层字段上使用它。不渲染已广告字段类型的客户端必须保留其现有配置值，而不是强制转换或删除它，并且以单行控件渲染 multiline 字段的客户端必须逐字保留存储值，而不是写回其去除换行符的输入值。对象字段不能是必需的，嵌套属性不能是机密或环境可解析字段；这些管理协议仍然仅限于顶层。仅在写入中存在父对象时，才强制执行嵌套的 required 属性；省略父对象会使嵌套要求不被检查。写入会整体替换每个字段的存储值，因此保留对象意味着重发存储的对象；守护进程不会合并部分对象。

配置写入使用乐观并发控制和严格的操作员权限门控：

• PUT /workspace/channels/:name
• DELETE /workspace/channels/:name
• PUT /workspace/channels/:name/startup
• 每次设置变更都包含 /workspaces/:workspace/...。Upsert 请求包含一个

每个设置变更都包含 expectedRevision。Upsert 请求包含一个 config 对象，并可能包含显式的机密操作：preserve、replace 或 clear。Channel 配置不能选择在已解析工作区之外的工作目录。

运行时操作是严格门控的 POST 请求，指向 .../channels/:name/start、stop 或 restart。它们仅作用于已解析工作区所属的工作器。

配对管理仅适用于配置了 pairing 发送者策略或群组策略的实例：

• GET .../channels/:name/pairing-requests
• POST .../channels/:name/pairing-requests/approve 与 { "code": "..." }
• GET .../channels/:name/pairing-approvals
• DELETE .../channels/:name/pairing-approvals 配合 { "senderId": "..." } 或 { "groupId": "..." }

所有配对路由都需要严格的运营商权限并使用 Cache-Control: no-store。请求、批准和撤销的范围限定于选定的 Channel 实例和工作区。待处理请求包含类型化的用户或群组主体；群组请求还保留发起请求的发送者。批准快照包含 senderIds 和 groupIds，因为允许列表不持久化显示名称。撤销未知用户或群组返回 404 channel_pairing_approval_not_found。

通道交付和通知

channel_delivery 宣告支持即时尽力而为的投递。这是一种协议能力，而非 worker 健康信号。投递绝不会启动缺失的 worker、回退到另一个工作区、重试、持久化发件箱或重放历史通知。

两个路由都使用严格变更门控。限定路由仅解析

POST /workspace/notify
POST /workspaces/:workspace/notify
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "text": "service unavailable",
  "delivery": {
    "kind": "channel",
    "target": {
      "channelName": "dingtalk",
      "type": "user",
      "id": "platform-user-id"
    }
  }
}

两个路由都使用严格变更门控。合格路由仅解析已注册且受信任的工作区。成功状态为 200 {delivered:true,deliveryId}。delivered:true 表示 Channel 发送 Promise 已解决；它并不证明提供商接受、用户接收或读取回执。特定于提供商的响应验证以及跨 IM 适配器的一致错误原因语义不在本 V1 契约范围内。错误包括 400 channel_delivery_invalid、503 channel_worker_unavailable 或 channel_delivery_queue_full、504 channel_delivery_timeout，以及 502 channel_delivery_rejected 或 channel_delivery_failed。超时结果未知且不重试。有意不设单独的连接性测试端点：正常的 Notify 调用即为端到端测试。

成功的空 Prompt 最终状态省略了错误字段：

{
  "type": "channel_delivery_result",
  "promptId": "prompt-1",
  "data": {
    "sessionId": "session-1",
    "deliveryId": "prompt-1",
    "source": "prompt",
    "status": "failed",
    "promptId": "prompt-1",
    "code": "channel_worker_unavailable",
    "error": "Channel worker is not running."
  }
}

空的成功 Prompt 最终结果省略错误字段：

{
  "type": "channel_delivery_result",
  "promptId": "prompt-1",
  "data": {
    "sessionId": "session-1",
    "deliveryId": "prompt-1",
    "source": "prompt",
    "status": "skipped",
    "promptId": "prompt-1"
  }
}

source 是 prompt 或 scheduled；status 是 delivered、failed 或 skipped。skipped 表示符合条件的轮次已成功完成，但其最后一个无工具调用的助手响应块为空或仅含空白字符。守护进程消耗投递授权并发布事件，而不解析 Channel Worker。计划关联使用 taskId 和 firedAt。事件绝不包含目标 ID、消息文本、凭据或 webhook 密钥。

安全性：响应绝不包含 bearer 令牌、客户端 ID、完整的 ACP 连接 ID、设备流用户代码或验证 URL。两种详细级别都可能包含附加的 daemon.runId、daemon.logMode 和 daemon.logHealth。summary 省略守护进程日志路径和丢失详情；full 可能为经过身份验证的运营商包含 logPath、logIssues、logDroppedRecords 和 logDroppedBytes。降级文件日志记录会在正常状态汇总中添加不含路径的 daemon_log_degraded 警告。

GET /capabilities

{
  "v": 1,
  "protocolVersions": {
    "current": "v1",
    "supported": ["v1"]
  },
  "mode": "http-bridge",
  "features": [
    "health",
    "daemon_status",
    "capabilities",
    "multi_workspace_sessions",
    "..."
  ],
  "limits": {
    "maxRegisteredWorkspaces": 256,
    "maxChannelControlWorkspaces": 25,
    "maxPendingPromptsPerSession": 5,
    "maxSessionsPerWorkspace": 32,
    "maxTotalSessions": 800,
    "sessionRestoreTimeoutMs": 60000
  },
  "modelServices": [],
  "workspaceCwd": "/canonical/path/to/primary-workspace",
  "workspaces": [
    {
      "id": "stable-workspace-id",
      "cwd": "/canonical/path/to/primary-workspace",
      "primary": true,
      "trusted": true
    },
    {
      "id": "stable-secondary-workspace-id",
      "cwd": "/canonical/path/to/secondary-workspace",
      "displayName": "Payments Production",
      "primary": false,
      "trusted": true
    }
  ]
}

稳定契约：当 v 递增时，帧布局以向后不兼容的方式发生了变化。

protocolVersions 描述了守护进程可以支持的 serve 协议版本。current 是守护进程首选的协议版本，supported 是兼容集。需要特定协议的客户端应检查 supported；特定功能的 UI 仍应基于 features 进行门控。对 v=1 的附加内容：较旧的 v=1 守护进程会省略此字段，因此针对旧构建版本的 SDK 客户端应将其视为可选字段。

在 Stage 1 中，modelServices 始终为 []。 Agent 使用其单一默认模型服务，并且不会通过网络枚举它。Stage 2 将从注册的模型适配器填充此字段，以便 SDK 客户端可以构建服务选择器；在此之前，请勿依赖此字段非空。

workspaceCwd 是守护进程主工作区的规范绝对路径。使用它在 POST /session 上省略 cwd（路由回退到此主路径），并保持与旧的单工作区客户端兼容。对 v=1 的附加内容：§02 之前的 v=1 守护进程会省略该字段——针对旧构建版本的客户端在使用前应进行 null 检查。

workspaces[] 列出了所有已注册的运行时。较新的单工作区守护进程即使在没有 multi_workspace_sessions 的情况下也会包含主运行时，以便客户端可以发现工作区限定路由所需的稳定 id；较旧的守护进程可能会省略该数组。每个条目都是 { id, cwd, displayName?, primary, trusted, removable? }。displayName 仅用于展示，未设置时会省略。第一个/主工作区仍由 workspaceCwd 镜像反映；新客户端通过将该条目的 cwd 传递给 POST /session 来选择非主运行时。不受信任的工作区会被广播用于诊断，但在信任更改之前会以 403 untrusted_workspace 拒绝创建新会话。支持运行时移除的守护进程上存在 removable，且仅对于进程动态或持久化恢复的次级运行时为 true。

session_worktree_persistence_v1 意味着守护进程可以持久化并验证 Part 4A worktree 所有权。成功的 worktree 创建响应，以及子项在空闲时被移动或已经报告经过验证的 worktree cwd 的恢复响应，携带 worktree 元数据加上 worktreeState: "persisted-v1"。遗留的最佳努力恢复，或者触发而非停放恢复提示（suppressWorktreeContextRestore 关闭，因此路由要求桥接不进行延迟）并因此报告没有当前 cwd 的活动提示的冷恢复，可能仍然返回 worktree 而没有该证明。请求隔离的客户端必须预检此标签并验证每个响应；单独的 worktree 对象不是持久所有权的证明。

session_worktree_reset_v1 意味着守护进程支持 worktree 所有权转移：POST /session/:id/worktree-reset 将持久化的 worktree 会话的检出所有权移动到新的替换会话。恢复响应随之获得三种类型的 409 分类：worktree_session_superseded（会话的 sidecar 携带一个 supersededBy 链接——分类仅根据该链接决定，在任何标记读取之前，并且链接在标记翻转之前写入，因此正文中的 replacementSessionId 是需要验证的重定向而不是所有权证明：在中断提交状态下，它命名了一个不是标记所有者的会话，本身无法恢复，并被重试的重置回收）、worktree_marker_missing（检出标记缺失；重置任务以重新创建它——恢复重试不能这样做，因为没有恢复路径会写入标记）以及 worktree_reset_interrupted（之前的传输在飞行中崩溃，其 sidecar 链接一致；重试重置）。中断分类首先被检查：缺少标记但其 supersedes/supersededBy 链接一致的情况显示为 worktree_reset_interrupted，绝不会显示为 worktree_marker_missing。有关传输协议和失败分类法，请参见下面的路由部分。

工作区功能标签和 workspaces[] 是动态的。添加工作区的客户端必须在变更完成后再次获取 /capabilities；守护进程不会向缓存了较早响应的客户端广播能力变化。忘记持久化不会卸载活动运行时，因此该运行时在重启前仍会被广播。

GET /brand

Web Shell 的产品品牌标识，供希望白标 shell 的主机使用。从操作员设置范围中的 ui.brand 解析。受 web_shell_brand 功能标签门控；没有该路由的守护进程回答 404。

{
  "name": "QiuQiu Code",
  "logoDataUri": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E"
}

两个字段都是可选的，且 {} 是一个正常响应。 字段缺失意味着“使用客户端内置品牌”——Web Shell 渲染其自己的名称和内联 logo。客户端不得将空主体视为错误。

处理程序始终返回 200，即使配置了被拒绝的徽标。 文件缺失、符号链接、硬链接文件、目录、非 SVG 文档或超过 32 KiB 的内容都会导致响应体中没有 logoDataUri，且原因会作为 qwen serve: GET /brand: ui.brand.logoPath … 写入守护进程的 stderr。因此客户端无法区分“未配置品牌”和“操作员的徽标被拒绝”；面向操作员的信息渠道是守护进程日志。有一条建议比拒绝更宽松，共有两条：根元素 <svg> 没有可用的 viewBox 且没有正的、非百分比的 width/height（格式错误或零面积的 viewBox 视为不可用），浏览器可能在侧边栏固定大小下将其渲染为空白；以及前缀绑定的根元素其无前缀元素缺少默认命名空间绑定，这会使它们不可见。位于处理程序之前的中间件会在其运行之前做出响应——当需要 Bearer 认证但缺失时返回 401，当可选速率限制器启用时返回 429。正在排空的守护进程不会拒绝此路由：在排空期间速率限制器是宽松的，因此处理程序会持续返回 200，直到监听器关闭且客户端看到连接失败。在此路由上启动不是 503：在默认的延迟运行时路径中，请求会被 挂起 直到运行时就绪然后返回 200，因此较短的客户端超时可能会提前触发。带有 code: "daemon_runtime_starting" 的 503 仅在运行时就绪前就响应的配置（例如 --open）上到达此路由，并且是可重试的；带有 code: "daemon_runtime_failed" 的 503 是终止性的，直到守护进程重启，且不携带 Retry-After —— 不要重试它。

工作区设置永远不会贡献内容。 该路由使用 skipWorkspaceSettings 加载设置，因此仓库的 .qwen/settings.json 不能重命名产品或指定供守护进程读取并内联到每个已连接浏览器的文件。仅按此优先级读取系统默认值、用户和系统设置。出于同样的原因，每当占位符替换会更改品牌值时，守护进程的 stderr 上都会发出警告并拒绝该品牌值：替换从进程范围的环境变量中提取，而工作区的 .qwen/.env 或 env 块在启动时首先填充这些变量。无法解析的占位符（变量未设置）保持原样，因此拼写错误的变量显示为字面文本而不是静默回退。

logoDataUri 必须作为图像渲染，绝不能作为标记注入。 守护进程不会对读取的 SVG 进行清理。通过 img src 或 favicon href 加载的 SVG 无法执行脚本；注入到文档中的 SVG 可以。Web Shell 只将其分配给图像上下文，这一不变性使得缺少清理器是安全的。

进程全局。 该路由不接受工作区选择器和会话 ID：值源自用户全局配置，因此对于守护进程服务的每个工作区都是相同的。它在 bearerAuth 和速率限制器之后注册，并在 Web Shell SPA 回退之前注册，因此它对任何 Accept 头都响应 JSON。

POST /workspaces

注册额外的运行时工作区。路径必须是现有的、可访问的绝对目录，且不与另一个已注册的工作区重复或嵌套。除非客户端发送 persist: true，否则注册是进程本地的；客户端必须在请求持久化之前预检 persistent_workspace_registration。当宣传 workspace_display_name 时，请求还可以包含一个可选的 displayName。

当宣传 git_workspace_clone 时，相同的路由也接受 { "kind": "git", "url": "...", "target": "/absolute/new/path" }。这种形式要求一个尚不存在的绝对 target，启动异步克隆，不注册任何内容，并返回 202 { "kind": "git-workspace-clone", "jobId": "..." }。下面的 201 和 200 响应描述了同步的 cwd 和 scratch 形式；git 形式不注册任何内容，克隆进度和取消使用 GET/DELETE /workspace-git-clone-jobs/:jobId。

{
  "cwd": "/canonical/path/to/secondary-workspace",
  "persist": true,
  "displayName": "Payments Production"
}

新创建的运行时返回 201；将已激活的次要工作区提升为持久化返回 200。持久化成功包括 persisted: true：

{
  "id": "stable-workspace-id",
  "cwd": "/canonical/path/to/secondary-workspace",
  "displayName": "Payments Production",
  "primary": false,
  "trusted": true,
  "persisted": true
}

displayName 必须是修剪周围空白后长度不超过 256 个字符的字符串。空结果被视为无名称，内部 C0 (U+0000–U+001F) 或 DEL (U+007F) 控制字符会被拒绝。JSON null 不是创建值并返回 400 invalid_display_name；省略该字段以不提供初始名称。允许重复的显示名称。随进程本地注册提供的名称仅在该守护进程存续期间有效；persist: true 将其与持久化注册一起存储，以便在重启后可以恢复。对已持久化的工作区重复请求是幂等的，并且不会重命名它。

错误包括 400 invalid_path / invalid_persist_flag / invalid_persist_target / invalid_display_name, 409 workspace_exists / workspace_nested / workspace_limit_reached / workspace_registration_store_too_large, 500 workspace_registration_store_error / runtime_creation_failed, 以及 501 persistence_not_available / not_implemented。

PATCH /workspaces/:workspace

更新由工作区 ID 或 URL 编码的绝对 cwd 选择的活跃工作区资源。该端点目前仅支持显示名称元数据：

{ "displayName": "Payments Production" }

发送 { "displayName": null } 以清除名称。这里 null 是一个仅限更新的删除哨兵；非 null 值遵循与 POST /workspaces 相同的字符串规范化规则。响应是更新后的 { id, cwd, displayName?, primary, trusted, removable? } 工作区投影。运行时元数据始终更新。如果运行时具有匹配的持久化注册身份，则每个别名都通过现有的 schema-v1 注册存储原子性地更新；该端点从不创建或提升持久化注册。

不支持的字段会失败关闭而不是被静默忽略。错误包括 400 empty_patch / invalid_display_name / unsupported_field / workspace_mismatch, 409 workspace_registration_in_progress, 500 workspace_registration_store_error, 以及 503 daemon_shutting_down。

DELETE /workspaces/:workspace

移除一个可移除的次要运行时。选择器遵循复数工作区路由规则，并接受工作区 ID 或 URL 编码的绝对 cwd。可选的 JSON 主体是 { "force": boolean }；省略它表示请求非强制移除。

当冻结的运行时拥有会话、提示词、待处理的启动、ACP 连接、内存任务或工作区通道工作者时，非强制移除返回带有 activity 快照的 409 workspace_busy。发送 { "force": true } 请求终止这些资源。持久化移除是提交点：随后的清理是有界且尽力而为的，清理失败会被记录，逻辑移除仍然收敛而不是恢复运行时。成功的响应是：

{
  "removed": true,
  "workspaceId": "stable-workspace-id",
  "workspaceCwd": "/canonical/path/to/secondary-workspace",
  "forced": true,
  "persistedRegistrationRemoved": true,
  "activity": {
    "sessions": 2,
    "activePrompts": 1,
    "pendingSessionStarts": 0,
    "acpConnections": 1,
    "memoryTasks": 0,
    "channelWorkers": 0,
    "voiceSessions": 0
  }
}

立即繁忙的非强制请求返回快速的预排空活动快照。一旦排空开始，繁忙或成功响应包含在准入和 ACP 排空门关闭之后、清理开始之前拍摄的最终快照。错误包括 400 invalid_force_flag / workspace_mismatch, 409 workspace_busy / primary_workspace_removal_forbidden / static_workspace_removal_forbidden / workspace_removal_in_progress / workspace_registration_in_progress, 500 workspace_persist_failed / workspace_runtime_removal_failed, 501 workspace_runtime_removal_unsupported, 以及 503 daemon_shutting_down。

GET /workspace-registrations

列出此主工作区的持久化期望工作区集。当当前启动期间无法恢复存储目录时，条目仍可见并带有 active: false。只要其运行时正在排空，条目就保持 active: true 状态，因为在移除完成之前，运行时仍拥有活动资源。如果持久化注册包含可选的 displayName，则条目中也包含该字段。

{
  "schemaVersion": 1,
  "primaryWorkspace": "/canonical/path/to/primary-workspace",
  "entries": [
    {
      "id": "stable-registration-id",
      "cwd": "/canonical/path/to/secondary-workspace",
      "displayName": "Payments Production",
      "active": true,
      "persisted": true
    }
  ]
}

当未配置注册存储时返回 501 persistence_not_available，当存储无法读取时返回 500 workspace_registration_store_error。

DELETE /workspace-registrations/:id

忘记一个持久化的注册。这不会卸载活动运行时或终止其会话；restartRequired: true 意味着活动运行时将在下次守护进程重启时消失。

{ "removed": true, "active": true, "restartRequired": true }

返回 404 workspace_registration_not_found、500 workspace_registration_store_error 或 501 persistence_not_available。与其他变更路由一样，当启用守护进程身份验证时，此端点需要变更身份验证。

只读运行时状态路由

这些路由报告守护进程侧的运行时快照。它们是附加的 v1 路由，不会改变状态，也不会更改 serve 协议版本。工作区状态路由有意不仅仅因为客户端轮询 GET 路由就启动 ACP 子进程。GET /workspace/mcp 在守护进程空闲且未持有保留的 MCP 观察结果时，返回带有空快照的 initialized: false；如果之前的活动子进程曾回答过，空闲读取会重放该观察结果，并带有 source: "cache" 及其原始 initialized 值。相反，GET /workspace/skills 提供保留的守护进程观察结果或守护进程本地枚举，并且仅在不存在保留的观察结果且两个源均不可用（或冷读取被节流）时，才报告带有 errors 条目的 initialized: false（可重试的不可用性，而非空目录）——参见 GET /workspace/skills。GET /workspace/providers 由守护进程本地根据工作区设置和环境变量进行回答，因此不依赖于活动的 ACP 子进程，且 acpChannelLive 报告存活状态。其 initialized 在成功路径上为 true，当工作区设置或模型配置无法解析时，则为带有 errors 条目的 false；构造时没有守护进程本地提供程序构建器的守护进程会回退到活动的 ACP 快照，而守护进程本地的回答会省略运行时注册的模型。会话状态路由需要活动会话，并对未知 ID 返回 404 { code: "session_not_found", ... }。

运行时，其配置的启动策略可能独立地预热 ACP。

• workspace_mcp → GET /workspace/mcp
• workspace_skills → GET /workspace/skills
• workspace_providers → GET /workspace/providers
• workspace_acp_status → GET /workspace/acp/status
• workspace_env → GET /workspace/env
• workspace_preflight → GET /workspace/preflight
• session_context → GET /session/:id/context
• session_supported_commands → GET /session/:id/supported-commands
• session_tasks → GET /session/:id/tasks
• session_resources → GET /session/:id/resources
• session_monitor_tool_correlation → 来自 GET /session/:id/tasks 的监控条目包含 toolUseId 以用于转录到任务的关联
• session_status → GET /session/:id/status
• session_info → GET /workspace/:id/session-info 和 GET /workspaces/:workspace/session-info
• session_transcript → GET /session/:id/transcript
• workspace_persisted_transcript → GET /workspaces/:workspace/session/:id/transcript
• workspace_session_export → GET /workspaces/:workspace/session/:id/export
• workspace_archived_session_export → GET /workspaces/:workspace/session/:id/archive/export
• workspace_session_live_state → GET /workspaces/:workspace/sessions/live-state
• workspace_qualified_memory → POST /workspaces/:workspace/memory/{remember,forget,dream} 和 GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId

workspace_acp_status 将主工作区 ACP 通道的瞬时存活状态报告为 { channelLive: boolean }。处理程序不会创建通道，但访问运行时路由可能会首先启动延迟的守护进程运行时，其配置的启动策略可能会独立预热 ACP。快照不是租约：客户端必须让 Session 创建重新验证或启动通道。

ACP 预热

能力标签：workspace_acp_preheat。

POST /workspace/acp/preheat?timeoutMs=N 尽力初始化主工作区 ACP 通道。timeoutMs 默认为 5000，必须是正整数且不大于 60000。并发调用者和 Session 创建共享相同的桥接初始化。请求超时仅结束该 HTTP 等待；它不会取消共享初始化。

interface WorkspaceAcpPreheatResult {
  ready: boolean;
  channelLive: boolean;
  durationMs: number;
  reason?: 'timeout' | 'error';
  error?: string;
}

ready 始终等于 channelLive。实时响应省略 reason 和 error；否则 reason 为 timeout 或 error。durationMs 衡量的是当前的 HTTP 调用，而非该调用所加入的初始化过程的整个生命周期。操作超时或失败返回 HTTP 200。无效的 timeoutMs 返回 400，而身份验证、速率限制和延迟运行时故障保留其正常响应。

两个 ACP 工作区路由均为单数且仅针对主工作区。客户端不得将它们用于辅助工作区，也不得将任一响应解释为持久就绪保证。

通用状态单元格：

type DaemonStatus =
  | 'ok'
  | 'warning'
  | 'error'
  | 'disabled'
  | 'not_started'
  | 'unknown';
 
type DaemonErrorKind =
  | 'missing_binary'
  | 'blocked_egress'
  | 'auth_env_error'
  | 'init_timeout'
  | 'restore_timeout'
  | 'protocol_error'
  | 'missing_file'
  | 'parse_error';
 
interface DaemonStatusCell {
  kind: string;
  status: DaemonStatus;
  error?: string;
  errorKind?: DaemonErrorKind;
  hint?: string;
}

errorKind 是一个由 /workspace/preflight、/workspace/env 以及（最终）MCP 护栏共享的封闭枚举，以便 SDK 客户端可以按类别渲染补救措施，而不是解析自由格式的消息。最初的七个状态字面量来自 #4175；restore_timeout 是为会话恢复请求单独添加的。在出口探测落地之前，blocked_egress 保持保留状态。

状态载荷绝不暴露 MCP 环境变量值、标头、OAuth/服务账户详细信息、提供商 API 密钥、提供商 baseUrl / envKey、技能正文、技能文件系统路径、钩子定义或秘密环境变量的值。/workspace/env 仅报告白名单环境变量的 存在性；代理 URL 在传输前会被剥离凭据并简化为 host:port。

GET /workspace/mcp

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "discoveryState": "completed",
  "servers": [
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "docs",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
      "description": "Documentation server",
      "extensionName": "docs-ext"
    }
  ]
}

discoveryState 是 not_started、in_progress 或 completed 之一。transport 是 stdio、sse、http、websocket、sdk 或 unknown 之一。当发现成功时，省略 errors。

当产生观察结果的子进程处于活动状态时，source 为 "live"。当守护进程空闲且活动的子进程此前已响应时，响应会重放带有 source: "cache" 及子进程原始值（包括 initialized: true 及其服务器列表）的观察结果。缓存的观察结果仅在新的 MCP 发现开始时清除；回收子进程不会丢弃它，因此空闲的 GET /workspace/mcp 可能会报告当前没有活动子进程提供的目录。

MCP 客户端护栏（问题 #4175 ）。 当前守护进程通过四个附加字段和一个能力范围预算单元扩展了载荷：

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "discoveryState": "completed",
  "clientCount": 3,
  "clientBudget": 2,
  "budgetMode": "enforce",
  "budgets": [
    {
      "kind": "mcp_budget",
      "scope": "workspace",
      "status": "error",
      "errorKind": "budget_exhausted",
      "hint": "Raise --mcp-client-budget or remove servers from mcpServers config.",
      "liveCount": 2,
      "budget": 2,
      "mode": "enforce",
      "refusedCount": 1,
    },
  ],
  "servers": [
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "a",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
    },
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "b",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
    },
    {
      "kind": "mcp_server",
      "status": "error",
      "name": "c",
      "mcpStatus": "disconnected",
      "transport": "stdio",
      "disabled": false,
      "disabledReason": "budget",
      "errorKind": "budget_exhausted",
      "hint": "...",
    },
  ],
}

budgetMode 是 enforce、warn 或 off 之一。当未设置预算时，clientBudget 不存在。在宣传 mcp_guardrails 的守护进程上，budgets[] 始终是一个数组（当 budgetMode === 'off' 时可能为空）；较旧的守护进程完全省略该字段。当宣传 mcp_workspace_pool 时，该单元具有 scope: 'workspace' 并覆盖所选工作区运行时的共享池。当缺少该标签时，包括在 QWEN_SERVE_NO_MCP_POOL=1 下，遗留管理器发出 scope: 'session'。消费者必须容忍额外的无法识别的范围值。

每服务器单元上的 disabledReason 区分操作员禁用（'config' — disabledMcpServers 配置列表）与预算拒绝（'budget' — 已发现但因 enforce 模式从未连接）。拒绝由 Object.entries(mcpServers) 声明顺序确定性地决定。每服务器的 status: 'error', errorKind: 'budget_exhausted' 遮蔽了原始的 mcpStatus: 'disconnected'（后者为真但并非面向操作员的严重性级别）。

预算执行由能力驱动。使用 mcp_workspace_pool 时，一个工作区运行时内的会话共享传输层和一个 WorkspaceMcpBudget；不同的工作区运行时从不共享池或预算。没有该标签时，每个 ACP 会话的 McpClientManager 强制执行其自身的上限副本，快照代表该遗留会话视图。

检测预算压力。 两个表面，均在 PR-14b 后填充：

• 推送事件（通过 mcp_guardrail_events 宣传）：订阅 GET /session/:id/events 并通过 KnownDaemonEvent 缩小 mcp_budget_warning / mcp_child_refused_batch 帧。状态机在每次向上跨越 75% 阈值时触发一次（低于 37.5% 时重新武装）；在 enforce 模式下，拒绝在每个发现过程中合并一次。

• 快照轮询（通过 mcp_guardrails 宣传）：GET /workspace/mcp 并检查预算单元（budgets[0]）以及 mcp_workspace_pool 以确定其范围：

• budgets[0].status === 'warning' ⇔ liveCount >= 0.75 * clientBudget（匹配 PR 14b 推送事件将使用的滞回阈值）。

• budgets[0].status === 'error' ⇔ refusedCount > 0（一个或多个服务器在此发现过程中被拒绝）。

• budgets[0].status === 'ok' ⇔ 低于 75% 阈值且无拒绝。

建议轮询频率：与已经轮询 /workspace/mcp 的任何内容对齐；快照成本低廉，且预算单元不带来额外的发现成本。订阅推送事件的 SDK 客户端仍可从快照中受益，以获取长时间断开后的状态（SSE 重放环深度有限 — --event-ring-size，默认 8000 — 因此离线时间超过环覆盖范围的客户端回退到快照重新同步）。

GET /workspace/skills

主要和工作区限定的清单路由会在后台重新验证的同时立即返回保留的快照。启动频率被限制为每秒一次，从任务开始计时，并发读取器共享一个任务。暖后台重新验证在五秒后释放其槽位；超时允许重试，但不会取消观察或 ACP 工作。冷读取遵循 ACP 配置的请求超时（默认为十秒），如果 ACP 不可用，则随后进行守护进程本地枚举。它们不对任一来源施加后台截止时间。如果在开始后一秒内失败的冷读取，则该窗口的剩余部分会立即返回不可用状态；较慢的失败不会留下节流窗口，因此客户端需要自己的重试退避策略。晚到的成功后台观察可以在重试挂起期间发布，但不能替换稍后已开始并已发布的观察。失效的任务不能发布；成功的失效观察仍可以响应其原始调用者。显式失效会丢弃已知无效的清单并清除节流。在其超时前完成的成功的 ACP 预热也会使保留的清单失效，包括当子进程已经处于活动状态时，因此随后的读取可以看到该子进程。超时然后发现通道处于活动状态的预热也会报告 ready: true —— ready 始终等于 channelLive —— 但保留清单，因为启动可能仍未完成；下一次读取返回该保留数据，一旦一秒的启动节流允许，后台重新验证就会将其替换。技能删除绕过快照和节流，但需要一个新枚举的目录：它使用本地回退，并且绝不从保留的快照中响应。启用身份读取绕过快照和节流，等待新的观察结果，先使用本地回退，然后在两个来源都失败时使用保留的快照。

携带保留守护进程观察结果的清单响应还包含可选的快照元数据。直接配置/运行时状态读取、会话资源清单和较旧的守护进程省略此信息。被取代的成功冷读取在可用时返回更新的保留快照；否则，它返回其自己的未缓存观察结果而不带此元数据。只有没有错误的已初始化观察结果才能替换保留的快照：

{
  "snapshot": {
    "observedAt": 1792486800000,
    "ageMs": 1500,
    "stale": true,
    "refreshing": true
  }
}

observedAt 是成功观察结果的 Unix 毫秒级开始时间；ageMs 会在每次响应时重新计算，并保守地包含收集时间。stale 表示该观察结果至少已存在一秒。refreshing 报告重新验证是否占用共享槽位；超时的观察结果可能在槽位释放后仍会完成。读取失败、槽位超时以及运行时停止后的重放不会刷新时间戳；后续成功的发布将记录其自身的观察开始时间。客户端可以显示此年龄信息，但它不是文件系统修订版本，也不能证明每个会话都是最新的。如果不存在已初始化的快照且两个源均不可用（或冷读取被节流），则响应包含 initialized: false、一个 errors 条目，并且没有 snapshot 元数据。这是可重试的不可用状态，而不是空目录；有效的空目录具有 initialized: true。状态读取不会调用影响会话的技能刷新命令。已关闭或正在排空的工作区运行时会拒绝读取；保留的数据在子通道回收后依然存在，但在运行时退役后不再存在。

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "skills": [
    {
      "kind": "skill",
      "status": "ok",
      "name": "review",
      "description": "Review code",
      "level": "project",
      "modelInvocable": true,
      "userInvocable": false,
      "installedPath": "/home/alice/project/.qwen/skills/review/SKILL.md",
      "argumentHint": "[path]"
    },
    {
      "kind": "skill",
      "status": "ok",
      "name": "database-review",
      "description": "Review database changes",
      "level": "extension",
      "modelInvocable": true,
      "installedPath": "/home/alice/.qwen/extensions/alibabacloud-database-suite/skills/database-review/SKILL.md",
      "extensionName": "alibabacloud-database-suite",
      "extensionDisplayName": "Alibaba Cloud Database Suite"
    }
  ]
}

level 是 project、user、extension 或 bundled 之一。userInvocable（布尔值，可选）对于普通技能会被省略（意味着 true），仅当技能无法手动调用时才作为 false 出现。它不会限制下面描述的仅限设置的技能切换路由。modelInvocable 是独立的：false 意味着技能仍然可以手动使用，但对模型调用隐藏。installedPath 是指向技能的 SKILL.md 的现有绝对路径；守护进程按存储原样返回它，不单独解析符号链接或规范化它。当前守护进程会为每个技能发出此字段，而客户端必须容忍较旧的 v1 守护进程中缺少此字段的情况。技能主体、钩子、skillRoot 和其他技能配置仍然被排除在外。当发现成功时，errors 会被省略。

对于扩展拥有的技能，extensionName 是规范的清单名称，可以安全地用作所有者标识。extensionDisplayName 是一个可选的本地化展示值，可能不唯一。新客户端应显示 extensionDisplayName ?? extensionName；较旧的守护进程会省略展示字段。

重复读取从最后提交的工作区快照中提供服务，并定期针对子进程的内存缓存进行重新验证。稳态读取不会扫描技能目录或重新解析 SKILL.md 文件；冷守护进程本地回退可以从磁盘枚举。子进程确实会验证其扩展源未发生变化——即扩展目录的一个 readdir 加上每个条目的一个 stat、启用文件以及存储的激活状态——并且仅在它们发生移动时刷新，因此在守护进程外部安装或切换的扩展将通过重新验证被拾取，并在该重新验证发布后的后续读取中出现。暖读取始终返回保留的观察结果，即使它启动了后台工作。安全和裸模式会跳过检查，这与它们排除扩展的行为一致。

GET /workspace/providers

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "current": { "authType": "qwen", "modelId": "qwen3(qwen)" },
  "providers": [
    {
      "kind": "model_provider",
      "status": "ok",
      "authType": "qwen",
      "current": true,
      "models": [
        {
          "modelId": "qwen3(qwen)",
          "baseModelId": "qwen3",
          "name": "Qwen 3",
          "description": null,
          "contextLimit": 4096,
          "isCurrent": true,
          "isRuntime": false
        }
      ]
    }
  ]
}

模型按认证类型分组。提供商连接诊断位于 /workspace/preflight 的 providers 单元格中；环境预检位于 /workspace/preflight 和 /workspace/env（见下文）。当快照构建成功时，errors 会被省略。

GET /workspace/env

报告守护进程运行时的运行时、平台、沙箱、代理以及白名单密钥环境变量的存在性。始终从 process.* 状态获取答案——守护进程绝不会生成 ACP 子进程来服务此路由，无论 ACP 处于活动还是空闲状态，响应都是相同的。acpChannelLive 字段仅供参考。

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": false,
  "cells": [
    { "kind": "runtime", "name": "node", "status": "ok", "value": "22.4.0" },
    { "kind": "platform", "name": "darwin", "status": "ok", "value": "arm64" },
    {
      "kind": "sandbox",
      "name": "SANDBOX",
      "status": "disabled",
      "present": false
    },
    {
      "kind": "proxy",
      "name": "HTTPS_PROXY",
      "status": "ok",
      "present": true,
      "value": "proxy.internal:1080"
    },
    {
      "kind": "proxy",
      "name": "NO_PROXY",
      "status": "disabled",
      "present": false
    },
    {
      "kind": "env_var",
      "name": "OPENAI_API_KEY",
      "status": "ok",
      "present": true
    },
    {
      "kind": "env_var",
      "name": "ANTHROPIC_BASE_URL",
      "status": "disabled",
      "present": false
    }
  ]
}

单元格形状：

type DaemonEnvKind =
  | 'runtime' // name: 'node' | 'bun' | 'unknown'; value: process.versions.node
  | 'platform' // name: process.platform; value: process.arch
  | 'sandbox' // name: 'SANDBOX' | 'SEATBELT_PROFILE'; value optional
  | 'proxy' // name: HTTP_PROXY | HTTPS_PROXY | NO_PROXY | ALL_PROXY; value: redacted host
  | 'env_var'; // presence-only; value field is ALWAYS omitted
 
interface DaemonEnvCell extends DaemonStatusCell {
  kind: DaemonEnvKind;
  name: string;
  present?: boolean;
  value?: string;
}

脱敏策略。 kind: 'env_var' 单元格从不包含 value 字段；客户端只能看到 present: boolean。kind: 'proxy' 单元格将原始环境变量值通过凭证脱敏（redactProxyCredentials）处理，然后通过 URL 解析，因此传输线上只携带 host:port。NO_PROXY 经过脱敏处理后原样传递，因为它是一个主机列表而不是 URL。当前枚举的密钥环境变量白名单包括 OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、GOOGLE_API_KEY、DASHSCOPE_API_KEY、OPENROUTER_API_KEY 和 QWEN_SERVER_TOKEN。其他环境变量未被枚举，因此意外设置的密钥保持不可见。

GET /workspace/preflight

报告守护进程就绪检查。守护进程级别的单元格（node_version、cli_entry、workspace_dir、ripgrep、git、npm）始终从 process.* 和 node:fs 填充。ACP 级别的单元格（auth、mcp_discovery、skills、providers、tool_registry、egress）需要一个活动的 ACP 子进程——当守护进程空闲时，它们发出 status: 'not_started' 占位符。该路由绝不会仅为填充单元格而生成的 ACP；相应的单元格回退到 not_started。

空闲响应（无 ACP 子进程）：

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": false,
  "cells": [
    {
      "kind": "node_version",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "22.4.0", "required": ">=22" }
    },
    {
      "kind": "cli_entry",
      "status": "ok",
      "locality": "daemon",
      "detail": { "path": "/usr/local/bin/qwen", "source": "process.argv[1]" }
    },
    {
      "kind": "workspace_dir",
      "status": "ok",
      "locality": "daemon",
      "detail": { "path": "/canonical/path" }
    },
    { "kind": "ripgrep", "status": "ok", "locality": "daemon" },
    {
      "kind": "git",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "2.45.0" }
    },
    {
      "kind": "npm",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "10.7.0" }
    },
    {
      "kind": "auth",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "mcp_discovery",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "skills",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "providers",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "tool_registry",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "egress",
      "status": "not_started",
      "locality": "acp",
      "hint": "egress probing lands in PR 14 (#4175)"
    }
  ]
}

单元格形状：

type DaemonPreflightKind =
  | 'node_version'
  | 'cli_entry'
  | 'workspace_dir'
  | 'ripgrep'
  | 'git'
  | 'npm'
  | 'auth'
  | 'mcp_discovery'
  | 'skills'
  | 'providers'
  | 'tool_registry'
  | 'egress';
 
interface DaemonPreflightCell extends DaemonStatusCell {
  kind: DaemonPreflightKind;
  locality: 'daemon' | 'acp';
  detail?: Record<string, unknown>;
}

errorKind 语义：

• missing_binary — Node 版本低于要求，缺少 QWEN_CLI_ENTRY，ripgrep / git / npm 不在 PATH 中（对于可选二进制文件，这些是警告而非错误）。
• missing_file — boundWorkspace 不存在或不是目录；指向缺失或不可读文件的技能解析错误。
• parse_error — SKILL.md 解析失败，配置 JSON 格式错误。
• auth_env_error — validateAuthMethod 返回了非空的失败字符串，或者从提供商解析传播来的 ModelConfigError 子类。
• init_timeout — 桥接中的 withTimeout 拒绝（在等待 ACP 往返时实际发生超时）。通过 BridgeTimeoutError 类型类识别。注意：带有 connecting > 0 的瞬时 mcp_discovery warning 单元格不携带此类型——这是正常的握手进行中状态，与真正的超时不同。
• restore_timeout — 会话加载或恢复超出了专用的恢复预算。REST 响应为 504，且可重试；它与子进程初始化以及有界重放窗口限制不同。
• protocol_error — ACP extMethod 被拒绝，因为通道在请求中途关闭，或者工具注册表意外缺失。
• blocked_egress — 保留给 PR 14 (#4175)。PR 13 将 egress 单元格留为 status: 'not_started'。

如果桥接器在处理预检请求时无法连接到 ACP 子进程（例如请求中途通道关闭），则信封的 errors 数组包含一个描述该失败的 ServeStatusCell，并且单元格回退到 not_started ACP 占位符。仍然返回守护进程级别的单元格。

GET /workspace/tools

返回由主工作区的 ACP 子进程报告的工具目录。这是一个遗留的主工作区路由：它没有工作区选择器，不得用于推断非主运行时的工具。

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": true,
  "tools": [
    {
      "name": "ReadFile",
      "displayName": "Read",
      "description": "Read a file",
      "enabled": true
    }
  ]
}

当没有活动的 ACP 子进程时，路由仍然返回 200，其中包含 acpChannelLive: false、一个空的 tools 数组，以及可选 errors 数组中的一个 not_started 条目。意外的桥接失败使用标准的 500 桥接错误响应。TypeScript SDK 方法是 workspaceTools()；没有专用的能力标签，因此支持旧版守护进程的客户端应将 404 视为不支持。

工作区文件路由

遗留文件路由通过主工作区解析路径；/workspaces/:workspace/... 路由通过选定运行时的的工作区解析路径。响应使用相对于工作区的路径，并且在正常成功情况下绝不返回绝对文件系统路径。成功的文件响应包括：

Cache-Control: no-store
X-Content-Type-Options: nosniff

文件系统错误使用此 JSON 格式：

{
  "errorKind": "hash_mismatch",
  "error": "expected sha256:..., found sha256:...",
  "hint": "re-read the file and retry with the latest hash",
  "status": 409
}

errorKind 值包括 path_outside_workspace、symlink_escape、path_not_found、binary_file、file_too_large、untrusted_workspace、permission_denied、parse_error、hash_mismatch、file_already_exists、text_not_found 和 ambiguous_text_match。

GET /file

读取文本文件。查询参数：path（必需）、maxBytes、line、limit 和 cursor。守护进程拒绝二进制文件。超过 256 KiB 完整快照上限的文件需要至少一个显式窗口参数（line、limit 或 maxBytes）；如果没有这些参数，请求仍保持 file_too_large。这样的窗口是流式传输的，其返回的 UTF-8 内容保持在 256 KiB 的上限内。maxBytes 始终适用于解码后的 UTF-8 响应字节，包括当源在完整快照上限内使用另一种支持的编码时。

行偏移量是通过从文件开头扫描来解析的，因此如果到达某个窗口需要读取超过 8 MiB（MAX_TEXT_SCAN_BYTES），则该窗口也会被 file_too_large 拒绝。使用 GET /file/bytes 直接到达更深的偏移量。路由无法解码的大文本编码会返回 binary_file，而不是 file_too_large — 使用更小的窗口重试无济于事，而 readBytes 是同样适用于二进制文件的补救措施。

对于在完整快照上限内的文件，响应包括 hash，即整个文件原始磁盘字节的 SHA-256 摘要，即使 line、limit 或 maxBytes 返回了切片也是如此。大型部分窗口省略 hash，保留完整的 sizeBytes，设置 truncated: true，并在流在 EOF 之前停止时返回 originalLineCount: null。

使用 cursor 进行分页

需要 workspace_file_read_cursor 能力。如果有更多数据可供返回，响应将返回 hasMore: true，并且当可以推导出文件字节偏移量时，返回一个 nextCursor 令牌。将其作为 cursor 传回可在 O(1) 时间内恢复，而深层 line 偏移量需要从字节 0 开始扫描，并且在超过 8 MiB 时被拒绝。

GET /file?path=big.log&limit=500          → { content, nextCursor, hasMore: true }
GET /file?path=big.log&limit=500&cursor=… → next page

cursor 和 line 互斥（parse_error）— 两者都指定起始点。格式错误或过长的游标会导致 parse_error；如果文件已被替换或截断，则游标会导致 hash_mismatch (409)。追加操作不会使未完成的游标失效，这正是该功能存在的原因。

content 省略其最后一行的终止换行符，与其他所有读取操作一样，因此重新组装页面的客户端使用 \n 将它们连接起来。hasMore 不是 nextCursor 的重述：使用 limit 读取的小型非 UTF-8 文件有更多内容但没有可推导的字节偏移量，因此它报告 hasMore: true 并带有 nextCursor: null。当字节上限切断当前行时，游标也为 null，因为从该偏移量恢复将返回部分行。对于许多短行，降低 limit 直到页面在字节上限之前结束并返回游标。对于单个超大行，显式请求下一行（例如，从第 1 行开始时使用 line=2），然后继续使用游标；当需要完整的超大行时使用 GET /file/bytes。

{
  "kind": "file",
  "path": "src/index.ts",
  "content": "export {};\n",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "sizeBytes": 11,
  "returnedBytes": 11,
  "truncated": false,
  "hash": "sha256:...",
  "matchedIgnore": null,
  "originalLineCount": null
}

GET /file/bytes

从文件中读取原始字节而不进行解码。查询参数：path（必需）、offset（默认 0）和 maxBytes（默认 65536，最大 262144）。此路由支持对大型二进制文件进行有界窗口读取，而无需一次性读取整个文件。仅当返回的窗口覆盖整个文件时，响应才包括 hash。

{
  "kind": "file_bytes",
  "path": "assets/logo.png",
  "offset": 0,
  "sizeBytes": 3912,
  "returnedBytes": 3912,
  "truncated": false,
  "contentBase64": "...",
  "hash": "sha256:..."
}

GET /stat

返回一个主工作区路径的元数据。查询参数 path 是必需的。

{
  "kind": "stat",
  "path": "src/index.ts",
  "type": "file",
  "sizeBytes": 128,
  "modifiedMs": 1700000000123
}

type 是 file、directory、symlink 或 other。该路由使用工作区文件边界和上述常见的文件系统错误信封。TypeScript SDK 方法是 fileStat()。

GET /list

列出主工作区中的一个目录。查询参数 path 为必填项；includeIgnored=1（或 true）包含被忽略规则匹配的条目。响应上限为 2,000 个条目，当存在更多条目时设置 truncated: true。

{
  "kind": "list",
  "path": ".",
  "entries": [{ "name": "src", "kind": "directory", "ignored": false }],
  "truncated": false,
  "matchedIgnore": null
}

每个条目的 kind 为 file、directory、symlink 或 other。TypeScript SDK 方法为 dirList()。

GET /glob

匹配主工作区内的路径。查询参数 pattern 为必填项。可选的 cwd 缩小搜索范围，includeIgnored=1（或 true）包含被忽略的路径，maxResults 是 1 到 50,000 之间的整数（默认值为 5,000）。

{
  "kind": "glob",
  "pattern": "**/*.ts",
  "cwd": "",
  "matches": ["src/index.ts"],
  "count": 1,
  "truncated": false,
  "durationMs": 4
}

匹配结果相对于工作区。无效的查询值返回 400；工作区信任、包含关系、缺失路径和意外失败使用通用的文件系统错误封装。TypeScript SDK 方法为 glob()。

POST /file/write

创建或替换文本文件。这是一个严格的变更路由：无令牌的受信任回环主请求已被授权。到达网关但缺乏受信任回环权限的无令牌主请求返回 401 { "code": "token_required" }。配置令牌和本地控制凭据失败会在更早阶段以普通的 401 Unauthorized 拒绝；若启用 --require-auth，全局 Bearer 中间件会在路由运行前拒绝未认证请求。

字符，基于磁盘上的原始字节计算得出。

{
  "path": "src/new.ts",
  "content": "export const value = 1;\n",
  "mode": "create"
}

{
  "path": "src/existing.ts",
  "content": "export const value = 2;\n",
  "mode": "replace",
  "expectedHash": "sha256:..."
}

mode 必须为 create 或 replace。create 永远不会覆盖现有文件（409 file_already_exists）。replace 需要 expectedHash；缺失或格式错误的哈希值为 400 parse_error，过期的哈希值为 409 hash_mismatch。expectedHash 由 sha256: 加上 64 个小写十六进制字符组成，基于磁盘上的原始字节计算得出。

可提供 bom、encoding 和 lineEnding。默认情况下，替换操作会保留现有文件的编码配置文件；显式字段会覆盖它。二进制写入不在范围内。

守护进程在目标目录中写入一个随机临时文件，在支持的地方执行 fsync，在 rename() 之前立即重新检查当前哈希值，然后重命名到位。这防止了部分文件观察并序列化了对同一文件的守护进程发起的写入，但这不是跨进程的内核比较并交换（CAS）：外部编辑器仍可能在最终哈希检查和重命名之间的微小窗口内发生竞争。

{
  "kind": "file_write",
  "path": "src/existing.ts",
  "mode": "replace",
  "created": false,
  "sizeBytes": 24,
  "hash": "sha256:...",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "matchedIgnore": null
}

POST /file/edit

对现有文本文件应用一次精确的文本替换。这也是一个严格的变更路由，需要 expectedHash。

{
  "path": "src/config.ts",
  "oldText": "timeout: 30000",
  "newText": "timeout: 60000",
  "expectedHash": "sha256:..."
}

oldText 必须非空且恰好出现一次。无匹配返回 422 text_not_found；多个匹配返回 422 ambiguous_text_match。该路由保留编码、BOM 和行尾符，并在原子重命名之前立即重新检查 expectedHash。

允许对被忽略路径进行显式写入/编辑，因为已认证的调用者指定了该路径。成功响应和审计事件包含 matchedIgnore: "file" | "directory" | null。

{
  "kind": "file_edit",
  "path": "src/config.ts",
  "replacements": 1,
  "sizeBytes": 128,
  "hash": "sha256:...",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "matchedIgnore": null
}

POST /workspaces/:workspace/directory/create

需要 workspace_qualified_rest_core 和 workspace_directory_create、严格的变更权限以及受信任的活动本地工作区。正文：

{ "path": "src/new-folder" }

父目录必须存在。创建操作是排他的：现有的文件或目录返回 409 file_already_exists；最终的符号链接返回 400 symlink_escape。成功状态码为 201 { "kind": "directory_create", "path": "src/new-folder" }。SDK 方法为 WorkspaceDaemonClient.createWorkspaceDirectory(path, clientId?)。

POST /workspaces/:workspace/directory/delete

在相同的严格变更和受信任本地运行时策略下，需要 workspace_qualified_rest_core 和 workspace_directory_delete。正文：

{ "path": "src/old-folder" }

递归删除空或非空目录。工作区根目录、常规文件和最终符号链接会被拒绝；嵌套的符号链接条目在不跟随其目标的情况下被移除。缺失的目标返回 404 path_not_found。成功状态码为 200 { "kind": "directory_delete", "path": "src/old-folder" }。SDK 方法为 WorkspaceDaemonClient.deleteWorkspaceDirectory(path, clientId?)。

两个目录路由在解析选定工作区内的父目录时，都会保留词汇上的最终名称。路径不得以分隔符结尾；可疑的路径模式返回 400 path_outside_workspace，而格式错误的叶节点形状返回 400 parse_error。不支持的自定义工厂返回 422；SSH 工作区被 SSH 边界以 501 拒绝。未知、不可用、已移除或不受信任的所有者绝不会回退到主工作区。

删除操作是永久性的，失败可能会留下部分删除的内容。并发写入者可能导致 ENOTEMPTY，作为 503 io_error 返回；在写入者停止后重试相同操作。按路径加锁不会将目录与每个子写入操作序列化，并且通过可移植的路径检查无法使外部目录替换成为原子操作。允许对被忽略目录进行显式变更，并在适用时在审计事件中注释 matchedIgnore；创建记录 sizeBytes: 0。

GET /session/:id/context

{
  "v": 1,
  "sessionId": "<sid>",
  "workspaceCwd": "/canonical/path",
  "state": {
    "models": {},
    "modes": {},
    "configOptions": []
  }
}

对于顶级会话，state 镜像了 POST /session、POST /session/:id/load 和 POST /session/:id/resume 使用的相同 ACP 模型/模式/配置选项形状。带有 subagent. 前缀的虚拟会话 ID 针对其父运行时解析，并返回一个空的 state 对象。

GET /session/:id/supported-commands

{
  "v": 1,
  "sessionId": "<sid>",
  "availableCommands": [
    {
      "name": "init",
      "description": "Initialize the project",
      "input": null,
      "_meta": { "source": "builtin" }
    }
  ],
  "availableSkills": ["review"]
}

availableCommands 是 available_commands_update SSE 通知使用的相同命令快照。availableSkills 仅列出技能名称；客户端不应期望通过此路由获取技能主体或路径。

GET /session/:id/tasks

{
  "v": 1,
  "sessionId": "<sid>",
  "now": 1700000000000,
  "tasks": [
    {
      "kind": "agent",
      "id": "agent-1",
      "label": "reviewer: check failure",
      "description": "check failure",
      "status": "running",
      "startTime": 1699999999000,
      "runtimeMs": 1000,
      "outputFile": "/tmp/agent-1.jsonl",
      "isBackgrounded": true,
      "subagentType": "reviewer"
    },
    {
      "kind": "agent",
      "id": "agent-2",
      "label": "general-purpose: run the failing test",
      "description": "run the failing test",
      "status": "running",
      "startTime": 1699999999500,
      "runtimeMs": 500,
      "outputFile": "/tmp/agent-2.jsonl",
      "isBackgrounded": false,
      "subagentType": "general-purpose",
      "parentAgentId": "agent-1",
      "parentName": "reviewer",
      "depth": 1
    }
  ]
}

此路由是一个只读的带外快照。它有意不作为提示，可以在会话流式传输期间查询。响应仅包含来自代理、Shell 和监控任务注册表的白名单元数据；控制器、计时器、偏移量、待处理消息和原始注册表对象永远不会暴露。

由另一个子代理生成的代理任务（嵌套子代理，受 maxSubagentDepth 限制）包含三个可选的血统字段：parentAgentId（生成该任务的代理任务的 id）、parentName（生成该任务的代理的 subagentType，在注册时捕获，因此即使父级从注册表中被驱逐也能保留），以及 depth（基于 0 的启动深度；0 = 由顶层会话生成）。由顶层会话启动的代理会省略 parentAgentId 和 parentName；客户端应将这三个字段视为可选字段，并在缺失时回退到扁平列表。

GET /session/:id/tasks/:taskId/runtime

单个 Shell 任务的按需详细信息。GET /session/:id/tasks 仅包含生命周期事实；此路由读取捕获的输出文件并探测进程树，因此打开的详情面板会单独请求这些信息。

ACP 方法是 _qwen/session/task_runtime，带有 sessionId 和 taskId 参数。两种传输方式都会解析活动会话所有者；ACP 还要求连接拥有该会话。

路径的 taskId 会根据会话自身的 Shell 注册表进行解析；调用者永远不会传递文件路径。

{
  "v": 1,
  "sessionId": "<sid>",
  "taskId": "bg_0123abcd",
  "runtime": {
    "memoryBytes": 104857600,
    "outputBytes": 65536,
    "outputModifiedAt": 1700000000000,
    "outputTail": "ready in 120ms\n",
    "outputTailTruncated": true
  }
}

当任务未知、已被驱逐或不是 Shell 任务时，runtime 为 null。memoryBytes 是 Shell 进程树的常驻集，仅在任务运行时采样；共享页面每个进程只计算一次，容器沙箱可能仅暴露包装器进程。outputTail 的上限与完成通知使用的 8 KiB 限制相同，且 outputTailTruncated 标记从文件中间开始的尾部。当文件无法读取时设置 outputError；成功部分中的字段仍可能存在。

POST /session/:id/tasks/:taskId/workflow-action

控制工作流运行，或启动新运行。ACP 方法是 _qwen/session/tasks/workflow_action。

{
  "action": "run-script",
  "script": "export const meta = { name: 'daily-audit', description: 'Audits yesterday' }\nreturn await agent(args.question)",
  "args": { "question": "which tables grew?" },
  "sourceRef": { "id": "definition-7", "revision": "rev-3" }
}

taskId 的名称取决于操作：

args、sourceRef 和 script 仅由 run-saved 和 run-script 读取。args 绑定到脚本的 args 全局变量，可以是任何 JSON 值；sourceRef 是调用者自己的 {id, revision}，记录在运行、其日志及其快照中；script 是源 run-script 运行的内容，且为其所必需。重试或重新运行会重放原始运行自身的 args 和 sourceRef —— 这就是使其成为同一运行的原因 —— 因此这些字段与控制操作一起被忽略。

已启动的运行属于会话所有：它在后台运行而无需审批提示，其完成状态会到达会话的完成通道。之后它像任何其他运行一样是一个 retry/rerun 目标。

retry 和 rerun 也接受从历史记录恢复的运行（GET /session/:id/tasks 中的 isHistorical），例如守护进程重启中断的运行：运行从其快照的脚本、args 和 sourceRef 重新开始，并在发送操作的会话中注册并向其报告完成状态。retry 在相同的运行 ID 下恢复运行的日志，适用于没有进程仍在运行的 failed 运行；rerun 从任何已完成的运行开始一个新的运行 ID。携带 argsOmitted 的历史条目因 args 过大而无法保留而启动，因此这两种操作都不适用于它。在 args 被保留之前写入的快照也不适用，因为它既不携带 argsOmitted 也不携带 argsRecorded：运行的日志以其 args 的哈希值为键，因此重启一个其 args 无法通过历史命名的运行将不会重放任何内容并会重新调度每个代理。这两种拒绝都是 workflow_args_unavailable，且 GET /session/:id/tasks 在条目上将两者都报告为 argsUnavailable，以便客户端可以隐藏这两个操作，而不是通过调用发现拒绝。argsOmitted 作为原因保留在其旁边，供想要说明具体原因的客户端使用。args 本身绝不会发送到网络上。

run-script 不传递定义名称，因此运行由脚本自身的 export const meta 标记 —— 编译后的脚本应声明一个，否则运行只显示其 ID。

对于已启动的运行，响应为 {"changed": true, "status": "running", "taskId": "<runId>"}；对于生效的控制操作，响应为 {"changed": true, "status": "<status>"}；对于未发生任何情况，响应为 {"changed": false}：工作流对会话不可用（禁用、裸模式、不受信任文件夹）、工作区不受信任、保存的工作流名称未知、运行 ID 未知，或者在相同的 taskId 下已有另一个启动正在进行。仅重叠的启动会被去重：在一个 taskId 下的两个并发 run-script 调用只会启动一个运行。一旦该启动返回，键即被释放；再次提交它可以启动另一个运行，即使第一个运行仍处于活动状态。该键不提供丢失响应后的重试幂等性。

被拒绝的参数是一个 400（在 ACP 上为 -32602），而不是已启动的运行：未知的 action、没有 script 的 run-script、不是非空字符串的 {id, revision} 的 sourceRef，或因无效语法或确定性违规而在启动前被拒绝的脚本。工作流启动输入错误携带 workflow_invalid_params 并保留拒绝消息。

四种拒绝来自运行存储的状态而非请求。每种在 ACP 上都是 -32602，携带其 errorKind 和其 data.httpStatus。其中三种是 409；第四种 workflow_not_recorded 是 503，因为什么都没启动且同样的调用可以简单地再次执行：retry 在运行开始前记录其正在再次运行 —— 该记录可防止其他进程第二次启动它 —— 但该记录无法写入。

workflowToolFeatures 在 GET /session/:id/supported-commands 中宣告支持 runSavedArgs 和 runScript；不具备这些功能的守护进程既不接受启动输入，也不接受 run-script 操作。它还携带 nameOnly，当会话的模型仅可运行命名工作流时为 true（tools.workflowNameOnly）：模型自身的 script 和 scriptPath 调用会被拒绝，但上述所有操作（包括 run-script）仍可启动运行。retryHistorical 为 true 时表示 retry 和 rerun 接受从历史记录恢复的运行；较旧的守护进程会以 {"changed": false} 响应它们，因此客户端应仅在报告了该状态时，才为历史条目提供这些控件。

GET /session/:id/lsp

{
  "v": 1,
  "sessionId": "<sid>",
  "workspaceCwd": "/canonical/path",
  "enabled": true,
  "configuredServers": 1,
  "readyServers": 1,
  "failedServers": 0,
  "inProgressServers": 0,
  "notStartedServers": 0,
  "servers": [
    {
      "name": "typescript",
      "status": "READY",
      "languages": ["typescript", "javascript"],
      "transport": "stdio",
      "command": "typescript-language-server"
    }
  ]
}