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: describe upstream failures by platform, drop error.source

Pnantaaac8d22fe66
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c17f8ae7..7820fa4a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -40,7 +40,7 @@ English:
- 浏览器渠道可以并行查询:同一平台最多 2 条、合计 4 条同时跑,多出来的排队而不是立刻报"正忙";登录窗口、退出登录等操作等正在跑的查询结束再做。
- 没登录时报"需要登录"而不是"上游工具坏了":雪球社区(错误码 400016)、B站字幕(没有 B站登录)、LinkedIn(专用浏览器里没有 LinkedIn 登录)。
- 从 1.5 升级更顺:update.md 先看版本再分流;`agent-reach update` 遇到 pip/pipx 装的旧版会自己换成 uv 安装;`setup` 删掉旧版 Agent Reach 程序(只删它自己,不动其他工具),安装汇报说明保留了什么、变了什么、以前用过哪些渠道可以加回来。安装地址改为始终指向最新正式版。
-- 上游工具出错时,报错原话和它自带的处理建议原样交给 AI,并用 `error.source` 标明是哪个工具说的;不再用 Reach 自己编的建议覆盖("要登录"仍给 Reach 自己专用浏览器的登录步骤)。
+- 平台出错时,报错原话和自带的处理建议原样交给 AI,由 AI 用平台名告诉用户哪个平台暂时有问题;不再用 Reach 自己编的建议覆盖("要登录"仍给 Reach 自己专用浏览器的登录步骤)。
English (technical):
- Browser channels share one profile, close after ten idle minutes and reopen on demand.
@@ -53,7 +53,7 @@ English (technical):
- Browser channels run queries in parallel: up to 2 per platform and 4 in total, with the rest queued instead of failing BUSY at once; login windows, logout and browser setup wait for running queries.
- Report NEED_LOGIN instead of UPSTREAM_BROKEN when not logged in: Xueqiu community (error 400016), Bilibili subtitles (no Bilibili login), LinkedIn (no LinkedIn login in the dedicated browser).
- Smoother upgrade from 1.5: update.md checks the version first; `agent-reach update` moves a pip/pipx install to uv by itself; `setup` removes the old Agent Reach program (only Agent Reach itself) and the install report explains what was kept, what changed and which old channels can be added back. Install URLs always point at the latest release.
-- Upstream errors reach the agent unchanged: the tool's own message and help, with `error.source` naming the tool. Reach no longer replaces them with its own advice (NEED_LOGIN still gives Reach's dedicated-browser login steps).
+- Upstream errors reach the agent unchanged (the original message and help); the agent tells the user which platform is temporarily unavailable, by platform name. Reach no longer replaces them with its own advice (NEED_LOGIN still gives Reach's dedicated-browser login steps).
### ✨ New / 新增
diff --git a/agent_reach/backends/opencli.py b/agent_reach/backends/opencli.py
index da3cc257..369401a9 100644
--- a/agent_reach/backends/opencli.py
+++ b/agent_reach/backends/opencli.py
@@ -45,15 +45,15 @@ def _opencli_error(text: str, login_hint: str):
upstream_hint = str(err.get("help") or err.get("hint") or "").strip() or None
low = message.lower()
if any(w in low for w in ("环境异常", "环境存在异常", "browser environment", "captcha", "验证码", "安全验证", "account_risk")) or code in {"ACCOUNT_RISK", "CAPTCHA_REQUIRED"}:
- return ReachError(PLATFORM_BLOCKED, message, hint=upstream_hint, source="opencli")
+ return ReachError(PLATFORM_BLOCKED, message, hint=upstream_hint)
if code in {"RATE_LIMITED", "RATE_LIMIT"} or any(w in low for w in ("http 429", "too many requests", "访问过于频繁")):
- return ReachError(RATE_LIMITED, message, source="opencli")
+ return ReachError(RATE_LIMITED, message)
login_words = ("login", "log in", "logged in", "sign in", "http 401", "登录")
if not re.search(r"\bHTTP 404\b", message, re.I) and (
"AUTH" in code or "LOGIN" in code or any(w in low for w in login_words)):
# Upstream would send the user to their own Chrome; Reach logs in in its own browser.
- return ReachError(NEED_LOGIN, message, hint=login_hint or None, source="opencli")
- return ReachError(UPSTREAM_BROKEN, message, hint=upstream_hint, source="opencli")
+ return ReachError(NEED_LOGIN, message, hint=login_hint or None)
+ return ReachError(UPSTREAM_BROKEN, message, hint=upstream_hint)
def opencli_call(site: str, args, *, timeout: float, login_hint: str = ""):
diff --git a/agent_reach/channels/bilibili.py b/agent_reach/channels/bilibili.py
index 037e926f..b070b14e 100644
--- a/agent_reach/channels/bilibili.py
+++ b/agent_reach/channels/bilibili.py
@@ -71,14 +71,14 @@ def _bili_json(args: list, timeout: float) -> Any:
message = str(err.get("message", "bili-cli failed"))[:500]
upstream_hint = str(err.get("hint") or "").strip() or None
if any(word in code.lower() for word in ("risk", "captcha", "verification")):
- raise ReachError(PLATFORM_BLOCKED, message, hint=upstream_hint, source="bili-cli")
+ raise ReachError(PLATFORM_BLOCKED, message, hint=upstream_hint)
if "rate" in code.lower() or "频繁" in message:
- raise ReachError(RATE_LIMITED, message, source="bili-cli")
+ raise ReachError(RATE_LIMITED, message)
if code == "not_found":
- raise ReachError(NOT_FOUND, message, source="bili-cli")
+ raise ReachError(NOT_FOUND, message)
if "login" in code or "auth" in code or "credential" in code:
- raise ReachError(NEED_LOGIN, message, hint=_BILI_LOGIN_HINT, source="bili-cli")
- raise ReachError(UPSTREAM_BROKEN, message, hint=upstream_hint, source="bili-cli")
+ raise ReachError(NEED_LOGIN, message, hint=_BILI_LOGIN_HINT)
+ raise ReachError(UPSTREAM_BROKEN, message, hint=upstream_hint)
return payload.get("data") or {}
diff --git a/agent_reach/runtime/result.py b/agent_reach/runtime/result.py
index f378e78d..61ac296c 100644
--- a/agent_reach/runtime/result.py
+++ b/agent_reach/runtime/result.py
@@ -37,7 +37,7 @@ DEFAULT_HINTS = {
PLATFORM_BLOCKED: "Stop automation. Keep this profile; the user must resolve the platform verification in the official page. Do not switch backends or retry.",
NEED_SETUP: "This backend is not installed. Ask the user to run `agent-reach doctor` for setup steps.",
NEED_LOGIN: "The attempted saved/local session did not grant access. Offer site-scoped local reuse or let the user log in themselves; never ask for a password.",
- UPSTREAM_BROKEN: "The upstream tool failed; `message` is its own wording. Tell the user what it says; do not retry in a loop, and suggest `agent-reach update` only if the message points to an outdated tool.",
+ UPSTREAM_BROKEN: "This channel is temporarily not working; `message` is what was reported. Tell the user in plain words which platform has a problem, without naming tools; suggest `agent-reach update` only if the message points to an outdated tool; do not retry in a loop.",
TIMEOUT: "The operation timed out. Inspect channel status and the failed stage; do not reopen login windows or repeat requests in a loop.",
RATE_LIMITED: "The platform reported a rate limit. Reach pauses this channel; respect retry_after_seconds and do not switch backends.",
NOT_FOUND: "The requested content does not exist. Check the link or id.",
@@ -48,15 +48,13 @@ _MAX_MESSAGE_CHARS = 500
class ReachError(Exception):
- """A failure with a unified code. `source` names who wrote `message`/`hint`:
- an upstream tool (passed through unchanged) or None for Agent Reach itself."""
+ """A failure with a unified code; upstream messages and hints are passed through unchanged."""
- def __init__(self, code: str, message: str, hint: Optional[str] = None, source: Optional[str] = None):
+ def __init__(self, code: str, message: str, hint: Optional[str] = None):
super().__init__(message)
self.code = code
self.message = message
self.hint = hint
- self.source = source
def _clean(text: object) -> str:
@@ -140,6 +138,5 @@ def envelope(
"code": error.code,
"message": error.message,
"hint": error.hint or DEFAULT_HINTS.get(error.code, ""),
- "source": getattr(error, "source", None) or "agent-reach",
},
}
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 45332fa3..b16129cc 100644
--- a/agent_reach/skill/SKILL.md
+++ b/agent_reach/skill/SKILL.md
@@ -42,7 +42,7 @@ agent-reach read <链接> # 按链接自动选渠道
|---|---|
| `NEED_SETUP` | 缺依赖或密钥。按提示 `agent-reach add <渠道>`;要密钥时请用户本人提供,再 `agent-reach configure <key>` |
| `NEED_LOGIN` | 保留已有结果,告诉用户需要登录;`agent-reach login <渠道>` 打开浏览器,由用户本人登录,你绝不代登、不要密码 |
-| `UPSTREAM_BROKEN` | 上游工具出错,`message` 是它的原话(`source` 写着是哪个工具)。把原话的意思告诉用户;原话说明工具过时,才在用户同意后跑一次 `agent-reach update`;不循环重试 |
+| `UPSTREAM_BROKEN` | 这个平台暂时有问题,`message` 是出错时的原话。用平台名告诉用户哪个平台暂时用不了、大概是什么原因,不说工具名;原话说明工具过时,才在用户同意后跑一次 `agent-reach update`;不循环重试 |
| `TIMEOUT` | 看失败阶段和渠道状态(`agent-reach doctor --text`);不反复重试、不反复开窗 |
| `RATE_LIMITED` | 平台限流,Reach 已暂停该渠道;按 `retry_after_seconds` 等,不换后端 |
| `PLATFORM_BLOCKED` | 平台要求验证(验证码/风控)。停下,请用户在官方页面处理;不换账号、不换后端 |
diff --git a/agent_reach/skill/SKILL_en.md b/agent_reach/skill/SKILL_en.md
index 2ba86a1f..21efcd59 100644
--- a/agent_reach/skill/SKILL_en.md
+++ b/agent_reach/skill/SKILL_en.md
@@ -43,7 +43,7 @@ agent-reach read <url> # picks the channel from the URL
|---|---|
| `NEED_SETUP` | Missing dependency or key. Run `agent-reach add <channel>` as hinted; for a key, the user provides it, then `agent-reach configure <key>` |
| `NEED_LOGIN` | Keep existing results and tell the user login is needed; `agent-reach login <channel>` opens the browser and the user logs in themselves. Never log in for them or ask for a password |
-| `UPSTREAM_BROKEN` | The upstream tool failed; `message` is its own wording (`source` names the tool). Tell the user what it says; run `agent-reach update` once, after they agree, only if the message points to an outdated tool; never retry in a loop |
+| `UPSTREAM_BROKEN` | This platform is temporarily not working; `message` is what was reported. Tell the user which platform is unavailable and roughly why, by platform name, without naming tools; run `agent-reach update` once, after they agree, only if the message points to an outdated tool; never retry in a loop |
| `TIMEOUT` | Check the failed stage and channel status (`agent-reach doctor --text`); do not retry or reopen windows in a loop |
| `RATE_LIMITED` | The platform rate-limited; Reach paused the channel. Wait `retry_after_seconds`; do not switch backends |
| `PLATFORM_BLOCKED` | The platform wants verification (captcha/risk check). Stop; the user resolves it on the official page. Do not switch accounts or backends |
diff --git a/tests/test_unified_entry.py b/tests/test_unified_entry.py
index 7dde709e..4626abb7 100644
--- a/tests/test_unified_entry.py
+++ b/tests/test_unified_entry.py
@@ -628,16 +628,12 @@ def test_opencli_message_and_help_reach_the_agent_unchanged():
err = _opencli_error(text, "reach login steps")
out = envelope(channel="reddit", action="search", error=err)["error"]
assert out == {"code": "UPSTREAM_BROKEN", "message": 'Browser profile "x" is not connected',
- "hint": "Open the matching Chrome profile.", "source": "opencli"}
+ "hint": "Open the matching Chrome profile."}
login = _opencli_error("ok: false\nerror:\n code: AUTH_REQUIRED\n message: Not logged into x.com\n"
" help: Log in in your Chrome.\n", "reach login steps")
assert login.message == "Not logged into x.com" and login.hint == "reach login steps" # Reach's own browser
-def test_reach_own_errors_say_so():
- from agent_reach.runtime.result import ReachError, envelope
- assert envelope(channel=None, action=None, error=ReachError("BUSY", "full"))["error"]["source"] == "agent-reach"
-
def test_query_uses_an_open_login_window_without_closing_it(fake_browser):
from agent_reach.runtime import browser