把工程 Agent 跑在本地、留在证据里、管在边界内。
Evolva 是一个 TUI-first 的本地 Agent 工作台：连接模型、仓库上下文、工具、MCP、Trace、Eval 和 Loop，让一次对话可以沉淀成可复查的工程执行记录。

English · 快速开始 · 核心能力 · Loop Engineering · 自我进化

一个本地工作台里完成模型配置、工具执行、Trace 复盘、MCP 接入和 Loop 编排。

很多 Agent Demo 都能回答问题，但一到真实仓库就会遇到几件麻烦事：上下文散在文件里，工具执行缺少边界，失败后难复盘，改进也很难沉淀。Evolva 解决的是这条落地链路，而不是再做一个聊天壳。

它把一次任务拆成可检查的运行过程：

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

复杂任务可以被保存成 Loop：有阶段、有质量门、有 Trace、有产物记录。跑完以后，失败原因、工具调用、策略决策和可复用经验都会留下来，下一次不是从零开始。

Evolva 更像一个本地 Agent 控制台，而不是云端平台。你可以接入自己的 OpenAI-compatible 模型、MCP server、私有工具和评测数据，在本地完成调试、回放、回归和能力沉淀：

• Repo-aware：通过仓库索引、上下文、记忆和 Skill 建立可检索的工程上下文。
• Traceable：每次工具调用、策略决策、失败信息和最终输出都进入 Trace，便于回放与审计。
• Evaluable：JSONL Eval Harness 把 Agent 行为变成可回归的测试资产。
• Self-improving：从反馈、Trace 模式和 Eval 失败样本中提炼 lesson，再进入长期记忆与 Skill。
• Local-first：默认在本地文件系统和沙箱中运行，核心能力不绑定云服务。

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

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，并在界面中脱敏展示：

/config wizard                         # 交互式配置 model / base_url / api_key / temperature
F4                                     # 快速唤起配置入口
/config                                # 查看当前 provider 配置，AK 只显示脱敏状态
/config set model <model>              # 单独切换模型
/config set base_url https://...       # 配置 OpenAI-compatible endpoint
/config set api_key <api-key>          # 保存到本地 git-ignored runtime config，界面中会脱敏
/model                                 # 查看当前模型与 provider

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

日常使用围绕 Slash Commands：

/config wizard                         # 配置模型与 AK
/model <model>                         # 切换模型
/repo build                             # 构建仓库索引
/repo search evolution                  # 搜索代码符号/片段
/mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
/mcp tools filesystem                   # 查看 MCP tools
/trace list                             # 查看最近运行
/loop list                              # 查看可复用 Agent Loops
/loop 做一个响应式 landing page，有 hero、pricing、FAQ
                                       # 一句话生成 Loop 草案，不会直接执行
/loop revise 增加移动端验收和暗色模式检查
/loop confirm                          # strict validate + dry-run
/loop execute                          # 仅 confirm 通过后执行
/loop save landing-page-loop            # 保存为可复用 Loop
/loop run dream-loop                    # 运行 Dream 证据闭环
/dream --min-confidence 0.8             # 运行 Dreaming 质量门分析
/evolve audit                           # 查看自进化覆盖

Evolva 的功能按真实使用路径组织：先让 Agent 看懂仓库，再安全执行工具，最后把证据沉淀成可回归的资产。

架构上只有三件事：

1. 运行入口：TUI 负责对话、Slash Command、模型配置和 Trace 查看；Core Runtime 负责编排 plan / act / observe。
2. 执行边界：所有文件、Shell、Python、MCP、Workflow 调用都先经过 Policy 和 Sandbox，风险决策会被记录。
3. 证据回流：Trace 记录过程，Eval 做回归，Evolution 把稳定经验写回 Memory / Skills，让下一次执行更有上下文。

Evolva 把复杂任务建模为 Loop，不是把一串 prompt 和脚本散落在聊天记录里。Loop 描述阶段、依赖、质量门和产物；执行后会生成 Trace、Context 和 Loop Run Report，也可以继续进入 Eval / Dream 做回归和改进。

Loop Engineering 的核心不是“让 Agent 自己乱跑”，而是把一句话需求先变成一份可审阅的执行草案。LLM 负责拆解意图，Evolva 负责清洗命令、确认风险、dry-run、预算限制和证据留存。

内置 Loop：

TUI 内使用：

/loop list
/loop show dream-loop
/loop validate dream-loop
/loop dry-run dream-loop
/loop run dream-loop
/loop run repo-improvement-loop

