SOS A股 Agent Gateway

SOS A股 Agent Gateway — 完整机器说明（llms-full.txt）

面向 Agent / 自动化脚本。读这一份即可完成接入。最后更新：2026-11-06。

Base URL: https://sos-a-share-gateway.pages.dev 传输: HTTPS + JSON (UTF-8) 鉴权: 无。免注册、免密钥。 CORS: 允许任意来源（Access-Control-Allow-Origin: *） 缓存: 所有接口 Cache-Control: no-store，请勿依赖 CDN 缓存 费用: 查/验免费；发只登记任务，人工确认报价，线下转账，无自动扣款 数据来源: https://lianban.pages.dev/api/stocks/review|tianti|qingxu（公开只读接口，本网关不写入该站点）

0. 错误约定

所有失败都返回统一结构，HTTP 状态码同时表达语义：

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "platform 必须是 weibo | zhihu | toutiao | taoguba | xueqiu 之一",
    "details": { }
  }
}

code	HTTP	含义	调用方应怎么做
invalid_request	400	参数缺失/类型错误/超长	修正参数后重试，不要原样重试
method_not_allowed	405	方法用错（如 GET /v1/publish）	换正确方法
queue_full	429	发布任务队列已满（上限 300）	等运营方清理，不要循环重试
internal_error	500	网关内部异常	可重试一次；持续失败请记录 message
upstream_unavailable	502	盘面数据源不可用	稍后重试；不要把上次结果当今日数据
storage_unavailable	503	服务端 KV 未绑定，无法持久化/计数	稍后重试

约定：数据源失败时返回 502，不会返回空数据、旧数据、缓存兜底值或编造值。

1. GET /v1/market — 今日真实盘面

无参数。每次请求实时拉取上游三个接口（review / tianti / qingxu）。

顶层字段

字段	类型	说明
ok	boolean	成功恒为 true
data_date	string	数据交易日，格式 YYYYMMDD（如 20261106）
data_date_iso	string/null	同一日期的 YYYY-MM-DD
prev_data_date	string/null	上一交易日 YYYYMMDD
data_stale	boolean	必看：true 表示这不是今日数据
stale_reason	string/null	data_stale=true 时的原因
session	string	pre_open / morning_session / lunch_break / afternoon_session / closed（北京时间）
is_intraday	boolean	是否处于连续竞价时段（盘中数据还会变）
as_of_shanghai	string	网关生成响应时的北京时间
fetched_at	string	ISO 时间戳
breadth	object	涨跌广度，见下
rates	object	封板率/炸板率/晋级率
sentiment	object	情绪温度与阶段
indices	array	指数涨跌与成交额
themes	array	主线题材（最多 12 条）
ladder	array	连板梯队（按板高降序分组）
ladder_detail	object/null	天梯原始汇总：total_rows / promote_11d / relay
warnings	string[]	数据时效与降级提示
sources	array	每个上游的 url / http_status / latency_ms / fetched_at / ok
license_notice	string	固定声明：仅供研究参考，不构成投资建议

breadth

limit_up, limit_up_prev, limit_down, limit_down_prev,
lianban, lianban_prev, max_board, max_board_prev,
advance, decline, red_pct, turnover_yi

• turnover_yi 单位：亿元。
• lianban = 连板（≥2 板）家数；max_board = 最高板高度。

rates

seal_rate_pct            封板率 %
broken_count             炸板家数
broken_rate_pct          炸板率 %
promotion_rate_pct       晋级率 % = promotion_hits / promotion_sample
promotion_hits           今日连板家数（relay.promoted）
promotion_sample         上一交易日涨停家数（relay.total）
promotion_rate_formula   公式原文
first_board_promotion_rate_pct  首板晋级率 %
first_board_promotion_formula   公式原文

晋级率由上游 relay 字段计算，公式随响应返回，可自行复核。

sentiment

temperature    情绪温度（整数）
phase          情绪阶段代码（如 ebb）
phase_label    阶段中文名（如 退潮期）
consec         情绪阶段连续天数（上游 qingxu 提供）
recent         最近 8 条情绪轨迹（上游 qingxu 提供）

themes[]（主线题材）

name            题材名
limit_up_count  该题材当日涨停家数
leader          龙头股名称（可能为 null）
driver          驱动原因（可能为 null）

ladder[]（连板梯队）

board     板高
count     该板高家数
stocks[]  { code, name, board, tag, first_seal_time, open_times, limit_up_days, window_days, window_count }

响应头

X-Data-Date：数据交易日；X-Data-Stale：true/false。

调用示例

curl -s https://sos-a-share-gateway.pages.dev/v1/market \
  -H "X-Agent-Source: my-agent"

2. POST /v1/verify — 一句话事实核验

给一句话，逐条判定其中的数字、个股、题材是否与当日真实盘面一致，并返回原始依据。

请求体：

{ "text": "今日涨停32家，最高5板。闽发铝业5板。" }

也支持 GET /v1/verify?text=...（URL 编码）。text 上限 2000 字，必填。

响应字段

