@dshtrading/kit-hk 0.2.1 → 0.4.0

package/assets/skills/hk-risk-checklist.md

@@ -1 +1,25 @@
-../../../packages/kit-hk/assets/skills/hk-risk-checklist.md
+---
+name: hk-risk-checklist
+description: 港股交易风控检查清单：开仓前逐项核对 T+0 回转与无涨跌幅限制、碎股（ board lot）与手数、供股/配股摊薄、窝轮牛熊证杠杆与强制收回、港元汇率与港股通差异。
+---
+
+# 港股风控检查清单（hk-risk-checklist）
+
+开仓前逐项核对，任何一项不过则不建仓：
+
+**依据闸门（先过）**：每条开仓理由必须能指回锚点（工具名 + 参数 + 数值 + 数据时间 / 公告或章节 / facts 条目 / 知识卡 id + updatedAt）。只有 C/D/E 级来源、或写不出锚点的理由，按证据不足处理（insufficient），不得作为入场依据。
+
+1. **T+0 回转与无涨跌幅**：港股当日可无限次回转买卖（T+0），且**没有涨跌停板**——个股单日可以 ±30% 甚至更多，停牌复牌跳空无限制。止损单不能保证按止损价成交，隔夜仓必须有明确的仓位上限与最坏情景预算。T+0 不等于必须高频：无涨跌幅市场里频繁回转的交易成本（佣金+印花税+买卖价差）会迅速吞噬收益。
+2. **碎股与手数（board lot）**：港股每只股票有各自的每手股数（如腾讯 100 股/手，部分仙股 2000/10000 股/手），下单数量必须是每手的整数倍；**非整手为碎股（odd lot）**，碎股只能经碎股市场议价卖出，成交价通常折让、买入通常溢价。下单前核对该股 board lot（本插件 hk 行情不含手数，需自行查询），数量取整手。
+3. **供股 / 配股摊薄**：港股再融资门槛低、节奏快——供股（rights issue，向全体股东按比例折价配售，除净后正股价同步折价）与配股（placement，向特定投资者）都可能在无预警下公告。停牌一两天的配股公告、深度折价供股会直接打穿止损位；持有高负债、频繁再融资的公司必须预设摊薄情景。收到供股权利：供（继续投钱）、卖（-rights 权证）、放任（被摊薄）三选一，不作为也是决策。
+4. **窝轮（权证）/牛熊证警示**：Warrant（窝轮）与 CBBC（牛熊证）是发行商创设的杠杆衍生品，**不是正股**：有时间价值损耗（窝轮每日衰减）、发行商买卖价差宽、牛熊证触及收回价（call price）即**强制收回、剩余价值可能为零**。核清单：识别代码形态（窝轮 5 位数字、牛熊证带特殊编号）与到期日；不懂止损机制与街货比就不碰；严禁把衍生品仓位当作正股持仓过夜。
+5. **港元汇率与港股通差异**：港股以 HKD 计价，人民币投资者的最终损益叠加 CNH/HKD 汇率波动。经港股通持有：股息红利税 20%（H股 28% 口径另有规定）、交易汇率按结算汇兑比率每日浮动、不可参与融资融券与部分公司行为（如港股通标的供股需另行申报，逾期视同放弃）。碎股不可经港股通卖出（须自行处理）。
+6. **基本面估值与新闻**：调用 `hk_get_fundamentals` 核对总市值、市盈率 PE(TTM)、市净率 PB、股息率与 52 周区间；调用 `hk_get_news` 检查港股相关快讯（降级源），排查供配股、回购与财报公告；不做无基本面支撑的长尾仙股。
+7. **流动性与仙股**：港股头部流动性集中于恒指成分，长尾中小票日成交额极低、买卖价差可达百分之几，仙股（股价 < 1 HKD）有单日腰斩与庄股崩盘史。仓位上限按「占该股日均成交额的比例」设定，小票降低上限；不做无基本面的低价股博弈。
+8. **对手侧情景**：价格反向运行到止损位后，是否接受该笔亏损并继续执行原计划（无涨跌幅市场跳空会直接穿越止损）；连续两笔止损即当日停手复盘（T+0 允许报复性交易，纪律上必须自我设限）。
+
+退出纪律：
+- 达到目标位或止损位按计划执行；移动止损只朝有利方向。
+- 财报、供股公告窗口前重估隔夜仓：停牌期间无法止损，不确定就减仓。
+
+> 本清单是方法论，不构成投资建议。行情与下单工具均为 dry-run 起步，实盘需显式开关与审批（dsh-trading 铁律 #3）；行情数据来自腾讯公共端点（无官方授权），个人使用边界以腾讯服务条款为准。

