@dshtrading/connector-polymarket 0.6.2 → 0.7.0

package/README.md

@@ -1,7 +1,8 @@
 # @dshtrading/connector-polymarket
 
 Polymarket 预测市场连接器（**只读**公开 API，无密钥）。v1 只覆盖 **FOMC 决议路径**：
-给出一场会议的各档位标签与隐含概率，供右侧栏预测市场面板使用。
+给出一场会议的各档位标签与隐含概率。同一份取数服务供两处消费——右侧栏预测市场面板
+（经桥 `/dshtrading/api/prediction/fomc`）与三个 agent 只读工具（见下）；**没有第二份取数逻辑**。
 
 判据与口径的唯一来源是 [spikes/impl-polymarket/EVIDENCE.md](../../spikes/impl-polymarket/EVIDENCE.md)
 （P0 spike 裁决）。**不要另起一套猜法**——发现规则与概率口径都在那份证据里钉死了。
@@ -11,13 +12,35 @@ Polymarket 预测市场连接器（**只读**公开 API，无密钥）。v1 只
 - `src/gamma.ts` —— gamma HTTP 传输层。固定自有 UA（实测 200；`Python-urllib` 会触发
   Cloudflare 1010 → 403 且响应体是 text/plain）、显式超时、三层失败语义
   （传输 → `TRADING_NETWORK`；4xx/5xx → `TRADING_UPSTREAM_ERROR`；200 非 JSON → 契约破损）。
+- `src/json.ts` —— 上游 JSON 取值原语（字符串化数组、字符串数字、空串判定），发现面与
+  事件面共用同一份口径。
 - `src/discovery.ts` —— 发现规则 L0..L5（`series_id=35` → `series[].id` 校验 → 标题正则
   → `negRisk` + 档位数 4..6 → 噪声排除 → 按 id 去重/`endDate` 升序）与档位归一化。
   纯函数，可离线复核历史证据。
+- `src/events.ts` —— 事件读取面：关键词检索（单页本地过滤）与单事件详情，纯函数。
 - `src/snapshot.ts` —— 本地快照（存 trading home）。只回答「自上次观察变了多少」，
   缺失时 `changeSincePrevious` **缺省而不是 0**。
-- `src/service.ts` —— 取数服务 + host 面服务对象（`tradingPredictionFeed`）。
-- `src/plugin.ts` —— 插件入口。
+- `src/service.ts` —— 取数服务 + host 面服务对象（`tradingPredictionFeed`）+ 工具面方法。
+- `src/tools.ts` —— agent 工具面（三个只读工具）。
+- `src/plugin.ts` —— 插件入口（`inject: ['tools']`；provide 服务并注册工具）。
+
+## agent 工具面
+
+| 工具 | 入参 | 说明 |
+|---|---|---|
+| `prediction_fomc_meetings` | `meetingId?`（id 或 slug） | FOMC 档位与隐含概率（含已结算），每档带 `changeSincePrevious`（有历史快照时才有，缺失 = 不知道） |
+| `prediction_search_events` | `keyword`（必填）、`limit?`（1..50，默认 20） | 关键词列出预测市场事件 |
+| `prediction_event_detail` | `eventId`（必填，id 或 slug） | 单事件详情：各档 `outcomes`/`outcomePrices`/报价/流动性/`negRisk` |
+
+三个工具每次调用只发**一次** `GET /events`，出参一律带 `observedAt`（取数时刻）、
+`source`（读取面）、`stale`（`cf-cache-status: HIT` = 拿到的是最多 5 分钟前的 CDN 副本；
+`false` 的含义是「没有观察到缓存命中」，不是「已证明实时」）。
+
+**上游 `/events` 没有关键词参数**（`q=` / `title=` 被忽略，默认排序是 event id 升序），
+因此检索是「一次拉 100 条开盘中 24h 成交额降序的事件 + 本地过滤」，出参显式标注
+`filtering: "local-page-filter"`、`pageLimit`、`scanned`、`matched`（截断前命中数）。
+命中面是事件**标题与 slug**，不含档位标签（否则 `fed` 会命中人名 `Federico`）。
+实测与原始响应：[spikes/impl-polymarket/agent-tools-ACCEPTANCE.md](../../spikes/impl-polymarket/agent-tools-ACCEPTANCE.md)。
 
 ## 只读边界（硬约束）
 

package/lib/clob.d.ts

