Core 扩展点索引（一方扩展速查）

@aalis/core 与基础契约包暴露的 declare module 扩展点，及本仓库内谁在 augment 什么—— 便于在一方代码里查定义、查谁扩了什么。

这不是注册门禁。 第三方插件扩展任一扩展点，只需在你自己的包里对扩展点所在的模块写 declare module（事件表 '@aalis/core'、钩子表 '@aalis/api-hooks'、贡献点表 '@aalis/api-contributions'、 配置字段 '@aalis/api-host-config'，见 plugin-author-guide）， 编译期即生效——无需在本表登记，也不会（无法）出现在本表里。扩展点的权威定义在各 -api 包的 declare module 声明；本表只收录本仓库的一方包，作发现与查阅之用，并非全集。 查找一个事件/钩子/贡献点的真实定义，按本表「扩展者」列的包名去 packages/<包目录>/src/index.ts 查（一方实现；例外路径在行内标注）。

核心原则：core 只保留事件表 AalisEvents，它自持基础设施事件，从来不空。钩子表与贡献点表是 @aalis/api-hooks / @aalis/api-contributions 里的空接口，键值由各 -api 包通过 declaration merging 注入。 服务类型随描述符走，不经一张核心服务名表。 这是「忒修斯之船」原则——业务概念可以全部换掉，core 永远不感知它们。

---

1. 服务描述符（不是一张核心类型表）

契约包导出运行时描述符（defineService 的结果）。消费方 import { tools } from '@aalis/api-tools' 写进 uses，apply 参数类型从描述符推导。同名多实现时，use 打到哪一家由「本插件偏好 > 全局偏好 > priority > 注册顺序」决定。

领域能力（LLM 的 tool-calling / vision 等）不在描述符的 name 上—— 它们挂在服务实例 / model-handle 元数据上，由各领域 *-api 的 helper（如 resolveLLMModel）按需筛选。

一方契约包各导出一条描述符，服务名即包名去掉 api- 前缀（agent / asr / authority / checkpoint / code-sandbox / commands / contributions / cron-engine / doctor / embedding / flow-control / gateway / hooks / host-config / host-logs / host-paths / llm / media / memory / message-archive / package-manager / persona / platform / plugin-source / process / session-history / session-manager / session-protocol / storage / todo-list / tools / trigger / user-relation / vectorstore / workflow），两个例外： @aalis/api-webui 导出 webui-server 与 webui-client 两条；@aalis/api-approval 的服务名是 approvals。

没有独立契约包、在自己 src/index.ts 里就地 defineService 的插件：

插件包	注册的服务
@aalis/plugin-cli	cli
@aalis/plugin-memory-vector	semantic-memory
@aalis/plugin-scheduler	scheduler
@aalis/plugin-skills	skills
@aalis/plugin-websearch-serper	web-search

宿主管理面（须显式 uses）：app / plugins 由 core 在根激活上提供（packages/core/src/orchestration/host-services.ts）； host-paths、host-logs、host-config 与 plugin-source 由宿主提供，Node 宿主 @aalis/runtime 四项都提供。

---

2. AalisEvents

EventBus 事件签名表。events.use.on(name, handler) 在编译期靠它做事件名 + payload 约束。

位置：packages/core/src/types/events.ts。core 内置八项，目录与时序说明以 core/events.md 为准 （没有 dispose 事件——清理副作用用 lifecycle.use.onDispose，见 context）

扩展者：

api 包	注入的事件键
@aalis/schema-message	inbound:message / inbound:message:archived / assistant:message:archived / outbound:message / outbound:stream
@aalis/api-agent	token:usage / token:request
@aalis/api-approval	approval:created / approval:settled
@aalis/api-doctor	doctor:updated
@aalis/api-gateway	gateway:phase:done
@aalis/api-media	media:processed
@aalis/api-memory	memory:messages-deleted / memory:messages-rewritten / history:changed / session:compressing
@aalis/api-session-manager	session:created / session:updated / session:completed / session:deleted
@aalis/api-tools	tool:execute
@aalis/api-workflow	trigger:fired / workflow:run:start / workflow:run:done / workflow:run:error / workflow:node:done
@aalis/plugin-scheduler	scheduler:job:start / scheduler:job:done / scheduler:job:error
@aalis/plugin-todo-list	todo:updated
@aalis/runtime、@aalis/plugin-cli	terminal:claimed / terminal:released（同一对键，两处等价声明）

---

3. HookContextMap

中间件钩子上下文表。hooks.use.middleware(name, fn) 在编译期靠它推 data 类型。

位置：packages/api-hooks/src/index.ts（空 interface；增广写 declare module '@aalis/api-hooks'）

扩展者：

api 包	注入的钩子键
@aalis/api-agent	agent:input:before / agent:turn:before / agent:llm:before / agent:llm:after / agent:tool:before / agent:tool:after / agent:reply:before / agent:turn:after
@aalis/api-gateway	inbound:command / inbound:trigger / inbound:flow / inbound:dispatch / outbound:dispatch
@aalis/api-memory	memory:clear

---

4. ContributionPointMap

贡献点表：贡献点名 → spec 类型。contributions.use.contribute(point, spec) / collect(point) 在编译期靠它推 spec 类型。