package/assets/skills/knowledge-curation.md

@@ -30,6 +30,8 @@ description: 财经观点沉淀与知识库策展指南：基于 Content Insight
   - `medium`：核心逻辑有参考价值，但部分数据存在滞后或口误出入；
   - `low`：存在重大关键事实失准或关键数据无法核实。
 
+> **分层说明（勿混用）**：卡片 `factCheck` 三桶是**素材级**核查记录（这条声称被核实到什么程度）；结论级证据契约的 `supported` / `contradicted` / `mixed` / `insufficient` 四态是**结论级**判定（这条结论能否成立）。卡片字段不因四态改名；引用卡片时按证据契约归入 C/D 级线索，不得单独支撑 `supported` 结论。
+
 ---
 
 ## 3. 标准策展 SOP

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

@@ -584,6 +584,10 @@ declare module '@deepseek-ai/cordis' {
     tradingCnMarketData: MarketDataService;
     /** hk 市场行情服务（由腾讯连接器同包双实例提供，config.market 分流；cn+hk 切片 2026-08-31 补齐）。 */
     tradingHkMarketData: MarketDataService;
+    /** futures 市场行情服务（由同花顺期货连接器提供，issue #97；日K + 当日分时聚合）。 */
+    tradingFuturesMarketData: MarketDataService;
+    /** 全球品种行情（global 市场：大宗/外汇/海外指数；@dshtrading/connector-jin10 dataplane 行提供）。 */
+    tradingGlobalMarketData: MarketDataService;
     /**
      * crypto 市场交易服务（R3 2026-08-29 补齐，crypto 市场第一个真实 TradeService）：
      * 由 connector-okx 实现（签名 demo/live 下单），与 connector-binance 经
@@ -614,6 +618,10 @@ declare module '@deepseek-ai/cordis' {
      * 各市场 Kit apply 时注册 aggregateNews 纯函数，GUI 行情桥按市场获取。
      */
     tradingNewsRegistry: TradingNewsRegistry;
+    /** 跨市场快讯源（@dshtrading/connector-jin10 提供；缺席 = 未安装快讯连接器）。 */
+    tradingFlashFeed: FlashFeedService;
+    /** 宏观/利率源（@dshtrading/connector-jin10 提供；缺席 = 未安装金十连接器）。 */
+    tradingMacroFeed: MacroFeedService;
   }
 }
 /**
@@ -689,6 +697,8 @@ interface NewsItem {
   readonly publishedAt: string;
   /** 关联标的代码（可选，格式随源不同）。 */
   readonly relatedCodes?: readonly string[];
