AI、上下文与 workflows 参考

准备 AI 实例

配置子系统前，先获取 const ai = await wu.aiReady()。wu-framework/ai 子路径只公开导出 WuAI；context、conversation 和 permissions 对象暴露特定方法，不提供对内部类的无限制访问。

对话示例应先配置带自定义传输或服务器代理的 demo provider。即使 Promise 已成功解析，也必须处理 success:false 的 action 响应。签名中的结果名称描述数据结构，不承诺额外 TypeScript exports。

AI 策略与 core grants 各有用途。确定性 workflows 直接执行宿主基础操作，不是向外来代码授予执行权的 API。完整集成流程请参阅 AI 与 MCP 示例。

wu.aiReady

加载可选子系统，返回可配置的就绪实例。

wu.aiReady(): Promise<WuAI>

• 参数： 使用 core facade 时无需导入 wu-framework/ai。
• 返回值： WuAI 实例的 Promise。
• 错误： 无法导入可选模块时拒绝。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

const ai = await wu.aiReady();
ai.init({ permissions: { executeActions: false } });

即时读取操作请等待 aiReady；lazy facade 可能在加载完成前返回初始值。

参考：src/index.js.

WuAI

使用显式依赖创建 AI 协调器。

new WuAI({ eventBus, store, core?, token? })

• 参数： 与宿主共享的 eventBus 和 store；core 用于查询应用。
• 返回值： 尚未初始化的实例。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

import { WuAI } from 'wu-framework/ai';
const ai = new WuAI({ eventBus: wu.eventBus, store: wu.store, core: wu });
ai.init();

参考：src/ai/wu-ai.js.

ai.init

初始化 providers、对话、actions、上下文及执行保护。

ai.init(config?): WuAI

• 参数： permissions、context、conversation、triggers、agent、orchestrate、rateLimit、circuitBreaker、loopProtection、allowedDomains 和 browser。provider 通过 ai.provider(name, config) 单独注册。
• 返回值： 同一实例；后续调用重新配置支持的选项。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

const ai = await wu.aiReady();
ai.init({ permissions: { executeActions: true, network: false }, allowedDomains: [] });

声明的授权不能隔离自定义处理函数捕获的 JavaScript；宿主代码仍属于可信代码。

参考：src/ai/wu-ai.js.

ai.provider

注册内置 provider 或自定义传输函数。

ai.provider(name, config): WuAI

• 参数： name；adapter、endpoint、model、active；或自定义 send/stream。凭据请通过服务器代理处理。
• 返回值： 同一实例。
• 错误： 不识别 adapter 且没有 send/stream 时抛出。检测到生产环境时，默认移除直接 API key。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

ai.provider('demo', {
  send: async () => ({ content: 'Respuesta determinista', usage: {} }),
});
const result = await ai.send('Hola', { provider: 'demo' });

自定义传输是宿主特权代码，不能用于证明网络隔离。

参考：src/ai/wu-ai.js.

ai.send

发送消息并处理 provider 请求的工具。

ai.send(message, options?): Promise<ConversationResponse>

• 参数： message 字符串；namespace、provider、systemPrompt、templateVars、temperature、maxTokens、responseFormat 和 signal。
• 返回值： 包含 content、namespace 及可用结果/用量的响应。Preflight 拒绝时解析为 content:“[blocked] …”；取消时解析为 content:“[aborted]”。
• 错误： provider 错误通常会拒绝；preflight 阻止和 AbortError 表示为已解析响应，content 中带标记。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： ai.abort(namespace) 中止对应对话；clear 删除历史，deleteNamespace 删除并中止。

const response = await ai.send('Resume el estado', { namespace: 'help', provider: 'demo' });
console.log(response.content);

参考：src/ai/wu-ai.js.

ai.stream

增量提供文本和工具事件。

ai.stream(message, options?): AsyncGenerator<StreamChunk>

• 参数： 与 send 相同的对话选项；provider 必须支持 streaming。
• 返回值： 异步迭代器，chunk 通过 type 区分。
• 错误： provider 错误和 abort 作为 type:“error” chunk 发出。systemPrompt 的构造在 try 之前，可能直接导致迭代拒绝。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

for await (const chunk of ai.stream('Explica el estado', { namespace: 'help' })) {
  if (chunk.type === 'text') console.log(chunk.content);
}

