@dshtrading/kit-hk 0.5.0 → 0.6.0

package/assets/skills/indicator-authoring.md

@@ -1,3 +1,7 @@
+---
+name: indicator-authoring
+description: 自定义技术指标创作指南：根据用户自然语言需求生成符合契约的指标代码（TD9/SuperTrend/OBV+MA等），并通过 indicator_author 工具验证与落库。
+---
 # 指标创作指南（Indicator Authoring Guide）
 
 当用户在会话列中用自然语言提出编写或添加技术指标的需求时（例如："帮我写一个 TD9 指标"、"帮我写一个 SuperTrend 指标"、"给 OBV 加一个 34 天均线"），请遵循本指南生成符合 `@dshtrading/indicators` 契约规范的 JavaScript 纯函数代码，并调用 `indicator_author` 工具进行沙箱校验与落库。

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

@@ -1,14 +1,7 @@
+import "./instrument-form.js";
+import "@deepseek-ai/cordis";
 //#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';
 /** 最新行情快照（公共数据，无需凭证）。 */
@@ -423,16 +416,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';
@@ -443,10 +452,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;
 }
 /** 订单回执/状态。 */
@@ -486,9 +503,49 @@ interface TradeFill {
 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 {
@@ -497,13 +554,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）。
    * 可选方法：仅当数据源在同一公共端点里携带基本面字段时实现
@@ -539,11 +595,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>;
@@ -568,6 +654,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>;
 }
 /**
  * Cordis Context 服务键（能力三角色之「声明」）：市场命名空间键由契约包统一声明，
@@ -598,7 +691,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;
@@ -799,4 +892,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, 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, TradingNewsRegistry };
+export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, AuctionSnapshot, BuybackItem, CompanyProfile, CryptoFundamentals, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, DividendItem, DragonTigerItem, FinancialCell, FinancialIndicatorRow, FinancialReportGroup, FinancialReportMatrix, FlashFeedService, ForecastSummary, FundamentalsPackage, HolderNumSummary, InsiderTradeItem, InstitutionalHoldingItem, InstrumentAssetClass, InstrumentContract, InstrumentForm, InstrumentRef, Interval, Kline, LeverageSetting, LimitUpPoolItem, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MainOperationSegment, MarginMode, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewsAggregator, NewsItem, OperatingEfficiency, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, Position, PositionSide, ResearchReportItem, SetLeverageRequest, ShareholderItem, SplitItem, StockFundamentals, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingNewsRegistry };

package/lib/api/lib/instrument-form.d.ts

@@ -0,0 +1 @@
+import "./index.js";

package/lib/index.js

@@ -170,7 +170,7 @@ function renderNewsItem(item) {
 function createGetNewsTool(toolOptions = {}) {
 	return defineTool({
 		name: "hk_get_news",
-		description: "Get recent Hong Kong stock market news, derived from Eastmoney financial fast-news (HK column) filtered to HK-relevant items (HKEX-listed marketId=116 codes or HK keywords). DEGRADED SOURCE — Eastmoney is a unified CN financial feed; HK coverage is PARTIAL (HK news without an HK-listed code or HK keyword is not captured; not a dedicated HK news source). Each item carries source name (东方财富), publish time and a link for traceability; fetches metadata only, never redistributes article bodies. Optionally filter by symbol (HK code, e.g. 00700 / 00700.HK) and by a time window. No credentials required.",
+		description: "Get recent Hong Kong stock news from the Eastmoney fast-news HK column, filtered to HK-relevant items (HKEX marketId=116 or HK keywords). DEGRADED SOURCE — Eastmoney is a unified CN feed; HK coverage is PARTIAL (news without an HK code or keyword is missed), not a dedicated HK source. Each item carries source (东方财富), time and link; metadata only, never article bodies. Optional symbol filter (e.g. 00700 / 00700.HK) and window; no credentials required.",
 		parameters: {
 			symbol: {
 				type: "string",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/kit-hk",
   "description": "Hong Kong market toolkit plugin for dsh-trading: HK risk checklist skill provider and HK fast-news (degraded) / fundamentals tools; runs as an hk-trader preset row (session-scoped)",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/indicators": "0.5.0",
-    "@dshtrading/knowledge": "0.5.0"
+    "@dshtrading/indicators": "0.6.0",
+    "@dshtrading/knowledge": "0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
-    "@dshtrading/api": "0.5.0"
+    "@dshtrading/api": "0.6.0"
   },
   "scripts": {
     "build": "tsdown",