源自 deepseek-tui 血统的 Zagens 实测：当 AI Agent 有了桌面控制台

花了两天克隆、构建、上手，这篇是纯体验向的记录

一、先说说血统

如果你用过 deepseek-tui ，需要知道它 upstream 已经 rebranding 成 CodeWhale （codewhale 命令，v0.8.x，社区 30k+ stars）------仍然是 Rust 终端 agent，但早已不是「只有聊天 + 改文件」的轻量壳：MCP、skills、hooks、持久化 sub-agent、SQLite 会话/thread 回放、macOS Seatbelt、codewhale serve --http 等都在主线里。

Zagens 从这条 runtime 血统分叉出来，走桌面 harness 路线。 不是把 CodeWhale 换皮，而是把引擎嵌进 Tauri 2 桌面壳 + 独立 sidecar ，交互层、Office 工作流、LHT 完成门禁、Windows 原生沙箱、CRAFT 多角色 fix-loop 等是 Zagens 自己的 product bet。配置目录是 ~/.zagens/；legacy ~/.deepseek/ 会在首次启动迁移 config/skills/MCP（会话库不迁）。

项目在 GitHub 上：github.com/didclawapp-...，MIT 许可。Runtime 系谱见 NOTICE.md。

二、从终端到桌面：Zagens 长出了什么

说「分叉进化」并不夸张，但不能把 upstream 写扁 ------今天的 CodeWhale 本身已是功能完整的终端 harness。Zagens 的差异主要在桌面控制面、Office 工作流、LHT 完成门禁、Windows 沙箱、CRAFT 编排，而不是「CodeWhale 什么都没有」。

核心引擎：同血统，不同产品形态

CodeWhale 默认是 TUI 单进程 （也可 codewhale serve --http 做 headless）；会话、checkpoint、side-git 快照、thread 事件时间线都在 upstream 里。Zagens 把同血统引擎拆成 桌面壳 + loopback sidecar，并叠加 Code/Office 双任务类型与 LHT。

下表对比 CodeWhale upstream（deepseek-tui 现品牌，v0.8.x） 与 Zagens v0.7.4+（TUI / kernel-v2 部分见 v0.7.5 unreleased）：

维度	CodeWhale（deepseek-tui upstream）	Zagens（当前）
交互形态	终端 TUI 为主 + HTTP/SSE Runtime API + 编辑器/GUI 集成	桌面应用（Tauri 2）为主 + 可选 `zagens-tui` + CLI
进程模型	TUI 单进程；或独立 `serve --http`	桌面默认双进程：Tauri 壳 + `zagens-runtime` sidecar
会话耐久	SQLite thread store、`--resume`/fork、checkpoint/offline queue、API 事件回放	SQLite 全量持久化 + 桌面 UI 按轮回放/fork
任务验证	checklist/plan + durable task gates（`task_gate_run` 等 verifier）	LHT 三层完成门禁（自检 → 硬验收 exit code → 交付物 Rust 对账，LLM 不做终审）
多代理	持久化 sub-agent（`agent_open`/`agent_eval`）、RLM 会话、并发子代理	CRAFT 多角色 + 结构化裁决（PASS/BLOCKER/MAJOR/FAIL）+ fix-loop + 黑板
文档产出	无 Office 生成工具	`write_office`：XLSX（Rust）+ DOCX/PPTX/PDF（Python）
沙箱隔离	macOS Seatbelt 已强制；Linux Landlock 规划中；Windows 尚无完整 OS 级沙箱	Windows elevated/unelevated 原生沙箱 + macOS Seatbelt + Linux 可选 bwrap（`prefer_bwrap`）
审批控制	Plan / Agent / YOLO + 工具审批对话框	四档审批（on-request/untrusted/never/auto）+ 域名级网络规则 + Token 不出 WebView
技能/MCP	`~/.codewhale/skills` + MCP + hooks	`~/.zagens/skills` + MCP + 路由规则
多提供商	DeepSeek 优先 + OpenRouter/NIM/Ollama/MiMo 等 10+ 路由	DeepSeek + OpenAI + NIM + OpenRouter + Ollama 等
凭证存储	config + OS keyring + env	OS keyring 为主
i18n	README/文档多语言；TUI 以英文为主	桌面 UI 简中 / English / 日本語 / Português (BR)
生命周期钩子	pre/post tool 等 hooks	pre/post session、tool、subagent 钩子
定时任务	AutomationManager + RRULE	RRULE 定时自动化（后台 Tasks）
KV 缓存可观测	capacity/pricing 遥测；无 prefix fingerprint UI 芯片	prefix fingerprint + 缓存命中率芯片（kernel-v2 M5）
代码规模	大型 Rust monorepo（30k+ stars 社区）	15 个 workspace crates + 桌面前端

