> Language: 简体中文
> English default entry: [English](../../en/architecture/architecture-overview.md)
> Translation status: current

# Eva-CLI 总体架构方案

更新日期：2026-07-20

## 1. 范围与版本语义

本文描述当前 Eva-CLI workspace 已实现的架构，是代码地图，不是目标设计或交付计划。

Cargo 版本是 `1.11.5-alpha`。`V1.17.6` 是 `eva version` 与
`eva release check` 暴露的 V1.x alpha closure 检查点名称；它不是第二套产品版本、
release tag，也不表示生产就绪。

Eva-CLI 是一个本地、由 Rust 托管的运行时与运维 CLI，用于组织 typed event、
有界 Agent 执行、受控 Lua handler、外部 capability provider、文件系统持久化、
恢复证据和带门禁的生命周期操作。

## 2. 系统总览

![Eva-CLI 总体架构](../../../assets/eva-cli-architecture.zh-CN.svg)

当前实现可按五个职责平面理解：

| 平面 | 已实现职责 | 主要 crate |
| --- | --- | --- |
| 契约与控制数据 | ID、Topic pattern、Event/Invoke 契约、配置、策略决策 | `eva-core`、`eva-config`、`eva-policy` |
| 本地执行 | 事件发布、Topic 路由、有界 mailbox、Agent 生命周期、受控 Lua `on_event` | `eva-eventbus`、`eva-scheduler`、`eva-agent`、`eva-lua-host` |
| 能力与集成 | Capability 选择与门禁、Adapter transport、MCP、发现、记忆、硬件 | `eva-capability`、`eva-adapter`、`eva-mcp`、`eva-discovery`、`eva-memory`、`eva-hardware` |
| 持久化与运维 | 文件状态、event/task/provider 记录、artifact、备份、恢复、升级和发布证据 | `eva-storage`、`eva-backup`、`eva-lifecycle`、`eva-release` |
| 组合与运维入口 | Runtime 报告、basic 执行、前台/后台 daemon 控制、direct service entry、诊断、稳定 CLI 输出 | `eva-runtime`、`eva-cli`、根 `eva` binary |

`eva-observability` 是横切层：提供 trace 字段、audit/metric 契约、JSONL sink、
tracing bridge、OTLP exporter smoke 路径和 retention policy 执行。

## 3. 架构决策

### 3.1 Rust 拥有权威与副作用

Rust 校验配置、计算策略、持有队列与生命周期状态、打开 durable store、调用 provider、
执行文件系统 mutation 并记录证据。Lua 不能绕过这些边界。

### 3.2 Lua 是受控 handler 边界

Agent script 在受限 Lua 5.4 VM 中实现 `on_event(event, ctx)`。Host 暴露只读的
event/context table、host observation，以及经 `CapabilityHostApi` 执行的
`ctx.tools.call`。VM 只启用少量标准库，并实施 timeout、instruction、cancellation
和 memory limit；它不暴露任意 shell、文件系统、网络、环境变量或进程 API。

### 3.3 Topic 路由是显式契约

`Topic` 与 `TopicPattern` 是共享契约。Scheduler 把匹配规则展开为有界 Agent
mailbox 投递。`fanout` 选择全部已列 Agent；当前 `compete` 实现固定选择列表中的
第一个 Agent，并不是负载均衡器。

显式 `EventTarget::Agent` 会绕过 Topic rule 选择。Capability 与 Adapter target
存在于 Event 契约和 `emit` 输出中，但当前 Scheduler 不会把这两类 target 转换为
provider invocation。

### 3.4 Durable 当前指本地文件系统持久化

已实现的 durable backend 使用带版本的文件系统布局，保存 event log、dead letter、
task snapshot、provider process snapshot、audit record 和 artifact。SQLite 仍是
placeholder，当前没有分布式 broker 或 database-backed state store。

### 3.5 组合按命令路径发生

`RuntimeBuilder` 从已校验的 `ProjectConfig` 构建包含 service summary 的
`Runtime`，它不会长期持有全部 concrete service 的对象图。basic、daemon、provider、diagnostics、restore、
upgrade 与 release 路径分别创建自己需要的具体对象。架构图不能把
`RuntimeBuilder` 描述成完整依赖注入容器。

## 4. 已实现运行链路

### 4.1 配置与 CLI 控制流

