@hhxg/dsh-hhxg-market 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.2 (2026-11-02)
+
+结果可信度与兼容性修复版（外部评估 + Codex 审阅后的批次）。工具名、数量（7 免费 + 6 VIP）不变。
+
+- **时效显式化** `hhxg_realtime` 的结果文本首行标出帧的状态与交易日（如「【非实时·上一交易日｜帧交易日 2026-10-30｜采集 2026-10-30 15:35】不是此刻的实时数据，引用时注明帧日期。」）；`status=live` 但 `is_live=false` 的矛盾帧按非实时处理，绝不显示成实时。web profile 结果卡的徽标改为显示同一段完整文案（host 投影统一生成）。
+- **日 K 可比性语义** 服务端 `get_realtime view=kline` 响应 `schema_version` 升到 2：`live.comparable` 可为 `null`（无法判断：历史缓存落后于帧、个股最后收盘不在上一交易日、缺基准价或交易日历不可用，原因在 `live.reason`），`false` 改为「疑似除权 / 价格基准不一致」而非「确认除权」，新增响应级 `history`（缓存末日、按交易日历算的缺口）。插件文本在 `comparable !== true` 时追加提示行，卡片里帧那天的 K 不再一律标「今日·未收盘」。
+- **本地预检** `view=kline` 的 `codes ≤ 5`、`bars` 1–260 整数、去重后 `codes × bars ≤ 1000`，以及 `view=quotes` 的 `codes ≤ 30`，越界在本地返回「参数有误：…（INVALID_ARG / RESULT_TOO_LARGE）」，不发请求。
+- **Token 来源** 配置 `mcpToken` 留空时读环境变量 `HHXG_MCP_TOKEN`（显式配置非空时以配置为准；日志只记来源不记值）。
+- **client 降级** 宿主未提供 React / jsx-runtime 或 slots 注册失败时，client 半不再抛错，只是不注册结果卡（宿主默认文本视图照常）。
+- **peer 范围** `@deepseek-ai/dsh-tools` 放宽到 `>=0.1.1-rc.1 <0.3.0-0`（严格 semver 下另列出已知的 0.1.7-rc.2 / 0.2.0-rc.1 / 0.2.1-rc.5 / 0.2.2-alpha.2 预发布版本），cordis / schemastery 改为「不低于当前、不跨主版本」；契约测试新增两种预发布匹配模式的范围断言。
+- npm 包 `@hhxg/dsh-hhxg-market` 自 0.4.1 起可用，README 安装段以 npm 为主。
+
 ## 0.4.1 (2026-11-01)
 
 文案纠错 + 日 K 参数透传。工具名、数量（7 免费 + 6 VIP）与行为不变。

package/README.md

@@ -9,16 +9,16 @@
 
 ## 安装
 