Zagens 相对 CodeWhale 血统额外强化的几块

不是「upstream 从零没有」，而是 Zagens 在这些方向上走得更 productized：

Sidecar + 桌面控制面 ------桌面模式下引擎跑在独立子进程（zagens-runtime），UI 只走 loopback HTTP/SSE。WebView 崩溃 sidecar 仍在；sidecar 重启不拖垮壳；执行 Token 不进 WebView。Sidecar 也可单独 zagens serve --http --port 7878 给 CI/脚本用（CodeWhale 同样有 serve --http，差异在 Zagens 默认桌面即 sidecar-first）。

CRAFT 多角色 fix-loop ------CodeWhale 有成熟的持久化 sub-agent 和 task verifier，但没有 Zagens 这套 Explore → Implementer → Reviewer → Verifier 角色链 + 结构化裁决 + 黑板 fix-loop（Implementer 最多三轮后 escalate）。这是编排协议层的差异，不是「有没有子代理」。

Office 工具链 ------upstream 不涉及 xlsx/docx/pptx/pdf 生成。Zagens 的 write_office：XLSX 纯 Rust（rust_xlsxwriter），DOCX/PPTX/PDF 走捆绑 Python；生成后在 deliverables/.office/ 留 .payload.json，可用 load_office_payload 增量改稿。

Windows 沙箱 ------CodeWhale 在 macOS 上 Seatbelt 是主线能力；Windows 侧 upstream 文档仍标注「helper 未就绪、不宣传完整 OS 沙箱」。Zagens 0.7.x 已落地 Windows elevated（Token+ACL+WFP）/ unelevated 两档。Linux 两边都还在演进：CodeWhale 推 Landlock；bwrap 在 Zagens 需 prefer_bwrap = true 且安装 bubblewrap，默认仍是 degraded。

桌面级会话回放 ------CodeWhale 的 thread 事件时间线可通过 Runtime API 回放；Zagens 额外提供桌面壳内的按步可视化回放（文件树、Diff、子代理面板同一上下文），更适合审计长程 agent 轨迹。

三、装起来看看

下载

Releases 页有 Windows 安装包（.zip 压缩包+CLI 二进制），解压就能跑。macOS 和 Linux 目前 CLI 二进制可用，桌面安装包还在路上。

从源码构建（以 Windows 为例）

bash 复制代码

git clone https://github.com/didclawapp-ai/zagens.git
cd zagens

# 编译 sidecar
cargo build -p zagens-cli

# 装前端依赖
cd crates/desktop/web-ui && npm install

# 启动开发模式
cd .. && cargo tauri dev

Rust 1.88+，Node 20 LTS，Python 3.8+，Tauri CLI 2。首次 Cargo 完整构建需要等待一段时间（具体取决于机器），npm install 也需几分钟。

首次启动

开屏是一个浅色/深色自适应（跟随系统）的聊天界面，左侧是会话列表，右侧是文件树、Diff 和子代理面板：

点「设置」填入 DeepSeek API Key（也支持 keyring 存凭据），选模型（deepseek-v4-pro / deepseek-v4-flash），设好 reasoning_effort 级别，就能开始对话了。Zagens 使用自己的配置目录 ~/.zagens/config.toml（首次启动自动创建默认模板）。如果原来有 ~/.deepseek/ 目录，配置、技能、MCP 会在首次启动时自动迁移过来，但会话数据库不会迁移。

