@zltquant/zlt-mcp 0.4.2 → 0.5.0-beta.1

package/README.md

@@ -14,6 +14,12 @@ npx -y @zltquant/zlt-mcp list --json
 npx -y @zltquant/zlt-mcp call zlt-runtime-doctor --args-json '{}'
 ```
 
+业务调用支持 `call --output-json <新文件路径>`：完整 JSON 写入文件，stdout 返回含
+`ok`、`tool`、`resultFile`、`cliProvenance`、精简 `data` 的回执。
+输出目录须已存在，已有文件会在执行工具前报错；每次使用新文件名。完整参数与大段数据从结果文件读取。
+stderr 保留诊断，失败返回非零退出码。工具执行后若写文件失败，完整结果会输出到 stdout；先核对结果，不要自动重复执行。
+不传该参数时保持原有完整 stdout。
+
 其他支持原生 MCP 的客户端（Trae / Claude Code / Cursor 等）可以使用下面的配置：
 
 ```json

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zltquant/zlt-mcp",
-  "version": "0.4.2",
+  "version": "0.5.0-beta.1",
   "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 };
@@ -24936,6 +24971,12 @@ function echoResolvedBacktestConfig(tool, args, result, contexts) {
     const echoedRunId = typeof parsed.Data.runId === "string" ? parsed.Data.runId.trim() : "";
     const runId = echoedRunId || (tool.name === "mcp-re-backtest" && typeof args.runId === "string" ? args.runId.trim() : "");
     const context = runId ? contexts.get(runId) : void 0;
+    if (runId) echo.runId = runId;
+    if (context?.codePath) {
+      echo.codePath = context.codePath;
+      echo.runDir = context.codePath;
+    }
+    if (context?.runParams) echo.runParams = { ...context.runParams };
     if (context?.attemptStartedAtMs) {
       echo.attemptFence = {
         attemptStartedAtMs: context.attemptStartedAtMs,
@@ -27501,7 +27542,7 @@ function runtimeRecoveryStopData(message, extra = {}, handler = "runtimeStart")
 // src/index.ts
 var CLI_NAME = "zlt-mcp";
 var CLI_FALLBACK_PACKAGE_NAME = "@zltquant/zlt-mcp";
-var CLI_FALLBACK_VERSION = "0.4.2";
+var CLI_FALLBACK_VERSION = "0.5.0-beta.0";
 if (process.argv.length <= 2) {
   startMcpServer();
 } else {
@@ -27511,21 +27552,44 @@ if (process.argv.length <= 2) {
     if (kind !== "backtest") throw new Error(`Unsupported keepalive kind: ${kind}`);
     await keepMcpBacktestAlive(id, codePath);
   });
-  program2.command("call <tool>").description("Call any MCP tool through the bundled MCP server").option("--args-json <json>", "JSON object containing tool arguments").option("--args-file <path>", "Read the JSON argument object from a file").option("--timeout-ms <ms>", "MCP request inactivity timeout in milliseconds").option("--max-total-timeout-ms <ms>", "Optional hard upper bound for the request").option("--no-progress", "Suppress progress diagnostics on stderr").action(async (tool, options) => {
+  program2.command("call <tool>").description("Call any MCP tool through the bundled MCP server").option("--args-json <json>", "JSON object containing tool arguments").option("--args-file <path>", "Read the JSON argument object from a file").option("--output-json <path>", "Save the complete result to a new JSON file and print a compact receipt").option("--timeout-ms <ms>", "MCP request inactivity timeout in milliseconds").option("--max-total-timeout-ms <ms>", "Optional hard upper bound for the request").option("--no-progress", "Suppress progress diagnostics on stderr").action(async (tool, options) => {
+    let outputFd;
     try {
       const args = parseMcpArgs(options.argsJson, options.argsFile);
+      const timeoutMs = parseTimeoutOption(options.timeoutMs, "--timeout-ms");
+      const maxTotalTimeoutMs = parseTimeoutOption(options.maxTotalTimeoutMs, "--max-total-timeout-ms");
+      const resultFile = options.outputJson === void 0 ? void 0 : path14.resolve(options.outputJson);
+      if (resultFile !== void 0) outputFd = fs13.openSync(resultFile, "wx");
       const result = await callMcpTool(tool, args, {
-        timeoutMs: parseTimeoutOption(options.timeoutMs, "--timeout-ms"),
-        maxTotalTimeoutMs: parseTimeoutOption(options.maxTotalTimeoutMs, "--max-total-timeout-ms"),
+        timeoutMs,
+        maxTotalTimeoutMs,
         showProgress: options.progress !== false
       });
-      process.stdout.write(JSON.stringify(withCliProvenance(result)) + "\n");
+      const complete = withCliProvenance(result);
+      const serialized = JSON.stringify(complete) + "\n";
+      if (outputFd !== void 0 && resultFile !== void 0) {
+        try {
+          fs13.writeFileSync(outputFd, serialized, "utf-8");
+          fs13.closeSync(outputFd);
+          outputFd = void 0;
+        } catch (error2) {
+          process.stdout.write(serialized);
+          throw new Error(`Tool returned a result, but saving ${resultFile} failed; complete result is on stdout. Do not repeat the tool automatically. ${String(error2)}`);
+        }
+        const receipt = compactCliReceipt(tool, complete, resultFile);
+        process.stdout.write(JSON.stringify(receipt) + "\n");
+        if (!receipt.ok) process.exitCode = 1;
+      } else {
+        process.stdout.write(serialized);
+      }
       if (result.isError === true) process.exitCode = 1;
     } catch (error2) {
       const message = error2 instanceof Error ? error2.message : String(error2);
       process.stderr.write(`Error: ${message}
 `);
       process.exitCode = 1;
+    } finally {
+      if (outputFd !== void 0) fs13.closeSync(outputFd);
     }
   });
   program2.command("list").description("List MCP tools exposed by the bundled server").option("--json", "Emit the complete tools/list response as JSON").action(async (options) => {
@@ -27619,6 +27683,50 @@ function resolveCliPackageProvenance() {
 function withCliProvenance(result) {
   return { ...result, cliProvenance: resolveCliPackageProvenance() };
 }
+function compactCliReceipt(tool, result, resultFile) {
+  const payload = parseMcpResult(result);
+  const code = payload?.ErrNo;
+  const ok = result.isError !== true && (code === void 0 || code === null || Number(code) === 0);
+  const source = payload?.Data;
+  const data = {};
+  if (source && typeof source === "object" && !Array.isArray(source)) {
+    const fields = source;
+    for (const key of [
+      "runId",
+      "backtestId",
+      "strategyId",
+      "localPath",
+      "codePath",
+      "runDir",
+      "attemptFence",
+      "status",
+      "progress",
+      "available",
+      "runtimeReady",
+      "backtestReady",
+      "backtestOutcome",
+      "isTerminal",
+      "evidenceSource",
+      "failureCause",
+      "nextAction",
+      "recommendedAction",
+      "error_code",
+      "error_msg"
+    ]) {
+      if (fields[key] !== void 0) {
+        data[key] = key === "error_msg" && typeof fields[key] === "string" ? fields[key].slice(0, 512) : fields[key];
+      }
+    }
+  }
+  return {
+    ok,
+    tool,
+    resultFile,
+    cliProvenance: result.cliProvenance,
+    data,
+    ...!ok ? { error: { code: code ?? null, message: String(payload?.ErrMsg ?? "Tool reported an error; see resultFile").slice(0, 512) } } : {}
+  };
+}
 function parseTimeoutOption(value, flag) {
   if (value === void 0) return void 0;
   const parsed = Number(value);