# 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 状态码同时表达语义：

```json
{
  "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`。

### 调用示例

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

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

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

请求体：

```json
{ "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[]` 每条：

```json
{
  "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`。

### 调用示例

```bash
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 — 登记发布任务（不执行）

请求体：

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

成功返回 201：

```json
{
  "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 — 真实调用计数

```json
{
  "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。