四、干活实测

4.1 写代码

选 Code 任务类型，丢给 Zagens 一个常见问题：

「帮我把这个 Rust 项目里的 unwrap() 全部替换成有意义的错误处理」

Zagens 的做法和「只聊天不改仓库」或「只靠 checklist 自报进度」不同（CodeWhale upstream 也有 plan/checklist 和 task verifier，但 Zagens 的 LHT 额外加了硬验收 exit code + 交付物 Rust 对账）：

先预览项目结构，找到所有含 unwrap() 的文件
逐个读取文件，理解上下文
用 edit_file 工具逐个编辑，每个编辑完自动触发 LSP 诊断，如果出现编译错误它会自己修复再继续
最后执行 cargo check 验证全部通过

整个流程是「计划 → 分批执行 → 验证 → 报告」，不是一口气吐出来让你自己改。

这背后是 Long-Horizon Task（LHT） 机制------一个可组合的完成门禁系统：模型自检（plan + checklist）→ 硬验收命令（cargo check/跑测试看 exit code）→ 交付物对账（纯 Rust 模块做路径存在性检查，不经过 LLM），哪一层没通过就继续，而不是模型说「改完了」就算完。

实测感受：小规模项目（几千行）的 unwrap 替换完全可行，省去手动 grep 替换的重复劳动。大规模重构建议分段任务，让它逐个模块处理。

4.2 写文档和报表

切换任务类型到 Office：

「写一份 Q2 项目周报，汇总这三周的 Git 提交记录」

Zagens 会先读 Git 日志，然后调用 write_office 工具生成一个格式整齐的 XLSX 文件，自动带表头样式、列宽、交替行色和自动筛选：

复制代码

格式：XLSX
路径：deliverables/周报_2026-W25.xlsx
├─ 工作项（日期、提交人、描述、统计）
├─ 汇总行
└─ 自动筛选 + 冻结首行

PPTX 和 DOCX 也支持（通过嵌入式 Python），但生成速度稍慢于 XLSX（后者是纯 Rust 实现）。

实测感受：对「从数据直接出表格文档」的场景非常实用，省掉了从代码日志复制到 Excel 的手工步骤。但复杂的图文混排、特定模板排版还是需要人工调。

4.3 多代理协作（CRAFT）

Zagens 的 CRAFT 机制是多角色协作：

Explore：只读探索代码库
Implementer：写代码
Reviewer：审查代码，给出结构化裁决（PASS/BLOCKER/MAJOR/FAIL）
Verifier：跑测试和 lint
Auditor：全库审计时用，机械验证 cited 行号和文件路径是否正确

默认的对话模式是单代理，但系统会根据任务自动 spawn 子代理，也可以用 agent_spawn 显式创建。例如：

「调查一下这个模块的测试覆盖率」

它会 spawn 一个只读 Explore 子代理去查目录结构、读测试文件、看 CI 配置，然后把结果汇总回来。多个子代理之间并行运行。

实测感受：单代理和子代理在同一个会话里，子代理的发现可以被主代理直接利用。对于「先调研再实施」的工作流非常自然。但子代理数目多了（超过 5 个），右侧面板会有点挤，UI 还有优化空间。

4.4 会话回放

Zagens 把 upstream 已有的 SQLite thread 持久化，做成了桌面里的按步可视化回放------历史 session 里能看到每一步模型输出、工具调用与返回，配合文件树/Diff/子代理面板做审计。CodeWhale 同样 durable 存 thread，并可通过 Runtime API 拉事件时间线；差别主要在 Zagens 给非终端用户的一体式回放 UI。

五、架构上的差异化设计

scss 复制代码

