@dshtrading/api 0.6.1 → 0.6.2

package/lib/index.d.ts

@@ -1,11 +1,21 @@
-import { CRON_MAX, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, ExecutionRecord, NewTaskInput, PIN_MAX, PROMPT_MAX, ScheduleRule, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, TaskPermission, TaskRecord, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, hasOpenExecution, isTaskPermission, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions } from "./tasks-protocol.js";
+import { CRON_MAX, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, ExecutionRecord, NewTaskInput, PIN_MAX, PROMPT_MAX, ScheduleRule, ScheduleSkipRecord, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, TaskPermission, TaskRecord, TaskSkipReason, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, countOpenExecutions, hasOpenExecution, isTaskPermission, isTaskSkipReason, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions } from "./tasks-protocol.js";
 import { CronSchedule, isValidCron, nextRunAtMs, parseCron } from "./tasks-schedule.js";
 import { SWAP_SYMBOL_SUFFIX, instrumentFormOf } from "./instrument-form.js";
 import { Context as CordisContext } from "@deepseek-ai/cordis";
 //#region src/index.d.ts
 /** K线周期（Binance 现货/合约 interval 词汇）。 */
 type Interval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
-/** 最新行情快照（公共数据，无需凭证）。 */
+/**
+ * 最新行情快照（公共数据，无需凭证）。
+ *
+ * **降级派生（2026-10-14）**：数据源的首选取价路径不可用时，连接器可用**同源序列**派生快照
+ * （connector-eastmoney 即用当日分钟序列的末根收盘价 + 该序列自带的昨收与名称；2026-10-14
+ * 实测其派生价与同刻腾讯报价逐位一致）。此时 `price` 是「最近一根分钟 bar 的收盘」而非逐笔
+ * 最新价，滞后以该源的降级策略为界。派生值必须自洽——涨跌幅由同一对 `price`/`prevClose` 推出，
+ * 名称与昨收取自同一响应；**拿不到的量宁可缺省**（`volume` 本就可选），不得用窗口合计之类的
+ * 近似值冒充当日累计。降级不得掩盖「该标的确实不存在」：`TRADING_SYMBOL_NOT_FOUND` /
+ * `TRADING_UNSUPPORTED_SYMBOL` 照实上报，消费方无需区分快照来自直取还是派生。
+ */
 interface Ticker {
   /** 交易对符号，**市场规范词汇**（docs/symbol-vocabulary.md：crypto=BTCUSDT，us=AAPL，cn=600519.SH，hk=00700.HK）。 */
   readonly symbol: string;
@@ -466,6 +476,23 @@ interface OrderRequest {
   readonly marginMode?: MarginMode;
   /** 缺省/true 时仅模拟，不触碰交易所。实盘还受 @dshtrading/authority 的人工签署授权与 approval 约束 [S4]。 */
   readonly dryRun?: boolean;
+  /**
+   * Stable caller-assigned idempotency id for this order intent.
+   *
+   * Required for live submissions (`dryRun: false`); a dry-run receipt may omit it.
+   * Reusing the id with the same normalized request (same venue payload, provider,
+   * environment and account) returns the recorded venue receipt instead of
+   * submitting a second order; reusing it with a different payload, provider,
+   * environment or account is rejected as a conflict and the request is never
+   * silently re-parameterised. Only a venue receipt carrying a real non-empty
+   * order id is recorded as confirmed — a timeout, storage failure or crash leaves
+   * the intent unresolved and nothing is resubmitted automatically.
+   *
+   * The venue-facing client order key (`clOrdId` / `client_order_id` / `cOID` /
+   * `remark` / `user_mark`) is derived from this id inside the connector and is
+   * never surfaced: this id is the only handle callers pass in and read back.
+   */
+  readonly intentId?: string;
 }
 /** 订单回执/状态。 */
 interface Order {
@@ -549,6 +576,77 @@ interface InstrumentRef {
   readonly assetClass?: InstrumentAssetClass;
   readonly contract?: InstrumentContract;
 }
+/** 港股通单日持股快照（东财 RPT_MUTUAL_STOCK_HOLDRANKS 口径）。 */
+interface SouthboundHoldingPoint {
+  /** 交易日（UTC 当日 00:00 的 epoch ms；与日 K 的 openTime 同口径便于对齐）。 */
+  readonly date: number;
+  /** 持股比例（百分比数值，如 11.9 表示 11.9%）。来源字段 HOLD_SHARES_RATIO（占港股已发行股本）。 */
+  readonly holdRatio: number;
+  /** 持股数量（股）。 */
+  readonly holdShares: number;
+  /** 持股市值（HKD）。 */
+  readonly holdMarketCap: number;
+}
+/** 港股通持股历史（按交易日升序，旧→新，已按日去重）。 */
+interface SouthboundHoldingHistory {
+  /** 市场规范词汇 symbol（如 00700.HK）。 */
+  readonly symbol: string;
+  /** 序列升序；同一交易日至多一条。标的不在港股通范围时为空数组（不是抛错）。 */
+  readonly points: readonly SouthboundHoldingPoint[];
+}
+/**
+ * 当日累计主动买盘快照（cn 行情行盘口推断口径，2026-10-13）。
+ *
+ * **口径**：`outerLots`/`innerLots` 是行情源按「成交价对盘口的主动方向」推断的当日累计
+ * 外盘/内盘（外盘 = 主动买、内盘 = 主动卖），**不是交易所官方逐笔方向**；涨跌停一字板与
+ * 对倒（自成交）交易日读数会系统性失真。占比一律按「÷当日总量」口径。
+ * `totalLots` 与 `outerLots + innerLots` 存在残差（未归向成交：集合竞价与价间成交计入总量
+ * 但不计入外/内盘），实测 2026-10-13 为 002714 12/121808 手（0.0099%）、600519
+ * 45/7154 手（0.629%）——残差**不是**固定量级，且**不据它修正读数**，源读数原样返回。
+ */
+interface ActiveBuySnapshot {
+  /** 市场规范词汇 symbol（如 002714.SZ）。 */
+  readonly symbol: string;
+  /** 快照所属交易日 `YYYY-MM-DD`（源字段 30，交易所本地墙钟）。 */
+  readonly date: string;
+  /** 快照时刻 `HH:MM:SS`（源字段 30，交易所本地墙钟）。 */
+  readonly time: string;
+  /** 当日累计总量（手）。 */
+  readonly totalLots: number;
+  /** 当日累计外盘 = 主动买（手）。 */
+  readonly outerLots: number;
+  /** 当日累计内盘 = 主动卖（手）。 */
+  readonly innerLots: number;
+  /** 主动买占比 `outer/total*100`（2 位小数）。 */
+  readonly buySharePct: number;
+  /** 净主动买占比 `(outer-inner)/total*100`（2 位小数，负值 = 净主动卖）。 */
+  readonly netSharePct: number;
+  /** 涨停价（源字段 47；指数/ETF 等无涨跌停的标的不带此字段）。 */
+  readonly limitUp?: number;
+  /** 跌停价（源字段 48；同上缺省）。 */
+  readonly limitDown?: number;
+  /** 数据源标识（如 'qt.gtimg.cn'）。 */
+  readonly source: string;
+  /** 取数时刻，ISO 8601 带偏移（交易所本地墙钟，如 2026-10-13T09:53:12+08:00）。 */
+  readonly fetchedAt: string;
+}
+/**
+ * 连接器自我申报的 K 线能力（2026-10-15 跨源 K 线路由）：对自己**能诚实服务**的
+ * (周期, 请求深度) 的声明。深度必须来自本连接器自己的实证，不借别家的数字。
+ *
+ * `maxBars` 是该周期能承接的 `limit` 上限，**不是返回根数保证**：
+ *   - `limit <= maxBars`：请求在本源自己的语义下已被诚实服务——返回根数以本源自己的
+ *     取数窗口/上游上限为界（如窗口型源的 5 个交易日），但不得因为请求更大而静默降级
+ *     到更小的窗口或更浅的历史；
+ *   - `limit > maxBars`：本源结构性不足——上游会静默截到更少根数、忽略该参数，
+ *     或根本没有该周期的通道。
+ *
+ * 方法缺席 = **未声明**，不是「不支持」：消费方照旧可直接调用，错误码才是判据。
+ */
+interface KlineCapability {
+  readonly interval: Interval;
+  readonly maxBars: number;
+}
 /**
  * 行情服务契约：由市场连接器实现，注册到按市场命名空间的 ctx 键（如 ctx.tradingCrypto）。
  * 符号词汇（2026-08-31 规范，docs/guides/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
@@ -557,7 +655,29 @@ interface InstrumentRef {
 interface MarketDataService {
   getTicker(symbol: string): Promise<Ticker>;
   getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  /**
+   * K 线能力声明（可选，2026-10-15 跨源 K 线路由；语义见 KlineCapability）：本源能诚实
+   * 服务的 (周期, 请求深度) 清单。桥据它做跨源解析——active 覆盖请求就用 active，只有
+   * active 结构性不足时才换同市场其它已注册源——并把同市场全部注册项的并集上报客户端。
+   * 可选方法：未声明的连接器缺席，桥退回「按 TRADING_UNSUPPORTED_INTERVAL 错误码兜底」
+   * 路径（行为与不声明前一致）。
+   */
+  klineCapabilities?(): readonly KlineCapability[];
   subscribeTicker(symbol: string, cb: (ticker: Ticker) => void): Disposable;
+  /**
+   * 批量最新报价（GUI 自选/盘中列表每拍取价用，2026-10-14）：一次请求取多只标的，
+   * 免掉「N 只标的 N 次请求」。键**必须是入参里的原字符串**（调用方按它一一对应），
+   * 值为该标的的行情快照（`Ticker.symbol` 仍是市场规范形）。
+   *
+   * 语义约定（调用方与实现共同遵守）：
+   *   - 只返回**确实拿到**的标的：未收录/无法解析的符号不出现在结果里，由调用方回落
+   *     到 `getTicker` 单取（保住各符号自己的错误码），故实现**不得**为凑齐入参造假行；
+   *   - 整批取数失败（网络/上游故障）**应抛出**，调用方按整批失败上报，不做 N 次重试；
+   *   - 单次请求的标的数由调用方裁剪（桥侧 MAX_SYMBOLS），实现无需自行分片。
+   *
+   * 可选方法：数据源无原生批量端点的市场不实现，调用方自动回落逐只 `getTicker`。
+   */
+  getTickers?(symbols: string[]): Promise<Record<string, Ticker>>;
   /**
    * 查询本市场/交易所支持的全部标的名册（动态全集，Issue #15）。
    * 输出 `symbol` 一律市场规范词汇（docs/guides/symbol-vocabulary.md），形态由符号后缀承载
@@ -599,6 +719,24 @@ interface MarketDataService {
    * 可选方法：无公共逐笔端点的数据源（腾讯沪深行情行）不实现。
    */
   getRecentTrades?(symbol: string, limit?: number): Promise<TradeTick[]>;
+  /**
+   * 港股通持股历史（GUI「港股通持股比例」副图用，2026-10-13）：日频序列，
+   * 升序、按交易日去重。可选方法：无该数据端点的数据源不实现（当前仅
+   * connector-eastmoney 的 hk 实例实现）；标的不在港股通范围时返回空 points
+   * （**空 ≠ 0**，消费方隐藏副图而非画零线），上游失败则抛错。
+   * 入参接受规范形与连接器原生形，输出 `symbol` 一律市场规范词汇。
+   */
+  getSouthboundHoldings?(symbol: string): Promise<SouthboundHoldingHistory>;
+  /**
+   * 当日累计主动买盘快照（外盘/内盘/买占比/净买占比，cn 专用，2026-10-13）。
+   * 可选方法：仅 cn 数据源实现（腾讯行情行的盘口推断口径，**非交易所官方逐笔方向**）；
+   * 涨跌停一字板与对倒交易日读数失真。hk 等无该字段的市场**方法缺席**——消费方据此
+   * 降级（隐藏该面板），**不回退成 0**：缺席表示「无此读数」，不是「主动买为 0」。
+   * 读数非法（总量 <= 0、外盘/内盘字段缺失或非有限）时抛 TRADING_EXCHANGE_ERROR，
+   * 绝不补 0、绝不返回 NaN。
+   * 入参接受规范形与连接器原生形，输出 `symbol` 一律市场规范词汇。
+   */
+  getActiveBuySnapshot?(symbol: string): Promise<ActiveBuySnapshot>;
 }
 /**
  * 杠杆设置请求（合约交易语义，P7；仅 `form=perp` 的标的可传）。
@@ -681,6 +819,15 @@ type TradingErrorCode =
 'TRADING_NO_TRADE_SERVICE' |
 /** 该市场注册了交易连接器，但路由选中的数据 provider 没有交易面（需设 tradeProvider；≠ 未安装）。 */
 'TRADING_TRADE_PROVIDER_NOT_ROUTED' | 'TRADING_UNSUPPORTED_SYMBOL' | 'TRADING_UNSUPPORTED_INTERVAL' |
+/**
+ * 请求到达了上游、上游答了，但没有这个标的（HTTP 404、400 + `label` 以 `INVALID_` 开头，
+ * 或 200 但没有任何可用行）——与 `TRADING_UNSUPPORTED_SYMBOL`（本地就判定这个形态不支持、
+ * 零请求）区分：这里是「上游说查不到」，消费方不该当基础设施抖动去重试。
+ * 8 个连接器已按此语义实际使用该码（akshare / eastmoney / finnhub / fmp / longbridge /
+ * polygon / tushare / ccxt 的行级判空与 404 映射），此前只是漏进了本词汇表（类型层缺口，
+ * 与 `TRADING_UPSTREAM_ERROR` 曾经的缺口同形）。
+ */
+'TRADING_SYMBOL_NOT_FOUND' |
 /** 凭证缺失或无效（ctx.credentials 引用解析失败 [S4]）。 */
 'TRADING_CREDENTIALS_MISSING' | 'TRADING_AUTH_FAILED' | 'TRADING_RATE_LIMITED' | 'TRADING_NETWORK' |
 /**
@@ -701,7 +848,18 @@ type TradingErrorCode =
 /** approval 被拒/无应答（headless fail-closed [S4]）。 */
 'TRADING_APPROVAL_DENIED' |
 /** 本次为 dry-run 模拟结果（非故障语义）。 */
-'TRADING_DRY_RUN' | 'TRADING_EXCHANGE_ERROR' | 'TRADING_UNKNOWN';
+'TRADING_DRY_RUN' |
+/** Order intents（实盘幂等台账）：实盘请求缺稳定 `intentId`（dry-run 可缺省）。 */
+'TRADING_INTENT_REQUIRED' |
+/** Order intents：同一 `intentId` 已被不同规范载荷/provider/环境/账户占用——拒绝，不自动改参数。 */
+'TRADING_INTENT_CONFLICT' |
+/**
+ * Order intents：该 `intentId` 已有持久记录（已提交或结局未知）而**尚无** venue 回执。
+ * 明确告知「未知/在飞」，绝不自动重发；推进只能靠人工或读对账。
+ */
+'TRADING_INTENT_UNKNOWN' |
+/** Order intents：台账写盘失败——本次不调用 venue（宁可不发，也不发一笔没有持久记录的实盘单）。 */
+'TRADING_INTENT_STORE_FAILED' | 'TRADING_EXCHANGE_ERROR' | 'TRADING_UNKNOWN';
 /** 结构化错误载体（实现方在 Error 上附加该形状，或直接以 code 抛出）。 */
 interface TradingError {
   readonly code: TradingErrorCode;
@@ -762,6 +920,8 @@ declare module '@deepseek-ai/cordis' {
     tradingFlashFeed: FlashFeedService;
     /** 宏观/利率源（@dshtrading/connector-jin10 提供；缺席 = 未安装金十连接器）。 */
     tradingMacroFeed: MacroFeedService;
+    /** 预测市场源（@dshtrading/connector-polymarket 提供；缺席 = 未安装预测市场连接器）。 */
+    tradingPredictionFeed: PredictionFeedService;
   }
 }
 /**
@@ -932,6 +1092,93 @@ interface MacroFeedService {
   /** 央行最新利率（全量，客户端按地区过滤）。 */
   listRates(): Promise<readonly MacroRateEntry[]>;
 }
