Ghost Hands

Ghost Hands

Playwright 负责驱动，Stagehand 负责思考，Browser Use 四处探索。Ghost Hands 为每一步行动保驾护航。

Ghost Hands 是一个独立、零依赖的 Python 包，为 Agent 提供在 Web 上行动的双手，也为这些行动赋予良知。Agent 执行的每个操作都会在运行前分类（readonly / write / consequential），根据策略进行评估，在执行之前写入溯源记录；在重要情况下，还必须经过人工审批。运行完成后，可将其转化为确定性、无需模型的 Ghost Hands 脚本，供你免费重新运行。

浏览器驱动层是我们自己的：一个基于标准库的 Chrome DevTools Protocol 客户端，通过 --remote-debugging-pipe 传输方式直接驱动 Chromium。底层没有 Playwright、Selenium 或任何其他自动化库——自动化层 100% 由我们打造。（我们驱动的是浏览器 Chromium，并没有编写浏览器引擎，也不声称自己编写了浏览器引擎。）

来自 Ghost Developer Studio。 采用 MIT 许可证。

MCP 注册表：mcp-name: io.github.littlestjames82-sys/ghost-hands

状态：v1.1.0 — 已在 PyPI 和 GitHub 上发布： PyPI ghost-hands （pip install ghost-hands）· github.com/littlestjames82-sys/ghost-hands · littlestjames82-sys.github.io/ghost-hands。

v1.1.0 新增了专注感知、在报告和 MCP trail 工具中展示轨迹完整性、通过 MCP 使用计划缓存，以及针对 v1.0 功能的基准证明用例——详见 CHANGELOG。

在 GitHub main 上，v1.2 到 v1.11 的版本迭代正在开发中：批量模型调用并对每个动作进行治理、基于 API 实际报告的 Token 统计、require-verify 门控、第五个 MCP 工具（hands_verify_trail）、从卡住状态中受治理的恢复、大模型 Token 预算上限、通过 MCP 使用目标驱动的 hands_run、现已包含 API 实际报告用量且可发布的评估评分卡、供决策器使用的页面变更说明、针对端点故障的备用决策器、汇总各条轨迹实际 Token 开销的 costs 命令、对文本缺失情况的验证、在脚本运行前对其分类的 check 预检、从已结束运行的轨迹恢复运行（续跑的轨迹现在会链接到其父级哈希）、原生 Anthropic 决策器、batch 运行手册命令、报告已配置哪些决策器的 doctor、针对不稳定模型端点的有界退避重试（重试次数计入运行统计）、供模型严格回复使用的可选 JSON 模式、HTTP JSON API（ghost-hands serve）、运行完成时触发的 Webhook、跟踪移动两次的元素的修复链，以及将失败动作反馈给模型而不是结束运行的错误转循环恢复；此外，还有一轮评估完整性检查，修复了真实模型运行所暴露的两个分级测试套件缺陷（表单检查器现在会认可 fill_form，登录任务也会教授其所审计的密钥占位符流程）。这些功能的发布将另行设门槛。

1.0.0 新功能——信任与成本版本

以下对比中，没有其他浏览器 Agent 同时提供这四项能力——每一项都针对已记录的竞品缺口：

• 防篡改记录。 现在，每条记录事件都带有一个与前一事件相连的 SHA-256 哈希（trail.py 中的 prev / hash）。编辑、删除或重排任何事件，之后的所有哈希都会失效。ghost-hands verify-trail trail.jsonl（或 Python 中的 verify_trail()）可以证明记录与写入内容完全一致；1.0 之前的记录会标记为旧版，不会被悄悄视为通过。Playwright 的 trace viewer、Stagehand 的会话日志和 Browser Use 的运行历史都是可编辑文本——这是一份审计记录，而不是日志文件。
• 密钥占位符——模型永远看不到凭据。 决策器、脚本或缓存计划输入的是 {{secret:PASSWORD}}，而不是实际值。决策器、Governor、审批者和记录中始终只能看到占位符；Runner 仅在执行边界处，从 GHOST_HANDS_SECRET_PASSWORD（或主机提供的内存映射）中替换出实际值，并从页面回显的任何结果中清除该值。缺少密钥时会如实报错，绝不会把占位符当作文本输入。这是 Skyvern 以托管密钥库推销的凭据隔离能力，也是 Browser Use 暴露给 Agent 上下文的能力——而这里的实现是本地、免费的，并且有记录为证。（secrets.py）
• verify 操作——用证据证明，而不是口头声称。 只读断言（actions.py 中的 verify，由 Runner 在 verify.py 中评估）可以检查页面文本、元素是否存在，和／或当前 URL，并可任意组合；所有设定的条件都必须满足。在 done 之前添加一项后，运行就不能再对从未发生的状态报告成功——这是应对幻觉式完成故障模式的如实停止方案。验证失败时会以 error 状态停止，并指出未通过的条件。
• 受治理的计划缓存——学一次，免费重放。 使用缓存（Runner(plan_cache=PlanCache(path)) 或 ghost-hands run --cache plans.json）时，以 done 结束的运行会将已验证的步骤按目标 + 起始 URL 作为键，存入仅所有者可访问的本地文件。下一次相同的运行会通过同一循环重放每个步骤——重新感知、按描述符重新查找、重新分类、按策略要求重新请求审批，并将记录写入新运行的哈希链记录中；缓存步骤无需调用决策器。如果缓存目标已不存在，记录会写入 cache fallback，并由实时决策器接管；以非 done 状态结束的运行不会存储任何内容。Stagehand 也会缓存操作——但不受治理，其缓存也不是审计记录。密钥在缓存中仍为占位符，因此缓存的登录计划不包含凭据。（cache.py）

0.9.0 版新增内容