也可以用自然语言直接生成一次性的工程闭环：

/loop 帮我做一个网页，介绍 AI 简历生成器，包含上传入口、示例预览、价格卡片、FAQ，移动端适配

这不会立刻改代码。Evolva 会先生成一个可确认的 Loop Draft，包含：

• 需求理解与 intent 类型；
• 阶段拆解；
• 检查点；
• 命令候选和 shell allowlist；
• 风险与开放问题；
• 有界执行预算，例如 max_repair_rounds、max_duration_seconds、max_tool_calls。

确认流程：

/loop show-draft        # 查看当前草案和生成的 LoopSpec
/loop revise <反馈>     # 修改阶段、检查点或验收要求
/loop approve <确认说明> # 回答开放问题/接受默认方案，进入再次确认
/loop confirm           # 只做 strict validate / dry-run，不执行
/loop execute           # confirm 通过后才执行
/loop save <name>       # 保存为 evolva/loops/<id>.json
/loop cancel            # 放弃当前草案

CLI 自动化也支持同样能力：

evolva loop plan "做一个响应式 landing page，有 hero、pricing、FAQ" --show-spec
# `--show-spec` 也可以放在自然语言需求前：evolva loop plan --show-spec "做一个响应式 landing page"
evolva loop revise "增加移动端验收"
evolva loop approve "做产品官网 landing page，使用占位素材，不接后端"
evolva loop confirm
evolva loop save landing-page-loop
evolva loop execute --json

CLI 中可使用 evolva loop --yes run <loop> --resume 从最近失败运行恢复。

为了让 Loop 能直接承载真实工程流水线，Loop 运行现在默认具备几项落地能力：

• 运行前校验 / Dry-run：/loop validate <loop> 与 evolva loop dry-run <loop> 会在不执行 phase 的情况下检查依赖顺序、Gate 引用、必填命令、工具是否存在、命令 allowlist、timeout/retries 与 Policy 拦截结果。
• LLM-first Intent-to-Loop Planner：/loop <自然语言需求> 会优先调用当前配置的 LLM，把需求拆成目标、阶段 DAG、检查点、命令候选、风险和执行预算；LLM 只生成草案，不会直接执行。草案会经过 sanitizer/validator（过滤危险命令、修正依赖、限制预算）后展示给用户确认；未配置模型或 LLM 输出不可解析时，才降级到 heuristic fallback，保证仍可离线开箱使用。
• 确认后执行，不靠猜：如果一句话需求仍有开放问题，/loop approve <确认说明> 可以把用户补充写入 assumptions/revisions，清空开放问题并重新生成 LoopSpec；执行失败会自动恢复到 ready_to_run，用户可修正后重试。
• 非修改阶段直连 LLM：设计、复核、最终报告等非修改 phase 默认使用 direct LLM 输出，不进入可调用工具的 agent loop，避免在 todo/context 工具上消耗步骤；上下文扫描和实施阶段仍保留完整工具能力。
• 有界执行：生成的 LoopSpec 会携带 execution_limits，限制 phase 数、修复轮次、重试次数、总时长、工具调用、命令运行和文件修改规模，避免无限循环；运行器会在执行中硬性拦截超预算的 phase/gate，而不是只做静态校验。
• 仓库自适应验证：Planner 会根据本地仓库特征选择可运行的低风险验证命令，例如有 package.json 时优先 npm build/test/lint，有 Python 工程或 tests 时优先 pytest；不会在非 Node 仓库里默认强跑 npm run build。
• 命令白名单：所有 shell phase 和 command_success gate 必须通过 command_allowlist、phase/gate allowlist 或前缀通配规则显式放行，同时仍会经过 Evolva Policy 与 Sandbox。未声明 allowlist 的 Loop 会在运行前失败，而不是隐式执行本地命令。
• Trace 生命周期：独立执行 LoopRunner.run() 会自动创建 Trace；嵌套在 Agent 对话中的 Loop 会复用当前 Trace，避免覆盖上层审计链路。Loop Report 会记录 trace_run_id。
• 真实质量门：command_success Gate 会通过 Evolva 的 shell 工具和确认/策略路径实际执行命令，并把命令、cwd、输出摘要写入 Gate 结果。
• 工程执行控制：Phase 支持 timeout 与 retries。对于 shell / python_exec 工具阶段，若 args 未显式设置 timeout，会自动下发 phase timeout；每次尝试都会写入运行报告。
• 失败恢复：CLI 支持 evolva loop --yes run <loop> --resume，会从同一 Loop 最近失败运行中复用 fingerprint 匹配的成功 phase 输出，避免长流程从头重跑；不匹配的 phase 会重新执行。

