Agent-Reach 金融行情实战：雪球股票行情、最小 Cookie 配置与故障诊断全解

本文围绕 Agent-Reach 的金融能力参考文档 finance.md 展开，讲解如何在 AI Agent 中读取雪球股票行情、搜索标的并获取热门内容。读完本篇后，你将掌握 agent-reach doctor 状态判读、OpenCLI 复用浏览器登录态的完整命令集、xq_a_token 最小 Cookie 的显式导入方式，以及“退出码 0 但结果为空”“HTTP 400”等典型故障的正确诊断方法——这些能力让 Agent 能零 API 费用地接入雪球公开行情接口。

定位与适用前提

Agent-Reach 在技能体系中把渠道按主题分类，其中金融类对应雪球（股票行情/搜索/热帖/热股），入口文档即 finance.md，在 SKILL.md 中登记为 finance 分类：

需求场景	分类	参考文档
雪球/股票行情	finance	references/finance.md

该渠道由 XueqiuChannel 实现，其元信息表明后端为“Xueqiu API（需要登录 Cookie）”：

class XueqiuChannel(Channel):
    name = "xueqiu"
    description = "雪球股票行情与社区动态"
    backends = ["Xueqiu API (需要登录 Cookie)"]
    tier = 1

从源码结构看，行情数据来自雪球的公开 JSON 端点（如 stock.xueqiu.com/v5/stock/quote.json、xueqiu.com/stock/search.json、xueqiu.com/v4/statuses/public_timeline_by_category.json、stock.xueqiu.com/v5/stock/hot_stock/list.json），但访问这些端点通常需要已登录会话或最小 Cookie——这是本文后续所有诊断规则的根源。行情可能存在延迟，本文内容不构成投资建议。

第一步：用 doctor 检查渠道状态

任何雪球操作开始前，先运行健康检查：

agent-reach doctor --json

判读规则（继承自 finance.md，并与源码对应）：

• xueqiu.active_backend 有值：说明 Doctor 完成了实时内容验证，按该后端给出的方式使用即可；
• xueqiu.active_backend 为 null：仅表示 Doctor 没有完成实时内容验证，不等于渠道不可用；
• 不能把 HTTP 400 当成“股票不存在”：400 通常指向会话/Cookie 问题。

源码层面，check() 会用固定代码 SH601138 请求详情行情端点做探针：

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 响应异常（返回数据为空）"

三种结果路径：返回有效 quote → ok 并置 active_backend；返回空数据 → warn（“返回数据为空”）；连接异常 → warn 并提示运行 agent-reach configure --from-browser chrome --platform xueqiu，同时明确说明 doctor 不会自动读取浏览器 Cookie。这一行为由测试 test_check_never_reads_browser_cookie_store_implicitly 固化：即使 rookiepy 等浏览器读取库在模块表中，check() 全程不得触发浏览器凭据读取（断言 browser_reads == []）。

OpenCLI 路径：复用桌面 Chrome 登录态（优先）

当 xueqiu.active_backend 指向 OpenCLI 时，说明桌面 Chrome 已存在可复用的登录态。OpenCLI 通过浏览器扩展 + 本地守护进程驱动用户已经存在且明确控制的 Chrome 会话，实现零平台配置。核心命令集：

# 验证当前登录态
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

两条使用纪律：

1. 不要自动执行 opencli xueqiu login。OpenCLI 只复用用户已明确控制的浏览器会话；没有现成登录态时，正确做法是让用户先在 Chrome 中登录雪球，或改用下一节的最小 Cookie 显式导入。
2. 验证 OpenCLI 是否就绪时，Agent 侧应使用只读探测。opencli_status() 的实现体现了这一点：它只执行无副作用的 opencli --version，再读取守护进程回环 /status 接口判断 extensionConnected；而 OpenCLIStatus.ready 要求“安装 + 未损坏 + 扩展已连接”三者同时成立——仅凭磁盘上存在扩展文件不足以判定可用，避免 Agent 误诊环境。

最小 Cookie 导入：只采集 xq_a_token

无法使用 OpenCLI 时（无桌面 Chrome 登录态、扩展未连接等），可以显式导入雪球所需的最小 Cookie：

agent-reach configure --from-browser chrome --platform xueqiu

该命令的安全边界在 cookie_extract.py 的平台规格中明确定义：

{
    "name": "Xueqiu",
    "domains": (".xueqiu.com",),
    "cookies": ("xq_a_token",),   # 只读取这一个 Cookie
    "config_key": "xueqiu",
},

实际落盘逻辑见 configure 流程：仅从浏览器中提取 xq_a_token，以 xq_a_token=<token> 的形式写入配置键 xueqiu_cookie，不会顺带采集其他平台的 Cookie；若未找到 xq_a_token，则提示“请先在浏览器中登录 xueqiu.com”并以非零码退出。

运行时的 Cookie 装配优先级在 _ensure_cookies 中实现：