```text
eva binary
  -> eva-cli parser 与 command module
  -> 加载 eva.yaml 和配置 root
  -> 加载 Agent / Adapter / Capability manifest、policy 与 route
  -> 跨文件校验
  -> 命令专属 runtime 或 service 组合
  -> text 或稳定 JSON envelope + trace + exit code
```

公开命令族为 `version`、`doctor`、`config`、`inspect`、`run`、`emit`、
`daemon`、`agent`、`capability`、`task`、`adapter`、`mcp`、`skill`、
`discovery`、`memory`、`observability`、`hardware`、`backup`、`snapshot`、
`restore`、`upgrade` 和 `release`。

### 4.2 Basic 内存 Agent 链路

```text
run --example basic
  -> RuntimeBuilder::in_memory_v10
  -> typed Event
  -> InMemoryEventBus publish
  -> SubscriptionTable route 与 mailbox delivery
  -> AgentRuntime accept 与受控 retry loop
  -> LuaHost on_event
  -> 使用 ctx.tools.call 时进入 builtin CapabilityRouter
  -> EventBus ack，或 fail + dead letter
  -> TaskReport、Lua observation 与 audit evidence
  -> 可选 filesystem task snapshot
```

这条链路是同步、进程内执行。它的 Lua tool host 只包含 builtin `config.lint` 和
`runtime.echo`，不是完整的外部 Adapter provider 链。

### 4.3 外部 Capability 链路

```text
CLI capability call
  -> CapabilityRegistry 与确定性 provider plan
  -> manifest 与 PermissionSet gate
  -> RuntimePolicyGate
  -> CLI dry-run / operator confirmation gate
  -> AdapterBackedCapabilityHost
  -> AdapterRuntime route
  -> ProviderSupervisor admission 与 credential scope
  -> builtin | stdio | HTTP | MCP | Skill | hardware transport
  -> 有界且已脱敏的 output / artifact
  -> audit、metrics 与 InvokeResponse
```

operator confirmation 只属于 CLI 命令路径。其他 Rust caller 必须先通过自身的
authorization 与 execution gate，才能进入 `AdapterBackedCapabilityHost`。

只有被分类为 retryable 的失败才会尝试后续 provider。Supervisor 记录 concurrency、
rate、circuit、session、health、restart policy 和 durable process evidence；它不是
OS process manager。

### 4.4 Daemon 模式与恢复链路

```text
daemon start --foreground | --background
  -> filesystem lock 与 PID/state file
  -> durable backend verify
  -> task、event 与 provider recovery scan
  -> policy 与 observability 检查
  -> 一次 hotplug reconcile
  -> memory TTL GC 与 knowledge rebuild checkpoint
  -> smoke shutdown，或 filesystem control-mailbox polling loop
       -> durable dead-letter retry tick
       -> status / submit / cancel / drain / reload / shutdown request
```

前台模式保留当前进程；后台模式使用独立 parent/child startup handshake，并且只在
child 已持有 durable PID/lease identity 后发布成功。两种模式都不会自动启动 provider
process。retry tick 会 redrive 到期事件、路由到本轮临时 Scheduler mailbox，并记录
scheduler ack；它不会为该投递执行 Agent 或 Lua handler。下节 direct OS service 路径是
第三种模式，不经过 background child entrypoint。

### 4.5 OS Service Direct Entry 链路

```text
eva service install/start
  -> 规范化 executable + native argv + working directory
  -> service kind/name + 稳定 identity digest
  -> Windows SCM | systemd | launchd Adapter
  -> 隐藏 daemon __service-entry
  -> 校验 project、host kind、service name 与 identity
  -> 直接获取 daemon PID/lease，不二次 spawn
  -> SCM control 或 Unix signal 只设置 atomic stop token
  -> 既有 Shutdown request -> task drain -> stopped/PID cleanup/lease release
```

这是已实现的代码契约，不是生产 host 认证。signal/SCM callback 不直接执行 runtime
工作，只请求 cooperative stop；daemon loop 负责 generation-bound drain/shutdown 事务。
受控真实 host stop/boot/reboot transcript、destructive lifecycle harness 与 production
release gate 仍需补齐。

### 4.6 带门禁的运维链路

