@zltquant/zlt-mcp 0.1.0-rc.0 → 0.1.0-rc.1

package/config.json

@@ -507,7 +507,7 @@
     },
     {
       "name": "mcp-create-and-run-backtest",
-      "description": "创建并启动回测。strategyId 必须来自 mcp-create-strategy 返回的策略ID；runType 固定为 2；普通日线回测只传 strategyId，其余参数 MCP 补齐。未指定周期时 end 取自然日 T-1、start 从 end 往前推半年；ZLTAF 按实际交易日执行，非交易日不产生行情或策略调用。run/create 失败直接报错，不要去复用策略里自动生成的 debug runId（建策略时已回显为 debugRunId，跑它等于跑创建那一刻的模板快照）。\n\n日线类频率只可见到 context.previous_date：要用交易日 T 的收盘，end 必须设成 T 的下一个交易日；end 落在未来不报错但结果为空。展开见返回的 dailyVisibilityNote / endWarning。\n\n返回 Data 回显 resolvedStart/resolvedEnd/resolvedCapital——向用户汇报区间和初始资金时一律以这些字段为准，不要自行推算或臆测。**基准不在此列**：回显的 requestedBenchmark 只是请求值，策略 initialize 里的 set_benchmark() 会覆盖它，收益产物里的「基准收益」按策略实际用的基准算。说基准是什么之前先读策略代码里的 set_benchmark，否则会把一只个股的涨跌报成指数的。\n\n**期货回测要同时改三处，少一处引擎就按股票跑**：runParams.marketIds 加上对应期货交易所（zj 中金所、zs 郑商所、ds 大商所、sq 上期所、gq 广期所），account_list 的 account_type 改成 2（实测用 6 直接废单），费率用 ratio_tpl_obj.future。合约代码形如 zjIM2605。基准保持默认 sz399300 即可，它对期货策略只是业绩比较基准。数据前置见 mcp-download-data：除行情外还必须有市场规则 mr。",
+      "description": "创建并启动回测。strategyId 必须来自 mcp-create-strategy 返回的策略ID；runType 固定为 2；普通日线回测只传 strategyId，其余参数 MCP 补齐。未指定周期时 end 取自然日 T-1、start 从 end 往前推半年；ZLTAF 按实际交易日执行，非交易日不产生行情或策略调用。run/create 失败直接报错，不要去复用策略里自动生成的 debug runId（建策略时已回显为 debugRunId，跑它等于跑创建那一刻的模板快照）。\n\n**返回 runId 后立即调用 mcp-wait（kind=backtest，id=runId）阻塞等待回测结束，不要用 mcp-get-backtest-state 轮询。**\n\n日线类频率只可见到 context.previous_date：要用交易日 T 的收盘，end 必须设成 T 的下一个交易日；end 落在未来不报错但结果为空。展开见返回的 dailyVisibilityNote / endWarning。\n\n返回 Data 回显 resolvedStart/resolvedEnd/resolvedCapital——向用户汇报区间和初始资金时一律以这些字段为准，不要自行推算或臆测。**基准不在此列**：回显的 requestedBenchmark 只是请求值，策略 initialize 里的 set_benchmark() 会覆盖它，收益产物里的「基准收益」按策略实际用的基准算。说基准是什么之前先读策略代码里的 set_benchmark，否则会把一只个股的涨跌报成指数的。\n\n**期货回测要同时改三处，少一处引擎就按股票跑**：runParams.marketIds 加上对应期货交易所（zj 中金所、zs 郑商所、ds 大商所、sq 上期所、gq 广期所），account_list 的 account_type 改成 2（实测用 6 直接废单），费率用 ratio_tpl_obj.future。合约代码形如 zjIM2605。基准保持默认 sz399300 即可，它对期货策略只是业绩比较基准。数据前置见 mcp-download-data：除行情外还必须有市场规则 mr。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -907,7 +907,7 @@
     },
     {
       "name": "mcp-re-backtest",
-      "description": "重新运行会话中最新的回测：用同一个 runId 重跑**该次回测已生成的代码快照**（策略工程 backtest/ 目录下那份副本）。\n\n**它不会把你在策略源工程里刚改过的 main.py 拷进去**——刚编辑过源代码就必须改用 mcp-create-and-run-backtest 生成新的代码快照，否则会重复运行修改前的旧代码，表现为「源码已修复却仍报同样的错误」。所以本工具只适合调整 runParams（回测区间、资金等）后重跑。\n\nstrategyId、strategyName、runId、runType、runParams 从当前会话最近一次 mcp-create-and-run-backtest 的成功结果里取得并传入本工具，不需要用户手动输入；会话中没有运行结果就提示无回测，无法重新回测。runParams 默认沿用最近一次创建回测的条件，允许用户修改部分回测参数；MCP 重启后这份上下文会丢失，届时必须传完整 runParams。返回的 resolved* 是本次实际生效的区间、资金与基准，向用户报告时以它为准。",
+      "description": "重新运行会话中最新的回测：用同一个 runId 重跑**该次回测已生成的代码快照**（策略工程 backtest/ 目录下那份副本）。\n\n**它不会把你在策略源工程里刚改过的 main.py 拷进去**——刚编辑过源代码就必须改用 mcp-create-and-run-backtest 生成新的代码快照，否则会重复运行修改前的旧代码，表现为「源码已修复却仍报同样的错误」。所以本工具只适合调整 runParams（回测区间、资金等）后重跑。\n\nstrategyId、strategyName、runId、runType、runParams 从当前会话最近一次 mcp-create-and-run-backtest 的成功结果里取得并传入本工具，不需要用户手动输入；会话中没有运行结果就提示无回测，无法重新回测。runParams 默认沿用最近一次创建回测的条件，允许用户修改部分回测参数；MCP 重启后这份上下文会丢失，届时必须传完整 runParams。返回的 resolved* 是本次实际生效的区间、资金与基准，向用户报告时以它为准。\n\n重跑启动后同样立即调用 mcp-wait（kind=backtest，id=runId）阻塞等待结束，不要轮询状态。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1128,7 +1128,7 @@
     },
     {
       "name": "mcp-get-backtest-state",
-      "description": "查询回测运行状态与进度。立即返回：只做一次查询，不会阻塞等待状态变化。status：0 准备中/1 运行中/2 失败/3 取消/4 终止/5 完成；status=5 前不要调用收益查询。\n\n未进终态时返回一定带 nextPollAfterMs：按它等待后再查一次，不要自己拍一个间隔，也不要用 shell sleep 空转；终态不带该字段。数据准备阶段的进度取自磁盘 result.json，只要 download_update_time 仍在推进就视为有进展；durationSeconds 变化不算进展。若实际工作状态连续无变化但数据准备刚更新，返回 dataPrepInProgress=true，继续等待再查一次；若数据准备也已停滞，返回 pollingStopped=true、stopAutoPolling=true 和 manualRecheckAfterMs，此时暂停自动轮询、约 1 分钟后手动再查一次，不要密集轮询。若磁盘 result.json 已确认数据准备或策略引擎启动失败，即使 IPC 仍报 status=1，也会返回 ErrNo 10043 让你停止。",
+      "description": "查询回测运行状态与进度，是手动/兜底查询入口：适用于用户主动询问进度，或 mcp-wait 异常中断后复查。**等回测结束请用 mcp-wait（kind=backtest，id=runId），不要用本工具循环轮询。** 立即返回：只做一次查询，不会阻塞等待状态变化。status：0 准备中/1 运行中/2 失败/3 取消/4 终止/5 完成；status=5 前不要调用收益查询。\n\n兜底查询时未进终态的返回一定带 nextPollAfterMs，那是 wait 不可用时的节奏参考；终态不带该字段。数据准备阶段的进度取自磁盘 result.json，只要 download_update_time 仍在推进就视为有进展；durationSeconds 变化不算进展。若实际工作状态连续无变化但数据准备刚更新，返回 dataPrepInProgress=true；若数据准备也已停滞，返回 pollingStopped=true、stopAutoPolling=true 和 manualRecheckAfterMs，此时停止查询、约 1 分钟后手动再查一次。若磁盘 result.json 已确认数据准备或策略引擎启动失败，即使 IPC 仍报 status=1，也会返回 ErrNo 10043 让你停止。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1334,6 +1334,33 @@
       },
       "ipcUri": "/zltaf_slave/v1/strategy/open-vscode",
       "bodyFromParams": true
