@zltquant/zlt-mcp 0.7.2-beta.0 → 0.7.2

package/package.json

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

package/zlt-mcp-proxy.bundle.cjs

@@ -10609,11 +10609,59 @@ var {
 // src/cli-evidence.ts
 var fs = __toESM(require("node:fs"), 1);
 var path = __toESM(require("node:path"), 1);
+var READABLE_LINE_LIMIT = 1e3;
+function readableValue(value) {
+  if (Array.isArray(value)) return value.map(readableValue);
+  if (!value || typeof value !== "object") return value;
+  const source = value;
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [key, entry] of Object.entries(source)) result[key] = readableValue(entry);
+  if (source.type === "text" && typeof source.text === "string") {
+    try {
+      result.text = {
+        displayNote: "Parsed from content[].text JSON. Exact original text remains in result.json.",
+        parsedJson: readableValue(JSON.parse(source.text))
+      };
+    } catch {
+      result.text = source.text;
+    }
+  }
+  return result;
+}
+function takeChunk(value, limit) {
+  let end = Math.min(limit, value.length);
+  if (end < value.length && end > 0) {
+    const code = value.charCodeAt(end - 1);
+    if (code >= 55296 && code <= 56319) end -= 1;
+  }
+  return [value.slice(0, end), value.slice(end)];
+}
+function buildReadableEvidence(value) {
+  const header = [
+    "ZLT CLI readable evidence v1 - DISPLAY ONLY; result.json is the authoritative complete saved result.",
+    "WRAPPING: | starts a rendered logical line; + continues the preceding line. Strip the first character and join + lines before interpretation.",
+    "Embedded content[].text that is valid JSON is expanded under parsedJson; non-JSON text is preserved as text."
+  ];
+  const rendered = JSON.stringify(readableValue(value), null, 2).split("\n");
+  const lines = [...header];
+  for (const logical of rendered) {
+    let remaining = logical;
+    let marker = "|";
+    do {
+      const [chunk, rest] = takeChunk(remaining, READABLE_LINE_LIMIT - 1);
+      lines.push(marker + chunk);
+      marker = "+";
+      remaining = rest;
+    } while (remaining.length > 0);
+  }
+  return lines.join("\n") + "\n";
+}
 function evidenceDirectoryArg(args) {
-  if (!["call", "list"].includes(args[0])) return void 0;
+  const authCommand = args[0] === "auth" && ["login", "status", "wait"].includes(args[1]);
+  if (!["call", "list"].includes(args[0]) && !authCommand) return void 0;
   let directory;
-  const valueOptions = /* @__PURE__ */ new Set(["--args-json", "--args-file", "--output-json", "--tool", "--timeout-ms", "--max-total-timeout-ms"]);
-  for (let i = 1; i < args.length && args[i] !== "--"; i++) {
+  const valueOptions = /* @__PURE__ */ new Set(["--args-json", "--args-file", "--output-json", "--tool", "--timeout-ms", "--max-total-timeout-ms", "--session"]);
+  for (let i = authCommand ? 2 : 1; i < args.length && args[i] !== "--"; i++) {
     const arg = args[i];
     if (valueOptions.has(arg)) {
       i++;
@@ -10629,6 +10677,7 @@ function evidenceDirectoryArg(args) {
 }
 var CliEvidence = class {
   resultFile;
+  readableFile;
   diagnosticsFile;
   executionFile;
   state;
@@ -10640,6 +10689,7 @@ var CliEvidence = class {
     const root2 = path.resolve(directory);
     fs.mkdirSync(root2);
     this.resultFile = path.join(root2, "result.json");
+    this.readableFile = path.join(root2, "result.readable.txt");
     this.diagnosticsFile = path.join(root2, "diagnostics.log");
     this.executionFile = path.join(root2, "execution.json");
     this.state = {
@@ -10653,6 +10703,7 @@ var CliEvidence = class {
       business: "not_reported",
       exitCode: null,
       resultFile: this.resultFile,
+      readableFile: this.readableFile,
       diagnosticsFile: this.diagnosticsFile,
       retry: "inspect_state_before_retry"
     };
@@ -10682,6 +10733,13 @@ var CliEvidence = class {
   checkDiagnostics() {
     if (this.diagnosticFailure) throw new Error(`Saving diagnostics failed: ${this.diagnosticFailure.message}`);
   }
+  writeReadable(value) {
+    fs.writeFileSync(this.readableFile, buildReadableEvidence(value), { encoding: "utf8", flag: "wx" });
+  }
+  writeResult(value) {
+    fs.writeFileSync(this.resultFile, JSON.stringify(value) + "\n", { encoding: "utf8", flag: "wx" });
+    this.writeReadable(value);
+  }
   started(tool) {
     this.checkDiagnostics();
     this.state = { ...this.state, ...tool ? { tool } : {}, stage: "tool_call", toolExecution: "unknown" };
@@ -10730,7 +10788,7 @@ var CliEvidence = class {
     this.failed(stage, this.state.toolExecution, this.state.business);
   }
   receiptFields() {
-    return { executionFile: this.executionFile, diagnosticsFile: this.diagnosticsFile };
+    return { executionFile: this.executionFile, diagnosticsFile: this.diagnosticsFile, readableFile: this.readableFile };
   }
   close() {
     if (process.stderr.write === this.teeWrite) process.stderr.write = this.originalWrite;
@@ -10919,6 +10977,7 @@ function buildCliUsage(tool, tools) {
         mutuallyExclusiveWith: "--output-json",
         files: {
           resultJson: "result.json is exclusively reserved before execution. It is parseable only after a complete response is saved; existence alone does not prove a response was received, and disconnects or write failures can leave it empty or partial.",
+          resultReadableTxt: "result.readable.txt is a display-only, line-bounded view that expands JSON inside content[].text without truncating content. result.json remains authoritative.",
           diagnosticsLog: "diagnostics.log captures CLI and child-MCP diagnostics while stderr remains live.",
           executionJson: "execution.json records state, toolExecution, business outcome, and the CLI exitCode."
         },
@@ -29220,6 +29279,7 @@ var path25 = __toESM(require("node:path"), 1);
 var import_node_crypto5 = require("node:crypto");
 var SOURCE = "zlt-mcp-device-login";
 var IGNORED_API_ENV = /* @__PURE__ */ new Set(["ZLTQUANT_API_KEY", "ZLTQUANT_API_BASE"]);
+var SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function authCliEnv(env) {
   return Object.fromEntries(
     Object.entries(env).filter(([key]) => !IGNORED_API_ENV.has(key.toUpperCase()))
@@ -29289,9 +29349,12 @@ function authErrorMessage(error2) {
   return "Authentication operation failed; check local credential configuration and storage permissions. No credential was returned.";
 }
 function sessionPath(id, e = process.env) {
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) throw Error("Invalid authentication session");
+  if (!SESSION_ID.test(id)) throw Error("Invalid authentication session");
   return path25.join(root(e), id + ".json");
 }
+function validateAuthSessionId(id) {
+  if (!SESSION_ID.test(id)) throw Error("Invalid authentication session");
+}
 function drop(id, e = process.env) {
   fs26.rmSync(sessionPath(id, e), { force: true });
 }
@@ -29299,7 +29362,7 @@ function preflight(e) {
   if (e.ZLTQUANT_CREDENTIALS || readCredentials(e))
     throw Error("Authentication is already configured");
 }
-async function finish(s, e, c, json) {
+async function finish(s, e, c, json, emit = true) {
   const grant = await c.poll(s, {
     maxDurationMs: s.expiresIn * 1e3
   });
@@ -29314,7 +29377,7 @@ async function finish(s, e, c, json) {
     apiKeyMask: a.apiKeyMask,
     apiBase: a.apiBase
   };
-  process.stdout.write(json ? JSON.stringify(o) + "\n" : `Signed in (${a.apiKeyMask}).
+  if (emit) process.stdout.write(json ? JSON.stringify(o) + "\n" : `Signed in (${a.apiKeyMask}).
 `);
   return o;
 }
@@ -29332,10 +29395,10 @@ async function runAuthLogin(o = {}) {
       expiresIn: s.expiresIn,
       widget: buildShowWidgetPayload(s)
     };
-    process.stdout.write(JSON.stringify(out) + "\n");
+    if (o.emit !== false) process.stdout.write(JSON.stringify(out) + "\n");
     return out;
   }
-  process.stdout.write(
+  if (o.emit !== false) process.stdout.write(
     o.json ? JSON.stringify({
       status: "pending",
       verificationUri: s.verificationUri,
@@ -29343,7 +29406,7 @@ async function runAuthLogin(o = {}) {
     }) + "\n" : `Open ${s.verificationUri} and enter code ${s.userCode}.
 `
   );
-  return finish(s, e, c, o.json);
+  return finish(s, e, c, o.json, o.emit !== false);
 }
 async function runAuthWait(id, o = {}) {
   const e = authCliEnv(o.env || process.env);
@@ -29357,7 +29420,7 @@ async function runAuthWait(id, o = {}) {
   }
   try {
     const x = load(id, e);
-    const result = await finish(x.authorization, e, o.client || client, o.json);
+    const result = await finish(x.authorization, e, o.client || client, o.json, o.emit !== false);
     drop(id, e);
     return result;
   } catch (error2) {
@@ -29401,7 +29464,10 @@ if (process.argv.length <= 2) {
   let evidenceSetupError;
   try {
     const directory = evidenceDirectoryArg(process.argv.slice(2));
-    if (directory !== void 0) evidence = new CliEvidence(directory, resolveCliPackageProvenance(), process.argv[2]);
+    if (directory !== void 0) {
+      const command = process.argv[2] === "auth" ? `auth ${process.argv[3] ?? ""}`.trim() : process.argv[2];
+      evidence = new CliEvidence(directory, resolveCliPackageProvenance(), command);
+    }
   } catch (error2) {
     evidenceSetupError = error2;
   }
@@ -29422,34 +29488,127 @@ if (process.argv.length <= 2) {
   });
   program2.name(CLI_NAME).description("MCP proxy for ZLTHost IPC service").version(resolveCliVersion()).configureOutput({ outputError: writeCliArgumentError }).addHelpText("after", "\nDiscovery: list for names; list --tool <name> --json for one complete input schema.\nUse call --help for input, output and diagnostic handling.\nFor npx registry selection, put --registry before the package name; it is not a zlt-mcp option.");
   const auth = program2.command("auth").description("Manage local ZLT Quant authentication");
-  auth.command("login").description("Sign in with a device code").option("--json", "Emit a JSON descriptor and status").option("--widget", "Return a login card immediately; render it before running auth wait").addHelpText("after", "\nAgent flow: auth login --widget --json returns a local session ID and widget descriptor.\nInvoke the host show_widget tool with widget.arguments, or show the login URL/code.\nThen run auth wait --session <returned-id> --json. The descriptor alone does not render a widget.\nWithout --widget this command waits in the foreground. Never paste keys or private session files into chat.").action(async (options) => {
+  auth.command("login").description("Sign in with a device code").option("--json", "Emit a JSON descriptor and status").option("--widget", "Return a login card immediately; render it before running auth wait").option("--evidence-dir <path>", "Create a new directory for the display-safe login descriptor and execution status; requires --widget").addHelpText("after", "\nAgent flow: auth login --widget --json returns a local session ID and widget descriptor.\nInvoke the host show_widget tool with widget.arguments, or show the login URL/code.\nThen run auth wait --session <returned-id> --json. The descriptor alone does not render a widget.\nWithout --widget this command waits in the foreground. Never paste keys or private session files into chat.").action(async (options) => {
+    let toolExecution = "not_started";
+    let stage = "arguments";
+    let response;
     try {
-      await runAuthLogin(options);
+      if (evidence && !options.widget) throw new Error("--evidence-dir requires --widget for auth login");
+      evidence?.started();
+      toolExecution = evidence ? "unknown" : "not_started";
+      stage = "auth_login";
+      const result = await runAuthLogin({ ...options, emit: !evidence });
+      response = result;
+      if (!evidence) return;
+      toolExecution = "response_received";
+      stage = "output_write";
+      evidence.writeResult(result);
+      stage = "output_emit";
+      evidence.completed("not_reported", 0);
+      process.stdout.write(JSON.stringify({
+        ok: true,
+        command: "auth login",
+        resultFile: evidence.resultFile,
+        cliProvenance: resolveCliPackageProvenance(),
+        ...evidence.receiptFields()
+      }) + "\n");
     } catch (error2) {
-      process.stderr.write(`Error: ${authErrorMessage(error2)}
+      if (toolExecution === "response_received" && response !== void 0) {
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
+      const message = error2 instanceof Error && error2.message === "--evidence-dir requires --widget for auth login" ? error2.message : authErrorMessage(error2);
+      process.stderr.write(`Error: ${message}
 `);
       process.exitCode = 1;
+      try {
+        evidence?.failed(stage, toolExecution);
+      } catch (saveError) {
+        process.stderr.write(`Error: execution evidence could not be finalized: ${String(saveError)}
+`);
+      }
     }
   });
-  auth.command("status").description("Show masked local authentication status").option("--json", "Emit JSON").action((options) => {
+  auth.command("status").description("Show masked local authentication status").option("--json", "Emit JSON").option("--evidence-dir <path>", "Create a new directory for the masked status and execution state").action((options) => {
+    let toolExecution = "not_started";
+    let stage = "status_query";
+    let response;
     try {
+      evidence?.started();
+      toolExecution = evidence ? "unknown" : "not_started";
       const status = authStatus();
-      process.stdout.write(options.json ? `${JSON.stringify(status)}
+      response = status;
+      if (!evidence) {
+        process.stdout.write(options.json ? `${JSON.stringify(status)}
 ` : `${status.configured ? `Configured (${status.apiKeyMask})` : "Not configured"}
 `);
+        return;
+      }
+      toolExecution = "response_received";
+      stage = "output_write";
+      evidence.writeResult(status);
+      stage = "output_emit";
+      evidence.completed("not_reported", 0);
+      process.stdout.write(JSON.stringify({
+        ok: true,
+        command: "auth status",
+        resultFile: evidence.resultFile,
+        cliProvenance: resolveCliPackageProvenance(),
+        ...evidence.receiptFields()
+      }) + "\n");
     } catch (error2) {
+      if (toolExecution === "response_received" && response !== void 0) {
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
       process.stderr.write(`Error: ${authErrorMessage(error2)}
 `);
       process.exitCode = 1;
+      try {
+        evidence?.failed(stage, toolExecution);
+      } catch (saveError) {
+        process.stderr.write(`Error: execution evidence could not be finalized: ${String(saveError)}
+`);
+      }
     }
   });
-  auth.command("wait").description("Complete a saved device-code sign in").requiredOption("--session <id>", "Opaque local session ID from auth login --widget").option("--json", "Emit JSON").action(async (options) => {
+  auth.command("wait").description("Complete a saved device-code sign in").requiredOption("--session <id>", "Opaque local session ID from auth login --widget").option("--json", "Emit JSON").option("--evidence-dir <path>", "Create a new directory for the display-safe wait receipt and execution state").action(async (options) => {
+    let toolExecution = "not_started";
+    let stage = "arguments";
+    let business = "not_reported";
+    let response;
     try {
-      await runAuthWait(options.session, options);
+      if (evidence) validateAuthSessionId(options.session);
+      evidence?.started();
+      toolExecution = evidence ? "unknown" : "not_started";
+      stage = "auth_wait";
+      const result = await runAuthWait(options.session, { ...options, emit: !evidence });
+      response = result;
+      if (!evidence) return;
+      toolExecution = "response_received";
+      business = "success";
+      stage = "output_write";
+      evidence.writeResult(result);
+      stage = "output_emit";
+      evidence.completed("success", 0);
+      process.stdout.write(JSON.stringify({
+        ok: true,
+        command: "auth wait",
+        resultFile: evidence.resultFile,
+        cliProvenance: resolveCliPackageProvenance(),
+        ...evidence.receiptFields()
+      }) + "\n");
     } catch (error2) {
+      if (toolExecution === "response_received" && response !== void 0) {
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
       process.stderr.write(`Error: ${authErrorMessage(error2)}
 `);
       process.exitCode = 1;
+      try {
+        evidence?.failed(stage, toolExecution, business);
+      } catch (saveError) {
+        process.stderr.write(`Error: execution evidence could not be finalized: ${String(saveError)}
+`);
+      }
     }
   });
   auth.command("logout").description("Remove only CLI-login-owned credentials locally; does not revoke the gateway key").option("--json", "Emit JSON").action((options) => {
@@ -29504,9 +29663,13 @@ if (process.argv.length <= 2) {
           const fd = outputFd;
           outputFd = void 0;
           fs27.closeSync(fd);
+          if (evidence) {
+            stage = "readable_write";
+            evidence.writeReadable(complete);
+          }
         } 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)}`);
+          throw new Error(`Tool returned a result, but saving its evidence failed; complete result is on stdout and any saved result.json remains authoritative. Do not repeat the tool automatically. ${String(error2)}`);
         }
         stage = "output_emit";
         evidence?.completed(business, exitCode);
@@ -29563,6 +29726,7 @@ if (process.argv.length <= 2) {
   });
   program2.command("list").description("List MCP tools exposed by the bundled server").option("--json", "Emit the complete tools/list response as JSON").option("--tool <name>", "Select one exact tool name; combine with --json for its complete schema").option("--evidence-dir <path>", "Create a new directory for discovery, diagnostics and execution status").addHelpText("after", "\nReuse discovery within a task. Query one schema with list --tool <name> --json.\nUnknown names fail with exit code 1. Preserve stderr separately from JSON stdout.").action(async (options) => {
     let toolExecution = "not_started";
+    let stage = "discovery";
     try {
       evidence?.started();
       toolExecution = "unknown";
@@ -29577,7 +29741,8 @@ if (process.argv.length <= 2) {
         const complete = withCliProvenance(result);
         const serialized = JSON.stringify(complete) + "\n";
         try {
-          fs27.writeFileSync(evidence.resultFile, serialized, { encoding: "utf8", flag: "wx" });
+          stage = "output_write";
+          evidence.writeResult(complete);
           evidence.completed("not_reported", 0);
         } catch (error2) {
           process.stdout.write(serialized);
@@ -29609,7 +29774,7 @@ if (process.argv.length <= 2) {
 `);
       process.exitCode = 1;
       try {
-        evidence?.failed("discovery", toolExecution);
+        evidence?.failed(stage, toolExecution);
       } catch (saveError) {
         process.stderr.write(`Error: execution evidence could not be finalized: ${String(saveError)}
 `);