Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Python agent-infrastructureai-agentai-searchautomationbilibiliclaude-codeclicursorfree-apillm-toolsmcppythonreddit-scrapertwitter-scraperweb-scraperxiaohongshuyoutube-transcript
fix: clarify browser login window lifecycle
LohseZSaia29728d73a1b
diff --git a/agent_reach/backends/cloak.py b/agent_reach/backends/cloak.pyindex 628d6871..3ef65ead 100644--- a/agent_reach/backends/cloak.py+++ b/agent_reach/backends/cloak.py@@ -5,7 +5,7 @@ import jsonimport osfrom 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, ReachErrorfrom 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 Nonepath = 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.mdindex 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.mdindex 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.pyindex 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'