Benchhand

一个为期望工具记住自己工作内容的人而设计的持久、跨平台开发 MCP。

Benchhand 就是当“直到连接闪断之前都还能用”不再是开发中的有趣段子时所发生的事情。

它是一个围绕持久状态、精确变更、进程所有权、恢复以及枯燥而明确的契约构建的开发 MCP 平台。长期目标说起来简单，做起来难：成为一个可靠的 DevSpace 替代品，在实际工作变得严肃时更加可靠、更加可移植、更容易被信任。

没有魔法尘埃。没有覆盖在 shell 脚本上的“AI 驱动”贴纸。没有因为函数恰好没有抛异常而显示的成功消息。

Benchhand 仍处于预 alpha 阶段。基础正在优先构建，因为在用户到来后重建基础是一种学习新脏话的美妙方式。

30 秒简介

Benchhand 旨在为 MCP 客户端提供一个开发控制平面，包括：

• 可跨 MCP 边缘重启而存活的持久工作区；

• 在不触碰脏的主检出（main checkout）的情况下管理 Git 工作树；

• 有界文件读取、列出和搜索操作；

• 带 SHA-256 前置条件的原子写入；

• 确定性变更，遇到歧义时失败而不是猜测；

• 持久的操作状态和崩溃恢复；

• 位于持久本地守护进程之前的无状态 MCP 边缘；

• 一流的 Windows、macOS 和 Linux 语义；

• 未来的持久进程、终端、插件、外部 MCP、工件和 CLI 层。

理念不是“让工具做任何事”。

而是：让工具做强大的事情，但让这些事情的含义精确。

为什么 Benchhand 存在

当一个开发 MCP 忘记工作区、丢失长时间运行的进程、静默应用附近的补丁，或说“成功”却留下一半副作用时，它就变得无趣得多。

Benchhand 将这些视为架构问题，而不是性格特质。

该项目围绕几个固执的想法构建：

1. 传输状态不是应用状态。 MCP 连接可能会消失。你的工作区不应随之失忆。

2. 变更是契约。 如果写入或补丁无法证明其前置条件，它应该带着证据失败，而不是即兴发挥。

3. 恢复是快乐路径的一部分。 重启、陈旧状态、部分副作用、超时和重试是普通的工程条件。

4. 跨平台意味着语义，而不是编译。 “它在 Windows 上构建”不等于“它在 Windows 上意味着相同的事情。”

5. 测试是证据，不是装饰。 内部测试很重要。独立客户端、一致性工具、黑盒检查、审计和故障注入也很重要。

最后一点很重要。由定义行为的同一代码库编写的绿色测试套件是有用的。但它不是品格证明。

当前架构

MCP client
   |
   v
+------------------------+
| Benchhand MCP edge     |   disposable / protocol-facing
+------------------------+
   |
   | OS-local RPC
   v
+------------------------+
| Benchhand daemon       |   durable ownership / orchestration
+------------------------+
   |             |
   |             +--------------------+
   v                                  v
+------------------------+   +------------------------+
| Workspace/filesystem   |   | Operation journal      |
+------------------------+   +------------------------+
   |                                  |
   +----------------+-----------------+
                    v
             +--------------+
             | SQLite state |
             | WAL + FULL   |
             +--------------+

MCP 边缘有意不拥有持久的开发状态。它可以离开并回来。这是一个特性，而不是事故报告。

今天可用功能

当前本地开发线路已具备以下可工作的基础：

重要： “已实现”意味着在当前开发分支上实现，并通过了项目的本地门禁。它不意味着“稳定的公共 API”或“生产就绪发布。”

没有基于氛围的变更

Benchhand 不想在你的源代码树周围耍小聪明。

对于改变状态的操作，预期的契约是：

• 精确的前置条件；

• 适当的地方使用哈希或版本；

• 确定性目标；

• 原子提交点；

• 明确的冲突；

• 无静默回退；

• 无附近行猜测；

• 无模糊的“差不多”补丁；

• 明确说明重放和重试语义，而不是暗示；

• 在操作可重放时提供重复变更保护。

如果 Benchhand 无法证明某个变更正是你要求的那一个，正确的结果不是创造力。

正确的结果是冲突。

没有手铐的安全

Benchhand 是一个开发工具。开发工具需要强大的能力。

