@dshtrading/strategies 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/api/lib/index.d.ts

@@ -0,0 +1,461 @@
+//#region ../api/lib/index.d.ts
+//#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';
+/** 最新行情快照（公共数据，无需凭证）。 */
+interface Ticker {
+  /** 交易对符号，**市场规范词汇**（docs/symbol-vocabulary.md：crypto=BTCUSDT，us=AAPL，cn=600519.SH，hk=00700.HK）。 */
+  readonly symbol: string;
+  /** 标的/公司名称（如“紫光股份”、“苹果”、“腾讯控股”；部分数据源可缺省）。 */
+  readonly name?: string;
+  /** 最新成交价。 */
+  readonly price: number;
+  /** 最优买价（部分数据源可缺省）。 */
+  readonly bid?: number;
+  /** 最优卖价（部分数据源可缺省）。 */
+  readonly ask?: number;
+  /** 24h 成交量（base 资产计）。 */
+  readonly volume?: number;
+  /** 快照时间（epoch ms）。 */
+  readonly timestamp: number;
+  /** 官方昨收（涨跌基准锚点；部分数据源可缺省，缺省时消费方退回日 K 自算）。 */
+  readonly prevClose?: number;
+  /** 相对昨收的涨跌幅（百分比，如 -0.89 表示 -0.89%；部分数据源可缺省）。 */
+  readonly changePercent?: number;
+}
+/** 单根 K 线。 */
+interface Kline {
+  readonly openTime: number;
+  readonly open: number;
+  readonly high: number;
+  readonly low: number;
+  readonly close: number;
+  readonly volume: number;
+  readonly closeTime: number;
+}
+/** 衍生品市场指标快照（持仓量/多空比/资金费等）。 */
+interface DerivativesData {
+  /** 交易对符号，市场规范词汇（如 BTCUSDT 或 BTCUSDT-SWAP）。 */
+  readonly symbol: string;
+  /** 数据来源（如 binance / okx）。 */
+  readonly source: string;
+  /** 未平仓合约量（Open Interest，base 币数或张数）。 */
+  readonly openInterest?: number;
+  /** 未平仓合约总价值（USD 或 quote 计价）。 */
+  readonly openInterestValue?: number;
+  /** 多空人数比（Long/Short Account Ratio）。 */
+  readonly longShortRatio?: number;
+  /** 大户持仓多空比（Top Trader Long/Short Position Ratio）。 */
+  readonly topTraderLongShortRatio?: number;
+  /** 主动买入/卖出量比（Taker Buy/Sell Volume Ratio）。 */
+  readonly takerBuySellRatio?: number;
+  /** 最新资金费率（小数，如 0.0001 表示 0.01%）。 */
+  readonly fundingRate?: number;
+  /** 预测（下一期）资金费率（小数；交易所未发布预测时缺省，issue #54）。 */
+  readonly nextFundingRate?: number;
+  /** 下一期资金费率结算时间（epoch ms，GUI 倒计时用，issue #54）。 */
+  readonly nextFundingTime?: number;
+  /** 标记价格（Mark Price，永续合约；issue #54 基差卡用）。 */
+  readonly markPrice?: number;
+  /** 指数价格（Index Price，现货指数；与 markPrice 配对计算基差）。 */
+  readonly indexPrice?: number;
+  /** 快照时间（epoch ms）。 */
+  readonly timestamp: number;
+}
+/** 衍生品时序数据点（资金费率历史 / OI 历史共用词汇，issue #54）。 */
+interface DerivativesPoint {
+  /** 采样时间（epoch ms）。 */
+  readonly time: number;
+  /** 采样值（费率序列为小数费率；OI 序列单位与快照 openInterest 同语义）。 */
+  readonly value: number;
+}
+/**
+ * 衍生品历史序列（GUI「衍生品」页签趋势卡用，issue #54）：
+ * 资金费率历史 + 未平仓量历史，时间一律升序（旧→新，与 K 线序列同向）。
+ * 可选方法 getDerivativesHistory 的返回面；任一序列不可得时该字段缺省，
+ * 消费方按卡降级（隐藏趋势图、保留快照读数）。
+ */
+interface DerivativesHistory {
+  /** 交易对符号，市场规范词汇（如 BTCUSDT-SWAP）。 */
+  readonly symbol: string;
+  /** 数据来源（如 binance / okx）。 */
+  readonly source: string;
+  /** 资金费率历史（时间升序，value 为小数费率）。 */
+  readonly fundingRates?: DerivativesPoint[];
+  /** OI 历史（时间升序，value 单位与 DerivativesData.openInterest 同语义）。 */
+  readonly openInterest?: DerivativesPoint[];
+}
+/** 股票市场标的基本面与财务估值快照（US/CN/HK）。 */
+interface StockFundamentals {
+  /** 标的规范符号（如 AAPL, 600519.SH, 00700.HK）。 */
+  readonly symbol: string;
+  /** 公司/标的名称。 */
+  readonly name?: string;
+  /** 总市值（本位币计价）。 */
+  readonly marketCap?: number;
+  /** 流通市值（A 股/港股适用）。 */
+  readonly floatMarketCap?: number;
+  /** 滚动市盈率 PE (TTM)。 */
+  readonly peTtm?: number;
+  /** 静态市盈率 PE (静)。 */
+  readonly peStatic?: number;
+  /** 动态/预测市盈率 Forward / Dynamic PE。 */
+  readonly peDynamic?: number;
+  /** 市净率 PB。 */
+  readonly pb?: number;
+  /** 市销率 PS。 */
+  readonly ps?: number;
+  /** 每股收益 EPS。 */
+  readonly eps?: number;
+  /** 每股净资产 BPS。 */
+  readonly bps?: number;
+  /** 股息率（小数，如 0.015 表示 1.5%）。 */
+  readonly dividendYield?: number;
+  /** 换手率（小数或百分比）。 */
+  readonly turnoverRate?: number;
+  /** 振幅（百分比）。 */
+  readonly amplitudePercent?: number;
+  /** 涨停价（A 股适用）。 */
+  readonly limitUpPrice?: number;
+  /** 跌停价（A 股适用）。 */
+  readonly limitDownPrice?: number;
+  /** 52 周最高价。 */
+  readonly fiftyTwoWeekHigh?: number;
+  /** 52 周最低价。 */
+  readonly fiftyTwoWeekLow?: number;
+  /** 快照时间（epoch ms）。 */
+  readonly timestamp: number;
+}
+/** 盘口档位（价格 + 挂单量，量单位=标的基准单位：股票股、crypto 币）。 */
+interface OrderbookLevel {
+  readonly price: number;
+  readonly amount: number;
+}
+/**
+ * 盘口快照（GUI「盘口」竖栏用，issue #39）。实现保证：bids 按价格降序（买一在前）、
+ * asks 按价格升序（卖一在前），档位数由数据源决定（沪深五档、crypto 常见 5~20 档）。
+ */
+interface Orderbook {
+  readonly symbol: string;
+  readonly bids: readonly OrderbookLevel[];
+  readonly asks: readonly OrderbookLevel[];
+  /** 快照时间（epoch ms）。 */
+  readonly timestamp: number;
+}
+/** 逐笔成交（taker 视角：side 为主动方；流水单条）。 */
+interface TradeTick {
+  /** 交易所成交 id（字符串透传，排序稳定性由时间戳保证）。 */
+  readonly id: string;
+  readonly symbol: string;
+  readonly price: number;
+  /** 成交量（基准单位，同 OrderbookLevel.amount）。 */
+  readonly amount: number;
+  /** 主动方向：buy=主动买（外盘）、sell=主动卖（内盘）；数据源缺方向时 unknown。 */
+  readonly side: 'buy' | 'sell' | 'unknown';
+  readonly timestamp: number;
+}
+type PositionSide = 'long' | 'short';
+/** 持仓快照。 */
+interface Position {
+  readonly symbol: string;
+  readonly side: PositionSide;
+  /** 仓位数量（正数；方向由 side 表达）。 */
+  readonly size: number;
+  readonly entryPrice: number;
+  readonly markPrice?: number;
+  readonly unrealizedPnl?: number;
+  readonly leverage?: number;
+  readonly timestamp: number;
+}
+type OrderSide = 'buy' | 'sell';
+type OrderType = 'limit' | 'market';
+type OrderStatus = 'new' | 'partially_filled' | 'filled' | 'canceled' | 'rejected' | 'expired';
+/** 下单请求（安全闸门：dryRun 缺省视为 true）。 */
+interface OrderRequest {
+  readonly symbol: string;
+  readonly side: OrderSide;
+  readonly type: OrderType;
+  readonly quantity: number;
+  /** limit 单必填。 */
+  readonly price?: number;
+  /** 缺省/true 时仅模拟，不触碰交易所。实盘还受插件 liveTrading 闸门与 approval 约束 [S4]。 */
+  readonly dryRun?: boolean;
+}
+/** 订单回执/状态。 */
+interface Order {
+  readonly id: string;
+  readonly symbol: string;
+  readonly side: OrderSide;
+  readonly type: OrderType;
+  readonly status: OrderStatus;
+  readonly price?: number;
+  readonly quantity: number;
+  readonly filledQuantity?: number;
+  /** 本次订单是否为模拟单（回执必须显式回带，防 dry-run 语义丢失）。 */
+  readonly dryRun: boolean;
+  readonly timestamp: number;
+}
+interface AccountBalance {
+  readonly asset: string;
+  readonly free: number;
+  readonly locked: number;
+}
+/** 成交流水单条（GUI 交易台「成交历史」用，issue #40）。 */
+interface TradeFill {
+  /** 交易所成交 id。 */
+  readonly id: string;
+  readonly symbol: string;
+  readonly side: OrderSide;
+  readonly price: number;
+  /** 成交量（base 币数）。 */
+  readonly amount: number;
+  /** 手续费（绝对值，币种由 feeAsset 表达）。 */
+  readonly fee?: number;
+  readonly feeAsset?: string;
+  readonly timestamp: number;
+}
+/** 订阅句柄：dispose 即退订（连接器用 ctx.effect/cordis 生命周期托管）。 */
+interface Disposable {
+  dispose(): void;
+}
+/**
+ * 行情服务契约：由市场连接器实现，注册到按市场命名空间的 ctx 键（如 ctx.tradingCrypto）。
+ * 符号词汇（2026-08-31 规范，docs/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
+ * 输出 `symbol` 一律市场规范形——消费方（GUI/Agent/工作流）与数据源方言解耦。
+ */
+interface MarketDataService {
+  getTicker(symbol: string): Promise<Ticker>;
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker) => void): Disposable;
+  /**
+   * 查询本市场/交易所支持的全部标的名册（动态全集，Issue #15）。
+   * 输出 `symbol` 一律市场规范词汇（docs/symbol-vocabulary.md）。
+   * 可选方法：无公开全集端点的数据源（如 tencent/yahoo/stooq）可缺省或由桥/前端回退。
+   */
+  listInstruments?(): Promise<Array<{
+    symbol: string;
+    name?: string;
+  }>>;
+  /**
+   * 标的基本面与估值快照（GUI「基本面」页签用，2026-09-02）。
+   * 可选方法：仅当数据源在同一公共端点里携带基本面字段时实现
+   * （腾讯行情行 cn/hk 已实现）；未实现的市场由消费方降级为派生数据（日K 52 周高低）。
+   * 输出 `symbol` 一律市场规范词汇（docs/symbol-vocabulary.md）。
+   */
+  getFundamentals?(symbol: string): Promise<StockFundamentals>;
+  /**
+   * 衍生品市场指标快照（GUI「衍生品」面板用，issue #38，2026-09-02）：持仓量/
+   * 多空比/资金费等微观结构数据，crypto 永续合约市场专属。
+   * 可选方法：现货/股票数据源不实现；未实现时消费方直接隐藏面板（不降级不报错）。
+   * 入参接受规范形与连接器原生形，输出 `symbol` 一律规范词汇 SWAP 形（BTCUSDT-SWAP）。
+   */
+  getDerivatives?(symbol: string): Promise<DerivativesData>;
+  /**
+   * 衍生品历史序列（GUI「衍生品」页签趋势卡用，issue #54）：资金费率历史 +
+   * OI 历史，时间升序。可选方法：无公开历史端点的数据源不实现；未实现或失败
+   * 时消费方隐藏趋势图、保留快照读数（与快照同族的降级纪律）。
+   * 入参接受规范形与连接器原生形，输出 symbol 一律规范词汇 SWAP 形。
+   */
+  getDerivativesHistory?(symbol: string): Promise<DerivativesHistory>;
+  /**
+   * 盘口快照（GUI「盘口」竖栏用，issue #39）：档位词汇见 Orderbook。可选方法：
+   * 数据源无盘口能力时不实现（如 stooq/yahoo、腾讯 r_hk 港股行档位全 0）。
+   * 入参接受规范形与连接器原生形，输出 `symbol` 一律市场规范词汇。
+   */
+  getOrderbook?(symbol: string): Promise<Orderbook>;
+  /**
+   * 最近逐笔成交流水（GUI「分笔」用，issue #39）：取最近 limit 笔（缺省 ≤50），
+   * **时间升序（旧→新）**，与 K 线序列同向；方向缺省的数据源 side='unknown'。
+   * 可选方法：无公共逐笔端点的数据源（腾讯沪深行情行）不实现。
+   */
+  getRecentTrades?(symbol: string, limit?: number): Promise<TradeTick[]>;
+}
+/**
+ * 交易服务契约：placeOrder 默认 dry-run；实盘前必须过插件 liveTrading 开关与
+ * ctx.approval.request（交互形态；headless 下 ask=deny，fail-closed [S4]）。
+ *
+ * R3（okx 切片 2026-08-29）修订：cancelOrder 增加可选 symbol、新增 getOrder——
+ * OKX 按 (instId, ordId) 双键定位订单，单参 id 形态不够；无其他实现方，扩展向后兼容。
+ */
+interface TradeService {
+  placeOrder(req: OrderRequest): Promise<Order>;
+  /** 撤单。symbol 可选：按 (symbol, id) 双键定位订单的交易所（如 OKX）必须提供。 */
+  cancelOrder(id: string, symbol?: string): Promise<void>;
+  /** 查询单笔订单状态（按 (symbol, id) 双键）。 */
+  getOrder(symbol: string, id: string): Promise<Order>;
+  getPositions(): Promise<Position[]>;
+  /**
+   * 账户余额快照（issue #40 GUI 交易台；只读，需凭证）。
+   * 可选方法：实现方已有只读余额面时实现（connector-okx 的 crypto_get_balance 同源）。
+   */
+  getBalances?(): Promise<AccountBalance[]>;
+  /**
+   * 当前挂单列表（issue #40 GUI 交易台；只读，需凭证）。
+   * 可选方法：无批量挂单端点的实现方可缺省（GUI 隐藏挂单区）。
+   * 输出 `symbol` 一律市场规范词汇；status 只含 new / partially_filled。
+   */
+  listOpenOrders?(symbol?: string): Promise<Order[]>;
+  /**
+   * 最近成交流水（issue #40 GUI 交易台；只读，需凭证）。
+   * 可选方法：时间升序（旧→新），最多 limit 条（缺省 ≤50）。
+   */
+  listTradeFills?(symbol?: string, limit?: number): Promise<TradeFill[]>;
+}
+/**
+ * Cordis Context 服务键（能力三角色之「声明」）：市场命名空间键由契约包统一声明，
+ * 连接器 provide、消费方 inject 时获得完整类型。此处仅类型增强——本包保持
+ * 零运行时依赖，不产生任何 JS 输出。
+ */
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** crypto 市场行情服务（由 Binance 连接器以公共 REST 提供，无需凭证）。 */
+    tradingCryptoMarketData: MarketDataService;
+    /** us 市场行情服务（由 Stooq 连接器以公共 CSV 端点提供，无需凭证；us 复制 2026-08-31 补齐）。 */
+    tradingUsMarketData: MarketDataService;
+    /** cn 市场行情服务（由腾讯连接器以公共端点提供，无需凭证；cn+hk 切片 2026-08-31 补齐）。 */
+    tradingCnMarketData: MarketDataService;
+    /** hk 市场行情服务（由腾讯连接器同包双实例提供，config.market 分流；cn+hk 切片 2026-08-31 补齐）。 */
+    tradingHkMarketData: MarketDataService;
+    /**
+     * crypto 市场交易服务（R3 2026-08-29 补齐，crypto 市场第一个真实 TradeService）：
+     * 由 connector-okx 实现（签名 demo/live 下单），与 connector-binance 经
+     * Config.enabled 互斥激活同一 tradingCryptoMarketData 键时一并 provide。
+     */
+    tradingCryptoTrade: TradeService;
+    /**
+     * 交易服务注册表（issue #40 GUI 交易台，@dshtrading/api 类型声明）：
+     * 与 tradingMarketDataRegistry 同构的宿主平面注册面——交易连接器 host 面数据行
+     * 注册，GUI 桥按路由当前值惰性解析。**注册不改变安全语义**：placeOrder 的
+     * 服务缝闸门（dryRun 缺省 true + liveTrading 显式开关）随服务实例生效；
+     * GUI 桥只放行 dry-run 下单与只读查询，实盘路径仍走 Agent 工具的 base 审批闸门。
+     */
+    tradingTradeRegistry: TradeRegistry;
+    /**
+     * 市场路由服务（R5 2026-08-29 补齐，@dshtrading/router 提供）：
+     * 连接器 apply 时 consult activeProvider(market) 决定是否激活——用户设置
+     * dshtrading.markets.<market>.provider 选谁谁激活（docs/exchange-routing.md）。
+     */
+    tradingMarketRouter: MarketRouterService;
+    /**
+     * 行情服务注册表（2026-08-30 注册表模式定稿，@dshtrading/router 同插件提供）：
+     * 连接器 host 面数据行注册，GUI 行情桥按路由当前值惰性解析（热切换）。
+     */
+    tradingMarketDataRegistry: MarketDataRegistry;
+    /**
+     * 新闻聚合器注册表（Issue #37，@dshtrading/router 同插件提供）：
+     * 各市场 Kit apply 时注册 aggregateNews 纯函数，GUI 行情桥按市场获取。
+     */
+    tradingNewsRegistry: TradingNewsRegistry;
+  }
+}
+/**
+ * 行情服务注册表契约（router 插件提供，2026-08-30 注册表模式定稿）：
+ * 连接器 host 面数据行不再互斥式 provide 市场键，而是全部注册进本注册表；
+ * 消费方（GUI 行情桥）经 active() 按路由当前值惰性解析——settings 变更即刻生效
+ * （GUI 热切换），无 watch、无进程重启。preset 平面不走注册表：会话内数据源
+ * 一致性是有意语义，切交易所对会话 = 新建会话生效（docs/exchange-routing.md §2.2）。
+ *
+ * 与 tradeProvider 预留的衔接：本注册表只承载 MarketDataService；数据/交易分离
+ * 落地时 TradeService 走独立注册面（不复用本键），铁律 #4 到时再抽象。
+ */
+interface MarketDataRegistration {
+  /** 市场 slug（crypto/us/cn/hk；开放词汇，新市场 = 新键）。 */
+  readonly market: string;
+  /** 提供者 slug（binance/okx/…；开放词汇，第三方连接器可注册新 slug）。 */
+  readonly provider: string;
+  readonly service: MarketDataService;
+}
+interface MarketDataRegistry {
+  /**
+   * 注册一个市场的某 provider 行情服务；同 (market, provider) 重复注册抛错
+   * （配置错误必须响亮）。返回注销函数（调用方包进 ctx.effect 随 fiber 注销）。
+   */
+  register(market: string, provider: string, service: MarketDataService): () => void;
+  /**
+   * 路由裁决后的当前激活注册项：router 选中的 provider 已注册 → 返回之；
+   * 选中了但未注册（包未装/enabled=false）→ undefined（调用方面向用户报错，
+   * 不静默降级到别家——用户设置是权威）；router 无该市场路由（未知市场键）
+   * 且恰好一个注册项 → 返回之（新市场零配置可用）；否则 undefined。
+   */
+  active(market: string): MarketDataRegistration | undefined;
+  /** 某市场全部注册项（诊断/设置 UI 展示用）。 */
+  list(market: string): readonly MarketDataRegistration[];
+}
+/** 交易服务注册项（tradingTradeRegistry 的条目，issue #40）。 */
+interface TradeRegistration {
+  readonly market: string;
+  readonly provider: string;
+  readonly service: TradeService;
+}
+/**
+ * 交易服务注册表（router 插件同款注册模式，issue #40）：交易连接器在 host 面
+ * 数据行注册（凭证经 ctx.credentials / 环境变量解析，缺失时只读方法 fail-closed
+ * 报 TRADING_CREDENTIALS_MISSING）；注册面本身不做安全裁决——闸门在服务缝
+ * （placeOrder 三态）与桥层（GUI 只放行 dry-run）。
+ */
+interface TradeRegistry {
+  register(market: string, provider: string, service: TradeService): () => void;
+  active(market: string): TradeRegistration | undefined;
+  list(market: string): readonly TradeRegistration[];
+}
+/**
+ * 市场路由服务契约（router 插件提供）：按市场查询当前激活的数据/交易所提供方。
+ * 用户设置（dshtrading namespace，settings.yaml）是权威；无设置时 = 组合默认值
+ * （现状零变化）。供应商取值与连接器的 provider slug 比对，相符者激活。
+ */
+interface MarketRouterService {
+  /** 某市场当前激活的 provider slug（settings resolved：用户层赢，缺省 base 默认）。 */
+  activeProvider(market: string): string | undefined;
+  /** 订阅激活变化（settings commit 驱动）。 */
+  watch(cb: (next: string | undefined, prev: string | undefined) => void): () => void;
+}
+/** 新闻/快讯条目（各市场 Kit 统一输出形状）。 */
+interface NewsItem {
+  /** 来源标识（如 'eastmoney'、'yahoo'、'googlenews'、'binance'、'coindesk' 等）。 */
+  readonly source: string;
+  /** 新闻/快讯标题。 */
+  readonly title: string;
+  /** 详情页 URL。 */
+  readonly url: string;
+  /** ISO 8601 发布时间。 */
+  readonly publishedAt: string;
+  /** 关联标的代码（可选，格式随源不同）。 */
+  readonly relatedCodes?: readonly string[];
+}
+/** 新闻聚合请求选项。 */
+interface AggregateNewsOptions {
+  /** 输出条数上限（1~50，默认 20）。 */
+  limit?: number | undefined;
+  /** 时间窗口（小时，1~168，默认 24）。 */
+  windowHours?: number | undefined;
+  /** 按标的代码过滤（可选）。 */
+  symbol?: string | undefined;
+  /** CryptoPanic API token（仅 crypto 市场使用，可选）。 */
+  cryptoPanicKey?: string | undefined;
+}
+/** 新闻聚合结果。 */
+interface AggregateNewsResult {
+  /** 按发布时间倒序的新闻条目。 */
+  readonly items: readonly NewsItem[];
+  /** 失败的数据源名称（fail-soft 容错：可用源正常返回，不可用源记录在此）。 */
+  readonly unavailable: readonly string[];
+}
+/** 新闻聚合器函数签名（各 Kit 导出的 aggregateNews 符合此形状）。 */
+type NewsAggregator = (options?: AggregateNewsOptions) => Promise<AggregateNewsResult>;
+/** 新闻聚合器注册表契约（Issue #37，router 插件提供）。 */
+interface TradingNewsRegistry {
+  register(market: string, aggregator: NewsAggregator): () => void;
+  get(market: string): NewsAggregator | undefined;
+  markets(): string[];
+}
+//#endregion
+export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, Interval, Kline, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewsAggregator, NewsItem, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, Position, PositionSide, StockFundamentals, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingNewsRegistry };

