Agent Reach 更新日志解析：从 1.0 到 1.3.1，渠道演进与雪球渠道反爬修复全记录

Agent Reach（agent-reach）的 CHANGELOG.md 记录了项目从首次发布到 1.3.1 的完整演进轨迹：1.0.0 建立"一个平台、一个可插拔 Python 文件"的渠道架构，1.1.0 与 1.3.0 扩充职业社交与零配置社区渠道，1.3.1 则完成雪球渠道的一次系统性反爬修复。本文以更新日志为骨架，逐版本梳理关键变更，并结合仓库源码印证每条记录背后的实际实现，帮助读者快速判断当前版本的能力边界与已知限制。

版本演进总览

更新日志按时间倒序记录了四个版本节点，核心脉络如下：

版本	日期	关键变更
1.3.1	2026-03-27	雪球渠道全面修复：Cookie 加载策略、UA/Referer、热帖端点
1.3.0	2026-03-12	新增 V2EX 渠道（公开 JSON API，零配置），渠道数 14 → 15
1.1.0	2025-02-25	新增 LinkedIn、Boss直聘渠道；移除 Instagram；渠道数 9 → 12
1.0.0	2025-02-24	首次发布：9 渠道 + read/search/doctor/install CLI

需要说明的是：从 pyproject.toml 看，当前仓库版本号为 1.5.0，而更新日志的记录截至 1.3.1——这份日志是 1.0 至 1.3.1 阶段的历史快照，后文所有描述均以此范围为适用前提。

1.0.0 首次发布：统一渠道架构奠基

日志记录的首次发布包含九个渠道：Web、Twitter/X、YouTube、Bilibili、GitHub、Reddit、XiaoHongShu、RSS、Exa Search，以及四项核心工程特性：

• CLI 支持 read、search、doctor、install 命令；
• 统一渠道接口——每个平台是一个独立可插拔的 Python 文件；
• 自动检测本地/服务器环境；
• 内置诊断 agent-reach doctor；
• Skill 注册支持 Claude Code / OpenClaw / Cursor。

"统一渠道接口"这一条是整个架构的基石。从源码结构看，该设计落地在 渠道注册表：所有渠道类（GitHubChannel、TwitterChannel、V2EXChannel、XueqiuChannel 等）统一实例化后注册进 ALL_CHANNELS 列表，doctor.py 通过 get_all_channels() 遍历执行健康检查。每个渠道继承 Channel 基类，实现 can_handle()（URL 路由）、check()（健康探测）和数据获取方法——因此新增一个平台只需新增一个文件并加入注册表，这正是更新日志中"渠道数量 X → Y"能够频繁变更的原因。

1.1.0：一次增删并进的渠道扩充

该版本的变更分两条线：

移除 Instagram。 日志明确记录原因：Instagram 的激进反爬措施导致所有可用开源工具（instaloader 等）全部失效，参考上游 issue #2585，"上游恢复后会重新加回"。这是更新日志中少有的"做减法"记录，体现了渠道入选标准——不是"平台重要"就该接入，而是"当前有稳定可行的公开路径"才接入。

新增 LinkedIn 与 Boss直聘。 两者都走 MCP 协议扩展：

• LinkedIn：通过 linkedin-scraper-mcp 读取个人 Profile、公司页面、职位详情，MCP 搜索人才和职位并以 Exa 兜底，未配置 MCP 时自动回退到 Jina Reader；
• Boss直聘：通过 mcp-bosszp 扫码登录，MCP 搜索职位、向 HR 打招呼，Jina Reader 兜底读取职位页面。

配套的改进包括：agent-reach doctor 检测全部渠道、CLI 新增 search-linkedin、search-bosszhipin 子命令、安装指南同步更新。

从当前源码可以印证 LinkedIn 的"主后端 + 兜底"结构：LinkedIn 渠道声明 backends = ["mcp-server-linkedin", "Jina Reader"]，其 check() 会先探测本机 mcporter 命令是否存在、再检查 mcporter 配置中是否注册了 LinkedIn MCP 服务名（linkedin/mcp-server-linkedin 等），未配置时返回 off 状态并给出具体的 uvx mcp-server-linkedin@latest --login 与 mcporter config add 配置命令——诊断输出本身就是一份配置指引。

