快速开始

1. 安装 CLI

需要 Node.js 22.22 或更高版本。产品名为 GoodVision CLI，命令为 goodvision（简写 gv）。客户端包名为 @goodvision/cli、@goodvision/sdk，与 @goodvision/ui 使用同一 npm scope，可直接从 NPM 安装，也可以从源码构建。

在接入项目中安装公开包：

npm install @goodvision/cli @goodvision/sdk
npx --no-install goodvision --help

持有源码交付物时，在源码根目录运行：

pnpm install --frozen-lockfile
pnpm tooling:verify
node packages/cli/bin/gv.mjs api list
node packages/cli/bin/gv.mjs schema resolveCustomerUserContext

源码或离线 .tgz 制品只用于本地开发、验收或无网络环境。使用源码时，在源码根目录运行上面的构建门禁；使用离线制品时，将制品路径传给 npm install。

后续示例用 goodvision 表示命令入口；项目安装后可使用 npx --no-install goodvision，源码模式使用 node packages/cli/bin/gv.mjs。它只消费公开 API，操作列表不表示当前身份已获得授权或目标环境已开放。

2. 配置应用

从当前应用取得 API 地址、应用 ID 及已授权的用户 Token，将 Token 保存在自己的受控文件中；文件仅本人可读，不提交到项目。配置只保存文件引用：

goodvision config init --file ./goodvision.json \
  --api-base "$GOODVISION_API_BASE" \
  --docs-origin "$GOODVISION_DEVELOPER_DOCS_ORIGIN" \
  --application "$GOODVISION_APPLICATION_ID" \
  --environment sandbox --token-file ./current-token
goodvision context --config ./goodvision.json
goodvision auth status --config ./goodvision.json
goodvision auth check --config ./goodvision.json

auth status 离线显示是否配置凭据，不读取 Token，也不判断有效期。auth check 只检查凭据可读取或获取，不代表任何业务权限已通过。服务端接入可改用 --issuer "$GOODVISION_IDENTITY_ISSUER" --client-id "$GOODVISION_SERVICE_CLIENT_ID" --secret-file ./client-secret --scope openplatform.api.invoke，按需提供当前合同 Scope。此身份只用于应用已开通的能力，不能代替用户授权。

同文件可配置多个 profiles，通过 --profile 显式选择。环境只使用 sandbox 或 production。相对凭据文件按配置文件目录解析；失效、错应用、撤权或依赖故障不会自动切换身份／环境，也不会读取浏览器 Cookie。终端交互式 OAuth 登录不在首期认证合同中。

3. 开始第一个任务

在 Codex 中输入：

使用 GoodVision CLI 找到用户空间解析 API，读取 Schema 和所需 Scope。
用 sandbox 配置预览首次请求，先把请求给我看，再执行。

goodvision api products
goodvision api search user context
goodvision schema resolveCustomerUserContext
goodvision api call resolveCustomerUserContext --config ./goodvision.json --input ./request.json --dry-run

本次请求的 request.json 为 {"body":{}}。核对预览后，去掉 --dry-run 显式执行；此 API 需要当前用户 Token。详见 API 调用和认证与配置。