前端

同一条 AgentEvent 流有三个消费者,外加包在第三个外面的一层桌面外壳。添加其中任何一个都不需要改动引擎,这正是拆分的意义所在。

终端

oharness

一个全屏界面:滚动历史、固定的输入框、状态栏,以及用于批准和模式选择的浮层。它没有用 TUI 库,所以有几件事必须自己做对,而不能想当然:

  • CJK 宽度。 东亚字符占两列。按一列来算,下面每一行都会在错误的位置换行。
  • 恢复终端。 真正要紧的失败不是画错一帧,而是退出时没有离开 raw 模式:用户会面对一个没有回显、没有光标的终端,只能盲打 reset。恢复逻辑接到了每一条退出路径上,包括未捕获的异常,并有一个让真实进程崩溃的测试来证明。
  • 括号粘贴(bracketed paste)。 没有它,粘贴三行文字就会触发三轮对话。

管道输入、CI 和哑终端会退回到一个基于行的循环,行为相同,也依然可以写脚本调用。

产物在这里每个占一行——标题、类型、大小、修订版本。终端能如实展示的类型就展示;页面、图片或 SVG 会说明这一点,并指向浏览器前端。这种拒绝是明确声明的答案,而不是遗漏:每种类型在一张表里都有一项,每个前端都必须填写;如果引擎新增了某种类型却没有对应项,测试会失败,而不是在三个前端之一里悄无声息地渲染成空白。

无头模式

oharness-headless "a task"
echo "a task" | oharness-headless

stdout 只输出 JSONL,别无其他,所以可以直接管道给 jq。诊断信息走 stderr。运行失败时退出码为 1。

没有人在场回答权限询问,所以任何需要询问的操作都会被拒绝,并作为事件报告出来。悄悄批准会让无人值守的运行比有人值守的更危险,这就本末倒置了。用规则预先授权,或者传入 --permission-mode。

出于同样的原因,也没有人回答 ask_user 的提问。这个工具会立即返回,告诉模型选一个合理的默认值并说明自己的假设;JSONL 里仍然会带上 question_request 和 question_result,让监管方能看到它原本想问什么。

浏览器

oharness-web

Markdown 渲染、可折叠的工具卡片、文件 diff、产物架、会话标签页、项目切换器、模型和权限选择器、附件。

会话在哪里运行,是在输入框上设置的,就在模型和权限模式旁边——这三样决定了这条消息将以什么条件发出。它默认是当前已打开的项目,这几乎每次都是正确答案;菜单里列出在这里打开过的每个目录,另有一个文件夹对话框用于还没打开过的目录。它只在会话说出第一句话之前存在:会话记录属于录制它的那棵目录树,所以在第一条消息之前更换文件夹,会在新目录里重新开始会话,并把未动过的原会话直接丢掉,而不是把它归档到侧边栏里。

移除一个项目是两件不同的事,它们放在两个不同的地方,因为除了用词之外毫无共同点。从列表中移除——项目切换器某一行上的 ✕——只是忘掉一个路径:已记录的东西都不会动,只要项目在侧边栏里还有会话,它就保留在那里,因为侧边栏是按会话记录所属的目录树分组的,而不是按那个列表。真正把项目从侧边栏移除的是删除它的会话,这在项目标题的菜单里,会询问一次,并说明会删除什么:会话记录、产物和权限记录,包括本机以及你同步的所有设备上的。无论哪种方式,目录及其文件都不会被动。删除你当前所在的项目时,窗口会先切换到另一个项目。

会话带着自己的目录树,已经打开的标签页也带着各自的——在另一个项目里开始工作,它们会继续运行;一旦有两个标签页的项目不一致,标签页就会标出自己的项目名。在侧边栏里点击另一个项目的会话记录也一样:它会在那个项目的 harness 上打开,而不是把所有东西都搬过去。侧边栏顶部的切换器仍然是你表达「我现在在这里工作」的方式;会话最后一次在哪棵目录树里启动或重新打开,下一次运行就在哪里打开。

输入框有两种方式让消息指向某样东西,按东西在哪里来区分。