Loop spec 示例：

{
  "id": "engineering-check-loop",
  "command_allowlist": [
    ".venv/bin/python -m pytest -q*"
  ],
  "phases": [
    {
      "id": "tests",
      "type": "tool",
      "tool": "shell",
      "args": {"command": ".venv/bin/python -m pytest -q"},
      "timeout": 180,
      "retries": 1
    }
  ],
  "gates": [
    {
      "after": "tests",
      "type": "command_success",
      "command": ".venv/bin/python -m pytest -q tests/test_loops.py",
      "cwd": ".",
      "timeout": 120
    }
  ]
}

命令 allowlist 支持三种匹配：完整命令精确匹配、可执行文件名匹配（如 python3）、以及以 * 结尾的前缀匹配（如 .venv/bin/python -m pytest -q*）。建议生产环境优先使用完整命令或窄前缀，并把 destructive 命令继续交给 Policy/Sandbox 拦截。

Loop 与 Workflow 的边界：Workflow 更像底层 DAG 执行格式；Loop 是面向真实工程习惯的闭环抽象，强调 gate、trace、eval、dream 和长期能力沉淀。

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 会扫描最近 Trace、最新 Eval 报告和当前 Memory/Skill 覆盖，执行 Evidence → Hypothesis → Candidate → Verifier → Promotion。每个候选改进都会带上影响面、风险、建议动作和 verifier；只有通过质量门的高置信候选，才会被分阶段沉淀为 Memory / Skill。

日常使用从 TUI 开始：对话、工具调用、MCP 接入、Trace 检索、模型切换、Loop/Workflow 编排都收敛在同一套 Slash Commands 中。 默认界面基于 Textual 渲染，提供持久对话区、Trace / Tool Stream 侧栏、状态栏和快捷键；依赖缺失时会自动回退到轻量 inline 模式。

evolva

TUI 内常用路径：

/model [name]                         查看/切换模型
/repo build                           构建仓库索引
/repo search <query>                  搜索代码符号、引用和片段
/mcp                                  查看已接入的 MCP server
/mcp add <name> <command> [args...]   接入一个 stdio MCP server
/mcp tools [server]                   查看 MCP tools
/run mcp_call {"server":"...","tool":"...","arguments":{}}
/trace list                           查看最近运行
/trace context latest                 查看最新上下文/Prompt 事件
/loop list                            查看内置与工作区 Agent Loops
/loop show <loop>                     查看 Loop 阶段、Gate 和产物
/loop validate <loop>                 运行前校验 Loop spec
/loop run <loop>                      运行 Loop 并写入 Trace/Context/Loop Report
/workflow path/to/workflow.json        运行 workflow spec
/evolve audit                         查看自进化覆盖
/dream --min-confidence 0.8           运行 Dreaming 质量门分析
/dream backlog                        查看候选改进 Backlog
/dream verify                         运行候选改进 Verifier

/help                     查看帮助
/tools                    列出工具
/skills                   列出技能
/memory [query]           查看或搜索长期记忆
/memory stats             查看记忆统计
/memory recent [n]        查看最近记忆
/context [query]          查看持久上下文
/todo                     查看 TodoList
/todo add <title>         添加 todo
/todo done <id>           标记 todo 完成
/agents                   列出多 agent 角色
/trace list               查看最近 trace
/trace show <run_id>      查看单次 trace
/trace context <run_id>   查看 trace 中的上下文/Prompt 事件
/model [name]             查看或切换当前模型
/policy                   查看 guardrail 策略
/repo build               构建本地仓库索引
/repo search <query>      搜索代码符号、引用和片段
/mcp                      查看 MCP servers
/mcp add <name> <cmd...>  接入 stdio MCP server
/mcp remove <name>        移除 MCP server 配置
/mcp tools [server]       查看 MCP tools
/image <path|url> [text]  对图片提问
/evolve [feedback]        基于反馈自我进化
/dream                    运行 Dreaming 质量门报告
/dream backlog            查看候选改进 Backlog
/dream verify             运行候选改进 Verifier
/dream --min-confidence n 调整 drift-guard 置信阈值
/dream apply              应用高置信 Dreaming 建议
/loop list                查看 Agent Loops
/loop show <loop>         查看 Loop spec
/loop validate <loop>     运行前校验 Loop spec
/loop run <loop>          运行 Loop
/workflow <json-spec-path> 运行 workflow spec
/run <tool> <json>        直接调用工具
/exit                     退出

