Zagens 核心架构拆解：事件溯源引擎如何让本地 Agent 可验证-平芜编程栈

1. 本地 Agent 为什么总在长任务上翻车：从 Zagens 事件溯源说起

如果你用本地 Agent 跑过超过半小时的重构任务，大概率遇到过这三种情况：终端一关，上下文全丢；模型信誓旦旦说"已完成 61 个文件"，实际覆盖率只有 16.3%；事后想复盘某次工具调用为什么被放行，翻遍日志也找不到证据。这三个问题不是模型能力问题，而是架构问题——大多数本地 Agent 把状态放在内存里，把"完成"交给模型自己判断，把执行过程当成黑盒。

Zagens 这个项目有意思的地方在于，它没有去做更好的 Chat UI，而是给 Agent 装了一套"飞行记录仪 + 机器门禁"。核心就是事件溯源引擎 Kernel V3：所有状态跃迁以结构化 JSON 追加写入kernel_events表，UI 只是这份日志的投影视图，不是真源。这意味着会话崩了能从日志重建，任务是否完成由机器对账而不是模型自述，每一轮 turn 的决策链路都能回放。

这篇文章面向本地 Agent 开发者，把 Zagens 的事件日志、状态重建、可验证链路拆开讲，并给出可复制的配置片段和验证动作。你不需要先成为 Zagens 用户，只要理解事件溯源这套思路，就能把它迁移到自己的 Agent 项目里。适合谁：正在做本地 Agent、被长程任务状态丢失困扰、想让"完成"变成可机器验证的开发者。

2. 前置准备：TaoToken 接入与 Zagens 本地环境搭建

在复现事件回放之前，先把模型调用链路打通。Zagens 本身不托管模型，它通过 OpenAI 兼容接口调用外部模型服务，所以你需要一个稳定的 API 入口。我这边用的是 TaoToken，它提供 OpenAI 兼容的/v1/chat/completions接口，配置方式和标准 OpenAI SDK 一致，适合作为本地 Agent 的模型后端。

先拿 Key。访问 https://taotoken.net/api-keys 创建 API Key，注意这个 Key 只在创建时完整显示一次，复制后妥善保存。TaoToken 的 API 根地址是https://taotoken.net/api，注意不要带任何查询参数，Base URL 就填这个。

拿到 Key 之后，先做一次最小验证，确认链路通：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "deepseek-v4", "messages": [{"role": "user", "content": "reply with ok"}], "stream": false }'

返回里能看到choices[0].message.content就说明 Key 和网络都没问题。这一步很重要，因为后面 Zagens 的事件回放验证会依赖模型调用的稳定性，如果模型接口本身 401 或者超时，你会分不清是引擎问题还是网络问题。

接下来准备 Zagens 本地环境。Zagens 的引擎跑在 sidecar 进程里，桌面端是 Tauri 2 + WebView，TUI 是 ratatui 全屏终端，CLI 支持exec和serve --http。三个入口共用同一套引擎，所以你可以先用 CLI 验证，再上桌面。

# 克隆仓库 git clone https://github.com/didclawapp-ai/zagens.git cd zagens # 查看当前版本，v0.8.0 架构主干已落地 cat Cargo.toml | grep version # 构建 CLI（Rust 工具链需 1.75+） cargo build --release --bin zagens # 初始化配置目录 ./target/release/zagens init --config-dir ~/.zagens

初始化后会在~/.zagens下生成配置文件。你需要把模型后端指向 TaoToken。编辑~/.zagens/config.toml：

