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(skill): document verified backend fallbacks

Pnant748ffc4e153b
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 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.md
index 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 search
gh 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 topics
curl -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 user
agent-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 channel
diff --git a/agent_reach/skill/references/finance.md b/agent_reach/skill/references/finance.md
new file mode 100644
index 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.md
index 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.py
index 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