Skip to content

version-checks.md

Latest commit

 

History

History
44 lines (29 loc) · 3.46 KB

version-checks.md

File metadata and controls

44 lines (29 loc) · 3.46 KB
Raw

CLI 版本检查与升级提示

dws auth status、dws version 和 dws --version 会检查当前发行渠道是否有新版本。开源版默认通过 HTTP 查询 npm Registry，不需要本机安装 npm 或 Node.js，也不下载或安装软件。

关键指令

dws auth status --format json
dws version --format json
dws --version
  • auth status 和 version 的 JSON 保留现有字段，新增 version_check。有新版本时还包含 _notice.update，其中 command 为可执行的升级指令。
  • --version 保留 stdout 原有的单行版本字符串，检查结果写入 stderr。其他人读格式的检查结果也使用 stderr。
  • version_check.status 为 update_available（有更新）、up_to_date（同渠道无更新）、unknown（无法确认）或 skipped（关闭、开发版本或宿主托管）。只有成功取得有效发布信息才会报告前两种状态。
  • 成功查询缓存 24 小时，命中缓存时 cached=true，并保留 checked_at。缓存按来源地址、仓库、发行版、渠道及当前版本隔离。
  • 网络检查最多等待一秒。离线、超时、无有效 Release 或缓存不可用时不会改变原命令的业务结果和退出码。
  • auth status --readonly 仅读取有效版本缓存，不联网、不写入缓存；没有有效缓存时返回 unknown。未知参数导致解析提前停止时，仍保留 --readonly 的只读意图。

正式版查询 https://registry.npmjs.org/dingtalk-workspace-cli/latest；beta 版查询同一包的 /beta，并提示 dws upgrade --beta。开发构建与无法识别的版本不参与比较。Registry 查询不携带 GH_TOKEN 或 GITHUB_TOKEN。

DWS_UPGRADE_REGISTRY 可设置兼容 npm Registry 的根地址。显式设置 DWS_UPGRADE_URL 或 DWS_UPGRADE_REPOSITORY 时，继续使用原有的 GitHub Release 协议，优先于 Registry 配置；自动检查仍不携带 GitHub 凭据，显式升级的 GitHub Token 行为保留。自定义发行版必须配置自己的升级来源，避免误用公开包。

未知命令或参数

遇到当前命令树不认识的命令或 flag 时，CLI 在参数解析边界记录该事实，并先检查是否已有明确的纠正建议。

  • 已有具体拼写候选、人工声明的路径或参数纠正、已知处理方案时，直接保留原有 hint，不发起版本网络检查，也不附加升级提示。
  • 没有明确纠正建议、只有通用 --help 指引时，才进行一次限时版本检查。此时跳过日缓存，避免漏掉当天新发布的能力。

上述检查发现新版时，错误 JSON 附带 _notice.update；人读错误附带升级建议。原有错误类别、退出码和帮助指引保留。普通业务错误、缺少必填参数、已知 flag 的非法值、帮助及补全请求不会因此触发检查。这项分流不改变 auth status、version 和 --version 的关键指令检查行为。

提示只说明“当前版本可能不支持此命令或参数”，不会宣称该命令一定存在于最新版，也不会宣称升级必然修复错误。准确判断某命令的最低支持版本需要独立的版本化命令目录，本功能不提供这项判断。

关闭和主动查询

设置 DWS_NO_UPDATE_CHECK=1 可关闭上述自动检查；关键指令返回 skipped，未知命令保持原错误输出。

DWS_NO_UPDATE_CHECK=1 dws --version
dws upgrade --check

dws upgrade --check 保持现有主动查询行为，不受该开关影响。