-直接从 GitHub 安装：
+从 npm 安装（推荐，2026-11-01 起发布为 [`@hhxg/dsh-hhxg-market`](https://www.npmjs.com/package/@hhxg/dsh-hhxg-market)）：
 
 ```bash
-dsh plugin --profile web add github:Niceck/dsh-hhxg-market
+dsh plugin --profile web add @hhxg/dsh-hhxg-market
 ```
 
-或从 npm（发布后）：
+或直接从 GitHub 安装（备选，解析到仓库最新提交）：
 
 ```bash
-dsh plugin --profile web add @hhxg/dsh-hhxg-market
+dsh plugin --profile web add github:Niceck/dsh-hhxg-market
 ```
 
 > **⚠️ 仍在用 0.2.x 的请升级**：0.2.x 的 `hhxg_strategy_signals` / `hhxg_stock_alerts` 调用的服务端旧工具名已于 2026-10-27 下线（原定 2026-11-30，提前），这两个工具现在会报「工具已下线」（其余工具不受影响）。重新执行上面的 GitHub 安装命令即可升级到最新版（`dsh plugin` 把参数转给 pnpm，`add` 会重新解析到仓库最新提交）。
@@ -48,7 +48,7 @@ dsh plugin --profile web add @hhxg/dsh-hhxg-market
 | `hhxg_predict_lianban` | 连板股次日晋级率预测（题材热度 / 行业热度 / 板高强度 3 因子） |
 | `hhxg_stock_alerts` | 个股近 30 日异动历史（普通 / 临近严重 / 严重异动逐日记录） |
 | `hhxg_query_dataset` | 对数据集（JSON 与 300KB 以内的 CSV）做过滤 / 排序 / 截断查询（先用免费的 `hhxg_datasets` 查合法 id 与是否可查） |
-| `hhxg_realtime` | **Max 专属**盘中实时（交易日约 1 分钟一帧，盘后为当日收盘帧）：`view=market` 涨跌家数 / 涨跌停与炸板 / 涨停池与连板晋级率；`view=quotes` 指定个股（最多 30 只）的最新价与日 / 周 / 月指标；`view=screen` 全市场条件筛选（最多 8 条、返回 50 行）；`view=fields` 可用字段与示例；`view=kline` 指定个股（最多 5 只）的日 K 序列（已完成交易日 ≤260 根，`adj` 前复权 / 不复权）+ 今天这根未走完的 K（`live`，除权日标 `comparable=false`）。结果带 `frame.status`（盘中 / 午休 / 收盘 / 非今日 / 延迟）。分钟 K 不提供（快照差分还原不了区间高低） |
+| `hhxg_realtime` | **Max 专属**盘中实时（交易日约 1 分钟一帧，盘后为当日收盘帧）：`view=market` 涨跌家数 / 涨跌停与炸板 / 涨停池与连板晋级率；`view=quotes` 指定个股（最多 30 只）的最新价与日 / 周 / 月指标；`view=screen` 全市场条件筛选（最多 8 条、返回 50 行）；`view=fields` 可用字段与示例；`view=kline` 指定个股（最多 5 只）的日 K 序列（已完成交易日 ≤260 根，`codes × bars ≤ 1000`，`adj` 前复权 / 不复权）+ 实时帧那天未走完的 K（`live`；`comparable` 只有 `true` 才可与历史拼接，`false` 疑似除权 / 基准不一致，`null` 无法判断——缓存滞后、个股停牌或日历不可用，原因见 `live.reason`，缓存状态见 `history`）。结果文本首行标出帧的时效与交易日，并带 `frame.status`（盘中 / 午休 / 收盘 / 非今日 / 延迟）；不是 `live` 就不是此刻的数据。分钟 K 不提供（快照差分还原不了区间高低） |
 
 **解锁步骤**：
 
@@ -64,7 +64,9 @@ dsh plugin --profile web add @hhxg/dsh-hhxg-market
         mcpToken: "<你的 MCP Token>"
 ```
 
-未填 Token 时 VIP 工具仍会注册为引导占位（调用返回开通指引），不影响免费工具。设 `enableVipTools: false` 可整体关闭 VIP 工具注册。
+从终端启动 dsh 的话也可以不改文件：配置留空，设环境变量 `HHXG_MCP_TOKEN=<你的 MCP Token>`（显式配置非空时以配置为准；GUI 启动的 dsh 不一定继承 shell 环境）。
+
+未填 Token 时 VIP 工具仍会注册为引导占位（调用返回开通指引），不影响免费工具。设 `enableVipTools: false` 可整体关闭 VIP 工具注册（此时环境变量也不会解锁）。
 
 `hhxg_strategy_signals` 的 12 个策略标识里有 3 个（`oversold_rebound` / `macd_death_cross` / `distribution`）需要列间比较或分位数，暂不能作为预设，调用会返回说明（`PRESET_NOT_SUPPORTED`）。全市场指标全表（`quant_signal_pool`）自 2026-10-23 起为会员数据、不再提供下载地址；需要自定义条件时，可在 MCP 客户端直接调 `screen_stocks(filters=...)` 按「字段 对 常量」筛选后自行比较。
 
@@ -84,7 +86,7 @@ Header: Authorization: Bearer <你的 MCP Token>
 ## 设计约定
 
 - **只读（research-only）**：本插件只提供行情与研究数据，不下单、不划转资金，也不存在任何交易执行接口。
-- **凭证最小暴露**：Token 仅用于请求的 `Authorization` 头，不写盘、不打日志；错误信息经脱敏处理，不回显 Token。Token 本体只存在于你本机的 profile 配置。
+- **凭证最小暴露**：Token 仅用于请求的 `Authorization` 头，不写盘、不打日志（日志只记「来自配置 / 环境变量 / 未配置」）；错误信息经脱敏处理，不回显 Token。Token 本体只存在于你本机的 profile 配置或你自己设置的环境变量里（环境变量对同进程插件与继承环境的子进程可见，不是保险库）。
 - **上游文本消毒**：新闻标题、题材名等第三方文本进入模型上下文前统一清洗（删不可见字符、压平控制字符、断开链接/图片语法），降低数据侧 prompt injection 风险。
 - **免责声明**：所有数据仅供研究参考，不构成投资建议。数据可能存在延迟或缺失，据此操作风险自负。
 

package/cordis.patch.yml

@@ -12,6 +12,7 @@
 #       - id: hhxg-market
 #         config:
 #           mcpToken: "<hhxg.top/account/mcp.html 生成的 MCP Token>"
+# 从终端启动 dsh 时也可以不改文件：配置留空，设环境变量 HHXG_MCP_TOKEN。
 - insert:
     - id: hhxg-market
       name: '@hhxg/dsh-hhxg-market'

package/lib/api.js

@@ -16,6 +16,21 @@ export const BASE_URL = 'https://hhxg.top'
 export const MCP_RPC_URL = `${BASE_URL}/mcp/rpc`
 export const UPGRADE_URL = `${BASE_URL}/vip.html`
 export const TOKEN_URL = `${BASE_URL}/account/mcp.html`
+/** mcpToken 的环境变量回退来源（终端启动 dsh 时可用；GUI 启动不一定继承 shell 环境）。 */
+export const TOKEN_ENV = 'HHXG_MCP_TOKEN'
+
+/**
+ * 解析 MCP Token 来源：显式配置（非空）优先；为空才看环境变量 HHXG_MCP_TOKEN；两者都空 = 未配置。
+ * 显式配置非法（含空白 / 非 ASCII）时不回退环境变量——那是用户填错了，要报错而不是悄悄换一把。
+ * 返回 { token, source }，source ∈ config / env / none；只在 host apply() 读一次，不写回任何地方。
+ */
+export function resolveMcpToken(config, env = process.env) {
+  const configured = typeof config?.mcpToken === 'string' ? config.mcpToken.trim() : ''
+  if (configured) return { token: configured, source: 'config' }
+  const fromEnv = typeof env?.[TOKEN_ENV] === 'string' ? env[TOKEN_ENV].trim() : ''
+  if (fromEnv) return { token: fromEnv, source: 'env' }
+  return { token: '', source: 'none' }
+}
 
 const require = createRequire(import.meta.url)
 const { version: PLUGIN_VERSION } = require('../package.json')

package/lib/client.js

@@ -25,12 +25,16 @@ window.__ModuleLoader__.load({
     let react
     let jsx
     let jsxs
+    // 宿主没给 React（或 jsx-runtime）：不抛——抛出去会让宿主把整个 client 模块判坏；
+    // 改成「不注册卡片」，宿主继续用默认文本视图，免费工具与其它 VIP 工具不受影响。
+    let unavailable = null
     try {
       react = require('react')
       ;({ jsx, jsxs } = require('react/jsx-runtime'))
+      if (typeof jsx !== 'function' || typeof jsxs !== 'function') throw new Error('jsx runtime missing')
     } catch (error) {
-      console.error('[hhxg-market] client require failed; card cannot mount:', error)
-      throw error
+      unavailable = error
+      console.warn('[hhxg-market] client dependencies unavailable; realtime card disabled, host default view kept:', error)
     }
 
     const TOOL = 'hhxg_realtime'
@@ -106,11 +110,14 @@ window.__ModuleLoader__.load({
 
     function badgeEl(frame) {
       if (!frame || typeof frame !== 'object' || typeof frame.status !== 'string') return null
-      const label = STATUS_LABEL[frame.status] || frame.status
-      const at = typeof frame.updated_at === 'string' ? frame.updated_at.slice(5, 16) : ''
+      // host 投影给的 effective_status / label 优先（is_live=false 的矛盾帧已被降为 stale，日期完整可见）；
+      // 旧版 meta 没有这两个字段时按本地表回退
+      const status = typeof frame.effective_status === 'string' && frame.effective_status ? frame.effective_status : frame.status
+      const label = typeof frame.label === 'string' && frame.label ? frame.label : STATUS_LABEL[status] || status
+      const at = typeof frame.label === 'string' && frame.label ? '' : typeof frame.updated_at === 'string' ? frame.updated_at.slice(5, 16) : ''
       return jsxs('span', {
         className: 'hhxg_badge',
-        'data-status': frame.status,
+        'data-status': status,
         title: typeof frame.status_text === 'string' ? frame.status_text : '',
         children: [label, at ? jsx('span', { className: 'hhxg_meta', children: at }) : null],
       })
@@ -169,13 +176,21 @@ window.__ModuleLoader__.load({
     const inject = ['slots']
 
     function apply(ctx) {
+      if (unavailable) return // 依赖缺失：不注册，宿主默认视图照常
+      const warn = (error) => console.warn('[hhxg-market] could not register the realtime card; host default view kept:', error)
+      // inject 的回调可能被宿主延后执行（slots 就绪后才调）：异常要在回调里自己接住，外层 try 兜不到
+      const register = () => {
+        try {
+          return ctx.slots.register({ name: 'tool.call.toolview', key: TOOL }, RealtimeCard)
+        } catch (error) {
+          warn(error)
+          return undefined
+        }
+      }
       try {
-        ctx.slots.inject('tool.call.toolview', () =>
-          ctx.slots.register({ name: 'tool.call.toolview', key: TOOL }, RealtimeCard),
-        )
+        ctx.slots.inject('tool.call.toolview', register)
       } catch (error) {
-        console.error('[hhxg-market] could not register the realtime card:', error)
-        throw error
+        warn(error) // slots 不可用：同样不往上抛，只少一张卡
       }
     }
 
@@ -184,6 +199,7 @@ window.__ModuleLoader__.load({
     exports.RealtimeCard = RealtimeCard
     exports.TOOL = TOOL
     exports.react = react
+    exports.unavailable = unavailable
     return module.exports
   },
 })

package/lib/index.js

@@ -12,7 +12,8 @@
 
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { realtimePresentation } from './present.js'
+import { resolveMcpToken } from './api.js'
+import { realtimePresentation, renderRealtimeText } from './present.js'
 import { FREE_TOOLS, VIP_TOOLS, runVipTool, vipLockedMessage } from './tools.js'
 
 export const name = 'hhxg-market'
@@ -23,7 +24,7 @@ export const Config = z.object({
     .string()
     .role('secret')
     .default('')
-    .description('恢恢量化会员的 MCP Token（Max 会员在 https://hhxg.top/account/mcp.html 生成）。留空时仅免费工具可用。'),
+    .description('恢恢量化会员的 MCP Token（Max 会员在 https://hhxg.top/account/mcp.html 生成）。留空时读环境变量 HHXG_MCP_TOKEN；都没有则仅免费工具可用。'),
   enableVipTools: z
     .boolean()
     .default(true)
@@ -37,20 +38,25 @@ const TEXT_OUTPUT = {
 
 /**
  * 桌面端卡片用的结构化投影：按工具名挑一个 presentationMeta（客户端半 lib/client.js 只认这些 kind）。
- * 投影从 execute 返回的同一份文本解析，模型看到的内容不变；解析不出就不给 meta，走默认文本卡。
+ * 投影与文本渲染都从 execute 返回的同一份原文解析（execute 本身不改写原文）：
+ * render 给模型 / 用户的文本在首行标出帧日期与时效，presentationMeta 照旧从原 JSON 投影。
  */
 const PRESENTATIONS = {
-  hhxg_realtime: realtimePresentation,
+  hhxg_realtime: { present: realtimePresentation, render: renderRealtimeText },
 }
 
 function outputFor(name) {
-  const present = PRESENTATIONS[name]
-  if (!present) return TEXT_OUTPUT
-  return { ...TEXT_OUTPUT, presentationMeta: (args, value) => present(args, String(value ?? '')) }
+  const entry = PRESENTATIONS[name]
+  if (!entry) return TEXT_OUTPUT
+  return {
+    ...TEXT_OUTPUT,
+    render: (args, value) => [{ type: 'text', text: entry.render(args, String(value ?? '')) }],
+    presentationMeta: (args, value) => entry.present(args, String(value ?? '')),
+  }
 }
 
 export function apply(ctx, config) {
-  const token = String(config?.mcpToken || '').trim()
+  const { token, source } = resolveMcpToken(config)
 
   for (const spec of FREE_TOOLS) {
     ctx.tools.register(defineTool({
@@ -82,8 +88,9 @@ export function apply(ctx, config) {
     }))
   }
 
+  // 只记来源，绝不记值
+  const sourceText = { config: 'MCP Token 来自配置', env: 'MCP Token 来自环境变量 HHXG_MCP_TOKEN', none: '未配置 Token，VIP 工具为引导占位' }[source]
   ctx.logger?.info?.(
-    `[hhxg-market] 已注册 ${FREE_TOOLS.length} 个免费工具 + ${VIP_TOOLS.length} 个 VIP 工具` +
-    (token ? '（MCP Token 已配置）' : '（未配置 Token，VIP 工具为引导占位）'),
+    `[hhxg-market] 已注册 ${FREE_TOOLS.length} 个免费工具 + ${VIP_TOOLS.length} 个 VIP 工具（${sourceText}）`,
   )
 }

package/lib/present.js

@@ -34,6 +34,54 @@ function table(columns, rows) {
   }
 }
 
+/** 帧状态 → 人话；status=live 但 is_live=false 的矛盾帧按「非实时」处理，绝不显示成实时。 */
+const STATUS_LABEL = {
+  live: '盘中实时',
+  lunch_break: '午间休市',
+  closed: '收盘帧',
+  previous_session: '非实时·上一交易日',
+  stale: '非实时·延迟',
+}
+const LIVE_STATUSES = new Set(['live', 'lunch_break'])
+
+/** 进首行的服务端字段统一清洗：删控制 / 不可见字符、压平空白、限长——首行是模型最先读到的位置。 */
+function safeText(v, limit) {
+  if (typeof v !== 'string') return ''
+  const s = v.replace(/[\p{Cc}\p{Cf}]/gu, '').replace(/\s+/g, ' ').trim()
+  return s.length > limit ? s.slice(0, limit - 1) + '…' : s
+}
+
+/** 8 位交易日 → YYYY-MM-DD；格式不对返回空串（不回显来路不明的字符串）。 */
+function ymd(v) {
+  const s = typeof v === 'string' ? v : ''
+  return /^\d{8}$/.test(s) ? `${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6)}` : ''
+}
+
+/**
+ * 帧的有效状态：只有 status=live 却 is_live=false 这种矛盾才降为 stale（不能显示绿色）。
+ * lunch_break 服务端本来就给 is_live=false（午休不是实时），不算矛盾。
+ */
+function effectiveStatus(f) {
+  const status = typeof f?.status === 'string' ? f.status : ''
+  if (status === 'live' && f?.is_live === false) return 'stale'
+  return status
+}
+
+const UPDATED_AT_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}/
+
+/**
+ * 徽标正文（host 统一生成，client 只显示）：状态 + 帧交易日 + 采集时间，日期必须完整可见。
+ * 进首行的服务端字段只走白名单 / 严格格式：状态不在表里显示「状态未知」，日期时间格式不对就省略，
+ * 绝不把未知字符串原样提升到模型最先读到的位置。
+ */
+function frameLabel(f) {
+  const status = effectiveStatus(f)
+  const label = STATUS_LABEL[status] || '状态未知'
+  const date = ymd(f?.trade_date)
+  const at = typeof f?.updated_at === 'string' && UPDATED_AT_RE.test(f.updated_at) ? f.updated_at.slice(0, 16) : ''
+  return [label, date ? `帧交易日 ${date}` : '', at ? `采集 ${at}` : ''].filter(Boolean).join('｜')
+}
+
 function frameOf(data) {
   const f = data?.frame
   if (!f || typeof f !== 'object') return null
@@ -42,6 +90,77 @@ function frameOf(data) {
     status_text: cell(f.status_text),
     trade_date: cell(f.trade_date),
     updated_at: cell(f.updated_at),
+    // 布尔原样保留（cell 会把它变成「是 / 否」）；缺失为 null
+    is_live: typeof f.is_live === 'boolean' ? f.is_live : null,
+    effective_status: cell(effectiveStatus(f)),
+    // 徽标正文要完整可见（含日期与时间），不走 40 字的单元格截断；上限 80 字兜底
+    label: frameLabel(f).slice(0, 80),
+  }
+}
+
+/** live 段的可比性说明：只有 comparable===true 才能与 rows 拼接。 */
+const REASON_TEXT = {
+  history_gap: '历史缓存落后于实时帧（中间有交易日没同步）',
+  last_close_not_previous_session: '该股最后一个收盘价不在上一交易日（停牌或缺数据）',
+  missing_reference_price: '缺少昨收 / 最后收盘价',
+  calendar_unavailable_or_incomplete: '交易日历不可用，无法判断缓存是否滞后',
+  reference_price_mismatch: '帧昨收与缓存最后收盘偏差 >0.5%，疑似除权或价格基准不一致',
+}
+
+function comparabilityNote(live) {
+  if (!live || typeof live !== 'object' || live.comparable === true) return null
+  // reason 走白名单：未知值不回显，只说「原因未说明」
+  const why = REASON_TEXT[live.reason] || (live.reason ? '原因未说明' : '')
+  const head = live.comparable === false ? '实时 K 与历史不可比' : '实时 K 与历史的可比性无法判断'
+  return `${head}${why ? `：${why}` : ''}；不要把 live 直接拼到 rows 后面。`
+}
+
+/** 多只股票：每只有 live 且 comparable !== true 的都列出（代码走 safeText），最多列 5 只。 */
+function comparabilityLines(items) {
+  const out = []
+  for (const it of items) {
+    const note = comparabilityNote(it?.live)
+    if (!note) continue
+    const code = safeText(typeof it.股票代码 === 'string' ? it.股票代码 : '', 12) || '（未知代码）'
+    out.push(`${code}：${note}`)
+    if (out.length >= 5) {
+      out.push('（其余见 JSON 的 live.reason）')
+      break
+    }
+  }
+  return out
+}
+
+/**
+ * 工具文本首行：把帧的时效与日期放到模型 / 用户第一眼能看到的位置（原 JSON 原样跟在后面，
+ * presentationMeta 仍从同一份原文解析）。非成功信封（业务答复 / 占位 / 报错）原样返回。
+ */
+export function renderRealtimeText(args, text) {
+  try {
+    if (typeof text !== 'string' || !text.startsWith('{')) return text
+    const envelope = JSON.parse(text)
+    const data = envelope?.data
+    if (!data || typeof data !== 'object') return text
+    const view = typeof args?.view === 'string' ? args.view.trim() : ''
+    if (view === 'fields') return text // 字段清单本来就没有帧，不加时效行
+    const lines = []
+    if (data.frame && typeof data.frame === 'object') {
+      // 盘中 / 午休帧不加告警（午休是上午最后一帧，仍是今天的实时口径）；其余都不是此刻的数据
+      const warn = LIVE_STATUSES.has(effectiveStatus(data.frame)) ? '' : '不是此刻的实时数据，引用时注明帧日期。'
+      lines.push(`【${frameLabel(data.frame)}】${warn}`)
+    } else if (view === 'kline') {
+      const last = ymd(data?.history?.last_date)
+      lines.push(`【历史日 K${last ? `｜截至 ${last}` : ''}】未附实时帧。`)
+    } else {
+      lines.push('【时效未知】结果里没有帧信息。')
+    }
+    if (view === 'kline') {
+      const notes = comparabilityLines(dicts(data.items))
+      if (notes.length) lines.push(`【注意】${notes.join('；')}`)
+    }
+    return `${lines.map((l) => safeText(l, 600)).join('\n')}\n${text}`
+  } catch {
+    return text
   }
 }
 
@@ -83,12 +202,19 @@ function klineTable(data) {
   if (!first || !columns.length) return { title: '日 K', ...table(columns, []) }
   const rows = Array.isArray(first.rows) ? first.rows.filter(Array.isArray) : []
   const live = first.live && typeof first.live === 'object' && Array.isArray(first.live.bar) ? first.live.bar : null
-  // 卡片只放最近的几十根 + 今天这根（标「今日·未收盘」），完整序列在模型侧文本里
+  // 卡片只放最近的几十根 + 帧那天的 K：帧是盘中才叫「未收盘」，收盘帧 / 旧帧不能这么标
+  const status = effectiveStatus(data?.frame)
+  const liveTag = status === 'live' || status === 'lunch_break' ? '帧K·未收盘' : `帧K·${STATUS_LABEL[status] || '非实时'}`
   const tail = rows.slice(-(MAX_ROWS - (live ? 1 : 0)))
-  const shown = live ? [...tail, [`${live[0]} 今日·未收盘`, ...live.slice(1)]] : tail
+  const shown = live ? [...tail, [`${live[0]} ${liveTag}`, ...live.slice(1)]] : tail
   const name = [first.股票代码, first.股票名称].filter(Boolean).join(' ')
   const more = items.length > 1 ? `（另 ${items.length - 1} 只见文本）` : ''
-  return { title: `日 K ${name}${more}`, ...table(columns, shown), truncated: rows.length > tail.length || items.length > 1 }
+  return {
+    title: `日 K ${name}${more}`,
+    ...table(columns, shown),
+    truncated: rows.length > tail.length || items.length > 1,
+    note: comparabilityNote(first.live),
+  }
 }
 
 function fieldsTable(data) {
@@ -111,7 +237,9 @@ export function realtimePresentation(args, text) {
     const envelope = JSON.parse(text)
     const data = envelope?.data
     if (!data || typeof data !== 'object') return undefined
-    const { title, columns, rows, truncated } = build(data)
+    const { title, columns, rows, truncated, note: builtNote } = build(data)
+    // 表自带的说明（如日 K 的可比性）优先于服务端 note——它更要紧；note 不走 40 字的单元格截断
+    const note = safeText(builtNote || (typeof data.note === 'string' ? data.note : ''), 160)
     return {
       schema: PRESENTATION_SCHEMA,
       kind: REALTIME_KIND,
@@ -121,7 +249,7 @@ export function realtimePresentation(args, text) {
       columns,
       rows,
       truncated,
-      note: typeof data.note === 'string' ? cell(data.note.slice(0, 120)) : null,
+      note: note || null,
     }
   } catch {
     return undefined

package/lib/tools.js

@@ -382,6 +382,34 @@ function realtimeView(a) {
   return Object.hasOwn(REALTIME_PARAMS_BY_VIEW, view) ? view : ''
 }
 
+// 与服务端同值的硬上限（EdgeOne agent_tools/realtime.js + VPS realtime.py）：本地先拒明显越界的请求，
+// 省一次往返与配额；权威校验仍在服务端。文案沿用业务答复格式「参数有误：…（CODE）」。
+const REALTIME_MAX_CODES = { quotes: 30, kline: 5 }
+const KLINE_BARS = { default: 120, min: 1, max: 260 }
+const KLINE_MAX_TOTAL_BARS = 1000
+const localArgError = (msg, code = 'INVALID_ARG') => `参数有误：${msg}（${code}）`
+
+/** 本地边界预检（view 与缺 codes 之后）：越界返回说明文字，合法返回 null。 */
+function realtimeBoundsRefusal(view, codes, a) {
+  const cap = REALTIME_MAX_CODES[view]
+  // 原始数组长度先判（服务端 _str_list 也是去重前查长度），全是重复项也照拒
+  if (cap && Array.isArray(codes) && codes.length > cap) {
+    return localArgError(`view=${view} 的 codes 最多 ${cap} 只（收到 ${codes.length} 只），请减少 codes`)
+  }
+  if (view !== 'kline') return null
+  const bars = a?.bars === undefined || a?.bars === null ? KLINE_BARS.default : a.bars
+  // 字符串 "60"、布尔、小数都不是合法整数：不替模型强转，让它改
+  if (!Number.isInteger(bars) || bars < KLINE_BARS.min || bars > KLINE_BARS.max) {
+    return localArgError(`bars 须为 ${KLINE_BARS.min}–${KLINE_BARS.max} 的整数（默认 ${KLINE_BARS.default}）`)
+  }
+  // 乘积按服务端 _codes 的去重规则算：trim + 转大写后去重（"600519" 与 "600519.SH" 仍是两个，不替它合并）
+  const unique = new Set(codes.map((c) => String(c).trim().toUpperCase()).filter(Boolean)).size
+  if (unique * bars > KLINE_MAX_TOTAL_BARS) {
+    return localArgError(`codes × bars 不能超过 ${KLINE_MAX_TOTAL_BARS} 根，请减少 codes 或 bars`, 'RESULT_TOO_LARGE')
+  }
+  return null
+}
+
 export const VIP_TOOLS = [
   {
     name: 'hhxg_diagnose_stock',
@@ -468,10 +496,11 @@ export const VIP_TOOLS = [
       'view=screen：全市场按 filters [{field, op, value}] 筛选（最多 8 条，op：gt/gte/lt/lte/eq/ne/in/not_null），' +
       'sort 字段名前加 - 为降序，fields 选返回列（最多 12），limit 1-50，exclude_st 排除 ST；周 / 月指标字段名加前缀「周」「月」（如 周MACD_HIST）；' +
       'view=fields：全部可用字段、取值说明与示例，不确定字段名时先调它；' +
-      'view=kline：codes（最多 5 只）的日 K 序列——rows 为已完成交易日（period 只支持 day，bars 1-260 默认 120，adj=qfq 前复权 / none 不复权，' +
-      '单位 元 / 股 / 元，缺值 null），live 为今天这根未走完的 K（最新价当收盘价；live.comparable=false 表示今日除权，不要与前复权历史直接拼接）。' +
-      '每个结果都带 frame.status（live 盘中 / lunch_break 午休 / closed 收盘帧 / previous_session 非今日 / stale 延迟），引用数据前先看它；' +
-      '盘中价格是最新价不是收盘价。Pro 会员调用会返回「需要 Max」的说明。',
+      'view=kline：codes（最多 5 只）的日 K 序列——rows 为已完成交易日（period 只支持 day，bars 1-260 默认 120，codes × bars ≤ 1000，adj=qfq 前复权 / none 不复权，' +
+      '单位 元 / 股 / 元，缺值 null），live 为实时帧那天未走完的 K（最新价当收盘价）；live.comparable 只有 true 才可与 rows 拼接，' +
+      'false = 疑似除权 / 价格基准不一致，null = 无法判断（缓存滞后 / 个股停牌 / 日历不可用，原因见 live.reason，缓存状态见 history）。' +
+      '结果文本首行会标出帧的时效与交易日；每个结果都带 frame.status（live 盘中 / lunch_break 午休 / closed 收盘帧 / previous_session 非今日 / stale 延迟），' +
+      '不是 live 就不是此刻的数据，引用时注明帧日期；盘中价格是最新价不是收盘价。Pro 会员调用会返回「需要 Max」的说明。',
     parameters: {
       view: { type: 'string', enum: REALTIME_VIEWS, required: true, description: 'market 市场概况 / quotes 指定个股 / screen 全市场筛选 / fields 字段清单 / kline 日 K 序列' },
       codes: { type: 'array', items: { type: 'string' }, description: 'view=quotes：6 位代码或 600519.SH 格式，最多 30 只；view=kline 最多 5 只' },
@@ -516,10 +545,10 @@ export const VIP_TOOLS = [
       if (!view) return REALTIME_VIEW_HINT
       const codes = realtimeCodes(a?.codes)
       if (REALTIME_VIEWS_WITH_CODES.has(view) && !(Array.isArray(codes) && codes.length)) {
-        const cap = view === 'kline' ? 5 : 30
+        const cap = REALTIME_MAX_CODES[view]
         return `view=${view} 需要 codes（6 位代码数组，最多 ${cap} 只，如 ["600519", "000001"]）。`
       }
-      return null
+      return realtimeBoundsRefusal(view, codes, a)
     },
     buildArgs: (a) => {
       const view = realtimeView(a)
@@ -555,7 +584,7 @@ export function vipLockedMessage(toolName) {
     `       - id: hhxg-market\n` +
     `         config:\n` +
     `           mcpToken: "<你的 MCP Token>"\n` +
-    `   保存后重启 dsh 生效\n\n` +
+    `   保存后重启 dsh 生效；从终端启动 dsh 的话也可以不改文件，设环境变量 HHXG_MCP_TOKEN=<你的 MCP Token>（配置留空时读取）\n\n` +
     `免费工具（hhxg_snapshot / hhxg_news / hhxg_margin / hhxg_calendar / hhxg_sentiment / ` +
     `hhxg_datasets / hhxg_themes）无需配置即可使用。`
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhxg/dsh-hhxg-market",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "恢恢量化 (hhxg.top) A股量化数据插件 for DeepSeek Harness：免费提供日报快照/财经快讯/融资融券/A股日历/市场情绪/题材热度/数据集目录 7 个工具；填入会员 MCP Token 后解锁个股诊断/量化策略信号/连板晋级预测/盘中实时（Max）等 6 个进阶工具。A-share quant data plugin for DeepSeek Harness (dsh): 7 free tools + 6 VIP tools (incl. Max-only intraday realtime) bridged to the hhxg MCP server.",
   "keywords": [
     "dsh",
@@ -31,7 +31,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/contract.test.js test/security.test.js test/tools.test.js test/present.test.js test/client.test.js"
+    "test": "node --test test/contract.test.js test/peers.test.js test/security.test.js test/tools.test.js test/present.test.js test/freshness.test.js test/client.test.js"
   },
   "repository": {
     "type": "git",
@@ -52,8 +52,11 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/cordis": ">=4.0.1 <5.0.0-0",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.1 <0.3.0-0 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.1-rc.5 || 0.2.2-alpha.2",
+    "@deepseek-ai/schemastery": ">=3.18.1 <4.0.0-0"
+  },
+  "devDependencies": {
+    "semver": "^7.7.2"
   }
 }