+/**
+ * 预测市场档位条目（2026-10-11 Polymarket 接入）。
+ *
+ * 标签与概率均来自上游 `groupItemTitle` / `outcomePrices[0]`；`key` 是归一化后的
+ * 稳定档位标识（上游标签在大小写与 `+` 上会漂移——实测 `No change` / `No Change`、
+ * `50+ bps decrease` / `50 bps decrease` 并存，按原文匹配会随会议换 slug 静默失效）。
+ */
+interface PredictionOutcomeBucket {
+  /** 稳定档位键（如 `no_change` / `inc_25` / `dec_50plus`；未识别形态 = `raw:<原文>`）。 */
+  readonly key: string;
+  /** 上游档位标签原文（展示用，不做改写）。 */
+  readonly label: string;
+  /** 对应利率变动（bps；降息为负）。未识别形态 = undefined（不猜）。 */
+  readonly changeBps?: number | undefined;
+  /** 隐含概率 = 上游 `outcomePrices[0]`（gamma 与 CLOB midpoint 实测 15/15 完全相等）。 */
+  readonly probability: number;
+  /** 最优买价（结算后上游为 null → 缺省）。 */
+  readonly bestBid?: number | undefined;
+  /** 最优卖价。 */
+  readonly bestAsk?: number | undefined;
+  /** 价差（bestAsk − bestBid；任一端缺失则缺省）。 */
+  readonly spread?: number | undefined;
+  /** 盘口深度（上游 `liquidityNum`，美元）。 */
+  readonly liquidity?: number | undefined;
+  /** 累计成交额（上游 `volumeNum`，美元）。 */
+  readonly volume?: number | undefined;
+  /** 24 小时成交额（上游 `volume24hr`，美元）。 */
+  readonly volume24h?: number | undefined;
+  /** 最小报价粒度（上游 `orderPriceMinTickSize`）。 */
+  readonly tickSize?: number | undefined;
+  /**
+   * 是否仍可下单（上游 market 级 `acceptingOrders`）。**不用 `active` 判断**：
+   * 实测结算后 `active` 仍为 true，只有 `closed`/`acceptingOrders` 会翻转。
+   */
+  readonly acceptingOrders: boolean;
+  /** 该档位市场是否已结算（上游 market 级 `closed`）。 */
+  readonly closed: boolean;
+  /** 与最近一条本地快照的差值（无快照/首次采样 = undefined，绝不填 0 冒充无变动）。 */
+  readonly changeSincePrevious?: number | undefined;
+}
+/** 一场 FOMC 决议会议（会议时间 + 档位集合 + 健康标记）。 */
+interface PredictionMeeting {
+  /** 上游 event id（去重键；slug 带随机后缀，不可作标识）。 */
+  readonly id: string;
+  readonly slug: string;
+  readonly title: string;
+  /** 决议结果窗口结束（上游 event `endDate`，ISO 8601 UTC）。 */
+  readonly endDate: string;
+  /** FOMC 会议日程（从上游 description 解析，如 `October 27-28, 2026`；未解析到 = 缺省）。 */
+  readonly meetingWindow?: string | undefined;
+  readonly closed: boolean;
+  /** 档位集合，按利率变动从低到高排序（未知形态排末位）。 */
+  readonly buckets: readonly PredictionOutcomeBucket[];
+  /** 各档概率之和（健康检查；实测正常区间约 [0.98, 1.03]，不假设严格等于 1）。 */
+  readonly probabilitySum: number;
+  /**
+   * 数据质量提示（空 = 全部健康）。桥与面板只做展示，不据此改写概率。
+   * 例：`probability-sum-out-of-band`、`probability-out-of-range`、`bucket-quote-missing`、
+   * `bucket-unrecognized-label`。
+   */
+  readonly degraded: readonly string[];
+}
+/**
+ * 预测市场快照（一次取数的完整结果）。
+ *
+ * `fetchedAt` 是**本进程的取数时刻**——上游只给 `updatedAt` 级别的事件时间，
+ * 没有响应级时间戳，所以数据时间戳由取数侧记录（单调可信）。
+ */
+interface PredictionFeed {
+  /** 取数时刻（ISO 8601 UTC；数据时间戳的唯一来源）。 */
+  readonly fetchedAt: string;
+  readonly meetings: readonly PredictionMeeting[];
+}
+/**
+ * 预测市场源契约（2026-10-11 Polymarket 接入，v1 只覆盖 FOMC 决议路径）：
+ * host 平面由 connector-polymarket provide `tradingPredictionFeed`，GUI 面板经桥
+ * `/dshtrading/api/prediction/*` 消费；服务缺席 = 未安装/未启用该数据源 →
+ * 消费方报 TRADING_NOT_IMPLEMENTED，绝不把「没有数据源」伪装成「没有数据」。
+ *
+ * 发现规则与概率口径以 spikes/impl-polymarket/EVIDENCE.md 为唯一判据：
+ * `GET /events?series_id=35` → 系列校验 → 标题正则 → 形状 → 噪声排除 → 去重/排序；
+ * 概率取 gamma `outcomePrices[0]`（与 CLOB midpoint 数值等价，单请求可取全量）。
+ */
+interface PredictionFeedService {
+  /** 当前 FOMC 决议路径全部会议（含已结算；按 endDate 升序）。 */
+  listFomcMeetings(): Promise<PredictionFeed>;
+}
 /** 新闻聚合器注册表契约（Issue #37，router 插件提供）。 */
 interface TradingNewsRegistry {
   register(market: string, aggregator: NewsAggregator): () => void;
@@ -939,4 +1186,4 @@ interface TradingNewsRegistry {
   markets(): string[];
 }
 //#endregion
-export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, AuctionSnapshot, BuybackItem, CRON_MAX, CompanyProfile, type CordisContext, CronSchedule, CryptoFundamentals, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, DividendItem, DragonTigerItem, EXECUTION_HISTORY_LIMIT, ExecutionRecord, FinancialCell, FinancialIndicatorRow, FinancialReportGroup, FinancialReportMatrix, FlashFeedService, ForecastSummary, FundamentalsPackage, HolderNumSummary, IAccount, InsiderTradeItem, InstitutionalHoldingItem, InstrumentAssetClass, InstrumentContract, InstrumentForm, InstrumentRef, Interval, Kline, LeverageSetting, LimitUpPoolItem, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MainOperationSegment, MarginMode, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewTaskInput, NewsAggregator, NewsItem, OperatingEfficiency, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, PIN_MAX, PROMPT_MAX, Position, PositionSide, ResearchReportItem, SWAP_SYMBOL_SUFFIX, ScheduleRule, SetLeverageRequest, ShareholderItem, SplitItem, StockFundamentals, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, TaskPermission, TaskRecord, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingError, TradingErrorCode, TradingNewsRegistry, hasOpenExecution, instrumentFormOf, isTaskPermission, isValidCron, nextRunAtMs, parseCron, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };
+export { AccountBalance, ActiveBuySnapshot, AggregateNewsOptions, AggregateNewsResult, AuctionSnapshot, BuybackItem, CRON_MAX, CompanyProfile, type CordisContext, CronSchedule, CryptoFundamentals, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, DividendItem, DragonTigerItem, EXECUTION_HISTORY_LIMIT, ExecutionRecord, FinancialCell, FinancialIndicatorRow, FinancialReportGroup, FinancialReportMatrix, FlashFeedService, ForecastSummary, FundamentalsPackage, HolderNumSummary, IAccount, InsiderTradeItem, InstitutionalHoldingItem, InstrumentAssetClass, InstrumentContract, InstrumentForm, InstrumentRef, Interval, Kline, KlineCapability, LeverageSetting, LimitUpPoolItem, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MainOperationSegment, MarginMode, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewTaskInput, NewsAggregator, NewsItem, OperatingEfficiency, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, PIN_MAX, PROMPT_MAX, Position, PositionSide, PredictionFeed, PredictionFeedService, PredictionMeeting, PredictionOutcomeBucket, ResearchReportItem, SWAP_SYMBOL_SUFFIX, ScheduleRule, ScheduleSkipRecord, SetLeverageRequest, ShareholderItem, SouthboundHoldingHistory, SouthboundHoldingPoint, SplitItem, StockFundamentals, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, TaskPermission, TaskRecord, TaskSkipReason, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingError, TradingErrorCode, TradingNewsRegistry, countOpenExecutions, hasOpenExecution, instrumentFormOf, isTaskPermission, isTaskSkipReason, isValidCron, nextRunAtMs, parseCron, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };

package/lib/index.js

@@ -1,4 +1,4 @@
-import { CRON_MAX, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, hasOpenExecution, isTaskPermission, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions } from "./tasks-protocol.js";
+import { CRON_MAX, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, countOpenExecutions, hasOpenExecution, isTaskPermission, isTaskSkipReason, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions } from "./tasks-protocol.js";
 import { isValidCron, nextRunAtMs, parseCron } from "./tasks-schedule.js";
 import { SWAP_SYMBOL_SUFFIX, instrumentFormOf } from "./instrument-form.js";
-export { CRON_MAX, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, SWAP_SYMBOL_SUFFIX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, hasOpenExecution, instrumentFormOf, isTaskPermission, isValidCron, nextRunAtMs, parseCron, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };
+export { CRON_MAX, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, SWAP_SYMBOL_SUFFIX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, countOpenExecutions, hasOpenExecution, instrumentFormOf, isTaskPermission, isTaskSkipReason, isValidCron, nextRunAtMs, parseCron, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };

package/lib/tasks-protocol.d.ts

@@ -33,6 +33,12 @@ declare const DEFAULT_TASK_AGENT_PRESET: "master";
  * 执行 /permission——缺省会话回退宿主默认（read-only），拿不到写入。
  */
 declare const DEFAULT_TASK_PERMISSION: TaskPermission;
