Capability 预检与版本契约
按具体行为检查特性标签，区分协议、封套和事件版本。
客户端先读取 GET /capabilities，确认协议、可用行为、工作区及当前审批策略，再调用相应接口。相同 v1 不代表所有 daemon 都开启同样能力。
三条版本轴
| 字段或常量 | 当前值 | 管理的变化 |
|---|---|---|
| capabilities 的 v / CAPABILITIES_SCHEMA_VERSION | 1 | capability envelope 结构 |
| protocol.current / SERVE_PROTOCOL_VERSION | v1 | 协议与行为特性 |
| SSE 的 v / EVENT_SCHEMA_VERSION | 1 | 事件 frame 结构 |
三者独立。添加可选字段或新 tag 可在 v1 内增量进行；改变既有 frame 形状需要相应 schema 版本变化，不能只因 protocol 仍是 v1 就忽略事件不兼容。
当前支持协议列表为 ['v1']。不应假定未来 supported 只含一项，也不要把 unstable_* 行为视为无条件稳定。
Envelope 的读取
原始 envelope 提供 mode、features、canonical workspaceCwd，以及可选 workspaces、protocol、policy。features 是特性列表，不能把 SDK 转换后的便利结构直接当成原始 JSON 形状。
workspaceCwd 是主工作区；workspaces 是登记目录与信任信息。multi_workspace_sessions 是多运行时能力，不能仅从主路径字段猜测所有请求都发往 primary。
permission_mediation 的 modes 是构建支持的策略集合，policy.permission 才是当前采用的策略。同样，mcp_guardrails 支持 warn/enforce 不代表当前一定 enforce。
条件特性
| Tag | 主要启用条件 |
|---|---|
| require_auth | require-auth 配置开启 |
| mcp_workspace_pool / mcp_pool_restart | pool 实际开启 |
| allow_origin | Origin allowlist 功能实际启用 |
| prompt_absolute_deadline / writer_idle_timeout | 相应期限为正 |
| workspace_settings / user_language_sync / workspace_voice | 持久设置能力可用 |
| session_shell_command | session shell 显式启用 |
| rate_limit | 运行时限流启用 |
| workspace_reload | reload 实现可用 |
| workspace_voice_transcription / voice_transcribe | 对应语音路径可用 |
QWEN_SERVE_NO_MCP_POOL=1 会使两个 pool 标签消失，但改变 MCP budget 数字本身不会删除 mcp_guardrails。标签描述行为存在，配置与状态决定具体数值和当前结果。
必须分别预检的接口
- secondary session rewind 需要 session_rewind 加 multi_workspace_session_rewind；shell 对应 session_shell_command 加 multi_workspace_session_shell。
- workspace_session_export 与 workspace_archived_session_export 分别控制活动、归档完整导出，不能由 session_export 或 workspace_qualified_rest_core 推断。
- workspace_session_live_state 独立于 workspace_qualified_rest_core，且要求受信 runtime；持久 transcript 的有限未信任读取策略不外推到 live 状态。
- session_catalog_batch 独立支持最多 20 个登记工作区的目录批量请求，单工作区也可广告；不能从 multi_workspace_sessions 推断。
- extension_management_v2、extension_local_path_install、extension_batch_activation_v2 是独立承诺；有 V2 管理不代表支持本地路径或批量 activation。
- workspace_file_read_cursor 需单独确认游标读取，不能从一般文件读取推断。
缺少精确 tag 时使用已确认的兼容接口或显示不支持，不能试探带副作用的新接口后再靠错误猜测。
Activation 提交与生效分开
extension_activation_explicit_refresh 表示 activation 操作在持久策略提交后完成，不直接刷新所有 live sessions。需立即生效时，再针对需要的 workspace 提交 refresh；全局默认变化没有一个可替代全部 workspace 的单次刷新。
未主动刷新者由后续约 30 秒 generation reconciler 收敛。有该 tag 的客户端才采用这种两步流程；旧 daemon 已在 activation 内刷新，不能再无条件额外刷新一次。
Skill 设置标签也有替换：workspace_skill_settings_toggle / workspace_skill_settings_batch_toggle 替代旧的 catalog-validated toggle 标签。正确修订行为可能在 v1 中通过新 tag 取代旧 tag，客户端必须跟随准确的能力名称。
认证在预检之前
--require-auth 下 capabilities 本身要求 bearer；无法先匿名读取 require_auth 再决定是否提交凭据。未认证 401 是该阶段可见的反馈，成功登录后的 tag 才是硬化状态确认。
不要把无法读取 capabilities 当作“没有功能”，也不要因为某 tag 在编译注册表中存在就声称当前部署广告了它。
修改注册表的要求
上游 SERVE_CAPABILITY_REGISTRY 记录每个 tag 的 since 和可选 modes；CONDITIONAL_SERVE_FEATURES 将条件成员与 predicate 放在一起。新增有条件功能时，两处都要维护，并验证开启/关闭条件下的广告结果。
getRegisteredServeFeatures 返回未筛选注册集合，getAdvertisedServeFeatures 才按协议与运行时条件筛选。客户端以实际响应为准；内部测试不能只证明某字符串在注册表里存在。