Scarf：为Hermes AI Agent打造的可视化macOS原生管理平台

1. 项目概述：Scarf，为Hermes AI Agent打造的macOS原生伴侣

如果你和我一样，每天都在和Hermes AI Agent打交道，通过命令行管理会话、查看日志、配置工具，那你一定体会过那种在终端和文件系统之间反复横跳的割裂感。Hermes本身是个强大的多模态AI代理框架，但它的所有状态——会话历史、工具调用、配置、记忆——都散落在~/.hermes/目录下的各种文件里。想要一个全局视角？你得自己写脚本去解析SQLite数据库；想实时监控某个项目的Agent活动？几乎不可能。这种体验上的断层，正是Scarf诞生的初衷。

Scarf是一个用Swift和SwiftUI编写的原生macOS应用，它将自己定位为Hermes AI Agent的“驾驶舱”。简单来说，它把~/.hermes/这个黑盒子彻底打开了，通过一个精心设计的图形界面，让你能看见、管理并交互你所有Hermes代理的一切。从实时聊天、会话历史浏览，到工具配置、多项目管理，再到远程服务器监控，Scarf试图将Hermes生态中所有离散的操作点，整合到一个统一、直观的视觉环境中。它不是一个替代品，而是一个功能倍增器，让你对AI代理的掌控力提升一个维度。

这个项目适合所有Hermes的用户，无论你是刚入门的新手，希望简化配置流程；还是资深开发者，需要管理分布在多台服务器上的复杂Agent集群。Scarf的核心价值在于可视化和集中化，它把命令行工具的强大与图形界面的便捷无缝结合了起来。

2. 核心架构与设计哲学：MVVM-Feature与零外部依赖

打开Scarf的源码目录，你会发现它的结构清晰得令人愉悦。这得益于其严格遵守的MVVM-Feature架构模式，以及近乎“洁癖”般的零外部依赖原则（除了必要的终端模拟器SwiftTerm）。

2.1 模块化功能设计

项目根目录下的Features/文件夹是Scarf的心脏，每一个子目录都是一个自包含的功能模块：

• Dashboard/: 系统健康总览，实时显示Hermes运行状态、Token消耗、成本估算。
• Insights/: 深度数据分析，提供Token分解（包括推理Token）、模型使用统计、活动热力图。
• Sessions/: 完整的会话浏览器，支持全文搜索、重命名、删除和JSONL导出。
• Chat/: 提供两种聊天模式——基于ACP协议的富文本实时流式聊天，以及嵌入SwiftTerm的完整终端模拟。
• Projects/: 项目仪表盘功能的核心，支持自定义JSON定义的可视化组件。
• MCPServers/: 管理Model Context Protocol服务器，支持预设配置和自定义连接。
• Settings/: 将Hermes近60个隐藏配置字段，重新组织成10个逻辑清晰的配置选项卡。

这种设计带来的最大好处是高内聚、低耦合。每个功能模块独立开发、测试和维护，它们通过Core/目录下的共享模型（Models/）和数据服务（Services/）进行通信。例如，Services/SQLiteReader.swift负责以只读方式安全地查询Hermes的state.db数据库，所有需要会话或消息数据的模块都调用它，避免了重复的数据库访问代码和潜在的连接冲突。

2.2 数据访问策略：只读与CLI桥接

Scarf与Hermes交互的核心智慧体现在其数据访问策略上，它巧妙地平衡了实时性、安全性和功能性。

1. 监控类操作：只读直接访问对于需要实时反映状态的数据，如会话列表、消息流、日志，Scarf采用只读方式直接访问Hermes的数据文件。它使用GCD（Grand Central Dispatch）的文件监视器（DispatchSourceFileSystemObject）来监听~/.hermes/目录下的变更。一旦state.db或任何日志文件发生变化，相关的UI视图会自动刷新。这种方式延迟极低，用户体验流畅。

但这里有个关键细节：SQLite数据库是以WAL（Write-Ahead Logging）模式打开的。Hermes作为主进程在持续写入，如果Scarf也以可写方式打开同一个数据库文件，极易造成数据库锁或损坏。Scarf的解决方案是，在打开数据库连接时显式设置SQLITE_OPEN_READONLY标志，并配合PRAGMA query_only = 1;语句，从根源上杜绝了写入的可能。同时，它利用SQLite的.backup命令为远程服务器的数据库创建原子快照，缓存到本地，既保证了数据一致性，又避免了网络延迟对UI响应的影响。

2. 管理类操作：CLI命令桥接对于需要修改Hermes状态的操作，如重命名会话、启用/禁用工具、编辑记忆文件，Scarf绝不直接写文件，而是调用对应的Hermes CLI命令。例如，重命名一个会话，Scarf会在后台执行hermes sessions rename <session_id> <new_name>。这样做有三大好处：

