AB
AiBoss站
project

crab - 通过黑盒观察重建软件行为的洁净室工具

crab 是一个洁净室式行为重建工具:观察代理把目标软件当黑盒探测,产出经过门禁审查的规格,再由洁净实现代理仅凭规格写出自己的实现。本文介绍其维护状态、主要能力、安装入口与许可边界。

crab 是一个面向「行为重建」的开源工具。它要解决的问题是:当你在某个软件里看到一个想要的功能时,如何在不阅读对方实现的前提下,把它重新做出来。据项目自述,crab 让一个被称为 observer(观察者)的代理把目标软件当作黑盒来研究,记录它接受什么、拒绝什么、默认值是什么、在边界上如何表现、界面如何串联;这些观察被转成可证伪的规则与断言,并以「净化后的规格」形式发布。随后另一个被称为 clean implementer(洁净实现者)的代理只看到这份规格,写出自己的实现。它适合需要以行为而非代码为参照来复刻功能的开发者、需要留下审计痕迹的团队,以及希望把「观察」与「实现」在流程上隔离开的工程场景。

维护者与状态

项目仓库为 lemonadesaltbagel/crab,维护者是 lemonadesaltbagel,许可证为 Apache-2.0。仓库创建于 2026-10-22,最后一次提交在 2026-11-14。截至 2026-11-19,项目获得 395 个星标。事实表显示该项目尚无正式 release,因此没有可引用的版本发布记录;素材中提到的 0.4 版本号属于项目自述,读者应以仓库实际状态为准。

据项目说明,crab 在 0.3 之前名为 Teardown,旧的 teardown 命令、TEARDOWN_* 环境变量与已有的 ~/.teardown 目录在本版本中仍然可用,而包名已改为 crab-cleanroom。项目自述也明确表示这是早期软件,并要求使用者在开始分析时声明用途、自行承担法律评估。

主要能力

以下能力均据项目自述整理,未经本站验证。

  • 只观察行为,不接触实现。 项目称 crab 从不采集代码、反编译产物或堆栈跟踪;无法观察到的部分会被显式标记为「未知」,而不是留成静默缺口。
  • 观察与实现分处两个隔离环境。 observer 运行在容器中,通往目标的唯一路径是 crab 的驱动;implementer 运行在只能看到规格的容器中。每一次跨越都经过门禁,并记录在带签名的哈希链审计日志里。项目强调这种隔离是「强制执行」而非「口头约定」。
  • 规则校验与覆盖率清单。 观察者按等价类和边界探测字段,注入故障(服务端错误、网络失败、畸形响应体、不可读文件、飞行模式等),并用自己的话陈述规则;crab 会把每条规则拿到原软件上核对,标记为已证实或已证伪。覆盖率清单列出尚未覆盖的控件、字段、端点与故障组合、数据状态、登录与未登录的每条路由等,未逐项执行或解释前不允许发布。
  • 发布门禁。 发布前会检查是否存在照抄的表达(与所有观察结果及摄入文档做逐字与近似匹配),并把真实名称替换为代号。严格模式下,发现项需要使用者本人在终端记录批准。
  • 洁净实现与验证。 洁净代理依据规格构建,并可请求门禁验证;门禁用同一套测试跑原软件与克隆实现,只返回抽象的通过/失败结论,不返回原文或证据。

在可分析的目标类型上,项目自述的现状是:命令行工具为稳定支持,可观察退出码、标准输出、诊断信息是否存在及 errno 类别、文件副作用,可注入封闭或写满的标准输入输出、不可读文件、只读目录等故障;Web 应用为可用状态,可观察面向用户的 Playwright 定位器与断言能区分的全部差异,以及 API 的方法、路径、状态码与公开契约选择器;Android 应用为可用状态,可观察按角色与名称标识的控件及其状态标志、可见文本与系统对话框,可注入飞行模式;Linux 桌面应用为实验性,基于 AT-SPI 树;macOS、Windows 与 iOS 尚未开始。

项目自述还给出了一组评测结果,例如某个模型未见过的命令行工具在仅有规格的情况下取得 397/397,三个留出的 Web 应用分别为 129/130、126/130、125/127。这些数字来自项目自己的评测说明,本站未做复现,读者应结合其评测文档中的限定条件理解。

使用入口

代码仓库地址:lemonadesaltbagel/crab。PyPI 页面:crab-cleanroom。

据项目说明,安装需要 Python 3.12 及以上,命令名为 crab:

uv tool install "crab-cleanroom[web]"
crab install-browser
crab demo

其中 crab install-browser 为 Web 目标安装 Chromium,crab demo 在内置示例上跑通「观察 → 门禁 → 洁净实现 → 判定」的完整流程。项目称 pip install "crab-cleanroom[web]" 同样可用。针对命令行目标以及强制隔离房间需要 Docker;Android 目标需要 SDK 以及可通过 adb 访问的模拟器或设备。

与代理协作时,项目给出的方式是把 observe 服务注册到支持 MCP 的客户端,例如:

claude mcp add crab-observe -- crab observe --project /path/to/project

之后通过 observe_target 提示词驱动观察流程。发布侧的命令包括 crab review、crab approve、crab release 与 crab export-clean;洁净室侧则通过 crab cleanroom up、crab cleanroom check、crab cleanroom shell 与 crab cleanroom down 管理。

许可与限制

许可证为 Apache-2.0,以仓库中的 LICENSE 文件为准。

据项目说明,使用前需要了解的边界包括:这是早期软件,接口与行为可能变化;使用者必须在分析开始时声明用途,并自行完成法律评估;crab 拒绝绕过目标软件的保护措施,也不采集实现层数据。功能覆盖上,Linux 桌面支持仍属实验性,macOS、Windows 与 iOS 尚未开始,因此跨平台桌面与移动端场景目前并不完整。运行环境方面,命令行目标与强制隔离房间依赖 Docker,Android 依赖 SDK 与模拟器或设备,Web 目标需要 Playwright 的 Chromium。项目自述的评测也显示,面对体量更大的真实应用时结果会明显下降,并存在观察者未能发现的服务器模式与未探索区块,说明规格的完整度直接决定重建质量。