Skip to content

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

fix: clarify browser login window lifecycle

LohseZSaia29728d73a1b
diff --git a/agent_reach/backends/cloak.py b/agent_reach/backends/cloak.py
index 628d6871..3ef65ead 100644
--- a/agent_reach/backends/cloak.py
+++ b/agent_reach/backends/cloak.py
@@ -5,7 +5,7 @@ import json
import os
from pathlib import Path
-from agent_reach.runtime.result import BAD_INPUT, NEED_SETUP, ReachError
+from agent_reach.runtime.result import BAD_INPUT, NEED_SETUP, TIMEOUT, ReachError
from agent_reach.utils.paths import (
atomic_write_private_text,
ensure_no_symlink_path,
@@ -88,7 +88,18 @@ def setup():
def login(channel):
"""User completes login in Cloak's own persistent browser, then closes it."""
from agent_reach.runtime import state
- items = call(channel, "login", timeout=900)
+ try:
+ items = call(channel, "login", timeout=900)
+ except ReachError as exc:
+ if exc.code != TIMEOUT:
+ raise
+ raise ReachError(
+ TIMEOUT,
+ "Cloak login window closed after 15 minutes without a saved session. "
+ "Ask the user whether to reopen it; do not retry automatically.",
+ hint="The user must finish login and close the Cloak window to save the session. "
+ "Then run agent-reach ensure for this channel.",
+ ) from None
path = folder(channel)
atomic_write_private_text(path / "configured.json", json.dumps({"source": "native login", "channel": channel}))
saved = state.load()
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 46b733ca..335d2a89 100644
--- a/agent_reach/skill/SKILL.md
+++ b/agent_reach/skill/SKILL.md
@@ -60,6 +60,8 @@ agent-reach read <链接> # 给链接,自动认出渠道
Cloak 查询和导入验收默认 `headless=True`。独立登录使用 `agent-reach cloak login CHANNEL`:由用户在可视窗口登录,完成后关闭窗口保存会话,再验收查询。此路径不需要 OpenCLI;OpenCLI 使用自己的 Chrome 会话,Cookie 导入仅为可选迁移方式。
+登录时只应弹出一个 Cloak 窗口;普通 Cloak 查询在后台运行并自动关闭窗口。`cloak login` 最多等待 15 分钟,用户未完成并关窗时返回超时,不能自行反复重开。旧的 `browser setup` 会另开标有 OpenCLI Browser 的专用 Chrome,只有用户明确选择该路径时才执行;它闲置约 10 分钟后关闭。复用用户已有 Chrome 时,不要关闭原窗口。
+
安装和 `add` 不打开浏览器。`ensure <渠道>` 优先复用已有会话并执行正式验收;显式 `--reuse-profile ID` 授权从该 Chrome 配置导入指定站点的 Cookie,该授权在本机保存,可用 `--forget-source` 撤销。`login <渠道>` 默认只查看现有连接。连接正常或保存过状态不等于当前已登录。
后端按动作选择:小红书 search/read、Twitter/Reddit search、Facebook search、Instagram search/profile/posts 使用 CloakBrowser → OpenCLI;BOSS search 使用 CloakBrowser → OpenCLI → boss-agent-cli,BOSS read 仅支持 CloakBrowser;LinkedIn jobs 使用 CloakBrowser → linkedin-mcp。其他动作以 `agent-reach channels` 中的后端声明为准。具体会话选择见 [会话配置](references/sessions.md)。
diff --git a/agent_reach/skill/references/sessions.md b/agent_reach/skill/references/sessions.md
index bc8ebe7e..f8f3188e 100644
--- a/agent_reach/skill/references/sessions.md
+++ b/agent_reach/skill/references/sessions.md
@@ -17,6 +17,8 @@ Use `agent-reach check CHANNEL --search` for one bounded live search check. Save
`setup` installs default channels. XHS and BOSS are optional: `agent-reach add xiaohongshu` or `agent-reach add boss` installs Cloak SDK and its browser binary without opening a browser. Installation does not import credentials.
+窗口生命周期:`cloak login CHANNEL` 打开一次可视 Cloak 窗口。用户完成登录后关闭该窗口,Reach 才保存会话;15 分钟内未关闭则超时并结束该窗口,不要自动重试。Cloak 查询和导入验收是 headless,执行结束会关闭自己的上下文。`browser setup` 属于旧的专用 OpenCLI Chrome 路径,可能显示 `OpenCLI Browser` 和 `about:blank`;它闲置约 10 分钟后关闭。通过 `browser use ID` 复用用户 Chrome 时,Reach 不关闭用户窗口。若同时出现两种窗口,先查实际执行的命令,不要把 OpenCLI Browser 称为 Ego Lite。
+
## Cloak:小红书与 BOSS / XHS and BOSS
独立路径:运行 `agent-reach cloak login CHANNEL`,用户登录完成后关闭窗口;再用 `--backend cloakbrowser` 验收查询。关闭窗口只标记会话已保存,不声称登录或业务验收成功。窗口等待上限 15 分钟;关闭登录窗口后再执行查询。
diff --git a/tests/test_cloak_backend.py b/tests/test_cloak_backend.py
index 76f1133b..f74791bc 100644
--- a/tests/test_cloak_backend.py
+++ b/tests/test_cloak_backend.py
@@ -97,6 +97,17 @@ def test_native_login_needs_no_opencli(monkeypatch, tmp_path):
assert json.loads((cloak.folder('instagram')/'configured.json').read_text())['source'] == 'native login'
+def test_native_login_timeout_explains_window_lifecycle(monkeypatch, tmp_path):
+ monkeypatch.setenv('HOME', str(tmp_path))
+ monkeypatch.setattr(cloak, 'call', lambda *a, **kw: (_ for _ in ()).throw(ReachError('TIMEOUT', 'worker timeout')))
+ with pytest.raises(ReachError) as caught:
+ cloak.login('xiaohongshu')
+ assert caught.value.code == 'TIMEOUT'
+ assert '15 minutes' in caught.value.message
+ assert 'do not retry automatically' in caught.value.message
+ assert not (cloak.folder('xiaohongshu') / 'configured.json').exists()
+
+
def test_import_removes_staging_file_after_failure(monkeypatch,tmp_path):
monkeypatch.setenv('HOME',str(tmp_path))
source=tmp_path/'cookies.json'