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 prompt | 800 | 拆到 reference,按需 file_read |
| tools schema (首次) | 2000 | 工具数 ≤ 10、描述 ≤ 80 字符 |
| tools schema (指纹复用) | 30 | 单行替代 |
| history 段 | 1500 | summary + tag 压缩 |
| user 新 + tool_results | 8000 | smart_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.toml | TOML | 用户编辑 | provider / model / 预算 / 安全 |
logs/{task_id}.jsonl | JSONL | Session | 一任务一份 append-only 日志 |
skills/*.yaml | YAML | Skill | 学会的 skill |
skills/index.json | JSON | SkillTree | skill tree 索引 |
memory/{L0..L5}.jsonl | JSONL | Memory | 分层记忆 |
cost.jsonl | JSONL | CostEngine | 每轮 cost event |
secrets/<provider>.key | text | 向导 | chmod 600 |
secrets/vault.json | JSON | Vault | chmod 600 — 命名密钥保险柜 |
agents/*.toml | TOML | ACP 目录 | 外部 agent profile |
mcp/*.toml | TOML | MCP 目录 | MCP server profile |