+/**
+ * 全局在飞执行容量上限的保守缺省：同一时刻最多几条真实 dsh 会话在跑。
+ * 每个在飞执行都是一条消耗 API 额度的真实会话，无上限时 cron 同时到点会无界扇出；
+ * 4 允许少量日常任务并行，又不给宿主放大出容量压力（服务 opts 可覆盖）。
+ */
+declare const DEFAULT_MAX_INFLIGHT_EXECUTIONS = 4;
 /** 权限等级比较：高于会话默认的钉住权限必须经人工确认才能运行。 */
 declare function permissionRank(permission: TaskPermission): number;
 /** 是否为已知权限预设 id。 */
@@ -53,6 +59,12 @@ interface ExecutionRecord {
   error: string | undefined;
   /** 本次执行的触发来源。 */
   trigger: 'cron' | 'manual';
+  /**
+   * 未结算期间的侦查诊断：为什么这条执行还开着（会话读取失败、会话空闲且历史
+   * 无 turn/end、等待收敛窗口等）。只在内容变化时落盘，避免每轮轮询写放大；
+   * 结算时清空。它让「读取异常导致长期 pending」在快照上留痕而不是静默。
+   */
+  note?: string;
 }
 /**
  * 每任务保留的执行历史上限：新执行开始时裁掉最旧的已结算记录，账本体积与
@@ -64,6 +76,28 @@ declare const EXECUTION_HISTORY_LIMIT = 20;
  * 未结算（运行中）的执行永不裁剪：Host 监视与重启恢复都依赖活跃记录。
  */
 declare function retainRecentExecutions(executions: readonly ExecutionRecord[]): ExecutionRecord[];
