Agent 接入能力概述
GoodVision 面向 Agent 开发者提供三类可组合能力，分别解决“用谁的身份接入”“如何接收变化”“如何执行业务动作”三个问题。
应用与凭据：创建应用，选择用户授权或应用服务身份，固定应用和环境。
事件 SDK：通过长连接或 Webhook 接收已订阅事件，持久处理后确认。
GoodVision CLI：让 Codex 发现 API、读取参数、预览请求并调用模型、客户经营、订阅和订单等公开能力；代码集成使用同一套 TypeScript SDK。
能力一览
三层按需组合。只调用 API 时，先取得所需身份即可，不必建立事件连接。下面的“交互层”指业务事件输入；聊天会话、流式消息和卡片 Channel SDK 尚未提供。
| 能力 | 什么时候使用 | 形态 | 接入指引 |
|---|---|---|---|
| 应用与凭据 · 凭据层 | 为应用确定身份、用户授权、Scope 和 sandbox／production 上下文。目标：取得本次任务所需的身份。 | 开发者后台、网页 OAuth／PKCE、应用服务凭据；CLI 引用私有文件 | 创建应用与开发测试、用户授权、服务身份 |
| 事件 SDK · 交互层 | 接收应用已订阅的事件，按事件 ID 幂等处理并在持久完成后确认。目标：让自动化响应业务变化。 | TypeScript／Node.js SDK、SSE、HTTPS Webhook、接收模板 | 长连接、Webhook、应用用户与事件 |
| GoodVision CLI · 执行层 | 搜索公开能力、读取 Schema、调用 API、组合脚本。目标：让 Agent 执行已获准的业务动作。 | goodvision／gv CLI、@goodvision/sdk、JSON／JSONL；npm 包和源码均可用 | GoodVision CLI、API 产品、接入模板 |
如何组合这些能力
| 路径 | 适合什么场景 | 使用组合 | 第一个可执行任务 |
|---|---|---|---|
| A · IDE 中直接执行 | 在 Codex 中查能力、调试 API、生成接入代码 | 应用与凭据 → CLI | 找到用户空间 API，查看参数，用 sandbox 预览首次请求 |
| B · 服务端业务集成 | 在自己的应用或脚本中调用公开业务 API | 应用与凭据 → TypeScript SDK | 按当前身份查询可用模型、客户资料或订单，按 Schema 处理结果 |
| C · 事件驱动自动化 | 订阅状态变化后持续处理业务 | 应用服务身份 → 事件 SDK／Webhook → 业务 API | 持久接收事件，读取原事件对应的当前状态，完成幂等处理后 ACK |
应用服务身份适用于合同明确支持的操作。需要当前用户、客户授权或产品策略的操作仍须逐次授权，不能因为已经连上事件通道而获得业务权限。
业务能力地图
GoodVision 的公开能力覆盖模型与 Token、客户经营、订阅、订单支付、用户空间、应用目录、事件与诊断，详见 GoodVision CLI 能力地图。
最短开始路径
- 按 GoodVision CLI 指南从 npm 安装 CLI／SDK。
- 配置自己的应用及
sandbox上下文，通过auth status查看配置，通过auth check检查凭据获取。 - 用
api products查看能力地图、api search找到操作，读取schema，运行--dry-run预览，再显式执行。自动化脚本通过--profile固定应用和环境。
例如在 Codex 中输入：
使用 GoodVision CLI 的 api products 查看全局能力，找到用户空间解析 API，读取参数和所需权限。
使用我的 sandbox profile 预览请求，把结果给我确认后再调用。命令目录表示合同已登记；凭据检查表示文件可读取或 Token 可获取；实际业务权限和资源可用性由每次 API 请求核验。应用服务身份不能代替用户授权。
SDK 与事件能力
TypeScript/Node.js 项目使用 @goodvision/sdk 调用相同操作，类型由公开合同生成。事件接收按事件 ID 幂等持久处理，完成后才 ACK；events watch 用于调试，不自动确认业务完成。按需使用 api、pkce-web、event-receiver、webhook 四种模板。
当前事件 SDK 提供开放平台事件消费；聊天会话、消息渲染和流式卡片等 Channel SDK 能力尚未提供。扫码建应用和终端 OAuth 登录同样尚未提供；创建应用与用户授权沿已有开发者后台及网页授权流程完成。客户委托 Agent 操作第三方应用业务功能尚未开放。
能力状态与后续接入
| 状态 | 能力 | 当前路径 |
|---|---|---|
| 已提供 npm 包与源码 | CLI、TypeScript SDK、能力发现、Schema、请求预览、多 Profile、四类模板、SSE 与 Webhook 接收 | 按 CLI 指南从 npm 安装；业务授权由 API 逐次核验 |
| 待建设 | 扫码自动创建应用、终端 OAuth 登录／登出、聊天 Channel SDK、第三方应用业务委托 | 当前使用后台创建、网页授权及业务事件接入；相应公开合同和完整验收交付后再开放 |