ambleloftHooks 事件与注册 API
内部 alpha.9 / M2 预览：声明完成事件，在 activate 同步注册，按至少一次语义处理持久投递。
API 参考
按章节查看契约、签名、字段与示例；未注明的默认值不作推断。
本页内容
01事件与调用签名
预览能力 · SDK 0.1.0-alpha.9
只支持下列两种事件。background.job.completed 表示作业进入终态，不能等同于 succeeded。
代码示例
type TurnReference = { conversationId: string; turnId: string; version: number };
type HookEnvelope = { eventId: string; projectId: string; occurredAt: string } & (
| (TurnReference & { type: 'conversation.turn.completed' })
| { type: 'background.job.completed'; jobId: string; status: BackgroundJob['status'] }
);
// ExtensionContext
hooks.register(handler: string, callback: (event: HookEnvelope,
context: { signal: AbortSignal; projectId: string; requestId: string }
) => void | Promise<void>): Disposable;02清单与注册校验
Schema 限定事件枚举和结构。CLI/宿主校验 main、项目权限、重复事件和 handler 名称；hooks 与 operations 的 handler 统一不可重名。声明名称必须与注册名称匹配，且必须在 activate 同步注册。
| 字段 / API | 说明 |
|---|---|
| conversation.turn.completed | 完整工具循环与最终回复结束后生成；非 token 流、非工具片段。 |
| background.job.completed | 用 jobId 调 jobs.get 读取权威结果，处理所有终态。 |
| Disposable | 将注册返回值加入 context.subscriptions，停用时释放。 |
03ACK、重试与顺序
handler 成功返回即 ACK；至少一次投递，相同 eventId 可重复。handler 最长 30 秒，首次失败后最多 5 次宿主重试。同一聊天等待前一 pending/delivering 尝试完成，死信不阻塞后续；跨聊天没有全局顺序。业务副作用必须自行幂等。 ACK 不代表作业或业务成功；这些持久 Hooks 与普通通知监听不同。
04保留与不支持的能力
快照和未确认事件保留 7 天；每扩展事件容量 1000。撤权、停用、卸载会清理对应事件；重新授权不补历史。不提供实时消息流、任意生命周期事件、聊天拦截或修改回复 API。