Kun 扩展开发指南：模型 Provider、账号与认证体系的完整实现-平芜编程栈

人工智能
AI Agent
自主智能体
桌面应用
MCP Clients

【免费下载链接】Kun

Local-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.

项目地址：https://gitcode.com/gh_mirrors/de/Kun

点击查看免费下载

本文基于 docs/extensions/providers-and-accounts.en.md 展开，并结合 Kun 仓库的 Extension API 源码、示例扩展与测试验证。适合希望为 Kun 接入自有模型服务的扩展开发者阅读：你将掌握如何在 Manifest 中声明模型 Provider 与认证方式、如何实现 Provider Adapter 与流式协议、如何管理账号生命周期与凭据安全，以及如何让扩展在 GUI 与 headless（kun serve）环境下行为一致。

Kun 允许一个扩展实现完整的自定义模型传输层（custom model transport），而无需创建新的 Agent runtime。Kun 会把一次模型请求归一化，通过RemoteModelClient路由到扩展的 Node Host，再把校验过的规范化 stream 写回既有的 AgentLoop、工具与用量路径。这意味着扩展侧只需聚焦「如何与上游模型服务对话」，会话调度、工具执行、权限审批与用量记账都由 Kun 核心接管。

三个独立概念：Provider Definition、Account 与 Provider Binding

Kun 把模型接入拆分为三个互不混淆的记录，这是整个体系的基石：

记录	描述	是否包含秘密
Provider Definition	传输方式、模型/能力、认证方式、拥有者	否
Account	用户在该 Provider 下的一个命名账号、认证类型、状态、credential reference	否；秘密存放在 Credential Store
Provider Binding	一次 thread/profile/role 使用的 provider + account + model	否

Binding 必须自洽（coherent）：Provider A 不能绑定 Provider B 拥有的 account/model。当账号缺失时，系统返回account-required，绝不会自动选择另一个账号。这一约束在源码层被强制实现——kun/src/services/extension-provider-account-store.ts中的validateBinding会在 probe、listModels、stream 之前逐一校验 provider/account/model 的归属，任何不匹配都会抛出 opaque 错误（opaqueProviderError/opaqueAccountError），参见 kun/src/services/extension-provider-account-store.ts。

权限模型与入口约束

扩展声明 Provider、读取账号、发起认证流程都需要显式权限（manifestpermissions字段）：

Provider 贡献必须声明 Nodemain，并持有providers.register权限；
查看脱敏后的账号元数据需要accounts.read；
使用某个账号发起请求需要accounts.use:<providerId>；
请求创建/更新/删除账号流程需要accounts.manage:<providerId>；
若自定义签名确实需要读取原始秘密材料，需要accounts.secrets.read:<providerId>——仅 Node 端可用，且需单独的高风险确认（见下文「Authenticated Fetch 与 Secret Read」）；
由 Broker 代发的上游请求还需要network:<hostname>。

一个关键设计约束：模型 Provider、认证 handler 和动态模型发现必须在没有 browser/Webview 内容的环境下也能运行。browser永远不是 headless 回退方案，这保证了扩展 Provider 在 GUI 关闭时仍可被kun serve、定时任务或 CLI 使用。

在 Manifest 中声明 Provider

下面是最小可用的 Manifest 示例（完整继承自原文档）。它声明了一个模型 Provideracme-models，关联一个 API Key 认证源acme-auth：

{ "main": "dist/extension.js", "activationEvents": [ "onProvider:acme-models", "onAuthentication:acme-auth" ], "contributes": { "modelProviders": [ { "id": "acme-models", "displayName": "Acme Models", "authenticationProviderId": "acme-auth", "credentialHosts": ["api.acme.example"], "models": [ { "id": "reasoning-small", "displayName": "Reasoning Small", "capabilities": { "input": ["text"], "output": ["text"], "reasoning": true, "tools": true, "parallelTools": true, "streaming": true } } ] } ], "authentication": [ { "id": "acme-auth", "displayName": "Acme Account", "type": "api-key", "apiKey": { "header": "Authorization", "prefix": "Bearer " } } ] }, "permissions": [ "providers.register", "accounts.read", "accounts.use:acme-models", "accounts.manage:acme-models", "network:api.acme.example" ] }

精确的 capability/auth 元数据以 Manifest Schema 为准（packages/extension-api/schema/kun-extension.schema.json）。结合源码 packages/extension-api/src/providers.ts 与 packages/extension-api/src/accounts.ts，Schema 约束要点包括：