backup 与 snapshot 命令写入 artifact-backed evidence。restore apply 要求显式 plan、
confirmation、policy approval、filesystem lock、pre-restore evidence、分阶段
copy/replace/delete、transaction log、health check 和 rollback path。upgrade apply
同样通过 policy、lock、health、state store、runtime binary 与 rollback evidence
约束 release pointer handoff。

`release check` 聚合本地 readiness evidence。它负责验证证据，不负责签名或上传生产发行物。

## 5. 横切不变量

- 跨 crate 的 ID、Topic、Event、Invoke 和 Error 统一来自 `eva-core`。
- 配置或 discovery 发现不等于授权；执行边界必须再次做授权判断。
- policy、manifest、session 与 request constraint 合并时，effective permission
  只能收窄。
- 外部 provider 执行与高风险 mutation 默认拒绝并要求显式 policy；高风险 CLI
  apply 还必须暴露 confirmation 和 mutation state。
- queue 与 provider stream 都有上限；overflow、timeout、cancellation、retryability、
  truncation 和 degradation 都必须成为显式结果。
- durable mutation record 由所属 storage 或 operation service 写入，不能隐藏在 Event
  payload 或全局可变状态中。
- trace、audit、metrics 与 operator evidence 在持久化前必须按 credential 与 memory
  policy 脱敏。
- JSON command contract 采用 additive 兼容；公开既有字段由 golden-subset 校验保护。

## 6. 状态归属

| 状态 | 归属 |
| --- | --- |
| Event append/ack/fail 与 dead-letter redrive | `eva-eventbus`，底层使用 `eva-storage` |
| Scheduler mailbox 与 route expansion | `eva-scheduler` |
| Agent queue 与 lifecycle | `eva-agent` |
| Lua execution 与 shadow-load report | `eva-lua-host` |
| Provider admission 与 session/process evidence | `eva-adapter` 与 `eva-storage` |
| Memory/knowledge record 与 checkpoint | `eva-memory`，复用 `eva-storage` layout |
| Hardware lease、permission 与 hotplug reconcile | `eva-hardware` |
| Backup/restore transaction evidence | `eva-backup` |
| Generation、handoff、apply lock、rollback、service definition 与 OS-stop bridge | `eva-lifecycle` |
| Daemon control file、direct service mode、drain/shutdown 与 runtime recovery coordination | `eva-runtime` |

## 7. 当前能力边界

已实现边界包括：in-memory basic 执行、filesystem durable event/task/provider store、
受控 stdio/plain-HTTP/MCP/Skill provider 执行、面向 simulator 的 hardware safety、
带 rollback 的 destructive restore、release-pointer mutation、JSONL observability、
tracing 集成、显式 OTLP exporter smoke 验证、host-bound service Adapter，以及绑定
identity 的隐藏 direct daemon entrypoint；其 stop token 复用既有 drain/shutdown 事务。

以下内容不能描述为已实现的生产能力：

- 经过真实 host stop/boot/reboot evidence、destructive lifecycle harness 与 production
  release gate 认证的 OS-managed daemon；
- 长生命周期通用 task executor 或 provider 自动启动；
- `compete` 均衡调度、async actor、cluster 或 remote broker；
- 生产 MCP server proxy、OS credential vault 或完整 TLS 边界；
- 联网 registry discovery 或自动安装；
- 真实硬件认证或生产硬件 driver；
- SQLite/database state、生产 observability database sink 或常驻 retention scheduler；
- 经过验证的 systemd、Windows SCM 或 launchd lifecycle recovery 与真实 blue-green handoff；
- remote backup transport 或生产 key management；
- 生产 signing、attestation、包仓库发布或 release upload；
- 跨持久 runtime generation 的 live atomic Lua VM replacement。

## 8. V1.17.6 Closure 状态

`REL-V1X-CLOSURE-001` 汇总 daemon、MCP compatibility、provider supervision、restore、
service-manager abstraction、hardware safety、observability policy 和 public JSON
contract gate。当前本地结果是 `ready_with_external_blockers`。

生产 signing/attestation credential、包仓库权限、用于 destructive stop/boot/reboot
evidence 的平台 service-manager 测试环境、真实或虚拟 hardware fixture，以及生产
database observability sink 仍是 external blocker。direct-entry 代码契约单独记录，
不会关闭这些 production gate。

完整 crate 依赖图与职责表见[模块划分方案](模块划分方案.md)，共享契约模型见
[eva-core 契约模块](eva-core模块设计.md)。