ambleloft后端 SDK 与调用上下文
@ambleloft/extension-sdk：注册业务操作、访问项目资源、管理扩展状态。
按章节查看契约、签名、字段与示例；未注明的默认值不作推断。
本页内容
01入口与生命周期
defineExtension 接收 activate 和可选 deactivate；activate 可返回 void 或 Promise<void>。operations.register 的 handler 名必须匹配清单 handler。返回对象必须符合 outputSchema。
import { defineExtension } from '@ambleloft/extension-sdk';
export const { activate } = defineExtension({
activate(context) {
context.subscriptions.push(
context.operations.register('echo', async input => ({ text: input.text }))
);
}
});| 字段 / API | 说明 |
|---|---|
| OperationHandler | (input: JsonObject, context: InvocationContext) → Promise<JsonObject>。 |
| Disposable | dispose(): void；加入 subscriptions 管理释放。 |
| extensionId / packageRevision | 只读扩展身份与安装包修订。 |
02InvocationContext
每次调用的上下文由宿主绑定；不得用任意输入替代项目、表单或消息身份。
| 字段 / API | 说明 |
|---|---|
| requestId / caller | 请求标识；caller 为 page 或 agent。 |
| projectId / signal | 可选绑定项目；AbortSignal 用于传播取消。 |
| form? | flowInstanceId、stepId、submissionId、templateDigest、conversationId。 |
| message? | invocationId、messageId、actionId。 |
| resources | 本次调用的 ProjectResources。 |
| authentication.requestSession(resourceId) | 交互式获取 AuthenticationSession，仅 page 调用；登录操作 timeoutMs 设为 120000。 |
03ProjectResources
项目 ID 必须匹配本次调用绑定的项目，清单声明权限还需要运行时授权。创建对话只创建草稿，不启动 Agent。
| 字段 / API | 说明 |
|---|---|
| getProject(projectId): Promise<Project> | projects.read；返回 id、name、description。 |
| getProjectPath(projectId): Promise<string> | projects.path.read；读取项目路径。 |
| createConversation({projectId,title,initialPrompt?}) | conversations.create；Promise<ConversationRef>，包含 id、projectId、state。 |
| openConversation(conversationId): Promise<void> | conversations.open；page 才可交互打开，agent 得到 INTERACTION_REQUIRED。 |
04配置、存储与密钥
相应能力需要在清单声明。KV revision 用于乐观并发控制；null 只允许创建不存在的键，删除后重新创建仍使用 null，修订保持单调。
| 字段 / API | 说明 |
|---|---|
| storage.get(key): Promise<KvEntry | null> | KvEntry = {value: Json, revision: number}。 |
| storage.set(key,value,expectedRevision): Promise<number> | expectedRevision 为 number 或 null；返回新修订。 |
| storage.delete(key,expectedRevision): Promise<void> | 必须提供当前修订，冲突需要重读。 |
| configuration.get(): Promise<JsonObject> | 读取配置；onDidChange(listener): Disposable 监听变化。 |
| secrets.get / set / delete | get(key): Promise<string|null>；set(key,value)、delete(key): Promise<void>。 |
| context.set(key,value): Promise<void> | 值为 boolean / string / number。 |
| l10n.t(key,args?): string | args 为 Record<string,string|number|boolean>；扩展字符串本地化。 |
05runtime-preview 辅助函数
预览能力 · SDK 0.1.0-alpha.9
getResources(invocation) 返回绑定资源访问器，拒绝空 ID，不会在打开时创建对话。observeConfiguration 先订阅再读取，避免旧初值覆盖新事件；不自动重试。
getResources(invocation: InvocationContext): ProjectResources;
observeConfiguration<T>(
context: ExtensionContext,
decode: (value: JsonObject) => T,
onChange: (value: T) => void
): Disposable & { ready: Promise<void> };06迁移到本轮内部契约
预览能力 · SDK 0.1.0-alpha.9
先按入门指南安装同批 SDK、CLI、core 本地包并使用配套宿主。内部版本 0.1.0-alpha.9 不代表正式发行或平台认证。本轮不保留旧宿主五方法兼容：getMessages 要求全部七方法，缺任一方法抛出 UNSUPPORTED。动作记录使用 id 和 effect，reportActionResult 参数使用 invocationId；handler 返回成功后仍需显式报告业务结果。
准备同批本地包07迁移模型工具与重试处理
user-input 是仅类型入口，使用 import type；tools.schema.json 和 validate-input 用于静态校验，实际调用由宿主模型工具完成。保留 UI 返回的完整 flow，更新后使用新 ID。input 创建重试返回当前状态，mutation 重试返回原回执；answer 与 delivery 分开判断。jobs 重试保留原始序列化请求和键顺序，unknown 先核实原任务。分别处理 operation Result、Node rejection、input Result 和 MCP isError，不统一补造错误字段。
运行最小输入案例08运行已提供的消费检查
在配套 ambleloft-extension-samples 根目录执行；前提是协调器已安装并核对同批本地包。第一条覆盖消息、页面授权与取消、CLI 静态正反例；第二条检查类型。宿主替身结果不能证明真实授权或桌面流程。随后按各能力指南在配套宿主检查可见结果和失败恢复；doctor 仍只报告源码匹配，runtimeStatus=not-tested。
node --test verification/local-sdk/consumer.test.mjs verification/local-sdk/cli.test.cjs
node node_modules/typescript/bin/tsc -p verification/local-sdk/tsconfig.json