Ruvie Agent Harness（智能体执行底座）架构图

核心结构：Deep Module（深模块）

• CLI（命令行）与 Electron（桌面端）复用同一个 Runtime module（运行时模块），但各自在所属进程创建实例。
• Runtime interface（运行时接口）保持窄：run / dispatch / close（运行/派发控制/关闭）；HostAdapter（宿主适配器）发起 attach（挂接），Runtime（运行时）读取 SessionStore（会话存储）重建权威状态，Projection（投影层）按 seq（序号）去重。
• Transport（传输）、UI（界面）、数据库驱动和模型 SDK（开发工具包）不进入核心。

一致性：Durable Before Visible（持久后确认）

• 完整消息、审批决定、工具终态和运行终态先写入 Journal（日志），再作为权威状态发布。
• Token delta（令牌增量）是可丢弃的预览，不写日志、不用于崩溃恢复。
• GUI（图形界面）重连使用 Snapshot（快照）和 afterSeq（序号游标后事件），不从界面文本反推状态。

安全：Approval ≠ Sandbox（审批不等于沙箱）

• Approval（审批）表达用户是否同意某次调用；Sandbox（沙箱）限制进程实际可访问的系统能力。
• v1 至少实现路径规范化、工作目录限制、环境变量白名单、超时、输出上限和进程树取消。
• 工具产生副作用后不自动重试；崩溃恢复遇到不确定结果时默认合成 interrupted/unknown（中断/未知）结果。

一条任务如何跑完：Happy Path（正常路径）

下列六段对应主图的阅读顺序。工具分支完成后会回到上下文构建，因此一个 Run（运行实例）可以包含多个模型轮次。

输入与准入
01 → 03

持久化并建上下文
04 → 06

模型流与结果判断
07 → 09

审批与工具执行
10 → 13

顺序屏障与下一轮
14 → 17 → 06

持久结束并输出
18 → 19

Host Topology（宿主拓扑）节点说明

宿主只负责收集用户意图、转发命令和投影事件；不复制 Agent Loop（智能体循环）业务规则。

节点	职责	输入	输出	约束
01 Task Input（任务输入）	把文本、附件引用和运行参数规范化为 `UserInput`。	用户输入、模型选择、可选 sessionId（会话标识）。	类型化的开始运行命令。	附件存引用而非把大二进制直接塞进事件。
02A CLI Host（命令行宿主）	参数解析、终端渲染、审批提示、Ctrl-C 取消。	命令行参数和 RuntimeEvent（运行时事件）。	RuntimeCommand（运行时命令）和 stdout/stderr（标准输出/错误输出）。	默认与 Runtime（运行时）同进程，不经过常驻服务。
02B Renderer + Projection Reducer（渲染进程与投影归约器）	将事件投影成聊天消息、工具卡、审批卡和运行状态。	Snapshot（快照）、durable tail（持久尾部事件）和 transient delta（瞬时增量）。	可视界面和用户控制意图。	按 seq（序号）去重；界面状态不是恢复权威来源。
Preload Bridge（预加载桥接层）	暴露冻结、白名单、类型化的桌面端调用接口。	Renderer（渲染进程）的用户意图。	经过校验的 IPC（进程间通信）调用和事件订阅。	不暴露原始 ipcRenderer、Node、文件系统或密钥。
Electron Main（主进程）	窗口、safeStorage（安全存储）、Utility Supervisor（工具进程监督器）和重连。	预加载命令、工具进程退出/错误、加密凭据。	MessagePort（消息通道）命令、恢复状态和桌面事件。	明文密钥只经独立 private channel（私有通道）按需送入工具进程，永不进入公共事件、Trace（追踪）或存储。
utilityProcess（独立工具进程）	承载桌面端 Runtime instance（运行时实例）和单写 SessionStore（会话存储）。	类型化命令、私有运行配置。	事件流、响应、ready handshake（就绪握手）。	先取得 cross-process lease（跨进程租约）；CLI 与桌面端同时打开同一会话时，失败方返回 SESSION_BUSY（会话忙）。它提供 crash isolation（崩溃隔离），不是 OS sandbox（操作系统沙箱）。
RuntimeCommand / RuntimeEvent（运行时命令/事件）	所有宿主共用的版本化协议。	approve / 审批steer / 引导abort / 中止compact / 压缩	delta / 增量messagetoolrun_finished	ControlAck（控制确认）只表示命令已接收，不表示动作已经完成。

