EvoClaw — 系统架构图

本地优先 · 自主进化 · ACP / MCP 标准互通 · 密钥隔离屏障 · 闭环可证
English · 中文 · 设计图 →

1. 一张图看懂

EvoClaw 是一个二进制 + 一个可选的本地 HTTP daemon。运行自主进化的 agent loop,在 runtime 边界处脱敏密钥,所有状态以 JSONL / YAML / TOML / JSON 形式持久化在 ~/.evoclaw/。本图把所有关键模块画在同一画布上。

flowchart LR classDef frontend fill:#2a1f4a,stroke:#a78bfa,color:#fff classDef gateway fill:#1a2f4a,stroke:#5fb3ff,color:#fff classDef loop fill:#0f3a44,stroke:#22d3ee,color:#fff classDef cap fill:#0f3a2a,stroke:#34d399,color:#fff classDef route fill:#3a2f0a,stroke:#facc15,color:#fff classDef policy fill:#3a210a,stroke:#fb923c,color:#fff classDef store fill:#3a1414,stroke:#f87171,color:#fff classDef ext fill:#1a2f4a,stroke:#5fb3ff,color:#fff,stroke-dasharray:4 3 CLI[CLI evoclaw]:::frontend REPL[交互式 REPL]:::frontend GW[本地 Gateway HTTP]:::gateway LOOP[Agent Loop]:::loop RED[Redactor 保险柜]:::policy TOOL[Tool Registry]:::cap SK[Skill Tree]:::cap MEM[记忆 L0 至 L5]:::cap REF[反思 + 蒸馏]:::cap PROV[Provider 适配器]:::route ACP[ACP Provider]:::route MCP[MCP Tool 包装器]:::route POL[权限引擎]:::policy COST[Cost 引擎]:::policy AUD[JSONL Audit]:::policy FS[(workspace 与 logs)]:::store YAML[(skills 下的 yaml)]:::store VAULT[(secrets 下的 vault.json)]:::store AGENTS[(agents 下的 toml)]:::store MCPCFG[(mcp 下的 toml)]:::store MODEL((模型 API)):::ext EXTAGENT((外部 CLI)):::ext EXTSRV((MCP 服务器)):::ext CLI --> REPL REPL --> RED GW --> RED RED --> LOOP LOOP --> TOOL LOOP --> SK LOOP --> MEM LOOP --> REF TOOL --> PROV TOOL --> MCP LOOP --> ACP PROV --> MODEL ACP -. spawn stdio .-> EXTAGENT MCP -. spawn stdio .-> EXTSRV TOOL --> POL PROV --> COST LOOP --> AUD TOOL --> AUD POL --> AUD REF --> SK REF --> MEM SK --> YAML MEM --> FS AUD --> FS RED --> VAULT ACP --> AGENTS MCP --> MCPCFG

2. 分层视图(横向泳道)

每条泳道是一层职责。从上往下读。每层内部各盒子是兄弟关系,左到右排列,不互相纵向依赖。跨层依赖永远只朝下。

L7 前端
evoclaw CLI
交互式 REPL
Web 渠道
L6 Gateway 与向导
本地 Gateway
Onboard 向导
MCP Bootstrap
L5 Agent Loop
ConversationRuntime
SummaryParser
Compression
反思 · 蒸馏
L4 能力面
Tool Registry
Skill Tree
记忆 L0 至 L5
Session JSONL
L3 路由与适配器
OpenAI 兼容
Anthropic
Copilot OAuth
ACP Provider
MCP 包装器
L2 策略 / 成本 / 脱敏
权限引擎
Cost 引擎
Vault + Redactor
Audit 总线
L1 持久化
JSONL
YAML
TOML
JSON
文件系统

无环每层横向铺开 — 不再是一根独柱反向通信只走 Audit 事件总线

3. Runtime:单任务端到端(闭环)

用户输入从左侧进入,先被 redactor 脱敏,loop 循环到模型不再请求工具为止,最后写反思 + 蒸馏 + JSONL End 记录。每段过模型边界的文本都被 scrub 过;闭环可由 doctor closure 验证。

flowchart LR U[用户输入] --> RED1[Redactor scrub] RED1 --> TASK[写 Task 记录] TASK --> PLAN[规划这一轮] PLAN --> CACHE{schema 指纹命中?} CACHE -- 是 --> SKIP[复用短标记] CACHE -- 否 --> FULL[发完整 schema] SKIP --> CALL[provider.stream] FULL --> CALL CALL --> ASSIST[assistant 文本 + tool calls] ASSIST --> RED2[Redactor scrub] RED2 --> TOOLS{有工具调用?} TOOLS -- 是 --> EXEC[执行工具] EXEC --> RED3[Redactor scrub 结果] RED3 --> TURN[写 Turn 记录] TURN --> PLAN TOOLS -- 否 --> FINAL[最终文本] FINAL --> REF[反思回合] REF --> DIST[蒸馏] DIST --> SK[Skill upsert] REF --> MEM[记忆 L3 写入] REF --> END[写 End 记录] END --> DOC[doctor closure 审计]

