Driver 开发者平台 API

供官方 Driver「开发者中心」调用的 OAuth 管理通道。它把当前 OAuth 用户映射到既有 Team、Project 和 OAuth Product/Client 服务，不创建第二套账号、团队或插件模型。

认证与上线条件

所有接口使用 Authorization: Bearer <OAuth access token>，并同时满足：

• 读取与创建类接口（context / projects / scopes / products / clients）要求 token 具有 developer:platform；体验者管理接口要求 token 具有独立写档 developer:manage； 两者都只能通过 authorization code + PKCE + consent 获得；
• token 所属 App 为 is_official=true、app_type=standard；
• Client ID 位于当前节点的 OAUTH_DEVELOPER_PLATFORM_HOST_CLIENT_IDS 白名单；
• 当前用户已通过平台准入检查。

developer:platform、developer:manage 与 oauth:delegate 相互独立。旧 token 不会自动获得 新 Scope；后台完成 migration、受控授予和环境变量配置后，Driver 必须重新登录并 consent。只持有读档的 旧 token 调用体验者管理接口返回 403 insufficient_scope（Driver 应提示重新登录），不会得到 5xx。 未就绪区域保持拒绝，不应降级为网站 JWT 或 API Key。

所有成功或失败响应均带 Cache-Control: no-store 和 Pragma: no-cache。错误体只返回稳定 { "error": "code" }，不回显 token、允许 Scope、Client 白名单或请求路径。

草稿、审核与版本发布

完整流程见 开发生命周期 API v1。新增 developer:draft、developer:review、developer:release 均仅面向指定官方 App，不是任何 App 都能申请的通用权限。必须由后台按 App 单独授予，再由用户重新授权；旧 token 与 refresh 不扩权。基础功能和体验者接口继续保持兼容。

接口

GET /oauth/developer-platform/context

返回当前用户可访问的 Team。

{
  "success": true,
  "teams": [{ "id": "team-uuid", "name": "示例团队", "slug": "example" }]
}

GET /oauth/developer-platform/teams/:teamId/projects

返回当前用户在目标 Team 中至少可读的 Project。

{
  "success": true,
  "projects": [{
    "id": "project-uuid",
    "teamId": "team-uuid",
    "name": "示例项目",
    "description": null,
    "systemPurpose": null
  }]
}

GET /oauth/developer-platform/teams/:teamId/projects/:projectId/scopes

返回当前用户、Team、Project 与开发模式实时资格的 Scope 交集。创建表单只能提交该集合中的 code。

{
  "success": true,
  "scopes": [{
    "code": "chat:completions",
    "name": "AI 对话",
    "description": "调用 AI 对话能力",
    "selfServiceEligibility": { "kind": "project_permission", "minimum": "execute" },
    "definitionVersion": 2
  }]
}

GET /oauth/developer-platform/teams/:teamId/products

列出目标 Team 中当前用户可见的插件 Product，并内嵌 Client、审核单和 release 摘要。

{
  "success": true,
  "products": [{
    "id": "product-uuid",
    "primaryManagementClientId": "management-client-uuid",
    "ownerUserId": "user-uuid",
    "teamId": "team-uuid",
    "projectId": "project-uuid",
    "listingKind": "plugin",
    "packageAppId": null,
    "firstApprovedAt": null,
    "clients": [],
    "submissions": [],
    "releases": []
  }]
}

POST /oauth/developer-platform/teams/:teamId/products

创建 plugin Product 和单一 primary OAuth Client。请求头必须包含长度不超过 128 的非空 Idempotency-Key。

{
  "projectId": "project-uuid",
  "name": "示例插件",
  "purpose": "本地开发测试",
  "scopeCodes": ["chat:completions"]
}

请求只接受上述四个字段，额外字段会被拒绝。服务端固定 listing_kind=plugin、platform=Primary、 空回调地址和空授权配置。相同 key 与相同内容重放返回 200；相同 key 改变内容返回 409。

首次创建返回 201：

{
  "success": true,
  "product": {
    "productId": "product-uuid",
    "managementClientId": "management-client-uuid",
    "oauthClientId": "public-oauth-client-id",
    "draftRevisionId": "revision-uuid",
    "idempotent": false
  }
}

GET /oauth/developer-platform/teams/:teamId/clients/:managementClientId

