架构
面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/architecture/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。
Ankole 是围绕 Meta Ankole 公司大脑构建的开源数字总部与企业级 Agent Harness,可私有部署在企业自有基础设施内,将 Pod 协作工作空间与个人助理、专业 AI 同事融为一体,统一提供组织知识、细粒度权限控制、长任务断点恢复与闭环结果反馈。
在这套底座内,成员与 Agent 可连续数小时协同推进复杂工作,调取共享公司大脑,借助浏览器、终端、统一云盘(Unified Drive)、小应用(Applets)及已连接的企业系统执行任务,并交付可供人工复核且能与真实业务结果闭环印证的成果。在每一步操作中,Ankole 都会识别当前责任主体、在运行时强制执行访问规则、从 PostgreSQL 自动恢复中断任务,并将纠偏经验沉淀到后续决策中。
系统总图
工作空间与外部系统
控制面 · 一个逻辑管理边界
执行层 · 单 Agent Worker 与 Function Runtime
持久化边界
每个私有部署实例由一个逻辑控制面、无状态的 Function Runtime(ankole-function-runtime)服务,以及按每个 Agent 独占分配的 Agent Computer Worker 组成。控制面统筹管理身份权限、持久化状态、统一连接器(Connectors)与任务调度,承载 Pod 协作工作空间,调用 Function Runtime 隔离实例执行 Pod 小应用后端、已发布小应用 Action、宿主 MCP 桥接与确定性 TypeScript 程序,并通过 WorkerProviders 按需拉起 Worker,为每个 Agent 提供独享的计算环境。
在业务流转上,Pod 工作空间(层级文档 Docs、基于物理分片的双层 Base 多维表、React + TypeScript 小应用、统一云盘与多人 Pod Chat)与外部渠道适配器共同记录对话发言;各类发言、连接器触发器、Webhook 与定时事件统一由 Ankole.Signals 接纳,按目标分发至 Ankole.Sessions 驱动 Agent 执行,或交由 Ankole.AutomationJobs 运行确定性小应用 Action。统一认证层与身份源提供商提供免密 Email OTP(SiteCredential)、企业 SSO 与组织目录同步;AIGateway 则统一收口语言模型、Embedding、Rerank、图像生成与网页工具能力。
控制面、Function Runtime 与 Agent Computer Worker
控制面保存状态并提交决策
控制面基于 Elixir/OTP 构建,统一掌管 Pod(文档、多维表及物理分片、小应用、统一云盘与多人 Pod Chat)、Meta Ankole(Brain、Skills 与 AGENTS.md / DESIGN.md 契约)、统一连接器(Ankole.Connectors)、Console 管理台、主体与 AuthZ、系统配置、信号路由、Sessions、Workflow、自动化任务(Automation Jobs)、后台 Agent 任务、AIGateway 以及 Control Plane Plugin。所有模块遵循同一条持久化铁律:凡是会改变用户可见结果的状态变更,都必须先提交写入 PostgreSQL,随后才驱动执行或对外投递。因此即使进程随时重启,已接纳的消息、任务进度、长期记忆与审计记录依然完整无损。
运行时,OTP 监督树将不同 Agent、外部连接与后台任务隔离在各自的故障域内:当某条执行分支卡死或崩溃时,控制面仅局部重启并恢复该分支,绝不波及整个实例。核心控制面代码与关键状态机同时经过形式化验证,确保在重试、重启与并发输入交织下核心状态迁移与边界不变量始终成立。
Worker 提供 Agent 专属电脑
主 Agent 循环直接在控制面内运行;只有当会话需要调用电脑环境工具或启动 Codex 任务时,控制面才会按需拉起 Agent Computer Worker。在 Worker 内,Agent 运行终端工具、Skills、无头浏览器、文件读写、MCPorter 工具调用、Git 凭证助手与 Codex 任务;而确定性自动化任务则作为已发布小应用 Action 在 Function Runtime 上独立执行。
每个 Agent 拥有唯一的 Worker 身份,同一时刻最多接入一个活跃 Worker 实例,Agent 之间绝不混用 Worker、缓存盘或凭证。在 Worker 容器(或 Kubernetes Pod)内,受信任的监管进程负责通过 FUSE 挂载 /drive,并将模型驱动的子进程降权至清空 Linux 能力集且无 sudo 的 uid 1000 运行(在 Kubernetes 中还可通过 Pod 模板的 RuntimeClass 叠加 gVisor)。根据所选 WorkerProvider(Docker、Kubernetes、Cloudflare、Vercel、AWS Lambda MicroVMs 或阿里云函数计算),控制面将持久 Agent Home 挂载在 /workspace,将可重建缓存挂载在 /var/cache/ankole,并在 /drive 下投影 Public、MyDrive、AgentDrive、ChatDrive 以及只读的 Brain、Skills、AGENTS.md 与 DESIGN.md。
RuntimeFabric 为每台 Worker 维护一条专属 Phoenix Channel,低延迟传递唤醒、引导、取消、/drive 缓存定向失效通知、实时进度与执行结果。由于 RuntimeFabric 只是实时传输通道而非数据库,断线重连后的故障恢复始终以 PostgreSQL 中已提交的状态为准。
WorkerProviders 选择运行平台与规格配置
运维人员在 Console → Worker Providers 中配置站点级 WorkerProviders,每条记录定义平台类型、YAML 规格与加密存储的平台凭据。多个 Agent 可绑定同一个 WorkerProvider,同时各自保有独立的电脑实例与持久 /workspace 主目录;需要区分底层平台或实例规格时,分别创建不同的 WorkerProvider 即可。
创建 Agent 时可显式指定 WorkerProvider 或沿用站点默认项,保存后绑定关系固定不变。此后控制面按需拉起 Worker,空闲时暂停或释放实例,并在配置升级时完整保留 /workspace 平滑替换旧实例,/var/cache/ankole 缓存则可独立重建;详见 WorkerProviders 与 Workers。
每台 Worker 独立统计环境工作区与 Codex 回合并发槽位;主对话回合、Workflow 与已发布小应用 Action 均在 Worker 之外运行,不占用 Worker 容量。
一条消息如何变成可恢复的工作
对话保存参与者的发言
对话(Conversation)是人类成员与 Agent 共享的协作空间,由 Ankole.Conversations 维护参与者与消息记录——涵盖私聊、多人房间以及用于跨 Agent 委派的隔离 agent_peer 会话。Pod 原生消息直接写入 PostgreSQL;外部聊天工具中的发言由渠道适配器观察登记,消息系统记录仍以外部平台为准。
Ankole 将对话发言与 Agent 内部执行状态严格分离:发言归属于对话参与者,而模型调用、工具结果与上下文压缩属于 Session 在 AIGateway 中的模型链。Session 从不跨越对话边界,一个对话的内部执行过程不会串入另一个对话。
所有刺激由 Signals 接纳
当消息提及 Agent,或定时计划触发、连接器事件/Webhook 到达、延后回查(check-back)到期、后台任务完成时,Ankole.Signals 会先将来源、来源事件 ID、目标、归因与授权信息持久化落库,再唤醒 Session 或入队 Automation Job Run。
Pod 原生消息及其派生 Signal 在同一事务内原子提交。准入阶段按 (target, source, id) 幂等去重以避免重复入队,下游动作则通过各自的幂等键与尝试栅栏(fence)保证安全。
Signal 可显式指定目标 Session,也可通过对话参与关系或信号路由规则选定目标。对话宿主类适配器同时负责观察入站消息与投递回复,事件源适配器则只产生 Signal。对于确定性的定时计划、Webhook 与连接器事件,Ankole.AutomationJobs 直接在 Function Runtime 上执行零模型开销的已发布小应用 Action,仅在确需模型判断时才向 Agent Session 发送跟进 Signal;参见 自动化任务。
Sessions 执行并恢复工作
Ankole.Sessions 统一执掌输入队列、准入控制(Admission)、Driver、Run、内置工具、冷唤醒轮转与故障恢复。同一 Session 在同一时刻只运行一个 Run;每次启动前,Admission 都会核验租户状态、Agent 状态、人类工作授权与访问权限。AIGateway 在每次模型调用前检查 Token 配额。
每个 Agent 在对话中拥有独立的 Session,其执行权限取决于 Agent 子类型:
- 个人助理(
personal_assistant):与内部人类成员 1:1 绑定,在云盘、Pod 与用户组等协作资源上通过Principals.authority_uid/1映射所属成员本人的权限(不含site_console:**与tenant_console:**管理权限),同时保留独立 Agent 主体身份用于审计归因与自有运行时存储。 - AI 同事(
ai_colleague):在云盘、Pod、Workflow、定时任务与后台 Agent 任务中完全使用该 Agent 自身的主体授权执行。当某项写操作(如新建或修订受保护知识对象)超出 AI 同事自身写权限时,Agent 会在 Pod 对话中调用propose_action_card发起交互式审批卡片,交由有权限的人类成员确认执行。在知识召回时,Brain 会对提问者与 Agent 的可读权限取交集(strict群聊中还会与全体在场成员权限取交集)。
在共享群聊中,Agent 公开发出的消息不会自动唤醒其他 Agent,从根源上杜绝死循环。当需要将工作委派给专业 AI 同事时,Agent 会显式调用 send_to_agent 开启隔离的 agent_peer 会话,异步收回同事结论而不混入对方的内部工具历史。同样地,Cron 定时任务与后台任务也在独立 Session 中运行,完成后只把最终消息发布回目标对话。
AIGateway 持久化并续接模型会话状态,会话运行时则负责选择输入、指令、工具、续接断点、冷唤醒轮转(sessions.wake_recycle)与上下文压缩。Driver 利用 PostgreSQL 单调递增的 epoch 栅栏拦截过期写入;故障恢复时从已提交进度继续推进:未完成的模型请求可重新发起,已落库的工具结果直接复用,结果未明的 Worker 工具调用则标记为 interrupted。
Presentation 与 Delivery 提交可见结果
回合结束时,Presentation 一次性确定可见回复:静默回合不产生发言,Pod 原生回复或交互式 Action Card 在完成事务中直接落库,发往外部渠道的回复则先写入持久化 Delivery 投递意图再交由适配器发送。
外部平台确认发送成功后,Ankole 在标记投递成功的同一事务内写入对话发言;后续收到带相同外部消息 ID 的平台回显事件时会自动归并到该行。失败、过期或结果不明的投递绝不生成发言,且对结果不明的投递绝不盲目重发。
实时流式推送仅用于展示生成进度,正式提交后才进入对话历史;断线重连的浏览器客户端直接读取已提交历史与实时运行状态,不会重放半截流式片段。详见对话、信号与执行会话。
Meta Ankole 与 Brain:持续演进的世界模型
Meta Ankole 的 Brain 并非堆放聊天切片的向量库,而是以独立 Brain 根目录下按本体类别(ontology category)组织的 :knowledge 知识页为核心,结合结构化事实(Facts)、观点预测(Takes)、时间线与类型化 brain_links 关系边构建的世界模型。知识来源涵盖 Agent 对话、符合条件的群聊讨论、已登记的 URL Source,以及显式开启事实抽取(metadata.extract_facts: true)的 Space 业务页面。新证据到达时,Brain 补充、修正或更替既有断言;遇到前后矛盾时,离线 Dreaming 会记录冲突供人工复核,而非静默覆盖旧结论。
同一租户内的 Agent 共享同一个租户隔离的知识图谱,并直接复用 Pod 页面实时 ACL 锚点图判权:挂在公共实体名下的私有断言依然严格保留原出处的可见范围,一旦源页面收回访问授权,后续读取会立即过滤掉由此派生的断言与切片。
在线回合中,BM25 + 向量混合召回提供长期上下文;离线阶段,Dreaming 整合新证据、生成继承源页面权限的分析页、对到期预测打分并标出矛盾。在 Brain 掌管组织知识的同时,Meta Ankole 还统一管理共享 Skills 与可组合的 AGENTS.md / DESIGN.md 契约,并通过 Skill Lessons 从后台任务真实轨迹中自动提炼带 7 天租期的单 Agent 流程警示,在不改动共享 SKILL.md 正文的前提下持续减少重复失误。
后台 Agent 任务:不阻塞主会话的长时执行
前台 Agent 可将长耗时调研、数据分析、文档生成、代码修改与 Deep Research 委派给后台 Agent 任务,使主 Session 保持空闲以继续响应用户对话。
控制面在 PostgreSQL 中持久化维护 Job 生命周期;即使底层 Worker 实例发生替换,新实例也能从 /workspace 中的任务工作区与 Codex 线程文件恢复执行。运行期间主 Agent 与 Job 可双向通信:Job 需要人工确认时会主动释放 Worker 并发槽位,待收到答复后无缝续跑,也可按指令返回最终成果或静默结束。
Deep Research 直接构建在这套原语之上:由 Agent Plugin 提供 workspace-template 初始化目录、Skill 提供研究方法论、后台 Agent 任务保障持久执行。草稿工作区留在 /workspace 内,需要对外共享的研究材料与交付物则发布到统一云盘。详见 后台 Agent 任务 与 Deep Research。
AIGateway:统一的 AI 能力边界
AIGateway 将上游 AI 服务与调用方解耦,使个人助理、AI 同事、后台 Agent 任务、Brain、Pod 小应用与外部 OIDC 客户端共享同一个 LLM、Embedding、Rerank、图像生成、Web Search 与 Web Fetch 边界。
Ankole.AIGateway.ModelProfiles 采用三层稀疏继承(Site -> Pod -> Agent/System)并结合跨槽位回退(heavy -> primary 与 light -> primary)解析模型。内置 system 服务主体负责运行内部模型任务,绝不占用任何前台 Agent 的 Token 配额:其中 ankole_brain 执行 Brain 抽取(light)、Dreaming 与教训复核(heavy,缺省回退 primary)、URL Source 抓取(web_fetch)及召回重排(rerank);站点级 brain.embedding_model 则统一驱动共享向量索引。Pod Applet 的无状态 ctx.ai 调用使用所选执行主体:Human 解析 Pod/站点的语言模型默认配置,Agent 解析自身生效的语言模型档案。这些调用不消耗交互式 Agent 的 Token 配额。运维人员在 Console → Model Profiles 集中配置站点、Pod 与 system 主体的模型配置,所有上游 Provider 凭证均加密保存在控制面内。
AIGateway 同时支持无状态请求与可跨轮续接的 WebSocket 模型会话,统一处理协议转换、流式归一化、工具回执、上下文压缩、用量计量与结果提交。面对大规模工具集时,模型可通过 Tool Search 动态检索工具,或通过程序化工具调用(PTC)一次性提交编排脚本;AIGateway 与 Workflow 均在无状态 ankole-function-runtime 隔离实例(POST /v1/program/run)中运行这些确定性 TypeScript 程序。单个 Provider 还可配置多凭证池(含 ChatGPT 订阅账号等 OAuth 池),按单把凭证独立追踪冷却、重试与用量。详见 AIGateway 与 添加 LLM Provider。
企业身份、统一连接器与扩展机制
Ankole 将人员、Agent 与内置服务(system、ankole_brain)统一表示为支持租户内重命名的 (tenant_id, uid) 主体(Principal)。免密认证贯穿 Pod 与 Console:个人 SiteCredential Email OTP 与租户级企业身份源(OIDC/OAuth SSO 及组织目录同步)在无需存储密码的前提下完成成员与管理员认证。
Ankole.AuthZ 在 Elixir 控制面与 Rust 内核中按主体(或个人助理在协作资源上的所属成员)、权限组、云盘 5 位 ACL 锚点、执行动作与 CEL 条件实时裁决权限,绝不依赖提示词约定。
编译期集成的站点级 Control Plane Plugin 提供六类子系统适配器契约(Signals 适配器、Webhook 处理器、身份源提供商、AIGateway Provider、WorkerProvider 类型以及 connectors.connector 统一连接器)、受监督 OTP 进程、外层 HTTP Plug、双作用域 /api/v2 JSON:API 路由、领域事务钩子、AppConfigure 配置项与类型化 UI 插槽。Agent Plugin 负责打包成员 Skills、Codex Hooks 与 workspace-template 目录;Ankole.Connectors 则运行控制面 MCP 网关(/api/internal/mcp/toolkits/:toolkit 与 /api/internal/mcp/skills/:skill/:server),将租户应用密钥(authConfigId)与个人 OAuth 令牌安全保存在 PostgreSQL 中,并通过 MCPorter 与宿主桥接器分别向 Worker 和 Function Runtime 小应用暴露明确的工具契约。详见 主体与权限组、Control Plane Plugins、Agent 能力库 与 使用 MCP。
持久化边界
PostgreSQL 18+ 控制面数据库保存全部权威领域事实——涵盖身份、AuthZ 授权、系统配置、连接器凭证与触发器、Pod 页面树与 XML 正文、Meta Ankole 的 Skills(skills、skill_files)与 AGENTS.md / DESIGN.md 契约(agent_contracts)、对话消息、Sessions、自动化任务、后台 Agent 任务、Brain 断言与本体关系、投递状态及审计记录;物理 **Base 分片数据库(BASE_DB_URLS)**则保存各租户的 Base 表记录。执行时间点恢复(PITR)时,所有 Base 分片库的恢复目标时间点必须晚于或等于(>=)控制面数据库。判断某项结果是否已正式生效,一律以 PostgreSQL 记录为准。
对象存储(控制面文件存储中的 file_objects)保存不可变的统一云盘文件字节、Pod 与对话附件、Skill 附属文件以及编译后的小应用产物包;持久 Agent Home(/workspace)则单独保存会话与任务草稿工作区、用户安装的软件包及 Codex 线程文件。灾备备份时必须将控制面 PostgreSQL 数据库、全部物理 Base 分片数据库、对象存储、所有 Agent Home 以及部署加密密钥一并备份。
RuntimeFabric 连接、ankole-function-runtime 隔离实例、运行中的 Worker 进程、/drive FUSE 缓存、流式预览与 /var/cache/ankole 均属无状态或可重建数据;唯独 /workspace Home 必须在实例替换后持久保留并纳入备份,详见备份与还原。
三种部署形态
| 形态 | 控制面、Function Runtime 与 Worker | 持久化 |
|---|---|---|
| Docker Compose · 单机推荐 | 单台 Linux、macOS 或 Windows 主机运行控制面与 ankole-function-runtime,控制面通过 Docker Socket 为每个 Agent 按需创建独立 Worker 容器 |
PostgreSQL 18+(及配置的 BASE_DB_URLS 分片库)、对象存储与每个 Agent 独享的持久 /workspace Home 卷 |
| Kubernetes · 企业生产推荐 | Helm 部署控制面与 ankole-function-runtime Deployment,控制面调用 Kubernetes API 为每个 Agent 创建带 /dev/fuse(用于 /drive)的独立 Worker Pod |
PostgreSQL 18+ 与物理 Base 分片数据库、对象存储、持久 Home PVC 或共享存储;缓存卷独立挂载 |
| 源码安装 | bun run services:start 启动 PostgreSQL 18 与 ankole-function-runtime;bun dev 启动控制面,并以监听(watch)模式为每个 Agent 创建 Docker Worker 容器 |
PostgreSQL 18、var/ankole-dev/files 与独享 Docker 持久 Home 卷 |
三种部署形态共享同一套逻辑边界:单一控制面统筹全局,并通过 WorkerProviders 为每个 Agent 分配隔离的专属 Worker。分步安装流程请参阅 快速开始。
支撑运行时的五项技术选择
| 机制 | 解决的问题 |
|---|---|
| Virtual Actor 承载 AI 工作 | 为每个 Session 赋予固定地址、消息信箱、生命周期与精确恢复断点 |
| OTP 监督树划分故障域 | 局部自愈单个 Agent、连接器长连接或任务分支,不波及整套实例 |
| Phoenix Channel 承载实时控制 | 在运行期间低延迟传递唤醒、引导、/drive 缓存失效通知、进度与背压信号 |
| Worker 与 Function Runtime 分层执行 | 为每个 Agent 提供带 /drive FUSE 与 /workspace 的独立电脑,并在无状态隔离实例中运行小应用 Action 与 PTC/Workflow |
| PostgreSQL 账本保存权威事实 | 让 Pod 页面、连接器、消息、任务、Brain 断言与已提交操作可恢复、可审计 |
这五项选择共同保证了个人助理与 AI 同事能够跨越 Pod 与聊天渠道连续工作数小时、中途吸收新上下文、在故障时独立恢复,并为每一步已提交操作留下完整审计记录。
关于底层运行时的深入原理,请参阅 《为什么 OTP 是更好的多智能体编排运行时》。