优康云 CLI 命令文档

优康云 CLI（ukang）面向体检机构实施人员、自动化脚本和 AI 工具。对 AI 说一句：帮我安装优康云体检软件。AI 可根据优康云安装清单，自动下载组件、执行安装、检查环境、申请账号并生成实施报告。第一阶段已开放环境检测、Manifest 读取和诊断报告能力，自动安装、开户注册和云绑定能力正在升级。

产品定位：优康云体检智能体，让体检软件从人工实施进入 AI 自动交付。

当前状态：doctor、check-env、status、version、check manifest、check mysql-connection、register-org 为第一阶段开放能力。安装、绑定云端和安装网关命令为即将支持能力，页面保留命令协议和安全要求，不表示当前已可自动完成正式开通。

全局约定

项目	说明
默认输出	`--json`，便于 AI 工具解析。
人工查看	`--text`，输出便于实施人员阅读的诊断信息。
安装清单	`--manifest <url-or-path>`，默认读取 `https://www.ukang.cc/manifest/ukang-agent-manifest.json`。
云端 API	`register-org` 默认读取 Manifest 中的 `agentApi.defaultBaseUrl`，也可用 `--api-base <url>` 指定本地或 117 内测 API。
失败处理	命令失败必须返回非 0 退出码、明确错误码和原因，不允许静默吞错或失败后假成功。
敏感信息	不得在前端、Manifest 或示例中写死 MySQL 密码、云端密钥、机构密钥。

命令清单

命令示例	作用	状态
`ukang doctor`	完整环境诊断，生成实施诊断报告，并包含 MySQL、体检软件主体和云网关预检结果。	第一阶段开放
`ukang check-env`	检查操作系统、端口、运行库、MySQL、权限。	第一阶段开放
`ukang check mysql84`	只读检查兼容 MySQL 服务、3306 端口、字符集、排序规则和配置格式。	第一阶段开放
`ukang check mysql-connection`	验证 AI 或 DBA 已准备好的 MySQL / PolarDB 连接，检查数据库是否存在、账号能否查询、字符集和排序规则是否符合要求。	第一阶段开放
`ukang install mysql84`	MySQL 由 AI 从官方渠道安装或连接已有环境；该命令只输出要求和检查结果，不下载、不安装、不写配置。	外部管理
`ukang check health-exam`	只读检查主体安装包、SHA256 声明文件、基础 SQL、安装目录、8001 端口、.NET 8 和 MySQL 前置状态。	第一阶段开放
`ukang install health-exam`	体检软件主体安装前检查。第一阶段不解压、不建库、不写连接串、不启动服务。	第一阶段预检
`ukang register-org --name "某某体检中心" --phone "13800000000"`	申请优康云机构账号，提交后进入待审核流程，不默认开通正式机构。	第一阶段开放
`ukang register-status --machine-code ukang-xxxx`	查询机构申请审核状态，便于 AI 判断是否可继续绑定云端配置。	第一阶段开放
`ukang agent-version`	读取优康云 Agent API 当前版本、Manifest 地址、内测通道和组件可用状态。	第一阶段开放
`ukang download-token --component ukang-cli`	向优康云 Agent API 获取 CLI 受控下载授权。大型历史包和未发布组件必须返回不可用状态，不返回假下载地址。	第一阶段开放
`ukang submit-report`	上传当前诊断报告、组件状态和异常项到优康云内测 API。	第一阶段开放
`ukang doctor --submit`	执行完整环境诊断并自动提交实施诊断报告，报告包含三项安装预检详情。	第一阶段开放
`ukang bind-cloud --machine-code ukang-xxxx`	审批通过后读取云端绑定配置摘要。第一阶段只做绑定就绪检查，不写入本地配置，不返回云端密钥明文。	第一阶段开放
`ukang bind-cloud --org-code "YK202605240001"`	按机构编码绑定本地系统到云端机构。该模式将在后续阶段支持。	即将支持
`ukang check gateway`	只读检查云网关预期目录、配置文件路径和 Windows 服务状态。	第一阶段开放
`ukang install gateway`	云网关安装前检查：校验云端绑定是否就绪并输出本地配置格式。第一阶段不下载、不写配置、不安装服务、不保存密钥。	第一阶段预检
`ukang status`	查看当前安装状态和组件运行状态。	第一阶段开放

