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://<your-local-ip>:6080
请打开这个 URL，帮我完成当前受阻的步骤：http://<your-local-ip>: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 传输流本身。
