服务契约层（services）
每个 @aalis/api-* 契约包对应一篇文档，面向写 provider 或消费服务的第三方作者。 每篇统一结构：一句话定位 + 服务注册名 → 契约接口签名 → 谁提供/谁消费 → 写一个 provider（最小必须 vs 可选、 provide 注册、双源对齐）→ 标准消费方式（业务句柄 caps.x.use）→ 能力/风险→影响 → 边界与注意事项 → 交叉链接。
先读概念层（服务模型、惰性访问、双源 manifest），再按需查下表。
基础设施
| 服务 | 定位 |
|---|---|
| storage | 存储后端：声明根（读/写/删权限位）、<root>:/path 读写删；resolveLocalPath 可选且非沙箱。参考实现 storage-local。 |
| memory | 会话消息持久化 + 最近消息/区间查询。参考实现 memory-sqlite。 |
| vectorstore | 向量库 add/search/deleteByFilter；维度不匹配处理；flat 与 lancedb 的 score 均为余弦相似度、跨后端量纲对齐（边界处微小浮点漂移）。 |
| embedding | 文本 → 向量 provider。 |
| process | 子进程执行 + readExternalFile；输出缓冲须有界；非沙箱。参考实现 process-local。 |
| code-sandbox | OS 级沙箱（bwrap/seatbelt）、fail-closed；v1 非强隔离、不挡读。参考实现 code-sandbox-os。 |
消息与平台
| 服务 | 定位 |
|---|---|
| gateway | 平台消息网关：入站/出站路由；adapter 经它收发，agent 回话走 dispatchOutbound。 |
| platform | 平台身份/self 识别 helper，供 adapter/persona 消费。 |
| message | 契约（Message role×kind 模型）——详见概念层 message-llm-pipeline，本篇为类型速查。 |
| message-archive | shadow 归档服务；串行归档契约。 |
| trigger | 要不要开口：选出当前生效的触发插件（规则 plugin-trigger-policy 或模型 plugin-trigger-laya，二选一），由它在 inbound:trigger 相位判定。 |
| flow-control | 会话级节流硬闸：禁言、回复后冷却、限速；要不要开口由生效的触发插件判定。 |
智能体核心
| 服务 | 定位 |
|---|---|
| agent | agent 回合编排（LLM loop）；agent:input:before/agent:turn:before/agent:turn:after hook；abort 语义。 |
| llm | LLM 对话 provider：出口必调 prepareLLMMessages、流式 + 工具调用、model 句柄带能力元数据。参考实现 llm-openai/llm-deepseek/llm-ollama。 |
| persona | 人设角色卡 + outputFormat + 状态持久化 + skills 白名单。 |
| commands | /command 注册与分发；authority risk 门控。 |
| session-manager | 会话生命周期、场所与会话树 + subtask inputContext；按会话覆盖插件配置见 api-session-settings。 |
安全与确认
| 服务 | 定位 |
|---|---|
| authority | 访问控制：开放数字等级 + 双轴（等级 + 确认）；risk/visibility/deniedCapabilities；owner=∞。参考实现 authority。 |
工具与媒体
| 服务 | 定位 |
|---|---|
| tools | 工具注册表：ToolDefinition（{type:'function',function:{...}}）+ handler 返回 string 或 ToolExecutionResult（需要交图给主模型时）；执行守卫（restricted/confirm）。参考实现 tool-system。 |
| tool-session | 按会话 id 读历史（session-history），能读哪些会话按会话管理的规则。 |
| media | 媒体转码/图片描述；detailLevel 档；描述缓存用 util-bounded-map。 |
| asr | 语音转写 provider（音频 → 文本）。参考实现 asr-openai/whisper-cpp。 |
调度与运维
| 服务 | 定位 |
|---|---|
| workflow | 工作流引擎 + 触发器；event 触发的事件参数以 {{vars.args}} 注入。 |
| cron-engine | cron 调度原语（workflow/scheduler 触发器底层）。 |
| doctor | 健康检查注册与聚合。 |
前端
| 服务 | 定位 |
|---|---|
| webui | WebUI 扩展 API：注册页面/面板、市场、配置表单（SchemaField）。AGPL 层。 |
其它入口：概念层 · 工具库（utils） · 脚手架上手 · 插件作者隐式契约指南