版本、来源与兼容性

版本号、Git 提交和构建产物回答不同问题。使用命令、修改部署或解释示例响应前，应检查相关身份，而不是只看一个版本字符串。

本版手册的基线

表面	基线	能说明什么
服务端与 CLI	`1.1.0`，发布源码 `fd340879076a87c2662c454788178eecb05d0036`	稳定页针对的已发布产品行为。
已核验 main 源码	`03751a679ed0205505ab9fae5207a66189c47a18`	文档契约核验的源码，包括后续发布工具工作；main 不等于另一个已发布服务端镜像。
原生客户端	`0.1.0`，独立版本线	应用 marketing version，不表示服务端或附带 CLI 也是 0.1.0；build number、架构、分发渠道也重要。
文档	`contracts/manifest.json`	手册版本、核验/发布源码、契约摘要、dirty/candidate 状态和发布就绪状态。
APNs Widget 快照	尚未发布的预览工作，不属于 server 1.1.0	不能作为稳定版安装前提，也不能承诺为稳定版内网刷新路径。

新文档在覆盖和验收门槛通过前仍是重建预览。页面标为 channel: stable 表示描述已发布能力，不代表整套新手册已完成正式发布。同样，不能仅为了通过部署检查，就把 source_dirty: true、review_status: candidate 改成干净且已审阅的导出。

检查已安装组件

viat --version
viat version

--version 只检查本地；version 还会尝试读取已登录服务端经过认证的 /version。本地成功不证明服务端网络或认证有效。服务端响应形状如下：

{"version":"1.1.0"}

这是目标发行版的示意响应，不保证当前所选实例就是该版本。/healthz 刻意不暴露版本，不能从探针成功推断发行身份。具体输出和错误行为见 CLI 通用命令。

原生产物应与随附发布元数据、摘要共同保存，检查应用版本、build number、架构/渠道和附带 CLI 版本。iOS 开发设备产物、注册设备分发、App Store Connect 产物的签名和安装要求不同，重命名文件不能改变分发渠道。

兼容性规则

使用运行中服务端对应的手册版本，而不只是网站最新页面。
本地测试宿主协议要求 CLI、viat-test-host、viat-endpoint-test-host 匹配。仅安装 CLI 不会安装 Python、Bun 或 Rust 构建工具链。
资源 schema 描述结构，不涵盖全部条件 API 规则；当前源码支持某类型，不证明较旧运行服务端支持它。
管理 API/控制台类型与项目端点 OpenAPI 是不同契约，生成的端点 OpenAPI 不描述整个管理 API。
Cargo 版本仍为 1.1.0 的检出可能已经包含未发布变更，使用新行为前要核对提交和产物来源。
端点快照固定端点/目标状态，不固定所有外部依赖或凭据；工作流步骤 uses: 有实时解析例外，见核心概念。
重建或回滚端点不回滚数据库迁移、外部系统、资源凭据或共享实时依赖。

更新契约与文档

维护者从明确选择的产品检出导出契约，以 candidate 导入，审阅差异，同步两种语言并重跑示例。资源、语言清单、CLI 叶命令和 MCP 工具有覆盖检查，但检查不替代行为审阅或提供商/设备验收。

每页原始 Markdown 带相同版本/通道信息；稳定 LLM 索引不包含预览能力页。离线书从同一份 Markdown 生成，替换随产品携带的书之前必须固定为已验收文档产物，不是启动时从最新网站抓取。

版本不一致时

现象	处理
CLI 比服务端新	查阅服务端对应手册并验证所需命令/API，不假定新字段向后兼容。
本地测试 host 报另一版本	换成与 CLI 匹配的 host，不绕过握手。
原生应用能用，但某功能缺失	核对平台、构建/渠道和服务端能力，应用 marketing version 不足以判断。
main 有某功能，发行产物没有	保持预览标识，直到匹配产物真正发布。
文档 build 成功，release check 失败	查看覆盖/证据缺口；预览成功不是把 manifest 标为 ready 的理由。

本页记录来源，不执行升级。真实升级前应按安装说明备份部署状态并验证恢复。不要仅因文档示例提到更新提交，就修改 DNS、发布产物或替换运行服务。