1.3.0：V2EX——零配置渠道的完整实现

V2EX 渠道是本日志中新增记录最完整的一次：通过 V2EX 公开 JSON API 提供热门帖子、节点帖子、帖子详情+回复、用户信息四类能力，且零配置——无需认证、无需代理、无需 API Key。日志列出的四个 API 方法与源码一一对应，见 V2EX 渠道实现：

日志记录的方法	源码位置	能力
get_hot_topics(limit)	get_hot_topics	调用 /api/topics/hot.json，返回标题、链接、回复数、所属节点
get_node_topics(node_name, limit)	get_node_topics	调用 /api/topics/show.json，浏览 python/tech/jobs 等节点最新帖
get_topic(id)	get_topic	帖子详情 + 第一页回复列表（/api/replies/show.json）
get_user(username)	get_user	用户资料，含 website、twitter、github、bio 等字段

源码中还体现了日志未展开的工程细节，对理解"零配置"的代价与保障很有价值：

• 严格 URL 白名单：_validate_api_url() 只放行 https://v2ex.com 或 https://www.v2ex.com 下 /api/ 前缀的路径，拒绝自定义端口、URL 内嵌凭据等变体，防止调用方注入非预期请求目标；
• 响应体积上限：响应超过 1 MiB 即抛错（_MAX_RESPONSE_BYTES），避免大响应拖垮 Agent 上下文；
• TLS 故障自愈：Python 标准库 urllib 遇到 UNEXPECTED_EOF_WHILE_READING 类 TLS 错误时，_get_json() 会识别该特定错误并用系统 curl 的 TLS 栈重试一次——这是纯零配置渠道也能应对国内网络环境抖动的关键设计；
• 搜索能力的诚实声明：search() 方法因 V2EX 公开 API 不提供搜索端点，直接返回错误提示并建议改用站内搜索页或 Exa 渠道的 site:v2ex.com 搜索，而不是返回伪造结果。

渠道的 tier = 0 也印证了其"开箱即用"定位：渠道注册表中 V2EX 与雪球（tier = 1，需要登录 Cookie）并列，但健康检查时 agent-reach doctor 对 V2EX 只需请求 /api/topics/show.json?node_name=python 验证连通性即可判定可用（check()）。

1.3.1：雪球渠道系统性修复

这是更新日志中技术密度最高的一个版本，一次性修复了导致雪球渠道 400 错误的整条因果链。逐条拆解：

400 错误根因与三级 Cookie 加载策略

日志指出的根本原因：_ensure_cookies() 仅访问首页只能拿到 acw_tc（防 DDoS token），而真正的登录态 xq_a_token 由雪球前端 JS 动态生成，无法通过纯 HTTP 请求获取。因此新增了三级 Cookie 加载策略：

1. 读取配置文件（configure --from-browser 保存的 Cookie 串）；
2. 自动从本地 Chrome 浏览器提取（需安装 browser-cookie3）；
3. 访问首页作为兜底。

雪球渠道源码中的 _ensure_cookies() 完整实现了这一策略：优先通过 _load_cookies_from_config() 从 agent-reach 配置的 xueqiu_cookie 键加载并注入 Cookie Jar（_inject_cookie_string() 将 name=value; name2=value2 串解析为 .xueqiu.com 域的 Cookie 对象）；配置缺失时才回退到访问首页捡取 acw_tc。源码注释明确说明该兜底"对需要登录会话的 API 不足够，但可避免仅依赖会话 Cookie 的公开端点硬性失败"。

第二级"从浏览器提取"落在 cookie_extract.py：1.3.1 的修复点是将 Xueqiu 加入 PLATFORM_SPECS（域名 .xueqiu.com，检测 Cookie 为 xq_a_token，配置键 xueqiu），且 configure_from_browser() 只有在确实提取到 xq_a_token 时才写入配置（xueqiu_cookie=xq_a_token=<token>），提取不到则明确提示"未找到 xq_a_token，请先在浏览器中登录 xueqiu.com"。该提取器支持 Chrome/Firefox/Edge/Brave/Opera，优先使用 rookiepy、回退 browser_cookie3，并对返回的 Cookie 做二次域名校验。

