把 Agent 跑在本地，把执行留在证据里，把风险关进边界内。
一个面向真实仓库的 Agent 工作台：能规划、调用工具、恢复任务，也能解释自己做过什么。

English · 快速开始 · 核心能力 · Loop Engineering · 生产运行

把 Agent 放进真实仓库，问题就不只是“答得对不对”：它还要找得到上下文、管得住工具、失败后接得上，结果也得经得起复查。Evolva 就是围绕这几件事做的。

Plan -> Act -> Observe -> Evaluate -> Evolve

• 执行前有边界：Policy、审批和 Sandbox 共同约束文件、Shell、Python 与 MCP。
• 执行中有状态：Workflow、Loop 和 Session 保存进度，失败后可以恢复或重试。
• 执行后有证据：Trace、Artifact 与 Eval 记录结果，经验经过验证后才进入 Memory / Skill。

需要 Python 3.10+。推荐使用 uv：

git clone https://github.com/koppx/Evolva.git
cd Evolva
uv sync
uv run evolva

也可以安装为全局命令：

pipx install git+https://github.com/koppx/Evolva.git
evolva

进入 TUI 后，用 /config wizard 配置任意 OpenAI-compatible 模型；没有模型时，文件工具、Trace、Workflow 和 Eval 仍可在本地规则模式下使用。

/config wizard             配置 model、base_url、api_key 和 temperature
/repo build                建立当前仓库索引
分析这个项目的风险         直接开始任务
/trace list                查看任务执行记录
/session list              查看持久化会话
/resume                    查看并续跑中断的 Agent 任务
/cancel                    停止当前任务，也可按 Ctrl+K

运行态统一保存在 .evolva/，不会混入源码目录。可通过 EVOLVA_RUNTIME_HOME 把它放到独立磁盘或受控目录。

安全提示：默认 local backend 是开发模式，不隔离宿主机读取或进程。生产环境必须使用隔离 backend；见生产运行边界。

架构分成三条主线：

1. Reasoning & State：TUI、Core、Session、Context 和 Repo Index 按相关性与预算组织任务上下文。
2. Guarded Execution：工具调用经过 Policy、审批与 Sandbox；生产命令执行要求强隔离。
3. Evidence & Learning：主循环在结束前检查 diff、回读或测试证据；失败会受限恢复，中断可从 checkpoint 续跑，经验通过 verifier 后才会晋级。

模型可按任务分层并在故障时有序降级：EVOLVA_MODEL_FAST、EVOLVA_MODEL_CODING、EVOLVA_MODEL_REASONING 和逗号分隔的 EVOLVA_MODEL_FALLBACKS。未设置时继续使用 OPENAI_MODEL，不改变现有配置。

Loop 面向“需要反复做、必须验收”的工程任务。自然语言需求先生成草案，用户确认后才执行；每个阶段都可以声明依赖、预算、质量门和产物。

/loop 做一次发布检查：运行测试、类型检查和安全 Eval
/loop revise 失败时只修复相关模块，最多重试两轮
/loop confirm
/loop execute
/loop save release-check

内置 Loop：

Loop 更接近工程闭环；Workflow 是它下面的通用 DAG 执行层。

Workflow 支持成功节点恢复、节点级重试、条件、超时、有限并行和失败补偿。下面是一个最小示例：

{
  "id": "repository_review",
  "nodes": [
    {
      "id": "search",
      "type": "tool",
      "tool": "repo_index_search",
      "args": {"query": "policy sandbox"},
      "retries": 1
    },
    {
      "id": "review",
      "type": "role",
      "role": "reviewer",
      "depends_on": ["search"],
      "task": "基于 {{search}} 给出风险结论"
    }
  ]
}

evolva workflow path/to/workflow.json --yes

MCP server 默认只继承白名单环境变量，并支持 trust level、工具 allow/deny list 和 Docker 隔离。Memory / Skill 则把“可审计地保存”与“允许进入 prompt”分开，过期、冲突、隔离或已回滚内容不会自动影响 Agent。

这里的“进化”不是让 Agent 不受控地改自己，而是一个保守的晋升流程：

Evidence -> Hypothesis -> Candidate -> Verifier -> Promotion

/dream apply 只生成候选；/dream verify --promote 才会把通过验证的 lesson 写入 Memory / Skill。晋升后的 verifier 如果回归，关联资产会按 fingerprint 回滚；也可以显式执行 evolva dream rollback <candidate_id>。

/evolve audit
/dream
/dream backlog
/dream verify --promote

Eval Harness 把 Agent 行为写成 JSONL 契约，同时检查回答、Trace 事件、工具顺序、Artifact、Policy 决策和运行指标。

evolva eval evals/tasks/security.jsonl --yes \
  --baseline evals/baselines/security.json \
  --min-score 1.0 \
  --no-regression

真实模型评测可以额外限制可用性、P95 和成本：

evolva eval path/to/live-suite.jsonl \
  --require-llm \
  --max-p95-ms 30000 \
  --max-cost-usd 1.00

运行指标保存在本地，并可导出为 Prometheus 文本或 OTLP-shaped JSON：

evolva metrics prometheus
evolva metrics otlp --limit 1000
evolva metrics prune

Evolva 能运行代码，因此 workspace 目录不等于安全隔离。边界需要分层理解：

生产启动建议：

export EVOLVA_PROFILE=prod
export EVOLVA_SANDBOX_BACKEND=docker
export EVOLVA_SANDBOX_CONTAINER_NETWORK=none
export EVOLVA_RUNTIME_HOME=/secure/runtime/evolva

evolva sandbox smoke
evolva

生产 profile 在没有隔离 backend 时会拒绝 Shell / Python。第三方 MCP 也应单独设置 isolation: docker、环境白名单和工具 allowlist。

API key 默认可保存在权限为 0600 的本地 runtime config。需要系统凭据库时：

uv sync --extra credentials
export EVOLVA_CREDENTIAL_BACKEND=keyring
uv run evolva

升级已有运行态前先 dry-run：

evolva migrate state
evolva migrate state --apply

更多说明见 Production Operations、State Migrations 和 Security Policy。

/config wizard                  配置模型
/session list|new|use|rename    管理会话
/session fork|retry             分支或重跑最近一轮
/resume [run_id|latest]         查看或续跑中断的 Agent 任务
/cancel                         停止当前任务
/repo build|status|search       管理仓库索引
/trace list|show|context        查看执行证据
/memory [query|stats|recent]    查看长期记忆
/mcp add|remove|tools|health    管理 MCP server
/loop <request>                 生成 Loop 草案
/loop confirm|execute|save      确认、执行和保存 Loop
/dream status|backlog|verify    管理改进候选
/workflow <json-path>           执行 Workflow
/run <tool> <json>              直接调用工具
/help                           查看完整帮助

uv sync --extra dev
uv run ruff check evolva tests
uv run mypy evolva
uv run coverage run -m pytest -q
uv run coverage report
uv build

CI 还会运行 smoke、repo_index、security、scorers、trace_artifacts 和 43 项 agent_quality Eval baseline。

• Changelog
• Contributing
• Security
• Apache-2.0 License

Evolva · Local-first, inspectable, self-evolving Agent Harness.
如果你也在构建可评测、可回放、可治理的 Agent 系统，欢迎 Star。