不要假定每个 chunk 都包含文本；还可能是工具结果、完成或错误。

参考：src/ai/wu-ai.js.

ai.json

请求 JSON 输出，将收到的原始文本与解析结果分开。

ai.json(message, options?): Promise<JsonResponse>

• 参数： 可选 schema/schemaName，以及 send 选项。
• 返回值： {data, raw, error, usage, namespace}。
• 错误： 无效 JSON 通过 error 报告，并令 data:null；provider 失败可能导致拒绝。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

const result = await ai.json('Devuelve {"ready":true}', { provider: 'demo' });
if (result.error) console.error(result.error);
else console.log(result.data);

provider 支持 schema 不能替代结果的业务验证。

参考：src/ai/wu-ai.js.

ai.abort

取消一个或全部对话的活动请求。

ai.abort(namespace?): void

• 参数： 可选 Namespace；省略则全部中止。
• 返回值： void。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 中止不删除先前消息；还需清空历史时，使用 conversation.clear。

ai.abort('help');

参考：src/ai/wu-ai.js.

ai.action

注册带描述、参数和处理函数的可执行操作。

ai.action(name, config): WuAI

• 参数： description、parameters、handler；可选 confirm、permissions、permissionsWhen 和 dangerous。
• 返回值： 同一实例。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： executeActions 允许执行；permissions/permissionsWhen 可要求额外 AI 标志。
• 清理： 所属运行时结束时调用 ai.destroy()。

ai.action('math.double', {
  description: 'Duplica un número',
  parameters: { type: 'object', properties: { value: { type: 'number' } }, required: ['value'] },
  handler: ({ value }) => value * 2,
});

参考：src/ai/wu-ai.js.

ai.execute

通过子系统策略和控制执行已注册 action。

ai.execute(actionName, params?): Promise<ActionResult>

• 参数： 精确名称和参数对象。
• 返回值： {success, result?, reason?}；success:false 也属于已解析响应。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： 需要 executeActions 和 action 特定权限；可能要求确认。
• 清理： 所属运行时结束时调用 ai.destroy()。

const result = await ai.execute('math.double', { value: 21 });
if (!result.success) throw new Error(result.reason);
console.log(result.result);

参考：src/ai/wu-ai.js.

ai.trigger

将事件模式连接到助手请求。

ai.trigger(name, config): WuAI

• 参数： pattern、prompt；可选 condition、debounce、priority 和 onResult。
• 返回值： 同一实例。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： ai.destroy() 移除 triggers 创建的订阅。

ai.trigger('cart-help', {
  pattern: 'cart:help',
  prompt: 'Explica cómo revisar este carrito',
  debounce: 500,
  onResult: (response) => console.log(response.content),
});

使用 condition 和 debounce 限制触发；不要在将用于上下文的事件中发布敏感数据。

参考：src/ai/wu-ai.js.

ai.fireTrigger

显式请求执行已注册 trigger。

ai.fireTrigger(name, data?): Promise<unknown>

• 参数： 名称，以及 prompt/condition 配置接收的数据。
• 返回值： 异步执行结果；跳过时可能无结果。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

await ai.fireTrigger('cart-help', { itemCount: 2 });

参考：src/ai/wu-ai.js.

ai.agent

执行可查询上下文并调用 actions 的多步循环。

ai.agent(goal, options?): AsyncGenerator<AgentStep>

• 参数： goal 字符串；maxSteps、namespace、provider 和 signal 等代理选项。
• 返回值： 步骤迭代器，不是单一文本。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： Actions 仍受 executeActions 及其标志约束。限制 maxSteps 不会授予权限。
• 清理： 所属运行时结束时调用 ai.destroy()。

for await (const step of ai.agent('Explica las acciones disponibles', { maxSteps: 3 })) {
  console.log(step);
}

参考：src/ai/wu-ai.js.

ai.capability

以应用功能身份注册 action，供编排使用。

ai.capability(appName, actionName, config): WuAI

• 参数： appName、actionName，以及包含 description、parameters 和 handler 的 action 配置。
• 返回值： 同一实例。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

ai.capability('calculator', 'double', {
  description: 'Duplica un número',
  parameters: { value: { type: 'number', required: true } },
  handler: ({ value }) => value * 2,
});

