From d291d276645c335b93b815461ab6bd7ff90f5882 Mon Sep 17 00:00:00 2001
From: Panniantong <panniantong@users.noreply.github.com>
Date: Wed, 25 Feb 2026 21:45:40 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20install.md=20=E5=92=8C=20SKILL.md=20?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85=20Twitter=20=E4=BB=A3=E7=90=86=E6=96=B9?=
 =?UTF-8?q?=E6=A1=88=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

让 Agent 在配置 Twitter 时知道：
- undici 需要安装（npm install -g undici）
- 代理注入是自动的，不需要用户额外操作
- fetch failed 的排查步骤
---
 agent_reach/skill/SKILL.md | 17 +++++++++++++++++
 docs/install.md            | 13 +++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 8c6a455..e9e6028 100644
--- a/agent_reach/skill/SKILL.md
+++ b/agent_reach/skill/SKILL.md
@@ -103,3 +103,20 @@ These are things only the user can do. When `doctor` indicates one is needed, ex
 - If a channel is ⬜ but the user hasn't asked for it, don't push — let them opt in
 - If a channel breaks, run `agent-reach doctor` to diagnose
 - LinkedIn and Boss直聘 have Jina Reader fallback even without full setup
+- Twitter search 在 bird 失败时会自动 fallback 到 Exa 搜索
+
+## Troubleshooting
+
+### Twitter "fetch failed"
+
+bird CLI 用 Node.js 原生 `fetch()`，不走 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量。
+Agent Reach 已内置解决方案：通过 `undici` 的 `EnvHttpProxyAgent` 自动注入代理。
+
+**你（Agent）需要确认：**
+1. `undici` 已全局安装：`npm list -g undici`，没有就装：`npm install -g undici`
+2. 用户已配置代理：`agent-reach configure proxy http://user:pass@ip:port`
+3. Agent Reach 会自动处理注入，不需要用户额外操作
+
+如果以上都没问题仍然 "fetch failed"，建议用户使用透明代理（如 Clash TUN 模式、Proxifier）。
+
+详见 https://github.com/Panniantong/Agent-Reach/blob/main/docs/troubleshooting.md
diff --git a/docs/install.md b/docs/install.md
index 352a73a..499302b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -90,6 +90,19 @@ Some channels need credentials only the user can provide. Based on the doctor ou
 agent-reach configure twitter-cookies "PASTED_STRING"
 ```
 
+> **代理说明（中国大陆等需要翻墙的网络环境）：**
+>
+> bird CLI 使用 Node.js 原生 `fetch()`，默认不走系统代理（`HTTP_PROXY`/`HTTPS_PROXY`）。
+> Agent Reach 已内置解决方案：安装时会自动安装 `undici`（`npm install -g undici`），
+> 运行 bird 时自动注入 `EnvHttpProxyAgent`，让 fetch 走用户配置的代理。
+>
+> **你（Agent）需要做的：**
+> 1. 确认 `undici` 已全局安装：`npm list -g undici`，没有就装：`npm install -g undici`
+> 2. 确认用户配了代理：`agent-reach configure proxy http://user:pass@ip:port`
+> 3. Agent Reach 会自动处理剩下的，不需要用户做额外操作
+>
+> 如果用户报告 "fetch failed"，参考 [troubleshooting.md](troubleshooting.md)
+
 **Reddit & Bilibili full access (server users):**
 > "Reddit and Bilibili block server IPs. To unlock full access, I need a residential proxy. You can get one at https://webshare.io ($1/month). Send me the proxy address."