HumanCanHelp (HCL) / 人工接手工具

HumanCanHelp is a local human-in-the-loop handoff tool for moments when AI needs a person to briefly see a live screen, click, type, drag, or complete a blocked step. It supports both browser tab sharing (CDP) and full desktop sharing (VNC).

HumanCanHelp 是一个本地运行的人机接手工具，适用于 AI 需要真人临时看一眼实时画面、点击、输入、拖动，或把卡住的步骤继续做完的场景。它同时支持浏览器标签页共享（CDP）和桌面共享（VNC）。

When to Use / 适用场景

• Visual checks that need a real person to look at the screen

需要真人查看屏幕的视觉确认步骤

• Short blocked browser or desktop steps during an automated workflow

自动化流程里短暂卡住的浏览器或桌面步骤

• Ordinary login pages or sign-in steps that a remote helper can legitimately complete

远程协助者可以合理代为完成的普通登录页面或登录步骤

• Any interactive handoff where AI cannot safely complete the step alone

任何 AI 无法单独安全完成的交互式接手场景

How to Use / 使用方式

Use a local checkout as the primary flow right now. If you publish the package into your own environment later, the CLI behavior stays the same: start HCL, send the printed URL to a helper, and wait for the CLI to exit.

当前更推荐直接从本地仓库运行。如果以后你把这个包发布到自己的环境里，CLI 行为也保持一致：启动 HCL，把打印出的 URL 发给协助者，然后等待 CLI 退出。

npm install
npm run build
npm start

Optional published-package flow, only after you have actually published or installed it:

只有在你真的已经发布或安装过这个包之后，才适合使用下面这种已发布包流程：

npx humancanhelp start

If you installed it globally yourself, hcl start is equivalent.

如果你是自己全局安装的，那么 hcl start 也是等价的。

Step 1: Start the help server / 第一步：启动帮助服务

HCL starts its own helper HTTP server automatically. You do not need to install a separate HTTP server first.

HCL 会自动启动自己的 helper HTTP 服务。你不需要先额外安装独立的 HTTP 服务。

What you do need is one of these local session sources:

你真正需要的是以下任意一种本地会话来源：

• a Chromium browser with remote debugging enabled for CDP mode, or

一个开启远程调试的 Chromium 浏览器，用于 CDP 模式

• a reachable VNC server for desktop mode.

一个可连通的 VNC 服务，用于桌面模式

hcl start

HCL auto-detects the best mode:

• If Chrome DevTools is running on port 9222 → CDP mode (shares browser tab)
• Otherwise → VNC mode (shares full desktop, requires VNC server)

HCL 会自动检测最合适的模式：

• 如果 9222 端口上的 Chrome DevTools 可用 → 使用 CDP 模式（共享浏览器标签页）
• 否则 → 回退到 VNC 模式（共享完整桌面，但需要 VNC 服务）

If neither source is available, HCL now fails early with setup instructions instead of starting a session that cannot connect.

如果两种来源都不可用，HCL 现在会直接提前失败，并给出设置提示，而不是先启动一个实际上根本连不上的会话。

For explicit mode selection:

如果你想显式指定模式：

# CDP mode (browser tab only)
# CDP 模式（仅共享浏览器标签页）
hcl start --cdp localhost:9222

# VNC mode (full desktop)
# VNC 模式（共享完整桌面）
hcl start --vnc localhost:5900

CDP mode output:

CDP 模式输出示例：

  HumanCanHelp started

  Local:   http://<your-local-ip>:6080
  Mode:    CDP (Chrome DevTools Protocol)
  Target:  ws://localhost:9222/devtools/page/XXXX
  Timeout: 600s

VNC mode output:

VNC 模式输出示例：

  HumanCanHelp started

  Local:   http://<your-local-ip>:6080
  Mode:    VNC
  VNC:     localhost:5900
  Timeout: 600s

For remote helpers (public URL) / 远程协助者访问（公共 URL）

hcl start --public --password "use-a-long-random-password"

If you want --public, install the optional tunnel dependency first from your local checkout:

如果你想使用 --public，请先在本地仓库里安装可选隧道依赖：

npm install localtunnel

This creates both a local and a public tunnel URL:

这样会同时生成本地地址和公共访问地址：

  Local:   http://<your-local-ip>:6080
  Public:  https://abc123.lhr.life
  Mode:    CDP (Chrome DevTools Protocol)
  Timeout: 600s
  Password: yes

Only use --public when you intentionally want to expose the live help session outside your local network.

只有在你明确希望把实时帮助会话暴露到本地网络之外时，才应使用 --public。

If you expose a public URL, always use a strong, unique --password so the helper must authenticate before they can access the live session.

如果你暴露公共 URL，请务必使用强且唯一的 --password，这样协助者在访问实时会话前必须先认证。

Step 2: Tell the user to open the URL / 第二步：让用户打开 URL

Say something like:

你可以这样说：

> Please open this URL to help me finish the blocked step: http://:6080