读取属于目标 Team 且当前用户可管理的 Client。

{
  "success": true,
  "detail": {
    "client": {
      "id": "management-client-uuid",
      "productId": "product-uuid",
      "clientId": "public-oauth-client-id",
      "clientLabel": "Primary",
      "name": "示例插件",
      "projectId": "project-uuid",
      "appType": "plugin",
      "currentPublicRevisionId": null,
      "disabledAt": null,
      "createdAt": "2026-09-01T00:00:00Z",
      "updatedAt": "2026-09-01T00:00:00Z"
    },
    "revisions": []
  }
}

体验者管理（developer:manage）

以下三个接口管理插件 Product 的开发体验者名单。业务规则与网页控制台一致：体验资格以 accepted 团队成员身份为准（名单即授权）；owner 固定不占名额且不可移除；名额上限 testerLimit 由服务端 权威下发；移除体验者后其开发授权（code/token）立即失效。三个接口的响应都返回同一份刷新后的 testers 信封，客户端可直接用它刷新界面。

GET /oauth/developer-platform/teams/:teamId/products/:productId/testers

{
  "success": true,
  "testers": {
    "owner": {
      "userId": "owner-user-uuid",
      "status": "active",
      "displayName": "创建者",
      "avatarUrl": "https://…",
      "username": "owner"
    },
    "items": [
      {
        "userId": "tester-user-uuid",
        "status": "active",
        "displayName": "体验者",
        "avatarUrl": null,
        "username": "tester"
      }
    ],
    "testerLimit": 5,
    "canManageTesters": true
  }
}

status 为 active 或 ineligible（已非 accepted 团队成员）；canManageTesters 表示当前 token 用户是否具备该 Product 绑定 Project 的写权限。

POST /oauth/developer-platform/teams/:teamId/products/:productId/testers

请求头必须包含长度不超过 128 的非空 Idempotency-Key。请求体只接受一个字段：

{ "userId": "tester-user-uuid" }

成功返回 201（体验者已在名单中的幂等重放返回 200），响应体为刷新后的同一 testers 信封。

DELETE /oauth/developer-platform/teams/:teamId/products/:productId/testers/:testerUserId

天然幂等（目标不在名单时同样返回成功）。成功返回 200，响应体为刷新后的同一 testers 信封。

常见错误

HTTP	error	含义
400	invalid_team_id	Team ID 格式无效
400	invalid_developer_platform_context	Scope 查询缺少 context=development 或包含额外查询参数
400	oauth_product_project_binding_invalid	Team/Project ID 格式或绑定无效
400	invalid_team_oauth_product_create	创建请求 body、字段或幂等键格式无效
400	oauth_self_service_scope_not_allowed	请求的 Scope 不在当前用户、Team、Project 的开发模式资格交集中
400	invalid_developer_platform_request	Client 详情或体验者请求参数格式无效
400	oauth_development_tester_invalid	体验者请求 body、userId 或 Idempotency-Key 格式无效
400	oauth_development_tester_not_team_member	目标用户不是该 Team 的 accepted 成员
400	oauth_development_tester_limit_exceeded	体验者名额已满（上限以 testerLimit 为准）
400	oauth_development_creator_not_tester	不能把 owner 添加或移除出体验者名单
401	invalid_token	token 无效、过期、撤销，或所属 App 已禁用/删除
403	insufficient_scope	token 缺少所需 Scope（读档 developer:platform / 写档 developer:manage）或路由不在 Scope 定义中
403	unauthorized_client	Host 非官方、非 standard 或不在当前节点白名单
403	invite_activation_required	当前账号未通过平台准入
403	oauth_team_member_required	当前用户不是该 Team 的成员
403	oauth_project_read_required	当前用户对该 Product 绑定 Project 无读权限
403	forbidden	当前用户对该 Product 绑定 Project 无写权限（写操作）
404	oauth_app_not_found	目标 Product/Client 不存在或不可见
404	oauth_product_not_found	目标 Product 不存在或不可见
409	oauth_team_product_create_idempotency_conflict	相同幂等键对应不同创建内容

体验者管理使用 developer:manage。Driver 审核提交、发布和下架使用 开发生命周期 API v1；网站继续使用 Team OAuth 应用 API。