API 包索引

@aalis/api-* 包是 Aalis 三层包架构中的契约层：

@aalis/core              ← 平台无关的运行时（服务描述符、内置能力、插件定义、编排）
       ↑
@aalis/api-<X>           ← 契约：服务接口、运行时描述符、事件/钩子/贡献点声明、领域 helper
       ↑
@aalis/plugin-<X>        ← 实现：provide.use(描述符, 实现) 与业务逻辑

依赖规则：

• 实现包值导入自己的 -api 包，拿到描述符与类型
• 消费方插件只依赖 -api，不依赖实现包；在 definePlugin 的 uses 里声明描述符，apply(caps) 里经绑定接口取用
• 每个服务名全仓只有一处 defineService，包的发布依赖（dependencies / optionalDependencies / peerDependencies）里不出现插件实现包；两条由 test/architecture/service-contracts.test.ts 守
• 描述符是运行时值，必须进 dependencies，不能只放 devDependencies / import type
• -api 包之间允许相互依赖（如 api-tools 依赖 api-authority）

包列表

API 包	提供的核心契约	已知实现
api-agent	agent 描述符 + BoundAgent（registerPreprocessor）	plugin-agent
api-approval	approvals 描述符 + BoundApprovals（registerSurface）：审批的发起、在场、应答与结算；审批对象类型、approval:* 事件与卡片清洗 sanitizeForCard	plugin-session-server
api-authority	authority 描述符 + ExecutionGuard	plugin-authority
api-checkpoint	checkpoint 描述符 + CheckpointService：存储写前快照、按回合回滚	plugin-checkpoint
api-commands	commands 描述符 + BoundCommands（command builder）	plugin-commands
api-contributions	contributions 描述符 + Contributions（contribute / collect）+ 扩展点 ContributionPointMap	plugin-contributions
api-embedding	embedding 描述符	plugin-embedding-openai / plugin-embedding-ollama
api-gateway	gateway 描述符	plugin-gateway
api-hooks	hooks 描述符 + Hooks（middleware / run）+ 扩展点 HookContextMap	plugin-hooks
api-host-config	hostConfig 描述符（服务名 host-config）+ HostConfig + 配置文档类型 AalisConfig	宿主提供（@aalis/runtime）
api-host-logs	hostLogs 描述符（服务名 host-logs）+ HostLogs：最近的日志与此后的实时日志	宿主提供（@aalis/runtime）
api-host-paths	hostPaths 描述符（服务名 host-paths）+ HostPaths：数据目录、安装集与数据目录布局的绝对路径	宿主提供（@aalis/runtime）
api-i18n	i18n 描述符 + I18nService；出口共用的 localizeFor、贡献点 i18n:pack	plugin-i18n
api-media	media 描述符	plugin-media
api-llm	llm 描述符（per-model handle）+ listLLMModels / resolveLLMModel	plugin-llm-openai / plugin-llm-ollama / plugin-llm-deepseek 等
api-memory	memory 描述符	plugin-memory-inmemory / sqlite / mongodb / vector
api-package-manager	packageManager 描述符（服务名 package-manager）+ PackageManagerService	plugin-package-manager
api-plugin-source	pluginSource 描述符（服务名 plugin-source）+ 插件入口判定 pluginDefinitionOf	宿主提供（@aalis/runtime）
api-reach	reach 描述符（服务名 reach）+ ReachService；档位与越界策略、resolveReach / judgeReach、三张受保护清单 protectedLists、沙箱策略 sandboxPolicyOf、触及凭据的类型与品牌符号	plugin-reach
schema-i18n	给人看的文字对象：原文字典、消息格式与按读者语言解析（库，无 service）	没有实现，各包直接依赖
schema-message	消息数据契约（无 service）	由各 adapter 直接 emit
api-session-history	sessionHistory 描述符（服务名 session-history），按会话 id 读历史	plugin-tool-session
api-session-manager	sessionManager 描述符：会话、场所与会话树	plugin-session-manager
api-session-settings	sessionFields（读取门面）与 sessionSettings（管理面）描述符，服务名 session-settings：插件配置字段按会话覆盖的声明、层表与读取器	plugin-session-settings
api-session-protocol	sessionProtocol 描述符（服务名 session-protocol）+ 会话协议的 zod schema：owner 客户端与守护进程之间的帧、会话列表、条目与回合控制（实验性）	plugin-session-server
api-storage	storage 描述符 + BoundStorage（恒定义 resolveLocalPath / readFileRange / watch，插件私有目录 own）+ 路径文法 helper	plugin-storage-local
api-todo-list	todoList 描述符（服务名 todo-list）+ TodoListService：读与清空会话的待办；TodoItem 与 todo:updated 事件	plugin-todo-list
api-tools	tools 描述符 + BoundTools / withToolGroups；后台任务登记 backgroundTasks	plugin-tools
api-trigger	trigger 描述符（选出生效的触发插件，二选一）与触发插件共用的函数	plugin-trigger-policy（规则判定）
api-user-relation	userRelation 描述符（服务名 user-relation）+ 查询接口 UserRelationService	plugin-user-relation
api-vectorstore	vectorstore 描述符	plugin-vectorstore-flat / plugin-vectorstore-lancedb
api-webui	webuiServer / webuiClient 描述符 + BoundWebui（definePage / notify）；声明式页面、管理面事件与主题格式	plugin-webui-server

阅读顺序

如果你在写新插件：

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

如果你在做架构改造：

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

约定

1. 服务身份是描述符的 name。例：@aalis/api-tools 导出 tools，name 为 'tools'。消费方 uses: { tools }，拿到选择层（list() / use / of(id) / present / follow()）；业务层 use 默认是提供者形状的活句柄，登记型能力的契约在业务层上另加登记方法（如 tools.use.register、webui.use.definePage）。
2. 按名仲裁：同名多实现按「本插件偏好 > 全局偏好 > 优先级 > 注册顺序」选中一家，偏好由用户在 WebUI 设置「系统」的服务偏好或配置 servicePreferences 里调整。领域能力（LLM 的 vision / tool-calling）挂在服务实例 / model-handle 的元数据上，由各领域 helper 过滤（如 resolveLLMModel(caps.llm, ref, ['vision'])），不经 core DI、也不用按能力选服务。
3. 事件通过 declare module '@aalis/core' { interface AalisEvents } 注入；订阅者在 uses 里声明 events，用 events.use.on / events.use.emit。
4. 钩子与贡献点的键分别经 declare module '@aalis/api-hooks' { interface HookContextMap } 与 declare module '@aalis/api-contributions' { interface ContributionPointMap } 注入。使用方在 uses 里声明 hooks / contributions（描述符分别从这两个契约包导入），服务由 @aalis/plugin-hooks / @aalis/plugin-contributions 提供，core 不内置。
5. 业务层 vs 动态查询：登记（工具、指令、页面、预处理器）走业务层上的登记方法，归属这次激活、提供者换人自动重挂。调用选中的那一家用 x.use（活句柄，每次访问重新解析，存起来也跟着换人；optional 先看 x.present）。动态按名查询走 services.use.get，不产生依赖边，关停期可能拿空。把它拿到的原始实例存进字段后，关停边不保护这份缓存引用：提供者有失效逻辑则抛，无则静默成功。