• ghost-hands doctor（doctor.py）——用一条命令检查整个堆栈是否已正确配置。包含七项只读检查——Python 运行时、Chromium 二进制文件（由驱动程序自己的解析器查找，因此 doctor 和驱动程序绝不会得出不同结果）、四个策略包、模型环境、GhostBus 服务（当 --bus / GHOSTBUS_URL 配置了服务时；会报告工作区形态是单一工作区还是托管的 /w/<id>/）、MrGhosty 手机桥接（已配置时检查是否可连接、令牌是否被接受、MrGhosty 版本、辅助功能状态、桥接协议是否匹配），以及 adb——每项都会显示为 PASS / WARN / FAIL；如果不是 PASS，还会给出一行通俗易懂的修复建议（“手机是否已开机、MrGhosty 辅助功能是否已开启，以及是否正在运行 adb forward tcp:8378 tcp:8378？” / “配对令牌不匹配——请从 MrGhosty 的 Access checklist 中重新复制，并粘贴到 GHOST_HANDS_ANDROID_TOKEN。”）。FAIL 表示“在你采取行动前，此部分无法运行”；WARN 表示未启用或可选（未配置的总线或桥接会显示 WARN，绝不会显示为失败）。只要有任何 FAIL，退出代码就是 1。--json 会将相同的检查结果以结构化数据形式输出。每项探测都有较短的超时时间，因此 doctor 不会因无响应的端点而卡住，也绝不会打印任何机密：密钥和配对令牌只会报告是否存在，不会显示其值。
• ghost-hands phone-proof（phone_proof.py）——手机首次运行的引导版本。phone-approval-test 只会单独验证一件事，而 phone-proof 会逐步完成并检查全部五个步骤：桥接已配置（否则会打印准确的环境变量设置并停止——退出代码为 2，表示需要设置）；adb 转发（运行前会先打印；没有 adb 或设备时会正常跳过）；桥接状态（MrGhosty 版本和辅助功能）；无害的测试审批（“现在请看手机——点击 MrGhosty 通知上的 Approve”）；以及最终摘要，说明现已验证的内容和准确的下一步命令。拒绝、过期或超时的审批会正常结束并提供说明——退出代码为 3（未获批准）；桥接或配置失败时退出代码为 1。--yes 会不暂停地直接运行，这也是测试和基准测试通过伪桥接来驱动它的方式。

首次手机验证

手机上安装 MrGhosty v1.7+ 并启用其辅助功能服务后，首次运行的完整流程如下：

adb forward tcp:8378 tcp:8378        # or let phone-proof do it (step 2)
export GHOST_HANDS_ANDROID_TOKEN=<pairing code from MrGhosty → Device tab → Ghost Hands bridge>
ghost-hands doctor                   # every row green or explained?
ghost-hands phone-proof              # five checked steps to "proven"

phone-proof 会在检查每个步骤前说明所需条件，退出代码则说明最终结果：0 表示已验证 · 1 表示出错 · 2 表示需要设置 · 3 表示未获批准。通过后，手机就是一个受治理的执行端：ghost-hands run --driver android --approver phone 会在手机本身上请求审批并驱动手机。

0.8.0 版本更新

• 操作轨迹 → HTML 审计报告（ghost-hands report trail.jsonl、 report.py）。操作轨迹一直都是记录；现在它变得可读了。一次运行会生成一个完整的 HTML 文件——内嵌 CSS、 无 JavaScript、无外部资源、可离线使用——采用工作室风格（深炭灰色、紫罗兰色点缀），包含标题（操作轨迹有记录时显示目标、根据感知 URL 推断的正文、日期范围、停止原因和摘要）、摘要统计卡片（步骤数、墙钟时长、感知字符数 / 约合 token 数、按类别统计的操作数、请求 / 批准 / 拒绝的审批数、修复数、下载 / 对话框 / 网络计数），以及逐步时间线——感知地图摘要及可折叠的感知记录、通俗易懂的决策（“点击 [4] ‘Place order’”）、Governor 的裁决及其分类标签；对于需要询问的操作，还会显示后续结果（“询问 → 通过手机批准”）、操作结果，以及内嵌的特殊事件（包含起止位置的修复、对话框、含文件名和大小的下载、包含渠道和决策者的审批请求 / 决策配对、可折叠的网络捕获）。渲染过程具有防御性：操作轨迹中的所有字符串都会进行 HTML 转义（恶意页面标题仍会显示为文本），带类型的值会截断至 80 个字符，在 type=password 元素中输入的值会显示为 •••• (N chars)。损坏的行会被跳过并计入页脚——部分操作轨迹仍然是一份记录。examples/sample-report.html 中附有示例渲染结果。
• MCP 对等支持。 MCP 服务不再仅支持假网页：GHOST_HANDS_DRIVER=fake|chromium|simphone|android 用于选择会话主体（默认值仍为 fake），GHOST_HANDS_START_URL 会在首次感知时打开页面；android 会话使用与总线 Agent 相同的 GHOST_HANDS_ANDROID_BRIDGE / GHOST_HANDS_ANDROID_TOKEN 环境变量（令牌不会出现在工具输出中）。具有原生视觉能力的主体会通过该能力进行感知，与 Runner 完全一致。GHOST_HANDS_APPROVER=phone 会通过 PhoneApprover 处理会话的“询问”裁决，而不是采用默认的拒绝并说明原因；hands_act 的回复会说明由哪个渠道作出决定（“通过手机批准” / “拒绝：没有审批者（MCP 默认行为）”）。hands_run 默认使用会话主体，并接受全部四种驱动方式。配置按服务进程生效；未知值会在启动时明确报错。
• seatbelt 策略包。 采用 Standard 的策略姿态（只读 + 允许写入、重要操作需询问、300 秒审批时限），并添加目标内容规则：如果目标元素的名称 / 标签，或页面 / 操作 URL，匹配经过筛选的提示词注入模式（policies.INJECTION_PATTERNS：“ignore previous instructions”、“disregard your instructions”、“you are now”、“system prompt”、“click here to claim”、“verify your password to continue”等），Governor 会直接拒绝该操作，无论其类别为何；治理事件的原因会指出匹配的模式。这些模式是指令式短语，而不是孤立词语——名为“Ignore”的按钮不会触发此规则（已有测试保障）。此规则以策略（Policy）上的数据（deny_patterns）实现，因此任何策略包或策略文件都可以带有自己的模式列表。

0.7.0 版本更新