字段	说明
verdict	supported / partially_supported / contradicted / unverifiable
summary	claims_total / matched / mismatched / info_only / unknown / unverified_numbers
claims[]	逐条判定结果，见下
unverified_numbers[]	文中出现但当日没有可对照指标的数字（原样列出，不猜）
coverage	核验覆盖范围：数据日期、是否 stale、已对照指标、涨停池只数、题材数
data_date / data_stale / session / as_of_shanghai / sources / warnings	与 /v1/market 同源同时效

claims[] 每条：

{
  "type": "number | stock | stock_code | theme",
  "metric": "limit_up",
  "label": "涨停家数",
  "claim": "涨停32家",
  "stated": 32,
  "actual": 32,
  "status": "match | mismatch | unknown | info",
  "evidence": { "field": "limit_up", "value": 32, "data_date": "20261106", "source": "https://..." }
}

判定规则：

• match：与当日真实数据一致（百分比指标带容差：封板率/炸板率 ±0.6，晋级率 ±0.8，成交额相对误差 1%）。
• mismatch：与当日真实数据矛盾。
• unknown：该指标当日无法对照（例如出现 6 位代码但不在当日涨停池——不在涨停池 ≠ 今天没涨，会原样说明）。
• info：个股/题材命中当日涨停池但句中未声称板高或家数，仅返回客观依据（板高、首封时间、开板次数、题材涨停家数）。

verdict 规则：任一条 mismatch → contradicted；全部 match 且无未核验数字 → supported；有 match 或 info → partially_supported；否则 unverifiable。

调用示例

curl -s -X POST https://sos-a-share-gateway.pages.dev/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-Agent-Source: my-agent" \
  -d '{"text":"今日涨停32家，情绪温度57，最高5板"}'

3. POST /v1/publish — 登记发布任务（不执行）

请求体：

{
  "platform": "weibo | zhihu | toutiao | taoguba | xueqiu",
  "title": "可选，≤120 字",
  "content": "必填，10–4000 字",
  "requester": "可选，≤80 字"
}

成功返回 201：

{
  "ok": true,
  "task": {
    "id": "req-...",
    "type": "publish_request",
    "platform": "weibo",
    "content": "...",
    "content_length": 42,
    "requester": "my-agent",
    "reward": { "currency": "CNY", "amount": null, "mode": "quote_required" },
    "settlement": { "mode": "manual", "auto_payout": false },
    "status": "pending_human_review",
    "execution": { "mode": "local_browser_required", "executes": false }
  },
  "next_step": "运营方人工确认报价与内容后，在本机登录态浏览器执行；不自动发布、不自动扣款。"
}

限制与如实说明：

• 公网只登记，不执行；发布依赖运营方本机已登录的浏览器，本机关机就无法执行。
• 队列上限 300 条，满则 429 queue_full。
• 无自动结算、无虚拟余额、无自动扣款；reward.amount 在运营方确认前恒为 null。
• GET /v1/publish 返回 405。

4. GET /v1/stats — 真实调用计数

{
  "ok": true,
  "updated_at": "2026-11-06T...Z",
  "totals": { "calls": 0, "external_calls": 0, "internal_calls": 0 },
  "first_external_call_at": null,
  "last_external_call_at": null,
  "has_external_calls": false,
  "by_endpoint": [ { "endpoint": "v1_market", "calls": 0 } ],
  "by_source": [ { "source": "unknown", "calls": 0, "first_call_at": null, "last_call_at": null } ],
  "counting_note": "...",
  "endpoints_note": "..."
}

• 内部自测：请求头 X-Gateway-Self-Test: 1 或 ?self_test=1，计入 internal_calls。
• 外部来源：其余全部，计入 external_calls；来源名取 X-Agent-Source 或 ?source=，缺省为 unknown。
• 唯一有效的验证指标是 external_calls > 0 与 first_external_call_at 非空。
• 诚实说明：来源标记为自声明，理论上可被伪造；计数写入 D1（单条 upsert），比 KV 读改写可靠，但不宣称是计费级精确统计。
• 只统计网关真实 HTTP 调用，不含本机 MCP（stdio）调用。

5. 其它入口

路径	说明
GET /manifest.json	能力清单：能力、验证状态、定价、结算、限制
GET /tasks	任务列表（内置能力任务 + 已登记发布请求）
GET /tasks/:id	单个任务详情
POST /tasks	与 /v1/publish 等价的提交入口
GET /llms.txt	精简版机器说明（本文件的摘要）
GET /openapi.json	OpenAPI 3.1 定义
GET /agent-card.json	能力卡片（a2a_compatible: false，非标准 A2A 服务器）

6. 数据时效与诚实边界

1. 上游只提供最近一个交易日。非交易日、盘前、上游未更新时 data_stale=true，warnings 会写明原因。
2. 交易时段内取到的是盘中快照，收盘前会变；is_intraday=true。
3. 数据源不可用 → 502 upstream_unavailable；不返回空壳、不返回旧值。
4. 本网关不写 lianban.pages.dev，只读调用；数据版权与免责归上游，仅供研究参考，不构成投资建议。
5. 没有任何用户量、下载量、调用量被夸大：所有计数只在 /v1/stats 真实读出，为 0 就显示 0。