┌─ Zagens (Tauri 2) ────────────────────────┐
│   WebView UI (React/TS) ←→ Rust 外壳     │
│         │ HTTP + SSE                      │
│         ▼                                 │
│   Runtime sidecar (loopback HTTP/SSE)     │
│   ┌─ 核心 crates ─────────────────────┐   │
│   │ agent, core, config, tools, mcp   │   │
│   └───────────────────────────────────┘   │
└───────────────────────────────────────────┘

几个值得注意的点：

Sidecar 架构 ：Agent 引擎跑在独立的子进程里（Tauri externalBin），UI 只通过 HTTP/SSE 通信。这意味着即使用 WebView 崩溃，sidecar 还在跑；反过来，sidecar 重启不会影响 UI 壳。执行 Token 从不出 WebView，安全边界清晰。

Code + Office 双模式：同一个 sidecar，切换任务类型时工具面和提示词不同，但共享配置和引擎。切换类型时新开 session，避免 KV 缓存污染。

Windows 原生沙箱 ：elevated 模式用系统沙箱隔离子进程，配置文件只读隔离 + WFP 文件保护；unelevated 模式做工作区写隔离。macOS 用 sandbox-exec。Linux 默认未强制；安装 bubblewrap 且 prefer_bwrap = true 时走 bwrap。

六、和一些常见方案的粗略对比

维度	Zagens	普通 ChatGPT/DeepSeek Web	Cursor/VS Code AI
执行模型	本地 sidecar，自备 Key	云端，包月/按量	IDE 插件
桌面集成	系统托盘、通知、PTY 终端	浏览器 Tab	IDE 内
长程任务	分层门禁 + 可回放	一次性对话	有限
Office 支持	原生 xlsx/docx/pptx/pdf	无	无（靠插件）
多代理	CRAFT（多角色 fix-loop）	单 agent	单 agent
会话回放	SQLite 持久化 + 按步回放	历史记录	历史记录
沙箱	Windows 原生 / macOS Seatbelt / Linux 可选 bwrap	服务端	依赖 IDE/产品策略
开放性	MIT，可自建	闭源	闭源（部分开源）

和 CodeWhale（deepseek-tui upstream）怎么选？ 要成熟终端 TUI、Constitution 式治理、side-git /restore、VS Code Runtime API 集成------CodeWhale 仍是主力。要 Windows 桌面壳、Office 产出、LHT 三层门禁、CRAFT fix-loop------看 Zagens。两者不是替代关系，血统相同、产品形态不同。

不是说 Zagens 更「好」，但它的设计决策和现有方案有明显的取舍差异------如果你很在意本地执行的可控性 、长程任务的可信度 、代码+文档一个工作流，它确实填补了一个空白。

七、近期动态：TUI 终端和 V2 内核升级

Zagens 的迭代速度很快。从 CHANGELOG 来看，最近两个方向的投入值得关注。

7.1 全功能 TUI 终端（`zagens-tui`）

Zagens 最初是桌面应用（Tauri 壳 + sidecar）。但在 v0.7.5 unreleased 中，新增了一个可选 feature tui 和独立二进制 zagens-tui------一个基于 ratatui 的全屏三栏终端界面 ，跟桌面版共用同一套 agent 引擎（RuntimeThreadManager 跑在进程内，不再 split 成 sidecar）。

这意味着用户多了一个选择：习惯终端的可以在 iTerm/Windows Terminal 里跑 zagens-tui，习惯桌面的用 Tauri 壳。两种形态共享配置、会话存储、技能和 MCP。

TUI 目前已具备的能力（从 unreleased 的密集提交来看）：

三栏布局：左侧会话列表，中间 Transcript + Composer，右侧 Inspector 面板
LHT 完整支持 ：长程任务 checklist、plan phases、blocked/nudge 状态在 TUI 里实时展示，/lht 切换模式
模型/审批切换 ：/model 选模型、Ctrl+A 循环审批策略
Inspector 面板 ：Files（文件树预览）、Diff（staged/worktree 切换）、Agents、MCP 四 tab，j/k/1--4/Enter 键盘导航
会话恢复 ：启动时恢复到上次所在的 workspace 和 session（--fresh 跳过）
活动状态条：模型运行时显示 THK / 工具调用 / AI 阶段动画条
39+ 单元测试、Ctrl+V 粘贴、光标编辑、prompt 历史、流式渲染