请求头修复：UA 与 Referer

• User-Agent：原来的 "agent-reach/1.0" 被雪球反爬识别拒绝，现改为真实 Chrome UA，见 _UA（Chrome 120 on macOS 的完整指纹）；
• Referer：所有 API 请求补上 Referer: https://xueqiu.com/，见 _get_json() 中统一设置的请求头。

这两个修复与 Cookie 策略共同构成雪球"伪装成正常浏览器会话"的完整请求面：真实 UA + 正确 Referer + 登录 Cookie。

热帖端点迁移与 JSON 解析

原端点 /statuses/hot/listV3.json 已废弃（返回空 body），改为 v4 公共时间线端点 /v4/statuses/public_timeline_by_category.json。get_hot_posts() 的实现还揭示了一个容易踩坑的响应结构：列表中每个 item.data 字段本身是一段JSON 编码的字符串，需要二次 json.loads() 才能拿到真正的帖子载荷（title、description、user、like_count、target），再做 HTML 标签剥离和实体解码后输出 id/title/text/author/likes/url 结构化字段，limit 上限 50。

其余修复与错误信息改善

• urllib.request.quote 改为正确的 urllib.parse.quote（源码 与 搜索方法 中均已使用）；
• 文档纠偏：README/SKILL.md 中"无需配置"/"public API, no login required" 的误导性描述改为准确说明需要 browser cookie——渠道类自身的 backends 也如实标注为 "Xueqiu API (需要登录 Cookie)"；
• check() 探测 stock.xueqiu.com/v5/stock/quote.json?symbol=SH601138 行情接口，失败时的提示从"可能需要代理"改为给出可执行命令 agent-reach configure --from-browser chrome --platform xueqiu，并明确说明 doctor 不会自动读取浏览器 Cookie。

修复后的雪球渠道对外提供实时行情（get_stock_quote，支持 SH600519/SZ000858/AAPL/00700 等代码）、股票搜索（search_stock）、热门帖子（get_hot_posts）与热门股票排行（get_hot_stocks，10=人气榜、12=关注榜）四类能力。

对照当前仓库：更新日志之外的现状

结合仓库现状，有几点值得读者注意：

1. 渠道注册表已扩展：当前 渠道注册表 实际注册了 15 个渠道实例（GitHub、Twitter、YouTube、Reddit、Facebook、Instagram、Bilibili、XiaoHongShu、LinkedIn、Xiaoyuzhou、V2EX、Xueqiu、RSS、Exa、Web），比 1.3.0 日志记录的 15 个在构成上已有变化——例如 Xiaoyuzhou（小宇宙播客）、Facebook 等渠道的实现文件均存在于 channels 目录 中，但更新日志尚未补记对应条目。
2. 诊断能力是变更的落点：无论哪个版本的新渠道或修复，最终都体现为 agent-reach doctor 的检查项。doctor.py 遍历全部渠道输出"X/Y 个渠道可用"，并对未激活的可选渠道给出一行式解锁提示——这是验证本日志所述各渠道状态的最直接手段。
3. 日志滞后于版本：如前所述，pyproject.toml 版本 1.5.0 高于日志最后记录的 1.3.1，因此本文结论严格限定于日志记载的范围；如需了解 1.3.1 之后的变更，需以当前源码为准。

小结

Agent Reach 的更新日志呈现出清晰的项目治理特征：能力靠渠道插拔扩张（1.1.0、1.3.0 的新渠道均遵循"一个平台一个文件"的既定架构），稳定性靠根因修复而非绕过（1.3.1 对雪球 400 错误的处理是逐级定位到 Cookie 生成机制后重建加载策略，并同步纠正了文档误导），可用性靠诚实的降级声明（V2EX 无搜索端点时明确报错并给出替代路径，Instagram 上游失效时干脆移除）。对使用者而言，读这份日志的最实用方式是：先确认所需渠道在其记录版本中是否可用、需要何种配置（零配置 / browser cookie / MCP 服务），再用 agent-reach doctor 在本地验证当前环境下的真实状态。