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(skill): document verified backend fallbacks
Pnant748ffc4e153b
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.mdindex e65d4601..d633a6c5 100644--- a/agent_reach/skill/SKILL.md+++ b/agent_reach/skill/SKILL.md@@ -18,7 +18,7 @@ description: >发帖/评论/点赞等写操作;已有专门 skill 的平台(先用专门 skill)。【路由方式】SKILL.md 包含路由表和常用命令,复杂场景需按需阅读对应分类的 references/*.md。- 分类:search / social (小红书/推特/B站/V2EX/Reddit/Facebook/Instagram) / career(LinkedIn) / dev(github) / web(网页/文章/RSS) / video(YouTube/B站/播客)。+ 分类:search / social (小红书/推特/B站/V2EX/Reddit/Facebook/Instagram) / career(LinkedIn) / dev(github) / web(网页/文章/RSS) / video(YouTube/B站/播客) / finance(雪球/股票)。triggers:- research: 调研/全网调研/帮我调研/研究一下/research/深入了解- search: 搜/查/找/search/搜索/查一下/帮我搜/看看大家怎么说@@ -47,7 +47,9 @@ metadata:## 常驻规则(全程适用)1. **动手前先体检**:多后端/登录态平台(小红书/Reddit/B站/Twitter/Facebook/Instagram)先跑- `agent-reach doctor --json`,按各平台 `active_backend` 字段选命令组。+ `agent-reach doctor --json`。`active_backend` 有值时按它选命令组;`active_backend: null`+ 表示 Doctor 为避免触发浏览器 Cookie 读取或远端写入而没有做实时验证,不代表后端不存在。+ 只有用户任务明确需要该平台时,才按对应 reference 的只读命令手动验证。2. **声明你在用什么**:开始干活前说一句「使用 agent-reach 的 X 平台 / Y 后端」。3. **失败按 references 里的重试链处理**,不要瞎猜命令。4. **全网调研类任务**:组合多平台(Exa 搜索 + Twitter/Reddit 看讨论 + 小红书/B站看中文场景),并行收集再汇总。@@ -67,6 +69,7 @@ metadata:| GitHub/代码 | dev | [references/dev.md](references/dev.md) || 网页/文章/RSS | web | [references/web.md](references/web.md) || YouTube/B站/播客字幕 | video | [references/video.md](references/video.md) |+| 雪球/股票行情 | finance | [references/finance.md](references/finance.md) |## 零配置快速命令@@ -80,8 +83,8 @@ curl -s "https://r.jina.ai/URL"# GitHub 搜索gh search repos "query" --sort stars --limit 10-# YouTube 字幕(注意:B站不要用 yt-dlp,见 video.md)-yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL"+# YouTube 字幕(注意:B站不要用 yt-dlp,失败重试链见 video.md)+yt-dlp --write-sub --write-auto-sub --skip-download -o "/tmp/%(id)s" "URL"# V2EX 热门curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"@@ -126,6 +129,12 @@ opencli instagram user USERNAME -f yaml # 读指定用户最近帖子agent-reach doctor --json```+## OpenCLI 适配器发现++路由表没有覆盖用户需要的平台或命令时,先用 `opencli list` 查已有适配器,再用+`opencli <平台> --help` 查看公开命令。发现适配器只证明命令存在,不证明登录态或+目标内容可用;仅在用户任务明确需要该平台时执行只读命令,并以实际非空内容验收。+## 工作区规则**不要在 agent workspace 创建文件。** 使用 `/tmp/` 存放临时输出,`~/.agent-reach/` 存放持久数据。@@ -140,6 +149,7 @@ agent-reach doctor --json- [开发工具](references/dev.md) — GitHub CLI- [网页阅读](references/web.md) — Jina Reader, RSS- [视频播客](references/video.md) — YouTube, B站, 小宇宙+- [金融行情](references/finance.md) — 雪球股票行情、搜索、热门内容## 配置渠道diff --git a/agent_reach/skill/SKILL_en.md b/agent_reach/skill/SKILL_en.mdindex e102df1c..0d57dd67 100644--- a/agent_reach/skill/SKILL_en.md+++ b/agent_reach/skill/SKILL_en.md@@ -29,8 +29,10 @@ these platforms — do not invent your own approach.**## Standing rules (apply for the whole session)1. **Health-check before acting**: for multi-backend/login-backed platforms (XiaoHongShu /- Reddit / Bilibili / Twitter / Facebook / Instagram), run `agent-reach doctor --json` first and- pick the command group matching each platform's `active_backend`.+ Reddit / Bilibili / Twitter / Facebook / Instagram), run `agent-reach doctor --json` first.+ Use a populated `active_backend`; `active_backend: null` means Doctor deliberately skipped a+ live probe to avoid browser-cookie reads or remote writes, not that no backend exists. Only when+ the user's task requires that platform, run the reference's read-only command to verify it.2. **Announce what you use**: say "using agent-reach, platform X via backend Y"before starting.3. **On failure, follow the retry chains in references/** — never guess@@ -55,6 +57,7 @@ these platforms — do not invent your own approach.**| GitHub / code | dev | [references/dev.md](references/dev.md) || Web pages / articles / RSS | web | [references/web.md](references/web.md) || YouTube / Bilibili / podcast transcripts | video | [references/video.md](references/video.md) |+| Xueqiu / stock quotes | finance | [references/finance.md](references/finance.md) |## Zero-config quick commands@@ -68,8 +71,8 @@ curl -s "https://r.jina.ai/URL"# GitHub searchgh search repos "query" --sort stars --limit 10-# YouTube subtitles (NOTE: never use yt-dlp for Bilibili — see video.md)-yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL"+# YouTube subtitles (never use yt-dlp for Bilibili; retry chain in video.md)+yt-dlp --write-sub --write-auto-sub --skip-download -o "/tmp/%(id)s" "URL"# V2EX hot topicscurl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"@@ -116,6 +119,13 @@ opencli instagram user USERNAME -f yaml # recent posts from one useragent-reach doctor --json```+## Discovering OpenCLI adapters++When the routing table lacks a needed platform or command, run `opencli list`,+then inspect `opencli <platform> --help`. Discovery proves only that an adapter+exists, not that authentication or target content works. Run read-only commands+only when the user's task requires that platform, and require non-empty content.+## Workspace rules**Never create files in the agent workspace.** Use `/tmp/` for temporary@@ -133,6 +143,7 @@ chains — note: reference docs are written in Chinese, commands are universal):- [Dev](references/dev.md) — GitHub CLI- [Web](references/web.md) — Jina Reader, RSS- [Video](references/video.md) — YouTube, Bilibili, Xiaoyuzhou+- [Finance](references/finance.md) — Xueqiu quotes, search and market content## Configure a channeldiff --git a/agent_reach/skill/references/finance.md b/agent_reach/skill/references/finance.mdnew file mode 100644index 00000000..bebfce93--- /dev/null+++ b/agent_reach/skill/references/finance.md@@ -0,0 +1,46 @@+# 金融行情++雪球股票行情、搜索与热门内容。行情可能延迟,不构成投资建议。++## 先检查状态++```bash+agent-reach doctor --json+```++`xueqiu.active_backend` 有值时按该后端使用;值为 `null` 只表示 Doctor 没有完成+实时内容验证。雪球需要已登录会话或最小 Cookie,不能把 HTTP 400 当成股票不存在。++## OpenCLI(桌面已有 Chrome 登录态时优先)++```bash+# 验证当前登录态+opencli xueqiu whoami -f yaml++# 股票搜索与实时行情+opencli xueqiu search "英伟达" -f yaml+opencli xueqiu stock NVDA -f yaml++# 热门内容与热门股票+opencli xueqiu hot -f yaml+opencli xueqiu hot-stock -f yaml++# 查看全部只读命令+opencli xueqiu --help+```++OpenCLI 只复用用户已经存在且明确控制的浏览器会话。不要自动执行+`opencli xueqiu login`;没有现成登录态时,让用户先在 Chrome 登录,或显式导入+雪球所需的最小 Cookie:++```bash+agent-reach configure --from-browser chrome --platform xueqiu+```++该配置只读取并保存 `xq_a_token`,不会顺带采集其他平台 Cookie。++## 验收与失败处理++- 以返回股票名称、代码、价格或非空内容列表为成功;退出码 0 但字段为空不算成功。+- HTTP 400 通常是会话/Cookie 问题,不表示股票代码不存在。+- `whoami` 成功而 `stock`/`hot` 失败时,按适配器解析或平台接口问题报告,不要误诊成未登录。diff --git a/agent_reach/skill/references/video.md b/agent_reach/skill/references/video.mdindex 529d1ca8..b9d8227a 100644--- a/agent_reach/skill/references/video.md+++ b/agent_reach/skill/references/video.md@@ -39,6 +39,20 @@ yt-dlp --dump-json "ytsearch5:query"> **字幕注意**: 手动上传的字幕提取可靠;自动生成字幕可能存在行间重复,需后处理。> **评论注意**: `--write-comments` 基于网页抓取(非 YouTube Data API),部分评论可能丢失。+### 字幕失败时的重试链(按序执行,拿到实质内容即停)++`doctor` 只确认 yt-dlp 本体与 JS runtime 能执行,不会请求具体视频;因此+`active_backend: yt-dlp` 不等于目标视频的字幕已经通过实时验证。++1. 先用上面的 `yt-dlp --write-sub --write-auto-sub` 命令。+2. 若出现 bot 校验、字幕响应为空或没有生成字幕文件,且 OpenCLI 已连接:+ `opencli youtube transcript "URL" -f yaml`。+3. OpenCLI 若返回 `Caption URL returned empty response`,最多重试 3 次;这是带+ 过期时间的字幕 URL 偶发失效,不能把空响应当成“视频没有字幕”。+4. 仍失败或视频本来就没有字幕:`agent-reach transcribe "URL"` 下载音频转写。++成功标准是实际得到非空字幕/转录内容,不是命令退出码或 `doctor` 的版本探测结果。+### 无字幕兜底:Whisper 音频转写```bash@@ -124,7 +138,7 @@ agent-reach doctor| 场景 | 推荐工具 ||-----|---------|-| YouTube 字幕 | yt-dlp |+| YouTube 字幕 | yt-dlp;失败时 OpenCLI(最多 3 次)→ agent-reach transcribe || B站视频详情/搜索 | bili-cli || B站字幕 | opencli bilibili subtitle || 播客转录 | 小宇宙 transcribe.sh |diff --git a/tests/test_auth_guidance_policy.py b/tests/test_auth_guidance_policy.pyindex 3eeaf817..99b173fa 100644--- a/tests/test_auth_guidance_policy.py+++ b/tests/test_auth_guidance_policy.py@@ -164,3 +164,42 @@ def test_public_guidance_never_installs_the_unrelated_pypi_package():)assert not violations, "\n".join(violations)+++def test_skill_explains_unverified_backend_state():+ """A null backend is an explicit safety state, not a routing instruction."""+ skills = (+ ROOT / "agent_reach" / "skill" / "SKILL.md",+ ROOT / "agent_reach" / "skill" / "SKILL_en.md",+ )+ for path in skills:+ text = path.read_text(encoding="utf-8")+ assert "active_backend: null" in text, path.relative_to(ROOT)+ assert "Doctor" in text, path.relative_to(ROOT)+++def test_video_reference_has_content_level_youtube_fallbacks():+ """Version-only health must not be presented as proof subtitles work."""+ text = (+ ROOT / "agent_reach" / "skill" / "references" / "video.md"+ ).read_text(encoding="utf-8")+ assert "opencli youtube transcript" in text+ assert "最多重试 3 次" in text+ assert "agent-reach transcribe" in text+++def test_skill_routes_finance_and_documents_opencli_discovery():+ skills = (+ ROOT / "agent_reach" / "skill" / "SKILL.md",+ ROOT / "agent_reach" / "skill" / "SKILL_en.md",+ )+ for path in skills:+ text = path.read_text(encoding="utf-8")+ assert "references/finance.md" in text, path.relative_to(ROOT)+ assert "opencli list" in text, path.relative_to(ROOT)+ assert "--help" in text, path.relative_to(ROOT)++ finance = ROOT / "agent_reach" / "skill" / "references" / "finance.md"+ text = finance.read_text(encoding="utf-8")+ assert "opencli xueqiu stock" in text+ assert "agent-reach configure --from-browser chrome --platform xueqiu" in text