与 HookContextMap 的分工：改写或截停既有流程 → hooks；往共享产物添自己的一块 → 贡献点。 贡献者拿只读视图、无短路、无排序影响力；排布与执行策略归收集方（贡献点 owner）。

位置：packages/api-contributions/src/index.ts（空 interface；增广写 declare module '@aalis/api-contributions'）

扩展者：

api 包	注入的贡献点键
@aalis/api-agent	agent:prompt（提示词块，锚位 identity / knowledge / context / turn-context / turn-hint）
@aalis/api-memory	memory:clear-type（/clear 的清理类型）

---

5. AalisConfig（配置 schema 业务字段）

宿主配置文档的字段表。@aalis/api-host-config 只声明宿主层字段（name / logLevel / plugins / disabledPlugins / servicePreferences）， 业务字段由 -api 包通过 declaration merging 注入。core 不持配置文档。

位置：packages/api-host-config/src/index.ts（interface AalisConfig；增广写 declare module '@aalis/api-host-config'）。表单描述 CORE_CONFIG_SCHEMA 在 packages/schema-config/src/index.ts，那是宿主侧的渲染词汇，与本接口是两件事。

扩展者：

api 包	注入的字段
@aalis/api-authority	owners / deniedCapabilities / authorityOverrides / authorityGroups / confirmOverrides / restrictedPolicy / network

---

6. 按激活绑定的领域业务层

各契约包导出描述符（值）。消费方写进 uses，apply 拿到选择层，业务层（caps.x.use）带契约定义的登记方法：登记自动归属这次激活，提供者换人整体重挂。不要再给 Context 挂领域方法。

扩展者：

api 包	业务层上额外的方法（在提供者接口之外）
@aalis/api-tools	tools.use.register / registerGroup；withToolGroups(tools.use, groups)
@aalis/api-commands	commands.use.command(name, description?)
@aalis/api-webui	webui.use.definePage / notify（描述符 webuiServer）
@aalis/api-agent	agent.use.registerPreprocessor

示例：

import { agent } from '@aalis/api-agent';
import { commands } from '@aalis/api-commands';
import { tools, withToolGroups } from '@aalis/api-tools';
import { webuiServer } from '@aalis/api-webui';
import { definePlugin, optional } from '@aalis/core';

export default definePlugin({
  name: 'my-plugin',
  uses: { tools, commands: optional(commands), webui: optional(webuiServer), agent: optional(agent) },
  apply({ tools, commands, webui, agent }) {
    const grouped = withToolGroups(tools.use, ['my-group']);
    grouped.register({
      definition: {
        type: 'function',
        function: { name: 'ping', description: 'ping', parameters: { type: 'object', properties: {} } },
      },
      handler: async () => 'pong',
    });

    commands.use.command('hello', 'hi').action(async () => 'hi');

    webui.use.definePage({ key: 'my', title: '我的', icon: 'star', content: [{ type: 'markdown', id: 'about', data: () => '你好' }] });

    agent.use.registerPreprocessor('my-preproc', async (msg, next) => {
      await next();
    });
  },
});

第三方要造同类登记方法：在自己的契约包 defineService(name, port => …)，用 port.registrar / follow / track（BindingPort），在 Object.create(port.provider) 上加方法，不要给内部激活记录加方法。

---

7. PluginMeta

插件定义的元数据扩展点（core 对这里的字段零感知，只原样带在定义上）。PluginDefinition 自持 name / displayName / subsystem / uses / provides / reusable / apply。

扩展者：

包	注入的字段
@aalis/schema-config	configSchema（插件配置表单 schema，默认值经 defaultsFrom 派生）
@aalis/api-webui	extends（对 core 扩展的声明，仅前端展示；页面与提示在 apply 里经 webui.use.definePage / notify）

subsystem 是 PluginDefinition 上的展示字符串，core 不读不校验；第一方界面认的 id 见 DEFAULT_SUBSYSTEM_METADATA。

---

8. 各服务的 XxxCapabilityRegistry

按服务隔离的能力注册表。每个服务自己定义一个 XxxCapabilityRegistry interface， 第三方插件可以 augment 它新增能力字面量。

示例：

• LLMCapabilityRegistry（packages/api-llm/src/index.ts）— LLM 能力

第三方扩展示例：

declare module '@aalis/api-llm' {
  interface LLMCapabilityRegistry {
    AudioInput: 'audio_input';
  }
}

---

速查：我想……

• 加一个新事件 → 在自己的 *-api 包内 declare module '@aalis/core' { interface AalisEvents { ... } }
• 加一个新钩子 → 在自己的 *-api 包内 declare module '@aalis/api-hooks' { interface HookContextMap { ... } }
• 加一个新贡献点 → 在自己的 *-api 包内 declare module '@aalis/api-contributions' { interface ContributionPointMap { ... } }（spec 须含 id: string）
• 加一个新服务 → 在 -api 包 export const mySvc = defineService<MyIface>('my-svc')（登记型再给 bind）。领域能力放到实例 / model-handle 元数据上，用 helper 筛选（可选 XxxCapabilityRegistry 见第 8 节）
• 加一个登记方法 → defineService 的 bind 里用 BindingPort.registrar，返回 Object.assign(Object.create(port.provider), { 登记方法 })
• 加一个配置字段 → 在 *-api 包 declare module '@aalis/api-host-config' { interface AalisConfig { myField: ... } }