Workflow 是 Evolva 的底层 DAG 执行格式。它支持显式 depends_on，执行前会检查重复节点、缺失依赖和循环依赖；执行结果会进入 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}} 评审当前自我进化安全边界"}
  ]
}

Eval Harness 用 JSONL 把 Agent 行为固化成回归样本。CI 会运行单元测试、语法检查和 eval gate，用 baseline 拦住分数下降、任务缺失和通过项回退。

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

JSONL 任务不再绑定单一 checklist，而是进入可插拔 Scorer Registry：内置 contains、not_contains、regex、artifact_exists、artifact_contains、artifact_manifest、json_match、memory_contains、context_contains、trace_event、trace_schema、tool_sequence、command、latency、no_tool_error 等评测算子。每个 check 都会产出 dimension、weight、evidence、expected/actual，并汇总为 weighted score，便于业务方继续接入自定义 rule-based scorer 或 LLM-as-judge。baseline 位于 evals/baselines/，CI 配置位于 .github/workflows/ci.yml。

Trace 与 artifact 也进入同一套回归体系：Evolva trace 使用 trace.v1 schema，为每个事件分配 event_id、span_id、parent_id，方便 TUI/可视化层构建 timeline/DAG；写文件等产物会同步进入 evolva/artifacts/manifest.jsonl，记录 path、sha256、producer、run_id 与 event_id，让 Eval、Replay、Dream 能基于同一份可审计证据工作。

Evolva 不提供一个虚高的“万能分数”。它把关键机制拆成可检查、可替换、可扩展的工程层，当前路线聚焦四类生产化方向：

业务侧的评测数据、领域 scorer、私有工具和安全策略都可以接到这套本地 harness 上，形成自己的 Agent 运行底座。

TUI 支持常见工作台快捷键：

Evolva 是本地优先的 Agent，具备文件、Shell 和 Python 执行能力，因此把安全边界作为运行时的一等公民：

• Sandbox root：文件工具统一通过 workspace sandbox 解析路径，阻止路径逃逸。
• Sandbox backend：执行层通过 backend 接口隔离，默认本地 workspace backend，后续可扩展到更强隔离实现。
• Dangerous command denylist：拦截 rm -rf /、git reset --hard、mkfs、shutdown 等高危片段。
• Policy engine：对 Shell / Python、网络、路径、secret pattern 进行风险分级。
• Confirmation gate：非 --yes 模式下，Shell / Python / MCP 等高风险工具需要确认。
• Trace audit：关键决策、工具调用、失败信息和最终回答都会进入 trace，便于审计和复盘。

Evolva 的评测与工程检查已经按照 CI 质量门组织，用于守住 Trace / Eval / Self-Evolution 的回归基线。

PYTHONPYCACHEPREFIX=.pycache uv run python -m compileall evolva tests
uv run pytest -q
evolva eval evals/tasks/smoke.jsonl --yes --baseline evals/baselines/smoke.json --min-score 1.0 --no-regression
evolva eval evals/tasks/repo_index.jsonl --yes --baseline evals/baselines/repo_index.json --min-score 1.0 --no-regression
evolva eval evals/tasks/scorers.jsonl --yes --baseline evals/baselines/scorers.json --min-score 1.0 --no-regression

evolva/
  cli.py                     `evolva` console 入口，默认启动 TUI
  tui.py                     TUI 工作台
  agent/core.py              Agent 对外门面
  agent/langgraph_runtime.py LangGraph StateGraph 运行时
  agent/evolution.py         lesson + skill 自进化引擎
  agent/evolution_analyzer.py Trace / Eval 进化分析器
  agent/dream.py             离线 Dream 反思循环
  agent/images.py            本地/URL 图片输入
  agent/mcp.py               stdio MCP client
  agent/memory.py            带 evidence/status/version 的长期记忆
  agent/policy.py            guardrails 与风险决策
  agent/sandbox.py           workspace sandbox 与 backend 执行抽象
  tools/builtin.py           内置工具注册
  eval/harness.py            JSONL eval runner
  workflow/engine.py         workflow DAG engine
evals/
  baselines/                 Eval-as-CI 回归基线
.github/workflows/ci.yml     单测 + Eval gate
assets/
  evolva-poster.jpeg        README 顶部海报
  architecture.png
  tui-mockup.svg
  workflow-mcp-memory.png

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