Providerid必须匹配^[a-z][a-z0-9-]*$（1～64 字符），displayName最长 128 字符；
credentialHosts支持*.domain通配前缀，最多 64 项；
models数组最多 512 个模型；每个模型的capabilities中input/output支持text、image、audio、video、file五种 modality，另含reasoning、tools、parallelTools、streaming布尔能力，以及可选的maxContextTokens、maxOutputTokens；
认证声明按类型做必填校验：oauth2-pkce必须提供clientId、redirectUri、authorizationUrl、tokenUrl；device-code必须提供clientId、deviceAuthorizationUrl、tokenUrl；
API Key 认证默认注入Authorization: Bearer <key>，可自定义header与prefix。

命名空间规则：Provider 与模型 ID 必须稳定；注册时与扩展身份合成 namespaced identity（源码中通过extensionProviderId(extensionId, id)实现，见 kun/src/adapters/model/extension-model-provider.ts）。扩展 Provider 不能占用 built-in 或其它扩展的 ID。注册时序上，认证 Provider 必须先于模型 Provider 注册——register()会先检查对应 authentication provider 是否已存在且 owner 匹配，否则直接抛错（见 kun/src/adapters/model/extension-model-provider.ts）。

credentialHosts 与网络安全边界

credentialHosts是「允许附加认证材料的接收方」的独立白名单，一个宽泛的network:*权限并不能替代它。authenticatedFetch要求目标 URL 同时匹配network:<hostname>授权与当前 Provider 的credentialHosts。其它安全策略：

远程目标必须使用 HTTPS；只有显式声明的 loopback 目标允许 HTTP，且每个解析出的地址都必须仍是 loopback；
重定向由 Broker 以 manual 模式逐跳返回，每一跳都重新检查，并剥离响应中的 credential/cookie header；
生产 transport 会解析全部地址，拒绝任何 special-use 或 mixed DNS 应答，并把获准地址 pin 到实际连接；
Kun 发起的 OAuth device、token exchange 与 refresh 请求使用同一套策略；
测试可以注入 fake fetch，但它不代表生产环境的 SSRF/DNS-rebinding 防护水平。

静态与动态模型目录

Kun 会把 Manifest 中的静态模型与 Adapter 的listModels(binding)动态结果合并成一个Provider-owned catalog。动态条目不能逃出 Provider 命名空间；无效/重复模型会被确定性拒绝或去重。如果动态发现失败，合法的静态模型仍然保留，但永远不会借用另一个 Provider 的模型。相关实现可参考mergedProviderModels与诊断记录逻辑（kun/src/adapters/model/extension-model-provider.ts）。

Provider Adapter 生命周期

一个 Provider adapter 需要实现五个方法（接口定义见 packages/extension-api/src/providers.ts）：

方法	职责	说明
`probe(binding, context)`	验证连接/账号	返回规范化成功或 Provider error，不启动 Agent turn；返回`{ ok, latencyMs?, message?, details? }`
`listModels(binding, context)`	返回动态模型	返回`ProviderModel[]`，与静态模型合并
`stream(request, context)`	处理完整规范化请求	以`AsyncIterable`形式 yield 有序事件
`cancel(requestId)`	取消指定请求	按 requestId 取消，可与`stream`并发执行
`countTokens(request)`（可选）	精确 token 计数	缺失时由 Kun 核心估算，不算 adapter 失败

注册方式是通过context.modelProviders.registerProvider(declaration, adapter)完成，把返回的Disposable加入context.subscriptions。当扩展被禁用、Host 退出或 disposal 时，Kun 会 cancel/fail 所有在途请求并释放 correlation state——源码中disposeRegistration会 abort 所有 active request 并尽力调用 adapter 的cancel（见 kun/src/adapters/model/extension-model-provider.ts）。

仓库自带的示例扩展 examples/extensions/streaming-model-provider/src/extension.ts 演示了一个完整的DemoStreamingAdapter：probe通过listAccounts检查账号是否connected，stream逐段 yieldtextDelta，检查取消标志后 yieldusage与completed，并实现cancel与countTokens。其 Manifest（examples/extensions/streaming-model-provider/kun-extension.json）同时声明了 API Key 与 OAuth PKCE 两种认证源和两个 Provider（echo-api-key、echo-oauth），是「一次认证、双 Provider」的参考样板。

规范化请求（Normalized Request）

Provider 收到的是一个**公开、版本化（public versioned）**的对象（ModelProviderRequestSchema，见 packages/extension-api/src/providers.ts），包含：