> 请打开这个 URL，帮我完成当前受阻的步骤：http://:6080

Step 3: Wait / 第三步：等待

The CLI blocks until:

• The user clicks "Done" on the page → exits with code 0
• The user clicks "Owner action required" only when the real account owner must continue personally → exits with a dedicated login-required failure outcome so the workflow can escalate to the account owner
• The user clicks "Cannot solve" → exits with code 1
• Timeout expires → HCL immediately starts a fresh session with the same config

CLI 会一直阻塞，直到：

• 用户在页面上点击 “Done” → 以退出码 0 结束
• 用户只有在必须由真实账号持有者本人继续时才点击 “Owner action required” → 以专门的 login-required 失败结果结束，方便把流程升级给账号持有者
• 用户点击 “Cannot solve” → 以退出码 1 结束
• 超时 → 当前会话立刻过期，旧页面会失效，而 HCL 会用相同配置立即启动一个新的会话

Step 4: Continue / 第四步：继续

After the CLI exits with code 0, the human has finished interacting with the screen. Normal login-related help can still complete this way. Continue your task.

当 CLI 以退出码 0 结束后，说明人工已经完成了屏幕交互；普通登录相关协助也同样可以通过这种方式完成。此时你就可以继续原来的任务。

Use the dedicated "Owner action required" outcome only for the narrower case where the real account owner must take over personally, such as owner-bound MFA, SSO approval, or another identity step the helper cannot legitimately complete.

只有在更窄的那类情况——必须由真实账号持有者本人接手，例如 owner 绑定的 MFA、SSO 批准，或其他协助者不能合理代办的身份确认步骤——才使用专门的 “Owner action required” 结果。

CLI Reference / CLI 参考

hcl start [options]

Options:
  --cdp <host:port>    Use CDP mode (Chrome DevTools Protocol), e.g. --cdp localhost:9222
  --vnc <host:port>    Use VNC mode, VNC server address (default: localhost:5900)
  --port <number>      HTTP server port (default: 6080)
  --timeout <seconds>  Session expiry in seconds; HCL immediately starts a fresh session after timeout (default: 600)
  --public             Also create a public tunnel URL for remote helpers
  --password <string>  Protect the help URL with a password
  --mask <regions>     Render black helper-side mask regions and block pointer input: "x,y,w,h;x,y,w,h"

hcl start [参数]

参数:
  --cdp <host:port>    使用 CDP 模式（Chrome DevTools Protocol），例如 --cdp localhost:9222
  --vnc <host:port>    使用 VNC 模式，VNC 服务地址（默认：localhost:5900）
  --port <number>      HTTP 服务端口（默认：6080）
  --timeout <seconds>  会话过期时间，单位秒；超时后会按相同配置立即开启新会话（默认：600）
  --public             为远程协助者生成公共访问地址
  --password <string>  为帮助 URL 添加访问密码
  --mask <regions>     渲染黑色协助者侧遮罩并阻止指针输入："x,y,w,h;x,y,w,h"

Modes / 模式

CDP Mode (recommended) / CDP 模式（推荐）

Shares only the browser tab via Chrome DevTools Protocol. Supports mouse clicks, typing, and slider drag interactions. Best for Playwright, Puppeteer, and browser-based recovery workflows.

通过 Chrome DevTools Protocol 仅共享浏览器标签页。支持鼠标点击、键盘输入和滑块拖动。适合 Playwright、Puppeteer 和其他浏览器自动化恢复场景。

Requires Chrome launched with --remote-debugging-port=9222.

要求 Chrome 通过 --remote-debugging-port=9222 启动。

VNC Mode / VNC 模式

Shares the full desktop via VNC. Requires a VNC server running on the machine.

通过 VNC 共享完整桌面。要求机器上已经有 VNC 服务在运行。

Session Expiry / 会话过期

The help page automatically expires when:

• Timeout is reached → page shows "This session has expired", disconnects
• Helper clicks Done → session ends, CLI exits with code 0
• Helper clicks "Cannot solve" → session ends, CLI exits with code 1

帮助页面会在以下情况自动过期：

• 达到超时时间 → 当前页面显示 “This session has expired” 并断开连接，同时 HCL 会立即按原配置重新拉起一个新会话
• 协助者点击 Done → 会话结束，CLI 以退出码 0 结束
• 协助者点击 “Cannot solve” → 会话结束，CLI 以退出码 1 结束

Privacy / 隐私说明

Password protection is available now. For password-protected sessions, remote helpers must authenticate before HCL exposes live session metadata or event updates. The --mask flag now renders black helper-side mask regions and blocks helper pointer input inside them, but it does not sanitize the underlying CDP/VNC transport stream itself.

当前已经支持密码保护。对于带密码的会话，远程协助者必须先通过认证，HCL 才会暴露实时会话元数据或事件更新。--mask 现在会在协助者界面中渲染黑色遮罩，并阻止协助者在这些区域内进行指针操作，但它不会改写底层 CDP/VNC 传输流本身。