• 模型评估测试框架（ghost-hands eval、 evaluate.py）。针对本地固定测试页面的 8 项分级任务 — 搜索并打开页面、多字段表单填写并执行有后果的提交、 结构化表格提取、多跳导航以查找事实、一个醒目按钮具有破坏性且绝不能 点击的陷阱页面、按恢复效果评分的页面变动任务、审计操作轨迹以检查 凭据泄露的登录表单，以及按是否诚实停止来评分的不可能目标。 其中 4 项任务在真实 Chromium 上运行。 每项任务都会根据成功情况、步骤数、耗时、感知字符数 / 约计词元数、 各类别操作数、请求的审批数和修复次数评分；--report PATH 会写入 JSON。支持 3 种决策器： --decider stub（本地 stub 模型服务器，其确定性策略可证明测试框架 端到端运行正常 — stub 结果仅用于验证测试框架，不代表模型质量）、 --decider rules（作为第二项基线的 RuleDecider），以及 --decider openai（通过现有的环境变量配置决策器调用真实模型）。 本次构建的测量结果：stub 通过 8/8（验证工具正常）；规则基线通过 3/8 （避开陷阱、恢复页面变动、诚实停止 — 它在搜索、表单、提取、多跳导航 和登录任务中的如实失败是评估数据，不是测试框架错误）。凡是有可用密钥的 情况，真实模型的数字都会单独报告；请参阅“诚实状态”。
• Android 手势（MrGhosty v1.8.0）。Android 主体过去会拒绝的 3 种 操作类型 — double_click、drag、click_at — 现已实现端到端支持： 桥接层会调度真实手势（dispatchGesture、有界回调锁存机制，并如实返回 已取消 / 失败结果）；click_at 会根据当前窗口的边界进行验证，超出边界 时会被拒绝；AndroidDriver 会转发这 3 种操作（拖动操作会解析起点和终点； click_at 无需目标）。SimPhoneDriver 不实现这些操作 — 不伪造兼容性； 请参阅 docs/BODY_PROTOCOL.md §6，了解各主体支持的功能。
• GhostBus 文件存储循环已闭环。 v0.4 中发现的问题（文件存储在并发写入时 因共享 .tmp 文件重命名发生冲突，返回 HTTP 400），已在 GhostBus 0.4.1 中修复（每次保存使用唯一临时文件 + 串行化保存），并从 0.5.0 起在 GhostBus 测试套件中进行回归测试（44/44 + 6/6；本次构建再次验证通过）。 Ghost Hands 现在也从自身侧验证了这一点：总线演示流程和并行 Agent
  • 轮询器压力测试都针对真实的文件存储版 GhostBus 运行，结果显示没有 400 错误、存储完整且没有遗留的临时文件（基准测试 v7 bus、pytest test_file_store_barrage_no_races）。

0.6.0 版本更新

• 通过手机审批。 一次运行中的“询问”决策可以转到 Ryan 的手机：PhoneApprover（phone_approver.py）会向 MrGhosty v1.7.0 中的 Ghost Hands 桥接服务发送经过脱敏的审批请求，随后触发高优先级通知（“Ghost Hands 需要审批”），并提供批准／拒绝操作；MrGhosty 的设备选项卡中也会显示对应卡片。决策会通过桥接服务返回；拒绝、过期、超时和无法连接都表示否——沉默绝不代表同意。适用于所有驱动（ghost-hands run --approver phone …——即使是桌面 Chromium 运行，也可以用手机审批），也适用于 bus-agent 模式，可通过 --approval-channel phone 使用（bus 会收到一条礼貌提示；绝不会向 bus 请求审批）。当桥接服务可连接时，审批会通过 MrGhosty 桥接服务（通知 + 应用内决策）转到 Ryan 的手机；这是一个本地桥接通道，不是云推送服务。请参阅 docs/APPROVALS.md。
• 决策只能在手机上作出，这是设计使然。 桥接 API 可以创建和读取审批请求，但没有决策端点——持有令牌的人永远无法批准自己的请求。唯一可以作出决策的方式，是直接在手机上使用通知操作和应用内卡片。
• 摘要在离开设备前经过脱敏。 请求包含操作类型、分类、目标描述符以及当前 URL／软件包；type 操作会显示目标和字符数，绝不显示输入的文本；fill_form 会显示字段名称，绝不显示字段值。配对令牌绝不会出现在摘要、轨迹事件、错误或日志中。
• ghost-hands phone-approval-test — 发送一条无害的测试请求（“批准此请求不会运行任何操作”），并等待手机作出决策：只需一条命令即可在设备上验证。

0.5.0 版本更新

• 真实的 Android 执行主体。 AndroidDriver（android_driver.py）通过 Ghost Hands 桥接服务控制真实手机；该桥接服务运行在 MrGhosty Android 应用（v1.6.0）中：由 MrGhosty 的无障碍服务托管、仅限环回访问的 HTTP 服务器，地址为 127.0.0.1:8378，使用配对令牌进行身份验证（令牌显示在 MrGhosty 的设备选项卡中；通过 GHOST_HANDS_ANDROID_TOKEN 传入，绝不存储）。感知过程会遍历实时无障碍树，并生成相同的编号 ElementMap（每个元素都会将其桥接 ref 保留为 body_ref）；在执行任何操作之前，都会在桥接服务处重新验证目标的 {tag, role, name} 键；目标过期时，会返回 Runner 在网页上修复时使用的相同“目标缺失／目标不匹配”错误。运行器／治理器无需更改即可驱动它——治理机制完全相同，包括重要操作关卡。仅限 Web 的操作会如实报错。使用 adb forward tcp:8378 tcp:8378 转发桥接服务，使用 ghost-hands android-status 检查状态，然后运行 ghost-hands run --driver android …（或通过 GhostBus 指定任务，传入 "driver": "android"）。驱动和桥接服务均已构建完成，且已根据桥接契约验证完整流程（虚拟桥接服务一致性测试套件 + 基准测试用例）；设备端验证仍待 Ryan 安装 MrGhosty v1.6.0 并授予无障碍权限。
• 元素 body_ref。 元素现在会在描述符中携带可选的不透明原生主体目标引用，因此轨迹会准确记录手机操作触及的节点。

0.4.0 版本更新