[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model_id = "deepseek-v4" stream = true [kernel] # 事件溯源引擎版本，v0.8.0 默认 v3 engine = "v3" # 事件日志数据库路径 event_db = "~/.zagens/kernel_events.db" # 记忆平面查询开关 memory_planes = true [sandbox] # read-only | workspace-write | danger-full-access mode = "workspace-write" workspace_root = "~/projects/my-agent-task"

这里三个关键字段要写全：Base URL 是https://taotoken.net/api，Key 通过环境变量TAOTOKEN_API_KEY注入，Model ID 填deepseek-v4。Zagens 的 sidecar 只从 keyring 或环境变量读 Key，不会把 Key 写进 WebView，这一点在架构上是刻意的。

设置环境变量并验证配置：

export TAOTOKEN_API_KEY="你的Key" ./target/release/zagens config check

config check会依次探测模型接口、事件数据库可写性、沙箱根目录权限。三项都返回ok再往下走。如果模型探测失败，先回到前面的 curl 步骤排查，不要带着坏配置去跑事件回放，否则你会把网络错误误判成引擎 bug。

3. 可复制配置：kernel_events 表结构与事件回放参数

事件溯源的核心是那张只追加、不篡改的kernel_events表。理解它的字段设计，你才能写出正确的回放查询。Zagens 的建表语句是这样的：

CREATE TABLE kernel_events ( id INTEGER PRIMARY KEY AUTOINCREMENT, seq INTEGER NOT NULL, -- 单调递增序号，回放排序依据 ts_ms INTEGER NOT NULL, -- 毫秒时间戳 kind TEXT NOT NULL, -- 事件类型 turn_id TEXT, -- 所属 turn payload TEXT NOT NULL -- JSON 序列化的 KernelEvent );

seq是回放的唯一排序依据，不要用ts_ms排序，因为同一毫秒内可能写入多个事件。kind字段决定了这条事件属于哪个记忆平面：SteerInjected和ScratchpadReminderInjected归 Working 平面，TopicMemoryInjected归 Episodic 平面，CompactionArtifactCreated归 Archival 平面。引擎在每个模型调用前通过Effect::QueryMemory { layer }按需拉取对应平面，而不是把所有历史塞进 prompt。

要开启完整的事件回放能力，在配置里补上回放相关参数：

[replay] # 开启 golden replay 对拍 enabled = true # fixture 目录，存放可复现的 turn 输入 fixture_dir = "~/.zagens/fixtures" # 回放时是否严格比对 Effect 序列 strict_effect_match = true # 允许的最大 seq 偏差（0 表示完全一致） max_seq_drift = 0 [harness.lht] # L1 模型自检 l1_model_selfcheck = true # L2 编译/测试/lint，机器 exit code 判定 l2_machine_check = true # L3 交付物对账，纯 Rust 检查，不经 LLM l3_artifact_reconcile = true # L3 对账的路径 glob artifact_globs = ["src/**/*.rs", "docs/**/*.md", "output/**/*.xlsx"]

strict_effect_match = true是回放验证的关键。Kernel V3 把生产路径和回放路径统一到同一套Effect枚举上：CallModel、ExecuteBatch、InjectSteer、RequestApproval、RunCompaction。同一份 fixture 同时跑 live 和 replay，如果 Effect 序列不一致，说明引擎逻辑改动破坏了旧行为，机器会直接报出来。

LHT 门禁的三层设计也值得单独配置。L1 是模型自检，输出 plan 和 checklist；L2 是编译、测试、lint，由 exit code 判定；L3 是交付物对账，纯 Rust 检查路径和 glob 是否存在，完全不经过 LLM。多数 Agent 止步于 L1，模型说完成就显示完成。Zagens 的 L3 是 Harness 和 Chat 壳的分界线——它不信模型，自己去数文件。

配置写完后，用一条命令验证事件表是否正常写入：

./target/release/zagens exec \ --task "读取 README.md 并总结三句话" \ --session test-events-001 \ --config ~/.zagens/config.toml

执行完成后查询事件表：

sqlite3 ~/.zagens/kernel_events.db \ "SELECT seq, kind, turn_id, substr(payload,1,80) FROM kernel_events ORDER BY seq LIMIT 20;"

你应该能看到ToolCallPlanned、ToolCallStarted、ToolCallFinished这样的完整链条，而不是只有一条"Assistant 读了 README.md"。UI 里显示的那句话是投影，日志里存的才是真源。这就是可验证链路的第一层：执行过程可追问。

4. 验证请求与成功结果：事件回放与一致性对拍实操

配置就绪后，跑一次完整的事件回放验证。目标是证明两件事：会话能从日志重建，回放结果与生产结果一致。

第一步，跑一个会产生多轮工具调用的任务，并保存 fixture：

./target/release/zagens exec \ --task "在 workspace 下创建 hello.rs，写入一个 main 函数，然后编译它" \ --session replay-demo-001 \ --save-fixture ~/.zagens/fixtures/replay-demo-001.json \ --config ~/.zagens/config.toml

--save-fixture会把这次 turn 的输入、模型响应、工具调用序列完整落盘。执行结束后，先看 LHT 门禁的判定结果：

./target/release/zagens harness report --session replay-demo-001

输出会分三层显示。L1 是模型自检的 checklist，L2 是cargo build的 exit code，L3 是交付物对账——它会检查hello.rs是否真实存在、内容是否包含fn main。如果 L3 报artifact missing，说明模型说完成了但文件没落地，这正是"完成不靠说"的价值。

第二步，用同一份 fixture 跑回放：

./target/release/zagens replay \ --fixture ~/.zagens/fixtures/replay-demo-001.json \ --session replay-demo-001-replay \ --strict \ --config ~/.zagens/config.toml

--strict对应配置里的strict_effect_match = true。回放完成后，引擎会输出 Effect 序列对拍结果：

Effect sequence comparison: live: CallModel -> ExecuteBatch(1) -> CallModel -> ExecuteBatch(1) -> RunCompaction replay: CallModel -> ExecuteBatch(1) -> CallModel -> ExecuteBatch(1) -> RunCompaction match: true seq_drift: 0

match: true且seq_drift: 0说明回放路径和生产路径行为一致。如果你改了引擎逻辑，比如调整了工具波次的 DAG 调度顺序，回放会立刻报出 Effect 序列不一致，这就是改引擎时的安全网。

第三步，验证会话重建。模拟桌面崩溃场景——直接 kill 掉进程，然后重开：

# 启动一个长任务 ./target/release/zagens exec \ --task "重构 src 下所有模块，逐个添加文档注释" \ --session crash-test-001 \ --config ~/.zagens/config.toml & # 拿到 PID 后强制杀掉，模拟崩溃 kill -9 $! # 重开，从事件日志恢复 ./target/release/zagens resume --session crash-test-001

resume会从kernel_events里读取该 session 的所有事件，重建 transcript 和记忆平面状态，从停下的地方继续。你不需要重述任务，因为 Working 平面的 scratchpad、Episodic 平面的 TopicMemory 图、Archival 平面的压缩产物都从日志里恢复了。

第四步，验证多端同源。用 CLI 的serve --http起一个 API 服务，然后用 TUI 连同一个 session：

# 终端 A：起 HTTP 服务 ./target/release/zagens serve --http --port 8787 --config ~/.zagens/config.toml # 终端 B：TUI 连接同一 session ./target/release/zagens-tui --session crash-test-001 --connect http://127.0.0.1:8787

TUI 里看到的聊天记录、工具调用链、审批状态，和桌面 WebView 投影出来的是同一份事件日志。换壳不丢引擎语义——这是 sidecar 架构换来的：UI 崩了 runtime 还在，一套/v1/*OpenAPI 多端复用。

到这里，事件回放和一致性校验的完整流程就跑通了。核心验证点有三个：kernel_events里有完整的 ToolCall 链条，golden replay 的 Effect 序列 match 为 true，resume 能从日志重建会话。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth

事件溯源链路跑起来后，最容易卡住的不是引擎本身，而是模型接口和鉴权。下面按真实报错逐条排查。

401 Unauthorized。这是最常见的。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在：

echo $TAOTOKEN_API_KEY | head -c 8

如果输出为空，说明环境变量没导出，或者你换了终端窗口。Zagens 的 sidecar 从环境变量或 keyring 读 Key，不会从配置文件读明文 Key。另外检查 Base URL 是否写成了https://taotoken.net/api/v1——正确写法是https://taotoken.net/api，/v1由 SDK 自动拼接。多写一层会变成/api/v1/v1/chat/completions，直接 404 或 401。

local proxy failed。这个报错通常出现在 sidecar 启动阶段，表示本地代理端口被占用或健康探测失败。Zagens 的 sidecar 会监听一个本地端口用于 UI 和引擎通信。排查步骤：

# 查看端口占用 lsof -i :8787 # 换端口重启 ./target/release/zagens serve --http --port 8899 --config ~/.zagens/config.toml

如果换了端口还是失败，检查~/.zagens/config.toml里有没有残留的proxy字段。Zagens 不需要额外代理配置，模型调用直接走 Base URL。任何proxy = "..."的配置都应该删掉。

reading choices 报错。典型信息是error reading choices: unexpected end of JSON input或choices field missing。这通常是模型返回了非标准响应，或者流式响应被中途截断。先确认stream = true时客户端能正确处理 SSE：

curl -N https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4","messages":[{"role":"user","content":"hi"}],"stream":true}'

如果 curl 能正常收到data:开头的分块，说明接口没问题，问题在 Zagens 的流式解析。检查config.toml里model.stream和kernel.engine是否匹配——v3 引擎要求流式 delta 以StreamDelta事件写入kernel_events，如果引擎版本和配置不一致，解析会失败。把engine显式设为"v3"再试。

OAuth 相关报错。如果你在配置里看到OAuth token expired或refresh token failed，说明误配了 OAuth 流程。Zagens 调用 OpenAI 兼容接口用的是 Bearer Token，不需要 OAuth。检查配置里有没有auth_type = "oauth"之类的字段，删掉，改成：

[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model_id = "deepseek-v4"

三件套写全：Base URL、Key 来源、Model ID。缺任何一个都会导致鉴权链路断裂。

事件表写入失败。报错kernel_events: database is locked。这是因为 SQLite 在多进程写入时锁表。Zagens 的 sidecar 是唯一写入方，如果你同时开了 CLI 和桌面端写同一个 session，就会锁。解决方法是确保同一 session 只有一个写入进程，或者把event_db指向不同文件做隔离测试。

回放 seq_drift 不为 0。说明回放路径和生产路径的 Effect 序列有偏差。先看strict_effect_match是否为 true，再看 fixture 是否完整。如果 fixture 是在旧引擎版本下生成的，换引擎后 seq 会漂移，重新生成 fixture 即可。这不是 bug，是事件溯源在正确工作——它检测到了行为变化。

6. 把事件溯源迁移到你的 Agent：从日志到可验证链路

Zagens 的架构选择可以浓缩成一句话：诊断层不能是引擎的补丁，诊断层必须是引擎本身。V2 时代他们试过 Shadow Bake——在命令式 turn loop 旁边额外跑一份诊断逻辑，对比输出差异。这个方案失败了，因为它只能告诉你"哪里不一致"，给不了恢复能力。会话崩了，shadow 日志能帮开发者排查，但用户面对的还是一句"上下文丢了"。

所以如果你在自己的 Agent 里想引入可验证性，第一步不是加日志，而是把状态真源从内存搬到只追加的事件表。具体做法：每次 turn 内的模型请求、流式 delta、工具规划/执行/完成、审批裁决、护栏触发、压缩标记，全部以结构化 JSON 写入一张kernel_events表，seq单调递增，UI 只做投影。这一步做完，会话重建和回放对拍就是自然结果。

第二步是把计划与执行分离。不要在 turn loop 里 inline 调模型和工具，而是先规划Effect，再统一解释执行。生产路径和回放路径共用同一套 Effect 枚举，这样你才能用一份 fixture 同时跑 live 和 replay，改引擎逻辑时有机器帮你回答"有没有破坏旧行为"。

第三步是加机器门禁。L1 模型自检、L2 编译测试、L3 交付物对账，只有 L3 是硬的。多数 Agent 止步于 L1，模型说完成就显示完成。L3 用纯代码检查路径和 glob 是否存在，不经过 LLM，这是"完成不靠说"的底线。

如果你想把模型调用链路也标准化，TaoToken 的 OpenAI 兼容接口可以直接作为后端，Base URL 填https://taotoken.net/api，Key 从环境变量注入，Model ID 按需选择。接入文档在 https://taotoken.net/doc 有完整的参数说明。想先验证模型响应格式，可以用模型对话页面 https://taotoken.net/chat 快速试一轮。长期跑编码和 Agent 任务的话，Coding Plan https://taotoken.net/coding-plan 更适合高频调用场景。

事件溯源这套思路不绑定 Zagens，也不绑定任何特定模型。它的价值在于把 Agent 的执行过程从黑盒变成可追问、可回放、可机器验证的链路。你从一张kernel_events表开始，就能让本地 Agent 的"完成"变成可验证的事实，而不是模型的一行字。