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: rewrite skill and install guide

Pnant0cfbb9e0e810
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 5a07c8c3..c87b9ee2 100644
--- a/agent_reach/skill/SKILL.md
+++ b/agent_reach/skill/SKILL.md
@@ -1,14 +1,13 @@
---
name: agent-reach
description: >
- Use when the user names a supported platform, shares its URL, or asks to configure or diagnose its channel:
- 小红书/xiaohongshu, B站/bilibili, Twitter/X, Reddit, Facebook, Instagram,
- YouTube (subtitles, transcripts), 小宇宙/Xiaoyuzhou podcasts, V2EX, 雪球/股票行情, GitHub,
- LinkedIn/Boss直聘 jobs,
- or when your built-in web search / fetch is missing or fails.
- Supplement existing agent capabilities: prefer available public web tools for public content on any platform.
- Use Reach when evidence is insufficient, tools are unavailable, or a declared structured action is needed.
- Read-only: never post, comment, like, or log in on the user's behalf.
+ 只读读取各平台内容:搜索、读帖、看评论、取字幕、查行情和职位。
+ Use when 用户提到或贴出链接:小红书/xiaohongshu、B站/bilibili、Twitter/X、Reddit、
+ YouTube(字幕、转录)、GitHub、V2EX、雪球/股票行情、LinkedIn/Boss直聘 职位、
+ Instagram、Facebook、小宇宙播客;或说"帮我搜/看看/读一下这个链接"而自带网页搜索/读取不可用、失败或拿不到正文;
+ 或要安装、加上/去掉某个平台、登录/退出、看状态、更新、卸载 Agent Reach。
+ 不做:发帖、评论、点赞、私信等任何写操作;不替用户登录、不索要密码。
+ 公开内容优先用 Agent 自带工具,Reach 补缺口。
metadata:
homepage: https://github.com/Panniantong/Agent-Reach
version: "{{VERSION}}"
@@ -16,116 +15,90 @@ metadata:
# Agent Reach
-一个命令接所有平台:`agent-reach`。只读,默认输出 JSON;`setup --text` 直接显示安装能力表。
+一个命令读所有平台:`agent-reach`。只读,默认输出一行 JSON。
-## 安装完成展示精简能力表
+动手前先说一句"用 agent-reach skill(X 渠道)"。本 skill 被调用后全程有效,以下规则一直适用。
-安装或重新初始化后,最终回复直接展示 `result.installation_report.markdown`:按安装电脑本地时间生成的问候、默认安装结果、图标说明、一张“平台 / 不登录可以查什么 / 需要登录后再试”的三列表、一句实测状态。不要自行补另一句问候,也不要再补详细矩阵或后台动作清单;详细边界仅在用户追问时读取 [能力边界](references/capabilities.md)。
-
-运行 `agent-reach setup` 获取 JSON;用户操作终端可用 `agent-reach setup --text`。报告链接只作补充。保留安装失败、用户移除和需处理的状态。✅ 表示不用登录可先查的内容;❌ 只标明所列 Reach 功能需要登录后再试,登录不保证访问成功;— 表示这里没有额外的登录功能。Reddit 的公开帖子、正文和公开评论先用现有网页工具,不要求登录,也不承诺读全评论。
-
-问候由程序读取本地时钟:05–10 点早上、11–13 点中午、14–17 点下午、18–21 点晚上,其余为深夜;不联网定位、不询问时区。表中写清内容类型,如“搜摘要”“读正文”“读详情”,避免“页面提示登录时”“更多站内功能”“部分推文”等含糊说法。网络失败、尚未实测、未支持的功能不能标成 ❌ 要求用户登录。如果当前运行时没有 `installation_report`,核对所装版本和来源。
-
-表格功能项尽量用 2–3 字短语,如“读正文、看评论”“看热帖、看热股”。短语保留内容区别:摘要和链接不写成全文,热门股票不写成“牛股”;评论范围、字幕来源的共同说明只在表下写一次。
-
-## 怎么用
-
-按所需内容选择入口,所有平台适用:
-
-1. **公开信息**:有链接先用已有网页工具打开;找内容先用已有搜索工具,按需加 `site:平台域名`。正文、评论、字幕分别检查是否已满足请求。已有结果足够就直接回答,不准备渠道或登录。
-2. **补充能力**:公开结果缺少用户需要的部分、现有工具不可用,或用户要求 Reach 已声明的结构化/站内动作时,再查 `agent-reach channels`,调用对应动作。已有免登录原生工具或公开接口可直接复用;不要求每个任务先重复做一次网页搜索。网页工具不可用时,Reach `web search` / `web read` 提供匿名保底。
-3. **按需认证**:仅当尚未满足的任务所选路径确实要求登录时,再加载 [会话配置](references/sessions.md),先复用本机已有的该站登录和 Reach 保存的会话,失效或缺失时再请用户本人登录。没有配置浏览器说明需要配置;403、验证码、DNS/TLS 错误、限流、超时按各自原因处理。正文旁的登录按钮不算登录墙。
-4. **交付已有结果**:保留公开结果,说明缺少正文、哪些评论或字幕;登录仅服务于剩余缺口。用户跳过登录也能拿到已读取的内容。评论计数、字幕轨道清单、页面壳、搜索摘要分别标注,不当成评论正文、字幕正文或完整文章。
-
-平台名称和 URL 用来识别来源,不自动触发安装、`ensure` 或登录。用户要求安装、登录或退出时读会话配置;故障、升级或卸载时读 [维护说明](references/maintenance.md),查询时按需加载。
-
-CLI 也按此顺序执行:渠道**已经加上**(默认渠道或 `add` 过)时,搜索/阅读直接走这个渠道的站内工具,不先查网页。渠道**还没加**时,带 `public_web` 的搜索/阅读动作先复用 Reach 的免登录网页搜索/读取,成功后直接返回,不准备浏览器。`backend: public-web` 和 `meta.access.scope` 区分搜索结果与页面文字;不保证站内排序、最新状态、全文或全部评论。公开结果不足才尝试站内工具,实际返回 `NEED_LOGIN` 才请用户登录。用 `--backend public-web` 可只查公开网页;需要站内数据时指定该动作声明的 `--backend opencli` 或 `--backend boss-agent-cli`。评论、字幕、账号列表等动作保持原有粒度;Instagram 搜用户不以通用网页搜索冒充。
-
-Reddit 公开帖可搜索 `site:reddit.com 关键词` 再打开原帖,公开 JSON 有时包含评论父子 ID;以本次实际返回为准。YouTube/B站简介与字幕、视频内容分别验收;X 的单帖公开内容与评论流分别验收。某台机器的失败不能推广为平台必须登录,也不固化“某平台总能匿名读全”。网络路径不同的结果分别记录。
+## 选路
+- 公开内容先用你自带的搜索/读取工具(可加 `site:域名`)。正文、评论、字幕分别核对是否已拿到;够了就直接回答,不装渠道、不登录。
+- 自带工具不可用、结果缺了用户要的部分、或用户要的是渠道声明的站内动作时,再用 Reach。不确定有哪些动作和参数先跑 `agent-reach channels`。
+- 渠道已经加上(默认渠道或 `add` 过)时,搜索/阅读直接走该站工具;还没加的渠道,搜索/阅读先试免登录公开网页,结果里 `backend: public-web` 标明来源。`--backend public-web` 只查公开网页;`--backend <后端>` 指定站内工具。
+- 平台名或链接只用来认出来源,不自动触发安装或登录。
+- 摘要、页面壳、评论计数、字幕轨道列表不等于正文、评论或字幕本身,要分别说明。用户跳过登录时,已拿到的公开结果照样交付。
```bash
-agent-reach channels # 每个渠道有哪些动作、要什么参数(不确定就先跑这个)
-agent-reach ensure <渠道> # 安装、复用专用会话并实测
+agent-reach channels # 每个渠道的动作和参数
agent-reach <渠道> <动作> [参数] # 例:agent-reach xiaohongshu search "咖啡" --limit 5
-agent-reach read <链接> # 给链接,自动认出渠道
+agent-reach read <链接> # 按链接自动选渠道
```
-结果:
+## 结果与错误
-- `ok: true` → 内容在 `items` 里,每条有 `title / url / author / published_at / text`,原始数据在 `raw`。
-- `ok: false` → 看 `error.code`,按 `error.hint` 做:
+- `ok: true` → 内容在 `items`,每条有 `title / url / author / published_at / text`,原始数据在 `raw`。
+- `ok: false` → 看 `error.code`,照 `error.hint` 做:
| error.code | 怎么办 |
|---|---|
-| `UPSTREAM_BROKEN` | 告诉用户当前故障,可询问是否从原安装来源更新一次;不自动更新、不反复重试 |
-| `TIMEOUT` | 看失败阶段与渠道状态,不反复开窗或立即重试 |
-| `RATE_LIMITED` | 按 `retry_after_seconds` 等待,程序暂停该渠道 |
-| `NOT_FOUND` / `BAD_INPUT` | 检查链接或参数,必要时跑 `agent-reach channels` |
-
-## 规则
-
-1. 所有平台先判断现有公开能力是否满足任务;只为缺口调用 Reach。需要结构化/站内动作时可直接选已声明动作,认证按实际路径决定。
-2. 实际调用 Reach 渠道前说一句"用 agent-reach 的 X 渠道"。
-3. 多平台调研按会话分组;共用浏览器的命令串行,独立会话可以并行。
-4. 只做读取。发帖、评论、点赞一律不做。
-5. 优先复用本地已有的站点登录:已连接的浏览器只读导出当前网站 Cookie,原浏览器不变;不得输出凭据。缺失或失效时,才由用户本人登录。
-
-## 渠道
-
-{{CHANNEL_TABLE}}
+| `NEED_SETUP` | 缺依赖或密钥。按提示 `agent-reach add <渠道>`;要密钥时请用户本人提供,再 `agent-reach configure <key>` |
+| `NEED_LOGIN` | 保留已有结果,告诉用户需要登录;`agent-reach login <渠道>` 打开浏览器,由用户本人登录,你绝不代登、不要密码 |
+| `UPSTREAM_BROKEN` | 上游工具坏了。说明情况,用户同意后跑一次 `agent-reach update`;不循环重试 |
+| `TIMEOUT` | 看失败阶段和渠道状态(`agent-reach doctor --text`);不反复重试、不反复开窗 |
+| `RATE_LIMITED` | 平台限流,Reach 已暂停该渠道;按 `retry_after_seconds` 等,不换后端 |
+| `PLATFORM_BLOCKED` | 平台要求验证(验证码/风控)。停下,请用户在官方页面处理;不换账号、不换后端 |
+| `BUSY` | 排队等了 2 分钟浏览器仍然满,或用户正开着登录窗口。过一会儿、或等用户说登好了再试;不关窗口、不切换配置 |
+| `NOT_FOUND` | 内容不存在,核对链接或 ID |
+| `BAD_INPUT` | 参数不对,跑 `agent-reach channels` 看用法 |
-表中 `login` 是渠道认证入口,公开内容查询不以登录为前提;不同动作的要求以实际结果为准。`default` 表示默认安装,不保证所有网络环境均可达;调用可选渠道时由 `ensure` 准备。Reddit 的公开网页路径无需添加 Reddit 渠道。默认渠道也可以去掉,去掉后更新不会再加回来。
+遇到 `PLATFORM_BLOCKED`、`RATE_LIMITED`、`NEED_LOGIN`、`BUSY` 就停止本次尝试,不换账号、后端或浏览器反复请求。网络失败或某台机器的失败不能说成"平台必须登录"。
+## 登录与专用浏览器
+所有浏览器渠道共用一个专用浏览器(优先 CloakBrowser,装不上时用本机 Chrome),默认无头不弹窗,闲置 10 分钟自动关闭,下次调用自动重开。可以并行调用(包括子代理同时查):同一平台最多同时 2 条,所有平台合计 4 条,多出来的自动排队;同一平台的搜索之间自动间隔几秒。
-## 会话复用:先检查,再决定是否需要登录
+第一次用某个网站时,如果用户的 Chrome 已连接 OpenCLI 扩展,程序会把该站登录自动复制一次到专用浏览器,之后一直复用;只复制该站,不动原浏览器。登录失效或没有可复制的来源时,才请用户本人 `agent-reach login <渠道>`。刷新、选来源、退出等细节见 [会话与专用浏览器](references/sessions.md):用户要登录、退出、换账号,或遇到 `NEED_LOGIN` 时读它。
+## 平台注意
+- 小红书 read 只返回文字描述,不要声称看懂了图片或视频。
+- Boss 直聘搜索结果 `salary_encoded=true` 时绝不猜薪资数字;read 职位链接拿详情里的可读薪资。
+- 各平台公开能做什么、Reach 补什么,见 [能力边界](references/capabilities.md):用户问"能查什么/查得全吗"或要判断结果完整度时读它。
-`setup` 安装默认渠道;`add` 为浏览器渠道自动准备共用浏览器和插件。`login <渠道>` 打开该网站,由用户登录。先尝试复用本地浏览器已有的站点登录;程序定期保存,无需关窗。业务访问需要实际验证。
-
+## 渠道
-小红书 read 仅返回文字描述,不声称理解图片/视频。BOSS 搜索若 salary_encoded=true,不能猜数字;read 职位链接获取详情中的可读薪资。
+{{CHANNEL_TABLE}}
+`default` 是默认安装的渠道,也可以去掉,去掉后更新不会加回来。`login` 列是认证入口,不是查公开内容的前提。
-遇到 PLATFORM_BLOCKED、RATE_LIMITED、NEED_LOGIN、BUSY 就停止本次降级,不换账号或后端反复请求。同一 profile 的 Reach 命令互斥;多渠道共用同一 profile 时串行。
+## 安装完成时
-依赖修复和发布升级见 [维护说明](references/maintenance.md);普通查询不修改依赖。
+`agent-reach setup` 后,把 `result.installation_report.markdown` 原样展示给用户,不增删、不重排、不自己补问候或表格;报告由程序生成。
## 用户要管理 Agent Reach 时
| 用户说 | 你运行 |
|---|---|
-| 加上某个平台 | `agent-reach add <渠道>`,自动准备依赖;需要登录时再请用户本人完成 |
-| 看看状态 / 哪些能用 | `agent-reach doctor --text`(要实测再跑 `agent-reach check <渠道> --search --text`) |
-| 登录过期了 | 先读会话配置;`agent-reach login <渠道>` 打开共用专用浏览器,由用户本人登录 |
-| 去掉某个平台 / 退出登录 | `agent-reach remove <渠道>`;`agent-reach logout <渠道>` 清除专用浏览器中该网站的登录 |
-| 升级 / 更新 | 先读 [维护说明](references/maintenance.md),确认当前安装来源和版本,再执行更新。 |
+| 加上某个平台 | `agent-reach add <渠道>`,依赖自动装好;只告诉用户他必须做的事(登录或提供密钥) |
+| 去掉某个平台 | `agent-reach remove <渠道>` |
+| 登录 / 登录过期 | `agent-reach login <渠道>`,由用户本人在打开的窗口里登录 |
+| 退出登录 | `agent-reach logout <渠道>` |
+| 看看状态 / 哪些能用 | `agent-reach doctor --text`;要实测跑 `agent-reach check <渠道> --text` |
+| 升级 / 更新 | `agent-reach update` |
| 卸载 | 先 `agent-reach uninstall --dry-run` 给用户看,确认后 `agent-reach uninstall` |
| 让另一个 AI 也能用 | `agent-reach skill link <那个 AI 的 skill 目录>`;`agent-reach skill` 查看现在放在哪 |
-首次安装按上方“安装完成展示精简能力表”交付;普通查询按需读取 [能力边界](references/capabilities.md),不预先安装全部可选渠道。
+故障排查、浏览器维护和卸载细节见 [维护说明](references/maintenance.md):更新失败、浏览器起不来或要卸载时读它。
## 有新版本时
-任何结果里出现 `meta.update`,就说明有新版本。每次对话只提一次,用用户的语言、大白话:
-
-1. 告诉用户 Agent Reach 有新版本(`meta.update.latest`)。
-2. 从 `meta.update.notes` 里挑 1 到 3 个简短要点,说清楚这次改了什么。
-3. 问用户要不要更新。
-
-用户同意更新后,先读 [维护说明](references/maintenance.md),确认安装来源;从相同来源更新,避免将本地构建覆盖为其他版本。更新后说明实际改动和仍需用户完成的操作。
-
-
-## 共用专用浏览器
-
-普通查询默认 headless,不弹窗;`login CHANNEL` 才显窗,下一次查询收回窗口转回无头,始终沿用同一配置。所有浏览器渠道使用 `~/.agent-reach/browser/profile`,CloakBrowser 优先,下载失败回退本机 Chrome。OpenCLI 插件自动准备,网页提取由上游 OpenCLI 或原生 CLI 执行。BOSS 使用同一专用浏览器;不启动额外个人 Chrome。闲置 10 分钟自动关闭,下次调用自动重开。
-
-需要 Reach 时可直接运行 `agent-reach execute CHANNEL ACTION --params '{...}'`,公开路径成功就返回,剩余站内请求才准备依赖和会话。`ensure CHANNEL` 留给站内安装验收和排障;需要本人登录会返回明确提示。`execute` 返回 `operation_id` 时,在用户完成后运行 `agent-reach resume OPERATION_ID`,直接验证待完成的站内动作。本版没有 ask 或 Reach MCP 服务,无需模型 API Key。
+结果里出现 `meta.update` 就说明有新版本。每次对话只提一次,用用户的语言、大白话:
-优先按站点复用本地已有登录;默认使用已连接的浏览器,只读复制当前网站 Cookie。多个来源对应不同账号时,用 `browser profiles` / `browser use ID` 选择,不随机切换。来源不可用时保留 Reach 已保存的会话。定期保存会话;真实页面操作和 Reach 调用重置十分钟计时。OpenCLI Bridge 随浏览器启动和回收;已有用户进程保留,版本冲突交由用户处理。详细步骤见 [sessions.md](references/sessions.md)。
+1. 告诉用户有新版本(`meta.update.latest`)。
+2. 从 `meta.update.notes` 挑 1 到 3 个要点说清改了什么。
+3. 问要不要更新;用户同意后才跑 `agent-reach update`。
-`agent-reach add CHANNEL` 会准备渠道所需依赖、专用浏览器和插件;`remove CHANNEL` 清除该网站的登录和存储,保留其他网站。小宇宙保留为可选转录渠道,需要 Groq Key。
+## 红线
-安装、升级和清理只处理台账记录的 Reach 文件。普通查询不升级依赖、不启动更新检查、不写其他软件配置。渠道需完成真实查询验收才能发布;doctor 和单元测试不代替验收。
+- 只读。发帖、评论、点赞、私信一律不做。
+- 不替用户登录,不索要或输出密码、Cookie 等凭据。
+- 普通查询不改依赖、不自动更新。
diff --git a/agent_reach/skill/SKILL_en.md b/agent_reach/skill/SKILL_en.md
index ea2a9795..3d888124 100644
--- a/agent_reach/skill/SKILL_en.md
+++ b/agent_reach/skill/SKILL_en.md
@@ -1,15 +1,14 @@
---
name: agent-reach
description: >
- Use when the user names a supported platform, shares its URL, or asks to configure or diagnose its channel:
- Xiaohongshu, Bilibili, Twitter/X, Reddit, Facebook, Instagram, YouTube
- (subtitles, transcripts), V2EX, Xueqiu stock quotes,
- GitHub, LinkedIn / Boss Zhipin jobs,
- or when your built-in web search / fetch
- is missing or fails. Read-only: never post, comment, like, or log in on the
- user's behalf.
- Supplement existing agent capabilities: prefer available public web tools on every platform.
- Use Reach for missing evidence, unavailable tools or declared structured actions.
+ Read-only access to platform content: search, read posts, view comments, fetch subtitles, stock quotes and jobs.
+ Use when the user mentions or pastes a link from Xiaohongshu, Bilibili, Twitter/X, Reddit,
+ YouTube (subtitles, transcripts), GitHub, V2EX, Xueqiu/stock quotes, LinkedIn/Boss Zhipin jobs,
+ Instagram, Facebook or Xiaoyuzhou podcasts; or says "search / look up / read this link" and your built-in
+ web search or fetch is unavailable, fails, or misses the body;
+ or wants to install, add/remove a platform, log in/out, check status, update or uninstall Agent Reach.
+ Does not: post, comment, like, message or any other write; never logs in for the user or asks for passwords.
+ Prefer your own tools for public content; Reach fills the gaps.
metadata:
homepage: https://github.com/Panniantong/Agent-Reach
version: "{{VERSION}}"
@@ -17,112 +16,90 @@ metadata:
# Agent Reach
-One command for every platform: `agent-reach`. Read-only; JSON by default, or a human-readable installation report with `setup --text`.
+One command for every platform: `agent-reach`. Read-only; prints one JSON object by default.
-## Compact installation handoff
+Before acting, say "using the agent-reach skill (channel X)". Once invoked, these rules apply for the whole session.
-Present `result.installation_report.markdown` directly: a greeting generated from the installing computer's local clock, the install outcome, an icon legend, one three-column table (platform / content without login / features to try after login), and one verification line. Do not add another greeting, detailed matrices or internal action lists. Load [Capability scope](references/capabilities.md) only when the user asks for detail.
-
-Use JSON `agent-reach setup`, or `setup --text` for direct terminal output. A report link is supplementary. Preserve failed installs, user removals and states requiring attention. ✅ marks content to try without login; ❌ marks the listed authenticated Reach features, with no promise that login guarantees access; — means no additional login feature here. Public Reddit search, post bodies and available comments use existing web tools without login; do not promise complete comment trees.
-
-Local greeting hours: morning 05–10, noon 11–13, afternoon 14–17, evening 18–21, late night otherwise. No geolocation or timezone question is needed. Name concrete content and actions; avoid vague phrases such as "when the page asks," "more site features" or "some tweets." Network failures, untested paths and unsupported actions must not become ❌ login requirements. If `installation_report` is missing, check the build/source.
-
-Keep feature labels short: "read posts, view replies" or "view posts, trending stocks." Preserve distinctions between snippets, links and full text; trending stocks are not investment picks. State shared comment coverage and subtitle availability once below the table.
-
-## Usage
-
-Route by the evidence needed, on every platform:
-
-1. For public information, open supplied links with existing web tools or search with an optional site filter. Check body text, comments and subtitles separately. Answer when sufficient; no channel setup or login is needed.
-2. Use a declared Reach action when evidence is missing, existing tools are unavailable, or a structured/site-specific operation is requested. Inspect `agent-reach channels` when needed. Reuse available anonymous native tools or public APIs directly; do not force a redundant web search before a suitable action. Reach `web search` / `web read` provide an anonymous fallback.
-3. Load [Sessions](references/sessions.md) only when the remaining task's chosen path actually requires authentication or session setup. Reuse authorized sessions before requesting login. Missing browser setup, 403, challenges, DNS/TLS failures, rate limits and timeouts need their own diagnosis. A login button beside readable content is not a login wall.
-4. Keep public evidence and deliver it even if login is skipped. Identify the remaining gap. Counts, subtitle track lists, page shells and search snippets do not establish comment text, subtitle text or complete bodies.
-
-A platform name or URL identifies a source; it does not automatically trigger installation, ensure or login. Read Sessions for explicit setup/login/logout requests and [Maintenance](references/maintenance.md) for failures/updates/uninstall.
-
-When a channel is **already added** (a default channel, or one the user added), its search/read actions go straight to that channel's site tools, with no web search first. For channels **not added yet**, CLI search/read actions with `public_web` try anonymous web access before preparing site tools. Results identify `backend: public-web` and `meta.access.scope` as search results or page text; site ordering, freshness and completeness remain unverified. Use `--backend public-web` for public access only, or an action's declared `--backend opencli` / `--backend boss-agent-cli` for a site-specific request. Only an actual login requirement warrants asking the user to log in. Comments, subtitles and account-list actions keep their declared scope.
-
-Public Reddit JSON may expose parent IDs; verify actual coverage. YouTube/Bilibili descriptions, subtitles and video content are separate evidence. Public X posts and reply streams are separate capabilities. Do not generalize a local failure into a platform-wide login requirement, or promise universal anonymous access. Distinguish local HTTP, proxy and built-in web-tool results.
+## Choosing a route
+- For public content, use your own search/read tools first (optionally `site:domain`). Check body text, comments and subtitles separately; when they are enough, answer directly without adding channels or logging in.
+- Use Reach when your tools are unavailable, the result lacks what the user needs, or the user wants a site action a channel declares. Unsure of actions and params? Run `agent-reach channels`.
+- An added channel (a default one, or one added with `add`) sends search/read straight to its site tool. For channels not added yet, search/read first try anonymous public web access; results mark it with `backend: public-web`. `--backend public-web` limits to public web; `--backend <backend>` picks a site tool.
+- A platform name or link only identifies the source; it never triggers install or login by itself.
+- Snippets, page shells, comment counts and subtitle track lists are not body text, comments or subtitles; say which you have. If the user skips login, still deliver the public results already gathered.
```bash
-agent-reach channels # actions and params per channel (run this when unsure)
-agent-reach ensure <channel> # setup, authorized reuse, live check
+agent-reach channels # actions and params per channel
agent-reach <channel> <action> [args] # e.g. agent-reach bilibili search "rust async" --limit 5
agent-reach read <url> # picks the channel from the URL
```
-Results:
+## Results and errors
- `ok: true` → content in `items`; each has `title / url / author / published_at / text`, upstream data in `raw`.
- `ok: false` → branch on `error.code` and follow `error.hint`:
| error.code | What to do |
|---|---|
-| `NEED_LOGIN` | Keep public results. If the remaining task needs this path, the user logs in; resume using `operation_id` |
-| `UPSTREAM_BROKEN` | Report the failure; offer one update from the same source after user approval. Never update automatically or retry in a loop |
-| `TIMEOUT` | Inspect the failed stage and channel status; do not reopen or retry in a loop |
-| `RATE_LIMITED` | Respect `retry_after_seconds`; the runtime pauses this channel |
-| `NOT_FOUND` / `BAD_INPUT` | Check the link or args; run `agent-reach channels` if needed |
+| `NEED_SETUP` | Missing dependency or key. Run `agent-reach add <channel>` as hinted; for a key, the user provides it, then `agent-reach configure <key>` |
+| `NEED_LOGIN` | Keep existing results and tell the user login is needed; `agent-reach login <channel>` opens the browser and the user logs in themselves. Never log in for them or ask for a password |
+| `UPSTREAM_BROKEN` | The upstream tool failed. Explain, and after the user agrees run `agent-reach update` once; never retry in a loop |
+| `TIMEOUT` | Check the failed stage and channel status (`agent-reach doctor --text`); do not retry or reopen windows in a loop |
+| `RATE_LIMITED` | The platform rate-limited; Reach paused the channel. Wait `retry_after_seconds`; do not switch backends |
+| `PLATFORM_BLOCKED` | The platform wants verification (captcha/risk check). Stop; the user resolves it on the official page. Do not switch accounts or backends |
+| `BUSY` | The browser stayed full for the 2-minute wait in line, or the user has a login window open. Retry later, or after the user says they are logged in; do not close the window or switch profiles |
+| `NOT_FOUND` | Content does not exist; check the link or ID |
+| `BAD_INPUT` | Wrong arguments; run `agent-reach channels` for usage |
-## Rules
+On `PLATFORM_BLOCKED`, `RATE_LIMITED`, `NEED_LOGIN` or `BUSY`, stop this attempt; do not retry with other accounts, backends or browsers. A network failure or a failure on one machine does not mean "the platform requires login".
-1. On every platform, check whether existing public capabilities satisfy the request; use Reach for the missing capability. Declared structured/site-specific actions may be selected directly; authentication depends on the actual path.
-2. Say "using agent-reach channel X" before calling a Reach channel.
-3. Serialize commands sharing one browser profile; independent sessions may run in parallel.
-4. Read only. Never post, comment, or like.
-5. Reuse existing local site sessions first through read-only, site-scoped Browser Bridge export. Keep source browsers unchanged and never print credentials. Human login is the fallback.
+## Login and the dedicated browser
-## Channels
+All browser channels share one dedicated browser (CloakBrowser preferred, falling back to installed Chrome). It runs headless by default, closes after 10 idle minutes and reopens on the next call. Calls may run in parallel, including from subagents: up to 2 per platform and 4 in total run at once, the rest wait in line, and same-platform searches are spaced a few seconds apart.
-{{CHANNEL_TABLE}}
+The first time a site is used, if the user's Chrome is connected to the OpenCLI extension, that site's login is copied once into the dedicated browser and reused afterwards; only that site is copied and the source browser is untouched. Only when the login has expired or there is no source to copy from does the user run `agent-reach login <channel>` and log in themselves. Refreshing, choosing a source and logging out are in [Sessions](references/sessions.md): read it when the user wants to log in, log out or switch accounts, or on `NEED_LOGIN`.
-The login column lists authentication entry points, not prerequisites for public access. Requirements depend on the selected action. `default` means installed by default, not guaranteed network reachability; `ensure` prepares optional channels when needed. Reddit's public web path needs no Reddit channel setup. Default channels can be removed too; updates never add a removed one back.
+## Platform notes
+- Xiaohongshu read returns text descriptions only; never claim to understand the images or video.
+- When a Boss Zhipin search result has `salary_encoded=true`, never guess the salary digits; read the job link for the readable salary in the detail.
+- What each platform offers publicly and what Reach adds is in [Capability scope](references/capabilities.md): read it when the user asks "what can it get / is it complete" or you need to judge completeness.
+## Channels
-## Reuse before login
-
-
-`setup` installs defaults; adding a browser channel prepares the shared browser and extension. `login CHANNEL` opens the site for the user to log in. Reuse saved dedicated sessions and verify the requested action. Read only the requested site’s local session.
-
+{{CHANNEL_TABLE}}
-XHS read returns text descriptions, not image/video understanding. Never guess BOSS salary digits when salary_encoded=true; read the job detail instead.
+`default` channels are installed by default and can be removed; updates never add a removed one back. The `login` column is the authentication entry point, not a prerequisite for public content.
+## After installation
-Stop on PLATFORM_BLOCKED/RATE_LIMITED/NEED_LOGIN/BUSY. Serialize commands sharing a profile. Use `check CHANNEL --search` for live verification. See [Maintenance](references/maintenance.md) for dependency repair and distribution. Never modify dependencies during queries.
+After `agent-reach setup`, show `result.installation_report.markdown` to the user as is: no additions, removals, reordering, extra greeting or tables. The program generates it.
## When the user wants to manage Agent Reach
-| User asks | You run |
+| User says | You run |
|---|---|
-| Status / what works | `agent-reach doctor --text` (for a live test, `agent-reach check <channel> --search --text`) |
-| Add a platform ("add Xiaohongshu") | `agent-reach add <channel>`; one command installs everything it needs. Tell the user only what they must do: follow the login instructions (`agent-reach login <channel>`), or provide a key |
-| Login expired | Read Sessions first; `agent-reach login <channel>` opens the shared browser for the user to log in |
-| Remove a platform / log out | `agent-reach remove <channel>`; read Sessions before logout. `agent-reach logout <channel>` clears only that site in the shared browser |
-| Upgrade / update | Read [Maintenance](references/maintenance.md), check the installation source, then update from the same source |
+| Add a platform | `agent-reach add <channel>`; dependencies install automatically. Tell the user only what they must do (log in or provide a key) |
+| Remove a platform | `agent-reach remove <channel>` |
+| Log in / login expired | `agent-reach login <channel>`; the user logs in themselves in the window that opens |
+| Log out | `agent-reach logout <channel>` |
+| Status / what works | `agent-reach doctor --text`; for a live test `agent-reach check <channel> --text` |
+| Upgrade / update | `agent-reach update` |
| Uninstall | show `agent-reach uninstall --dry-run` first, then `agent-reach uninstall` once they confirm |
| Another AI should use it | `agent-reach skill link <that AI's skills folder>`; `agent-reach skill` shows where it is placed now |
-Follow the required installation handoff above. Ordinary queries load [Capability scope](references/capabilities.md) only when needed and do not install every optional channel.
+Troubleshooting, browser maintenance and uninstall details are in [Maintenance](references/maintenance.md): read it when an update fails, the browser will not start, or the user wants to uninstall.
## When there is a new version
Any result with `meta.update` means a newer version exists. Mention it once per conversation, in the user's language and plain words:
1. Agent Reach has a new version (`meta.update.latest`).
-2. What changed: 1 to 3 short points taken from `meta.update.notes`.
-3. Ask whether to update.
-
-After the user agrees, read [Maintenance](references/maintenance.md) and confirm the installation source. Update from the same source, then report the actual changes and remaining user actions.
-
-
-## Shared dedicated browser
-
-Queries default to headless. Explicit login opens a window; the next query switches back using the same profile. All browser channels use `~/.agent-reach/browser/profile`. CloakBrowser is preferred; installation/download failure falls back to installed Chrome. OpenCLI prepares the extension and performs website extraction. BOSS uses the same dedicated browser. The idle watcher closes it after ten minutes; the next action reopens it.
-
-Use `agent-reach execute CHANNEL ACTION --params '{...}'` to try the declared public route first and prepare site tools only when needed. Reserve `ensure CHANNEL` for setup checks and diagnosis. After the user completes a requested login, use `agent-reach resume OPERATION_ID` when an operation ID was returned. There is no Reach MCP server or model planner in this version, and no model API key is required.
+2. What changed: 1 to 3 short points from `meta.update.notes`.
+3. Ask whether to update; run `agent-reach update` only after the user agrees.
-Reuse the requested site’s existing local login first. Use a connected local Browser Bridge source or saved Reach state; preserve the source. Choose explicitly when multiple source accounts are available. The user logs in in the Reach window; sessions are saved periodically. Human page input and Reach calls reset the idle timer. The official Bridge is supervised alongside the browser; existing user processes are preserved. See [Sessions](references/sessions.md).
+## Red lines
-`add CHANNEL` prepares dependencies, browser and extension. `remove CHANNEL` clears only that site's login/storage, preserving other sites. Xiaoyuzhou remains an optional transcription channel requiring a Groq key.
+- Read only. Never post, comment, like or message.
+- Never log in for the user; never ask for or print passwords, cookies or other credentials.
+- Ordinary queries never change dependencies or update automatically.
diff --git a/agent_reach/skill/references/capabilities.md b/agent_reach/skill/references/capabilities.md
index 5e8d5659..024b78ea 100644
--- a/agent_reach/skill/references/capabilities.md
+++ b/agent_reach/skill/references/capabilities.md
@@ -1,7 +1,7 @@
# 能力边界 / Capability scope
-查询时仅在需要核对粒度时加载。安装摘要同时给出声明能力和本机状态;下表用于解释结果,不代表所有网络、账号和内容均已实测。
-Use only when evidence depth needs clarification. Declared actions and local acceptance are separate.
+用户问"能查什么、查得全吗",或要判断结果完整度时读这份。下表是声明能力,不代表所有网络、账号和内容都已实测。
+Read when the user asks what can be fetched or how complete a result is. Declared capabilities, not guaranteed results.
## 三层说明
@@ -9,7 +9,7 @@ Use only when evidence depth needs clarification. Declared actions and local acc
- **Reach 补充**:当前发布版声明的动作,见 `agent-reach channels`。需要配置时先复用专用浏览器已保存的会话,所选路径实际要求登录时才本人登录。
- **本机已验证**:只列本机最近成功验收的具体动作;安装、保存会话和网络可达均不等于业务验收。
-## 本版渠道(包含小宇宙)
+## 本版渠道
| 渠道 | 公开路径可尝试 | Reach 补充与边界 |
|---|---|---|
@@ -21,16 +21,11 @@ Use only when evidence depth needs clarification. Declared actions and local acc
| 小红书 | 公开列表或索引可能有笔记 ID、作者、标题,空字段不能补猜 | search/read/comments;文字描述、顶级评论及已加载回复;不保证全部评论,不声称理解图片/视频 |
| Instagram | 部分索引和主页浅层信息;HTML 应用壳不算帖文 | search 搜用户、profile 主页、posts 指定用户帖子描述;无统一评论动作,不声称理解图片/视频 |
| Facebook | 部分索引或 HTML 摘要;摘要可能被截断 | search/profile;无统一详情或评论动作,不把搜索摘要当全文 |
-| LinkedIn | 搜公开职位、读公开 JD;已有免登录成功样本 | jobs/read 先尝试公开网页;指定 opencli 才直接走站内;不保证所有职位可读 |
+| LinkedIn | 搜公开职位、读公开 JD | jobs/read 先尝试公开网页;指定 opencli 才直接走站内;不保证所有职位可读 |
| BOSS | 搜索索引中可能有职位摘要 | search/read 职位列表与 JD;不能根据编码薪资猜数字;详情后备能力依渠道声明 |
| V2EX | 主题、正文及公开回复 | hot/node/read/user;返回范围以本次响应为准,不保证隐藏或缺失回复 |
| 雪球 | 部分公开行情和索引信息 | quote/search/hot_posts/hot_stocks;行情与社区路径分别验收 |
| Web | Agent 自带搜索/读取 | Reach web search/read 为匿名保底;摘要、页面壳和验证页不能当完整正文 |
-
-## 今日验证如何使用
-
-2026-10-19 的本机测试显示:内置网页工具与本机 HTTP/代理可能返回不同内容。Reddit 的内置读取拿到评论父子 ID;X 的公开嵌入拿到单帖全文;独立 yt-dlp 拿到 5 条评论及英文字幕正文;B 站公开接口拿到部分评论父子 ID。Claude 的另组样本出现不同的 HTML 壳、验证页和空字幕响应。这些差异要求按路径、样本和结果验收,不能固化成平台必须登录或匿名总能成功的规则。
-
-上述原生工具结果不自动成为 Reach 的正式动作;尤其 YouTube/B站的公开评论能力尚无 Reach 统一 comments 动作。新增渠道本版暂不发布。
+| 小宇宙 | 节目页标题、简介 | transcribe 整集转文字;需要用户提供 Groq Key(`agent-reach configure groq-key`) |
登录后的能力表述使用“可启用/尝试上述浏览器动作”,不使用“登录后支持全部评论”。用户跳过登录时交付已有公开证据。
diff --git a/agent_reach/skill/references/maintenance.md b/agent_reach/skill/references/maintenance.md
index c993f326..19958f21 100644
--- a/agent_reach/skill/references/maintenance.md
+++ b/agent_reach/skill/references/maintenance.md
@@ -1,9 +1,12 @@
# 维护
-- 已安装时使用 `agent-reach update`,更新后查看实际结果与安装能力表。
-- `agent-reach doctor --text` 读取本地状态;`check CHANNEL --search --text` 做一次联网验收。
-- `agent-reach browser status` 查看共用浏览器;`browser setup` 准备内核和扩展;`browser stop` 关闭程序管理的浏览器。
-- CloakBrowser 下载失败会保留缓存并尝试本机 Chrome。区分依赖下载、浏览器连接、登录、网页加载和平台限流;不要把网络超时说成登录失效。
-- 不修改 OpenCLI 安装文件。遇到上游缺陷记录错误和版本,再升级上游或反馈。
-- PLATFORM_BLOCKED、RATE_LIMITED、NEED_LOGIN、BUSY 停止本次尝试。需要用户处理后再继续;不反复开窗。
-- 卸载先查看 `agent-reach uninstall --dry-run`,确认范围后执行 uninstall;保留用户不属于 Reach 的文件与浏览器。
+更新失败、浏览器起不来、渠道报错或用户要卸载时读这份。
+
+- 更新:`agent-reach update` 升级 Agent Reach、已加渠道的工具和 skill;`agent-reach update --check` 只查有没有新版本。只在用户同意后执行。
+- 状态:`agent-reach doctor --text` 读本地状态,不联网;`agent-reach check <渠道> --text` 联网实测一次(`--search` 只测搜索/职位)。安装成功不等于实测通过。
+- 浏览器:`agent-reach browser status` 看状态,`browser setup` 准备内核和扩展,`browser stop` 关闭;CloakBrowser 下载失败后修好网络可 `browser setup --retry-cloak`。
+- 分清失败环节:依赖下载、浏览器连接、登录、网页加载、平台限流各是各的;网络超时不要说成登录失效。
+- 上游工具出错:记下错误和版本,用户同意后 `agent-reach update` 一次;不改上游工具的安装文件,不循环重试。
+- `PLATFORM_BLOCKED`、`RATE_LIMITED`、`NEED_LOGIN`、`BUSY` 停止本次尝试,等用户处理后再继续,不反复开窗。
+- 密钥和代理:`agent-reach configure groq-key | openai-key | proxy | github-token`,值由用户本人提供。
+- 卸载:先 `agent-reach uninstall --dry-run` 给用户看范围,确认后 `agent-reach uninstall`。只删 Reach 自己装的东西,用户的其他文件和浏览器保留。
diff --git a/agent_reach/skill/references/sessions.md b/agent_reach/skill/references/sessions.md
index 3e3a850e..a0dafa0c 100644
--- a/agent_reach/skill/references/sessions.md
+++ b/agent_reach/skill/references/sessions.md
@@ -1,34 +1,41 @@
# 会话与专用浏览器
-所有浏览器渠道共用 `~/.agent-reach/browser/profile`。CloakBrowser 优先,安装或下载失败时使用已安装的 Chrome。Node、OpenCLI、内核和扩展由 `agent-reach add CHANNEL` 自动准备;CloakBrowser 的扩展自动加载,Windows Chrome 回退路径可能需要点击一次“添加至 Chrome”。
+用户要登录、退出、换账号,或结果返回 `NEED_LOGIN` 时读这份。
-专用浏览器由 watcher 管理,闲置 10 分钟自动关闭;查询自动准备和重开。此配置与日常 Chrome 分开,程序不关闭用户的日常浏览器。
+## 专用浏览器
-## 使用与登录
+- 所有浏览器渠道共用一个专用浏览器配置,和用户日常的 Chrome 分开;程序不关闭、不修改用户的日常浏览器。
+- 内核优先 CloakBrowser;下载或安装失败时用本机已装的 Chrome,并记住这个回退,不每次重下。网络修好后可 `agent-reach browser setup --retry-cloak` 重试。
+- `agent-reach add <渠道>` 自动准备 Node、OpenCLI、内核和扩展。工具按本版测试过的版本安装。Windows 上用 Chrome 回退时,可能需要用户点一次"添加至 Chrome"。
+- 默认无头,不弹窗。只有 `agent-reach login <渠道>` 会显示窗口;窗口开着时查询直接用这个窗口,不会收掉它,用户登录期间等用户说登好了再查。窗口关闭后,之后的查询回到无头。
+- 闲置 10 分钟自动关闭,下次调用自动重开;真实页面操作和 Reach 调用会重置计时。登录期间定期保存,用户不用关窗。
+- 可以并行:同一平台最多同时 2 条,所有平台合计 4 条,多出来的排队,最多等 2 分钟,等不到才返回 `BUSY`。同一平台的搜索之间自动间隔几秒。打开登录窗口、退出登录、重装浏览器会等正在跑的查询结束再做。
+- `agent-reach browser status` 查看状态,`browser setup` 准备内核和扩展,`browser stop` 关闭程序管理的浏览器。
-1. 公开内容先用 Agent 已有搜索和读取,结果足够就回答。
-2. `agent-reach execute CHANNEL ACTION --params '{...}'` 对已声明的公开路径先搜索/读取,成功就返回;不足时才准备站内依赖与会话。`--backend public-web` 限定公开查询;指定 `--backend opencli` 等声明后端可直接使用站内能力。不要为每个请求先跑一次 ensure 的测试查询。
-3. 只有实际返回 NEED_LOGIN 才请用户登录;`agent-reach login CHANNEL` 打开专用浏览器,登录由用户本人完成。BOSS 等原生工具按返回提示执行 `login CHANNEL --sync`。
-4. 若返回 operation_id,用户完成后使用 `agent-reach resume OPERATION_ID`。保存的是任务参数,不会为等待登录另起常驻任务服务。
+## 自动复用已有登录
-## 默认无头,优先复用已有登录
+1. 第一次用某个网站时,如果用户的 Chrome 已连接 OpenCLI 扩展,程序把该站的登录(只限该站 Cookie)复制一次到专用浏览器。不复制整个浏览器目录、其他网站或密码库,也不改动来源浏览器。
+2. 复制成功后一直复用保存的会话,不按时间重新复制。Cookie 在不代表登录有效,以真实动作结果为准。
+3. 用户 Chrome 没连扩展时,不能承诺自动复用,也不能据此认定用户没登录;此时用 Reach 已保存的会话。
+4. 本机有多个浏览器都登录了该站时:`agent-reach browser profiles` 列出来源,`agent-reach browser use <ID>` 选定一个,不随机切换。
+5. `agent-reach login <渠道> --import-existing` 主动重新复制一次该站登录,不打开窗口。
+6. 用户本人在专用窗口里登录过,或执行过 `logout` / `remove`,就不再自动复制,避免已退出的登录复活。
-查询默认 headless,不弹窗口。`login CHANNEL` 专门给本人登录,会显示窗口;下一次查询先保存,再用同一配置转回无头。先恢复保存的会话,再打开目标页。
+## 需要本人登录时
-第一次调用网站时,优先从已连接的本地浏览器只读复制该站 Cookie;不会复制整个 Chrome 目录、其他网站登录、访问密码库或修改来源。没有可用来源时继续用 Reach 保存的会话,包括旧版分站快照。Cookie 存在不代表登录有效,必须看真实动作结果。
+- 只有实际返回 `NEED_LOGIN`、且剩下的任务确实需要这条路径时,才请用户登录。正文旁边有个登录按钮不算要求登录。
+- `agent-reach login <渠道>` 打开专用浏览器到该站登录页,用户本人完成登录。你不代登、不要密码、不输出 Cookie。
+- 返回结果里的 `next` 写了后续步骤就照做;部分原生工具渠道(如雪球)登录后要再跑 `agent-reach login <渠道> --sync`。
+- 用户完成后,重新执行原来的动作验证。
-原 Chrome 需已连接官方 OpenCLI 扩展;未连接时不能承诺自动复用,也不据此认定账号未登录。只有实际需要本人登录时才打开专用窗口。Cloak 内核不依赖该来源才能启动;已有专用会话仍可独立复用。
+## 平台差异
-多个本地浏览器都可能有该站账号时:`browser profiles` 查看连接,`browser use ID` 选择来源。`login CHANNEL --import-existing` 可主动刷新该站登录,不打开登录窗口。首次复制成功后持续复用保存的会话,不按时间重新导入;退出和删除渠道后停止自动导入,避免登录复活。
-
-复用以该站 Cookie 快照为准,清除专用浏览器中来源没有的旧 Cookie,保留其他网站。导入失败会尝试恢复原站点 Cookie,并保留已保存的会话。切换来源不会撤销已退出的渠道,也不覆盖本人明确选择的专用登录。
-
-BOSS 站内搜索优先走 OpenCLI,共用该配置。JD 的 OpenCLI 提取在部分职位上存在上游误报登录问题,不据此要求用户反复登录。原生 Boss CLI 仍可显式选择;其 JD 读取需要同一原生 CLI 搜索产生的短期引用,引用只保存在本地,不返回给模型。公开网页结果另行标注。B站只在读字幕时尝试把已有站点登录交给官方 B站 CLI,普通搜索不准备浏览器;没装 OpenCLI 时,仍可沿用保存的 B站 CLI 登录。雪球社区动作会自动同步已有登录,无需额外执行同步命令。
-
-登录期间定期保存,无需关窗才能保存。真实页面操作和 Reach 调用重置十分钟计时。OpenCLI Bridge 随专用浏览器由计时程序管理;Reach 启动的桥随浏览器退出,用户已有桥保留。
-
-CloakBrowser 下载失败后会记住 Chrome 回退,避免每次查询重新下载。修好网络后可用 `agent-reach browser setup --retry-cloak` 重试。
+- Boss 直聘站内搜索走 OpenCLI,共用专用浏览器。职位详情若因上游误报要求登录,不要让用户反复登录。
+- B 站只在读字幕时把已有登录交给 B 站官方命令行工具;普通搜索不准备浏览器。
+- 雪球社区动作需要登录;会话几小时内过期,过期后重复登录步骤。
## 退出和删除
-`agent-reach logout CHANNEL` 清除专用浏览器中该站登录和渠道自有状态。`remove CHANNEL` 还清理该渠道授权与待完成任务,保留其他网站登录。清理失败保留渠道记录,用户可重试清理。限流或验证码时停止,不换账号或浏览器反复尝试。
+- `agent-reach logout <渠道>`:清除专用浏览器里该站的登录和渠道自己的状态,其他网站保留。
+- `agent-reach remove <渠道>`:去掉渠道,同时清该站登录和存储,其他网站保留。清理失败时渠道记录保留并返回错误,用户可重试。
+- 两者之后都不再自动复制该站登录。
diff --git a/docs/install.md b/docs/install.md
index 72127314..f57006fc 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,6 +1,6 @@
# Install Agent Reach
-For the AI doing the install. Run every command yourself. Each `agent-reach` command prints one JSON object (with `--text`: plain text for people); read `ok`, `result` and `error.hint`.
+For the AI doing the install. Run every command yourself. Each `agent-reach` command 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.
@@ -15,52 +15,23 @@ For the AI doing the install. Run every command yourself. Each `agent-reach` com
## 1. Install and set up
-**This branch is an unpublished 1.6.0 candidate.** The latest verified official release is v1.5.0 and does not include the candidate's browser/setup changes.
-
-For the official stable version:
-
-```bash
-uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v1.5.0.zip
-```
-
-Continue with the [v1.5.0 installation instructions](https://github.com/Panniantong/Agent-Reach/blob/v1.5.0/docs/install.md). Stop here for a stable install; do not run this candidate's commands against 1.5.0.
-
-For this candidate's local test package, use the supplied wheel:
-
```bash
-uv tool install --force /path/to/agent_reach-1.6.0-py3-none-any.whl
+uv tool install https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v1.6.0.zip
agent-reach setup
-agent-reach doctor --text
```
-Do not run the stable install command over a candidate. Once v1.6.0 has actually been released, the official URL can advance to that tag. Already-installed ordinary users run `agent-reach update` explicitly; local candidate users keep the candidate source until it is released.
-
-`agent-reach setup --text` prints the same compact capability table directly. Plain `setup` preserves the JSON contract and saves `installation-report.md` under the private Reach directory.
-
`agent-reach` not found after install? Run `uv tool update-shell` and open a new shell.
-`setup` turns on the default channels (web, YouTube, GitHub, V2EX, Bilibili) and installs the Skill. It does not register an MCP server or require a model key.
-
-`doctor --text` reads local status without opening browsers or querying every platform. Installation is separate from acceptance. When the user needs a specific channel, use one bounded `check CHANNEL --search --text` or the requested formal action. Diagnose actual errors; a failure does not establish a platform-wide login requirement.
+`setup` turns on the default channels and installs the agent skill.
## 2. Report to the user
-Present the generated compact report directly in the final response:
-
-1. **Installation outcome**: the generated receipt includes the version and default dependency results. Do not repeat them or append the full agent-link list unless asked. An `ok: true` dependency install is not a live business check.
-2. **Capabilities**: present `result.installation_report.markdown` unchanged: a local-time greeting, install outcome, icon legend, three-column table (platform / without login / try after login), and live-verification line. Keep failures and user removals visible. Do not append detailed matrices or internal action lists. ✅ describes public content, ❌ the listed authenticated Reach features, and — no additional login feature here. Sign-in is no guarantee of access; network failures and untested actions are not login requirements. The report link is supplementary.
-3. **Optional capabilities**: add only for a missing capability or explicit setup request. `login_if_required` and `logins[].when=only_if_required` are conditional, not a to-do list. Existing public content remains available if login is skipped.
-4. **Example, Reddit**: public search, bodies and some comments can be attempted with existing web tools. Reach browser actions add search, post reading and subreddit lists; reuse an authorized session and log in only when the selected path requires it. Full comment trees, all replies and writing comments are outside the guarantee.
-5. **Later management**: the user can say 'add Xiaohongshu' or 'remove V2EX'. Default channels can be removed too.
-
-Before selecting Reach for a platform mention, check whether existing public tools already satisfy the task. For a structured/site-specific action, use its declared Reach route directly; no redundant search is required.
-
-When the user asks for a channel, run `agent-reach add <channel>`. Browser channels install Node, OpenCLI, the dedicated browser and its extension automatically. One profile under `~/.agent-reach/browser/profile` is shared by all sites. CloakBrowser is preferred; download failure falls back to installed Chrome. The owned browser closes after 10 idle minutes and reopens on the next action. The Chrome fallback on Windows may need one Web Store click.
-
-Queries default to headless and first try a read-only export of the requested site’s cookies from an existing connected local browser. No source browser is changed, no full Chrome profile is cloned, and no password/keychain is accessed. If no connected source is available, use saved Reach state. Multiple possible accounts require browser profiles/use selection. Only missing/expired login needs the human in a visible Reach window; the next query returns to headless with the same profile. Login is periodically saved without requiring the user to close the window. Human page interactions and Reach calls reset the idle timer. The Bridge is supervised with the browser; existing user-owned Bridge processes are preserved, and version conflicts are reported without restarting them.
+Show `result.installation_report.markdown` to the user as is. The program generates it; do not rewrite, reorder or add to it.
-If login is still needed, `agent-reach login CHANNEL` opens the shared dedicated browser. The user logs in there; for native tools, follow the returned sync instruction. `agent-reach execute CHANNEL ACTION --params '{...}'` prepares and executes the actual task once. If it returns `operation_id`, use `agent-reach resume OPERATION_ID` after the user finishes login. No additional model key is required.
+## 3. Later
-Removing a browser channel clears only that site's login/storage in the dedicated browser and its native session. Other sites are retained. If required cleanup fails, the channel remains registered and the error is returned. Xiaoyuzhou remains optional and needs a Groq key for transcription.
+- 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).