opaque request ID；
生效的 provider/account/model（binding）；
system/mode 指令（instructions）；
稳定前缀与模型可见的 history items（messages，含system/developer/user/assistant/tool五种角色）；
text/image/audio/video/file 等模型支持的附件表示；
已广告的工具 schemas（tools，含name、description、inputSchema）；
reasoning/sampling/生成控制（generation：temperature(0~2)、topP(0~1)、maxOutputTokens、stop(≤16 项)、reasoningEffort(low/medium/high)、toolChoice）；
一个account handle，默认不是原始凭据。

请求对象不包含Kun 内部 class、TurnItem对象身份、runtime token、文件系统凭据或 JavaScriptAbortSignal。取消是对同一 request ID 的独立操作（调用cancel(requestId)）。如果选中模型没有声明某 input modality、tool mode 或 generation control，请求会在发送到 transport 之前以 capability error 拒绝（assertModelRequestCapabilities）。

流事件协议与规则

v1 协议只接受七种有序、版本化事件：

textDelta
reasoningDelta
toolCallDelta
toolCallComplete
usage
completed
error

协议规则（每条都可在 kun/src/adapters/model/extension-model-provider.ts 的 stream 校验循环中找到对应实现）：

每个请求的sequence必须从 0 开始单调递增，Host/Kun 按序严格校验，跳号即报错；
分片工具调用（toolCallDelta）按callId独立组装；并行调用保留 first-seen 顺序；
完整工具参数必须满足对应工具 Schema，才能写入 history；
每个请求最多一个 terminal 事件：completed或error；
成功的completed必须在此之前或与之同时提供至少一个已知usage字段；缺失/空 usage 是 protocol error。独立的usage事件与completed内联 usage 只按最后一个累计快照记账一次（源码中lastUsage的覆盖逻辑即为此设计）；未知字段不编造，reasoning/cache-write token 与任意三字母币种（cost+currency必须成对出现）的成本会保留；
未知事件、错误顺序、超限 payload/事件数、第二个 terminal 或畸形调用会终止协议，且不提交无效的 assistant/tool history；
terminal/cancel 之后到达的事件一律丢弃。

一个最小 stream 示意（完整继承自原文档）：

async function* stream(request) { yield { type: 'textDelta', requestId: request.requestId, sequence: 0, delta: 'Hello' } yield { type: 'usage', requestId: request.requestId, sequence: 1, usage: { inputTokens: 12, outputTokens: 1 } } yield { type: 'completed', requestId: request.requestId, sequence: 2, finishReason: 'stop' } }

finishReason的合法值为stop、length、tool_calls、content_filter、other；error事件带code、message、retryable与可选details。事件字段的精确约束以同版本 SDK 类型为准，不要手工拼装。

组装与提交细节：Kun 按callId组装并行toolCallDelta分片并依 first-seen 顺序提交；最终参数必须是 JSON object、匹配已广告工具及其 input Schema，分片与显式toolCallComplete不一致时fail closed。成功 terminal 只有在确认没有 late/duplicate 事件之后才会提交。持续有 RPC stream event 的长请求会刷新 idle watchdog——健康的长请求不受固定 60 秒总时限约束，只有超过 idle limit 仍无活动才超时。

异步迭代要求：async-iterator 的消费/ack 必须遵守 backpressure，绝不要把无界上游流整体缓存后再处理。

取消、超时与背压

用户中断或模型超时后，Kun 会调用cancel(requestId)，停止向 UI/Agent history 投影晚到事件，并在 cancellation grace 后释放状态。Adapter 应当同时中止上游 HTTP 请求、读取循环与计时器——示例扩展中cancel()把 requestId 记入#cancelled集合，stream循环每次迭代检查该集合，实现协作式取消。

默认 Host stream 窗口为 32 个未确认事件或 4 MiB（以先到达者为准），平台 policy 可以收紧。消费者落后时应当暂停上游读取，而不是继续堆积。超过 queue、payload 或 idle 限制时，以 Provider protocol/limit error 失败，且只影响该扩展本身，不会波及其它 Provider 或 built-in 模型。

用量与工具调用

只报告上游确实返回的 usage。Kun 把可用字段归一化进主用量/记账路径，并保留 Provider/model/account/run 归属（attribution）。估算值不能冒充 Provider 原生的 cache hit/miss 或 cost——要么标记为 estimate，要么省略；
工具调用分片必须携带稳定的 call ID。并行调用的分片可以交错，但不同调用的 name/arguments 绝不能混在一起；
Provider 只负责生成tool call；真正的执行仍会经过 Kun ToolHost、pinned catalog、权限、审批、预算与取消机制。