这里 capability 表示向编排器发布的 action，不会创建 core 的 events.emit/rpc.call/store.write grant。

参考：src/ai/wu-ai.js.

ai.intent

使用应用注册的能力解析意图。

ai.intent(description, options?): Promise<IntentResult>

• 参数： 描述及编排/provider 选项。
• 返回值： 包含 content、tool_results、usage、resolved 和 appsInvolved 的结果。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

const result = await ai.intent('Duplica 7 usando calculator');
console.log(result.resolved, result.appsInvolved);

参考：src/ai/wu-ai.js.

ai.removeApp

移除与应用关联的 AI 能力。

ai.removeApp(appName): WuAI

• 参数： 注册 capability 时使用的名称。
• 返回值： 同一实例。
• 错误： 传播配置或执行错误；应捕获拒绝并检查 action 结果。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 不卸载 core 中的应用，也不删除其全局状态。

ai.removeApp('calculator');

参考：src/ai/wu-ai.js.

ai.workflow

注册确定性操作序列，或由代理解释的步骤。

ai.workflow(name, config): WuAI

• 参数： 非空 steps；deterministic 模式支持 click、type、navigate、wait、emit 和 setState。ai 模式支持描述。可选 parameters、maxSteps、provider 和 temperature。
• 返回值： 同一实例。
• 错误： 注册时名称缺失，或 steps 为空/无效，会抛出。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 所属运行时结束时调用 ai.destroy()。

ai.workflow('mark-ready', {
  mode: 'deterministic',
  steps: [{ action: 'setState', path: 'workflow.ready', value: true }],
});

确定性步骤是宿主基础操作，不调用 ai.action 注册的 actions。它们直接执行，不经过 ai.execute 或其权限检查。

参考：src/ai/wu-ai.js.

ai.runWorkflow

执行 workflow 并发出步骤进度。

ai.runWorkflow(name, params?, options?): AsyncGenerator<WorkflowStep>

• 参数： 注册名称、workflow.parameters 要求的参数，以及执行选项。
• 返回值： 结果的异步迭代器。
• 错误： 未知 workflow 或缺少必填参数会在迭代时拒绝。
• 权限： AI 模式控制其工具调用；deterministic 模式直接执行宿主基础操作，不应用 ai.permissions 标志。只接受可信 workflows 和参数。
• 清理： 所属运行时结束时调用 ai.destroy()。

for await (const step of ai.runWorkflow('mark-ready')) console.log(step);

参考：src/ai/wu-ai.js.

ai.context.configure

配置上下文选择与预算。

ai.context.configure(config): void

• 参数： budget、charRatio，以及包含 store、events 和 custom 的 sources。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.context.configure({ budget: 1500, sources: { store: { include: ['cart'] } } });

参考：src/ai/wu-ai.js.

ai.context.register

添加自定义上下文收集器。

ai.context.register(name, config): void

• 参数： 名称和 {collector,priority}；collector 可以是异步函数。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.context.register('build', { collector: () => ({ release: 'demo' }), priority: 'high' });

参考：src/ai/wu-ai.js.

ai.context.collect

收集应用、状态、事件及已配置的收集器数据。

ai.context.collect(): Promise<ContextSnapshot>

• 参数： 无参数。
• 返回值： Promise
• 错误： 单个收集器失败会被记录，不阻止其余收集器。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

await ai.context.collect();

参考：src/ai/wu-ai.js.

ai.context.getSnapshot

返回上一次收集的上下文，不重新查询来源。

ai.context.getSnapshot(): ContextSnapshot | null

• 参数： 无参数。
• 返回值： ContextSnapshot | null
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.context.getSnapshot();

参考：src/ai/wu-ai.js.

ai.conversation.getHistory

读取对话历史。

ai.conversation.getHistory(namespace?): Message[]

• 参数： Namespace；省略时使用 default。
• 返回值： Message[]
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.getHistory('help');

参考：src/ai/wu-ai.js.

ai.conversation.clear

清空一个对话的消息。

ai.conversation.clear(namespace?): void

• 参数： Namespace；不等同于中止活动请求。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.clear('help');

参考：src/ai/wu-ai.js.

ai.conversation.clearAll

清空所有现有 namespaces 的消息。

ai.conversation.clearAll(): void

• 参数： 无参数。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.clearAll();