对 CodeWhale 老用户来说，这个 TUI 不是简单 fork 回 upstream------它把 Zagens 桌面版积累的 LHT、CRAFT 等编排能力带回了终端（MCP/skills/hooks/sub-agent 两边血统本就有）。

7.2 内核从 V1 到 V2 升级（kernel-v2）

Zagens 的底层工具执行内核正在经历一次系统性的重写，内部代号 kernel-v2 。M0--M5 里程碑均已落地首版或 partial/initial 交付，默认仍以 legacy 运行；通过 config.toml 的 [tools] 两路开关灰度尝鲜

简单说，V1 的工具调度是「能跑就行」------按顺序排，等上一个结束再下一个。V2 把每个工具的读写边界（Footprint）、资源依赖（ResourceSet）、安全来源（Provenance）都 formalize 了；scheduler = dag 才启用 DAG 并行，policy = engine 才切 manifest 驱动审批------两者独立，不是单一 engine 开关全包。

以上升级预计将在下周的0.8.0版本放出

八、诚实说一些不足

体验两天下来，值得列出来的：

macOS/Linux 桌面包还在路上。 目前 Windows 桌面体验最完整，macOS/Linux 可以用 CLI（zagens exec 模式）或从源码构建。三平台的 CLI 二进制都是可用的，但如果想要完整桌面体验，现阶段 Windows 是第一选择。
Office 深度有限。 读写核心路径走通了（尤其是 XLSX，纯 Rust 速度很好），但企业级的邮件合并、复杂模板、数据透视表还是得回 Office 原生软件。
文档和社区还在早期。 相对 CodeWhale 的 30k+ stars 与成熟文档站，Zagens 教程、最佳实践、第三方集成仍在积累（Issues/Discussions 里维护者会回，但生态差距客观存在）。
CRAFT 子代理的 UI 有待打磨。 多子代理并发时右侧面板的信息密度有点高，需要时间来适应信息布局。
长程任务的边界案例。 LHT 门禁系统在大多数场景下工作良好，但如果任务本身模糊（比如「重构这个模块，但我不确定要改成什么样」），模型可能会在「继续做」和「停下来问」之间摇摆。

九、总结

Zagens 不是又一轮 AI 聊天工具。它从 CodeWhale / deepseek-tui 的 agent runtime 血统出发，做了一个以本地执行为核心的桌面控制台------Code 和 Office 共享引擎、桌面级会话回放、LHT 完成门禁而不是「模型说完了就算」。

相对 CodeWhale upstream ，Zagens 的差异不在「有没有 MCP/子代理/沙箱/持久化」------upstream 这些已经很强------而在 桌面 sidecar 控制面、Office 产出、LHT 三层门禁、CRAFT fix-loop、Windows 原生沙箱 。近期又补上了可选 zagens-tui，并把工具执行内核升级到 kernel-v2------不是换 UI 壳，而是另一套 product 取舍。

适合这样的人群：

日常用 DeepSeek API，想要桌面 harness（而不只是终端 TUI 或编辑器插件）
做长程代码任务，需要能回放、可审计的 agent 执行轨迹
代码和 Office 文档在同一个工作流里流转
在意本地执行的沙箱隔离和审批控制

不太适合：

只想开个网页聊天，不想装东西
团队要用托管 SaaS 和统一计费
只用 macOS/Linux 桌面且不想用 CLI 或源码构建

项目地址：github.com/didclawapp-...，MIT 开源。Upstream 血统：github.com/Hmbown/Code...。代码架构：15 个 Rust workspace crates + 桌面前端，模块边界清晰。

文章基于 Zagens v0.7.4 / v0.7.5（unreleased），2026-06-13 实测。配置环境：Windows 11 + DeepSeek V4 Pro。