诊断命令

ukang doctor 用于完整环境诊断，输出操作系统、内存、磁盘、端口、.NET Runtime、MySQL、体检软件主体、云网关和 Manifest 可达性等信息，并生成实施报告。当前报告已包含 MySQL 8.4、MySQL / PolarDB 连接、体检软件主体和云网关预检详情。未提供数据库连接参数时，连接检查会标记为 skipped；一旦提供连接参数，连接未就绪会返回失败，避免 AI 误判。

ukang doctor --json
ukang doctor --text

ukang doctor --host 127.0.0.1 --port 3306 --database btv10b --user ukang_app --password-env UKANG_DB_PASSWORD --json

ukang doctor --submit --json

ukang check-env 用于快速检查安装前置条件，重点覆盖操作系统、端口、运行库、MySQL、权限。

ukang check-env --json

安装命令

ukang check mysql84 用于只读检查兼容 MySQL 服务、3306 端口、字符集、排序规则和初始化配置格式。

ukang check mysql84

ukang check mysql-connection 用于验证已准备好的 MySQL / PolarDB 连接。CLI 使用本机 mysql 客户端执行只读查询，检查连接、数据库存在性、账号查询能力、字符集和排序规则。建议通过 --password-env 传入密码，避免密码出现在命令历史或 AI 输出中。

ukang check mysql-connection --host 127.0.0.1 --port 3306 --database btv10b --user ukang_app --password-env UKANG_DB_PASSWORD

ukang check mysql-connection --host ukang59.mysql.polardb.huhehaote.rds.aliyuncs.com --port 3306 --database ukangtest --user ukangcloud --password-env UKANG_DB_PASSWORD --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"

ukang install mysql84 当前不下载也不安装 MySQL。AI 应从 MySQL 官方渠道安装，或连接机构已有 MySQL / PolarDB；CLI 只输出端口、字符集、账号权限和配置要求。

ukang install mysql84

ukang check health-exam 用于只读检查主体安装包、SHA256 声明文件、基础 SQL、安装目录、8001 端口、.NET 8 和 MySQL 前置状态。

ukang check health-exam

ukang install health-exam 当前用于体检软件主体安装前检查。第一阶段不解压、不建库、不写连接串、不启动服务；正式开放后应从本机安全配置或交互输入获取数据库连接信息。

ukang install health-exam

云端开通命令

register-org 用于申请优康云机构账号。机构开户注册必须进入待审核或验证码确认流程，不得默认放行。未指定 --api-base 时，CLI 会先读取 Manifest 中的 agentApi.defaultBaseUrl；117 内测 API 上线后，只需要更新 Manifest 即可让 AI 工具指向内测环境。

ukang register-org --name "某某体检中心" --phone "13800000000"

ukang register-org --name "某某体检中心" --phone "13800000000" --api-base http://localhost:5048

ukang register-status --machine-code ukang-xxxx

ukang agent-version

ukang download-token --component ukang-cli --channel internal-test

ukang bind-cloud --machine-code ukang-xxxx

ukang submit-report

bind-cloud 用于绑定已审核通过的云端机构。绑定所需密钥应由云端下发或本机安全输入，不得硬编码。

ukang bind-cloud --org-code "YK202605240001"

check gateway 用于只读检查云网关预期目录、配置文件路径和 Windows 服务状态，不创建文件、不安装服务。

ukang check gateway

install gateway 当前用于安装前预检，后续承载预约同步、报告上传、报告推送和云端规则下发。第一阶段只检查云绑定状态并输出配置格式，不下载、不写配置、不安装服务、不保存密钥。

ukang install gateway

状态命令

ukang status 用于查看当前安装状态，适合 AI 在每一步执行后判断是否继续。

ukang status --json

返回 AI 安装页面