博客

Eva-CLI 项目文件夹结构与配置文件导览

介绍 Eva-CLI 已落地的目录布局、Rust workspace 骨架、扁平 Agent 目录、配置文件、Schema 校验和 policy 边界。

发布： 2026-06-30 分类：运行时

Eva-CLI 当前仓库已经有两个具体基础：可编译的 Rust workspace 骨架，以及项目配置树。这意味着项目不再只是架构笔记，而是已经具备后续运行时代码可以校验、检查和执行的结构。

最关键的设计选择是：目录不授予权力。目录只让内容可发现。真正的权力仍来自 manifest、schema、policy、route 和 Runtime 组合根。

Eva-CLI 项目结构地图，展示 Rust workspace crate、配置目录、扁平 Agent 目录、schema、policy、route、adapter 和运行时交接。 — 当前仓库把实现归属、人工维护配置和运行时权力分开表达。

顶层目录分别表达什么

根目录布局刻意保持直接。静态官网在 website/，架构文档在 docs/，共享插图在 assets/，运行配置在 config/，Rust 实现边界在 crates/。

目录	用途	运行时规则
`config/`	人工维护的 YAML、JSON Schema、Agent manifest、Adapter manifest、policy、route 和 capability 声明。	运行时注册前必须解析和校验。密钥只引用环境变量名，不在配置里明文保存。
`crates/`	Rust workspace crate，承载 core contract、config、policy、scheduler、adapter、discovery、runtime 等稳定职责边界。	下层 crate 不反向依赖 `eva-runtime`；`eva-runtime` 是组合根。
`src/`	很薄的 binary shim，只把进程入口转交给 `eva-cli`。	保持很小。CLI 行为属于 `crates/eva-cli`。
`docs/`	架构、模块划分、配置、发现、记忆、硬件、生命周期和路线图文档。	文档描述实现需要保持的契约，但不是运行时配置。
`website/`	静态官网源文件和生成页面，包括博客内容和多语言 JSON。	由模板和 i18n 数据生成；源数据和生成后的 HTML 应一起提交。

配置树的边界

主运行时配置是 config/eva.yaml。它描述环境、workspace 路径、EventBus、Scheduler 默认值、状态、记忆、知识库、观测配置，以及其他配置目录的位置。它应该保持全局。单个 Agent 的订阅、单个 Adapter 的命令、MCP allowlist 应该放到各自文件里。

配置路径	负责	不负责
`config/agents/<agent-id>/`	Agent manifest、Lua 入口脚本、可选 constraints、订阅、inbox、timeout、状态命名空间和权限。	API key、provider command、全局 policy，或通过目录嵌套隐式表达父子行为。
`config/adapters/`	CLI、HTTP、MCP、Skill、硬件等 provider manifest。	明文密钥或用户可控 shell 片段。
`config/policies/`	沙箱、Adapter、MCP server、硬件、重试和全局权限下限。	业务路由或 provider 私有 payload 逻辑。
`config/routes/topics.yaml`	Topic pattern 到 Agent 的投递规则。	业务逻辑，或通过目录层级做自动递归投递。
`config/schemas/`	校验 YAML 解析后结构的 JSON Schema。	校验之后的运行时策略裁决。

为什么 Agent 目录要扁平

早期嵌套示例把 Topic 层级和 Agent 存放层级混在了一起。这会误导读者，因为 /sys/route-a/route-aa 是路由，不是 Agent。当前模型保持一个目录只表达一个 Agent 实体：

config/agents/
  root-agent/
    agent.yaml
    constraints.md
    main.lua
  agent-a/
    agent.yaml
    constraints.md
    main.lua
  agent-a11/
    agent.yaml
    main.lua
  agent-a12/
    agent.yaml
    main.lua

运行时父子关系仍然通过 agent.yaml 中的 parent、children、subscriptions 和 permissions.emit 显式表达。Topic 投递仍然通过 config/routes/topics.yaml 表达。这样 discovery、热加载和 policy audit 都更简单：先扫描 Agent manifest，再校验它声明的权力。

配置如何变成运行时权力

推荐加载顺序是确定的：内置默认配置、config/eva.yaml、policy 文件、routes、Agent manifest、Adapter manifest、环境变量引用、低风险 CLI 覆盖。每一步可以补充信息，但权限只能在合并到 effective policy 的过程中逐层收紧。

YAML 文件
  -> 解析成结构化值
  -> 使用 JSON Schema 校验
  -> 归一化 manifest
  -> 合并 policy 下限
  -> 构建 effective config
  -> 注册 runtime handle

下一步实际实现工作，是通过 eva config validate、eva config inspect 和 eva config dump-effective 这类命令把它变成可见证据。目录树不只是整齐，它应该成为 Runtime 可执行、可审计的输入。

相关技术文档：项目配置方案和模块划分方案。