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.

chore: v2 cutover: remove legacy code, rewrite docs, add release workflow

Pnant628973399e66
diff --git a/.github/workflows/pytest.yml b/.github/workflows/pytest.yml
index 4371ace8..5c6e1168 100644
--- a/.github/workflows/pytest.yml
+++ b/.github/workflows/pytest.yml
@@ -78,9 +78,9 @@ jobs:
names = zipfile.ZipFile(whl).namelist()
dupes = [n for n, c in collections.Counter(names).items() if c > 1]
assert not dupes, f"duplicate entries in wheel: {dupes}"
- assert "agent_reach/skill/SKILL.md" in names, "SKILL.md missing from wheel"
- for prefix in ("agent_reach/guides/", "agent_reach/scripts/", "agent_reach/skill/references/"):
- assert any(n.startswith(prefix) for n in names), f"{prefix} missing from wheel"
+ for path in ("agent_reach/skill/SKILL.md", "agent_reach/skill/SKILL_en.md"):
+ assert path in names, f"{path} missing from wheel"
+ assert any(n.startswith("agent_reach/scripts/") for n in names), "agent_reach/scripts/ missing from wheel"
print(f"wheel OK: {len(names)} entries, no duplicates, data files present")
PY
@@ -89,4 +89,5 @@ jobs:
python -m venv /tmp/smoke
/tmp/smoke/bin/pip install --quiet dist/*.whl
/tmp/smoke/bin/agent-reach version
+ cd /tmp && /tmp/smoke/bin/agent-reach channels | /tmp/smoke/bin/python -c "import json, sys; d = json.load(sys.stdin); assert d['ok'] and d['channels'], d; print(f\"channels OK: {len(d['channels'])}\")"
cd /tmp && /tmp/smoke/bin/python -c "import agent_reach; from importlib.resources import files; assert (files('agent_reach')/'skill'/'SKILL.md').is_file(); print('SKILL.md ships in site-packages OK')"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..58f5a95e
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,62 @@
+name: release
+
+# Push a tag like v2.0.0 to publish. Users install from the tagged archive,
+# so a release is only created after the tests pass and the tag matches the
+# version in pyproject.toml and agent_reach/__init__.py.
+
+on:
+ push:
+ tags: ["v*"]
+
+permissions:
+ contents: write
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Tag must match the package version
+ run: |
+ tag="${GITHUB_REF_NAME#v}"
+ py=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+ init=$(python -c "import re;print(re.search(r'__version__ = \"(.+?)\"', open('agent_reach/__init__.py').read()).group(1))")
+ echo "tag=$tag pyproject=$py __init__=$init"
+ test "$tag" = "$py" && test "$tag" = "$init"
+
+ - name: Test
+ run: |
+ python -m pip install --upgrade pip
+ pip install -c constraints.txt -e ".[dev]"
+ pytest -q
+
+ - name: Build and smoke-install the wheel
+ run: |
+ python -m pip install build
+ python -m build
+ python -m venv /tmp/smoke
+ /tmp/smoke/bin/pip install --quiet dist/*.whl
+ /tmp/smoke/bin/agent-reach version
+ /tmp/smoke/bin/agent-reach channels > /dev/null
+
+ - name: Release notes from CHANGELOG
+ run: |
+ python - <<'PY'
+ import os, re
+ version = os.environ["GITHUB_REF_NAME"].lstrip("v")
+ text = open("CHANGELOG.md", encoding="utf-8").read()
+ m = re.search(rf"^## \[{re.escape(version)}\].*?$(.*?)(?=^## \[|\Z)", text, re.M | re.S)
+ if not m:
+ raise SystemExit(f"CHANGELOG.md has no section for {version}")
+ open("notes.md", "w", encoding="utf-8").write(m.group(1).strip() + "\n")
+ PY
+
+ - name: Create GitHub release
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc367cb1..15081553 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,32 @@ All notable changes to this project will be documented in this file.
---
-## [Unreleased]
+## [2.0.0] - unreleased
+
+v2 is a rebuild. Agents call one command, `agent-reach`; everything Agent Reach installs or stores lives under `~/.agent-reach/`.
+v2 是重构版本:Agent 只调一个命令 `agent-reach`,Agent Reach 装的、存的东西全部在 `~/.agent-reach/` 下。
+
+### ✨ New / 新增
+
+- **Unified entry / 统一入口**: `agent-reach <channel> <action>`, `agent-reach read <url>`, `agent-reach channels`. One JSON envelope per call, unified error codes with hints, per-call timeout, automatic fallback to the next backend.
+- **Management / 管理命令**: `setup`, `add` / `remove <channel>`, `login` / `logout <channel>`, `doctor`, `check`, `watch`, `update`, `configure`, `uninstall`.
+- **Private, pinned upstream installs / 上游私有安装**: tools go into `~/.agent-reach/tools/` at versions we tested; the user's own copies are untouched. Single-instance tools (OpenCLI) reuse the user's copy and are upgraded only with `--allow-upgrade`.
+- **Login state under `~/.agent-reach/` / 登录状态统一管理**: CLI tool logins in `sessions/`, browser logins in a dedicated Agent Reach browser (`agent-reach browser setup`). Agent Reach never logs in for the user and never reads the user's own browser cookies.
+- **doctor states / 体检**: not_added, needs_setup, needs_login, unverified, ready, broken. `watch` reports only what broke since the last check.
+- **update** upgrades the program with its original installer, syncs tools to pinned versions and refreshes the agent skill. Pre-2.0 installs are migrated on first `setup` / `update`; `config.yaml` keys are kept.
+- Xueqiu quotes and stock search via Tencent public quotes (no login); Xueqiu community data uses a session the user imports with `agent-reach login xueqiu --sync`.
+- YouTube `transcribe`; LinkedIn uses its own MCP registration in `~/.agent-reach/mcporter.json`.
+
+### 🔄 Changed / 变更
+
+- Default channels: web (fallback only), YouTube, GitHub, V2EX. Optional: 小红书, B站, Reddit, LinkedIn, Boss直聘, 小宇宙, 雪球. Experimental: Twitter, Facebook, Instagram.
+- The agent skill is generated from the channel list and replaced on every update.
+
+### 🗑️ Removed / 移除
+
+- RSS channel (agents read feeds themselves).
+- xhs-cli, rdt-cli, twitter-cli backends: they read browser cookies by themselves.
+- `configure --from-browser`, `twitter-cookies`, `xhs-cookies`, the old `install --channels`, `skill`, `format`, `check-update`, MCP server entry.
### 🐛 Bug Fixes / 修复
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 299b8145..42855c9e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,107 +1,73 @@
# Contributing to Agent Reach
-Thank you for your interest in contributing to Agent Reach! This document provides guidelines and instructions for contributing.
+Agent Reach makes it easier for AI agents to reach the internet. Contributions that add or repair a channel are the most useful.
-## Getting Started
-
-1. Fork the repository on GitHub
-2. Clone your fork locally
-3. Create a new branch for your contribution
-4. Make your changes
-5. Run tests and linting
-6. Submit a pull request
-
-## Development Setup
+## Development setup
```bash
-# Clone your fork
git clone https://github.com/YOUR_USERNAME/Agent-Reach.git
cd Agent-Reach
-
-# Install in development mode
-pip install -e ".[dev]"
-
-# Install pre-commit hooks (optional but recommended)
-pre-commit install
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
```
-## Code Style
-
-We use the following tools to maintain code quality:
-
-- **ruff**: Linting and import sorting
-- **mypy**: Type checking
-- **pytest**: Testing
-
-Run all checks before submitting a PR:
+Checks before a PR:
```bash
-# Linting
-ruff check agent_reach tests
-ruff format agent_reach tests
-
-# Type checking
-mypy agent_reach
-
-# Tests
-pytest
+.venv/bin/ruff check agent_reach tests
+.venv/bin/pytest
```
-## Adding New Channels
+## The channel contract
-Agent Reach uses a unified channel interface. To add a new platform:
+A channel is a `Channel` subclass in `agent_reach/channels/`, registered in `agent_reach/channels/__init__.py`. It declares:
-1. Create a new file in `agent_reach/channels/`
-2. Implement the channel contract (see existing channels for examples)
-3. Add tests in `tests/test_channels.py`
-4. Update `agent_reach/doctor.py` to include the new channel
-5. Update documentation
+- `name`, `description`, and `can_handle(url)` so `agent-reach read <url>` can route links to it.
+- `level`: `"default"` (works with no setup), `"optional"` (turned on with `agent-reach add`), or `"experimental"` (works but may break any time).
+- `actions`: a tuple of `Action`s. Each has a `name`, `help`, `params` (a tuple of `Param(name, help, required, type, default)`), and **ordered** `backends` as `(label, method name)` pairs. The dispatcher tries them in order and falls back on retryable errors. `live_test` holds the params `agent-reach check` uses; a backend passes when it returns at least one item. Slow actions can set `timeout`.
+- `tools` (optional): keys of `runtime.tools.TOOLS` that `agent-reach add` installs privately under `~/.agent-reach/tools/`, pinned to an exact version.
+- `prereqs` (optional): machine prerequisites that are only checked and explained (keys of `runtime.manage.PREREQS`: node, git, chrome, ffmpeg, uv).
+- Login, if the platform needs it:
+ - `login_url`: page opened in the Agent Reach browser by `agent-reach login`; the user logs in there.
+ - `session` + `login_argv`: a CLI tool whose own login runs with its state in `~/.agent-reach/sessions/<session>/`. `legacy_state` lists old locations `login --import-existing` may copy from.
+- `setup_problems()`: what still blocks the channel after its tools are installed (missing key, browser not set up). Shown by `agent-reach doctor`.
-## Pull Request Guidelines
+Backend methods return items built with `make_item(...)` and raise `ReachError(code, message, hint=...)` with one of `NEED_SETUP`, `NEED_LOGIN`, `UPSTREAM_BROKEN`, `TIMEOUT`, `RATE_LIMITED`, `NOT_FOUND`, `BAD_INPUT`. Hints are written for the agent and must never tell it to log in for the user.
-- **Small, focused changes** are preferred over large refactors
-- Include tests for new functionality
-- Update documentation if needed
-- Follow existing code style
-- Reference any related issues
+Rules:
-## Reporting Issues
+- Never read the user's own browser cookies and never log in on their behalf.
+- Everything a channel stores lives under `~/.agent-reach/`.
+- Don't install anything globally; add the tool to `runtime.tools.TOOLS` with a pinned version.
-When reporting bugs, please include:
+## Before merging a channel
-- Python version
-- Operating system
-- Steps to reproduce
-- Expected vs actual behavior
-- Any error messages
+A new or changed channel must pass a live check on your machine:
-## Questions?
-
-Feel free to open an issue for questions or join discussions.
+```bash
+agent-reach add <channel> # optional / experimental channels
+agent-reach login <channel> # if it needs a login
+agent-reach check <channel> --text
+```
----
+Paste the `check --text` output into the PR. Also add unit tests under `tests/` (see `tests/test_channel_contracts.py`).
-感谢您对 Agent Reach 的贡献!本文档提供了贡献指南。
+## Pull requests
-## 快速开始
+- Small, focused changes.
+- Commit messages in English.
+- Update the README channel table if you add a channel or change what it needs.
+- Never commit keys, cookies, account names or machine-specific paths.
-1. 在 GitHub 上 fork 仓库
-2. 本地 clone 您的 fork
-3. 创建新分支
-4. 提交更改
-5. 运行测试和 lint
-6. 提交 pull request
+## Reporting issues
-## 代码规范
+Include your OS, `agent-reach doctor --text`, `agent-reach check <channel> --text`, steps to reproduce, and what you expected. Remove personal data first.
-- 使用 **ruff** 进行代码检查
-- 使用 **mypy** 进行类型检查
-- 使用 **pytest** 运行测试
+---
-## 添加新渠道
+## 中文简述
-1. 在 `agent_reach/channels/` 创建新文件
-2. 实现渠道接口
-3. 添加测试
-4. 更新 doctor 检测
-5. 更新文档
+- 渠道 = `agent_reach/channels/` 里的一个 `Channel` 子类,在 `channels/__init__.py` 注册。需要声明 `level`、`actions`(`Action`/`Param`、有序后端、`live_test`),按需声明 `tools`、`prereqs`、`login_url` / `session` / `login_argv`、`setup_problems()`。
+- 不读用户自己浏览器的 Cookie,不替用户登录,数据只放在 `~/.agent-reach/` 下。
+- 新渠道合并前必须在本地跑通 `agent-reach check <channel>` 实测,并把输出贴在 PR 里。
+- 提交前运行 `ruff check agent_reach tests` 和 `pytest`。Commit message 用英文。
diff --git a/README.md b/README.md
index 5ef5446b..2b934563 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
<h1 align="center">👁️ Agent Reach</h1>
<p align="center">
- <strong>给你的 AI Agent 一键装上互联网能力</strong>
+ <strong>让 AI Agent 够得着它自己上不去的互联网</strong>
</p>
<p align="center">
- 当下最稳的接入方式,替你选好、装好、体检好——接入方式会换代,你不用操心
+ 登录墙后的平台、视频和播客里的内容、中文平台、干净的结构化数据,一条命令拿到,统一 JSON 输出
</p>
<p align="center">
@@ -57,241 +57,157 @@
## 为什么需要 Agent Reach?
-AI Agent 已经能帮你写代码、改文档、管项目——但你让它去网上找点东西,它就抓瞎了:
+Claude Code、Codex、Hermes Agent、OpenClaw 这类 CLI Agent 自带搜索和网页读取,但下面这些它们基本够不着:
-- 📺 "帮我看看这个 YouTube 教程讲了什么" → **看不了**,拿不到字幕
-- 🐦 "帮我搜一下推特上大家怎么评价这个产品" → **搜不了**,Twitter API 要付费
-- 📖 "去 Reddit 上看看有没有人遇到过同样的 bug" → **403 被封**,服务器 IP 被拒
-- 📕 "帮我看看小红书上这个品的口碑" → **打不开**,必须登录才能看
-- 📺 "B站上有个技术视频,帮我总结一下" → **拿不到**,通用下载工具被 B站风控全面拦截
-- 🔍 "帮我在网上搜一下最新的 LLM 框架对比" → **没有好用的搜索**,要么付费要么质量差
-- 🌐 "帮我看看这个网页写了啥" → **抓回来一堆 HTML 标签**,根本没法读
-- 📦 "这个 GitHub 仓库是干嘛的?Issue 里说了什么?" → 能用,但认证配置很麻烦
-- 📡 "帮我订阅这几个 RSS 源,有更新告诉我" → 要自己装库写代码
+- **要登录才能看的平台**:小红书、Twitter/X、Reddit、LinkedIn、Boss直聘……网页抓不到,或者只能看到登录页。
+- **视频和音频里的内容**:YouTube 和 B站的字幕、小宇宙播客的完整文字稿。
+- **中文平台**:B站、小红书、V2EX、雪球、小宇宙,通用搜索覆盖很差。
+- **干净的结构化数据**:雪球行情、V2EX 帖子和回复、GitHub 仓库和 issue,直接给字段,不用从 HTML 里猜。
-**这些不难实现,但是需要自己折腾配置**
+Agent Reach 把这些平台背后的开源工具替你装好、固定版本、定期体检,然后给 Agent 一个统一入口:
-每个平台都有自己的门槛——要付费的 API、要绕过的封锁、要登录的账号、要清洗的数据。你要一个一个去踩坑、装工具、调配置,光是让 Agent 能读个推特就得折腾半天。
-
-**Agent Reach 把这件事变成一句话:**
-
-```
-帮我安装 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
+```bash
+agent-reach channels # 有哪些渠道、每个渠道能做什么
+agent-reach bilibili search "大模型" # agent-reach <渠道> <动作> [参数]
+agent-reach read https://www.v2ex.com/t/123 # 按链接自动选渠道
```
-复制给你的 Agent,几分钟后它就能读推特、搜 Reddit、看 YouTube、刷小红书了。
-
-**已经装过了?更新也是一句话:**
-
-```
-帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-```
+每条命令都输出同一种 JSON,Agent 不用学每个工具的用法,也不用解析各家五花八门的输出。
-> ⭐ **Star 这个项目**,我们会持续追踪各平台的变化、接入新的渠道。你不用自己盯——平台封了我们修,有新渠道我们加。
+> `web` 渠道(网页搜索和阅读)只是保底:Agent 自带的搜索或网页读取不可用、或者读失败时再用它。
### ✅ 在你用之前,你可能想知道
-| | |
-|---|---|
-| 💰 **完全免费** | 所有工具开源、所有 API 免费。唯一可能花钱的是服务器代理($1/月),本地电脑不需要 |
-| 🔒 **隐私安全** | Cookie 只存在你本地,不上传不外传。代码完全开源,随时可审查 |
-| 🔄 **持续换代** | 每个平台都是「首选 + 备选」多后端路由。某个接入方式失效了,我们换下一个,你无感(2026-06 实例:yt-dlp 被 B站风控封死 → 已切换 bili-cli,用户零操作) |
-| 🤖 **兼容所有 Agent** | Claude Code、OpenClaw、Cursor、Windsurf……任何能跑命令行的 Agent 都能用 |
-| 🩺 **自带诊断** | `agent-reach doctor` 一条命令告诉你哪个通、哪个不通、怎么修 |
+- **适用于哪些 Agent?** 任何能执行命令行的 Agent。`agent-reach setup` 会把使用说明(skill)装进 Claude Code、Codex、OpenCode、OpenClaw 等的 skill 目录。
+- **要花钱吗?** 程序和后端工具都是开源免费的。只有两处可能要你自己的 Key:播客/视频转文字用 Groq(有免费额度)或 OpenAI 的 Whisper 接口。
+- **会碰我的浏览器和账号吗?** 不会读你自己浏览器里的 Cookie,也从不替你登录。需要登录的渠道,由你本人在 Agent Reach 专用浏览器里登录。详见[安全性](#安全性)。
+- **支持哪些系统?** 优先保证 macOS,Linux 可用,Windows 尽力支持。
---
## 支持的平台
-| 平台 | 装好即用 | 配置后解锁 | 怎么配 |
-|------|---------|-----------|-------|
-| 🌐 **网页** | 阅读任意网页 | — | 无需配置 |
-| 📺 **YouTube** | 字幕提取 + 视频搜索 | — | 无需配置 |
-| 📡 **RSS** | 阅读任意 RSS/Atom 源 | — | 无需配置 |
-| 🔍 **全网搜索** | — | 全网语义搜索 | 自动配置(MCP 接入,免费无需 Key) |
-| 📦 **GitHub** | 读公开仓库 + 搜索 | 私有仓库、提 Issue/PR、Fork | 告诉 Agent「帮我登录 GitHub」 |
-| 🐦 **Twitter/X** | 读单条推文 | 搜索推文、浏览时间线、读长文 | 告诉 Agent「帮我配 Twitter」 |
-| 📺 **B站** | 搜索 + 视频详情(bili-cli,无需登录) | 字幕(OpenCLI) | 告诉 Agent「帮我配 B站」 |
-| 📖 **Reddit** | —(没有零配置路径:匿名接口已被封) | 搜索 + 读帖子和评论 | 桌面装 OpenCLI 用浏览器登录态;或 rdt-cli + Cookie |
-| 📘 **Facebook** | — | 搜索、主页、Feed、群组列表 | 桌面装 OpenCLI(复用 Chrome 登录态) |
-| 📷 **Instagram** | — | 用户搜索、Profile、用户最近帖子、Explore | 桌面装 OpenCLI(复用 Chrome 登录态) |
-| 📕 **小红书** | — | 搜索、阅读、评论 | OpenCLI 只用用户已有 Chrome 会话;MCP/存量工具用 Cookie-Editor |
-| 💼 **LinkedIn** | Jina Reader 读公开页面 | Profile 详情、公司页面、职位搜索 | 告诉 Agent「帮我配 LinkedIn」 |
-| 🎯 **Boss直聘** | CDP 链路体检 | 搜索岗位 + JD 全文(专用真 Chrome) | 告诉 Agent「帮我配 Boss直聘」;Agent 打开专用 Chrome,你手动登录 |
-| 💻 **V2EX** | 热门帖子、节点帖子、帖子详情+回复、用户信息 | — | 无需配置 |
-| 📈 **雪球** | 股票行情、搜索股票、热门帖子、热门股票排行 | — | 告诉 Agent「帮我配雪球」 |
-| 🎙️ **小宇宙播客** | — | 播客音频转文字(Whisper 转录,免费 Key) | 告诉 Agent「帮我配小宇宙播客」 |
-
-> **不知道怎么配?不用查文档。** 直接告诉 Agent「帮我配 XXX」,它知道需要什么、会一步一步引导你。
->
-> 🍪 Twitter 只接受用户通过 Cookie-Editor 手工导出的内容。Agent Reach 不替用户执行小红书登录,也不读取小红书浏览器 Cookie;OpenCLI 只使用用户已经存在且明确控制的 Chrome 会话。`agent-reach configure xhs-cookies` 不会把 Cookie 注入 OpenCLI / Chrome;没有现成会话时,改用 Cookie-Editor 导出后配置 xiaohongshu-mcp / 存量工具。
->
-> Twitter Cookie 保存后仅供 `agent-reach doctor` 检查配置是否齐全;直接运行上游 `twitter` 命令前,仍需在当前进程环境中显式设置 `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`。
->
-> 🔒 Cookie 只存在你本地,不上传不外传。代码完全开源,随时可审查。
-> 💻 本地电脑不需要代理。代理只有部署在服务器上才需要(~$1/月)。
+`agent-reach channels` 是实时的准确来源,下表是当前版本的情况。
+
+| 渠道 | 等级 | 能做什么 | 需要什么 |
+|---|---|---|---|
+| github | 默认 | 搜仓库、读仓库/README、读 issue 和 PR(含评论) | 无(装了 `gh` 或配置 token 后额度更高) |
+| youtube | 默认 | 视频信息、搜索、字幕、语音转文字 | 无;转文字需要 Groq 或 OpenAI Key |
+| v2ex | 默认 | 热门、节点、帖子和回复、用户 | 无 |
+| web | 默认 | 网页搜索、网页阅读(保底) | 无 |
+| xiaohongshu | 可选 | 搜笔记、读笔记 | 浏览器 + 登录 |
+| bilibili | 可选 | 搜索、视频信息、热门、字幕 | 字幕需要登录(扫码) |
+| reddit | 可选 | 搜索、读帖子和评论、看版块 | 浏览器 + 登录 |
+| linkedin | 可选 | 搜职位 | 登录(需要 Node.js 和 uv) |
+| boss | 可选 | 搜职位和 JD | 浏览器 + 登录(需要 git) |
+| xiaoyuzhou | 可选 | 播客完整转文字 | Groq Key + ffmpeg |
+| xueqiu | 可选 | 实时行情、搜股票、热帖、热股 | 行情免登录;热帖热股需要浏览器登录 |
+| twitter | 实验 | 搜推文、用户资料、用户推文、读推文串 | 浏览器 + 登录 |
+| facebook | 实验 | 搜索、主页资料 | 浏览器 + 登录 |
+| instagram | 实验 | 搜用户、主页资料、用户帖子 | 浏览器 + 登录 |
+
+- **默认**:装好就能用。
+- **可选**:用 `agent-reach add <渠道>` 按需开启,Agent Reach 会把它要的工具装到自己的目录里。
+- **实验**:能用,但平台反爬更严,可能随时失效。
+- **浏览器**:指 Agent Reach 专用浏览器,一个独立的 Chrome 窗口(需要已安装 Google Chrome 和 Node.js),第一次用要在里面装一个 OpenCLI 扩展,`agent-reach browser setup` 会带你完成。
---
## 快速上手
-> ⚠️ **OpenClaw 用户请先确认 exec 权限已开启**
->
-> Agent Reach 依赖 Agent 执行 shell 命令(`pip install`、`mcporter`、`twitter` 等)。如果你的 OpenClaw 使用了默认的 `messaging` 工具配置,Agent 将无法执行命令。**安装前请先开启 exec 权限**:
->
-> ```bash
-> openclaw config set tools.profile "coding"
-> ```
-> 或在 `~/.openclaw/openclaw.json` 中设置 `"tools": { "profile": "coding" }`。
-> 设置后重启 Gateway(`openclaw gateway restart`)并开启新对话即可。其他平台(Claude Code、Cursor、Windsurf 等)不受此限制。
-
-复制这句话给你的 AI Agent(Claude Code、OpenClaw、Cursor 等):
+把这句话发给你的 Agent:
```
帮我安装 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
-就这一步。Agent 会自己完成剩下的所有事情。
-
-> 🔄 **已安装过?** 更新也是一句话:
-> ```
-> 帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-> ```
+Agent 会照着 [install.md](docs/install.md) 做完这几步:
-> 🛡️ **默认安全:** `agent-reach install` 默认只检查环境,不会自动装系统包或写入配置:
-> ```
-> 帮我安全检查并安装 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
-> ```
-> 只有在你明确允许修改系统后,才使用 `agent-reach install --system`。
+1. 安装程序:`uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip`
+2. 运行 `agent-reach setup`:检查环境,把使用说明装进 Agent 的 skill 目录
+3. 把可选渠道列给你,你选要哪些,它运行 `agent-reach add <渠道>`
+4. 需要登录的渠道,它运行 `agent-reach login <渠道>` 打开登录页,**由你本人登录**
-<details>
-<summary>它会做什么?(点击展开)</summary>
+> ⚠️ PyPI 上叫 `agent-reach` 的包不是本项目,请勿从 PyPI 安装,只用上面的 GitHub 地址。
-1. **安装 CLI 工具** — 从本仓库安装 `agent-reach` 命令行(自带 yt-dlp、feedparser;不要从 PyPI 安装同名包,它不是本项目)
-2. **检查系统基建** — 检查 Node.js、gh CLI、mcporter,并给出缺失项的安装方式
-3. **按授权安装与配置** — 仅在显式传入 `--system` 时安装依赖并通过 MCP 接入 Exa
-4. **检测环境** — 判断是本地电脑还是服务器,给出对应的配置建议
-5. **按授权注册 SKILL.md** — 仅在显式 `--system` 时写入 Agent 的 skills 目录;默认检查不改文件
-6. **问你要不要更多** — 默认只激活 6 个零配置渠道;小红书、Twitter、Reddit、Facebook、Instagram 这些需要登录态的,Agent 会列菜单问你要哪些,点名才装
+想自己动手也一样,照着 [install.md](docs/install.md) 敲命令就行。
-安装完之后,`agent-reach doctor` 一条命令告诉你每个渠道的状态、当前走哪条路。
-</details>
+```mermaid
+flowchart LR
+ A[Agent] -->|agent-reach 渠道 动作| B[Agent Reach]
+ B --> C{按顺序尝试后端}
+ C -->|首选| D[上游工具 1]
+ C -->|失败时备选| E[上游工具 2]
+ D --> F[统一 JSON]
+ E --> F
+ F --> A
+```
---
## 装好就能用
-不需要任何配置,告诉 Agent 就行:
+装好后,日常只会用到这几条(大多由 Agent 替你运行):
-- "帮我看看这个链接" → `curl https://r.jina.ai/URL` 读任意网页
-- "这个 GitHub 仓库是做什么的" → `gh repo view owner/repo`
-- "这个 YouTube 视频讲了什么" → `yt-dlp` 提取字幕
-- "B站搜一下 AI 教程" → `bili search`(无需登录)
-- "全网搜一下 LLM 框架对比" → Exa 语义搜索
-- "订阅这个 RSS" → `feedparser` 解析
+| 命令 | 作用 |
+|---|---|
+| `agent-reach doctor --text` | 看每个渠道的状态:未开启 / 待配置 / 待登录 / 未验证 / 可用 / 故障 |
+| `agent-reach check [渠道] --text` | 真实跑一遍测试,确认渠道能用 |
+| `agent-reach watch --text` | 只报告"上次还好、现在坏了"的渠道,以及有没有新版本 |
+| `agent-reach update` | 一次更新程序、后端工具和 skill,见 [update.md](docs/update.md) |
+| `agent-reach add` / `remove <渠道>` | 开启 / 关闭可选渠道 |
+| `agent-reach login` / `logout <渠道>` | 登录(你本人操作)/ 清除登录 |
+| `agent-reach configure <项> [值]` | 保存 `groq-key`、`openai-key`、`proxy`、`github-token` |
-**不需要记命令。** Agent 读了 SKILL.md 之后自己知道该调什么。需要登录的平台(小红书、Twitter、Reddit、Facebook、Instagram),告诉 Agent「帮我配 XXX」即可解锁。
+出错时,JSON 里的 `error.code` 会告诉 Agent 下一步该做什么。每种错误和状态的处理办法见 [troubleshooting.md](docs/troubleshooting.md)。
---
## 设计理念
-**Agent Reach 是一个能力层(capability layer),不是又一个工具。**
-
-它比任何具体实现高一层——负责**选型、安装、体检、路由**,不负责底层读取本身。读取由 Agent 直接调用上游工具完成,没有包装层。
-
-你给一个新 Agent 装环境的时候,总要花时间去找工具、装依赖、调配置——Twitter 用什么读?Reddit 怎么登录?小红书的 CLI 停更了换什么?每次都要重新踩一遍。Agent Reach 做的事情很简单:**当下最稳的接入方式,我们替你选好、装好、体检好。接入方式会换代(2026 年 3 月一批单平台 CLI 集体停更,我们换了路由),你不用操心。**
-
### 🔌 每个平台 = 首选 + 备选的有序后端列表
-换接入方式 = 调整列表顺序,不是重写代码。`agent-reach doctor` 会告诉你每个平台**当前在用哪个后端**。
-
-```
-channels/
-├── web.py → Jina Reader
-├── twitter.py → twitter-cli ▸ OpenCLI ▸ bird
-├── youtube.py → yt-dlp
-├── github.py → gh CLI
-├── bilibili.py → bili-cli ▸ OpenCLI ▸ 搜索 API(yt-dlp 已被 B站风控封死,退役)
-├── reddit.py → OpenCLI ▸ rdt-cli(无零配置路径,必须登录态)
-├── facebook.py → OpenCLI(桌面浏览器登录态)
-├── instagram.py → OpenCLI(桌面浏览器登录态)
-├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
-├── linkedin.py → mcp-server-linkedin ▸ Jina Reader
-├── rss.py → feedparser
-├── exa_search.py → Exa via mcporter
-└── __init__.py → 渠道注册(doctor 检测用)
-```
-
-每个渠道文件按序**真实探测**各候选后端(不只是看命令存不存在),第一个完整可用的当选;坏掉的会给出修复处方。实际的读取和搜索由 Agent 直接调用上游工具完成。
+每个渠道的每个动作都有一个有序的后端列表。比如 `bilibili read` 先用 bili-cli,失败了自动换 B站公开接口;`web read` 先用 Jina Reader,再用 Exa。返回的 JSON 里 `backend` 字段会写明这次实际用的是谁。
-### 当前选型
+平台改版、工具失效是常态。换后端只是调整这个列表,Agent 的调用方式不变。
-| 场景 | 首选 | 备选 | 为什么这么选 |
-|------|------|------|-----------|
-| 读网页 | [Jina Reader](https://github.com/jina-ai/reader) | — | 免费,不需要 API Key |
-| 读推特 | [twitter-cli](https://github.com/public-clis/twitter-cli) | [OpenCLI](https://github.com/jackwener/opencli) | 实测搜索稳定;OpenCLI 走浏览器登录态兜底 |
-| Reddit | [OpenCLI](https://github.com/jackwener/opencli)(桌面) | [rdt-cli](https://github.com/public-clis/rdt-cli) | 匿名接口已被封、官方 API 审批制——只剩登录态路线 |
-| Facebook | [OpenCLI](https://github.com/jackwener/opencli)(桌面) | — | Graph API/Groups API 权限收紧;浏览器登录态是当前最实用路径 |
-| Instagram | [OpenCLI](https://github.com/jackwener/opencli)(桌面) | 官方 Graph API(Business/Creator + 审批) | instaloader 类路径不稳定;OpenCLI 复用真实浏览器会话 |
-| YouTube 字幕 + 搜索 | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | 154K Star,YouTube 仍是最佳(注意:不再用于 B站) |
-| B站 | [bili-cli](https://github.com/public-clis/bilibili-cli) | OpenCLI ▸ 搜索 API | yt-dlp 被 B站风控 412 封死(2026-06 实测),bili-cli 无登录可搜可读 |
-| 搜全网 | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | — | AI 语义搜索,MCP 接入免 Key |
-| GitHub | [gh CLI](https://cli.github.com) | — | 官方工具,认证后完整 API 能力 |
-| 读 RSS | [feedparser](https://github.com/kurtmckee/feedparser) | — | Python 生态标准选择 |
-| 小红书 | [OpenCLI](https://github.com/jackwener/opencli)(桌面) | [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)(服务器)▸ xhs-cli | OpenCLI 只用用户已有会话;其余后端用 Cookie-Editor 手工导出 |
-| LinkedIn | [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server) | Jina Reader | MCP 服务,浏览器自动化 |
+### 📌 固定版本,私有安装
-> 📌 这些都是「当前选型」,基于真机实测定期复核。某条路失效了我们换下一条——`agent-reach doctor` 永远告诉你现在走的是哪条。
+Agent Reach 装的工具(OpenCLI、bili-cli、boss-agent-cli、mcporter)都固定在验证过的版本,装在 `~/.agent-reach/tools/` 里,不污染你的全局环境。`agent-reach update` 会把它们一起更新到新版本验证过的版本。
----
+### 🩺 能用要靠实测
-## 安全性
+`doctor` 只做离线检查;`check` 会真的去平台上请求一次。一个渠道只有通过实测才会标为"可用"。
-Agent Reach 在设计上重视安全:
+### 统一输出
-| 措施 | 说明 |
-|------|------|
-| 🔒 **凭据本地存储** | Cookie、Token 只存在你本机 `~/.agent-reach/config.yaml`,文件权限 600(仅所有者可读写),不上传不外传 |
-| 🛡️ **默认安全** | `agent-reach install` 默认不修改系统;只有显式 `--system` 才安装外部工具和写入配置 |
-| 👀 **完全开源** | 代码透明,随时可审查。所有依赖工具也是开源项目 |
-| 🔍 **Dry Run** | `agent-reach install --dry-run` 预览所有操作,不做任何改动 |
-| 🧩 **可插拔架构** | 不信任某个组件?换掉对应的 channel 文件即可,不影响其他 |
+所有 Agent 命令都输出一个 JSON:
-### 🍪 Cookie 安全建议
+```json
+{"schema_version": 1, "ok": true, "channel": "v2ex", "action": "hot", "backend": "v2ex-api",
+ "items": [{"title": "...", "url": "...", "text": "..."}], "meta": {}, "error": null}
+```
-> ⚠️ **封号风险提醒:** 使用 Cookie 登录的平台(Twitter、小红书等),通过脚本/API 调用**存在被平台检测并封号的风险**。请务必使用**专用小号**,不要用你的主账号。
+失败时 `ok` 为 `false`,`error` 里有 `code`(`NEED_SETUP` / `NEED_LOGIN` / `UPSTREAM_BROKEN` / `TIMEOUT` / `RATE_LIMITED` / `NOT_FOUND` / `BAD_INPUT`)、`message` 和给 Agent 的 `hint`。
-需要 Cookie 或登录态的平台(Twitter、小红书、Reddit、Facebook、Instagram 等)建议使用**专用小号**,不要用主账号。原因有二:
-1. **封号风险** — 平台可能检测到非正常浏览器的 API 调用行为,导致账号被限制或封禁
-2. **安全风险** — Cookie 等同于完整登录权限,用小号可以在凭据泄露时限制影响范围
+---
-### 📦 安装方式
+## 安全性
-| 方式 | 命令 | 适合场景 |
-|------|------|---------|
-| 默认安全检查 | `agent-reach install --env=auto` | 所有环境;只读检查并列出缺失项 |
-| 显式安装系统依赖 | `agent-reach install --env=auto --system` | 你明确允许修改当前机器时 |
-| 兼容安全参数 | `agent-reach install --env=auto --safe` | 与默认行为相同 |
-| 仅预览 | `agent-reach install --env=auto --dry-run` | 先看看会做什么 |
+- **所有东西都在 `~/.agent-reach/` 下**:`config.yaml`(Key 和代理)、`state.json`、`tools/`(私有工具)、`sessions/`(命令行工具的登录状态)、`browser/`(专用浏览器的资料目录)、`mcporter.json`。
+- **从不替你登录,也不读你自己浏览器的 Cookie。** 需要登录的渠道,由你本人在 Agent Reach 专用浏览器或工具自己的登录流程(比如 B站扫码)里完成。
+- **专用浏览器的调试端口只监听本机**(127.0.0.1:9222),但本机任何程序都能通过它控制这个浏览器。不用的时候请关掉那个窗口。
+- **建议用小号登录。** 平台可能限制自动化访问的账号,别拿主账号冒险。
+- **API Key 不要发在聊天里**:在你自己的终端运行 `agent-reach configure groq-key`,会隐藏输入。
### 🗑️ 卸载
```bash
-agent-reach uninstall
-```
-
-会清除:`~/.agent-reach/`(含所有 token/cookie)、各 Agent 的 skill 文件、mcporter 中的 MCP 配置。
-
-```bash
-# 只预览,不实际删除
-agent-reach uninstall --dry-run
-
-# 只删 skill 文件,保留 token 配置(重装时用)
-agent-reach uninstall --keep-config
+agent-reach uninstall --dry-run # 先看会删哪些东西
+agent-reach uninstall # 删除 Agent Reach 装的工具、登录、配置和 skill
```
-卸载 Python 包本身:`pip uninstall agent-reach`
+卸载前先关掉 Agent Reach 专用浏览器。命令最后会告诉你怎么卸载程序本身(比如 `uv tool uninstall agent-reach`)。
---
@@ -311,7 +227,7 @@ Star 一下,下次需要的时候能找到。⭐
## 致谢
-[OpenCLI](https://github.com/jackwener/opencli) · [twitter-cli](https://github.com/public-clis/twitter-cli) · [rdt-cli](https://github.com/public-clis/rdt-cli) · [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) · [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [feedparser](https://github.com/kurtmckee/feedparser) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
+[OpenCLI](https://github.com/jackwener/opencli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [boss-agent-cli](https://github.com/can4hou6joeng4/boss-agent-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
## 联系
diff --git a/agent_reach/__init__.py b/agent_reach/__init__.py
index f60634ab..30c0bbd7 100644
--- a/agent_reach/__init__.py
+++ b/agent_reach/__init__.py
@@ -1,9 +1,6 @@
# -*- coding: utf-8 -*-
-"""Agent Reach — Give your AI Agent eyes to see the entire internet."""
+"""Agent Reach — internet access for AI agents."""
__version__ = "1.5.0"
-__author__ = "Neo Reid"
-from agent_reach.core import AgentReach
-
-__all__ = ["AgentReach"]
+__all__ = ["__version__"]
diff --git a/agent_reach/backends/__init__.py b/agent_reach/backends/__init__.py
index fa7ff2db..51bc7094 100644
--- a/agent_reach/backends/__init__.py
+++ b/agent_reach/backends/__init__.py
@@ -2,15 +2,8 @@
"""Cross-channel backends.
A backend here is an upstream runtime that serves MULTIPLE channels
-(e.g. OpenCLI covers xiaohongshu/reddit/bilibili/twitter through one
-browser session), as opposed to the per-platform tools probed inside
-each channel file.
+(e.g. OpenCLI covers xiaohongshu/reddit/twitter/facebook/instagram through
+the Agent Reach browser).
"""
-from .opencli import ( # noqa: F401
- OPENCLI_EXTENSION_URL,
- OPENCLI_PACKAGE,
- OpenCLIStatus,
- opencli_status,
- opencli_summary,
-)
+from .opencli import OPENCLI_EXTENSION_URL, opencli_call, opencli_items # noqa: F401
diff --git a/agent_reach/backends/opencli.py b/agent_reach/backends/opencli.py
index 751d157b..939e81d7 100644
--- a/agent_reach/backends/opencli.py
+++ b/agent_reach/backends/opencli.py
@@ -1,203 +1,18 @@
# -*- coding: utf-8 -*-
-"""OpenCLI backend probing.
+"""OpenCLI backend: run `opencli <site> ...` in the Agent Reach browser.
-OpenCLI (github.com/jackwener/opencli) drives the user's real Chrome via a
-browser-bridge extension + local daemon, reusing existing login sessions —
-zero per-platform configuration, desktop-only (no headless).
-
-Probing notes (verified live):
- - `opencli doctor` AUTO-STARTS the daemon — a side effect, so health
- checks must never use it.
- - Current OpenCLI startup also mutates ``~/.opencli`` before handling
- ``daemon status``. Only ``--version`` is a side-effect-free CLI fast path;
- live daemon state is read from its documented loopback ``/status`` API.
- - "Extension: disconnected" can mean a sleeping service worker, a disabled
- extension, or an extension that was never loaded. Disk files distinguish
- possible installation sources, but only a live daemon connection proves
- the browser actually loaded and enabled the extension.
+OpenCLI (github.com/jackwener/opencli) drives Chrome through a browser-bridge
+extension + local daemon. Agent Reach binds it to its own dedicated browser
+profile (see agent_reach.runtime.browser) and never touches the user's Chrome.
"""
-import glob
import json
-import os
-import urllib.request
-from dataclasses import dataclass
-
-from agent_reach.probe import probe_command
-OPENCLI_PACKAGE = "@jackwener/opencli"
OPENCLI_EXTENSION_ID = "ildkmabpimmkaediidaifkhjpohdnifk"
OPENCLI_EXTENSION_URL = (
f"https://chromewebstore.google.com/detail/opencli/{OPENCLI_EXTENSION_ID}"
)
-# OpenCLIApp 0.1.35 injected this now-unsupported variable into every child.
-# OpenCLI >=1.8.5 rejects it before even handling ``--version``. Doctor is a
-# read-only observer, so strip the stale app setting only from its child probes.
-_UNSUPPORTED_APP_ENV = ("OPENCLI_DAEMON_PORT",)
-
-#: Chromium-family profile roots that contain <Profile>/Extensions/<id>/
-_CHROME_PROFILE_ROOTS = (
- "~/Library/Application Support/Google/Chrome", # macOS Chrome
- "~/Library/Application Support/Chromium", # macOS Chromium
- "~/Library/Application Support/Microsoft Edge", # macOS Edge
- "~/.config/google-chrome", # Linux Chrome
- "~/.config/chromium", # Linux Chromium
- "~/.config/microsoft-edge", # Linux Edge
-)
-
-_OPENCLI_UNPACKED_EXTENSION = "~/.opencli/extension"
-_OPENCLI_DAEMON_STATUS_URL = "http://127.0.0.1:19825/status"
-_MAX_DAEMON_STATUS_BYTES = 64 * 1024
-
-
-def _fetch_daemon_status(timeout: int = 2):
- """Read OpenCLI's loopback status endpoint without starting the CLI."""
- request = urllib.request.Request(
- _OPENCLI_DAEMON_STATUS_URL,
- headers={"X-OpenCLI": "1"},
- method="GET",
- )
- opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
- try:
- with opener.open(request, timeout=min(timeout, 2)) as response:
- raw = response.read(_MAX_DAEMON_STATUS_BYTES + 1)
- except Exception:
- return None
- if len(raw) > _MAX_DAEMON_STATUS_BYTES:
- return None
- try:
- payload = json.loads(raw.decode("utf-8"))
- except (UnicodeDecodeError, json.JSONDecodeError):
- return None
- if not isinstance(payload, dict) or payload.get("ok") is not True:
- return None
- return payload
-
-
-def _extension_installed_on_disk() -> bool:
- """True if store-installed OpenCLI files exist in a browser profile.
-
- This is disk evidence only: a user may have disabled or removed the
- extension while stale files remain, so callers must not treat it as proof
- that the extension is loaded, connected, or usable.
- """
- roots = [os.path.expanduser(p) for p in _CHROME_PROFILE_ROOTS]
- local_app_data = os.environ.get("LOCALAPPDATA")
- if local_app_data: # Windows
- roots.append(os.path.join(local_app_data, "Google", "Chrome", "User Data"))
- roots.append(os.path.join(local_app_data, "Microsoft", "Edge", "User Data"))
- for root in roots:
- if glob.glob(os.path.join(root, "*", "Extensions", OPENCLI_EXTENSION_ID)):
- return True
- return False
-
-
-def _unpacked_extension_files_present() -> bool:
- """True when OpenCLI's unpacked extension source contains a manifest.
-
- ``~/.opencli/extension`` is downloaded source, not browser state. Its
- existence never proves the user completed “Load unpacked” or left the
- extension enabled.
- """
- unpacked = os.path.expanduser(_OPENCLI_UNPACKED_EXTENSION)
- return os.path.isfile(os.path.join(unpacked, "manifest.json"))
-
-
-@dataclass
-class OpenCLIStatus:
- installed: bool = False
- broken: bool = False
- daemon_running: bool = False
- extension_connected: bool = False
- extension_installed: bool = False
- unpacked_extension_files: bool = False
- version: str = ""
- hint: str = ""
-
- @property
- def ready(self) -> bool:
- """True only when the backend is provably usable now.
-
- Only a live daemon connection proves that a browser loaded and enabled
- the extension. Disk files alone are deliberately not enough.
- """
- return self.installed and not self.broken and self.extension_connected
-
-
-def opencli_status(timeout: int = 10) -> OpenCLIStatus:
- """Probe OpenCLI install + daemon/extension state without side effects."""
- version_probe = probe_command(
- "opencli",
- ["--version"],
- timeout=timeout,
- package=OPENCLI_PACKAGE,
- remove_env=_UNSUPPORTED_APP_ENV,
- )
- if version_probe.status == "missing":
- return OpenCLIStatus(installed=False)
- if not version_probe.ok:
- return OpenCLIStatus(
- installed=True,
- broken=True,
- hint=(
- "opencli 命令存在但无法执行(node 环境损坏),重装:\n"
- f" npm install -g {OPENCLI_PACKAGE}"
- ),
- )
-
- st = OpenCLIStatus(installed=True, version=version_probe.output.strip())
-
- daemon_status = _fetch_daemon_status(timeout)
- if daemon_status is not None:
- st.daemon_running = True
- st.extension_connected = bool(
- daemon_status.get("extensionConnected")
- )
-
- if not st.extension_connected:
- st.extension_installed = _extension_installed_on_disk()
- st.unpacked_extension_files = _unpacked_extension_files_present()
- if st.extension_installed:
- st.hint = (
- "检测到 Chrome/Edge 的 OpenCLI 扩展文件,但扩展当前未连接;"
- "仅凭磁盘文件无法确认它已加载或启用。\n"
- " 打开浏览器扩展页确认 OpenCLI 已启用,再运行一个 opencli 命令验证"
- )
- elif st.unpacked_extension_files:
- st.hint = (
- "检测到 ~/.opencli/extension/ 源文件,但文件存在不代表已经在"
- " Chrome/Edge 中“加载已解压的扩展程序”。\n"
- " 请在浏览器扩展页加载并启用该目录,再运行一个 opencli 命令验证"
- )
- else:
- st.hint = (
- "OpenCLI 已安装,但未检测到已连接的浏览器扩展。\n"
- f" 1. 安装并启用扩展(Chrome/Edge):{OPENCLI_EXTENSION_URL}\n"
- " 2. 保持浏览器打开,再运行一个 opencli 命令验证"
- )
- return st
-
-
-def opencli_summary(st: OpenCLIStatus) -> str:
- """One-line state description for channel messages / install output."""
- if not st.installed:
- return "OpenCLI 未安装"
- if st.broken:
- return "OpenCLI 无法执行(node 环境损坏)"
- if st.extension_connected:
- return f"OpenCLI 可用(浏览器登录态,v{st.version})"
- if st.extension_installed:
- return "OpenCLI 已安装,检测到扩展文件但当前未连接(无法确认已加载)"
- if st.unpacked_extension_files:
- return "OpenCLI 已安装,检测到 unpacked 源文件但尚未确认浏览器已加载"
- if st.daemon_running:
- return "OpenCLI 已安装,等待 Chrome 扩展安装"
- return "OpenCLI 已安装(daemon 未运行,使用时自动启动;需 Chrome 扩展)"
-
-
-# ── unified entry: run one OpenCLI site command ──
-
_NAV_REJECTED_HINT = (
"OpenCLI's browser extension could not open the page. This is a known open "
"OpenCLI issue on recent Chrome (github.com/jackwener/opencli/issues/2487); "
diff --git a/agent_reach/channels/__init__.py b/agent_reach/channels/__init__.py
index a748cce4..d32d1d90 100644
--- a/agent_reach/channels/__init__.py
+++ b/agent_reach/channels/__init__.py
@@ -1,21 +1,18 @@
# -*- coding: utf-8 -*-
"""
-Channel registry — lists all supported platforms for doctor checks.
+Channel registry — every platform exposed by `agent-reach <channel> <action>`.
"""
from typing import List, Optional
-# Import all channels
from .base import Channel
from .bilibili import BilibiliChannel
from .boss import BossChannel
-from .exa_search import ExaSearchChannel
from .facebook import FacebookChannel
from .github import GitHubChannel
from .instagram import InstagramChannel
from .linkedin import LinkedInChannel
from .reddit import RedditChannel
-from .rss import RSSChannel
from .twitter import TwitterChannel
from .v2ex import V2EXChannel
from .web import WebChannel
@@ -38,8 +35,6 @@ ALL_CHANNELS: List[Channel] = [
XiaoyuzhouChannel(),
V2EXChannel(),
XueqiuChannel(),
- RSSChannel(),
- ExaSearchChannel(),
WebChannel(),
]
diff --git a/agent_reach/channels/_opencli_site.py b/agent_reach/channels/_opencli_site.py
index 38df41a7..09688282 100644
--- a/agent_reach/channels/_opencli_site.py
+++ b/agent_reach/channels/_opencli_site.py
@@ -9,19 +9,13 @@ from .base import Channel
class OpenCLISiteChannel(Channel):
- """A platform served directly by OpenCLI.
-
- These channels are intentionally thin: Agent Reach only installs,
- health-checks, and routes. Agents call `opencli <site> ...` directly.
- """
+ """A platform served only through OpenCLI in the Agent Reach browser."""
site: str = ""
domains: tuple[str, ...] = ()
usage: str = ""
login_hint: str = ""
- backends = ["OpenCLI"]
- tier = 1
tools = ("opencli",)
prereqs = ("node", "chrome")
@@ -33,28 +27,6 @@ class OpenCLISiteChannel(Channel):
def can_handle(self, url: str) -> bool:
return host_matches(url, *self.domains)
- def check(self, config=None):
- from agent_reach.backends import opencli_status
-
- self.active_backend = None
- st = opencli_status()
- if not st.installed:
- return "off", (
- f"未安装 {self.description} 后端。安装:\n"
- " agent-reach install --system --channels opencli\n"
- f"然后在 Chrome 里登录 {self.login_hint}"
- )
- if st.broken:
- return "error", st.hint
-
- if st.ready:
- return "warn", (
- f"OpenCLI 桥接已连接,但 {self.description} 的登录态和实际命令"
- "未实时验证;Doctor 不执行平台命令,因此当前不标记为可用。"
- f"需要时请先在 Chrome 里登录 {self.login_hint}"
- )
- return "warn", st.hint
-
# ── unified entry helper ──
def _opencli(self, args, timeout: float, *, empty_is_error: bool = True) -> list:
diff --git a/agent_reach/channels/base.py b/agent_reach/channels/base.py
index 33863137..f4404840 100644
--- a/agent_reach/channels/base.py
+++ b/agent_reach/channels/base.py
@@ -1,25 +1,14 @@
# -*- coding: utf-8 -*-
"""
-Channel base class — platform availability checking.
-
-Each channel represents a platform (YouTube, Twitter, GitHub, etc.)
-and provides:
- - can_handle(url) → does this URL belong to this platform?
- - check(config) → is the upstream tool installed and configured?
-
-After installation, agents call upstream tools directly.
-
-Backend routing semantics:
- - `backends` is an ORDERED candidate list: backends[0] is the preferred
- backend, the rest are fallbacks. "Switching backends" for a platform
- means reordering this list (or a user override) — not rewriting code.
- - check() must set `self.active_backend` to the backend that is actually
- serving the channel right now (None when nothing usable is found).
- shutil.which() alone is NOT proof of health — a stale venv shim passes
- which() but cannot execute (see agent_reach.probe). Channels should
- really execute a lightweight command before claiming a backend active.
- - Users can force a backend with config key `<channel>_backend`
- (or env var `<CHANNEL>_BACKEND`); ordered_backends() applies it.
+Channel base class.
+
+Each channel represents a platform (YouTube, GitHub, V2EX, ...) and declares:
+ - can_handle(url) → does this URL belong to this platform? (used by `read`)
+ - level → "default" / "optional" / "experimental"
+ - actions → unified actions (`agent-reach <channel> <action>`), each with an
+ ordered list of (backend label, method name); the dispatcher tries them in
+ order and falls back on retryable errors.
+ - tools / prereqs / session / login_* → what `add`, `login` and `doctor` need.
"""
from abc import ABC, abstractmethod
@@ -62,12 +51,8 @@ class Channel(ABC):
name: str = "" # e.g. "youtube"
description: str = "" # e.g. "YouTube 视频和字幕"
- backends: List[str] = [] # ordered candidates — backends[0] = preferred
- tier: int = 0 # 0=zero-config, 1=needs free key, 2=needs setup
- #: Unified-entry tier: "default" / "optional" / "experimental".
- #: Empty means the channel is not on the unified entry yet. `tier` above
- #: is the legacy doctor grouping and goes away at cutover.
+ #: "default" / "optional" / "experimental".
level: str = ""
#: Unified actions this channel exposes.
actions: Tuple[Action, ...] = ()
@@ -107,37 +92,7 @@ class Channel(ABC):
"""
return None
- #: Backend currently serving this channel; set by check(), None = unavailable.
- active_backend: Optional[str] = None
-
@abstractmethod
def can_handle(self, url: str) -> bool:
"""Check if this channel can handle this URL."""
...
-
- def ordered_backends(self, config=None) -> List[str]:
- """Candidate backends in probe order, honoring the user override.
-
- The config key `<channel>_backend` (env `<CHANNEL>_BACKEND`) moves the
- named backend to the front of the list; unknown values are ignored so
- a stale override can never hide working backends.
- """
- candidates = list(self.backends)
- override = config.get(f"{self.name}_backend") if config else None
- if override:
- for i, b in enumerate(candidates):
- if b == override or b.startswith(override):
- candidates.insert(0, candidates.pop(i))
- break
- return candidates
-
- def check(self, config=None) -> Tuple[str, str]:
- """
- Check if this channel's upstream tool is available.
- Returns (status, message) where status is 'ok'/'warn'/'off'/'error'.
-
- Subclasses with external backends must really probe them (see
- agent_reach.probe.probe_command) and set self.active_backend.
- """
- self.active_backend = self.backends[0] if self.backends else "内置"
- return "ok", f"{'、'.join(self.backends) if self.backends else '内置'}"
diff --git a/agent_reach/channels/bilibili.py b/agent_reach/channels/bilibili.py
index 72cce46a..98b592a7 100644
--- a/agent_reach/channels/bilibili.py
+++ b/agent_reach/channels/bilibili.py
@@ -13,7 +13,6 @@ import json
import re
import urllib.request
-from agent_reach.probe import probe_command
from agent_reach.runtime.result import (
BAD_INPUT,
NEED_LOGIN,
@@ -115,26 +114,11 @@ def _bili_api(path: str, timeout: float) -> dict:
_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
-_TIMEOUT = 10
-_SEARCH_API = "https://api.bilibili.com/x/web-interface/search/all/v2?keyword=test&page=1"
-
-
-def _search_api_ok() -> bool:
- """Return True if Bilibili search API responds with code 0."""
- req = urllib.request.Request(_SEARCH_API, headers={"User-Agent": _UA})
- try:
- with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
- data = json.loads(resp.read())
- return data.get("code") == 0
- except Exception:
- return False
class BilibiliChannel(Channel):
name = "bilibili"
description = "B站视频、字幕和搜索"
- backends = ["bili-cli", "OpenCLI", "B站搜索 API"]
- tier = 1
level = "optional"
session = "bili-cli"
@@ -180,81 +164,6 @@ class BilibiliChannel(Channel):
return host_matches(url, "bilibili.com", "b23.tv")
- def check(self, config=None):
- """Probe candidates in order; first fully-usable backend wins."""
- self.active_backend = None
- findings = []
-
- for backend in self.ordered_backends(config):
- if backend == "bili-cli":
- result = self._check_bili_cli()
- elif backend == "OpenCLI":
- result = self._check_opencli()
- else:
- result = self._check_search_api()
- if result is None:
- continue
- findings.append((backend, *result))
-
- # 有后端断链时,即使别的候选兜底成功也要把处方带出来
- broken_notes = [m for _, s, m in findings if s == "error"]
-
- for wanted in ("ok", "warn"):
- for backend, status, message in findings:
- if status == wanted:
- self.active_backend = backend if status == "ok" else None
- if broken_notes:
- message += "\n[备选后端异常] " + ";".join(broken_notes)
- return status, message
-
- if findings:
- return "error", "\n".join(m for _, _, m in findings)
-
- return "off", (
- "没有可用的 B站后端(搜索 API 也不可达,可能是网络问题)。推荐:\n"
- " pipx install bilibili-cli(搜索/热门/视频详情,无需登录)\n"
- " 或桌面装 OpenCLI(额外解锁字幕):agent-reach install --system --channels opencli"
- )
-
- def _check_bili_cli(self):
- """bili-cli candidate. None = not installed."""
- probe = probe_command("bili", ["--version"], timeout=10, package="bilibili-cli")
- if probe.status == "missing":
- return None
- if probe.status == "broken":
- return "error", "bili 命令存在但无法执行\n" + probe.hint
- if not probe.ok:
- return "warn", f"bili-cli 探测失败({probe.status}),运行 `bili status` 查看详情"
- return "ok", (
- "bili-cli 可用(搜索/热门/排行/视频详情/音频,无需登录;"
- "字幕需 OpenCLI。上游 2026-03 起停更)"
- )
-
- def _check_opencli(self):
- """OpenCLI candidate. None = not installed."""
- from agent_reach.backends import opencli_status
-
- st = opencli_status()
- if not st.installed:
- return None
- if st.broken:
- return "error", st.hint
- if st.ready:
- return "warn", (
- "OpenCLI 桥接已连接,但 Bilibili 页面、登录态和实际命令"
- "未实时验证;Doctor 不执行平台命令,因此当前不标记为可用。"
- )
- return "warn", st.hint
-
- def _check_search_api(self):
- """Zero-dependency search API fallback. None = unreachable."""
- if not _search_api_ok():
- return None
- return "ok", (
- "B站搜索 API 可达(仅搜索,curl 直连)。"
- "完整功能建议安装 bili-cli:pipx install bilibili-cli"
- )
-
# ── unified entry backends ──
def _cli_search(self, *, query: str, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/boss.py b/agent_reach/channels/boss.py
index e8c272f2..37951eba 100644
--- a/agent_reach/channels/boss.py
+++ b/agent_reach/channels/boss.py
@@ -1,40 +1,19 @@
# -*- coding: utf-8 -*-
-"""Boss直聘 — 经 boss-agent-cli + CDP 真 Chrome 搜岗位、取 JD。
+"""Boss直聘 — boss-agent-cli drives the Agent Reach browser over CDP (127.0.0.1:9222).
-后端是 boss-agent-cli(CDP 调试端口复用已登录的真 Chrome)。headless 是禁区
-(触发 code 36 风控),故 check() 只做四层只读探测,不实例化 BossClient、不拉起浏览器。
+headless is off-limits (triggers code 36 risk control), so search only runs
+against the already-running Agent Reach browser with the user's own login.
-抓取走 boss-agent-cli 公开 API(search_jobs + job_card_browser + browser_source="existing-browser"),
-调用姿势见 skill/references/career.md;check() 只负责「装没装 + CDP 链路就绪 +
-浏览器内有无登录 cookie」的体检,不搜索。
-
-双登录态存储(体检必须区分,历史教训)。两者都是必需的,但认证的是不同通道:
-
-- `~/.boss-agent/auth/session.enc`(`boss status` / `status --live` 只校验它)
- 1. 是硬性门槛:`_get_browser()` 无条件 `get_token()`,读不到就 `AuthRequired`,
- 所以别删它——CDP 搜索会在连上浏览器之前就失败;
- 2. 但**不是搜索的认证凭据**:CDP 连上真 Chrome 后复用 `contexts[0]`,其 cookies
- 只在「没有任何 context」的分支才注入,实际从未生效;
- 3. httpx 通道(低危 op:status/detail/cities/`job_card_httpx`)真用它的
- cookies + stoken;code 37 的 `force_refresh()` 也回写它。
-- 专用 Chrome profile 内的浏览器 cookie:CDP 模式下 search/greet 等高危 op
- 实际携带的凭据。
-
-所以 session.enc 有效 + 浏览器未登录 = `boss status` 报已登录但搜索报
-`AUTH_EXPIRED`。第 4 层直接问 CDP 浏览器本体(Storage.getCookies),以浏览器为准。
+Two login stores, both required:
+- the session under ~/.agent-reach/sessions/boss-agent-cli/ (`boss login --cdp`
+ writes it; boss-agent-cli refuses to start without it);
+- the browser cookies in the Agent Reach browser profile, which the search
+ actually sends.
"""
-import base64
-import hashlib
import json
-import os
-import platform
import socket
-import struct
-import urllib.request
-from urllib.parse import urlparse
-from agent_reach.probe import probe_command
from agent_reach.runtime.result import (
NEED_LOGIN,
NEED_SETUP,
@@ -49,222 +28,11 @@ from agent_reach.utils.url import host_matches
from .base import Action, Channel, Param
_CDP_URL = "http://localhost:9222"
-_CDP_TIMEOUT = 5
-
-
-def _chrome_launch_command(system: str | None = None) -> str:
- """Return a dedicated-profile Chrome command for the current OS."""
- system = system or platform.system()
- common = (
- "--remote-debugging-address=127.0.0.1 "
- "--remote-debugging-port=9222 "
- )
- url = '"https://www.zhipin.com/web/geek/job"'
- if system == "Darwin":
- return (
- 'open -na "Google Chrome" --args '
- + common
- + '--user-data-dir="$HOME/.boss-chrome-profile" '
- + url
- )
- if system == "Windows":
- return (
- "Start-Process chrome.exe -ArgumentList "
- "'--remote-debugging-address=127.0.0.1',"
- "'--remote-debugging-port=9222',"
- '"--user-data-dir=$env:USERPROFILE\\.boss-chrome-profile",'
- "'https://www.zhipin.com/web/geek/job'"
- )
- return (
- "google-chrome "
- + common
- + '--user-data-dir="$HOME/.boss-chrome-profile" '
- + url
- )
-
-
-def _cdp_json(path: str):
- """GET 本地 CDP 端点(禁用系统代理),返回解析后的 JSON;失败返回 None。
-
- CDP 只绑定回环地址(127.0.0.1),直连即可,故用空 ProxyHandler 显式绕过任何
- 已配置的系统/全局代理——localhost 探测走代理既无意义也可能被拦截。这是有意的
- localhost-only 假设,不可被 config 的 proxy 覆盖。
- """
- req = urllib.request.Request(f"{_CDP_URL}{path}", method="GET")
- opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
- try:
- with opener.open(req, timeout=_CDP_TIMEOUT) as resp:
- return json.loads(resp.read())
- except Exception:
- return None
-
-
-def _has_zhipin_page(pages) -> bool:
- """CDP /json 页签列表里是否存在可复用的 zhipin.com 页签(精确 hostname 校验)。"""
- for page in pages or []:
- if page.get("type") == "page" and host_matches(page.get("url", ""), "zhipin.com"):
- return True
- return False
-
-
-_SECURITY_CHECK_MARKERS = ("security-check", "zhipin-security", "_security_check")
-
-
-def _security_check_blocks_all(pages) -> bool:
- """现有 zhipin 页签是否全部停在反爬安全校验页(不是登录页)。"""
- zhipin_urls = [
- page.get("url", "")
- for page in (pages or [])
- if page.get("type") == "page" and host_matches(page.get("url", ""), "zhipin.com")
- ]
- if not zhipin_urls:
- return False
- return all(
- any(marker in url.lower() for marker in _SECURITY_CHECK_MARKERS)
- for url in zhipin_urls
- )
-
-
-_WS_ACCEPT_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
-
-
-def _read_ws_text_frame(sock: socket.socket, initial: bytes = b""):
- """读下一个文本帧,返回 (payload, leftover)。
-
- leftover 是本次 recv 多收、属于后续帧的字节,调用方应把它作为下一帧的 initial
- 传回(一次 recv 可能拿到多帧)。收到 close 帧或连接断开返回 (None, leftover)。
- 忽略 ping/pong。
- """
- buf = initial
- while True:
- while len(buf) < 2:
- chunk = sock.recv(4096)
- if not chunk:
- return None, buf
- buf += chunk
- opcode = buf[0] & 0x0F
- length = buf[1] & 0x7F
- header_len = 2
- if length == 126:
- while len(buf) < header_len + 2:
- chunk = sock.recv(4096)
- if not chunk:
- return None, buf
- buf += chunk
- length = struct.unpack(">H", buf[header_len:header_len + 2])[0]
- header_len += 2
- elif length == 127:
- while len(buf) < header_len + 8:
- chunk = sock.recv(4096)
- if not chunk:
- return None, buf
- buf += chunk
- length = struct.unpack(">Q", buf[header_len:header_len + 8])[0]
- header_len += 8
- while len(buf) < header_len + length:
- chunk = sock.recv(4096)
- if not chunk:
- return None, buf
- buf += chunk
- payload = buf[header_len:header_len + length]
- buf = buf[header_len + length:]
- if opcode == 0x8: # close
- return None, buf
- if opcode in (0x1, 0x2, 0x0): # text / binary / continuation
- return payload, buf
- # ping(0x9)/pong(0xA) 等:忽略,继续读下一帧
-
-
-def _send_ws_text(sock: socket.socket, text: str) -> None:
- payload = text.encode("utf-8")
- mask = os.urandom(4)
- masked = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
- header = bytes([0x81]) # FIN + text
- n = len(payload)
- if n < 126:
- header += bytes([0x80 | n])
- elif n < 65536:
- header += bytes([0x80 | 126]) + struct.pack(">H", n)
- else:
- header += bytes([0x80 | 127]) + struct.pack(">Q", n)
- sock.sendall(header + mask + masked)
-
-
-def _cdp_zhipin_login_cookie() -> bool | None:
- """只读探测专用 Chrome 浏览器内的 zhipin.com 登录 cookie(wt2)。
-
- True=有;False=没有(浏览器未登录,CDP 搜索会报 AUTH_EXPIRED);
- None=探测失败(CDP WebSocket 不可达等),登录态未知。
- 只证明浏览器 profile 登录过,不验证 cookie 的服务端有效性。
- """
- version = _cdp_json("/json/version")
- ws_url = (version or {}).get("webSocketDebuggerUrl")
- if not ws_url:
- return None
- parsed = urlparse(ws_url)
- host = parsed.hostname or "127.0.0.1"
- port = parsed.port or 80
- path = parsed.path or "/"
- try:
- with socket.create_connection((host, port), timeout=_CDP_TIMEOUT) as sock:
- sock.settimeout(_CDP_TIMEOUT)
- key = base64.b64encode(os.urandom(16)).decode()
- # IPv6 字面量需在 Host 头里加方括号(urlparse().hostname 已剥掉)
- host_header = f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
- handshake = (
- f"GET {path} HTTP/1.1\r\n"
- f"Host: {host_header}\r\n"
- "Upgrade: websocket\r\n"
- "Connection: Upgrade\r\n"
- f"Sec-WebSocket-Key: {key}\r\n"
- "Sec-WebSocket-Version: 13\r\n"
- "\r\n"
- )
- sock.sendall(handshake.encode())
- response = b""
- while b"\r\n\r\n" not in response:
- chunk = sock.recv(4096)
- if not chunk:
- return None
- response += chunk
- head, _, rest = response.partition(b"\r\n\r\n")
- status_line = head.split(b"\r\n", 1)[0]
- # 精确解析状态码 token:接受 "HTTP/1.1 101"(可空 reason 短语),拒绝 1019 等伪码
- if status_line.split()[1:2] != [b"101"]:
- return None
- accept = base64.b64encode(
- hashlib.sha1((key + _WS_ACCEPT_GUID).encode()).digest()
- ).decode()
- if accept not in head.decode("latin-1"):
- return None
- _send_ws_text(sock, json.dumps({"id": 1, "method": "Storage.getCookies"}))
- # Chrome 可能先推事件帧(无 id);持续读帧直到拿到 id==1 的响应(设上限防死循环)。
- # leftover 携带上次 recv 多收的字节,确保一次 recv 到多帧时不丢数据。
- buf = rest
- for _ in range(16):
- payload, buf = _read_ws_text_frame(sock, initial=buf)
- if payload is None:
- return None
- data = json.loads(payload.decode("utf-8"))
- if data.get("id") != 1:
- continue # 事件帧等:跳过,读下一帧
- if "result" not in data:
- return None
- for cookie in data["result"].get("cookies", []):
- if cookie.get("name") == "wt2" and "zhipin" in cookie.get("domain", ""):
- return True
- return False
- return None
- except Exception:
- return None
class BossChannel(Channel):
name = "boss"
description = "Boss直聘 职位搜索与 JD"
- backends = ["boss-agent-cli (CDP)"]
- tier = 2
-
level = "optional"
login_url = "https://www.zhipin.com/web/user/?ka=header-login"
session = "boss-agent-cli"
@@ -290,82 +58,6 @@ class BossChannel(Channel):
def can_handle(self, url: str) -> bool:
return host_matches(url, "zhipin.com")
- def check(self, config=None):
- self.active_backend = None
-
- # 层 1:boss-agent-cli 装没装
- probe = probe_command("boss", ["--version"], timeout=10)
- if probe.status == "missing":
- return "off", (
- "boss-agent-cli 未安装。请先获得用户授权,再运行:\n"
- " agent-reach install --system --channels=boss\n"
- "安装后由用户在专用 Chrome 中手动登录 zhipin.com。"
- )
- if probe.status == "broken":
- return "error", (
- "boss 命令存在但无法执行——安装已损坏。重装:\n"
- " agent-reach install --system --channels=boss"
- )
- if not probe.ok:
- return "warn", f"boss 命令探测失败({probe.status}),请检查安装"
-
- # 层 2:CDP 端口通不通
- if _cdp_json("/json/version") is None:
- return "off", (
- "CDP 调试端口不可达。请先启动调试 Chrome:\n"
- f" {_chrome_launch_command()}\n"
- " 然后由用户在该窗口手动登录 zhipin.com。\n"
- "仅绑定 127.0.0.1;任何能访问 9222 的进程都可完全控制这个 Chrome。"
- )
-
- # 层 3:有无可复用 BOSS 页签
- pages = _cdp_json("/json")
- if pages is None:
- return "warn", "CDP 端口可达但 /json 页签枚举失败"
- if not _has_zhipin_page(pages):
- return "warn", (
- "CDP 可达但未发现现成 zhipin.com 页签(不代表未登录:Cookie 可能仍在,"
- "boss-agent-cli 会自行新建页签)。建议先在 Chrome 登录 zhipin.com。"
- )
-
- # 层 4:浏览器内登录 cookie(wt2)。以浏览器为准——`boss status` 只校验
- # 本地 session.enc,与浏览器登录态互不代表。
- browser_cookie = _cdp_zhipin_login_cookie()
- if browser_cookie is False:
- return "warn", (
- "CDP 链路就绪,但专用 Chrome 浏览器内没有 zhipin.com 登录 cookie(wt2)"
- "——浏览器未登录,搜索会报 AUTH_EXPIRED。注意 `boss status` 报的 logged_in "
- "只代表本地 session.enc 凭据,不代表浏览器已登录。请让用户在该 Chrome 窗口"
- "肉眼确认并登录 zhipin.com(拉起 CDP Chrome 后应先做这一步),然后运行 "
- "`boss --cdp-url http://localhost:9222 login --cdp` 同步登录态。"
- )
-
- cookie_note = (
- "浏览器内有登录 cookie(wt2)" if browser_cookie else "浏览器登录 cookie 探测失败,登录态未知"
- )
-
- if _security_check_blocks_all(pages):
- return "warn", (
- f"CDP 链路就绪,但现有 zhipin 页签都停在安全校验页"
- "(security-check / zhipin-security)。这是 Boss 反爬挑战,与登录无关"
- "——已登录也会出现,不代表未登录,不要据此要求用户重新登录,"
- "让用户手动过滑块即可。"
- f"浏览器登录态参考:{cookie_note}。"
- "不要用 `boss status` 判断 CDP 浏览器登录态(它只校验本地 session.enc)。"
- )
-
- # 四层探测全过:CDP 链路就绪,标记实际服役的后端(base 契约)
- self.active_backend = self.backends[0]
- return "warn", (
- f"CDP 链路就绪(9222 端口通 + 有可复用 zhipin 页签,{cookie_note})。"
- "Doctor 不实际执行搜索、不验证 cookie 服务端有效性或上游 boss-agent-cli #403-#407 API;"
- "先运行 `boss --cdp-url http://localhost:9222 login --cdp` 同步现有登录态;"
- "搜索时使用 `boss --browser-source existing-browser --cdp-url http://localhost:9222 search ...`,"
- "确保 CDP 不可用时立即停止而不是降级 headless。"
- "若搜索报 AUTH_EXPIRED,按登录 runbook 处理(用户在专用窗口登录 + login --cdp),"
- "不要往安全校验方向解释。"
- )
-
# ── unified entry backends ──
def _cli_search(self, *, query: str, city, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/exa_search.py b/agent_reach/channels/exa_search.py
deleted file mode 100644
index 74427ddc..00000000
--- a/agent_reach/channels/exa_search.py
+++ /dev/null
@@ -1,44 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Exa Search — check if mcporter + Exa MCP is available."""
-
-import shutil
-
-from .base import Channel
-from .mcporter import McporterConfigError, inspect_mcporter_config
-
-
-class ExaSearchChannel(Channel):
- name = "exa_search"
- description = "全网语义搜索"
- backends = ["Exa via mcporter"]
- tier = 0
-
- def can_handle(self, url: str) -> bool:
- return False # Search-only channel
-
- def check(self, config=None):
- self.active_backend = None
- if not shutil.which("mcporter"):
- return "off", (
- "需要 mcporter + Exa MCP。安装:\n"
- " npm install -g mcporter\n"
- " mcporter config add exa https://mcp.exa.ai/mcp --scope home"
- )
- try:
- inspection = inspect_mcporter_config()
- except McporterConfigError as exc:
- return "error", f"mcporter 配置检查失败:{exc}"
- if "exa" in inspection.server_names:
- return "warn", (
- "Exa 已写入 mcporter 配置,但 Doctor 未启动远端服务做"
- "连通验证,不能仅凭配置宣称可用。"
- )
- if inspection.imports_unchecked:
- return "warn", (
- "mcporter 本地配置未发现 Exa;配置还启用了 editor imports,"
- "Doctor 为避免扩大凭据读取范围没有展开,当前未验证。"
- )
- return "off", (
- "mcporter 已装但 Exa 未配置。运行:\n"
- " mcporter config add exa https://mcp.exa.ai/mcp --scope home"
- )
diff --git a/agent_reach/channels/github.py b/agent_reach/channels/github.py
index dc36ad4c..f56eb17c 100644
--- a/agent_reach/channels/github.py
+++ b/agent_reach/channels/github.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-"""GitHub — check if gh CLI is available."""
+"""GitHub — repositories, issues and PRs via gh CLI, falling back to the REST API."""
from __future__ import annotations
@@ -7,12 +7,8 @@ import json
import os
import re
import urllib.error
-from pathlib import Path
from urllib.parse import urlencode
-import yaml
-
-from agent_reach.probe import probe_command
from agent_reach.runtime.result import (
BAD_INPUT,
NEED_LOGIN,
@@ -22,10 +18,6 @@ from agent_reach.runtime.result import (
make_item,
)
from agent_reach.runtime.run import CommandFailed, http_request, run_cmd
-from agent_reach.utils.paths import (
- PrivatePathError,
- read_small_text_no_follow,
-)
from .base import Action, Channel, Param
@@ -36,7 +28,6 @@ _TARGET_RE = re.compile(
)
_README_MAX_CHARS = 50_000
-_MAX_HOSTS_BYTES = 1024 * 1024
_GH_READ_ONLY_ENV = {
# gh 2.92 creates ~/.local/state/gh/device-id even for `--version` unless
# telemetry is disabled. These are documented gh environment controls.
@@ -47,71 +38,6 @@ _GH_READ_ONLY_ENV = {
}
-class GitHubConfigError(ValueError):
- """Raised when gh credential metadata cannot be read safely."""
-
-
-def _gh_hosts_path() -> Path:
- override = os.environ.get("GH_CONFIG_DIR")
- if override:
- return Path(os.path.abspath(os.path.expanduser(override))) / "hosts.yml"
-
- xdg_config = os.environ.get("XDG_CONFIG_HOME")
- if xdg_config:
- return Path(xdg_config) / "gh" / "hosts.yml"
-
- if os.name == "nt":
- app_data = os.environ.get("APPDATA")
- if app_data:
- return Path(app_data) / "GitHub CLI" / "hosts.yml"
-
- return Path.home() / ".config" / "gh" / "hosts.yml"
-
-
-def _saved_github_host_configured() -> bool:
- """Inspect github.com's hosts.yml entry without executing gh."""
- hosts_path = _gh_hosts_path()
- try:
- raw = read_small_text_no_follow(
- hosts_path,
- max_bytes=_MAX_HOSTS_BYTES,
- )
- except (OSError, PrivatePathError, UnicodeError) as exc:
- raise GitHubConfigError("gh hosts.yml 无法安全读取") from exc
- if raw is None:
- return False
- try:
- payload = yaml.safe_load(raw)
- except yaml.YAMLError as exc:
- raise GitHubConfigError("gh hosts.yml 不是有效的 UTF-8 YAML") from exc
- if payload is None:
- return False
- if not isinstance(payload, dict):
- raise GitHubConfigError("gh hosts.yml 顶层必须是对象")
-
- host = payload.get("github.com")
- if host is None:
- return False
- if not isinstance(host, dict):
- raise GitHubConfigError("gh hosts.yml 的 github.com 配置无效")
-
- users = host.get("users")
- if users is not None and not isinstance(users, dict):
- raise GitHubConfigError("gh hosts.yml 的 users 配置无效")
- return bool(host.get("oauth_token") or host.get("user") or users)
-
-
-def _explicit_github_credentials(config) -> bool:
- if any(os.environ.get(name) for name in ("GH_TOKEN", "GITHUB_TOKEN")):
- return True
- if config is None:
- return False
- try:
- return bool(config.get("github_token"))
- except Exception as exc:
- raise GitHubConfigError("Agent Reach 的 GitHub 配置无法读取") from exc
-
-
def _parse_target(target: str):
"""owner/repo, a repo link, or an issue/PR link → (owner, repo, number|None)."""
m = _TARGET_RE.match(str(target).strip())
@@ -176,8 +102,6 @@ def _repo_item(repo: dict, readme: str | None = None) -> dict:
class GitHubChannel(Channel):
name = "github"
description = "GitHub 仓库和代码"
- backends = ["gh CLI"]
- tier = 0
level = "default"
actions = (
@@ -205,47 +129,6 @@ class GitHubChannel(Channel):
return host_matches(url, "github.com")
- def check(self, config=None):
- self.active_backend = None
- probe = probe_command(
- "gh",
- ["--version"],
- timeout=10,
- package="gh",
- env=_GH_READ_ONLY_ENV,
- )
- if probe.status == "missing":
- return "warn", "gh CLI 未安装。安装:https://cli.github.com"
- if probe.status == "broken":
- return "error", (
- "gh 命令存在但无法执行——安装已损坏。重装即可修复:\n"
- " brew reinstall gh\n"
- "或从 https://cli.github.com 重新安装 gh CLI"
- )
- if not probe.ok:
- detail = probe.hint or probe.status
- return "error", f"gh CLI 版本检查失败:{detail}"
-
- try:
- configured = _explicit_github_credentials(
- config
- ) or _saved_github_host_configured()
- except GitHubConfigError as exc:
- return "warn", (
- f"gh CLI 可执行,但认证配置无法安全确认:{exc}。"
- "Doctor 不执行会写 device-id 的 `gh auth status`,当前未验证。"
- )
-
- if configured:
- return "warn", (
- "gh CLI 可执行,且检测到显式认证配置;Doctor 不执行会写"
- " device-id 的 `gh auth status`,因此未实时验证,未标记为可用。"
- )
- return "warn", (
- "gh CLI 可执行,但未检测到显式认证配置。运行 `gh auth login` "
- "完成登录;Doctor 不会自动执行 `gh auth status`。"
- )
-
# ── unified entry backends ──
@staticmethod
diff --git a/agent_reach/channels/linkedin.py b/agent_reach/channels/linkedin.py
index c81c0dc8..6a088e62 100644
--- a/agent_reach/channels/linkedin.py
+++ b/agent_reach/channels/linkedin.py
@@ -1,27 +1,14 @@
# -*- coding: utf-8 -*-
-"""LinkedIn — check if mcp-server-linkedin is configured."""
+"""LinkedIn — job search through mcp-server-linkedin via mcporter."""
import json
-import shutil
from agent_reach.runtime.result import NEED_SETUP, UPSTREAM_BROKEN, ReachError, make_item
from agent_reach.runtime.run import CommandFailed, run_cmd
from .base import Action, Channel, Param
-from .mcporter import McporterConfigError, configured_server_names, inspect_mcporter_config
-
-_LINKEDIN_SERVER_NAMES = {
- "linkedin",
- "linkedin-scraper",
- "linkedin-scraper-mcp",
- "mcp-server-linkedin",
-}
-_LOGIN_COMMAND = "uvx mcp-server-linkedin@latest --login"
-_UV_INSTALL_URL = "https://docs.astral.sh/uv/getting-started/installation/"
-_CONFIG_COMMAND = (
- "mcporter config add linkedin --command uvx "
- "--arg mcp-server-linkedin@latest --env UV_HTTP_TIMEOUT=300 --scope home"
-)
+from .mcporter import configured_server_names
+
_LINKEDIN_MCP_VERSION = "4.26.2"
@@ -50,8 +37,6 @@ def _write_own_servers(servers: dict) -> None:
class LinkedInChannel(Channel):
name = "linkedin"
description = "LinkedIn 职业社交"
- backends = ["mcp-server-linkedin", "Jina Reader"]
- tier = 2
level = "optional"
tools = ("mcporter",)
@@ -102,43 +87,6 @@ class LinkedInChannel(Channel):
return host_matches(url, "linkedin.com")
- def check(self, config=None):
- self.active_backend = None
- if not shutil.which("mcporter"):
- return "off", (
- "基本内容可通过 Jina Reader 读取。完整功能需要:\n"
- f" 先安装 uv/uvx:{_UV_INSTALL_URL}\n"
- f" {_LOGIN_COMMAND}\n"
- f" {_CONFIG_COMMAND}\n"
- " 详见 https://github.com/stickerdaniel/linkedin-mcp-server"
- )
- try:
- inspection = inspect_mcporter_config()
- except McporterConfigError as exc:
- return "error", f"mcporter 配置检查失败:{exc}"
- if inspection.server_names & _LINKEDIN_SERVER_NAMES:
- if not shutil.which("uvx"):
- return "warn", (
- "LinkedIn MCP 已写入 mcporter 配置,但 uvx 未安装,"
- "当前无法启动服务。安装:\n"
- f" {_UV_INSTALL_URL}"
- )
- return "warn", (
- "LinkedIn MCP 已写入 mcporter 配置,但 Doctor 未启动本地"
- "服务做连通验证,不能仅凭配置宣称完整可用。"
- )
- if inspection.imports_unchecked:
- return "warn", (
- "mcporter 本地配置未发现 LinkedIn MCP;配置还启用了 editor "
- "imports,Doctor 为避免扩大凭据读取范围没有展开,当前未验证。"
- )
- return "off", (
- "mcporter 已装但 LinkedIn MCP 未配置。运行:\n"
- f" 先安装 uv/uvx:{_UV_INSTALL_URL}\n"
- f" {_LOGIN_COMMAND}\n"
- f" {_CONFIG_COMMAND}"
- )
-
# ── unified entry backends ──
def _mcp_jobs(self, *, query: str, location, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/mcporter.py b/agent_reach/channels/mcporter.py
index 0d7ee8a1..d269f183 100644
--- a/agent_reach/channels/mcporter.py
+++ b/agent_reach/channels/mcporter.py
@@ -1,133 +1,12 @@
-"""Read-only helpers for interpreting mcporter configuration."""
+"""Helpers for reading mcporter output."""
from __future__ import annotations
import json
-import os
-from dataclasses import dataclass
-from pathlib import Path
-
-from agent_reach.utils.paths import (
- PrivatePathError,
- read_small_text_no_follow,
-)
-
-_MAX_CONFIG_BYTES = 1024 * 1024
-_MISSING = object()
class McporterConfigError(ValueError):
- """Raised when mcporter configuration is not trustworthy."""
-
-
-@dataclass(frozen=True)
-class McporterConfigInspection:
- """Minimal, non-secret routing facts from one mcporter config layer."""
-
- server_names: frozenset[str]
- source: str | None
- imports_unchecked: bool = False
-
-
-def inspect_mcporter_config(
- root_dir: str | Path | None = None,
-) -> McporterConfigInspection:
- """Read the effective local mcporter config without starting mcporter.
-
- An explicit ``MCPORTER_CONFIG`` is a single layer. Otherwise mcporter
- 0.7.3 loads the first home config
- (``~/.mcporter/mcporter.json`` / ``mcporter.jsonc``) and then
- ``<cwd>/config/mcporter.json``; project entries override duplicate home
- names. Only exact ``mcpServers`` keys are returned. Editor imports are
- deliberately not opened because Doctor must not expand its
- credential-read boundary.
- """
- selected_layers = _select_config_layers(root_dir)
- if not selected_layers:
- return McporterConfigInspection(frozenset(), None)
-
- names = set()
- imports_unchecked = False
- sources = []
- for config_path, source in selected_layers:
- payload = _read_config_object(config_path)
- servers = payload.get("mcpServers")
- if not isinstance(servers, dict):
- raise McporterConfigError("mcporter 配置缺少 mcpServers 对象")
-
- for name, definition in servers.items():
- if not isinstance(name, str) or not name.strip():
- raise McporterConfigError("mcporter 配置包含无效的 server name")
- if not isinstance(definition, dict):
- raise McporterConfigError("mcporter server 定义必须是对象")
- names.add(name.casefold())
-
- imports = payload.get("imports", _MISSING)
- if imports is _MISSING:
- # mcporter defaults to importing supported editor configs when the
- # key is omitted. Doctor intentionally does not open those files.
- imports_unchecked = True
- elif not isinstance(imports, list) or not all(
- isinstance(item, str) for item in imports
- ):
- raise McporterConfigError("mcporter imports 必须是字符串列表")
- elif imports:
- imports_unchecked = True
- sources.append(source)
-
- return McporterConfigInspection(
- frozenset(names),
- "+".join(sources),
- imports_unchecked=imports_unchecked,
- )
-
-
-def _select_config_layers(
- root_dir: str | Path | None,
-) -> list[tuple[Path, str]]:
- root = Path(os.path.abspath(os.fspath(root_dir or Path.cwd())))
- explicit = os.environ.get("MCPORTER_CONFIG", "").strip()
- if explicit:
- expanded = Path(os.path.expanduser(explicit))
- if not expanded.is_absolute():
- expanded = root / expanded
- return [(Path(os.path.abspath(os.fspath(expanded))), "explicit")]
-
- layers = []
- home_base = Path.home() / ".mcporter"
- for name in ("mcporter.json", "mcporter.jsonc"):
- candidate = home_base / name
- if os.path.lexists(candidate):
- layers.append((candidate, "home"))
- break
-
- project_path = root / "config" / "mcporter.json"
- if os.path.lexists(project_path):
- layers.append((project_path, "project"))
- return layers
-
-
-def _read_config_object(config_path: Path) -> dict:
- try:
- raw = read_small_text_no_follow(
- config_path,
- max_bytes=_MAX_CONFIG_BYTES,
- )
- except PrivatePathError as exc:
- raise McporterConfigError(
- f"mcporter 配置文件无法安全读取:{exc}"
- ) from exc
- except (OSError, UnicodeError) as exc:
- raise McporterConfigError("mcporter 配置文件无法安全读取") from exc
- if raw is None:
- raise McporterConfigError("mcporter 配置文件不存在")
- try:
- payload = json.loads(raw)
- except json.JSONDecodeError as exc:
- raise McporterConfigError("mcporter 配置不是有效的 UTF-8 JSON") from exc
- if not isinstance(payload, dict):
- raise McporterConfigError("mcporter 配置顶层必须是对象")
- return payload
+ """Raised when mcporter output is not trustworthy."""
def configured_server_names(output: str) -> set[str]:
diff --git a/agent_reach/channels/reddit.py b/agent_reach/channels/reddit.py
index 2382d4d4..48a27ed7 100644
--- a/agent_reach/channels/reddit.py
+++ b/agent_reach/channels/reddit.py
@@ -1,25 +1,13 @@
# -*- coding: utf-8 -*-
-"""Reddit — multi-backend: OpenCLI / rdt-cli. Login is mandatory.
-
-Honest tiering (live-verified 2026-06): there is NO zero-config path.
-Anonymous .json endpoints are blocked (403 anti-bot, all variants), and
-the official API closed self-service registration in 2025-11 (manual
-approval, individual scripts rarely granted — PRAW is only an option for
-users who already hold credentials). Every working backend rides a
-logged-in session: OpenCLI reuses the browser's, rdt-cli imports cookies.
-"""
+"""Reddit — OpenCLI in the Agent Reach browser. Login is mandatory.
-import json
-import shutil
-import time
-from pathlib import Path
+Live-verified 2026-06: there is NO zero-config path. Anonymous .json
+endpoints are blocked (403 anti-bot, all variants), and the official API
+closed self-service registration in 2025-11.
+"""
from agent_reach.backends.opencli import opencli_call, opencli_items
from agent_reach.runtime.result import BAD_INPUT, UPSTREAM_BROKEN, ReachError
-from agent_reach.utils.paths import (
- PrivatePathError,
- read_small_text_no_follow,
-)
from .base import Action, Channel, Param
@@ -36,18 +24,9 @@ def _reddit(args, timeout: float) -> list:
return items
-_CREDENTIAL_FILE = "~/.config/rdt-cli/credential.json"
-_CREDENTIAL_TTL_SECONDS = 7 * 86400
-_MAX_CREDENTIAL_BYTES = 1024 * 1024
-# Pinned to the 0.4.2 state — PyPI still only has 0.4.1 (upstream issue #10).
-_RDT_GIT_SOURCE = "git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66"
-
-
class RedditChannel(Channel):
name = "reddit"
description = "Reddit 帖子和评论"
- backends = ["OpenCLI", "rdt-cli"]
- tier = 1 # no zero-config path exists — see module docstring
level = "optional"
login_url = "https://www.reddit.com/login/"
@@ -93,118 +72,6 @@ class RedditChannel(Channel):
return host_matches(url, "reddit.com", "redd.it")
- def check(self, config=None):
- """Probe candidates in order; first fully-usable backend wins."""
- self.active_backend = None
- findings = []
-
- for backend in self.ordered_backends(config):
- if backend == "OpenCLI":
- result = self._check_opencli()
- else:
- result = self._check_rdt()
- if result is None:
- continue
- findings.append((backend, *result))
-
- for wanted in ("ok", "warn"):
- for backend, status, message in findings:
- if status == wanted:
- self.active_backend = backend if status == "ok" else None
- return status, message
-
- if findings:
- return "error", "\n".join(m for _, _, m in findings)
-
- return "off", (
- "未安装任何 Reddit 后端。注意:Reddit 没有零配置路径"
- "(匿名 .json 已被封,官方 API 需人工审批),必须用登录态。推荐:\n"
- " 桌面:agent-reach install --system --channels opencli\n"
- " (复用 Chrome 登录态,登录过 reddit.com 即可用)\n"
- f" 服务器/存量:pipx install '{_RDT_GIT_SOURCE}'\n"
- " 然后 `rdt login` 或手动写入 Cookie(见 doctor 提示)\n"
- "中国大陆访问 Reddit 需要代理"
- )
-
- def _check_opencli(self):
- """OpenCLI candidate. None = not installed."""
- from agent_reach.backends import opencli_status
-
- st = opencli_status()
- if not st.installed:
- return None
- if st.broken:
- return "error", st.hint
- if st.ready:
- return "warn", (
- "OpenCLI 桥接已连接,但 Reddit 登录态和实际命令未实时验证;"
- "Doctor 不执行平台命令,因此当前不标记为可用。"
- )
- return "warn", st.hint
-
- def _check_rdt(self):
- """Inspect rdt's saved credential without invoking its auto-refresh."""
- if not shutil.which("rdt"):
- return None
-
- credential_path = Path.home() / ".config" / "rdt-cli" / "credential.json"
- try:
- payload = read_small_text_no_follow(
- credential_path,
- max_bytes=_MAX_CREDENTIAL_BYTES,
- )
- except PrivatePathError as exc:
- return "warn", (
- f"rdt-cli 已安装,但 credential.json 无法安全读取:{exc}。"
- )
- except OSError:
- return "warn", (
- "rdt-cli 已安装,但 credential.json 无法安全读取;"
- "Doctor 未执行会自动刷新 Cookie 的 `rdt status`。"
- )
- if payload is None:
- return "warn", self._rdt_login_hint()
- try:
- data = json.loads(payload)
- except (UnicodeError, json.JSONDecodeError, ValueError):
- return "warn", (
- "rdt-cli 已安装,但保存的 credential.json 无法安全解析;"
- "Doctor 未执行会自动刷新 Cookie 的 `rdt status`。"
- )
- if not isinstance(data, dict):
- return "warn", self._rdt_login_hint()
- cookies = data.get("cookies")
- if not isinstance(cookies, dict) or not cookies.get("reddit_session"):
- return "warn", self._rdt_login_hint()
-
- saved_at = data.get("saved_at")
- if isinstance(saved_at, (int, float)) and (
- time.time() - saved_at > _CREDENTIAL_TTL_SECONDS
- ):
- return "warn", (
- "rdt-cli 已安装,保存的 Cookie 已超过 7 天;Doctor 不会让"
- "上游自动读取浏览器或刷新文件,请用 Cookie-Editor 明确更新。"
- )
- return "warn", (
- "rdt-cli 已安装并检测到显式保存的 Reddit Cookie;Doctor 为避免"
- "上游自动刷新浏览器 Cookie,不执行 `rdt status`,因此未实时验证。"
- )
-
- @staticmethod
- def _rdt_login_hint():
- return (
- "rdt-cli 已安装但没有可用的显式 Cookie。请使用 Cookie-Editor:\n"
- " 1. Chrome 应用商店安装 Cookie-Editor 扩展:\n"
- " https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm\n"
- " 2. 在浏览器打开 reddit.com(确保已登录)\n"
- " 3. 点击 Cookie-Editor 图标,找到 `reddit_session`,复制其 Value\n"
- f" 4. 将以下内容写入 {_CREDENTIAL_FILE}:\n"
- ' {"cookies": {"reddit_session": "<粘贴 Value>"}, '
- '"source": "manual", "username": "<你的用户名>", '
- '"modhash": null, "saved_at": 0, "last_verified_at": null}\n\n'
- "Doctor 不会运行会自动读取浏览器并写文件的 `rdt status`。"
- )
-
# ── unified entry backends ──
def _opencli_search(self, *, query: str, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/rss.py b/agent_reach/channels/rss.py
deleted file mode 100644
index 5f630727..00000000
--- a/agent_reach/channels/rss.py
+++ /dev/null
@@ -1,27 +0,0 @@
-# -*- coding: utf-8 -*-
-"""RSS — check if feedparser is available."""
-
-from .base import Channel
-
-
-class RSSChannel(Channel):
- name = "rss"
- description = "RSS/Atom 订阅源"
- backends = ["feedparser"]
- tier = 0
-
- def can_handle(self, url: str) -> bool:
- return any(x in url.lower() for x in ["/feed", "/rss", ".xml", "atom"])
-
- def check(self, config=None):
- try:
- import feedparser # noqa: F401
- except ImportError:
- self.active_backend = None
- return "off", "feedparser 未安装。安装:pip install feedparser"
- except Exception as e:
- # 已安装但导入期崩溃(半残安装/版本冲突)→ 重装处方
- self.active_backend = None
- return "error", f"feedparser 导入失败:{e}\n修复:pip install --force-reinstall feedparser"
- self.active_backend = self.backends[0]
- return "ok", "可读取 RSS/Atom 源"
diff --git a/agent_reach/channels/twitter.py b/agent_reach/channels/twitter.py
index c4d274dc..7b156daa 100644
--- a/agent_reach/channels/twitter.py
+++ b/agent_reach/channels/twitter.py
@@ -1,8 +1,5 @@
# -*- coding: utf-8 -*-
-"""Twitter/X — check if twitter-cli or bird CLI is available."""
-
-import os
-import shutil
+"""Twitter/X — OpenCLI in the Agent Reach browser (experimental)."""
from agent_reach.backends.opencli import opencli_call, opencli_items
from agent_reach.runtime.result import UPSTREAM_BROKEN, ReachError
@@ -23,33 +20,9 @@ def _x(args, timeout: float) -> list:
return items
-def twitter_cli_child_env(config=None) -> dict[str, str]:
- """Return saved credentials missing from the current process environment.
-
- The returned mapping is meant for a single child process. Existing shell
- variables remain authoritative and ``os.environ`` is never mutated.
- """
- if config is None:
- return {}
-
- child_env = {}
- for env_name, config_key in (
- ("TWITTER_AUTH_TOKEN", "twitter_auth_token"),
- ("TWITTER_CT0", "twitter_ct0"),
- ):
- if env_name in os.environ:
- continue
- value = config.get(config_key)
- if value:
- child_env[env_name] = str(value)
- return child_env
-
-
class TwitterChannel(Channel):
name = "twitter"
description = "Twitter/X 推文"
- backends = ["twitter-cli", "OpenCLI", "bird CLI (legacy)"]
- tier = 1
# twitter-cli is not used here: even with explicit credentials it re-reads
# browser cookies whenever verification fails.
@@ -101,107 +74,6 @@ class TwitterChannel(Channel):
def can_handle(self, url: str) -> bool:
return host_matches(url, "x.com", "twitter.com")
- def check(self, config=None):
- """Probe candidates in order; first fully-usable backend wins.
-
- 与其他多后端渠道同一套两段式:先收集全部候选状态,第一个 ok 获胜;
- 没有 ok 才轮到第一个 warn——否则「装了但未登录」的 twitter-cli
- 会把排在后面、完整可用的 OpenCLI 挡在门外。
- """
- self.active_backend = None
- findings = []
-
- for backend in self.ordered_backends(config):
- if backend == "twitter-cli":
- result = self._check_twitter_cli(config)
- elif backend == "OpenCLI":
- result = self._check_opencli()
- elif backend == "bird CLI (legacy)":
- result = self._check_bird()
- else:
- continue
-
- if result is None:
- continue # 未安装——不参与候选
- findings.append((backend, *result))
-
- for wanted in ("ok", "warn"):
- for backend, status, message in findings:
- if status == wanted:
- self.active_backend = backend if status == "ok" else None
- return status, message
-
- if findings: # 只剩 broken/timeout 候选
- return "error", "\n".join(m for _, _, m in findings)
-
- return "warn", (
- "Twitter CLI 未安装。安装方式:\n"
- " pipx install twitter-cli\n"
- "或:\n"
- " uv tool install twitter-cli"
- )
-
- def _check_twitter_cli(self, config=None):
- """Inspect explicit credentials without starting twitter-cli.
-
- Upstream ``twitter status`` automatically reads browser cookies when
- credentials are missing *or invalid*. Doctor cannot disable that
- fallback, so executing it would violate the Cookie-Editor-only policy.
- """
- if not shutil.which("twitter"):
- return None
-
- child_env = twitter_cli_child_env(config)
- auth_token = os.environ.get("TWITTER_AUTH_TOKEN") or child_env.get(
- "TWITTER_AUTH_TOKEN"
- )
- ct0 = os.environ.get("TWITTER_CT0") or child_env.get("TWITTER_CT0")
- if auth_token and ct0:
- return "warn", (
- "twitter-cli 已安装,且 Cookie-Editor 凭据已配置;"
- "Doctor 不会执行 `twitter status`,因为上游在验证失败时会"
- "自动读取浏览器 Cookie。请在你明确同意时手动验证。"
- )
- return "warn", (
- "twitter-cli 已安装但没有完整的显式凭据。请用 Cookie-Editor "
- "从 x.com 导出后运行:\n"
- " agent-reach configure twitter-cookies\n"
- "Doctor 不会自动读取浏览器 Cookie。"
- )
-
- def _check_opencli(self):
- """OpenCLI candidate. None = not installed."""
- from agent_reach.backends import opencli_status
-
- st = opencli_status()
- if not st.installed:
- return None
- if st.broken:
- return "error", st.hint
- if st.ready:
- return "warn", (
- "OpenCLI 桥接已连接,但 Twitter/X 登录态和实际命令未实时验证;"
- "Doctor 不执行平台命令,因此当前不标记为可用。"
- )
- return "warn", st.hint
-
- def _check_bird(self):
- """Inspect legacy bird credentials without launching browser fallback."""
- for cmd in ("bird", "birdx"):
- if not shutil.which(cmd):
- continue
- if os.environ.get("AUTH_TOKEN") and os.environ.get("CT0"):
- return (
- "warn",
- f"{cmd} 已安装且显式环境凭据存在;Doctor 为避免上游"
- "浏览器 Cookie 回退,不执行 `check`,未实时验证。",
- )
- return "warn", (
- f"{cmd} 已安装但未检测到显式 AUTH_TOKEN/CT0;"
- "仅使用 Cookie-Editor 手动导出的凭据。"
- )
- return None
-
# ── unified entry backends ──
def _opencli_search(self, *, query: str, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/v2ex.py b/agent_reach/channels/v2ex.py
index de01ce97..421b4800 100644
--- a/agent_reach/channels/v2ex.py
+++ b/agent_reach/channels/v2ex.py
@@ -8,11 +8,10 @@ import ssl
import subprocess
import urllib.request
from typing import Any
-from urllib.parse import quote, urlencode, urlsplit
+from urllib.parse import urlencode, urlsplit
from agent_reach.runtime.result import BAD_INPUT, NOT_FOUND, ReachError, make_item, unix_to_iso
from agent_reach.utils.process import utf8_subprocess_env
-from agent_reach.utils.text import scrub_url_credentials
from .base import Action, Channel, Param
@@ -165,12 +164,9 @@ def _topic_item(topic: dict, text: Any = None, raw: Any = None) -> dict:
)
-
class V2EXChannel(Channel):
name = "v2ex"
description = "V2EX 节点、主题与回复"
- backends = ["V2EX API (public)"]
- tier = 0
level = "default"
actions = (
@@ -207,210 +203,11 @@ class V2EXChannel(Channel):
),
)
- # ------------------------------------------------------------------ #
- # URL routing
- # ------------------------------------------------------------------ #
-
def can_handle(self, url: str) -> bool:
from agent_reach.utils.url import host_matches
return host_matches(url, "v2ex.com")
- # ------------------------------------------------------------------ #
- # Health check
- # ------------------------------------------------------------------ #
-
- def check(self, config=None):
- try:
- _get_json(
- "https://www.v2ex.com/api/topics/show.json?node_name=python&page=1"
- )
- self.active_backend = self.backends[0]
- return "ok", "公开 API 可用(热门主题、节点浏览、主题详情、用户信息)"
- except Exception as e:
- self.active_backend = None
- return (
- "warn",
- f"V2EX API 连接失败(可能需要代理):{scrub_url_credentials(e)}",
- )
-
- # ------------------------------------------------------------------ #
- # Data-fetching methods
- # ------------------------------------------------------------------ #
-
- def get_hot_topics(self, limit: int = 20) -> list:
- """获取热门帖子列表。
-
- Returns a list of dicts with keys:
- title, url, replies, node_name, node_title, content
- """
- data = _get_json("https://www.v2ex.com/api/topics/hot.json")
- results = []
- for item in data[:limit]:
- node = item.get("node") or {}
- content = item.get("content", "") or ""
- results.append(
- {
- "id": item.get("id", 0),
- "title": item.get("title", ""),
- "url": item.get("url", ""),
- "replies": item.get("replies", 0),
- "node_name": node.get("name", ""),
- "node_title": node.get("title", ""),
- "content": content[:200],
- "created": item.get("created", 0),
- }
- )
- return results
-
- def get_node_topics(self, node_name: str, limit: int = 20) -> list:
- """获取指定节点的最新帖子。
-
- Args:
- node_name: 节点名称,如 "python"、"tech"、"jobs"
- limit: 最多返回条数
-
- Returns a list of dicts with keys:
- title, url, replies, node_name, node_title, content
- """
- url = _v2ex_url(
- "/api/topics/show.json",
- node_name=node_name,
- page=1,
- )
- data = _get_json(url)
- results = []
- for item in data[:limit]:
- node = item.get("node") or {}
- content = item.get("content", "") or ""
- results.append(
- {
- "id": item.get("id", 0),
- "title": item.get("title", ""),
- "url": item.get("url", ""),
- "replies": item.get("replies", 0),
- "node_name": node.get("name", node_name),
- "node_title": node.get("title", ""),
- "content": content[:200],
- "created": item.get("created", 0),
- }
- )
- return results
-
- def get_topic(self, topic_id: int) -> dict:
- """获取单个帖子详情和回复列表。
-
- Args:
- topic_id: 帖子 ID(从 URL https://www.v2ex.com/t/<id> 中获取)
-
- Returns a dict with keys:
- id, title, url, content, replies_count, node_name, node_title,
- author, created, replies (list of dicts with: author, content, created)
- """
- topic_data = _get_json(
- _v2ex_url("/api/topics/show.json", id=topic_id)
- )
- # API returns a list even for single-ID queries
- if isinstance(topic_data, list):
- topic = topic_data[0] if topic_data else {}
- else:
- topic = topic_data
-
- node = topic.get("node") or {}
- member = topic.get("member") or {}
-
- # Fetch replies (first page)
- try:
- replies_raw = _get_json(
- _v2ex_url(
- "/api/replies/show.json",
- topic_id=topic_id,
- page=1,
- )
- )
- except Exception:
- replies_raw = []
-
- replies = [
- {
- "author": (r.get("member") or {}).get("username", ""),
- "content": r.get("content", ""),
- "created": r.get("created", 0),
- }
- for r in (replies_raw or [])
- ]
-
- return {
- "id": topic.get("id", topic_id),
- "title": topic.get("title", ""),
- "url": topic.get(
- "url",
- f"{_API_BASE}/t/{quote(str(topic_id), safe='')}",
- ),
- "content": topic.get("content", ""),
- "replies_count": topic.get("replies", 0),
- "node_name": node.get("name", ""),
- "node_title": node.get("title", ""),
- "author": member.get("username", ""),
- "created": topic.get("created", 0),
- "replies": replies,
- }
-
- def get_user(self, username: str) -> dict:
- """获取用户信息。
-
- Args:
- username: V2EX 用户名
-
- Returns a dict with keys:
- id, username, url, website, twitter, psn, github, btc,
- location, bio, avatar, created
- """
- data = _get_json(
- _v2ex_url("/api/members/show.json", username=username)
- )
- return {
- "id": data.get("id", 0),
- "username": data.get("username", username),
- "url": data.get(
- "url",
- f"{_API_BASE}/member/{quote(str(username), safe='')}",
- ),
- "website": data.get("website", ""),
- "twitter": data.get("twitter", ""),
- "psn": data.get("psn", ""),
- "github": data.get("github", ""),
- "btc": data.get("btc", ""),
- "location": data.get("location", ""),
- "bio": data.get("bio", ""),
- "avatar": data.get("avatar_large", data.get("avatar_normal", "")),
- "created": data.get("created", 0),
- }
-
- def search(self, query: str, limit: int = 10) -> list:
- """搜索帖子。
-
- 注意:V2EX 公开 API 暂不支持全文搜索端点(/api/search.json 不可用)。
- 本方法通过 Jina Reader 代理 V2EX 站内搜索页面获取结果(纯文本,无结构化数据)。
-
- 如需精确搜索,建议直接访问 https://www.v2ex.com/?q=<query> 或
- 使用 Exa channel 的 site:v2ex.com 搜索。
-
- Returns:
- list of dicts with keys: title, url, snippet
- 如果搜索不可用,返回包含单条 {"error": str} 的列表。
- """
- search_url = _v2ex_url("/", q=query)
- return [
- {
- "error": (
- "V2EX 公开 API 不提供搜索端点。"
- f"建议改用:{search_url} "
- "或通过 Exa channel 使用 site:v2ex.com 搜索。"
- )
- }
- ]
-
# ------------------------------------------------------------------ #
# Unified entry backends
# ------------------------------------------------------------------ #
diff --git a/agent_reach/channels/web.py b/agent_reach/channels/web.py
index 3e2e17d7..2c91129e 100644
--- a/agent_reach/channels/web.py
+++ b/agent_reach/channels/web.py
@@ -128,8 +128,6 @@ def _parse_jina(url: str, body: str) -> dict:
class WebChannel(Channel):
name = "web"
description = "网页搜索与阅读(Agent 自带工具不可用时的保底)"
- backends = ["Jina Reader"]
- tier = 0
level = "default"
actions = (
@@ -155,11 +153,6 @@ class WebChannel(Channel):
def can_handle(self, url: str) -> bool:
return True # Fallback — handles any URL
- def check(self, config=None):
- # 恒可用兜底渠道:无本地命令、不做网络探测(doctor 已有多个渠道触网),保持零开销
- self.active_backend = self.backends[0]
- return "ok", "通过 Jina Reader 读取任意网页(curl https://r.jina.ai/URL)"
-
def read(self, url: str, timeout: float = 30) -> str:
"""通过 Jina Reader 读取网页,返回 Markdown 全文。"""
url = normalize_public_http_url(url)
diff --git a/agent_reach/channels/xiaohongshu.py b/agent_reach/channels/xiaohongshu.py
index 86eaaa7d..e53ceccd 100644
--- a/agent_reach/channels/xiaohongshu.py
+++ b/agent_reach/channels/xiaohongshu.py
@@ -1,173 +1,20 @@
# -*- coding: utf-8 -*-
-"""XiaoHongShu — multi-backend: OpenCLI / xiaohongshu-mcp / xhs-cli.
-
-Backend order encodes the recommendation, and probing order makes the
-environment split automatic: OpenCLI needs a desktop Chrome so it simply
-never probes alive on a server, where xiaohongshu-mcp (self-contained
-headless browser) takes over after an explicit Cookie-Editor import.
-xhs-cli (upstream unmaintained since
-2026-03) keeps working for existing installs as the last candidate.
-"""
-
-import json
-import shutil
-import time
-import urllib.error
-import urllib.request
-from pathlib import Path
+"""XiaoHongShu — OpenCLI in the Agent Reach browser."""
from agent_reach.backends.opencli import opencli_call, opencli_items
from agent_reach.runtime.result import BAD_INPUT, NOT_FOUND, UPSTREAM_BROKEN, ReachError
-from agent_reach.utils.paths import (
- PrivatePathError,
- read_small_text_no_follow,
-)
from .base import Action, Channel, Param
-from .mcporter import McporterConfigError, inspect_mcporter_config
-_MCP_ENDPOINT = "http://localhost:18060/mcp"
-_MCP_INSTALL_URL = "https://github.com/xpzouying/xiaohongshu-mcp"
-_XHS_COOKIE_TTL_SECONDS = 7 * 86400
-_MAX_XHS_COOKIE_BYTES = 1024 * 1024
_XHS_LOGIN_HINT = (
"Ask the user to log in to xiaohongshu.com in their own Chrome (the one with "
"the OpenCLI extension). Never log in or read browser cookies for them."
)
-def _mcp_service_reachable(timeout: int = 3) -> bool:
- """True if the xiaohongshu-mcp HTTP service answers on localhost.
-
- Any HTTP response counts (the MCP endpoint replies 405 to GET) —
- we only care that the service is up. Proxies are bypassed explicitly:
- localhost must never be routed through HTTP_PROXY.
- """
- req = urllib.request.Request(_MCP_ENDPOINT, method="GET")
- opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
- try:
- opener.open(req, timeout=timeout)
- return True
- except urllib.error.HTTPError:
- return True # 405/404 etc. — service is alive
- except Exception:
- return False
-
-
-def format_xhs_result(data):
- """Clean XHS API response, keeping only useful fields.
-
- Handles both single note objects and lists of notes (search results).
- Drastically reduces token usage by stripping structural redundancy (#134).
- """
- if isinstance(data, list):
- return [_clean_note(item) for item in data]
- if isinstance(data, dict):
- # Handle search_feeds wrapper: {"items": [...]} or {"data": {"items": [...]}}
- items = None
- if "items" in data:
- items = data["items"]
- elif "data" in data and isinstance(data.get("data"), dict):
- items = data["data"].get("items") or data["data"].get("notes")
- if items and isinstance(items, list):
- return [_clean_note(item) for item in items]
- # Single note
- return _clean_note(data)
- return data
-
-
-def _clean_note(note):
- """Extract useful fields from a single XHS note/feed item."""
- if not isinstance(note, dict):
- return note
-
- # Some responses nest the note under "note_card" or "note"
- inner = note.get("note_card") or note.get("note") or note
-
- result = {}
-
- # Basic info
- for key in ("id", "note_id", "xsec_token", "title", "desc", "type", "time"):
- if key in inner:
- result[key] = inner[key]
-
- # Content (may be in desc or content)
- if "content" in inner and "desc" not in result:
- result["content"] = inner["content"]
-
- # Author
- user = inner.get("user") or inner.get("author")
- if isinstance(user, dict):
- result["user"] = {
- k: user[k] for k in ("nickname", "user_id", "nick_name") if k in user
- }
-
- # Engagement metrics
- interact = inner.get("interact_info") or inner.get("note_interact_info") or {}
- if isinstance(interact, dict):
- for key in ("liked_count", "collected_count", "comment_count", "share_count"):
- if key in interact:
- result[key] = interact[key]
- # Also check top-level (some API formats)
- for key in ("liked_count", "collected_count", "comment_count", "share_count"):
- if key in inner and key not in result:
- result[key] = inner[key]
-
- # Images — just URLs
- images = inner.get("image_list") or inner.get("images_list") or []
- if isinstance(images, list):
- urls = []
- for img in images:
- if isinstance(img, dict):
- url = img.get("url") or img.get("url_default") or img.get("original")
- if url:
- urls.append(url)
- elif isinstance(img, str):
- urls.append(img)
- if urls:
- result["images"] = urls
-
- # Tags
- tags = inner.get("tag_list") or inner.get("tags") or []
- if isinstance(tags, list):
- tag_names = []
- for t in tags:
- if isinstance(t, dict) and "name" in t:
- tag_names.append(t["name"])
- elif isinstance(t, str):
- tag_names.append(t)
- if tag_names:
- result["tags"] = tag_names
-
- # Comments (if present, e.g. from get_feed_detail with comments)
- comments = inner.get("comments") or []
- if isinstance(comments, list) and comments:
- result["comments"] = [_clean_comment(c) for c in comments]
-
- return result
-
-
-def _clean_comment(comment):
- """Extract useful fields from a comment."""
- if not isinstance(comment, dict):
- return comment
- result = {}
- if "content" in comment:
- result["content"] = comment["content"]
- user = comment.get("user_info") or comment.get("user")
- if isinstance(user, dict):
- result["user"] = user.get("nickname") or user.get("nick_name", "")
- for key in ("like_count", "sub_comment_count"):
- if key in comment:
- result[key] = comment[key]
- return result
-
-
class XiaoHongShuChannel(Channel):
name = "xiaohongshu"
description = "小红书笔记"
- backends = ["OpenCLI", "xiaohongshu-mcp", "xhs-cli (xiaohongshu-cli)"]
- tier = 1
level = "optional"
login_url = "https://www.xiaohongshu.com/explore"
@@ -203,142 +50,6 @@ class XiaoHongShuChannel(Channel):
return host_matches(url, "xiaohongshu.com", "xhslink.com")
- def check(self, config=None):
- """Probe candidates in order; first fully-usable backend wins.
-
- If none is fully usable, the first fixable candidate (warn) is
- reported, so the user gets one actionable prescription instead
- of three half-relevant ones.
- """
- self.active_backend = None
- findings = [] # (backend, status, message)
-
- for backend in self.ordered_backends(config):
- if backend == "OpenCLI":
- result = self._check_opencli()
- elif backend == "xiaohongshu-mcp":
- result = self._check_mcp()
- else:
- result = self._check_xhs_cli()
- if result is None:
- continue # not installed — not a candidate right now
- findings.append((backend, *result))
-
- for wanted in ("ok", "warn"):
- for backend, status, message in findings:
- if status == wanted:
- self.active_backend = backend if status == "ok" else None
- return status, message
-
- if findings: # only broken candidates left
- return "error", "\n".join(m for _, _, m in findings)
-
- return "off", (
- "未安装任何小红书后端。推荐:\n"
- " 桌面:agent-reach install --system --channels opencli\n"
- " (复用 Chrome 登录态,刷过小红书即零配置可用)\n"
- f" 服务器:xiaohongshu-mcp:{_MCP_INSTALL_URL}\n"
- " 登录只使用 Cookie-Editor 明确导出:\n"
- " agent-reach configure xhs-cookies(隐藏输入)"
- )
-
- def _check_opencli(self):
- """OpenCLI candidate. None = not installed."""
- from agent_reach.backends import opencli_status
-
- st = opencli_status()
- if not st.installed:
- return None
- if st.broken:
- return "error", st.hint
- if st.ready:
- return "warn", (
- "OpenCLI 桥接已连接,但小红书登录态和实际命令未实时验证;"
- "Doctor 不执行平台命令,因此当前不标记为可用。"
- )
- return "warn", st.hint
-
- def _check_mcp(self):
- """xiaohongshu-mcp candidate. None = service not running."""
- if not _mcp_service_reachable():
- return None
- if not shutil.which("mcporter"):
- return "warn", (
- "xiaohongshu-mcp 服务可达,但 mcporter 未安装,Doctor 未接入"
- "该服务。先安装:npm install -g mcporter"
- )
- try:
- inspection = inspect_mcporter_config()
- except McporterConfigError as exc:
- return "error", f"mcporter 配置检查失败:{exc}"
- if "xiaohongshu" in inspection.server_names:
- return "warn", (
- "xiaohongshu-mcp 服务可达且已接入 mcporter,但 Doctor "
- "未验证登录态,不能据此宣称笔记功能可用。若未登录,用 "
- "Cookie-Editor 导出后运行 agent-reach configure xhs-cookies"
- )
- if inspection.imports_unchecked:
- return "warn", (
- "xiaohongshu-mcp 服务可达;mcporter 本地配置未发现"
- " xiaohongshu,且 editor imports 未展开,Doctor 当前未验证接入。"
- )
- return "warn", (
- "xiaohongshu-mcp 服务在跑但 mcporter 未接入。运行:\n"
- f" mcporter config add xiaohongshu {_MCP_ENDPOINT} --scope home"
- )
-
- def _check_xhs_cli(self):
- """Inspect saved xhs-cli cookies without invoking browser extraction."""
- if not shutil.which("xhs"):
- return None
- cookie_path = Path.home() / ".xiaohongshu-cli" / "cookies.json"
- try:
- payload = read_small_text_no_follow(
- cookie_path,
- max_bytes=_MAX_XHS_COOKIE_BYTES,
- )
- except PrivatePathError as exc:
- return "warn", (
- f"xhs-cli 已安装,但 cookies.json 无法安全读取:{exc}。"
- )
- except OSError:
- return "warn", (
- "xhs-cli 已安装,但 cookies.json 无法安全读取;"
- "Doctor 未执行会自动提取浏览器 Cookie 的 `xhs status`。"
- )
- if payload is None:
- return self._xhs_cookie_hint()
- try:
- data = json.loads(payload)
- except (UnicodeError, json.JSONDecodeError, ValueError):
- return "warn", (
- "xhs-cli 已安装,但保存的 cookies.json 无法安全解析;"
- "Doctor 未执行会自动提取浏览器 Cookie 的 `xhs status`。"
- )
- if not isinstance(data, dict) or not data.get("a1"):
- return self._xhs_cookie_hint()
- saved_at = data.get("saved_at")
- if isinstance(saved_at, (int, float)) and (
- time.time() - saved_at > _XHS_COOKIE_TTL_SECONDS
- ):
- return "warn", (
- "xhs-cli 已安装,保存的 Cookie 已超过 7 天;Doctor 不会让"
- "上游自动读取浏览器或刷新文件,请用 Cookie-Editor 明确更新。"
- )
- return "warn", (
- "xhs-cli 已安装并检测到显式保存的 Cookie;Doctor 为避免上游"
- "自动读取浏览器或改写 Cookie,不执行 `xhs status`,未实时验证。"
- )
-
- @staticmethod
- def _xhs_cookie_hint():
- return "warn", (
- "xhs-cli 已安装但没有可用的显式 Cookie。不要运行会自动读取"
- "浏览器的 `xhs login/status`;请迁移到 xiaohongshu-mcp,"
- "再用 Cookie-Editor 导出并运行 "
- "agent-reach configure xhs-cookies。"
- )
-
# ── unified entry backends ──
def _opencli_search(self, *, query: str, limit: int, timeout: float) -> list:
diff --git a/agent_reach/channels/xiaoyuzhou.py b/agent_reach/channels/xiaoyuzhou.py
index 96fc12c8..c223b405 100644
--- a/agent_reach/channels/xiaoyuzhou.py
+++ b/agent_reach/channels/xiaoyuzhou.py
@@ -6,7 +6,6 @@ import shutil
import tempfile
from agent_reach.config import Config
-from agent_reach.probe import probe_command
from agent_reach.runtime.result import BAD_INPUT, NEED_SETUP, ReachError, make_item
from agent_reach.runtime.run import run_cmd
@@ -18,8 +17,6 @@ _SCRIPT = os.path.join(os.path.dirname(os.path.dirname(__file__)), "scripts", "t
class XiaoyuzhouChannel(Channel):
name = "xiaoyuzhou"
description = "小宇宙播客转文字"
- backends = ["groq-whisper", "ffmpeg"]
- tier = 1
level = "optional"
prereqs = ("ffmpeg",)
@@ -44,50 +41,6 @@ class XiaoyuzhouChannel(Channel):
return host_matches(url, "xiaoyuzhoufm.com")
- def check(self, config=None):
- self.active_backend = None
-
- # Check ffmpeg — really execute it: a stale pip-installed ffmpeg shim
- # passes shutil.which() but cannot run
- probe = probe_command("ffmpeg", ["-version"], timeout=10, package="ffmpeg")
- if probe.status == "missing":
- return "off", (
- "需要 ffmpeg(音频转码和切片)。安装:\n"
- " Ubuntu/Debian: apt install -y ffmpeg\n"
- " macOS: brew install ffmpeg"
- )
- if not probe.ok:
- return "error", (
- "ffmpeg 无法执行,重装:brew install ffmpeg(macOS)/ apt install ffmpeg(Linux)"
- )
-
- # Check script exists
- script = os.path.expanduser("~/.agent-reach/tools/xiaoyuzhou/transcribe.sh")
- if not os.path.isfile(script):
- return "off", (
- "转录脚本未安装。运行:\n"
- " agent-reach install --env=auto --system --channels=xiaoyuzhou\n"
- " 或手动复制 transcribe.sh 到 ~/.agent-reach/tools/xiaoyuzhou/"
- )
-
- # Check GROQ_API_KEY — prefer env var, fall back to Agent Reach config
- has_key = bool(os.environ.get("GROQ_API_KEY"))
- if not has_key:
- try:
- cfg = config if config is not None else Config()
- has_key = bool(cfg.get("groq_api_key"))
- except Exception:
- has_key = False
- if not has_key:
- return "warn", (
- "需要配置 Groq API Key(免费)。步骤:\n"
- " 1. 注册 https://console.groq.com\n"
- " 2. 运行: agent-reach configure groq-key(隐藏输入)"
- )
-
- self.active_backend = "groq-whisper"
- return "ok", "完整可用(播客下载 + Whisper 转录)"
-
# ── unified entry backends ──
def _script_transcribe(self, *, target: str, timeout: float) -> list:
diff --git a/agent_reach/channels/xueqiu.py b/agent_reach/channels/xueqiu.py
index e5a05778..2f2dd3f1 100644
--- a/agent_reach/channels/xueqiu.py
+++ b/agent_reach/channels/xueqiu.py
@@ -17,7 +17,7 @@ from .base import Action, Channel, Param
_XQ_LOGIN_HINT = (
"Xueqiu community data needs a browser session. Run `agent-reach login xueqiu`, "
"let the user open xueqiu.com in the Agent Reach browser, then run "
- "`agent-reach login xueqiu --sync`. While that browser is open, Agent Reach renews the session itself."
+ "`agent-reach login xueqiu --sync`. The session expires within hours; repeat these steps when it does."
)
_UA = (
@@ -85,7 +85,7 @@ def _ensure_cookies(config=None) -> None:
"""Populate session cookies without touching browser credential stores.
Priority order:
- 1. Saved cookie string in ~/.agent-reach/config.yaml (set by configure --from-browser)
+ 1. Saved cookie string in ~/.agent-reach/config.yaml (set by `agent-reach login xueqiu --sync`)
2. Homepage visit fallback (only yields public session cookies and may not
be sufficient when Xueqiu requires a logged-in session)
"""
@@ -148,23 +148,14 @@ def _xueqiu_symbol(market: str, code: str) -> str:
return code.split(".")[0].upper()
-def _refresh_from_browser() -> bool:
- """Pull a fresh Xueqiu session from the Agent Reach browser, if it is running."""
+def _import_from_browser() -> bool:
+ """Copy the Xueqiu session the user has in the Agent Reach browser (only on `login --sync`)."""
global _cookies_initialized
from agent_reach.runtime import browser, cdp
if not browser.is_running():
return False
jar = {c["name"]: c["value"] for c in cdp.cookies("xueqiu.com")}
- if "xq_a_token" not in jar:
- try:
- browser.open_url("https://xueqiu.com/")
- except Exception: # noqa: BLE001
- return False
- import time
-
- time.sleep(4)
- jar = {c["name"]: c["value"] for c in cdp.cookies("xueqiu.com")}
if "xq_a_token" not in jar:
return False
from agent_reach.config import Config
@@ -175,15 +166,13 @@ def _refresh_from_browser() -> bool:
return True
-def _xq_json(url: str, _retried: bool = False) -> Any:
+def _xq_json(url: str) -> Any:
try:
return _get_json(url)
except (urllib.error.HTTPError, json.JSONDecodeError) as exc:
rejected = isinstance(exc, json.JSONDecodeError) or exc.code in (400, 401, 403)
if not rejected:
raise
- if not _retried and _refresh_from_browser():
- return _xq_json(url, _retried=True)
raise ReachError(NEED_LOGIN, "Xueqiu rejected the session", hint=_XQ_LOGIN_HINT) from None
@@ -220,15 +209,13 @@ def _parse_hot_posts(data: Any, limit: int) -> list:
class XueqiuChannel(Channel):
name = "xueqiu"
description = "雪球股票行情与社区动态"
- backends = ["Xueqiu API (需要登录 Cookie)"]
- tier = 1
level = "optional"
login_url = "https://xueqiu.com/"
logout_keys = ("xueqiu_cookie",)
def sync_login(self):
- if not _refresh_from_browser():
+ if not _import_from_browser():
raise ReachError(
NEED_LOGIN, "no Xueqiu session found in the Agent Reach browser",
hint="Run `agent-reach login xueqiu`, let the user open xueqiu.com there, then `agent-reach login xueqiu --sync`.",
@@ -269,159 +256,11 @@ class XueqiuChannel(Channel):
),
)
- # ------------------------------------------------------------------ #
- # URL routing
- # ------------------------------------------------------------------ #
-
def can_handle(self, url: str) -> bool:
from agent_reach.utils.url import host_matches
return host_matches(url, "xueqiu.com")
- # ------------------------------------------------------------------ #
- # Health check
- # ------------------------------------------------------------------ #
-
- def check(self, config=None):
- self.active_backend = None
- try:
- data = _get_json(
- "https://stock.xueqiu.com/v5/stock/quote.json"
- "?symbol=SH601138&extend=detail",
- config,
- )
- quote = (data.get("data") or {}).get("quote") or {}
- if quote:
- self.active_backend = self.backends[0]
- return "ok", "公开 API 可用(行情、搜索、热帖、热股)"
- return "warn", "API 响应异常(返回数据为空)"
- except Exception as e:
- from agent_reach.utils.text import scrub_url_credentials
-
- detail = scrub_url_credentials(e).rstrip(": ")
- return "warn", (
- f"Xueqiu API 连接失败:{detail}。"
- "如需登录 Cookie,请运行:agent-reach configure "
- "--from-browser chrome --platform xueqiu;"
- "doctor 不会自动读取浏览器 Cookie。"
- )
-
- # ------------------------------------------------------------------ #
- # Data-fetching methods
- # ------------------------------------------------------------------ #
-
- def get_stock_quote(self, symbol: str) -> dict:
- """获取实时股票行情。
-
- Args:
- symbol: 股票代码,如 SH600519(沪)、SZ000858(深)、AAPL(美)、00700(港)
-
- Returns a dict with keys:
- symbol, name, current, percent, chg, high, low, open, last_close,
- volume, amount, market_capital, turnover_rate, pe_ttm, pe_forecast,
- pb, eps, timestamp
- """
- encoded_symbol = urllib.parse.quote(symbol, safe="")
- data = _get_json(
- "https://stock.xueqiu.com/v5/stock/quote.json"
- f"?symbol={encoded_symbol}&extend=detail"
- )
- q = (data.get("data") or {}).get("quote") or {}
- return {
- "symbol": q.get("symbol", symbol),
- "name": q.get("name", ""),
- "current": q.get("current"),
- "percent": q.get("percent"),
- "chg": q.get("chg"),
- "high": q.get("high"),
- "low": q.get("low"),
- "open": q.get("open"),
- "last_close": q.get("last_close"),
- "volume": q.get("volume"),
- "amount": q.get("amount"),
- "market_capital": q.get("market_capital"),
- "turnover_rate": q.get("turnover_rate"),
- "pe_ttm": q.get("pe_ttm"),
- "pe_forecast": q.get("pe_forecast"),
- "pb": q.get("pb"),
- "eps": q.get("eps"),
- "timestamp": q.get("timestamp"),
- }
-
- def search_stock(self, query: str, limit: int = 10) -> list:
- """搜索股票。
-
- Args:
- query: 股票代码或中文名称,如 "茅台"、"600519"
- limit: 最多返回条数
-
- Returns a list of dicts with keys:
- symbol, name, exchange
- """
- data = _get_json(
- f"https://xueqiu.com/stock/search.json"
- f"?code={urllib.parse.quote(query)}&size={limit}"
- )
- stocks = data.get("stocks") or []
- results = []
- for s in stocks[:limit]:
- results.append(
- {
- "symbol": s.get("code", ""),
- "name": s.get("name", ""),
- "exchange": s.get("exchange", ""),
- }
- )
- return results
-
- def get_hot_posts(self, limit: int = 20) -> list:
- """获取雪球热门帖子。
-
- Uses the v4 public timeline endpoint which returns posts in a `list`
- array. Each item carries a JSON-encoded `data` field containing the
- actual post payload (title, description, user, like_count, target).
-
- Args:
- limit: 最多返回条数(上限 50)
-
- Returns a list of dicts with keys:
- id, title, text, author, likes, url
- """
- if limit < 0:
- raise ValueError("limit must be non-negative")
- limit = min(limit, 50)
- if limit == 0:
- return []
- return _parse_hot_posts(_get_json(_HOT_POSTS_URL.format(limit=limit)), limit)
-
- def get_hot_stocks(self, limit: int = 10, stock_type: int = 10) -> list:
- """获取热门股票排行。
-
- Args:
- limit: 最多返回条数(上限 50)
- stock_type: 10=人气榜(默认),12=关注榜
-
- Returns a list of dicts with keys:
- symbol, name, current, percent, rank
- """
- data = _get_json(
- f"https://stock.xueqiu.com/v5/stock/hot_stock/list.json"
- f"?size={limit}&type={stock_type}"
- )
- items = (data.get("data") or {}).get("items") or []
- results = []
- for idx, item in enumerate(items[:limit], 1):
- results.append(
- {
- "symbol": item.get("code") or item.get("symbol", ""),
- "name": item.get("name", ""),
- "current": item.get("current"),
- "percent": item.get("percent"),
- "rank": idx,
- }
- )
- return results
-
# ── unified entry backends ──
def _tencent_quote(self, *, symbol: str, timeout: float) -> list:
diff --git a/agent_reach/channels/youtube.py b/agent_reach/channels/youtube.py
index 9206f2a0..5061b01d 100644
--- a/agent_reach/channels/youtube.py
+++ b/agent_reach/channels/youtube.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-"""YouTube — check if yt-dlp is available with JS runtime."""
+"""YouTube — video info, search, subtitles (yt-dlp) and Whisper transcription."""
import html
import json
@@ -9,7 +9,6 @@ import shutil
import sys
import tempfile
-from agent_reach.probe import probe_command
from agent_reach.runtime.result import (
BAD_INPUT,
NEED_LOGIN,
@@ -19,12 +18,6 @@ from agent_reach.runtime.result import (
make_item,
)
from agent_reach.runtime.run import CommandFailed, run_cmd
-from agent_reach.utils.paths import (
- PrivatePathError,
- get_ytdlp_config_path,
- read_small_text_no_follow,
- render_ytdlp_fix_command,
-)
from .base import Action, Channel, Param
@@ -96,33 +89,9 @@ def vtt_to_text(vtt: str) -> str:
return "\n".join(out)
-_JS_RUNTIMES_SUPPORTED_FROM = (2025, 11, 12)
-_YTDLP_UPGRADE_COMMAND = 'python -m pip install -U "yt-dlp[default]"'
-
-
-def _parse_ytdlp_version(version: str):
- """Return a comparable stable yt-dlp release tuple, if recognised."""
- match = re.fullmatch(r"\s*(\d{4})\.(\d{1,2})\.(\d{1,2})\s*", version)
- return tuple(map(int, match.groups())) if match else None
-
-
-def _has_js_runtime_config(config_path) -> bool:
- """Return whether yt-dlp config explicitly enables a JS runtime."""
- try:
- payload = read_small_text_no_follow(
- config_path,
- max_bytes=1024 * 1024,
- )
- return payload is not None and "--js-runtimes" in payload
- except (OSError, UnicodeError, PrivatePathError):
- return False
-
-
class YouTubeChannel(Channel):
name = "youtube"
description = "YouTube 视频和字幕"
- backends = ["yt-dlp"]
- tier = 0
level = "default"
actions = (
@@ -167,99 +136,6 @@ class YouTubeChannel(Channel):
return host_matches(url, "youtube.com", "youtu.be")
- def check(self, config=None):
- # 真跑 yt-dlp --version 探活,区分未装 / venv 断链 / 跑不动
- probe = probe_command("yt-dlp", ["--version"], timeout=10, package="yt-dlp")
- if probe.status == "missing":
- self.active_backend = None
- return "off", f"yt-dlp 未安装。安装:{_YTDLP_UPGRADE_COMMAND}"
- if probe.status == "broken":
- self.active_backend = None
- return "error", (
- "yt-dlp 已安装但无法执行。重装(含 JS 支持):\n"
- f" {_YTDLP_UPGRADE_COMMAND}\n{probe.hint}"
- )
- if not probe.ok: # timeout / error:装了但跑不动
- self.active_backend = None
- detail = probe.hint or probe.output or probe.status
- return "error", f"yt-dlp 无法正常运行:{detail}"
- # yt-dlp 本体是活的;后面的 JS runtime/转写检查只影响 ok/warn,不影响后端归属
- self.active_backend = "yt-dlp"
- # Check JS runtime
- has_js = shutil.which("deno") or shutil.which("node")
- if not has_js:
- return "warn", (
- "yt-dlp 已安装但缺少 JS runtime(YouTube 必须)。\n"
- " 安装 Node.js 或 deno,然后运行:agent-reach install --system"
- )
- # Check yt-dlp config for --js-runtimes
- # Deno works out of the box; Node.js requires explicit config
- has_deno = shutil.which("deno")
- if not has_deno:
- ytdlp_config = get_ytdlp_config_path()
- if not _has_js_runtime_config(ytdlp_config):
- version = _parse_ytdlp_version(probe.output)
- if version is None:
- return "warn", (
- "无法确认 yt-dlp 版本是否支持 JS runtime 配置。"
- "请先升级并重新运行 doctor:\n"
- f" {_YTDLP_UPGRADE_COMMAND}"
- )
- if version < _JS_RUNTIMES_SUPPORTED_FROM:
- return "warn", (
- "yt-dlp 版本过旧,不支持 JS runtime 配置。请先升级并重新运行 doctor:\n"
- f" {_YTDLP_UPGRADE_COMMAND}"
- )
- return "warn", (
- f"yt-dlp 已安装但未配置 JS runtime。运行:\n {render_ytdlp_fix_command()}"
- )
- # Surface transcription readiness so `doctor` reports it.
- msg = "可提取视频信息和字幕"
- if config is not None:
- providers = []
- if config.is_configured("groq_whisper"):
- providers.append("groq")
- if config.is_configured("openai_whisper"):
- providers.append("openai")
- if providers:
- missing_media_tools = [
- tool
- for tool in ("ffmpeg", "ffprobe")
- if not shutil.which(tool)
- ]
- if missing_media_tools:
- msg += (
- "(音频转写需安装 "
- + "、".join(missing_media_tools)
- + ")"
- )
- else:
- msg += f",可转写音频({'/'.join(providers)})"
- return "ok", msg
-
- def transcribe(
- self,
- url: str,
- *,
- provider: str = "auto",
- config=None,
- allow_provider_fallback: bool = False,
- ) -> str:
- """Download a YouTube video's audio and return its transcript.
-
- Delegates to :func:`agent_reach.transcribe.transcribe`. Imported lazily
- so the channel module stays cheap to import for users who never
- transcribe.
- """
- from agent_reach.transcribe import transcribe as _transcribe
-
- return _transcribe(
- url,
- provider=provider,
- config=config,
- allow_provider_fallback=allow_provider_fallback,
- )
-
# ── unified entry backends ──
def _ytdlp_read(self, *, target: str, timeout: float) -> list:
diff --git a/agent_reach/cli.py b/agent_reach/cli.py
index 81f91d07..a705d6c5 100644
--- a/agent_reach/cli.py
+++ b/agent_reach/cli.py
@@ -1,42 +1,8 @@
# -*- coding: utf-8 -*-
-"""
-Agent Reach CLI — installer, doctor, and configuration tool.
+"""Console entry point for `agent-reach`; all commands live in agent_reach.runtime.cli."""
-Usage:
- agent-reach install --env=auto
- agent-reach doctor
- agent-reach configure twitter-cookies
- agent-reach setup
-"""
-
-import argparse
-import json
import os
import sys
-import time
-
-from agent_reach import __version__
-
-# Pinned to the 0.4.2 state — PyPI still only has 0.4.1 (upstream issue #10).
-_RDT_GIT_SOURCE = "git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66"
-# boss-agent-cli PRs #403-#407 are all merged into upstream master. Pin to a fixed
-# upstream commit that contains strict CDP, JobItem.lid, job_card_browser(), and the
-# throttle progress feedback. Never point the installer at a moving branch. Once an
-# upstream release containing #403/#404/#406 ships, switch to a version specifier.
-_BOSS_AGENT_CLI_PR_COMMIT = "4c991b77086a203173bf08a4cb64a23af6514fe6"
-_BOSS_AGENT_CLI_SOURCE = (
- "git+https://github.com/can4hou6joeng4/boss-agent-cli.git@"
- + _BOSS_AGENT_CLI_PR_COMMIT
-)
-_MAX_CONFIGURE_VALUE_CHARS = 1024 * 1024
-_SENSITIVE_CONFIG_KEYS = {
- "proxy",
- "github-token",
- "groq-key",
- "openai-key",
- "twitter-cookies",
- "xhs-cookies",
-}
def _ensure_utf8_console():
@@ -67,2340 +33,14 @@ def _configure_logging(verbose: bool = False):
def main():
_ensure_utf8_console()
+ argv = sys.argv[1:]
+ verbose = any(a in ("-v", "--verbose") for a in argv)
+ argv = [a for a in argv if a not in ("-v", "--verbose")]
+ _configure_logging(verbose)
- # Unified entry (`<channel> <action>`, `read`, `channels`, `check`) prints
- # JSON only and runs before the legacy argparse tree.
from agent_reach.runtime import cli as unified
- if unified.handles(sys.argv[1:]):
- _configure_logging(False)
- sys.exit(unified.main(sys.argv[1:]))
-
- parser = argparse.ArgumentParser(
- prog="agent-reach",
- description="Give your AI Agent eyes to see the entire internet",
- )
- parser.add_argument("-v", "--verbose", action="store_true", help="Show debug logs")
- parser.add_argument("--version", action="version", version=f"Agent Reach v{__version__}")
- sub = parser.add_subparsers(dest="command", help="Available commands")
-
- # ── setup ──
- sub.add_parser("setup", help="Interactive configuration wizard")
-
- # ── install ──
- p_install = sub.add_parser("install", help="One-shot installer with flags")
- p_install.add_argument("--env", choices=["local", "server", "auto"], default="auto",
- help="Environment: local, server, or auto-detect")
- p_install.add_argument("--proxy", default="",
- help="Network proxy saved for agents to export as HTTP(S)_PROXY "
- "in restricted networks (http://user:pass@ip:port)")
- install_mode = p_install.add_mutually_exclusive_group()
- install_mode.add_argument(
- "--system",
- action="store_true",
- help="Explicitly allow system dependency, global tool, config, and skill installation",
- )
- install_mode.add_argument(
- "--safe",
- action="store_true",
- help="Safe check-only mode (default; retained for compatibility)",
- )
- p_install.add_argument("--dry-run", action="store_true",
- help="Show what would be done without making any changes")
- p_install.add_argument("--channels", default="",
- help="Comma-separated optional channels to install "
- "(twitter,xiaoyuzhou,xueqiu,xiaohongshu,"
- "reddit,facebook,instagram,bilibili,linkedin,boss,all)")
-
- # ── configure ──
- p_conf = sub.add_parser("configure", help="Set a config value or auto-extract from browser")
- p_conf.add_argument("key", nargs="?", default=None,
- choices=["proxy", "github-token", "groq-key", "openai-key",
- "twitter-cookies", "youtube-cookies",
- "xhs-cookies"],
- help="What to configure (omit if using --from-browser)")
- p_conf.add_argument("value", nargs="*", help="The value(s) to set")
- p_conf.add_argument(
- "--stdin",
- dest="read_stdin",
- action="store_true",
- help="Read the value from stdin instead of exposing it in process arguments",
- )
- p_conf.add_argument("--from-browser", metavar="BROWSER",
- choices=["chrome", "firefox", "edge", "brave", "opera"],
- help="Extract cookies for one explicitly selected platform")
- p_conf.add_argument(
- "--platform",
- choices=["twitter", "xiaohongshu", "bilibili", "xueqiu"],
- help="Platform to import (required with --from-browser)",
- )
- p_conf.add_argument(
- "--profile",
- help="Exact browser profile; a missing profile fails instead of falling back",
- )
- p_conf.add_argument(
- "--sync-legacy-twitter",
- action="store_true",
- help="With twitter-cookies, also write legacy xfetch/bird credential files",
- )
-
- # ── doctor ──
- p_doctor = sub.add_parser("doctor", help="Check platform availability")
- p_doctor.add_argument("--json", action="store_true",
- help="Output machine-readable JSON instead of the text report")
-
- # ── uninstall ──
- p_uninstall = sub.add_parser("uninstall", help="Remove all Agent Reach config, tokens, and skill files")
- p_uninstall.add_argument("--dry-run", action="store_true",
- help="Show what would be removed without making any changes")
- p_uninstall.add_argument("--keep-config", action="store_true",
- help="Remove skill files only, keep ~/.agent-reach/ config and tokens")
-
- # ── skill ──
- p_skill = sub.add_parser("skill", help="Manage agent skill registration")
- p_skill_group = p_skill.add_mutually_exclusive_group(required=True)
- p_skill_group.add_argument("--install", action="store_true",
- help="Install SKILL.md to agent skill directories")
- p_skill_group.add_argument("--uninstall", action="store_true",
- help="Remove SKILL.md from agent skill directories")
-
- # ── format ──
- p_format = sub.add_parser("format", help="Clean and format platform API output")
- p_format.add_argument("platform", choices=["xhs"], help="Platform to format (xhs)")
-
- # ── check-update ──
- # ── transcribe ──
- p_tr = sub.add_parser("transcribe", help="Transcribe a URL or local audio file (Whisper via Groq/OpenAI)")
- p_tr.add_argument("source", help="Audio/video URL or local file path")
- p_tr.add_argument("--provider", choices=["auto", "groq", "openai"], default="auto",
- help="Transcription provider (default: first configured provider)")
- p_tr.add_argument(
- "--allow-provider-fallback",
- action="store_true",
- help=(
- "With --provider auto, allow sending audio to the next "
- "configured provider after a failure"
- ),
- )
- p_tr.add_argument("-o", "--output", default=None,
- help="Write transcript to a file instead of stdout")
-
- sub.add_parser("check-update", help="Check for new versions and changes")
-
- # ── watch ──
- sub.add_parser("watch", help="Quick health check + update check (for scheduled tasks)")
-
- # ── version ──
- sub.add_parser("version", help="Show version")
-
- args = parser.parse_args()
-
- if args.command == "configure" and args.from_browser:
- if args.read_stdin:
- p_conf.error("--stdin cannot be combined with --from-browser")
- if not args.platform:
- p_conf.error("--platform is required with --from-browser")
- manual_keys = {
- "twitter": "twitter-cookies",
- "xiaohongshu": "xhs-cookies",
- }
- if args.platform in manual_keys:
- p_conf.error(
- f"{args.platform} requires Cookie-Editor export; use "
- f"`agent-reach configure {manual_keys[args.platform]} ...`"
- )
- if args.profile and args.from_browser not in {"chrome", "edge", "brave"}:
- p_conf.error(
- "--profile is supported only for Chrome/Edge/Brave"
- )
- if args.sync_legacy_twitter:
- p_conf.error("--sync-legacy-twitter is only valid with twitter-cookies")
- elif args.command == "configure":
- if args.read_stdin and args.value:
- p_conf.error("--stdin cannot be combined with a positional value")
- if args.read_stdin and not args.key:
- p_conf.error("--stdin requires a configure key")
- if args.profile or args.platform:
- p_conf.error("--platform/--profile require --from-browser")
- if args.sync_legacy_twitter and args.key != "twitter-cookies":
- p_conf.error("--sync-legacy-twitter is only valid with twitter-cookies")
-
- if (
- args.command == "transcribe"
- and args.allow_provider_fallback
- and args.provider != "auto"
- ):
- p_tr.error("--allow-provider-fallback requires --provider auto")
-
- # Suppress loguru noise unless --verbose
- _configure_logging(getattr(args, "verbose", False))
-
- if not args.command:
- parser.print_help()
- sys.exit(0)
-
- if args.command == "version":
- print(f"Agent Reach v{__version__}")
- sys.exit(0)
-
- if args.command == "doctor":
- _cmd_doctor(args)
- elif args.command == "check-update":
- _cmd_check_update()
- elif args.command == "watch":
- _cmd_watch()
- elif args.command == "setup":
- _cmd_setup()
- elif args.command == "install":
- _cmd_install(args)
- elif args.command == "configure":
- _cmd_configure(args)
- elif args.command == "uninstall":
- _cmd_uninstall(args)
- elif args.command == "skill":
- _cmd_skill(args)
- elif args.command == "format":
- _cmd_format(args)
- elif args.command == "transcribe":
- _cmd_transcribe(args)
-
-
-# ── Command handlers ────────────────────────────────
-
-
-def _cmd_install(args):
- """One-shot deterministic installer."""
- import os
-
- from agent_reach.config import Config
- from agent_reach.doctor import check_all, format_report
-
- safe_mode = getattr(args, "safe", False) or not getattr(args, "system", False)
- dry_run = args.dry_run
-
- # Validate channel names before constructing config or changing the system.
- CHANNEL_INSTALLERS = {
- "twitter": _install_twitter_deps,
- "xiaoyuzhou": _install_xiaoyuzhou_deps,
- "xiaohongshu": _install_xhs_deps,
- "reddit": _install_reddit_deps,
- "facebook": _install_opencli_deps,
- "instagram": _install_opencli_deps,
- "bilibili": _install_bili_deps,
- "boss": _install_boss_deps,
- "opencli": _install_opencli_deps, # cross-channel backend, desktop only
- # xueqiu: cookie-only, no install step
- # linkedin: manual setup, no auto-install
- }
- supported_channels = set(CHANNEL_INSTALLERS) | {"xueqiu", "linkedin"}
- raw_channels = [
- channel.strip().lower()
- for channel in args.channels.split(",")
- if channel.strip()
- ]
- unknown_channels = set(raw_channels) - supported_channels - {"all"}
- if unknown_channels:
- supported = ", ".join(sorted(supported_channels | {"all"}))
- unknown = ", ".join(sorted(unknown_channels))
- print(
- f"agent-reach install: error: unknown channel(s): {unknown}. "
- f"Supported: {supported}",
- file=sys.stderr,
- )
- raise SystemExit(2)
-
- if "all" in raw_channels:
- requested_channels = supported_channels
- else:
- requested_channels = set(raw_channels)
-
- config = Config(read_only=dry_run or safe_mode)
- print()
- print("Agent Reach Installer")
- print("=" * 40)
-
- if dry_run:
- print("DRY RUN — showing what would be done (no changes)")
- print()
- if safe_mode:
- print("SAFE MODE — skipping automatic system changes")
- print()
-
- # Only a real installation may create persistent directories.
- if not dry_run and not safe_mode:
- tools_dir = os.path.expanduser("~/.agent-reach/tools")
- os.makedirs(tools_dir, exist_ok=True)
-
- DESKTOP_ONLY_CHANNELS = {"opencli", "facebook", "instagram", "boss"}
- COOKIE_CHANNELS = {"twitter", "xueqiu", "bilibili", "xiaohongshu"}
-
- # Auto-detect environment
- env = args.env
- if env == "auto":
- env = _detect_environment()
-
- if env == "server":
- print("Environment: Server/VPS (auto-detected)")
- else:
- print("Environment: Local computer (auto-detected)")
-
- server_skipped_desktop_channels = set()
- if env == "server" and requested_channels:
- # Browser-session channels require a real desktop Chrome.
- server_skipped_desktop_channels = requested_channels & DESKTOP_ONLY_CHANNELS
- requested_channels -= server_skipped_desktop_channels
-
- # Apply explicit flags
- if args.proxy:
- if dry_run or safe_mode:
- mode = "dry-run" if dry_run else "safe"
- print(f"[{mode}] Would save network proxy")
- else:
- config.set("proxy", args.proxy)
- config.set("bilibili_proxy", args.proxy) # legacy key
- print("✅ 代理已保存(Agent 访问受限网络时使用)")
-
- # ── Install core system dependencies (lightweight, always) ──
- print()
- core_install_ok = True
- if dry_run:
- _install_system_deps_dryrun()
- elif safe_mode:
- _install_system_deps_safe()
- else:
- core_install_ok = _install_system_deps() is not False
-
- # ── mcporter (for Exa search) ──
- print()
- if dry_run:
- print("[dry-run] Would install mcporter and configure Exa search")
- elif safe_mode:
- _install_mcporter_safe()
- else:
- core_install_ok = (_install_mcporter() is not False) and core_install_ok
-
- if server_skipped_desktop_channels:
- print()
- print(" -- 以下渠道需要桌面环境 + Chrome,服务器环境跳过:"
- f"{', '.join(sorted(server_skipped_desktop_channels))}")
-
- # ── Install optional channels (only if --channels specified) ──
- if requested_channels and not dry_run and not safe_mode:
- print()
- print("Installing optional channels...")
- ran_installers = set()
- optional_install_ok = True
- for ch_name in sorted(requested_channels):
- installer = CHANNEL_INSTALLERS.get(ch_name)
- if installer and installer not in ran_installers:
- optional_install_ok = (
- installer() is not False
- ) and optional_install_ok
- ran_installers.add(installer)
- else:
- optional_install_ok = True
-
- if requested_channels and dry_run:
- print()
- print(f"[dry-run] Would install optional channels: {', '.join(sorted(requested_channels))}")
-
- # ── Cookie setup (explicit only — install never reads browser credentials) ──
- needs_cookies = bool(requested_channels & COOKIE_CHANNELS)
- if env == "local" and needs_cookies and not dry_run:
- print()
- print("Cookie login is never read automatically.")
- print("Run only the platform command you intend to authorize:")
- for channel in sorted(requested_channels & COOKIE_CHANNELS):
- if channel == "twitter":
- print(" agent-reach configure twitter-cookies")
- elif channel == "xiaohongshu":
- print(" agent-reach configure xhs-cookies")
- else:
- print(
- " agent-reach configure --from-browser chrome "
- f"--platform {channel}"
- )
- elif env == "local" and needs_cookies and dry_run:
- print()
- print("[dry-run] Cookie import remains explicit; install will not read a browser")
-
- # Environment-specific advice
- if env == "server":
- print()
- print("Tip: 部分平台对服务器 IP 有风控。")
- print(" Reddit 必须登录态(rdt-cli + Cookie,见 doctor 提示),中国大陆网络还需代理。")
- print(" 保存代理供 Agent 使用:agent-reach configure proxy(隐藏输入)")
- print(" Cheap option: https://www.webshare.io ($1/month)")
-
- # Test channels
- if not dry_run:
- print()
- print("Testing channels...")
- results = check_all(config)
- ok = sum(1 for r in results.values() if r["status"] == "ok")
- total = len(results)
-
- # Final status
- print()
- print(format_report(results))
- print()
-
- if safe_mode:
- print(
- "Safe mode check complete. No changes were made. "
- f"{ok}/{total} channels active."
- )
- else:
- # ── Install agent skill ──
- skill_install_ok = _install_skill() is not False
- install_ok = (
- core_install_ok and optional_install_ok and skill_install_ok
- )
-
- if install_ok:
- print(f"Installation complete. {ok}/{total} channels active.")
- else:
- print(
- "Installation incomplete: one or more requested "
- f"steps failed. {ok}/{total} channels active."
- )
-
- if not requested_channels:
- # First install — hint about optional channels
- print()
- print("More channels available! Use --channels to install:")
- print(" agent-reach install --system --channels=twitter,xiaohongshu,reddit,facebook,instagram,...")
- print(" agent-reach install --system --channels=all (install everything)")
-
- # Star reminder
- print()
- print("如果 Agent Reach 帮到了你,给个 Star 让更多人发现它吧:")
- print(" https://github.com/Panniantong/Agent-Reach")
- print(" 只需一秒,对独立开发者意义很大。谢谢!")
- if not install_ok:
- raise SystemExit(1)
- else:
- print()
- print("Dry run complete. No changes were made.")
-
-
-def _install_skill(force: bool = True):
- """Install Agent Reach as an agent skill for supported agent clients."""
- import importlib.resources
- import os
- import shutil
-
- def _is_english_locale(value: str) -> bool:
- normalized = value.strip().lower()
- return normalized.startswith("en") or normalized.startswith("english")
-
- def _skill_resource_name() -> str:
- locale_candidates = (
- os.environ.get("AGENT_REACH_LANG", ""),
- os.environ.get("LC_ALL", ""),
- os.environ.get("LC_MESSAGES", ""),
- os.environ.get("LANG", ""),
- )
- if any(_is_english_locale(candidate) for candidate in locale_candidates):
- return "SKILL_en.md"
- return "SKILL.md"
-
- def _read_skill_markdown(skill_pkg):
- resource_name = _skill_resource_name()
- try:
- return skill_pkg.joinpath(resource_name).read_text(encoding="utf-8")
- except FileNotFoundError:
- return skill_pkg.joinpath("SKILL.md").read_text(encoding="utf-8")
-
- def _copy_skill_dir(target: str) -> str | None:
- """Copy entire skill directory (locale-specific SKILL.md + references/)."""
- try:
- if not force and os.path.exists(os.path.join(target, "SKILL.md")):
- return "preserved"
-
- # Clear existing installation. A symlinked skill dir (dotfiles
- # setups) breaks shutil.rmtree — unlink the link itself instead.
- if os.path.islink(target):
- os.unlink(target)
- elif os.path.exists(target):
- shutil.rmtree(target)
- os.makedirs(target, exist_ok=True)
-
- # Get skill directory from package (with fallback for editable installs)
- try:
- skill_pkg = importlib.resources.files("agent_reach").joinpath("skill")
- skill_md = _read_skill_markdown(skill_pkg)
- except Exception:
- from pathlib import Path
- skill_pkg = Path(__file__).resolve().parent / "skill"
- skill_md = _read_skill_markdown(skill_pkg)
-
- # Copy SKILL.md using the selected locale file
- with open(os.path.join(target, "SKILL.md"), "w", encoding="utf-8") as f:
- f.write(skill_md)
-
- # Copy references/ directory
- refs_pkg = skill_pkg.joinpath("references")
- refs_target = os.path.join(target, "references")
- os.makedirs(refs_target, exist_ok=True)
-
- for ref_file in refs_pkg.iterdir():
- name = ref_file.name if hasattr(ref_file, 'name') else str(ref_file).split('/')[-1]
- if name.endswith(".md"):
- content = ref_file.read_text(encoding="utf-8") if hasattr(ref_file, 'read_text') else ref_file.read_text()
- with open(os.path.join(refs_target, name), "w", encoding="utf-8") as f:
- f.write(content)
-
- return "installed"
- except Exception as e:
- print(f" Warning: Could not install skill: {e}")
- return None
-
- # Install into every known skill root that already exists.
- skill_dirs = [
- (os.path.expanduser("~/.agents/skills"), "Agent"),
- (os.path.expanduser("~/.config/opencode/skills"), "OpenCode"),
- (os.path.expanduser("~/.openclaw/skills"), "OpenClaw"),
- (os.path.expanduser("~/.claude/skills"), "Claude Code"),
- ]
-
- # Insert OPENCLAW_HOME path at the beginning if environment variable is set
- openclaw_home = os.environ.get("OPENCLAW_HOME")
- if openclaw_home:
- skill_dirs.insert(
- 0,
- (os.path.join(openclaw_home, ".openclaw", "skills"), "OpenClaw"),
- )
-
- installed = False
- for skill_dir, platform_name in skill_dirs:
- if os.path.isdir(skill_dir):
- target = os.path.join(skill_dir, "agent-reach")
- status = _copy_skill_dir(target)
- if status:
- if status == "preserved":
- print(f"Skill already installed for {platform_name}, preserving existing files: {target}")
- else:
- print(f"Skill installed for {platform_name}: {target}")
- installed = True
-
- if not installed:
- # No known skill directory found — create for .agents by default
- target = os.path.expanduser("~/.agents/skills/agent-reach")
- os.makedirs(os.path.dirname(target), exist_ok=True)
- status = _copy_skill_dir(target)
- if status == "preserved":
- print(f"Skill already installed, preserving existing files: {target}")
- elif status == "installed":
- print(f"Skill installed: {target}")
- installed = True
- else:
- print(" -- Could not install agent skill (optional)")
- print(
- " -- Tip: install OpenCode, OpenClaw, Claude Code, "
- "or create ~/.agents/skills/ manually"
- )
- return installed
-
-
-def _uninstall_skill():
- """Remove SKILL.md from all known agent skill directories."""
- import shutil
-
- skill_dirs = [
- ("~/.config/opencode/skills/agent-reach", "OpenCode"),
- ("~/.openclaw/skills/agent-reach", "OpenClaw"),
- ("~/.claude/skills/agent-reach", "Claude Code"),
- ("~/.agents/skills/agent-reach", "Agent"),
- ]
-
- # Also check OPENCLAW_HOME
- openclaw_home = os.environ.get("OPENCLAW_HOME")
- if openclaw_home:
- skill_dirs.insert(
- 0,
- (os.path.join(openclaw_home, ".openclaw", "skills", "agent-reach"), "OpenClaw"),
- )
-
- removed = False
- for skill_path_template, platform_name in skill_dirs:
- skill_path = os.path.expanduser(skill_path_template)
- if os.path.isdir(skill_path):
- try:
- if os.path.islink(skill_path):
- os.unlink(skill_path)
- else:
- shutil.rmtree(skill_path)
- print(f" Removed {platform_name} skill: {skill_path}")
- removed = True
- except Exception as e:
- print(f" Could not remove {skill_path}: {e}")
-
- if not removed:
- print(" No skill installations found.")
-
-
-def _cmd_skill(args):
- """Manage agent skill registration."""
- if args.install:
- if not _install_skill():
- raise SystemExit(1)
- elif args.uninstall:
- _uninstall_skill()
-
-
-def _cmd_format(args):
- """Clean and format platform API output from stdin."""
- import json
- import sys
-
- if args.platform == "xhs":
- from agent_reach.channels.xiaohongshu import format_xhs_result
-
- raw = sys.stdin.read().strip()
- if not raw:
- print("Error: no input on stdin", file=sys.stderr)
- sys.exit(1)
- try:
- data = json.loads(raw)
- except json.JSONDecodeError as e:
- print(f"Error: invalid JSON: {e}", file=sys.stderr)
- sys.exit(1)
-
- cleaned = format_xhs_result(data)
- print(json.dumps(cleaned, ensure_ascii=False, indent=2))
-
-
-def _install_system_deps():
- """Install system dependencies through an existing OS package manager."""
- import platform
- import shutil
- import subprocess
-
- print("Checking system dependencies...")
-
- gh_installed = bool(shutil.which("gh"))
- node_installed = bool(shutil.which("node") and shutil.which("npm"))
-
- if gh_installed:
- print(" ✅ gh CLI already installed")
- if node_installed:
- print(" ✅ Node.js already installed")
-
- missing_labels = []
- if not gh_installed:
- missing_labels.append("gh CLI")
- if not node_installed:
- missing_labels.append("Node.js")
- system_install_ok = not missing_labels
-
- os_type = platform.system().lower()
- if missing_labels and os_type == "linux":
- apt_get = shutil.which("apt-get")
- if not apt_get:
- system_install_ok = False
- print(
- " [!] Missing system dependencies: "
- f"{', '.join(missing_labels)}. apt-get is not available; "
- "install them manually."
- )
- else:
- packages = []
- if not gh_installed:
- packages.append("gh")
- if not node_installed:
- packages.extend(("nodejs", "npm"))
- print(f" Installing {', '.join(missing_labels)} with apt-get...")
- try:
- update_result = subprocess.run(
- [apt_get, "update", "-qq"],
- capture_output=True,
- timeout=120,
- )
- if update_result.returncode != 0:
- system_install_ok = False
- print(
- " [!] apt-get update failed; no packages were installed."
- )
- else:
- install_result = subprocess.run(
- [apt_get, "install", "-y", "-qq", *packages],
- capture_output=True,
- timeout=180,
- )
- if install_result.returncode == 0:
- system_install_ok = True
- print(
- " ✅ Installed with apt-get: "
- f"{', '.join(missing_labels)}"
- )
- else:
- system_install_ok = False
- print(
- " [!] apt-get install failed for: "
- f"{', '.join(missing_labels)}"
- )
- except (OSError, subprocess.TimeoutExpired):
- system_install_ok = False
- print(
- " [!] apt-get failed for: "
- f"{', '.join(missing_labels)}"
- )
- elif missing_labels and os_type == "darwin":
- brew = shutil.which("brew")
- if not brew:
- system_install_ok = False
- print(
- " [!] Missing system dependencies: "
- f"{', '.join(missing_labels)}. Homebrew is not available; "
- "install them manually."
- )
- else:
- system_install_ok = True
- brew_packages = []
- if not gh_installed:
- brew_packages.append(("gh", "gh CLI"))
- if not node_installed:
- brew_packages.append(("node", "Node.js"))
- for package, label in brew_packages:
- print(f" Installing {label} with Homebrew...")
- try:
- undici_result = subprocess.run(
- [brew, "install", package],
- capture_output=True,
- timeout=180,
- )
- if undici_result.returncode == 0:
- print(f" ✅ {label} installed")
- else:
- system_install_ok = False
- print(f" [!] {label} install failed")
- except (OSError, subprocess.TimeoutExpired):
- system_install_ok = False
- print(f" [!] {label} install failed")
- elif missing_labels:
- system_install_ok = False
- print(
- " [!] Missing system dependencies: "
- f"{', '.join(missing_labels)}. Install them manually."
- )
-
- # ── undici (proxy support for Node.js fetch) ──
- npm_cmd = shutil.which("npm")
- if npm_cmd:
- try:
- npm_root_result = subprocess.run(
- [npm_cmd, "root", "-g"],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=5,
- )
- except (OSError, subprocess.TimeoutExpired):
- npm_root_result = None
-
- if npm_root_result is None or npm_root_result.returncode != 0:
- print(
- " -- Could not inspect global npm packages; "
- "skipping optional undici install"
- )
- else:
- npm_root = npm_root_result.stdout.strip()
- undici_path = (
- os.path.join(npm_root, "undici", "index.js")
- if npm_root
- else ""
- )
- if os.path.exists(undici_path):
- print(" ✅ undici already installed (Node.js proxy support)")
- else:
- try:
- result = subprocess.run(
- [npm_cmd, "install", "-g", "undici"],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=60,
- )
- if result.returncode == 0:
- print(" ✅ undici installed (Node.js proxy support)")
- else:
- print(
- " -- undici install failed "
- "(optional — may not work behind proxies)"
- )
- except (OSError, subprocess.TimeoutExpired):
- print(
- " -- undici install failed "
- "(optional — may not work behind proxies)"
- )
-
- # ── yt-dlp JS runtime config (YouTube requires external JS runtime) ──
- if shutil.which("deno"):
- print(" ✅ yt-dlp can use the installed Deno JS runtime")
- elif shutil.which("node"):
- from agent_reach.channels.youtube import (
- _JS_RUNTIMES_SUPPORTED_FROM,
- _parse_ytdlp_version,
- )
- from agent_reach.utils.paths import (
- PrivatePathError,
- atomic_write_private_text,
- get_ytdlp_config_path,
- read_small_text_no_follow,
- )
-
- ytdlp_cmd = shutil.which("yt-dlp")
- installed_version = None
- if ytdlp_cmd:
- try:
- version_result = subprocess.run(
- [ytdlp_cmd, "--version"],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=10,
- )
- if version_result.returncode == 0:
- installed_version = _parse_ytdlp_version(
- version_result.stdout.strip()
- )
- except (OSError, subprocess.TimeoutExpired):
- installed_version = None
-
- if (
- installed_version is None
- or installed_version < _JS_RUNTIMES_SUPPORTED_FROM
- ):
- print(
- " -- 未写入 yt-dlp JS runtime 配置:yt-dlp 缺失、过旧或"
- "版本无法确认。先升级:python -m pip install -U "
- '"yt-dlp[default]"'
- )
- else:
- ytdlp_config = get_ytdlp_config_path()
- try:
- existing_config = read_small_text_no_follow(
- ytdlp_config,
- max_bytes=1024 * 1024,
- )
- if (
- existing_config is not None
- and "--js-runtimes" in existing_config
- ):
- print(" ✅ yt-dlp JS runtime already configured")
- else:
- existing_config = existing_config or ""
- separator = (
- ""
- if not existing_config
- or existing_config.endswith(("\n", "\r"))
- else "\n"
- )
- atomic_write_private_text(
- ytdlp_config,
- existing_config
- + separator
- + "--js-runtimes node\n",
- )
- print(
- " ✅ yt-dlp configured to use Node.js as JS runtime "
- "(YouTube)"
- )
- except (OSError, UnicodeError, ValueError, PrivatePathError):
- print(
- " -- Could not configure yt-dlp JS runtime "
- "(YouTube may not work)"
- )
-
- # NOTE: twitter-cli, xiaoyuzhou, xhs-cli etc. are optional.
- # They are installed via --channels flag, not here.
- # See CHANNEL_INSTALLERS in _cmd_install().
- return system_install_ok
-
-
-def _install_xiaoyuzhou_deps():
- """Install Xiaoyuzhou podcast transcription script."""
- import shutil
-
- from agent_reach.config import Config
- from agent_reach.utils.paths import PrivatePathError, atomic_write_private_text
-
- config = Config()
- print("Setting up Xiaoyuzhou podcast transcription...")
-
- tools_dir = os.path.expanduser("~/.agent-reach/tools/xiaoyuzhou")
- script_dst = os.path.join(tools_dir, "transcribe.sh")
-
- script_src = os.path.join(
- os.path.dirname(__file__),
- "scripts",
- "transcribe_xiaoyuzhou.sh",
- )
- script_ok = False
- if os.path.isfile(script_src):
- existed = os.path.isfile(script_dst)
- try:
- with open(script_src, encoding="utf-8") as source:
- script_text = source.read()
- atomic_write_private_text(script_dst, script_text)
- os.chmod(script_dst, 0o700)
- action = "updated" if existed else "installed"
- print(f" ✅ Xiaoyuzhou transcription script {action}")
- script_ok = True
- except (OSError, UnicodeError, PrivatePathError) as exc:
- print(f" [!] Failed to install script: {exc}")
- else:
- print(" [!] Script source not found in package")
-
- # Check ffmpeg
- ffmpeg_ok = bool(shutil.which("ffmpeg"))
- if ffmpeg_ok:
- print(" ✅ ffmpeg available")
- else:
- print(" -- ffmpeg not found. Install: apt install -y ffmpeg (or brew install ffmpeg)")
-
- # Check GROQ_API_KEY
- has_key = bool(os.environ.get("GROQ_API_KEY")) or bool(config.get("groq_api_key"))
- if has_key:
- print(" ✅ Groq API key configured")
- else:
- print(" -- Groq API key not set. Get free key at https://console.groq.com")
- print(" Then run: agent-reach configure groq-key(隐藏输入)")
- return script_ok and ffmpeg_ok
-
-
-def _install_twitter_deps():
- """Install twitter-cli for Twitter search + timeline."""
- import shutil
- import subprocess
-
- print("Setting up Twitter (twitter-cli)...")
- if shutil.which("twitter"):
- print(" ✅ twitter-cli already installed")
- return True
- for tool, args in [
- ("pipx", ["install", "twitter-cli"]),
- ("uv", ["tool", "install", "twitter-cli"]),
- ]:
- tool_cmd = shutil.which(tool)
- if tool_cmd:
- try:
- result = subprocess.run(
- [tool_cmd, *args], capture_output=True, encoding="utf-8",
- errors="replace", timeout=120,
- )
- if result.returncode == 0 and shutil.which("twitter"):
- print(" ✅ twitter-cli installed")
- return True
- except (OSError, subprocess.TimeoutExpired):
- pass
- print(" [!] twitter-cli install failed. Run: pipx install twitter-cli")
- return False
-
-
-def _install_boss_deps():
- """Install the strict-CDP boss-agent-cli build required by the Boss channel.
-
- Upstream boss-agent-cli PRs #403-#407 are all merged into master; the source is
- pinned to a fixed upstream commit containing those five PRs. Force-installing is
- intentional: PyPI 1.18.0 exposes the ``boss`` executable but lacks the public
- strict-CDP APIs required by this channel.
- """
- import shutil
- import subprocess
-
- print("Setting up Boss直聘 (boss-agent-cli upstream pinned commit)...")
- for tool, args in [
- ("pipx", ["install", "--force", _BOSS_AGENT_CLI_SOURCE]),
- ("uv", ["tool", "install", "--force", _BOSS_AGENT_CLI_SOURCE]),
- ]:
- tool_cmd = shutil.which(tool)
- if not tool_cmd:
- continue
- try:
- result = subprocess.run(
- [tool_cmd, *args],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=300,
- )
- if result.returncode == 0 and shutil.which("boss"):
- print(" ✅ boss-agent-cli installed from pinned upstream commit")
- print(" 下一步:启动专用 Chrome,由用户手动登录 zhipin.com,再运行 agent-reach doctor")
- return True
- except (OSError, subprocess.TimeoutExpired):
- pass
-
- print(" [!] boss-agent-cli install failed. Install pipx or uv, then retry:")
- print(f" pipx install --force '{_BOSS_AGENT_CLI_SOURCE}'")
- return False
-
-
-def _install_xhs_deps():
- """Set up XiaoHongShu — backend depends on environment.
-
- Desktop: OpenCLI (reuses the browser session, zero config).
- Server: xiaohongshu-mcp guide with an explicit Cookie-Editor export;
- we don't manage long-running services, so guide only.
- xhs-cli is no longer installed by default — upstream unmaintained
- since 2026-03; existing installs keep working as a fallback backend.
- """
- import shutil
-
- print("Setting up XiaoHongShu...")
- if _detect_environment() == "server":
- print(" 服务器环境推荐 xiaohongshu-mcp:")
- print(" 1. 下载 binary:https://github.com/xpzouying/xiaohongshu-mcp/releases")
- print(" (建议放到 ~/.agent-reach/tools/ 下)")
- print(" 2. 启动服务(首次运行会下载约 150MB 浏览器,请等待完成)")
- print(" 3. 用 Cookie-Editor 从 xiaohongshu.com 明确导出 Cookie")
- print(" agent-reach configure xhs-cookies(粘贴到隐藏输入提示)")
- print(" 4. 接入:mcporter config add xiaohongshu http://localhost:18060/mcp --scope home")
- print(" 5. 验证:agent-reach doctor")
- return False
-
- opencli_ok = _install_opencli_deps()
- xhs_ok = bool(shutil.which("xhs"))
- if xhs_ok:
- print(" ✅ 检测到存量 xhs-cli,将作为备选后端继续可用")
- return opencli_ok or xhs_ok
-
-
-def _install_opencli_deps():
- """Install OpenCLI — cross-platform backend riding the user's Chrome session.
-
- Desktop-only. The npm package installs automatically; the Chrome
- extension CANNOT be installed programmatically (Chrome security model),
- so we print a one-click guide instead.
- """
- import shutil
- import subprocess
-
- from agent_reach.backends import (
- OPENCLI_EXTENSION_URL,
- OPENCLI_PACKAGE,
- opencli_status,
- opencli_summary,
- )
-
- print("Setting up OpenCLI (browser-session backend, desktop only)...")
- st = opencli_status()
- if st.installed and not st.broken:
- print(f" ✅ {opencli_summary(st)}")
- if not st.ready:
- print(f" {st.hint}")
- return True
-
- npm_cmd = shutil.which("npm")
- if not npm_cmd:
- print(" [!] OpenCLI requires Node.js ≥ 20. Install Node first:")
- print(" https://nodejs.org (或 brew install node)")
- return False
-
- try:
- install_result = subprocess.run(
- [npm_cmd, "install", "-g", OPENCLI_PACKAGE],
- capture_output=True, encoding="utf-8", errors="replace", timeout=300,
- )
- except (OSError, subprocess.TimeoutExpired):
- install_result = None
-
- st = opencli_status()
- if (
- install_result is not None
- and install_result.returncode == 0
- and st.installed
- and not st.broken
- ):
- print(" ✅ OpenCLI installed")
- print(" 最后一步(必须手动,Chrome 安全限制):安装浏览器扩展")
- print(f" 1. 打开 {OPENCLI_EXTENSION_URL}")
- print(" 2. 点「添加至 Chrome」")
- print(" 3. 运行 `opencli doctor` 验证连接")
- return True
- else:
- print(f" [!] OpenCLI install failed. Run: npm install -g {OPENCLI_PACKAGE}")
- return False
-
-
-def _install_reddit_deps():
- """Set up Reddit — desktop prefers OpenCLI, rdt-cli for servers/legacy.
-
- No zero-config path exists (anonymous .json blocked, official API
- approval-gated since 2025-11) — every backend needs a logged-in session.
- """
- if _detect_environment() != "server":
- installed = _install_opencli_deps()
- print(" Reddit 走 OpenCLI(浏览器里登录过 reddit.com 即可用)")
- import shutil
- if shutil.which("rdt"):
- print(" ✅ 检测到存量 rdt-cli,将作为备选后端继续可用")
- return installed
-
- return _install_rdt_cli()
-
-
-def _install_rdt_cli():
- """Install rdt-cli (pinned git source — PyPI lags upstream)."""
- import shutil
- import subprocess
-
- print("Setting up Reddit (rdt-cli)...")
- if shutil.which("rdt"):
- print(" ✅ rdt-cli already installed")
- return True
- for tool, args in [
- ("pipx", ["install", _RDT_GIT_SOURCE]),
- ("uv", ["tool", "install", "--from", _RDT_GIT_SOURCE, "rdt-cli"]),
- ]:
- tool_cmd = shutil.which(tool)
- if tool_cmd:
- try:
- result = subprocess.run(
- [tool_cmd, *args], capture_output=True, encoding="utf-8",
- errors="replace", timeout=120,
- )
- if result.returncode == 0 and shutil.which("rdt"):
- print(" ✅ rdt-cli installed")
- return True
- except (OSError, subprocess.TimeoutExpired):
- pass
- print(f" [!] rdt-cli install failed. Run: pipx install '{_RDT_GIT_SOURCE}'")
- return False
-
-
-def _install_bili_deps():
- """Install bili-cli for Bilibili hot/rank/search."""
- import shutil
- import subprocess
-
- print("Setting up Bilibili (bili-cli)...")
- if shutil.which("bili"):
- print(" ✅ bili-cli already installed")
- return True
- for tool, args in [
- ("pipx", ["install", "bilibili-cli"]),
- ("uv", ["tool", "install", "bilibili-cli"]),
- ]:
- tool_cmd = shutil.which(tool)
- if tool_cmd:
- try:
- result = subprocess.run(
- [tool_cmd, *args], capture_output=True, encoding="utf-8",
- errors="replace", timeout=120,
- )
- if result.returncode == 0 and shutil.which("bili"):
- print(" ✅ bili-cli installed")
- return True
- except (OSError, subprocess.TimeoutExpired):
- pass
- print(" [!] bili-cli install failed. Run: pipx install bilibili-cli")
- return False
-
-
-def _install_system_deps_safe():
- """Safe mode: check what's installed, print instructions for what's missing."""
- import shutil
-
- print("Checking system dependencies (safe mode — no auto-install)...")
-
- deps = [
- ("gh", ["gh"], "GitHub CLI", "https://cli.github.com — or: apt install gh / brew install gh"),
- ("node", ["node", "npm"], "Node.js", "https://nodejs.org — or: apt install nodejs npm"),
- ]
-
- missing = []
- for name, binaries, label, install_hint in deps:
- found = all(shutil.which(b) for b in binaries)
- if found:
- print(f" ✅ {label} already installed")
- else:
- print(f" -- {label} not found")
- missing.append((label, install_hint))
-
- if missing:
- print()
- print(" To install missing dependencies manually:")
- for label, hint in missing:
- print(f" {label}: {hint}")
- else:
- print(" All system dependencies are installed!")
-
-
-def _install_system_deps_dryrun():
- """Dry-run: just show what would be checked/installed."""
- import shutil
-
- print("[dry-run] System dependency check:")
-
- checks = [
- ("gh CLI", ["gh"], "apt-get install gh / brew install gh"),
- (
- "Node.js",
- ["node", "npm"],
- "apt-get install nodejs npm / brew install node",
- ),
- ]
-
- for label, binaries, method in checks:
- found = all(shutil.which(b) for b in binaries)
- if found:
- print(f" ✅ {label}: already installed, skip")
- else:
- print(f" {label}: would install via: {method}")
-
-
-
-def _install_mcporter():
- """Install mcporter and configure Exa search."""
- import shutil
- import subprocess
-
- print("Setting up mcporter (search backend)...")
-
- mcporter_cmd = shutil.which("mcporter")
- if mcporter_cmd:
- print(" ✅ mcporter already installed")
- else:
- npm_cmd = shutil.which("npm")
- if not npm_cmd:
- print(" [!] mcporter requires Node.js. Install Node.js first:")
- print(" https://nodejs.org/")
- return False
- try:
- install_result = subprocess.run(
- [npm_cmd, "install", "-g", "mcporter"],
- capture_output=True, encoding="utf-8", errors="replace", timeout=120,
- )
- mcporter_cmd = shutil.which("mcporter")
- if install_result.returncode == 0 and mcporter_cmd:
- print(" ✅ mcporter installed")
- else:
- print(" [X] mcporter install failed. Retry: npm install -g mcporter (check network/timeout), or try: npx mcporter@latest list")
- return False
- except (OSError, subprocess.TimeoutExpired) as e:
- print(f" [X] mcporter install failed: {e}")
- return False
-
- # Configure Exa MCP (free, no key needed)
- try:
- from agent_reach.channels.mcporter import (
- McporterConfigError,
- configured_server_names,
- )
-
- r = subprocess.run(
- [mcporter_cmd, "config", "list", "--json"],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=5,
- )
- if r.returncode != 0:
- raise McporterConfigError("mcporter 配置查询失败")
- server_names = configured_server_names(r.stdout)
- if "exa" not in server_names:
- add_result = subprocess.run(
- [
- mcporter_cmd,
- "config",
- "add",
- "exa",
- "https://mcp.exa.ai/mcp",
- "--scope",
- "home",
- ],
- capture_output=True, encoding="utf-8", errors="replace", timeout=10,
- )
- if add_result.returncode == 0:
- print(" ✅ Exa search configured (free, no API key needed)")
- return True
- else:
- print(
- " [!] Could not configure Exa. Run manually: "
- "mcporter config add exa https://mcp.exa.ai/mcp --scope home"
- )
- return False
- else:
- print(" ✅ Exa search already configured")
- return True
- except Exception:
- print(" [!] Could not configure Exa. Run manually: mcporter config add exa https://mcp.exa.ai/mcp --scope home")
- return False
-
- # NOTE: xhs-cli is now optional, installed via --channels=xiaohongshu
-
-
-def _install_mcporter_safe():
- """Safe mode: check mcporter status, print instructions."""
- import shutil
-
- print("Checking mcporter (safe mode)...")
-
- if shutil.which("mcporter"):
- print(" ✅ mcporter already installed")
- print(" To configure Exa search: mcporter config add exa https://mcp.exa.ai/mcp --scope home")
- else:
- print(" -- mcporter not installed")
- print(" To install: npm install -g mcporter")
- print(" Then configure Exa: mcporter config add exa https://mcp.exa.ai/mcp --scope home")
-
-
-def _detect_environment():
- """Auto-detect if running on local computer or server."""
- import os
-
- # Check common server indicators
- indicators = 0
-
- # SSH session
- if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):
- indicators += 2
-
- # Docker / container
- if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
- indicators += 2
-
- # No display (headless)
- if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
- indicators += 1
-
- # Cloud VM identifiers
- for cloud_file in ["/sys/hypervisor/uuid", "/sys/class/dmi/id/product_name"]:
- if os.path.exists(cloud_file):
- try:
- with open(cloud_file) as f:
- content = f.read().lower()
- if any(x in content for x in ["amazon", "google", "microsoft", "digitalocean", "linode", "vultr", "hetzner"]):
- indicators += 2
- except Exception:
- pass
-
- # systemd-detect-virt
- try:
- import subprocess
- result = subprocess.run(["systemd-detect-virt"], capture_output=True, encoding="utf-8", errors="replace", timeout=3)
- if result.returncode == 0 and result.stdout.strip() != "none":
- indicators += 1
- except Exception:
- pass
-
- return "server" if indicators >= 2 else "local"
-
-
-def _read_configure_value(args) -> str:
- """Read one configure value without echoing secrets by default."""
- values = getattr(args, "value", None) or []
- if getattr(args, "read_stdin", False):
- try:
- value = sys.stdin.read(_MAX_CONFIGURE_VALUE_CHARS + 1)
- except OSError:
- print("Could not read configure value from stdin", file=sys.stderr)
- raise SystemExit(1) from None
- if len(value) > _MAX_CONFIGURE_VALUE_CHARS:
- print("Configure value exceeds the 1 MiB safety limit", file=sys.stderr)
- raise SystemExit(1)
- return value.rstrip("\r\n")
-
- if values:
- if getattr(args, "key", None) in _SENSITIVE_CONFIG_KEYS:
- print(
- "Warning: positional secrets are deprecated because shell history "
- "and process listings may expose them; omit the value for a hidden "
- "prompt or use --stdin.",
- file=sys.stderr,
- )
- return " ".join(values)
-
- try:
- interactive = bool(sys.stdin.isatty())
- except (AttributeError, OSError):
- interactive = False
- if not interactive:
- return ""
-
- import getpass
-
- try:
- return getpass.getpass(f"Value for {args.key}: ")
- except (EOFError, KeyboardInterrupt):
- print("Configure input cancelled", file=sys.stderr)
- raise SystemExit(1) from None
-
-
-def _cmd_configure(args):
- """Set a config value and test it, or auto-extract from browser."""
- import shutil
- from typing import cast
-
- from agent_reach.config import Config
-
- config = Config()
-
- # ── Auto-extract from browser ──
- if args.from_browser:
- from agent_reach.cookie_extract import configure_from_browser
-
- browser = args.from_browser
- platform = "xhs" if args.platform == "xiaohongshu" else args.platform
- print(f"Extracting {args.platform} cookies from {browser}...")
- print()
-
- try:
- results = configure_from_browser(
- browser,
- config,
- platform=platform,
- profile=args.profile,
- )
- except ValueError as exc:
- from agent_reach.utils.text import scrub_url_credentials
-
- print(
- f"agent-reach configure: error: "
- f"{scrub_url_credentials(exc)}",
- file=sys.stderr,
- )
- raise SystemExit(2) from None
-
- found_any = False
- for result in results:
- if hasattr(result, "platform"):
- result_platform = result.platform
- success = result.success
- message = result.message
- targets = getattr(result, "targets", ())
- else:
- legacy_result = cast(tuple[str, bool, str], result)
- result_platform, success, message = legacy_result
- targets = ()
- if success:
- print(f" ✅ {result_platform}: {message}")
- if targets:
- print(f" 写入:{', '.join(targets)}")
- found_any = True
- else:
- print(f" -- {result_platform}: {message}")
-
- print()
- if found_any:
- print("✅ Cookies configured! Run `agent-reach doctor` to see updated status.")
- else:
- print(f"No cookies found. Make sure you're logged into the platforms in {browser}.")
- raise SystemExit(1)
- return
-
- # ── Manual configure ──
- if not args.key:
- print("Usage: agent-reach configure <key> [--stdin]")
- print(" Omit the value to enter it through a hidden prompt.")
- print(
- " or: agent-reach configure --from-browser chrome "
- "--platform xueqiu"
- )
- return
-
- value = _read_configure_value(args)
- if not value:
- print(f"Missing value for {args.key}")
- raise SystemExit(1)
-
- if args.key == "proxy":
- # Generic network proxy for restricted environments. Nothing reads
- # this key at runtime — agents read it back and export HTTP(S)_PROXY
- # before invoking upstream tools (see docs/install.md). The legacy
- # bilibili_proxy key is kept in sync for older configs.
- config.set("proxy", value)
- config.set("bilibili_proxy", value)
- print("✅ 代理已保存(供 Agent 在访问 Reddit/Twitter 等需要代理的网络时设置 HTTP_PROXY/HTTPS_PROXY)")
- print(" Note: B站走 bili-cli,国内网络无需代理。")
-
- elif args.key == "twitter-cookies":
- # Accept two formats:
- # 1. auth_token ct0 (two separate values)
- # 2. Full cookie header string: "auth_token=xxx; ct0=yyy; ..."
- auth_token, ct0 = _parse_twitter_cookie_input(value)
-
- if auth_token and ct0:
- config.set("twitter_auth_token", auth_token)
- config.set("twitter_ct0", ct0)
-
- print("✅ Twitter cookies 已保存到 ~/.agent-reach/config.yaml")
- if getattr(args, "sync_legacy_twitter", False):
- from agent_reach.cookie_extract import (
- _sync_bird_env,
- _sync_xfetch_session,
- )
-
- legacy_results = (
- (
- "~/.config/xfetch/session.json",
- _sync_xfetch_session(auth_token, ct0),
- ),
- (
- "~/.config/bird/credentials.env",
- _sync_bird_env(auth_token, ct0),
- ),
- )
- for path, success in legacy_results:
- outcome = "written" if success else "failed"
- print(f" {outcome}: {path}")
- if all(success for _, success in legacy_results):
- print(" Legacy copies written successfully.")
-
- print(
- " 凭据未实时验证:不会执行 `twitter status`,因为上游在"
- "验证失败时会自动读取浏览器 Cookie。"
- )
- if not shutil.which("twitter"):
- print(
- " [!] twitter-cli 未安装。运行:pipx install twitter-cli"
- )
- else:
- print(
- " 注意:独立 `twitter` 命令不会读取 Agent Reach 配置;"
- "直接使用时需显式设置 TWITTER_AUTH_TOKEN/TWITTER_CT0。"
- )
- else:
- print("[X] Could not find auth_token and ct0 in your input.")
- print(" Run `agent-reach configure twitter-cookies` and paste either:")
- print(" 1. AUTH_TOKEN and CT0 separated by whitespace")
- print(" 2. A Cookie-Editor Header String")
- print(" For automation, pass the same value through --stdin.")
- raise SystemExit(1)
-
- elif args.key == "youtube-cookies":
- config.set("youtube_cookies_from", value)
- print(f"✅ YouTube cookie source configured: {value}")
- print(" yt-dlp will use cookies from this browser for age-restricted/member videos.")
-
- elif args.key == "xhs-cookies":
- if not _configure_xhs_cookies(value):
- raise SystemExit(1)
-
- elif args.key == "github-token":
- config.set("github_token", value)
- print("✅ GitHub token configured!")
-
- elif args.key == "groq-key":
- config.set("groq_api_key", value)
- print("✅ Groq key configured!")
-
- elif args.key == "openai-key":
- config.set("openai_api_key", value)
- print("✅ OpenAI key configured!")
-
-
-def _cmd_transcribe(args):
- """Transcribe a URL or local audio file via an explicitly selected provider."""
- from pathlib import Path
-
- from agent_reach.transcribe import TranscribeError, transcribe
- from agent_reach.utils.text import scrub_url_credentials
-
- try:
- text = transcribe(
- args.source,
- provider=args.provider,
- allow_provider_fallback=getattr(
- args,
- "allow_provider_fallback",
- False,
- ),
- )
- except TranscribeError as e:
- print(f"❌ {scrub_url_credentials(e)}")
- sys.exit(1)
-
- if args.output:
- Path(args.output).write_text(text + "\n", encoding="utf-8")
- print(f"✅ Transcript written to {args.output}")
- else:
- print(text)
-
-
-def _parse_twitter_cookie_input(value: str):
- """Parse Twitter cookie input from either separate values or a cookie header."""
- auth_token = None
- ct0 = None
-
- if "auth_token=" in value and "ct0=" in value:
- # Full cookie string — parse it.
- for part in value.replace(";", " ").split():
- if part.startswith("auth_token="):
- auth_token = part.split("=", 1)[1]
- elif part.startswith("ct0="):
- ct0 = part.split("=", 1)[1]
- elif len(value.split()) == 2 and "=" not in value:
- # Two separate values: AUTH_TOKEN CT0.
- parts = value.split()
- auth_token = parts[0]
- ct0 = parts[1]
-
- return auth_token, ct0
-
-
-def _configure_xhs_cookies(value) -> bool:
- """Import cookies into xiaohongshu-mcp Docker container.
-
- Accepts two formats:
- 1. Cookie-Editor JSON export (array of cookie objects)
- 2. Header String: "name1=value1; name2=value2; ..."
-
- The xiaohongshu-mcp container stores cookies at $COOKIES_PATH
- (default: /app/data/cookies.json or cookies.json in workdir).
- Format: JSON array of {name, value, domain, path, expires, httpOnly, secure, sameSite}.
- """
- import json
- import os
- import shutil
- import subprocess
-
- value = value.strip()
- if not value:
- print("[X] Missing cookie value.")
- print(" Run `agent-reach configure xhs-cookies` and paste the Cookie-Editor export.")
- print(" For automation, pass the same value through --stdin.")
- return False
-
- # Detect format and parse
- cookies_json = None
-
- # Try JSON format first (Cookie-Editor JSON export)
- if value.startswith("["):
- try:
- parsed = json.loads(value)
- if isinstance(parsed, list) and parsed:
- from agent_reach.utils.url import domain_matches
-
- valid_cookies = []
- ignored_domains = 0
- ignored_invalid = 0
- for cookie in parsed:
- if (
- not isinstance(cookie, dict)
- or not isinstance(cookie.get("name"), str)
- or not cookie["name"]
- or not isinstance(cookie.get("value"), str)
- ):
- ignored_invalid += 1
- continue
- if not domain_matches(
- cookie.get("domain", ""),
- "xiaohongshu.com",
- ):
- ignored_domains += 1
- continue
- valid_cookies.append(cookie)
-
- if ignored_domains:
- print(
- f" [!] 已忽略 {ignored_domains} 个非 "
- "xiaohongshu.com 域 Cookie"
- )
- if ignored_invalid:
- print(
- f" [!] 已忽略 {ignored_invalid} 个格式无效的 Cookie"
- )
- if not valid_cookies:
- print(
- "[X] Cookie-Editor JSON 中没有有效的 "
- "xiaohongshu.com 域 Cookie"
- )
- return False
- cookies_json = json.dumps(valid_cookies)
- print(
- f" Parsed {len(valid_cookies)} "
- "xiaohongshu.com cookies from JSON format"
- )
- else:
- print("[X] Empty or invalid JSON array")
- return False
- except json.JSONDecodeError as e:
- print(f"[X] Invalid JSON: {e}")
- return False
-
- # Header String format: "key1=val1; key2=val2; ..."
- if cookies_json is None and "=" in value:
- cookies = []
- for part in value.split(";"):
- part = part.strip()
- if "=" not in part:
- continue
- name, val = part.split("=", 1)
- name = name.strip()
- val = val.strip()
- if name:
- cookies.append({
- "name": name,
- "value": val,
- "domain": ".xiaohongshu.com",
- "path": "/",
- "expires": -1,
- "size": len(name) + len(val),
- "httpOnly": False,
- "secure": False,
- "session": True,
- "sameSite": "Lax",
- })
- if cookies:
- cookies_json = json.dumps(cookies)
- print(f" Parsed {len(cookies)} cookies from Header String format")
- else:
- print("[X] Could not parse any cookies from input")
- return False
-
- if not cookies_json:
- print("[X] Could not parse cookies. Accepted formats:")
- print(' 1. JSON array: \'[{"name":"x","value":"y","domain":".xiaohongshu.com",...}]\'')
- print(' 2. Header String: "key1=val1; key2=val2; ..."')
- return False
-
- # Find the container
- docker = shutil.which("docker")
- if not docker:
- # No Docker - write to a local file for manual import.
- from agent_reach.utils.paths import (
- PrivatePathError,
- atomic_write_private_text,
- home_dir,
- )
-
- cookie_path = home_dir() / ".agent-reach" / "xhs-cookies.json"
- try:
- atomic_write_private_text(cookie_path, cookies_json)
- except (OSError, PrivatePathError) as exc:
- print(f"[X] Could not save cookies safely: {exc}")
- return False
- print(f" Cookies saved to {cookie_path}")
- print(" Docker not found. Copy manually:")
- print(f" docker cp {cookie_path} xiaohongshu-mcp:/app/data/cookies.json")
- return True
-
- # Check if xiaohongshu-mcp container is running
- try:
- result = subprocess.run(
- [docker, "ps", "--filter", "name=xiaohongshu-mcp", "--format", "{{.Names}}"],
- capture_output=True, encoding="utf-8", timeout=5,
- )
- container_name = result.stdout.strip()
- if not container_name:
- print("[X] xiaohongshu-mcp container is not running.")
- print(" Start it first:")
- print(" docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp")
- return False
- except Exception as e:
- print(f"[X] Could not check Docker: {e}")
- return False
-
- # Find the cookies path inside the container
- try:
- result = subprocess.run(
- [docker, "exec", container_name, "printenv", "COOKIES_PATH"],
- capture_output=True, encoding="utf-8", timeout=5,
- )
- cookie_path_in_container = result.stdout.strip()
- if not cookie_path_in_container:
- cookie_path_in_container = "/app/cookies.json" # fallback: absolute path in workdir
- except Exception:
- cookie_path_in_container = "/app/cookies.json"
-
- # Write cookies into the container
- tmp_path = None
- try:
- # Write to temp file then docker cp
- import tempfile
- with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
- f.write(cookies_json)
- tmp_path = f.name
-
- result = subprocess.run(
- [docker, "cp", tmp_path, f"{container_name}:{cookie_path_in_container}"],
- capture_output=True, encoding="utf-8", timeout=10,
- )
-
- if result.returncode != 0:
- print(f"[X] Failed to copy cookies: {result.stderr}")
- return False
-
- print(f"✅ Cookies written to {container_name}:{cookie_path_in_container}")
- # Restart container so it reloads cookies from disk
- print(" Restarting container to reload cookies...", end=" ", flush=True)
- try:
- restart = subprocess.run(
- [docker, "restart", container_name],
- capture_output=True, encoding="utf-8", timeout=30,
- )
- if restart.returncode != 0:
- detail = (
- (restart.stderr or "").strip()[:200]
- or f"exit {restart.returncode}"
- )
- print(f"\n [!] Could not restart container: {detail}")
- print(f" Restart manually: docker restart {container_name}")
- return False
- print("done")
- except Exception as e:
- print(f"\n [!] Could not restart container: {e}")
- print(f" Restart manually: docker restart {container_name}")
- return False
- except Exception as e:
- print(f"[X] Failed to write cookies: {e}")
- return False
- finally:
- if tmp_path:
- try:
- os.unlink(tmp_path)
- except FileNotFoundError:
- pass
- except OSError as e:
- print(f" [!] Could not remove temporary cookie file: {e}")
-
- # Verify login status via mcporter
- mcporter = shutil.which("mcporter")
- if mcporter:
- print(" Verifying login status...", end=" ")
- try:
- result = subprocess.run(
- [mcporter, "call", "xiaohongshu.check_login_status()"],
- capture_output=True, encoding="utf-8", errors="replace", timeout=15,
- )
- if "已登录" in result.stdout or "logged" in result.stdout.lower():
- print("✅ Login verified!")
- else:
- print("[!] Login check returned unexpected result:")
- print(f" {result.stdout.strip()[:200]}")
- print(" Cookies were written but login might not be valid. Try fresh cookies.")
- except Exception as e:
- print(f"[!] Could not verify: {e}")
- else:
- print(" (mcporter not found, skipping verification)")
- return True
-
-
-def _cmd_uninstall(args):
- """Remove all Agent Reach config, tokens, and skill files."""
- import shutil
- import subprocess
-
- from agent_reach.utils.paths import home_dir
-
- dry_run = args.dry_run
- keep_config = args.keep_config
-
- print()
- print("Agent Reach Uninstaller")
- print("=" * 40)
-
- if dry_run:
- print("DRY RUN — showing what would be removed (no changes)")
- print()
-
- removed_any = False
- mcporter_cleanup_skipped = False
-
- # ── 1. Config directory (~/.agent-reach/) ──
- config_dir = home_dir() / ".agent-reach"
- if not keep_config:
- if os.path.isdir(config_dir):
- if dry_run:
- print(f"[dry-run] Would remove config directory: {config_dir}")
- print(" (contains config.yaml with all tokens/cookies/API keys)")
- else:
- try:
- shutil.rmtree(config_dir)
- print(f" Removed config directory: {config_dir}")
- removed_any = True
- except Exception as e:
- print(f" Could not remove {config_dir}: {e}")
- else:
- print(f" Config directory not found (already clean): {config_dir}")
- else:
- print(f" Skipping config directory (--keep-config): {config_dir}")
-
- # Opt-in legacy copies may be shared with upstream tools. Without a
- # provenance marker it would be unsafe to delete them automatically, so
- # surface every exact path that may still contain Twitter credentials.
- legacy_credential_paths = (
- home_dir() / ".config" / "xfetch" / "session.json",
- home_dir() / ".config" / "bird" / "credentials.env",
- )
- present_legacy_paths = [
- path for path in legacy_credential_paths if os.path.lexists(path)
- ]
- if present_legacy_paths:
- print(" [!] 检测到可选的 Twitter legacy 凭据副本;不会自动删除:")
- for path in present_legacy_paths:
- print(f" {path}")
- print(" 若确认不再被 xfetch/bird 使用,请手动删除。")
-
- # ── 2. Skill files ──
- skill_dirs = [
- ("~/.config/opencode/skills/agent-reach", "OpenCode"),
- ("~/.openclaw/skills/agent-reach", "OpenClaw"),
- ("~/.claude/skills/agent-reach", "Claude Code"),
- ("~/.agents/skills/agent-reach", "Agent"),
- ]
-
- for skill_path_template, platform_name in skill_dirs:
- skill_path = os.path.expanduser(skill_path_template)
- if os.path.isdir(skill_path):
- if dry_run:
- print(f"[dry-run] Would remove {platform_name} skill: {skill_path}")
- else:
- try:
- if os.path.islink(skill_path):
- os.unlink(skill_path)
- else:
- shutil.rmtree(skill_path)
- print(f" Removed {platform_name} skill: {skill_path}")
- removed_any = True
- except Exception as e:
- print(f" Could not remove {skill_path}: {e}")
-
- # ── 3. mcporter MCP entries ──
- if shutil.which("mcporter"):
- from agent_reach.channels.mcporter import (
- McporterConfigError,
- configured_server_names,
- )
-
- try:
- result = subprocess.run(
- [
- "mcporter",
- "config",
- "list",
- "--json",
- ],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=10,
- )
- if result.returncode != 0:
- raise McporterConfigError("mcporter config query failed")
- server_names = configured_server_names(result.stdout)
- except (
- McporterConfigError,
- OSError,
- subprocess.TimeoutExpired,
- ):
- mcporter_cleanup_skipped = True
- print(
- " [!] 无法安全核验 mcporter 配置来源;"
- "不会自动删除 exa/xiaohongshu 项。"
- )
- else:
- for mcp_name in ("exa", "xiaohongshu"):
- if mcp_name not in server_names:
- continue
- mcporter_cleanup_skipped = True
- print(
- f" [!] mcporter entry {mcp_name} 来源无法证明由 "
- "Agent Reach 管理;已保留。若确认不再需要,请手动移除。"
- )
-
- # ── 4. Summary and optional steps ──
- print()
- if dry_run:
- print("Dry run complete. No changes were made.")
- print("Run without --dry-run to actually remove the above.")
- else:
- if removed_any:
- print("Agent Reach data removed.")
- elif mcporter_cleanup_skipped:
- print("No proven Agent Reach-managed mcporter data was removed.")
- else:
- print("Nothing to remove — already clean.")
-
- print()
- print("Optional: remove the Agent Reach Python package itself:")
- print(" pip uninstall agent-reach")
- print()
- print("Optional: remove tools installed by Agent Reach:")
- print(" npm uninstall -g mcporter")
- print(" pipx uninstall twitter-cli")
- print(" npm uninstall -g undici")
-
-
-def _cmd_doctor(args=None):
- from agent_reach.config import Config
- from agent_reach.doctor import check_all, format_report
- config = Config(read_only=True)
- results = check_all(config)
-
- if args is not None and getattr(args, "json", False):
- print(json.dumps(results, ensure_ascii=False, indent=2))
- return
-
- report = format_report(results)
- try:
- from rich import print as rich_print
- except ImportError:
- print(report)
- else:
- rich_print(report)
-
-
-def _cmd_setup():
- import getpass
-
- from agent_reach.config import Config
-
- config = Config()
- print()
- print("Agent Reach Setup")
- print("=" * 40)
- print()
-
- # Step 1: Exa (via mcporter, no API key required)
- import shutil
- import subprocess
-
- print("【推荐】全网搜索 — Exa(通过 mcporter)")
- print(" 免费,无需 API Key")
-
- if not shutil.which("mcporter"):
- print(" 当前状态: -- mcporter 未安装")
- print(" 安装:npm install -g mcporter")
- print(" 然后:mcporter config add exa https://mcp.exa.ai/mcp --scope home")
- print()
- else:
- try:
- from agent_reach.channels.mcporter import (
- McporterConfigError,
- configured_server_names,
- )
-
- r = subprocess.run(
- ["mcporter", "config", "list", "--json"],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=10,
- )
- if r.returncode != 0:
- raise McporterConfigError("mcporter 配置查询失败")
- if "exa" in configured_server_names(r.stdout):
- print(" 当前状态: ✅ 已配置")
- else:
- print(" 当前状态: -- 未配置")
- setup_now = input(" 现在自动配置 Exa 吗?[Y/n]: ").strip().lower()
- if setup_now in ("", "y", "yes"):
- add_r = subprocess.run(
- [
- "mcporter",
- "config",
- "add",
- "exa",
- "https://mcp.exa.ai/mcp",
- "--scope",
- "home",
- ],
- capture_output=True, encoding="utf-8", errors="replace", timeout=10,
- )
- if add_r.returncode == 0:
- print(" ✅ Exa 已配置")
- else:
- print(" [!] 自动配置失败,请手动执行:")
- print(" mcporter config add exa https://mcp.exa.ai/mcp --scope home")
- except Exception:
- print(" [!] 无法检查 Exa 配置,请手动执行:")
- print(" mcporter config add exa https://mcp.exa.ai/mcp --scope home")
- print()
-
- # Step 2: GitHub token
- print("【可选】GitHub Token — 提高 API 限额")
- print(" 无 token: 60 次/小时 | 有 token: 5000 次/小时")
- print(" 获取: https://github.com/settings/tokens (无需任何权限)")
- current = config.get("github_token")
- if current:
- print(" 当前状态: ✅ 已配置")
- else:
- key = getpass.getpass(" GITHUB_TOKEN (回车跳过): ").strip()
- if key:
- config.set("github_token", key)
- print(" ✅ GitHub API 已提升至 5000 次/小时!")
- else:
- print(" 跳过。公开 API 也能用")
- print()
-
- # Step 3: Reddit — rdt-cli
- print("【信息】Reddit — 必须登录态(无零配置路径)。桌面推荐 OpenCLI;或 rdt-cli:")
- print(f" 安装:pipx install '{_RDT_GIT_SOURCE}'")
- print(" 然后运行:rdt login(需先在浏览器登录 reddit.com)")
- print()
-
- # Step 4: Groq (Whisper)
- print("【可选】Groq API — 视频无字幕时的语音转文字")
- print(" 免费额度,注册: https://console.groq.com")
- current = config.get("groq_api_key")
- if current:
- print(" 当前状态: ✅ 已配置")
- else:
- key = getpass.getpass(" GROQ_API_KEY (回车跳过): ").strip()
- if key:
- config.set("groq_api_key", key)
- print(" ✅ 语音转文字已开启!")
- else:
- print(" 跳过")
- print()
-
- # Summary
- print("=" * 40)
- print(f"✅ 配置已保存到 {config.config_path}")
- print("运行 agent-reach doctor 查看完整状态")
- print()
-
-
-def _classify_update_error(exc):
- """Classify update-check errors for user-friendly diagnostics."""
- import requests
-
- if isinstance(exc, requests.exceptions.Timeout):
- return "timeout"
- if isinstance(exc, requests.exceptions.ConnectionError):
- msg = str(exc).lower()
- dns_markers = [
- "name or service not known",
- "temporary failure in name resolution",
- "nodename nor servname",
- "getaddrinfo failed",
- "name resolution",
- "dns",
- ]
- if any(marker in msg for marker in dns_markers):
- return "dns"
- return "connection"
- if isinstance(exc, requests.exceptions.HTTPError):
- return "http"
- return "unknown"
-
-
-def _update_error_text(kind):
- """Map internal error kinds to user-facing text."""
- mapping = {
- "timeout": "网络超时",
- "dns": "DNS 解析失败",
- "rate_limit": "GitHub API 速率限制",
- "connection": "网络连接失败",
- "server_error": "GitHub 服务暂时不可用",
- "http": "HTTP 请求失败",
- "unknown": "未知网络错误",
- }
- return mapping.get(kind, "请求失败")
-
-
-def _classify_github_response_error(resp):
- """Classify non-200 GitHub responses that merit special handling."""
- if resp is None:
- return "unknown"
- if resp.status_code == 429:
- return "rate_limit"
- if resp.status_code == 403:
- remaining = resp.headers.get("X-RateLimit-Remaining", "")
- if remaining == "0":
- return "rate_limit"
- try:
- message = resp.json().get("message", "").lower()
- if "rate limit" in message:
- return "rate_limit"
- except Exception:
- pass
- if 500 <= resp.status_code < 600:
- return "server_error"
- return None
-
-
-def _github_get_with_retry(url, timeout=10, retries=3, sleeper=time.sleep):
- """GET GitHub API with retry/backoff and basic error classification."""
- import requests
-
- for attempt in range(1, retries + 1):
- try:
- resp = requests.get(url, timeout=timeout)
- except requests.exceptions.RequestException as exc:
- if attempt >= retries:
- return None, _classify_update_error(exc), attempt
- sleeper(2 ** (attempt - 1))
- continue
-
- err_kind = _classify_github_response_error(resp)
- if err_kind in ("rate_limit", "server_error"):
- if attempt >= retries:
- return None, err_kind, attempt
- delay = 2 ** (attempt - 1)
- retry_after = resp.headers.get("Retry-After")
- if err_kind == "rate_limit" and retry_after:
- try:
- delay = max(delay, float(retry_after))
- except Exception:
- pass
- sleeper(delay)
- continue
-
- return resp, None, attempt
-
- return None, "unknown", retries
-
-
-#: Full update = package + upstream tools + skill. The one-liner walks an
-#: agent through all three (docs/update.md); bare pip only updates the package.
-_UPDATE_INSTRUCTIONS = (
- "更新方式(推荐,复制这句话给你的 AI Agent,会完整更新本体+上游工具+skill):\n"
- " 帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md\n"
- "仅更新本体(不含上游工具和 skill):\n"
- " pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip"
-)
-
-
-def _is_newer_version(remote: str, local: str) -> bool:
- """True if remote is strictly newer than local (semantic compare).
-
- A plain != would tell users "update available" when their local build is
- AHEAD of the latest release (e.g. installed from main during a release
- window) — and walk them into a downgrade.
- """
- def parse(v):
- try:
- return tuple(int(x) for x in v.strip().split("."))
- except ValueError:
- return None
-
- remote_version, local_version = parse(remote), parse(local)
- if remote_version is None or local_version is None:
- return remote != local # unparseable — fall back to old behavior
- return remote_version > local_version
-
-
-def _cmd_check_update():
- """Check for newer versions on GitHub."""
- from agent_reach import __version__
-
- print(f"当前版本: v{__version__}")
- release_url = "https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest"
- commit_url = "https://api.github.com/repos/Panniantong/Agent-Reach/commits/main"
-
- # Fetch latest release with retry/backoff.
- resp, err, attempts = _github_get_with_retry(release_url, timeout=10, retries=3)
- if err:
- print(f"[!] 无法检查更新({_update_error_text(err)},已重试 {attempts} 次)")
- return "error"
-
- if resp.status_code == 200:
- data = resp.json()
- latest = data.get("tag_name", "").lstrip("v")
- body = data.get("body", "")
-
- if latest and _is_newer_version(latest, __version__):
- print(f"最新版本: v{latest} ← 有更新!")
- if body:
- print()
- print("更新内容:")
- # Show first 20 lines of release notes
- for line in body.strip().split("\n")[:20]:
- print(f" {line}")
- print()
- print(_UPDATE_INSTRUCTIONS)
- return "update_available"
- print("✅ 已是最新版本")
- return "up_to_date"
-
- release_err = _classify_github_response_error(resp)
- if release_err == "rate_limit":
- print("[!] 无法检查更新(GitHub API 速率限制,请稍后重试)")
- return "error"
-
- # No releases yet, fall back to latest main commit.
- resp2, err2, attempts2 = _github_get_with_retry(commit_url, timeout=10, retries=2)
- if err2:
- print(f"[!] 无法检查更新({_update_error_text(err2)},已重试 {attempts + attempts2} 次)")
- return "error"
- if resp2.status_code == 200:
- commit = resp2.json()
- sha = commit.get("sha", "")[:7]
- msg = commit.get("commit", {}).get("message", "").split("\n")[0]
- date = commit.get("commit", {}).get("committer", {}).get("date", "")[:10]
- print(f"最新提交: {sha} ({date}) {msg}")
- print()
- print(_UPDATE_INSTRUCTIONS)
- return "unknown"
-
- commit_err = _classify_github_response_error(resp2)
- if commit_err == "rate_limit":
- print("[!] 无法检查更新(GitHub API 速率限制,请稍后重试)")
- return "error"
-
- print(f"[!] 无法检查更新(GitHub 返回 {resp2.status_code})")
- return "error"
-
-
-def _cmd_watch():
- """Quick health check + update check, designed for scheduled tasks.
-
- Only outputs problems. If everything is fine, outputs a single line.
- """
- from agent_reach import __version__
- from agent_reach.config import Config
- from agent_reach.doctor import check_all
-
- config = Config(read_only=True)
- issues = []
-
- # Check channels
- results = check_all(config)
- ok = sum(1 for r in results.values() if r["status"] == "ok")
- total = len(results)
-
- # Find broken channels (were working, now broken)
- for key, r in results.items():
- if r["status"] in ("off", "error"):
- issues.append(f"[X] {r['name']}:{r['message']}")
- elif r["status"] == "warn":
- issues.append(f"[!] {r['name']}:{r['message']}")
-
- # Check for updates
- update_available = False
- new_version = ""
- release_body = ""
- resp, err, _attempts = _github_get_with_retry(
- "https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest",
- timeout=10,
- retries=2,
- )
- if not err and resp and resp.status_code == 200:
- data = resp.json()
- latest = data.get("tag_name", "").lstrip("v")
- if latest and _is_newer_version(latest, __version__):
- update_available = True
- new_version = latest
- release_body = data.get("body", "")
-
- # Output
- if not issues and not update_available:
- print(f"Agent Reach: 全部正常 ({ok}/{total} 渠道可用,v{__version__} 已是最新)")
- return
-
- print("Agent Reach 监控报告")
- print("=" * 40)
- print(f"版本: v{__version__} | 渠道: {ok}/{total}")
-
- if issues:
- print()
- for issue in issues:
- print(f" {issue}")
-
- if update_available:
- print()
- print(f"新版本可用: v{new_version}")
- if release_body:
- for line in release_body.strip().split("\n")[:10]:
- print(f" {line}")
- print(" 更新(一句话发给 Agent 即可完整更新):")
- print(" 帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md")
+ sys.exit(unified.main(argv))
if __name__ == "__main__":
diff --git a/agent_reach/cookie_extract.py b/agent_reach/cookie_extract.py
deleted file mode 100644
index d2f65952..00000000
--- a/agent_reach/cookie_extract.py
+++ /dev/null
@@ -1,506 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Least-privilege cookie extraction from local browsers.
-
-Supports: Chrome, Firefox, Edge, Brave, Opera
-Extracts one explicitly requested platform at a time.
-
-Usage:
- agent-reach configure --from-browser chrome --platform xueqiu
-"""
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Dict, Iterator, List, Optional, Tuple, TypedDict
-
-from agent_reach.utils.text import scrub_url_credentials
-from agent_reach.utils.url import domain_matches
-
-
-class PlatformSpec(TypedDict):
- name: str
- domains: Tuple[str, ...]
- cookies: Optional[Tuple[str, ...]]
- config_key: str
-
-
-class ChromiumPaths(TypedDict):
- darwin: str
- linux: str
- win32: Tuple[str, ...]
-
-
-PLATFORM_SPECS: Tuple[PlatformSpec, ...] = (
- {
- "name": "Twitter/X",
- "domains": (".x.com", ".twitter.com"),
- "cookies": ("auth_token", "ct0"),
- "config_key": "twitter",
- },
- {
- "name": "XiaoHongShu",
- "domains": (".xiaohongshu.com",),
- "cookies": None, # manual Cookie-Editor export only
- "config_key": "xhs",
- },
- {
- "name": "Bilibili",
- "domains": (".bilibili.com",),
- "cookies": ("SESSDATA", "bili_jct"),
- "config_key": "bilibili",
- },
- {
- "name": "Xueqiu",
- "domains": (".xueqiu.com",),
- "cookies": ("xq_a_token",),
- "config_key": "xueqiu",
- },
-)
-
-_PLATFORM_SPECS_BY_KEY: Dict[str, PlatformSpec] = {
- spec["config_key"]: spec for spec in PLATFORM_SPECS
-}
-SUPPORTED_BROWSERS = ("chrome", "firefox", "edge", "brave", "opera")
-PROFILE_SELECTABLE_BROWSERS = ("chrome", "edge", "brave")
-_MAX_XFETCH_SESSION_BYTES = 64 * 1024
-_COOKIE_EDITOR_ONLY = {
- "twitter": "twitter-cookies",
- "xhs": "xhs-cookies",
-}
-
-_CHROMIUM_USER_DATA_DIRS: Dict[str, ChromiumPaths] = {
- "chrome": {
- "darwin": "~/Library/Application Support/Google/Chrome",
- "linux": "~/.config/google-chrome",
- "win32": ("Google", "Chrome", "User Data"),
- },
- "edge": {
- "darwin": "~/Library/Application Support/Microsoft Edge",
- "linux": "~/.config/microsoft-edge",
- "win32": ("Microsoft", "Edge", "User Data"),
- },
- "brave": {
- "darwin": "~/Library/Application Support/BraveSoftware/Brave-Browser",
- "linux": "~/.config/BraveSoftware/Brave-Browser",
- "win32": ("BraveSoftware", "Brave-Browser", "User Data"),
- },
-}
-
-
-@dataclass(frozen=True)
-class BrowserConfigResult:
- """One browser configuration outcome with non-secret write targets."""
-
- platform: str
- success: bool
- message: str
- targets: Tuple[str, ...] = ()
-
- def __iter__(self) -> Iterator[object]:
- """Preserve the historical three-value unpacking API."""
- yield self.platform
- yield self.success
- yield self.message
-
-
-def _chromium_user_data_dir(browser: str) -> Optional[Path]:
- """Return the browser's profile root on the current operating system."""
- import os
- import sys
-
- paths = _CHROMIUM_USER_DATA_DIRS.get(browser)
- if paths is None:
- return None
- if sys.platform == "win32":
- local_appdata = os.environ.get("LOCALAPPDATA")
- if not local_appdata:
- return None
- return Path(local_appdata).joinpath(*paths["win32"])
- path = paths["darwin"] if sys.platform == "darwin" else paths["linux"]
- return Path(os.path.expanduser(path))
-
-
-def list_browser_profiles(browser: str = "chrome") -> List[Dict[str, str]]:
- """List named Chromium profiles that contain a cookie database."""
- browser = browser.lower()
- root = _chromium_user_data_dir(browser)
- if root is None:
- return []
- root = Path(root)
- if not root.is_dir():
- return []
-
- profiles = []
- for profile_dir in root.iterdir():
- if not profile_dir.is_dir():
- continue
- cookie_file = profile_dir / "Network" / "Cookies"
- if not cookie_file.is_file():
- cookie_file = profile_dir / "Cookies"
- if cookie_file.is_file():
- profiles.append(
- {
- "folder": profile_dir.name,
- "cookies_path": str(cookie_file),
- }
- )
-
- def sort_key(item):
- folder = item["folder"]
- suffix = folder.rsplit(" ", 1)[-1]
- number = int(suffix) if suffix.isdigit() else 0
- return (folder != "Default", number, folder)
-
- profiles.sort(key=sort_key)
- return profiles
-
-
-def _profile_cookie_file(browser: str, profile: str) -> str:
- """Resolve an explicit profile or fail without falling back to Default."""
- if browser not in PROFILE_SELECTABLE_BROWSERS:
- raise ValueError(
- "Profile selection is supported only for "
- f"{', '.join(PROFILE_SELECTABLE_BROWSERS)}, "
- f"not {scrub_url_credentials(browser)}."
- )
-
- profiles = list_browser_profiles(browser)
- for candidate in profiles:
- if candidate["folder"] == profile:
- return candidate["cookies_path"]
-
- available = ", ".join(
- scrub_url_credentials(item["folder"]) for item in profiles
- )
- hint = f" Available profiles: {available}." if available else ""
- raise ValueError(
- f"Profile '{scrub_url_credentials(profile)}' not found for "
- f"{scrub_url_credentials(browser)}.{hint}"
- )
-
-
-def _platform_spec(platform: Optional[str]) -> PlatformSpec:
- """Return the one explicitly requested platform specification."""
- if not platform:
- raise ValueError(
- "platform is required for browser-cookie extraction; "
- f"choose one of: {', '.join(_PLATFORM_SPECS_BY_KEY)}"
- )
- key = platform.lower()
- try:
- return _PLATFORM_SPECS_BY_KEY[key]
- except KeyError as exc:
- raise ValueError(
- f"Unsupported platform: {scrub_url_credentials(platform)}. "
- f"Supported: {', '.join(_PLATFORM_SPECS_BY_KEY)}"
- ) from exc
-
-
-def _require_browser_extractable(spec: PlatformSpec) -> None:
- """Reject platforms whose project policy requires a manual cookie export."""
- manual_key = _COOKIE_EDITOR_ONLY.get(spec["config_key"])
- if manual_key:
- raise ValueError(
- f"Automatic browser extraction is disabled for {spec['name']}. "
- "Export the required cookies with Cookie-Editor, then use "
- f"`agent-reach configure {manual_key}`."
- )
-
-
-def extract_all(
- browser: str = "chrome",
- *,
- platform: Optional[str] = None,
- profile: Optional[str] = None,
-) -> Dict[str, dict]:
- """
- Extract cookies for one explicitly requested platform.
-
- The legacy function name is retained for API compatibility, but an
- all-platform read is intentionally no longer supported.
-
- Returns:
- {"xueqiu": {"xq_a_token": "xxx"}}
- """
- spec = _platform_spec(platform)
- _require_browser_extractable(spec)
- browser = browser.lower()
- if browser not in SUPPORTED_BROWSERS:
- raise ValueError(
- f"Unsupported browser: {scrub_url_credentials(browser)}. "
- f"Supported: {', '.join(SUPPORTED_BROWSERS)}"
- )
- cookie_file = _profile_cookie_file(browser, profile) if profile else None
- needed_cookies = spec["cookies"]
- if needed_cookies is None:
- raise ValueError(
- f"Automatic full-domain extraction is disabled for {spec['name']}."
- )
-
- # Try rookiepy first (Rust-based, more stable), fallback to browser_cookie3
- use_rookiepy = False
- if cookie_file is None:
- try:
- import rookiepy
- use_rookiepy = True
- except ImportError:
- pass
- if not use_rookiepy:
- try:
- import browser_cookie3
- except ImportError:
- profile_hint = (
- f" for profile '{scrub_url_credentials(profile)}'"
- if profile is not None
- else ""
- )
- raise RuntimeError(
- f"Cookie extraction{profile_hint} requires browser_cookie3"
- " (or rookiepy when no profile is selected).\n"
- "Install: pip install browser-cookie3"
- )
-
- if use_rookiepy:
- # rookiepy returns list of dicts with name/value/domain/path keys
- try:
- browser_funcs = {
- "chrome": rookiepy.chrome,
- "firefox": rookiepy.firefox,
- "edge": rookiepy.edge,
- "brave": rookiepy.brave,
- "opera": rookiepy.opera,
- }
- raw_cookies = browser_funcs[browser](list(spec["domains"]))
- # Wrap into objects with .name, .value, .domain for compatibility
- class _Cookie:
- def __init__(self, d):
- self.name = d.get("name", "")
- self.value = d.get("value", "")
- self.domain = d.get("domain", "")
- cookie_jar = [_Cookie(c) for c in raw_cookies]
- except Exception as e:
- raise RuntimeError(
- f"Could not read {browser} cookies via rookiepy: "
- f"{scrub_url_credentials(e)}\n"
- f"Make sure {browser} is closed and you have permission."
- )
- else:
- browser_funcs = {
- "chrome": browser_cookie3.chrome,
- "firefox": browser_cookie3.firefox,
- "edge": browser_cookie3.edge,
- "brave": browser_cookie3.brave,
- "opera": browser_cookie3.opera,
- }
- try:
- cookie_jar = []
- seen = set()
- for domain in spec["domains"]:
- kwargs = {"domain_name": domain}
- if cookie_file is not None:
- kwargs["cookie_file"] = cookie_file
- for cookie in browser_funcs[browser](**kwargs):
- identity = (
- getattr(cookie, "name", ""),
- getattr(cookie, "domain", ""),
- getattr(cookie, "path", ""),
- getattr(cookie, "value", ""),
- )
- if identity not in seen:
- seen.add(identity)
- cookie_jar.append(cookie)
- except Exception as e:
- raise RuntimeError(
- f"Could not read {browser} cookies: {scrub_url_credentials(e)}\n"
- f"Make sure {browser} is closed and you have permission."
- )
-
- results = {}
-
- platform_cookies = {}
- for cookie in cookie_jar:
- # Re-check returned cookies instead of trusting the backend filter.
- if not domain_matches(cookie.domain, *spec["domains"]):
- continue
-
- if cookie.name in needed_cookies:
- platform_cookies[cookie.name] = cookie.value
-
- if platform_cookies:
- results[spec["config_key"]] = platform_cookies
-
- return results
-
-
-def _read_xfetch_session(path: Path) -> dict:
- """Read a small regular legacy session file without following symlinks."""
- import json
-
- from agent_reach.utils.paths import read_small_text_no_follow
-
- payload = read_small_text_no_follow(
- path,
- max_bytes=_MAX_XFETCH_SESSION_BYTES,
- )
- if payload is None:
- return {}
- loaded = json.loads(payload)
- if not isinstance(loaded, dict):
- raise ValueError("xfetch 会话文件必须是 JSON object")
- return loaded
-
-
-def _sync_xfetch_session(auth_token: str, ct0: str) -> bool:
- """Sync Twitter credentials to ~/.config/xfetch/session.json (legacy xreach compat)."""
- import json
-
- try:
- from agent_reach.utils.paths import (
- atomic_write_private_text,
- home_dir,
- make_private_dir,
- )
-
- xfetch_dir = home_dir() / ".config" / "xfetch"
- make_private_dir(xfetch_dir)
- session_path = Path(xfetch_dir) / "session.json"
- session_data = _read_xfetch_session(session_path)
- session_data["authToken"] = auth_token
- session_data["ct0"] = ct0
- atomic_write_private_text(
- session_path,
- json.dumps(session_data, indent=2),
- )
- return True
- except Exception:
- # Non-fatal: agent-reach config is the source of truth, xfetch sync is best-effort
- return False
-
-
-def _sync_bird_env(auth_token: str, ct0: str) -> bool:
- """Write Twitter credentials to ~/.config/bird/credentials.env for bird CLI.
-
- bird reads AUTH_TOKEN and CT0 from environment variables. This writes a
- shell-sourceable file so users can `source ~/.config/bird/credentials.env`.
- Values are passed through shlex.quote so a token containing a quote, $, or
- backtick cannot break out into shell syntax when the file is sourced.
- """
- import shlex
-
- try:
- from agent_reach.utils.paths import (
- atomic_write_private_text,
- home_dir,
- make_private_dir,
- )
-
- bird_dir = home_dir() / ".config" / "bird"
- make_private_dir(bird_dir)
- env_path = bird_dir / "credentials.env"
- atomic_write_private_text(
- env_path,
- f"AUTH_TOKEN={shlex.quote(auth_token)}\n"
- f"CT0={shlex.quote(ct0)}\n",
- )
- return True
- except Exception:
- # Non-fatal: agent-reach config is the source of truth, bird env sync is best-effort
- return False
-
-
-# Alias for callers expecting the name _sync_bird_credentials
-_sync_bird_credentials = _sync_bird_env
-
-
-def configure_from_browser(
- browser: str,
- config,
- *,
- platform: Optional[str] = None,
- profile: Optional[str] = None,
-) -> List[BrowserConfigResult]:
- """
- Extract and configure exactly one explicitly selected platform.
-
- Result objects still unpack as ``(platform, success, message)`` and expose
- a ``targets`` attribute so the CLI can disclose every non-secret config key
- or legacy path written.
- """
- spec = _platform_spec(platform)
- _require_browser_extractable(spec)
- results_list: List[BrowserConfigResult] = []
-
- try:
- extracted = extract_all(
- browser,
- platform=spec["config_key"],
- profile=profile,
- )
- except ValueError:
- raise
- except Exception as e:
- return [
- BrowserConfigResult(
- "Browser", False, scrub_url_credentials(e)
- )
- ]
-
- config_key = spec["config_key"]
- if config_key not in extracted:
- return [
- BrowserConfigResult(
- spec["name"],
- False,
- f"No {spec['name']} cookies found in {browser}. "
- f"Make sure you're logged into the selected platform.",
- )
- ]
-
- if config_key == "bilibili":
- bc = extracted["bilibili"]
- if "SESSDATA" in bc:
- config.set("bilibili_sessdata", bc["SESSDATA"])
- targets = ["bilibili_sessdata"]
- if "bili_jct" in bc:
- config.set("bilibili_csrf", bc["bili_jct"])
- targets.append("bilibili_csrf")
- results_list.append(
- BrowserConfigResult(
- "Bilibili",
- True,
- "SESSDATA" + (" + bili_jct" if "bili_jct" in bc else ""),
- tuple(targets),
- )
- )
- else:
- results_list.append(
- BrowserConfigResult(
- "Bilibili",
- False,
- f"No SESSDATA found. "
- f"Make sure you're logged into bilibili.com in {browser}.",
- )
- )
-
- elif config_key == "xueqiu":
- token = extracted["xueqiu"].get("xq_a_token", "")
- if token:
- cookie_str = f"xq_a_token={token}"
- config.set("xueqiu_cookie", cookie_str)
- results_list.append(
- BrowserConfigResult(
- "Xueqiu",
- True,
- "xq_a_token",
- ("xueqiu_cookie",),
- )
- )
- else:
- results_list.append(
- BrowserConfigResult(
- "Xueqiu",
- False,
- f"未找到 xq_a_token,请先在 {browser} 中登录 xueqiu.com",
- )
- )
-
- return results_list
diff --git a/agent_reach/core.py b/agent_reach/core.py
deleted file mode 100644
index 075d9de1..00000000
--- a/agent_reach/core.py
+++ /dev/null
@@ -1,42 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-AgentReach — installer, doctor, and configuration tool.
-
-Agent Reach helps AI agents install and configure upstream platform tools
-(twitter-cli, yt-dlp, mcporter, gh CLI, etc.). After installation, agents
-call the upstream tools directly — no wrapper layer needed.
-
-Usage:
- from agent_reach.doctor import check_all, format_report
- from agent_reach.config import Config
-
- config = Config()
- results = check_all(config)
- print(format_report(results))
-"""
-
-from typing import Dict, Optional
-
-from agent_reach.config import Config
-
-
-class AgentReach:
- """Give your AI Agent eyes to see the entire internet.
-
- This class provides health-check functionality.
- For reading/searching, use the upstream tools directly
- (see SKILL.md for commands).
- """
-
- def __init__(self, config: Optional[Config] = None):
- self.config = config or Config()
-
- def doctor(self) -> Dict[str, dict]:
- """Check all channel availability."""
- from agent_reach.doctor import check_all
- return check_all(self.config)
-
- def doctor_report(self) -> str:
- """Get formatted health report."""
- from agent_reach.doctor import check_all, format_report
- return format_report(check_all(self.config))
diff --git a/agent_reach/doctor.py b/agent_reach/doctor.py
deleted file mode 100644
index 9ee98cf2..00000000
--- a/agent_reach/doctor.py
+++ /dev/null
@@ -1,131 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Environment health checker — powered by channels.
-
-Each channel knows how to check itself. Doctor just collects the results.
-"""
-
-from typing import Dict
-
-from rich.markup import escape
-
-from agent_reach.channels import get_all_channels
-from agent_reach.config import Config
-from agent_reach.utils.text import scrub_url_credentials
-
-
-def check_all(config: Config) -> Dict[str, dict]:
- """Check all channels and return status dict.
-
- A single misbehaving channel must never take the whole report down,
- so per-channel exceptions degrade to status="error".
- """
- results = {}
- for ch in get_all_channels():
- try:
- status, message = ch.check(config)
- active = getattr(ch, "active_backend", None)
- except Exception as e: # noqa: BLE001 — doctor must survive any channel
- # Channels are registry singletons: a stale active_backend from a
- # previous check must not leak into an errored result.
- status = "error"
- message = f"体检异常:{e}"
- active = None
- # Doctor is the final output boundary for both expected channel
- # messages and unexpected exceptions. Upstream probe output can echo a
- # configured URL, so scrub every path before JSON/text rendering.
- message = scrub_url_credentials(message)
- results[ch.name] = {
- "status": status,
- "name": ch.description,
- "message": message,
- "tier": ch.tier,
- "backends": ch.backends,
- "active_backend": active,
- }
- return results
-
-
-def _name_msg(r: dict, escape) -> str:
- """Render one channel line; show the active backend when there is a choice."""
- text = f"[bold]{escape(r['name'])}[/bold] — {escape(r['message'])}"
- active = r.get("active_backend")
- if active and len(r.get("backends", [])) > 1:
- text += f" [dim](当前后端:{escape(active)})[/dim]"
- return text
-
-
-def format_report(results: Dict[str, dict]) -> str:
- """Format results as a readable text report (with Rich markup)."""
- lines = []
- lines.append("[bold cyan]Agent Reach 状态[/bold cyan]")
- lines.append("[cyan]" + "=" * 40 + "[/cyan]")
- lines.append("图例:[green]✅[/green] 可用 [yellow][!][/yellow] 已装但需配置/登录 [red][X][/red] 未安装")
-
- ok_count = sum(1 for r in results.values() if r["status"] == "ok")
- total = len(results)
-
- # Tier 0 — zero config
- lines.append("")
- lines.append("[bold]✅ 装好即用:[/bold]")
- for key, r in results.items():
- if r["tier"] == 0:
- name_msg = _name_msg(r, escape)
- if r["status"] == "ok":
- lines.append(f" [green]✅[/green] {name_msg}")
- elif r["status"] == "warn":
- lines.append(f" [yellow][!][/yellow] {name_msg}")
- elif r["status"] in ("off", "error"):
- lines.append(f" [red][X][/red] {name_msg}")
-
- # Tier 1 — needs free key / login
- tier1 = {k: r for k, r in results.items() if r["tier"] == 1}
- tier1_active = {k: r for k, r in tier1.items() if r["status"] == "ok"}
- tier1_inactive = {k: r for k, r in tier1.items() if r["status"] != "ok"}
- if tier1_active:
- lines.append("")
- lines.append("[bold]可选渠道(已安装):[/bold]")
- for key, r in tier1_active.items():
- lines.append(f" [green]✅[/green] {_name_msg(r, escape)}")
-
- # Tier 2 — optional complex setup
- tier2 = {k: r for k, r in results.items() if r["tier"] == 2}
- tier2_active = {k: r for k, r in tier2.items() if r["status"] == "ok"}
- tier2_inactive = {k: r for k, r in tier2.items() if r["status"] != "ok"}
- if tier2_active:
- if not tier1_active:
- lines.append("")
- lines.append("[bold]可选渠道(已安装):[/bold]")
- for key, r in tier2_active.items():
- lines.append(f" [green]✅[/green] {_name_msg(r, escape)}")
-
- lines.append("")
- status_color = "green" if ok_count == total else ("yellow" if ok_count > 0 else "red")
- lines.append(f"状态:[{status_color}]{ok_count}/{total}[/{status_color}] 个渠道可用")
-
- # Summarize inactive optional channels in one line instead of listing each
- all_inactive = list(tier1_inactive.values()) + list(tier2_inactive.values())
- if all_inactive:
- names = [r["name"] for r in all_inactive]
- lines.append(
- f"还有 {len(names)} 个可选渠道可以解锁({'、'.join(names)}),"
- "告诉你的 Agent「帮我装 XXX」即可"
- )
-
- # Security check: config file permissions (Unix only)
- import stat
- import sys
-
- config_path = Config.CONFIG_DIR / "config.yaml"
- if config_path.exists() and sys.platform != "win32":
- try:
- mode = config_path.stat().st_mode
- if mode & (stat.S_IRGRP | stat.S_IROTH):
- lines.append("")
- lines.append(
- "[bold red][!] 安全提示:config.yaml 权限过宽(其他用户可读)[/bold red]"
- )
- lines.append(" 修复:chmod 600 ~/.agent-reach/config.yaml")
- except OSError:
- pass
-
- return "\n".join(lines)
diff --git a/agent_reach/guides/setup-exa.md b/agent_reach/guides/setup-exa.md
deleted file mode 100644
index 3dc0ab89..00000000
--- a/agent_reach/guides/setup-exa.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Exa Search 配置指南
-
-## 功能说明
-Exa 是一个 AI 语义搜索引擎。通过 MCP 接入,**免费、无需 API Key**。配置后解锁:
-- 全网语义搜索
-- Reddit 搜索(通过 site:reddit.com)
-- Twitter 搜索(通过 site:x.com)
-
-## Agent 可自动完成的步骤
-
-用户明确授权后,`agent-reach install --env=auto --system` 会完成以下步骤。
-不带 `--system` 的默认命令只做只读检查。
-
-### 1. 安装 mcporter
-```bash
-npm install -g mcporter
-```
-
-### 2. 注册 Exa MCP
-```bash
-mcporter config add exa https://mcp.exa.ai/mcp --scope home
-```
-
-### 3. 验证
-```bash
-agent-reach doctor | grep "Search"
-mcporter call exa.web_search_exa query="test" numResults=1
-```
-
-## 需要用户手动做的步骤
-
-**无。** Exa 通过 MCP 接入,免费、无需注册、无需 API Key。
-
-如果 `agent-reach install --system` 因为网络问题没有配置 Exa,手动运行上面两条命令即可。
-
-## 常见问题
-
-**Q: 有搜索次数限制吗?**
-A: MCP 端点由 Exa 官方提供(mcp.exa.ai),当前免费无限制。如果未来有变化,会在 agent-reach 更新中适配。
-
-**Q: mcporter 是什么?**
-A: MCP 协议的命令行桥接工具,用来调用 MCP Server。Agent Reach 用它来连接 Exa 和小红书。
diff --git a/agent_reach/guides/setup-groq.md b/agent_reach/guides/setup-groq.md
deleted file mode 100644
index 071da35d..00000000
--- a/agent_reach/guides/setup-groq.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Groq Whisper 配置指南
-
-## 功能说明
-当 YouTube/Bilibili 视频没有字幕时,用 Groq 的 Whisper API 进行语音转文字。Groq 提供免费额度。
-
-## Agent 可自动完成的步骤
-
-1. 检查是否已配置:
-```bash
-agent-reach doctor | grep -i "groq\|whisper"
-```
-
-2. 如果用户提供了 key,写入配置:
-```python
-from agent_reach.config import Config
-c = Config()
-c.set("groq_api_key", "用户提供的KEY")
-```
-
-3. 测试(可选):
-```bash
-curl -s https://api.groq.com/openai/v1/models \
- -H "Authorization: Bearer 用户提供的KEY" \
- -o /dev/null -w "%{http_code}"
-```
-返回 200 = 可用
-
-## 需要用户手动做的步骤
-
-请告诉用户:
-
-> 视频语音转文字需要一个 Groq API Key(免费)。
->
-> 步骤:
-> 1. 打开 https://console.groq.com
-> 2. 用 Google 账号或邮箱注册
-> 3. 点击左侧 "API Keys"
-> 4. 点击 "Create API Key"
-> 5. 复制生成的 Key,发给我
->
-> Groq 提供免费额度,日常使用完全够用。
-
-## Agent 收到 key 后的操作
-
-1. 写入配置:`config.set("groq_api_key", key)`
-2. 测试 API 可用性
-3. 反馈:"✅ 语音转文字已开启!现在遇到没有字幕的视频,我也能帮你提取内容了。"
diff --git a/agent_reach/guides/setup-reddit.md b/agent_reach/guides/setup-reddit.md
deleted file mode 100644
index 8e733dd3..00000000
--- a/agent_reach/guides/setup-reddit.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Reddit 配置指南
-
-## 功能说明
-
-Reddit 封锁了几乎所有非浏览器的直接访问(包括数据中心和 ISP 代理 IP),JSON API 返回 403。
-
-Agent Reach 通过 **rdt-cli** 实现 Reddit 的搜索和阅读功能:
-- **搜索**:`rdt search "关键词"`
-- **阅读完整帖子+评论**:`rdt read POST_ID`
-
-免费,无需代理,无需 API Key。需要登录认证(`rdt login`,自动从浏览器提取 Cookie)。
-
-## Agent 可自动完成的步骤
-
-1. 检查 rdt-cli 是否可用:
-```bash
-which rdt && echo "installed" || echo "not installed"
-```
-
-2. 如果未安装,自动安装(PyPI 版本暂时落后,从 GitHub 安装最新版):
-```bash
-pipx install 'git+https://github.com/public-clis/rdt-cli.git'
-```
-
-或一键安装:
-```bash
-agent-reach install --env=auto --system --channels=reddit
-```
-
-## 使用示例
-
-搜索 Reddit 内容:
-```bash
-rdt search "python best practices" -n 5
-```
-
-阅读完整帖子和评论:
-```bash
-rdt read POST_ID
-```
-
-## 需要用户手动做的步骤
-
-无。用户明确授权后,rdt-cli 通过
-`agent-reach install --env=auto --system --channels=reddit` 安装。
-
-## Fallback:Exa 搜索
-
-如果你已经配置了 Exa(通过 mcporter),也可以通过 Exa 搜索 Reddit 内容:
-
-```bash
-mcporter call exa.web_search_exa query="site:reddit.com python best practices" numResults=5
-```
-
-rdt-cli 是当前推荐方案,无需额外配置即可使用。
diff --git a/agent_reach/guides/setup-twitter.md b/agent_reach/guides/setup-twitter.md
deleted file mode 100644
index da9d563c..00000000
--- a/agent_reach/guides/setup-twitter.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# Twitter 高级功能配置指南(twitter-cli)
-
-Twitter 基础阅读通过 Jina Reader 免费可用,无需配置。
-
-高级功能需要 twitter-cli(@public-clis/twitter-cli):
-
-- 搜索推文(`twitter search`)
-- 读取完整推文和对话链(`twitter tweet`、`twitter thread`)
-- 用户时间线(`twitter timeline`)
-- 长文阅读(`twitter article`)
-
-twitter-cli 是免费开源工具(pipx 安装),但需要你的 Twitter 账号 cookie。
-
-## 快速配置
-
-1. 检查 twitter-cli 是否安装:
-
-```bash
-which twitter && echo "installed" || echo "not installed"
-```
-
-2. 安装 twitter-cli:
-
-```bash
-pipx install twitter-cli
-```
-
-3. 确认命令已安装(此时不做认证请求):
-
-```bash
-twitter --help
-```
-
-## 获取 Cookie(Cookie-Editor 方式,推荐)
-
-1. 安装 [Cookie-Editor](https://cookie-editor.com/) 浏览器扩展
-2. 登录 x.com
-3. 点击 Cookie-Editor 图标 → Export → Header String
-4. 运行配置命令:
-
-```bash
-agent-reach configure twitter-cookies
-```
-
-这会提取 `auth_token` 和 `ct0`,安全保存到
-`~/.agent-reach/config.yaml`,供 `agent-reach doctor` 检查显式凭据是否齐全。
-`doctor` 不会执行 `twitter status`,不会实时验证账号是否可用,也不会修改当前 Shell。
-
-默认只写 `~/.agent-reach/config.yaml`。只有用户明确同意复制凭据并显式增加
-`--sync-legacy-twitter` 时,才会额外写入:
-
-- `~/.config/xfetch/session.json`
-- `~/.config/bird/credentials.env`
-
-```bash
-agent-reach configure twitter-cookies --sync-legacy-twitter
-```
-
-`agent-reach uninstall` 只会提醒这些 legacy 副本,不会自动删除。需要清理时,
-先让用户确认,再手工删除上述两个文件。
-
-`twitter` 是独立的上游命令,不会读取 Agent Reach 的配置文件。直接运行
-`twitter status/search/read/...` 时,必须按下节在当前 Shell 或子进程环境中
-显式设置 `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`。不要依赖自动读取浏览器 Cookie。
-
-## 手动设置 Cookie
-
-如果你已经知道 `auth_token` 和 `ct0`:
-
-1. 安装 twitter-cli(如果没装):`pipx install twitter-cli`
-
-2. 设置环境变量:
-
-```bash
-export TWITTER_AUTH_TOKEN="你的auth_token"
-export TWITTER_CT0="你的ct0"
-```
-
-3. 测试:
-
-```bash
-twitter search "test" -n 1
-```
-
-## 代理配置
-
-> twitter-cli 支持通过环境变量设置代理:
-
-```bash
-export HTTP_PROXY="http://user:pass@host:port"
-export HTTPS_PROXY="http://user:pass@host:port"
-twitter search "test" -n 1
-```
-
-也可以使用全局代理工具:
-
-```bash
-proxychains twitter search "test" -n 1
-```
-
-## Fallback:bird CLI
-
-如果你已经安装了 [bird CLI](https://www.npmjs.com/package/@steipete/bird)(`npm install -g @steipete/bird`),它也能正常工作。Agent Reach 会自动检测并使用已安装的 bird。两者功能类似,twitter-cli 是当前推荐方案。
diff --git a/agent_reach/guides/setup-xiaohongshu.md b/agent_reach/guides/setup-xiaohongshu.md
deleted file mode 100644
index b1eb0978..00000000
--- a/agent_reach/guides/setup-xiaohongshu.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# 小红书配置指南
-
-## 功能说明
-读取和搜索小红书笔记。桌面优先使用 OpenCLI,服务器使用
-[xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp);
-xhs-cli 仅作为已安装用户的存量备选。
-
-## 前置条件
-- OpenCLI:用户已经存在且明确控制的 Chrome 小红书会话
-- xiaohongshu-mcp / 存量工具:Cookie-Editor 浏览器扩展
-
-## 认证边界
-
-Agent Reach 不替用户执行小红书登录,也不读取浏览器 Cookie。
-
-OpenCLI 只使用用户已经存在且明确控制的 Chrome 会话。
-`agent-reach configure xhs-cookies` 不会把 Cookie 注入 OpenCLI 或 Chrome。
-如果没有现成会话,不要自动登录;改用 Cookie-Editor 手工导出后配置
-xiaohongshu-mcp 或存量工具:
-
-1. 在 Chrome 中安装 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 扩展
-2. 用户自行在 xiaohongshu.com 准备要导出的会话
-3. 点击 Cookie-Editor 图标 → Export → Header String
-4. 把导出的字符串发给 Agent,运行:
-
-```bash
-agent-reach configure xhs-cookies
-agent-reach doctor
-```
-
-该显式命令会保存/导入用户提供的 xiaohongshu.com 同域 Cookie 集;执行前请
-确认 Cookie 名称和范围。非 xiaohongshu.com 域 Cookie 会被忽略。
-
-如果 xiaohongshu-mcp 容器正在运行,配置命令会把 Cookie 导入容器;否则会写入
-owner-only 的本地文件,并打印后续手工导入路径。
-
-## 使用示例
-
-先按 `agent-reach doctor --json` 的 `active_backend` 选择命令。存量 xhs-cli 示例:
-
-搜索笔记:
-```bash
-xhs search "关键词"
-```
-
-阅读笔记详情:
-```bash
-xhs read NOTE_ID
-```
-
-查看评论:
-```bash
-xhs comments NOTE_ID
-```
-
-## 常见问题
-
-**Q: Cookie 过期了?**
-A: 重新通过 Cookie-Editor 手工导出,再运行
-`agent-reach configure xhs-cookies`,并粘贴到隐藏输入提示。
-
-**Q: 小红书提示 IP 风险?**
-A: 推荐使用住宅代理:`export HTTP_PROXY="http://user:pass@ip:port"`。
-
-**Q: xhs-cli 不支持我的系统?**
-A: 确保 Python 3.10+ 和 pipx 已安装。运行 `pipx install xiaohongshu-cli` 即可。
-
-## 服务器方案:Docker MCP
-
-如果你已经在使用 [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) Docker 方案,它也能正常工作:
-
-```bash
-docker run -d \
- --name xiaohongshu-mcp \
- -p 18060:18060 \
- xpzouying/xiaohongshu-mcp
-
-mcporter config add xiaohongshu http://localhost:18060/mcp --scope home
-```
-
-该服务器后端使用上面的 Cookie-Editor 手工导出流程。
diff --git a/agent_reach/integrations/__init__.py b/agent_reach/integrations/__init__.py
deleted file mode 100644
index 40a96afc..00000000
--- a/agent_reach/integrations/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-# -*- coding: utf-8 -*-
diff --git a/agent_reach/integrations/mcp_server.py b/agent_reach/integrations/mcp_server.py
deleted file mode 100644
index 9b226706..00000000
--- a/agent_reach/integrations/mcp_server.py
+++ /dev/null
@@ -1,79 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Agent Reach MCP Server — expose doctor/status as MCP tool.
-
-Run: python -m agent_reach.integrations.mcp_server
-
-Agent Reach is an installer + doctor tool. For actual reading/searching,
-agents should call upstream tools directly (twitter-cli, yt-dlp, mcporter, etc.).
-"""
-
-import asyncio
-import json
-import sys
-
-from agent_reach.config import Config
-from agent_reach.core import AgentReach
-from agent_reach.utils.text import scrub_url_credentials
-
-try:
- from mcp.server import Server
- from mcp.server.stdio import stdio_server
- from mcp.types import TextContent, Tool
-
- HAS_MCP = True
-except ImportError:
- HAS_MCP = False
-
-
-def create_server():
- if not HAS_MCP:
- print(
- "MCP not installed. Install: python -m pip install "
- "'agent-reach[mcp] @ "
- "https://github.com/Panniantong/agent-reach/archive/main.zip'",
- file=sys.stderr,
- )
- sys.exit(1)
-
- server = Server("agent-reach")
- config = Config(read_only=True)
- eyes = AgentReach(config)
-
- @server.list_tools()
- async def list_tools():
- return [
- Tool(name="get_status",
- description="Get Agent Reach status: which channels are installed and active.",
- inputSchema={"type": "object", "properties": {}}),
- ]
-
- @server.call_tool()
- async def call_tool(name: str, arguments: dict):
- try:
- if name == "get_status":
- result = eyes.doctor_report()
- else:
- result = f"Unknown tool: {name}"
-
- text = json.dumps(result, ensure_ascii=False, indent=2) if isinstance(result, (dict, list)) else str(result)
- return [TextContent(type="text", text=text)]
- except Exception as e:
- return [
- TextContent(
- type="text",
- text=f"Error: {scrub_url_credentials(e)}",
- )
- ]
-
- return server
-
-
-async def main():
- server = create_server()
- async with stdio_server() as (read_stream, write_stream):
- await server.run(read_stream, write_stream, server.create_initialization_options())
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/agent_reach/probe.py b/agent_reach/probe.py
deleted file mode 100644
index 3652d8b9..00000000
--- a/agent_reach/probe.py
+++ /dev/null
@@ -1,120 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Lightweight upstream command probing.
-
-Distinguishes the three failure modes that look identical to shutil.which():
- - missing: command not on PATH
- - broken: command exists but cannot execute — most commonly a stale venv
- shebang after a system Python upgrade (pipx/uv tool installs break this
- way: which() finds the shim, but exec fails with FileNotFoundError
- pointing at the shim itself)
- - timeout/error: command runs but misbehaves
-
-Channels use probe_command() inside check() so doctor reports real health,
-not just file existence.
-"""
-
-import shutil
-import subprocess
-from dataclasses import dataclass
-from typing import Mapping, Optional, Sequence
-
-from agent_reach.utils.process import utf8_subprocess_env
-
-#: Exit codes shells use for "found but not executable" / "not found".
-_BROKEN_EXIT_CODES = (126, 127)
-
-
-@dataclass
-class ProbeResult:
- status: str # "ok" | "missing" | "broken" | "timeout" | "error"
- output: str = ""
- hint: str = ""
-
- @property
- def ok(self) -> bool:
- return self.status == "ok"
-
-
-def reinstall_hint(package: str) -> str:
- """Prescription for a broken (stale-venv) CLI install."""
- return (
- f"命令存在但无法执行——通常是系统 Python 升级后 venv 解释器丢失。重装即可修复:\n"
- f" uv tool install --force {package}\n"
- f"或:pipx reinstall {package}"
- )
-
-
-def probe_command(
- cmd: str,
- args: Sequence[str] = ("--version",),
- timeout: int = 10,
- retries: int = 0,
- package: Optional[str] = None,
- env: Optional[Mapping[str, str]] = None,
- remove_env: Sequence[str] = (),
-) -> ProbeResult:
- """Actually execute `cmd *args` and classify the result.
-
- Intended for SIDE-EFFECT-FREE health probes only (version/status
- commands): retries re-run the command verbatim with no backoff, so a
- non-idempotent command would repeat its effect.
-
- package: pip/pipx package name used in the broken-install hint
- (defaults to cmd).
- env: values added only to the probed child process.
- remove_env: inherited variables removed only from the child process.
- """
- path = shutil.which(cmd)
- if not path:
- return ProbeResult("missing")
-
- last: Optional[ProbeResult] = None
- for _ in range(retries + 1):
- last = _run_once(path, args, timeout, package or cmd, env, remove_env)
- if last.ok:
- return last
- # missing/broken won't heal between retries — only transient
- # failures (timeout/error) are worth a second attempt
- if last.status in ("missing", "broken"):
- return last
- assert last is not None # retries + 1 always executes at least once
- return last
-
-
-def _run_once(
- path: str,
- args: Sequence[str],
- timeout: int,
- package: str,
- env: Optional[Mapping[str, str]] = None,
- remove_env: Sequence[str] = (),
-) -> ProbeResult:
- try:
- subprocess_env = utf8_subprocess_env()
- for key in remove_env:
- subprocess_env.pop(key, None)
- if env:
- subprocess_env.update(env)
- r = subprocess.run(
- [path, *args],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- timeout=timeout,
- env=subprocess_env,
- )
- except FileNotFoundError:
- # which() found it but exec failed: the shebang interpreter is gone
- return ProbeResult("broken", hint=reinstall_hint(package))
- except OSError:
- return ProbeResult("broken", hint=reinstall_hint(package))
- except subprocess.TimeoutExpired:
- return ProbeResult("timeout", hint=f"`{path}` 响应超时(>{timeout}s)")
-
- if r.returncode in _BROKEN_EXIT_CODES:
- return ProbeResult("broken", hint=reinstall_hint(package))
-
- output = (r.stdout or "") + (r.stderr or "")
- if r.returncode != 0:
- return ProbeResult("error", output=output.strip())
- return ProbeResult("ok", output=output.strip())
diff --git a/agent_reach/runtime/cli.py b/agent_reach/runtime/cli.py
index 68071678..fdad621f 100644
--- a/agent_reach/runtime/cli.py
+++ b/agent_reach/runtime/cli.py
@@ -38,7 +38,6 @@ from .sessions import clear_session, has_login_state, import_legacy_state, sessi
_MANAGEMENT = (
"setup", "add", "remove", "update", "doctor", "watch", "uninstall", "configure", "version",
)
-_TOP_LEVEL = ("channels", "check", "read", "login", "logout", "browser", "help", "-h", "--help") + _MANAGEMENT
HELP = """agent-reach — internet access for AI agents (all output is JSON)
@@ -62,7 +61,7 @@ For the user:
def unified_channels() -> List[Channel]:
- """Channels already moved to the unified entry."""
+ """Channels exposed on the command line."""
return [ch for ch in get_all_channels() if ch.level]
@@ -70,14 +69,6 @@ def _channel(name: str) -> Optional[Channel]:
return next((ch for ch in unified_channels() if ch.name == name), None)
-def handles(argv: Sequence[str]) -> bool:
- """Whether this argv belongs to the unified entry (vs. legacy commands)."""
- if not argv:
- return True
- head = argv[0]
- return head in _TOP_LEVEL or _channel(head) is not None
-
-
def _mgmt(action: str, fn, *args, **kwargs) -> int:
"""Run a management function and print {schema_version, ok, action, result, error}."""
try:
@@ -483,5 +474,6 @@ def main(argv: Sequence[str]) -> int:
if head in _MANAGEMENT:
return _cmd_management(head, rest)
channel = _channel(head)
- assert channel is not None # guaranteed by handles()
+ if channel is None:
+ return _bad_input(None, head, f"unknown command or channel: {head}; run `agent-reach help`")
return _cmd_action(channel, rest)
diff --git a/agent_reach/skill/references/career.md b/agent_reach/skill/references/career.md
deleted file mode 100644
index 2a965761..00000000
--- a/agent_reach/skill/references/career.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# 职场招聘
-
-LinkedIn、Boss直聘。
-
-## LinkedIn
-
-```bash
-# 获取个人资料
-mcporter call linkedin.get_person_profile linkedin_username="username" sections="experience,education"
-
-# 搜索人才
-mcporter call linkedin.search_people keywords="AI engineer" location="Shanghai"
-
-# 获取公司资料
-mcporter call linkedin.get_company_profile company_name="openai" sections="posts,jobs"
-
-# 搜索职位
-mcporter call linkedin.search_jobs keywords="software engineer" location="Remote" max_pages=2
-```
-
-> **需要登录**: 首次使用前运行 `uvx mcp-server-linkedin@latest --login`,保存有效登录态。
-
-### Fallback 方案
-
-如果 MCP 不可用,可以用 Jina Reader:
-
-```bash
-curl -s "https://r.jina.ai/https://linkedin.com/in/username"
-```
-
-## Boss直聘
-
-当用户说“帮我配 Boss直聘”时,按本节完成安装、启动专用 Chrome、等待用户手动
-登录和最终验证。不要把 9222 端口等实现细节先甩给用户,也不要替用户输入账号、
-扫码或处理滑块。
-
-> **关键区分:登录门槛 ≠ 反爬安全校验。** zhipin.com 落地后可能停在三种页面:
-> 已登录的 `web/geek/job`、未登录的 `web/user/`(扫码登录/手机号登录)、以及
-> 反爬的**安全校验页**(URL 含 `security-check` / `zhipin-security` /
-> `_security_check`)。安全校验页与登录无关:**已登录也会出现**(带 CDP 调试
-> 端口的 Chrome 几乎必现)。绝不用当前页 URL 判断登录态。
-
-> **双登录态存储(existing-browser 严格 CDP 模式下以浏览器为准)。** 存在两个凭据存储,
-> **都不能删**,但认证的是不同通道:
->
-> | 存储 | 角色 |
-> |---|---|
-> | `~/.boss-agent/auth/session.enc` | ① 硬性门槛:`_get_browser()` 无条件 `get_token()`,读不到直接 `AuthRequired`,CDP 搜索会在连浏览器前就失败;② **不是**搜索的认证凭据:CDP 复用真 Chrome 的 `contexts[0]` 时,它的 cookies 只在「无 context」分支注入,实际从未生效;③ httpx 通道(低危 op:`status`/`detail`/`cities`/`job_card_httpx`)真用它的 cookies + stoken,code 37 的 `force_refresh()` 也回写它 |
-> | 专用 Chrome profile 内的浏览器 cookie | CDP 模式下 search/greet 等高危 op 实际携带的凭据 |
->
-> **`boss status` / `status --live` 只校验 session.enc**——即使报
-> `logged_in: true`,也不代表 CDP 浏览器已登录。所以:
-> 1. 拉起专用 Chrome 后,第一步必须**暂停并让用户肉眼确认**窗口内是已登录
-> 状态(右上角有头像),确认后才允许执行搜索;
-> 2. doctor 的 boss 行会直接探测浏览器内有无 wt2 cookie,以它为准;
-> 3. **`AUTH_EXPIRED` 是 ground truth**:搜索报它就直接走登录 runbook
-> (用户在专用窗口登录 → `login --cdp`),禁止再往「安全校验」方向解释;
-> `_security_check` 页面只在 `AUTH_EXPIRED` 不存在时才按滑块处理。
-> 4. 不要为了「清理旧凭据」删除 session.enc;要刷新它就跑 `login --cdp`。
-
-> **依赖状态**:所需公开 strict-CDP API 来自 boss-agent-cli 后继拆分 PR #403–#407
-> (#402/#382 已按维护者意见拆分),已全部合并入上游 master。Agent Reach 的安装器锁定
-> 上游固定提交
-> `4c991b77086a203173bf08a4cb64a23af6514fe6`,而不是会移动的 branch;上游发布正式版后
-> 应把安装器切回版本约束。
-
-体检(无副作用,不搜索):
-
-```bash
-agent-reach doctor # boss 行:off = 未装或 CDP 不通;warn = 链路就绪,
- # message 会注明浏览器内有无 wt2 登录 cookie(以浏览器为准)
-```
-
-搜索 + JD 使用公开 API(`browser_source` / `job_card_browser` / `JobItem.lid`)。
-因为 pipx/uv tool 是隔离环境,普通 `python` 不一定能 import 已安装工具;
-用 `uv run --with` 保证脚本和锁定依赖处于同一解释器环境:
-
-```bash
-uv run --isolated --no-project \
- --with 'git+https://github.com/can4hou6joeng4/boss-agent-cli.git@4c991b77086a203173bf08a4cb64a23af6514fe6' \
- python - <<'PY'
-from pathlib import Path
-
-from boss_agent_cli.api.client import AccountRiskError, BossClient, EnvironmentRiskError
-from boss_agent_cli.auth.manager import AuthManager
-from boss_agent_cli.platforms.zhipin import BossPlatform
-
-auth = AuthManager(Path.home() / ".boss-agent")
-
-# 严格 CDP 模式:复用已登录浏览器、CDP 失败立即抛错、永不 headless
-with BossClient(
- auth,
- cdp_url="http://localhost:9222",
- browser_source="existing-browser",
-) as boss:
- raw = boss.search_jobs("大模型", city="深圳", page=1)
- if raw.get("code") != 0:
- code, message = BossPlatform(boss).parse_error(raw)
- raise RuntimeError(f"{code}: {message}")
- items = raw.get("zpData", {}).get("jobList", [])
- for item in items:
- card = boss.job_card_browser(item["securityId"], item["lid"])
- post_desc = card.get("zpData", {}).get("jobCard", {}).get(
- "postDescription", ""
- )
- print(item.get("jobName"), post_desc)
-
-# AccountRiskError / EnvironmentRiskError → 立即停止,不自动重试;
-# 明确 token/stoken 过期的 code 37 由 BossClient 最多刷新并重试一次。
-PY
-```
-
-### 环境体检与恢复(抓取前必查)
-
-搜索前若 `agent-reach doctor` 报 boss 为 `off` 或 `warn`,按下面 runbook 排查,不要读源码瞎猜:
-
-1. **CDP 端口通不通**:
- ```bash
- curl -s http://localhost:9222/json/version # 有 Browser 字段 = 端口通
- ```
-
-2. **调试 Chrome 没开 / 已关**:按系统启动专用 Chrome(登录态独立,不污染日常浏览器):
- ```bash
- # macOS
- open -na "Google Chrome" --args --remote-debugging-address=127.0.0.1 \
- --remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
- "https://www.zhipin.com/web/geek/job"
-
- # Linux
- google-chrome --remote-debugging-address=127.0.0.1 \
- --remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
- "https://www.zhipin.com/web/geek/job"
- ```
-
- Windows PowerShell:
- ```powershell
- Start-Process chrome.exe -ArgumentList '--remote-debugging-address=127.0.0.1','--remote-debugging-port=9222',"--user-data-dir=$env:USERPROFILE\.boss-chrome-profile",'https://www.zhipin.com/web/geek/job'
- ```
-
- 只绑定回环地址。任何能访问 9222 的进程都能完全控制该 Chrome;不要监听公网。
- 这个专用 profile 要长期复用,以保留稳定登录态;不要每次运行时删除或新建,
- 也不要默认切换到日常主 Chrome。不使用时关闭这个专用窗口。
-
- **拉起后第一步:暂停并让用户肉眼确认窗口内是已登录状态(右上角有头像)。**
- 不要用 `boss status` 代替这一步——它只校验本地 session.enc,不代表浏览器。
-
-3. **用户手动登录(浏览器未登录时)**:判定以 doctor 的浏览器 cookie 探测为准
- (无 wt2 = 浏览器未登录),其次才是用户肉眼确认;`boss status` 只作参考。
- 让用户在这个专用窗口登录或扫码。用户确认完成后,保存 CDP 登录态:
- ```bash
- boss --cdp-url http://localhost:9222 login --cdp
- ```
-
- 若窗口停在安全校验页(`security-check` / `zhipin-security`),这是反爬挑战、
- 不是登录页:等它自动放行或让用户手动过一下滑块即可,不要当成“未登录”去
- 重新扫码登录。
-
-4. **登录态是否有效**(浏览器 cookie 探测 + stoken 是否过期):
- ```bash
- agent-reach doctor # 看 boss 行 message 里的浏览器 wt2 cookie 探测结果
- boss status # 只反映本地 session.enc,仅作参考
- ```
-
-5. **错误码处置**(搜索/取 JD 时):
- - `AUTH_EXPIRED`(用户未登录)→ **ground truth**:CDP 浏览器未登录(不管
- `boss status` 说什么),直接走第 3 步登录流程 + `login --cdp`,禁止往
- 「安全校验」方向解释;
- - code 36(ACCOUNT_RISK)→ 立即停,手动到 BOSS 页面处理,不可自动重试;
- - code 9(RATE_LIMITED)→ 冷却后重试;
- - code 37 + `环境存在异常` → `ENVIRONMENT_RISK`,立即停止,不刷新 Token、不重新登录、不自动重试;
- - 只有文案明确表示 token/stoken 过期的 code 37 才是 `TOKEN_REFRESH_FAILED`;客户端最多自动刷新并重试一次,仍失败再重新登录。
-
-用户要求开始搜索时,Agent 必须指定严格 CDP 模式(全局选项放在子命令之前):
-
-```bash
-boss --browser-source existing-browser --cdp-url http://localhost:9222 search "大模型" --city 广州 --page 1
-```
-
-不要无提示连续翻页。boss-agent-cli PR #383 为跨 CLI 进程的普通搜索增加持久
-5–10 秒列表预算;该 PR 合并发布前,Agent 仍应主动串行、降频调用。
-
-> **等待属预期,不是卡死**:连续搜索命中节流时,boss-agent-cli 会静默等待 5–10 秒
-> (TTY 下会显示「节流等待 Ns…」提示;Agent Reach 以 `--json` 调用,看不到该提示)。
-> 等待窗口内不要重试、不要拉起新浏览器、不要切换 profile。
diff --git a/agent_reach/skill/references/dev.md b/agent_reach/skill/references/dev.md
deleted file mode 100644
index ca247622..00000000
--- a/agent_reach/skill/references/dev.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# 开发工具
-
-GitHub CLI
-
-## GitHub (gh CLI)
-
-GitHub 官方命令行工具,用于仓库、Issue、PR、Actions、Release 以及 API 访问。
-
-```bash
-# 认证
-gh auth login
-gh auth status
-
-# 搜索
-gh search repos "query" --sort stars --limit 10
-gh search code "query" --language python
-
-# 仓库
-gh repo view owner/repo
-gh repo clone owner/repo
-gh repo create my-repo --private
-gh repo fork owner/repo
-gh repo fork owner/repo --clone
-gh repo sync owner/repo
-
-# Issues
-gh issue list -R owner/repo --state open
-gh issue view 123 -R owner/repo
-gh issue create -R owner/repo --title "Title" --body "Body"
-
-# Pull Requests
-gh pr list -R owner/repo --state open
-gh pr view 123 -R owner/repo
-gh pr create -R owner/repo --title "Title" --body "Body"
-gh pr checks 123 --repo owner/repo
-
-# Actions / CI
-gh run list --repo owner/repo --limit 10
-gh run view <run-id> --repo owner/repo
-gh run view <run-id> --repo owner/repo --log-failed
-gh workflow list --repo owner/repo
-
-# Releases
-gh release list -R owner/repo
-gh release create v1.0.0
-
-# API
-gh api /user
-gh api repos/owner/repo
-
-# JSON 输出
-gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
-```
-
-
-## 选择指南
-
-| 工具 | 来源 | 用途 |
-|-----|------|------|
-| gh CLI | agent-reach | Git 操作 |
-| zread | my-mcp-tools | 读仓库内容 |
-| context7 | my-mcp-tools | 查技术文档 |
diff --git a/agent_reach/skill/references/finance.md b/agent_reach/skill/references/finance.md
deleted file mode 100644
index bebfce93..00000000
--- a/agent_reach/skill/references/finance.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# 金融行情
-
-雪球股票行情、搜索与热门内容。行情可能延迟,不构成投资建议。
-
-## 先检查状态
-
-```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/search.md b/agent_reach/skill/references/search.md
deleted file mode 100644
index d571c2ef..00000000
--- a/agent_reach/skill/references/search.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# 搜索工具
-
-Exa AI 搜索引擎。
-
-## Exa AI 搜索
-
-高质量 AI 搜索引擎,适合查找技术文档、官方示例和相关网页。
-
-```bash
-mcporter call exa.web_search_exa query="query" numResults=5
-mcporter call exa.web_search_exa query="library API code example" numResults=5
-```
-
-### 使用场景
-
-| 场景 | 参数 |
-|-----|------|
-| 网页搜索 | `web_search_exa(query: "...", numResults: 5)` |
-| 技术/代码资料 | `web_search_exa(query: "框架名 API 示例", numResults: 5)` |
-
-> Exa MCP 的 `get_code_context_exa` 已弃用且默认不注册。代码问题也使用
-> `web_search_exa`;需要精确搜索仓库内容时,改用 `dev.md` 中的 GitHub 搜索。
-
-### 特点
-
-- 擅长英文内容和技术文档
-- 可通过查询词定位官方文档和代码示例
-- 结果质量高
-
-## 与其他搜索工具对比
-
-| 工具 | 来源 | 适用场景 |
-|-----|------|---------|
-| Exa | agent-reach | 英文/技术/代码搜索 |
-| 智谱搜索 | my-mcp-tools | 中文搜索 |
-| GitHub 搜索 | agent-reach (dev.md) | 仓库/代码搜索 |
diff --git a/agent_reach/skill/references/social.md b/agent_reach/skill/references/social.md
deleted file mode 100644
index a2b6f47b..00000000
--- a/agent_reach/skill/references/social.md
+++ /dev/null
@@ -1,301 +0,0 @@
-# 社交媒体 & 社区
-
-小红书、Twitter/X、B站、V2EX、Reddit、Facebook、Instagram。
-
-## 小红书 / XiaoHongShu(多后端)
-
-小红书有三个后端,**先跑 `agent-reach doctor --json` 看 xiaohongshu 的 `active_backend` 是哪个**,再用对应命令组。
-
-### 后端 A:OpenCLI(桌面首选)
-
-```bash
-# 搜索笔记
-opencli xiaohongshu search "query" -f yaml
-
-# 读笔记正文+互动数据(用搜索结果里的完整 URL,含 xsec_token)
-opencli xiaohongshu note "NOTE_URL" -f yaml
-
-# 评论(支持楼中楼)
-opencli xiaohongshu comments NOTE_ID -f yaml
-
-# 首页推荐 feed
-opencli xiaohongshu feed -f yaml
-
-# 用户主页公开笔记
-opencli xiaohongshu user USER_ID -f yaml
-```
-
-> 要求 Chrome 打开且装了 OpenCLI 扩展。OpenCLI 只使用用户已经存在且明确控制
-> 的 Chrome 会话;Agent Reach 不替用户登录,也不读取浏览器 Cookie。
-> `agent-reach configure xhs-cookies` 不会把 Cookie 注入 OpenCLI。
-> 如果没有现成会话,不要自动登录;改走后端 B/C,并按对应的
-> Cookie-Editor 手工导出流程配置。
-
-### 后端 B:xiaohongshu-mcp(服务器场景)
-
-```bash
-# 认证前先让用户用 Cookie-Editor 手工导出,再显式导入
-agent-reach configure xhs-cookies
-
-# 只读检查当前状态
-mcporter call xiaohongshu.check_login_status --timeout 120000
-
-# 搜索
-mcporter call xiaohongshu.search_feeds keyword="query" --timeout 120000
-
-# 笔记详情+评论(feed_id 和 xsec_token 从搜索结果取)
-mcporter call xiaohongshu.get_feed_detail feed_id="..." xsec_token="..." --timeout 120000
-```
-
-> 首次调用会自动下载约 150MB 无头浏览器,务必带 `--timeout 120000`。
-> 认证只走 Cookie-Editor 手工导出;导入后先运行 `check_login_status`。
-> 该显式命令会保存/导入用户提供的 xiaohongshu.com 同域 Cookie 集,用户应
-> 确认范围;非 xiaohongshu.com 域 Cookie 会被忽略。
-
-### 后端 C:xhs-cli(存量备选,上游 2026-03 起停更)
-
-```bash
-xhs search "query" # 搜索
-xhs read NOTE_ID_OR_URL # 读笔记(必须用搜索结果中的 URL/ID,不能裸 note_id)
-xhs comments NOTE_ID_OR_URL # 评论
-xhs hot # 热门
-xhs feed # 推荐
-```
-
-> 已知不稳定:`xhs user` / `xhs user-posts` / `xhs favorites` 可能返回 API error(上游停更无人修)。新装用户建议直接走后端 A/B。
-
-### 通用注意事项
-
-> **认证边界**: Agent Reach 不得替用户执行小红书登录,也不得读取浏览器
-> Cookie。OpenCLI 只能使用用户已有且明确控制的 Chrome 会话;
-> xiaohongshu-mcp / 存量工具使用 Cookie-Editor 手工导出。
->
-> **xsec_token 限制**: 小红书强制 xsec_token 机制,**不能直接用裸 note_id 去读**。正确流程:先搜索/feed 拿结果,再用结果中的完整 URL/ID 去读。三个后端都一样。
->
-> **频率控制**: 高频请求(批量搜索、深翻评论)会触发验证码,平台限制无法绕过。每次操作间隔 2-3 秒。
->
-> **写操作(发帖/评论/点赞)**: 建议只读。xhs-cli v0.6.x 写操作可能因签名问题返回 406。
-
-## Twitter/X (twitter-cli)
-
-### 认证前置条件
-
-`agent-reach configure twitter-cookies` 通过隐藏输入保存的 Cookie 只供
-`agent-reach doctor` 检查显式凭据是否齐全。`doctor` 不执行上游
-`twitter status`,也不会设置当前 Shell。运行下面任何 `twitter` 命令前,
-必须在同一个 Shell 或子进程环境中显式提供:
-
-```bash
-export TWITTER_AUTH_TOKEN="..."
-export TWITTER_CT0="..."
-```
-
-### 稳定命令
-
-```bash
-# 首页时间线(最稳定)
-twitter feed -n 20
-
-# 读取单条推文(含回复)
-twitter tweet URL_OR_ID
-
-# 读取长文 / X Article
-twitter article URL_OR_ID
-
-# 用户时间线
-twitter user-posts @username -n 20
-
-# 用户资料
-twitter user @username
-```
-
-### 可能不稳定的命令
-
-```bash
-# 搜索推文(Twitter 频繁改 GraphQL 端点,可能 404)
-twitter search "query" -n 10
-
-# likes(2024 年后只能看自己的,平台限制)
-twitter likes
-```
-
-### search 失败时的重试链(按序执行,成功即停)
-
-1. 直接重试一次(偶发失败常见):`twitter search "query" -n 10`
-2. 升级后再试:`pipx upgrade twitter-cli && twitter search "query" -n 10`
-3. 换 OpenCLI 备选(桌面,复用浏览器登录态):`opencli twitter search "query" -f yaml`
-4. 都不行就改用 `twitter feed` / `twitter user-posts @somebody` 等稳定命令绕路
-
-### 重要注意事项
-
-> **安装**: `pipx install twitter-cli`(确保 v0.8.5+)
->
-> **认证**: 只用 Cookie-Editor 手工导出,再显式设置环境变量
-> `TWITTER_AUTH_TOKEN` + `TWITTER_CT0`;不要依赖自动浏览器读取。
->
-> **IP 风控**: 不要在 VPS/数据中心 IP 上频繁调用,尤其是 followers/following,有封号风险。使用住宅代理或本地环境。
->
-> **OpenCLI 备选**: 桌面装了 OpenCLI 的话,`opencli twitter search/article/user-posts -f yaml` 全套可用(浏览器登录态,无需 cookie 环境变量)。
->
-> **输出格式**: 建议用 `--yaml` 或 `--json` 获得结构化输出,对 AI agent 更友好。
-
-## B站 / Bilibili
-
-> ⚠️ **不要用 yt-dlp 读 B站**(风控已全面 412 拦截,实测无解)。用 bili-cli / OpenCLI。
-
-```bash
-# 搜索 / 热门 / 视频详情(bili-cli,只读无需登录)
-bili search "query" --type video -n 5
-bili hot -n 10
-bili video BVxxx
-
-# 字幕(OpenCLI,需桌面 Chrome)
-opencli bilibili subtitle BVxxx
-```
-
-> 详细命令(音频转写、API 直连兜底)见 [references/video.md](video.md)。
-
-## V2EX (公开 API)
-
-无需认证,直接调用公开 API。
-
-### 热门主题
-
-```bash
-curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"
-```
-
-### 节点主题
-
-```bash
-# node_name 如: python, tech, jobs, qna, programmers
-curl -s "https://www.v2ex.com/api/topics/show.json?node_name=python&page=1" -H "User-Agent: agent-reach/1.0"
-```
-
-### 主题详情
-
-```bash
-# topic_id 从 URL 获取,如 https://www.v2ex.com/t/1234567
-curl -s "https://www.v2ex.com/api/topics/show.json?id=TOPIC_ID" -H "User-Agent: agent-reach/1.0"
-```
-
-### 主题回复
-
-```bash
-curl -s "https://www.v2ex.com/api/replies/show.json?topic_id=TOPIC_ID&page=1" -H "User-Agent: agent-reach/1.0"
-```
-
-### 用户信息
-
-```bash
-curl -s "https://www.v2ex.com/api/members/show.json?username=USERNAME" -H "User-Agent: agent-reach/1.0"
-```
-
-### Python 调用示例
-
-```python
-from agent_reach.channels.v2ex import V2EXChannel
-
-ch = V2EXChannel()
-
-# 获取热门帖子
-topics = ch.get_hot_topics(limit=10)
-for t in topics:
- print(f"[{t['node_title']}] {t['title']} ({t['replies']} 回复)")
-
-# 获取节点帖子
-node_topics = ch.get_node_topics("python", limit=5)
-
-# 获取帖子详情 + 回复
-topic = ch.get_topic(1234567)
-print(topic["title"], "—", topic["author"])
-
-# 获取用户信息
-user = ch.get_user("Livid")
-```
-
-> **节点列表**: https://www.v2ex.com/planes
-
-## Reddit(多后端,必须登录态)
-
-**Reddit 没有零配置路径**:匿名 `.json` 端点已被封(403),官方 API 自 2025-11 起人工审批基本不批。两个后端都靠登录态,先跑 `agent-reach doctor --json` 看 reddit 的 `active_backend`。中国大陆访问需代理。
-
-### 后端 A:OpenCLI(桌面首选,复用浏览器登录态)
-
-```bash
-# 搜索帖子
-opencli reddit search "query" -f yaml
-
-# 读帖子全文 + 评论
-opencli reddit read POST_ID -f yaml
-
-# 浏览 subreddit / 热门 / Popular
-opencli reddit subreddit LocalLLaMA -f yaml
-opencli reddit hot -f yaml
-opencli reddit popular -f yaml
-
-# subreddit 元信息(订阅数、简介)
-opencli reddit subreddit-info LocalLLaMA -f yaml
-```
-
-> 要求 Chrome 打开且浏览器里登录过 reddit.com。
-
-### 后端 B:rdt-cli(存量/服务器备选,上游 2026-03 起停更)
-
-```bash
-rdt search "query" --limit 10 # 搜索帖子
-rdt read POST_ID # 读帖子全文 + 评论
-rdt sub python --limit 20 # 浏览 subreddit
-rdt popular --limit 10 # 浏览热门
-rdt all --limit 10 # 浏览 /r/all
-```
-
-> **安装**: `pipx install 'git+https://github.com/public-clis/rdt-cli.git'`(PyPI 版本落后,需从 GitHub 装 v0.4.2+)。先 `rdt login` 才能搜索和阅读(服务器无浏览器时手动写 Cookie,见 doctor 提示)。
-> 建议使用 `--yaml` 输出,对 AI agent 更友好。
-
-### 高级选项:官方 API + PRAW(仅限已有凭证的用户)
-
-2025-11 前注册过 Reddit script app(持有 client_id/client_secret)的用户可以用 PRAW 走官方 API(100 QPM 免费)。新申请需人工审批且个人项目基本不批,**不要推荐新用户走这条路**。
-
-## Facebook(OpenCLI,必须登录态)
-
-Facebook 走 OpenCLI,复用用户 Chrome 里的 facebook.com 登录态。先跑 `agent-reach doctor --json` 看 facebook 的 `active_backend`,正常应为 `OpenCLI`。不要推荐 Jina/Exa/Graph API 作为默认路径。
-
-```bash
-# 搜索用户 / 主页 / 帖子
-opencli facebook search "query" -f yaml
-
-# 用户或主页信息
-opencli facebook profile zuck -f yaml
-
-# 当前账号 News Feed
-opencli facebook feed --limit 10 -f yaml
-
-# 当前账号可见的群组列表/最近动态
-opencli facebook groups --limit 20 -f yaml
-```
-
-> 要求 Chrome 打开且装了 OpenCLI 扩展,并已登录 facebook.com。Facebook Groups 当前只承诺读取当前账号可见的群组列表/最近动态,不承诺任意群帖子和评论 API。
-
-## Instagram(OpenCLI,必须登录态)
-
-Instagram 走 OpenCLI,复用用户 Chrome 里的 instagram.com 登录态。先跑 `agent-reach doctor --json` 看 instagram 的 `active_backend`,正常应为 `OpenCLI`。不要默认恢复 instaloader;历史上 cookies/401/429 不稳定。
-
-```bash
-# 搜索用户(不是全站帖子关键词搜索)
-opencli instagram search "query" -f yaml
-
-# 用户 Profile
-opencli instagram profile nasa -f yaml
-
-# 用户最近帖子
-opencli instagram user nasa --limit 12 -f yaml
-
-# Explore / Discover
-opencli instagram explore --limit 20 -f yaml
-
-# 当前账号收藏
-opencli instagram saved --limit 20 -f yaml
-```
-
-> 要求 Chrome 打开且装了 OpenCLI 扩展,并已登录 instagram.com。`instagram search` 是用户搜索;读帖子需要先确定 username,再用 `instagram user USERNAME`。若出现 429 / login required,先让用户在 Chrome 里重新登录并降低频率。
diff --git a/agent_reach/skill/references/video.md b/agent_reach/skill/references/video.md
deleted file mode 100644
index 54d44948..00000000
--- a/agent_reach/skill/references/video.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# 视频/播客
-
-YouTube、B站、小宇宙播客的字幕和转录。
-
-## YouTube (yt-dlp)
-
-### 获取视频元数据
-
-```bash
-yt-dlp --dump-json "URL"
-```
-
-### 下载字幕
-
-```bash
-# 下载字幕 (不下载视频)
-yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download -o "/tmp/%(id)s" "URL"
-
-# 然后读取 .vtt 文件
-cat /tmp/VIDEO_ID.*.vtt
-```
-
-### 获取评论
-
-```bash
-# 提取评论(best-effort,不保证完整)
-yt-dlp --write-comments --skip-download --write-info-json \
- --extractor-args "youtube:max_comments=20" \
- -o "/tmp/%(id)s" "URL"
-# 评论在 .info.json 的 comments 字段中
-```
-
-### 搜索视频
-
-```bash
-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
-# 视频没有字幕时的兜底:下载音频并用 Whisper 转写(Groq 免费 key 即可)
-agent-reach transcribe "https://www.youtube.com/watch?v=VIDEO_ID"
-agent-reach transcribe ./local_audio.mp3 -o /tmp/transcript.txt
-```
-
-> `agent-reach transcribe` 只接收公开 http(s) URL 或本地音频文件。用 `ytsearch5:` 搜索时,先从 yt-dlp 结果里选出具体视频 URL,再转写。
-> 需要先配置 key:`agent-reach configure groq-key`(隐藏输入;免费,console.groq.com)
-> 或 `agent-reach configure openai-key`。默认 auto 模式只使用第一个已配置服务商
->(优先 Groq,否则 OpenAI),失败即停止,不会把音频自动发给另一家。
-> `--allow-provider-fallback` 会显式授权跨服务商降级;同一音频内容可能被 Groq 和
-> OpenAI 分别处理,并可能产生 OpenAI 费用,只应在确认内容可分享给两家后使用。
-
-## B站 / Bilibili(bili-cli 为主,OpenCLI 补字幕)
-
-> ⚠️ **不要用 yt-dlp 读 B站**:B站风控已全面 412 拦截 yt-dlp(实测最新版、直连/代理/带 Cookie 全部无效)。yt-dlp 只用于 YouTube。
-
-### 视频详情/搜索/热门/排行 (bili-cli,只读无需登录)
-
-```bash
-# 视频详情(标题/UP主/时长/播放互动数据/字幕可用性)
-bili video BVxxx
-
-# 搜索视频
-bili search "query" --type video -n 5
-
-# 热门视频 / 排行榜
-bili hot -n 10
-bili rank -n 10
-
-# 下载音频并切分为 ASR-ready WAV(无字幕时配合 agent-reach transcribe 转写)
-bili audio BVxxx
-```
-
-### 字幕 (OpenCLI,需要桌面 Chrome)
-
-```bash
-# 字幕逐句带时间轴
-opencli bilibili subtitle BVxxx
-
-# OpenCLI 也能搜索/读视频元数据(备选)
-opencli bilibili search "query" -f yaml
-opencli bilibili video BVxxx -f yaml
-```
-
-### 零配置兜底:搜索 API 直连
-
-```bash
-UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
-curl -s -c /tmp/bili_ck.txt -o /dev/null -A "$UA" "https://www.bilibili.com/"
-curl -s -b /tmp/bili_ck.txt -A "$UA" -e "https://www.bilibili.com/" \
- "https://api.bilibili.com/x/web-interface/search/all/v2?keyword=QUERY&page=1"
-```
-
-> **安装 bili-cli**: `pipx install bilibili-cli`(上游 2026-03 起停更但实测健康;只读场景无需登录,`bili login` 扫码可解锁动态/收藏等个人功能)。
-
-## 小宇宙播客 / Xiaoyuzhou Podcast
-
-### 转录单集播客(可选 --polish 增强标点)
-
-```bash
-# 输出 Markdown 文件到 /tmp/。--polish 让 Llama 3.3 70B 给文稿补中文标点+合理分段
-~/.agent-reach/tools/xiaoyuzhou/transcribe.sh --polish "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID"
-```
-
-> 转写 prompt 已要求 Whisper 输出中文标点;若标点效果仍不理想,可加 `--polish` 用 Groq 上免费的 Llama 3.3 70B 补标点+合理分段(9 分钟播客约多 ~7 秒)。每次转写多一轮 LLM 调用,按需使用。
-
-### 前置要求
-
-1. **ffmpeg**: `brew install ffmpeg`
-2. **Groq API Key** (免费): https://console.groq.com/keys
-3. **配置 Key**: `agent-reach configure groq-key`(隐藏输入)
-4. **首次运行**: `agent-reach install --env=auto --system --channels=xiaoyuzhou`(需用户明确授权)
-
-### 检查状态
-
-```bash
-agent-reach doctor
-```
-
-> 输出 Markdown 文件默认保存到 `/tmp/`。
-
-## 选择指南
-
-| 场景 | 推荐工具 |
-|-----|---------|
-| YouTube 字幕 | yt-dlp;失败时 OpenCLI(最多 3 次)→ agent-reach transcribe |
-| B站视频详情/搜索 | bili-cli |
-| B站字幕 | opencli bilibili subtitle |
-| 播客转录 | 小宇宙 transcribe.sh |
-| 无字幕音视频 | agent-reach transcribe(B站音频先 `bili audio`) |
diff --git a/agent_reach/skill/references/web.md b/agent_reach/skill/references/web.md
deleted file mode 100644
index bbfa3c04..00000000
--- a/agent_reach/skill/references/web.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# 网页阅读
-
-通用网页、RSS。
-
-## 通用网页 (Jina Reader)
-
-```bash
-# 读取任意网页内容
-curl -s "https://r.jina.ai/URL"
-
-# 示例
-curl -s "https://r.jina.ai/https://example.com/article"
-```
-
-**适用场景**: 大多数网页可以直接用 Jina Reader 读取。
-
-## Web Reader (MCP)
-
-```bash
-# 读取网页内容 (Markdown 格式)
-mcporter call web-reader.webReader url="https://example.com"
-
-# 保留图片
-mcporter call web-reader.webReader url="https://example.com" retain_images=true
-
-# 纯文本格式
-mcporter call web-reader.webReader url="https://example.com" return_format="text"
-```
-
-**适用场景**: 需要更精确控制输出格式时使用。
-
-## RSS (feedparser)
-
-```python
-python3 -c "
-import feedparser
-for e in feedparser.parse('FEED_URL').entries[:5]:
- print(f'{e.title} — {e.link}')
-"
-```
-
-**适用场景**: 订阅博客、新闻源、播客等 RSS feed。
-
-## 选择指南
-
-| 场景 | 推荐工具 |
-|-----|---------|
-| 通用网页 | Jina Reader (`curl r.jina.ai`) |
-| 需要图片/格式控制 | web-reader MCP |
-| RSS 订阅 | feedparser |
diff --git a/agent_reach/utils/paths.py b/agent_reach/utils/paths.py
index fb814ce3..6e460b7f 100644
--- a/agent_reach/utils/paths.py
+++ b/agent_reach/utils/paths.py
@@ -1,9 +1,8 @@
-"""Cross-platform path and remediation helpers."""
+"""Cross-platform private path helpers."""
from __future__ import annotations
import os
-import shlex
import stat
import sys
import tempfile
@@ -180,46 +179,3 @@ def read_small_text_no_follow(
finally:
os.close(fd)
return payload.decode(encoding)
-
-
-def get_ytdlp_config_dir() -> Path:
- """Return yt-dlp's first user config directory.
-
- yt-dlp checks ``$XDG_CONFIG_HOME/yt-dlp`` first on every supported
- platform, falling back to ``~/.config/yt-dlp`` when the variable is not
- set. Writing anywhere else can make Agent Reach and Doctor agree with each
- other while the real yt-dlp process silently ignores the setting.
- """
-
- xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
- config_home = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
- return config_home / "yt-dlp"
-
-
-def get_ytdlp_config_path() -> Path:
- """Return the yt-dlp user config file path for this OS."""
-
- return get_ytdlp_config_dir() / "config"
-
-
-def render_ytdlp_fix_command() -> str:
- """Return an OS-appropriate command to enable Node.js as yt-dlp JS runtime."""
-
- config_path = get_ytdlp_config_path()
- if sys.platform == "win32":
- return (
- f"$cfg = '{config_path}'\n"
- "New-Item -ItemType Directory -Force -Path (Split-Path $cfg) | Out-Null\n"
- "if (-not (Test-Path $cfg) -or -not (Select-String -Path $cfg -Pattern '--js-runtimes' -Quiet)) {\n"
- " Add-Content -Path $cfg -Value '--js-runtimes node'\n"
- "}"
- )
- config_dir = shlex.quote(str(config_path.parent))
- config_file = shlex.quote(str(config_path))
- return (
- f"mkdir -p {config_dir} && "
- "{ "
- f"grep -qxF -- '--js-runtimes node' {config_file} 2>/dev/null || "
- f"printf '%s\\n' '--js-runtimes node' >> {config_file}; "
- "}"
- )
diff --git a/agent_reach/utils/process.py b/agent_reach/utils/process.py
index 27766163..c648d83f 100644
--- a/agent_reach/utils/process.py
+++ b/agent_reach/utils/process.py
@@ -16,11 +16,3 @@ def utf8_subprocess_env(base: Mapping[str, str] | None = None) -> dict[str, str]
env = dict(base or os.environ)
env.update(UTF8_ENV)
return env
-
-
-def mcporter_utf8_env_args() -> list[str]:
- """Return mcporter --env arguments for UTF-8 Python stdio servers."""
- args = []
- for key, value in UTF8_ENV.items():
- args.extend(["--env", f"{key}={value}"])
- return args
diff --git a/agent_reach/utils/text.py b/agent_reach/utils/text.py
index 9ab61b99..994981c3 100644
--- a/agent_reach/utils/text.py
+++ b/agent_reach/utils/text.py
@@ -1,9 +1,8 @@
-"""UTF-8-safe text helpers for cross-platform file operations."""
+"""Text helpers."""
from __future__ import annotations
import re
-from pathlib import Path
_URL_CREDENTIALS_RE = re.compile(
r"([A-Za-z][A-Za-z0-9+.\-]{0,19}://)[^/\s@]+@"
@@ -26,12 +25,3 @@ def scrub_url_credentials(text: object) -> str:
scrubbed = _URL_CREDENTIALS_RE.sub(r"\1***@", str(text))
scrubbed = _BARE_USERINFO_RE.sub("***@", scrubbed)
return _URL_QUERY_SECRET_RE.sub(r"\1***", scrubbed)
-
-
-def read_utf8_text(path: str | Path, default: str = "") -> str:
- """Read text as UTF-8 with replacement semantics."""
-
- target = Path(path)
- if not target.exists():
- return default
- return target.read_text(encoding="utf-8", errors="replace")
diff --git a/constraints.txt b/constraints.txt
index 1cefa184..28ad3c9c 100644
--- a/constraints.txt
+++ b/constraints.txt
@@ -3,10 +3,8 @@
# pip install -c constraints.txt -e .[dev]
requests==2.32.5
-feedparser==6.0.12
loguru==0.7.3
PyYAML==6.0.3
-rich==14.3.2
yt-dlp==2026.07.04
yt-dlp-ejs==0.8.0
diff --git a/docs/README_en.md b/docs/README_en.md
index b15b3ce6..8be0e929 100644
--- a/docs/README_en.md
+++ b/docs/README_en.md
@@ -1,11 +1,11 @@
<h1 align="center">👁️ Agent Reach</h1>
<p align="center">
- <strong>Give your AI Agent one-click access to the entire internet</strong>
+ <strong>Let your AI agent reach the parts of the internet it can't reach on its own</strong>
</p>
<p align="center">
- The most reliable access path for each platform — chosen, installed, and health-checked for you. Backends come and go; you won't notice.
+ Login-walled platforms, what's inside videos and podcasts, Chinese platforms, clean structured data. One command, one JSON shape.
</p>
<p align="center">
@@ -59,253 +59,163 @@
## Why Agent Reach?
-AI Agents can already access the internet — but "can go online" is barely the start.
+CLI agents such as Claude Code, Codex, Hermes Agent and OpenClaw come with web search and page fetching, but they mostly can't reach:
-The most valuable information lives across social and niche platforms: Twitter discussions, Reddit feedback, YouTube tutorials, XiaoHongShu reviews, Bilibili videos, GitHub activity… **These are where information density is highest**, but each platform has its own barriers:
+- **Login-walled platforms**: XiaoHongShu, Twitter/X, Reddit, LinkedIn, Boss Zhipin... a plain fetch gets nothing or a login page.
+- **What's inside video and audio**: YouTube and Bilibili subtitles, full transcripts of Xiaoyuzhou podcasts.
+- **Chinese platforms**: Bilibili, XiaoHongShu, V2EX, Xueqiu, Xiaoyuzhou, which general search covers poorly.
+- **Clean structured data**: Xueqiu quotes, V2EX topics and replies, GitHub repos and issues, as fields instead of HTML to guess from.
-| Pain Point | Reality |
-|------------|---------|
-| Twitter API | Pay-per-use, moderate usage ~$215/month |
-| Reddit | Server IPs get 403'd |
-| XiaoHongShu | Login required to browse |
-| Bilibili | Blocks overseas/server IPs |
+Agent Reach installs the open-source tools behind these platforms, pins their versions, health-checks them, and gives the agent one entry point:
-To connect your Agent to these platforms, you'd have to find tools, install dependencies, and debug configs — one by one.
-
-**Agent Reach turns this into one command:**
-
-```
-Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
+```bash
+agent-reach channels # which channels exist and what each can do
+agent-reach bilibili search "LLM" # agent-reach <channel> <action> [args]
+agent-reach read https://www.v2ex.com/t/123 # picks the channel from the link
```
-Copy that to your Agent. A few minutes later, it can read tweets, search Reddit, and watch Bilibili.
+Every command prints the same JSON shape, so the agent doesn't have to learn each tool or parse each tool's output.
-**Already installed? Update in one command:**
-
-```
-Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-```
+> The `web` channel (web search and page reading) is only a fallback, for when the agent's own search or fetch is missing or fails.
### ✅ Before you start, you might want to know
-| | |
-|---|---|
-| 💰 **Completely free** | All tools are open source, all APIs are free. The only possible cost is a server proxy ($1/month) — local computers don't need one |
-| 🔒 **Privacy safe** | Cookies stay local. Never uploaded. Fully open source — audit anytime |
-| 🔄 **Kept up to date** | Every platform routes through a primary + fallback backend list. When an access path dies, we switch to the next — you won't notice (June 2026: Bilibili 412-blocked yt-dlp → switched to bili-cli, zero action on your side) |
-| 🤖 **Works with any Agent** | Claude Code, OpenClaw, Cursor, Windsurf… any Agent that can run commands |
-| 🩺 **Built-in diagnostics** | `agent-reach doctor` — one command shows what works, what doesn't, and how to fix it |
+- **Which agents?** Any agent that can run shell commands. `agent-reach setup` installs the usage instructions (a skill) into the skill folders of Claude Code, Codex, OpenCode, OpenClaw and others.
+- **Does it cost money?** The program and its backends are open source and free. The only keys you may need are for speech-to-text: Groq (has a free tier) or OpenAI Whisper.
+- **Does it touch my browser or accounts?** It never reads your own browser's cookies and never logs in for you. For login channels, you log in yourself in the dedicated Agent Reach browser. See [Security](#security).
+- **Which OS?** macOS first, Linux works, Windows best effort.
---
## Supported Platforms
-| Platform | Capabilities | Setup | Notes |
-|----------|-------------|:-----:|-------|
-| 🌐 **Web** | Read | Zero config | Any URL → clean Markdown ([Jina Reader](https://github.com/jina-ai/reader) ⭐9.8K) |
-| 🐦 **Twitter/X** | Read · Search | Cookie | Cookie unlocks search, timeline, tweet reading, articles ([twitter-cli](https://github.com/public-clis/twitter-cli)) |
-| 📕 **XiaoHongShu** | Read · Search · Comments | OpenCLI / MCP | OpenCLI uses only an existing user-controlled Chrome session; MCP/legacy tools use a manual Cookie-Editor export |
-| 📘 **Facebook** | Search · Profiles · Feed · Groups list | OpenCLI | Desktop only: [OpenCLI](https://github.com/jackwener/opencli) reuses your logged-in Chrome session |
-| 📷 **Instagram** | User search · Profiles · Recent posts · Explore | OpenCLI | Desktop only: [OpenCLI](https://github.com/jackwener/opencli) reuses your logged-in Chrome session |
-| 💼 **LinkedIn** | Jina Reader (public pages) | Full profiles, companies, job search | Tell your Agent "help me set up LinkedIn" |
-| 💻 **V2EX** | Hot topics · Node topics · Topic detail + replies · User profile | Zero config | Public JSON API, no auth required. Great for tech community content |
-| 📈 **Xueqiu (雪球)** | Stock quotes · Search · Hot posts · Hot stocks | Browser cookie | Tell your Agent "help me set up Xueqiu" |
-| 🎙️ **Xiaoyuzhou Podcast** | Transcription | Free API key | Podcast audio → full text transcript via Groq Whisper (free) |
-| 🔍 **Web Search** | Search | Auto-configured | Auto-configured during install, free, no API key ([Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter)) |
-| 📦 **GitHub** | Read · Search | Zero config | [gh CLI](https://cli.github.com) powered. Public repos work immediately. `gh auth login` unlocks Fork, Issue, PR |
-| 📺 **YouTube** | Read · **Search** | Zero config | Subtitles + search across 1800+ video sites ([yt-dlp](https://github.com/yt-dlp/yt-dlp) ⭐148K) |
-| 📺 **Bilibili** | Read · **Search** | Zero config | Search + video detail via [bili-cli](https://github.com/public-clis/bilibili-cli) (no login needed); subtitles via [OpenCLI](https://github.com/jackwener/opencli). yt-dlp is 412-blocked by Bilibili and no longer used here |
-| 📡 **RSS** | Read | Zero config | Any RSS/Atom feed ([feedparser](https://github.com/kurtmckee/feedparser) ⭐2.3K) |
-| 📖 **Reddit** | Search · Read | OpenCLI / Cookie | No zero-config path (anonymous endpoints blocked). Desktop: [OpenCLI](https://github.com/jackwener/opencli) via browser session; or [rdt-cli](https://github.com/public-clis/rdt-cli) + cookie |
-
-> **Setup levels:** Zero config = install and go · Auto-configured = handled during install · mcporter = needs MCP service · Cookie = export from browser · Proxy = $1/month
+`agent-reach channels` is the live source of truth; this table reflects the current release.
+
+| Channel | Level | What it does | Needs |
+|---|---|---|---|
+| github | default | search repos, read a repo/README, read issues and PRs with comments | nothing (higher limits with `gh` or a token) |
+| youtube | default | video info, search, subtitles, speech-to-text | nothing; speech-to-text needs a Groq or OpenAI key |
+| v2ex | default | hot topics, nodes, topics with replies, users | nothing |
+| web | default | web search, page reading (fallback) | nothing |
+| xiaohongshu | optional | search notes, read a note | browser + login |
+| bilibili | optional | search, video info, trending, subtitles | subtitles need a login (QR scan) |
+| reddit | optional | search, read posts with comments, browse a subreddit | browser + login |
+| linkedin | optional | job search | login (needs Node.js and uv) |
+| boss | optional | job and JD search | browser + login (needs git) |
+| xiaoyuzhou | optional | full podcast transcripts | Groq key + ffmpeg |
+| xueqiu | optional | real-time quotes, stock search, hot posts, hot stocks | quotes need nothing; hot posts/stocks need a browser login |
+| twitter | experimental | search tweets, profiles, user tweets, threads | browser + login |
+| facebook | experimental | search, profiles | browser + login |
+| instagram | experimental | user search, profiles, user posts | browser + login |
+
+- **default**: works right after install.
+- **optional**: turn on with `agent-reach add <channel>`; Agent Reach installs the tools it needs into its own folder.
+- **experimental**: works, but the platform fights automation harder and it can break at any time.
+- **browser**: the Agent Reach browser, a separate Chrome window (needs Google Chrome and Node.js). The first time, you add the OpenCLI extension to it; `agent-reach browser setup` walks you through it.
---
## Quick Start
-> ⚠️ **OpenClaw users: enable `exec` permission first**
->
-> Agent Reach relies on the Agent running shell commands (`pip install`, `mcporter`, `twitter`, etc.). If your OpenClaw uses the default `messaging` tool profile, the Agent won't be able to run them. **Enable `exec` before installing:**
->
-> ```bash
-> openclaw config set tools.profile "coding"
-> ```
-> Or set `"tools": { "profile": "coding" }` in `~/.openclaw/openclaw.json`. After changing it, restart the Gateway (`openclaw gateway restart`) and start a new conversation. Other platforms (Claude Code, Cursor, Windsurf, etc.) are not affected.
-
-Copy this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.):
+Send this to your agent:
```
Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
-The Agent installs the Python package, checks your environment, and tells you what's ready. System-level changes require an explicit `--system` flag.
+The agent follows [install.md](install.md):
-> 🔄 **Already installed?** Update in one command:
-> ```
-> Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-> ```
+1. Install the program: `uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip`
+2. Run `agent-reach setup`: checks prerequisites and installs the skill for your agent
+3. Shows you the optional channels; for the ones you pick it runs `agent-reach add <channel>`
+4. For login channels it runs `agent-reach login <channel>` to open the login page, and **you log in yourself**
-> 🛡️ **Safe by default:** `agent-reach install` checks the machine without installing system packages or writing configuration:
-> ```
-> Safely check and install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
-> ```
-> Use `agent-reach install --system` only after explicitly approving system changes.
+> ⚠️ The PyPI package named `agent-reach` is NOT this project. Don't install it from PyPI; use the GitHub URL above.
-<details>
-<summary>Manual install</summary>
+Prefer doing it by hand? Run the commands in [install.md](install.md) yourself.
-```bash
-pip install https://github.com/Panniantong/agent-reach/archive/main.zip
-agent-reach install --env=auto
+```mermaid
+flowchart LR
+ A[Agent] -->|agent-reach channel action| B[Agent Reach]
+ B --> C{try backends in order}
+ C -->|preferred| D[upstream tool 1]
+ C -->|fallback on failure| E[upstream tool 2]
+ D --> F[one JSON envelope]
+ E --> F
+ F --> A
```
-</details>
-
-<details>
-<summary>Install as a Skill (Claude Code / OpenClaw / any agent with Skills support)</summary>
-
-```bash
-npx skills add Panniantong/Agent-Reach@agent-reach
-```
-
-After the Skill is installed, the Agent will auto-detect whether `agent-reach` CLI is available and install it if needed.
-
-> If you explicitly install external tools with `agent-reach install --system`, the skill is registered automatically. The default read-only check leaves existing files unchanged.
->
-> Prefer an English-only skill file? Set an English locale or export `AGENT_REACH_LANG=en`
-> before running `agent-reach install --env=auto --system` or `agent-reach skill --install`.
-> The installed file is always written as `SKILL.md`, so switching languages means rerunning
-> the install command with the new locale and replacing the previously installed skill file.
-</details>
---
## Works Out of the Box
-No configuration needed — just tell your Agent:
+After install these are the commands you'll see (your agent usually runs them for you):
-- "Read this link" → `curl https://r.jina.ai/URL` for any web page
-- "What's this GitHub repo about?" → `gh repo view owner/repo`
-- "What does this video cover?" → `yt-dlp --dump-json URL` for subtitles
-- "Read this tweet" → set `TWITTER_AUTH_TOKEN` / `TWITTER_CT0`, then run `twitter tweet URL`
-- "Subscribe to this RSS" → `feedparser` to parse feeds
-- "Search GitHub for LLM frameworks" → `gh search repos "LLM framework"`
+| Command | What it does |
+|---|---|
+| `agent-reach doctor --text` | status of every channel: not_added / needs_setup / needs_login / unverified / ready / broken |
+| `agent-reach check [channel] --text` | run live tests to confirm a channel works |
+| `agent-reach watch --text` | report only what broke since the last check, and whether an update is out |
+| `agent-reach update` | update the program, its tools and the skill in one go, see [update.md](update.md) |
+| `agent-reach add` / `remove <channel>` | turn an optional channel on / off |
+| `agent-reach login` / `logout <channel>` | log in (you do it) / forget the login |
+| `agent-reach configure <key> [value]` | save `groq-key`, `openai-key`, `proxy`, `github-token` |
-**No commands to remember.** The Agent reads SKILL.md and knows what to call.
+When something fails, `error.code` in the JSON tells the agent what to do next. Every error code and status is explained in [troubleshooting.md](troubleshooting.md).
---
-## Unlock on Demand
+## Design Philosophy
-Don't use it? Don't configure it. Every step is optional.
+### 🔌 Every platform = an ordered backend list (primary + fallbacks)
-### 🍪 Cookies — Free, 2 minutes
+Each action of each channel has an ordered list of backends. `bilibili read` tries bili-cli first and falls back to Bilibili's public API; `web read` tries Jina Reader, then Exa. The `backend` field in the JSON says which one actually answered.
-Tell your Agent "help me configure Twitter cookies" — it'll guide you through a
-manual Cookie-Editor export. Agent Reach saves the values for `doctor` to check
-whether credentials are present; `doctor` does not run `twitter status`.
-Direct `twitter` commands still require `TWITTER_AUTH_TOKEN` and `TWITTER_CT0`
-in their process environment.
+Platforms change and tools break all the time. Switching backends only reorders that list; the way the agent calls Agent Reach stays the same.
-For XiaoHongShu, Agent Reach never logs the user in or reads browser cookies.
-OpenCLI may use only an existing Chrome session explicitly controlled by the
-user. If none exists, do not automate login; use a manual Cookie-Editor export
-with xiaohongshu-mcp or a legacy tool. `agent-reach configure xhs-cookies`
-does not inject cookies into OpenCLI or Chrome.
+### 📌 Pinned versions, private installs
-### 🌐 Proxy — $1/month, restricted networks only
+The tools Agent Reach installs (OpenCLI, bili-cli, boss-agent-cli, mcporter) are pinned to tested versions and live in `~/.agent-reach/tools/`, away from your global environment. `agent-reach update` moves them to the versions tested with the new release.
-Most users need no proxy. If your network blocks Reddit/Twitter (e.g. mainland China) get one ([Webshare](https://webshare.io) recommended, $1/month) and send the address to your Agent — it saves it and exports HTTP(S)_PROXY when calling those tools.
+### 🩺 Working means live-tested
-> Reddit needs a logged-in session either way — OpenCLI rides your browser session, or rdt-cli after `rdt login`. Bilibili works via bili-cli without a proxy.
+`doctor` only checks offline; `check` makes a real request to the platform. A channel is marked `ready` only after it passes a live check.
----
+### One output shape
-## Status at a Glance
+Every agent command prints one JSON object:
+```json
+{"schema_version": 1, "ok": true, "channel": "v2ex", "action": "hot", "backend": "v2ex-api",
+ "items": [{"title": "...", "url": "...", "text": "..."}], "meta": {}, "error": null}
```
-$ agent-reach doctor
-
-👁️ Agent Reach Status
-========================================
-✅ Ready to use:
- ✅ GitHub repos and code — public repos readable and searchable
- ✅ YouTube video subtitles — yt-dlp
- ✅ Bilibili search & video detail — bili-cli (subtitles via OpenCLI)
- ✅ RSS/Atom feeds — feedparser
- ✅ Web pages (any URL) — Jina Reader API
-
-🔍 Search (free Exa key to unlock):
- ⬜ Web semantic search — sign up at exa.ai for free key
-
-🔧 Configurable:
- ⚠️ Twitter/X — doctor checks only that explicit credentials exist; direct CLI still needs its environment variables
- ⬜ Reddit posts and comments — needs login: rdt-cli after `rdt login`, or OpenCLI browser session
- ⬜ XiaoHongShu notes — OpenCLI needs an existing user-controlled session; otherwise use Cookie-Editor with MCP/legacy tools
- ⬜ Facebook / Instagram — desktop: OpenCLI browser session
-
-Status: 6/9 channels available
-```
+On failure `ok` is `false` and `error` holds a `code` (`NEED_SETUP` / `NEED_LOGIN` / `UPSTREAM_BROKEN` / `TIMEOUT` / `RATE_LIMITED` / `NOT_FOUND` / `BAD_INPUT`), a `message`, and a `hint` for the agent.
---
-## Design Philosophy
+## Security
-**Agent Reach is a capability layer, not yet another tool.**
+- **Everything lives under `~/.agent-reach/`**: `config.yaml` (keys and proxy), `state.json`, `tools/` (private tool installs), `sessions/` (logins of CLI tools), `browser/` (the dedicated browser profile), `mcporter.json`.
+- **Agent Reach never logs in for you and never reads your own browser's cookies.** For login channels you log in yourself, in the Agent Reach browser or in the tool's own login flow (e.g. Bilibili QR scan).
+- **The Agent Reach browser's debugging port listens on loopback only** (127.0.0.1:9222), but any local process can use it to control that browser. Close the window when you're not using it.
+- **Use a secondary account for login channels.** Platforms may restrict accounts used for automated access.
+- **Don't paste API keys into chat**: run `agent-reach configure groq-key` in your own terminal; input is hidden.
-It sits one level above any specific implementation — it handles **selection, installation, health checks, and routing**, not the reading itself. Reading is done by your Agent calling upstream tools directly; there is no wrapper layer.
+### 🗑️ Uninstall
-Every time you spin up a new Agent, you spend time finding tools, installing deps, and debugging configs — what reads Twitter? How do you log into Reddit? What replaces a discontinued XiaoHongShu CLI? Every time, you re-do the same work. Agent Reach does one simple thing: **the most reliable access path for each platform, chosen, installed, and health-checked for you. Access paths come and go (in March 2026 a batch of single-platform CLIs went unmaintained — we re-routed), so you don't have to care.**
-
-### 🔌 Every platform = an ordered backend list (primary + fallbacks)
-
-Switching access paths means reordering the list, not rewriting code. `agent-reach doctor` tells you **which backend each platform is currently using**.
-
-```
-channels/
-├── web.py → Jina Reader
-├── twitter.py → twitter-cli ▸ OpenCLI ▸ bird
-├── youtube.py → yt-dlp
-├── github.py → gh CLI
-├── bilibili.py → bili-cli ▸ OpenCLI ▸ search API (yt-dlp retired, 412-blocked)
-├── reddit.py → OpenCLI ▸ rdt-cli (no zero-config path, login required)
-├── facebook.py → OpenCLI (desktop browser session)
-├── instagram.py → OpenCLI (desktop browser session)
-├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
-├── linkedin.py → linkedin-mcp ▸ Jina Reader
-├── rss.py → feedparser
-├── exa_search.py → Exa via mcporter
-└── __init__.py → Channel registry (for doctor checks)
+```bash
+agent-reach uninstall --dry-run # see what would be removed
+agent-reach uninstall # remove the tools, logins, config and skill Agent Reach installed
```
-Each channel file **actually probes** its candidate backends in order (not just checking that a command exists) — the first fully working one becomes the active backend, and broken ones come with a fix prescription. The actual reading and searching is done by the Agent calling the upstream tools directly.
-
-### Current Tool Choices
-
-| Scenario | Primary | Fallback | Why |
-|----------|---------|----------|-----|
-| Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | — | Free, no API key needed |
-| Read tweets | [twitter-cli](https://github.com/public-clis/twitter-cli) | [OpenCLI](https://github.com/jackwener/opencli) | Reliable search in real-world tests; OpenCLI falls back on your browser session |
-| Reddit | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [rdt-cli](https://github.com/public-clis/rdt-cli) | Anonymous endpoints blocked, official API gated — logged-in sessions are the only route left |
-| Facebook | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | — | Graph/Groups API access is heavily restricted; browser sessions are the practical route |
-| Instagram | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | Official Graph API (Business/Creator + review) | Instaloader-style paths are unstable; OpenCLI reuses the real browser session |
-| YouTube subtitles + search | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | 154K stars, still the best for YouTube (no longer used for Bilibili) |
-| Bilibili | [bili-cli](https://github.com/public-clis/bilibili-cli) | OpenCLI ▸ search API | yt-dlp is 412-blocked by Bilibili (verified June 2026); bili-cli searches and reads without login |
-| Search the web | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | — | AI semantic search, MCP integration, no API key |
-| GitHub | [gh CLI](https://cli.github.com) | — | Official tool, full API after auth |
-| Read RSS | [feedparser](https://github.com/kurtmckee/feedparser) | — | Python ecosystem standard |
-| XiaoHongShu | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) (server) ▸ xhs-cli | OpenCLI uses only an existing user-controlled session; other backends use a manual Cookie-Editor export |
-| LinkedIn | [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server) | Jina Reader | MCP server, browser automation |
-| Xiaoyuzhou Podcast | `transcribe.sh` | — | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh <URL>` |
-
-> 📌 These are the *current* choices, re-verified regularly on real machines. When a path dies we switch to the next — `agent-reach doctor` always tells you which one is active.
+Close the Agent Reach browser first. The output ends with the command that removes the program itself (e.g. `uv tool uninstall agent-reach`).
---
## Credits
-[twitter-cli](https://github.com/public-clis/twitter-cli) · [rdt-cli](https://github.com/public-clis/rdt-cli) · [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [feedparser](https://github.com/kurtmckee/feedparser) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
+[OpenCLI](https://github.com/jackwener/opencli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [boss-agent-cli](https://github.com/can4hou6joeng4/boss-agent-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
## Contact
diff --git a/docs/cookie-export.md b/docs/cookie-export.md
deleted file mode 100644
index 5f7fb98c..00000000
--- a/docs/cookie-export.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Cookie Export Guide — For Server Users
-
-Your Agent is on a server and can't access your browser directly.
-Here's how to export cookies from your local computer — **fastest method first**.
-
-## Method 1: Cookie-Editor Extension (Recommended — 30 seconds per site)
-
-1. Install **Cookie-Editor** for Chrome: https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm
- (Also available for Firefox, Edge)
-
-2. Go to the website (e.g. https://x.com) and make sure you're logged in
-
-3. Click the Cookie-Editor icon in your toolbar
-
-4. Click **Export** → **Header String**
-
-5. Paste the result to your Agent
-
-That's it! Your Agent will run:
-```bash
-agent-reach configure twitter-cookies
-agent-reach configure xhs-cookies
-```
-
-Both commands use a hidden prompt. For non-interactive automation, send the
-same exported value through stdin and add `--stdin`; never place cookies in
-the process arguments.
-
-Twitter values saved by Agent Reach are used by `agent-reach doctor` only to
-check whether explicit credentials are present. Doctor does not run
-`twitter status`. Direct `twitter` commands still require
-`TWITTER_AUTH_TOKEN` and `TWITTER_CT0` in their process environment.
-
-This XiaoHongShu export is for xiaohongshu-mcp or a legacy tool.
-`agent-reach configure xhs-cookies` does not inject cookies into OpenCLI or
-Chrome. OpenCLI may use only an existing Chrome session explicitly controlled
-by the user. Agent Reach never logs the user in or reads XiaoHongShu browser
-cookies.
-
-### Sites to export:
-
-| Site | URL to visit | What to tell Agent |
-|------|-------------|-------------------|
-| Twitter/X | https://x.com | "Here are my Twitter cookies: [paste]" |
-| XiaoHongShu | https://www.xiaohongshu.com | "Here are my XHS cookies: [paste]" |
-| Bilibili | https://www.bilibili.com | "Here are my Bilibili cookies: [paste]" |
-
-## Method 2: Manual (No extension needed)
-
-1. Open the site in Chrome, make sure you're logged in
-2. Press **F12** (or right-click → Inspect)
-3. Click the **Network** tab
-4. Refresh the page (F5)
-5. Click any request in the list
-6. In the right panel, scroll to **Request Headers**
-7. Find the line starting with `Cookie:`
-8. Copy the entire value after `Cookie: `
-9. Paste to your Agent
diff --git a/docs/install.md b/docs/install.md
index 91ca53f8..6b7ed929 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,425 +1,80 @@
-# Agent Reach — Installation Guide
+# Install Agent Reach
-## For Humans
+Instructions for the AI agent doing the install. Run the commands yourself; ask the user only where a step says so. Every `agent-reach` command prints one JSON object; read `ok`, `result` and `error.hint`.
-Copy this to your AI Agent:
+> ⚠️ The PyPI package named `agent-reach` is NOT this project. Never install it from PyPI; only use the GitHub URL below.
-```
-帮我安装 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
-```
-
-> 🛡️ **Safe by default:** `agent-reach install` only checks the machine and lists missing dependencies:
-> ```
-> 帮我安全检查并安装 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
-> ```
-> Only use `--system` after the user explicitly approves system-level installs and configuration writes.
-
----
-
-## For AI Agents
-
-### Goal
-
-Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (OpenCLI, twitter-cli, bili-cli, rdt-cli, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is the selector, installer, health checker and router, never a wrapper.
-
-### ⚠️ Boundaries
-
-When fixing issues, stay within these limits:
-
-- **DO NOT** run commands with `sudo` unless the user explicitly approved
-- **DO NOT** modify system files outside `~/.agent-reach/`
-- **DO NOT** install packages not listed in this guide
-- **DO NOT** disable firewalls, security settings, or system protections
-- **DO NOT** clone repos, create files, or run commands inside the agent workspace / working directory
-- If something requires elevated permissions, **tell the user** what's needed and let them decide
-
-### 📁 Directory Rules
-
-All Agent Reach files go in dedicated directories — **never in the agent workspace**:
-
-| Purpose | Directory | Example |
-|---------|-----------|---------|
-| Config & tokens | `~/.agent-reach/` | `~/.agent-reach/config.json` |
-| Upstream tool repos | `~/.agent-reach/tools/` | `~/.agent-reach/tools/xiaoyuzhou/` |
-| Temporary files | `/tmp/` | `/tmp/yt-dlp-output/` |
-| Skills | `~/.openclaw/skills/agent-reach/` | SKILL.md |
-
-**Why?** If you clone repos or create files in the workspace, it pollutes the user's project directory and can break their agent over time. Keep the workspace clean.
-
-### Step 1: Install the basics
+## 1. Install the program
-```bash
-# 推荐:pipx(最省心)
-pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
-agent-reach install --env=auto # Read-only check (default)
-# After the user explicitly approves system changes:
-agent-reach install --env=auto --system
-
-# 如果你的 Python 来自 Homebrew / 遇到 PEP 668(externally-managed-environment)
-# 用虚拟环境安装:
-python3 -m venv ~/.agent-reach-venv
-source ~/.agent-reach-venv/bin/activate
-pip install https://github.com/Panniantong/agent-reach/archive/main.zip
-agent-reach install --env=auto # Read-only check (default)
-# After the user explicitly approves system changes:
-agent-reach install --env=auto --system
-```
-
-> 💡 **Windows / Microsoft Store Python alias?**
-> 如果 `python3 --version` 打开 Microsoft Store,或 `where python3` 指向
-> `...\AppData\Local\Microsoft\WindowsApps\python3.exe`,说明 `python3` 是 Windows
-> 的 Store alias,不是可用的 Python 安装。请改用 Python Launcher `py -3`,或实际安装目录里的 `python.exe`。
->
-> PowerShell 示例:
-> ```powershell
-> py -3 -m venv $env:USERPROFILE\.agent-reach-venv
-> $env:USERPROFILE\.agent-reach-venv\Scripts\Activate.ps1
-> python -m pip install https://github.com/Panniantong/agent-reach/archive/main.zip
-> agent-reach install --env=auto
-> ```
-
-The default command checks core infrastructure (gh CLI, Node.js, mcporter, Exa search, yt-dlp config) without changing the host. With explicit `--system` approval it installs/configures the missing pieces and activates these zero-config channels:
-
-- Web (Jina Reader), YouTube, GitHub, RSS, Exa Search, V2EX, Bilibili (basic)
-
-> 💡 **macOS / Homebrew Python 提示 `externally-managed-environment`?**
-> 这是 PEP 668 保护,不是 Agent Reach 本身的问题。优先用 `pipx install ...`,或先创建 `venv` 再安装。
-
-**Install modes:**
+Already installed? Run `agent-reach update` instead and stop here (see [update.md](update.md)).
```bash
-agent-reach install --env=auto # Check only; safe default
-agent-reach install --env=auto --safe # Same check-only behavior (compatibility)
-agent-reach install --env=auto --system # Explicitly allow external/system installs
-agent-reach install --env=auto --dry-run # Preview what --system would do
+uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip
```
-### Step 2: Ask the user which optional channels they want
-
-After installing the basics, **ask the user** which additional channels they need. Present this list:
-
-> 基础渠道装好了!你现在可以让我搜网页、看 YouTube、读 GitHub 等。
->
-> 还有这些可选渠道,你需要哪些?
->
-> - 🌟 **OpenCLI**(桌面推荐)— 一次安装即可提供 Reddit/Facebook/Instagram/B站字幕/Twitter 备选,并作为小红书桌面后端;小红书只使用用户已有且明确控制的 Chrome 会话
-> - 🐦 **Twitter/X** — 搜推文、看时间线(需要登录 Cookie)
-> - 📈 **雪球** — 股票行情、热门帖子(需要登录 Cookie)
-> - 🎙️ **小宇宙播客** — 音频转文字(需要免费 Groq Key)
-> - 📕 **小红书** — 搜索、阅读、评论(OpenCLI 用已有会话;MCP/存量工具用 Cookie-Editor)
-> - 📖 **Reddit** — 搜索和阅读帖子(必须登录态:桌面 OpenCLI 或 rdt-cli + Cookie)
-> - 📘 **Facebook** — 搜索、主页、Feed、群组列表(桌面走 OpenCLI,复用 Chrome 登录态)
-> - 📷 **Instagram** — 用户搜索、Profile、用户最近帖子、Explore(桌面走 OpenCLI,复用 Chrome 登录态)
-> - 📺 **B站完整版** — 热门、排行、搜索、视频详情(bili-cli,无需登录)
-> - 💼 **LinkedIn** — Profile、职位搜索
-> - 🎯 **Boss直聘** — 搜索岗位 + JD 全文(本地专用 Chrome;用户手动登录)
->
-> 告诉我你要哪些,比如"帮我装小红书和 Twitter"、"帮我装 Facebook 和 Instagram"。或者说"全部装"。
-
-Based on the user's choice, run:
+No `uv`? Use pipx with the same URL:
```bash
-agent-reach install --env=auto --system --channels=opencli,xiaohongshu # Desktop user chose XHS
-agent-reach install --env=auto --system --channels=facebook,instagram # Desktop Meta channels
-agent-reach install --env=local --system --channels=boss # Desktop Boss直聘
-agent-reach install --env=auto --system --channels=all # User approved everything
+pipx install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip
```
-Supported channel names: `opencli`, `twitter`, `xiaoyuzhou`, `xueqiu`, `xiaohongshu`, `reddit`, `facebook`, `instagram`, `bilibili`, `linkedin`, `boss`, `all`
-
-### Step 3: Fix what's broken
-
-Run `agent-reach doctor` and check the output.
-
-Try to get as many channels to ✅ as possible. If something failed during install or shows as ❌/⚠️ in doctor, diagnose the problem and try to fix it — but stay within the boundaries above. If a fix requires elevated permissions or system changes, ask the user first.
-
-Only ask the user when you genuinely need their input (credentials, permissions, etc.).
+If `agent-reach` is not found afterwards, run `uv tool update-shell` (or `pipx ensurepath`) and open a new shell.
-### Step 3: Configure things that need user input
-
-Some channels need credentials only the user can provide. Based on the doctor output, ask for what's missing:
-
-> 🔒 **Security tip:** For platforms that need cookies or browser sessions (Twitter, XiaoHongShu, Reddit, Facebook, Instagram, Boss直聘), we recommend using a **dedicated/secondary account** rather than your main account. Cookie/browser-session auth carries two risks:
-> 1. **Account ban** — platforms may detect non-browser API calls and restrict or ban the account
-> 2. **Credential exposure** — cookies grant full account access; using a secondary account limits the blast radius if credentials are ever compromised
-
-> 🍪 **Cookie / 登录态:**
->
-> 传统 CLI 需要 Cookie 的平台(Twitter、雪球等),**优先使用 Cookie-Editor 导入**,这是最简单最可靠的方式:
-> 1. 用户在自己的浏览器上登录对应平台
-> 2. 安装 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) Chrome 插件
-> 3. 点击插件 → Export → Header String
-> 4. 把导出的字符串发给 Agent
->
-> Twitter 只接受用户通过 Cookie-Editor 明确导出的内容。Agent Reach 不替用户执行小红书登录,也不读取小红书浏览器 Cookie;小红书 OpenCLI 只使用用户已有且明确控制的 Chrome 会话。没有现成会话时,改用 Cookie-Editor 导出后配置 xiaohongshu-mcp / 存量工具。雪球、Bilibili 可按平台显式导入,例如 `agent-reach configure --from-browser chrome --platform xueqiu`;命令不会扫描或保存其他平台。
-
-**Twitter search & posting:**
-> "To unlock Twitter search, I need your Twitter cookies. Install the Cookie-Editor Chrome extension, go to x.com/twitter.com, click the extension → Export → Header String, and paste it to me."
+## 2. Set up
```bash
-agent-reach configure twitter-cookies
+agent-reach setup
```
-这会把 `twitter_auth_token` 和 `twitter_ct0` 保存给 Agent Reach 自己的
-`doctor` 配置检查。`doctor` 不会实时执行上游 `twitter status`,也不会修改
-当前 Shell。直接运行 `twitter search/read/...` 前,必须在该进程环境中显式设置:
+This checks prerequisites, installs the Agent Reach skill into your skill folder, and keeps keys from an older install. The default channels (github, youtube, v2ex, web) work now.
-```bash
-export TWITTER_AUTH_TOKEN="..."
-export TWITTER_CT0="..."
-twitter search "query" -n 10
-```
+If `result.prerequisites` shows something missing (node, git, chrome, ffmpeg, uv), tell the user the `hint`; only the channels that need it are affected.
-> **代理说明(中国大陆等需要翻墙的网络环境):**
->
-> twitter-cli 和 rdt-cli 使用 Python,在需要代理的网络环境下可通过环境变量配置代理。
->
-> **你(Agent)需要做的:**
-> 1. 确认用户配了代理:`agent-reach configure proxy`(隐藏输入)
-> 2. 设置环境变量:`export HTTP_PROXY="..." HTTPS_PROXY="..."`
-> 3. Agent Reach 会自动处理剩下的,不需要用户做额外操作
->
-> 如果用户报告 "fetch failed",参考 [troubleshooting.md](troubleshooting.md)
+## 3. Let the user pick optional channels
-**Reddit (login is mandatory — no zero-config path):**
-> Reddit 的匿名接口已被封、官方 API 需人工审批。桌面用户首选 OpenCLI(浏览器里登录过 reddit.com 即可用);服务器/存量用户用 rdt-cli:
+Show the user `result.optional_channels` from the setup output, with what each `needs`. Mention that `experimental` channels can break at any time. Then, for each channel they pick:
```bash
-# PyPI 落后,从 GitHub 装(与代码内 _RDT_GIT_SOURCE 同一钉定版本)
-pipx install 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66'
-rdt login # 自动提取浏览器 Cookie;服务器无浏览器时按 doctor 提示手动写 Cookie
+agent-reach add <channel>
```
-> 中国大陆访问 Reddit 需要代理;服务器 IP 被风控时可配住宅代理(如 https://webshare.io,约 $1/月):
-> ```bash
-> agent-reach configure proxy
-> ```
+Follow the `result.next` list it returns.
-**XiaoHongShu / 小红书(多后端,按环境选):**
+## 4. Logins and keys (the user does these)
-> **认证边界:** Agent Reach 不替用户执行小红书登录,也不读取浏览器
-> Cookie。OpenCLI 只使用用户已经存在且明确控制的 Chrome 会话;
-> `agent-reach configure xhs-cookies` 不会把 Cookie 注入 OpenCLI 或 Chrome。
-> 如果没有现成会话,不要自动登录;改用 Cookie-Editor 手工导出后配置
-> xiaohongshu-mcp 或存量工具:
->
-> ```bash
-> agent-reach configure xhs-cookies
-> ```
->
-> 该显式命令会保存/导入用户提供的 xiaohongshu.com 同域 Cookie 集;请先确认
-> Cookie 名称和范围。非 xiaohongshu.com 域 Cookie 会被忽略。
->
-> **桌面电脑(推荐 OpenCLI):**
+Never log in for the user, never ask for their password, never read their browser's cookies.
-```bash
-agent-reach install --system --channels opencli
-```
-
-> 装完后引导用户做唯一一步手动操作(Chrome 安全限制,无法代劳):
-> 1. 打开 https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
-> 2. 点「添加至 Chrome」
-> 3. 运行 `opencli doctor` 验证(显示 Extension: connected 即成功)
->
-> AUTH_REQUIRED 且用户没有现成会话时,不要替用户自动登录;改走下面的
-> xiaohongshu-mcp / 存量工具 Cookie-Editor 路线。
->
-> **服务器 / 无桌面环境(xiaohongshu-mcp):**
-> 1. 从 https://github.com/xpzouying/xiaohongshu-mcp/releases 下载对应平台 binary 到 `~/.agent-reach/tools/`
-> 2. 启动服务(首次运行会自动下载约 150MB 无头浏览器,耐心等完成)
-> 3. 按上面的 Cookie-Editor 流程手工导入 Cookie
-> 4. 接入:`mcporter config add xiaohongshu http://localhost:18060/mcp --scope home`
-> 5. 调用时务必带 `--timeout 120000`
->
-> **存量用户(xhs-cli):** 已装好的 xhs-cli 继续作为备选后端工作
-> (上游 2026-03 起停更,不推荐新装);认证仍使用上面的 Cookie-Editor
-> 手工导出流程。
-
-**Facebook / Instagram(桌面 OpenCLI):**
-> 这两个平台走 OpenCLI:复用用户自己的 Chrome 登录态,不保存账号密码,不走 Meta Graph API 审批流。服务器/无桌面环境不推荐支持。
+**Browser channels** (xiaohongshu, reddit, twitter, facebook, instagram, boss, xueqiu): once, first run
```bash
-agent-reach install --system --channels facebook,instagram
+agent-reach browser setup
```
-> 装完后:
-> 1. 确认 Chrome 已安装 OpenCLI 扩展并通过 `opencli doctor`
-> 2. 在 Chrome 里登录 facebook.com / instagram.com
-> 3. Agent 直接调用:
-> ```bash
-> opencli facebook search "query" -f yaml
-> opencli facebook profile zuck -f yaml
-> opencli facebook groups -f yaml
-> opencli instagram search "query" -f yaml # 用户搜索
-> opencli instagram profile nasa -f yaml
-> opencli instagram user nasa -f yaml # 指定用户最近帖子
-> ```
->
-> Facebook Groups 当前只承诺读取用户登录后可见的群组列表/最近动态,不承诺任意群帖子和评论 API。Instagram 的 search 是用户搜索,不是全站帖子关键词搜索;若提示 429/登录错误,先让用户在 Chrome 里重新登录并降低频率。
-
-**雪球 / Xueqiu (股票行情 + 热门帖子):**
-> "雪球需要登录后的 Cookie。请先在 Chrome 里登录 xueqiu.com,然后运行:"
+It opens the Agent Reach browser (a separate Chrome window) at the OpenCLI extension page. Ask the user to click "Add to Chrome" there, then run `agent-reach browser setup` again until `ok` is true. Then for each channel:
```bash
-agent-reach configure --from-browser chrome --platform xueqiu
+agent-reach login <channel>
```
-> 只会读取并保存雪球需要的最小 Cookie;不会顺带读取其他平台。
+The login page opens in the Agent Reach browser; the user logs in. If the output says to, run `agent-reach login <channel> --sync` after they are done.
-**小宇宙播客 / Xiaoyuzhou Podcast (Groq Whisper):**
-> "小宇宙播客转文字已默认安装,只需要一个免费的 Groq API Key。"
+**bilibili / linkedin**: `agent-reach login <channel>` runs the tool's own login (QR code or a browser window). Run it where the user can see the output.
-脚本已随 Agent Reach 自动安装,用户只需提供 Key:
+**Keys** (xiaoyuzhou, youtube transcribe): ask the user to get a free key at https://console.groq.com and run this in their own terminal (hidden input):
```bash
agent-reach configure groq-key
```
-> **获取 Groq API Key(免费、无需信用卡、30 秒搞定):**
-> 1. 打开 https://console.groq.com
-> 2. 用 Google/GitHub 账号登录(或注册)
-> 3. 左侧菜单 → API Keys → Create API Key
-> 4. 复制 Key(以 `gsk_` 开头),发给 Agent 即可
->
-> **使用方式:**
-> 用户发一个小宇宙链接给 Agent,Agent 自动调用:
-> ```bash
-> bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh https://www.xiaoyuzhoufm.com/episode/xxxxx
-> ```
->
-> 自动下载音频 → 转码切片 → Groq Whisper 转录 → 输出完整中文文字稿。
->
-> **免费额度和限制:**
-> - 每小时约 2 小时音频(7200 秒),超出后等 15 分钟自动恢复
-> - 日常听几期播客完全够用
-> - 转录质量高(Whisper large-v3),但不区分说话人
-> - 2 小时以上的播客建议分批处理
-
-**LinkedIn (可选 — mcp-server-linkedin):**
-> "LinkedIn 基本内容可通过 Jina Reader 读取。完整功能(Profile 详情、人才与职位搜索)需要 mcp-server-linkedin。"
-
-> **配置方式(推荐 stdio):**
-> 先按官方说明安装 `uv`(会同时提供 `uvx`):
-> https://docs.astral.sh/uv/getting-started/installation/
->
-> ```bash
-> mcporter config add linkedin --command uvx --arg mcp-server-linkedin@latest --env UV_HTTP_TIMEOUT=300 --scope home
-> ```
->
-> `uvx` 会按需获取并启动最新版服务,无需另装 Python 包或常驻 HTTP 服务。
->
-> **首次登录(需要浏览器界面):**
-> ```bash
-> uvx mcp-server-linkedin@latest --login
-> ```
-> 浏览器弹出后手动登录 LinkedIn;登录态会保存到 `~/.linkedin-mcp/profile/`。无桌面的服务器需在 VNC 等可见桌面中运行同一条登录命令。
->
-> 详见 https://github.com/stickerdaniel/linkedin-mcp-server
-
-**Boss直聘(桌面专用 — boss-agent-cli + CDP):**
-
-当用户说“帮我配 Boss直聘”时,Agent 完成可自动完成的部分,只把网站登录留给用户:
+If you must run it yourself, pipe the value: `agent-reach configure groq-key --stdin`.
-1. 先说明将安装一个上游 CLI、启动独立 Chrome 配置目录,并请求系统安装授权。
-2. 用户同意后运行:
- ```bash
- agent-reach install --env=local --system --channels=boss
- ```
-3. 按操作系统启动只绑定本机回环地址的专用 Chrome:
- ```bash
- # macOS
- open -na "Google Chrome" --args --remote-debugging-address=127.0.0.1 \
- --remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
- "https://www.zhipin.com/web/geek/job"
+Suggest a secondary account for login channels.
- # Linux
- google-chrome --remote-debugging-address=127.0.0.1 \
- --remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
- "https://www.zhipin.com/web/geek/job"
- ```
- Windows PowerShell:
- ```powershell
- Start-Process chrome.exe -ArgumentList '--remote-debugging-address=127.0.0.1','--remote-debugging-port=9222',"--user-data-dir=$env:USERPROFILE\.boss-chrome-profile",'https://www.zhipin.com/web/geek/job'
- ```
-4. 暂停,让**用户肉眼确认**窗口内的登录状态(右上角有头像);未登录则让**用户手动
- 登录**、扫码或处理滑块。Agent 不索取账号密码、不代替登录,也不要用 `boss status`
- 代替这一步——它只校验本地 `session.enc`,不代表这个 Chrome 已登录。
-5. 用户确认登录完成后运行:
- ```bash
- boss --cdp-url http://localhost:9222 login --cdp
- agent-reach doctor # 看 boss 行 message 里的浏览器 wt2 cookie 探测结果
- ```
+## 5. Verify
-> 安全边界:任何能访问调试端口 9222 的本机进程都能完全控制这个 Chrome。
-> 必须使用 `--remote-debugging-address=127.0.0.1`,不得暴露到局域网或公网;使用
-> 独立 profile 并长期复用,不要每次删除或新建,也不要默认切换到日常主 Chrome;
-> 不使用时关闭专用 Chrome。Boss 不支持服务器/无桌面环境。搜索命令必须带
-> `--browser-source existing-browser --cdp-url http://localhost:9222`。
->
-> 依赖:boss-agent-cli 后继拆分 PR #403–#407 已合并入上游 master,安装器锁定上游
-> 固定提交
-> `4c991b77086a203173bf08a4cb64a23af6514fe6`,不跟随会移动的 branch。该提交包含
-> `browser_source="existing-browser"`(严格 CDP)、`JobItem.lid` 和 `job_card_browser()`。上游发布正式版后,
-> Agent Reach 应改用版本约束。
-
-### Step 4: Final check
-
-Run `agent-reach doctor` one final time and report the results to your user.
-
-### Step 5: Set up daily monitoring (OpenClaw only)
-
-If you are running inside **OpenClaw**, ask your user:
-
-> "Agent Reach 安装好了。要不要我设一个每天自动检查的任务?它会帮你盯着这些渠道是否正常、有没有新版本。有问题才会通知你,没问题不打扰。"
-
-If the user agrees, create a **cron job** (daily, `sessionTarget: "isolated"`, `delivery: "announce"`) with this task:
-
-```
-运行 agent-reach watch 命令。
-如果输出包含"全部正常",不需要通知用户,静默结束。
-如果输出包含问题(❌ ⚠️)或新版本(🆕),把完整报告发给用户,并建议修复方案。
-如果有新版本可用,问用户是否要升级(把这句话发给用户的 Agent 即可完整更新:帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md)。
+```bash
+agent-reach check --text
+agent-reach doctor --text
```
-If the user wants a different agent to handle it, let them choose.
-
----
-
-## Quick Reference
-
-| Command | What it does |
-|---------|-------------|
-| `agent-reach install --env=auto` | Read-only dependency and channel check (default) |
-| `agent-reach install --env=auto --system` | Explicitly install/configure core external tools |
-| `agent-reach install --env=auto --system --channels=twitter,xiaohongshu` | Install approved optional channels |
-| `agent-reach install --env=local --system --channels=boss` | Install the desktop Boss直聘 strict-CDP backend |
-| `agent-reach install --env=auto --system --channels=all` | Install everything after explicit approval |
-| `agent-reach install --env=auto --safe` | Compatibility alias for the safe default |
-| `agent-reach install --env=auto --dry-run` | Preview what would be done |
-| `agent-reach doctor` | Show channel status |
-| `agent-reach watch` | Quick health + update check (for scheduled tasks) |
-| `agent-reach check-update` | Check for new versions |
-| `agent-reach configure twitter-cookies` | 通过隐藏输入保存 Twitter Cookie;直接调用仍需显式环境变量 |
-| `agent-reach configure proxy` | 通过隐藏输入保存代理地址;不是自动解锁开关 |
-| `agent-reach configure groq-key` | 通过隐藏输入配置小宇宙转录 Key |
-
-After installation, use upstream tools directly. See SKILL.md for the full command reference:
-
-| Platform | Upstream Tool | Example |
-|----------|--------------|---------|
-| Twitter/X | `twitter`(备选 `opencli`) | 设置 `TWITTER_AUTH_TOKEN` / `TWITTER_CT0` 后运行 `twitter search "query" -n 10` |
-| YouTube | `yt-dlp` | `yt-dlp --dump-json URL` |
-| Bilibili | `bili`(字幕走 `opencli`) | `bili search "query" --type video` / `opencli bilibili subtitle BVxxx` |
-| Reddit | `opencli`(备选 `rdt`) | `opencli reddit search "query" -f yaml` / `rdt read POST_ID` |
-| Facebook | `opencli` | `opencli facebook search "query" -f yaml` |
-| Instagram | `opencli` | `opencli instagram user nasa -f yaml` |
-| GitHub | `gh` | `gh search repos "query"` |
-| Web | `curl` + Jina | `curl -s "https://r.jina.ai/URL"` |
-| Exa Search | `mcporter` | `mcporter call exa.web_search_exa query="..." numResults=5` |
-| 小红书 | `opencli`(服务器 `mcporter`) | `opencli xiaohongshu search "query" -f yaml` |
-| 小宇宙播客 | `transcribe.sh` | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh <URL>` |
-| LinkedIn | `mcporter` | `mcporter call linkedin.get_person_profile linkedin_username="..."` |
-| Boss直聘 | `boss` / Python public API | `agent-reach doctor`(浏览器 wt2 探测;`boss status` 只反映本地 session.enc);搜索和 JD 见 `references/career.md` |
-| RSS | `feedparser` | `python3 -c "import feedparser; ..."` |
-
-> 多后端平台以 `agent-reach doctor --json` 的 `active_backend` 为准。
+Report to the user what is `ready` and what still needs something. Fixes for each status and error code: [troubleshooting.md](troubleshooting.md).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index e89bb474..28cff452 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,105 +1,63 @@
-# 常见问题排查
+# Troubleshooting
-## 雪球 / Xueqiu: API 返回 400
-
-**症状:** `agent-reach doctor` 显示雪球 ⚠️,报 `HTTP Error 400`
-
-**原因:** 雪球 API 需要登录 Cookie,无法通过匿名访问获取。
-
-**解决方案:** 在 Chrome 里登录 xueqiu.com,然后运行:
+Start with:
```bash
-agent-reach configure --from-browser chrome --platform xueqiu
+agent-reach doctor --text # offline status of every channel
+agent-reach check <channel> --text # live test of one channel
```
-再次运行 `agent-reach doctor` 确认恢复 ✅。Cookie 过期后重新运行即可。
-
----
-
-## Boss直聘: `boss status` 说已登录,但搜索报 `AUTH_EXPIRED`
-
-**症状:** `boss status` / `status --live` 返回 `logged_in: true`(甚至带用户名),
-但 `boss ... search` 立刻报 `{"code": "AUTH_EXPIRED", "message": "用户未登录"}`。
-专用 Chrome 可能同时停在带 `_security_check` 的 URL 上,看起来像反爬滑块。
-
-**原因:** Boss 有两个登录态存储,认证的是不同通道:
-
-| 存储 | 谁在用 |
-|---|---|
-| `~/.boss-agent/auth/session.enc` | `boss status` / `status --live`;httpx 通道的低危操作(`detail` / `cities` / `job_card_httpx`)。CDP 搜索也会读它(读不到直接报「未登录」),但复用真 Chrome context 时它的 cookie 从未真正生效 |
-| `~/.boss-chrome-profile` 内的浏览器 cookie | `existing-browser` 严格 CDP 模式下 search / greet 等高危操作实际携带的凭据 |
-
-`boss status` 只校验本地 session.enc。本地存着几天前的旧凭据、而专用 Chrome
-profile 本身没登录时,它依然报 `logged_in: true`——这不是登录态有效的证明。
-同时 `_security_check` 页面是反爬挑战,**已登录也会出现**,不能用它判断登录态;
-两者叠加很容易把「浏览器未登录」误判成「卡在滑块」。
-
-> 两个存储都不要删。session.enc 缺失会让 CDP 搜索在连上浏览器之前就失败;
-> 需要刷新它时跑 `login --cdp`,不要手工删文件。
-
-**判定顺序:**
-
-1. `AUTH_EXPIRED` 是 ground truth——出现即浏览器未登录,不管 `boss status` 说什么;
-2. `agent-reach doctor` 的 boss 行会直接探测浏览器内有无 `wt2` cookie,以它为准;
-3. `boss status` 仅作参考;页面 URL 完全不作为判据。
+## Error codes
-**解决方案:** 在专用 Chrome 窗口里肉眼确认并手动登录 zhipin.com,然后同步登录态:
+Every failed command returns `ok: false` and an `error` with `code`, `message` and `hint`. The `hint` is usually the exact next step.
-```bash
-boss --cdp-url http://localhost:9222 login --cdp
-agent-reach doctor # boss 行 message 应显示「浏览器内有登录 cookie(wt2)」
-```
-
-> 拉起专用 Chrome 后的第一步永远是让用户肉眼确认登录状态,不要用 `boss status` 代替。
+| Code | Meaning | What to do |
+|---|---|---|
+| `NEED_SETUP` | a tool, key, prerequisite or the Agent Reach browser is missing | run `agent-reach doctor --text` and follow the problem listed for the channel: `agent-reach add <channel>`, install the missing prerequisite, `agent-reach browser setup`, or `agent-reach configure groq-key` |
+| `NEED_LOGIN` | login is missing or expired | the user runs `agent-reach login <channel>` and logs in themselves; if it still fails, `agent-reach logout <channel>` then log in again |
+| `UPSTREAM_BROKEN` | the upstream tool or platform failed | don't retry in a loop; try again later, run `agent-reach update` (newer pinned tools often fix this), then `agent-reach check <channel>`; still broken → open an issue with the `message` |
+| `TIMEOUT` | no backend answered in time | retry later, or pass a larger `--timeout SECONDS`; on a restricted network set a proxy (below) |
+| `RATE_LIMITED` | the platform is throttling | wait before retrying; avoid many requests in a row |
+| `NOT_FOUND` | the content does not exist | check the link, id or username |
+| `BAD_INPUT` | wrong arguments or unknown channel/action | run `agent-reach channels` for valid actions and usage |
----
+## Doctor statuses
-## Twitter/X: twitter-cli 连接失败
+| Status | Meaning | What to do |
+|---|---|---|
+| `not_added` | optional channel not turned on | `agent-reach add <channel>` |
+| `needs_setup` | something is missing; `problems` says what | follow each problem: install prerequisite, `agent-reach add <channel>` again, `agent-reach browser setup`, or `agent-reach configure <key>` |
+| `needs_login` | the last live check failed only on login | `agent-reach login <channel>` (the user logs in) |
+| `unverified` | set up, but no live check in the last 24 hours | `agent-reach check <channel>` |
+| `ready` | passed a live check in the last 24 hours | nothing |
+| `broken` | the last live check failed for another reason | `agent-reach update`, then `agent-reach check <channel> --text`; see `UPSTREAM_BROKEN` |
-**症状:** `twitter search` 或其他命令返回错误
+`agent-reach doctor --live` runs the live checks first, then reports.
-**原因:** twitter-cli 需要 `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`
-环境变量才能访问 Twitter API。`agent-reach configure twitter-cookies`
-保存的值只供 doctor 检查配置是否齐全;doctor 不执行上游认证,也不会设置当前
-Shell。如果你的网络环境需要代理才能访问 x.com,还需要配置代理。
+## Agent Reach browser
-**解决方案:**
+Used by xiaohongshu, reddit, twitter, facebook, instagram, boss and xueqiu. It is a separate Chrome window with its own profile in `~/.agent-reach/browser/`.
-### 方案 1:设置环境变量代理
-
-```bash
-export TWITTER_AUTH_TOKEN="..."
-export TWITTER_CT0="..."
-export HTTP_PROXY="http://user:pass@host:port"
-export HTTPS_PROXY="http://user:pass@host:port"
-twitter search "test" -n 1
-```
+- **`agent-reach browser setup` keeps saying it is waiting for the extension**: in the Agent Reach window, click "Add to Chrome" on the OpenCLI extension page, then run `agent-reach browser setup` again.
+- **"more than one new OpenCLI profile connected"**: close other Chrome windows that have the OpenCLI extension, then run setup again.
+- **Chrome not installed**: install Google Chrome, then retry.
+- **Window closed**: `agent-reach browser start` reopens it; `agent-reach browser status` shows its state.
+- Close the window when you're done; any local process can control it through its debugging port.
-### 方案 2:使用全局代理工具
+## Proxy
-让代理工具接管所有网络流量,这样 twitter-cli 的请求也会走代理:
+Some platforms block certain networks or regions. Save a proxy once (the address is asked for with hidden input, since it may contain a password):
```bash
-# macOS — ClashX / Surge 开启"增强模式"
-# Linux — proxychains 或 tun2socks
-proxychains twitter search "test" -n 1
+agent-reach configure proxy
```
-### 方案 3:不用 twitter-cli,用 Exa 搜索替代
+An agent without a terminal prompt can pipe the value in: `agent-reach configure proxy --stdin`.
-twitter-cli 不可用时,可以直接用 Exa 搜索 Twitter 内容:
+It is used for every Agent Reach command. An `HTTPS_PROXY` set in your shell takes precedence.
-```bash
-mcporter call exa.web_search_exa query="site:x.com 搜索词" numResults=5
-```
-
-### 方案 4:检查认证
-
-```bash
-twitter check
-```
+## Still stuck
-> 如果返回 "Missing credentials",需要在运行该命令的进程环境中设置
-> `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`。
->
-> **Fallback:** 如果你已经安装了 bird CLI(`npm install -g @steipete/bird`),它也能正常工作。Agent Reach 会自动检测已安装的工具。
+- `agent-reach update` and try again.
+- Remove and re-add a channel: `agent-reach remove <channel>` then `agent-reach add <channel>` (this also clears its login).
+- Open an issue at https://github.com/Panniantong/Agent-Reach/issues with the output of `agent-reach doctor --text` (it starts with the version) and `agent-reach check <channel> --text`. Remove any personal data first.
diff --git a/docs/update.md b/docs/update.md
index 2ef00bb9..5df1042f 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,120 +1,43 @@
-# Agent Reach — Update Guide
+# Update Agent Reach
-## For Humans
-
-Copy this to your AI Agent:
-
-```
-帮我更新 Agent Reach:https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-```
-
-Or in English:
-
-```
-Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
-```
-
----
-
-## For AI Agents
-
-### ⚠️ Workspace Rules
-
-**Never create files, clone repos, or run commands in the agent workspace.** Use `/tmp/` for temporary work and `~/.agent-reach/` for persistent data.
-
-### Goal
-
-Update Agent Reach to the latest version, refresh upstream tools, migrate from retired backends, and verify everything works. The user should not need to do anything manually (except things only a human can do, like clicking a browser-extension install button).
-
-### Step 1: Check current version
+## 2.0 and later
```bash
-agent-reach check-update
+agent-reach update
```
-If it says "已是最新版本", skip to Step 4 (verify). Otherwise continue.
+One command does everything:
-### Step 2: Update Agent Reach package
+- upgrades the program with the installer you used (uv or pipx) to the latest GitHub release
+- moves the tools of your added channels to the versions pinned by that release
+- refreshes the Agent Reach skill in your agent's skill folder
-```bash
-pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip
-```
+Only want to know if there is a new version? `agent-reach update --check`. `agent-reach watch --text` also reports available updates.
-> If pip complains about `externally-managed-environment` (PEP 668), the user
-> originally installed via pipx or a venv — use the matching command:
-> `pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip`
-> or activate `~/.agent-reach-venv` first.
+Afterwards, `agent-reach check --text` confirms your channels still work.
-### Step 3: Refresh upstream tools
+If the upgrade step fails, the error `hint` holds the exact command to run by hand.
-Run these to keep installed tools current. **Only upgrade what is already
-installed — do not install new tools the user never asked for** (the one
-exception: OpenCLI on desktop, see below).
-
-```bash
-# Python-based CLIs the user already has (upgrade keeps signatures fresh)
-which twitter >/dev/null 2>&1 && { pipx upgrade twitter-cli 2>/dev/null || uv tool upgrade twitter-cli 2>/dev/null; }
-which bili >/dev/null 2>&1 && { pipx upgrade bilibili-cli 2>/dev/null || uv tool upgrade bilibili-cli 2>/dev/null; }
-which xhs >/dev/null 2>&1 && { pipx upgrade xiaohongshu-cli 2>/dev/null || uv tool upgrade xiaohongshu-cli 2>/dev/null; }
-which yt-dlp >/dev/null 2>&1 && { pipx install --force 'yt-dlp[default]' 2>/dev/null || uv tool install --force 'yt-dlp[default]' 2>/dev/null || python -m pip install -U 'yt-dlp[default]' 2>/dev/null; }
+## Coming from a version before 2.0
-# rdt-cli is pinned to a git source (PyPI lags upstream) — same pin as the code's _RDT_GIT_SOURCE
-which rdt >/dev/null 2>&1 && pipx install --force 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66' 2>/dev/null
+Older versions installed differently, so reinstall once with the same command as [install.md](install.md):
-# npm-based
-which mcporter >/dev/null 2>&1 && npm update -g mcporter 2>/dev/null
-which opencli >/dev/null 2>&1 && npm update -g @jackwener/opencli 2>/dev/null
+```bash
+uv tool install --force https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip
+agent-reach setup
```
-**Desktop users without OpenCLI**: since v1.5.0 OpenCLI is the preferred
-backend for 小红书/Reddit (and adds B站 subtitles). Offer it once. For
-小红书, OpenCLI may use only an existing Chrome session explicitly controlled
-by the user. The update must never log the user in or read browser cookies:
-
-> "这次更新引入了 OpenCLI 后端。要装吗?装完只需你在 Chrome 商店点一次
-> 『添加扩展』。小红书 OpenCLI 只使用你已有的 Chrome 会话;如果没有现成
-> 会话,我不会自动登录,会改用 Cookie-Editor 配置 MCP / 存量工具。"
-
-If yes: `agent-reach install --system --channels opencli` and guide them through the
-extension click. If no, everything keeps working on existing backends.
+(pipx: `pipx install --force <same URL>`.)
-### Step 4: Coexistence (DO NOT uninstall old tools)
+`agent-reach setup` migrates the old install:
-**Never uninstall tools the user already has.** Retired backends (e.g. yt-dlp
-no longer serves Bilibili; xhs-cli is no longer installed by default) keep
-working as fallbacks where they still function. Agent Reach routes around
-them automatically — removal is the user's call, not yours.
-
-### Step 5: Verify
+- keys in `~/.agent-reach/config.yaml` stay as they are
+- `result.migration.suggested_channels` lists channels you used before; add them again with `agent-reach add <channel>`
+- tools the old version installed globally are not removed; Agent Reach 2.0 uses its own private copies
+- old CLI logins (bilibili, boss) can be copied over instead of logging in again:
```bash
-agent-reach version
-agent-reach doctor
+agent-reach login <channel> --import-existing
```
-Running `agent-reach doctor` (text mode) also makes sure an Agent Reach skill
-exists in detected agent skill directories. If the user already has a skill
-there, doctor preserves it instead of overwriting local customizations. Use
-`agent-reach skill --install` when you explicitly want to refresh the bundled
-skill files.
-
-Check the doctor output:
-
-- Every channel shows ✅ / [!] with a clear message, and multi-backend
- channels (小红书/Reddit/B站/Twitter) report `当前后端:…`
-- If a previously-working channel now shows [X]/error, the message contains
- the exact fix (e.g. a venv-reinstall prescription) — run it, then re-check
-- `--json` gives the same data machine-readably (`active_backend` per channel)
-
-### Step 6: Report to user
-
-Tell the user:
-
-1. What version they're on now (`agent-reach version`)
-2. How many channels are available, and which backend each multi-backend
- platform is using (from doctor)
-3. Anything that needs their action (e.g. a Chrome extension click, or a
- manual Cookie-Editor export when XiaoHongShu uses MCP / a legacy tool)
-4. What changed in this update (release notes shown by `check-update`)
-
-Done.
+Browser-login channels (xiaohongshu, reddit, twitter, ...) no longer use your own browser's cookies. Run `agent-reach browser setup` and log in again in the Agent Reach browser with `agent-reach login <channel>`.
diff --git a/llms.txt b/llms.txt
index f56304e8..f48b0c6c 100644
--- a/llms.txt
+++ b/llms.txt
@@ -1,32 +1,29 @@
# Agent Reach
-> Give your AI agent eyes to see the internet. Agent Reach installs, routes, and health-checks upstream tools for 15 platforms — Twitter/X, Reddit, Facebook, Instagram, YouTube, GitHub, Bilibili, XiaoHongShu, LinkedIn, V2EX, Xueqiu, Xiaoyuzhou Podcast, RSS, web search, and any web page. One install, zero API fees.
+> Makes it easier for CLI agents (Claude Code, Codex, Hermes Agent, OpenClaw, ...) to reach the internet: login-walled platforms (XiaoHongShu, Twitter/X, Reddit, LinkedIn), video/audio content (YouTube and Bilibili subtitles, podcast transcripts), Chinese platforms, and clean structured data (Xueqiu, V2EX, GitHub). One entry point, one JSON output shape.
-## Quick Start
+## Install
-- [Installation Guide](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md): Step-by-step setup instructions for AI agents
-- [README (中文)](https://github.com/Panniantong/Agent-Reach/blob/main/README.md): Full documentation in Chinese
-- [README (English)](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md): Full documentation in English
+- [Installation Guide](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md): agent-executable steps
+- Install from GitHub only: `uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v2.0.0.zip` (or `pipx install` with the same URL), then `agent-reach setup`. The PyPI package named `agent-reach` is NOT this project.
-## Core Commands
+## Commands
-- [CLI Usage](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md): `agent-reach doctor --json` shows the active backend; agents then call upstream tools directly (`opencli`, `twitter`, `bili`, `yt-dlp`, `gh`, `mcporter`, etc.).
+- `agent-reach channels`: channels, actions, params (live source of truth)
+- `agent-reach <channel> <action> [args]`: e.g. `agent-reach bilibili search python`
+- `agent-reach read <url>`: read a link with the matching channel
+- Output: `{schema_version, ok, channel, action, backend, items, meta, error}`; error codes NEED_SETUP, NEED_LOGIN, UPSTREAM_BROKEN, TIMEOUT, RATE_LIMITED, NOT_FOUND, BAD_INPUT
+- Management: `setup`, `add|remove <channel>`, `login|logout <channel>` (the user logs in), `browser setup|start|status`, `doctor`, `check`, `watch`, `update`, `configure`, `uninstall`
-## Key Features
+## Channels
-- Read any URL: tweets, Reddit posts, Facebook pages/feed/groups, Instagram profiles/posts, YouTube videos (transcripts), GitHub repos, articles, XiaoHongShu notes, Bilibili videos, RSS feeds
-- Search/discover across platforms: Twitter/X, Reddit, Facebook, Instagram user search, GitHub, YouTube, Bilibili, XiaoHongShu, LinkedIn, V2EX, Xueqiu, Web (via Exa)
-- Self-diagnosis: `agent-reach doctor` checks what works and what needs setup
-- Auto-installs dependencies: `agent-reach install --env=auto`
-- Browser-session / cookie auth for platforms that require login (Twitter, Reddit, Facebook, Instagram, XiaoHongShu, Xueqiu)
-- Proxy support for platforms that block server IPs (Reddit, Twitter)
-- Zero API fees: all backends are free and open-source (OpenCLI, twitter-cli, rdt-cli, bili-cli, yt-dlp, Jina Reader, mcporter/Exa, etc.)
+- default: github, youtube, v2ex, web (web is a fallback when the agent's own search/fetch fails)
+- optional: xiaohongshu, bilibili, reddit, linkedin, boss, xiaoyuzhou, xueqiu
+- experimental: twitter, facebook, instagram
-## Troubleshooting
+## Docs
-- [Troubleshooting Guide](https://github.com/Panniantong/Agent-Reach/blob/main/docs/troubleshooting.md): Common issues and solutions
-
-## Optional
-
-- [SKILL.md](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md): Integration guide for AI agent frameworks (OpenClaw, Claude Code, etc.)
-- Install from GitHub (the `agent-reach` package on PyPI is NOT this project): `pipx install https://github.com/Panniantong/agent-reach/archive/main.zip`
+- [README (中文)](https://github.com/Panniantong/Agent-Reach/blob/main/README.md)
+- [README (English)](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md)
+- [Update](https://github.com/Panniantong/Agent-Reach/blob/main/docs/update.md)
+- [Troubleshooting](https://github.com/Panniantong/Agent-Reach/blob/main/docs/troubleshooting.md)
diff --git a/pyproject.toml b/pyproject.toml
index fb7a29a5..ea0c9b16 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
[project]
name = "agent-reach"
version = "1.5.0"
-description = "Give your AI Agent eyes to see the entire internet. Search + Read 10+ platforms."
+description = "Internet access for AI agents: one CLI with JSON output to search and read the web, YouTube, GitHub, V2EX and more."
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.10"
@@ -29,17 +29,12 @@ classifiers = [
dependencies = [
"requests>=2.28",
- "feedparser>=6.0",
"loguru>=0.7",
"pyyaml>=6.0",
- "rich>=13.0",
"yt-dlp[default]>=2026.07.04",
]
[project.optional-dependencies]
-browser = ["playwright>=1.40"]
-cookies = ["browser-cookie3>=0.19"]
-all = ["playwright>=1.40", "mcp[cli]>=1.0", "browser-cookie3>=0.19"]
dev = [
"pytest>=8.0",
"ruff>=0.8",
diff --git a/test.sh b/test.sh
old mode 100644
new mode 100755
index 6910dc07..d72a32d8
--- a/test.sh
+++ b/test.sh
@@ -1,7 +1,7 @@
#!/bin/bash
# Agent Reach clean-environment integration test.
-# Creates an isolated venv, installs this checkout, runs a read-only doctor,
-# then executes the repository test suite.
+# Creates an isolated venv and HOME, installs this checkout, runs the
+# read-only CLI commands, then executes the repository test suite.
set -euo pipefail
@@ -19,52 +19,43 @@ cleanup() {
trap cleanup EXIT INT TERM
PYTHON_CMD=()
-if command -v python3 >/dev/null 2>&1 && \
- python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
- PYTHON_CMD=(python3)
-elif command -v python >/dev/null 2>&1 && \
- python -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
- PYTHON_CMD=(python)
-elif command -v py >/dev/null 2>&1 && \
- py -3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
+for candidate in python3 python; do
+ if command -v "$candidate" >/dev/null 2>&1 && \
+ "$candidate" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
+ PYTHON_CMD=("$candidate")
+ break
+ fi
+done
+if [ ${#PYTHON_CMD[@]} -eq 0 ] && command -v py >/dev/null 2>&1 && \
+ py -3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
PYTHON_CMD=(py -3)
-elif [ -x "$REPO_ROOT/.venv/bin/python" ] && \
- "$REPO_ROOT/.venv/bin/python" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
- PYTHON_CMD=("$REPO_ROOT/.venv/bin/python")
-elif [ -x "$REPO_ROOT/.venv/Scripts/python.exe" ] && \
- "$REPO_ROOT/.venv/Scripts/python.exe" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then
- PYTHON_CMD=("$REPO_ROOT/.venv/Scripts/python.exe")
-else
+fi
+if [ ${#PYTHON_CMD[@]} -eq 0 ]; then
echo "Python 3.10+ is required" >&2
exit 1
fi
-echo "[1/5] Creating isolated environment"
+echo "[1/4] Creating isolated environment"
"${PYTHON_CMD[@]}" -m venv "$TEST_DIR/venv"
# shellcheck disable=SC1091
if [ -f "$TEST_DIR/venv/bin/activate" ]; then
source "$TEST_DIR/venv/bin/activate"
-elif [ -f "$TEST_DIR/venv/Scripts/activate" ]; then
- source "$TEST_DIR/venv/Scripts/activate"
else
- echo "Could not find the virtual environment activation script" >&2
- exit 1
+ source "$TEST_DIR/venv/Scripts/activate"
fi
-echo "[2/5] Installing this checkout and test dependencies"
+echo "[2/4] Installing this checkout and test dependencies"
python -m pip install --quiet --upgrade pip
python -m pip install --quiet -c "$REPO_ROOT/constraints.txt" -e "$REPO_ROOT[dev]"
-echo "[3/5] Verifying the installed CLI"
+echo "[3/4] Running read-only CLI commands"
agent-reach version
+agent-reach channels > "$TEST_DIR/channels.json"
+python -c 'import json,sys; d=json.load(open(sys.argv[1], encoding="utf-8")); assert d["ok"] and d["channels"], d; print(f"channels OK: {len(d[\"channels\"])}")' "$TEST_DIR/channels.json"
+agent-reach doctor > "$TEST_DIR/doctor.json"
+python -c 'import json,sys; d=json.load(open(sys.argv[1], encoding="utf-8")); assert "ok" in d, d; print("doctor OK")' "$TEST_DIR/doctor.json"
-echo "[4/5] Running read-only install check and doctor"
-agent-reach install --env=auto --safe
-agent-reach install --env=auto --system --dry-run
-agent-reach doctor --json > "$TEST_DIR/doctor.json"
-python -c 'import json,sys; data=json.load(open(sys.argv[1], encoding="utf-8")); assert isinstance(data, dict) and data, "doctor returned no channels"; print(f"doctor OK: {len(data)} channels")' "$TEST_DIR/doctor.json"
-
-echo "[5/5] Running repository tests"
+echo "[4/4] Running repository tests"
pytest "$REPO_ROOT/tests" -q
echo "Agent Reach integration test passed"
diff --git a/tests/test_auth_guidance_policy.py b/tests/test_auth_guidance_policy.py
index f30c3e75..4db9bce6 100644
--- a/tests/test_auth_guidance_policy.py
+++ b/tests/test_auth_guidance_policy.py
@@ -12,7 +12,6 @@ def _policy_documents() -> list[Path]:
documents = list(ROOT.glob("README*.md"))
for directory in (
ROOT / "docs",
- ROOT / "agent_reach" / "guides",
ROOT / "agent_reach" / "skill",
):
documents.extend(directory.rglob("*.md"))
@@ -54,107 +53,9 @@ def test_xiaohongshu_guidance_never_starts_implicit_login():
assert not violations, "\n".join(violations)
-def test_xiaohongshu_opencli_and_export_boundaries_are_truthful():
- """Cookie import is for MCP/legacy tools, never OpenCLI or Chrome."""
- boundary_docs = (
- ROOT / "docs" / "install.md",
- ROOT / "agent_reach" / "guides" / "setup-xiaohongshu.md",
- ROOT / "agent_reach" / "skill" / "references" / "social.md",
- )
- for path in boundary_docs:
- text = path.read_text(encoding="utf-8")
- assert "已经存在且明确控制" in text, path.relative_to(ROOT)
- assert "不会把 Cookie 注入 OpenCLI" in text, path.relative_to(ROOT)
-
- xhs_guide = boundary_docs[1].read_text(encoding="utf-8")
- assert "xiaohongshu.com 同域 Cookie 集" in xhs_guide
- assert "非 xiaohongshu.com 域 Cookie" in xhs_guide
-
-
-def test_twitter_operational_docs_explain_the_environment_boundary():
- """Saved cookies help doctor only; direct twitter commands need env vars."""
- operational_docs = (
- ROOT / "README.md",
- ROOT / "docs" / "README_en.md",
- ROOT / "docs" / "README_ja.md",
- ROOT / "docs" / "README_ko.md",
- ROOT / "docs" / "cookie-export.md",
- ROOT / "docs" / "install.md",
- ROOT / "docs" / "troubleshooting.md",
- ROOT / "agent_reach" / "guides" / "setup-twitter.md",
- ROOT / "agent_reach" / "skill" / "SKILL.md",
- ROOT / "agent_reach" / "skill" / "SKILL_en.md",
- ROOT / "agent_reach" / "skill" / "references" / "social.md",
- )
-
- for path in operational_docs:
- text = path.read_text(encoding="utf-8")
- assert "TWITTER_AUTH_TOKEN" in text, path.relative_to(ROOT)
- assert "TWITTER_CT0" in text, path.relative_to(ROOT)
-
- twitter_guide = (
- ROOT / "agent_reach" / "guides" / "setup-twitter.md"
- ).read_text(encoding="utf-8")
- assert "不会执行 `twitter status`" in twitter_guide
- assert "不会修改当前 Shell" in twitter_guide
- assert "Export → Header String" in twitter_guide
- assert "cookie JSON" not in twitter_guide
- assert "复制全部" not in twitter_guide
-
- for expected in (
- "--sync-legacy-twitter",
- "~/.agent-reach/config.yaml",
- "~/.config/xfetch/session.json",
- "~/.config/bird/credentials.env",
- ):
- assert expected in twitter_guide
- assert "默认只写" in twitter_guide
- assert "不会自动删除" in twitter_guide
-
- rendered_as_verified = (
- "✅ Twitter/X tweets",
- "✅ Twitter/Xツイート",
- "✅ Twitter/X 트윗",
- )
- all_text = "\n".join(
- path.read_text(encoding="utf-8") for path in _policy_documents()
- )
- assert not any(claim in all_text for claim in rendered_as_verified)
-
-
-def test_localized_readmes_keep_current_bilibili_and_xhs_routes():
- """Translations must not revive retired yt-dlp/Bilibili or XHS defaults."""
- readmes = (
- ROOT / "README.md",
- ROOT / "docs" / "README_en.md",
- ROOT / "docs" / "README_ja.md",
- ROOT / "docs" / "README_ko.md",
- )
-
- for path in readmes:
- text = path.read_text(encoding="utf-8")
- assert "bilibili.py → yt-dlp" not in text, path.relative_to(ROOT)
- assert "YouTube + Bilibili" not in text, path.relative_to(ROOT)
- assert "bili-cli" in text, path.relative_to(ROOT)
- assert (
- "xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli"
- in text
- ), path.relative_to(ROOT)
-
-
-def test_localized_readmes_do_not_advertise_retired_channels():
- """Japanese and Korean docs must match the channels shipped by the CLI."""
- for path in (ROOT / "docs" / "README_ja.md", ROOT / "docs" / "README_ko.md"):
- text = path.read_text(encoding="utf-8").lower()
- assert "douyin" not in text, path.relative_to(ROOT)
- assert "weibo" not in text, path.relative_to(ROOT)
-
-
def test_public_guidance_never_installs_the_unrelated_pypi_package():
"""The PyPI name is owned by another project; GitHub URLs are required."""
- candidates = _policy_documents() + [
- ROOT / "agent_reach" / "integrations" / "mcp_server.py",
- ]
+ candidates = _policy_documents()
bare_install = re.compile(
r"\bpip\s+install(?:\s+--upgrade)?\s+['\"]?agent-reach(?:\[[^\]]+\])?\b",
re.IGNORECASE,
@@ -194,42 +95,3 @@ def test_public_guidance_never_puts_secrets_in_process_arguments():
violations.append(f"{path.relative_to(ROOT)}: {marker}")
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
diff --git a/tests/test_boss_channel.py b/tests/test_boss_channel.py
index d378e925..5da0be58 100644
--- a/tests/test_boss_channel.py
+++ b/tests/test_boss_channel.py
@@ -1,31 +1,9 @@
# -*- coding: utf-8 -*-
-"""Dedicated tests for the ``boss`` channel.
+"""Dedicated tests for the ``boss`` channel."""
-Boss直聘 走 CDP 调试端口复用已登录的真 Chrome(headless 是禁区,code 36 风控)。
-check() 只做只读探测:boss-agent-cli 装没装 → CDP 端口通不通 → 有无可复用
-zhipin 页签 → 浏览器内有无登录 cookie(wt2)→ 页签是否都停在反爬安全校验页。
-各分支各自返回 (status, message),且永不触发浏览器启动(无副作用)。
-
-注意 `boss status` 只校验本地 session.enc,不代表 CDP 浏览器已登录——第 4 层
-以浏览器本体(Storage.getCookies)为准。
-"""
-
-import base64
-import hashlib
-import json
-from unittest.mock import patch
-
-from agent_reach.channels import boss as boss_mod
from agent_reach.channels.boss import BossChannel
-from agent_reach.probe import ProbeResult
-
-
-def _ok_probe():
- return ProbeResult("ok", output="1.18.0")
-# --- can_handle ---
-
def test_can_handle_matches_zhipin_hosts():
ch = BossChannel()
for url in [
@@ -40,265 +18,3 @@ def test_can_handle_matches_zhipin_hosts():
"https://[email protected]/job",
]:
assert ch.can_handle(url) is False, url
-
-
-# --- check() 四分支 ---
-
-def test_check_off_when_cli_missing():
- ch = BossChannel()
- with patch.object(boss_mod, "probe_command", return_value=ProbeResult("missing")):
- status, message = ch.check()
- assert status == "off"
- assert "boss-agent-cli" in message
- assert "agent-reach install --system --channels=boss" in message
- assert ch.active_backend is None
-
-
-def test_check_error_when_cli_broken():
- ch = BossChannel()
- with patch.object(boss_mod, "probe_command", return_value=ProbeResult("broken")):
- status, message = ch.check()
- assert status == "error"
- assert ch.active_backend is None
-
-
-def test_check_off_when_cdp_unreachable():
- ch = BossChannel()
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", return_value=None
- ):
- status, message = ch.check()
- assert status == "off"
- assert "9222" in message
- assert ch.active_backend is None
-
-
-def test_chrome_launch_command_is_portable_and_loopback_only():
- mac = boss_mod._chrome_launch_command("Darwin")
- linux = boss_mod._chrome_launch_command("Linux")
- windows = boss_mod._chrome_launch_command("Windows")
-
- assert mac.startswith('open -na "Google Chrome" --args ')
- assert linux.startswith("google-chrome ")
- assert windows.startswith("Start-Process chrome.exe -ArgumentList ")
- for command in (mac, linux, windows):
- assert "--remote-debugging-address=127.0.0.1" in command
- assert "--remote-debugging-port=9222" in command
- assert "boss-chrome-profile" in command
- assert "https://www.zhipin.com/web/geek/job" in command
-
-
-def test_check_warn_when_no_zhipin_page():
- ch = BossChannel()
-
- def fake_cdp(path):
- if path == "/json/version":
- return {"Browser": "Chrome"}
- return [{"type": "page", "url": "https://example.com"}]
-
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", side_effect=fake_cdp
- ), patch.object(boss_mod, "_cdp_zhipin_login_cookie", return_value=None):
- status, message = ch.check()
- assert status == "warn"
- assert ch.active_backend is None
-
-
-def test_check_warn_when_ready():
- ch = BossChannel()
-
- def fake_cdp(path):
- if path == "/json/version":
- return {"Browser": "Chrome"}
- return [{"type": "page", "url": "https://www.zhipin.com/web/geek/job"}]
-
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", side_effect=fake_cdp
- ), patch.object(boss_mod, "_cdp_zhipin_login_cookie", return_value=True):
- status, message = ch.check()
- assert status == "warn"
- assert "boss-agent-cli #403-#407" in message
- assert "boss --cdp-url http://localhost:9222 login --cdp" in message
- assert "--browser-source existing-browser" in message
- assert "code 37 = TOKEN_REFRESH_FAILED" not in message
- assert "wt2" in message
- # 就绪路径:check() 必须标记实际服役的后端(base 契约,doctor --json 不再恒 null)
- assert ch.active_backend == ch.backends[0]
-
-
-def test_check_warn_when_cookie_probe_fails():
- ch = BossChannel()
-
- def fake_cdp(path):
- if path == "/json/version":
- return {"Browser": "Chrome"}
- return [{"type": "page", "url": "https://www.zhipin.com/web/geek/job"}]
-
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", side_effect=fake_cdp
- ), patch.object(boss_mod, "_cdp_zhipin_login_cookie", return_value=None):
- status, message = ch.check()
- assert status == "warn"
- assert "登录态未知" in message
- # 链路已就绪(端口通 + 有页签),仅登录态未知 → 仍标记服役后端
- assert ch.active_backend == ch.backends[0]
-
-
-def test_check_warn_when_browser_not_logged_in():
- """浏览器内无 wt2 → 明确提示未登录,且指出 boss status 只代表 session.enc。"""
- ch = BossChannel()
-
- def fake_cdp(path):
- if path == "/json/version":
- return {"Browser": "Chrome"}
- return [{"type": "page", "url": "https://www.zhipin.com/web/geek/job"}]
-
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", side_effect=fake_cdp
- ), patch.object(boss_mod, "_cdp_zhipin_login_cookie", return_value=False):
- status, message = ch.check()
- assert status == "warn"
- assert "AUTH_EXPIRED" in message
- assert "session.enc" in message
- assert "boss --cdp-url http://localhost:9222 login --cdp" in message
- assert ch.active_backend is None
-
-
-def test_check_warn_when_stuck_on_security_check():
- ch = BossChannel()
-
- def fake_cdp(path):
- if path == "/json/version":
- return {"Browser": "Chrome"}
- return [
- {
- "type": "page",
- "url": "https://www.zhipin.com/web/common/security-check.html?seed=abc",
- }
- ]
-
- with patch.object(boss_mod, "probe_command", return_value=_ok_probe()), patch.object(
- boss_mod, "_cdp_json", side_effect=fake_cdp
- ), patch.object(boss_mod, "_cdp_zhipin_login_cookie", return_value=True):
- status, message = ch.check()
- assert status == "warn"
- assert "安全校验" in message
- assert "不代表未登录" in message
- assert "boss status" in message
- assert "wt2" in message
- assert ch.active_backend is None
-
-
-def test_cdp_cookie_probe_returns_none_without_ws_url():
- with patch.object(boss_mod, "_cdp_json", return_value={"Browser": "Chrome"}):
- assert boss_mod._cdp_zhipin_login_cookie() is None
-
-
-def test_check_clears_stale_active_backend():
- ch = BossChannel()
- ch.active_backend = "stale"
- with patch.object(boss_mod, "probe_command", return_value=ProbeResult("missing")):
- ch.check()
- assert ch.active_backend is None
-
-
-# --- _cdp_zhipin_login_cookie 的 WebSocket 客户端(doctor 只读探测 wt2)---
-
-# 固定 urandom → 固定 Sec-WebSocket-Key,使 accept 可预先算准
-_FIXED_KEY16 = b"\x01" * 16
-_FIXED_KEY = base64.b64encode(_FIXED_KEY16).decode()
-_FIXED_ACCEPT = base64.b64encode(
- hashlib.sha1((_FIXED_KEY + boss_mod._WS_ACCEPT_GUID).encode()).digest()
-).decode()
-
-
-def _ws_frame(payload: dict) -> bytes:
- """构造一个服务器→客户端的无 mask 文本帧。"""
- body = json.dumps(payload).encode("utf-8")
- n = len(body)
- header = bytes([0x81])
- if n < 126:
- header += bytes([n])
- elif n < 65536:
- header += bytes([126]) + n.to_bytes(2, "big")
- else:
- header += bytes([127]) + n.to_bytes(8, "big")
- return header + body
-
-
-def _handshake(status_line: bytes) -> bytes:
- return (
- status_line
- + b"\r\nSec-WebSocket-Accept: "
- + _FIXED_ACCEPT.encode()
- + b"\r\n\r\n"
- )
-
-
-class _FakeSock:
- """按顺序吐出预设字节流的假 socket,记录 sendall 内容。"""
-
- def __init__(self, chunks):
- self._chunks = list(chunks)
- self.sent = b""
-
- def settimeout(self, *_a):
- pass
-
- def sendall(self, data):
- self.sent += data
-
- def recv(self, _n):
- return self._chunks.pop(0) if self._chunks else b""
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_a):
- return False
-
-
-def _run_ws_probe(monkeypatch, chunks, ws_url="ws://127.0.0.1:9222/devtools/browser/abc"):
- """用假 socket 跑 _cdp_zhipin_login_cookie,返回 (结果, 假socket)。"""
- sock = _FakeSock(chunks)
- monkeypatch.setattr(boss_mod.os, "urandom", lambda n: _FIXED_KEY16)
- monkeypatch.setattr(boss_mod.socket, "create_connection", lambda *a, **k: sock)
- monkeypatch.setattr(
- boss_mod, "_cdp_json", lambda path: {"webSocketDebuggerUrl": ws_url}
- )
- return boss_mod._cdp_zhipin_login_cookie(), sock
-
-
-_WT2_RESULT = _ws_frame(
- {"id": 1, "result": {"cookies": [{"name": "wt2", "domain": ".zhipin.com"}]}}
-)
-
-
-def test_ws_probe_event_frame_before_response(monkeypatch):
- """#1:事件帧(无 id)先于响应帧到达,仍应读到 id==1 的响应并识别 wt2。"""
- event = _ws_frame({"method": "Storage.cookiesChanged", "params": {}})
- chunks = [_handshake(b"HTTP/1.1 101 Switching Protocols"), event + _WT2_RESULT]
- result, _ = _run_ws_probe(monkeypatch, chunks)
- assert result is True
-
-
-def test_ws_probe_accepts_empty_reason_phrase(monkeypatch):
- """#2:RFC 合法的空 reason 短语 'HTTP/1.1 101'(无尾部空格)应被接受。"""
- chunks = [_handshake(b"HTTP/1.1 101"), _WT2_RESULT]
- result, _ = _run_ws_probe(monkeypatch, chunks)
- assert result is True
-
-
-def test_ws_probe_rejects_bogus_1019(monkeypatch):
- """#2:伪码 1019(含 ' 101 ' 子串)不应被当作成功升级。"""
- chunks = [_handshake(b"HTTP/1.1 1019 Weird"), _WT2_RESULT]
- result, _ = _run_ws_probe(monkeypatch, chunks)
- assert result is None
-
-
-def test_ws_probe_ipv6_host_header_bracketed(monkeypatch):
- """#3:IPv6 回环的 webSocketDebuggerUrl,Host 头必须带方括号。"""
- chunks = [_handshake(b"HTTP/1.1 101 Switching Protocols"), _WT2_RESULT]
- result, sock = _run_ws_probe(monkeypatch, chunks, ws_url="ws://[::1]:9222/devtools/browser/x")
- assert result is True
- assert b"Host: [::1]:9222\r\n" in sock.sent
diff --git a/tests/test_channel_contracts.py b/tests/test_channel_contracts.py
index 7b51b02a..1ffbbd86 100644
--- a/tests/test_channel_contracts.py
+++ b/tests/test_channel_contracts.py
@@ -1,15 +1,7 @@
# -*- coding: utf-8 -*-
"""Contract tests for channel adapters."""
-import subprocess
-
from agent_reach.channels import get_all_channels
-from agent_reach.config import Config
-
-
-def _fake_run_ok(cmd, **kwargs):
- """Pretend any probed CLI executes fine and prints a version."""
- return subprocess.CompletedProcess(cmd, 0, "2026.06.09", "")
def test_channel_registry_contract():
@@ -21,146 +13,11 @@ def test_channel_registry_contract():
for ch in channels:
assert isinstance(ch.name, str) and ch.name
assert isinstance(ch.description, str) and ch.description
- assert isinstance(ch.backends, list)
- assert ch.tier in {0, 1, 2}
-
-
-def test_channel_check_contract_with_minimal_runtime(monkeypatch, tmp_path):
- # Keep contract tests deterministic by simulating "deps mostly absent".
- monkeypatch.setattr("shutil.which", lambda _cmd: None)
- config = Config(config_path=tmp_path / "config.yaml")
-
- for ch in get_all_channels():
- status, message = ch.check(config)
- assert status in {"ok", "warn", "off", "error"}
- assert isinstance(message, str) and message.strip()
-
-
-def test_channel_active_backend_attribute_contract():
- """Every channel exposes active_backend (default None, or str once set)."""
- for ch in get_all_channels():
- assert hasattr(ch, "active_backend")
- # Fresh instances must default to None / str (class attribute on base)
- fresh = type(ch)()
- assert fresh.active_backend is None or isinstance(fresh.active_backend, str)
-
-
-def test_channel_active_backend_set_by_check(monkeypatch, tmp_path):
- """After check(), active_backend is None or a str — never anything else."""
- monkeypatch.setattr("shutil.which", lambda _cmd: None)
-
- # Keep the network-based channels (V2EX/Xueqiu/Bilibili API) deterministic.
- import urllib.request
- from urllib.error import URLError
-
- def _no_net(*_a, **_k):
- raise URLError("offline")
-
- monkeypatch.setattr(urllib.request, "urlopen", _no_net)
- import agent_reach.channels.xueqiu as xueqiu_mod
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
- monkeypatch.setattr(xueqiu_mod._opener, "open", _no_net)
-
- config = Config(config_path=tmp_path / "config.yaml")
- for ch in get_all_channels():
- ch.check(config)
- assert ch.active_backend is None or isinstance(ch.active_backend, str), (
- f"{ch.name}: active_backend must be None or str after check()"
- )
-
-
-def test_ordered_backends_contract(tmp_path):
- """ordered_backends(config) is a reordering (same multiset) of backends."""
- config = Config(config_path=tmp_path / "config.yaml")
- for ch in get_all_channels():
- ordered = ch.ordered_backends(config)
- assert isinstance(ordered, list)
- assert sorted(ordered) == sorted(ch.backends), (
- f"{ch.name}: ordered_backends must be a permutation of backends"
- )
- # And without any config at all
- ordered_none = ch.ordered_backends(None)
- assert sorted(ordered_none) == sorted(ch.backends)
-
-
-def test_ordered_backends_override_moves_backend_to_front():
- """Config key <channel>_backend promotes the named backend to front."""
- from agent_reach.channels.twitter import TwitterChannel
-
- ch = TwitterChannel()
- ordered = ch.ordered_backends({"twitter_backend": "bird"})
- assert ordered[0] == "bird CLI (legacy)"
- assert sorted(ordered) == sorted(ch.backends)
-
- # Unknown override is ignored — never hides working backends
- ordered_unknown = ch.ordered_backends({"twitter_backend": "no-such-tool"})
- assert ordered_unknown == list(ch.backends)
-
-
-def test_youtube_warns_when_node_only_and_no_config(monkeypatch, tmp_path):
- """YouTube should warn when only Node.js is installed but no yt-dlp config exists."""
- from agent_reach.channels.youtube import YouTubeChannel
-
- def fake_which(cmd):
- if cmd == "yt-dlp":
- return "/usr/bin/yt-dlp"
- if cmd == "node":
- return "/usr/bin/node"
- return None # deno not installed
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr("subprocess.run", _fake_run_ok) # yt-dlp probe really executes now
- # Point to a non-existent config file
- monkeypatch.setattr("os.path.expanduser", lambda p: str(tmp_path / ".config/yt-dlp/config"))
-
- ch = YouTubeChannel()
- status, message = ch.check()
- assert status == "warn"
- assert "--js-runtimes" in message
- assert ch.active_backend == "yt-dlp" # 本体活着,warn 只关乎 JS runtime
-
-
-def test_youtube_warns_with_windows_specific_fix_command(monkeypatch, tmp_path):
- """Windows guidance should use a PowerShell-style yt-dlp config command."""
- from agent_reach.channels.youtube import YouTubeChannel
-
- def fake_which(cmd):
- if cmd == "yt-dlp":
- return "C:/yt-dlp.exe"
- if cmd == "node":
- return "C:/node.exe"
- return None
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr("subprocess.run", _fake_run_ok) # yt-dlp probe really executes now
- monkeypatch.setattr("agent_reach.utils.paths.sys.platform", "win32")
- monkeypatch.setenv("APPDATA", str(tmp_path / "AppData" / "Roaming"))
-
- ch = YouTubeChannel()
- status, message = ch.check()
- assert status == "warn"
- assert "Select-String" in message
- assert "--js-runtimes node" in message
-
-
-def test_youtube_ok_when_deno_installed(monkeypatch):
- """YouTube should return ok when Deno is installed (no config needed)."""
- from agent_reach.channels.youtube import YouTubeChannel
-
- def fake_which(cmd):
- if cmd == "yt-dlp":
- return "/usr/bin/yt-dlp"
- if cmd == "deno":
- return "/usr/bin/deno"
- return None
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr("subprocess.run", _fake_run_ok) # yt-dlp probe really executes now
-
- ch = YouTubeChannel()
- status, _msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "yt-dlp"
+ assert ch.level in {"default", "optional", "experimental"}
+ assert ch.actions, f"{ch.name} exposes no actions"
+ for action in ch.actions:
+ for _label, method in action.backends:
+ assert callable(getattr(ch, method, None)), f"{ch.name}.{method}"
def test_channel_can_handle_contract():
@@ -174,9 +31,7 @@ def test_channel_can_handle_contract():
"bilibili": "https://www.bilibili.com/video/BV1xx411",
"xiaohongshu": "https://www.xiaohongshu.com/explore/123",
"linkedin": "https://www.linkedin.com/in/test",
- "rss": "https://example.com/feed.xml",
"xueqiu": "https://xueqiu.com/S/SH600519",
- "exa_search": "https://example.com",
"web": "https://example.com",
}
for ch in get_all_channels():
diff --git a/tests/test_channels.py b/tests/test_channels.py
index a7cc31ea..f3ae303f 100644
--- a/tests/test_channels.py
+++ b/tests/test_channels.py
@@ -1,20 +1,10 @@
# -*- coding: utf-8 -*-
-"""Tests for channel registry basics and health checks."""
+"""Tests for channel registry basics, URL routing and Xueqiu session helpers."""
-import json
-import shutil
-import subprocess
-from urllib.error import URLError
-
-import pytest
-
-from agent_reach.backends import OpenCLIStatus
from agent_reach.channels import get_all_channels, get_channel
-from agent_reach.channels.bilibili import BilibiliChannel
from agent_reach.channels.facebook import FacebookChannel
from agent_reach.channels.instagram import InstagramChannel
from agent_reach.channels.v2ex import V2EXChannel
-from agent_reach.channels.xiaohongshu import XiaoHongShuChannel
from agent_reach.channels.xueqiu import XueqiuChannel
@@ -38,6 +28,7 @@ class TestChannelRegistry:
assert "v2ex" in names
+
class TestOpenCLISiteChannels:
def test_facebook_can_handle_common_urls(self):
ch = FacebookChannel()
@@ -54,57 +45,6 @@ class TestOpenCLISiteChannels:
assert ch.can_handle("https://instagr.am/p/abc123/")
assert not ch.can_handle("https://facebook.com/openai")
- def test_opencli_bridge_ready_is_unverified_for_login_platform(
- self, monkeypatch
- ):
- monkeypatch.setattr(
- "agent_reach.backends.opencli_status",
- lambda: OpenCLIStatus(
- installed=True,
- extension_connected=True,
- version="1.8.3",
- ),
- )
- ch = FacebookChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert ch.active_backend is None
- assert "桥接已连接" in msg
- assert "登录态和实际命令未实时验证" in msg
- assert "facebook.com" in msg
-
- instagram = InstagramChannel()
- status, msg = instagram.check()
- assert status == "warn"
- assert instagram.active_backend is None
- assert "桥接已连接" in msg
- assert "instagram.com" in msg
-
- def test_opencli_missing_reports_off(self, monkeypatch):
- monkeypatch.setattr(
- "agent_reach.backends.opencli_status",
- lambda: OpenCLIStatus(installed=False),
- )
- ch = InstagramChannel()
- status, msg = ch.check()
- assert status == "off"
- assert ch.active_backend is None
- assert "agent-reach install --system --channels opencli" in msg
- assert "instagram.com" in msg
-
- def test_opencli_installed_without_extension_reports_warn(self, monkeypatch):
- monkeypatch.setattr(
- "agent_reach.backends.opencli_status",
- lambda: OpenCLIStatus(
- installed=True,
- hint="OpenCLI 已安装,但 Chrome 扩展未安装。",
- ),
- )
- ch = InstagramChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert ch.active_backend is None
- assert "Chrome 扩展" in msg
class TestV2EXChannel:
@@ -115,333 +55,6 @@ class TestV2EXChannel:
assert not ch.can_handle("https://github.com/user/repo")
assert not ch.can_handle("https://reddit.com/r/Python")
- def test_check_ok_when_api_reachable(self, monkeypatch):
- import urllib.request
-
- class FakeResponse:
- status = 200
-
- def __enter__(self):
- return self
-
- def __exit__(self, *args):
- pass
-
- def read(self, _size=-1):
- return b"[]"
-
- monkeypatch.setattr(
- urllib.request,
- "urlopen",
- lambda req, timeout=None: FakeResponse(),
- )
- status, msg = V2EXChannel().check()
- assert status == "ok"
- assert "公开 API 可用" in msg
-
- def test_check_warn_when_api_unreachable(self, monkeypatch):
- import urllib.request
-
- def raise_error(req, timeout=None):
- raise URLError("connection refused")
-
- monkeypatch.setattr(urllib.request, "urlopen", raise_error)
- status, msg = V2EXChannel().check()
- assert status == "warn"
- assert "失败" in msg
-
- def test_check_passes_its_read_only_config_to_cookie_loading(self, monkeypatch):
- """Doctor's config object must flow through instead of reopening config."""
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- supplied_config = object()
- observed = []
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", False)
-
- def fake_load(config=None):
- observed.append(config)
- return False
-
- fake_response_data = {
- "data": {"quote": {"symbol": "SH601138", "current": 52.0}}
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_response_data).encode()
-
- monkeypatch.setattr(
- xueqiu_mod, "_load_cookies_from_config", fake_load
- )
- monkeypatch.setattr(
- xueqiu_mod._opener,
- "open",
- lambda req, timeout=None: FakeResponse(),
- )
-
- status, _ = XueqiuChannel().check(supplied_config)
-
- assert status == "ok"
- assert observed == [supplied_config]
-
- # ------------------------------------------------------------------ #
- # get_hot_topics
- # ------------------------------------------------------------------ #
-
- def test_get_hot_topics_returns_list(self, monkeypatch):
- import urllib.request
-
- fake_data = [
- {
- "id": 111,
- "title": "Python 3.13 发布了",
- "url": "https://www.v2ex.com/t/111",
- "replies": 42,
- "content": "发布公告内容",
- "created": 1700000000,
- "node": {"name": "python", "title": "Python"},
- },
- {
- "id": 222,
- "title": "Rust 好学吗",
- "url": "https://www.v2ex.com/t/222",
- "replies": 10,
- "content": "",
- "created": 1700000001,
- "node": {"name": "rust", "title": "Rust"},
- },
- ]
-
- class FakeResponse:
- status = 200
-
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self, _size=-1):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout=None: FakeResponse())
- topics = V2EXChannel().get_hot_topics(limit=5)
- assert len(topics) == 2
- assert topics[0]["id"] == 111
- assert topics[0]["title"] == "Python 3.13 发布了"
- assert topics[0]["replies"] == 42
- assert topics[0]["node_name"] == "python"
- assert topics[0]["node_title"] == "Python"
- assert topics[0]["created"] == 1700000000
-
- def test_get_hot_topics_respects_limit(self, monkeypatch):
- import urllib.request
-
- fake_data = [
- {"id": i, "title": f"Topic {i}", "url": f"https://v2ex.com/t/{i}", "replies": i,
- "content": "", "created": 1700000000 + i, "node": {"name": "tech", "title": "Tech"}}
- for i in range(10)
- ]
-
- class FakeResponse:
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout=None: FakeResponse())
- topics = V2EXChannel().get_hot_topics(limit=3)
- assert len(topics) == 3
-
- def test_get_hot_topics_truncates_content(self, monkeypatch):
- import urllib.request
-
- long_content = "A" * 300
- fake_data = [
- {"id": 1, "title": "Long post", "url": "https://v2ex.com/t/1", "replies": 0,
- "content": long_content, "created": 1700000000, "node": {"name": "tech", "title": "Tech"}}
- ]
-
- class FakeResponse:
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout=None: FakeResponse())
- topics = V2EXChannel().get_hot_topics(limit=1)
- assert len(topics[0]["content"]) == 200
-
- # ------------------------------------------------------------------ #
- # get_node_topics
- # ------------------------------------------------------------------ #
-
- def test_get_node_topics(self, monkeypatch):
- import urllib.request
-
- fake_data = [
- {
- "id": 333,
- "title": "Flask 部署问题",
- "url": "https://www.v2ex.com/t/333",
- "replies": 5,
- "content": "求帮助",
- "created": 1710000000,
- "node": {"name": "python", "title": "Python"},
- }
- ]
-
- class FakeResponse:
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout=None: FakeResponse())
- topics = V2EXChannel().get_node_topics("python")
- assert len(topics) == 1
- assert topics[0]["id"] == 333
- assert topics[0]["node_name"] == "python"
- assert topics[0]["title"] == "Flask 部署问题"
- assert topics[0]["created"] == 1710000000
-
- # ------------------------------------------------------------------ #
- # get_topic
- # ------------------------------------------------------------------ #
-
- def test_get_topic_returns_detail_and_replies(self, monkeypatch):
- import urllib.request
-
- topic_data = [
- {
- "id": 999,
- "title": "测试帖子",
- "url": "https://www.v2ex.com/t/999",
- "content": "帖子正文",
- "replies": 2,
- "node": {"name": "qna", "title": "问与答"},
- "member": {"username": "alice"},
- "created": 1700000000,
- }
- ]
- replies_data = [
- {
- "member": {"username": "bob"},
- "content": "第一条回复",
- "created": 1700000100,
- },
- {
- "member": {"username": "carol"},
- "content": "第二条回复",
- "created": 1700000200,
- },
- ]
-
- class FakeResponse:
- def __init__(self, payload):
- self._payload = payload
-
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(self._payload).encode()
-
- def fake_urlopen(req, timeout=None):
- url = req.full_url
- if "replies" in url:
- return FakeResponse(replies_data)
- return FakeResponse(topic_data)
-
- monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
- result = V2EXChannel().get_topic(999)
-
- assert result["id"] == 999
- assert result["title"] == "测试帖子"
- assert result["author"] == "alice"
- assert result["node_name"] == "qna"
- assert len(result["replies"]) == 2
- assert result["replies"][0]["author"] == "bob"
- assert result["replies"][1]["content"] == "第二条回复"
-
- def test_get_topic_handles_empty_replies(self, monkeypatch):
- import urllib.request
-
- topic_data = [
- {
- "id": 1,
- "title": "孤独帖子",
- "url": "https://www.v2ex.com/t/1",
- "content": "",
- "replies": 0,
- "node": {"name": "offtopic", "title": "水"},
- "member": {"username": "dave"},
- "created": 0,
- }
- ]
-
- class FakeResponse:
- def __init__(self, payload): self._payload = payload
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(self._payload).encode()
-
- def fake_urlopen(req, timeout=None):
- if "replies" in req.full_url:
- return FakeResponse([])
- return FakeResponse(topic_data)
-
- monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
- result = V2EXChannel().get_topic(1)
- assert result["replies"] == []
-
- # ------------------------------------------------------------------ #
- # get_user
- # ------------------------------------------------------------------ #
-
- def test_get_user_returns_profile(self, monkeypatch):
- import urllib.request
-
- fake_user = {
- "id": 42,
- "username": "alice",
- "url": "https://www.v2ex.com/member/alice",
- "website": "https://alice.dev",
- "twitter": "alice_tw",
- "psn": "",
- "github": "alice",
- "btc": "",
- "location": "Shanghai",
- "bio": "Python dev",
- "avatar_large": "https://cdn.v2ex.com/avatars/alice_large.png",
- "created": 1500000000,
- }
-
- class FakeResponse:
- def __enter__(self): return self
- def __exit__(self, *_): pass
- def read(self, _size=-1): return json.dumps(fake_user).encode()
-
- monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout=None: FakeResponse())
- user = V2EXChannel().get_user("alice")
-
- assert user["id"] == 42
- assert user["username"] == "alice"
- assert user["github"] == "alice"
- assert user["location"] == "Shanghai"
- assert "alice_large.png" in user["avatar"]
-
- # ------------------------------------------------------------------ #
- # search
- # ------------------------------------------------------------------ #
-
- def test_search_returns_unavailable_notice(self):
- result = V2EXChannel().search("python asyncio")
- assert len(result) == 1
- assert "error" in result[0]
- assert "V2EX" in result[0]["error"]
-
class TestXueqiuChannel:
def test_can_handle_xueqiu_urls(self):
@@ -452,260 +65,6 @@ class TestXueqiuChannel:
assert not ch.can_handle("https://github.com/user/repo")
assert not ch.can_handle("https://v2ex.com/t/123")
- def test_check_ok_when_api_reachable(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- fake_response_data = {
- "data": {
- "quote": {
- "symbol": "SH601138",
- "name": "工业富联",
- "current": 52.0,
- "pe_ttm": 38.1,
- }
- }
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_response_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- status, msg = XueqiuChannel().check()
- assert status == "ok"
- assert "公开 API 可用" in msg
-
- def test_check_warn_when_api_unreachable(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- def raise_error(req, timeout=None):
- raise URLError("connection refused")
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", raise_error)
- status, msg = XueqiuChannel().check()
- assert status == "warn"
- assert "失败" in msg
-
- # ------------------------------------------------------------------ #
- # get_stock_quote
- # ------------------------------------------------------------------ #
-
- def test_get_stock_quote(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- fake_data = {
- "data": {
- "quote": {
- "symbol": "SH600519",
- "name": "贵州茅台",
- "current": 1800.0,
- "percent": 1.5,
- "chg": 26.6,
- "high": 1810.0,
- "low": 1770.0,
- "open": 1775.0,
- "last_close": 1773.4,
- "volume": 12345678,
- "amount": 22000000000,
- "market_capital": 2260000000000,
- "turnover_rate": 0.098,
- "pe_ttm": 30.5,
- "pe_forecast": 25.2,
- "pb": 8.5,
- "eps": 59.0,
- "timestamp": 1700000000000,
- }
- }
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- quote = XueqiuChannel().get_stock_quote("SH600519")
- assert quote["symbol"] == "SH600519"
- assert quote["name"] == "贵州茅台"
- assert quote["current"] == 1800.0
- assert quote["percent"] == 1.5
- assert quote["volume"] == 12345678
-
- # ------------------------------------------------------------------ #
- # search_stock
- # ------------------------------------------------------------------ #
-
- def test_search_stock(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- fake_data = {
- "stocks": [
- {"code": "SH600519", "name": "贵州茅台", "exchange": "SHA"},
- {"code": "SZ000858", "name": "五粮液", "exchange": "SZA"},
- ]
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- results = XueqiuChannel().search_stock("茅台", limit=5)
- assert len(results) == 2
- assert results[0]["symbol"] == "SH600519"
- assert results[0]["name"] == "贵州茅台"
- assert results[1]["exchange"] == "SZA"
-
- # ------------------------------------------------------------------ #
- # get_hot_posts
- # ------------------------------------------------------------------ #
-
- def test_get_hot_posts_returns_list(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- # v4 timeline: each item has a JSON-encoded `data` field
- def make_item(id_, title, text, author, likes, target):
- post = {
- "id": id_,
- "title": title,
- "text": text,
- "user": {"screen_name": author},
- "like_count": likes,
- "target": target,
- }
- return {"data": json.dumps(post), "original_status": None}
-
- fake_data = {
- "list": [
- make_item(111, "市场分析", "<p>今天大盘走势&amp;分析</p>", "投资者A", 42, "/1234567890/111"),
- make_item(222, "", "短评", "投资者B", 10, "/9876543210/222"),
- ]
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- posts = XueqiuChannel().get_hot_posts(limit=10)
- assert len(posts) == 2
- assert posts[0]["id"] == 111
- assert posts[0]["author"] == "投资者A"
- assert posts[0]["likes"] == 42
- assert "今天大盘走势&分析" in posts[0]["text"] # HTML stripped
- assert "<p>" not in posts[0]["text"]
- assert posts[0]["url"] == "https://xueqiu.com/1234567890/111"
-
- def test_get_hot_posts_respects_limit(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- fake_data = {
- "list": [
- {
- "data": json.dumps({
- "id": i,
- "title": f"Post {i}",
- "text": f"Content {i}",
- "user": {"screen_name": f"User {i}"},
- "like_count": i,
- "target": f"/user/{i}",
- }),
- "original_status": None,
- }
- for i in range(10)
- ]
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- posts = XueqiuChannel().get_hot_posts(limit=3)
- assert len(posts) == 3
-
- # ------------------------------------------------------------------ #
- # get_hot_stocks
- # ------------------------------------------------------------------ #
-
- def test_get_hot_stocks(self, monkeypatch):
- import agent_reach.channels.xueqiu as xueqiu_mod
-
- monkeypatch.setattr(xueqiu_mod, "_cookies_initialized", True)
-
- fake_data = {
- "data": {
- "items": [
- {"code": "SH600519", "name": "贵州茅台", "current": 1800.0, "percent": 1.5},
- {"code": "SZ000858", "name": "五粮液", "current": 160.0, "percent": -0.8},
- {"code": "SH601318", "name": "中国平安", "current": 45.0, "percent": 0.3},
- ]
- }
- }
-
- class FakeResponse:
- def __enter__(self):
- return self
-
- def __exit__(self, *_):
- pass
-
- def read(self):
- return json.dumps(fake_data).encode()
-
- monkeypatch.setattr(xueqiu_mod._opener, "open", lambda req, timeout=None: FakeResponse())
- stocks = XueqiuChannel().get_hot_stocks(limit=10, stock_type=10)
- assert len(stocks) == 3
- assert stocks[0]["symbol"] == "SH600519"
- assert stocks[0]["rank"] == 1
- assert stocks[1]["percent"] == -0.8
- assert stocks[2]["rank"] == 3
-
- # ------------------------------------------------------------------ #
- # Cookie loading
- # ------------------------------------------------------------------ #
-
def test_ensure_cookies_loads_from_config(self, monkeypatch, tmp_path):
"""_ensure_cookies() should inject cookies from the config file."""
import agent_reach.channels.xueqiu as xueqiu_mod
@@ -793,78 +152,8 @@ class TestXueqiuChannel:
assert "agent-reach" not in captured["ua"]
-class TestRedditChannel:
- """多后端:OpenCLI > rdt-cli,没有零配置路径。"""
-
- @staticmethod
- def _isolate(monkeypatch, opencli=None):
- """隔离 OpenCLI 候选(None = 未安装),聚焦 rdt-cli 路径。"""
- from agent_reach.channels.reddit import RedditChannel
- monkeypatch.setattr(RedditChannel, "_check_opencli", lambda self: opencli)
-
- def test_reports_off_when_nothing_installed(self, monkeypatch):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: None)
- from agent_reach.channels.reddit import RedditChannel
- status, msg = RedditChannel().check()
- assert status == "off"
- # 诚实口径:明说没有零配置路径,推荐 OpenCLI + rdt git 源
- assert "零配置" in msg
- assert "opencli" in msg
- assert "git+https://github.com/public-clis/rdt-cli.git" in msg
-
- def test_opencli_ready_wins(self, monkeypatch):
- self._isolate(monkeypatch, opencli=("ok", "OpenCLI 可用(复用浏览器登录态)"))
- monkeypatch.setattr(shutil, "which", lambda _: None)
- from agent_reach.channels.reddit import RedditChannel
- ch = RedditChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "OpenCLI"
-
- def test_saved_rdt_cookie_is_unverified_not_active(
- self, monkeypatch, isolated_home
- ):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/rdt")
- credential_path = (
- isolated_home / ".config" / "rdt-cli" / "credential.json"
- )
- credential_path.parent.mkdir(parents=True)
- credential_path.write_text(
- json.dumps(
- {
- "cookies": {"reddit_session": "explicit"},
- "saved_at": __import__("time").time(),
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute rdt status"
- ),
- )
- from agent_reach.channels.reddit import RedditChannel
- ch = RedditChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "未实时验证" in msg
- assert ch.active_backend is None
-
- def test_reports_warn_when_cookie_is_missing(self, monkeypatch):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/rdt")
- from agent_reach.channels.reddit import RedditChannel
- ch = RedditChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "Cookie-Editor" in msg
- assert "chromewebstore.google.com" in msg
- assert ch.active_backend is None
+class TestRedditChannel:
def test_can_handle_reddit_urls(self):
from agent_reach.channels.reddit import RedditChannel
ch = RedditChannel()
@@ -872,951 +161,3 @@ class TestRedditChannel:
assert ch.can_handle("https://redd.it/abc123")
assert not ch.can_handle("https://github.com/user/repo")
assert not ch.can_handle("https://v2ex.com/t/123")
-
-
-class TestXiaoHongShuChannel:
- """多后端选择逻辑:OpenCLI > xiaohongshu-mcp > xhs-cli,第一个完整可用者获胜。"""
-
- @staticmethod
- def _isolate(monkeypatch, opencli=None, mcp_reachable=False):
- """隔离 OpenCLI / mcp 候选,让测试聚焦目标后端。
-
- opencli: None 表示未安装;否则传入 (status, message) 二元组。
- """
- import agent_reach.channels.xiaohongshu as xhs_mod
-
- monkeypatch.setattr(
- XiaoHongShuChannel, "_check_opencli", lambda self: opencli
- )
- monkeypatch.setattr(
- xhs_mod, "_mcp_service_reachable", lambda timeout=3: mcp_reachable
- )
-
- def test_opencli_bridge_ready_is_unverified(self, monkeypatch):
- monkeypatch.setattr(
- "agent_reach.backends.opencli_status",
- lambda: OpenCLIStatus(
- installed=True,
- extension_connected=True,
- version="1.8.6",
- ),
- )
-
- status, message = XiaoHongShuChannel()._check_opencli()
-
- assert status == "warn"
- assert "桥接已连接" in message
- assert "登录态和实际命令未实时验证" in message
-
- def test_saved_cli_cookie_is_unverified_not_active(
- self, monkeypatch, isolated_home
- ):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
- cookie_path = isolated_home / ".xiaohongshu-cli" / "cookies.json"
- cookie_path.parent.mkdir()
- cookie_path.write_text(
- json.dumps(
- {"a1": "explicit", "saved_at": __import__("time").time()}
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute xhs status"
- ),
- )
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "未实时验证" in msg
- assert ch.active_backend is None
-
- def test_saved_cli_cookie_refuses_ancestor_symlink(
- self, monkeypatch, isolated_home
- ):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
- victim_dir = isolated_home / "victim-xhs"
- victim_dir.mkdir()
- (victim_dir / "cookies.json").write_text(
- json.dumps({"a1": "do-not-read"}),
- encoding="utf-8",
- )
- (isolated_home / ".xiaohongshu-cli").symlink_to(
- victim_dir,
- target_is_directory=True,
- )
-
- status, message = XiaoHongShuChannel()._check_xhs_cli()
-
- assert status == "warn"
- assert "符号链接" in message
-
- def test_reports_warn_when_not_authenticated(self, monkeypatch):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 1, "", "ok: false\nerror:\n code: not_authenticated\n")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "Cookie-Editor" in msg
- assert "configure xhs-cookies" in msg
- assert ch.active_backend is None
-
- def test_reports_off_when_nothing_installed(self, monkeypatch):
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: None)
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "off"
- # off 指引推荐当代后端,而非停更的 xhs-cli
- assert "opencli" in msg
- assert "xiaohongshu-mcp" in msg
- assert ch.active_backend is None
-
- def test_opencli_ready_wins_over_cli(self, monkeypatch):
- """OpenCLI 完整可用时按序获胜,即使 xhs-cli 也完整可用。"""
- self._isolate(monkeypatch, opencli=("ok", "OpenCLI 可用(复用浏览器登录态)"))
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 0, "ok: true\n", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "OpenCLI"
-
- def test_opencli_warn_remains_first_when_cli_is_only_unverified(
- self, monkeypatch
- ):
- self._isolate(monkeypatch, opencli=("warn", "扩展未连接"))
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 0, "ok: true\n", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert msg == "扩展未连接"
- assert ch.active_backend is None
-
- def test_mcp_service_wins_when_opencli_absent(
- self, monkeypatch, tmp_path
- ):
- """服务器场景:OpenCLI 未装、mcp 服务可达且 mcporter 已接入 → mcp 获胜。"""
- self._isolate(monkeypatch, mcp_reachable=True)
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {"xiaohongshu": {"baseUrl": "http://local"}},
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
-
- def fake_which(name):
- return "/usr/local/bin/mcporter" if name == "mcporter" else None
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert ch.active_backend is None
- assert "未验证登录态" in msg
-
- def test_mcp_reachable_but_mcporter_unconfigured_warns(
- self, monkeypatch, tmp_path
- ):
- self._isolate(monkeypatch, mcp_reachable=True)
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {"exa": {"baseUrl": "https://example.test"}},
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
-
- def fake_which(name):
- return "/usr/local/bin/mcporter" if name == "mcporter" else None
-
- monkeypatch.setattr(shutil, "which", fake_which)
-
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
-
- ch = XiaoHongShuChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "mcporter config add xiaohongshu" in msg
- assert ch.active_backend is None
-
- def test_mcp_metadata_containing_xiaohongshu_is_not_configured(
- self, monkeypatch, tmp_path
- ):
- """Paths and URLs are not valid server-name health signals."""
- self._isolate(monkeypatch, mcp_reachable=True)
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- "unrelated": {
- "baseUrl": "http://xiaohongshu-project.test/mcp"
- }
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/usr/local/bin/mcporter"
- if name == "mcporter"
- else None,
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
-
- ch = XiaoHongShuChannel()
- status, message = ch.check()
-
- assert status == "warn"
- assert "未接入" in message
- assert ch.active_backend is None
-
- def test_all_xhs_auth_hints_exclude_qr_and_automatic_cookie_read(
- self, monkeypatch
- ):
- """XHS remediation must remain on the explicit Cookie-Editor path."""
- self._isolate(monkeypatch)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, **kwargs: subprocess.CompletedProcess(
- cmd, 1, "", "not_authenticated"
- ),
- )
-
- status, message = XiaoHongShuChannel().check()
-
- assert status == "warn"
- assert "Cookie-Editor" in message
- assert "configure xhs-cookies" in message
- assert "扫码" not in message
- assert "自动从浏览器" not in message
-
- def test_unverified_cli_override_cannot_hide_working_opencli(
- self, monkeypatch
- ):
- self._isolate(monkeypatch, opencli=("ok", "OpenCLI 可用"))
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/xhs")
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 0, "ok: true\n", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- class _Cfg:
- def get(self, key, default=None):
- return "xhs-cli" if key == "xiaohongshu_backend" else default
-
- ch = XiaoHongShuChannel()
- status, _ = ch.check(_Cfg())
- assert status == "ok"
- assert ch.active_backend == "OpenCLI"
-
-
-class TestBilibiliChannel:
- """多后端:bili-cli > OpenCLI > 搜索 API。yt-dlp 已退出 B站(412 实锤)。"""
-
- @staticmethod
- def _isolate(monkeypatch, opencli=None, api_ok=False):
- import agent_reach.channels.bilibili as bilibili_mod
- monkeypatch.setattr(
- bilibili_mod.BilibiliChannel, "_check_opencli", lambda self: opencli
- )
- monkeypatch.setattr(bilibili_mod, "_search_api_ok", lambda: api_ok)
-
- def test_bili_cli_ok_is_active_backend(self, monkeypatch):
- self._isolate(monkeypatch)
- monkeypatch.setattr(
- shutil, "which",
- lambda cmd: "/usr/local/bin/bili" if cmd == "bili" else None,
- )
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 0, "bili, version 0.6.2", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert "bili-cli 可用" in msg
- assert ch.active_backend == "bili-cli"
-
- def test_opencli_bridge_ready_is_unverified(self, monkeypatch):
- monkeypatch.setattr(
- "agent_reach.backends.opencli_status",
- lambda: OpenCLIStatus(
- installed=True,
- extension_connected=True,
- version="1.8.6",
- ),
- )
-
- status, message = BilibiliChannel()._check_opencli()
-
- assert status == "warn"
- assert "桥接已连接" in message
- assert "实际命令未实时验证" in message
-
- def test_bili_broken_falls_back_to_api_with_hint_kept(self, monkeypatch):
- """bili 断链 → API 兜底获胜,但重装处方必须保留在消息里。"""
- self._isolate(monkeypatch, api_ok=True)
- monkeypatch.setattr(
- shutil, "which",
- lambda cmd: "/usr/local/bin/bili" if cmd == "bili" else None,
- )
-
- def fake_run(cmd, **kwargs):
- raise FileNotFoundError(cmd[0])
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "ok" # 搜索 API 兜底
- assert ch.active_backend == "B站搜索 API"
- assert "备选后端异常" in msg
- assert "pipx reinstall bilibili-cli" in msg
-
- def test_bili_broken_and_no_fallback_reports_error(self, monkeypatch):
- self._isolate(monkeypatch, api_ok=False)
- monkeypatch.setattr(
- shutil, "which",
- lambda cmd: "/usr/local/bin/bili" if cmd == "bili" else None,
- )
-
- def fake_run(cmd, **kwargs):
- raise FileNotFoundError(cmd[0])
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "error"
- assert "uv tool install --force bilibili-cli" in msg
- assert ch.active_backend is None
-
- def test_unverified_opencli_falls_back_to_verified_api(self, monkeypatch):
- self._isolate(
- monkeypatch,
- opencli=("warn", "OpenCLI 桥接已连接但未验证"),
- api_ok=True,
- )
- monkeypatch.setattr(shutil, "which", lambda _: None)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "B站搜索 API"
-
- def test_unverified_opencli_alone_has_no_active_backend(self, monkeypatch):
- self._isolate(
- monkeypatch,
- opencli=("warn", "OpenCLI 桥接已连接但未验证"),
- api_ok=False,
- )
- monkeypatch.setattr(shutil, "which", lambda _: None)
-
- ch = BilibiliChannel()
- status, _ = ch.check()
-
- assert status == "warn"
- assert ch.active_backend is None
-
- def test_api_only_still_ok_with_install_nudge(self, monkeypatch):
- self._isolate(monkeypatch, api_ok=True)
- monkeypatch.setattr(shutil, "which", lambda _: None)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "B站搜索 API"
- assert "bilibili-cli" in msg
-
- def test_off_when_everything_unreachable(self, monkeypatch):
- self._isolate(monkeypatch, api_ok=False)
- monkeypatch.setattr(shutil, "which", lambda _: None)
- from agent_reach.channels.bilibili import BilibiliChannel
- ch = BilibiliChannel()
- status, msg = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
-
-class TestYouTubeChannel:
- def test_reports_error_with_reinstall_hint_when_broken(self, monkeypatch):
- """yt-dlp which 命中但 exec 抛 FileNotFoundError → error + 重装处方。"""
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/yt-dlp")
-
- def fake_run(cmd, **kwargs):
- raise FileNotFoundError(cmd[0])
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.youtube import YouTubeChannel
- ch = YouTubeChannel()
- status, msg = ch.check()
- assert status == "error"
- assert "无法执行" in msg
- assert "uv tool install --force yt-dlp" in msg
- assert ch.active_backend is None
-
-
-class TestGitHubChannel:
- def test_reports_error_with_reinstall_hint_when_broken(self, monkeypatch):
- """gh --version 断链时给出二进制重装处方。"""
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/gh")
-
- def fake_run(cmd, **kwargs):
- assert cmd[-1:] == ["--version"]
- raise FileNotFoundError(cmd[0])
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.github import GitHubChannel
- ch = GitHubChannel()
- status, msg = ch.check()
- assert status == "error"
- assert "无法执行" in msg
- assert "brew reinstall gh" in msg
- assert ch.active_backend is None
-
- def test_explicit_auth_is_unverified_and_never_marked_active(
- self, monkeypatch
- ):
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/gh")
- monkeypatch.setenv("GH_TOKEN", "configured-secret")
-
- def fake_run(cmd, **kwargs):
- assert cmd[-1:] == ["--version"]
- assert "auth" not in cmd
- assert kwargs["env"]["GH_TELEMETRY"] == "false"
- assert kwargs["env"]["DO_NOT_TRACK"] == "true"
- return subprocess.CompletedProcess(cmd, 0, "gh version 2.92.0", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.github import GitHubChannel
- ch = GitHubChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "显式认证配置" in msg
- assert "configured-secret" not in msg
- assert ch.active_backend is None
-
- def test_no_auth_metadata_remains_warn_and_inactive(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/gh")
- monkeypatch.delenv("GH_TOKEN", raising=False)
- monkeypatch.delenv("GITHUB_TOKEN", raising=False)
-
- def fake_run(cmd, **kwargs):
- assert cmd[-1:] == ["--version"]
- assert "auth" not in cmd
- return subprocess.CompletedProcess(cmd, 0, "gh version 2.92.0", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.github import GitHubChannel
- ch = GitHubChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "gh auth login" in msg
- assert ch.active_backend is None
-
- def test_hosts_metadata_is_read_without_exposing_token(
- self, monkeypatch, isolated_home
- ):
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/gh")
- monkeypatch.delenv("GH_TOKEN", raising=False)
- monkeypatch.delenv("GITHUB_TOKEN", raising=False)
- hosts = isolated_home / ".config" / "gh" / "hosts.yml"
- hosts.parent.mkdir(parents=True)
- hosts.write_text(
- "github.com:\n"
- " user: alice\n"
- " oauth_token: super-secret-token\n",
- encoding="utf-8",
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, **kwargs: subprocess.CompletedProcess(
- cmd, 0, "gh version 2.92.0", ""
- ),
- )
-
- from agent_reach.channels.github import GitHubChannel
-
- status, message = GitHubChannel().check()
-
- assert status == "warn"
- assert "显式认证配置" in message
- assert "alice" not in message
- assert "super-secret-token" not in message
-
- def test_hosts_metadata_refuses_ancestor_symlink(
- self, monkeypatch, isolated_home
- ):
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/gh")
- monkeypatch.delenv("GH_TOKEN", raising=False)
- monkeypatch.delenv("GITHUB_TOKEN", raising=False)
- real_config = isolated_home / "real-config"
- hosts = real_config / "gh" / "hosts.yml"
- hosts.parent.mkdir(parents=True)
- hosts.write_text(
- "github.com:\n oauth_token: do-not-read\n",
- encoding="utf-8",
- )
- (isolated_home / ".config").symlink_to(
- real_config,
- target_is_directory=True,
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda cmd, **kwargs: subprocess.CompletedProcess(
- cmd, 0, "gh version 2.92.0", ""
- ),
- )
-
- from agent_reach.channels.github import GitHubChannel
-
- channel = GitHubChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert "无法安全确认" in message
- assert "do-not-read" not in message
- assert channel.active_backend is None
-
-
-class TestLinkedInChannel:
- def test_setup_hint_uses_current_stdio_contract(self, monkeypatch):
- monkeypatch.setattr(shutil, "which", lambda _: None)
-
- from agent_reach.channels.linkedin import LinkedInChannel
-
- channel = LinkedInChannel()
- status, message = channel.check()
-
- assert status == "off"
- assert channel.backends[0] == "mcp-server-linkedin"
- assert "docs.astral.sh/uv/getting-started/installation" in message
- assert "uvx mcp-server-linkedin@latest --login" in message
- assert (
- "mcporter config add linkedin --command uvx "
- "--arg mcp-server-linkedin@latest --env UV_HTTP_TIMEOUT=300 "
- "--scope home"
- ) in message
- assert "pip install linkedin-scraper-mcp" not in message
- assert "localhost:3000/mcp" not in message
-
- def test_configured_linkedin_warns_when_uvx_is_missing(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- "linkedin": {
- "command": "uvx",
- "args": ["mcp-server-linkedin@latest"],
- }
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/usr/local/bin/mcporter"
- if name == "mcporter"
- else None,
- )
-
- from agent_reach.channels.linkedin import LinkedInChannel
-
- status, message = LinkedInChannel().check()
-
- assert status == "warn"
- assert "uvx 未安装" in message
- assert "docs.astral.sh/uv/getting-started/installation" in message
-
- def test_mcporter_is_never_executed(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
- from agent_reach.channels.linkedin import LinkedInChannel
- ch = LinkedInChannel()
- status, msg = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
- @pytest.mark.parametrize(
- "server_name",
- [
- "linkedin",
- "linkedin-scraper",
- "linkedin-scraper-mcp",
- "mcp-server-linkedin",
- ],
- )
- def test_configured_linkedin_name_is_not_false_positive_active(
- self, monkeypatch, tmp_path, server_name
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- server_name: {"command": "linkedin-mcp"}
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
- from agent_reach.channels.linkedin import LinkedInChannel
- ch = LinkedInChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "未启动" in msg
- assert ch.active_backend is None
-
- def test_config_metadata_containing_linkedin_is_not_a_backend(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- "unrelated": {
- "baseUrl": "http://linkedin-project.test/mcp"
- }
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- from agent_reach.channels.linkedin import LinkedInChannel
-
- ch = LinkedInChannel()
- status, _ = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
- def test_off_without_backend_when_linkedin_not_configured(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {"exa": {"baseUrl": "https://example.test"}},
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- from agent_reach.channels.linkedin import LinkedInChannel
- ch = LinkedInChannel()
- status, msg = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
-
-class TestExaSearchChannel:
- def test_mcporter_is_never_executed(self, monkeypatch, tmp_path):
- monkeypatch.chdir(tmp_path)
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
- from agent_reach.channels.exa_search import ExaSearchChannel
- ch = ExaSearchChannel()
- status, msg = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
- def test_configured_exa_is_not_false_positive_active(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- "exa": {"baseUrl": "https://mcp.example.test"}
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- from agent_reach.channels.exa_search import ExaSearchChannel
- ch = ExaSearchChannel()
- status, msg = ch.check()
- assert status == "warn"
- assert "未启动" in msg
- assert ch.active_backend is None
-
- def test_config_metadata_containing_exa_is_not_a_backend(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps(
- {
- "mcpServers": {
- "unrelated": {
- "baseUrl": "https://example.test/exa-project"
- }
- },
- "imports": [],
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- from agent_reach.channels.exa_search import ExaSearchChannel
-
- ch = ExaSearchChannel()
- status, _ = ch.check()
- assert status == "off"
- assert ch.active_backend is None
-
- def test_invalid_mcporter_json_is_reported_as_error_not_unconfigured(
- self, monkeypatch, tmp_path
- ):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text("not-json", encoding="utf-8")
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/mcporter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "Doctor must not execute mcporter"
- ),
- )
- from agent_reach.channels.exa_search import ExaSearchChannel
-
- ch = ExaSearchChannel()
- status, message = ch.check()
- assert status == "error"
- assert "JSON" in message
- assert ch.active_backend is None
-
-
-class TestXiaoyuzhouChannel:
- def test_reports_error_with_reinstall_hint_when_ffmpeg_broken(self, monkeypatch):
- """ffmpeg which 命中但 exec 失败(pip 假 ffmpeg 断链)→ error + 重装处方。"""
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/ffmpeg")
-
- def fake_run(cmd, **kwargs):
- raise FileNotFoundError(cmd[0])
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- from agent_reach.channels.xiaoyuzhou import XiaoyuzhouChannel
- ch = XiaoyuzhouChannel()
- status, msg = ch.check()
- assert status == "error"
- assert "无法执行" in msg
- assert "brew install ffmpeg" in msg
- assert ch.active_backend is None
-
- def test_active_backend_set_when_fully_configured(self, monkeypatch):
- monkeypatch.setattr(shutil, "which", lambda _: "/usr/local/bin/ffmpeg")
-
- def fake_run(cmd, **kwargs):
- return subprocess.CompletedProcess(cmd, 0, "ffmpeg version 7.0", "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- monkeypatch.setattr("os.path.isfile", lambda p: True) # transcribe.sh 已安装
- monkeypatch.setenv("GROQ_API_KEY", "gsk_test")
- from agent_reach.channels.xiaoyuzhou import XiaoyuzhouChannel
- ch = XiaoyuzhouChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "groq-whisper"
-
-
-class TestRSSChannel:
- """can_handle URL patterns + the three check() branches (ok / off / error)."""
-
- def test_can_handle_feed_urls(self):
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- assert ch.can_handle("https://example.com/feed")
- assert ch.can_handle("https://example.com/rss")
- assert ch.can_handle("https://example.com/feed.xml")
- assert ch.can_handle("https://blog.example.com/atom.xml")
- assert ch.can_handle("https://example.com/index.atom")
-
- def test_can_handle_is_case_insensitive(self):
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- assert ch.can_handle("https://example.com/FEED")
- assert ch.can_handle("https://example.com/Atom.XML")
-
- def test_can_handle_rejects_non_feed_urls(self):
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- assert not ch.can_handle("https://github.com/user/repo")
- assert not ch.can_handle("https://example.com/blog/post-1")
- assert not ch.can_handle("https://v2ex.com/t/123")
-
- def test_check_ok_when_feedparser_importable(self, monkeypatch):
- import sys
- import types
-
- monkeypatch.setitem(sys.modules, "feedparser", types.ModuleType("feedparser"))
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- status, msg = ch.check()
- assert status == "ok"
- assert ch.active_backend == "feedparser"
-
- def test_check_off_when_feedparser_missing(self, monkeypatch):
- """feedparser not installed → off + pip install prescription."""
- import sys
-
- # None in sys.modules makes `import feedparser` raise ImportError
- monkeypatch.setitem(sys.modules, "feedparser", None)
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- status, msg = ch.check()
- assert status == "off"
- assert "pip install feedparser" in msg
- assert ch.active_backend is None
-
- def test_check_error_when_import_crashes(self, monkeypatch):
- """Installed but crashes at import time (half-broken install) → error + reinstall prescription."""
- import builtins
-
- real_import = builtins.__import__
-
- def crashing_import(name, *args, **kwargs):
- if name == "feedparser":
- raise RuntimeError("broken install")
- return real_import(name, *args, **kwargs)
-
- monkeypatch.setattr(builtins, "__import__", crashing_import)
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- status, msg = ch.check()
- assert status == "error"
- assert "--force-reinstall" in msg
- assert ch.active_backend is None
-
- def test_check_failure_resets_stale_active_backend(self, monkeypatch):
- """A previously healthy instance must not keep a stale active_backend."""
- import sys
-
- from agent_reach.channels.rss import RSSChannel
- ch = RSSChannel()
- ch.active_backend = "feedparser" # pretend an earlier check() succeeded
- monkeypatch.setitem(sys.modules, "feedparser", None)
- status, _ = ch.check()
- assert status == "off"
- assert ch.active_backend is None
diff --git a/tests/test_cli.py b/tests/test_cli.py
deleted file mode 100644
index aaca7a4b..00000000
--- a/tests/test_cli.py
+++ /dev/null
@@ -1,500 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for Agent Reach CLI."""
-
-import shutil
-import subprocess
-from argparse import Namespace
-from unittest.mock import patch
-
-import pytest
-import requests
-
-import agent_reach.cli as cli
-from agent_reach.cli import main
-from agent_reach.config import Config
-
-
-class TestCLI:
- def test_version(self, capsys):
- with pytest.raises(SystemExit) as exc_info:
- with patch("sys.argv", ["agent-reach", "version"]):
- main()
- assert exc_info.value.code == 0
- captured = capsys.readouterr()
- assert "Agent Reach v" in captured.out
-
- def test_no_command_shows_help(self, capsys):
- with pytest.raises(SystemExit) as exc_info:
- with patch("sys.argv", ["agent-reach"]):
- main()
- assert exc_info.value.code == 0
-
- def test_doctor_runs(self, capsys):
- with patch(
- "agent_reach.doctor.check_all",
- return_value={
- "web": {
- "status": "ok",
- "name": "网页",
- "message": "可用",
- "tier": 0,
- "backends": ["Jina Reader"],
- "active_backend": "Jina Reader",
- }
- },
- ), patch(
- "agent_reach.doctor.format_report",
- return_value="Agent Reach\n✅ 网页可用",
- ), patch("sys.argv", ["agent-reach", "doctor"]):
- main()
- captured = capsys.readouterr()
- assert "Agent Reach" in captured.out
- assert "✅" in captured.out
-
- def test_doctor_is_read_only_and_never_installs_skill(
- self, monkeypatch, tmp_path, capsys
- ):
- skill_dir = tmp_path / ".agents" / "skills" / "agent-reach"
- skill_dir.mkdir(parents=True)
- skill_file = skill_dir / "SKILL.md"
- custom_content = "# custom Agent Reach skill\n"
- skill_file.write_text(custom_content, encoding="utf-8")
-
- monkeypatch.setattr(
- cli.os.path,
- "expanduser",
- lambda p: p.replace("~", str(tmp_path)),
- )
- config_dir = tmp_path / ".agent-reach"
- monkeypatch.setattr(Config, "CONFIG_DIR", config_dir)
- monkeypatch.setattr(Config, "CONFIG_FILE", config_dir / "config.yaml")
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda config: {})
- monkeypatch.setattr("agent_reach.doctor.format_report", lambda results: "report")
- install_calls = []
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda *args, **kwargs: install_calls.append((args, kwargs)),
- )
-
- cli._cmd_doctor(Namespace(json=False))
-
- assert skill_file.read_text(encoding="utf-8") == custom_content
- assert install_calls == []
- assert not config_dir.exists()
- out = capsys.readouterr().out
- assert "report" in out
- assert "Skill installed" not in out
- assert "preserving existing files" not in out
- assert f"Skill installed for Agent: {skill_dir}" not in out
-
- def test_transcribe_command_prints_text(self, capsys):
- with patch("agent_reach.transcribe.transcribe", return_value="hello transcript"):
- with patch("sys.argv", ["agent-reach", "transcribe", "audio.mp3"]):
- main()
- captured = capsys.readouterr()
- assert "hello transcript" in captured.out
-
- def test_transcribe_command_writes_output_file(self, capsys, tmp_path):
- out_file = tmp_path / "t.txt"
- with patch("agent_reach.transcribe.transcribe", return_value="saved text"):
- with patch("sys.argv", ["agent-reach", "transcribe", "audio.mp3", "-o", str(out_file)]):
- main()
- assert out_file.read_text(encoding="utf-8").strip() == "saved text"
- assert "Transcript written" in capsys.readouterr().out
-
- def test_transcribe_provider_fallback_requires_explicit_flag(self):
- with patch(
- "agent_reach.transcribe.transcribe",
- return_value="hello transcript",
- ) as mock_transcribe:
- with patch(
- "sys.argv",
- [
- "agent-reach",
- "transcribe",
- "audio.mp3",
- "--allow-provider-fallback",
- ],
- ):
- main()
-
- mock_transcribe.assert_called_once_with(
- "audio.mp3",
- provider="auto",
- allow_provider_fallback=True,
- )
-
- def test_transcribe_provider_fallback_rejects_explicit_provider(self, capsys):
- with patch("agent_reach.transcribe.transcribe") as mock_transcribe:
- with patch(
- "sys.argv",
- [
- "agent-reach",
- "transcribe",
- "audio.mp3",
- "--provider",
- "groq",
- "--allow-provider-fallback",
- ],
- ):
- with pytest.raises(SystemExit) as exc_info:
- main()
-
- assert exc_info.value.code == 2
- assert "requires --provider auto" in capsys.readouterr().err
- mock_transcribe.assert_not_called()
-
- def test_parse_twitter_cookie_input_separate_values(self):
- auth_token, ct0 = cli._parse_twitter_cookie_input("token123 ct0abc")
- assert auth_token == "token123"
- assert ct0 == "ct0abc"
-
- def test_parse_twitter_cookie_input_cookie_header(self):
- auth_token, ct0 = cli._parse_twitter_cookie_input(
- "auth_token=token123; ct0=ct0abc; other=value"
- )
- assert auth_token == "token123"
- assert ct0 == "ct0abc"
-
- def test_twitter_config_does_not_run_unsafe_verification_or_mutate_env(
- self, monkeypatch, capsys
- ):
- monkeypatch.setenv("TWITTER_AUTH_TOKEN", "shell-auth")
- monkeypatch.setenv("TWITTER_CT0", "shell-ct0")
- monkeypatch.setattr(shutil, "which", lambda name: "/bin/twitter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "configure must not execute twitter status"
- ),
- )
-
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="twitter-cookies",
- value=["saved-auth", "saved-ct0"],
- sync_legacy_twitter=False,
- )
- )
-
- output = capsys.readouterr().out
- assert "未实时验证" in output
- assert "不会执行 `twitter status`" in output
- assert cli.os.environ["TWITTER_AUTH_TOKEN"] == "shell-auth"
- assert cli.os.environ["TWITTER_CT0"] == "shell-ct0"
-
- def test_install_rdt_cli_prefers_github_source(self, monkeypatch, capsys):
- state = {"rdt_installed": False}
- commands = []
-
- def fake_which(name):
- if name == "rdt":
- return "/usr/local/bin/rdt" if state["rdt_installed"] else None
- if name == "pipx":
- return "/usr/local/bin/pipx"
- return None
-
- def fake_run(cmd, **kwargs):
- commands.append(cmd)
- state["rdt_installed"] = True
- return subprocess.CompletedProcess(cmd, 0, "", "")
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_rdt_cli()
-
- out = capsys.readouterr().out
- assert commands == [["/usr/local/bin/pipx", "install", cli._RDT_GIT_SOURCE]]
- assert "✅ rdt-cli installed" in out
-
- def test_install_boss_deps_pins_pr_commit_with_pipx(self, monkeypatch, capsys):
- state = {"boss_installed": False}
- commands = []
-
- def fake_which(name):
- if name == "boss":
- return "/usr/local/bin/boss" if state["boss_installed"] else None
- if name == "pipx":
- return "/usr/local/bin/pipx"
- return None
-
- def fake_run(cmd, **kwargs):
- commands.append(cmd)
- state["boss_installed"] = True
- return subprocess.CompletedProcess(cmd, 0, "", "")
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- assert cli._install_boss_deps() is True
-
- assert commands == [
- [
- "/usr/local/bin/pipx",
- "install",
- "--force",
- cli._BOSS_AGENT_CLI_SOURCE,
- ]
- ]
- assert cli._BOSS_AGENT_CLI_PR_COMMIT in cli._BOSS_AGENT_CLI_SOURCE
- assert cli._BOSS_AGENT_CLI_PR_COMMIT == "4c991b77086a203173bf08a4cb64a23af6514fe6"
- assert "can4hou6joeng4/boss-agent-cli" in cli._BOSS_AGENT_CLI_SOURCE
- assert "iqjiy" not in cli._BOSS_AGENT_CLI_SOURCE
- assert "boss-agent-cli upstream pinned commit" in capsys.readouterr().out
-
- def test_install_boss_deps_falls_back_to_uv(self, monkeypatch):
- state = {"boss_installed": False}
- commands = []
-
- def fake_which(name):
- if name == "boss":
- return "/usr/local/bin/boss" if state["boss_installed"] else None
- if name == "uv":
- return "/usr/local/bin/uv"
- return None
-
- def fake_run(cmd, **kwargs):
- commands.append(cmd)
- state["boss_installed"] = True
- return subprocess.CompletedProcess(cmd, 0, "", "")
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- assert cli._install_boss_deps() is True
- assert commands == [
- [
- "/usr/local/bin/uv",
- "tool",
- "install",
- "--force",
- cli._BOSS_AGENT_CLI_SOURCE,
- ]
- ]
-
- def test_install_reddit_deps_routes_by_environment(self, monkeypatch):
- """桌面 → OpenCLI;服务器 → rdt-cli(钉 git 源)。"""
- calls = []
- monkeypatch.setattr(cli, "_install_opencli_deps", lambda: calls.append("opencli"))
- monkeypatch.setattr(cli, "_install_rdt_cli", lambda: calls.append("rdt"))
- monkeypatch.setattr(shutil, "which", lambda _: None)
-
- monkeypatch.setattr(cli, "_detect_environment", lambda: "local")
- cli._install_reddit_deps()
- assert calls == ["opencli"]
-
- calls.clear()
- monkeypatch.setattr(cli, "_detect_environment", lambda: "server")
- cli._install_reddit_deps()
- assert calls == ["rdt"]
-
- def test_install_opencli_uses_resolved_windows_npm_path(self, monkeypatch):
- import agent_reach.backends as backends
- from agent_reach.backends import OpenCLIStatus
-
- statuses = iter(
- [
- OpenCLIStatus(installed=False),
- OpenCLIStatus(installed=True, extension_connected=False),
- ]
- )
- calls = []
- monkeypatch.setattr(backends, "opencli_status", lambda: next(statuses))
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "C:/Tools/npm.CMD" if name == "npm" else None,
- )
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda args, **_kwargs: calls.append(args)
- or subprocess.CompletedProcess(args, 0, "", ""),
- )
-
- assert cli._install_opencli_deps() is True
- assert calls == [
- ["C:/Tools/npm.CMD", "install", "-g", backends.OPENCLI_PACKAGE]
- ]
-
- def test_install_facebook_instagram_routes_to_opencli_once(self, monkeypatch, capsys):
- calls = []
-
- monkeypatch.setattr(cli, "_detect_environment", lambda: "local")
- monkeypatch.setattr(cli, "_install_system_deps", lambda: None)
- monkeypatch.setattr(cli, "_install_mcporter", lambda: None)
- monkeypatch.setattr(cli, "_install_opencli_deps", lambda: calls.append("opencli"))
- monkeypatch.setattr(cli, "_install_skill", lambda: None)
- monkeypatch.setattr(
- "agent_reach.doctor.check_all",
- lambda config: {
- "facebook": {
- "status": "ok",
- "name": "Facebook",
- "message": "ok",
- "tier": 1,
- "backends": ["OpenCLI"],
- "active_backend": "OpenCLI",
- }
- },
- )
- monkeypatch.setattr("agent_reach.doctor.format_report", lambda results: "report")
-
- cli._cmd_install(
- Namespace(
- env="auto",
- proxy="",
- system=True,
- safe=False,
- dry_run=False,
- channels="facebook,instagram,opencli",
- )
- )
-
- assert calls == ["opencli"]
- assert "Installation complete" in capsys.readouterr().out
-
- def test_install_server_dry_run_skips_opencli_only_channels(self, monkeypatch, capsys):
- monkeypatch.setattr(cli, "_install_system_deps_dryrun", lambda: None)
-
- cli._cmd_install(
- Namespace(
- env="server",
- proxy="",
- system=True,
- safe=False,
- dry_run=True,
- channels="facebook,instagram,opencli,boss,bilibili",
- )
- )
-
- out = capsys.readouterr().out
- assert "服务器环境跳过:boss, facebook, instagram, opencli" in out
- assert "[dry-run] Would install optional channels: bilibili" in out
- assert "boss, facebook, instagram, opencli, bilibili" not in out
-
-
-class TestCheckUpdateRetry:
- def test_retry_timeout_classification(self):
- sleeps = []
-
- def fake_sleep(seconds):
- sleeps.append(seconds)
-
- with patch("requests.get", side_effect=requests.exceptions.Timeout("timed out")):
- resp, err, attempts = cli._github_get_with_retry(
- "https://api.github.com/test",
- timeout=1,
- retries=3,
- sleeper=fake_sleep,
- )
-
- assert resp is None
- assert err == "timeout"
- assert attempts == 3
- assert sleeps == [1, 2]
-
- def test_retry_dns_classification(self):
- error = requests.exceptions.ConnectionError("getaddrinfo failed for api.github.com")
- with patch("requests.get", side_effect=error):
- resp, err, attempts = cli._github_get_with_retry(
- "https://api.github.com/test",
- retries=1,
- sleeper=lambda _x: None,
- )
- assert resp is None
- assert err == "dns"
- assert attempts == 1
-
- def test_retry_rate_limit_then_success(self):
- sleeps = []
-
- class R:
- def __init__(self, code, payload=None, headers=None):
- self.status_code = code
- self._payload = payload or {}
- self.headers = headers or {}
-
- def json(self):
- return self._payload
-
- sequence = [
- R(429, headers={"Retry-After": "3"}),
- R(200, payload={"tag_name": "v1.5.0"}),
- ]
-
- with patch("requests.get", side_effect=sequence):
- resp, err, attempts = cli._github_get_with_retry(
- "https://api.github.com/test",
- retries=3,
- sleeper=lambda s: sleeps.append(s),
- )
-
- assert err is None
- assert resp is not None
- assert resp.status_code == 200
- assert attempts == 2
- assert sleeps == [3.0]
-
- def test_classify_rate_limit_from_403(self):
- class R:
- status_code = 403
- headers = {"X-RateLimit-Remaining": "0"}
-
- @staticmethod
- def json():
- return {"message": "API rate limit exceeded"}
-
- assert cli._classify_github_response_error(R()) == "rate_limit"
-
- def test_check_update_reports_classified_error(self, capsys):
- with patch("agent_reach.cli._github_get_with_retry", return_value=(None, "timeout", 3)):
- result = cli._cmd_check_update()
-
- captured = capsys.readouterr()
- assert result == "error"
- assert "网络超时" in captured.out
- assert "已重试 3 次" in captured.out
-
-
-class TestVersionCompare:
- def test_newer_remote_triggers_update(self):
- assert cli._is_newer_version("1.5.0", "1.4.2") is True
-
- def test_equal_versions_no_update(self):
- assert cli._is_newer_version("1.5.0", "1.5.0") is False
-
- def test_local_ahead_of_release_no_downgrade_prompt(self):
- """发版窗口期本地装了 main(更新)时,不能提示"有更新"诱导降级。"""
- assert cli._is_newer_version("1.4.2", "1.5.0") is False
-
- def test_unparseable_falls_back_to_inequality(self):
- assert cli._is_newer_version("2026.06-beta", "1.5.0") is True
- assert cli._is_newer_version("1.5.0", "1.5.0-dev") is True
-
-
-class TestWatchVersionCompare:
- def test_watch_does_not_prompt_downgrade(self, monkeypatch, capsys):
- """watch 与 check-update 同语义:本地领先远端 release 时不提示更新。"""
- class R:
- status_code = 200
- headers = {}
-
- @staticmethod
- def json():
- return {"tag_name": "v1.4.2", "body": ""}
-
- monkeypatch.setattr(cli, "_github_get_with_retry", lambda *a, **k: (R(), None, 1))
- monkeypatch.setattr(
- "agent_reach.doctor.check_all",
- lambda config: {"web": {"status": "ok", "name": "任意网页", "message": "ok",
- "tier": 0, "backends": ["Jina Reader"], "active_backend": "Jina Reader"}},
- )
- cli._cmd_watch()
- out = capsys.readouterr().out
- assert "新版本可用" not in out
- assert "全部正常" in out
diff --git a/tests/test_cookie_extract_perms.py b/tests/test_cookie_extract_perms.py
deleted file mode 100644
index 579ca117..00000000
--- a/tests/test_cookie_extract_perms.py
+++ /dev/null
@@ -1,151 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Verify credential files written by cookie sync helpers and CLI helpers
-are owner-only (0o600) and that values containing shell metacharacters do
-not break the shell-sourceable env file produced by _sync_bird_env().
-
-Companion to tests/test_config.py::test_save_creates_file_with_restricted_permissions —
-the same threat-model claim ("Cookie/Token only stored locally, 600
-permissions") covers these paths.
-"""
-
-import json
-import os
-import stat
-import subprocess
-import sys
-
-import pytest
-
-from agent_reach.cli import _configure_xhs_cookies
-from agent_reach.cookie_extract import _sync_bird_env, _sync_xfetch_session
-
-
-def _owner_only(path: str) -> bool:
- mode = os.stat(path).st_mode
- return not (mode & (stat.S_IRGRP | stat.S_IWGRP | stat.S_IROTH | stat.S_IWOTH))
-
-
-def _owner_only_dir(path: str) -> bool:
- mode = os.stat(path).st_mode
- return not (
- mode
- & (
- stat.S_IRGRP
- | stat.S_IWGRP
- | stat.S_IXGRP
- | stat.S_IROTH
- | stat.S_IWOTH
- | stat.S_IXOTH
- )
- )
-
-
[email protected](sys.platform == "win32", reason="POSIX perm semantics only")
-def test_sync_xfetch_session_writes_0600(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- _sync_xfetch_session("auth_xxx", "ct0_yyy")
- session_path = tmp_path / ".config" / "xfetch" / "session.json"
- assert session_path.exists(), "expected ~/.config/xfetch/session.json"
- assert _owner_only_dir(str(session_path.parent)), "xfetch dir must be 0o700"
- assert _owner_only(str(session_path)), "session.json must be 0o600"
- # Round-trip the content so we know we didn't accidentally corrupt JSON.
- data = json.loads(session_path.read_text(encoding="utf-8"))
- assert data["authToken"] == "auth_xxx"
- assert data["ct0"] == "ct0_yyy"
-
-
[email protected](sys.platform == "win32", reason="POSIX perm semantics only")
-def test_sync_xfetch_session_tightens_existing_file(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- session_path = tmp_path / ".config" / "xfetch" / "session.json"
- session_path.parent.mkdir(parents=True)
- session_path.write_text('{"authToken": "old"}', encoding="utf-8")
- os.chmod(session_path, 0o644)
-
- _sync_xfetch_session("auth_xxx", "ct0_yyy")
-
- assert _owner_only(str(session_path)), "existing session.json must be tightened"
-
-
[email protected](sys.platform == "win32", reason="POSIX perm semantics only")
-def test_sync_bird_env_writes_0600(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- _sync_bird_env("auth_xxx", "ct0_yyy")
- env_path = tmp_path / ".config" / "bird" / "credentials.env"
- assert env_path.exists(), "expected ~/.config/bird/credentials.env"
- assert _owner_only_dir(str(env_path.parent)), "bird dir must be 0o700"
- assert _owner_only(str(env_path)), "credentials.env must be 0o600"
-
-
[email protected](sys.platform == "win32", reason="POSIX perm semantics only")
-def test_sync_bird_env_tightens_existing_file(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- env_path = tmp_path / ".config" / "bird" / "credentials.env"
- env_path.parent.mkdir(parents=True)
- env_path.write_text("AUTH_TOKEN=old\n", encoding="utf-8")
- os.chmod(env_path, 0o644)
-
- _sync_bird_env("auth_xxx", "ct0_yyy")
-
- assert _owner_only(str(env_path)), "existing credentials.env must be tightened"
-
-
[email protected](sys.platform == "win32", reason="POSIX sh needed for sourcing")
-def test_sync_bird_env_quotes_shell_metachars(tmp_path, monkeypatch):
- """Tokens containing ", $, `, ; etc. must not break out of the assignment.
-
- Prior implementation used `f'AUTH_TOKEN="{auth_token}"'` which an attacker-
- controlled cookie containing a literal `"` could break out of, turning a
- later `source ~/.config/bird/credentials.env` into arbitrary shell.
- """
- monkeypatch.setenv("HOME", str(tmp_path))
- # Side-effect markers live under tmp_path (auto-cleaned by pytest) rather
- # than a shared absolute /tmp path — otherwise one vulnerable run leaves a
- # marker behind that fails every later run on the same machine/CI runner.
- pwn_auth = tmp_path / "pwn-auth"
- pwn_ct0 = tmp_path / "pwn-ct0"
- hostile_auth = f'inj"; touch {pwn_auth}; #'
- hostile_ct0 = f"ct0_$(touch {pwn_ct0})"
- _sync_bird_env(hostile_auth, hostile_ct0)
- env_path = tmp_path / ".config" / "bird" / "credentials.env"
-
- # Sourcing the file must NOT execute the injected payload. Read back the
- # exported values from a subshell instead — they should equal the originals.
- probe = (
- f". {env_path}; "
- f'printf "AUTH=%s\\nCT0=%s\\n" "$AUTH_TOKEN" "$CT0"'
- )
- result = subprocess.run(
- ["sh", "-c", probe],
- capture_output=True,
- text=True,
- timeout=5,
- )
- assert result.returncode == 0, result.stderr
- lines = dict(
- line.split("=", 1) for line in result.stdout.strip().splitlines() if "=" in line
- )
- assert lines["AUTH"] == hostile_auth, "auth_token round-trip broke — injection possible"
- assert lines["CT0"] == hostile_ct0, "ct0 round-trip broke — injection possible"
- # And no side-effect files materialised.
- assert not pwn_auth.exists()
- assert not pwn_ct0.exists()
-
-
[email protected](sys.platform == "win32", reason="POSIX perm semantics only")
-def test_configure_xhs_cookies_tightens_local_fallback_file(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setattr("shutil.which", lambda name: None if name == "docker" else name)
-
- cookie_path = tmp_path / ".agent-reach" / "xhs-cookies.json"
- cookie_path.parent.mkdir()
- cookie_path.write_text("[]", encoding="utf-8")
- os.chmod(cookie_path, 0o644)
-
- _configure_xhs_cookies("web_session=xhs_secret")
-
- assert _owner_only_dir(str(cookie_path.parent)), "~/.agent-reach must be 0o700"
- assert _owner_only(str(cookie_path)), "existing xhs-cookies.json must be tightened"
- data = json.loads(cookie_path.read_text(encoding="utf-8"))
- assert data[0]["name"] == "web_session"
- assert data[0]["value"] == "xhs_secret"
diff --git a/tests/test_cookie_security.py b/tests/test_cookie_security.py
deleted file mode 100644
index 0e1ab4c4..00000000
--- a/tests/test_cookie_security.py
+++ /dev/null
@@ -1,222 +0,0 @@
-"""Least-privilege browser-cookie extraction and URL routing regressions."""
-
-from __future__ import annotations
-
-import sys
-from types import SimpleNamespace
-
-import pytest
-
-from agent_reach import cookie_extract
-
-
-class RecordingConfig:
- def __init__(self):
- self.values = {}
-
- def set(self, key, value):
- self.values[key] = value
-
-
-def test_browser_extraction_requires_an_explicit_platform():
- with pytest.raises(ValueError, match="platform"):
- cookie_extract.extract_all("chrome")
-
-
-def test_rookiepy_is_limited_at_source_to_the_requested_platform(monkeypatch):
- calls = []
-
- def chrome(domains):
- calls.append(domains)
- return [
- {"name": "SESSDATA", "value": "session", "domain": ".bilibili.com"},
- {"name": "bili_jct", "value": "csrf", "domain": ".bilibili.com"},
- ]
-
- fake_rookiepy = SimpleNamespace(
- chrome=chrome,
- firefox=lambda domains: [],
- edge=lambda domains: [],
- brave=lambda domains: [],
- opera=lambda domains: [],
- )
- monkeypatch.setitem(sys.modules, "rookiepy", fake_rookiepy)
-
- extracted = cookie_extract.extract_all("chrome", platform="bilibili")
-
- assert calls == [[".bilibili.com"]]
- assert extracted == {
- "bilibili": {"SESSDATA": "session", "bili_jct": "csrf"}
- }
-
-
-def test_xueqiu_collects_only_xq_a_token(monkeypatch):
- def chrome(domains):
- assert domains == [".xueqiu.com"]
- return [
- {"name": "xq_a_token", "value": "needed", "domain": ".xueqiu.com"},
- {"name": "device_id", "value": "unrelated", "domain": ".xueqiu.com"},
- {"name": "remember", "value": "private", "domain": ".xueqiu.com"},
- ]
-
- fake_rookiepy = SimpleNamespace(
- chrome=chrome,
- firefox=lambda domains: [],
- edge=lambda domains: [],
- brave=lambda domains: [],
- opera=lambda domains: [],
- )
- monkeypatch.setitem(sys.modules, "rookiepy", fake_rookiepy)
-
- extracted = cookie_extract.extract_all("chrome", platform="xueqiu")
-
- assert extracted == {"xueqiu": {"xq_a_token": "needed"}}
-
-
-def test_cookie_backend_cannot_smuggle_a_lookalike_domain(monkeypatch):
- def chrome(domains):
- assert domains == [".xueqiu.com"]
- return [
- {"name": "xq_a_token", "value": "valid", "domain": ".xueqiu.com"},
- {
- "name": "xq_a_token",
- "value": "lookalike",
- "domain": ".notxueqiu.com",
- },
- ]
-
- fake_rookiepy = SimpleNamespace(
- chrome=chrome,
- firefox=lambda domains: [],
- edge=lambda domains: [],
- brave=lambda domains: [],
- opera=lambda domains: [],
- )
- monkeypatch.setitem(sys.modules, "rookiepy", fake_rookiepy)
-
- extracted = cookie_extract.extract_all("chrome", platform="xueqiu")
-
- assert extracted == {"xueqiu": {"xq_a_token": "valid"}}
-
-
- ("platform", "manual_key"),
- [
- ("twitter", "twitter-cookies"),
- ("xhs", "xhs-cookies"),
- ],
-)
-def test_browser_extraction_rejects_cookie_editor_platforms(platform, manual_key):
- with pytest.raises(ValueError, match=rf"Cookie-Editor.*{manual_key}"):
- cookie_extract.extract_all("chrome", platform=platform)
-
-
-def test_explicit_profile_uses_only_that_cookie_database(tmp_path, monkeypatch):
- cookie_db = tmp_path / "Profile 1" / "Network" / "Cookies"
- cookie_db.parent.mkdir(parents=True)
- cookie_db.write_bytes(b"test database placeholder")
- monkeypatch.setattr(
- cookie_extract, "_chromium_user_data_dir", lambda browser: tmp_path
- )
- monkeypatch.setitem(sys.modules, "rookiepy", None)
-
- calls = []
-
- def chrome(*, cookie_file=None, domain_name=""):
- calls.append((cookie_file, domain_name))
- return []
-
- fake_browser_cookie3 = SimpleNamespace(
- chrome=chrome,
- firefox=lambda **kwargs: [],
- edge=lambda **kwargs: [],
- brave=lambda **kwargs: [],
- opera=lambda **kwargs: [],
- )
- monkeypatch.setitem(sys.modules, "browser_cookie3", fake_browser_cookie3)
-
- cookie_extract.extract_all(
- "chrome", platform="xueqiu", profile="Profile 1"
- )
-
- assert calls == [
- (str(cookie_db), ".xueqiu.com"),
- ]
-
-
-def test_missing_explicit_profile_fails_instead_of_falling_back(tmp_path, monkeypatch):
- default_db = tmp_path / "Default" / "Network" / "Cookies"
- default_db.parent.mkdir(parents=True)
- default_db.write_bytes(b"default profile")
- monkeypatch.setattr(
- cookie_extract, "_chromium_user_data_dir", lambda browser: tmp_path
- )
-
- with pytest.raises(ValueError, match="Profile 7.*not found"):
- cookie_extract.extract_all(
- "chrome", platform="xueqiu", profile="Profile 7"
- )
-
-
-def test_configure_requires_platform_before_reading_browser():
- with pytest.raises(ValueError, match="platform"):
- cookie_extract.configure_from_browser("chrome", RecordingConfig())
-
-
-def test_invalid_platform_error_does_not_echo_url_secrets():
- with pytest.raises(ValueError) as error:
- cookie_extract.extract_all(
- "chrome",
- platform="https://user:[email protected]/?access_token=secret",
- )
-
- message = str(error.value)
- assert "user:pass" not in message
- assert "secret" not in message
- assert "***" in message
-
-
[email protected]("platform", ["twitter", "xhs"])
-def test_configure_from_browser_rejects_cookie_editor_platforms(platform):
- with pytest.raises(ValueError, match="Cookie-Editor"):
- cookie_extract.configure_from_browser(
- "chrome", RecordingConfig(), platform=platform
- )
-
-
-def test_xueqiu_config_persists_only_xq_a_token(monkeypatch):
- monkeypatch.setattr(
- cookie_extract,
- "extract_all",
- lambda browser, **kwargs: {"xueqiu": {"xq_a_token": "needed"}},
- )
- config = RecordingConfig()
-
- result = cookie_extract.configure_from_browser(
- "chrome", config, platform="xueqiu"
- )
-
- assert config.values == {"xueqiu_cookie": "xq_a_token=needed"}
- assert result[0].targets == ("xueqiu_cookie",)
-
-
-def test_bilibili_config_reports_each_written_key(monkeypatch):
- monkeypatch.setattr(
- cookie_extract,
- "extract_all",
- lambda browser, **kwargs: {
- "bilibili": {"SESSDATA": "session", "bili_jct": "csrf"}
- },
- )
- config = RecordingConfig()
-
- result = cookie_extract.configure_from_browser(
- "chrome", config, platform="bilibili"
- )
-
- assert config.values == {
- "bilibili_sessdata": "session",
- "bilibili_csrf": "csrf",
- }
- assert result[0].targets == ("bilibili_sessdata", "bilibili_csrf")
- assert tuple(result[0]) == ("Bilibili", True, "SESSDATA + bili_jct")
diff --git a/tests/test_core.py b/tests/test_core.py
deleted file mode 100644
index 0db1996a..00000000
--- a/tests/test_core.py
+++ /dev/null
@@ -1,29 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for AgentReach core class."""
-
-import pytest
-
-from agent_reach.config import Config
-from agent_reach.core import AgentReach
-
-
-def eyes(tmp_path):
- config = Config(config_path=tmp_path / "config.yaml")
- return AgentReach(config=config)
-
-
-class TestAgentReach:
- def test_init(self, eyes):
- assert eyes.config is not None
-
- def test_doctor(self, eyes):
- results = eyes.doctor()
- assert isinstance(results, dict)
- assert "web" in results
- assert "github" in results
-
- def test_doctor_report(self, eyes):
- report = eyes.doctor_report()
- assert isinstance(report, str)
- assert "Agent Reach" in report
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
deleted file mode 100644
index e181dd9a..00000000
--- a/tests/test_doctor.py
+++ /dev/null
@@ -1,325 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for doctor module."""
-
-import hashlib
-import json
-import os
-import shutil
-import subprocess
-from argparse import Namespace
-from pathlib import Path
-
-import pytest
-
-import agent_reach.doctor as doctor
-from agent_reach.config import Config
-
-
-class _StubChannel:
- def __init__(self, name, description, tier, status, message, backends=None,
- active_backend=None):
- self.name = name
- self.description = description
- self.tier = tier
- self._status = status
- self._message = message
- self.backends = backends or []
- self.active_backend = active_backend
-
- def check(self, config=None):
- return self._status, self._message
-
-
-def tmp_config(tmp_path):
- return Config(config_path=tmp_path / "config.yaml")
-
-
-class TestDoctor:
- def test_check_all_collects_channel_results(self, tmp_config, monkeypatch):
- monkeypatch.setattr(
- doctor,
- "get_all_channels",
- lambda: [
- _StubChannel("web", "网页", 0, "ok", "可抓取网页", ["requests"],
- active_backend="requests"),
- _StubChannel("github", "GitHub", 0, "warn", "gh 未安装", ["gh"]),
- _StubChannel("exa_search", "全网语义搜索", 1, "off", "mcporter 未配置", ["Exa"]),
- ],
- )
-
- results = doctor.check_all(tmp_config)
-
- assert results == {
- "web": {
- "status": "ok",
- "name": "网页",
- "message": "可抓取网页",
- "tier": 0,
- "backends": ["requests"],
- "active_backend": "requests",
- },
- "github": {
- "status": "warn",
- "name": "GitHub",
- "message": "gh 未安装",
- "tier": 0,
- "backends": ["gh"],
- "active_backend": None,
- },
- "exa_search": {
- "status": "off",
- "name": "全网语义搜索",
- "message": "mcporter 未配置",
- "tier": 1,
- "backends": ["Exa"],
- "active_backend": None,
- },
- }
-
- def test_format_report(self):
- report = doctor.format_report(
- {
- "web": {
- "status": "ok",
- "name": "网页",
- "message": "可抓取网页",
- "tier": 0,
- "backends": ["requests"],
- },
- "exa_search": {
- "status": "off",
- "name": "全网语义搜索",
- "message": "mcporter 未配置",
- "tier": 1,
- "backends": ["Exa"],
- },
- "xiaohongshu": {
- "status": "warn",
- "name": "小红书",
- "message": "MCP 已配置,但健康检查超时",
- "tier": 2,
- "backends": ["mcporter"],
- },
- }
- )
-
- # Strip Rich markup tags for assertion (PR #170 added [bold], [yellow] etc.)
- import re
- plain = re.sub(r"\[[^\]]*\]", "", report)
- assert "Agent Reach" in plain
- assert "装好即用:" in plain
- assert "1/3 个渠道可用" in plain
- # Inactive optional channels should be summarized in one line
- assert "可选渠道可以解锁" in plain
-
-
-def test_stale_active_backend_does_not_leak_into_errored_result(monkeypatch):
- """渠道单例上一轮的 active_backend 不得泄漏进本轮异常结果(Codex review 发现)。"""
- from agent_reach import doctor
-
- class _ExplodingChannel:
- name = "boom"
- description = "爆炸渠道"
- tier = 0
- backends = ["a", "b"]
- active_backend = "a" # 上一轮成功的残留
-
- def check(self, config=None):
- raise RuntimeError("boom")
-
- monkeypatch.setattr(doctor, "get_all_channels", lambda: [_ExplodingChannel()])
- results = doctor.check_all(config=None)
- assert results["boom"]["status"] == "error"
- assert results["boom"]["active_backend"] is None
-
-
-def test_channel_exception_credentials_are_scrubbed(monkeypatch):
- """Doctor is the final trust boundary for unexpected channel errors."""
-
- class _ExplodingChannel:
- name = "secret"
- description = "敏感渠道"
- tier = 0
- backends = ["secret-backend"]
- active_backend = None
-
- def check(self, config=None):
- raise RuntimeError(
- "request https://alice:[email protected]/data"
- "?access_token=top-secret failed"
- )
-
- monkeypatch.setattr(doctor, "get_all_channels", lambda: [_ExplodingChannel()])
-
- message = doctor.check_all(config=None)["secret"]["message"]
-
- assert "alice" not in message
- assert "password" not in message
- assert "top-secret" not in message
- assert "https://***@example.test/data?access_token=***" in message
-
-
-def test_channel_success_message_credentials_are_scrubbed(monkeypatch):
- """Expected channel messages must pass through the same trust boundary."""
- channel = _StubChannel(
- "configured",
- "已配置渠道",
- 0,
- "warn",
- (
- "upstream returned https://alice:[email protected]/data"
- "?api_key=top-secret"
- ),
- ["upstream"],
- )
- monkeypatch.setattr(doctor, "get_all_channels", lambda: [channel])
-
- message = doctor.check_all(config=None)["configured"]["message"]
-
- assert "alice" not in message
- assert "password" not in message
- assert "top-secret" not in message
- assert "https://***@example.test/data?api_key=***" in message
-
-
-def _snapshot_user_roots() -> tuple:
- entries = []
- seen = set()
- for variable in (
- "HOME",
- "USERPROFILE",
- "XDG_CONFIG_HOME",
- "APPDATA",
- "LOCALAPPDATA",
- ):
- root = Path(os.environ[variable])
- if root in seen:
- continue
- seen.add(root)
- if not root.exists():
- entries.append((variable, ".", "missing"))
- continue
- for path in sorted(root.rglob("*")):
- relative = path.relative_to(root).as_posix()
- if path.is_symlink():
- detail = ("symlink", os.readlink(path))
- elif path.is_dir():
- detail = ("directory", path.stat().st_mode & 0o777)
- elif path.is_file():
- detail = (
- "file",
- path.stat().st_mode & 0o777,
- hashlib.sha256(path.read_bytes()).hexdigest(),
- )
- else:
- detail = ("other",)
- entries.append((variable, relative, detail))
- return tuple(entries)
-
-
-def test_real_doctor_path_is_zero_write_and_never_runs_risky_status_commands(
- monkeypatch, tmp_path, capsys
-):
- """Run the real Doctor collector with deterministic external probes."""
- import agent_reach.backends.opencli as opencli
- import agent_reach.channels.bilibili as bilibili
- import agent_reach.channels.v2ex as v2ex
- import agent_reach.channels.xiaohongshu as xiaohongshu
- import agent_reach.channels.xueqiu as xueqiu
- from agent_reach import cli
-
- workdir = tmp_path / "empty-workdir"
- workdir.mkdir()
- monkeypatch.chdir(workdir)
- monkeypatch.delenv("MCPORTER_CONFIG", raising=False)
- monkeypatch.delenv("GH_TOKEN", raising=False)
- monkeypatch.delenv("GITHUB_TOKEN", raising=False)
-
- available = {
- "gh",
- "opencli",
- "yt-dlp",
- "bili",
- "ffmpeg",
- "mcporter",
- "twitter",
- "rdt",
- "xhs",
- "deno",
- "node",
- }
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: f"/audit-bin/{name}" if name in available else None,
- )
-
- calls = []
-
- def fake_run(command, **kwargs):
- argv = [str(item) for item in command]
- calls.append(argv)
- name = Path(argv[0]).name
- assert name != "mcporter"
- assert argv[1:] not in (
- ["auth", "status"],
- ["status"],
- ["daemon", "status"],
- )
- if name == "gh":
- assert argv[1:] == ["--version"]
- assert kwargs["env"]["GH_TELEMETRY"] == "false"
- assert kwargs["env"]["DO_NOT_TRACK"] == "true"
- output = "gh version 2.92.0"
- elif name == "opencli":
- assert argv[1:] == ["--version"]
- output = "1.8.6"
- elif name == "yt-dlp":
- output = "2026.01.01"
- elif name == "bili":
- output = "0.3.0"
- elif name == "ffmpeg":
- output = "ffmpeg version 7.0"
- else:
- pytest.fail(f"unexpected Doctor subprocess: {argv}")
- return subprocess.CompletedProcess(argv, 0, output, "")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
- monkeypatch.setattr(opencli, "_fetch_daemon_status", lambda timeout=2: None)
- monkeypatch.setattr(opencli, "_extension_installed_on_disk", lambda: False)
- monkeypatch.setattr(
- opencli, "_unpacked_extension_files_present", lambda: False
- )
- monkeypatch.setattr(bilibili, "_search_api_ok", lambda: False)
- monkeypatch.setattr(
- xiaohongshu, "_mcp_service_reachable", lambda timeout=3: False
- )
- monkeypatch.setattr(v2ex, "_get_json", lambda _url: [])
- monkeypatch.setattr(
- xueqiu,
- "_get_json",
- lambda _url, _config=None: {
- "data": {"quote": {"symbol": "SH601138"}}
- },
- )
-
- before = _snapshot_user_roots()
- cli._cmd_doctor(Namespace(json=True))
- after = _snapshot_user_roots()
-
- assert after == before
- assert calls
- assert all(Path(call[0]).name != "mcporter" for call in calls)
- payload = json.loads(capsys.readouterr().out)
- assert payload["github"]["status"] == "warn"
- assert payload["github"]["active_backend"] is None
- for channel_name in (
- "twitter",
- "reddit",
- "facebook",
- "instagram",
- "xiaohongshu",
- ):
- assert payload[channel_name]["status"] == "warn"
- assert payload[channel_name]["active_backend"] is None
diff --git a/tests/test_doctor_credential_boundaries.py b/tests/test_doctor_credential_boundaries.py
deleted file mode 100644
index 82f3cf00..00000000
--- a/tests/test_doctor_credential_boundaries.py
+++ /dev/null
@@ -1,172 +0,0 @@
-"""Doctor must not trigger upstream browser-cookie refresh or persistence."""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import time
-
-from agent_reach.channels.reddit import RedditChannel
-from agent_reach.channels.twitter import TwitterChannel
-from agent_reach.channels.xiaohongshu import XiaoHongShuChannel
-
-
-def _forbid_subprocess(*_args, **_kwargs):
- raise AssertionError("credential-backed health checks must not execute upstream CLIs")
-
-
-def test_twitter_doctor_does_not_start_cli_without_explicit_credentials(
- monkeypatch,
-):
- monkeypatch.delenv("TWITTER_AUTH_TOKEN", raising=False)
- monkeypatch.delenv("TWITTER_CT0", raising=False)
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/twitter" if name == "twitter" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
-
- channel = TwitterChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert channel.active_backend is None
- assert "Cookie-Editor" in message
- assert "浏览器" not in message or "不会" in message
-
-
-def test_twitter_doctor_still_avoids_upstream_fallback_with_saved_credentials(
- monkeypatch,
-):
- class Config:
- def get(self, key, default=None):
- return {
- "twitter_auth_token": "explicit-auth",
- "twitter_ct0": "explicit-ct0",
- }.get(key, default)
-
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/twitter" if name == "twitter" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
-
- status, message = TwitterChannel().check(Config())
-
- assert status == "warn"
- assert "已配置" in message
- assert "不会执行" in message
-
-
-def test_reddit_doctor_does_not_create_or_refresh_missing_credentials(
- isolated_home, monkeypatch
-):
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/rdt" if name == "rdt" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
-
- channel = RedditChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert channel.active_backend is None
- assert "Cookie-Editor" in message
- assert not (isolated_home / ".config" / "rdt-cli").exists()
-
-
-def test_reddit_doctor_reports_stale_saved_credential_without_refresh(
- isolated_home, monkeypatch
-):
- credential_path = (
- isolated_home / ".config" / "rdt-cli" / "credential.json"
- )
- credential_path.parent.mkdir(parents=True)
- credential_path.write_text(
- json.dumps(
- {
- "cookies": {"reddit_session": "explicit-cookie"},
- "saved_at": time.time() - 8 * 86400,
- }
- ),
- encoding="utf-8",
- )
- original = credential_path.read_bytes()
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/rdt" if name == "rdt" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
-
- status, message = RedditChannel().check()
-
- assert status == "warn"
- assert "超过 7 天" in message
- assert credential_path.read_bytes() == original
-
-
-def test_xhs_doctor_does_not_create_or_extract_missing_cookies(
- isolated_home, monkeypatch
-):
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/xhs" if name == "xhs" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
- monkeypatch.setattr(
- XiaoHongShuChannel,
- "_check_opencli",
- lambda self: None,
- )
- monkeypatch.setattr(
- XiaoHongShuChannel,
- "_check_mcp",
- lambda self: None,
- )
-
- channel = XiaoHongShuChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert channel.active_backend is None
- assert "Cookie-Editor" in message
- assert not (isolated_home / ".xiaohongshu-cli").exists()
-
-
-def test_xhs_doctor_reports_stale_cookie_without_refresh(
- isolated_home, monkeypatch
-):
- cookie_path = isolated_home / ".xiaohongshu-cli" / "cookies.json"
- cookie_path.parent.mkdir(parents=True)
- cookie_path.write_text(
- json.dumps(
- {
- "a1": "explicit-cookie",
- "saved_at": time.time() - 8 * 86400,
- }
- ),
- encoding="utf-8",
- )
- original = cookie_path.read_bytes()
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/local/bin/xhs" if name == "xhs" else None,
- )
- monkeypatch.setattr(subprocess, "run", _forbid_subprocess)
- monkeypatch.setattr(
- XiaoHongShuChannel,
- "_check_opencli",
- lambda self: None,
- )
- monkeypatch.setattr(
- XiaoHongShuChannel,
- "_check_mcp",
- lambda self: None,
- )
-
- status, message = XiaoHongShuChannel().check()
-
- assert status == "warn"
- assert "超过 7 天" in message
- assert cookie_path.read_bytes() == original
diff --git a/tests/test_home_isolation.py b/tests/test_home_isolation.py
deleted file mode 100644
index c572c97d..00000000
--- a/tests/test_home_isolation.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Regression guards for test-suite and Doctor filesystem isolation."""
-
-import os
-from argparse import Namespace
-from pathlib import Path
-
-import agent_reach.cli as cli
-from agent_reach.config import Config
-
-
-def test_runtime_home_and_config_are_inside_test_sandbox(isolated_home):
- assert Path.home() == isolated_home
- assert Path(os.path.expanduser("~")) == isolated_home
- assert Config.CONFIG_DIR.is_relative_to(isolated_home)
- assert Config.CONFIG_FILE.is_relative_to(isolated_home)
-
-
-def test_doctor_leaves_sandbox_home_unchanged(
- isolated_home, monkeypatch, capsys
-):
- """If Doctor is truly read-only, even the sandbox remains empty."""
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda config: {})
- monkeypatch.setattr("agent_reach.doctor.format_report", lambda results: "report")
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda *args, **kwargs: (_ for _ in ()).throw(
- AssertionError("doctor must not install skills")
- ),
- )
-
- cli._cmd_doctor(Namespace(json=False))
-
- assert capsys.readouterr().out.strip() == "report"
- assert list(isolated_home.iterdir()) == []
diff --git a/tests/test_integration_script.py b/tests/test_integration_script.py
deleted file mode 100644
index a3058ec4..00000000
--- a/tests/test_integration_script.py
+++ /dev/null
@@ -1,36 +0,0 @@
-import subprocess
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-SCRIPT = ROOT / "test.sh"
-
-
-def test_integration_script_has_valid_shell_syntax(bash_executable):
- subprocess.run([bash_executable, "-n", SCRIPT.name], check=True, cwd=ROOT)
-
-
-def test_integration_script_exercises_the_current_cli_contract():
- text = SCRIPT.read_text(encoding="utf-8")
-
- assert 'pip install --quiet -c "$REPO_ROOT/constraints.txt"' in text
- assert 'TEST_DIR=$(cd "$TEST_DIR" && pwd -P)' in text
- assert 'export HOME="$TEST_DIR/home"' in text
- assert "sys.version_info >= (3, 10)" in text
- assert 'PYTHON_CMD=("$REPO_ROOT/.venv/bin/python")' in text
- assert 'venv/Scripts/activate' in text
- assert "agent-reach install --env=auto --safe" in text
- assert "agent-reach install --env=auto --system --dry-run" in text
- assert "agent-reach doctor --json" in text
- assert 'pytest "$REPO_ROOT/tests" -q' in text
-
- nonexistent_commands = (
- "agent-reach read ",
- "agent-reach search ",
- "agent-reach search-github ",
- "agent-reach search-twitter ",
- "agent-reach search-reddit ",
- "agent-reach search-youtube ",
- "agent-reach search-bilibili ",
- "agent-reach search-xhs ",
- )
- assert not any(command in text for command in nonexistent_commands)
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
deleted file mode 100644
index d70f3917..00000000
--- a/tests/test_mcp_server.py
+++ /dev/null
@@ -1,101 +0,0 @@
-"""Security boundaries for the optional Agent Reach MCP server."""
-
-import asyncio
-from types import SimpleNamespace
-
-import agent_reach.integrations.mcp_server as mcp_server
-
-
-class _FakeServer:
- def __init__(self, name):
- self.name = name
- self.list_tools_handler = None
- self.call_tool_handler = None
-
- def list_tools(self):
- def register(handler):
- self.list_tools_handler = handler
- return handler
-
- return register
-
- def call_tool(self):
- def register(handler):
- self.call_tool_handler = handler
- return handler
-
- return register
-
-
-def _install_fake_mcp(monkeypatch):
- monkeypatch.setattr(mcp_server, "HAS_MCP", True)
- monkeypatch.setattr(mcp_server, "Server", _FakeServer, raising=False)
- monkeypatch.setattr(
- mcp_server,
- "Tool",
- lambda **kwargs: SimpleNamespace(**kwargs),
- raising=False,
- )
- monkeypatch.setattr(
- mcp_server,
- "TextContent",
- lambda **kwargs: SimpleNamespace(**kwargs),
- raising=False,
- )
-
-
-def test_mcp_status_uses_read_only_config(monkeypatch):
- _install_fake_mcp(monkeypatch)
- created_configs = []
-
- class _RecordingConfig:
- def __init__(self, *, read_only=False):
- self.read_only = read_only
- created_configs.append(self)
-
- class _AgentReach:
- def __init__(self, config):
- self.config = config
-
- def doctor_report(self):
- return "ok"
-
- monkeypatch.setattr(mcp_server, "Config", _RecordingConfig)
- monkeypatch.setattr(mcp_server, "AgentReach", _AgentReach)
-
- server = mcp_server.create_server()
- result = asyncio.run(server.call_tool_handler("get_status", {}))
-
- assert len(created_configs) == 1
- assert created_configs[0].read_only is True
- assert result[0].text == "ok"
-
-
-def test_mcp_status_exception_credentials_are_scrubbed(monkeypatch):
- _install_fake_mcp(monkeypatch)
-
- class _Config:
- def __init__(self, *, read_only=False):
- self.read_only = read_only
-
- class _ExplodingAgentReach:
- def __init__(self, config):
- self.config = config
-
- def doctor_report(self):
- raise RuntimeError(
- "request https://alice:[email protected]/data"
- "?token=top-secret failed"
- )
-
- monkeypatch.setattr(mcp_server, "Config", _Config)
- monkeypatch.setattr(mcp_server, "AgentReach", _ExplodingAgentReach)
-
- server = mcp_server.create_server()
- result = asyncio.run(server.call_tool_handler("get_status", {}))
- text = result[0].text
-
- assert "alice" not in text
- assert "password" not in text
- assert "top-secret" not in text
- assert "https://***@example.test/data?token=***" in text
diff --git a/tests/test_mcporter_config.py b/tests/test_mcporter_config.py
deleted file mode 100644
index fe864105..00000000
--- a/tests/test_mcporter_config.py
+++ /dev/null
@@ -1,158 +0,0 @@
-"""Read-only mcporter configuration inspection tests."""
-
-from __future__ import annotations
-
-import json
-
-import pytest
-
-from agent_reach.channels.mcporter import (
- McporterConfigError,
- configured_server_names,
- inspect_mcporter_config,
-)
-
-
-def _write_config(path, servers, *, imports=()):
- path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(
- json.dumps({"mcpServers": servers, "imports": list(imports)}),
- encoding="utf-8",
- )
-
-
-def test_home_and_project_layers_are_merged(
- monkeypatch, tmp_path, isolated_home
-):
- monkeypatch.chdir(tmp_path)
- _write_config(
- isolated_home / ".mcporter" / "mcporter.json",
- {
- "home-only": {"baseUrl": "https://home.example.test"},
- "shared": {"baseUrl": "https://home-shared.example.test"},
- },
- )
- _write_config(
- tmp_path / "config" / "mcporter.json",
- {
- "project-only": {"command": "project-mcp"},
- "shared": {"baseUrl": "https://project-shared.example.test"},
- },
- )
-
- inspection = inspect_mcporter_config()
-
- assert inspection.server_names == {
- "home-only",
- "project-only",
- "shared",
- }
- assert inspection.source == "home+project"
- assert inspection.imports_unchecked is False
-
-
-def test_explicit_config_is_the_only_layer(
- monkeypatch, tmp_path, isolated_home
-):
- monkeypatch.chdir(tmp_path)
- _write_config(
- isolated_home / ".mcporter" / "mcporter.json",
- {"home-only": {"command": "home"}},
- )
- _write_config(
- tmp_path / "config" / "mcporter.json",
- {"project-only": {"command": "project"}},
- )
- _write_config(
- tmp_path / "explicit.json",
- {"explicit-only": {"command": "explicit"}},
- )
- monkeypatch.setenv("MCPORTER_CONFIG", "explicit.json")
-
- inspection = inspect_mcporter_config()
-
- assert inspection.server_names == {"explicit-only"}
- assert inspection.source == "explicit"
-
-
-def test_missing_explicit_config_fails_closed(monkeypatch, tmp_path):
- monkeypatch.chdir(tmp_path)
- monkeypatch.setenv("MCPORTER_CONFIG", "missing.json")
-
- with pytest.raises(McporterConfigError, match="不存在"):
- inspect_mcporter_config()
-
-
-def test_symlink_config_is_rejected(monkeypatch, tmp_path):
- monkeypatch.chdir(tmp_path)
- target = tmp_path / "real.json"
- _write_config(target, {"exa": {"baseUrl": "https://example.test"}})
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- try:
- config_path.symlink_to(target)
- except OSError:
- pytest.skip("symlinks are unavailable on this platform")
-
- with pytest.raises(McporterConfigError, match="符号链接"):
- inspect_mcporter_config()
-
-
-def test_ancestor_symlink_config_is_rejected(monkeypatch, tmp_path):
- real_root = tmp_path / "real-root"
- _write_config(
- real_root / "config" / "mcporter.json",
- {"exa": {"baseUrl": "https://example.test"}},
- )
- linked_root = tmp_path / "linked-root"
- try:
- linked_root.symlink_to(real_root, target_is_directory=True)
- except OSError:
- pytest.skip("symlinks are unavailable on this platform")
- monkeypatch.setenv(
- "MCPORTER_CONFIG",
- str(linked_root / "config" / "mcporter.json"),
- )
-
- with pytest.raises(McporterConfigError, match="安全读取"):
- inspect_mcporter_config()
-
-
-def test_invalid_json_fails_closed(monkeypatch, tmp_path):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text("{not-json", encoding="utf-8")
-
- with pytest.raises(McporterConfigError, match="UTF-8 JSON"):
- inspect_mcporter_config()
-
-
-def test_omitted_imports_are_reported_but_not_expanded(
- monkeypatch, tmp_path
-):
- monkeypatch.chdir(tmp_path)
- config_path = tmp_path / "config" / "mcporter.json"
- config_path.parent.mkdir()
- config_path.write_text(
- json.dumps({"mcpServers": {"exa": {"command": "exa"}}}),
- encoding="utf-8",
- )
-
- inspection = inspect_mcporter_config()
-
- assert inspection.server_names == {"exa"}
- assert inspection.imports_unchecked is True
-
-
-def test_machine_output_parser_remains_available_for_install_flows():
- output = json.dumps(
- {
- "servers": [
- {"name": "Exa", "baseUrl": "https://example.test"},
- {"name": "linkedin-scraper"},
- ]
- }
- )
-
- assert configured_server_names(output) == {"exa", "linkedin-scraper"}
diff --git a/tests/test_opencli_backend.py b/tests/test_opencli_backend.py
deleted file mode 100644
index 5eeb19f3..00000000
--- a/tests/test_opencli_backend.py
+++ /dev/null
@@ -1,199 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for the OpenCLI cross-channel backend probing."""
-
-from unittest.mock import patch
-
-from agent_reach.backends import opencli_status, opencli_summary
-from agent_reach.backends.opencli import (
- OPENCLI_EXTENSION_ID,
- _extension_installed_on_disk,
- _unpacked_extension_files_present,
-)
-from agent_reach.probe import ProbeResult
-
-
-def _status_with(
- version_probe,
- daemon_status=None,
- ext_on_disk=False,
- unpacked_files=False,
-):
- """Run opencli_status with the CLI version and HTTP status patched."""
- calls = []
-
- def fake_probe(cmd, args=("--version",), **kwargs):
- calls.append(list(args))
- return version_probe
-
- with patch("agent_reach.backends.opencli.probe_command", side_effect=fake_probe), \
- patch(
- "agent_reach.backends.opencli._fetch_daemon_status",
- return_value=daemon_status,
- ), \
- patch(
- "agent_reach.backends.opencli._extension_installed_on_disk",
- return_value=ext_on_disk,
- ), \
- patch(
- "agent_reach.backends.opencli._unpacked_extension_files_present",
- return_value=unpacked_files,
- ):
- return opencli_status(), calls
-
-
-def test_not_installed():
- st, _ = _status_with(ProbeResult("missing"))
- assert not st.installed
- assert not st.ready
- assert "未安装" in opencli_summary(st)
-
-
-def test_broken_node_env_gives_npm_hint():
- st, _ = _status_with(ProbeResult("broken", hint="x"))
- assert st.installed and st.broken
- assert "npm install -g @jackwener/opencli" in st.hint
- assert not st.ready
-
-
-def test_daemon_running_extension_connected_is_ready():
- daemon_status = {
- "ok": True,
- "pid": 37389,
- "extensionConnected": True,
- }
- st, _ = _status_with(
- ProbeResult("ok", output="1.8.3"),
- daemon_status,
- )
- assert st.installed and st.daemon_running and st.extension_connected
- assert st.ready
- assert "1.8.3" in opencli_summary(st)
-
-
-def test_extension_never_installed_not_ready_with_store_guide():
- daemon_status = {"ok": True, "pid": 1, "extensionConnected": False}
- st, _ = _status_with(
- ProbeResult("ok", output="1.8.3"),
- daemon_status,
- ext_on_disk=False,
- )
- assert st.daemon_running and not st.extension_connected
- assert not st.ready
- assert "chromewebstore.google.com" in st.hint
-
-
-def test_extension_files_on_disk_are_not_reported_as_loaded_or_ready():
- """A disabled/stale extension leaves files behind, so disk != loaded."""
- daemon_status = {"ok": True, "pid": 1, "extensionConnected": False}
- st, _ = _status_with(
- ProbeResult("ok", output="1.8.3"),
- daemon_status,
- ext_on_disk=True,
- )
- assert not st.extension_connected
- assert st.extension_installed
- assert not st.ready
- assert "可用" not in opencli_summary(st)
- assert "无法确认" in st.hint
-
-
-def test_unpacked_source_files_are_not_reported_as_loaded_or_ready():
- daemon_status = {"ok": True, "pid": 1, "extensionConnected": False}
- st, _ = _status_with(
- ProbeResult("ok", output="1.8.3"),
- daemon_status,
- unpacked_files=True,
- )
- assert st.unpacked_extension_files
- assert not st.extension_connected
- assert not st.ready
- assert "不代表" in st.hint
- assert "可用" not in opencli_summary(st)
-
-
-def test_daemon_not_running_parsed_correctly():
- st, _ = _status_with(
- ProbeResult("ok", output="1.8.3"),
- None,
- )
- assert st.installed
- assert not st.daemon_running
- assert not st.extension_connected
- assert "自动启动" in opencli_summary(st)
-
-
-def test_probe_never_executes_any_daemon_or_doctor_command():
- """Even `daemon status` mutates ~/.opencli in current upstream releases."""
- _, calls = _status_with(
- ProbeResult("ok", output="1.8.3"),
- None,
- )
- assert calls == [["--version"]]
-
-
-def test_opencli_probes_strip_deprecated_app_env_only_from_children(monkeypatch):
- """OpenCLIApp can inject a variable that makes every CLI command exit 78.
-
- Agent Reach must remove it from both read-only child probes without
- mutating the desktop app's parent environment.
- """
- monkeypatch.setenv("OPENCLI_DAEMON_PORT", "19825")
- calls = []
-
- def fake_probe(cmd, args=("--version",), **kwargs):
- calls.append((list(args), tuple(kwargs.get("remove_env", ()))))
- if "OPENCLI_DAEMON_PORT" not in kwargs.get("remove_env", ()):
- return ProbeResult(
- "error",
- output="OPENCLI_DAEMON_PORT is no longer supported",
- )
- return ProbeResult("ok", output="1.8.6")
-
- with patch("agent_reach.backends.opencli.probe_command", side_effect=fake_probe), patch(
- "agent_reach.backends.opencli._fetch_daemon_status",
- return_value=None,
- ), patch(
- "agent_reach.backends.opencli._extension_installed_on_disk",
- return_value=False,
- ):
- status = opencli_status()
-
- assert status.installed and not status.broken
- assert calls == [
- (["--version"], ("OPENCLI_DAEMON_PORT",)),
- ]
- assert "OPENCLI_DAEMON_PORT" in __import__("os").environ
-
-
-def test_store_install_scan_includes_edge_profiles(tmp_path, monkeypatch):
- edge_root = tmp_path / "Microsoft Edge"
- (
- edge_root
- / "Default"
- / "Extensions"
- / OPENCLI_EXTENSION_ID
- / "1.0.0"
- ).mkdir(parents=True)
-
- monkeypatch.setattr(
- "agent_reach.backends.opencli._CHROME_PROFILE_ROOTS",
- (str(edge_root),),
- )
- monkeypatch.delenv("LOCALAPPDATA", raising=False)
-
- assert _extension_installed_on_disk()
-
-
-def test_unpacked_scan_requires_manifest_but_does_not_claim_browser_load(
- tmp_path, monkeypatch
-):
- unpacked = tmp_path / ".opencli" / "extension"
- unpacked.mkdir(parents=True)
- monkeypatch.setattr(
- "agent_reach.backends.opencli._OPENCLI_UNPACKED_EXTENSION",
- str(unpacked),
- )
-
- assert not _unpacked_extension_files_present()
- (unpacked / "manifest.json").write_text('{"name": "OpenCLI"}', encoding="utf-8")
- assert _unpacked_extension_files_present()
diff --git a/tests/test_opencode_skill.py b/tests/test_opencode_skill.py
deleted file mode 100644
index bee5d391..00000000
--- a/tests/test_opencode_skill.py
+++ /dev/null
@@ -1,105 +0,0 @@
-"""OpenCode discovery and metadata compatibility for the packaged skill."""
-
-from __future__ import annotations
-
-import importlib.resources
-import os
-import re
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import patch
-
-import pytest
-import yaml
-
-from agent_reach.cli import _cmd_uninstall, _install_skill, _uninstall_skill
-
-
-def _frontmatter(resource_name: str) -> dict[str, object]:
- text = (
- importlib.resources.files("agent_reach")
- .joinpath("skill", resource_name)
- .read_text(encoding="utf-8")
- )
- match = re.match(r"\A---\n(.*?)\n---\n", text, flags=re.DOTALL)
- assert match is not None, f"{resource_name} must start with YAML frontmatter"
- return yaml.safe_load(match.group(1))
-
-
-def test_skill_frontmatter_uses_opencode_supported_fields():
- """Both locale variants must follow OpenCode's documented schema."""
- allowed_fields = {
- "name",
- "description",
- "license",
- "compatibility",
- "metadata",
- }
-
- for resource_name in ("SKILL.md", "SKILL_en.md"):
- frontmatter = _frontmatter(resource_name)
- assert set(frontmatter) <= allowed_fields, resource_name
- assert frontmatter["name"] == "agent-reach", resource_name
-
- description = frontmatter["description"]
- assert isinstance(description, str), resource_name
- assert 1 <= len(description) <= 1024, resource_name
-
- metadata = frontmatter.get("metadata", {})
- assert isinstance(metadata, dict), resource_name
- assert all(
- isinstance(key, str) and isinstance(value, str)
- for key, value in metadata.items()
- ), resource_name
-
-
-def test_install_skill_discovers_opencode_global_directory(tmp_path: Path):
- skill_parent = tmp_path / ".config" / "opencode" / "skills"
- skill_parent.mkdir(parents=True)
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda value: value.replace("~", os.fspath(tmp_path)),
- ), patch.dict(os.environ, {}, clear=True):
- _install_skill()
-
- installed = skill_parent / "agent-reach" / "SKILL.md"
- assert installed.is_file()
- assert "Agent Reach" in installed.read_text(encoding="utf-8")
-
-
-def test_uninstall_skill_removes_opencode_global_directory(tmp_path: Path):
- installed = tmp_path / ".config" / "opencode" / "skills" / "agent-reach"
- installed.mkdir(parents=True)
- (installed / "SKILL.md").write_text("test", encoding="utf-8")
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda value: value.replace("~", os.fspath(tmp_path)),
- ), patch.dict(os.environ, {}, clear=True):
- _uninstall_skill()
-
- assert not installed.exists()
-
-
-def test_full_uninstall_includes_opencode_directory(
- tmp_path: Path, capsys: pytest.CaptureFixture[str]
-):
- installed = tmp_path / ".config" / "opencode" / "skills" / "agent-reach"
- installed.mkdir(parents=True)
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda value: os.fspath(
- tmp_path / value.removeprefix("~/")
- )
- if value.startswith("~/")
- else value,
- ), patch("agent_reach.utils.paths.home_dir", return_value=tmp_path), patch(
- "shutil.which", return_value=None
- ):
- _cmd_uninstall(SimpleNamespace(dry_run=True, keep_config=True))
-
- output = capsys.readouterr().out
- assert f"Would remove OpenCode skill: {installed}" in output
- assert installed.is_dir()
diff --git a/tests/test_p0_cli.py b/tests/test_p0_cli.py
deleted file mode 100644
index 116bb57f..00000000
--- a/tests/test_p0_cli.py
+++ /dev/null
@@ -1,1398 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Regression tests for P0 CLI safety and configuration failures."""
-
-from __future__ import annotations
-
-import io
-import json
-import subprocess
-import sys
-from argparse import Namespace
-from pathlib import Path
-
-import pytest
-
-import agent_reach.cli as cli
-
-
-class _MemoryConfig:
- def __init__(self, *args, **kwargs):
- self.data = {}
- self.read_only = kwargs.get("read_only", False)
-
- def get(self, key, default=None):
- return self.data.get(key, default)
-
- def set(self, key, value):
- self.data[key] = value
-
-
-def test_configure_reads_secret_from_stdin_without_echoing_it(
- monkeypatch, capsys
-):
- import agent_reach.config as config_module
-
- secret = "gsk-secret-from-stdin"
- config = _MemoryConfig()
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(sys, "stdin", io.StringIO(secret + "\n"))
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "groq-key", "--stdin"],
- )
-
- cli.main()
-
- assert config.data["groq_api_key"] == secret
- output = capsys.readouterr()
- assert secret not in output.out
- assert secret not in output.err
-
-
-def test_configure_uses_hidden_prompt_when_no_value_is_given(
- monkeypatch, capsys
-):
- import getpass
-
- import agent_reach.config as config_module
-
- class TtyInput(io.StringIO):
- def isatty(self):
- return True
-
- secret = "sk-secret-from-prompt"
- config = _MemoryConfig()
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(sys, "stdin", TtyInput())
- monkeypatch.setattr(getpass, "getpass", lambda _prompt: secret)
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "openai-key"],
- )
-
- cli.main()
-
- assert config.data["openai_api_key"] == secret
- output = capsys.readouterr()
- assert secret not in output.out
- assert secret not in output.err
-
-
-def test_setup_uses_hidden_prompts_for_secrets(monkeypatch, capsys):
- import getpass
- import shutil
-
- import agent_reach.config as config_module
-
- github_secret = "ghp-secret-from-setup"
- groq_secret = "gsk-secret-from-setup"
- secrets = iter([github_secret, groq_secret])
- prompts = []
- config = _MemoryConfig()
- config.config_path = Path("/tmp/agent-reach-test-config.yaml")
-
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(shutil, "which", lambda _name: None)
- monkeypatch.setattr(
- getpass,
- "getpass",
- lambda prompt: prompts.append(prompt) or next(secrets),
- )
-
- cli._cmd_setup()
-
- assert config.data["github_token"] == github_secret
- assert config.data["groq_api_key"] == groq_secret
- assert prompts == [
- " GITHUB_TOKEN (回车跳过): ",
- " GROQ_API_KEY (回车跳过): ",
- ]
- output = capsys.readouterr()
- assert github_secret not in output.out
- assert github_secret not in output.err
- assert groq_secret not in output.out
- assert groq_secret not in output.err
-
-
-def test_configure_positional_secret_warns_to_use_safe_input(
- monkeypatch, capsys
-):
- import agent_reach.config as config_module
-
- config = _MemoryConfig()
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "groq-key", "legacy-secret"],
- )
-
- cli.main()
-
- assert config.data["groq_api_key"] == "legacy-secret"
- error = capsys.readouterr().err
- assert "deprecated" in error.lower()
- assert "--stdin" in error
- assert "legacy-secret" not in error
-
-
-def test_configure_rejects_stdin_combined_with_positional_value(
- monkeypatch, capsys
-):
- monkeypatch.setattr(
- cli,
- "_cmd_configure",
- lambda _args: pytest.fail("invalid input sources must not configure"),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "configure",
- "groq-key",
- "legacy-secret",
- "--stdin",
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
- assert "--stdin cannot be combined" in capsys.readouterr().err
-
-
-def test_browser_cookie_import_requires_explicit_platform(monkeypatch):
- """A bare --from-browser must fail before any browser credential access."""
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: pytest.fail("browser cookie reader must not run"),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "--from-browser", "chrome"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
-
-
-def test_browser_cookie_import_passes_explicit_platform_and_profile(
- monkeypatch, capsys
-):
- """The CLI forwards an allowed minimal-cookie platform and exact profile."""
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- captured = {}
-
- def fake_configure(browser, config, **kwargs):
- captured.update(browser=browser, config=config, **kwargs)
- return [("Twitter/X", True, "saved to config.yaml")]
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(cookie_extract, "configure_from_browser", fake_configure)
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "configure",
- "--from-browser",
- "chrome",
- "--platform",
- "xueqiu",
- "--profile",
- "Profile 2",
- ],
- )
-
- cli.main()
-
- assert captured["browser"] == "chrome"
- assert captured["platform"] == "xueqiu"
- assert captured["profile"] == "Profile 2"
- assert "Cookies configured" in capsys.readouterr().out
-
-
-def test_browser_cookie_import_without_cookie_exits_one(monkeypatch, capsys):
- """An unsuccessful browser import is a CLI failure, not a silent success."""
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: [
- ("Xueqiu", False, "No Xueqiu cookies found")
- ],
- )
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "configure",
- "--from-browser",
- "chrome",
- "--platform",
- "xueqiu",
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- assert "No cookies found" in capsys.readouterr().out
-
-
- ("platform", "manual_key"),
- [("twitter", "twitter-cookies"), ("xiaohongshu", "xhs-cookies")],
-)
-def test_browser_cookie_import_rejects_cookie_editor_only_platforms(
- monkeypatch, capsys, platform, manual_key
-):
- """Twitter/XHS browser stores are never opened by the automatic importer."""
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: pytest.fail("browser cookie reader must not run"),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "configure",
- "--from-browser",
- "chrome",
- "--platform",
- platform,
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
- assert manual_key in capsys.readouterr().err
-
-
-def test_install_does_not_implicitly_read_browser_cookies(monkeypatch, tmp_path, capsys):
- """Installing a cookie-backed channel prints an explicit command instead."""
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(
- cli.os.path,
- "expanduser",
- lambda value: value.replace("~", str(tmp_path)),
- )
- monkeypatch.setattr(cli, "_install_system_deps", lambda: None)
- monkeypatch.setattr(cli, "_install_mcporter", lambda: None)
- monkeypatch.setattr(cli, "_install_twitter_deps", lambda: None)
- monkeypatch.setattr(cli, "_install_skill", lambda: None)
- monkeypatch.setattr(
- "agent_reach.doctor.check_all",
- lambda _config: {},
- )
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: pytest.fail("install must not read browser cookies"),
- )
-
- cli._cmd_install(
- Namespace(
- env="local",
- proxy="",
- system=True,
- safe=False,
- dry_run=False,
- channels="twitter",
- )
- )
-
- output = capsys.readouterr().out
- assert "configure twitter-cookies" in output
- assert "Importing cookies from browser" not in output
-
-
-def test_install_rejects_safe_and_system_together(monkeypatch, capsys):
- monkeypatch.setattr(
- cli,
- "_cmd_install",
- lambda _args: pytest.fail("conflicting install modes must not run"),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "install", "--safe", "--system"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
- assert "not allowed with argument" in capsys.readouterr().err
-
-
-def test_install_rejects_unknown_channel_before_side_effects(
- monkeypatch, capsys
-):
- """A typo in --channels fails before config or system installation starts."""
- import agent_reach.config as config_module
-
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- config_module,
- "Config",
- lambda *_args, **_kwargs: pytest.fail(
- "Config must not be constructed for an invalid channel"
- ),
- )
- monkeypatch.setattr(
- cli,
- "_install_system_deps",
- lambda: pytest.fail("system dependencies must not be installed"),
- )
- monkeypatch.setattr(
- cli.os,
- "makedirs",
- lambda *_args, **_kwargs: pytest.fail(
- "install directories must not be created"
- ),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "install",
- "--env",
- "local",
- "--channels",
- "twiter",
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
- assert "twiter" in capsys.readouterr().err
-
-
-def test_install_accepts_boss_channel_in_dry_run(monkeypatch, capsys):
- monkeypatch.setattr(cli, "_install_system_deps_dryrun", lambda: None)
-
- cli._cmd_install(
- Namespace(
- env="local",
- proxy="",
- system=True,
- safe=False,
- dry_run=True,
- channels="boss",
- )
- )
-
- assert "Would install optional channels: boss" in capsys.readouterr().out
-
-
-def test_install_all_includes_boss_on_desktop(monkeypatch, capsys):
- monkeypatch.setattr(cli, "_install_system_deps_dryrun", lambda: None)
-
- cli._cmd_install(
- Namespace(
- env="local",
- proxy="",
- system=True,
- safe=False,
- dry_run=True,
- channels="all",
- )
- )
-
- install_line = next(
- line
- for line in capsys.readouterr().out.splitlines()
- if "Would install optional channels:" in line
- )
- assert "boss" in install_line
-
-
[email protected]("sync_legacy", [False, True])
-def test_manual_twitter_cookie_legacy_copies_are_opt_in(
- monkeypatch, capsys, sync_legacy
-):
- """The source-of-truth config is always written; legacy copies are optional."""
- import shutil
-
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- calls = []
- config = _MemoryConfig()
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(shutil, "which", lambda _name: None)
- monkeypatch.setattr(
- cookie_extract,
- "_sync_xfetch_session",
- lambda auth, ct0: calls.append(("xfetch", auth, ct0)) or True,
- )
- monkeypatch.setattr(
- cookie_extract,
- "_sync_bird_env",
- lambda auth, ct0: calls.append(("bird", auth, ct0)) or True,
- )
-
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="twitter-cookies",
- value=["auth-value", "ct0-value"],
- sync_legacy_twitter=sync_legacy,
- )
- )
-
- assert config.get("twitter_auth_token") == "auth-value"
- assert config.get("twitter_ct0") == "ct0-value"
- assert bool(calls) is sync_legacy
- output = capsys.readouterr().out
- assert ("Legacy copies written" in output) is sync_legacy
-
-
- ("xfetch_ok", "bird_ok", "written_count", "failed_count"),
- [
- (True, True, 2, 0),
- (True, False, 1, 1),
- (False, True, 1, 1),
- (False, False, 0, 2),
- ],
-)
-def test_legacy_twitter_sync_reports_only_confirmed_results(
- monkeypatch,
- capsys,
- xfetch_ok,
- bird_ok,
- written_count,
- failed_count,
-):
- import shutil
-
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(shutil, "which", lambda _name: None)
- monkeypatch.setattr(
- cookie_extract,
- "_sync_xfetch_session",
- lambda *_args: xfetch_ok,
- )
- monkeypatch.setattr(
- cookie_extract,
- "_sync_bird_env",
- lambda *_args: bird_ok,
- )
-
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="twitter-cookies",
- value=["auth-value", "ct0-value"],
- sync_legacy_twitter=True,
- )
- )
-
- output = capsys.readouterr().out
- assert output.count(" written:") == written_count
- assert output.count(" failed:") == failed_count
-
-
-def test_twitter_configure_never_runs_upstream_browser_fallback(
- monkeypatch, capsys
-):
- import shutil
-
- import agent_reach.config as config_module
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(shutil, "which", lambda _name: "/usr/bin/twitter")
- monkeypatch.setattr(
- subprocess,
- "run",
- lambda *_args, **_kwargs: pytest.fail(
- "configure must not execute twitter status"
- ),
- )
-
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="twitter-cookies",
- value=["auth-value", "ct0-value"],
- sync_legacy_twitter=False,
- )
- )
-
- output = capsys.readouterr().out
- assert "已保存" in output
- assert "未实时验证" in output
- assert "Twitter access works" not in output
-
-
-def test_doctor_never_installs_or_updates_skill(monkeypatch, capsys):
- """A diagnostic command is read-only and must not mutate agent instructions."""
- import agent_reach.config as config_module
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr("agent_reach.doctor.format_report", lambda _results: "report")
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda *_args, **_kwargs: pytest.fail("doctor must not install skill"),
- )
-
- cli._cmd_doctor(Namespace(json=False))
-
- assert "report" in capsys.readouterr().out
-
-
-def test_watch_uses_read_only_config(monkeypatch, capsys):
- """Scheduled diagnostics must enforce the same no-write boundary as doctor."""
- import agent_reach.config as config_module
-
- created = []
-
- class RecordingConfig(_MemoryConfig):
- def __init__(self, *args, **kwargs):
- super().__init__(*args, **kwargs)
- created.append(self)
-
- class _Release:
- status_code = 200
-
- @staticmethod
- def json():
- return {"tag_name": "v0.0.0", "body": ""}
-
- monkeypatch.setattr(config_module, "Config", RecordingConfig)
- monkeypatch.setattr(
- "agent_reach.doctor.check_all",
- lambda _config: {
- "web": {
- "status": "ok",
- "name": "网页",
- "message": "可用",
- "tier": 0,
- "backends": ["Jina Reader"],
- "active_backend": "Jina Reader",
- }
- },
- )
- monkeypatch.setattr(
- cli,
- "_github_get_with_retry",
- lambda *_args, **_kwargs: (_Release(), None, 1),
- )
-
- cli._cmd_watch()
-
- assert len(created) == 1
- assert created[0].read_only is True
- assert "全部正常" in capsys.readouterr().out
-
-
-def _docker_result(args, returncode=0, stdout="", stderr=""):
- return subprocess.CompletedProcess(args, returncode, stdout, stderr)
-
-
-def test_xhs_docker_cookie_copy_succeeds_without_local_os_binding_error(
- monkeypatch, capsys
-):
- """The Docker branch must be able to unlink its temporary file."""
- calls = []
-
- def fake_which(name):
- if name == "docker":
- return "/usr/bin/docker"
- return None
-
- def fake_run(args, **_kwargs):
- calls.append(args)
- if args[1] == "ps":
- return _docker_result(args, stdout="xiaohongshu-mcp\n")
- if args[1:3] == ["exec", "xiaohongshu-mcp"]:
- return _docker_result(args, stdout="/app/data/cookies.json\n")
- return _docker_result(args)
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._configure_xhs_cookies("web_session=xhs_secret")
-
- output = capsys.readouterr().out
- assert "Cookies written to xiaohongshu-mcp:/app/data/cookies.json" in output
- assert "cannot access local variable 'os'" not in output
- assert any(call[1] == "cp" for call in calls)
-
-
-def test_xhs_docker_cookie_copy_always_removes_temporary_file(monkeypatch, capsys):
- """Failed docker cp must not leave a plaintext cookie file behind."""
- copied_from = []
-
- def fake_which(name):
- if name == "docker":
- return "/usr/bin/docker"
- return None
-
- def fake_run(args, **_kwargs):
- if args[1] == "ps":
- return _docker_result(args, stdout="xiaohongshu-mcp\n")
- if args[1:3] == ["exec", "xiaohongshu-mcp"]:
- return _docker_result(args, stdout="/app/data/cookies.json\n")
- if args[1] == "cp":
- copied_from.append(args[2])
- return _docker_result(args, returncode=1, stderr="copy failed")
- return _docker_result(args)
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._configure_xhs_cookies("web_session=xhs_secret")
-
- assert copied_from
- assert not Path(copied_from[0]).exists()
- assert "Failed to copy cookies: copy failed" in capsys.readouterr().out
-
-
-def test_xhs_docker_restart_failure_returns_failure(monkeypatch, capsys):
- """Cookies are not active until the container successfully restarts."""
-
- def fake_which(name):
- return "/usr/bin/docker" if name == "docker" else None
-
- def fake_run(args, **_kwargs):
- if args[1] == "ps":
- return _docker_result(args, stdout="xiaohongshu-mcp\n")
- if args[1:3] == ["exec", "xiaohongshu-mcp"]:
- return _docker_result(args, stdout="/app/data/cookies.json\n")
- if args[1] == "restart":
- return _docker_result(
- args,
- returncode=1,
- stderr="no such container",
- )
- return _docker_result(args)
-
- monkeypatch.setattr("shutil.which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- result = cli._configure_xhs_cookies("web_session=xhs_secret")
-
- output = capsys.readouterr().out
- assert result is False
- assert "Could not restart container" in output
- assert "no such container" in output
- assert "Restart manually" in output
- assert "done" not in output
-
-
-def test_system_install_uses_ytdlp_first_user_config(
- monkeypatch, tmp_path
-):
- """Installer writes the first config directory that real yt-dlp reads."""
- import shutil
-
- import agent_reach.utils.paths as paths
-
- monkeypatch.setattr(paths.Path, "home", classmethod(lambda cls: tmp_path))
- monkeypatch.delenv("XDG_CONFIG_HOME")
- monkeypatch.setattr(
- cli.os.path,
- "expanduser",
- lambda value: str(tmp_path / ".legacy-config")
- if value == "~/.config/yt-dlp"
- else value.replace("~", str(tmp_path)),
- )
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: f"/usr/bin/{name}"
- if name in {"gh", "node", "npm", "yt-dlp"}
- else None,
- )
-
- def fake_run(args, **_kwargs):
- if args[-1:] == ["--version"] and args[0].endswith("yt-dlp"):
- return _docker_result(args, stdout="2026.07.04\n")
- return _docker_result(
- args,
- stdout="/tmp/npm-root\n"
- if args[1:3] == ["root", "-g"]
- else "",
- )
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- config_path = tmp_path / ".config" / "yt-dlp" / "config"
- assert config_path.read_text(encoding="utf-8") == "--js-runtimes node\n"
- assert not (tmp_path / ".legacy-config" / "config").exists()
-
-
-def test_system_install_uses_existing_apt_without_remote_bootstrap(
- monkeypatch,
-):
- """Linux installs only from an already-configured apt package manager."""
- import builtins
- import io
- import platform
- import shutil
-
- commands = []
- system_source_writes = []
- real_open = builtins.open
-
- def fake_which(name):
- if name == "apt-get":
- return "/usr/bin/apt-get"
- return None
-
- def fake_open(path, mode="r", *args, **kwargs):
- if str(path).startswith(("/etc/apt/", "/usr/share/keyrings/")):
- system_source_writes.append((str(path), mode))
- return io.StringIO()
- return real_open(path, mode, *args, **kwargs)
-
- def fake_run(args, **_kwargs):
- commands.append(args)
- return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
-
- monkeypatch.setattr(platform, "system", lambda: "Linux")
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(builtins, "open", fake_open)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- assert commands == [
- ["/usr/bin/apt-get", "update", "-qq"],
- [
- "/usr/bin/apt-get",
- "install",
- "-y",
- "-qq",
- "gh",
- "nodejs",
- "npm",
- ],
- ]
- assert system_source_writes == []
-
-
-def test_system_install_stops_after_failed_apt_update(monkeypatch, capsys):
- """A failed apt index refresh blocks the package installation step."""
- import platform
- import shutil
-
- commands = []
- monkeypatch.setattr(platform, "system", lambda: "Linux")
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/usr/bin/apt-get" if name == "apt-get" else None,
- )
-
- def fake_run(args, **_kwargs):
- commands.append(args)
- return subprocess.CompletedProcess(args, 1, stdout="", stderr="failed")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- assert commands == [["/usr/bin/apt-get", "update", "-qq"]]
- output = capsys.readouterr().out
- assert "apt-get update failed" in output
- assert "Installed with apt-get" not in output
-
-
-def test_system_install_uses_brew_and_checks_each_result(monkeypatch, capsys):
- """Homebrew failures are reported per dependency and never as success."""
- import platform
- import shutil
-
- commands = []
- monkeypatch.setattr(platform, "system", lambda: "Darwin")
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/opt/homebrew/bin/brew" if name == "brew" else None,
- )
-
- def fake_run(args, **_kwargs):
- commands.append(args)
- returncode = 0 if args[-1] == "gh" else 1
- return subprocess.CompletedProcess(
- args,
- returncode,
- stdout="",
- stderr="failed" if returncode else "",
- )
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- assert commands == [
- ["/opt/homebrew/bin/brew", "install", "gh"],
- ["/opt/homebrew/bin/brew", "install", "node"],
- ]
- output = capsys.readouterr().out
- assert "✅ gh CLI installed" in output
- assert "[!] Node.js install failed" in output
- assert "✅ Node.js installed" not in output
-
-
-def test_system_install_stops_undici_setup_when_npm_root_fails(
- monkeypatch, capsys
-):
- """A failed discovery step must not trigger a global npm write."""
- import shutil
-
- commands = []
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: f"/usr/bin/{name}"
- if name in {"gh", "node", "npm", "deno"}
- else None,
- )
-
- def fake_run(args, **_kwargs):
- commands.append(args)
- return subprocess.CompletedProcess(
- args,
- 1,
- stdout="/untrusted/npm-root\n",
- stderr="npm root failed",
- )
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- assert commands == [["/usr/bin/npm", "root", "-g"]]
- output = capsys.readouterr().out
- assert "undici installed" not in output
- assert "Could not inspect global npm packages" in output
-
-
-def test_system_install_does_not_report_failed_undici_as_success(
- monkeypatch, capsys
-):
- import shutil
-
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: f"/usr/bin/{name}"
- if name in {"gh", "node", "npm", "deno"}
- else None,
- )
-
- def fake_run(args, **_kwargs):
- if args[1:3] == ["root", "-g"]:
- return subprocess.CompletedProcess(
- args,
- 0,
- stdout="/missing/npm-root\n",
- stderr="",
- )
- return subprocess.CompletedProcess(
- args,
- 1,
- stdout="",
- stderr="install failed",
- )
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- output = capsys.readouterr().out
- assert "✅ undici installed" not in output
- assert "undici install failed" in output
-
-
-def test_install_dry_run_never_suggests_remote_setup_scripts(
- monkeypatch, capsys
-):
- import shutil
-
- monkeypatch.setattr(shutil, "which", lambda _name: None)
-
- cli._install_system_deps_dryrun()
-
- output = capsys.readouterr().out
- assert "curl" not in output
- assert "NodeSource" not in output
- assert "apt-get" in output
- assert "brew" in output
-
-
- "helper",
- [cli._install_system_deps_safe, cli._install_system_deps_dryrun],
-)
-def test_system_dependency_checks_require_both_node_and_npm(
- monkeypatch, capsys, helper
-):
- import shutil
-
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: f"/usr/bin/{name}" if name in {"gh", "node"} else None,
- )
-
- helper()
-
- output = capsys.readouterr().out
- assert "Node.js" in output
- assert "All system dependencies are installed" not in output
- assert "Node.js: already installed" not in output
-
-
- "yt_dlp_version",
- [None, "2025.10.22", "not-a-stable-version"],
-)
-def test_system_install_never_writes_unsupported_ytdlp_flag(
- monkeypatch, tmp_path, yt_dlp_version
-):
- """A missing, old, or unknown yt-dlp must not receive a fatal option."""
- import shutil
-
- import agent_reach.utils.paths as paths
-
- monkeypatch.setattr(paths.sys, "platform", "darwin")
- monkeypatch.setattr(paths.Path, "home", classmethod(lambda cls: tmp_path))
- monkeypatch.delenv("XDG_CONFIG_HOME")
-
- def fake_which(name):
- if name in {"gh", "node", "npm"}:
- return f"/usr/bin/{name}"
- if name == "yt-dlp" and yt_dlp_version is not None:
- return "/usr/bin/yt-dlp"
- return None
-
- def fake_run(args, **_kwargs):
- if args[-1:] == ["--version"] and args[0].endswith("yt-dlp"):
- return _docker_result(args, stdout=f"{yt_dlp_version}\n")
- return _docker_result(
- args,
- stdout="/tmp/npm-root\n"
- if args[1:3] == ["root", "-g"]
- else "",
- )
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- config_path = tmp_path / ".config" / "yt-dlp" / "config"
- assert not config_path.exists()
-
-
-def test_update_guide_preserves_ytdlp_default_extra():
- """Every documented upgrade path keeps yt-dlp's default/EJS dependencies."""
- guide = (
- Path(__file__).resolve().parents[1] / "docs" / "update.md"
- ).read_text(encoding="utf-8")
- update_line = next(
- line for line in guide.splitlines() if line.startswith("which yt-dlp")
- )
-
- assert update_line.count("yt-dlp[default]") == 3
- assert "pipx install --force 'yt-dlp[default]'" in update_line
-
-
-def test_mcporter_install_adds_exa_to_home_scope(monkeypatch):
- """Installer config remains available across working directories."""
- import shutil
-
- calls = []
-
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/usr/bin/mcporter" if name == "mcporter" else None,
- )
-
- def fake_run(args, **_kwargs):
- calls.append(args)
- if args == ["/usr/bin/mcporter", "config", "list", "--json"]:
- return _docker_result(args, stdout='{"servers": []}')
- return _docker_result(args)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_mcporter()
-
- assert [
- "/usr/bin/mcporter",
- "config",
- "add",
- "exa",
- "https://mcp.exa.ai/mcp",
- "--scope",
- "home",
- ] in calls
- assert ["/usr/bin/mcporter", "config", "list", "--json"] in calls
-
-
-def test_mcporter_install_does_not_treat_metadata_as_exa_server(
- monkeypatch,
-):
- """Only a server object's exact name may suppress Exa setup."""
- import json
- import shutil
-
- calls = []
- payload = {
- "servers": [
- {
- "name": "unrelated",
- "source": {"path": "/tmp/exa-project/mcporter.json"},
- "url": "https://example.test/?note=exa",
- }
- ]
- }
-
- monkeypatch.setattr(
- shutil,
- "which",
- lambda name: "/usr/bin/mcporter" if name == "mcporter" else None,
- )
-
- def fake_run(args, **_kwargs):
- calls.append(args)
- if args == ["/usr/bin/mcporter", "config", "list", "--json"]:
- return _docker_result(args, stdout=json.dumps(payload))
- return _docker_result(args)
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_mcporter()
-
- assert [
- "/usr/bin/mcporter",
- "config",
- "add",
- "exa",
- "https://mcp.exa.ai/mcp",
- "--scope",
- "home",
- ] in calls
-
-
-def test_mcporter_install_uses_resolved_windows_command_paths(monkeypatch):
- """Windows .CMD shims must not be replaced with unresolved bare names."""
- import shutil
-
- npm_cmd = "C:/Tools/npm.CMD"
- mcporter_cmd = "C:/Tools/mcporter.CMD"
- state = {"installed": False}
- calls = []
-
- def fake_which(name):
- if name == "npm":
- return npm_cmd
- if name == "mcporter" and state["installed"]:
- return mcporter_cmd
- return None
-
- def fake_run(args, **_kwargs):
- calls.append(args)
- if args[:4] == [npm_cmd, "install", "-g", "mcporter"]:
- state["installed"] = True
- return _docker_result(args)
- if args == [mcporter_cmd, "config", "list", "--json"]:
- return _docker_result(
- args,
- stdout='{"servers": [{"name": "exa"}]}',
- )
- return _docker_result(args, returncode=1)
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- assert cli._install_mcporter() is True
- assert calls == [
- [npm_cmd, "install", "-g", "mcporter"],
- [mcporter_cmd, "config", "list", "--json"],
- ]
-
-
-def test_server_xhs_install_never_recommends_qr_or_browser_extraction(
- monkeypatch, capsys
-):
- """Project policy requires an explicit Cookie-Editor export for XHS."""
- monkeypatch.setattr(cli, "_detect_environment", lambda: "server")
-
- cli._install_xhs_deps()
-
- output = capsys.readouterr().out
- assert "Cookie-Editor" in output
- assert "configure xhs-cookies" in output
- assert "扫码" not in output
- assert "二维码" not in output
-
-
-def test_configure_usage_does_not_recommend_blocked_twitter_browser_import(
- capsys,
-):
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key=None,
- value=[],
- sync_legacy_twitter=False,
- )
- )
-
- output = capsys.readouterr().out
- assert "--platform xueqiu" in output
- assert "--platform twitter" not in output
-
-
-def test_configure_missing_value_exits_one(monkeypatch, capsys):
- """A selected config key without a value must fail at the CLI boundary."""
- import agent_reach.config as config_module
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "github-token"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- assert "Missing value for github-token" in capsys.readouterr().out
-
-
-def test_twitter_cookie_parse_failure_exits_one(monkeypatch, capsys):
- """Malformed Twitter cookie input must not produce a successful CLI status."""
- import agent_reach.config as config_module
-
- config = _MemoryConfig()
- monkeypatch.setattr(config_module, "Config", lambda: config)
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- sys,
- "argv",
- ["agent-reach", "configure", "twitter-cookies", "not-a-cookie"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- assert "Could not find auth_token and ct0" in capsys.readouterr().out
- assert config.data == {}
-
-
-def test_profile_rejects_unsupported_browser_before_cookie_backend(
- monkeypatch, capsys
-):
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: pytest.fail(
- "unsupported profile must fail before browser access"
- ),
- )
- monkeypatch.setattr(
- sys,
- "argv",
- [
- "agent-reach",
- "configure",
- "--from-browser",
- "firefox",
- "--platform",
- "xueqiu",
- "--profile",
- "default-release",
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 2
- assert "Chrome/Edge/Brave" in capsys.readouterr().err
-
-
-def test_missing_profile_is_clean_cli_error_without_traceback(
- monkeypatch, capsys
-):
- import agent_reach.config as config_module
- import agent_reach.cookie_extract as cookie_extract
-
- monkeypatch.setattr(config_module, "Config", _MemoryConfig)
- monkeypatch.setattr(
- cookie_extract,
- "configure_from_browser",
- lambda *_args, **_kwargs: (_ for _ in ()).throw(
- ValueError(
- "Profile 'secret-profile' not found for chrome; "
- "https://user:[email protected]/?token=hidden"
- )
- ),
- )
-
- with pytest.raises(SystemExit) as exc:
- cli._cmd_configure(
- Namespace(
- from_browser="chrome",
- platform="xueqiu",
- profile="Missing",
- key=None,
- value=[],
- sync_legacy_twitter=False,
- )
- )
-
- error = capsys.readouterr().err
- assert exc.value.code == 2
- assert "Traceback" not in error
- assert "user:pass" not in error
- assert "hidden" not in error
- assert "***" in error
-
-
-def test_install_dry_run_does_not_create_agent_reach_directory(
- isolated_home, monkeypatch
-):
- monkeypatch.setattr(cli, "_install_system_deps_dryrun", lambda: None)
-
- cli._cmd_install(
- Namespace(
- env="local",
- proxy="",
- system=True,
- safe=False,
- dry_run=True,
- channels="",
- )
- )
-
- assert not (isolated_home / ".agent-reach").exists()
-
-
-def test_uninstall_warns_about_opt_in_legacy_credential_copies(
- isolated_home, capsys
-):
- xfetch = isolated_home / ".config" / "xfetch" / "session.json"
- bird = isolated_home / ".config" / "bird" / "credentials.env"
- xfetch.parent.mkdir(parents=True)
- bird.parent.mkdir(parents=True)
- xfetch.write_text("{}", encoding="utf-8")
- bird.write_text("AUTH_TOKEN=secret\n", encoding="utf-8")
-
- cli._cmd_uninstall(Namespace(dry_run=True, keep_config=False))
-
- output = capsys.readouterr().out
- assert str(xfetch) in output
- assert str(bird) in output
- assert "不会自动删除" in output
- assert xfetch.exists()
- assert bird.exists()
-
-
-def test_uninstall_preserves_mcporter_entries_without_agent_reach_provenance(
- isolated_home, monkeypatch, capsys
-):
- """Names and endpoints alone do not prove Agent Reach owns an MCP entry."""
- calls = []
- payload = {
- "servers": [
- {
- "name": "exa",
- "source": {
- "kind": "local",
- "path": str(isolated_home / ".mcporter" / "mcporter.json"),
- },
- "baseUrl": "https://mcp.exa.ai/mcp",
- },
- {
- "name": "xiaohongshu",
- "source": {
- "kind": "local",
- "path": str(isolated_home / ".mcporter" / "mcporter.json"),
- },
- "baseUrl": "http://localhost:18060/mcp",
- },
- ]
- }
-
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/bin/mcporter" if name == "mcporter" else None,
- )
-
- def fake_run(args, **_kwargs):
- calls.append(args)
- return _docker_result(args, stdout=json.dumps(payload))
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._cmd_uninstall(Namespace(dry_run=False, keep_config=True))
-
- output = capsys.readouterr().out
- assert not any("remove" in call for call in calls)
- assert "来源无法证明" in output
diff --git a/tests/test_paths.py b/tests/test_paths.py
deleted file mode 100644
index c0d0bbde..00000000
--- a/tests/test_paths.py
+++ /dev/null
@@ -1,43 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Behavior tests for cross-platform path and remediation helpers."""
-
-import shutil
-import subprocess
-from pathlib import Path
-
-import pytest
-
-from agent_reach.utils import paths
-
-
-def test_posix_ytdlp_fix_is_single_line_executable_and_idempotent(
- monkeypatch, tmp_path
-):
- monkeypatch.setattr(paths.sys, "platform", "linux")
- monkeypatch.setattr(paths.Path, "home", classmethod(lambda cls: tmp_path))
- monkeypatch.delenv("XDG_CONFIG_HOME")
-
- command = paths.render_ytdlp_fix_command()
-
- assert "\n" not in command
- shell = shutil.which("sh")
- if not shell:
- pytest.skip("POSIX sh is unavailable on this platform")
- subprocess.run([shell, "-c", command], check=True)
- subprocess.run([shell, "-c", command], check=True)
-
- config = tmp_path / ".config" / "yt-dlp" / "config"
- assert config.read_text(encoding="utf-8") == "--js-runtimes node\n"
-
-
-def test_ytdlp_config_dir_matches_upstream_first_user_location(
- monkeypatch, tmp_path
-):
- from yt_dlp.options import get_user_config_dirs
-
- config_home = tmp_path / "xdg-config"
- monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-
- expected = Path(next(get_user_config_dirs("yt-dlp")))
-
- assert paths.get_ytdlp_config_dir() == expected
diff --git a/tests/test_private_file_writes.py b/tests/test_private_file_writes.py
index 2f8466c4..491488de 100644
--- a/tests/test_private_file_writes.py
+++ b/tests/test_private_file_writes.py
@@ -2,16 +2,11 @@
from __future__ import annotations
-import json
import os
import stat
-import subprocess
-from argparse import Namespace
import pytest
-from agent_reach import cli
-from agent_reach.cookie_extract import _sync_bird_env, _sync_xfetch_session
from agent_reach.utils import paths
@@ -44,597 +39,41 @@ def test_atomic_private_text_write_preserves_old_file_on_replace_failure(
assert list(target.parent.glob(".secret.txt.*.tmp")) == []
-def test_legacy_xfetch_sync_refuses_target_symlink(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- session_path = tmp_path / ".config" / "xfetch" / "session.json"
- session_path.parent.mkdir(parents=True)
- victim = tmp_path / "victim.json"
- victim.write_text('{"keep": "unchanged"}', encoding="utf-8")
- try:
- session_path.symlink_to(victim)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- assert _sync_xfetch_session("new-auth", "new-ct0") is False
- assert victim.read_text(encoding="utf-8") == '{"keep": "unchanged"}'
- assert session_path.is_symlink()
-
-
-def test_legacy_xfetch_sync_refuses_parent_symlink(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- config_dir = tmp_path / ".config"
- config_dir.mkdir()
- victim_dir = tmp_path / "victim-dir"
- victim_dir.mkdir()
- xfetch_dir = config_dir / "xfetch"
- try:
- xfetch_dir.symlink_to(victim_dir, target_is_directory=True)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- assert _sync_xfetch_session("new-auth", "new-ct0") is False
- assert not (victim_dir / "session.json").exists()
- assert xfetch_dir.is_symlink()
-
-
-def test_legacy_xfetch_sync_refuses_ancestor_symlink(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- victim_dir = tmp_path / "victim-config"
- victim_dir.mkdir()
- config_dir = tmp_path / ".config"
- try:
- config_dir.symlink_to(victim_dir, target_is_directory=True)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- assert _sync_xfetch_session("new-auth", "new-ct0") is False
- assert list(victim_dir.iterdir()) == []
- assert config_dir.is_symlink()
-
-
-def test_credential_writes_honor_home_when_expanduser_disagrees(
- tmp_path, monkeypatch
-):
- """Windows expanduser ignores HOME; private writes must not escape it."""
- intended_home = tmp_path / "isolated-home"
- windows_profile = tmp_path / "windows-profile"
- intended_home.mkdir()
- windows_profile.mkdir()
- monkeypatch.setenv("HOME", str(intended_home))
- real_expanduser = os.path.expanduser
- def windows_expanduser(value):
- if value == "~":
- return str(windows_profile)
- if value.startswith("~/"):
- return str(windows_profile / value[2:])
- return real_expanduser(value)
- monkeypatch.setattr(os.path, "expanduser", windows_expanduser)
- monkeypatch.setattr("shutil.which", lambda _name: None)
- assert _sync_xfetch_session("auth", "ct0") is True
- assert _sync_bird_env("auth", "ct0") is True
- assert cli._configure_xhs_cookies("web_session=xhs-secret") is True
- assert (intended_home / ".config" / "xfetch" / "session.json").exists()
- assert (intended_home / ".config" / "bird" / "credentials.env").exists()
- assert (intended_home / ".agent-reach" / "xhs-cookies.json").exists()
- assert list(windows_profile.rglob("*")) == []
-def test_expanduser_fallback_still_refuses_symlinked_profile(
- tmp_path, monkeypatch
-):
- """Without HOME, the USERPROFILE fallback remains guarded end to end."""
- victim_dir = tmp_path / "victim-profile"
- victim_dir.mkdir()
- profile_link = tmp_path / "profile-link"
- try:
- profile_link.symlink_to(victim_dir, target_is_directory=True)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- monkeypatch.delenv("HOME", raising=False)
- monkeypatch.setattr(
- os.path,
- "expanduser",
- lambda value: str(profile_link) if value == "~" else value,
- )
-
- assert _sync_xfetch_session("auth", "ct0") is False
- assert _sync_bird_env("auth", "ct0") is False
- assert list(victim_dir.rglob("*")) == []
-
-
-def test_legacy_xfetch_sync_refuses_oversized_existing_session(
- tmp_path, monkeypatch
-):
- monkeypatch.setenv("HOME", str(tmp_path))
- session_path = tmp_path / ".config" / "xfetch" / "session.json"
- session_path.parent.mkdir(parents=True)
- previous = json.dumps({"untrusted": "x" * (1024 * 1024)})
- session_path.write_text(previous, encoding="utf-8")
-
- assert _sync_xfetch_session("new-auth", "new-ct0") is False
- assert session_path.read_text(encoding="utf-8") == previous
-
-
-def test_legacy_bird_sync_refuses_target_symlink(tmp_path, monkeypatch):
- monkeypatch.setenv("HOME", str(tmp_path))
- env_path = tmp_path / ".config" / "bird" / "credentials.env"
- env_path.parent.mkdir(parents=True)
- victim = tmp_path / "victim.env"
- victim.write_text("KEEP=unchanged\n", encoding="utf-8")
- try:
- env_path.symlink_to(victim)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- assert _sync_bird_env("new-auth", "new-ct0") is False
- assert victim.read_text(encoding="utf-8") == "KEEP=unchanged\n"
- assert env_path.is_symlink()
-
-
-def test_xhs_cookie_editor_json_ignores_non_xhs_domains(
- tmp_path, monkeypatch, capsys
-):
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setattr("shutil.which", lambda name: None)
- exported = [
- {
- "name": "web_session",
- "value": "valid-root",
- "domain": ".xiaohongshu.com",
- "path": "/",
- },
- {
- "name": "a1",
- "value": "valid-subdomain",
- "domain": "www.xiaohongshu.com",
- "path": "/",
- },
- {
- "name": "foreign",
- "value": "must-not-persist",
- "domain": ".example.com",
- "path": "/",
- },
- {
- "name": "lookalike",
- "value": "must-not-persist",
- "domain": ".notxiaohongshu.com",
- "path": "/",
- },
- ]
-
- cli._configure_xhs_cookies(json.dumps(exported))
-
- cookie_path = tmp_path / ".agent-reach" / "xhs-cookies.json"
- saved = json.loads(cookie_path.read_text(encoding="utf-8"))
- assert [cookie["name"] for cookie in saved] == ["web_session", "a1"]
- output = capsys.readouterr().out
- assert "忽略" in output
- assert "2" in output
-
-
-def test_xhs_cookie_editor_json_fails_without_valid_xhs_cookie(
- tmp_path, monkeypatch, capsys
-):
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setattr(
- "shutil.which",
- lambda name: pytest.fail("invalid cookies must fail before tool lookup"),
- )
- exported = [
- {
- "name": "session",
- "value": "foreign",
- "domain": ".example.com",
- },
- {
- "name": "lookalike",
- "value": "foreign",
- "domain": ".xiaohongshu.com.evil.test",
- },
- ]
-
- monkeypatch.setattr("agent_reach.config.Config", lambda: object())
- with pytest.raises(SystemExit) as exc:
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="xhs-cookies",
- value=[json.dumps(exported)],
- sync_legacy_twitter=False,
- )
- )
-
- assert exc.value.code == 1
- assert not (tmp_path / ".agent-reach" / "xhs-cookies.json").exists()
- output = capsys.readouterr().out
- assert "没有有效的 xiaohongshu.com" in output
-
-
-def test_xhs_local_fallback_refuses_target_symlink(
- tmp_path, monkeypatch, capsys
-):
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setattr("shutil.which", lambda name: None)
- cookie_path = tmp_path / ".agent-reach" / "xhs-cookies.json"
- cookie_path.parent.mkdir()
- victim = tmp_path / "victim.json"
- victim.write_text('{"keep": "unchanged"}', encoding="utf-8")
- try:
- cookie_path.symlink_to(victim)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- result = cli._configure_xhs_cookies("web_session=xhs-secret")
-
- assert result is False
- assert victim.read_text(encoding="utf-8") == '{"keep": "unchanged"}'
- assert cookie_path.is_symlink()
- assert "Could not save cookies" in capsys.readouterr().out
-
-
-def test_xhs_docker_success_via_configure_command_does_not_exit(
- monkeypatch, capsys
-):
- monkeypatch.setattr("agent_reach.config.Config", lambda: object())
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/bin/docker" if name == "docker" else None,
- )
-
- def fake_run(args, **_kwargs):
- if args[1] == "ps":
- return subprocess.CompletedProcess(
- args, 0, stdout="xiaohongshu-mcp\n", stderr=""
- )
- if args[1:3] == ["exec", "xiaohongshu-mcp"]:
- return subprocess.CompletedProcess(
- args, 0, stdout="/app/data/cookies.json\n", stderr=""
- )
- return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="xhs-cookies",
- value=["web_session=xhs-secret"],
- sync_legacy_twitter=False,
- )
- )
-
- assert "Cookies written to" in capsys.readouterr().out
-
-
-def test_xhs_docker_failure_via_configure_command_exits_one(
- monkeypatch, capsys
-):
- monkeypatch.setattr("agent_reach.config.Config", lambda: object())
- monkeypatch.setattr(
- "shutil.which",
- lambda name: "/usr/bin/docker" if name == "docker" else None,
- )
-
- def fake_run(args, **_kwargs):
- if args[1] == "ps":
- return subprocess.CompletedProcess(
- args, 0, stdout="xiaohongshu-mcp\n", stderr=""
- )
- if args[1:3] == ["exec", "xiaohongshu-mcp"]:
- return subprocess.CompletedProcess(
- args, 0, stdout="/app/data/cookies.json\n", stderr=""
- )
- if args[1] == "cp":
- return subprocess.CompletedProcess(
- args, 1, stdout="", stderr="copy failed"
- )
- return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
-
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- with pytest.raises(SystemExit) as exc:
- cli._cmd_configure(
- Namespace(
- from_browser=None,
- key="xhs-cookies",
- value=["web_session=xhs-secret"],
- sync_legacy_twitter=False,
- )
- )
-
- assert exc.value.code == 1
- assert "Failed to copy cookies" in capsys.readouterr().out
-
-
-def test_ytdlp_config_write_refuses_target_symlink(
- tmp_path, monkeypatch, capsys
-):
- import shutil
-
- import agent_reach.utils.paths as paths
-
- monkeypatch.setattr(paths.sys, "platform", "darwin")
- monkeypatch.setattr(
- paths.Path,
- "home",
- classmethod(lambda cls: tmp_path),
- )
- monkeypatch.delenv("XDG_CONFIG_HOME")
- config_path = tmp_path / ".config" / "yt-dlp" / "config"
- config_path.parent.mkdir(parents=True)
- victim = tmp_path / "victim.conf"
- victim.write_text("# keep unchanged\n", encoding="utf-8")
- try:
- config_path.symlink_to(victim)
- except OSError:
- pytest.skip("symlinks are not supported on this platform")
-
- def fake_which(name):
- if name in {"gh", "node", "npm", "yt-dlp"}:
- return f"/usr/bin/{name}"
- return None
-
- def fake_run(args, **_kwargs):
- if args[-1:] == ["--version"] and args[0].endswith("yt-dlp"):
- return subprocess.CompletedProcess(
- args, 0, stdout="2026.07.04\n", stderr=""
- )
- stdout = "/tmp/npm-root\n" if args[1:3] == ["root", "-g"] else ""
- return subprocess.CompletedProcess(args, 0, stdout=stdout, stderr="")
-
- monkeypatch.setattr(shutil, "which", fake_which)
- monkeypatch.setattr(subprocess, "run", fake_run)
-
- cli._install_system_deps()
-
- assert victim.read_text(encoding="utf-8") == "# keep unchanged\n"
- assert config_path.is_symlink()
- assert "Could not configure yt-dlp JS runtime" in capsys.readouterr().out
-
-
-def test_transcribe_cli_scrubs_credentials_from_errors(
- monkeypatch, capsys
-):
- import agent_reach.transcribe as transcribe_module
-
- secret_url = (
- "https://alice:[email protected]/audio"
- "?access_token=hidden-token"
- )
-
- def fail_transcribe(*_args, **_kwargs):
- raise transcribe_module.TranscribeError(
- f"yt-dlp failed for {secret_url}"
- )
-
- monkeypatch.setattr(transcribe_module, "transcribe", fail_transcribe)
-
- with pytest.raises(SystemExit) as exc:
- cli._cmd_transcribe(
- Namespace(
- source=secret_url,
- provider="auto",
- output=None,
- )
- )
-
- assert exc.value.code == 1
- output = capsys.readouterr().out
- assert "alice:super-secret" not in output
- assert "hidden-token" not in output
- assert "***" in output
-
-
-def test_safe_install_with_proxy_makes_no_persistent_writes(
- isolated_home, monkeypatch, capsys
-):
- observed_configs = []
- skill_calls = []
-
- monkeypatch.setattr(cli, "_install_system_deps_safe", lambda: None)
- monkeypatch.setattr(cli, "_install_mcporter_safe", lambda: None)
- monkeypatch.setattr(
- "agent_reach.doctor.check_all",
- lambda config: observed_configs.append(config) or {},
- )
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda: skill_calls.append("installed"),
- )
-
- cli._cmd_install(
- Namespace(
- env="local",
- proxy="http://user:[email protected]:8080",
- system=False,
- safe=True,
- dry_run=False,
- channels="twitter",
- )
- )
-
- assert len(observed_configs) == 1
- assert observed_configs[0].read_only is True
- assert skill_calls == []
- assert not (isolated_home / ".agent-reach").exists()
- assert not (isolated_home / ".agent-reach" / "tools").exists()
- assert not (isolated_home / ".openclaw" / "skills" / "agent-reach").exists()
- assert not (isolated_home / ".claude" / "skills" / "agent-reach").exists()
- assert not (isolated_home / ".agents" / "skills" / "agent-reach").exists()
- output = capsys.readouterr().out
- assert "SAFE MODE" in output
- assert "Would save network proxy" in output
-
-
-def test_install_is_safe_by_default(isolated_home, monkeypatch, capsys):
- """Plain install checks readiness without modifying the host."""
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cli,
- "_install_system_deps",
- lambda: pytest.fail("default install must not modify system dependencies"),
- )
- monkeypatch.setattr(
- cli,
- "_install_mcporter",
- lambda: pytest.fail("default install must not install global tools"),
- )
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda: pytest.fail("default install must not register agent skills"),
- )
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli.sys,
- "argv",
- ["agent-reach", "install", "--env", "local"],
- )
-
- cli.main()
-
- assert not (isolated_home / ".agent-reach").exists()
- output = capsys.readouterr().out
- assert "SAFE MODE" in output
- assert "No changes were made" in output
-
-
-def test_install_system_flag_explicitly_enables_writes(
- isolated_home, monkeypatch, capsys
-):
- """The legacy write path remains available only through --system."""
- calls = []
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(
- cli,
- "_install_system_deps",
- lambda: calls.append("system-deps"),
- )
- monkeypatch.setattr(
- cli,
- "_install_mcporter",
- lambda: calls.append("mcporter"),
- )
- monkeypatch.setattr(
- cli,
- "_install_skill",
- lambda: calls.append("skill"),
- )
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli.sys,
- "argv",
- ["agent-reach", "install", "--env", "local", "--system"],
- )
-
- cli.main()
-
- assert calls == ["system-deps", "mcporter", "skill"]
- assert (isolated_home / ".agent-reach" / "tools").is_dir()
- assert "Installation complete" in capsys.readouterr().out
-
-
-def test_install_system_exits_nonzero_when_core_steps_fail(
- isolated_home, monkeypatch, capsys
-):
- """Automation must not receive exit zero after failed core installation."""
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(cli, "_install_system_deps", lambda: False)
- monkeypatch.setattr(cli, "_install_mcporter", lambda: False)
- monkeypatch.setattr(cli, "_install_skill", lambda: None)
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli.sys,
- "argv",
- ["agent-reach", "install", "--env", "local", "--system"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- output = capsys.readouterr().out
- assert "Installation incomplete" in output
- assert "Installation complete" not in output
-
-
-def test_install_system_exits_nonzero_when_requested_channel_fails(
- isolated_home, monkeypatch, capsys
-):
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(cli, "_install_system_deps", lambda: True)
- monkeypatch.setattr(cli, "_install_mcporter", lambda: True)
- monkeypatch.setattr(cli, "_install_opencli_deps", lambda: False)
- monkeypatch.setattr(cli, "_install_skill", lambda: True)
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli.sys,
- "argv",
- [
- "agent-reach",
- "install",
- "--env",
- "local",
- "--system",
- "--channels=opencli",
- ],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- assert "Installation incomplete" in capsys.readouterr().out
-
-
-def test_install_system_exits_nonzero_when_skill_install_fails(
- isolated_home, monkeypatch, capsys
-):
- monkeypatch.setattr(cli, "_configure_logging", lambda _verbose=False: None)
- monkeypatch.setattr(cli, "_install_system_deps", lambda: True)
- monkeypatch.setattr(cli, "_install_mcporter", lambda: True)
- monkeypatch.setattr(cli, "_install_skill", lambda: False)
- monkeypatch.setattr("agent_reach.doctor.check_all", lambda _config: {})
- monkeypatch.setattr(
- "agent_reach.doctor.format_report",
- lambda _results: "report",
- )
- monkeypatch.setattr(
- cli.sys,
- "argv",
- ["agent-reach", "install", "--env", "local", "--system"],
- )
-
- with pytest.raises(SystemExit) as exc:
- cli.main()
-
- assert exc.value.code == 1
- assert "Installation incomplete" in capsys.readouterr().out
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tests/test_probe.py b/tests/test_probe.py
deleted file mode 100644
index ac8e2d9c..00000000
--- a/tests/test_probe.py
+++ /dev/null
@@ -1,115 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for agent_reach.probe — real-execution probing and failure classification."""
-
-import os
-import stat
-import sys
-
-import pytest
-
-from agent_reach.probe import probe_command, reinstall_hint
-
-
-def _make_executable(path, content):
- path.write_text(content)
- path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
- return str(path)
-
-
-def test_missing_command():
- r = probe_command("definitely-not-a-real-command-xyz")
- assert r.status == "missing"
- assert not r.ok
-
-
[email protected](sys.platform == "win32", reason="shebang semantics are POSIX-only")
-def test_broken_shebang_detected_as_broken(tmp_path, monkeypatch):
- """A stale venv shim: which() finds it, exec raises FileNotFoundError."""
- _make_executable(
- tmp_path / "stale-tool", "#!/nonexistent/venv/bin/python\nprint('hi')\n"
- )
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
-
- r = probe_command("stale-tool", package="stale-tool-pkg")
- assert r.status == "broken"
- assert "uv tool install --force stale-tool-pkg" in r.hint
- assert "pipx reinstall stale-tool-pkg" in r.hint
-
-
[email protected](sys.platform == "win32", reason="shell script fixture is POSIX-only")
-def test_healthy_command_returns_ok_with_output(tmp_path, monkeypatch):
- _make_executable(
- tmp_path / "healthy-tool", "#!/bin/sh\necho 'healthy-tool 1.2.3'\n"
- )
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
-
- r = probe_command("healthy-tool")
- assert r.ok
- assert "1.2.3" in r.output
-
-
[email protected](sys.platform == "win32", reason="shell script fixture is POSIX-only")
-def test_probe_child_env_can_add_and_remove_without_mutating_parent(tmp_path, monkeypatch):
- _make_executable(
- tmp_path / "env-tool",
- (
- "#!/bin/sh\n"
- 'if [ -n "${BLOCKED_APP_VAR+x}" ]; then exit 78; fi\n'
- 'echo "$PROBE_ONLY_VALUE"\n'
- ),
- )
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
- monkeypatch.setenv("BLOCKED_APP_VAR", "inherited")
-
- result = probe_command(
- "env-tool",
- env={"PROBE_ONLY_VALUE": "child-only"},
- remove_env=("BLOCKED_APP_VAR",),
- )
-
- assert result.ok
- assert result.output == "child-only"
- assert os.environ["BLOCKED_APP_VAR"] == "inherited"
- assert "PROBE_ONLY_VALUE" not in os.environ
-
-
[email protected](sys.platform == "win32", reason="shell script fixture is POSIX-only")
-def test_nonzero_exit_classified_as_error(tmp_path, monkeypatch):
- _make_executable(
- tmp_path / "failing-tool", "#!/bin/sh\necho 'boom' >&2\nexit 3\n"
- )
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
-
- r = probe_command("failing-tool")
- assert r.status == "error"
- assert "boom" in r.output
-
-
[email protected](sys.platform == "win32", reason="shell script fixture is POSIX-only")
-def test_exit_127_classified_as_broken(tmp_path, monkeypatch):
- _make_executable(tmp_path / "wrapper-tool", "#!/bin/sh\nexit 127\n")
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
-
- r = probe_command("wrapper-tool", package="wrapper-pkg")
- assert r.status == "broken"
- assert "wrapper-pkg" in r.hint
-
-
[email protected](sys.platform == "win32", reason="shell script fixture is POSIX-only")
-def test_retries_help_transient_failures(tmp_path, monkeypatch):
- """First call fails (exit 1), second succeeds — retries=1 should return ok."""
- marker = tmp_path / "ran-once"
- _make_executable(
- tmp_path / "flaky-tool",
- f"#!/bin/sh\nif [ -f {marker} ]; then echo ok; exit 0; fi\ntouch {marker}\nexit 1\n",
- )
- monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ.get("PATH", ""))
-
- r = probe_command("flaky-tool", retries=1)
- assert r.ok
-
-
-def test_reinstall_hint_mentions_both_installers():
- hint = reinstall_hint("some-pkg")
- assert "uv tool install --force some-pkg" in hint
- assert "pipx reinstall some-pkg" in hint
diff --git a/tests/test_process.py b/tests/test_process.py
index 550acfb9..9492346c 100644
--- a/tests/test_process.py
+++ b/tests/test_process.py
@@ -1,4 +1,4 @@
-from agent_reach.utils.process import mcporter_utf8_env_args, utf8_subprocess_env
+from agent_reach.utils.process import utf8_subprocess_env
def test_utf8_subprocess_env_forces_python_utf8():
@@ -9,10 +9,3 @@ def test_utf8_subprocess_env_forces_python_utf8():
assert env["OTHER"] == "value"
-def test_mcporter_utf8_env_args():
- assert mcporter_utf8_env_args() == [
- "--env",
- "PYTHONUTF8=1",
- "--env",
- "PYTHONIOENCODING=utf-8",
- ]
diff --git a/tests/test_reddit_channel.py b/tests/test_reddit_channel.py
index f4232758..97f9753a 100644
--- a/tests/test_reddit_channel.py
+++ b/tests/test_reddit_channel.py
@@ -1,9 +1,7 @@
# -*- coding: utf-8 -*-
"""Dedicated tests for Reddit's read-only multi-backend health check."""
-import json
-import time
-from unittest.mock import Mock, patch
+from unittest.mock import Mock
from agent_reach.channels.reddit import RedditChannel
@@ -26,201 +24,35 @@ def test_can_handle_rejects_non_reddit():
assert channel.can_handle(url) is False, url
-def test_check_rdt_returns_none_when_not_installed():
- with patch("shutil.which", return_value=None):
- assert RedditChannel()._check_rdt() is None
-
-
-def test_check_rdt_missing_credential_is_warn():
- with patch("shutil.which", return_value="/usr/local/bin/rdt"):
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "Cookie-Editor" in message
-
-
-def test_check_rdt_saved_credential_is_unverified_not_false_ok(
- isolated_home,
-):
- path = isolated_home / ".config" / "rdt-cli" / "credential.json"
- path.parent.mkdir(parents=True)
- path.write_text(
- json.dumps(
- {
- "cookies": {"reddit_session": "explicit"},
- "saved_at": time.time(),
- }
- ),
- encoding="utf-8",
- )
- with patch("shutil.which", return_value="/usr/local/bin/rdt"), patch(
- "subprocess.run"
- ) as run:
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "未实时验证" in message
- run.assert_not_called()
-
-
-def test_check_rdt_stale_credential_is_not_refreshed(isolated_home):
- path = isolated_home / ".config" / "rdt-cli" / "credential.json"
- path.parent.mkdir(parents=True)
- path.write_text(
- json.dumps(
- {
- "cookies": {"reddit_session": "explicit"},
- "saved_at": time.time() - 8 * 86400,
- }
- ),
- encoding="utf-8",
- )
- before = path.read_bytes()
- with patch("shutil.which", return_value="/usr/local/bin/rdt"), patch(
- "subprocess.run"
- ) as run:
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "超过 7 天" in message
- assert path.read_bytes() == before
- run.assert_not_called()
-
-
-def test_check_rdt_unparseable_credential_is_warn(isolated_home):
- path = isolated_home / ".config" / "rdt-cli" / "credential.json"
- path.parent.mkdir(parents=True)
- path.write_text("not json", encoding="utf-8")
- with patch("shutil.which", return_value="/usr/local/bin/rdt"):
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "无法安全解析" in message
-
-
-def test_check_rdt_refuses_symlink_credential(isolated_home):
- victim = isolated_home / "victim.json"
- victim.write_text('{"secret": "do-not-read"}', encoding="utf-8")
- path = isolated_home / ".config" / "rdt-cli" / "credential.json"
- path.parent.mkdir(parents=True)
- path.symlink_to(victim)
- with patch("shutil.which", return_value="/usr/local/bin/rdt"):
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "符号链接" in message
-
-
-def test_check_rdt_refuses_ancestor_symlink(isolated_home):
- victim_dir = isolated_home / "victim-config"
- credential_path = victim_dir / "rdt-cli" / "credential.json"
- credential_path.parent.mkdir(parents=True)
- credential_path.write_text(
- '{"cookies": {"reddit_session": "do-not-read"}}',
- encoding="utf-8",
- )
- (isolated_home / ".config").symlink_to(
- victim_dir,
- target_is_directory=True,
- )
-
- with patch("shutil.which", return_value="/usr/local/bin/rdt"):
- status, message = RedditChannel()._check_rdt()
-
- assert status == "warn"
- assert "符号链接" in message
-def _opencli(installed=True, broken=False, ready=True, hint=""):
- return Mock(installed=installed, broken=broken, ready=ready, hint=hint)
-def test_check_opencli_not_installed_is_none():
- with patch(
- "agent_reach.backends.opencli_status",
- return_value=_opencli(installed=False),
- ):
- assert RedditChannel()._check_opencli() is None
-def test_check_opencli_broken_is_error():
- with patch(
- "agent_reach.backends.opencli_status",
- return_value=_opencli(broken=True, hint="reinstall opencli"),
- ):
- status, message = RedditChannel()._check_opencli()
- assert status == "error"
- assert message == "reinstall opencli"
-def test_check_opencli_bridge_ready_is_unverified():
- with patch(
- "agent_reach.backends.opencli_status",
- return_value=_opencli(ready=True),
- ):
- status, message = RedditChannel()._check_opencli()
- assert status == "warn"
- assert "桥接已连接" in message
- assert "登录态和实际命令未实时验证" in message
-def test_check_opencli_installed_not_ready_is_warn():
- with patch(
- "agent_reach.backends.opencli_status",
- return_value=_opencli(ready=False, hint="connect the extension"),
- ):
- status, message = RedditChannel()._check_opencli()
- assert status == "warn"
- assert message == "connect the extension"
-def test_check_prefers_ok_over_warn_regardless_of_probe_order():
- channel = RedditChannel()
- with patch.object(
- channel, "_check_opencli", return_value=("warn", "opencli sleepy")
- ), patch.object(
- channel, "_check_rdt", return_value=("ok", "rdt ready")
- ):
- status, message = channel.check()
- assert status == "ok"
- assert message == "rdt ready"
- assert channel.active_backend == "rdt-cli"
+
+def _opencli(installed=True, broken=False, ready=True, hint=""):
+ return Mock(installed=installed, broken=broken, ready=ready, hint=hint)
+
+
+
+
+
+
+
+
-def test_check_warn_has_no_active_backend():
- channel = RedditChannel()
- with patch.object(
- channel, "_check_opencli", return_value=("warn", "not ready")
- ), patch.object(
- channel, "_check_rdt", return_value=("warn", "unverified")
- ):
- status, message = channel.check()
- assert status == "warn"
- assert message == "not ready"
- assert channel.active_backend is None
-def test_check_all_errors_returns_error_and_no_active_backend():
- channel = RedditChannel()
- with patch.object(
- channel, "_check_opencli", return_value=("error", "e1")
- ), patch.object(channel, "_check_rdt", return_value=("error", "e2")):
- status, message = channel.check()
- assert status == "error"
- assert "e1" in message and "e2" in message
- assert channel.active_backend is None
-def test_check_no_backend_installed_is_off():
- channel = RedditChannel()
- with patch.object(channel, "_check_opencli", return_value=None), patch.object(
- channel, "_check_rdt", return_value=None
- ):
- status, message = channel.check()
-
- assert status == "off"
- assert "零配置" in message
- assert channel.active_backend is None
diff --git a/tests/test_scrub_credentials.py b/tests/test_scrub_credentials.py
index 4687326c..83f6dbed 100644
--- a/tests/test_scrub_credentials.py
+++ b/tests/test_scrub_credentials.py
@@ -1,15 +1,7 @@
"""Secrets embedded in URLs must not reach user-facing diagnostics."""
-import sys
-from types import SimpleNamespace
-import pytest
-from agent_reach import cookie_extract
-from agent_reach.channels import v2ex as v2ex_module
-from agent_reach.channels import xueqiu as xueqiu_module
-from agent_reach.channels.v2ex import V2EXChannel
-from agent_reach.channels.xueqiu import XueqiuChannel
from agent_reach.utils.text import scrub_url_credentials
@@ -55,49 +47,5 @@ def test_leaves_non_secret_urls_and_plain_text_unchanged():
assert scrub_url_credentials(raw) == raw
- ("module", "channel"),
- [
- (v2ex_module, V2EXChannel()),
- (xueqiu_module, XueqiuChannel()),
- ],
-)
-def test_channel_health_messages_scrub_url_secrets(module, channel, monkeypatch):
- def fail(_url, *_args, **_kwargs):
- raise RuntimeError(
- "proxy http://user:[email protected]:8080 refused "
- "https://api.test/data?access_token=top-secret"
- )
-
- monkeypatch.setattr(module, "_get_json", fail)
-
- _status, message = channel.check()
-
- assert "user:pass" not in message
- assert "top-secret" not in message
- assert "***" in message
-
-
-def test_browser_backend_errors_scrub_url_secrets(monkeypatch):
- def chrome(_domains):
- raise RuntimeError(
- "failed via http://user:[email protected] "
- "https://api.test/?token=top-secret"
- )
-
- fake_rookiepy = SimpleNamespace(
- chrome=chrome,
- firefox=lambda domains: [],
- edge=lambda domains: [],
- brave=lambda domains: [],
- opera=lambda domains: [],
- )
- monkeypatch.setitem(sys.modules, "rookiepy", fake_rookiepy)
- with pytest.raises(RuntimeError) as error:
- cookie_extract.extract_all("chrome", platform="xueqiu")
- message = str(error.value)
- assert "user:pass" not in message
- assert "top-secret" not in message
- assert "***" in message
diff --git a/tests/test_skill_command.py b/tests/test_skill_command.py
deleted file mode 100644
index 38a702cf..00000000
--- a/tests/test_skill_command.py
+++ /dev/null
@@ -1,255 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for 'agent-reach skill' command and _install_skill / _uninstall_skill."""
-
-import importlib.resources
-import os
-import re
-import tempfile
-import unittest
-from argparse import Namespace
-from pathlib import Path
-from unittest.mock import patch
-
-from agent_reach.cli import _cmd_skill, _install_skill, _uninstall_skill
-
-
-class TestSkillCommand(unittest.TestCase):
- """Test skill install and uninstall via CLI helpers."""
-
- def test_skill_resources_include_both_locales(self):
- """Package resources should expose both default and English skill markdown files."""
- skill_dir = importlib.resources.files("agent_reach").joinpath("skill")
-
- default_skill = skill_dir.joinpath("SKILL.md").read_text(encoding="utf-8")
- english_skill = skill_dir.joinpath("SKILL_en.md").read_text(encoding="utf-8")
-
- self.assertTrue(default_skill.strip())
- self.assertTrue(english_skill.strip())
-
- def test_exa_reference_uses_default_registered_tools_only(self):
- """Agent instructions must not call Exa tools disabled by default."""
- search_reference = (
- importlib.resources.files("agent_reach")
- .joinpath("skill", "references", "search.md")
- .read_text(encoding="utf-8")
- )
-
- self.assertIn("web_search_exa", search_reference)
- self.assertNotIn("exa.get_code_context_exa", search_reference)
- self.assertNotIn("get_code_context_exa(", search_reference)
-
- def test_mcporter_examples_use_shell_safe_named_arguments(self):
- """Packaged commands must survive PowerShell and POSIX parsing."""
- root = Path(__file__).resolve().parents[1]
- markdown_files = [
- *(root / "agent_reach" / "skill").rglob("*.md"),
- *(root / "agent_reach" / "guides").rglob("*.md"),
- root / "docs" / "install.md",
- root / "docs" / "troubleshooting.md",
- ]
- function_call = re.compile(r"mcporter call\s+['\"][^'\"\r\n]+\(")
-
- for markdown_file in markdown_files:
- with self.subTest(markdown_file=markdown_file):
- content = markdown_file.read_text(encoding="utf-8")
- self.assertNotRegex(content, function_call)
-
- def test_linkedin_reference_uses_current_tool_contract(self):
- """LinkedIn examples should use the current server and parameters."""
- career_reference = (
- importlib.resources.files("agent_reach")
- .joinpath("skill", "references", "career.md")
- .read_text(encoding="utf-8")
- )
-
- self.assertIn(
- "linkedin.get_person_profile "
- 'linkedin_username="username" '
- 'sections="experience,education"',
- career_reference,
- )
- self.assertIn(
- 'linkedin.search_people keywords="AI engineer" '
- 'location="Shanghai"',
- career_reference,
- )
- self.assertIn(
- 'linkedin.get_company_profile company_name="openai" '
- 'sections="posts,jobs"',
- career_reference,
- )
- self.assertIn(
- 'linkedin.search_jobs keywords="software engineer" '
- 'location="Remote" max_pages=2',
- career_reference,
- )
- self.assertNotIn("linkedin-scraper.", career_reference)
-
- def test_linkedin_install_docs_use_current_stdio_contract(self):
- """LinkedIn install guidance should use uvx over stdio."""
- install_doc = (
- Path(__file__).resolve().parents[1] / "docs" / "install.md"
- ).read_text(encoding="utf-8")
- linkedin_section = install_doc.split(
- "**LinkedIn (", maxsplit=1
- )[1].split("### Step 4:", maxsplit=1)[0]
-
- self.assertIn(
- "uvx mcp-server-linkedin@latest --login",
- linkedin_section,
- )
- self.assertIn(
- "mcporter config add linkedin --command uvx "
- "--arg mcp-server-linkedin@latest --env UV_HTTP_TIMEOUT=300 "
- "--scope home",
- linkedin_section,
- )
- self.assertNotIn("linkedin-scraper-mcp", linkedin_section)
- self.assertNotIn("localhost:3000/mcp", linkedin_section)
- self.assertNotIn("linkedin-scraper.", linkedin_section)
- self.assertNotIn("--transport streamable-http", linkedin_section)
-
- def test_boss_setup_is_agent_driven_and_reproducible(self):
- root = Path(__file__).resolve().parents[1]
- install_doc = (root / "docs" / "install.md").read_text(encoding="utf-8")
- skill = (root / "agent_reach" / "skill" / "SKILL.md").read_text(
- encoding="utf-8"
- )
- career = (
- root / "agent_reach" / "skill" / "references" / "career.md"
- ).read_text(encoding="utf-8")
- readme = (root / "README.md").read_text(encoding="utf-8")
-
- for content in (install_doc, skill, readme):
- self.assertIn("帮我配 Boss直聘", content)
- self.assertIn("agent-reach install --env=local --system --channels=boss", install_doc)
- self.assertIn("--remote-debugging-address=127.0.0.1", install_doc)
- self.assertIn("用户手动登录", install_doc)
- self.assertIn("完全控制", install_doc)
-
- self.assertIn(
- 'auth = AuthManager(Path.home() / ".boss-agent")', career
- )
- self.assertIn('browser_source="existing-browser"', career)
- self.assertIn("job_card_browser", career)
- self.assertIn("4c991b77086a203173bf08a4cb64a23af6514fe6", career)
- self.assertIn("ENVIRONMENT_RISK", career)
- self.assertIn("--browser-source existing-browser", career)
- self.assertIn("长期复用", career)
- self.assertNotIn("code 37(TOKEN_REFRESH_FAILED)→ 重新登录", career)
- self.assertNotIn("client = BossClient(auth", career)
-
- def test_localized_readmes_use_current_linkedin_server_name(self):
- root = Path(__file__).resolve().parents[1]
- for name in ("README_ja.md", "README_ko.md"):
- content = (root / "docs" / name).read_text(encoding="utf-8")
- self.assertIn("mcp-server-linkedin", content)
- self.assertNotIn("linkedin-scraper-mcp", content)
-
- def test_skill_install_command_exits_nonzero_when_install_fails(self):
- with patch("agent_reach.cli._install_skill", return_value=False):
- with self.assertRaises(SystemExit) as raised:
- _cmd_skill(Namespace(install=True, uninstall=False))
-
- self.assertEqual(raised.exception.code, 1)
-
- def test_install_skill_creates_skill_md(self):
- """_install_skill should create SKILL.md in the first available skill dir."""
- with tempfile.TemporaryDirectory() as tmpdir:
- skill_dir = os.path.join(tmpdir, "skills")
- os.makedirs(skill_dir)
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda p: p.replace("~", tmpdir),
- ), patch.dict(os.environ, {}, clear=False):
- # Remove OPENCLAW_HOME to avoid interference
- env = os.environ.copy()
- env.pop("OPENCLAW_HOME", None)
- with patch.dict(os.environ, env, clear=True):
- _install_skill()
-
- # Check at least one known skill dir pattern
- for dirpath, _, filenames in os.walk(tmpdir):
- if "SKILL.md" in filenames:
- # Verify content is non-empty
- with open(os.path.join(dirpath, "SKILL.md"), encoding="utf-8") as f:
- content = f.read()
- self.assertIn("Agent Reach", content)
- # _install_skill may or may not find dirs depending on mock; just ensure no crash
- # The important test is that the function runs without error
-
- def test_uninstall_skill_removes_dir(self):
- """_uninstall_skill should remove skill directories."""
- with tempfile.TemporaryDirectory() as tmpdir:
- # Create a fake skill installation
- skill_path = os.path.join(tmpdir, ".openclaw", "skills", "agent-reach")
- os.makedirs(skill_path)
- with open(os.path.join(skill_path, "SKILL.md"), "w", encoding="utf-8") as f:
- f.write("test")
-
- self.assertTrue(os.path.exists(skill_path))
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda p: p.replace("~", tmpdir),
- ), patch.dict(os.environ, {}, clear=False):
- env = os.environ.copy()
- env.pop("OPENCLAW_HOME", None)
- with patch.dict(os.environ, env, clear=True):
- _uninstall_skill()
-
- self.assertFalse(os.path.exists(skill_path))
-
- def test_install_creates_dir_if_parent_exists(self):
- """_install_skill should create agent-reach dir inside existing skill dir."""
- with tempfile.TemporaryDirectory() as tmpdir:
- # Create the .openclaw/skills parent but not agent-reach subdir
- skill_parent = os.path.join(tmpdir, ".openclaw", "skills")
- os.makedirs(skill_parent)
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda p: p.replace("~", tmpdir),
- ), patch.dict(os.environ, {}, clear=False):
- env = os.environ.copy()
- env.pop("OPENCLAW_HOME", None)
- with patch.dict(os.environ, env, clear=True):
- _install_skill()
-
- target = os.path.join(skill_parent, "agent-reach", "SKILL.md")
- self.assertTrue(os.path.exists(target))
- with open(target, encoding="utf-8") as f:
- content = f.read()
- self.assertIn("Agent Reach", content)
-
- def test_install_uses_english_skill_for_english_locale(self):
- """_install_skill should install the English skill file for English locales."""
- with tempfile.TemporaryDirectory() as tmpdir:
- skill_parent = os.path.join(tmpdir, ".openclaw", "skills")
- os.makedirs(skill_parent)
-
- with patch(
- "agent_reach.cli.os.path.expanduser",
- side_effect=lambda p: p.replace("~", tmpdir),
- ):
- env = os.environ.copy()
- env.pop("OPENCLAW_HOME", None)
- env["LANG"] = "en_US.UTF-8"
- with patch.dict(os.environ, env, clear=True):
- _install_skill()
-
- target = os.path.join(skill_parent, "agent-reach", "SKILL.md")
- self.assertTrue(os.path.exists(target))
- with open(target, encoding="utf-8") as f:
- content = f.read()
- self.assertTrue(content.strip())
- self.assertIn("Xiaoyuzhou Podcast, LinkedIn", content)
- self.assertNotIn("搜推特", content)
- self.assertTrue(
- os.path.exists(os.path.join(skill_parent, "agent-reach", "references"))
- )
-
-
-if __name__ == "__main__":
- unittest.main()
diff --git a/tests/test_transcribe.py b/tests/test_transcribe.py
index 4c2d6ba2..279ead47 100644
--- a/tests/test_transcribe.py
+++ b/tests/test_transcribe.py
@@ -859,43 +859,6 @@ class TestSubprocessDecoding:
tr._probe_audio_duration(tmp_path / "audio.m4a")
-# --- YouTubeChannel integration --------------------------------------- #
-
-
-class TestYouTubeChannelTranscribe:
- def test_delegates_to_transcribe(self, monkeypatch, fake_config):
- from agent_reach.channels.youtube import YouTubeChannel
-
- captured = {}
-
- def fake_transcribe(
- source,
- *,
- provider="auto",
- out_dir=None,
- config=None,
- allow_provider_fallback=False,
- ):
- captured["source"] = source
- captured["provider"] = provider
- captured["config"] = config
- captured["allow_provider_fallback"] = allow_provider_fallback
- return "delegated text"
-
- monkeypatch.setattr(tr, "transcribe", fake_transcribe)
- out = YouTubeChannel().transcribe(
- "https://youtu.be/abc",
- provider="groq",
- config=fake_config,
- allow_provider_fallback=True,
- )
- assert out == "delegated text"
- assert captured["source"] == "https://youtu.be/abc"
- assert captured["provider"] == "groq"
- assert captured["config"] is fake_config
- assert captured["allow_provider_fallback"] is True
-
-
# --- Config feature requirement --------------------------------------- #
diff --git a/tests/test_twitter_channel.py b/tests/test_twitter_channel.py
deleted file mode 100644
index 12dc2251..00000000
--- a/tests/test_twitter_channel.py
+++ /dev/null
@@ -1,171 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Twitter health checks must never trigger upstream browser-cookie fallback."""
-
-import os
-from unittest.mock import Mock, patch
-
-from agent_reach.backends import OpenCLIStatus
-from agent_reach.channels.twitter import (
- TwitterChannel,
- twitter_cli_child_env,
-)
-
-
-def _which(*present):
- return lambda name: f"/usr/local/bin/{name}" if name in present else None
-
-
-def test_twitter_cli_without_explicit_auth_is_unverified():
- channel = TwitterChannel()
- with patch("shutil.which", side_effect=_which("twitter")), patch(
- "subprocess.run",
- side_effect=AssertionError("twitter status must not run"),
- ):
- status, message = channel.check()
-
- assert status == "warn"
- assert "Cookie-Editor" in message
- assert channel.active_backend is None
-
-
-def test_saved_credentials_are_recognised_without_starting_upstream(
- monkeypatch,
-):
- config = Mock()
- config.get.side_effect = lambda key: {
- "twitter_auth_token": "saved-auth-token",
- "twitter_ct0": "saved-ct0",
- }.get(key)
- monkeypatch.delenv("TWITTER_AUTH_TOKEN", raising=False)
- monkeypatch.delenv("TWITTER_CT0", raising=False)
-
- with patch("shutil.which", side_effect=_which("twitter")), patch(
- "subprocess.run"
- ) as run:
- channel = TwitterChannel()
- status, message = channel.check(config)
-
- assert status == "warn"
- assert "已配置" in message
- assert "不会执行" in message
- assert channel.active_backend is None
- run.assert_not_called()
- assert "TWITTER_AUTH_TOKEN" not in os.environ
- assert "TWITTER_CT0" not in os.environ
-
-
-def test_child_env_keeps_existing_shell_credentials_authoritative(
- monkeypatch,
-):
- config = Mock()
- config.get.side_effect = lambda key: {
- "twitter_auth_token": "saved-auth-token",
- "twitter_ct0": "saved-ct0",
- }.get(key)
- monkeypatch.setenv("TWITTER_AUTH_TOKEN", "shell-auth-token")
- monkeypatch.setenv("TWITTER_CT0", "shell-ct0")
-
- assert twitter_cli_child_env(config) == {}
- assert os.environ["TWITTER_AUTH_TOKEN"] == "shell-auth-token"
- assert os.environ["TWITTER_CT0"] == "shell-ct0"
-
-
-def test_child_env_supplies_only_missing_saved_credentials(monkeypatch):
- config = Mock()
- config.get.side_effect = lambda key: {
- "twitter_auth_token": "saved-auth-token",
- "twitter_ct0": "saved-ct0",
- }.get(key)
- monkeypatch.setenv("TWITTER_AUTH_TOKEN", "shell-auth-token")
- monkeypatch.delenv("TWITTER_CT0", raising=False)
-
- assert twitter_cli_child_env(config) == {"TWITTER_CT0": "saved-ct0"}
-
-
-def test_bird_with_explicit_env_remains_unverified(monkeypatch):
- monkeypatch.setenv("AUTH_TOKEN", "explicit-auth")
- monkeypatch.setenv("CT0", "explicit-ct0")
- with patch("shutil.which", side_effect=_which("bird")), patch(
- "subprocess.run",
- side_effect=AssertionError("bird check must not run"),
- ):
- channel = TwitterChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert "未实时验证" in message
- assert channel.active_backend is None
-
-
-def test_bird_without_explicit_env_is_warn(monkeypatch):
- monkeypatch.delenv("AUTH_TOKEN", raising=False)
- monkeypatch.delenv("CT0", raising=False)
- with patch("shutil.which", side_effect=_which("bird")):
- channel = TwitterChannel()
- status, message = channel.check()
-
- assert status == "warn"
- assert "未检测到显式" in message
- assert channel.active_backend is None
-
-
-def test_nothing_installed_returns_install_hint():
- channel = TwitterChannel()
- with patch("shutil.which", return_value=None):
- status, message = channel.check()
-
- assert status == "warn"
- assert "twitter-cli" in message
- assert channel.active_backend is None
-
-
-def test_opencli_bridge_ready_is_unverified_for_twitter():
- with patch(
- "agent_reach.backends.opencli_status",
- return_value=OpenCLIStatus(
- installed=True,
- extension_connected=True,
- version="1.8.6",
- ),
- ):
- status, message = TwitterChannel()._check_opencli()
-
- assert status == "warn"
- assert "桥接已连接" in message
- assert "登录态和实际命令未实时验证" in message
-
-
-def test_verified_backend_result_wins_over_unverified_twitter_cli():
- channel = TwitterChannel()
- with patch.object(
- TwitterChannel,
- "_check_twitter_cli",
- return_value=("warn", "twitter-cli 未验证"),
- ), patch.object(
- TwitterChannel,
- "_check_opencli",
- return_value=("ok", "OpenCLI 可用"),
- ), patch.object(TwitterChannel, "_check_bird", return_value=None):
- status, message = channel.check()
-
- assert status == "ok"
- assert message == "OpenCLI 可用"
- assert channel.active_backend == "OpenCLI"
-
-
-def test_all_warn_returns_first_warning_without_active_backend():
- channel = TwitterChannel()
- with patch.object(
- TwitterChannel,
- "_check_twitter_cli",
- return_value=("warn", "twitter-cli 未验证"),
- ), patch.object(
- TwitterChannel,
- "_check_opencli",
- return_value=("warn", "扩展未连接"),
- ), patch.object(TwitterChannel, "_check_bird", return_value=None):
- status, message = channel.check()
-
- assert status == "warn"
- assert message == "twitter-cli 未验证"
- assert channel.active_backend is None
diff --git a/tests/test_unified_entry.py b/tests/test_unified_entry.py
index 5ca2c298..6b3dd78e 100644
--- a/tests/test_unified_entry.py
+++ b/tests/test_unified_entry.py
@@ -181,12 +181,13 @@ def test_read_routes_by_url(capsys, fake_cli):
assert out["items"][0]["title"] == "https://fake.test/a"
-def test_handles_only_claims_unified_commands(fake_cli):
- assert unified.handles(["fake", "search"])
- assert unified.handles(["channels"])
- assert unified.handles(["doctor"])
- assert unified.handles([])
- assert not unified.handles(["check-update"])
+def test_unknown_command_is_bad_input(capsys, fake_cli):
+ for argv in (["install"], ["check-update"], ["nosuchchannel", "search", "x"]):
+ code, out = _run(capsys, argv)
+ assert code == 1
+ assert out["ok"] is False
+ assert out["error"]["code"] == "BAD_INPUT"
+ assert "agent-reach help" in out["error"]["message"]
def test_channels_lists_usage_for_agents(capsys, fake_cli):
diff --git a/tests/test_v2ex_channel.py b/tests/test_v2ex_channel.py
index 4704c09a..b7537563 100644
--- a/tests/test_v2ex_channel.py
+++ b/tests/test_v2ex_channel.py
@@ -16,7 +16,6 @@ import ssl
import subprocess
from unittest.mock import patch
from urllib.error import URLError
-from urllib.parse import parse_qs, urlsplit
import pytest
@@ -35,22 +34,8 @@ def test_can_handle_matches_v2ex_hosts():
# --- check() ---
-def test_check_ok_sets_active_backend():
- ch = V2EXChannel()
- with patch.object(v2, "_get_json", return_value=[{"id": 1}]):
- status, message = ch.check()
- assert status == "ok"
- assert ch.active_backend == ch.backends[0]
-def test_check_warn_on_exception_clears_backend():
- ch = V2EXChannel()
- ch.active_backend = "stale"
- with patch.object(v2, "_get_json", side_effect=OSError("no proxy")):
- status, message = ch.check()
- assert status == "warn"
- assert "连接失败" in message
- assert ch.active_backend is None
def test_get_json_retries_unexpected_tls_eof_with_bounded_curl():
@@ -135,205 +120,39 @@ def test_get_json_rejects_non_api_targets_before_network(url):
run.assert_not_called()
-def test_check_is_healthy_when_native_curl_recovers_tls_eof():
- ch = V2EXChannel()
- tls_error = ssl.SSLError(
- "[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol"
- )
-
- with patch.object(v2, "_get_json_with_urllib", side_effect=tls_error), patch.object(
- v2.shutil, "which", return_value="/usr/bin/curl"
- ), patch.object(
- v2.subprocess,
- "run",
- return_value=subprocess.CompletedProcess(["curl"], 0, "[]", ""),
- ):
- status, _message = ch.check()
-
- assert status == "ok"
- assert ch.active_backend == ch.backends[0]
# --- get_hot_topics / get_node_topics ---
-def test_get_hot_topics_maps_node_and_truncates_content():
- ch = V2EXChannel()
- items = [{
- "id": 9, "title": "T", "url": "https://www.v2ex.com/t/9",
- "replies": 12, "content": "x" * 300,
- "node": {"name": "python", "title": "Python"},
- }]
- with patch.object(v2, "_get_json", return_value=items):
- topics = ch.get_hot_topics(limit=5)
- t = topics[0]
- assert t["node_name"] == "python"
- assert t["node_title"] == "Python"
- assert len(t["content"]) == 200
- assert t["replies"] == 12
-
-
-def test_get_hot_topics_respects_limit():
- ch = V2EXChannel()
- items = [{"id": i} for i in range(10)]
- with patch.object(v2, "_get_json", return_value=items):
- assert len(ch.get_hot_topics(limit=3)) == 3
-def test_get_node_topics_falls_back_to_requested_node_name():
- ch = V2EXChannel()
- # node missing in the payload -> node_name falls back to the requested one
- with patch.object(v2, "_get_json", return_value=[{"id": 1, "title": "x"}]):
- topics = ch.get_node_topics("jobs")
- assert topics[0]["node_name"] == "jobs"
- "node_name",
- ["python&page=99", "foo#bar", "c++", "Python 开发"],
-)
-def test_get_node_topics_percent_encodes_node_name(node_name):
- ch = V2EXChannel()
- captured = {}
- def fake_get_json(url):
- captured["url"] = url
- return []
- with patch.object(v2, "_get_json", side_effect=fake_get_json):
- ch.get_node_topics(node_name)
-
- parts = urlsplit(captured["url"])
- query = parse_qs(parts.query)
- assert parts.fragment == ""
- assert query["node_name"] == [node_name]
- assert query["page"] == ["1"]
# --- get_topic: list-or-dict shape + replies fetch + fallbacks ---
-def test_get_topic_unwraps_list_and_maps_replies():
- ch = V2EXChannel()
- topic = [{
- "id": 42, "title": "Hello", "url": "https://www.v2ex.com/t/42",
- "content": "body", "replies": 2,
- "node": {"name": "tech", "title": "Tech"},
- "member": {"username": "op"},
- }]
- replies = [
- {"member": {"username": "alice"}, "content": "nice", "created": 1},
- {"member": {"username": "bob"}, "content": "+1", "created": 2},
- ]
- with patch.object(v2, "_get_json", side_effect=[topic, replies]):
- result = ch.get_topic(42)
- assert result["id"] == 42
- assert result["author"] == "op"
- assert result["node_name"] == "tech"
- assert len(result["replies"]) == 2
- assert result["replies"][0] == {"author": "alice", "content": "nice", "created": 1}
-
-def test_get_topic_survives_failing_replies_fetch():
- ch = V2EXChannel()
- topic = {"id": 7, "title": "x"} # dict shape (not a list)
- with patch.object(v2, "_get_json", side_effect=[topic, OSError("boom")]):
- result = ch.get_topic(7)
- assert result["id"] == 7
- assert result["replies"] == [] # failed replies fetch degrades to empty
-def test_get_topic_url_fallback_when_missing():
- ch = V2EXChannel()
- with patch.object(v2, "_get_json", side_effect=[[], []]):
- result = ch.get_topic(99)
- assert result["id"] == 99
- assert result["url"] == "https://www.v2ex.com/t/99"
-def test_get_topic_percent_encodes_topic_id_in_both_requests():
- ch = V2EXChannel()
- captured = []
- def fake_get_json(url):
- captured.append(url)
- return [{"id": 1}] if len(captured) == 1 else []
-
- with patch.object(v2, "_get_json", side_effect=fake_get_json):
- ch.get_topic("1#&page=99")
-
- topic_parts = urlsplit(captured[0])
- replies_parts = urlsplit(captured[1])
- assert topic_parts.fragment == ""
- assert replies_parts.fragment == ""
- assert parse_qs(topic_parts.query)["id"] == ["1#&page=99"]
- assert parse_qs(replies_parts.query)["topic_id"] == ["1#&page=99"]
- assert parse_qs(replies_parts.query)["page"] == ["1"]
# --- get_user: field mapping + avatar/url fallbacks ---
-def test_get_user_maps_fields_and_prefers_large_avatar():
- ch = V2EXChannel()
- data = {
- "id": 1, "username": "neo", "github": "neo-gh",
- "avatar_large": "/large.png", "avatar_normal": "/normal.png",
- }
- with patch.object(v2, "_get_json", return_value=data):
- user = ch.get_user("neo")
- assert user["github"] == "neo-gh"
- assert user["avatar"] == "/large.png"
-
-
-def test_get_user_avatar_falls_back_to_normal():
- ch = V2EXChannel()
- with patch.object(v2, "_get_json", return_value={"avatar_normal": "/normal.png"}):
- user = ch.get_user("neo")
- assert user["avatar"] == "/normal.png"
- # url + username fall back to the requested handle
- assert user["username"] == "neo"
- assert user["url"] == "https://www.v2ex.com/member/neo"
-def test_get_user_percent_encodes_username():
- ch = V2EXChannel()
- captured = {}
- def fake_get_json(url):
- captured["url"] = url
- return {}
- with patch.object(v2, "_get_json", side_effect=fake_get_json):
- ch.get_user("张三&admin=true")
- parts = urlsplit(captured["url"])
- assert parts.fragment == ""
- assert parse_qs(parts.query)["username"] == ["张三&admin=true"]
-def test_fallback_display_urls_percent_encode_path_segments():
- ch = V2EXChannel()
- with patch.object(v2, "_get_json", return_value={}):
- user_url = ch.get_user("a b/c")["url"]
- with patch.object(v2, "_get_json", side_effect=[{}, []]):
- topic_url = ch.get_topic("9 9")["url"]
-
- assert user_url == "https://www.v2ex.com/member/a%20b%2Fc"
- assert topic_url == "https://www.v2ex.com/t/9%209"
-
# --- search: intentionally offline (no public search endpoint) ---
-def test_search_returns_guidance_without_network():
- ch = V2EXChannel()
- with patch.object(v2, "_get_json", side_effect=AssertionError("must not hit network")):
- results = ch.search("python")
- assert len(results) == 1
- assert "error" in results[0]
- assert "python" in results[0]["error"]
-
-def test_search_guidance_percent_encodes_query():
- ch = V2EXChannel()
- message = ch.search("rust & go#lang")[0]["error"]
- assert "?q=rust+%26+go%23lang" in message
- assert "?q=rust & go#lang" not in message
diff --git a/tests/test_web_channel.py b/tests/test_web_channel.py
index 91606ef1..8757f07b 100644
--- a/tests/test_web_channel.py
+++ b/tests/test_web_channel.py
@@ -41,15 +41,6 @@ def test_can_handle_accepts_any_url():
# --- check: ready without any network probe (零开销兜底) ---
-def test_check_is_ok_and_touches_no_network():
- channel = WebChannel()
- with patch("urllib.request.urlopen") as mock_open:
- status, message = channel.check()
- assert status == "ok"
- assert channel.active_backend == "Jina Reader"
- assert "Jina Reader" in message
- # The fallback channel must stay zero-overhead: no probing on check().
- mock_open.assert_not_called()
# --- read: URL normalisation + Jina Reader request shape ---
diff --git a/tests/test_xhs_format.py b/tests/test_xhs_format.py
deleted file mode 100644
index 787ba186..00000000
--- a/tests/test_xhs_format.py
+++ /dev/null
@@ -1,133 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Tests for XiaoHongShu output formatter (issue #134)."""
-
-import unittest
-
-from agent_reach.channels.xiaohongshu import format_xhs_result
-
-
-class TestFormatXhsResult(unittest.TestCase):
- """Test format_xhs_result strips redundant fields."""
-
- SAMPLE_NOTE = {
- "id": "abc123",
- "title": "测试笔记",
- "desc": "这是正文内容",
- "type": "normal",
- "xsec_token": "tok_xxx",
- "user": {
- "nickname": "小红",
- "user_id": "u123",
- "avatar": "https://example.com/avatar.jpg",
- "extra_field": "should be dropped",
- },
- "interact_info": {
- "liked_count": "100",
- "collected_count": "50",
- "comment_count": "20",
- "share_count": "10",
- "sticky_count": "0",
- "relation": "none",
- },
- "image_list": [
- {
- "url": "https://img.example.com/1.jpg",
- "info_list": [{"url": "https://img.example.com/1_small.jpg", "image_scene": "WB_DFT"}],
- "width": 1080,
- "height": 1440,
- "trace_id": "tr_123",
- },
- {
- "url": "https://img.example.com/2.jpg",
- "info_list": [{"url": "https://img.example.com/2_small.jpg"}],
- "width": 1080,
- "height": 1080,
- },
- ],
- "tag_list": [
- {"id": "t1", "name": "旅行", "type": "topic"},
- {"id": "t2", "name": "美食", "type": "topic"},
- ],
- "at_user_list": [],
- "geo_info": {"latitude": 0, "longitude": 0},
- "audit_info": {"audit_status": 0},
- "model_type": None,
- "note_flow_source": "search",
- }
-
- def test_single_note_keeps_useful_fields(self):
- result = format_xhs_result(self.SAMPLE_NOTE)
- self.assertEqual(result["id"], "abc123")
- self.assertEqual(result["title"], "测试笔记")
- self.assertEqual(result["desc"], "这是正文内容")
- self.assertEqual(result["type"], "normal")
- self.assertEqual(result["user"]["nickname"], "小红")
- self.assertEqual(result["liked_count"], "100")
- self.assertEqual(result["collected_count"], "50")
- self.assertEqual(result["images"], [
- "https://img.example.com/1.jpg",
- "https://img.example.com/2.jpg",
- ])
- self.assertEqual(result["tags"], ["旅行", "美食"])
-
- def test_single_note_drops_useless_fields(self):
- result = format_xhs_result(self.SAMPLE_NOTE)
- self.assertNotIn("at_user_list", result)
- self.assertNotIn("geo_info", result)
- self.assertNotIn("audit_info", result)
- self.assertNotIn("model_type", result)
- self.assertNotIn("note_flow_source", result)
- # User should not have extra fields
- self.assertNotIn("avatar", result.get("user", {}))
- self.assertNotIn("extra_field", result.get("user", {}))
-
- def test_search_results_wrapper(self):
- """Handle {"items": [...]} wrapper from search_feeds."""
- wrapped = {"items": [self.SAMPLE_NOTE, self.SAMPLE_NOTE]}
- result = format_xhs_result(wrapped)
- self.assertIsInstance(result, list)
- self.assertEqual(len(result), 2)
- self.assertEqual(result[0]["title"], "测试笔记")
-
- def test_list_input(self):
- result = format_xhs_result([self.SAMPLE_NOTE])
- self.assertIsInstance(result, list)
- self.assertEqual(len(result), 1)
- self.assertEqual(result[0]["title"], "测试笔记")
-
- def test_note_card_wrapper(self):
- """Handle notes nested under 'note_card'."""
- wrapped = {"note_card": self.SAMPLE_NOTE}
- result = format_xhs_result(wrapped)
- self.assertEqual(result["title"], "测试笔记")
-
- def test_with_comments(self):
- note = dict(self.SAMPLE_NOTE)
- note["comments"] = [
- {
- "content": "写得好!",
- "user_info": {"nickname": "路人甲", "user_id": "u456"},
- "like_count": 5,
- "sub_comment_count": 1,
- "ip_location": "上海",
- "status": 0,
- }
- ]
- result = format_xhs_result(note)
- self.assertEqual(len(result["comments"]), 1)
- self.assertEqual(result["comments"][0]["content"], "写得好!")
- self.assertEqual(result["comments"][0]["user"], "路人甲")
- self.assertEqual(result["comments"][0]["like_count"], 5)
- self.assertNotIn("ip_location", result["comments"][0])
-
- def test_empty_input(self):
- self.assertEqual(format_xhs_result({}), {})
- self.assertEqual(format_xhs_result([]), [])
-
- def test_non_dict_passthrough(self):
- self.assertEqual(format_xhs_result("hello"), "hello")
- self.assertIsNone(format_xhs_result(None))
-
-
-if __name__ == "__main__":
- unittest.main()
diff --git a/tests/test_xiaoyuzhou_install.py b/tests/test_xiaoyuzhou_install.py
deleted file mode 100644
index 15eb0157..00000000
--- a/tests/test_xiaoyuzhou_install.py
+++ /dev/null
@@ -1,330 +0,0 @@
-# -*- coding: utf-8 -*-
-
-import os
-import re
-import subprocess
-from pathlib import Path
-from unittest.mock import patch
-
-import pytest
-
-import agent_reach.cli as cli
-
-ROOT = Path(__file__).resolve().parents[1]
-TRANSCRIBE_SCRIPT = ROOT / "agent_reach" / "scripts" / "transcribe_xiaoyuzhou.sh"
-
-
-class _DummyConfig:
- def get(self, _key):
- return None
-
-
-def test_install_xiaoyuzhou_deps_does_not_raise_when_no_groq_key(
- monkeypatch, tmp_path, capsys
-):
- monkeypatch.setattr(
- cli.os.path,
- "expanduser",
- lambda value: value.replace("~", str(tmp_path)),
- )
- with patch("agent_reach.config.Config", return_value=_DummyConfig()), patch(
- "shutil.which", return_value=None
- ):
- cli._install_xiaoyuzhou_deps()
-
- out = capsys.readouterr().out
- assert "Xiaoyuzhou" in out
- assert "Groq API key not set" in out
-
-
-def test_install_xiaoyuzhou_deps_replaces_stale_managed_script(
- monkeypatch, tmp_path, capsys
-):
- import stat
-
- installed = tmp_path / ".agent-reach" / "tools" / "xiaoyuzhou" / "transcribe.sh"
- installed.parent.mkdir(parents=True)
- installed.write_text("#!/bin/sh\necho stale\n", encoding="utf-8")
-
- monkeypatch.setattr(
- cli.os.path,
- "expanduser",
- lambda value: value.replace("~", str(tmp_path)),
- )
- monkeypatch.setattr("agent_reach.config.Config", lambda: _DummyConfig())
- monkeypatch.setattr("shutil.which", lambda _name: None)
-
- cli._install_xiaoyuzhou_deps()
-
- assert installed.read_text(encoding="utf-8") == TRANSCRIBE_SCRIPT.read_text(
- encoding="utf-8"
- )
- if os.name != "nt":
- assert installed.stat().st_mode & stat.S_IXUSR
- assert "script updated" in capsys.readouterr().out
-
-
-def test_transcribe_script_is_cross_platform_shell_syntax(bash_executable):
- subprocess.run(
- [bash_executable, "-n", TRANSCRIBE_SCRIPT.relative_to(ROOT).as_posix()],
- check=True,
- cwd=ROOT,
- )
-
-
-def test_transcribe_script_handles_git_bash_python_and_size_math():
- text = TRANSCRIBE_SCRIPT.read_text(encoding="utf-8")
- assert "command -v python3" in text
- assert "command -v python" in text
- assert "command -v py" in text
- assert "cygpath -w" in text
- assert "| bc" not in text
-
-
-def _bash_path(path: Path) -> str:
- """Render a native path for a Bash process, including Git Bash on Windows."""
- rendered = path.resolve().as_posix()
- if os.name == "nt" and len(rendered) >= 3 and rendered[1:3] == ":/":
- return f"/{rendered[0].lower()}{rendered[2:]}"
- return rendered
-
-
-def _append_bash_function(path: Path, name: str, script: str) -> None:
- lines = script.splitlines()
- if lines and lines[0].startswith("#!"):
- lines = lines[1:]
- body = "\n".join(lines)
- with path.open("a", encoding="utf-8") as handle:
- handle.write(f"{name}() {{\n{body}\n}}\n")
-
-
-def _script_env(
- tmp_path: Path, curl_script: str
-) -> tuple[dict[str, str], Path, Path, Path]:
- curl_log = tmp_path / "curl.log"
- temp_root = tmp_path / "tmp"
- temp_root.mkdir()
- bash_env = tmp_path / "bash-env.sh"
- _append_bash_function(bash_env, "curl", curl_script)
-
- env = os.environ.copy()
- env.update({
- "BASH_ENV": _bash_path(bash_env),
- "CURL_LOG": _bash_path(curl_log),
- "GROQ_API_KEY": "test-key",
- "TMPDIR": _bash_path(temp_root),
- })
- return env, curl_log, temp_root, bash_env
-
-
-def _assert_work_dir_cleaned(temp_root: Path) -> None:
- assert list(temp_root.glob("agent-reach-xiaoyuzhou.*")) == []
-
-
- "url",
- [
- "ftp://xiaoyuzhoufm.com/episode/123",
- "https://notxiaoyuzhoufm.com/episode/123",
- "https://xiaoyuzhoufm.com.evil.example/episode/123",
- "https://evil.example/episode/123?next=xiaoyuzhoufm.com",
- ],
-)
-def test_transcribe_script_rejects_non_xiaoyuzhou_urls_before_curl(
- tmp_path, url, bash_executable
-):
- env, curl_log, temp_root, _ = _script_env(
- tmp_path,
- "#!/bin/sh\nprintf 'called\\n' >> \"$CURL_LOG\"\nexit 42\n",
- )
-
- result = subprocess.run(
- [
- bash_executable,
- TRANSCRIBE_SCRIPT.relative_to(ROOT).as_posix(),
- url,
- _bash_path(tmp_path / "out.txt"),
- ],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- env=env,
- cwd=ROOT,
- )
-
- assert result.returncode != 0
- assert "仅支持 xiaoyuzhoufm.com" in result.stderr
- assert not curl_log.exists()
- _assert_work_dir_cleaned(temp_root)
-
-
- "url",
- [
- "http://xiaoyuzhoufm.com/episode/123",
- "https://www.xiaoyuzhoufm.com/episode/123",
- ],
-)
-def test_transcribe_script_accepts_http_xiaoyuzhou_hosts(
- tmp_path, url, bash_executable
-):
- env, curl_log, temp_root, _ = _script_env(
- tmp_path,
- "#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$CURL_LOG\"\nexit 42\n",
- )
-
- result = subprocess.run(
- [
- bash_executable,
- TRANSCRIBE_SCRIPT.relative_to(ROOT).as_posix(),
- url,
- _bash_path(tmp_path / "out.txt"),
- ],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- env=env,
- cwd=ROOT,
- )
-
- assert result.returncode != 0
- assert curl_log.exists()
- _assert_work_dir_cleaned(temp_root)
-
-
-def test_transcribe_script_uses_secure_temp_and_bounded_curl_calls():
- text = TRANSCRIBE_SCRIPT.read_text(encoding="utf-8")
-
- assert "mktemp -d" in text
- assert "xiaoyuzhou_$$" not in text
- assert "/tmp/podcast_transcript.txt" not in text
- assert 'mktemp "${TEMP_ROOT%/}/agent-reach-transcript.XXXXXX"' in text
- assert "trap cleanup EXIT" in text
- assert text.count('--connect-timeout "$CURL_CONNECT_TIMEOUT"') == 4
- assert text.count('--max-time "$GROQ_TIMEOUT"') == 2
- assert text.count("--fail --show-error --location") == 2
- assert text.count("--max-filesize") == 4
- assert text.count('--max-filesize "$MAX_API_RESPONSE_BYTES"') == 2
- assert "MAX_DURATION_SECONDS=10800" in text
- assert '-t "$MAX_DURATION_SECONDS"' in text
- assert 'if [ "$WAIT_SEC" -gt 900 ]' in text
- assert "r.read(32 * 1024 * 1024 + 1)" in text
-
- page_limit = int(re.search(r"^MAX_PAGE_BYTES=(\d+)$", text, re.MULTILINE).group(1))
- audio_limit = int(re.search(r"^MAX_AUDIO_BYTES=(\d+)$", text, re.MULTILINE).group(1))
- api_response_limit = int(
- re.search(r"^MAX_API_RESPONSE_BYTES=(\d+)$", text, re.MULTILINE).group(1)
- )
- assert page_limit <= 10 * 1024 * 1024
- assert 25 * 1024 * 1024 <= audio_limit <= 2 * 1024 * 1024 * 1024
- assert api_response_limit <= 32 * 1024 * 1024
-
-
[email protected]("ffprobe_output", ["", "not-a-number"])
-def test_transcribe_script_fails_clearly_for_invalid_duration(
- tmp_path, ffprobe_output, bash_executable
-):
- env, _, temp_root, bash_env = _script_env(
- tmp_path,
- """#!/bin/bash
-output=""
-while [ "$#" -gt 0 ]; do
- if [ "$1" = "-o" ]; then
- output="$2"
- shift 2
- else
- shift
- fi
-done
-if [ -n "$output" ]; then
- printf 'fake audio' > "$output"
-else
- printf '%s' '<html><script>"title":"Test"</script>https://media.xyzcdn.net/test.mp3</html>'
-fi
-""",
- )
- _append_bash_function(
- bash_env,
- "ffprobe",
- "#!/bin/sh\nprintf '%s' \"$FFPROBE_OUTPUT\"\n",
- )
- env["FFPROBE_OUTPUT"] = ffprobe_output
-
- result = subprocess.run(
- [
- bash_executable,
- TRANSCRIBE_SCRIPT.relative_to(ROOT).as_posix(),
- "https://www.xiaoyuzhoufm.com/episode/123",
- _bash_path(tmp_path / "out.txt"),
- ],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- env=env,
- cwd=ROOT,
- )
-
- assert result.returncode != 0
- assert "ffprobe 返回无效音频时长" in result.stderr
- _assert_work_dir_cleaned(temp_root)
-
-
[email protected]("ffprobe_output", ["10801", "9" * 500])
-def test_transcribe_script_rejects_overlong_audio_before_ffmpeg_or_groq(
- tmp_path, ffprobe_output, bash_executable
-):
- env, curl_log, temp_root, bash_env = _script_env(
- tmp_path,
- """#!/bin/bash
-printf '%s\n' "$*" >> "$CURL_LOG"
-output=""
-while [ "$#" -gt 0 ]; do
- if [ "$1" = "-o" ]; then
- output="$2"
- shift 2
- else
- shift
- fi
-done
-if [ -n "$output" ]; then
- printf 'fake audio' > "$output"
-else
- printf '%s' '<html><script>"title":"Test"</script>https://media.xyzcdn.net/test.mp3</html>'
-fi
-""",
- )
- ffmpeg_marker = tmp_path / "ffmpeg-called"
- _append_bash_function(
- bash_env,
- "ffprobe",
- "#!/bin/sh\nprintf '%s' \"$FFPROBE_OUTPUT\"\n",
- )
- _append_bash_function(
- bash_env,
- "ffmpeg",
- "#!/bin/sh\nprintf 'called' > \"$FFMPEG_MARKER\"\n",
- )
- env["FFMPEG_MARKER"] = _bash_path(ffmpeg_marker)
- env["FFPROBE_OUTPUT"] = ffprobe_output
-
- result = subprocess.run(
- [
- bash_executable,
- TRANSCRIBE_SCRIPT.relative_to(ROOT).as_posix(),
- "https://www.xiaoyuzhoufm.com/episode/123",
- _bash_path(tmp_path / "out.txt"),
- ],
- capture_output=True,
- encoding="utf-8",
- errors="replace",
- env=env,
- cwd=ROOT,
- )
-
- assert result.returncode != 0
- assert "音频时长超过 3 小时限制" in result.stderr
- assert not ffmpeg_marker.exists()
- curl_calls = curl_log.read_text(encoding="utf-8").splitlines()
- assert len(curl_calls) == 2
- assert all("api.groq.com" not in call for call in curl_calls)
- _assert_work_dir_cleaned(temp_root)
diff --git a/tests/test_xueqiu_channel.py b/tests/test_xueqiu_channel.py
index 4b1ace2b..66eb3bd4 100644
--- a/tests/test_xueqiu_channel.py
+++ b/tests/test_xueqiu_channel.py
@@ -9,15 +9,8 @@ offline. Follow-up to #331 — extends dedicated channel coverage after rss
(#360), github (#361), web (#363) and reddit (#364).
"""
-import json
-import sys
-import types
-from unittest.mock import patch
-from urllib.parse import parse_qs, urlsplit
-import pytest
-from agent_reach.channels import xueqiu as xq
from agent_reach.channels.xueqiu import XueqiuChannel, _strip_html
# --- can_handle ---
@@ -40,243 +33,43 @@ def test_strip_html_removes_tags_and_decodes_entities():
# --- check(): single public endpoint, items present/empty/error ---
-def test_check_validates_detail_quote_endpoint():
- ch = XueqiuChannel()
- requested = []
- with patch.object(
- xq,
- "_get_json",
- side_effect=lambda url, config=None: requested.append(url)
- or {"data": {"quote": {"symbol": "SH601138", "pe_ttm": 38.1}}},
- ):
- status, message = ch.check()
-
- assert status == "ok"
- assert ch.active_backend == ch.backends[0]
- assert requested == [
- "https://stock.xueqiu.com/v5/stock/quote.json"
- "?symbol=SH601138&extend=detail"
- ]
-
-
-def test_check_warn_when_quote_empty():
- ch = XueqiuChannel()
- with patch.object(xq, "_get_json", return_value={"data": {"quote": {}}}):
- status, message = ch.check()
- assert status == "warn"
- assert "为空" in message
- assert ch.active_backend is None
-def test_check_warn_on_exception():
- import urllib.error
- ch = XueqiuChannel()
- with patch.object(xq, "_get_json", side_effect=urllib.error.URLError("refused")):
- status, message = ch.check()
- assert status == "warn"
- assert "连接失败" in message
- assert ch.active_backend is None
-def test_check_never_reads_browser_cookie_store_implicitly(monkeypatch):
- browser_reads = []
- fake_rookiepy = types.SimpleNamespace(
- chrome=lambda *_args, **_kwargs: browser_reads.append("rookiepy") or []
- )
- monkeypatch.setitem(sys.modules, "rookiepy", fake_rookiepy)
- monkeypatch.setattr(xq, "_cookies_initialized", False)
- monkeypatch.setattr(
- xq,
- "_load_cookies_from_config",
- lambda config=None: False,
- )
- class FakeResponse:
- def __enter__(self):
- return self
- def __exit__(self, *_args):
- return None
- def read(self):
- return b'{"data":{"quote":{"symbol":"SH601138","pe_ttm":38.1}}}'
- monkeypatch.setattr(xq._opener, "open", lambda *_args, **_kwargs: FakeResponse())
+# --- get_stock_quote: field mapping + missing-data fallback ---
- status, _message = XueqiuChannel().check()
- assert status == "ok"
- assert browser_reads == []
-# --- get_stock_quote: field mapping + missing-data fallback ---
-def test_get_stock_quote_maps_fields():
- ch = XueqiuChannel()
- payload = {"data": {"quote": {
- "symbol": "SH600519", "name": "贵州茅台", "current": 1700.5,
- "percent": 1.23, "volume": 1234, "pe_ttm": 30.1,
- "pe_forecast": 27.4, "pb": 8.2, "eps": 59.0,
- }}}
- requested = []
- with patch.object(
- xq, "_get_json", side_effect=lambda url: requested.append(url) or payload
- ):
- q = ch.get_stock_quote("SH600519")
-
- assert requested == [
- "https://stock.xueqiu.com/v5/stock/quote.json"
- "?symbol=SH600519&extend=detail"
- ]
- assert q["symbol"] == "SH600519"
- assert q["name"] == "贵州茅台"
- assert q["current"] == 1700.5
- assert q["volume"] == 1234
- assert q["pe_ttm"] == 30.1
- assert q["pe_forecast"] == 27.4
- assert q["pb"] == 8.2
- assert q["eps"] == 59.0
-
-
-def test_get_stock_quote_falls_back_when_no_items():
- ch = XueqiuChannel()
- with patch.object(xq, "_get_json", return_value={"data": {"items": []}}):
- q = ch.get_stock_quote("AAPL")
- assert q["symbol"] == "AAPL" # echoes the requested symbol
- assert q["name"] == ""
- assert q["current"] is None
+# --- search_stock: mapping + limit ---
-# --- search_stock: mapping + limit ---
-def test_search_stock_maps_and_respects_limit():
- ch = XueqiuChannel()
- stocks = [
- {"code": "SH600519", "name": "贵州茅台", "exchange": "SH"},
- {"code": "SZ000858", "name": "五粮液", "exchange": "SZ"},
- {"code": "SH601318", "name": "中国平安", "exchange": "SH"},
- ]
- with patch.object(xq, "_get_json", return_value={"stocks": stocks}):
- results = ch.search_stock("酒", limit=2)
- assert len(results) == 2
- assert results[0] == {"symbol": "SH600519", "name": "贵州茅台", "exchange": "SH"}
-
-
-def test_search_stock_handles_missing_stocks_key():
- ch = XueqiuChannel()
- with patch.object(xq, "_get_json", return_value={}):
- assert ch.search_stock("无") == []
# --- get_hot_posts: JSON-in-JSON unwrap, html strip, url build, bad data ---
-def test_get_hot_posts_unwraps_and_shapes():
- ch = XueqiuChannel()
- inner = {
- "id": 42, "title": "茅台大涨",
- "text": "<p>今天<b>大涨</b>&nbsp;了</p>",
- "user": {"screen_name": "韭菜王"},
- "like_count": 99, "target": "/SH600519/123",
- }
- payload = {"list": [{"data": json.dumps(inner, ensure_ascii=False)}]}
- with patch.object(xq, "_get_json", return_value=payload):
- posts = ch.get_hot_posts(limit=5)
- assert len(posts) == 1
- p = posts[0]
- assert p["id"] == 42
- assert p["title"] == "茅台大涨"
- assert p["text"] == "今天大涨 了" # html stripped, entity decoded
- assert p["author"] == "韭菜王"
- assert p["likes"] == 99
- assert p["url"] == "https://xueqiu.com/SH600519/123"
-
-
-def test_get_hot_posts_truncates_text_to_200_chars():
- ch = XueqiuChannel()
- inner = {"text": "x" * 500, "target": ""}
- payload = {"list": [{"data": json.dumps(inner)}]}
- with patch.object(xq, "_get_json", return_value=payload):
- posts = ch.get_hot_posts()
- assert len(posts[0]["text"]) == 200
- assert posts[0]["url"] == "" # no target -> no url
-def test_get_hot_posts_tolerates_bad_data_field():
- ch = XueqiuChannel()
- # one item with non-string data, one with invalid JSON -> both -> defaults
- payload = {"list": [{"data": 123}, {"data": "{not json"}]}
- with patch.object(xq, "_get_json", return_value=payload):
- posts = ch.get_hot_posts()
- assert len(posts) == 2
- for p in posts:
- assert p["id"] == 0
- assert p["author"] == ""
- assert p["url"] == ""
-
-
-def test_get_hot_posts_requests_the_requested_count():
- ch = XueqiuChannel()
- captured = {}
- def fake_get_json(url):
- captured["url"] = url
- return {"list": []}
- with patch.object(xq, "_get_json", side_effect=fake_get_json):
- ch.get_hot_posts(limit=50)
- assert parse_qs(urlsplit(captured["url"]).query)["count"] == ["50"]
-def test_get_hot_posts_clamps_count_to_documented_maximum():
- ch = XueqiuChannel()
- captured = {}
- payload = {"list": [{"data": "{}"}] * 60}
- def fake_get_json(url):
- captured["url"] = url
- return payload
- with patch.object(xq, "_get_json", side_effect=fake_get_json):
- posts = ch.get_hot_posts(limit=500)
- assert parse_qs(urlsplit(captured["url"]).query)["count"] == ["50"]
- assert len(posts) == 50
-def test_get_hot_posts_zero_limit_skips_network():
- ch = XueqiuChannel()
- with patch.object(
- xq,
- "_get_json",
- side_effect=AssertionError("zero limit must not make a request"),
- ):
- assert ch.get_hot_posts(limit=0) == []
-def test_get_hot_posts_rejects_negative_limit():
- ch = XueqiuChannel()
- with pytest.raises(ValueError, match="non-negative"):
- ch.get_hot_posts(limit=-1)
+# --- get_hot_stocks: ranking + code/symbol fallback ---
-# --- get_hot_stocks: ranking + code/symbol fallback ---
-def test_get_hot_stocks_ranks_and_falls_back_to_symbol():
- ch = XueqiuChannel()
- items = [
- {"code": "SH600519", "name": "贵州茅台", "current": 1700, "percent": 1.2},
- {"symbol": "SZ000858", "name": "五粮液", "current": 150, "percent": -0.5},
- ]
- with patch.object(xq, "_get_json", return_value={"data": {"items": items}}):
- results = ch.get_hot_stocks(limit=10)
- assert results[0]["rank"] == 1
- assert results[0]["symbol"] == "SH600519"
- assert results[1]["rank"] == 2
- assert results[1]["symbol"] == "SZ000858" # used `symbol` since `code` absent
-
-
-def test_get_hot_stocks_empty_when_no_items():
- ch = XueqiuChannel()
- with patch.object(xq, "_get_json", return_value={"data": {}}):
- assert ch.get_hot_stocks() == []
diff --git a/tests/test_youtube_channel.py b/tests/test_youtube_channel.py
index 1281e882..9cd02bce 100644
--- a/tests/test_youtube_channel.py
+++ b/tests/test_youtube_channel.py
@@ -12,11 +12,8 @@ reddit (#364), xueqiu (#365) and v2ex (#366).
"""
from pathlib import Path
-from unittest.mock import Mock, patch
-from agent_reach.channels import youtube as yt
-from agent_reach.channels.youtube import YouTubeChannel, _has_js_runtime_config
-from agent_reach.probe import ProbeResult
+from agent_reach.channels.youtube import YouTubeChannel
def _which(*present):
@@ -41,126 +38,33 @@ def test_can_handle_matches_youtube_hosts():
# --- _has_js_runtime_config ---
-def test_has_js_runtime_config_missing_file_is_false(tmp_path):
- assert _has_js_runtime_config(tmp_path / "nope.conf") is False
-def test_has_js_runtime_config_true_when_flag_present(tmp_path):
- cfg = tmp_path / "config"
- cfg.write_text("--js-runtimes deno\n--no-mtime\n", encoding="utf-8")
- assert _has_js_runtime_config(cfg) is True
-def test_has_js_runtime_config_false_when_flag_absent(tmp_path):
- cfg = tmp_path / "config"
- cfg.write_text("--no-mtime\n", encoding="utf-8")
- assert _has_js_runtime_config(cfg) is False
-def test_has_js_runtime_config_swallows_oserror(tmp_path):
- bad = tmp_path / "config"
- with patch.object(
- yt,
- "read_small_text_no_follow",
- side_effect=OSError("denied"),
- ):
- assert _has_js_runtime_config(bad) is False
# --- check(): yt-dlp probe states ---
-def test_check_off_when_ytdlp_missing():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("missing")):
- status, message = ch.check()
- assert status == "off"
- assert "yt-dlp[default]" in message
- assert ch.active_backend is None
-def test_check_error_when_ytdlp_broken():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("broken", hint="relink venv")):
- status, message = ch.check()
- assert status == "error"
- assert "relink venv" in message
- assert "yt-dlp[default]" in message
- assert ch.active_backend is None
-def test_check_error_when_ytdlp_unrunnable():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("timeout", hint="too slow")):
- status, message = ch.check()
- assert status == "error"
- assert ch.active_backend is None
# --- check(): JS runtime gating (backend stays yt-dlp once the probe is ok) ---
-def test_check_warn_when_no_js_runtime_but_backend_active():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which()): # no deno, no node
- status, message = ch.check()
- assert status == "warn"
- assert "JS runtime" in message
- assert "agent-reach install --system" in message
- assert ch.active_backend == "yt-dlp" # probe was ok → backend attributed
-def test_check_warn_when_node_only_and_config_missing_flag():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("node")), \
- patch.object(yt, "_has_js_runtime_config", return_value=False):
- status, message = ch.check()
- assert status == "warn"
- assert ch.active_backend == "yt-dlp"
-def test_check_tells_user_to_upgrade_when_ytdlp_predates_js_runtimes():
- ch = YouTubeChannel()
- probe = ProbeResult("ok", output="2025.10.22")
- with patch.object(yt, "probe_command", return_value=probe), \
- patch("shutil.which", side_effect=_which("node")), \
- patch.object(yt, "_has_js_runtime_config", return_value=False):
- status, message = ch.check()
-
- assert status == "warn"
- assert "升级" in message
- assert "--js-runtimes" not in message
- assert ch.active_backend == "yt-dlp"
-def test_check_does_not_prescribe_unverified_flag_when_version_is_unknown():
- ch = YouTubeChannel()
- probe = ProbeResult("ok", output="dev-build")
- with patch.object(yt, "probe_command", return_value=probe), \
- patch("shutil.which", side_effect=_which("node")), \
- patch.object(yt, "_has_js_runtime_config", return_value=False):
- status, message = ch.check()
- assert status == "warn"
- assert "无法确认" in message
- assert "升级" in message
- assert "yt-dlp[default]" in message
- assert "--js-runtimes" not in message
- assert ch.active_backend == "yt-dlp"
-def test_check_prescribes_js_runtimes_from_first_supported_stable_release():
- ch = YouTubeChannel()
- probe = ProbeResult("ok", output="2025.11.12")
- with patch.object(yt, "probe_command", return_value=probe), \
- patch("shutil.which", side_effect=_which("node")), \
- patch.object(yt, "_has_js_runtime_config", return_value=False):
- status, message = ch.check()
-
- assert status == "warn"
- assert "--js-runtimes node" in message
- assert ch.active_backend == "yt-dlp"
-
def test_constraints_pin_ytdlp_to_current_stable_release():
constraints = Path(__file__).parents[1] / "constraints.txt"
@@ -182,61 +86,13 @@ def test_project_installs_official_ytdlp_default_dependencies():
assert "yt-dlp-ejs==0.8.0" in constraints
-def test_check_ok_with_deno():
- ch = YouTubeChannel()
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("deno")):
- status, message = ch.check()
- assert status == "ok"
- assert message == "可提取视频信息和字幕"
- assert ch.active_backend == "yt-dlp"
# --- check(): transcription readiness surfaced (deno present so JS path is ok) ---
-def test_check_ok_reports_transcription_when_provider_and_ffmpeg_present():
- ch = YouTubeChannel()
- cfg = Mock()
- cfg.is_configured = lambda key: key == "groq_whisper"
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("deno", "ffmpeg", "ffprobe")):
- status, message = ch.check(config=cfg)
- assert status == "ok"
- assert "groq" in message
- assert "可转写音频" in message
-
-def test_check_lists_multiple_transcription_providers_without_implying_fallback():
- ch = YouTubeChannel()
- cfg = Mock()
- cfg.is_configured = lambda key: key in {"groq_whisper", "openai_whisper"}
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("deno", "ffmpeg", "ffprobe")):
- status, message = ch.check(config=cfg)
- assert status == "ok"
- assert "groq/openai" in message
- assert "groq→openai" not in message
-def test_check_ok_flags_missing_ffmpeg_for_transcription():
- ch = YouTubeChannel()
- cfg = Mock()
- cfg.is_configured = lambda key: key == "openai_whisper"
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("deno")): # provider yes, ffmpeg no
- status, message = ch.check(config=cfg)
- assert status == "ok"
- assert "ffmpeg" in message
-def test_check_ok_flags_missing_ffprobe_for_transcription():
- ch = YouTubeChannel()
- cfg = Mock()
- cfg.is_configured = lambda key: key == "openai_whisper"
- with patch.object(yt, "probe_command", return_value=ProbeResult("ok")), \
- patch("shutil.which", side_effect=_which("deno", "ffmpeg")):
- status, message = ch.check(config=cfg)
- assert status == "ok"
- assert "ffprobe" in message
- assert "可转写音频" not in message