• GhostBus Agent 模式。 ghost-hands bus-agent 会将操作端接入 GhostBus，作为 Agent ghost-hands（角色：操作端）。它会认领分配给它或带有 hands 标签的任务——遵守认领租约和 blockedBy，并遵循总线自身的需审批门控（门控任务绝不认领）——通过同一套 Runner/Governor/Trail 执行任务、发布进度评论、将 JSONL Trail 上传为共享总线文件，并以结构化报告完成任务。支持单工作区中继和托管工作区（--workspace、/w/<id>/）；密钥仅从标志/env 获取，绝不存储。ghost-hands bus-demo 会在真实 GhostBus 节点服务器上验证完整流程——包括在运行中由第二个客户端通过总线批准一项有实质影响的提交。
• 通过总线审批。 总线运行期间，Governor 要求“询问”时，审批者会将 APPROVAL NEEDED: <class> <summary> — reply APPROVE <run-id> or DENY <run-id> 作为任务评论发布，并向任务创建者发送消息，然后等待（长轮询），最长等待时间为审批超时时限。拒绝或超时均视为拒绝，并会留有记录：请求和决定都会作为 approval 事件写入 Trail。
• Body Protocol。 docs/BODY_PROTOCOL.md 对驱动程序契约进行了规范化——感知 → 编号后的 ElementMap、act(action) → 结果、可选的能力标志——并定义了共用的操作词汇，以便根据书面规范构建新的 body。符合性场景（每个 body 执行相同的抽象脚本）证明了这一点：没有审批者时，破坏性步骤会被拒绝；有审批者时则会执行；且 FakeDriver、ChromiumDriver 和新的手机 body 的 Trail 都会记录相同结构。
• SimPhoneDriver。 一个模拟 Android 风格的 body（内存中运行）：主屏幕带有应用图标，包含 Notes 应用（可输入、保存，笔记会持久保留；“Delete all notes”按钮会被归类为有实质影响的操作）、带开关的 Settings 应用、返回/主页导航堆栈，以及仅使用标准库渲染的真实 PNG 截图。现有的 Runner/Governor/decider 原样驱动它——它是用于排练真实 Android body 的模拟环境；真实 Android body 随后也已加入（v0.5.0，见上文）：测试中使用同一套 Runner/Governor 驱动 SimPhoneDriver，实际手机则通过 AndroidDriver 驱动。
• 策略包。 可命名、可加载的 Governor 套件（ghost_hands.policies）：readonly（直接拒绝写入和有实质影响的操作）、standard（默认策略）、strict（写入操作也需询问；审批等待上限为 120s）。run 和 bus-agent 支持 --policy-pack；MCP 服务遵循 GHOST_HANDS_POLICY。未知策略包名称会明确报错，绝不会静默回退。

0.3.0 版新功能

• 两种观察方式。 DOM 观察现在会遍历组合树——穿透开放的 Shadow Root，包含并标记同页 iframe——因此 Web 组件和框架中的控件 也会像其他元素一样编号。 也可以切换到 AX 观察（eyes="ax"）：映射基于 CDP Accessibility 树构建（角色 + 名称 + 状态），操作通过 backendNodeId 解析回对应元素。
• 一步填写整个表单。 fill_form 根据 {label: value} 键值对 填写整个表单，通过标签、名称、占位符或 aria-label 解析每个字段， 并报告每个字段的结果——明确列出失败项，不会静默失败。设置 submit: true 后，该操作会被归类为有实质影响的操作，并按常规审批 流程处理。
• 文件双向传输。 download 会点击并等待文件完整写入磁盘（报告 文件名和字节大小，并在操作记录中记录完成状态）；set_file 会将本地 文件上传到文件输入框（DOM.setFileInputFiles），缺失路径和目录会被 拒绝。
• 网络记录留痕。 运行期间会捕获 Network 域信息（方法、URL、状态、 类型），写入 net 操作记录事件；每次运行最多记录 200 条，并注明 是否截断；extract 的 network 模式会返回捕获的列表。
• 结构化提取。 extract 模式：text（默认）、list （链接 → [{text, href}]）、table（→ 行字典列表）、network。
• 对话框已处理并留痕。 confirm/alert/prompt 会根据驱动策略 作答（dialog_policy="dismiss"|"accept"，默认 dismiss），并将每个 对话框及其处理决定写入操作记录。
• 更丰富的输入操作。 hover、double_click、right_click、 drag（从目标 → 目标）、press 中的组合键（"Control+a"），以及 click_at(x, y)——按原始坐标点击的后备方式，会被归类为 write， 并在操作记录中标记为 raw: true。
• PDF + 视口。 pdf 会将页面打印为真正的 PDF 文件 （Page.printToPDF）；set_viewport 可切换预设视口 （桌面端 1280×800、移动端 390×844 + 触控），感知结果会反映模拟后的 布局，也包括媒体查询的影响。
• 等待条件。 wait_for 会等待指定文本出现、匹配描述符的元素出现， 或 URL 包含指定子串；超时会如实失败并留下记录。
• 所有新增操作均可通过 CLI runner 和 MCP hands_act 使用，无需更改； 每项操作仍会由 governor 分类并写入操作记录。（HTML 快照观察不会穿透 Shadow Root 或 frame——这正是实时元素映射的用途。）

0.2.0 版有哪些新内容