@@ -0,0 +1,73 @@
+import { PredictionPricePoint } from "@dshtrading/api";
+//#region src/clob.d.ts
+declare const CLOB_BASE_URL = "https://clob.polymarket.com";
+/**
+ * 历史窗口上限 = 336 小时（Q3.2 实测：168h/336h 可查，720h 直接报窗口过长）。
+ *
+ * 桥侧（`PREDICTION_HISTORY_MAX_WINDOW_MS`）有一道同值闸门，本连接器再拦一次：桥是
+ * 可选面（HTTP 客户端可能绕过它），而**必然失败的长窗口不该被发到上游**。
+ */
+declare const PRICE_HISTORY_MAX_WINDOW_MS: number;
+/**
+ * fidelity 缺省 = 5 分钟。
+ *
+ * 依据：面板「事件对照」的对照粒度是事件时点（CPI/PPI 公布时刻），5 分钟足以把公布
+ * 前后几小时的变动读出来；同时上游对 1w 及以上窗口要求 `fidelity >= 5`
+ * （Q3.1：`interval=1w` 原文 `minimum 'fidelity' for '1w' range is 5`），取 5 不会在
+ * 任何合法窗口上被上游拒绝。体积实测（EVIDENCE Q3.6，2026-10-20）：24h/5min 一档
+ * **289 点、约 8 KB**；336h/5min 一档 **3969 点**，仍在单次响应的可接受体积内。
+ */
+declare const DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES = 5;
+interface ClobTransportOptions {
+  /** 单次请求超时（ms），缺省与 gamma 相同的 10s（`DEFAULT_TIMEOUT_MS`）。 */
+  readonly timeoutMs?: number;
+  /** 注入的 fetch（测试用契约化替身；缺省 globalThis.fetch）。 */
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** 基址覆盖（测试指向本地夹具服务用）。 */
+  readonly baseUrl?: string;
+  /** UA 覆盖。 */
+  readonly userAgent?: string;
+}
+interface ClobPriceHistoryRequest {
+  /** CLOB token（来自 gamma market 的 `clobTokenIds[0]`；公开数据，非凭据）。 */
+  readonly token: string;
+  /** 窗口起点（epoch ms；本层换算成上游的 unix 秒）。 */
+  readonly fromMs: number;
+  /** 窗口终点（epoch ms）。 */
+  readonly toMs: number;
+  /** 粒度（分钟）；缺省 {@link DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES}。 */
+  readonly fidelityMinutes?: number;
+}
+/** 一档的窗口内读数（`t` 为上游 unix 秒，`p` 为上游 midpoint 概率，均原样）。 */
+interface ClobPriceHistory {
+  readonly points: readonly PredictionPricePoint[];
+}
+/**
+ * 发请求前的窗口/粒度闸门（服务层与本层共用：服务层用它做到「非法请求零请求」）。
+ *
+ * 违约抛 `TRADING_UNSUPPORTED_INTERVAL`：上游对长窗口的原文就是 `… interval is too long`、
+ * 对非法粒度是 `minimum 'fidelity' for '1w' range is 5`——两者都是「这个区间/粒度我不服务」，
+ * 与 `TRADING_UPSTREAM_ERROR`（请求发出去了、上游报错）区分开：这里**一次请求都没发**。
+ */
+declare function assertPriceHistoryRange(fromMs: number, toMs: number, fidelityMinutes: number): void;
+/**
+ * CLOB 只读传输层：一次 `GET /prices-history` = 一档一个窗口。
+ *
+ * 失败语义三层（**全部抛结构化错误，绝不返回空数组冒充「没有变动」**）：
+ * - 传输层（DNS/TLS/超时）→ `TRADING_NETWORK`；
+ * - HTTP 非 2xx（403 的 text/plain 就是 Cloudflare 1010）→ `TRADING_UPSTREAM_ERROR`，
+ *   消息带状态码与响应片段；
+ * - 200 但体不是 JSON / 没有 `history` 数组 → `TRADING_UPSTREAM_ERROR`（契约破损）。
+ * 唯一不抛的「空」是 **200 + `{"history":[]}`**：那是上游的真实回答（见文件头第 4 条）。
+ */
+declare class ClobClient {
+  private readonly timeoutMs;
+  private readonly fetchImpl;
+  private readonly baseUrl;
+  private readonly userAgent;
+  constructor(options?: ClobTransportOptions);
+  /** 取一档在 [fromMs, toMs] 内的历史读数（按 `t` 升序；空 = 上游没有读数，不是失败）。 */
+  priceHistory(request: ClobPriceHistoryRequest): Promise<ClobPriceHistory>;
+}
+//#endregion
+export { CLOB_BASE_URL, ClobClient, ClobPriceHistory, ClobPriceHistoryRequest, ClobTransportOptions, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, PRICE_HISTORY_MAX_WINDOW_MS, assertPriceHistoryRange };

package/lib/clob.js