package/lib/custom-fs.d.ts

@@ -0,0 +1,5 @@
+import { CustomStrategyStore } from "./custom.js";
+//#region src/custom-fs.d.ts
+declare function createFileCustomStrategyStore(filePath: string): CustomStrategyStore;
+//#endregion
+export { createFileCustomStrategyStore };

package/lib/custom-fs.js

@@ -0,0 +1,72 @@
+import { dirname } from "node:path";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+//#region src/custom-fs.ts
+/**
+* 文件持久化版自定义策略存储（Node.js 宿主侧使用，落 ~/.dsh/strategies/custom.json）。
+*
+* 与 indicators/src/custom-fs.ts 同款 tmp + rename 原子写入模式（issue #31 规格）。
+*/
+function createFileCustomStrategyStore(filePath) {
+	let cache = null;
+	async function load() {
+		if (cache !== null) return cache;
+		try {
+			const content = await readFile(filePath, "utf8");
+			const parsed = JSON.parse(content);
+			const map = /* @__PURE__ */ new Map();
+			if (Array.isArray(parsed)) {
+				for (const item of parsed) if (item && typeof item.id === "string") map.set(item.id, item);
+			}
+			cache = map;
+			return map;
+		} catch (err) {
+			if (err?.code !== "ENOENT") console.error(`[dsh-trading/strategies] failed to read custom strategies from ${filePath}:`, err);
+			cache = /* @__PURE__ */ new Map();
+			return cache;
+		}
+	}
+	async function flush(map) {
+		const dir = dirname(filePath);
+		const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+		const data = JSON.stringify([...map.values()], null, 2);
+		try {
+			await mkdir(dir, { recursive: true });
+			await writeFile(tmpPath, data, "utf8");
+			let lastError;
+			for (let attempt = 0; attempt < 3; attempt++) try {
+				await rename(tmpPath, filePath);
+				return;
+			} catch (err) {
+				if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
+				lastError = err;
+				await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+			}
+			throw lastError;
+		} catch (error) {
+			console.error(`[dsh-trading/strategies] failed to atomic flush custom strategies to ${filePath}:`, error);
+			await unlink(tmpPath).catch(() => {});
+			throw error;
+		}
+	}
+	return {
+		async list() {
+			return [...(await load()).values()];
+		},
+		async get(id) {
+			return (await load()).get(id);
+		},
+		async save(record) {
+			const map = await load();
+			map.set(record.id, { ...record });
+			await flush(map);
+		},
+		async remove(id) {
+			const map = await load();
+			const existed = map.delete(id);
+			if (existed) await flush(map);
+			return existed;
+		}
+	};
+}
+//#endregion
+export { createFileCustomStrategyStore };