• 已通过真实网页验证。 Chromium 驱动程序现已能够端到端操作真实网站：example.com（沿着 IANA 链接进入 Example Domains 页面）和一次真实的 Wikipedia 搜索——确定性 RuleDecider 输入了“Oakdale, Tennessee”，提交后进入 Oakdale 条目。 使用 ghost-hands bench --live 重现（2 个测试案例，2026 年 10 月 8 日在工作室沙盒中验证）。
• 目标自动修复。 如果页面在感知与操作之间发生变化，系统会检测到目标已过期，根据记录的描述符重新查找目标，准确重试一次，并将修复记录为轨迹中的独立事件。
• 标签页。 open_tab / switch_tab / list_tabs——每个标签页都有自己的 CDP 目标；感知和操作会应用于当前活动标签页。
• 会话状态。 save_session / load_session：以精简的版本化 JSON 格式保存 Cookie（Network.getAllCookies / setCookie）以及当前来源的 localStorage。
• 将截图保存到磁盘。 截图操作现在会将真实的 PNG（Page.captureScreenshot）写入操作的 path。
• 代理支持。 驱动程序支持 HTTPS_PROXY / https_proxy（设置 proxy="" 可停用）。内置本地中继可为经过身份验证的代理注入 Chrome 本身无法接受的凭据；对于拦截 TLS 的代理，可使用 ignore_cert_errors=True。
• Decider 协议验证。 测试和一个针对本地 stub /chat/completions 服务的 bench 测试案例覆盖了 OpenAI 兼容 Decider 的协议——请求格式、环境变量控制、回复解析以及完整的 Runner 循环。实时模型的操作效果仍未经验证（请参阅“真实状态”）。
• 已执行进阶脚本。 Replay 导出现在支持 driver=（chromium 或内嵌页面的 fake）和 start_url=；bench 会在真实的 Chromium 上，使用 fixture 页面实际执行进阶脚本，并检查其完成标记。

快速入门

pip install ghost-hands        # (once published; for now: pip install . from a checkout)
ghost-hands demo               # scripted run over a built-in fake mini-web — no browser needed
ghost-hands bench              # the verification suite

操作真实页面：

from ghost_hands import ChromiumDriver, Runner, ScriptedDecider

driver = ChromiumDriver()  # finds Chromium/Chrome; $GHOST_HANDS_CHROME overrides
runner = Runner(driver, ScriptedDecider([
    {"kind": "navigate", "url": "https://example.com"},
    {"kind": "extract"},
    {"kind": "done", "summary": "looked at the page"},
]))
report = runner.run("look at example.com")
print(report.stop_reason, report.summary)
driver.close()

在 MCP 客户端中使用

MCP 服务通过 stdio 以 ghost-hands mcp 运行；请先使用 pip install ghost-hands 安装。它提供五个工具：hands_perceive、hands_act、hands_run、hands_trail 和 hands_verify_trail。服务在每个进程启动时读取一次环境变量配置： GHOST_HANDS_DRIVER（fake、chromium、simphone 或 android；默认值为 fake）、GHOST_HANDS_POLICY（策略包名称；默认值为 standard）以及 GHOST_HANDS_APPROVER（设为 phone 可将“ask”判定转发给手机审批者；如果没有审批者，系统会拒绝请求并说明原因）。首次执行 perceive 时，GHOST_HANDS_START_URL 会打开一个页面；android 会话还会读取 GHOST_HANDS_ANDROID_BRIDGE 和 GHOST_HANDS_ANDROID_TOKEN。以下每个客户端都会使用相同的环境变量启动同一条命令；只有包装格式不同。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "ghost-hands": {
      "command": "ghost-hands",
      "args": ["mcp"],
      "env": {
        "GHOST_HANDS_DRIVER": "chromium",
        "GHOST_HANDS_APPROVER": "phone",
        "GHOST_HANDS_POLICY": "standard"
      }
    }
  }
}

Claude Code

claude mcp add ghost-hands -e GHOST_HANDS_DRIVER=chromium -e GHOST_HANDS_APPROVER=phone -e GHOST_HANDS_POLICY=standard -- ghost-hands mcp

Cursor

在项目的 .cursor/mcp.json 中添加，或在 ~/.cursor/mcp.json 中添加以应用于所有项目：