@@ -0,0 +1,122 @@
+import { PolymarketError, bodySnippet, networkError } from "./errors.js";
+import "./gamma.js";
+//#region src/clob.ts
+const CLOB_BASE_URL = "https://clob.polymarket.com";
+/**
+* 历史窗口上限 = 336 小时（Q3.2 实测：168h/336h 可查，720h 直接报窗口过长）。
+*
+* 桥侧（`PREDICTION_HISTORY_MAX_WINDOW_MS`）有一道同值闸门，本连接器再拦一次：桥是
+* 可选面（HTTP 客户端可能绕过它），而**必然失败的长窗口不该被发到上游**。
+*/
+const PRICE_HISTORY_MAX_WINDOW_MS = 12096e5;
+/**
+* fidelity 缺省 = 5 分钟。
+*
+* 依据：面板「事件对照」的对照粒度是事件时点（CPI/PPI 公布时刻），5 分钟足以把公布
+* 前后几小时的变动读出来；同时上游对 1w 及以上窗口要求 `fidelity >= 5`
+* （Q3.1：`interval=1w` 原文 `minimum 'fidelity' for '1w' range is 5`），取 5 不会在
+* 任何合法窗口上被上游拒绝。体积实测（EVIDENCE Q3.6，2026-10-20）：24h/5min 一档
+* **289 点、约 8 KB**；336h/5min 一档 **3969 点**，仍在单次响应的可接受体积内。
+*/
+const DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES = 5;
+/**
+* 发请求前的窗口/粒度闸门（服务层与本层共用：服务层用它做到「非法请求零请求」）。
+*
+* 违约抛 `TRADING_UNSUPPORTED_INTERVAL`：上游对长窗口的原文就是 `… interval is too long`、
+* 对非法粒度是 `minimum 'fidelity' for '1w' range is 5`——两者都是「这个区间/粒度我不服务」，
+* 与 `TRADING_UPSTREAM_ERROR`（请求发出去了、上游报错）区分开：这里**一次请求都没发**。
+*/
+function assertPriceHistoryRange(fromMs, toMs, fidelityMinutes) {
+	if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || fromMs >= toMs) throw new PolymarketError("TRADING_UNSUPPORTED_INTERVAL", `polymarket clob /prices-history: window must satisfy fromMs < toMs (got fromMs=${fromMs}, toMs=${toMs})`);
+	if (toMs - fromMs > 12096e5) throw new PolymarketError("TRADING_UNSUPPORTED_INTERVAL", `polymarket clob /prices-history: window ${toMs - fromMs}ms exceeds the upstream limit of ${PRICE_HISTORY_MAX_WINDOW_MS}ms (336h) — not sent`);
+	if (!Number.isFinite(fidelityMinutes) || fidelityMinutes <= 0) throw new PolymarketError("TRADING_UNSUPPORTED_INTERVAL", `polymarket clob /prices-history: fidelityMinutes must be a positive number of minutes (got ${fidelityMinutes}) — not sent`);
+}
+/**
+* CLOB 只读传输层：一次 `GET /prices-history` = 一档一个窗口。
+*
+* 失败语义三层（**全部抛结构化错误，绝不返回空数组冒充「没有变动」**）：
+* - 传输层（DNS/TLS/超时）→ `TRADING_NETWORK`；
+* - HTTP 非 2xx（403 的 text/plain 就是 Cloudflare 1010）→ `TRADING_UPSTREAM_ERROR`，
+*   消息带状态码与响应片段；
+* - 200 但体不是 JSON / 没有 `history` 数组 → `TRADING_UPSTREAM_ERROR`（契约破损）。
+* 唯一不抛的「空」是 **200 + `{"history":[]}`**：那是上游的真实回答（见文件头第 4 条）。
+*/
+var ClobClient = class {
+	timeoutMs;
+	fetchImpl;
+	baseUrl;
+	userAgent;
+	constructor(options = {}) {
+		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+		this.baseUrl = options.baseUrl ?? "https://clob.polymarket.com";
+		this.userAgent = options.userAgent ?? "dsh-trading-connector-polymarket/0.6.1";
+	}
+	/** 取一档在 [fromMs, toMs] 内的历史读数（按 `t` 升序；空 = 上游没有读数，不是失败）。 */
+	async priceHistory(request) {
+		const token = request.token.trim();
+		if (token === "") throw new PolymarketError("TRADING_UNSUPPORTED_SYMBOL", "polymarket clob /prices-history: empty clob token id — no request sent");
+		const fidelityMinutes = request.fidelityMinutes ?? 5;
+		assertPriceHistoryRange(request.fromMs, request.toMs, fidelityMinutes);
+		const url = new URL("/prices-history", this.baseUrl);
+		url.searchParams.set("market", token);
+		url.searchParams.set("startTs", String(Math.floor(request.fromMs / 1e3)));
+		url.searchParams.set("endTs", String(Math.floor(request.toMs / 1e3)));
+		url.searchParams.set("fidelity", String(fidelityMinutes));
+		const controller = new AbortController();
+		const timer = setTimeout(() => {
+			controller.abort();
+		}, this.timeoutMs);
+		let response;
+		try {
+			response = await this.fetchImpl(url, {
+				method: "GET",
+				headers: {
+					"user-agent": this.userAgent,
+					accept: "application/json"
+				},
+				signal: controller.signal
+			});
+		} catch (cause) {
+			throw networkError(`polymarket clob ${url.pathname}`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		const text = await response.text();
+		if (!response.ok) throw new PolymarketError("TRADING_UPSTREAM_ERROR", `polymarket clob ${url.pathname}: HTTP ${response.status} — ${bodySnippet(text)}`);
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			throw new PolymarketError("TRADING_UPSTREAM_ERROR", `polymarket clob ${url.pathname}: HTTP ${response.status} but the body is not JSON — ${bodySnippet(text)}`);
+		}
+		return { points: readPoints(url.pathname, body, text) };
+	}
+};
+/**
+* `{"history":[…]}` → 读数数组。
+*
+* - 缺 `history` 数组 = 契约破损（抛错）——`{"history":[]}` 才是合法的空；
+* - 逐条丢弃非法读数（`t` 非有限数、`p` 非有限数或不在 0..1）；**不猜、不插值、
+*   不用相邻值补位**，少一个点就是上游没给这个点；
+* - 只按 `t` 升序排列（上游偶有乱序），不做去重/重采样/单位换算。
+*/
+function readPoints(pathname, body, text) {
+	const history = typeof body === "object" && body !== null ? body.history : void 0;
+	if (!Array.isArray(history)) throw new PolymarketError("TRADING_UPSTREAM_ERROR", `polymarket clob ${pathname}: HTTP 200 but the body has no history array — ${bodySnippet(text)}`);
+	const points = [];
+	for (const row of history) {
+		if (typeof row !== "object" || row === null) continue;
+		const { t, p } = row;
+		if (typeof t !== "number" || !Number.isFinite(t)) continue;
+		if (typeof p !== "number" || !Number.isFinite(p) || p < 0 || p > 1) continue;
+		points.push({
+			t,
+			p
+		});
+	}
+	points.sort((left, right) => left.t - right.t);
+	return points;
+}
+//#endregion
+export { CLOB_BASE_URL, ClobClient, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, PRICE_HISTORY_MAX_WINDOW_MS, assertPriceHistoryRange };

package/lib/discovery.js

@@ -1,3 +1,4 @@
+import { isRecord, num, parseStringArray, text } from "./json.js";
 //#region src/discovery.ts
 /** 判据来源系列：FOMC 决议（证据 Q1.2，39/39 命中、噪声 0）。 */
 const FOMC_SERIES_ID = "35";
@@ -48,21 +49,6 @@ const PROBABILITY_SUM_MIN = .98;
 const PROBABILITY_SUM_MAX = 1.03;
 /** 会议日程解析（上游 description 原文：`its meeting scheduled for October 27-28, 2026`）。 */
 const MEETING_WINDOW_RE = /meeting scheduled for ([A-Z][a-z]+ \d+(?:-\d+)?, \d{4})/;
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function num(value) {
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-	if (typeof value === "string" && value.trim() !== "") {
-		const parsed = Number(value);
-		if (Number.isFinite(parsed)) return parsed;
-	}
-}
-function text(value) {
-	if (typeof value !== "string") return void 0;
-	const trimmed = value.trim();
-	return trimmed.length > 0 ? trimmed : void 0;
-}
 /** 档位标签 → 稳定键与利率变动（证据 Q1.7：标签在大小写与 `+` 上会漂移）。 */
 function canonicalBucket(label) {
 	const value = label.trim();
@@ -93,6 +79,17 @@ function hasSeries(event) {
 }
 /** `outcomePrices` 是**字符串化的 JSON 数组**（如 `"[\"0.0035\",\"0.9965\"]"`）。 */
 function parseOutcomePrices(value) {
+	const parsed = parseStringArray(value);
+	if (parsed === void 0 || parsed.length === 0) return void 0;
+	return num(parsed[0]);
+}
+/**
+* `clobTokenIds` → 第 0 个 token（Yes 档，与 `outcomePrices[0]` 同档）。
+*
+* 上游把数组装成字符串（`"[\"706…\",\"528…\"]"`），与 `outcomePrices` 同一种包装；
+* 缺省/非字符串/不是数组/首元素不是非空字符串一律返回 undefined（不填，不猜）。
+*/
+function parseClobTokenId(value) {
 	if (typeof value !== "string") return void 0;
 	let parsed;
 	try {
@@ -101,7 +98,7 @@ function parseOutcomePrices(value) {
 		return;
 	}
 	if (!Array.isArray(parsed) || parsed.length === 0) return void 0;
-	return num(parsed[0]);
+	return text(parsed[0]);
 }
 function parseBucket(market) {
 	const label = text(market.groupItemTitle);
@@ -114,6 +111,7 @@ function parseBucket(market) {
 	const volume = num(market.volumeNum);
 	const volume24h = num(market.volume24hr);
 	const tickSize = num(market.orderPriceMinTickSize);
+	const clobTokenId = parseClobTokenId(market.clobTokenIds);
 	return {
 		key,
 		label,
@@ -126,6 +124,7 @@ function parseBucket(market) {
 		...volume !== void 0 ? { volume } : {},
 		...volume24h !== void 0 ? { volume24h } : {},
 		...tickSize !== void 0 ? { tickSize } : {},
+		...clobTokenId !== void 0 ? { clobTokenId } : {},
 		acceptingOrders: market.acceptingOrders === true,
 		closed: market.closed === true
 	};

package/lib/errors.d.ts

@@ -18,5 +18,15 @@ declare class PolymarketError extends Error {
  * 「失败路径不产生空数据假象」的第一道闸门。
  */
 declare function bodySnippet(text: string): string;
+/**
+ * 传输层失败（DNS/TLS/连接/超时）→ `TRADING_NETWORK`。
+ *
+ * 只在**请求没拿到响应**时调用；拿到响应但状态非 2xx 或体破损一律是
+ * `TRADING_UPSTREAM_ERROR`（由调用方构造，消息带状态码与响应片段）——这条分界是
+ * 「上游说不行」与「我们连不上」的区别，重试策略完全不同。
+ *
+ * 两个传输层（gamma / CLOB）共用这一处措辞，避免同一语义出现两种说法。
+ */
+declare function networkError(scope: string, cause: unknown): PolymarketError;
 //#endregion
-export { PolymarketError, bodySnippet };
+export { PolymarketError, bodySnippet, networkError };

package/lib/errors.js

@@ -25,5 +25,18 @@ function bodySnippet(text) {
 	const collapsed = text.replace(/\s+/g, " ").trim();
 	return collapsed.length > 200 ? `${collapsed.slice(0, 200)}…` : collapsed;
 }
+/**
+* 传输层失败（DNS/TLS/连接/超时）→ `TRADING_NETWORK`。
+*
+* 只在**请求没拿到响应**时调用；拿到响应但状态非 2xx 或体破损一律是
+* `TRADING_UPSTREAM_ERROR`（由调用方构造，消息带状态码与响应片段）——这条分界是
+* 「上游说不行」与「我们连不上」的区别，重试策略完全不同。
+*
+* 两个传输层（gamma / CLOB）共用这一处措辞，避免同一语义出现两种说法。
+*/
+function networkError(scope, cause) {
+	const reason = cause instanceof Error ? cause.message : String(cause);
+	return new PolymarketError("TRADING_NETWORK", `${scope}: ${cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError") ? "request timed out" : "network failure"} — ${reason}`, cause);
+}
 //#endregion
-export { PolymarketError, bodySnippet };
+export { PolymarketError, bodySnippet, networkError };

package/lib/events.d.ts

@@ -0,0 +1,97 @@
+//#region src/events.d.ts
+/** 一个档位（市场）的规范化读数。 */
+interface EventBucketQuote {
+  /** 稳定档位键（如 `no_change` / `dec_50plus`；未识别形态 = `raw:<原文>`）。 */
+  readonly key: string;
+  /** 展示标签原文（`groupItemTitle`，缺失时退到 `outcomes[0]`）。 */
+  readonly label: string;
+  /** 隐含概率 = `outcomePrices[0]`；解析不出则缺省（不猜）。 */
+  readonly probability?: number | undefined;
+}
+/** 检索结果里的一条事件（元数据 + 档位概率）。 */
+interface EventSummary {
+  readonly id: string;
+  readonly title: string;
+  readonly slug: string;
+  readonly closed: boolean;
+  /** 上游 event `endDate`（ISO 8601 UTC）；缺失则缺省。 */
+  readonly endDate?: string | undefined;
+  /** 累计成交额（上游 event `volume`，美元）。 */
+  readonly volume?: number | undefined;
+  /** 盘口深度（上游 event `liquidity`，美元）。 */
+  readonly liquidity?: number | undefined;
+  readonly buckets: readonly EventBucketQuote[];
+}
+/** 单市场详情里的一条档位/市场（保留上游原始报价维度）。 */
+interface EventMarketQuote {
+  readonly key: string;
+  readonly label: string;
+  /** 上游 `question`（市场问句原文）。 */
+  readonly question?: string | undefined;
+  /** 上游 `outcomes` 解析后的数组（如 `["Yes","No"]`）；解析不出则缺省。 */
+  readonly outcomes?: readonly string[] | undefined;
+  /** 上游 `outcomePrices` 解析后的数组（与 {@link outcomes} 同序）；解析不出则缺省。 */
+  readonly outcomePrices?: readonly number[] | undefined;
+  /** 最优买价（结算后上游为 null → 缺省）。 */
+  readonly bestBid?: number | undefined;
+  /** 最优卖价。 */
+  readonly bestAsk?: number | undefined;
+  /** 价差（上游 `spread`，缺省时由 bestAsk − bestBid 推得；两端缺失则缺省）。 */
+  readonly spread?: number | undefined;
+  /** 盘口深度（上游 `liquidityNum`，美元）。 */
+  readonly liquidity?: number | undefined;
+  /** 累计成交额（上游 `volumeNum`，美元）。 */
+  readonly volume?: number | undefined;
+  /** 该市场是否已结算（上游 market `closed`）。 */
+  readonly closed: boolean;
+  /** 是否仍可下单（上游 market `acceptingOrders`；**不用 `active` 判断**）。 */
+  readonly acceptingOrders: boolean;
+}
+/** 单个事件的详情。 */
+interface EventDetail {
+  readonly id: string;
+  readonly slug: string;
+  readonly title: string;
+  readonly closed: boolean;
+  readonly endDate?: string | undefined;
+  /** 上游 event `negRisk`（互斥档位集合标记）。 */
+  readonly negRisk: boolean;
+  readonly volume?: number | undefined;
+  readonly liquidity?: number | undefined;
+  readonly markets: readonly EventMarketQuote[];
+}
+/** 一页事件的关键词命中统计（`matched` 是**截断前**的命中数）。 */
+interface EventSearchPage {
+  readonly scanned: number;
+  readonly matched: number;
+  readonly events: readonly EventSummary[];
+}
+/** 单条上游事件 → 检索摘要；缺 id/title/slug 的事件不算一条（不编）。 */
+declare function parseEventSummary(event: unknown): EventSummary | undefined;
+/**
+ * 关键词命中：事件标题或 slug（大小写不敏感子串）。
+ *
+ * **不搜档位标签**（2026-10-15 实测决定的边界）：把档位标签算进命中面后，
+ * `fed` 会命中 `Ballon d'Or Winner 2026`——它的某个候选人是 `Federico ...`，
+ * 子串 `fed` 合法命中。检索工具的价值在精度，「命中了一个人名」对问「有没有
+ * 美联储相关盘口」的调用方是纯噪声。档位标签依然逐条回给调用方（`buckets`），
+ * 只是不参与匹配。
+ */
+declare function matchesKeyword(event: EventSummary, keyword: string): boolean;
+/**
+ * 对**一页**上游事件做本地关键词过滤（上游没有检索参数，见本模块头注）。
+ *
+ * 非数组体抛 TypeError 而不返回空结果：上游把「参数错」和「真的没有数据」都表现成
+ * 200（证据 Q5.2），这里只能在体形状上守边界。
+ */
+declare function searchEventsInPage(payload: unknown, keyword: string, limit: number): EventSearchPage;
+/**
+ * 单事件响应体 → 详情。
+ *
+ * `id=` / `slug=` 是精确匹配（实测最多一条），所以取首条可解析记录；
+ * 返回 undefined = 上游 200 但空集（**没有这个事件**，调用方抛 TRADING_SYMBOL_NOT_FOUND），
+ * 与「上游故障」是两件事，调用方不得把前者读成后者或反过来。
+ */
+declare function parseEventDetail(payload: unknown): EventDetail | undefined;
+//#endregion
+export { EventBucketQuote, EventDetail, EventMarketQuote, EventSearchPage, EventSummary, matchesKeyword, parseEventDetail, parseEventSummary, searchEventsInPage };

package/lib/events.js

@@ -0,0 +1,165 @@
+import { isRecord, num, parseNumberArray, parseTextArray, text } from "./json.js";
+import { canonicalBucket } from "./discovery.js";
+//#region src/events.ts
+/**
+* 事件读取面：关键词检索与单事件详情——两条都只走 `GET /events` **一次**。
+*
+* 上游约束（2026-10-15 实测，原始证据 spikes/impl-polymarket/agent-tools-ACCEPTANCE.md）：
+*
+* 1. **`/events` 没有关键词检索参数**：`q=fed` 与 `title=fed` 返回与无参数**逐条相同**
+*    的结果集（默认排序 = event id 升序，头几条是 2022 年的冷门体育盘），服务端过滤
+*    不存在。因此关键词检索 = 单次拉「开盘中、24h 成交额降序」的一页，再本地过滤；
+*    输出必须显式带 `filtering: 'local-page-filter'`，绝不冒充上游检索。
+* 2. **`order` 默认升序**：`order=volume24hr` 单用会返回成交额 0 的盘；
+*    `order=volume24hr&ascending=false` 才是「热门前 N」（实测把 Fed Decision 排到第 2）。
+* 3. **`id=<n>` 与 `slug=<精确 slug>` 精确匹配**：命中回长度 1 的数组，命中不到回
+*    `[]`（200）。「200 空数组」是唯一合法的「没有这个事件」形态，据此抛
+*    TRADING_SYMBOL_NOT_FOUND，不与上游故障混淆。
+*
+* 档位标签口径与 FOMC 面同源（discovery.ts 的 `canonicalBucket`）：`groupItemTitle`
+* 优先，缺失时退到 `outcomes[0]`（二元盘就是 `Yes`/`No`）——两者都不存在才丢弃该档，
+* 宁可少一档也不编一个概率出来。
+*/
+/** 档位标签：`groupItemTitle` 优先，缺失时退到首个 outcome。 */
+function bucketLabel(market) {
+	return text(market.groupItemTitle) ?? parseTextArray(market.outcomes)?.[0];
+}
+function parseBucketQuote(market) {
+	if (!isRecord(market)) return void 0;
+	const label = bucketLabel(market);
+	if (label === void 0) return void 0;
+	const probability = parseNumberArray(market.outcomePrices)?.[0];
+	return {
+		key: canonicalBucket(label).key,
+		label,
+		...probability !== void 0 ? { probability } : {}
+	};
+}
+function parseMarketQuote(market) {
+	if (!isRecord(market)) return void 0;
+	const label = bucketLabel(market);
+	if (label === void 0) return void 0;
+	const question = text(market.question);
+	const outcomes = parseTextArray(market.outcomes);
+	const outcomePrices = parseNumberArray(market.outcomePrices);
+	const bestBid = num(market.bestBid);
+	const bestAsk = num(market.bestAsk);
+	const spread = num(market.spread) ?? (bestBid !== void 0 && bestAsk !== void 0 ? Number((bestAsk - bestBid).toFixed(6)) : void 0);
+	const liquidity = num(market.liquidityNum);
+	const volume = num(market.volumeNum);
+	return {
+		key: canonicalBucket(label).key,
+		label,
+		...question !== void 0 ? { question } : {},
+		...outcomes !== void 0 ? { outcomes } : {},
+		...outcomePrices !== void 0 ? { outcomePrices } : {},
+		...bestBid !== void 0 ? { bestBid } : {},
+		...bestAsk !== void 0 ? { bestAsk } : {},
+		...spread !== void 0 ? { spread } : {},
+		...liquidity !== void 0 ? { liquidity } : {},
+		...volume !== void 0 ? { volume } : {},
+		closed: market.closed === true,
+		acceptingOrders: market.acceptingOrders === true
+	};
+}
+/** 单条上游事件 → 检索摘要；缺 id/title/slug 的事件不算一条（不编）。 */
+function parseEventSummary(event) {
+	if (!isRecord(event)) return void 0;
+	const id = text(String(event.id ?? ""));
+	const title = text(event.title);
+	const slug = text(event.slug);
+	if (id === void 0 || title === void 0 || slug === void 0) return void 0;
+	const endDate = text(event.endDate);
+	const volume = num(event.volume);
+	const liquidity = num(event.liquidity);
+	const buckets = [];
+	if (Array.isArray(event.markets)) for (const market of event.markets) {
+		const quote = parseBucketQuote(market);
+		if (quote !== void 0) buckets.push(quote);
+	}
+	return {
+		id,
+		title,
+		slug,
+		closed: event.closed === true,
+		...endDate !== void 0 ? { endDate } : {},
+		...volume !== void 0 ? { volume } : {},
+		...liquidity !== void 0 ? { liquidity } : {},
+		buckets
+	};
+}
+/**
+* 关键词命中：事件标题或 slug（大小写不敏感子串）。
+*
+* **不搜档位标签**（2026-10-15 实测决定的边界）：把档位标签算进命中面后，
+* `fed` 会命中 `Ballon d'Or Winner 2026`——它的某个候选人是 `Federico ...`，
+* 子串 `fed` 合法命中。检索工具的价值在精度，「命中了一个人名」对问「有没有
+* 美联储相关盘口」的调用方是纯噪声。档位标签依然逐条回给调用方（`buckets`），
+* 只是不参与匹配。
+*/
+function matchesKeyword(event, keyword) {
+	return `${event.title}\n${event.slug}`.toLowerCase().includes(keyword);
+}
+/**
+* 对**一页**上游事件做本地关键词过滤（上游没有检索参数，见本模块头注）。
+*
+* 非数组体抛 TypeError 而不返回空结果：上游把「参数错」和「真的没有数据」都表现成
+* 200（证据 Q5.2），这里只能在体形状上守边界。
+*/
+function searchEventsInPage(payload, keyword, limit) {
+	if (!Array.isArray(payload)) throw new TypeError("polymarket gamma /events: expected a JSON array of events");
+	const needle = keyword.toLowerCase();
+	const summaries = [];
+	for (const event of payload) {
+		const summary = parseEventSummary(event);
+		if (summary !== void 0) summaries.push(summary);
+	}
+	const matched = summaries.filter((event) => matchesKeyword(event, needle));
+	return {
+		scanned: summaries.length,
+		matched: matched.length,
+		events: matched.slice(0, limit)
+	};
+}
+function parseEventRecord(event) {
+	if (!isRecord(event)) return void 0;
+	const id = text(String(event.id ?? ""));
+	const title = text(event.title);
+	const slug = text(event.slug);
+	if (id === void 0 || title === void 0 || slug === void 0) return void 0;
+	const endDate = text(event.endDate);
+	const volume = num(event.volume);
+	const liquidity = num(event.liquidity);
+	const markets = [];
+	if (Array.isArray(event.markets)) for (const market of event.markets) {
+		const quote = parseMarketQuote(market);
+		if (quote !== void 0) markets.push(quote);
+	}
+	return {
+		id,
+		slug,
+		title,
+		closed: event.closed === true,
+		...endDate !== void 0 ? { endDate } : {},
+		negRisk: event.negRisk === true,
+		...volume !== void 0 ? { volume } : {},
+		...liquidity !== void 0 ? { liquidity } : {},
+		markets
+	};
+}
+/**
+* 单事件响应体 → 详情。
+*
+* `id=` / `slug=` 是精确匹配（实测最多一条），所以取首条可解析记录；
+* 返回 undefined = 上游 200 但空集（**没有这个事件**，调用方抛 TRADING_SYMBOL_NOT_FOUND），
+* 与「上游故障」是两件事，调用方不得把前者读成后者或反过来。
+*/
+function parseEventDetail(payload) {
+	if (!Array.isArray(payload)) throw new TypeError("polymarket gamma /events: expected a JSON array of events");
+	for (const event of payload) {
+		const detail = parseEventRecord(event);
+		if (detail !== void 0) return detail;
+	}
+}
+//#endregion
+export { matchesKeyword, parseEventDetail, parseEventSummary, searchEventsInPage };

package/lib/gamma.d.ts

@@ -18,12 +18,25 @@ interface GammaTransportOptions {
   /** UA 覆盖。 */
   readonly userAgent?: string;
 }
-/** 一次 GET 的结果：状态码 + 解析后的 JSON 体 + 原始文本（证据用）。 */
+/** 一次 GET 的结果：状态码 + 解析后的 JSON 体 + 原始文本 + 响应头（证据/新鲜度用）。 */
 interface GammaResponse {
   readonly status: number;
   readonly body: unknown;
   readonly text: string;
+  readonly headers: Headers;
 }
+/**
+ * 本次响应是否由 Cloudflare **共享缓存直接命中**（`cf-cache-status: HIT`）。
+ *
+ * 用途：工具面 `stale` 字段的**唯一判据**。`/events` 回
+ * `cache-control: public, max-age=300`，HIT 意味着拿到的是副本（实测 `age: 224`
+ * 的副本，见 spikes/impl-polymarket/agent-tools-ACCEPTANCE.md），最多可能比源站旧
+ * 5 分钟；MISS/DYNAMIC = 源站当次现算。
+ *
+ * 头缺失（本地夹具、非 Cloudflare 部署）返回 false——false 的语义是「没有观察到
+ * 共享缓存命中」，不是「已证明为源站实时值」，两者不可混为一谈（不猜）。
+ */
+declare function isCdnCached(response: GammaResponse): boolean;
 declare class GammaClient {
   private readonly timeoutMs;
   private readonly fetchImpl;
@@ -42,4 +55,4 @@ declare class GammaClient {
   get(path: string, query?: Readonly<Record<string, string>>): Promise<GammaResponse>;
 }
 //#endregion
-export { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, USER_AGENT };
+export { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, USER_AGENT, isCdnCached };