GUI Reconnect（图形界面重连）状态机

Disconnected（已断开）
保留 lastDurableSeq（最后持久序号）

Renderer（渲染进程）
attach(lastDurableSeq)（携游标挂接）

HostAdapter（宿主适配器）
订阅事件并锁定 headSeq（水位序号）

Runtime + Store（运行时与存储）
重建快照、持久尾部与待审批项

Resyncing（重新同步）
Projection（投影层）按 seq 重放去重

Live（在线）
接管 > headSeq 的排队事件，无缝转实时流

utilityProcess Crash Recovery（工具进程崩溃恢复）闭环

exit/error（退出/错误）
Main Supervisor（主进程监督器）检测

Recovering（恢复中）
界面停止接受新的副作用命令

spawn + lease（拉起并加租约）
创建新工具进程并取得单写权

checkpoint + tail（检查点与尾部）
重建权威状态

reconcile（对账）
闭合/标记运行与工具，恢复并重发待审批项

ready/replay → Live（就绪/重放到在线）
Renderer（渲染进程）解除命令阻断

如果新进程无法取得 lease（租约），Main（主进程）进入 RecoveryBlocked（恢复受阻）并返回 SESSION_BUSY（会话忙），保持副作用命令关闭。若无法证明崩溃前的 child process（子进程）已被终止，恢复器必须把它记录为 orphan/uncertain side effect（孤儿进程/不确定副作用），并要求人工确认；任何有副作用的工具都不能自动再执行。凭据只走 Main → utilityProcess（主进程到工具进程）的私有启动通道，不进入 RuntimeEvent（运行时事件）、Trace（追踪）或 SessionStore（会话存储）。

Agent Loop（智能体循环）逐节点说明

每一行都描述一个可观察的语义阶段；内部实现可以调整，但顺序、不变量和失败方式属于 Runtime interface（运行时接口）的一部分。

