@v587d/capital-generation 2.8.2 → 2.9.0

package/lib/sources/security-code.d.ts

@@ -6,22 +6,16 @@ export interface SecurityCode {
     tencentSymbol: string;
     isIndex: boolean;
 }
-/**
- * Parse an A-share/ETF/index code without dropping exchange information.
- * Bare 000xxx codes are rejected because they are ambiguous (e.g. 000001).
- */
+/** Parse an A-share/ETF/index code; bare 000xxx is rejected as ambiguous (000001). */
 export declare function parseSecurityCode(value: unknown, name?: string): SecurityCode;
 /**
- * 检索面的代码口径：只回答"把这串写法归一成 6 位数字"。
- *
- * 与 `parseSecurityCode` 的分工是刻意的：数据面必须消歧（裸 `000001` 在指数与个股之间
- * 有歧义），而**具名来源自己会回答"这台机器上有没有这只票"**——cninfo 只覆盖深市、
- * sseinfo 只覆盖沪市，越界返回 0 条并带 note 是真事实，不能在这一层把它拒掉。
- * 所以裸 `000001`（平安银行）在这里合法，`SH600519` / `600519.SH` 也合法（东财研报库
- * 实测只认纯数字，带前缀返回 0 条，因此归一化属于工具职责而不是模型的记性）。
+ * Search-side code normalization: reduce a spelling to 6 digits.
+ * Unlike `parseSecurityCode`, bare `000001` is legal: named sources cover one exchange
+ * (cninfo SZ-only, sseinfo SH-only) and must be allowed to answer "no rows" themselves.
+ * Eastmoney research reports accept digits only; prefixed input returns 0 rows.
  */
 export declare function bareAshareDigits(value: unknown, name?: string): string;
-/** Normalize a list while preserving first-seen order and rejecting duplicates after normalization. */
+/** Dedupe after normalization, preserving first-seen order. */
 export declare function normalizeSecurityCodes(value: unknown, name?: string, maximum?: number): SecurityCode[];
 export declare function requireTencentSecurity(code: SecurityCode, name?: string): SecurityCode;
 export declare function isLikelyIndex(code: SecurityCode): boolean;

package/lib/sources/security-code.js