package/lib/custom.d.ts

@@ -0,0 +1,28 @@
+import { StrategyHorizon } from "./types.js";
+//#region src/custom.d.ts
+interface CustomStrategyRecord {
+  /** 策略唯一 ID，如 'ema-stop-takeprofit'（校验器保留 6 大范式 id） */
+  id: string;
+  /** 策略展示名，如 '双均线止损止盈' */
+  title: string;
+  /** 策略期限词汇：'short' 短线 | 'swing' 波段 | 'long' 长线 */
+  horizon: StrategyHorizon;
+  /** 一句话思路（UI 名册与对话卡片展示） */
+  summary: string;
+  /** 参数规格数组（StrategyParamSpec[]）的 JSON 字符串 */
+  paramsJson: string;
+  /** JavaScript 纯函数源码，接收 (bars, params) 返回 StrategySignal[] */
+  computeSource: string;
+  /** 创建时间戳 */
+  createdAt: number;
+}
+interface CustomStrategyStore {
+  list(): Promise<CustomStrategyRecord[]>;
+  get(id: string): Promise<CustomStrategyRecord | undefined>;
+  save(record: CustomStrategyRecord): Promise<void>;
+  remove(id: string): Promise<boolean>;
+}
+/** 内存版自定义策略存储（纯浏览器与单测用）。 */
+declare function createMemoryCustomStrategyStore(initial?: CustomStrategyRecord[]): CustomStrategyStore;
+//#endregion
+export { CustomStrategyRecord, CustomStrategyStore, createMemoryCustomStrategyStore };

package/lib/custom.js

@@ -0,0 +1,16 @@
+//#region src/custom.ts
+/** 内存版自定义策略存储（纯浏览器与单测用）。 */
+function createMemoryCustomStrategyStore(initial = []) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of initial) map.set(item.id, item);
+	return {
+		list: async () => [...map.values()],
+		get: async (id) => map.get(id),
+		save: async (record) => {
+			map.set(record.id, { ...record });
+		},
+		remove: async (id) => map.delete(id)
+	};
+}
+//#endregion
+export { createMemoryCustomStrategyStore };

package/lib/engine.d.ts

@@ -0,0 +1,6 @@
+import { BacktestOptions, BacktestResult, StrategyDefinition } from "./types.js";
+import { Kline } from "@dshtrading/indicators";
+//#region src/engine.d.ts
+declare function run(bars: readonly Kline[], strategy: StrategyDefinition, paramsOverride?: Record<string, number>, options?: BacktestOptions): BacktestResult;
+//#endregion
+export { run };