• 安全性：所有修改都经过Hermes自身的验证逻辑，避免了因Scarf的解析错误导致配置损坏。
• 一致性：确保了通过Scarf执行的操作，与在终端中手动执行hermes命令的效果完全一致。
• 同步性：Hermes处理完命令后会更新其状态文件，Scarf的文件监视器能立刻捕捉到这一变化，从而更新UI，形成一个完美的闭环。

这种“监控用只读，管理走CLI”的双通道设计，是Scarf既强大又稳定的基石。

注意：正因为Scarf需要直接读取~/.hermes/和派生hermes子进程，它无法启用macOS的App Sandbox（应用沙盒）。这意味着你不能通过Mac App Store分发它。开发者选择了使用Developer ID证书签名并公证（Notarization），然后通过GitHub Releases分发，这是此类需要深度系统集成的工具类应用的典型做法。

3. 核心功能深度解析与实操要点

Scarf的功能列表看起来很长，但我们可以将其归纳为四大核心能力：监控、交互、配置和管理。下面我们挑几个最具特色和实操难点的功能深入聊聊。

3.1 项目仪表盘：将AI工作流可视化

这是Scarf区别于其他简单GUI工具的王牌功能。它允许你为任何项目（一个代码库、一个数据文件夹、一个研究课题）创建一个自定义的仪表盘。其本质是一个由JSON驱动的动态渲染引擎。

实操要点：如何让Agent自动维护仪表盘仪表盘的核心文件是项目根目录下的.scarf/dashboard.json。手动创建和维护它太麻烦，真正的威力在于让Hermes Agent来干这件事。你需要在给Agent的指令中明确以下几点：

1. 分析目标：告诉Agent分析当前项目的哪些方面（如测试覆盖率、待办事项、部署状态、数据质量指标）。
2. 输出格式：明确要求其生成或更新.scarf/dashboard.json文件，并遵循Scarf的Schema。
3. 注册项目：指示Agent将项目路径添加到Scarf的中央注册表~/.hermes/scarf/projects.json中，这样项目才会出现在Scarf的侧边栏。

一个高级技巧是利用Hermes的Cron（定时任务）功能。你可以设置一个每天运行的Cron作业，其任务就是“分析项目状态并更新Scarf仪表盘”。这样，你的项目仪表盘就能实现无人值守的自动更新，成为真正意义上的实时项目状态看板。

Webview Widget的妙用在众多Widget类型中，webview是最具扩展性的一个。它允许你在Scarf内部嵌入一个完整的网页视图。你可以用它来：

• 显示本地开发服务器（如http://localhost:3000）的实时页面。
• 嵌入由Agent生成的HTML格式的数据报告。
• 连接到你为项目搭建的Grafana或Metabase监控面板。 当仪表盘包含webview时，Scarf会自动在顶部添加一个“Site”标签页。点击后，该网页内容将以全画布模式呈现，充分利用整个应用窗口的空间，体验堪比一个独立的浏览器标签页，但上下文却牢牢锁定在你的项目中。

3.2 远程服务器管理：跨越SSH的透明操作

Scarf 2.0引入的多服务器支持，让它从一个本地管理工具升级为了一个轻量级的Agent集群管理平台。其实现原理非常巧妙。

连接原理与数据同步当你添加一个远程服务器（如ssh user@remote-server）时，Scarf并没有在远程安装任何守护进程或服务。它完全依靠系统的SSH和SFTP协议来完成所有操作：