+ 指向这台机器。附加文件或照片和附加文件夹会在 agent 运行的主机上打开平台自带的对话框,因为浏览器的文件输入框有意不提供路径——这对粘贴的截图来说是对的,但对一个 agent 本可以直接打开的日志来说毫无用处。它们是两行而不是一行,因为背后是两个对话框:只有 macOS 有一个能在同一次操作中同时选文件和文件夹的面板,在其他平台上,一行同时承诺两者的选项只能打开其中之一。旁边是这个 harness 已连接的 MCP 连接器及其实时工具数量、它加载的插件,以及真正会发送字节的上传功能。选中的东西变成一个标签,服务端把这些标签转成提示词上方的一小段内容:路径只写名字,不内联内容,所以 agent 会用你看得见的工具去读取它需要的东西。

连接器下面是可选的连接器列表——作为数据随 src/mcp/registry.json 发布,并由 ~/.oharness/connectors.json 叠加覆盖,所以往菜单里加一项永远不需要改代码。选中一项会同时完成两件事:服务器立刻连接,它的工具在下一轮就能用;声明也写进用户配置,明天还会回来。启动失败的连接器会被再次移除,而不是留下一行失效的条目,背后还挂着配置文件里的一行。

远程连接器对第一个请求返回 401,这不是失败——而是登录的开始,所以那一行会这样说明并提供登录,而不是显示红色错误。接下来全部是自动发现,无需任何配置:质询里指明了服务器的受保护资源文档,它指明了授权服务器,授权服务器的元数据给出各个端点,然后当场向它注册一个客户端。浏览器打开,重定向落在本进程在整个流程期间持有的回环监听器上,tokens 存进 auth.json,权限同样是模型厂商所用的 0600。这条链路上没有任何东西是针对某个厂商的,这正是关键:一个没人为它加过条目的服务器,和有条目的服务器一样好用。

这个列表保持简短,因为它是一种便利,而不是一道边界。它省下的只是你去查一个 URL。一个条目的门槛是:服务器由它所暴露数据的所有者发布,使用 streamable HTTP 而不是旧的双通道传输,并且点一下或设置一个指定的变量就能用;npm run verify:connectors 会逐个询问每个远程服务器由谁授权并报告返回结果,这就是注册表里 verified 日期的含义。

tokens 在每次请求时解析,而不是在构建传输层时捕获——一个访问 token 的有效期大约比一次长会话短一个小时,在连接时快照下来的请求头,意味着会话会在中途悄无声息地失效。刷新失败也不是致命的:旧 token 照样发出去,服务器返回 401,而这条路径本来就知道如何请求重新登录。

每一行都带有厂商的标志,但页面自己并不去获取它。否则十二行就是十二次第三方图片请求,每一次都在告诉某个厂商:这个用户在连接任何东西之前打开了菜单——而这个页面的全部主张就是它不和任何人通信。所以由服务端来解析图标:它读取厂商网站在自己的标记里声明的图标,退回到 /favicon.ico,检查返回的确实是图片,而不是一个对任何路径都返回 200 和自身页面的单页应用,然后把字节保存在磁盘上。页面只会请求本源。一个没有可用图标的网站不会有任何代价——那一行会画一个字母方块,连接器照常工作。

如果服务器要的是普通的 API key,就写 ${env:NAME}——可以放在请求头、参数、URL 或子进程的环境变量里。写进配置文件的是这个引用,值在服务器启动时从环境变量读取,所以一份被共享、同步或提交的配置永远不会包含 key。如果变量没有设置,会在尝试连接之前就点名指出,因为「MCP_TOKEN is not set」是一句你能据此行动的话,而服务器对一个空凭据说的话就未必了。

插件下面是这个 harness 加载了什么,而这个列表也不再只是某人手动复制进 ~/.oharness/plugins 的东西。这里的插件是一个清单文件加上一个 skills/ 和一个 agents/ 文件夹,Claude Code 插件也是如此——同一个想法被分别想到了两次,用了两种文件布局。同时读取两者只需要大约二十行代码,而它决定了这个面板背后是一个生态,还是在一台已经装了二十个插件的机器上一片空白。不会导入任何东西:目录留在安装器放置它的位置,就地读取,所以在那边更新,这边也就更新了。

采用哪些内容取决于插件来自哪里,分界线在于 agent 读取的东西和自行运行的东西之间。技能和 agent 是文本,在 agent 判断相关时才被查阅。钩子是在生命周期事件上触发的一条命令行,MCP 服务器是启动时拉起的一个进程。这两者会被读取和报告——那一行会说明插件带了什么——但不会从另一个程序的目录里激活,因为把它们装在那里的用户,是让它们服务于那个程序的。来自这类插件的服务器要按常规方式通过连接器添加,走那条路径本来就有的确认和登录流程。

