API 包索引

*-api 包是 Aalis 三层包架构中的"契约层"：

@aalis/core              ← 平台无关的运行时（Context / 事件 / 服务注册中心）
       ↑
@aalis/plugin-<X>-api    ← 契约：服务接口、事件 payload、Context 扩展方法、可复用 runtime 工具
       ↑
@aalis/plugin-<X>        ← 实现：具体的 service 注册、handler 逻辑

依赖规则：

• 实现包 import 自己的 -api 包以获得类型与 capability 声明
• 消费方插件只依赖 -api，不依赖实现包，运行时通过 ctx.getService('<name>') 取实例
• -api 包之间允许相互依赖（如 plugin-tools-api 依赖 plugin-authority-api）

包列表

API 包	提供的核心契约	已知实现
plugin-agent-api	AgentService —— 对话编排服务	plugin-agent
plugin-authority-api	AuthorityService + ExecutionGuard —— 权限校验与执行守卫	plugin-authority
plugin-commands-api	CommandService + useCommandService(ctx) —— 命令系统	plugin-commands
plugin-embedding-api	EmbeddingService —— 文本向量化	plugin-embedding-openai / plugin-embedding-ollama
plugin-gateway-api	GatewayService —— 消息入站编排	plugin-gateway
plugin-media-api	MediaService —— 多模态预处理（vision/audio/video）	plugin-media
plugin-llm-api	LLMService + capability 框架	plugin-openai / plugin-ollama / plugin-deepseek 等
plugin-memory-api	MemoryService —— 历史与元数据存储	plugin-memory-inmemory / sqlite / mongodb / vector
plugin-message-api	消息数据契约（无 service）	由各 adapter 直接 emit
plugin-session-manager-api	SessionManagerService —— 会话配置	plugin-session-manager
plugin-storage-api	StorageService —— 受控文件/对象存储 + createStorageGateway / getStorageRootConflicts helper	plugin-storage-local
plugin-tools-api	ToolService + 共享 SSRF/路径工具	plugin-tools
plugin-vectorstore-api	VectorStoreService —— 向量数据库	plugin-vectorstore-flat / plugin-vectorstore-lancedb
plugin-webui-api	WebUIService + 声明式页面组件	plugin-webui-server

阅读顺序

如果你在写新插件：

1. 先看 plugin-storage-api 与 plugin-tools-api —— 95% 插件都会用到
2. 看你要扩展的服务的 api 文档
3. 看对应 docs/plugins/*.md 里现有实现作为参考

如果你在做架构改造：

• 顶层视图见 docs/architecture.md
• 模块边界见 docs/design/api-packages

约定

1. 服务名 = 包名去掉 @aalis/plugin- 前缀和 -api 后缀。例：@aalis/plugin-tools-api 提供 ctx.getService('tools') 取到的 ToolService。
2. 服务一律按名字消费：ctx.getService('storage') / ctx.getAllServices('storage') 只接收服务名，inject.required: ['storage'] 也只列服务名（同名多实现时按「偏好 > 优先级 > 注册顺序」选胜者，可经 ctx.preferService 或 WebUI Services 页调整）。领域能力（如 storage 的 local-path、LLM 的 vision / tool-calling）挂在服务实例 / model-handle 的元数据上，由各领域 *-api helper 过滤（如 resolveLLMModel(ctx, ref, ['vision'])、storage gateway 的 resolveLocalPath），不经 core DI、也不用 getService(name, { capabilities })。
3. 事件通过 declare module '@aalis/core' { interface AalisEvents } 注入；订阅者用 ctx.on('event-name', ...)，类型自动补全。
4. 领域 helper：各契约包导出领域 helper（如 useToolService(ctx) / useCommandService(ctx)），内部封装 ctx.getService + whenService 延迟语义；调用方在 apply 阶段直接使用。Core 不再持有任何业务 Mixin。