# Hooks、插件、timeline 与 AI

运行时扩展和延迟加载子系统，明确其执行、注册和权限边界。

<span id="middleware-de-lifecycle"></span>

<span class="section-anchor" id="section-1"></span>

## 生命周期中间件

hook 接收 `(context, next)`。调用 `next()` 继续执行，不调用则取消链。优先级越高越先执行。注册返回取消函数；若中间件生命周期短于 shell，请保存它。`use` 的 TypeScript 声明返回 `void`，但运行时确实提供此清理函数。

```js
const remove = wu.hooks.use('beforeMount', async (context, next) => {
  console.log('Montando', context.appName);
  await next();
}, { name: 'mount-observer', priority: 10 });

// Después de observar el escenario:
remove();
```

阶段包括 `beforeInit`、`afterInit`、`beforeLoad`、`afterLoad`、`beforeMount`、`afterMount`、`beforeUpdate`、`afterUpdate`、`beforeUnmount`、`afterUnmount`、`beforeDestroy` 和 `afterDestroy`。上下文取决于阶段，并非所有 hook 都接收 lifecycle、sandbox 或 props。

中间件在调用 `next` 前抛错时，默认取消；`failOpen: true` 允许失败后继续。导出的 `createSimpleHook`、`createConditionalHook`、`createGuardHook`、`createTransformHook` 和 `createTimedHook` 用于创建中间件。timed helper 记录错误后调用 next，因此不适合作为超时后必须拒绝访问的控制。

<span id="plugin-con-grants-explícitos"></span>

<span class="section-anchor" id="section-2"></span>

## 带显式 grants 的插件

```js
let stop = () => {};

await wu.pluginSystem.use({
  name: 'catalog-observer',
  permissions: ['events'],
  install(api) {
    stop = api.on('catalog:selected', (event) => {
      console.info('Selección observada', event.data);
    });
  },
  uninstall() { stop(); },
}, { grants: ['events'] });

// Al retirarlo:
await wu.pluginSystem.uninstall('catalog-observer');
```

`use` 接受对象或 factory，等待安装并验证权限。`ready()` 可等待尚未完成的安装；`init` 已经等待此屏障。插件 hook 默认超时为 5000 ms。

factory 接收选项，不接收 core。调用 factory 前会复制宿主 grants，防止它扩大选项并自行授权。不过，插件仍是在宿主执行的代码；过滤后的 API 不能隔离该代码已有的闭包或全局访问。

<span id="timeline-y-tiempo-de-carga"></span>

<span class="section-anchor" id="section-3"></span>

## Timeline 与加载时机

```js
await wu.timelineReady();
wu.timeline.record({ snapshotEvery: 64, maxEntries: 5000 });

wu.store.set('demo.counter', 1);
wu.store.set('demo.counter', 2);

await wu.timeline.stepBack();
console.log(wu.store.get('demo.counter'));
await wu.timeline.live();

const recording = await wu.timeline.export();
wu.timeline.stop();
```

`timelineReady()` 在开始前加载 chunk。第一次调用 `record()` 后立即写入，写入可能早于延迟记录器就绪。模块到达期间，facade 会保留 record/stop 意图；要确保捕获下一次写入，请先等待 ready。

journal 记录经过 WU 的 store 写入、事件和生命周期/props。默认上限为 5000 条，每 64 条建立快照。可用 `seek`、`stepBack`、`stepForward`、`live`、`export`、`import`、`entries` 和 `status` 检查记录。

回退会重新生成投影，不会倒转应用内部 timer、HTTP 请求或基础设施。停留在过去时，新写入不会加入 journal，返回 live 会丢弃这些写入。没有历史分支，也没有隐式持久审计。

<span id="ia-optativa"></span>

<span class="section-anchor" id="section-4"></span>

## 可选 AI

主入口安装 lazy proxy。`provider`、`action`、`trigger`、`capability` 和 `workflow` 等可链式方法可以在 chunk 加载期间排队配置；返回数据的操作需要等待真实模块。`aiReady()` 是显式获取方式。

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

ai.action('sum_local', {
  description: 'Suma dos valores de demostración sin efectos externos',
  parameters: {
    type: 'object',
    properties: {
      a: { type: 'number' },
      b: { type: 'number' },
    },
    required: ['a', 'b'],
  },
  handler: async ({ a, b }) => ({ total: a + b }),
});

const result = await ai.execute('sum_local', { a: 2, b: 3 });
console.log(result);
```

注册并执行这个本地 action 不需要向模型发送数据。对话功能提供 providers、`send`、`stream`、`json`、`agent`、triggers 和 workflows，各有权限与配置。不要在公开 bundle 中放置私有服务 key。

Actions 验证参数、检查 `executeActions`、查询额外或条件权限，并可能要求确认。当前代码中 `dangerous: true` 强制确认。执行结果使用 `{ success, result? , reason? }` envelope；权限拒绝可能是失败结果，而不是异常。

默认允许 `readStore` 和 `emitEvents`；`writeStore`、`readDOM`、`modifyDOM`、`readDiagnostics`、`navigate`、`executeActions`、`network` 和 `allowDirectKey` 默认关闭。这些是 AI 模块标志，独立于应用 grants 和服务器授权。

<span id="mcp-y-automatización"></span>

<span class="section-anchor" id="section-5"></span>

## MCP 与自动化

`wu.mcp.connect(url, options)`、`disconnect()` 和 `isConnected()` 暴露延迟加载的客户端桥接。软件包还包含 `wu-mcp-server` 二进制及其子路径。桥接可按模块控制检查和修改状态/界面，但不会自行提供有约束力的 dry-run、幂等性、领域授权、回滚或永久日志。

代理需要操作真实资源时，请使用接收已验证命令并返回 receipts 的服务。store 可以投影其进度，action 不应变成无需重新验证即可执行特权操作的闭包。

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## 实现参考

Hooks：`src/core/wu-hooks.js`；插件：`src/core/wu-plugin.js`；timeline facade：`src/index.js`；journal：`src/core/wu-timeline.js`；AI：`src/ai/wu-ai.js`、`src/ai/wu-ai-actions.js`、`src/ai/wu-ai-actions.js`；默认值：`src/ai/wu-ai-permissions.js`；MCP：`src/index.js`。测试：`tests/unit/plugin-security.test.js`、`tests/unit/timeline-facade.test.js`、`tests/unit/lazy-ai-proxy.test.js`、`tests/unit/ai-actions.test.js`、`tests/unit/mcp-bridge-security.test.js`。