1. 优先：读取 ~/.agent-reach 配置中的 xueqiu_cookie（即上面 configure 写入的值），通过 _inject_cookie_string 解析 name=value; name2=value2 字符串并注入进程内 CookieJar（域固定为 .xueqiu.com、secure=True）；
2. 兜底：访问雪球首页获取 acw_tc 防 DDoS 会话 Cookie。源码注释明确指出，该兜底“不足以通过鉴权接口，但能让仅需会话 Cookie 的公开端点避免硬性失败”。

注意每次 HTTP 请求都会附带 Referer: https://xueqiu.com/ 和固定 Chrome 桌面 UA（见 xueqiu.py 常量区），这与雪球接口对请求头的一致性要求有关。

Python 渠道能力：行情、搜索、热帖、热股的字段契约

除 OpenCLI 外，Agent 也可直接调用 XueqiuChannel 的四个方法。它们的返回字段契约（由源码 docstring 与测试共同固化）如下：

实时行情 get_stock_quote(symbol)

get_stock_quote("SH600519")
# → {symbol, name, current, percent, chg, high, low, open, last_close,
#    volume, amount, market_capital, turnover_rate, pe_ttm, pe_forecast,
#    pb, eps, timestamp}

• 代码格式：沪市 SH600519、深市 SZ000858、美股直接 AAPL、港股 00700（源码 docstring 示例）；
• 请求经 URL 编码后拼接 extend=detail 参数；
• 响应缺失时不会抛异常，而是回显请求的 symbol 并返回空 name/None 数值（测试 test_get_stock_quote_falls_back_when_no_items 验证了这一点）。

股票搜索 search_stock(query, limit=10)

输入股票代码或中文名（如 "茅台"、"600519"），返回 [{symbol, name, exchange}] 列表，严格截取前 limit 条；响应中无 stocks 键时返回空列表而非报错（见 test_search_stock_handles_missing_stocks_key）。

热门帖子 get_hot_posts(limit=20)

• 返回 [{id, title, text, author, likes, url}]，正文经 _strip_html 去标签、解实体并截断至 200 字符；
• 底层端点返回的每条 item.data 是JSON 字符串（JSON-in-JSON），实现中做了二次解析，且对非字符串或非法 JSON 的 data 字段容错降级为默认值（test_get_hot_posts_tolerates_bad_data_field）；
• limit 上限 50，超出自动钳制（test_get_hot_posts_clamps_count_to_documented_maximum）；limit=0 直接返回空列表、不发起网络请求；负数抛 ValueError。

热门股票 get_hot_stocks(limit=10, stock_type=10)

• 返回 [{symbol, name, current, percent, rank}]，rank 从 1 开始按列表顺序编号；
• stock_type 取值：10=人气榜（默认），12=关注榜；
• 兼容 code/symbol 两种字段名（见 test_get_hot_stocks_ranks_and_falls_back_to_symbol）。

验收标准与失败处理（诊断决策表）

finance.md 给出的三条验收规则，是 Agent 调用雪球能力时必须遵守的判读逻辑：

现象	正确判读	依据
退出码 0 但字段为空	不算成功。以返回股票名称、代码、价格或非空内容列表为成功标准	空 quote 在 check() 中即被判为 warn
HTTP 400	通常是会话/Cookie 问题，不表示股票代码不存在	400 源于请求头/会话校验失败，应先补登录态再重试
whoami 成功，但 stock/hot 失败	按适配器解析或平台接口问题报告，不要误诊成未登录	登录态已验证，问题在响应整形或端点侧

第三条规则对应源码中一个真实风险点：热帖端点的 data 字段是 JSON 字符串，若平台侧调整了载荷结构，会出现“已登录但解析为空”的现象——此时 _get_hot_posts 的容错会静默降级为默认值，而非暴露解析失败。因此在报告此类故障时应指明“适配器解析/平台接口”方向，而不是回头让用户重新登录。

快速排查清单

按以下顺序定位雪球渠道问题：

1. agent-reach doctor --json → 看 xueqiu.active_backend：有值则走对应后端；为 null 时先做第 2 步，而不是下“不可用”结论；
2. 若后端为 OpenCLI：先 opencli xueqiu whoami -f yaml 验证登录态；失败时确认 Chrome 已登录雪球且 OpenCLI 扩展已连接（切勿自动执行 login）；
3. 若无可用登录态：让用户在 Chrome 登录后执行 agent-reach configure --from-browser chrome --platform xueqiu，确认输出为 ✅ Xueqiu: xq_a_token 且提示写入 xueqiu_cookie；
4. 复跑 agent-reach doctor，再执行只读命令（如 opencli xueqiu hot-stock -f yaml），以非空内容列表为最终验收；
5. 遇到 400 或“登录成功但取数失败”，对照上表归因，避免误诊。

完整的渠道解析与容错行为由 tests/test_xueqiu_channel.py 离线固化（全部用例以 stub 替换 _get_json，无需真实网络），可作为理解各端点响应整形逻辑的参考。