@dshtrading/api 0.5.0 → 0.6.1

package/lib/index.d.ts

@@ -1,13 +1,8 @@
+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 { 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
-/**
- * @dshtrading/api — 纯类型契约包（crypto-slice-plan §关键接口草案）。
- *
- * 零运行时、零依赖：服务契约由连接器实现（ctx 键按市场命名空间，如 ctx.tradingCrypto），
- * 消费方只依赖这里的类型。交易安全闸门（铁律 #3）在类型层面体现为
- * OrderRequest.dryRun 默认 true、错误词汇含 LIVE_TRADING_DISABLED / APPROVAL_DENIED。
- *
- * @module @dshtrading/api
- */
 /** K线周期（Binance 现货/合约 interval 词汇）。 */
 type Interval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
 /** 最新行情快照（公共数据，无需凭证）。 */
@@ -422,16 +417,32 @@ interface FundamentalsPackage {
   readonly dragonTiger?: DragonTigerItem;
 }
 type PositionSide = 'long' | 'short';
+/**
+ * 保证金模式（合约交易语义，P7）：`cross` = 全仓、`isolated` = 逐仓。
+ * 现货（cash）不使用该字段——缺席即「非保证金/未设置」。
+ */
+type MarginMode = 'cross' | 'isolated';
 /** 持仓快照。 */
 interface Position {
   readonly symbol: string;
   readonly side: PositionSide;
-  /** 仓位数量（正数；方向由 side 表达）。 */
+  /** 仓位数量（正数；方向由 side 表达）。合约仓位是 **base 币数**（连接器已按合约乘数 ctVal 由张换算）。 */
   readonly size: number;
   readonly entryPrice: number;
   readonly markPrice?: number;
   readonly unrealizedPnl?: number;
   readonly leverage?: number;
+  /**
+   * 强平价（交易所回传原样透传；交易所未提供或不适用时缺席，绝不本地推算强平价——
+   * 强平口径与保证金模式、账户级保证金、维持保证金率有关，本地公式会给出错误的安全感）。
+   */
+  readonly liquidationPrice?: number;
+  /** 维持保证金率（OKX `mgnRatio`；口径由交易所定义，原样透传，不在本地换算或反推）。 */
+  readonly marginRatio?: number;
+  /** 该仓位的保证金模式；现货持仓与交易所未提供时缺席。 */
+  readonly marginMode?: MarginMode;
+  /** 名义价值（USD，交易所口径；用于敞口核对，不参与本地风控公式）。 */
+  readonly notionalUsd?: number;
   readonly timestamp: number;
 }
 type OrderSide = 'buy' | 'sell';
@@ -442,10 +453,18 @@ interface OrderRequest {
   readonly symbol: string;
   readonly side: OrderSide;
   readonly type: OrderType;
+  /** **base 币数量**：合约（永续）由连接器按合约乘数换算成张，消费方恒用币数语义。 */
   readonly quantity: number;
   /** limit 单必填。 */
   readonly price?: number;
-  /** 缺省/true 时仅模拟，不触碰交易所。实盘还受插件 liveTrading 闸门与 approval 约束 [S4]。 */
+  /**
+   * 合约订单的保证金模式（缺省 `cross`）。仅对永续（`-SWAP`）有效：
+   * 现货订单只允许 cash 语义，传该字段由连接器结构化拒绝
+   * （现货逐仓/杠杆是另一个产品面，本仓未接线）。
+   * `isolated` 需先在交易所侧设好该标的的逐仓杠杆（OKX `setLeverage`）。
+   */
+  readonly marginMode?: MarginMode;
+  /** 缺省/true 时仅模拟，不触碰交易所。实盘还受 @dshtrading/authority 的人工签署授权与 approval 约束 [S4]。 */
   readonly dryRun?: boolean;
 }
 /** 订单回执/状态。 */
@@ -490,9 +509,49 @@ interface IAccount {
 interface Disposable {
   dispose(): void;
 }
+/**
+ * 标的形态轴（2026-10-08 加密永续与 TradFi 永续落地）：与 `market` 正交，**不新增市场键**。
+ * 缺省 = `spot`——已存自选、localStorage 与 iOS 冻结契约因此零迁移。
+ *
+ * 形态由规范符号后缀承载（`-SWAP` = 永续），见 docs/guides/symbol-vocabulary.md；
+ * `form` 只出现在名册/检索/wire 元数据里，行情方法不新增 form 形参。
+ */
+type InstrumentForm = 'spot' | 'perp';
+/**
+ * 标的资产类别标签（仅展示与检索排序用，不承载交易语义）。
+ * **只信交易所元数据**（OKX `instCategory`、Binance `underlyingType`+`underlyingSubType`）；
+ * 取不到时留空，禁止按符号字面猜（`SPX` 在 OKX 是迷因币 SPX6900，标普 500 是 `US500`）。
+ */
+type InstrumentAssetClass = 'crypto' | 'equity' | 'commodity' | 'index';
+/** 合约专有元数据（仅 `form=perp` 有值）：交易所元数据原样透传，不本地推断。 */
+interface InstrumentContract {
+  /** 合约乘数（OKX ctVal / Binance contractSize）。 */
+  readonly multiplier?: number;
+  /** 最小价格变动。 */
+  readonly tickSize?: number;
+  /** 最小下单量/张数步长。 */
+  readonly lotSize?: number;
+  /** 交易所允许的最大杠杆。 */
+  readonly maxLeverage?: number;
+  /** 结算币种（如 USDT）。 */
+  readonly settleCcy?: string;
+}
+/**
+ * 标的检索结果的最小元数据（名册/搜索/wire 共用）。
+ * 元素形状对既有 `{ symbol, name? }` 实现向后兼容：`form`/`assetClass`/`contract` 全可选。
+ */
+interface InstrumentRef {
+  /** 市场规范词汇符号（docs/guides/symbol-vocabulary.md）。 */
+  readonly symbol: string;
+  readonly name?: string;
+  /** 缺省 = spot（老数据零迁移）。 */
+  readonly form?: InstrumentForm;
+  readonly assetClass?: InstrumentAssetClass;
+  readonly contract?: InstrumentContract;
+}
 /**
  * 行情服务契约：由市场连接器实现，注册到按市场命名空间的 ctx 键（如 ctx.tradingCrypto）。
- * 符号词汇（2026-08-31 规范，docs/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
+ * 符号词汇（2026-08-31 规范，docs/guides/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
  * 输出 `symbol` 一律市场规范形——消费方（GUI/Agent/工作流）与数据源方言解耦。
  */
 interface MarketDataService {
@@ -501,13 +560,12 @@ interface MarketDataService {
   subscribeTicker(symbol: string, cb: (ticker: Ticker) => void): Disposable;
   /**
    * 查询本市场/交易所支持的全部标的名册（动态全集，Issue #15）。
-   * 输出 `symbol` 一律市场规范词汇（docs/symbol-vocabulary.md）。
+   * 输出 `symbol` 一律市场规范词汇（docs/guides/symbol-vocabulary.md），形态由符号后缀承载
+   * （`-SWAP` = 永续，`instrumentFormOf` 是唯一裁决实现）；每行可带
+   * `form`/`assetClass`/`contract` 元数据（InstrumentRef），缺省 = 现货。
    * 可选方法：无公开全集端点的数据源（如 tencent/yahoo/stooq）可缺省或由桥/前端回退。
    */
-  listInstruments?(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
+  listInstruments?(): Promise<InstrumentRef[]>;
   /**
    * 标的基本面与估值快照（GUI「基本面」页签用，2026-09-02）。
    * 可选方法：仅当数据源在同一公共端点里携带基本面字段时实现
@@ -543,11 +601,41 @@ interface MarketDataService {
   getRecentTrades?(symbol: string, limit?: number): Promise<TradeTick[]>;
 }
 /**
- * 交易服务契约：placeOrder 默认 dry-run；实盘前必须过插件 liveTrading 开关与
+ * 杠杆设置请求（合约交易语义，P7；仅 `form=perp` 的标的可传）。
+ * dryRun 缺省视为 true：只回本地模拟回执，不触碰交易所（与 placeOrder 同语义）。
+ */
+interface SetLeverageRequest {
+  readonly symbol: string;
+  /** 目标杠杆倍数（> 0；上限以交易所规格 `InstrumentContract.maxLeverage` 为准，超出即结构化拒绝）。 */
+  readonly leverage: number;
+  readonly marginMode: MarginMode;
+  /** 双向持仓模式下的方向（OKX `posSide`）；净持仓模式下缺席。 */
+  readonly posSide?: 'long' | 'short';
+  /** 全仓模式下按币种设置杠杆时的保证金币（OKX `ccy`）；逐仓与净持仓模式缺席。 */
+  readonly ccy?: string;
+  /** 缺省/true 时仅模拟。实盘还受 @dshtrading/authority 的人工签署授权与 approval 约束 [S4]。 */
+  readonly dryRun?: boolean;
+}
+/** 杠杆设置回执（dryRun=true 时是本地模拟回执，不触网）。 */
+interface LeverageSetting {
+  readonly symbol: string;
+  readonly leverage: number;
+  readonly marginMode: MarginMode;
+  readonly posSide?: 'long' | 'short';
+  readonly ccy?: string;
+  /** 本次是否为模拟回执（回执必须显式回带，防 dry-run 语义丢失）。 */
+  readonly dryRun: boolean;
+  readonly timestamp: number;
+}
+/**
+ * 交易服务契约：placeOrder 默认 dry-run；实盘前必须过 @dshtrading/authority 的人工签署授权与
  * ctx.approval.request（交互形态；headless 下 ask=deny，fail-closed [S4]）。
  *
  * R3（okx 切片 2026-08-29）修订：cancelOrder 增加可选 symbol、新增 getOrder——
  * OKX 按 (instId, ordId) 双键定位订单，单参 id 形态不够；无其他实现方，扩展向后兼容。
+ *
+ * P7（合约交易 Tier 2，2026-10-08）修订：新增可选 `setLeverage`——杠杆/保证金模式变更
+ * 是实盘动作，必须与下单同门槛（服务缝三态闸门 + base 审批闸门 + 人工签署授权）。
  */
 interface TradeService {
   placeOrder(req: OrderRequest): Promise<Order>;
@@ -572,6 +660,13 @@ interface TradeService {
    * 可选方法：时间升序（旧→新），最多 limit 条（缺省 ≤50）。
    */
   listTradeFills?(symbol?: string, limit?: number): Promise<TradeFill[]>;
+  /**
+   * 设置合约杠杆与保证金模式（P7 合约交易 Tier 2；仅支持合约的交易所实现）。
+   * 可选方法：不实现的连接器缺席即可，消费方按 TRADING_NOT_IMPLEMENTED 语义处理。
+   * 这是会改变账户真实风险参数的实盘动作：dryRun 缺省 true（只回本地模拟回执），
+   * dryRun=false 必须同时具备人工签署的实盘授权，并经 base 审批闸门。
+   */
+  setLeverage?(req: SetLeverageRequest): Promise<LeverageSetting>;
 }
 /**
  * 统一错误词汇（本包不做运行时 Error 类；实现方自行映射到该词汇）。
@@ -594,8 +689,15 @@ type TradingErrorCode =
  * 该码（rest.ts 的 HTTP 非 ok 分支），此前只是漏进了本词汇表（类型层缺口）。
  */
 'TRADING_UPSTREAM_ERROR' | 'TRADING_INSUFFICIENT_BALANCE' |
-/** liveTrading=false 闸门拒绝实盘（铁律 #3）。 */
+/** 未获人工签署实盘授权时拒绝实盘（铁律 #3）。 */
 'TRADING_LIVE_TRADING_DISABLED' |
+/**
+ * 请求缺一个**必填**的账户定位（当前用点：桥的 `cancel-order` 必须显式 `accId`——
+ * 请求里没有 market，HK / US 是两套 trd 上下文，桥不猜）。
+ * 与 TRADING_EXCHANGE_ERROR 分开：上游对同类缺格回的是它自己那句错误串，读起来像
+ * "venue 拒绝了这笔单"，而事实是**我们发错了请求**（客户端手里本来就有全部信息）。
+ */
+'TRADING_ACCOUNT_REQUIRED' |
 /** approval 被拒/无应答（headless fail-closed [S4]）。 */
 'TRADING_APPROVAL_DENIED' |
 /** 本次为 dry-run 模拟结果（非故障语义）。 */
@@ -636,7 +738,7 @@ declare module '@deepseek-ai/cordis' {
      * 交易服务注册表（issue #40 GUI 交易台，@dshtrading/api 类型声明）：
      * 与 tradingMarketDataRegistry 同构的宿主平面注册面——交易连接器 host 面数据行
      * 注册，GUI 桥按路由当前值惰性解析。**注册不改变安全语义**：placeOrder 的
-     * 服务缝闸门（dryRun 缺省 true + liveTrading 显式开关）随服务实例生效；
+     * 服务缝闸门（dryRun 缺省 true + @dshtrading/authority 人工签署授权）随服务实例生效；
      * GUI 桥只放行 dry-run 下单与只读查询，实盘路径仍走 Agent 工具的 base 审批闸门。
      */
     tradingTradeRegistry: TradeRegistry;
@@ -837,4 +939,4 @@ interface TradingNewsRegistry {
   markets(): string[];
 }
 //#endregion
-export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, AuctionSnapshot, BuybackItem, CompanyProfile, CryptoFundamentals, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, DividendItem, DragonTigerItem, FinancialCell, FinancialIndicatorRow, FinancialReportGroup, FinancialReportMatrix, FlashFeedService, ForecastSummary, FundamentalsPackage, HolderNumSummary, IAccount, InsiderTradeItem, InstitutionalHoldingItem, Interval, Kline, LimitUpPoolItem, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MainOperationSegment, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewsAggregator, NewsItem, OperatingEfficiency, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, Position, PositionSide, ResearchReportItem, ShareholderItem, SplitItem, StockFundamentals, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingError, TradingErrorCode, TradingNewsRegistry };
+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 };

package/lib/index.js

@@ -1 +1,4 @@
-export {};
+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 { 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 };

package/lib/instrument-form.d.ts

@@ -0,0 +1,11 @@
+import { InstrumentForm } from "./index.js";
+//#region src/instrument-form.d.ts
+/** 永续规范形后缀（规范词汇的唯一载体，见 docs/guides/symbol-vocabulary.md）。 */
+declare const SWAP_SYMBOL_SUFFIX = "-SWAP";
+/**
+ * 由规范符号裁决形态：带 `-SWAP` 后缀为 `perp`，否则 `spot`。
+ * 输入容忍小写与空白（trim + 大写化）后判定，**不剥后缀**——剥了就不是同一个符号了。
+ */
+declare function instrumentFormOf(symbol: string): InstrumentForm;
+//#endregion
+export { SWAP_SYMBOL_SUFFIX, instrumentFormOf };

package/lib/instrument-form.js

@@ -0,0 +1,12 @@
+//#region src/instrument-form.ts
+/** 永续规范形后缀（规范词汇的唯一载体，见 docs/guides/symbol-vocabulary.md）。 */
+const SWAP_SYMBOL_SUFFIX = "-SWAP";
+/**
+* 由规范符号裁决形态：带 `-SWAP` 后缀为 `perp`，否则 `spot`。
+* 输入容忍小写与空白（trim + 大写化）后判定，**不剥后缀**——剥了就不是同一个符号了。
+*/
+function instrumentFormOf(symbol) {
+	return symbol.trim().toUpperCase().endsWith("-SWAP") ? "perp" : "spot";
+}
+//#endregion
+export { SWAP_SYMBOL_SUFFIX, instrumentFormOf };

package/lib/tasks-protocol.d.ts

@@ -0,0 +1,197 @@
+//#region src/tasks-protocol.d.ts
+/**
+ * 右侧栏定时任务——协议层：任务记录形状、动作判别联合与线校验。
+ *
+ * 设计对齐 dsh-web dsh-task-board 的 Host 权威账本语义（浏览器是异步视图，
+ * Host 确认后的 snapshot 才是 UI 状态），但按交易侧栏场景裁剪：
+ *
+ * - 保留：任务记录（标题/prompt/定时规则/钉住三元组/权限确认门）、有界执行
+ *   历史、幂等动作信封、revision 快照、5 段 cron。
+ * - 裁剪：看板列状态/描述列/归档/续接冻结卡/交接包/浏览器导入——那些是看板
+ *   工作流概念；侧栏定时任务的心智模型是「到点自动开新会话跑 prompt」。
+ *
+ * 安全面与 task-board 同构：所有变更载荷走严格、版本化的判别联合 + 精确键
+ * 校验；浏览器不能写 scheduler 独占时间戳或执行结果；协议不接受命令、可执
+ * 行路径、shell 文本或任意参数字段。字符串字段全部有上界。
+ */
+declare const TASKS_SCHEMA_VERSION: 1;
+/** 交易桥上定时任务子路径（挂在 /dshtrading/api 之后）。 */
+declare const TASKS_API_SUBPATH = "/tasks";
+/** 动作载荷上限（对齐 task-board：普通动作 64 KiB）。 */
+declare const TASKS_ACTION_BYTES_LIMIT: number;
+/** 任务可钉住的会话权限预设（/permission <id> 的 id 词汇）。 */
+declare const TASK_PERMISSIONS: readonly ["read-only", "workspace-write", "danger-full-access"];
+/** 单个权限预设 id。 */
+type TaskPermission = (typeof TASK_PERMISSIONS)[number];
+/** 未钉住权限时的会话默认（确认门基准；交易宿主取 workspace-write——日常任务
+ * 默认可写，只有 danger-full-access 仍走人工确认门）。 */
+declare const DEFAULT_SESSION_PERMISSION: TaskPermission;
+/** 新建任务未钉住 agent 预设时的插件默认：大师（多 agent 团队主导者）。 */
+declare const DEFAULT_TASK_AGENT_PRESET: "master";
+/**
+ * 新建任务未钉住权限时的插件默认。必须有值落盘（钉住）：runner 只对钉住权限
+ * 执行 /permission——缺省会话回退宿主默认（read-only），拿不到写入。
+ */
+declare const DEFAULT_TASK_PERMISSION: TaskPermission;
+/** 权限等级比较：高于会话默认的钉住权限必须经人工确认才能运行。 */
+declare function permissionRank(permission: TaskPermission): number;
+/** 是否为已知权限预设 id。 */
+declare function isTaskPermission(value: unknown): value is TaskPermission;
+/** 单次真实执行尝试：自己的 id、承载它的 dsh 会话、结算结果。 */
+interface ExecutionRecord {
+  /** 执行尝试 id（uuid）。 */
+  id: string;
+  /** 承载本次执行的 dsh 会话；会话创建落定前缺省。 */
+  sessionId: string | undefined;
+  /** 启动时刻（ms epoch）。 */
+  startedAt: number;
+  /** 结算时刻；仍在运行时缺省。 */
+  endedAt: number | undefined;
+  /** 结算后的结果。 */
+  result: 'succeeded' | 'failed' | 'cancelled' | undefined;
+  /** 失败时的人类可读原因（prompt 拒绝、agent 出错、启动失败等）。 */
+  error: string | undefined;
+  /** 本次执行的触发来源。 */
+  trigger: 'cron' | 'manual';
+}
+/**
+ * 每任务保留的执行历史上限：新执行开始时裁掉最旧的已结算记录，账本体积与
+ * 单次写入成本不随历史无限增长。
+ */
+declare const EXECUTION_HISTORY_LIMIT = 20;
+/**
+ * 把执行列表裁剪到至多 {@link EXECUTION_HISTORY_LIMIT} 条，最近的在最后。
+ * 未结算（运行中）的执行永不裁剪：Host 监视与重启恢复都依赖活跃记录。
+ */
+declare function retainRecentExecutions(executions: readonly ExecutionRecord[]): ExecutionRecord[];
+/** 挂在任务上的定时规则；Host 调度器在 nextRunAt 到期时触发。 */
+interface ScheduleRule {
+  /** 是否已启用。 */
+  enabled: boolean;
+  /** 5 段 cron：分 时 日 月 周（宿主本地时区）。 */
+  cron: string;
+  /** 下次到期时刻（ms epoch）；由调度器/控制器维护。 */
+  nextRunAt: number | undefined;
+  /** 最近一次定时触发点的时刻（ms epoch）。 */
+  lastTriggeredAt: number | undefined;
+}
+/** 一条定时任务。 */
+interface TaskRecord {
+  /** 稳定任务 id（uuid）。 */
+  id: string;
+  /** 短标题（会话重命名同款文案）。 */
+  title: string;
+  /** 到点发给新 dsh 会话的 prompt。 */
+  prompt: string;
+  /** 创建时刻（ms epoch）。 */
+  createdAt: number;
+  /** 最近变更时刻（ms epoch）。 */
+  updatedAt: number;
+  /** 执行历史，最近在最后（见 {@link retainRecentExecutions}）。 */
+  executions: ExecutionRecord[];
+  /** 定时规则；未排期（仅手动运行）时缺省。 */
+  schedule?: ScheduleRule;
+  /** 执行必须落在的工作区（workspace id）；缺省 = 执行时的最近工作区回退。 */
+  workspaceId?: string;
+  /** 执行会话使用的 agent 预设（agentPreset id）；缺省 = 部署默认。 */
+  agentPreset?: string;
+  /** 经 /permission <id> 应用到执行会话的权限预设；缺省 = 会话默认。 */
+  permission?: TaskPermission;
+  /** 高于会话默认权限的人工确认戳（ms epoch）；钉住权限/变更即清除（重新武装确认门）。 */
+  permissionConfirmedAt?: number;
+}
+/** 新建任务输入（UI → Host）。 */
+interface NewTaskInput {
+  title: string;
+  prompt: string;
+  workspaceId?: string;
+  agentPreset?: string;
+  permission?: TaskPermission;
+  /** 创建时可携带的定时规则；enabled 且 cron 合法才武装。 */
+  schedule?: {
+    enabled: boolean;
+    cron: string;
+  };
+}
+/** 更新补丁：出现的键才更新；显式 null 清除对应钉住字段。 */
+interface TaskUpdatePatch {
+  title?: string;
+  prompt?: string;
+  workspaceId?: string | null;
+  agentPreset?: string | null;
+  permission?: TaskPermission | null;
+  schedule?: {
+    enabled: boolean;
+    cron: string;
+  };
+}
+/** 任务是否处于权限确认门待确认状态（定时与手动运行都拒绝）。 */
+declare function permissionPending(task: TaskRecord, sessionDefaultPermission: TaskPermission): boolean;
+/** 任务是否还有未结算的执行（同一任务不并发执行）。 */
+declare function hasOpenExecution(task: TaskRecord): boolean;
+/** 调度器快照（Host 独占字段，浏览器只读）。 */
+interface TasksSchedulerSnapshot {
+  timeZone: string;
+  lastTickAt?: number;
+  error?: string;
+}
+/** 完整 revision 快照：Host 确认后的唯一权威 UI 状态。 */
+interface TasksSnapshot {
+  schemaVersion: typeof TASKS_SCHEMA_VERSION;
+  revision: number;
+  tasks: TaskRecord[];
+  scheduler: TasksSchedulerSnapshot;
+  /** 确认门比较基准：部署的会话默认权限。 */
+  sessionDefaultPermission: TaskPermission;
+}
+type TasksAction = {
+  kind: 'create';
+  id: string;
+  input: NewTaskInput;
+} | {
+  kind: 'update';
+  taskId: string;
+  patch: TaskUpdatePatch;
+} | {
+  kind: 'delete';
+  taskId: string;
+} | {
+  kind: 'set-schedule';
+  taskId: string;
+  patch: {
+    enabled?: boolean;
+    cron?: string;
+  };
+} | {
+  kind: 'run';
+  taskId: string;
+} | {
+  kind: 'confirm-permission';
+  taskId: string;
+};
+/** 动作信封：requestId 供 Host 侧幂等去重（重启后仍有效）。 */
+interface TasksActionEnvelope {
+  requestId: string;
+  action: TasksAction;
+}
+declare const TITLE_MAX = 200;
+declare const PROMPT_MAX: number;
+declare const PIN_MAX = 200;
+declare const CRON_MAX = 100;
+/** 校验并收敛新建输入；非法返回 undefined（Host 拒绝而不是猜测）。 */
+declare function parseNewTaskInput(value: unknown): NewTaskInput | undefined;
+/**
+ * 校验并收敛更新补丁；非法返回 undefined。
+ *
+ * 显式 null 必须原样保留在补丁里——清除钉住字段的语义由 ledger.applyPatch
+ * 落实（patch.workspaceId === null → delete），这里若丢弃 null，UI 编辑器
+ * 发出的清除动作会在桥层被静默吞掉（2026-09-04 实证回归，随 agent 工具
+ * 面一并修复）。
+ */
+declare function parseTaskUpdatePatch(value: unknown): TaskUpdatePatch | undefined;
+/** 校验动作判别联合；非法返回 undefined。 */
+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 };

package/lib/tasks-protocol.js

@@ -0,0 +1,255 @@
+//#region src/tasks-protocol.ts
+/**
+* 右侧栏定时任务——协议层：任务记录形状、动作判别联合与线校验。
+*
+* 设计对齐 dsh-web dsh-task-board 的 Host 权威账本语义（浏览器是异步视图，
+* Host 确认后的 snapshot 才是 UI 状态），但按交易侧栏场景裁剪：
+*
+* - 保留：任务记录（标题/prompt/定时规则/钉住三元组/权限确认门）、有界执行
+*   历史、幂等动作信封、revision 快照、5 段 cron。
+* - 裁剪：看板列状态/描述列/归档/续接冻结卡/交接包/浏览器导入——那些是看板
+*   工作流概念；侧栏定时任务的心智模型是「到点自动开新会话跑 prompt」。
+*
+* 安全面与 task-board 同构：所有变更载荷走严格、版本化的判别联合 + 精确键
+* 校验；浏览器不能写 scheduler 独占时间戳或执行结果；协议不接受命令、可执
+* 行路径、shell 文本或任意参数字段。字符串字段全部有上界。
+*/
+const TASKS_SCHEMA_VERSION = 1;
+/** 交易桥上定时任务子路径（挂在 /dshtrading/api 之后）。 */
+const TASKS_API_SUBPATH = "/tasks";
+/** 动作载荷上限（对齐 task-board：普通动作 64 KiB）。 */
+const TASKS_ACTION_BYTES_LIMIT = 65536;
+/** 任务可钉住的会话权限预设（/permission <id> 的 id 词汇）。 */
+const TASK_PERMISSIONS = [
+	"read-only",
+	"workspace-write",
+	"danger-full-access"
+];
+/** 未钉住权限时的会话默认（确认门基准；交易宿主取 workspace-write——日常任务
+* 默认可写，只有 danger-full-access 仍走人工确认门）。 */
+const DEFAULT_SESSION_PERMISSION = "workspace-write";
+/** 新建任务未钉住 agent 预设时的插件默认：大师（多 agent 团队主导者）。 */
+const DEFAULT_TASK_AGENT_PRESET = "master";
+/**
+* 新建任务未钉住权限时的插件默认。必须有值落盘（钉住）：runner 只对钉住权限
+* 执行 /permission——缺省会话回退宿主默认（read-only），拿不到写入。
+*/
+const DEFAULT_TASK_PERMISSION = "workspace-write";
+/** 权限等级比较：高于会话默认的钉住权限必须经人工确认才能运行。 */
+function permissionRank(permission) {
+	return TASK_PERMISSIONS.indexOf(permission);
+}
+/** 是否为已知权限预设 id。 */
+function isTaskPermission(value) {
+	return typeof value === "string" && TASK_PERMISSIONS.includes(value);
+}
+/**
+* 每任务保留的执行历史上限：新执行开始时裁掉最旧的已结算记录，账本体积与
+* 单次写入成本不随历史无限增长。
+*/
+const EXECUTION_HISTORY_LIMIT = 20;
+/**
+* 把执行列表裁剪到至多 {@link EXECUTION_HISTORY_LIMIT} 条，最近的在最后。
+* 未结算（运行中）的执行永不裁剪：Host 监视与重启恢复都依赖活跃记录。
+*/
+function retainRecentExecutions(executions) {
+	if (executions.length <= 20) return [...executions];
+	const open = executions.filter((execution) => execution.endedAt === void 0);
+	const settled = executions.filter((execution) => execution.endedAt !== void 0);
+	const keepSettled = Math.max(20 - open.length, 0);
+	return [...settled.slice(Math.max(settled.length - keepSettled, 0)), ...open];
+}
+/** 任务是否处于权限确认门待确认状态（定时与手动运行都拒绝）。 */
+function permissionPending(task, sessionDefaultPermission) {
+	return permissionRank(task.permission ?? sessionDefaultPermission) > permissionRank(sessionDefaultPermission) && task.permissionConfirmedAt === void 0;
+}
+/** 任务是否还有未结算的执行（同一任务不并发执行）。 */
+function hasOpenExecution(task) {
+	return task.executions.some((execution) => execution.endedAt === void 0);
+}
+const TITLE_MAX = 200;
+const PROMPT_MAX = 65536;
+const PIN_MAX = 200;
+const CRON_MAX = 100;
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function exactKeys(value, allowed) {
+	return Object.keys(value).every((key) => allowed.includes(key));
+}
+function boundedString(value, max) {
+	return typeof value === "string" && value.length <= max;
+}
+/** undefined 或有界字符串。 */
+function optionalBoundedString(value, max) {
+	return value === void 0 || boundedString(value, max);
+}
+/** undefined / null 或有界字符串（补丁语义：null 显式清除钉住字段）。 */
+function optionalBoundedStringOrNull(value, max) {
+	return value === void 0 || value === null || boundedString(value, max);
+}
+/** undefined 或「有界且非空白」字符串（标题语义）。 */
+function optionalBoundedNonEmptyString(value, max) {
+	return value === void 0 || boundedString(value, max) && value.trim() !== "";
+}
+/** 校验并收敛 schedule 输入；非法返回 undefined。 */
+function scheduleInput(value) {
+	const row = record(value);
+	if (row === void 0 || !exactKeys(row, ["enabled", "cron"])) return void 0;
+	if (typeof row.enabled !== "boolean" || !boundedString(row.cron, 100)) return void 0;
+	return {
+		enabled: row.enabled,
+		cron: row.cron
+	};
+}
+/** 校验并收敛新建输入；非法返回 undefined（Host 拒绝而不是猜测）。 */
+function parseNewTaskInput(value) {
+	const row = record(value);
+	if (row === void 0 || !exactKeys(row, [
+		"title",
+		"prompt",
+		"workspaceId",
+		"agentPreset",
+		"permission",
+		"schedule"
+	])) return void 0;
+	if (!boundedString(row.title, 200) || row.title.trim() === "") return void 0;
+	if (!boundedString(row.prompt, 65536)) return void 0;
+	const workspaceId = row.workspaceId;
+	if (!optionalBoundedString(workspaceId, 200)) return void 0;
+	const agentPreset = row.agentPreset;
+	if (!optionalBoundedString(agentPreset, 200)) return void 0;
+	const permission = row.permission;
+	if (permission !== void 0) {
+		if (!isTaskPermission(permission)) return void 0;
+	}
+	const schedule = row.schedule === void 0 ? void 0 : scheduleInput(row.schedule);
+	if (row.schedule !== void 0 && schedule === void 0) return void 0;
+	return {
+		title: row.title,
+		prompt: row.prompt,
+		...workspaceId === void 0 ? {} : { workspaceId },
+		...agentPreset === void 0 ? {} : { agentPreset },
+		...permission === void 0 ? {} : { permission },
+		...schedule === void 0 ? {} : { schedule }
+	};
+}
+/**
+* 校验并收敛更新补丁；非法返回 undefined。
+*
+* 显式 null 必须原样保留在补丁里——清除钉住字段的语义由 ledger.applyPatch
+* 落实（patch.workspaceId === null → delete），这里若丢弃 null，UI 编辑器
+* 发出的清除动作会在桥层被静默吞掉（2026-09-04 实证回归，随 agent 工具
+* 面一并修复）。
+*/
+function parseTaskUpdatePatch(value) {
+	const row = record(value);
+	if (row === void 0 || !exactKeys(row, [
+		"title",
+		"prompt",
+		"workspaceId",
+		"agentPreset",
+		"permission",
+		"schedule"
+	])) return void 0;
+	const title = row.title;
+	if (title !== void 0 && !optionalBoundedNonEmptyString(title, 200)) return void 0;
+	const prompt = row.prompt;
+	if (prompt !== void 0 && !optionalBoundedString(prompt, 65536)) return void 0;
+	const workspaceId = row.workspaceId;
+	if (!optionalBoundedStringOrNull(workspaceId, 200)) return void 0;
+	const agentPreset = row.agentPreset;
+	if (!optionalBoundedStringOrNull(agentPreset, 200)) return void 0;
+	const permission = row.permission;
+	if (permission !== void 0 && permission !== null) {
+		if (!isTaskPermission(permission)) return void 0;
+	}
+	const schedule = row.schedule === void 0 ? void 0 : scheduleInput(row.schedule);
+	if (row.schedule !== void 0 && schedule === void 0) return void 0;
+	return {
+		...title === void 0 ? {} : { title },
+		...prompt === void 0 ? {} : { prompt },
+		...workspaceId === void 0 ? {} : { workspaceId },
+		...agentPreset === void 0 ? {} : { agentPreset },
+		...permission === void 0 ? {} : { permission },
+		...schedule === void 0 ? {} : { schedule }
+	};
+}
+/** 校验动作判别联合；非法返回 undefined。 */
+function parseTasksAction(value) {
+	const row = record(value);
+	if (row === void 0 || typeof row.kind !== "string") return void 0;
+	switch (row.kind) {
+		case "create": {
+			if (!exactKeys(row, [
+				"kind",
+				"id",
+				"input"
+			])) return void 0;
+			if (!boundedString(row.id, 64) || row.id === "") return void 0;
+			const input = parseNewTaskInput(row.input);
+			return input === void 0 ? void 0 : {
+				kind: "create",
+				id: row.id,
+				input
+			};
+		}
+		case "update": {
+			if (!exactKeys(row, [
+				"kind",
+				"taskId",
+				"patch"
+			])) return void 0;
+			if (!boundedString(row.taskId, 64) || row.taskId === "") return void 0;
+			const patch = parseTaskUpdatePatch(row.patch);
+			return patch === void 0 ? void 0 : {
+				kind: "update",
+				taskId: row.taskId,
+				patch
+			};
+		}
+		case "delete":
+		case "run":
+		case "confirm-permission":
+			if (!exactKeys(row, ["kind", "taskId"])) return void 0;
+			if (!boundedString(row.taskId, 64) || row.taskId === "") return void 0;
+			return {
+				kind: row.kind,
+				taskId: row.taskId
+			};
+		case "set-schedule": {
+			if (!exactKeys(row, [
+				"kind",
+				"taskId",
+				"patch"
+			])) return void 0;
+			if (!boundedString(row.taskId, 64) || row.taskId === "") return void 0;
+			const patch = record(row.patch);
+			if (patch === void 0 || !exactKeys(patch, ["enabled", "cron"])) return void 0;
+			if (patch.enabled !== void 0 && typeof patch.enabled !== "boolean") return void 0;
+			if (patch.cron !== void 0 && !boundedString(patch.cron, 100)) return void 0;
+			return {
+				kind: "set-schedule",
+				taskId: row.taskId,
+				patch: {
+					...patch.enabled === void 0 ? {} : { enabled: patch.enabled },
+					...patch.cron === void 0 ? {} : { cron: patch.cron }
+				}
+			};
+		}
+		default: return;
+	}
+}
+/** 校验动作信封；非法返回 undefined。 */
+function parseTasksEnvelope(value) {
+	const row = record(value);
+	if (row === void 0 || !exactKeys(row, ["requestId", "action"])) return void 0;
+	if (!boundedString(row.requestId, 64) || row.requestId === "") return void 0;
+	const action = parseTasksAction(row.action);
+	return action === void 0 ? void 0 : {
+		requestId: row.requestId,
+		action
+	};
+}
+//#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 };

package/lib/tasks-schedule.d.ts

@@ -0,0 +1,44 @@
+//#region src/tasks-schedule.d.ts
+/**
+ * 5 段 cron 解析与下次运行时间计算（右侧栏定时任务的调度纯模块）。
+ *
+ * 实现移植自 dsh-web 仓库 dsh-task-board 的 core/schedule.ts（2026-09 已在同机
+ * 验证过 DST/闰年语义），零依赖、框架无关：调度器（service.ts）与 UI 预览
+ * （client 半）共享同一份词汇。语法：五个空白分隔字段 = 分 时 日 月 周；每个
+ * 字段支持星号通配、步进（星号/n）、闭区间 a-b、单值与逗号混合列表；周字段 0/7 均为周日；日与周
+ * 同时受限时按标准 cron 的 OR 语义合并；时区基准为宿主本地时区。非法表达式
+ * parseCron 返回 null，由协议层/UI 拒绝。
+ */
+/** 一条 cron 表达式解析出的各字段匹配集。 */
+interface CronSchedule {
+  minutes: ReadonlySet<number>;
+  hours: ReadonlySet<number>;
+  days: ReadonlySet<number>;
+  months: ReadonlySet<number>;
+  /** 周几 0-6，0 = 周日（输入 7 归一化为 0）。 */
+  weekdays: ReadonlySet<number>;
+  /** 日字段是否为字面 '*'（未受限）。 */
+  dayWildcard: boolean;
+  /** 周字段是否为字面 '*'（未受限）。 */
+  weekdayWildcard: boolean;
+}
+/**
+ * 解析 5 段 cron 表达式。
+ * @returns 各字段匹配集；表达式非法时返回 null。
+ */
+declare function parseCron(expr: string): CronSchedule | null;
+/** 表达式是否可解析。 */
+declare function isValidCron(expr: string): boolean;
+/**
+ * 计算 `fromMs`（ms epoch）之后严格晚于它的下一个匹配时刻，本地时区、分钟粒
+ * 度。返回匹配分钟的起始 ms epoch；日历上永不可能匹配（如 `0 0 30 2 *`）时
+ * 返回 undefined。5 年上限覆盖完整闰年周期，2 月 29 日排期永远可达。
+ *
+ * 直接从解析出的字段集枚举候选 年/月/日/时/分，而非逐分钟扫描（稀疏表达式如
+ * `0 0 29 2 *` 逐分钟要走 ~150 万分钟才到下一个闰日）；墙钟字段构造 + 末次
+ * matches 复检精确保留旧实现的 DST 语义：春季不存在的分钟向前归一化，秋季重
+ * 复小时不会被访问两次。
+ */
+declare function nextRunAtMs(expr: string, fromMs: number): number | undefined;
+//#endregion
+export { CronSchedule, isValidCron, nextRunAtMs, parseCron };

package/lib/tasks-schedule.js

@@ -0,0 +1,166 @@
+//#region src/tasks-schedule.ts
+/** 各字段的闭区间，按 cron 顺序。 */
+const FIELD_RANGES = [
+	[0, 59],
+	[0, 23],
+	[1, 31],
+	[1, 12],
+	[0, 7]
+];
+/**
+* 解析 5 段 cron 表达式。
+* @returns 各字段匹配集；表达式非法时返回 null。
+*/
+function parseCron(expr) {
+	const fields = expr.trim().split(/\s+/);
+	if (fields.length !== 5) return null;
+	const sets = [];
+	for (let index = 0; index < 5; index++) {
+		const bounds = FIELD_RANGES[index];
+		const field = fields[index];
+		const set = /* @__PURE__ */ new Set();
+		if (bounds === void 0 || field === void 0 || !parseField(field, bounds[0], bounds[1], set)) return null;
+		sets.push(set);
+	}
+	const weekdays = /* @__PURE__ */ new Set();
+	for (const day of sets[4]) weekdays.add(day === 7 ? 0 : day);
+	return {
+		minutes: sets[0],
+		hours: sets[1],
+		days: sets[2],
+		months: sets[3],
+		weekdays,
+		dayWildcard: fields[2] === "*",
+		weekdayWildcard: fields[4] === "*"
+	};
+}
+/** 表达式是否可解析。 */
+function isValidCron(expr) {
+	return parseCron(expr) !== null;
+}
+/**
+* 计算 `fromMs`（ms epoch）之后严格晚于它的下一个匹配时刻，本地时区、分钟粒
+* 度。返回匹配分钟的起始 ms epoch；日历上永不可能匹配（如 `0 0 30 2 *`）时
+* 返回 undefined。5 年上限覆盖完整闰年周期，2 月 29 日排期永远可达。
+*
+* 直接从解析出的字段集枚举候选 年/月/日/时/分，而非逐分钟扫描（稀疏表达式如
+* `0 0 29 2 *` 逐分钟要走 ~150 万分钟才到下一个闰日）；墙钟字段构造 + 末次
+* matches 复检精确保留旧实现的 DST 语义：春季不存在的分钟向前归一化，秋季重
+* 复小时不会被访问两次。
+*/
+function nextRunAtMs(expr, fromMs) {
+	const schedule = parseCron(expr);
+	if (schedule === null) return void 0;
+	if (!hasPossibleCalendarDay(schedule)) return void 0;
+	const from = new Date(fromMs);
+	const limitMs = fromMs + 158112e6;
+	const sortedMinutes = [...schedule.minutes].sort((a, b) => a - b);
+	const sortedHours = [...schedule.hours].sort((a, b) => a - b);
+	const sortedMonths = [...schedule.months].sort((a, b) => a - b);
+	let year = from.getFullYear();
+	let month = from.getMonth() + 1;
+	let day = from.getDate();
+	let hour = from.getHours();
+	let minute = from.getMinutes() + 1;
+	while (new Date(year, month - 1, 1, 0, 0, 0, 0).getTime() <= limitMs) {
+		for (const candidateMonth of sortedMonths) {
+			if (candidateMonth < month) continue;
+			const daysInMonth = new Date(year, candidateMonth, 0).getDate();
+			const dayStart = candidateMonth === month ? day : 1;
+			for (let candidateDay = dayStart; candidateDay <= daysInMonth; candidateDay += 1) {
+				if (!dayCandidate(schedule, new Date(year, candidateMonth - 1, candidateDay, 0, 0, 0, 0))) continue;
+				const hourStart = candidateMonth === month && candidateDay === day ? hour : 0;
+				for (const candidateHour of sortedHours) {
+					if (candidateHour < hourStart) continue;
+					const minuteStart = candidateMonth === month && candidateDay === day && candidateHour === hour ? minute : 0;
+					for (const candidateMinute of sortedMinutes) {
+						if (candidateMinute < minuteStart) continue;
+						const candidate = new Date(year, candidateMonth - 1, candidateDay, candidateHour, candidateMinute, 0, 0);
+						const time = candidate.getTime();
+						if (time <= fromMs) continue;
+						if (time > limitMs) return void 0;
+						if (matches(schedule, candidate)) return time;
+					}
+				}
+			}
+		}
+		year += 1;
+		month = 1;
+		day = 1;
+		hour = 0;
+		minute = 0;
+	}
+}
+/** 日/周 OR 闸门：matches 与候选扫描共用。 */
+function dayCandidate(schedule, date) {
+	const dayMatches = schedule.days.has(date.getDate());
+	const weekdayMatches = schedule.weekdays.has(date.getDay());
+	if (schedule.dayWildcard) return weekdayMatches;
+	if (schedule.weekdayWildcard) return dayMatches;
+	return dayMatches || weekdayMatches;
+}
+/** 提前否决日历上不可能的 月/日 组合，省掉多年扫描。 */
+function hasPossibleCalendarDay(schedule) {
+	if (schedule.dayWildcard || !schedule.weekdayWildcard) return true;
+	const maximumDay = /* @__PURE__ */ new Map([
+		[1, 31],
+		[2, 29],
+		[3, 31],
+		[4, 30],
+		[5, 31],
+		[6, 30],
+		[7, 31],
+		[8, 31],
+		[9, 30],
+		[10, 31],
+		[11, 30],
+		[12, 31]
+	]);
+	for (const month of schedule.months) {
+		const maximum = maximumDay.get(month) ?? 0;
+		if ([...schedule.days].some((day) => day <= maximum)) return true;
+	}
+	return false;
+}
+/** 解析单个逗号列表字段到匹配集。 */
+function parseField(field, min, max, out) {
+	if (field === "*") {
+		for (let value = min; value <= max; value++) out.add(value);
+		return true;
+	}
+	for (const part of field.split(",")) {
+		if (part === "") return false;
+		const [range = "", stepRaw] = part.split("/");
+		let low;
+		let high;
+		if (range === "*") {
+			low = min;
+			high = max;
+		} else if (range.includes("-")) {
+			const [a = "", b = ""] = range.split("-");
+			if (a === "" || b === "" || !isDigits(a) || !isDigits(b)) return false;
+			low = Number(a);
+			high = Number(b);
+		} else if (isDigits(range)) {
+			low = Number(range);
+			high = Number(range);
+		} else return false;
+		if (low < min || high > max || low > high) return false;
+		const step = stepRaw === void 0 ? 1 : isDigits(stepRaw) ? Number(stepRaw) : NaN;
+		if (!Number.isInteger(step) || step < 1) return false;
+		for (let value = low; value <= high; value += step) out.add(value);
+	}
+	return true;
+}
+/** 日/周 OR 语义：某一面受限即按该面闸门。 */
+function matches(schedule, date) {
+	if (!schedule.minutes.has(date.getMinutes())) return false;
+	if (!schedule.hours.has(date.getHours())) return false;
+	if (!schedule.months.has(date.getMonth() + 1)) return false;
+	return dayCandidate(schedule, date);
+}
+function isDigits(value) {
+	return /^\d+$/.test(value);
+}
+//#endregion
+export { isValidCron, nextRunAtMs, parseCron };

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.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,9 +18,11 @@
   "license": "PolyForm-Noncommercial-1.0.0",
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "tsdown": "^0.22.0"
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
   },
   "scripts": {
-    "build": "tsdown"
+    "build": "tsdown",
+    "test": "vitest run"
   }
 }