一、本地 Agent 的三个硬伤
用本地 Agent 做长程任务的开发者都会撞上同一组问题：
- 关了就没。 终端崩了、桌面关了、进程杀掉了——会话状态在内存里，丢了就是丢了。
- 「做完了」不可信。 模型说生成 61 个文件，实际覆盖率 16.3%。没有机器验证，「完成」是 LLM 的一行字。
- 执行是黑盒。 这轮 turn 里模型为什么调了那个工具？审批为什么通过？事后查不出来。
4. 审核代码输出一份报告，内容看起来逻辑自洽，但是和代码实际对不上.
Zagens 的架构选择围绕这四个问题展开：不是做更好的 Chat UI，是给 Agent 装上飞行记录仪和机器门禁。
二、总体架构：三端一引擎
编辑
三个入口共用一套引擎：
| 入口 | 形态 | 场景 |
|---|---|---|
| Zagens 桌面 | Tauri 2 + WebView | 文件树、diff、多面板、PTY |
| zagens-tui | ratatui 全屏终端 | SSH 远程、不想开 GUI |
| zagens CLI | exec / serve --http | CI、脚本、headless |
引擎只在 sidecar 里执行。 桌面 WebView 不嵌入 turn 引擎，不持有 runtime Bearer token。换壳不丢引擎语义——你用桌面跑一轮长任务，关掉后 ssh 进去用 TUI 开同一个 session，看到的是同一份状态。
Sidecar 有成本——多一个进程、健康探测、端口与鉴权。换来的是 UI 崩了 runtime 还在、一套 /v1/* OpenAPI 多端复用、API Key 只走 keyring 不碰 WebView。
三、Kernel V3：用事件溯源替代黑盒循环
旧式 Agent 的 turn 引擎是一个命令式 loop：调模型 → 跑工具 → 输出 → 清空内存，下一轮从头来。中间状态不可重现，行为改动无安全网。
Kernel V3 用事件溯源替代了这个模型。但这个结论不是一步到位的——中间经历了一次失败的「修补」，才证明事后诊断解决不了根本问题。
3.1 V2 的教训：事后诊断为什么不够
Zagens 的 V2 引擎是一个典型的命令式 turn loop：handle_deepseek_turn 进入，op_loop 循环调模型、跑工具、输出文本，turn 结束后状态留在内存里，下一轮从头来。行为正确，但不可追问——崩了就是崩了。
团队尝试过一个折中方案叫 Shadow Bake：在 V2 的命令式循环旁边，额外跑一份基于事件日志的诊断逻辑，对比两者在每个 turn 的输出差异。思路是「不改引擎，只在外面套一层可观察性。」配置文件至今还接受 machine = "shadow"（虽然已映射到 V3）。
这个方案失败了——不是技术上有 bug，而是方向上就错了。事后诊断能告诉你「V2 和 V3 在某次 turn 的输出不一致」，但给不了你任何恢复能力。会话崩了，shadow 日志也许能帮开发者排查，但用户面对的还是那句话：「对不起，上下文丢了。」
Shadow Bake 在 2026 年 6 月的 final switch 中被彻底移除。教训很明确：诊断层不能是引擎的补丁，诊断层必须是引擎本身——所以有了 Kernel V3 的事件溯源设计。
编辑
3.2 设计：只追加，不篡改
每次 turn 内发生的所有状态跃迁——模型请求、流式 delta、工具规划/执行/完成、审批裁决、护栏触发、压缩标记——全部以结构化 JSON 写入 kernel_events 表：
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,
payload TEXT NOT NULL -- JSON KernelEvent
);
设计原则只有一条：kernel_events 是 SSOT。 UI 里显示的聊天界面是从这份日志投影出来的视图，不是真源。用户看到一条 "Assistant 读了 foo.rs"，日志里存的是 ToolCallPlanned → ToolCallStarted → ToolCallFinished 的完整链条，附带审批 verdict 和执行耗时。
编辑
3.3 记忆平面：一份日志，三个消费层
kernel_events 不是存完就放着的死数据。Kernel V3 内部按记忆时效把事件分成三个平面，引擎在每个模型调用前按需查询：
| 平面 | 存什么 | 时效 |
|---|---|---|
| Working | 当前 turn 的 scratchpad、steer 注入、续跑信号 | 本轮有效 |
| Episodic | 跨 turn 的 TopicMemory 图注入 | 会话级 |
| Archival | Compaction 压缩产物和摘要 | 长期归档 |
三类事件分别记入对应平面：SteerInjected / ScratchpadReminderInjected 归 Working，TopicMemoryInjected 归 Episodic，CompactionArtifactCreated 归 Archival。引擎通过 Effect::QueryMemory { layer } 在每步模型调用前拉取当前平面状态，注入上下文编译器——不是把所有历史塞进 prompt，而是按时效分层存取。
编辑
3.4 引擎内部：计划与执行分离
Kernel V3 不再在 turn loop 里 inline 调模型和工具，而是先规划 Effect，再统一解释执行：
| Effect | 做什么 |
|---|---|
CallModel | 流式 LLM 调用 |
ExecuteBatch | 工具波次（DAG 调度） |
InjectSteer | 用户干预或 LHT 续跑注入 |
RequestApproval | 策略门禁下的审批流 |
RunCompaction | 上下文压缩 |
生产路径和回放路径共用同一套 Effect 枚举。 这意味着可以用一份 fixture 同时跑 live 和 replay，对比结果是否一致——改引擎逻辑时有机器帮你回答「有没有破坏旧行为」。
编辑
3.5 用户得到什么
Kernel V3 的三层回放能力直接翻译成三个用户体验：
- 会话不丢。 桌面崩了、系统重启——重开 Zagens 后引擎从
kernel_events日志修复 transcript，从停下的地方继续，不需要重述任务。 - 完成不靠说。 LHT 门禁从同一份事件日志里读工具执行结果，主动跑编译/测试/文件对账——验证不经过模型。
- 状态不锁在 UI 里。 一份事件日志，桌面 WebView 投影成聊天、API 返回诊断报告、golden replay 跑一致性对拍——多端同源。
用一句话概括 Kernel V3 和旧 loop 的区别：旧方案跑完拉倒；Kernel V3 跑完、记好、能复现。
四、Harness 层：引擎之上再叠三层兜底
Kernel V3 解决「怎么记、怎么回放」。Harness 层解决「怎么算做完、怎么不越权」。
4.1 LHT 完成门禁：三层验证
Long-Horizon Task 门禁分三层，只有第三层是「硬」的：
| 层级 | 做什么 | 谁说了算 |
|---|---|---|
| L1 | 模型自检（plan + checklist） | 模型 |
| L2 | 编译 / 测试 / lint | 机器（exit code） |
| L3 | 交付物对账（路径/glob 是否存在） | 纯 Rust 检查，不经 LLM |
L3 是 Harness 和 Chat 壳的分界线。 多数 Agent 止步于 L1——模型说完成了就显示「完成」。Harness 不信模型，自己去数文件。
编辑
4.2 OS 级沙箱
本地 Agent 与用户同权，误操作风险真实。Zagens 提供三档沙箱：
read-only— 禁止 Shell 与文件写入workspace-write— 写入限于工作区（推荐默认）danger-full-access— 完整访问
Windows 下 elevated 模式额外限制工作区外不可写、敏感目录不可读。
4.3 Code + Office：同一 runtime，不同任务类型
纯 coding Agent 只覆盖代码路径。Zagens 额外支持 Office 任务类型——同一引擎下，read_file 读数据，write_office 出 DOCX/XLSX/PPTX/PDF。xlsx 走纯 Rust，docx/pptx/pdf 走捆绑 Python。
这不是「多一个工具」，是代码和文档交付被同一套门禁、同一份事件日志管着。
五、取舍：我们刻意重的，和刻意不做的
刻意重的： Sidecar 隔离 + 事件溯源 + golden replay + 机器验真 + OS 沙箱
刻意不做的：
- 不做 IDE 插件——不卷补全，不绑定编辑器
- 不做 SaaS——不托管模型，不替用户存 Key
- 不上手即用——当前 Windows 桌面安装包已发布，macOS/Linux 桌面包规划中
当前状态（v0.8.0）： 架构主干已落地。桌面仅 Windows，TUI/CLI 三平台。社区早期，文档建设中。
六、结语
Zagens 面向深度使用 DeepSeek V4 的开发者，适合中小型项目任务——从代码重构到原型搭建，从技术文档到周报、表格、PPT，同一引擎、同一套门禁、同一份可追溯的事件日志。个人用得顺手，团队协作有迹可循。跨轮次的长程任务有 LHT 门禁兜底，沙箱保障执行安全，代码与 Office 交付共享同一工作流。
许可： MIT · GitHub: github.com/didclawapp-…