+  /** 热度等级（可选；金十快讯网页版 火/热/沸/爆，其他源不填）。 */
+  readonly hot?: string;
 }
 /** 新闻聚合请求选项。 */
 interface AggregateNewsOptions {
@@ -700,6 +710,11 @@ interface AggregateNewsOptions {
   symbol?: string | undefined;
   /** CryptoPanic API token（仅 crypto 市场使用，可选）。 */
   cryptoPanicKey?: string | undefined;
+  /**
+   * 启用的新闻/公告源 id 列表（issue #96 源配置化；各 kit 的 NewsSource 词汇）。
+   * 缺省 = 该市场全部默认源；空数组 = 显式关闭（返回空结果）。
+   */
+  sources?: readonly string[] | undefined;
 }
 /** 新闻聚合结果。 */
 interface AggregateNewsResult {
@@ -710,6 +725,73 @@ interface AggregateNewsResult {
 }
 /** 新闻聚合器函数签名（各 Kit 导出的 aggregateNews 符合此形状）。 */
 type NewsAggregator = (options?: AggregateNewsOptions) => Promise<AggregateNewsResult>;
+/**
+ * 跨市场快讯源契约（2026-09-13 金十接入）：host 平面由快讯连接器 provide
+ * tradingFlashFeed，GUI 快讯面板（桥 /dshtrading/api/flash）与 agent 快讯工具
+ * 共用同一取数实现；服务缺席 = 未安装/未启用该数据源 → 消费方报
+ * TRADING_NOT_IMPLEMENTED，绝不把「没有数据源」伪装成「没有快讯」。
+ */
+interface FlashFeedService {
+  /**
+   * 最新快讯流（cursor 翻页）；条目只含元数据（标题/时间/链接）。
+   * `hot` 非空时按热度等级服务端过滤（金十网页版 火/热/沸/爆）。
+   */
+  listFlash(options?: {
+    cursor?: string | undefined;
+    limit?: number | undefined;
+    hot?: readonly string[] | undefined;
+  }): Promise<{
+    readonly items: readonly NewsItem[];
+    readonly nextCursor?: string | undefined;
+    readonly hasMore: boolean;
+  }>;
+  /** 关键词搜快讯（上游一次性返回、不支持翻页）。 */
+  searchFlash(keyword: string, limit?: number | undefined): Promise<readonly NewsItem[]>;
+}
+/**
+ * 宏观经济日历条目（金十当周经济数据，2026-09-15）：数值均为上游快照原样字符串，
+ * `actual` 缺省 = 未公布。
+ */
+interface MacroCalendarEntry {
+  /** ISO 8601 公布时间（东八区解释，同 NewsItem 口径）。 */
+  readonly publishedAt: string;
+  /** 重要度（上游 star，0–5）。 */
+  readonly star: number;
+  /** 地区（标题前缀推断，如 美国/日本/中国；未识别 = 空串）。 */
+  readonly region: string;
+  readonly title: string;
+  readonly previous?: string;
+  readonly consensus?: string;
+  readonly actual?: string;
+  readonly revised?: string;
+  /** 上游公布影响词（利多/利空/影响较小…；原样透传）。 */
+  readonly affect?: string;
+}
+/** 央行最新利率条目（金十网页版，2026-09-15）。 */
+interface MacroRateEntry {
+  /** 地区（flag 名推断，如 美国/日本/中国；未识别 = 空串）。 */
+  readonly region: string;
+  readonly bankName: string;
+  /** 最新利率（上游原样字符串，如 "3.75"/"0"）。 */
+  readonly rate: string;
+  /** 公布日（上游原样 YYYY-MM-DD）。 */
+  readonly publishedAt: string;
+  /** 所属指标名（如「美联储利率决定(上限)」；部分央行缺省）。 */
+  readonly indicatorName?: string;
+}
+/**
+ * 宏观/利率源契约（2026-09-15 金十接入）：host 平面由金十连接器 provide
+ * tradingMacroFeed，GUI 宏观面板（桥 /dshtrading/api/macro/*）消费；服务缺席 =
+ * 未安装/未启用该数据源 → 消费方报 TRADING_NOT_IMPLEMENTED，绝不把「没有数据源」
+ * 伪装成「没有数据」。日历走官方 MCP（list_calendar），利率走网页版公开接口
+ * （spikes/impl-jin10-macro-rates/EVIDENCE.md）。
+ */
+interface MacroFeedService {
+  /** 当周经济日历（周一~周日，北京时间；limit 截尾，缺省全周）。 */
+  listCalendar(limit?: number | undefined): Promise<readonly MacroCalendarEntry[]>;
+  /** 央行最新利率（全量，客户端按地区过滤）。 */
+  listRates(): Promise<readonly MacroRateEntry[]>;
+}
 /** 新闻聚合器注册表契约（Issue #37，router 插件提供）。 */
 interface TradingNewsRegistry {
   register(market: string, aggregator: NewsAggregator): () => void;
@@ -717,4 +799,4 @@ interface TradingNewsRegistry {
   markets(): string[];
 }
 //#endregion
-export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, AuctionSnapshot, BuybackItem, CompanyProfile, CryptoFundamentals, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, DividendItem, DragonTigerItem, FinancialCell, FinancialIndicatorRow, FinancialReportGroup, FinancialReportMatrix, ForecastSummary, FundamentalsPackage, HolderNumSummary, InsiderTradeItem, InstitutionalHoldingItem, Interval, Kline, LimitUpPoolItem, 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, 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 };

package/lib/index.d.ts

@@ -8,16 +8,18 @@ declare const provider: SkillProvider;
 interface Config {
   dryRun: boolean;
   liveTrading: boolean;
-  /** 角色预设按需收窄技能面；缺省保持全量捆绑目录。 */
-  skills?: string[];
+  /** 角色预设按需收窄技能面；字段缺席保持全量捆绑目录，显式空数组才表示不下发任何技能。 */
+  skills?: string[] | null;
 }
 declare const Config: Schema<Config>;
 declare const inject: string[];
 declare const name = "dsh-trading-hk-kit";
 /** 白名单视图：未知名 fail-fast 不静默缩面；白名单外的 get 拒绝分发。 */
-declare function providerForSkills(allowed?: readonly string[]): SkillProvider;
+declare function providerForSkills(allowed?: readonly string[] | null): SkillProvider;
 declare function apply(ctx: Context, config: Config): void;
-declare function createGetNewsTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createGetNewsTool(toolOptions?: {
+  getSources?: () => readonly string[] | undefined;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
 declare function createGetFundamentalsTool(options?: {
   fetch?: typeof globalThis.fetch;
 }): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/index.js

@@ -115,7 +115,7 @@ const provider = {
 const Config = Schema.object({
 	dryRun: Schema.boolean().default(true),
 	liveTrading: Schema.boolean().default(false),
-	skills: Schema.array(Schema.string())
+	skills: Schema.union([Schema.array(Schema.string()), Schema.const(null)]).default(null)
 });
 const inject = ["skills", "tools"];
 const name = "dsh-trading-hk-kit";
@@ -136,7 +136,9 @@ function providerForSkills(allowed) {
 }
 function apply(ctx, config) {
 	ctx.skills.registerProvider(() => providerForSkills(config.skills));
-	const newsTool = createGetNewsTool();
+	const routerCtx = ctx;
+	const readNewsSources = () => (routerCtx.get?.("tradingMarketRouter", false))?.newsSources?.("hk");
+	const newsTool = createGetNewsTool({ getSources: readNewsSources });
 	const fundamentalsTool = createGetFundamentalsTool();
 	const tools = ctx.tools;
 	const registerOnce = (tool) => {
@@ -165,7 +167,7 @@ const DEFAULT_NEWS_LIMIT = 20;
 function renderNewsItem(item) {
 	return `[${item.source}] ${item.publishedAt}  ${item.title}\n  ${item.url}`;
 }
-function createGetNewsTool() {
+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.",
@@ -197,7 +199,8 @@ function createGetNewsTool() {
 			const options = {
 				symbol: typeof args.symbol === "string" ? args.symbol : void 0,
 				windowHours: typeof args.windowHours === "number" ? args.windowHours : void 0,
-				limit: typeof args.limit === "number" ? args.limit : void 0
+				limit: typeof args.limit === "number" ? args.limit : void 0,
+				sources: toolOptions.getSources?.()
 			};
 			const { items, unavailable } = await aggregateNews(options);
 			if (items.length === 0 && unavailable.length === 0) return "hk_get_news: no news items found within the requested window (degraded source: Eastmoney HK column may have no HK-relevant items in-window).";

package/lib/news.d.ts

@@ -31,6 +31,8 @@ interface AggregateNewsOptions {
   now?: number | undefined;
   /** CryptoPanic API token（桥面透传，hk 聚合器忽略；对齐 api 契约形状）。 */
   cryptoPanicKey?: string | undefined;
+  /** 启用源 id 列表（issue #96 源配置化）；缺省 = 全部默认源，空数组 = 显式关闭。 */
+  sources?: readonly string[] | undefined;
 }
 interface AggregateNewsResult {
   items: NewsItem[];

package/lib/news.js

@@ -459,10 +459,13 @@ async function aggregateNews(options = {}) {
 	const now = options.now ?? Date.now();
 	const windowMs = clampNumber(options.windowHours, DEFAULT_WINDOW_HOURS, 1, 168) * 36e5;
 	const limit = clampNumber(options.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
-	const fetchers = [fetchEastmoneyHk(fetchImpl, limit)];
+	const enabled = options.sources;
+	const isEnabled = (id) => enabled === void 0 || enabled.includes(id);
+	const fetchers = [];
+	if (isEnabled("eastmoney")) fetchers.push(fetchEastmoneyHk(fetchImpl, limit));
 	if (options.symbol && options.symbol.trim()) {
-		fetchers.push(fetchEastmoneyHkAnnouncements(fetchImpl, options.symbol, limit));
-		fetchers.push(fetchHkexAnnouncements(fetchImpl, options.symbol, limit, now));
+		if (isEnabled("eastmoney-announcement")) fetchers.push(fetchEastmoneyHkAnnouncements(fetchImpl, options.symbol, limit));
+		if (isEnabled("hkex-announcement")) fetchers.push(fetchHkexAnnouncements(fetchImpl, options.symbol, limit, now));
 	}
 	const results = await Promise.allSettled(fetchers);
 	const items = [];

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.2.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/knowledge": "0.2.1",
-    "@dshtrading/indicators": "0.2.1"
+    "@dshtrading/indicators": "0.4.0",
+    "@dshtrading/knowledge": "0.4.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
-    "@dshtrading/api": "0.2.1"
+    "@dshtrading/api": "0.4.0"
   },
   "scripts": {
     "build": "tsdown",