# 客户端文档维护策略

客户端软件持续更新，界面与配置参数可能发生变更。本文档说明接入文档的维护与验证机制，以及过期内容的反馈渠道。

## 最近核验

已完成真实调用核验的客户端接入文档顶部标有「最近核验」日期，用于记录最近一次真实客户端核验。日期本身不能说明覆盖了哪些系统、版本和配置分支，应同时查看下方的核验范围。

历史页面若只有日期，会显示「核验范围未记录」，不代表所有分支都已验证。未在范围中列出的 App / CLI、系统或可选功能，需要单独确认兼容性。

页脚的「最后更新于」是另一回事，它来自 Git 提交时间，改一个错别字也会刷新。判断内容是否跟得上客户端版本，看「最近核验」。

尚未完成真实调用的教程标注 `verificationStatus: unverified`，页面显示「尚未实机核验」，不填写 `verifiedAt` 或 `verifiedWith`。完成核验后移除此状态，再填写日期与范围。

## 核验周期

目标是 30 天内至少核验一次。每次核验检查：

| 检查项     | 说明                             |
| ---------- | -------------------------------- |
| 安装方式   | 命令、包名、下载入口是否仍然有效 |
| 配置项名称 | 客户端改版后设置项常被改名或移位 |
| 截图       | 与当前界面是否一致               |
| 验证步骤   | 文档给出的验证命令能否正常返回   |

客户端发布大版本时应触发额外核验，不等周期到期。

## 记录核验范围

完成真实客户端测试后，在页面 frontmatter 中更新 `verifiedAt`，并用 `verifiedWith` 记录客户端完整版本号、操作系统及版本、配置方式和成功验证的功能。`verifiedWith` 是一段字符串，会显示在核验日期下方；中英文页面应记录同一组事实。

核验至少包含一次真实模型回复；安装成功或能获取模型列表不等于推理成功。部分分支完成时，只在核验范围中列出已通过的分支。正文保留使用步骤和兼容性限制，不记录测试过程。修改措辞、通过文档构建或翻译同步不应刷新核验日期。

## 覆盖范围

策略适用于 [编程客户端](https://docs.tokenflux.dev/docs/quickstart.md#客户端选型) 接入文档。

计费、错误码、API 端点这类文档不标核验日期，它们跟随 TokenFlux 自身变更，改动时同步更新。

## 发现内容过期

文档与实际不符时，用以下任一方式反馈：

- 页面底部的「在 GitHub 上编辑此页」直接提交修改
- 在 [仓库](https://github.com/TokenFlux/TokenDocs) 提 issue，注明客户端名称与版本
- 按 [排障](https://docs.tokenflux.dev/docs/troubleshooting.md#怎么反馈) 的模板反馈

请附上客户端版本号。同一份文档在不同版本下的表现可能完全不同。

## 相关入口

- [快速开始](https://docs.tokenflux.dev/docs/quickstart.md) — 按客户端选择接入方式
- [排障](https://docs.tokenflux.dev/docs/troubleshooting.md) — 按症状定位问题