因此，安全模型刻意务实：保护工作区边界、所有权、变更完整性、凭据和外部暴露面，而不会把每个有用的操作变成权限仪式。

项目倾向于：

• 精确的目标验证优于全面拒绝；

• 能力边界优于任意功能移除；

• 明确的高权限操作优于隐藏的权限提升；

• 尽可能可逆的操作；

• 拒绝时提供结构化证据。

换句话说：安全带，而不是拒绝离开车库的车。

跨平台是契约

Windows、macOS 和 Linux 是一等的目标。

核心不允许随意假设 Bash、tmux、systemd、launchd、Homebrew、POSIX 信号、Unix 权限、Unix 路径或 Unix PTY。当需要时，它们应属于平台适配器之后。

规则是：

同样的 Benchhand 操作在 Windows、macOS 和 Linux 上应具有相同的含义，或者当平台无法提供所需保证时明确失败。

当前开发证据在 macOS 上最强。Benchhand 不会仅仅因为 TypeScript 在 CI 中编译了三次就称自己为跨平台就绪。平台原生行为必须在声称支持它的平台上进行测试。

测试理念

Benchhand 对行为变更采用测试先行开发。

一个功能不会因为一个快乐路径单元测试通过就被视为完成。相关工作应涵盖失败模式，例如陈旧状态、冲突、并发、超时、守护进程重启、硬崩溃、重试、重放、重复变更、部分副作用、清理失败、路径边缘情况、符号链接/连接点以及平台差异。

在适用的情况下，完成还需要独立证据，例如：

• 官方 MCP SDK 客户端；

• MCP Inspector；

• MCP 一致性工具；

• 黑盒进程测试；

• 依赖审计和漏洞扫描；

• SBOM 生成；

• 许可证检查；

• 平台原生验证。

发布政策故意对“在我的机器上能跑”这句话不友好。

安装

目前还没有公开安装程序。

如果有人告诉你今天运行 npm install -g benchhand，他们要么来自未来，要么想卖你点东西。

Benchhand 将继续留在 0.x 发布线上，直到其公共契约、打包、恢复行为和跨平台门禁赢得一个稳定版本。

对于从源码工作的贡献者：

npm ci
npm run quality

这会验证格式/代码风格规则、严格的 TypeScript 检查和仓库测试套件。运行时打包和最终的 benchhand CLI 是后来的里程碑。

Benchhand 不是

• Git 的替代品；

• 一个戴着 MCP 徽章的终端多路复用器；

• DevSpace 的分支；

• 带有信心问题的模糊补丁引擎；

• 未经审查就信任生成更改的借口；

• 已经完成。

该项目研究现有开发工具、MCP 实现、操作系统和开源库中的有用思想。架构和契约是 Benchhand 自己的。

路线图

公开路线图位于 ROADMAP.md。

简短版本：

路线图顺序：可靠基础 → 文件系统 → 持久运行时 → 结构化 Git → 插件 → 外部 MCP 桥接 → CLI/工件 → UI/网关 → 跨平台打包 → 长期烧机

功能数量不是目标。一个能在故障中存活的小功能，比一个每次重启后都需要励志演讲的大功能更有价值。

贡献

一旦公共仓库开放，欢迎贡献。

在发送代码之前，请阅读 CONTRIBUTING.md。项目重视小而可审查的更改、修复前失败的测试、可复现的错误报告、明确的契约，以及能在作者笔记本之外存活的证据。

如果你的拉取请求包含一个聪明的捷径，那没问题。

如果这个捷径改变了失败时变更的含义，请带上零食来审查。

安全

请不要在公共问题中报告安全漏洞。

有关披露流程和项目当前支持状态，请参阅 SECURITY.md。

许可证

Benchhand 根据 Apache License 2.0 许可。参见 LICENSE。

第三方组件仍受其各自许可证约束。公开发布流程将维护机器检查的依赖和声明清单。

名字的由来

Bench hand 是靠近工作台的人：不是就工作发表主题演讲的人，而是帮助工作真正完成的人。

这就是这里的职位描述。

Benchhand 应该足够有用，能融入工作流；足够可靠，让你不再考虑恢复；足够可预测，以至于当它拒绝做某事时，你确切地理解为什么。

这就是标准。