编号与节点	输入	处理	输出	持久化与错误语义
03 Protocol + Admission（协议与准入）	版本化命令、当前 session（会话）状态。	校验 schema（结构）、协议版本、runtime 是否关闭、是否已有活动运行。	规范化请求和新 runId（运行标识），或类型化调用错误。	准入失败在运行接受前抛出；不会产生半个运行记录。
04 Run Coordinator（运行协调器）	规范化请求、控制邮箱、Clock/IdPort（时钟/标识端口）。	建立 runId、attemptId、AbortController（取消控制器）和状态机。	待提交的 `run_started`。	同一 session 同时只有一个 active run（活动运行）；取消命令幂等。
05 Input Commit（输入提交）	run 元数据和完整 UserInput（用户输入）。	通过串行 append queue（追加队列）写入运行开始与用户消息。	durable conversation entry（持久会话条目）。	写入失败立即 fail closed（关闭式失败），不得继续产生模型费用或工具副作用。
06 Context Build + Budget（上下文构建与预算）	系统提示、已提交历史、checkpoint（检查点）、Skills（技能）、AGENTS 规则、steering（引导消息）。	裁剪并构造不可变 bounded context snapshot（有界上下文快照），估算 token（令牌）。	模型请求上下文，或进入 C1 Compaction（压缩）。	绝不在 tool call（工具调用）与 tool result（工具结果）之间切割。
07 Model Attempt + Stream（模型尝试与流）	稳定上下文快照、模型配置、新 attemptId。	调用 ModelPort（模型端口），接收流式片段并响应 AbortSignal（取消信号）。	transient delta（瞬时增量）、usage（用量）、完整 assistant message（助手消息）或分类错误。	增量可合并、可丢弃；完整消息只有形成终态后才能提交。
08 Outcome Gate（结果闸门）	模型请求的 terminal outcome（终止结果）。	归类 completed（完成）、retryable（可重试）、fatal（致命）或 aborted（中止）。	完成进入 09；可重试进入 R1；致命/中止进入终止路径。	provider request end（模型请求结束）不等于整次 run end（运行结束）。
09 Assistant Commit（助手提交）	完整 assistant message 和完整、已校验的 tool arguments（工具参数）。	提交助手消息并提取保持源顺序的 tool-call list（工具调用列表）。	无工具时产生 final candidate（最终候选）；有工具时产生待审批批次。	流未完整或因长度截断的工具参数不得执行。
10 Policy + Approval（策略与审批）	每个 callId、工具风险、路径范围、宿主决策。	执行 policy（策略）并等待 allow/deny（允许/拒绝）；决策恰一次。	获准、拒绝或策略否决的持久决定。	没有审批者时默认 deny（拒绝）；拒绝也要生成合成 ToolResult（工具结果）。
11 Tool Batch Scheduler（工具批次调度）	有序调用批次和审批结果。	串行完成前置检查，再按并发上限启动获准工具。	执行计划和每个工具的 started/progress（开始/进度）事件。	新一轮模型请求必须等待整批工具全部进入终态。
12 Execution Control（执行控制）	工具 schema（结构）、参数、工作目录、AbortSignal。	路径规范化、环境变量白名单、超时、输出上限、进程树中止。	原始成功值、异常、超时或中止状态。	执行器不自动重试；工具是否重放必须由更高层明确证明安全。
13 Terminal Normalize（终态归一化）	成功、deny、timeout、abort、throw 或崩溃后的 unknown（未知）。	把所有分支归一化成 canonical ToolResult（规范工具结果）。	每个已提交 callId 恰好一个 terminal result（终态结果）。	中止也不能绕开工具结果闭合。
14 Ordering Barrier（顺序屏障）	并发工具的整批终态结果。	等待全部闭合；保留 UI completion order（界面完成顺序），重排模型 source order（源顺序）。	适合下一轮模型上下文的有序结果向量。	这是并发执行与确定性历史之间的关键屏障。
15 Tool Batch Commit（工具批次提交）	有序结果向量。	追加 durable tool results（持久工具结果）并刷新 turn boundary（轮次边界）。	合法、闭合的下一轮模型输入。	批次提交完成前不得开始下一次模型请求。
16 Turn Boundary（轮次边界）	工具结果、usage、steering mailbox（引导消息邮箱）和上下文大小。	决定 continue（继续）、compact（压缩）或 finish（结束）。	compact（压缩）进入 C1；continue/finish（继续/结束）进入 17，再由 17 回到 06 或进入 18。	steering（引导）只在安全边界进入上下文，不打断已经提交的工具批次。
17 Continue Decision（继续决策）	轮次状态和无工具的最终候选。	存在工具结果或 follow-up（后续输入）时继续，否则确认最终候选。	下一轮上下文或最终答案引用。	循环回边重新构建上下文，不复用旧的可变请求对象。
18 Durable Run Finish（持久化运行结束）	最终答案、失败或中止结果、usage 与统计。	追加唯一 `run_finished` 并 flush（刷新）。	authoritative final state（权威最终状态）。	一个 runId 最终只能出现一个持久终态。
19 Host Projection（宿主投影）	已持久化终态、快照、事件尾部。	CLI 终端输出或 GUI reducer（界面归约器）投影。	用户可见的最终答案、工具记录和运行状态。	断线后使用 lastDurableSeq（最后持久序号）重放，不依赖瞬时增量。

旁路：Retry、Compaction、Abort、Failure、Recovery（重试、压缩、中止、失败、恢复）

旁路	触发条件	处理顺序	禁止事项	回到哪里
R1 Retry Coordinator（重试协调器）	模型错误明确标为 retryable（可重试），且未超预算。	记录失败 → 可取消 backoff（退避）→ 新 attemptId → 使用同一不可变上下文。	不重试 fatal（致命）错误；不重新执行任何工具。	回到 07；预算耗尽进入 18 failed（失败）。
C1 Compaction Transaction（压缩事务）	超过上下文阈值、轮次边界建议压缩或用户手工要求。	`compaction_started` → 摘要 → 校验 → 追加 checkpoint（检查点）→ 原子采用。	新检查点成功前不删除旧上下文；不切断工具调用/结果。	成功回到 06；失败保留旧上下文并记录结果。
A1 Abort Coordinator（中止协调器）	07–17 任意活动阶段收到 abort（中止）。	停止新副作用 → 取消模型/退避/审批/工具 → 合成未闭合结果 → 通过顺序屏障。	不能把已接收 ControlAck（控制确认）误当成已终止；不能静默丢弃待投递 steering（引导）。	最终进入 18 aborted（已中止）。
F1 Persistence Failure（持久化失败）	任一 durable append/flush（持久追加/刷新）失败。	停止宣称新状态 → 取消后续副作用 → 最佳努力记录诊断。	不能向宿主发布未成功落盘的 complete/terminal（完整/终态）事件。	若仍能追加则记录 failed（失败）；否则只发送 best-effort diagnostic（最佳努力诊断），保持 uncertain（不确定），不进入 18 的已持久化终态。
X1 Crash Recovery（崩溃恢复）	CLI/utilityProcess（命令行/工具进程）异常退出后重启。	单写锁 → checkpoint + durable tail → 忽略撕裂尾行和增量 → 对账未闭合 run/tool。	副作用状态不确定的工具默认不得自动重放；不得从 GUI 文本恢复。	向 RuntimeEvent/Host Projection（运行时事件/宿主投影）输出 authoritative snapshot（权威快照）、待审批项和唯一安全的下一动作；不把 replay（重放）扩张成 Runtime（运行时）的第四个公开方法。