{
  "mcpServers": {
    "ghost-hands": {
      "command": "ghost-hands",
      "args": ["mcp"],
      "env": {
        "GHOST_HANDS_DRIVER": "chromium",
        "GHOST_HANDS_APPROVER": "phone",
        "GHOST_HANDS_POLICY": "standard"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json：

{
  "servers": {
    "ghost-hands": {
      "command": "ghost-hands",
      "args": ["mcp"],
      "env": {
        "GHOST_HANDS_DRIVER": "chromium",
        "GHOST_HANDS_APPROVER": "phone",
        "GHOST_HANDS_POLICY": "standard"
      }
    }
  }
}

Cline

添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "ghost-hands": {
      "command": "ghost-hands",
      "args": ["mcp"],
      "env": {
        "GHOST_HANDS_DRIVER": "chromium",
        "GHOST_HANDS_APPROVER": "phone",
        "GHOST_HANDS_POLICY": "standard"
      }
    }
  }
}

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.ghost-hands]
command = "ghost-hands"
args = ["mcp"]

[mcp_servers.ghost-hands.env]
GHOST_HANDS_DRIVER = "chromium"
GHOST_HANDS_APPROVER = "phone"
GHOST_HANDS_POLICY = "standard"

工作原理

层级	功能
Eyes (eyes.py)	带编号的 ElementMap — [3] <button> "Sign in" — 在字符预算内呈现精简文本。不使用屏幕截图或视觉模型。支持两种来源：HTML 快照解析（离线页面主体），或实时浏览器 — 组合树 DOM 遍历（影子根节点 + iframe）或 CDP 辅助功能树。
Hands (actions.py)	可类型化、可序列化为 JSON 的操作：导航、点击、输入、按键（含组合键）、选择、滚动、悬停、双击/右键、拖动、click_at（原始坐标）、fill_form、set_file、下载、提取（文本/列表/表格/网络）、截图（保存为实际 PNG 文件）、PDF、set_viewport、wait / wait_for、标签页、会话保存/加载、done。目标是元素编号，绝不使用原始选择器。
Governor (governor.py)	在执行每项操作之前进行分类，并应用策略：按类别允许/询问/拒绝、域名允许列表、屏蔽域名。表单提交，以及任何看起来涉及付款/发送/删除/发布/转账的操作，均属于后果重大操作。
Trail (trail.py)	JSONL 溯源记录：感知 → 决策 → 治理 → 执行 → 结果 → 停止（另含 heal、dialog、net、download 和 v1.0 cache 事件），并记录每次运行的统计信息（步骤数、感知字符数、按字符数/4 估算的 token 数、按类别统计的操作数）。治理与执行记录会在操作运行之前写入。v1.0：每个事件都通过 SHA-256 进行哈希链式关联 — 记录可检测篡改，并可通过 verify-trail 验证。
Secrets (secrets.py)	v1.0 凭据隔离：type/select/fill_form 值中的 {{secret:NAME}} 占位符，仅在执行边界从 GHOST_HANDS_SECRET_<NAME> 解析；结果会清除解析出的值。决策器、审批者、运行记录和计划缓存始终只保存占位符。
Verify (verify.py)	v1.0 只读断言（文本/元素/URL），由 Runner 根据实时感知结果进行评估 — 运行必须先证明结果，才能声明 done。
Plan cache (cache.py)	v1.0 受治理的计划缓存：done 运行会存储已验证的步骤（仅所有者可访问的文件）；相同目标会在完整 Governor 管控下重放，无需调用决策器，并会重新查找描述符；如果页面已更改，则会在运行记录中记录回退，并改用实时决策器。
Bodies (drivers.py, simphone.py, android_driver.py)	FakeDriver（用于测试/演示的内存迷你 Web）、ChromiumDriver（通过我们自己的 CDP 客户端驱动真实 Chromium：自动等待、标签页、会话保存/加载、截图保存到磁盘、下载/上传、网络捕获、对话框策略、视口模拟、PDF、支持带凭据注入本地中继的环境代理、过期目标检测）、SimPhoneDriver（模拟 Android 风格手机：应用、便笺、开关、返回/主页、渲染 PNG 截图），以及 AndroidDriver（通过 MrGhosty 应用的 Ghost Hands 桥接控制真实手机：环回 HTTP/JSON、配对令牌认证、通过 body_ref 目标进行辅助功能树感知、经密钥验证的操作、API 30+ 上的真实截图，且从设计上仅使用环回连接）。每个 body 都必须遵循的协议见 docs/BODY_PROTOCOL.md。
Brains (deciders.py)	ScriptedDecider（显式步骤）、RuleDecider（确定性的离线规则 — “前往…”、“点击…”、“在…中输入…”、“搜索…”）、OpenAICompatibleDecider（任意 OpenAI 兼容端点；密钥仅从环境变量读取，绝不存储；线协议已通过本地 stub 服务验证）。
Runner (runner.py)	执行循环，具有步骤预算、卡住检测（相同操作执行 3 次，或映射连续 3 步未变化）和自我修复：若目标在执行过程中移动，则按描述符重新查找并重试一次，并记录修复事件。明确的停止原因：done / budget / denied / stuck / error。沉默绝不代表同意：没有审批者时，“询问”即视为拒绝。
Replay export (export.py)	将运行记录转换为独立的 Ghost Hands 脚本，以确定性方式重放已执行步骤 — 无需模型，仍受治理。可使用 Chromium body，或内嵌迷你 Web 的 fake body。
Policy packs (policies.py)	以数据形式定义的具名 Governor 策略包：readonly（仅感知 — 直接拒绝写入和后果重大操作）、standard（默认）、strict（写入操作也需询问，审批时限为 120s）、seatbelt（标准策略 + 直接拒绝看似注入的目标 — v0.8）。每个策略包都设置按类别划分的允许/询问/拒绝规则、审批超时、允许列表附加项，以及可选的 deny_patterns。
Audit report (report.py)	将 trail JSONL 渲染为一个独立的 HTML 审计报告（v0.8）：标题、统计卡片、逐步时间线（含 Governor 判定和审批结果）、内嵌特殊事件。所有 trail 字符串均已转义；以密码形式输入的值会被遮蔽。
Bus mode (busclient.py, busagent.py)	使用标准库实现的 GhostBus REST 客户端（单工作区中继或托管的 /w/<id>/；密钥和 Agent 令牌通过标志/环境变量传入，仅保存在内存中），以及基于它构建的 Agent 循环：注册为 ghost-hands，领取指定对象/带标签的任务（遵守租约、blockedBy 和总线的需审批门控），在治理下执行任务，通过总线传回审批请求，将运行记录上传为共享文件，并附带结构化报告完成任务。
MCP 服务 (mcp_server.py)	仅使用标准库的 stdio MCP：hands_perceive、hands_act、hands_run、hands_trail。每个进程通过环境变量配置 body 和审批者：GHOST_HANDS_DRIVER（fake/chromium/simphone/android，v0.8）、GHOST_HANDS_START_URL、GHOST_HANDS_APPROVER=phone（在 Ryan 的手机上处理审批请求；默认拒绝并附带说明，回复中会标明作出决定的渠道）、GHOST_HANDS_POLICY（策略包名称）。

CLI

ghost-hands demo                                   # built-in fake-web demo
ghost-hands bench                                  # the offline verification suite
ghost-hands doctor                                 # diagnose the whole stack (add --json for tooling)
ghost-hands phone-proof                            # the guided on-device proof (exit: 0/1/2/3)
ghost-hands report trail.jsonl                     # trail -> trail.html audit report (-o for a path)
ghost-hands bench --live                           # + live cases: example.com, Wikipedia
ghost-hands run --script steps.json --driver fake  # or --driver chromium
adb forward tcp:8378 tcp:8378                      # forward the phone's Ghost Hands bridge (USB)
ghost-hands android-status                         # is MrGhosty's bridge answering? (token via env)
ghost-hands run --script steps.json --driver android   # drive the real phone, governed
ghost-hands run --script steps.json --policy policy.json --approve-all
ghost-hands run --script steps.json --policy-pack strict   # or readonly
| **Plan cache** (`cache.py`) | v1.0 governed plan cache: `done` runs store their proven steps (owner-only file); identical goals replay them through the full Governor with zero decider calls, descriptor re-finding, and an on-trail fallback to the live decider when the page has changed. |
ghost-hands run --script steps.json --cache plans.json     # v1.0 governed plan cache
ghost-hands verify-trail trail.jsonl                       # v1.0 prove a trail untampered
ghost-hands export trail.jsonl -o replay.py        # graduate a trail into a script
ghost-hands export trail.jsonl --driver fake --pages pages.json -o replay.py
ghost-hands mcp                                    # MCP server on stdio
ghost-hands bus-agent --once                       # work one GhostBus task, then exit
ghost-hands bus-agent --workspace studio           # hosted bus, /w/studio/ (key via GHOSTBUS_KEY)
ghost-hands bus-demo                               # prove bus mode vs the real GhostBus server

有关文件格式，请参阅 examples/steps.json 和 examples/policy.json。

对比

	驱动程序栈	意图层	治理 / 审批关卡	来源追踪记录	运行 → 脚本回放	主体
Playwright	自有 Chromium/Firefox/WebKit 协议驱动程序	无——确定性脚本	无	测试的 Trace Viewer	Codegen 记录脚本	Web
Playwright MCP	通过 MCP 使用 Playwright（23+ 个原始工具）	调用模型，不作中介	无	无内置功能	否	Web
Stagehand	Playwright + AI 原语（act/observe/extract/agent）	每一步都调用大模型	无	会话日志	操作缓存	Web（云浏览器为付费升级项）
Browser Use	自有浏览器 Agent 循环	完全自主的大模型循环	无	运行历史记录	否	Web
Jev	编号控制列表，低成本决策轮次	每一步进行一次低成本决策轮次	无（我们为此构建了 Agent Seatbelt）	最少	否	Web
Ghost Hands	自有 CDP 栈，零依赖——底层不使用 Playwright 或 Selenium	可插拔：脚本、确定性规则，或任何兼容 OpenAI 的模型	每次操作前分类 + 策略 + 审批；先记录后执行	完整的 JSONL 记录，含每次运行的用量统计	是——记录可发展为 Ghost Hands 脚本	Web（Chromium）+ 真正的 Android 主体（MrGhosty bridge）+ 模拟手机主体，遵循书面版 Body Protocol

按功能逐项比较

数据来自各项目的公开文档调查（2026 年 10 月）；“—”表示根据文档，该工具没有内置此功能。除标注为（fake）的项目外，Ghost Hands 的每项功能都有真实 Chromium 上具名基准测试用例作为证明——基准测试会说明每个用例在哪种主体上运行。

功能	Playwright	Stagehand	Browser Use	Ghost Hands
为模型提供编号元素映射	通过 MCP / 快照	observe	是（自有格式）	是——DOM 或 Accessibility-tree 视图
Shadow DOM 控件	是	是	部分支持	是——可穿透开放根节点（实时映射）
iframe 控件	是	是	部分支持	是——同页框架，带标签
JS 对话框（confirm/alert）	是	是	是	是——由策略驱动，决策记录在记录中
下载	是	是	是	是——记录完成状态和大小
文件上传	是	是	是	是——set_file
网络捕获	是（HAR/请求 API）	通过 Playwright	有限	是——net 记录事件 + 提取模式
一步填写整个表单	否（逐字段 API）	每个字段调用 act	Agent 循环	是——fill_form，返回逐字段结果
结构化提取（列表/表格）	手动定位器	extract（大模型架构）	Agent 循环	是——确定性执行，不调用模型
悬停 / 双击 / 右键 / 拖动	是	通过 act	是	是
组合按键（Control+a）	是	通过 act	是	是
原始坐标点击	是	—	是	是——分类为 write，并标记为原始操作
PDF 导出	是（Chromium）	通过 Playwright	—	是
设备/视口模拟	是	通过 Playwright	视口选项	是——具名预设，感知随之调整
等待文本/元素/URL	是	通过 act	Agent 循环	是——超时如实记录
每项操作都经过分类 + 审批关卡	否	否	否	是——核心所在
运行结果可发展为可回放脚本	Codegen（记录新操作）	操作缓存	否	是——由记录生成
防篡改审计记录	否（可编辑的跟踪记录）	否（会话日志）	否（运行历史记录）	是——SHA-256 哈希链，verify-trail（v1.0）
模型永远看不到凭据	否	否	部分支持（sensitive_data）	是——{{secret:NAME}} 占位符，仅从环境变量解析（v1.0）
执行 done 前检查成功断言	仅测试断言	否	否	是——verify 操作（v1.0）
自动治理计划缓存	否	操作缓存（无治理）	否	是——已验证计划经治理后回放，决策器调用次数为零（v1.0）

诚实说明

截至 v0.6.0（2026 年 10 月 8 日），哪些已得到验证，哪些尚未验证：

• **已验证：**完整的离线测试套件（299 个 pytest 测试、88 个基准测试用例）；Chromium 驱动程序在 fixture 页面上的表现（感知／输入／点击／标签页／会话往返／截图／分级脚本执行），以及在真实 Chromium 上的完整 v0.3 能力集（见矩阵说明）；在 example.com 和 Wikipedia 上的实时运行（ghost-hands bench --live，2/2）；LLM 决策器与本地 stub 端点之间的线路协议；Agent 总线模式连接真实 GhostBus 节点服务器——包括单工作区中继和托管的 /w/<id>/ 工作区，并在运行期间通过总线批准和拒绝各一次审批；三个进程内 body 上的 Body Protocol 一致性场景；模拟手机的笔记流程端到端运行；Android body 与桥接合约的对接——AndroidDriver 的完整受管控流程（包括变更后修复和重要删除门控）通过一个遵循真实桥接线路协议的模拟桥接进行测试，此外，MrGhosty v1.6.0 APK 已构建并完成签名验证，且已编译包含桥接；通过手机进行审批，符合相同的合约——PhoneApprover 的完整请求／轮询流程（已批准／已拒绝／已过期／超时／无法访问／401），已在线路上验证负载脱敏；在 Android 和 Web body 上，均通过模拟手机决策在运行期间批准和拒绝过重要操作；Agent 总线的手机通道已连接真实 GhostBus 服务器；MrGhosty v1.7.0 APK 已构建并完成签名验证，且已编译包含审批存储、接收器和桥接端点（审批存储逻辑通过 JVM 测试，共 44 项检查）。
• **尚未验证：**超出本地 fixture 范围的实时模型操控质量——v0.7 的评测框架会在 8 个本地分级任务上测量任何通过环境配置的模型（stub 得分 8/8 仅证明框架有效；规则基线为 3/8；真实模型的结果按每次运行报告，从不作为长期固定声明保存），但这些 fixture 规模小且位于本地：模型如何操控任意第三方网站取决于模型自身，在此尚未得到验证；Chromium 驱动程序在上述两个实时案例之外操控任意第三方网站的能力；与任何其他工具的速度对比（从未测量，也从未声称）；总线模式连接已部署的托管 GhostBus 的表现（已在本地启动的真实服务器上通过两种形式验证）；Android body 和手机审批流程在实体设备上的表现——驱动程序、MrGhosty 桥接和审批 UX 均已构建，但 v0.5／v0.6 构建期间没有连接手机；设备上的验证需等待 Ryan 安装 MrGhosty v1.8.0 并授予其无障碍权限（然后运行：adb forward tcp:8378 tcp:8378 和 ghost-hands phone-approval-test）。 v0.9 提供了专为该运行准备的工具：ghost-hands doctor 可在运行前后诊断整个技术栈，ghost-hands phone-proof 会引导他完成五个步骤并逐项检查——这两项工具均已在此通过模拟桥接和本地启动的总线验证，但尚未在他的实体手机上运行。v0.4 工作中发现的一项总线问题现已解决：GhostBus 的文件存储会通过单个共享 .tmp 文件写入，在大量并发写入时，文件重命名可能发生冲突（HTTP 400）——已在 GhostBus 0.4.1 中修复，自 GhostBus 0.5.0 起通过 GhostBus 测试套件的回归测试，并在 v0.7 中从本项目一侧再次验证（文件存储总线演示 + Agent／轮询器压力测试，400 错误为零）。GhostBus 的设计仍存在一个较窄的特性：共享存储会在每次操作时重新读取状态（读取－修改－写入，因此多个进程可以共享一个工作区文件），这意味着许多同时写入者仍可能静默地丢失更新——但 Ghost Hands 实际生成的 Agent＋轮询器工作负载不受影响（已测量）。

安全立场

• 不隐瞒。 Ghost Hands 会如实表明身份，绝不伪装自动化。治理就是产品；规避并非功能。
• 不存储密钥。 兼容 OpenAI 的决策器只从环境中读取 GHOST_HANDS_API_KEY / GHOST_HANDS_BASE_URL / GHOST_HANDS_MODEL。
• 拒绝即拒绝。 被阻止、拒绝或未获批准的操作绝不会执行——操作记录会显示判定结果及原因。

路线图

• GhostBus 传输 — 将 hands 作为总线 Agent，供其他 Agent 交办任务；审批通过总线路由（v0.4.0）。
• 策略包 — 命名的治理器捆绑包：readonly / standard / strict（v0.4.0）。可采用相同的数据格式，后续推出 Seatbelt/GhostGuard 风格的策略包。
• Body Protocol — 编写好的驱动程序契约，以及用于验证该契约的模拟手机机身（v0.4.0）。
• Android 机身 — 驱动程序 + MrGhosty 桥接已构建（v0.5.0）： MrGhosty 的无障碍服务通过回环配对令牌桥接实现 Body Protocol， AndroidDriver 可与其通信；设备端验证仍待 Ryan 安装并授予无障碍权限。一套 hands，同时支持手机 + Web。
• 通过手机推送审批 — 已完成（v0.6.0），但「推送」一词有一项明确说明： 桥接可访问时，审批会通过 MrGhosty 桥接发送到 Ryan 的手机 （通知 + 应用内决策）；这是本地桥接通道，并非云推送服务。桥接 API 没有决策端点—— 决策只能在手机本身上进行。
• 模型评估工具 — 已构建（v0.7.0）：ghost-hands eval 可对决策器执行 8 项本地任务评分（其中 4 项在真实 Chromium 上进行），并提供 逐项评分和 JSON 报告；同时附带 stub + rules 基线，真实模型通过环境接入。
• Android 手势 — 已构建（v0.7.0，MrGhosty v1.8.0）： 通过 dispatchGesture 在真实 Android 机身上实现了 double_click、drag 和 click_at；模拟器不会伪造这些操作。
• 现场工具包 — 已构建（v0.9.0）：ghost-hands doctor （全栈诊断，提供通俗易懂的修复建议；--json 供工具使用；绝不打印密钥）和 ghost-hands phone-proof（引导式五步设备端验证——经过检查，可脚本化，并返回退出码）。设备端验证本身仍待 Ryan 的手机就绪；这些工具可协助他运行验证。

仓库结构

链接： PyPI · 网站 · 版本 v0.3.0 · CHANGELOG.md · LAUNCH.md

• src/ghost_hands/ — 项目包，每一层对应一个模块：eyes （感知）、actions、governor、policies（策略包）、 trail、drivers（FakeDriver 和我们的 CDP ChromiumDriver）、simphone （模拟手机机身）、android_driver（通过 MrGhosty 桥接器连接的真实 Android 机身）、 phone_approver（在 Ryan 的手机上审批）、deciders、runner、export、 busclient + busagent（GhostBus 模式）、evaluate（v0.7 模型评估测试框架）、report（v0.8 将轨迹转换为 HTML 审计报告）、 doctor + phone_proof（v0.9 现场工具包）、 mcp_server、cli、bench。
• docs/BODY_PROTOCOL.md — 机身契约、能力标志、 一致性规则和 Android 映射表。
• docs/APPROVALS.md — 三种审批渠道（提示词、总线、 手机）、禁止通过 API 决策的规则，以及摘要脱敏规则。
• tests/ — pytest 测试套件（v0.9.0 中有 395 项测试）。
• 基准测试 — ghost-hands bench（离线，v0.9.0 中有 95 个案例）和 ghost-hands bench --live（需主动选择启用的真实 Web 案例）；基准测试代码位于 src/ghost_hands/bench.py。
• examples/ — ghost-hands run 的示例步骤和策略文件， 以及 sample-report.html — 一份渲染后的审计报告（来自 sample-trail.jsonl），展示 ghost-hands report 的确切输出。
• site/ — 项目网站源文件，由 .github/workflows/pages.yml 部署到 GitHub Pages。
• LAUNCH.md — 发布时编写的发布操作手册和文案包。
• PLAN.md — 项目开发启动前的现场调研和设计说明。

许可证

MIT — 详见 LICENSE。© 2026 Ghost Developer Studio。