# AI、上下文与 workflows 参考
AI 子系统的 providers、对话、actions、编排、权限和释放。
## 准备 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 示例](/zh-cn/docs/framework/ai-recipes/)。
## wu.aiReady
加载可选子系统，返回可配置的就绪实例。
`wu.aiReady(): Promise`
- **参数：** 使用 core facade 时无需导入 wu-framework/ai。
- **返回值：** WuAI 实例的 Promise。
- **错误：** 无法导入可选模块时拒绝。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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()。
```js
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()。
```js
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()。
```js
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`
- **参数：** 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 删除并中止。
```js
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`
- **参数：** 与 send 相同的对话选项；provider 必须支持 streaming。
- **返回值：** 异步迭代器，chunk 通过 type 区分。
- **错误：** provider 错误和 abort 作为 type:"error" chunk 发出。systemPrompt 的构造在 try 之前，可能直接导致迭代拒绝。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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`
- **参数：** 可选 schema/schemaName，以及 send 选项。
- **返回值：** {data, raw, error, usage, namespace}。
- **错误：** 无效 JSON 通过 error 报告，并令 data:null；provider 失败可能导致拒绝。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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。
```js
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()。
```js
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`
- **参数：** 精确名称和参数对象。
- **返回值：** {success, result?, reason?}；success:false 也属于已解析响应。
- **错误：** 传播配置或执行错误；应捕获拒绝并检查 action 结果。
- **权限：** 需要 executeActions 和 action 特定权限；可能要求确认。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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 创建的订阅。
```js
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`
- **参数：** 名称，以及 prompt/condition 配置接收的数据。
- **返回值：** 异步执行结果；跳过时可能无结果。
- **错误：** 传播配置或执行错误；应捕获拒绝并检查 action 结果。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
await ai.fireTrigger('cart-help', { itemCount: 2 });
```
参考：`src/ai/wu-ai.js`.
## ai.agent
执行可查询上下文并调用 actions 的多步循环。
`ai.agent(goal, options?): AsyncGenerator`
- **参数：** goal 字符串；maxSteps、namespace、provider 和 signal 等代理选项。
- **返回值：** 步骤迭代器，不是单一文本。
- **错误：** 传播配置或执行错误；应捕获拒绝并检查 action 结果。
- **权限：** Actions 仍受 executeActions 及其标志约束。限制 maxSteps 不会授予权限。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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()。
```js
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`
- **参数：** 描述及编排/provider 选项。
- **返回值：** 包含 content、tool_results、usage、resolved 和 appsInvolved 的结果。
- **错误：** 传播配置或执行错误；应捕获拒绝并检查 action 结果。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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 中的应用，也不删除其全局状态。
```js
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()。
```js
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`
- **参数：** 注册名称、workflow.parameters 要求的参数，以及执行选项。
- **返回值：** 结果的异步迭代器。
- **错误：** 未知 workflow 或缺少必填参数会在迭代时拒绝。
- **权限：** AI 模式控制其工具调用；deterministic 模式直接执行宿主基础操作，不应用 ai.permissions 标志。只接受可信 workflows 和参数。
- **清理：** 所属运行时结束时调用 ai.destroy()。
```js
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()。
```js
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()。
```js
ai.context.register('build', { collector: () => ({ release: 'demo' }), priority: 'high' });
```
参考：`src/ai/wu-ai.js`.
## ai.context.collect
收集应用、状态、事件及已配置的收集器数据。
`ai.context.collect(): Promise`
- **参数：** 无参数。
- **返回值：** Promise
- **错误：** 单个收集器失败会被记录，不阻止其余收集器。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
await ai.context.collect();
```
参考：`src/ai/wu-ai.js`.
## ai.context.getSnapshot
返回上一次收集的上下文，不重新查询来源。
`ai.context.getSnapshot(): ContextSnapshot | null`
- **参数：** 无参数。
- **返回值：** ContextSnapshot | null
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.context.getSnapshot();
```
参考：`src/ai/wu-ai.js`.
## ai.conversation.getHistory
读取对话历史。
`ai.conversation.getHistory(namespace?): Message[]`
- **参数：** Namespace；省略时使用 default。
- **返回值：** Message[]
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.conversation.getHistory('help');
```
参考：`src/ai/wu-ai.js`.
## ai.conversation.clear
清空一个对话的消息。
`ai.conversation.clear(namespace?): void`
- **参数：** Namespace；不等同于中止活动请求。
- **返回值：** void
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.conversation.clear('help');
```
参考：`src/ai/wu-ai.js`.
## ai.conversation.clearAll
清空所有现有 namespaces 的消息。
`ai.conversation.clearAll(): void`
- **参数：** 无参数。
- **返回值：** void
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
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()。
```js
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()。
```js
ai.conversation.getNamespaces();
```
参考：`src/ai/wu-ai.js`.
## ai.conversation.deleteNamespace
中止并删除 namespace。
`ai.conversation.deleteNamespace(namespace): void`
- **参数：** 精确名称。
- **返回值：** void
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.conversation.deleteNamespace('help');
```
参考：`src/ai/wu-ai.js`.
## ai.permissions.configure
更新已识别的 AI 布尔标志。
`ai.permissions.configure(flags): void`
- **参数：** 标志对象；忽略未知名称和非布尔值。
- **返回值：** void
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
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()。
```js
ai.permissions.check('executeActions');
```
参考：`src/ai/wu-ai.js`.
## ai.permissions.getPermissions
返回 AI 标志的副本。
`ai.permissions.getPermissions(): Record`
- **参数：** 无参数。
- **返回值：** Record
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.permissions.getPermissions();
```
标志副本不会向 scoped 应用授予权限。
参考：`src/ai/wu-ai.js`.
## ai.permissions.setAllowedDomains
替换 AI 控制传输所允许的域名。
`ai.permissions.setAllowedDomains(domains): void`
- **参数：** 字符串列表，过滤无效条目。
- **返回值：** void
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.permissions.setAllowedDomains(["api.example.com"]);
```
参考：`src/ai/wu-ai.js`.
## ai.tools
以工具格式描述 actions。
`ai.tools(): ToolSchema[]`
- **参数：** 无参数。
- **返回值：** ToolSchema[]
- **错误：** 子系统尚未就绪时可能初始化；只读方法不会请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.tools();
```
参考：`src/ai/wu-ai.js`.
## ai.expose
浏览器支持时，在 navigator.modelContext 中注册 actions。
`ai.expose(): Promise`
- **参数：** 无参数；实验性的 WebMCP 集成。
- **返回值：** Promise
- **错误：** 没有 navigator.modelContext 时返回 false；捕获单个注册错误。true 不保证所有工具均已注册。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
await ai.expose();
```
参考：`src/ai/wu-ai.js`.
## ai.confirmTool
接受待处理的工具确认。
`ai.confirmTool(confirmationId): void`
- **参数：** 确认流程发出的标识符。
- **返回值：** void
- **错误：** 实例未初始化时直接返回，不进行初始化；不请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.confirmTool(confirmationId);
```
参考：`src/ai/wu-ai.js`.
## ai.rejectTool
拒绝待处理的工具确认。
`ai.rejectTool(confirmationId): void`
- **参数：** 确认流程发出的标识符。
- **返回值：** void
- **错误：** 实例未初始化时直接返回，不进行初始化；不请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.rejectTool(confirmationId);
```
参考：`src/ai/wu-ai.js`.
## ai.getStats
汇总 AI 协调器的模块和计数器。
`ai.getStats(): object`
- **参数：** 无参数。
- **返回值：** {initialized:false}，或包含 initialized:true 和模块统计的对象。
- **错误：** 未初始化时返回 {initialized:false}，不初始化模块。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 协调器所属宿主在关闭时调用 ai.destroy()。
```js
ai.getStats();
```
参考：`src/ai/wu-ai.js`.
## ai.destroy
中止对话、移除 triggers 并释放协调器模块。
`ai.destroy(): void`
- **参数：** 无参数。
- **返回值：** void
- **错误：** 实例未初始化时直接返回，不进行初始化；不请求 provider。
- **权限：** AI 策略独立于微前端 grants。只配置所需操作。
- **清理：** 对象可以重新初始化；前次执行资源被释放。
```js
ai.destroy();
```
参考：`src/ai/wu-ai.js`.
在 4.0 的确定性工作流中，`emit` 步骤需要 `emitEvents`，且不能面向 `wu:`、`system:` 或 `app:` 事件。`setState` 步骤需要 `writeStore`。这些 flags 仍是 host AI 控制，与应用技术 grants 独立。