API 参考

Jingle Extension API 中用于构建命令视图、读取设置、访问连接和触发宿主能力的 SDK。

Jingle Extension API 为扩展命令提供 UI 组件、宿主能力和运行时工具。开发者预览阶段的实际包名是 @openwork/extension-api；公开版本命名会随平台发布节奏统一。

UI components

API	用途	状态
`List`	搜索、分组、列表项、accessories、empty view、dropdown、pagination	预览可用
`Detail`	Markdown 内容、metadata、链接和标签	预览可用
`Form`	表单字段、dropdown、tag picker、date picker、storeValue	预览可用
`ActionPanel` / `Action`	命令动作、复制、粘贴、打开浏览器、提交表单、push view	预览可用
`MenuBarExtra`	菜单栏入口和状态展示	预览可用

命令详情视图参考图 — UI SDK 的目标是让扩展作者描述信息架构和动作，而不是重新实现窗口、列表选择和键盘交互。

Preferences

`getPreferenceValues()`

读取扩展级和命令级设置。返回值按命令启动上下文解析，适合在命令组件和工具函数中使用。

const preferences = getPreferenceValues<{
  apiBaseUrl: string
  open_in: { name?: string; bundleId?: string; path?: string }
}>()

`getConnectionSecret(name)`

读取由宿主管理的连接 secret。扩展只请求需要的 secret 名称，不直接处理凭证存储位置。

const token = getConnectionSecret("accessToken")

`openExtensionPreferences()` / `openCommandPreferences()`

打开扩展或命令设置页。需要用户补充配置或连接账号时，命令可以把用户交给平台设置页，而不是在命令里重新实现一套设置界面。

import { Action, ActionPanel, Detail, openExtensionPreferences } from "@openwork/extension-api"

export default function Command() {
  return (
    <Detail
      markdown="Connect this extension before running the command."
      actions={
        <ActionPanel>
          <Action title="Open Extension Settings" onAction={openExtensionPreferences} />
        </ActionPanel>
      }
    />
  )
}

Storage

API	语义	状态
`LocalStorage.getItem`	按扩展 scope 读取持久值	预览可用
`LocalStorage.setItem`	写入扩展 scope 持久值	预览可用
`LocalStorage.removeItem`	删除扩展 scope 值	预览可用
`LocalStorage.clear`	清空扩展 scope 值	预览可用
`LocalStorage.allItems`	读取全部扩展 scope 值	预览可用
`Cache`	命名空间内同步缓存、订阅和容量裁剪	预览可用

Feedback and shell

API	用途	状态
`showToast` / `Toast`	展示成功、失败、加载等反馈	预览可用
`showHUD`	展示短反馈	预览可用
`Clipboard` / `writeClipboardText`	剪贴板读写	预览可用
`open` / `openExternal`	打开 URL 或外部资源	预览可用
`closeMainWindow`	隐藏或关闭主窗口	预览可用

API	用途	状态
`useNavigation()`	push / pop / openCommand / hideLauncher	预览可用
`launchCommand()`	从一个命令启动另一个命令	预览可用
`LaunchProps` / `LaunchType`	命令启动参数和启动类型	预览可用
`useCommandSeedQuery()`	读取 launcher 输入的种子查询	预览可用

OAuth

API	状态
`OAuth.PKCEClient` constructor	预览
`OAuth.RedirectMethod.Web`	预览
`authorizationRequest()`	规划中
`authorize()`	规划中
`setTokens()` / `getTokens()` / `removeTokens()`	规划中

Utilities

@openwork/extension-utils 提供面向账号连接的辅助函数，适合 token-backed integrations：

API	语义
`OAuthService.getAccessToken()`	从宿主管理的 connection secret 读取 `accessToken`
`OAuthService.authorize()`	读取当前连接 token；浏览器 OAuth 流程见 OAuth 章节
`withAccessToken(service)`	React command 缺 token 时展示连接空状态；普通函数缺 token 时抛错
`getAccessToken(service)`	读取当前 connection secret 或 service token