• 文件操作：通过scp/sftp读写远程~/.hermes/目录下的文件（如config.yaml,memories/*.md）。
• 数据库读取：通过ssh远程执行sqlite3 .backup命令，将远程的state.db数据库备份为一个快照文件，然后通过SFTP拉取到本地缓存目录（~/Library/Caches/scarf/snapshots/）。后续的查询都针对这个本地快照进行，定期更新。
• 实时聊天（ACP）：通过ssh -T启动一个交互式SSH会话，并在该会话中执行hermes acp命令。这样，ACP的JSON-RPC协议就通过SSH的stdio通道在本地Scarf和远程Hermes之间建立了隧道。
• 管理命令：所有hermesCLI命令（如hermes gateway restart）都通过SSH在远程执行。

避坑指南：远程连接故障排查远程连接最常见的问题是“连接成功，但看不到数据”。这通常是因为SSH用户对Hermes的数据目录没有读取权限。Scarf提供了一个极其有用的“运行诊断”功能（在服务器管理界面或工具栏的黄色警告胶囊中）。 这个诊断工具会在一次SSH会话中连续执行14项检查，并给出明确的失败原因和修复建议。例如：

• 检查 3/14: 在远程路径找到 sqlite3 ... 通过
• 检查 7/14: 读取 config.yaml ... 失败 - 权限被拒绝 (errno 13)
• 建议：Hermes可能由其他用户（如‘hermes’）运行。请尝试：1. 使用该用户SSH登录。2. 或将Hermes目录的组权限设置为可读，并将您的用户加入该组。

务必善用这个诊断工具，它能节省大量猜测和手动调试的时间。

3.3 工具网关与模型选择器：解锁Hermes v0.10+的全能力

从Hermes v0.10.0开始，引入了“工具网关”的概念，将Web搜索、图像生成、TTS等能力通过订阅路由到不同的提供商。Scarf 2.3完美地集成了这一特性。

模型选择器的进化之前的模型选择器可能只显示几个主流模型。现在，它背后集成了来自models.dev的缓存，囊括了111个提供商的所有主要模型。更重要的是，它将Hermes配置中“工具网关”的提供商覆盖表合并了进来。这意味着，像Nous Portal这样的提供商，以及另外5个以前在GUI中不可见的提供商，现在都会直接出现在模型选择下拉列表中。

Nous Portal的免终端登录对于Nous Portal这类使用设备码流程进行OAuth认证的提供商，Scarf 2.3提供了一个革命性的改进：应用内一键登录。你不再需要打开终端，复制设备码，再打开浏览器。Scarf现在有一个专门的“登录到 Nous Portal”表单，它会在应用内自动完成整个设备码流程——显示代码、等待你在浏览器中授权、获取令牌并安全存储。这彻底消除了凭证配置中最令人头疼的环节之一。

每个子任务独立控制在“设置” -> “辅助模型”中，你会发现8个辅助子模型任务（如文本嵌入、图像理解等）现在都各自有一个独立的“Nous Portal”开关。这意味着你可以精细地控制哪个任务使用Nous Portal的服务，哪个任务使用其他备用提供商或本地模型。

4. 从安装到精通：完整实操流程

4.1 安装与初次配置

方案一：直接下载（推荐）对于绝大多数用户，从GitHub Releases页面下载预编译的通用版本（Scarf-vX.X.X-Universal.zip）是最佳选择。下载后，将Scarf.app拖入“应用程序”文件夹即可。应用已通过苹果的公证（Notarization），首次打开时不会遇到安全拦截。

方案二：从源码构建如果你需要修改代码或处于网络受限环境，可以从源码构建：

git clone https://github.com/awizemann/scarf.git cd scarf/scarf # 使用Xcode打开 open scarf.xcodeproj # 或使用命令行构建通用版本 xcodebuild -project scarf.xcodeproj -scheme scarf -configuration Release -arch arm64 -arch x86_64 ONLY_ACTIVE_ARCH=NO build

构建产物位于DerivedData/scarf-xxxx/Build/Products/Release/目录下。

首次运行与本地Hermes连接首次启动Scarf，它会自动尝试连接本地的Hermes实例（位于~/.hermes/）。请确保：

1. Hermes已安装且版本在v0.6.0以上（v0.9.0+以获得完整体验）。
2. Hermes的网关可能正在运行。如果Scarf侧边栏的“仪表盘”显示“已停止”，你可以尝试在Scarf内点击“启动网关”，或者先在终端运行hermes gateway start。

4.2 核心工作流演练

工作流一：监控与洞察

1. 总览：打开Scarf，默认进入“仪表盘”视图。这里一眼就能看到Hermes的运行状态、今日/本周的Token消耗和估算成本。
2. 深度分析：点击侧边栏的“洞察”。在这里，你可以按时间范围（7/30/90天）筛选，查看Token的详细分解（特别注意“推理Token”的占比，这能帮你优化提示词成本），以及最常使用的工具和模型。
3. 会话审计：进入“会话浏览器”。使用顶部的搜索框进行全文搜索，例如搜索“bug”来查找所有讨论过bug的对话。你可以右键点击任何会话进行重命名、删除或导出为JSONL格式，便于后续分析。

工作流二：交互与创作

1. 富文本聊天：在“聊天”标签页，选择“富文本聊天”模式。这是一个类似iMessage的界面，支持Markdown渲染、工具调用可视化。当你输入/时，会弹出所有Agent已注册的命令以及你在config.yaml中定义的quick_commands。
2. 终端模式：如果你需要与Hermes进行更原始的、支持复杂行编辑的交互，切换到“终端”模式。这是一个功能完整的终端模拟器，运行着hermes chat命令，支持所有ANSI颜色和Rich库的格式化输出。
3. 记忆编辑：在“记忆”视图中，你可以直接查看和编辑MEMORY.md和USER.md。Scarf会监听文件变化，如果你在外部编辑器（如VSCode）中修改了这些文件，Scarf的视图会实时更新。

工作流三：配置与管理

1. 平台配置：这是Scarf 1.6版本最大的亮点之一。以前配置Telegram、Discord等平台需要手动编辑.env和config.yaml，现在只需在“平台”视图中填写表单。对于WhatsApp/Signal等需要配对的应用，Scarf甚至内置了一个终端来显示二维码和处理signal-cli守护进程。
2. MCP服务器管理：在“MCP服务器”中，你可以从预设列表（GitHub, Linear, Notion等）快速添加服务器，或完全自定义。添加后，使用“测试连接”功能，Scarf会运行hermes mcp test并列出该服务器提供的所有工具，确保配置正确。
3. 凭证池管理：在“凭证池”中管理不同模型提供商的API密钥。Scarf的UI只显示密钥的后四位，完整的密钥安全地存储在系统钥匙串（Keychain）或Hermes的配置中。你可以设置轮询策略（如fill_first,round_robin）。

4.3 项目模板的创建与分享

Scarf 2.2引入了项目模板（.scarftemplate），这是一个将项目配置、仪表盘、技能等打包分发的强大功能。

创建模板的步骤：

1. 准备项目：确保你的项目有一个定义好的.scarf/dashboard.json，以及任何你希望包含的Agent指令、技能文件。
2. 定义配置模式：在模板的manifest.json中，使用七种字段类型（string,text,number,bool,enum,list,secret）来声明配置项。secret类型的值会被安全地存入安装者的macOS钥匙串。
3. 包含AGENTS.md：这是关键。模板必须包含一个遵循agents.md标准的AGENTS.md文件。这确保了你的项目指令不仅能被Hermes理解，还能被Claude Code、Cursor、Aider等20多种其他原生支持此标准的AI编码助手读取，极大提升了模板的通用性。
4. 打包与测试：使用Scarf的“导出为模板”功能，或手动按照目录结构打包。然后通过“从文件安装”来测试安装流程是否顺畅。

分享模板：你可以将模板提交到Scarf的公共目录（通过向GitHub仓库的templates/目录提交PR），这样其他用户就可以在 https://awizemann.github.io/scarf/templates/ 浏览并一键安装你的模板。网站上的CI会自动验证模板的合法性。

5. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些典型问题。以下是我在长期使用中总结的排查清单。

5.1 连接与数据问题

5.2 功能与配置问题

5.3 性能与体验问题

问题：Scarf应用本身感觉卡顿，特别是打开大型会话历史时。排查：Scarf的会话浏览器会渲染所有消息内容。如果你有成千上万条会话记录，一次性加载所有可能会影响性能。解决：

1. 利用“洞察”页面的时间过滤功能，先聚焦近期数据。
2. 考虑定期归档或删除非常旧的、不重要的会话（可通过会话浏览器批量操作）。
3. 确保你的state.db数据库已经过优化（Hermes会自动维护）。在极端情况下，可以尝试在Hermes中运行VACUUM;命令（需先停止Hermes），但这通常不是必须的。

问题：远程服务器的仪表盘数据更新有延迟。排查：这是预期行为。为了性能和减少网络负载，Scarf不会实时同步远程数据库。它定期（默认为30秒）创建远程DB的快照并缓存到本地。解决：在远程服务器的Scarf窗口，点击仪表盘右上角的“刷新”按钮，可以手动触发一次快照更新。如果延迟不可接受，可以考虑在本地运行Hermes，或者接受监控数据非完全实时的事实。

问题：Webview Widget无法加载本地file://URL或某些HTTPS网站。排查：出于安全考虑，macOS的WKWebView对本地文件访问和混合内容有严格限制。解决：

• 对于本地文件，最好通过一个简单的本地HTTP服务器（如Python的python -m http.server）提供服务，然后使用http://localhost:8000/your-report.html这样的URL。
• 对于HTTPS网站，确保网站证书有效。对于自签名证书，Scarf可能无法直接加载，这是平台限制。

从我个人的使用经验来看，Scarf最强大的地方在于它把“可观察性”（Observability）带给了AI Agent工作流。以前，Agent在后台做了什么、消耗了多少资源、处于什么状态，都是一团迷雾。现在，通过Scarf的仪表盘、洞察和实时日志，这一切都变得清晰可见。它不仅仅是一个GUI外壳，更是一个AI工作流的集成管理平台。尤其是项目模板和远程管理功能，为团队协作和复杂部署场景打开了新的可能性。如果你正在严肃地使用Hermes进行开发或自动化，Scarf几乎是不可或缺的效率工具。它的设计哲学——深度集成、只读监控、CLI桥接管理——值得所有同类工具借鉴。