ambleloft主页 Webview API
@ambleloft/extension-sdk/webview 用于独立插件主页。聊天内自定义 UI 使用另一套 MCP Apps 协议。
API 参考
按章节查看契约、签名、字段与示例；未注明的默认值不作推断。
本页内容
01初始化与调用
在浏览器入口创建客户端并等待 initialize。下面的 operation ID 必须换成自己的已声明操作。Result 使用 ok 区分成功与失败；unwrap 会将失败抛为 ExtensionError，不会重试。
src/page.ts · call pattern
import { createClient, unwrap } from '@ambleloft/extension-sdk/webview';
const client = createClient();
const host = await client.initialize();
const result = await client.invoke('samples.hello-operation.count', { text: 'Hello' });
const output = unwrap(result);
console.log(host.locale, output);02WebviewClient 方法
点击页面按钮不是宿主授权。invoke 的写入确认由宿主针对具体请求处理；不要在页面自行制造授权令牌。
| 字段 / API | 说明 |
|---|---|
| initialize(): Promise<HostContext> | 首次握手，读取协议、主题、语言和支持方法。 |
| invoke(operationId,input,{signal?}?): Promise<Result<JsonObject>> | 调用已声明操作；signal 为 AbortSignal。 |
| selectProject({capabilities}): Promise<Result<Project|null>> | 用户取消返回成功值 null。 |
| requestGrant({projectId,capabilities}): Promise<Result<boolean>> | 用户取消返回 false。 |
| requestSecretInput({key,title}): Promise<Result<{saved:boolean}>> | 仅返回是否保存，页面无法读取密钥值。 |
| onHostContextChanged(listener): Disposable | 订阅主题/语言等上下文变化并释放。 |
03HostContext 与能力
不要假定旧宿主支持所有方法。supportedMethods 可用于界面降级；能力声明和授权依然由宿主裁决。
Type signatures
interface HostContext {
protocolVersion: '1';
extensionId: string;
pageInstanceId: string;
locale: string;
theme: 'light' | 'dark';
supportedMethods: string[];
}
type Capability = 'projects.read' | 'projects.path.read'
| 'conversations.create' | 'conversations.open'
| 'storage' | 'configuration' | 'secrets';04失败对象
保留 code、requestId 与 effectStatus 供排错。unknown 表示业务可能已经执行；不能因为 UI 超时就自动重试写入。
Result / Failure · signatures
type Result<T> = { ok: true; value: T } | { ok: false; error: Failure };
interface Failure {
code: ErrorCode;
message: string;
requestId: string;
effectStatus: 'notStarted' | 'unknown' | 'completed';
details?: JsonObject;
}