+    },
+    {
+      "name": "mcp-wait",
+      "description": "阻塞等待一个异步任务结束，直到需要 agent 行动的状态才返回。kind=backtest 等回测，id 传 mcp-create-and-run-backtest / mcp-re-backtest 返回的 runId；kind=download 等数据下载，id 传 mcp-download-data 返回的 uuid（传 \"0\" 等本机当前最新下载任务）。拿到任务 id 后应立即调用本工具，等待期间不要做任何其他事、不要轮询状态。\n\nkind=backtest 返回与 mcp-get-backtest-state 相同的终态结果（status 2 失败/3 取消/4 终止/5 完成；status=5 才能查收益）。\n\nkind=download 返回与 mcp-get-download-progress 相同的结果，按其中 nextAction 行动。除下载中以外的任何状态都会立即返回：resume-required / await-credential / report-stopped 表示任务不会自己结束，需要用户决定。\n\n任一 kind 带 waitStopped=no-progress 表示约 3 分钟毫无进展、先交回现状（回测可能仍在准备数据）；可用对应状态工具复查一次，再调用本工具继续等。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "backtest",
+              "download"
+            ],
+            "description": "任务类别：backtest 回测，download 数据下载。"
+          },
+          "id": {
+            "type": "string",
+            "description": "任务标识：kind=backtest 传 runId；kind=download 传 uuid（\"0\" 表示本机当前最新下载任务）。"
+          }
+        },
+        "required": [
+          "kind",
+          "id"
+        ],
+        "additionalProperties": false
+      },
+      "timeoutMs": 15000
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zltquant/zlt-mcp",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.1",
   "description": "智量通 ZLT Quant MCP server（Windows x64；量化策略创建与本地回测）",
   "bin": {
     "zlt-mcp": "./zlt-mcp-proxy.bundle.cjs"

package/zlt-mcp-proxy.bundle.cjs

@@ -20838,7 +20838,18 @@ var UNIVERSAL_AGENT_IPC_TOOL_NAMES = Object.freeze([
   "mcp-stop-backtest",
   "mcp-get-backtest-state",
   "mcp-get-backtest-profit",
-  "mcp-delete-strategy"
+  "mcp-delete-strategy",
+  // Data workflow + blocking wait, opened to the universal lane 2026-08-26.
+  // The six ship together: download-data's contract points at data-range
+  // (gap check), disk-space (mr/etf confirmation), and mcp-wait (blocking
+  // wait); get-download-progress is wait's early-return fallback; stop-download
+  // is the cancel valve. Listing a subset ships guidance at unreachable tools.
+  "mcp-get-data-range",
+  "mcp-download-data",
+  "mcp-get-download-progress",
+  "mcp-get-data-disk-space",
+  "mcp-stop-download",
+  "mcp-wait"
 ]);
 var UNIVERSAL_AGENT_TOOL_NAMES = Object.freeze([
   ...UNIVERSAL_AGENT_RUNTIME_TOOL_NAMES,
@@ -20867,7 +20878,8 @@ var NPM_PACKAGE_CONFIG_TOOL_NAMES = Object.freeze([
   "mcp-get-strategy-list",
   "mcp-get-st-for-backtest-list",
   "mcp-delete-strategy",
-  "mcp-open-vscode"
+  "mcp-open-vscode",
+  "mcp-wait"
 ]);
 
 // src/tool-pipeline.ts
@@ -23941,8 +23953,19 @@ async function startMcpServer() {
       inputSchema: t.inputSchema
     }))
   }));
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const { name, arguments: args } = request.params;
+    const progressToken = request.params._meta?.progressToken;
+    const waitControl = {
+      heartbeat: progressToken === void 0 ? void 0 : (progress) => {
+        void extra.sendNotification({
+          method: "notifications/progress",
+          params: { progressToken, progress, total: 100 }
+        }).catch(() => {
+        });
+      },
+      abortSignal: extra.signal
+    };
     const tool = callableTools.find((t) => t.name === name);
     if (!tool) {
       return {
@@ -24022,7 +24045,14 @@ async function startMcpServer() {
       repairHint: withRuntimeRepairHint
     };
     const dataRoots = tool.responseTransform === "dataRange" ? resolveDataRoots(readiness.clientRootDir) : void 0;
-    const special = await dispatchSpecialTool(tool, toolArgs, ipcClient, timeout, session);
+    const special = await dispatchSpecialTool(
+      tool,
+      toolArgs,
+      ipcClient,
+      timeout,
+      session,
+      tool.name === "mcp-wait" ? waitControl : void 0
+    );
     if (special) return special;
     if (tool.steps && tool.steps.length > 0) {
       const result = await executeSteps(tool.steps, ipcClient, stripControlParams(toolArgs), timeout, withRuntimeRepairHint);