句流 Agent 客户端架构图
4 路 模型通道统一到一个流式接口
12 轮 本地回放窗口,约束 token 膨胀
2 层 空转超时兜底(120s / 180s)
双轨 计量:付费预估 → 实时计量 → 触顶硬拦截

At a glance

案例速览

要解决的问题
agent CLI 很强,但黑底命令行对非开发者不友好:看不到它在调用什么工具、计划到了哪一步,也难以在多家模型之间切换。
约束条件
桌面端要在用户本机读写文件、执行命令,安全边界必须清晰;多家模型的协议不同(原生 messages + function calling vs. 服务端会话);付费调用不能静默烧钱。
我的职责边界
个人项目,独立完成需求、架构、Rust / Tauri 后端、React 前端、测试与打包。
结果
把 agent 的推理与工具活动变成可视、可追溯的图形界面;多家模型共用一套对话与编排接口,并有沙箱、超时与计量三重护栏。

Overview

项目说明

句流 SentenceFlow 本身是一个离线英语整句训练桌面应用。在它之上,我做了一件更「工程」的事:把 agent CLI 的工作方式拆开、复现,并做成一个图形化、多模型、带护栏的 Agent 客户端。

为什么做

opencode、Claude Code、Codex 这类 agent CLI 已经能读写文件、执行命令、规划多步任务,但它们运行在黑底终端里:看不到当前在调用什么工具、计划进行到哪一步,也很难在不同模型之间切换。

做了什么

  1. 拆原理:梳理 ReAct 循环、事件流、上下文压缩、权限沙箱与 MCP / 技能体系;
  2. 统一接口:用 ChannelAdapter 把 opencode 与 DeepSeek / Ollama / Zen 收敛到一个流式接口;
  3. 可视化:把事件流映射为打字机输出、工具活动条与任务清单;
  4. 加护栏:目录沙箱、空转超时、计量硬闸默认开启;
  5. 实测:用 Playwright MCP + WebView2 CDP 对打包后的 exe 做全功能真机测试。

配图说明:本项目为个人桌面应用,页面中的架构图按实际模块结构绘制。

Stack

技术栈与工具

  • Rust 1.85
  • Tauri 2
  • React 18 + TypeScript
  • Vite
  • wasm
  • SQLite
  • 系统钥匙串
  • Cargo workspace 多 crate
  • GitHub Actions CI
  • opencode
  • DeepSeek / Ollama / Zen
  • SSE / JSON 事件流
  • function calling
  • MCP · Agent Skills
  • Playwright MCP + WebView2 CDP

Build

实现过程

按实现顺序拆开关键模块:每一步解决什么问题、为什么这样做。

  1. 先拆原理:agent CLI 的 ReAct 循环长什么样

    拆解 opencode / Claude Code / Codex 三个 agent CLI 的「上下文装配 → 模型推理 → 工具调用 → 结果回灌 → 循环直到完成」,以及客户端—服务端事件流、上下文压缩、权限沙箱与 MCP / 技能体系,再据此设计自己的编排层。

  2. 统一的多模型 provider 抽象

    定义 ChannelAdapter trait,所有通道都实现同一个 chat_stream 流式接口。OpenAI 兼容通道(DeepSeek / Zen / Ollama)走原生 messages 多轮 + function calling;opencode 通道走服务端会话,用 SessionRef 事件把会话 id 回传给前端。

  3. 事件流 → 可视化界面

    解析 agent 的 JSON 事件流:text-delta 渲染为打字机式流式输出,start-step / finish-step / tool-call / tool-result 渲染为「工具活动条」,todowrite 还原为多步任务清单——比黑底终端更可视、更可追溯。

  4. 会话、记忆与自愈

    opencode 通道用服务端会话,API 模型用本地 12 轮回放窗口约束 token 膨胀,以本地 SQLite 为事实源。解决了「续聊只发用户消息导致协议失效」的问题(每轮重注入输出契约),并在空回复时自动用本地历史重开一轮。

  5. 护栏:目录沙箱、超时与计量硬闸

    agent 只能在用户显式选定的目录内操作,并对系统盘、主目录、桌面设多层护栏;点停止即杀掉子进程,会话可续跑;120s / 180s 空转超时兜底;计量从付费预估到实时计量再到触顶硬拦截,杜绝静默烧钱。

Decisions

关键决策

说明为什么这样做,而不只是列出做了哪些动作。

Q1

为什么先复现原理,而不是直接套 SDK

只有理解了「上下文怎么装配、工具结果怎么回灌、何时停止」,才能判断不同模型通道的差异该在哪一层抹平。ChannelAdapter 的边界就是从这一步推出来的。

Q2

可视化的价值是「可信」

用户愿意把文件和命令交给 agent,前提是看得见它在做什么。工具活动条和任务清单不是装饰,而是让人能随时判断「要不要喊停」的依据。

Q3

安全边界必须是默认值

目录沙箱、超时与计量硬闸都默认开启,而不是让用户自己记得去配置。对能执行命令的 agent 来说,保守的默认值比功能多更重要。

Result

交付与结果

交付内容

  • 统一 provider 抽象:以 ChannelAdapter trait 的 chat_stream 接口收敛 opencode CLI 与 DeepSeek / Zen / Ollama;OpenAI 兼容通道走原生 messages 多轮 + function calling,opencode 通道走服务端会话并用 SessionRef 事件回传会话 id
  • Agent 客户端与工具活动流:以 opencode run --format json --dir <目录> -s <会话> 驱动 agent,解析 text-delta / start-step / finish-step / tool-call / tool-result / todowrite 事件并分别渲染
  • 上下文 / 会话 / 记忆管理:服务端会话 + 本地 12 轮回放窗口,SQLite 为事实源;每轮输出契约重注入与空回复自愈
  • 权限、沙箱与韧性:仅在用户显式选定的目录内操作,系统盘 / 主目录 / 桌面多层护栏;停止即杀子进程且会话可续跑;120s / 180s 空转超时兜底
  • MCP 与 Agent Skills:技能搜索 / 调用 / 注入与图形化 SKILL.md 制作;诊断并一键修复 YAML frontmatter 非法导致的技能静默失效

项目结果

  • agent 的每一步推理、每一次工具调用都以可视组件呈现,过程可追溯
  • 续聊时协议不再失效:每轮重注入输出契约,空回复时丢弃服务端会话、用本地历史重开一轮,用户无感
  • 计量双轨(付费预估 → 实时计量 → 触顶硬拦截,免费请求桶 + 指数退避)杜绝静默烧钱
  • 用 Playwright MCP + WebView2 CDP 对打包后的 exe 做全功能真机实测

Retrospective

复盘

自己实现一遍 agent loop 之后,再用任何 agent 工具都更清楚它的边界:哪些问题该交给模型,哪些必须由客户端的护栏兜住。统一接口、事件可视化、护栏默认开启,是这个项目留下的三条做法。

References

方法与参考

本案例用到的工程模式与模型能力,附权威出处,方便核对。