@@ -17,10 +17,7 @@ function explicitMarket(prefix, suffix) {
 function isMarket(value) {
     return value === 'SH' || value === 'SZ' || value === 'BJ';
 }
-/**
- * Parse an A-share/ETF/index code without dropping exchange information.
- * Bare 000xxx codes are rejected because they are ambiguous (e.g. 000001).
- */
+/** Parse an A-share/ETF/index code; bare 000xxx is rejected as ambiguous (000001). */
 export function parseSecurityCode(value, name = 'code') {
     if (typeof value !== 'string' || value.trim().length === 0)
         throw new Error(`parameter ${name} must be a security code`);
@@ -54,13 +51,10 @@ export function parseSecurityCode(value, name = 'code') {
     };
 }
 /**
- * 检索面的代码口径：只回答"把这串写法归一成 6 位数字"。
- *
- * 与 `parseSecurityCode` 的分工是刻意的：数据面必须消歧（裸 `000001` 在指数与个股之间
- * 有歧义），而**具名来源自己会回答"这台机器上有没有这只票"**——cninfo 只覆盖深市、
- * sseinfo 只覆盖沪市，越界返回 0 条并带 note 是真事实，不能在这一层把它拒掉。
- * 所以裸 `000001`（平安银行）在这里合法，`SH600519` / `600519.SH` 也合法（东财研报库
- * 实测只认纯数字，带前缀返回 0 条，因此归一化属于工具职责而不是模型的记性）。
+ * Search-side code normalization: reduce a spelling to 6 digits.
+ * Unlike `parseSecurityCode`, bare `000001` is legal: named sources cover one exchange
+ * (cninfo SZ-only, sseinfo SH-only) and must be allowed to answer "no rows" themselves.
+ * Eastmoney research reports accept digits only; prefixed input returns 0 rows.
  */
 export function bareAshareDigits(value, name = 'code') {
     if (typeof value !== 'string' || value.trim().length === 0) {
@@ -72,7 +66,7 @@ export function bareAshareDigits(value, name = 'code') {
     }
     return match[2] ?? match[3];
 }
-/** Normalize a list while preserving first-seen order and rejecting duplicates after normalization. */
+/** Dedupe after normalization, preserving first-seen order. */
 export function normalizeSecurityCodes(value, name = 'codes', maximum = 50) {
     const rawValues = Array.isArray(value)
         ? value

package/lib/sources/security-identity.d.ts

@@ -5,10 +5,7 @@ export interface EastmoneySecurityIdentity {
     eastmoney_code: string;
     eastmoney_market: EastmoneyMarket;
 }
-/**
- * Resolve Eastmoney's provider identifiers without guessing a market from digits.
- * `market` is mandatory for a bare SECURITY_CODE; `secid` carries its own market.
- */
+/** Never guess a market from digits: `market` is mandatory for bare SECURITY_CODE; secid carries its own. */
 export declare function normalizeEastmoneySecurityIdentity(input: {
     secucode?: unknown;
     security_code?: unknown;

package/lib/sources/security-identity.js

@@ -1,9 +1,7 @@
 import { parseSecurityCode } from './security-code.js';
 /**
- * secid 市场码（实测于 2026-09-24，`push2.eastmoney.com/api/qt/stock/get`）：
- * `1.` = 沪；`0.` = **深市与北交所共用**（`0.920982`、`0.430047` 返回 rc=0，`2.*` 一律 rc=100）。
- * 因此 `0.` 的 BJ/SZ 由数字前缀区分（4/8/92 为北交所），与 `normalizeEastmoneyAshareIdentity`
- * 共用 `marketFromAshareDigits` 的同一份规则（§9.7：一条知识一个实现）。
+ * Eastmoney secid market prefix: `1.` = SH; `0.` = SZ and BJ combined (`2.*` returns rc=100).
+ * For `0.` the BJ/SZ split comes from digit prefixes, sharing `marketFromAshareDigits`.
  */
 const SECID_MARKET_BY_PREFIX = { '1': 'SH', '0': 'SZ_OR_BJ' };
 function marketFromAshareDigits(digits) {
@@ -38,10 +36,7 @@ function code(value, name) {
         return raw;
     throw new Error(`${name} must be a six-digit code, SECUCODE, or market-prefixed code`);
 }
-/**
- * Resolve Eastmoney's provider identifiers without guessing a market from digits.
- * `market` is mandatory for a bare SECURITY_CODE; `secid` carries its own market.
- */
+/** Never guess a market from digits: `market` is mandatory for bare SECURITY_CODE; secid carries its own. */
 export function normalizeEastmoneySecurityIdentity(input) {
     const explicit = input.secucode ?? input.security_code;
     if (explicit !== undefined) {

package/lib/sources/tencent-http.js

@@ -1,8 +1,8 @@
 import { buildDataKey } from '../data-collector/hub.js';
 import { getDataTimeContract } from '../time/tools.js';
 import { isLikelyIndex, normalizeSecurityCodes, parseSecurityCode, requireTencentSecurity } from './security-code.js';
-// 港美股快照、smartbox 与那条**唯一的**出口节流链都在内核里；本文件只留能力定义与 K 线 / 分笔编排。
-// 为什么必须共用：两条独立节流等于没有限流，两份字段位序表迟早只会修好一份（AGENTS.md §9.7）。
+// Shared core holds HK/US snapshots, smartbox and the one throttle chain; this file only defines
+// capabilities and K-line/tick orchestration. Two throttles = no throttle.
 import { QUOTE_URL, fetchOffshoreIndexQuotes, fetchOffshoreQuotes, isRecord, normalizeHkCode, normalizeOffshoreIndexCode, normalizeUsCode, numberOrNull, requiredNumber, resolveUsKlineSymbol, sourceError, tencentGetText as getText, } from './tencent-public-core.js';
 const TICK_URL = 'https://stock.gtimg.cn/data/index.php';
 const KLINE_HOSTS = [
@@ -262,7 +262,8 @@ async function callKlineHosts(transport, signal) {
             hostDownUntil.set(host, Date.now() + HOST_COOLDOWN_MS);
         }
         catch (error) {
-            // 取消与参数性失败都原样抛出，**先于**一切拉黑/换机逻辑（docs/dev/web-retriever.md §4.2「取消原样抛出」）。
+            // Cancellation and param failures rethrow before blacklist/rotation; see
+            // `docs/dev/web-retriever.md` §4.2.
             if (error instanceof Error && error.name === 'AbortError')
                 throw error;
             if (error.code === 'tencent_invalid_param')
@@ -463,13 +464,6 @@ async function executeTicks(params, signal) {
         schema: ticksOutput,
     };
 }
-/**
- * 港美股快照与 A 股快照**不能共用一份字段表**：实测腾讯在同一个 `~` 分隔串里换了列位——
- * 币种 A 股根本没有、港股在第 75 位、美股在第 35 位；换手率港股在第 59 位（分母是**总股本**）、
- * 美股在第 38 位（分母是**流通股本**）；成交额在港股**指数行**是万元级而个股行是元级。
- * 所以两张表各自映射（都在 `tencent-public-core.ts`，host 半边与这里共用），
- * 并且只收能用算术或量级证明的列（§10.2：口径猜错就是话说错）。
- */
 function normalizeOffshoreCodes(params, name, perCode) {
     if (!isRecord(params))
         throw new Error('params must be an object');
@@ -487,12 +481,10 @@ function normalizeOffshoreCodes(params, name, perCode) {
     return { codes: symbols };
 }
 async function executeOffshoreQuote(params, signal, market) {
-    // 取数编排（含美股"没回行就剥一段后缀重问"）在内核里，与自选股面板共用一份。
     const rows = await fetchOffshoreQuotes(market, params.codes, signal);
     return { data: rows, schema: market === 'hk' ? hkQuoteOutput : usQuoteOutput };
 }
 async function executeOffshoreIndexQuote(params, signal, market) {
-    // 指数只收点位那一族可证明的列；写法来自检索，身份形状由内核核对（猜写法会静默拿到别的标的）。
     const rows = await fetchOffshoreIndexQuotes(market, params.codes, signal);
     return { data: rows, schema: market === 'hk' ? hkIndexQuoteOutput : usIndexQuoteOutput };
 }
@@ -500,7 +492,6 @@ const offshoreKlinePaths = {
     hk: { qfq: '/appstock/app/hkfqkline/get', hfq: '/appstock/app/hkfqkline/get', none: '/appstock/app/kline/kline' },
     us: { qfq: '/appstock/app/usfqkline/get', none: '/appstock/app/kline/kline' },
 };
-/** 港美股 K 线入口：主机轮换全部走 `callKlineHosts`（一份实现），这里只补"序列在哪个 symbol 的哪个键下"。 */
 async function callOffshoreKline(path, param, symbol, signal) {
     const data = await callKlineHosts({
         path,
@@ -520,14 +511,14 @@ async function callOffshoreKline(path, param, symbol, signal) {
         throw sourceError(`Tencent K-line ${symbol} response has no series array`, 'tencent_invalid_response');
     return node[key];
 }
-/** K 线行：`[日期, 开, 收, 高, 低, 量, …]`——与 A 股同一套位序，第 6 位是上游附带的回购/分红文本。 */
+/** Row: `[date, open, close, high, low, volume, …]`; field 6 is buyback/dividend text. */
 function parseOffshoreKlineRows(items, canonical, tencentSymbol, period, adjust, market) {
     const rows = [];
     for (const item of items) {
         if (!Array.isArray(item) || item.length < 6)
             throw sourceError(`Tencent ${market} K-line ${tencentSymbol} row shape changed`, 'tencent_invalid_response');
         const date = String(item[0]);
-        // 只匹配 `\d{4}-\d{2}-\d{2}` 会把 2026-13-99 这样的假日期放过去，所以要按真历法回读一次。
+        // Shape alone accepts 2026-13-99, so re-read through the real calendar.
         if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || (() => { const parsed = new Date(`${date}T00:00:00Z`); return Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== date; })()) {
             throw sourceError(`Tencent ${market} K-line ${tencentSymbol} has unreadable date ${JSON.stringify(date)}`, 'tencent_invalid_response');
         }
@@ -551,7 +542,7 @@ function parseOffshoreKlineRows(items, canonical, tencentSymbol, period, adjust,
             volume,
         };
         if (market === 'hk') {
-            // 港股复权序列多回两列（第 7/8 位）；实测不复权序列只有七列，这两处就是 null。
+            // Adjusted series has two extra columns; unadjusted has seven, so both are null.
             row.turnover_pct = item.length > 7 ? numberOrNull(item[7]) : null;
             row.amount_wan_hkd = item.length > 8 ? numberOrNull(item[8]) : null;
         }
@@ -564,7 +555,7 @@ function parseOffshoreKlineRows(items, canonical, tencentSymbol, period, adjust,
 function normalizeOffshoreKline(params, market) {
     if (!isRecord(params))
         throw new Error('params must be an object');
-    // start/end 进 allowed 只为了给出**可用**的拒绝理由：默默忽略日期是最坏的一种失败（调用方以为过滤过了）。
+    // start/end are accepted only to reject them.
     assertKnown(params, ['code', 'period', 'adjust', 'count', 'start', 'end']);
     if (params.start !== undefined || params.end !== undefined)
         throw new Error('start/end are not supported: 实测 hkfqkline 忽略日期区间（带 2024-01-01..2024-03-01 与 count=640 仍回 640 条、最早到 2021-07-30），只有 count 生效');
@@ -586,7 +577,7 @@ async function executeOffshoreKline(params, signal, market) {
     const period = String(params.period);
     const adjust = String(params.adjust);
     const count = Number(params.count);
-    // K 线的 symbol 身份：港股就是 hk+5 位；美股必须带交易所后缀，且后缀由快照回答。
+    // HK is hk + 5 digits; US suffix must be resolved by the snapshot.
     const tencentSymbol = market === 'hk' ? `hk${code}` : await resolveUsKlineSymbol(code, signal);
     const canonical = market === 'hk' ? code : tencentSymbol.slice(2);
     const path = offshoreKlinePaths[market][adjust];
@@ -654,12 +645,8 @@ const usQuoteOutput = {
     },
 };
 /**
- * 港美股**指数**快照的输出表：只有点位那一族，且**刻意不收**任何量纲列与币种列。
- *
- * 为什么不收（2026-10-07 真报文）：港股指数行的第 6 / 36 / 37 位两列相等且量级像万元，
- * 美股指数行的第 37 位给了 2.1e14、第 38 / 44 / 45 / 62 / 63 位为空——口径推不出来，
- * 声明一列我们没有把握的东西比少给一列更糟（docs/dev/tool-schema.md §10.2）。
- * 为什么不收币种：上游确实在第 75 / 35 位塞了 `HKD` / `USD`，但指数是无量纲的数。
+ * Index output: point values only. Magnitude columns are unreadable (hkHSI 6/36/37 duplicate at
+ * 10k; usIXIC 37 is 2.1e14, 38/44/45/62/63 empty). No currency.
  */
 const offshoreIndexQuoteProperties = (symbolLabel) => ({
     code: { type: 'string' },
@@ -684,16 +671,15 @@ const usIndexQuoteOutput = {
     type: 'array',
     items: { type: 'object', properties: offshoreIndexQuoteProperties('美东'), additionalProperties: true },
 };
-/** 港美股 K 线的公共列：`[日期, 开, 收, 高, 低, 量]`，量纲是**股**。 */
+/** Columns `[date, open, close, high, low, volume]`, volume in shares. */
 const offshoreKlineProperties = () => ({
     code: { type: 'string' }, tencent_symbol: { type: 'string' }, adjust: { type: 'string' },
     period: { type: 'string' }, date: { type: 'string' },
     open: { type: 'number' }, high: { type: 'number' }, low: { type: 'number' }, close: { type: 'number' },
     volume: { type: 'number', description: '成交量（股）；不是 A 股 K 线那套"手"' },
 });
-// 只有**港股复权序列**多回两列，而其中成交额是**万港元**（实测腾讯 2026-10-05 给 366,702.882，
-// 当日快照给 3,667,028,820.9 港元，差整整 1e4）。美股的两个可用入口（qfq / none）实测都只回六列，
-// 所以美股这张表**没有** amount 字段——不声明一列恒为 null 的东西，那只会让人以为是缺数。
+// HK adjusted series has two extra columns; its amount is in 10k HKD. US qfq/none return six
+// columns, so the US table declares no amount field.
 const hkKlineOutput = {
     type: 'array',
     items: {

package/lib/sources/tencent-public-core.d.ts

@@ -1,10 +1,5 @@
 export declare const QUOTE_URL = "https://qt.gtimg.cn/q=";
 export declare const SMARTBOX_URL = "https://smartbox.gtimg.cn/s3/";
-/**
- * 腾讯出口的**唯一**节流链（进程级）。行情快照、分笔、K 线每一次换机、港美股快照、smartbox
- * 检索全部过这一条链——它们打的是同一家，按 IP 风控（429 / 空 data / 静默限流）。
- * 间隔取 120ms：与最早那版分笔翻页的节奏同量级。
- */
 export declare const TENCENT_MIN_INTERVAL_MS = 120;
 export declare const tencentThrottle: <T>(task: () => Promise<T>) => Promise<T>;
 export type JsonRecord = Record<string, unknown>;
@@ -12,81 +7,35 @@ export declare function isRecord(value: unknown): value is JsonRecord;
 export declare function numberOrNull(value: unknown): number | null;
 export declare function requiredNumber(value: unknown, field: string): number;
 export declare function sourceError(message: string, code?: string): Error;
-/**
- * 腾讯出口的取文本：取消不排队（队首那个请求挂住时，把这次取消塞进队列等于把它吞掉，
- * `docs/dev/web-retriever.md` §4.2「取消原样抛出」），排队与最小间隔由节流链负责。
- */
+/** Cancellation does not queue; see `docs/dev/web-retriever.md` §4.2. */
 export declare function tencentGetText(url: string, signal: AbortSignal, encoding?: 'utf-8' | 'gbk', init?: RequestInit): Promise<string>;
-/**
- * 港美股快照与 A 股快照**不能共用一份字段表**：实测腾讯在同一个 `~` 分隔串里换了列位——
- * 币种 A 股根本没有、港股在第 75 位、美股在第 35 位；换手率港股在第 59 位（分母是**总股本**）、
- * 美股在第 38 位（分母是**流通股本**）；成交额在港股**指数行**是万元级而个股行是元级。
- * 所以这两张表各自映射，并且只收能用算术或量级证明的列（docs/dev/tool-schema.md §10.2：口径猜错就是话说错）。
- */
+/** Separate HK/US and A-share field tables: currency 75/35; turnover 59 (total shares) vs 38 (float). */
 export declare const HK_QUOTE_FIELDS = 78;
 export declare const US_QUOTE_FIELDS = 73;
-/**
- * 腾讯港美股时间戳是**交易所当地时间**。分隔符**按行漂移**：2026-10-05 那批同一份响应里，
- * 一行给 `YYYY/MM/DD HH:mm:ss`、另一行给 `YYYY-MM-DD HH:mm:ss`——所以两种都吃，输出统一成横杠那一种。
- * （写成占位符而不是真日期：这两个形状在源码里只差一个字符，肉眼读注释分不出来。）
- */
+/** Exchange-local time; separator drifts per row (`/` vs `-`), normalize to hyphen. */
 export declare function offshoreQuoteTime(value: unknown): string | null;
-/** 逐行拆出 `v_<symbol>="…"`；symbol 就是请求里写出去的那串，所以请求与回执能一对一核对。 */
 export declare function snapshotRows(text: string, requested: Set<string>): Array<{
     symbol: string;
     fields: string[];
 }>;
-/** 港美股代码：HK 是 5 位数字（实测 `hk700`/`hk0700` 被上游静默丢掉，必须左补零），指数别名一律拒收。 */
+/** HK codes are 5 digits; `hk700`/`hk0700` are silently dropped upstream, so left-pad. */
 export declare function normalizeHkCode(value: unknown, name: string): string;
-/**
- * 美股写法照原样收下（`AAPL` / `BRK.B` / `BABA.N` / `AAPL.OQ` 都是真实存在的说法），
- * 消歧交给上游（见 `usSymbolVariants`）：实测腾讯**快照只认不带后缀的写法**（`usBABA.N` 整行不回，
- * `usBABA` 认），而 K 线只认**带正确后缀**的写法（`usAAPL` 回一列 2011 年的陌生序列、
- * `usAAPL.NS` 静默 0 行）。点号既可能是级别码（BRK.B / BF.B）也可能是交易所后缀（.N / .OQ），
- * 从字面上分不出来——所以不猜。
- */
+/** Snapshot matches only bare US tickers (`usBABA.N` → no row); K-line needs the suffix (`usAAPL` → stale 2011 data). */
 export declare function normalizeUsCode(value: unknown, name: string): string;
-/** 依次尝试的写法：原样 → 每次剥掉最后一段点号，最多剥两段（BRK.B.N → BRK.B → BRK）。 */
 export declare function usSymbolVariants(ticker: string): string[];
 export declare function parseHkQuoteRows(text: string, requested: Set<string>): JsonRecord[];
 export declare function parseUsQuoteRows(text: string, requested: Set<string>): Array<{
     symbol: string;
     row: JsonRecord;
 }>;
-/**
- * **港美股指数快照**：只收点位那一族能证明的列。
- *
- * 为什么必须另开一张表（而不是复用个股那张）：实测指数行的量纲列不可读——
- * 港 `hkHSI` 的第 6 / 36 / 37 位两列相等且量级像万元，美 `usIXIC` 的第 37 位给了 2.1e14、
- * 第 38 / 44 / 45 / 62 / 63 位是空。把这些列收进输出表就等于承诺一个我们证明不了的口径。
- *
- * 也**不收币种**：上游确实在第 75 / 35 位塞了 `HKD` / `USD`，但点位是无量纲的数，
- * 替它标货币单位是替上游说话（`docs/design/watchlist-hk-us.md` §3.5）。
- *
- * 身份守卫是形状而非猜测：指数行第 2 位美股回 `.IXIC`（**前导点**）、港股回 `HSI`（**纯字母**）；
- * 个股行美股回 `AAPL.OQ`（点在中间）、港股回 `00700`（5 位数字）。2026-10-07 实测踩到过
- * `usSSPX` 回的是 `SSPX.AM`（一只 ETF）——所以猜写法拿指数必错，而这一层的形状核对是最后一道闸。
- */
+/** Indices: points only; magnitude columns unreadable. No currency. US code has a leading dot, HK is letters. */
 export declare function parseOffshoreIndexRows(text: string, requested: Set<string>, market: 'hk' | 'us'): JsonRecord[];
-/** 港美股指数代码：HK 是字母码（HSI / HSTECH / HSCEI），美是裸字母码（IXIC / DJI / INX，请求时不带那个前导点）。 */
 export declare function normalizeOffshoreIndexCode(value: unknown, name: string, market: 'hk' | 'us'): string;
-/**
- * 港美股快照的**唯一**取数编排（能力侧与自选股面板共用）。
- * 港股一次批量问完；美股先按原写法问一轮，**没回行**的那几只才用剥掉后缀的写法再问，
- * 所以正常路径（纯字母 ticker）一次请求都不多花。
- */
+/** HK one batch; US retries only no-row tickers with stripped suffixes. */
 export declare function fetchOffshoreQuotes(market: 'hk' | 'us', codes: string[], signal: AbortSignal): Promise<JsonRecord[]>;
-/** 港美股指数快照的取数编排：字母码没有"剥后缀重问"这一说，所以一轮问完。 */
 export declare function fetchOffshoreIndexQuotes(market: 'hk' | 'us', codes: string[], signal: AbortSignal): Promise<JsonRecord[]>;
-/** 美股 K 线入口需要的带后缀身份：先从快照拿上游自己的第 2 位（能力侧用，形状判据同一条）。 */
 export declare function resolveUsKlineSymbol(ticker: string, signal: AbortSignal): Promise<string>;
-/**
- * smartbox（腾讯公开检索）的一行候选。
- *
- * 回包形状是 `v_hint="市场~代码~名称~拼音~类型^…"`：ASCII 的 `\uXXXX` 转义（**不需要 GBK**）、
- * `^` 分行、`~` 分列，最多约 10 条。无命中与**非法 `t` 值**都回 `N` 这一个哨兵（实测
- * `t=hk,us` 这种列表形态也落进 `N`），所以解析器把它当零条、调用方把 `t` 钉成常量。
- */
+/** smartbox `v_hint="market~code~name~pinyin~type^…"` (~10); no hit or invalid `t` both return `N`. */
 export interface SmartboxCandidate {
     market: string;
     code: string;
@@ -95,6 +44,5 @@ export interface SmartboxCandidate {
     type: string;
 }
 export declare function parseSmartbox(text: string): SmartboxCandidate[];
-/** smartbox 检索：市场段只能是上游认的单值（`hk` / `us` / `all`），列表形态实测失效。 */
 export declare const SMARTBOX_MARKETS: string[];
 export declare function fetchSmartbox(query: string, market: string, signal: AbortSignal): Promise<SmartboxCandidate[]>;

package/lib/sources/tencent-public-core.js

@@ -1,22 +1,10 @@
 /**
- * 腾讯公开接口的最小内核：**零 import 的叶子模块**（只依赖 `net/throttle.js`，它自己也是叶子）。
- *
- * 为什么单独一份：host 平面的自选股（`watchlist/index.js`）与插件侧的行情能力
- * （`tencent-http.ts`）必须共用三样东西——同一条出口节流链、同一份港美股字段位序表、同一套守卫。
- * 两条独立节流等于没有限流（东财那次的教训），两份位序表迟早只会修好一份（AGENTS.md §9.7）。
- * 这一层一旦被别的模块拖进来，host 半边就会顺带加载整棵插件依赖树，所以这里不放能力定义、
- * 不放 Dataset 依赖、也不放任何类型依赖。
- *
- * 错误文案与判定形状逐字保持历史形态（Agent 与用户看到的字符串不能因抽取而漂移）。
+ * Tencent public endpoint kernel: leaf (only `net/throttle.js`). Shared by the host-plane watchlist
+ * and `tencent-http.ts` for one throttle chain and one HK/US field table. No other dependencies.
  */
 import { createRequestThrottle } from '../net/throttle.js';
 export const QUOTE_URL = 'https://qt.gtimg.cn/q=';
 export const SMARTBOX_URL = 'https://smartbox.gtimg.cn/s3/';
-/**
- * 腾讯出口的**唯一**节流链（进程级）。行情快照、分笔、K 线每一次换机、港美股快照、smartbox
- * 检索全部过这一条链——它们打的是同一家，按 IP 风控（429 / 空 data / 静默限流）。
- * 间隔取 120ms：与最早那版分笔翻页的节奏同量级。
- */
 export const TENCENT_MIN_INTERVAL_MS = 120;
 export const tencentThrottle = createRequestThrottle(TENCENT_MIN_INTERVAL_MS);
 export function isRecord(value) {
@@ -45,10 +33,7 @@ async function readResponse(response, encoding) {
     const bytes = await response.arrayBuffer();
     return new TextDecoder(encoding).decode(bytes);
 }
-/**
- * 腾讯出口的取文本：取消不排队（队首那个请求挂住时，把这次取消塞进队列等于把它吞掉，
- * `docs/dev/web-retriever.md` §4.2「取消原样抛出」），排队与最小间隔由节流链负责。
- */
+/** Cancellation does not queue; see `docs/dev/web-retriever.md` §4.2. */
 export async function tencentGetText(url, signal, encoding = 'utf-8', init = {}) {
     signal.throwIfAborted();
     return tencentThrottle(async () => {
@@ -63,24 +48,14 @@ export async function tencentGetText(url, signal, encoding = 'utf-8', init = {})
         return text;
     });
 }
-/**
- * 港美股快照与 A 股快照**不能共用一份字段表**：实测腾讯在同一个 `~` 分隔串里换了列位——
- * 币种 A 股根本没有、港股在第 75 位、美股在第 35 位；换手率港股在第 59 位（分母是**总股本**）、
- * 美股在第 38 位（分母是**流通股本**）；成交额在港股**指数行**是万元级而个股行是元级。
- * 所以这两张表各自映射，并且只收能用算术或量级证明的列（docs/dev/tool-schema.md §10.2：口径猜错就是话说错）。
- */
+/** Separate HK/US and A-share field tables: currency 75/35; turnover 59 (total shares) vs 38 (float). */
 export const HK_QUOTE_FIELDS = 78;
 export const US_QUOTE_FIELDS = 73;
-/**
- * 腾讯港美股时间戳是**交易所当地时间**。分隔符**按行漂移**：2026-10-05 那批同一份响应里，
- * 一行给 `YYYY/MM/DD HH:mm:ss`、另一行给 `YYYY-MM-DD HH:mm:ss`——所以两种都吃，输出统一成横杠那一种。
- * （写成占位符而不是真日期：这两个形状在源码里只差一个字符，肉眼读注释分不出来。）
- */
+/** Exchange-local time; separator drifts per row (`/` vs `-`), normalize to hyphen. */
 export function offshoreQuoteTime(value) {
     const match = /^(\d{4})[-/](\d{2})[-/](\d{2}) (\d{2}:\d{2}:\d{2})$/.exec(String(value ?? '').trim());
     return match ? `${match[1]}-${match[2]}-${match[3]} ${match[4]}` : null;
 }
-/** 逐行拆出 `v_<symbol>="…"`；symbol 就是请求里写出去的那串，所以请求与回执能一对一核对。 */
 export function snapshotRows(text, requested) {
     const rows = [];
     for (const line of text.split(';')) {
@@ -93,7 +68,7 @@ export function snapshotRows(text, requested) {
     }
     return rows;
 }
-/** 港美股代码：HK 是 5 位数字（实测 `hk700`/`hk0700` 被上游静默丢掉，必须左补零），指数别名一律拒收。 */
+/** HK codes are 5 digits; `hk700`/`hk0700` are silently dropped upstream, so left-pad. */
 export function normalizeHkCode(value, name) {
     const raw = String(value ?? '').trim().toUpperCase();
     const digits = /^(?:HK)?(\d{1,5})(?:\.HK)?$/.exec(raw)?.[1];
@@ -101,24 +76,14 @@ export function normalizeHkCode(value, name) {
         throw new Error(`parameter ${name} must be a five-digit Hong Kong stock code (for example 00700, hk00700 or 700); HK index codes such as HSI/HSTECH are not supported here`);
     return digits.padStart(5, '0');
 }
-/**
- * 美股写法照原样收下（`AAPL` / `BRK.B` / `BABA.N` / `AAPL.OQ` 都是真实存在的说法），
- * 消歧交给上游（见 `usSymbolVariants`）：实测腾讯**快照只认不带后缀的写法**（`usBABA.N` 整行不回，
- * `usBABA` 认），而 K 线只认**带正确后缀**的写法（`usAAPL` 回一列 2011 年的陌生序列、
- * `usAAPL.NS` 静默 0 行）。点号既可能是级别码（BRK.B / BF.B）也可能是交易所后缀（.N / .OQ），
- * 从字面上分不出来——所以不猜。
- */
+/** Snapshot matches only bare US tickers (`usBABA.N` → no row); K-line needs the suffix (`usAAPL` → stale 2011 data). */
 export function normalizeUsCode(value, name) {
     const raw = String(value ?? '').trim().toUpperCase();
     const match = /^(?:US)?([A-Z]{1,6}(?:\.[A-Z]{1,3}){0,2})$/.exec(raw);
     if (!match)
         throw new Error(`parameter ${name} must be a US equity ticker such as AAPL, BRK.B or BABA.N (a Tencent exchange suffix like .OQ is accepted and re-resolved from the snapshot)`);
-    // 两位以上的点号尾段（.OQ/.AM/.NS）在腾讯那里一定是交易所后缀，直接剥掉，于是 AAPL 与 AAPL.OQ
-    // 是同一只票、只请求一次。**单字母尾段**（BRK.B 的级别码 vs BABA.N 的交易所码）字面上分不开，
-    // 就照原样留着，交给上游逐个写法裁决——猜错一次只是多一轮请求，猜错第二次就是把数据挂错标的。
     return match[1].replace(/\.[A-Z]{2,3}$/u, '');
 }
-/** 依次尝试的写法：原样 → 每次剥掉最后一段点号，最多剥两段（BRK.B.N → BRK.B → BRK）。 */
 export function usSymbolVariants(ticker) {
     const variants = [`us${ticker}`];
     let current = ticker;
@@ -136,8 +101,6 @@ export function parseHkQuoteRows(text, requested) {
     for (const { symbol, fields } of snapshotRows(text, requested)) {
         if (fields.length < HK_QUOTE_FIELDS)
             throw sourceError(`Tencent HK quote ${symbol} returned ${fields.length} fields, expected at least ${HK_QUOTE_FIELDS}`, 'tencent_invalid_response');
-        // 只收个股：指数行的第 6/37 位在实测里既不是"股"也不是"港元"（hkHSI 两列相等、量级像万元），
-        // 两种量纲不许进同一列；参数层已经拒掉字母指数，这里再核对一次上游没把行串错。
         if (!/^\d{5}$/.test(fields[2] ?? ''))
             throw sourceError(`Tencent HK quote ${symbol} is not a five-digit stock code (got ${JSON.stringify(fields[2] ?? '')})`, 'tencent_invalid_response');
         const quoteTime = offshoreQuoteTime(fields[30]);
@@ -179,8 +142,6 @@ export function parseUsQuoteRows(text, requested) {
     for (const { symbol, fields } of snapshotRows(text, requested)) {
         if (fields.length < US_QUOTE_FIELDS)
             throw sourceError(`Tencent US quote ${symbol} returned ${fields.length} fields, expected at least ${US_QUOTE_FIELDS}`, 'tencent_invalid_response');
-        // 上游在 2 号位回交易所后缀（AAPL.OQ / BABA.N），这是 K 线入口要用的身份，缺了就无法核对。
-        // 交易所后缀实测有**一个字母**的（NYSE：BABA.N / BRK.B.N），把下限写成 2 会把真代码判成畸形。
         if (!/^[A-Z][A-Z.]{0,9}\.[A-Z]{1,3}$/.test(fields[2] ?? ''))
             throw sourceError(`Tencent US quote ${symbol} has an unexpected code ${JSON.stringify(fields[2] ?? '')}`, 'tencent_invalid_response');
         const quoteTime = offshoreQuoteTime(fields[30]);
@@ -215,25 +176,11 @@ export function parseUsQuoteRows(text, requested) {
         const stale = row.amount_usd === 0 && row.price !== null && row.price === row.last_close;
         row.is_stale = stale;
         row.stale_reason = stale ? 'zero turnover and price equals previous close' : null;
-        // symbol 是"哪个写法换来了这一行"，只给上面的重试判定用，不出现在行里。
         rows.push({ symbol, row });
     }
     return rows;
 }
-/**
- * **港美股指数快照**：只收点位那一族能证明的列。
- *
- * 为什么必须另开一张表（而不是复用个股那张）：实测指数行的量纲列不可读——
- * 港 `hkHSI` 的第 6 / 36 / 37 位两列相等且量级像万元，美 `usIXIC` 的第 37 位给了 2.1e14、
- * 第 38 / 44 / 45 / 62 / 63 位是空。把这些列收进输出表就等于承诺一个我们证明不了的口径。
- *
- * 也**不收币种**：上游确实在第 75 / 35 位塞了 `HKD` / `USD`，但点位是无量纲的数，
- * 替它标货币单位是替上游说话（`docs/design/watchlist-hk-us.md` §3.5）。
- *
- * 身份守卫是形状而非猜测：指数行第 2 位美股回 `.IXIC`（**前导点**）、港股回 `HSI`（**纯字母**）；
- * 个股行美股回 `AAPL.OQ`（点在中间）、港股回 `00700`（5 位数字）。2026-10-07 实测踩到过
- * `usSSPX` 回的是 `SSPX.AM`（一只 ETF）——所以猜写法拿指数必错，而这一层的形状核对是最后一道闸。
- */
+/** Indices: points only; magnitude columns unreadable. No currency. US code has a leading dot, HK is letters. */
 export function parseOffshoreIndexRows(text, requested, market) {
     const fieldFloor = market === 'hk' ? HK_QUOTE_FIELDS : US_QUOTE_FIELDS;
     const codeOf = (code) => (market === 'hk' ? code : code.replace(/^./u, ''));
@@ -242,7 +189,6 @@ export function parseOffshoreIndexRows(text, requested, market) {
         if (fields.length < fieldFloor)
             throw sourceError(`Tencent ${market} index quote ${symbol} returned ${fields.length} fields, expected at least ${fieldFloor}`, 'tencent_invalid_response');
         const raw = String(fields[2] ?? '');
-        // 港：字母指数码；美：`.字母`。两种都明确排除个股形状（数字 / 点在中间的后缀形式）。
         const shapeOk = market === 'hk' ? /^[A-Z][A-Z0-9.]{1,9}$/u.test(raw) : /^\.[A-Z][A-Z0-9.]{1,9}$/u.test(raw);
         if (!shapeOk)
             throw sourceError(`Tencent ${market} index quote ${symbol} is not an index code (got ${JSON.stringify(raw)})`, 'tencent_invalid_response');
@@ -268,7 +214,6 @@ export function parseOffshoreIndexRows(text, requested, market) {
     }
     return rows;
 }
-/** 港美股指数代码：HK 是字母码（HSI / HSTECH / HSCEI），美是裸字母码（IXIC / DJI / INX，请求时不带那个前导点）。 */
 export function normalizeOffshoreIndexCode(value, name, market) {
     const raw = String(value ?? '').trim().toUpperCase().replace(/^(?:HK|US)/u, '');
     const stem = raw.replace(/^\./u, '').replace(/\.(?:HK|US)$/u, '');
@@ -280,11 +225,7 @@ export function normalizeOffshoreIndexCode(value, name, market) {
     }
     return stem;
 }
-/**
- * 港美股快照的**唯一**取数编排（能力侧与自选股面板共用）。
- * 港股一次批量问完；美股先按原写法问一轮，**没回行**的那几只才用剥掉后缀的写法再问，
- * 所以正常路径（纯字母 ticker）一次请求都不多花。
- */
+/** HK one batch; US retries only no-row tickers with stripped suffixes. */
 export async function fetchOffshoreQuotes(market, codes, signal) {
     if (market === 'hk') {
         const symbols = codes.map((code) => `hk${code}`);
@@ -303,8 +244,7 @@ export async function fetchOffshoreQuotes(market, codes, signal) {
             tried.add(symbol.toLowerCase());
         const text = await tencentGetText(`${QUOTE_URL}${symbols.join(',')}`, signal, 'gbk');
         const found = parseUsQuoteRows(text, new Set(symbols.map((symbol) => symbol.toLowerCase())));
-        // 上游把变量名原样回显（实测送 `usBRK.B` 回 `v_usBRK.B`），但"这一只没回行"的判断不该押在大小写上：
-        // 比不中就会对一只已经拿到数的票再问一轮剥短写法，白烧一次出网。
+        // Match case-insensitively; a miss would requery an already-resolved ticker.
         const hit = new Set(found.map((item) => item.symbol.toLowerCase()));
         rows.push(...found.map((item) => item.row));
         for (let index = 0; index < symbols.length; index += 1) {
@@ -312,7 +252,7 @@ export async function fetchOffshoreQuotes(market, codes, signal) {
                 pending[index] = [];
                 continue;
             }
-            // 快照没认这个写法：剥一段点号再看；剥无可剥就只能认定腾讯不认识这只（不编造身份）。
+            // Strip one dot-segment and retry; when nothing is left, upstream does not know the ticker.
             const next = pending[index].find((variant) => !tried.has(variant.toLowerCase()));
             if (next !== undefined)
                 pending[index] = [next, ...pending[index].filter((variant) => variant !== next)];
@@ -322,7 +262,6 @@ export async function fetchOffshoreQuotes(market, codes, signal) {
         throw sourceError(`Tencent returned no US quote rows for ${codes.join(',')}`, 'tencent_empty_response');
     return rows;
 }
-/** 港美股指数快照的取数编排：字母码没有"剥后缀重问"这一说，所以一轮问完。 */
 export async function fetchOffshoreIndexQuotes(market, codes, signal) {
     const symbols = codes.map((code) => `${market}${code}`);
     const text = await tencentGetText(`${QUOTE_URL}${symbols.join(',')}`, signal, 'gbk');
@@ -331,7 +270,6 @@ export async function fetchOffshoreIndexQuotes(market, codes, signal) {
         throw sourceError(`Tencent returned no ${market} index quote rows for ${symbols.join(',')}`, 'tencent_empty_response');
     return rows;
 }
-/** 美股 K 线入口需要的带后缀身份：先从快照拿上游自己的第 2 位（能力侧用，形状判据同一条）。 */
 export async function resolveUsKlineSymbol(ticker, signal) {
     for (const symbol of usSymbolVariants(ticker)) {
         const text = await tencentGetText(`${QUOTE_URL}${symbol}`, signal, 'gbk');
@@ -362,7 +300,6 @@ export function parseSmartbox(text) {
     }
     return candidates;
 }
-/** 回包里的名称是 `\uXXXX` 字面转义（实测），解一次转义；解不动就原样返回，不编造名称。 */
 function unescapeHint(value) {
     if (!value.includes('\\u'))
         return value;
@@ -373,14 +310,12 @@ function unescapeHint(value) {
         return value;
     }
 }
-/** smartbox 检索：市场段只能是上游认的单值（`hk` / `us` / `all`），列表形态实测失效。 */
 export const SMARTBOX_MARKETS = ['all', 'hk', 'us'];
 export async function fetchSmartbox(query, market, signal) {
     if (!SMARTBOX_MARKETS.includes(market))
         throw new Error(`smartbox market must be one of ${SMARTBOX_MARKETS.join('/')}; got ${JSON.stringify(market)}（列表形态实测回 N 哨兵，等于查无此票）`);
     const url = `${SMARTBOX_URL}?v=2&t=${encodeURIComponent(market)}&q=${encodeURIComponent(query)}`;
-    // 名称是 `\uXXXX` 字面转义、正文全 ASCII，所以走 utf-8；'ascii' 这个标签在 Encoding Standard 里
-    // 映射的是 windows-1252，不是 US-ASCII，拿来解 ASCII 正文是个埋着的坑。
+    // ASCII `\uXXXX` body: use utf-8; the 'ascii' label maps to windows-1252.
     const text = await tencentGetText(url, signal);
     return parseSmartbox(text);
 }

package/lib/sources/wind-mcp.d.ts

@@ -1,8 +1,3 @@
 import type { DataSource } from '../data-collector/hub.js';
 export type WindApiKeyResolver = () => Promise<string | undefined>;
-/**
- * §6.7 改口后的 P1 三条。`wind_edb_*` 是 P0（EDB 是唯一来源），`wind_stock_kline` 是 P1。
- * 不接的一概有理由：price_indicators 与全部 NL 工具（中文键 / 列名是 question 的函数）、
- * bond 与 fund/index（重叠或未测）、analytics_data（实测连 initialize 都挂）。
- */
 export declare function createWindSources(resolveApiKey: WindApiKeyResolver): DataSource[];