+/**
+ * 定时触发点被跳过的结构化原因（cron 跳过不补跑，但要说明为什么）。
+ *
+ * `registry-unavailable` / `gateway-unavailable` 是补偿用尽原因（2026-10-14
+ * 停机补跑修复）：宿主开机窗口内（workspace 域 `rebuildEntities()` 未跑完、
+ * 名册 `list()` 抛错）或网关目标服务未激活完时，起跑失败不消费触发点，由后续
+ * tick 有界重试；重试用尽才消费触发点并以此二值说明「这个触发点为什么最终没跑」。
+ */
+declare const TASK_SKIP_REASONS: readonly ["permission-pending", "capacity", "already-running", "registry-unavailable", "gateway-unavailable"];
+/** 单个跳过原因。 */
+type TaskSkipReason = (typeof TASK_SKIP_REASONS)[number];
+/** 是否为已知跳过原因（磁盘归一化用）。 */
+declare function isTaskSkipReason(value: unknown): value is TaskSkipReason;
+/** 一次被跳过的定时触发点：到点没跑、以及为什么。 */
+interface ScheduleSkipRecord {
+  /** 记录时刻（ms epoch）。 */
+  at: number;
+  /** 被跳过的那个触发点（原 nextRunAt，ms epoch）。 */
+  triggerPoint: number;
+  /** 结构化原因。 */
+  reason: TaskSkipReason;
+}
 /** 挂在任务上的定时规则；Host 调度器在 nextRunAt 到期时触发。 */
 interface ScheduleRule {
   /** 是否已启用。 */
@@ -74,6 +108,11 @@ interface ScheduleRule {
   nextRunAt: number | undefined;
   /** 最近一次定时触发点的时刻（ms epoch）。 */
   lastTriggeredAt: number | undefined;
+  /**
+   * 最近一次被跳过的触发点（权限门/容量/已有执行/补偿用尽）；正常起跑不覆盖
+   * 历史记录。补偿用尽的触发点已推进排期，不滞留。
+   */
+  lastSkip?: ScheduleSkipRecord;
 }
 /** 一条定时任务。 */
 interface TaskRecord {
@@ -129,6 +168,8 @@ interface TaskUpdatePatch {
 declare function permissionPending(task: TaskRecord, sessionDefaultPermission: TaskPermission): boolean;
 /** 任务是否还有未结算的执行（同一任务不并发执行）。 */
 declare function hasOpenExecution(task: TaskRecord): boolean;
+/** 全部任务上未结算执行的总数（全局在飞容量的判据）。 */
+declare function countOpenExecutions(tasks: readonly TaskRecord[]): number;
 /** 调度器快照（Host 独占字段，浏览器只读）。 */
 interface TasksSchedulerSnapshot {
   timeZone: string;
@@ -194,4 +235,4 @@ declare function parseTasksAction(value: unknown): TasksAction | undefined;
 /** 校验动作信封；非法返回 undefined。 */
 declare function parseTasksEnvelope(value: unknown): TasksActionEnvelope | undefined;
 //#endregion
-export { CRON_MAX, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, ExecutionRecord, NewTaskInput, PIN_MAX, PROMPT_MAX, ScheduleRule, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, TaskPermission, TaskRecord, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, hasOpenExecution, isTaskPermission, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };
+export { CRON_MAX, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, ExecutionRecord, NewTaskInput, PIN_MAX, PROMPT_MAX, ScheduleRule, ScheduleSkipRecord, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, TaskPermission, TaskRecord, TaskSkipReason, TaskUpdatePatch, TasksAction, TasksActionEnvelope, TasksSchedulerSnapshot, TasksSnapshot, countOpenExecutions, hasOpenExecution, isTaskPermission, isTaskSkipReason, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };

package/lib/tasks-protocol.js

@@ -35,6 +35,12 @@ const DEFAULT_TASK_AGENT_PRESET = "master";
 * 执行 /permission——缺省会话回退宿主默认（read-only），拿不到写入。
 */
 const DEFAULT_TASK_PERMISSION = "workspace-write";
+/**
+* 全局在飞执行容量上限的保守缺省：同一时刻最多几条真实 dsh 会话在跑。
+* 每个在飞执行都是一条消耗 API 额度的真实会话，无上限时 cron 同时到点会无界扇出；
+* 4 允许少量日常任务并行，又不给宿主放大出容量压力（服务 opts 可覆盖）。
+*/
+const DEFAULT_MAX_INFLIGHT_EXECUTIONS = 4;
 /** 权限等级比较：高于会话默认的钉住权限必须经人工确认才能运行。 */
 function permissionRank(permission) {
 	return TASK_PERMISSIONS.indexOf(permission);
@@ -59,6 +65,25 @@ function retainRecentExecutions(executions) {
 	const keepSettled = Math.max(20 - open.length, 0);
 	return [...settled.slice(Math.max(settled.length - keepSettled, 0)), ...open];
 }
+/**
+* 定时触发点被跳过的结构化原因（cron 跳过不补跑，但要说明为什么）。
+*
+* `registry-unavailable` / `gateway-unavailable` 是补偿用尽原因（2026-10-14
+* 停机补跑修复）：宿主开机窗口内（workspace 域 `rebuildEntities()` 未跑完、
+* 名册 `list()` 抛错）或网关目标服务未激活完时，起跑失败不消费触发点，由后续
+* tick 有界重试；重试用尽才消费触发点并以此二值说明「这个触发点为什么最终没跑」。
+*/
+const TASK_SKIP_REASONS = [
+	"permission-pending",
+	"capacity",
+	"already-running",
+	"registry-unavailable",
+	"gateway-unavailable"
+];
+/** 是否为已知跳过原因（磁盘归一化用）。 */
+function isTaskSkipReason(value) {
+	return typeof value === "string" && TASK_SKIP_REASONS.includes(value);
+}
 /** 任务是否处于权限确认门待确认状态（定时与手动运行都拒绝）。 */
 function permissionPending(task, sessionDefaultPermission) {
 	return permissionRank(task.permission ?? sessionDefaultPermission) > permissionRank(sessionDefaultPermission) && task.permissionConfirmedAt === void 0;
@@ -67,6 +92,12 @@ function permissionPending(task, sessionDefaultPermission) {
 function hasOpenExecution(task) {
 	return task.executions.some((execution) => execution.endedAt === void 0);
 }
+/** 全部任务上未结算执行的总数（全局在飞容量的判据）。 */
+function countOpenExecutions(tasks) {
+	let open = 0;
+	for (const task of tasks) for (const execution of task.executions) if (execution.endedAt === void 0) open += 1;
+	return open;
+}
 const TITLE_MAX = 200;
 const PROMPT_MAX = 65536;
 const PIN_MAX = 200;
@@ -252,4 +283,4 @@ function parseTasksEnvelope(value) {
 	};
 }
 //#endregion
-export { CRON_MAX, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TITLE_MAX, hasOpenExecution, isTaskPermission, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };
+export { CRON_MAX, DEFAULT_MAX_INFLIGHT_EXECUTIONS, DEFAULT_SESSION_PERMISSION, DEFAULT_TASK_AGENT_PRESET, DEFAULT_TASK_PERMISSION, EXECUTION_HISTORY_LIMIT, PIN_MAX, PROMPT_MAX, TASKS_ACTION_BYTES_LIMIT, TASKS_API_SUBPATH, TASKS_SCHEMA_VERSION, TASK_PERMISSIONS, TASK_SKIP_REASONS, TITLE_MAX, countOpenExecutions, hasOpenExecution, isTaskPermission, isTaskSkipReason, parseNewTaskInput, parseTaskUpdatePatch, parseTasksAction, parseTasksEnvelope, permissionPending, permissionRank, retainRecentExecutions };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/api",
   "description": "Pure TypeScript contracts for dsh-trading: market-data/trade service interfaces, domain types, and the shared error vocabulary",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -17,7 +17,7 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/cordis": "^4.0.5",
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0"
   },