账号连接

账号连接让扩展访问外部服务，同时把凭证管理留给 Jingle。扩展声明 provider、secret 名称和公开配置；Jingle 负责设置页、凭证读取、连接状态和运行时上下文。

连接类型

类型	用途	状态
`none`	本地能力，不需要登录，例如系统提醒事项	预览可用
`apiKey`	用户手动保存 API key，例如内部 integration token	预览可用
`personalAccessToken`	用户手动保存 personal access token	预览可用
`oauth`	平台托管 OAuth 登录和 token 生命周期	规划中

Manifest 声明

connection: {
  id: "default",
  provider: "github",
  title: "GitHub",
  auth: {
    type: "personalAccessToken",
    secretNames: ["accessToken"]
  },
  publicPreferenceNames: ["apiBaseUrl"],
  connectGuide: "Create a GitHub personal access token and save it in Settings."
}

命令运行时会收到解析后的连接对象：

interface NativeExtensionResolvedConnection {
  connectionId: string
  extensionName: string
  provider: string
  publicConfig: Record<string, unknown>
  missingSecretNames: string[]
  status: "connected" | "failed" | "missing" | "unsupported"
}

Provider reuse

一个扩展可以复用另一个 provider 扩展的连接。Jingle 会读取 provider 的公开配置和 secret，并把命令需要的值注入当前执行上下文。

这适合生成版、迁移版或垂直场景扩展：用户只连接一次 provider，多个 package 可以共享同一个平台管理的连接。

Settings handoff

连接缺失时，命令应打开平台设置页：

import { openExtensionPreferences } from "@openwork/extension-api"

await openExtensionPreferences()

可用入口：

openExtensionPreferences()
openCommandPreferences()
openNativeExtensionSettings({ extensionName, commandName })
withAccessToken() 提供连接空状态和设置页动作

Provider examples

Provider	预览阶段方式	适用场景
GitHub	`personalAccessToken` + `accessToken` secret	issue、PR、notification、repository、workflow run
Notion	`apiKey` + internal integration token	page、data source、quick capture

安全边界

账号连接应保持清晰分层：

extension code
  -> extension runtime SDK
  -> host capability request
  -> main connection service
  -> secure credential store

普通 preference 可以保存 apiBaseUrl、默认数据库、打开方式等非敏感配置。access token、refresh token、client secret 不应进入普通 settings、日志、renderer state 或 Agent prompt。