绝不静默回退（Never Silently Fall Back）

当显式 Binding 的 Provider、account 或 model 出现以下任一情况时，Kun在不把对话发送给其它 transport 的前提下直接失败：

unknown / uninstalled / disabled / incompatible；
circuit-open（熔断开启）或 Host 崩溃；
账号 missing / expired / interaction-required；
模型属于另一个 Provider；
capability 不足；
stream/protocol 失败。

Kun 不会切换到默认 Provider、另一个账号、或另一个 Provider 的同名模型。正确做法是修复 Binding 或恢复原 Provider，然后由用户/调用者显式重试。示例扩展的stream中对MODEL_NOT_FOUND与ACCOUNT_UNAVAILABLE直接 yield error，正是这一原则的体现。

数据披露与脱敏日志

扩展 Provider 会收到完整的模型可见请求：对话历史、system/mode 指令、附件与工具 schemas。安装权限确认与首次选择 Provider 时，Kun 会展示 Provider owner 与数据类别；如果新版本扩展了权限或输入能力，扩展将保持禁用直到用户重新确认。

Adapter 的错误/日志默认只能保留：extension、Provider、model、account ID、request ID、operation、规范化 category、retryability 与脱敏摘要。禁止记录完整 prompt、附件 body、authorization header、原始 adapter error payload 或 secret。Kun 会把常见的 authentication、authorization、rate-limit、invalid-request、unavailable、adapter-failure 映射为固定错误码，原始code/message/details不进入 history 或持久化诊断。源码中ExtensionModelProviderDiagnostic的category枚举（authentication/authorization/rate_limit/invalid_request/unavailable/adapter_failure/protocol）即对应这一规范化模型（见 kun/src/adapters/model/extension-model-provider.ts）。

用户选择与持久化 Binding

Extension Center 中的Provider 账号卡片是核心拥有的选择入口。流程为：用户连接账号 → 选择该账号实际可用的模型 → 点击「审阅并保存绑定」。Kun 会在 Main-owned protected window 中展示：扩展 owner、精确扩展版本、Provider、模型、opaque account reference，以及 Provider 可能收到的四类数据（完整对话历史、system/mode 指令、附件、工具 schemas）。确认之前不持久化任何内容、不发送任何模型内容。

确认后，Kun 原子写入一条记录到extensions/provider-bindings.json（存储路径定义见 kun/src/services/extension-provider-account-store.ts）：

providerId + accountId + modelId + ownerExtensionId + ownerExtensionVersion + dataAccessDigest

账号字段只是 opaque reference——API key、access/refresh token、OAuth code、授权 header永远不会进入 Binding。Binding 默认按当前 workspace 隔离，未选择 workspace 时写入 global scope。

Binding 出现在 Kun 模型选择器中的前提（全部满足）：

扩展仍是用户确认过的同一版本，并在该 workspace 中 enabled/trusted；
providers.register、accounts.read、accounts.use:<providerId>权限仍然有效；
Provider Host 已注册且账号状态为connected；
选中模型仍属于该 Provider；
由当前权限与模型能力计算出的 disclosure digest 与用户确认一致。

版本、权限或输入能力的变化会使旧确认失效、要求重新审阅；账号删除、Provider disable/crash、模型移除或 workspace grant 撤销都会让 Binding显式 unavailable——Kun 绝不将其修复成默认 Provider、另一个账号或同名模型。

主聊天在创建 thread/turn 时携带该 opaque account reference；扩展 Agent profile 声明相同 Provider/model 但省略 account 时，Kun 会在相同 workspace scope 解析用户已批准的账号；没有有效 Binding 时，在创建 Agent run 之前返回account-required，而不是回退。模型选择器不会把扩展 Provider 写入旧的 built-in Provider 凭据设置，只读取上述核心 Binding，因此 GUI 重启、headlesskun serve与扩展 Agent 遵循同一套 provider/account/model 所有权规则。

账号状态与列表

一个 Provider 可以有多个命名账号。公开账号对象只包含（AccountSchema，见 packages/extension-api/src/accounts.ts）：

稳定的 account ID/reference；
Provider ID；
用户 label；
认证类型（api-key/oauth2-pkce/device-code/custom）；
状态：connected、expired、interaction-required、error或unavailable；
安全的非秘密 metadata，以及protection状态（system/encrypted-fallback/unavailable）。