@ 指向项目。它从光标处开始对目录树做模糊搜索,并把路径放进句子里它本该出现的位置——「compare @a with @b」表达的意思,是输入框上方的两个标签表达不了的。这也是为什么 + 里没有项目浏览器:大家最常提到的文件就在项目里,而 @ 已经能点名它们了。

能访问这个端口,就等于拿到了这台机器上的一个 shell。 它背后的 agent 会写文件、跑命令,所以服务器只绑定回环地址,并要求一个每次运行时新生成、从不持久化的 token。比较是常数时间的:一个普通的 !== 会把 token 一个字符一个字符地泄露给任何能测量响应时间的东西。

页面完全自包含——没有 CDN,没有外部字体。一个能驱动 shell 的页面,绝不能在这个上下文里把脚本执行权交给第三方。出于同样的原因,渲染器构建 DOM 节点并设置 textContent;它从不把来自模型、工具结果或文件的内容赋给 innerHTML。

产物是唯一的例外,而这条规则之所以表述得如此精确,正是因为它们。HTML 产物的全部价值就在于浏览器执行它,所以它不能经过那个渲染器——它从自己的路由提供,放进一个 sandbox="allow-scripts" 且没有 allow-same-origin 的 iframe,并配有 Content-Security-Policy,其中 connect-src 'none' 是承重的部分:不透明源只能阻止框架读取响应,却挡不住它发送请求,而另一端的服务器驱动着一个会运行 shell 命令的 agent。那个路由用它自己的凭据把关,而不是会话 token,因为沙箱里的文档可以读取自己的 URL。

分析统计

默认关闭。除非服务器启动时带了 PostHog 项目 key,否则不会向任何地方发送任何东西——这是唯一能打开它的方式:

变量作用
OHARNESS_POSTHOG_KEYPostHog 项目 key。设置后,页面会加载 PostHog 并上报功能使用情况;不设置,就没有任何分析代码进入浏览器
OHARNESS_POSTHOG_HOST默认为 https://us.i.posthog.com。欧盟云是 https://eu.i.posthog.com;自托管实例就用它自己的源

打开它,就接受了上一段所拒绝的取舍,所以值得确切知道它换来什么、付出什么。会发送的:每个操作一个事件——app_opened、panel_opened、prompt_sent、model_switched、permission_answered——只带可枚举的属性,比如哪个面板、哪个模型。不会发送的:提示词、文件路径、diff、会话记录、会话标题,以及页面的 URL。自动采集是关闭的,所以永远不会按按钮上的文字记录点击;会话回放是关闭的;URL 相关属性被双重屏蔽,因为 URL 里带着那个等同于 shell 的 token。不识别任何人:不会创建用户画像,也从不调用 identify。src/analytics.ts 很短,全部逻辑都在里面。

桌面版

cd desktop && npm install && npm start

一个包着网页前端的 Electron 窗口。它在进程内启动服务器,所以只需要监管一个进程,而不会留下一个孤儿进程占着端口;它通过 preload 而不是地址栏把 token 交给页面——带 token 的 URL 会出现在历史记录里、窗口标题里,以及每一张 bug 报告的截图里。

Electron 放在 desktop/ 这个独立的包里,这样发布的库就只保留一个运行时依赖。有一个测试来强制这一点。

同步

oharness-sync --port 4483          # serve
oharness-sync token alice          # issue a token, printed once

这是可选的那一半。除非有人启动它,否则这里什么都不会运行:配置里没有 sync 块的 harness 从不打开套接字,本地存储本身就是完整的。它存在的原因是,两台机器要互相传递会话记录,总得有个地方放——而不是因为 harness 需要一个后端。

它有意做得很「笨」。它给不透明的数据块排序再交还回去;它不解析消息,不调用模型,也不知道工具是什么。正因如此,它可以放心地一直运行,消息格式也可以自由改变而无需重新部署。

这里不处理 TLS。把它放在一个终止 HTTPS 的反向代理后面:在不受信任的网络上用明文传输 bearer token,等于把这个 token 交给了这个网络上的任何人。