ambleloft页面、Agent 与操作
一份业务逻辑，可以服务于界面操作，也可以被 Agent 调用。
实践指南
完成后：注册业务操作，核对页面调用及失败处理。
前置条件：按本页具体步骤准备所需文件与工具；学习路线中的上一页不自动构成依赖。
本页内容
01注册 Node handler
在 activate 同步阶段注册 handler，使用本次 invocation 绑定的资源上下文。以下代码来自现有 project-card 示例。
代码示例
import { defineExtension } from '@ambleloft/extension-sdk';
export const { activate } = defineExtension({
activate(context) {
context.subscriptions.push(
context.operations.register('describeProject',
async (input, invocation) => {
const project = await invocation.resources
.getProject(input.projectId as string);
return { ...project };
}
)
);
}
});02声明清单
在 extension.json 中声明 main、权限、operation ID、对应 handler、输入输出 Schema。exposeTo: ["page", "agent"] 让同一操作可被两种入口使用。读取项目需要 projects.read 权限与项目绑定。
03页面调用
使用 webview 入口，先 initialize，再选择项目并 invoke。该桥接只能在桌面扩展页面运行。
代码示例
import { createClient, unwrap } from '@ambleloft/extension-sdk/webview';
const client = createClient();
await client.initialize();
const project = unwrap(await client.selectProject({
capabilities: ['projects.read']
}));
if (project) {
const result = await client.invoke('example.project-card.describe', {
projectId: project.id
});
if (result.ok) console.log(result.value);
else console.error(result.error.code);
}04处理失败与取消
取消表示停止等待，不代表撤销已经发生的写入。effectStatus 为 unknown 时不要自动重试。页面卸载时释放订阅；预览能力必须检测实际宿主方法。
检查结果与排错
注册业务操作，核对页面调用及失败处理。
按本页的验证步骤核对实际结果。涉及业务服务时，分别检查界面提交、工具回执与服务端记录。
打开错误代码与排错 →