参考
架构
运行基座的双层内核结构(engine/ 独立引擎 + runtime/ 生产宿主)、心脏的数学、身体孪生、一次醒来与工具循环、动态上下文管理、五层结构化记忆与 PRIME 闭环、MCP / 沙箱与 TUI 交互链路。
#总体结构与全链路业务蓝图
Quetzal 采用**「独立零依赖内核(engine/)+ 生产运行时宿主(runtime/)」**的双层解耦设计:
engine/(纯内核):包含通用模型协议(types.ts)、多步模型—工具执行循环(loop.ts的runTurn)、动态上下文窗口管理器(context-manager.ts)、结构化记忆状态机(memory.ts)、PRIME 经验蒸馏与演化规则(prime.ts)、纯分词与 BM25 评分策略(retrieval.ts)以及受限研究运行器(research.ts)。零第三方运行时依赖,不导入runtime/。runtime/(单进程 Node.js 22+ 宿主,dist/main.cjs):负责进程装配(main.ts)、身体数字孪生(body/)、心脏自主调度(heart/)、心智宿主与子 Agent(mind/)、结构化记忆持久化与灵魂 Git 同步(memory/)、多模型路由(providers/)、stdio MCP 客户端(mcp/)、权限闸门与平台沙箱(guard/、sandbox.ts)、WebRTC 多身体网状层(mesh/)以及网关与通道(gateway.ts、ops.ts、cli/src/tui.ts)。状态全部写在磁盘上(SQLite 与私有灵魂 Git 仓库),进程重启对 ta 来说只是"睡了一觉"。
系统架构 × 单轮全链路一体蓝图(SVG / HTML5) 独立零依赖引擎(engine/)与生产运行时宿主(runtime/)解耦协作。可在「单轮会话全链路时序图」与「系统架构分层图」之间切换,点击任意阶段或模块查看源码实现与分支逻辑。 一条消息或一次心跳进入大脑后的前 4 步过滤:决定在哪具身体处理、是不是密码、是并入正在跑的轮次还是开启新轮次。Agentic 运行基座:双层内核架构与单轮 6 阶段 22 步执行链路
路由转发 · 保密截取 · 插话/打断分流
Step 01–04mind/brain.ts: converse() / wake() · secrets.ts: intake()关键设计与工程边界
四种会话轮次触发源的链路差异对照
维度 1. 用户对话 (converse) 2. 环境声音/提醒 (ambient) 3. 自主醒来/做梦 (wake) 4. 后台子 Agent (spawnAgent) 触发入口 控制台 / TUI (chat.send)、飞书 麦克风 (/hear)、子Agent报告、同步提醒 心脏泊松抽样命中 think / dream 主 Agent 调用 agent_spawn 工具 入模前内省 无(有话必应) 无(进循环由模型判断回不回) 有:quick 模型 introspect() 决定是否动与选身体 无(创建即在后台独立启动) System 提示词 主 Agent 完整 dynamic 提示词 主 Agent 完整 dynamic 提示词 主 Agent 完整 dynamic 提示词 子 Agent 专用精简提示词(不继承主人格与主历史) 工具表差异 全部可用工具(无 finish) 全部可用工具(无 finish) 全部可用工具 + 专用结束工具 finish 排除 agent_*/session_* + 带 finish 结束判定与去向 不再调工具即回复 → 写 messages + 异步 learnTurn 回复「沉默」则标 ignored 隐藏;否则同对话 调 finish → 写灵魂日记 + 调驱动力 + 做梦演化经验 调 finish → 报告以 ambient 送回父会话
设计原则有四条:
- 内核与宿主解耦:核心循环、窗口预算和记忆验证规则在
engine/独立测试与演进,宿主能力经EnginePorts与TurnControl注入。 - 设备无关:核心只认识
BodyAdapter接口。仓库自带安卓、Termux、Linux、Windows 四个平台级适配器,见 适配器接口。 - 所有控制入口共用一个操作层(
ops.ts):App、网页版、CLI TUI 与飞书的行为一致,都经过审计。 - 没有定时器驱动的自主行为:提醒按承诺准点触发,而 ta 自己的醒来与做梦完全由内驱力与生物钟按概率抽样决定。
#心脏:什么时候醒来
#内驱力与生物钟
| 量 | 范围 | 动力学 |
|---|---|---|
| 好奇心 / 表达欲 / 想念 | 0–1 | 醒着时按各自的时间常数 趋向 1(默认 3 / 6 / 10 小时);睡着时只以 30% 的速度增长 |
| 牵挂 | 0–1 | 进行中的长期目标数 / 5(未完成的念头就是没有步骤的目标) |
| 睡眠压力 | 0–1 | 醒着时趋向 1( h),做事额外累积;睡着时指数回落( h) |
| 昼夜节律 | 0–1 | ,下午 4 点最清醒;夜里强光 ,白天黑暗 |
| 困意 | ;超过 入睡,睡眠中低于 自然醒 |
驱动力的趋近:
这是睡眠研究里的双过程模型(睡眠压力 + 昼夜节律)。默认参数下,ta 在 22:40 左右入睡、7:50 左右自然醒,作息由这两个量算出,没有预设的时刻表。
图表加载中…
#醒来率
瞬时醒来率(次 / 小时):
其中 是加权平均驱动力, 默认 2, 是清醒度, 是抑制系数(急停 / 暂停 / 无模型 → 0;过热 ×0.1、低电未充 ×0.2、离线 ×0.5、预算用尽 ×0.05;再乘活跃度旋钮)。
#抽样:非齐次泊松过程的稀疏化
图表加载中…
醒来间隔服从随时间变化的指数分布。15 分钟只是数值积分的步长,不会触发醒来。
#身体数字孪生
适配器的采样(电量、体温、光照、运动、屏幕、extra)与操作系统信息(负载、内存、存储、联网)一起镜像为内部模型。模型从中派生出身体感受(精力、冷热、明暗、安静 / 被拿起),再与上次比较得到 sense 事件(plugged、light、moved、hot、low_battery、screen_on、online…)。事件调整驱动力并触发重新抽样:被拿起 → 想念 +0.3、好奇 +0.2;光线变化 → 好奇 +0.1。采样间隔随变化在 2–10 分钟之间调整,不调用模型。
#大脑:一次醒来
图表加载中…
生产对话、思考和做梦默认启用 dynamic 动态上下文模式(mind/prompt.ts + mind/context.ts + engine/src/context-manager.ts):系统提示保留人格(SOUL.md)、身份与处境、日历与提醒、安全红线、保密库路径、沙箱状态、身体感受、其他在线身体、技能与自造工具、子 Agent、内在状态、灵魂同步知觉与其他会话近况;不再把常驻记忆全文、笔记目录树和最近日记固定塞进一轮的 system 快照,而是在每次模型请求前按实际候选模型窗口动态重建视图:
- 按候选模型窗口重算(
withModelPreparation):runTurn保留本轮完整原消息,路由层对每个候选模型(含故障转移切换的模型)从完整原消息重新生成克隆视图,绝不在已缩小的视图上二次裁剪。 - 保守预算与原子工具组:采用 UTF-8 字节数 + 消息/工具 Schema 开销 + 图片启发式成本 + 输出预留 + 5% 安全余量;同一次响应的
assistant.toolCalls与紧随的tool结果组成不可拆分的原子组;固定内容放不下时明确抛出ContextOverflow换更大窗口模型,不截断系统政策或本轮用户输入。 - 历史「基座附注」与原文回查(
context_read):历史里 ta 自己的每条回复前插入一条单独的user侧「基座附注」记录过往工具过程(防模型模仿格式编造假记录);超长工具结果自动投影为头尾节选并附context_read(ref)引用,较早历史按完整组分块由 quick 模型生成稳定摘要(context:summary),模型随时可用context_read分页回查 SQLite 原文与完整工具记录。
节奏由 ta 决定:步数不设上限。防止失控靠两道按「无进展」计时的时间墙(模型调用 90 秒无数据 / 180 秒无内容、会话 120 秒无进展)和急停。模型某一步空输出(如推理思考用尽长度)不会直接结束,基座会自动提醒重试最多 2 次;同一工具相同参数连续失败 2 次起自动追加警告阻止原样盲试。
多会话与子 Agent:对话分属不同会话,同一会话内顺序处理,不同会话并行且彼此可见(系统提示里有其他会话近况与 claim 认领锁)。ta 工作时你发来的消息默认插话(steer),也可以选排队(queue)或打断(interrupt)。耗时调研或独立任务可由 agent_spawn 派出后台子 Agent 独立跑工具循环,完成后以 ambient 环境输入送回原会话。进行中的一轮与子 Agent 定期写检查点:基座重启、或做事的身体离线时,在这具或另一具在线身体上从检查点接着做(由协调者决定谁接,同一件事只做一份)。长期目标(goal:步骤、进度、最近推进的时刻)取代未完成的念头,所有身体共用一份。
#记忆分层与 PRIME 经验闭环
记忆系统将**私有 Git 灵魂仓库(长期人类可读真相源)与本机 SQLite(对话、工具详情、FTS5 索引与派生状态)**结合,分为五层运作:
| 层 | 存储位置与格式 | 上下文准入与演进机制 |
|---|---|---|
| 原有人格 / 常驻 / 笔记 | SOUL.md、memories/MEMORY.md、USER.md、notes/**、journal/** | SOUL.md 常驻系统提示;原有 MEMORY、USER、普通笔记与日记保持原样,在结构化检索中兼容映射为标注「旧记忆未核实,仅参考」的 episode/warning |
| 结构化版本记忆 | notes/QuetzalMemory/<id>_v<version>.md(含 quetzal-memory-v1 JSON 与正文/来源) | 分 fact / preference(explicit|inferred)/ episode / experience 四类,状态为 candidate / active / superseded / archived,按 scope、有效期、阶段 stage 与标签/工具条件严格门禁 |
| 完整经历与语境观察 | SQLite messages、tool_calls + 灵魂 obs_* 分片 | 真实用户消息在学习前按 30,000 字符分片保存为 active 语境观察(只验证发言存在,不直接确认个人断言);recall 工具通过 FTS5(或 BM25 降级)全文检索全部对话与笔记 |
| 每步有界语义选择 | engine/src/memory.ts + runtime/src/memory/semantic.ts | 先通过 eligibleMemory 硬门禁,再按个人事实/偏好与经验/经历各半配额预筛最多 20 条短视图,由 quick 模型在每日 64k 预算内选出 ≤6 条注入当前步(超时自动退回同门禁词面排序) |
| PRIME 异步蒸馏与演化 | engine/src/prime.ts + runtime/src/memory/prime.ts | 轮次结束后在后台队列与做梦中提炼候选:个人事实/偏好默认存 candidate(需管理者 memory.confirm 确认后按稳定 slot 升版);真实单工具报错准入为限定 warning;成功 experience 须具备独立结果证据(如 memory.feedback)并通过第二次 quick 语义忠实性评审才激活;演化(rewrite/generalize/combine/archive)缺基线对照时保留候选 |
普通笔记工具(note_save / note_move / note_delete)经路径规范化与真实路径校验,禁止篡改或通过符号链接绕过 notes/QuetzalMemory/ 受管目录。所有记忆改动在 memory.exclusive() 写锁内落盘,并触发基座自动 Git 提交、条目级三方合并与推送。
#工具扩展、MCP、沙箱与 TUI 交互
- 工具汇聚(
mind/tools.ts):allTools()统一挂载内置工具、平台适配器工具、Agent 自造工具(实现在QUETZAL_HOME/tools/<name>,Agent Skills 说明书在灵魂仓库skills/<name>/SKILL.md)、跨身体工具(body_call/move_to)、插件工具(plugin_search/plugin_recommend/plugin_prompt)以及已连接的 MCP 来源提供的工具、资源与提示词。 - MCP 客户端(
runtime/src/mcp/)与插件(runtime/src/plugins/):来源配置在本机config/mcp.json,支持本机 stdio 命令与远程 Streamable HTTP / 旧版 HTTP+SSE(远程地址只收 HTTPS,回环除外,每个请求都经出站检查);远程服务要求登录时按 MCP 授权规范走 OAuth 2.1(发现、动态注册、PKCE,回调经网关本机回环/mcp/oauth/callback,令牌存secrets/mcp-oauth-<id>.json)。使用官方@modelcontextprotocol/client自动协商协议版本,工具暴露为稳定别名mcp_<id>_<sha256前24位>(名称冲突直接拒绝),resources 与 prompts 以基座加的列出 / 读取 / 取用工具交给 Agent。启动与每次调用分别经过mcp_start.<id>与mcp.<id>.<tool>闸门(默认均为询问),凭据只从secrets/mcp_*注入,输出先经redactSecrets脱敏再截断。远程来源缺省经网状层多端同步(不含令牌与凭据),stdio 来源缺省仅本机。插件包兼容 Claude Code 插件格式(.claude-plugin/plugin.json、skills/、.mcp.json、commands/、agents/)、Agent Skills 目录与插件市场marketplace.json,先预览再经控制台确认安装:技能文档写进灵魂仓库skills/,MCP 来源加入配置,hooks 不执行。 - 命令沙箱与真实环境(
sandbox.ts/host-mode.ts):Agent 的命令、自造工具与 POSIX MCP 默认在操作系统沙箱(Linuxbwrap/landlock、Androidproot、Windowssrt-win)中运行,遮蔽secrets/并锁定data/与soul/只读;会话级host_mode每次请求均需用户单独审批。 - 本机终端 TUI(
cli/src/tui.ts):quetzal tui/quetzal chat作为零外部依赖的瘦客户端连接本机回环网关ws://127.0.0.1:7788/rpc,与控制台共用同一个 Agent。所有输出经terminalText()剥离 ANSI 控制序列与双向控制符;会话进入pass_secret保密输入或断线时,TUI 立即静音回显并由TerminalInputQueue硬拦截一切普通文本,且断线超时绝不自动重发请求。
#模型层
一次请求的路径:统一的请求结构 → 按全局顺序遍历已启用模型 → 在该供应商的 Key 之间轮换(最多 2 把)→ 交给四种协议适配器之一。遇到限流、超时或 5xx 换 Key;遇到 400/401/403/404 换模型。Key 用 AES-256-GCM 加密,供应商 id 作为附加认证数据。
#闸门与审计
每个能力类别有三档授权。审批 30 分钟没处理视为拒绝。STOP 文件存在即急停。工具调用、配置修改、记忆修改、审批决定全部写入审计表。
#进程契约
进程守护由外部负责(runit、systemd、Windows 的计划任务)。10 分钟内启动超过 5 次,运行基座进入安全模式。部署者提供 Node.js 22+、QUETZAL_HOME、可选的 QUETZAL_ADAPTER 与守护者。