> Language: 简体中文 > English default entry: [English](../../en/architecture/module-partitioning.md) > Translation status: current # Eva-CLI 模块划分 更新日期：2026-07-20 ## 1. 范围 本文记录当前 Eva-CLI Rust workspace 的模块边界与直接内部依赖，描述 Cargo 版本 `1.11.5-alpha` 的实现，并包含 `V1.17.6` alpha closure gate。本文不是未来 workspace 提案。 `crates/` 目录恰好包含 20 个 workspace crate。Cargo 还包含根 `eva` package；它是 依赖 `eva-cli` 的薄 binary package，不是额外的架构职责域。 ## 2. 划分规则 - 共享值契约进入 `eva-core`，并保持它零依赖。 - `eva-config` 负责加载和归一化配置，`eva-policy` 负责执行策略判断。 - 事件发布、路由、Agent queue 与 Lua 执行保持独立边界。 - 外部副作用必须经过 capability 与 Adapter gate。 - 每类 durable state 都有显式 owner，不能把 EventBus 当作通用状态存储。 - 运维 mutation 归 backup/lifecycle service，并经带门禁的 CLI 路径暴露。 - `eva-runtime` 与 `eva-cli` 是组合表面，不是基础库。 - Cargo graph 是带横向连接的 DAG，不能按严格栈式分层理解。 ## 3. Workspace 总览 ![Eva-CLI 模块划分总览](../../assets/module-partition-overview.zh-CN.svg) ```text eva -> eva-cli 契约: eva-core 控制: eva-config, eva-policy 横切: eva-observability, eva-storage 执行: eva-eventbus, eva-scheduler, eva-agent, eva-lua-host 集成: eva-capability, eva-adapter, eva-mcp, eva-discovery, eva-memory, eva-hardware 运维: eva-backup, eva-lifecycle, eva-release 组合: eva-runtime, eva-cli ``` 这些标签只用于辅助阅读，下一节的直接 Cargo 依赖才是事实源。 ## 4. Crate 清单与直接依赖 | Crate | 负责 | 直接 Eva 依赖 | 不负责/当前边界 | | --- | --- | --- | --- | | `eva-core` | ID newtype、Topic/TopicPattern、Event、capability reference、Invoke 契约、结构化错误 | 无 | I/O、配置加载、路由、持久化、执行 | | `eva-config` | `eva.yaml`、配置 root、Agent/Adapter/Capability manifest、policy document、route、schema 与跨文件校验 | `eva-core` | runtime 授权或副作用 | | `eva-policy` | permission set、effective-policy 交集、sandbox policy、typed high-risk runtime decision | `eva-config`、`eva-core` | provider 执行、存储、discovery 扫描 | | `eva-observability` | trace field、audit/metric 契约、in-memory/JSONL sink、tracing bridge、OTLP smoke exporter、retention policy | `eva-core` | 业务路由、task 执行、生产 database sink | | `eva-storage` | in-memory/filesystem state、event log、task snapshot、provider process table、audit/artifact store、durable layout | `eva-core`、`eva-observability` | SQLite/database 实现；`sqlite.rs` 仍是 placeholder | | `eva-eventbus` | 同步 publish/ack/fail 契约、in-memory/filesystem durable bus、dead letter 与 redrive | `eva-core`、`eva-observability`、`eva-storage` | Topic subscription 选择或 Agent 执行 | | `eva-scheduler` | Topic matching、fanout/compete plan、有界 mailbox registry、generation route gate、retry dispatch helper | `eva-core`、`eva-observability`、`eva-policy` | Lua 执行、provider 调用、durable event 所有权 | | `eva-agent` | Agent lifecycle、有界 FIFO queue、受控 handler retry/timeout/cancellation、只读 Agent state snapshot | `eva-config`、`eva-core`、`eva-observability`、`eva-policy`、`eva-scheduler`、`eva-storage` | durable task 持久化、Lua VM 内部或外部 transport | | `eva-lua-host` | Lua script 加载、受限 VM、host binding、执行限制、shadow-load report | `eva-capability`、`eva-config`、`eva-core`、`eva-memory`、`eva-observability`、`eva-policy` | 任意 shell/filesystem/network；进程级 live VM swap | | `eva-capability` | capability registry、确定性 provider plan、permission gate、host API、builtin capability router、generation marker | `eva-config`、`eva-core`、`eva-observability`、`eva-policy` | 具体外部 transport 与 provider supervision | | `eva-adapter` | Adapter handle/registry/router、provider supervisor、credential scope、stream capture、builtin/stdio/HTTP/MCP/Skill/hardware transport | `eva-capability`、`eva-config`、`eva-core`、`eva-hardware`、`eva-mcp`、`eva-observability`、`eva-policy`、`eva-storage` | discovery 扫描、全局调度、OS process management | | `eva-mcp` | allowlist、tool mapping、JSON-RPC client、stdio/HTTP call、session/stream lifecycle record、compatibility matrix、最小 server tool gate | `eva-core`、`eva-observability`、`eva-policy` | 不受控 proxy 或生产常驻 MCP server | | `eva-discovery` | normalized candidate、trust/health report、project/PATH/MCP/OMX/Codex/registry-config source、内存增量 cache | `eva-config`、`eva-core`、`eva-observability`、`eva-policy` | 授权、联网 registry crawling、自动安装 | | `eva-memory` | private/global memory、knowledge record、context build、filesystem durability、TTL GC、rebuild checkpoint、retrieval/redaction evidence | `eva-capability`、`eva-core`、`eva-observability`、`eva-policy`、`eva-storage` | vector database 或生产常驻 retrieval scheduler | | `eva-hardware` | manifest-derived discovery、device/lease registry、simulator driver、OS permission gate、lifecycle 与 hotplug EventBus publish | `eva-config`、`eva-core`、`eva-eventbus`、`eva-observability`、`eva-policy` | 已认证真实硬件 driver 或 fixture | | `eva-backup` | backup scope/manifest、artifact archive、migration package、release snapshot、restore plan、staged file mutation 与 rollback | `eva-core`、`eva-observability`、`eva-policy`、`eva-storage` | remote backup upload 或生产 key management | | `eva-lifecycle` | generation/drain state、upgrade apply lock、supervisor handoff、release-pointer state、rollback、typed service-manager contract、Windows Service/systemd/launchd Adapter、规范化 direct-service argv identity 与 cooperative signal/SCM stop bridge | `eva-backup`、`eva-core`、`eva-observability`、`eva-policy` | 受控真实 host stop/boot/reboot transcript、destructive lifecycle harness 认证、production gate 或 blue-green 流量切换；Fake Adapter 仍只用于测试 | | `eva-release` | release readiness gate、artifact/distribution/scanner/benchmark verification、security/performance/migration report、V1.x closure report | `eva-core`、`eva-mcp`、`eva-storage` | signing credential、仓库发布或 release upload | | `eva-runtime` | service summary、basic run 组合、foreground/background daemon control、direct service mode、durable recovery/diagnostics、scheduler retry tick、generation-bound drain/shutdown、runtime task report | `eva-adapter`、`eva-agent`、`eva-backup`、`eva-capability`、`eva-config`、`eva-core`、`eva-discovery`、`eva-eventbus`、`eva-hardware`、`eva-lifecycle`、`eva-lua-host`、`eva-mcp`、`eva-memory`、`eva-observability`、`eva-policy`、`eva-scheduler`、`eva-storage` | release gate 聚合；长期持有全部 service 的容器 | | `eva-cli` | 公开 command parser/dispatch、service lifecycle 命令、隐藏 identity-bound service entry 校验、text/JSON writer、trace/exit-code mapping、命令专属组合与 operator gate | `eva-adapter`、`eva-agent`、`eva-backup`、`eva-capability`、`eva-config`、`eva-core`、`eva-discovery`、`eva-eventbus`、`eva-hardware`、`eva-lifecycle`、`eva-mcp`、`eva-memory`、`eva-observability`、`eva-policy`、`eva-release`、`eva-runtime`、`eva-storage` | 共享 domain 契约或通用长生命周期 task executor | ## 5. 依赖图 ![Eva-CLI 依赖方向规则](../../assets/module-dependency-rules.zh-CN.svg) 直接依赖图无环，但有意不采用纯分层： ```text eva-core <- eva-config <- eva-observability eva-config + eva-core <- eva-policy eva-core + eva-observability <- eva-storage eva-eventbus -> eva-core + eva-observability + eva-storage eva-scheduler -> eva-core + eva-observability + eva-policy eva-capability -> eva-config + eva-core + eva-observability + eva-policy eva-mcp -> eva-core + eva-observability + eva-policy eva-discovery -> eva-config + eva-core + eva-observability + eva-policy eva-backup -> eva-core + eva-observability + eva-policy + eva-storage eva-agent -> eva-config + eva-core + eva-observability + eva-policy + eva-scheduler + eva-storage eva-memory -> eva-capability + eva-core + eva-observability + eva-policy + eva-storage eva-hardware -> eva-config + eva-core + eva-eventbus + eva-observability + eva-policy eva-lifecycle -> eva-backup + eva-core + eva-observability + eva-policy eva-release -> eva-core + eva-mcp + eva-storage eva-lua-host -> eva-capability + eva-config + eva-core + eva-memory + eva-observability + eva-policy eva-adapter -> eva-capability + eva-config + eva-core + eva-hardware + eva-mcp + eva-observability + eva-policy + eva-storage eva-runtime -> runtime domain，但不依赖 eva-release eva-cli -> operator-facing domain + eva-runtime + eva-release ``` 关键结论： - `eva-hardware -> eva-eventbus`，因为 hotplug publish 属于 hardware 边界。 - `eva-memory -> eva-capability`，因为受监督 retrieval 使用 capability host 契约。 - `eva-adapter -> eva-hardware + eva-mcp`，因为二者是具体 Adapter transport。 - `eva-release` 由 `eva-cli` 直接使用，不进入 `eva-runtime`。 - `eva-cli` 不直接依赖 `eva-scheduler` 或 `eva-lua-host`；basic/daemon 链通过 `eva-runtime` 进入它们。 - 没有下层 crate 反向依赖 `eva-runtime` 或 `eva-cli`。 ## 6. 运行时交接 ![Eva-CLI 运行时调用链](../../assets/module-runtime-flow.zh-CN.svg) 当前没有一条覆盖所有能力的通用调用链，而是实现了三条交接路径。 ### 6.1 Basic Event 路径 ```text eva-cli -> eva-config -> eva-runtime basic composition -> eva-eventbus -> eva-scheduler mailbox -> eva-agent -> eva-lua-host -> eva-capability builtin host -> ack/fail + task/audit report ``` ### 6.2 外部 Provider 路径 ```text eva-cli 或 CapabilityHostApi caller -> eva-capability provider plan 与 permission gate -> eva-policy runtime gate -> eva-adapter router 与 supervisor -> stdio | HTTP | MCP | Skill | hardware transport -> eva-storage artifact/provider evidence -> eva-observability ``` ### 6.3 Durable 运维路径 ```text eva-cli -> eva-runtime daemon/recovery，或 eva-backup/eva-lifecycle operation -> eva-storage filesystem backend -> policy + confirmation + lock + health gate -> mutation/recovery/rollback evidence -> 请求时由 eva-release 聚合 readiness ``` `RuntimeBuilder` 参与 inspect 和 basic/daemon summary，但 concrete store、bus、 supervisor 与 operation coordinator 由实际使用它们的命令路径打开。 ### 6.4 Direct Service 路径 ```text eva-cli service install/start -> eva-lifecycle 平台 Adapter + 规范化 argv identity -> 隐藏 eva-cli daemon service entry -> eva-runtime 直接持有 daemon lease/PID -> eva-lifecycle atomic OS-stop token -> eva-runtime 既有 Shutdown drain 事务 ``` service process 不会再 spawn 第二个 daemon。代码测试覆盖 identity drift 与 drain cleanup； 真实 host destructive lifecycle 和 boot/reboot evidence 仍在 crate graph 之外。 ## 7. 跨 Crate 不变量 ### 7.1 契约不变量 跨 crate Event、Topic、ID、Invoke 与 Error 形态归 `eva-core`。provider-private protocol value 必须在 Adapter/MCP 边界完成转换。 ### 7.2 策略不变量 Discovery 与 manifest load 本身不授予执行权。effective permission 只能收窄。 high-risk action 要求 runtime policy；operator-facing apply 路径还要保留 dry-run/confirmation 和 execution-state 字段。 ### 7.3 状态不变量 Mailbox state 归 Scheduler/Agent，event recovery 归 EventBus，durable record 归 Storage，provider state 归 Adapter，memory data 归 Memory，hardware lease 归 Hardware，generation/handoff state 归 Lifecycle。不能为了方便把状态移入隐藏全局变量 或 Event payload。 ### 7.4 失败与可观测性不变量 跨 crate failure 使用 `EvaError`，保留稳定 kind、retryability、可选 provider code 和 context。有界资源失败、observability degradation、redaction、mutation execution 和 rollback requirement 都必须在 report 中显式呈现。 ## 8. 已实现边界与生产阻塞 现有代码实现了 filesystem durability、foreground/background daemon control、绑定 identity 的 direct service entrypoint、受控外部 provider 执行、MCP compatibility fixture、simulator hardware safety、destructive restore/rollback、JSONL observability 和本地 release evidence gate。 crate graph 不表示以下能力已经完成：具有真实 host stop/boot/reboot evidence 与 destructive harness 的 production-certified OS service 监督、live 通用 task executor、 均衡调度、生产 MCP serving/TLS/vault isolation、真实硬件、SQLite/database storage、 生产 database observability、blue-green service handoff、remote backup、生产 signing、 包仓库和 release upload。V1.17.6 closure report 把它们记录为 external 或后续生产 边界，而不是用模块名称掩盖缺口。 ## 9. 总结 `crates/` 下的 20 个 crate 将契约、控制、执行、集成、持久化、运维和 operator composition 分离，同时保留真实行为所需的显式横向依赖。依赖方向以 Cargo manifest 为事实源，不能以简化分层图替代。