Runtime Invariants（运行时不变量）

这些规则比具体类名更重要，应该成为测试和面试讲解的主线。

Single Active Run（单活动运行） 一个 session（会话）同时最多一个 active run（活动运行）；第二个请求明确返回 SESSION_BUSY。

Monotonic Sequence（单调序号） 持久事件 seq（序号）严格递增、永不复用；GUI 可依据序号去重和增量重放。

Durable Before Visible（持久后确认） 完整消息、审批、工具终态和运行终态先 append（追加），再作为权威结果发布。

Transient Not Authority（瞬时事件不是权威） delta/progress（增量/进度）可合并或丢失，不能用于恢复或推导最终状态。

Exactly One Tool Result（工具结果恰一） 每个已提交工具调用，无论成功、拒绝、超时、中止还是异常，都必须恰有一个终态结果。

Ordering Barrier（顺序屏障） 界面可按完成顺序显示；模型上下文必须按原工具调用源顺序接收结果。

No Unsafe Replay（禁止不安全重放） 已经开始且副作用状态未知的工具，恢复时默认不自动重执行。

Retry Is Classified（重试必须分类） 只有明确可重试的模型错误进入退避；工具不自动重试，致命错误直接结束。

Abort Still Closes（中止仍需闭合） 中止要停止新副作用，并为所有未闭合工具调用生成终态结果。

Atomic Compaction（原子采用压缩） 新 checkpoint（检查点）成功前，旧上下文始终保持为权威来源。

Exactly One Run Finish（运行结束恰一） 每个 runId 只有一个持久 run_finished，避免多终态和重复结算。

Approval ≠ Sandbox（审批不等于沙箱） 审批控制用户意图；真正的能力限制必须由 ToolExecutor（工具执行器）或操作系统沙箱完成。

Monorepo（单仓多包）映射与建议实施顺序

Workspace（工作区）	对应图中节点	第一阶段职责	后续扩展
`packages/protocol`	RuntimeCommand / RuntimeEvent（运行时命令/事件）	版本化 schema（结构）、错误码、序列化 DTO（数据传输对象）。	MessagePort、JSONL RPC 等 transport（传输）复用。
`packages/runtime`	03–19、R1/C1/A1/F1/X1	唯一 deep module（深模块）：循环、控制、审批、持久顺序和恢复。	Skills（技能）、MCP、更多 Provider（供应商）仍通过内部端口接入。
`packages/adapters-node`	ModelPort、ToolPort、SessionStore（模型/工具/存储端口）	OpenAI-compatible（OpenAI 兼容模型）、read_file（读文件）、JSONL 存储。	apply_patch、exec、container sandbox（容器沙箱）、MCP。
`packages/testkit`	所有 Port（端口）的确定性测试适配器	ScriptedModel（脚本模型）、MemoryStore（内存存储）、FakeClock/FakeId（假时钟/标识）。	故障注入、随机交错、golden replay（黄金事件重放）。
`apps/cli`	01、02A、19	第一条可运行纵切：输入任务、展示流、审批、Ctrl-C。	`--resume`、`trace`、可选 JSONL RPC。
`apps/desktop`	02B、Preload、Main、MessagePort、utilityProcess	CLI 核心稳定后接入，不复制 Runtime 逻辑。	崩溃自动重启、snapshot/replay（快照/重放）、safeStorage（安全存储）。

Ruvie Agent Harness（智能体执行底座）目标架构 · v1 设计视图 · 2026-09-02
设计来源：Pi 与 Ruvie 轻量运行时调研；本图描述目标关系，不代表所有节点已实现。