@zltquant/zlt-mcp 0.5.0-beta.0 → 0.5.0-beta.2

package/config.json

@@ -21,7 +21,7 @@
     },
     {
       "name": "mcp-strategy-get-template-list",
-      "description": "获取策略参数模板列表。创建策略前应先调用本工具，根据返回的模板列表选择 templateItemVal，再调用策略创建工具。",
+      "description": "获取平台策略参数模板列表。创建策略前应先调用本工具，只能从实时返回的条目取 val 作为 templateItemVal，不要编造或硬编码模板标识。用户明确指定的模板优先；用户只说「推荐策略并回测」等委托选择请求时，agent 可根据返回的名称、说明和可用标签选择合适模板，无需再要求用户选择。没有其他偏好时，优先选择实时返回的带平台推荐标签且适合的日线模板；没有返回推荐标记时，若列表中存在且适合用户需求，可选择「均线择时」作为后备；否则从当前列表选择其他合适模板并简要说明理由。随后调用 mcp-create-strategy-with-template 创建。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -47,13 +47,13 @@
     },
     {
       "name": "mcp-create-strategy-with-template",
-      "description": "基于用户选择的策略模板创建本地策略。先用 mcp-strategy-get-template-list 取模板列表让用户选，把所选模板的 val 填入 templateItemVal；templateVal 固定为 strategy。名称默认用「模板名称+日期时间（YYMMDD-HHMM）」，调用前允许用户修改或确认——ZLTAF 对重名策略会静默不创建并返回空结果，本工具已将其转为明确的 ErrNo 10051，遇到就改用唯一名称重试，**切勿改为复用既有同名策略**。\n\n返回含 strategyId 与 localPath，请直接使用，不要再自行查询策略列表按名称猜测。",
+      "description": "基于平台策略模板创建本地策略。先用 mcp-strategy-get-template-list 取实时列表，把所选条目的 val 填入 templateItemVal；templateVal 固定为 strategy。用户明确指定的模板优先；用户委托推荐时允许 agent 代选，无需再要求用户选择。名称默认用「模板名称+日期时间（YYMMDD-HHMM）」，允许用户修改；用户未指定名称时直接生成唯一名称——ZLTAF 对重名策略会静默不创建并返回空结果，本工具已将其转为明确的 ErrNo 10051，遇到就改用唯一名称重试，**切勿改为复用既有同名策略**。\n\n返回含 strategyId 与 localPath，请直接使用，不要再自行查询策略列表按名称猜测。",
       "inputSchema": {
         "type": "object",
         "properties": {
           "name": {
             "type": "string",
-            "description": "策略名称。默认使用“模板名称+日期（YYMMDD）”生成，允许用户修改；调用本工具时必须传入最终确认后的名称。"
+            "description": "策略名称。默认使用“模板名称+日期时间（YYMMDD-HHMM）”生成唯一名称，允许用户修改；用户未指定名称时由 agent 直接生成，调用时传入该名称。"
           },
           "templateVal": {
             "type": "string",
@@ -65,7 +65,7 @@
           },
           "templateItemVal": {
             "type": "string",
-            "description": "用户选择的模板 val，来自 mcp-strategy-get-template-list 返回的模板条目。调用前必须让用户选择模板。"
+            "description": "用户选择或委托 agent 代选的模板 val，必须来自 mcp-strategy-get-template-list 实时返回的模板条目；不要编造或硬编码。用户明确指定的模板优先。"
           },
           "userId": {
             "type": "string",
@@ -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，跑它等于跑创建那一刻的模板快照）。run/create 生成快照后，MCP 会在真正启动前拒绝 get_current_data().get(...) 这种当前对象不支持的访问。\n\n**返回 runId、codePath 和 attemptFence 后立即调用 mcp-wait（kind=backtest，id=runId）阻塞等待回测结束，不要用 mcp-get-backtest-state 轮询。CLI 创建命令启动的隐藏 guardian 会自行携带 attemptFence；任何后续显式 CLI call 或 MCP 重启后的调用，都必须把 codePath 和 attemptFence 一起传回 mcp-wait，避免把上一轮残留的 result.json 当成本轮错误；同一 MCP 会话内可省略。**\n\n日线类频率只可见到 context.previous_date：要用交易日 T 的收盘，end 必须设成 T 的下一个交易日；end 落在未来不报错但结果为空。展开见返回的 dailyVisibilityNote / endWarning。\n\n返回 Data 回显 resolvedStart/resolvedEnd/resolvedCapital——向用户汇报区间和初始资金时一律以这些字段为准，不要自行推算或臆测。evidence 给出 backtestId、实际 runDir、完整 effectiveRunParams 和代码快照 sourceSha256，后续结果必须与它对账。**基准不在此列**：回显的 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；已有配置基线时必须把本次 schema 支持的配置字段显式放入 runParams，再叠加用户明确要求；不要只传 strategyId 丢掉已有日期、资金、账户或费用。只有用户和配置都未提供周期时，才让 MCP 默认 end 为自然日 T-1、start 从 end 往前推半年；ZLTAF 按实际交易日执行，非交易日不产生行情或策略调用。run/create 失败直接报错，不要去复用策略里自动生成的 debug runId（建策略时已回显为 debugRunId，跑它等于跑创建那一刻的模板快照）。run/create 生成快照后，MCP 会在真正启动前拒绝 get_current_data().get(...) 这种当前对象不支持的访问。\n\n**返回 runId、codePath 和 attemptFence 后立即调用 mcp-wait（kind=backtest，id=runId）阻塞等待回测结束，不要用 mcp-get-backtest-state 轮询。CLI 创建命令启动的隐藏 guardian 会自行携带 attemptFence；任何后续显式 CLI call 或 MCP 重启后的调用，都必须把 codePath 和 attemptFence 一起传回 mcp-wait，避免把上一轮残留的 result.json 当成本轮错误；同一 MCP 会话内可省略。**\n\n日线类频率只可见到 context.previous_date：要用交易日 T 的收盘，end 必须设成 T 的下一个交易日；end 落在未来不报错但结果为空。展开见返回的 dailyVisibilityNote / endWarning。\n\n返回 Data 回显 resolvedStart/resolvedEnd/resolvedCapital——向用户汇报区间和初始资金时一律以这些字段为准，不要自行推算或臆测。evidence 给出 backtestId、实际 runDir、完整 effectiveRunParams 和代码快照 sourceSha256，后续结果必须与它对账。**基准不在此列**：回显的 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": {
@@ -529,7 +529,7 @@
           },
           "runParams": {
             "type": "object",
-            "description": "回测参数。普通日线回测可整体不传，MCP 按系统默认组装（含参数/费率模板与回测模式等服务端默认）；要改哪项传哪项，日期字段按用户描述动态计算。",
+            "description": "回测参数。有 tradesetting.json 配置基线时显式传入 schema 支持的已有字段（日期、资金、账户、频率、市场、预加载、参数/费率模板），用户本次要求覆盖对应字段；账户现金与初始资金保持一致。仅无用户要求且无配置基线的字段采用 MCP 默认值。",
             "properties": {
               "account_list": {
                 "type": "array",
@@ -588,12 +588,12 @@
               "start": {
                 "type": "string",
                 "format": "date",
-                "description": "回测开始日期，格式 YYYY-MM-DD。若用户未指定周期，默认从 end 往前推半年；若用户说近几天、近几月或近几年，则按对应时间长度回推。"
+                "description": "回测开始日期，格式 YYYY-MM-DD。用户要求优先，否则显式传已有配置的 start；两者都缺失时默认从 end 往前推半年。用户说近几天、近几月或近几年时按对应长度回推。"
               },
               "end": {
                 "type": "string",
                 "format": "date",
-                "description": "回测结束日期，格式 YYYY-MM-DD。若用户未指定周期，默认使用 T-1。"
+                "description": "回测结束日期，格式 YYYY-MM-DD。用户要求优先，否则显式传已有配置的 end；两者都缺失时默认使用 T-1。"
               },
               "freq": {
                 "type": "string",

package/package.json

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

package/zlt-mcp-proxy.bundle.cjs

@@ -23302,14 +23302,14 @@ function shapeToolResult(tool, args, result, session) {
     session.activeBacktestRunIds.delete(args.runId);
   }
   const echoed = echoResolvedBacktestConfig(tool, args, result, session.backtestRunContexts);
-  const guarded = applyBacktestResultGuards(
+  const guarded = annotateBacktestOutcome(tool, applyBacktestResultGuards(
     tool,
     args,
     echoed,
     session.backtestPollStates,
     session.backtestRunContexts,
     session.activeBacktestRunIds
-  );
+  ));
   const activeChange = classifyActiveBacktestChange(tool, args, guarded);
   if (activeChange) {
     if (activeChange.active) session.activeBacktestRunIds.add(activeChange.runId);
@@ -23323,6 +23323,38 @@ function shapeToolResult(tool, args, result, session) {
   const distilled = distillFactorDetectReport(tool, args, diagnosed);
   return injectDebugRunId(tool, injectStrategyDocsHint(tool, distilled, session.docsPath));
 }
+function backtestStatusNumber(status) {
+  return typeof status === "number" || typeof status === "string" && status.trim() !== "" ? Number(status) : NaN;
+}
+function annotateBacktestOutcome(tool, result) {
+  if (tool.name !== "mcp-get-backtest-state") return result;
+  try {
+    const parsed = JSON.parse(result.content[0]?.text ?? "");
+    if (!isRecord2(parsed) || !isRecord2(parsed.Data)) return result;
+    const data = parsed.Data;
+    const status = backtestStatusNumber(data.status);
+    const reconciled = parsed.ErrNo === 10043 && data.reconciledFrom === "result.json";
+    const backtestOutcome = reconciled ? "failed" : status === 0 || status === 1 ? "running" : status === 2 ? "failed" : status === 3 ? "cancelled" : status === 4 ? "terminated" : status === 5 ? "completed" : "unknown";
+    const isTerminal2 = backtestOutcome !== "running" && backtestOutcome !== "unknown";
+    const message = typeof data.error_msg === "string" ? data.error_msg.trim() : "";
+    return {
+      ...result,
+      content: [{ type: "text", text: JSON.stringify({
+        ...parsed,
+        Data: {
+          ...data,
+          backtestOutcome,
+          isTerminal: isTerminal2,
+          evidenceSource: reconciled ? "current-attempt-result.json" : "ipc-state",
+          nextAction: isTerminal2 ? "finalize-backtest" : backtestOutcome === "unknown" || data.waitStopped || data.pollingStopped ? "inspect-backtest-state" : "keep-waiting",
+          ...backtestOutcome === "failed" && !reconciled && (!message || /异常(?:退出|终止)|unexpected.*exit|exited unexpectedly/i.test(message)) ? { failureCause: "unknown" } : {}
+        }
+      }) }]
+    };
+  } catch {
+    return result;
+  }
+}
 var ZLTAF_CONFIG_SEGMENTS = ["zltaf", "application-local.properties"];
 var FALLBACK_FACTOR_PROJECT_PATH = ["Users", "factors"];
 var factorProjectRootCache = /* @__PURE__ */ new Map();
@@ -24404,11 +24436,11 @@ function unreadableDownloadProgressError(uuid2) {
   );
 }
 function unreadableBacktestStateError(runId) {
-  return waitError(
+  return annotateBacktestOutcome(BACKTEST_WAIT_POLL_IDENTITY, waitError(
     10054,
     "\u56DE\u6D4B\u72B6\u6001\u5E94\u7B54\u65E0\u6CD5\u89E3\u6790\uFF0C\u5DF2\u505C\u6B62\u7B49\u5F85\uFF1B\u8BF7\u7528 mcp-get-backtest-state \u590D\u67E5\u3002",
     { runId }
-  );
+  ));
 }
 function factorWaitLane(executionId, session) {
   let staleCount = 0;
@@ -24557,7 +24589,7 @@ function backtestWaitLane(runId, session, codePath, resultBaseline, attemptStart
           return { verdict: "return", result: unreadableBacktestStateError(runId) };
         }
         const data = parsed.Data;
-        const status = Number(data.status);
+        const status = backtestStatusNumber(data.status);
         if (!Number.isFinite(status)) {
           return { verdict: "return", result: unreadableBacktestStateError(runId) };
         }
@@ -24598,7 +24630,10 @@ function backtestWaitLane(runId, session, codePath, resultBaseline, attemptStart
         frozenCount = signature === lastSignature ? frozenCount + 1 : 0;
         lastSignature = signature;
         if (frozenCount >= WAIT_FROZEN_THRESHOLD) {
-          return { verdict: "return", result: frozenBacktestResult(parsed, data) };
+          return { verdict: "return", result: annotateBacktestOutcome(
+            BACKTEST_WAIT_POLL_IDENTITY,
+            frozenBacktestResult(parsed, data)
+          ) };
         }
         const progress = typeof data.progress === "number" && Number.isFinite(data.progress) ? data.progress : 0;
         return { verdict: "wait", progress };
@@ -27669,6 +27704,10 @@ function compactCliReceipt(tool, result, resultFile) {
       "available",
       "runtimeReady",
       "backtestReady",
+      "backtestOutcome",
+      "isTerminal",
+      "evidenceSource",
+      "failureCause",
       "nextAction",
       "recommendedAction",
       "error_code",