重命名 label 不会改变 reference 或既有 Binding；列表永不包含 API key、access/refresh token、client secret、cookie 或 credential blob。账号的公开状态还可映射为 Provider 健康状态available/degraded/unavailable/interaction-required（ProviderStatusSchema）。

账号创建与三种认证流程

扩展可以请求账号流程，但凭据只在Host-owned 的受保护界面（protected surface）收集——该界面不加载扩展的 Webview/content script。成功后扩展只得到一个 account reference。

公开的context.authenticationAPI 提供：listAccounts、createSession、getSession、cancelSession、deleteAccount、authenticatedFetch与高风险的revealSecret。账号流程使用 session ID 轮询/订阅五种状态：pending、completed、cancelled、expired、failed。约束包括：

Webview不能直接提交原始凭据；
Node Host 的 session 结果不会取得 authorization URL、device user code 或 protected-form 内容；
pending会话返回可操作的引导说明，由 Kun 自己的账号管理界面继续；只有 Main-owned protected surface 能拿到并显示短期交互材料；
用户可在 Extension Center 的受保护账号管理中重命名账号、原子替换 API key 或删除账号；重命名与换 key 都保留稳定 account ID 与既有 Binding，扩展 SDK 从不接收新 key；每次受保护操作都会绑定 extension/provider/account/operation digest 并写入不含秘密的审计记录。

API Key

用户在受保护表单中输入 key → Kun 存入 Credential Store，普通设置中只写 reference → Provider 可用该 account reference 执行脱敏 probe。替换 key 时原子更新 credential、保持 account ID、清除旧内存副本。probe 失败不得把 key 写入日志、state 或事件。

OAuth 2.0 Authorization Code + PKCE

Account Broker 生成并验证 state/PKCE，callback 只匹配发起交易的 transaction。缺失、过期、重放或不匹配的 callback 一律拒绝且不保存 secret。Code exchange 与 access/refresh token 的存储都在核心完成；用户取消返回cancelled，不创建账号。示例扩展 examples/extensions/streaming-model-provider/kun-extension.json 展示了完整的 OAuth 声明（clientId、redirectUri（kun-extension://协议）、authorizationUrl、tokenUrl、scopes）。

Device Authorization

受保护界面显示 verification URL 与 user code；Broker 遵守 Provider 的 interval、slow-down 与 expiry，保持一个有界 transaction，支持取消。成功后清除 transient code 并存储凭据；过期/取消不创建账号。

Token 刷新与 Credential Store

同一账号的并发 refresh 会合并为一次并原子替换 token。refresh token 被拒绝时账号变为interaction-required/expired，依赖请求显式失败、不切换账号。若上游 refresh 成功但安全持久化失败，Kunfail closed，不提交部分 token 状态。

Credential Store 优先使用操作系统凭据设施；不可用时只允许「已认证的加密回退（authenticated encrypted fallback）」，并向用户暴露非秘密的 degraded-protection 状态。两者都不可用时拒绝保存新 secret——不存在 plaintext-at-rest 回退。普通 settings、thread、extension state、IPC 与 logs 中只能出现 opaque reference。

受代理的 authenticatedFetch 与高危 Secret Read

优先使用 Broker 代发的认证请求（authenticatedFetch），五步流程：

扩展提供获准的 account handle 与允许的 URL/request；
Broker 校验 extension/provider/account/network scope；
必要时执行 refresh；
Broker 注入认证；
返回剥离 credential header 的有界响应。

扩展自行提供的冲突Authorization/credential 字段会被移除或拒绝，绝不与已存储凭据合并。每个手动 redirect hop 与每次 token/refresh 请求都会重新执行 DNS/address policy——先前的 hostname 校验结果不能被复用来连接新解析出的地址。该策略只覆盖 Broker 发起的直接连接：不约束 Node adapter 自己fetch/socket 的行为，也不声称能阻止一个合法公网服务在应用层代转请求。

只有 Node adapter 因自定义签名确实需要原始秘密时，才申请accounts.secrets.read:<providerId>（请求体仅含accountId与operation）。每次成功/拒绝都产生脱敏审计；Webview/content script 永远不能读取秘密；secret 只在最小 operation scope 内使用，不缓存、不记录、不回传 UI。

隔离、删除与缺失 Provider

Broker 从 Host channel 推导调用者身份，强制执行 Provider ownership 与 account scope。一个扩展不能枚举或使用另一个扩展的 private Provider 账号，除非核心明确提供 shared-provider permission。

