快速开始

Evolva 的主入口是一个本地 TUI 工作台。安装后直接运行 evolva，进入同一个界面完成对话、工具调用、MCP 接入、Trace 查看、模型切换、Loop/Workflow 编排和自我进化。

```bash git clone git@github.com:koppx/Evolva.git cd Evolva uv sync uv run evolva

安装为本地命令（可选）

uv pip install -e . evolva

或使用 pipx 从 GitHub 安装后直接运行

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

首次进入 TUI 后，直接在工作台里配置模型，不需要手动 export 环境变量。API key 会写入本地 git-ignored runtime config，并在界面中脱敏展示：

配置会保存到本地 `evolva/runtime/config.json`，该目录默认被 `.gitignore` 忽略；如果不配置模型，Evolva 仍可先以本地规则模式使用工具、记忆、Trace、Workflow、Eval 等能力。

日常使用围绕 Slash Commands：

自我进化：从运行证据到能力资产

<p align="center"> <img src="assets/evolva-dreaming-loop.jpeg" alt="Evolva Dreaming Loop" width="100%" /> </p>

Evolva 的自我进化是一条可检查、可回放、可审计的状态更新链路：

Feedback / Trace Pattern / Eval Failure
        ↓
Evidence
        ↓
Hypothesis
        ↓
Candidate + Verifier
        ↓
Dream Backlog
        ↓
Staged Promotion
        ↓
Long-term Memory / Markdown Skill

TUI 内示例：

/evolve audit
/evolve 以后写 Python 文件后自动运行语法检查和 pytest
/evolve trace
/evolve apply-trace
/evolve apply-eval
/dream
/dream backlog
/dream apply --min-confidence 0.8

它会把反馈或失败模式提炼成带 category / confidence / evidence / fingerprint 的 lesson，写入长期记忆，并可生成 Markdown Skill，让后续任务自动带上这些经验。evolve audit 会汇总 lesson 覆盖、已进化技能、Trace/Eval 待处理 proposal 和下一步建议，避免自我进化变成不可控的 prompt 堆叠。

dream 是 Evolva 的本地自进化研究循环：它会扫描最近 Trace、最新 Eval 报告和当前 Memory/Skill 覆盖，执行 Evidence → Hypothesis → Candidate → Verifier → Promotion。流程会先收集证据，再生成可证伪假设；通过 drift guard 后的假设会进入 DreamCandidate，携带 affected surfaces、risk、proposed change 和 verifier，并写入 evolva/dreams/backlog.json 形成候选改进池。加上 apply 后，Evolva 只会把通过质量门的高置信候选分阶段沉淀为 Memory / Skill，后续仍可通过 /dream verify 调用 Eval 或 Trace verifier 做回归确认，并把通过验证的候选推进为 verified/promoted。

Workflow 编排

Workflow 支持显式 depends_on，可以描述真正的 DAG；未声明依赖的旧规格仍按顺序执行，便于兼容已有工作流。执行前会检查重复节点、缺失依赖和循环依赖，执行结果会进入 Context 与 Trace，作为后续 Eval / Dream 的证据来源。

{
  "id": "evolution_audit_flow",
  "nodes": [
    {"id": "repo", "depends_on": [], "type": "tool", "tool": "repo_index_search", "args": {"query": "SelfEvolutionEngine DreamEngine"}},
    {"id": "policy", "depends_on": [], "type": "tool", "tool": "policy_info", "args": {}},
    {"id": "review", "depends_on": ["repo", "policy"], "type": "role", "role": "reviewer", "task": "基于 {{repo}} 和 {{policy}} 评审当前自我进化安全边界"}
  ]
}

Workflow / MCP / Memory 闭环

<p align="center"> <img src="assets/workflow-mcp-memory.svg" alt="Evolva workflow MCP memory" width="100%" /> </p>