4. 密钥隔离屏障

两层互补防线:Vault 命名替换 + 模式兜底。原值永不通过模型 API 离开本机。

flowchart LR classDef vault fill:#3a1414,stroke:#f87171,color:#fff classDef pat fill:#3a2f0a,stroke:#facc15,color:#fff classDef pass fill:#0f3a2a,stroke:#34d399,color:#fff IN[入口文本] --> V{Vault 命中?} V -- 是 --> SUB["dollar SECRET NAME 占位符"]:::vault V -- 否 --> P{模式命中?} P -- 是 --> RED["REDACTED kind fp"]:::pat P -- 否 --> THRU[原样通过]:::pass SUB --> OUT[模型 / JSONL / 记忆层] RED --> OUT THRU --> OUT

模式:sk-ant-*sk-*(≥20 字符)、ghp_/gho_/ghu_/ghs_/ghr_*AKIA…(20 位字母数字)、eyJ*.*.* JWT,以及任意 32 位以上、Shannon 熵 ≥ 4 bits/char 的高熵串。指纹 = SHA-256 前 8 位十六进制。

5. Token 经济(5 招叠加)

每招都有单测压住。叠加之后长任务实测花费降到 1/3。

flowchart LR T1[招式 1 schema 哈希指纹] --> G1[省 25 至 40 percent prompt] T2[招式 2 ephemeral cache] --> G2[实际花费降 60 至 70 percent] T3[招式 3 头加尾截断] --> G3[observation 省 50 至 70 percent] T4[招式 4 summary 工作记忆] --> G4[history 省 80 至 90 percent] T5[招式 5 tag 周期压缩] --> G5[长任务省 50 至 60 percent] G1 --> SUM[长任务花费 1/3 以下] G2 --> SUM G3 --> SUM G4 --> SUM G5 --> SUM

5.1 单轮预算(强约束)

段落上限 (tokens)超限处置
system prompt800拆到 reference,按需 file_read
tools schema (首次)2000工具数 ≤ 10、描述 ≤ 80 字符
tools schema (指纹复用)30单行替代
history 段1500summary + tag 压缩
user 新 + tool_results8000smart_format 截断
输入总和≤ 12K触发预算反馈

cache_hit_rate ≥ 60%compression_ratio ≥ 50%单轮 input ≤ 12K

6. ACP / MCP 标准互通

两条开放协议,都是 JSON-RPC 2.0 over stdio。ACP 把代理循环交给上游官方 CLI;MCP 把第三方工具搬进 ToolRegistry。

6.1 ACP — 把循环交出去

flowchart LR RT[ConversationRuntime] --> AP[AcpProvider] AP -- spawn stdio --> CLI[claude 或 codex 或 cursor 或 gh copilot] CLI -- session prompt --> AP AP --> RT

6.2 MCP — 自带工具进来

flowchart LR REG[ToolRegistry] --> WRAP[McpToolWrapper] WRAP -- tools call --> SRV[npx 或 uvx 或自写 MCP 服务器] SRV --> WRAP WRAP --> REG

7. 部署拓扑

MVP:仅本地。可选:本地 Gateway daemon。ACP / MCP 子进程一律和你跑在同一台机器上。

flowchart TB subgraph LM["你的笔记本"] direction LR UI[CLI / REPL] GD[evo-gateway daemon] RT[ConversationRuntime] BR[ACP 子进程] MS[MCP 子进程] DATA[(~/.evoclaw)] UI --> RT GD --> RT RT -. spawn .-> BR RT -. spawn .-> MS RT --> DATA end EXT((模型 API)) RT --> EXT

Vault、agents/*.toml、mcp/*.toml、logs/*.jsonl 全部在 ~/.evoclaw/,不出本机。

8. 存储索引(~/.evoclaw)

路径格式所有者用途
config.tomlTOML用户编辑provider / model / 预算 / 安全
logs/{task_id}.jsonlJSONLSession一任务一份 append-only 日志
skills/*.yamlYAMLSkill学会的 skill
skills/index.jsonJSONSkillTreeskill tree 索引
memory/{L0..L5}.jsonlJSONLMemory分层记忆
cost.jsonlJSONLCostEngine每轮 cost event
secrets/<provider>.keytext向导chmod 600
secrets/vault.jsonJSONVaultchmod 600 — 命名密钥保险柜
agents/*.tomlTOMLACP 目录外部 agent profile
mcp/*.tomlTOMLMCP 目录MCP server profile