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.

docs: one guide for install and update

Pnantbcb1f40caa63
diff --git a/.github/workflows/pytest.yml b/.github/workflows/pytest.yml
index 0bc01a4a..ec3d5cdb 100644
--- a/.github/workflows/pytest.yml
+++ b/.github/workflows/pytest.yml
@@ -111,7 +111,7 @@ jobs:
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')"
# Most users are on 1.5 (installed with pipx). Rehearse the documented
- # upgrade (docs/update.md step 3) on every OS: the new copy must win on PATH,
+ # upgrade (docs/install.md, "Upgrade from 1.5") on every OS: the new copy must win on PATH,
# keep the old config, explain the upgrade and remove the old pipx copy.
upgrade-from-1-5:
runs-on: ${{ matrix.os }}
@@ -155,7 +155,7 @@ jobs:
v="$(agent-reach version)"; echo "$v"
echo "$v" | grep -q "v1.5"
- - name: Upgrade as docs/update.md step 3 says
+ - name: Upgrade as docs/install.md says
run: |
uv tool install --force .
echo "$(uv tool dir --bin)" >> "$GITHUB_PATH"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7820fa4a..bbd545d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,7 +39,7 @@ English:
- 专用浏览器按扩展保存在它自己配置里的编号识别,不会再把用户日常的 Chrome 认成专用浏览器;登录窗口开着时查询不再把它收掉。
- 浏览器渠道可以并行查询:同一平台最多 2 条、合计 4 条同时跑,多出来的排队而不是立刻报"正忙";登录窗口、退出登录等操作等正在跑的查询结束再做。
- 没登录时报"需要登录"而不是"上游工具坏了":雪球社区(错误码 400016)、B站字幕(没有 B站登录)、LinkedIn(专用浏览器里没有 LinkedIn 登录)。
-- 从 1.5 升级更顺:update.md 先看版本再分流;`agent-reach update` 遇到 pip/pipx 装的旧版会自己换成 uv 安装;`setup` 删掉旧版 Agent Reach 程序(只删它自己,不动其他工具),安装汇报说明保留了什么、变了什么、以前用过哪些渠道可以加回来。安装地址改为始终指向最新正式版。
+- 从 1.5 升级更顺:安装和更新合成一份 install.md,先看版本再分流(旧版指向的 update.md 转到它);`agent-reach update` 遇到 pip/pipx 装的旧版会自己换成 uv 安装;`setup` 删掉旧版 Agent Reach 程序(只删它自己,不动其他工具),安装汇报说明保留了什么、变了什么、以前用过哪些渠道可以加回来。安装地址改为始终指向最新正式版。
- 平台出错时,报错原话和自带的处理建议原样交给 AI,由 AI 用平台名告诉用户哪个平台暂时有问题;不再用 Reach 自己编的建议覆盖("要登录"仍给 Reach 自己专用浏览器的登录步骤)。
English (technical):
@@ -52,7 +52,7 @@ English (technical):
- The dedicated browser is identified by the id its extension saves inside its own profile, so the user's own Chrome is never mistaken for it; a query no longer closes an open login window.
- Browser channels run queries in parallel: up to 2 per platform and 4 in total, with the rest queued instead of failing BUSY at once; login windows, logout and browser setup wait for running queries.
- Report NEED_LOGIN instead of UPSTREAM_BROKEN when not logged in: Xueqiu community (error 400016), Bilibili subtitles (no Bilibili login), LinkedIn (no LinkedIn login in the dedicated browser).
-- Smoother upgrade from 1.5: update.md checks the version first; `agent-reach update` moves a pip/pipx install to uv by itself; `setup` removes the old Agent Reach program (only Agent Reach itself) and the install report explains what was kept, what changed and which old channels can be added back. Install URLs always point at the latest release.
+- Smoother upgrade from 1.5: install and update share one guide, install.md, which checks the version first (update.md, where 1.5 sends users, points to it); `agent-reach update` moves a pip/pipx install to uv by itself; `setup` removes the old Agent Reach program (only Agent Reach itself) and the install report explains what was kept, what changed and which old channels can be added back. Install URLs always point at the latest release.
- Upstream errors reach the agent unchanged (the original message and help); the agent tells the user which platform is temporarily unavailable, by platform name. Reach no longer replaces them with its own advice (NEED_LOGIN still gives Reach's dedicated-browser login steps).
### ✨ New / 新增
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fb04d167..489ec60f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -75,7 +75,7 @@ Every version section in `CHANGELOG.md` starts with a short plain summary for us
## Releasing (maintainers)
-Users install and update from the latest GitHub release, and 1.5 users read `docs/update.md` on `main`, so the merge and the release must land together:
+Users install and update from the latest GitHub release, and 1.5 users are sent to `docs/update.md` on `main`, which points to `docs/install.md`, so the merge and the release must land together:
1. On the release branch, with the needed logins and keys in place, run `python scripts/record_release_acceptance.py` until it prints `release_ready: True` (`--only <channel>` rechecks some channels and keeps the rest). Commit `.github/release-acceptance.json`. Any later change under `agent_reach/` invalidates it; the record is valid for 7 days.
2. Set the version's date in `CHANGELOG.md`.
diff --git a/docs/install.md b/docs/install.md
index 3db3b6d3..ceda54e4 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,15 +1,16 @@
-# Install Agent Reach
+# Install or update Agent Reach
-For the AI doing the install. Run every command yourself. Each `agent-reach` command (1.6 and later) prints one JSON object; read `ok`, `result` and `error.hint`.
+For the AI doing the work. This one guide covers a fresh install, an update, and an upgrade from 1.5 or earlier. Run every command yourself. Each `agent-reach` command (1.6 and later) prints one JSON object; read `ok`, `result` and `error.hint`.
> ⚠️ The PyPI package named `agent-reach` is NOT this project. Never install it from PyPI; only use the GitHub URL below.
## 0. Before you start
- You must be able to run terminal commands. If you can't, tell the user: "Please turn on command execution for me in my settings, then ask again."
-- Already installed (`command -v agent-reach` prints a path)? Run `agent-reach version`:
- - it prints JSON → run `agent-reach update` and stop here.
- - it prints a plain line like `Agent Reach v1.5.0` → this is an old version; follow [update.md](update.md) instead.
+- Is it already installed? Run `agent-reach version`:
+ - it prints JSON (1.6 and later) → go to [Update](#update).
+ - it prints a plain line like `Agent Reach v1.5.0` → go to [Upgrade from 1.5 or earlier](#upgrade-from-15-or-earlier).
+ - `agent-reach` is not found → continue below.
- `uv` missing (`uv --version` fails)? Tell the user: "I'm installing uv, a small tool that installs command-line programs. It needs no admin password." Then run:
- macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
@@ -30,10 +31,31 @@ agent-reach setup
Show `result.installation_report.markdown` to the user as is. The program generates it; do not rewrite, reorder or add to it.
-## 3. Later
+## Update
+
+```bash
+agent-reach update
+```
+
+It upgrades the program, every added channel's tools and the skill. Tell the user each line of `result.user_actions`, and show `result.installation_report.markdown` as is when it is present. If it fails, `error.hint` holds the exact command to run.
+
+## Upgrade from 1.5 or earlier
+
+1.6 is installed with uv; 1.5 was installed with pipx or pip. Tell the user: "This is a big upgrade. Your keys and settings are kept; I'm moving Agent Reach to the new installer." Then:
+
+1. Install uv if it is missing (see step 0).
+2. Install 1.6:
+ ```bash
+ uv tool install --force https://github.com/Panniantong/Agent-Reach/releases/latest/download/agent-reach.zip
+ ```
+3. Open a new shell and check `agent-reach version` prints JSON. If it still prints the old line, run `uv tool update-shell`, open a new shell and check again.
+4. Run `agent-reach setup`. It keeps `~/.agent-reach/config.yaml`, removes the old Agent Reach program (only Agent Reach itself, never the user's other tools) and refreshes the skill for every AI.
+5. Show `result.installation_report.markdown` to the user as is. It explains what changed and which old channels they can add back.
+
+## Later
- The user just says what they want, e.g. "add Xiaohongshu" → `agent-reach add <channel>`; "remove V2EX" → `agent-reach remove <channel>`.
- Keys are entered by the user, e.g. a Groq key for Xiaoyuzhou transcription: `agent-reach configure groq-key`.
- Everything else (usage, login, browser) is covered by the installed skill.
-Problems: [troubleshooting.md](troubleshooting.md).
+Problems and rolling back: [troubleshooting.md](troubleshooting.md).
diff --git a/docs/update.md b/docs/update.md
index cbf74121..b9f5ba0a 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,53 +1,3 @@
# Update Agent Reach
-For the AI doing the update. Run every command yourself.
-
-## 1. Which version is installed?
-
-```bash
-agent-reach version
-```
-
-- Prints JSON (1.6 and later) → go to step 2.
-- Prints a plain line like `Agent Reach v1.5.0`, or `agent-reach update` says "invalid choice" → it is 1.5 or earlier; go to step 3.
-- `agent-reach` not found → follow [install.md](install.md).
-
-## 2. Update (1.6 and later)
-
-```bash
-agent-reach update
-```
-
-It upgrades the program, every added channel's tools and the skill, and removes old copies. Show the user each line of `result.user_actions`, and `result.installation_report.markdown` as is when it is present. Then `agent-reach check --text` confirms the channels still work.
-
-If it fails, `error.hint` holds the exact command to run.
-
-## 3. Upgrade from 1.5 or earlier
-
-1.6 is installed with uv, a small tool that installs command-line programs; 1.5 was installed with pipx or pip. Tell the user: "This is a big upgrade. Your keys and settings are kept; I'm moving Agent Reach to the new installer." Then:
-
-1. `uv --version` fails? Install uv (no admin password):
- - macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- - Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
-2. Install 1.6:
- ```bash
- uv tool install --force https://github.com/Panniantong/Agent-Reach/releases/latest/download/agent-reach.zip
- ```
-3. Open a new shell and check `agent-reach version` prints JSON. If it still prints the old line, run `uv tool update-shell`, open a new shell and check again.
-4. Set it up:
- ```bash
- agent-reach setup
- ```
- It keeps `~/.agent-reach/config.yaml`, removes the old Agent Reach program (only Agent Reach itself, never the user's other tools) and refreshes the skill for every AI.
-5. Show `result.installation_report.markdown` to the user as is. It explains what changed and which old channels they can add back.
-
-## Roll back
-
-A new version misbehaves? Go back to the previous one (replace `<previous>` with its number, e.g. `1.6.0`):
-
-```bash
-uv tool install --force https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v<previous>.zip
-agent-reach update --sync-only
-```
-
-Channels, keys and logins under `~/.agent-reach/` are kept.
+Installing and updating now use one guide. Follow [install.md](https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md) from step 0: it checks the installed version and updates, or upgrades from 1.5 and earlier, as needed.