Provider 扩展被 disable/uninstall 后：

相关 account 与 binding 变为unavailable；
秘密不会被自动删除；
thread/profile 的 binding 保留，用于恢复/诊断；
Kun 不会改绑其它 Provider。

用户显式删除账号时，Kun 删除 credential、invalidates sessions，并把依赖项置为account-required；删除确认前应展示受影响的 Bindings。

Headless 运行

有效的已存储账号可在 GUI 关闭时由kun serve、定时任务或 CLI 使用/刷新。需要 login、consent 或 secret-unlock 交互时，返回稳定的interaction-required与可操作的 continuation，既不会挂起，也不会隐式打开 renderer。这让扩展 Provider 天然支持无人值守的自动化场景。

旧凭据迁移（Legacy Credential Migration）

GUI 首次读取旧版kun-settings.json（或兼容的旧文件名）时，会为每个 Provider profile 与 Kun runtime override 建立独立的稳定 source ID，然后按固定顺序迁移：

在设置文件旁创建权限收紧的一次性回滚备份*.pre-extension-credential-migration.json；
先把secret 写入受保护的 Credential Store；
创建或复用kun.core账号，并在provider-bindings.json写入providerId + accountId + modelId；
在legacy-credential-migrations.json写入仅含 salted digest、opaque reference 与secure-committedphase 的恢复记录；
原子重写普通 settings，从 Provider profile/runtime override 中移除明文；GUI 管理的 Kunconfig.json也只写credentialSourceId，绝不写入 key 或 credential-derived header；
settings 落盘成功后，把恢复记录推进到settings-committed；下一次启动按 account reference 从安全存储解析请求凭据。

细节语义（均有测试覆盖，见 kun/src/services/legacy-provider-credential-migration.test.ts）：

同一 Provider 的相同 legacy secret 复用一个账号；不同 secret（如 Provider profile 与 runtime override 不同）保留为不同账号与 Binding；
Provider 暂时缺失时，账号与 Binding 保持unavailable；Provider 恢复后重新解析，不删除、不改绑；
迁移完成后从旧备份重新引入的明文不能覆盖安全存储中更新的 credential；受保护流程替换 key 时保留稳定 account ID；
普通 settings 写入失败时，回滚本次 pending 更新，原文件保持权威可读，且不写 completed marker；
进程在安全提交后中断 → 下次启动按 phase 重试或回滚；进程在 settings 原子写后、marker 完成前中断 → 从已存在的安全 account/binding 完成 marker；
markers、account records、Bindings 与 logs 永不包含 secret。

为兼容现有同步核心 Provider 调用，本 release cycle 的 Electron Main 进程会把账号凭据临时投影到内存中的 legacy settings shape——该投影不会写回普通文件，也不是 Extension API；扩展始终只能看到 account reference 与脱敏元数据。下一个不再支持该 legacy shape 的 major 版本会移除这条兼容读路径，详见状态与兼容迁移与权限与秘密。

官方测试清单与验证建议

原文档给出了覆盖全流程的测试清单，扩展作者可对照自测（对应测试文件可参考 kun/tests 与 kun/src/services/extension-host-broker.accounts.test.ts 等）：

probe / listModels / 静态 + 动态 catalog 合并；
text / reasoning / 并行分片 tool call / usage / terminal 全事件路径；
错误顺序 / 超限 payload / 超时 / 背压 / 取消与 late event；
Host crash / circuit 与显式 no-fallback；
多模态能力拒绝（capability rejection）；
多账号、重命名 / 删除 / 缺失 Binding；
API-key 拒绝、PKCE state/replay、device interval/expiry/cancel；
并发 refresh 与 secure-store 失败（fail closed）；
authenticated-fetch 的 header 处理与 secret-read 审计/脱敏；
headless 成功与interaction-required；
迁移幂等性、回滚备份与 unavailable Provider 保留。

小结

Kun 的 Provider/Account/Binding 三层模型把「模型传输」从 Agent 运行时中彻底解耦：扩展只需在 Manifest 中声明 Provider 与认证、实现五个方法的 Adapter、按七事件流协议 yield 规范化事件，即可获得与 built-in Provider 同等的路由、用量、工具执行、权限审批与安全边界。对扩展作者而言，最重要的三条纪律是：Binding 必须自洽、绝不静默回退、秘密永不进入扩展可见的任何普通状态——这既是协议约束，也是源码中每一处校验与脱敏逻辑共同保障的安全基线。