# 版本、来源与兼容性

> 核验版本：1.1.0；通道：stable；文档 ID：reference.versions

版本号、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` 改成干净且已审阅的导出。

## 检查已安装组件

```sh
viat --version
viat version
```

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

```json
{"version":"1.1.0"}
```

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

原生产物应与随附发布元数据、摘要共同保存，检查应用版本、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:` 有实时解析例外，见[核心概念](../overview/concepts.md)。
- 重建或回滚端点不回滚数据库迁移、外部系统、资源凭据或共享实时依赖。

## 更新契约与文档

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

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

## 版本不一致时

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

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