参考：src/ai/wu-ai.js.

ai.conversation.inject

向历史添加消息，不发送给 provider。

ai.conversation.inject(role, content, options?): void

• 参数： role、content 和 {namespace}。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.inject('user', 'Necesito ayuda con el catálogo', { namespace: 'help' });

参考：src/ai/wu-ai.js.

ai.conversation.getNamespaces

列出已创建的对话。

ai.conversation.getNamespaces(): string[]

• 参数： 无参数。
• 返回值： string[]
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.getNamespaces();

参考：src/ai/wu-ai.js.

ai.conversation.deleteNamespace

中止并删除 namespace。

ai.conversation.deleteNamespace(namespace): void

• 参数： 精确名称。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.conversation.deleteNamespace('help');

参考：src/ai/wu-ai.js.

ai.permissions.configure

更新已识别的 AI 布尔标志。

ai.permissions.configure(flags): void

• 参数： 标志对象；忽略未知名称和非布尔值。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.permissions.configure({ executeActions: true, network: false });

参考：src/ai/wu-ai.js.

ai.permissions.check

检查 AI 标志是否启用。

ai.permissions.check(permission): boolean

• 参数： 权限名称；未知名称返回 false。
• 返回值： boolean
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.permissions.check('executeActions');

参考：src/ai/wu-ai.js.

ai.permissions.getPermissions

返回 AI 标志的副本。

ai.permissions.getPermissions(): Record<string, boolean>

• 参数： 无参数。
• 返回值： Record<string, boolean>
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.permissions.getPermissions();

标志副本不会向 scoped 应用授予权限。

参考：src/ai/wu-ai.js.

ai.permissions.setAllowedDomains

替换 AI 控制传输所允许的域名。

ai.permissions.setAllowedDomains(domains): void

• 参数： 字符串列表，过滤无效条目。
• 返回值： void
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.permissions.setAllowedDomains(["api.example.com"]);

参考：src/ai/wu-ai.js.

ai.tools

以工具格式描述 actions。

ai.tools(): ToolSchema[]

• 参数： 无参数。
• 返回值： ToolSchema[]
• 错误： 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.tools();

参考：src/ai/wu-ai.js.

ai.expose

浏览器支持时，在 navigator.modelContext 中注册 actions。

ai.expose(): Promise<boolean>

• 参数： 无参数；实验性的 WebMCP 集成。
• 返回值： Promise
• 错误： 没有 navigator.modelContext 时返回 false；捕获单个注册错误。true 不保证所有工具均已注册。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

await ai.expose();

参考：src/ai/wu-ai.js.

ai.confirmTool

接受待处理的工具确认。

ai.confirmTool(confirmationId): void

• 参数： 确认流程发出的标识符。
• 返回值： void
• 错误： 实例未初始化时直接返回，不进行初始化；不请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.confirmTool(confirmationId);

参考：src/ai/wu-ai.js.

ai.rejectTool

拒绝待处理的工具确认。

ai.rejectTool(confirmationId): void

• 参数： 确认流程发出的标识符。
• 返回值： void
• 错误： 实例未初始化时直接返回，不进行初始化；不请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.rejectTool(confirmationId);

参考：src/ai/wu-ai.js.

ai.getStats

汇总 AI 协调器的模块和计数器。

ai.getStats(): object

• 参数： 无参数。
• 返回值： {initialized:false}，或包含 initialized:true 和模块统计的对象。
• 错误： 未初始化时返回 {initialized:false}，不初始化模块。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 协调器所属宿主在关闭时调用 ai.destroy()。

ai.getStats();

参考：src/ai/wu-ai.js.

ai.destroy

中止对话、移除 triggers 并释放协调器模块。

ai.destroy(): void

• 参数： 无参数。
• 返回值： void
• 错误： 实例未初始化时直接返回，不进行初始化；不请求 provider。
• 权限： AI 策略独立于微前端 grants。只配置所需操作。
• 清理： 对象可以重新初始化；前次执行资源被释放。

ai.destroy();

参考：src/ai/wu-ai.js.

在 4.0 的确定性工作流中，emit 步骤需要 emitEvents，且不能面向 wu:、system: 或 app: 事件。setState 步骤需要 writeStore。这些 flags 仍是 host AI 控制，与应用技术 grants 独立。