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

package/README.md

@@ -7,19 +7,30 @@
 
 ## 接入
 
-WorkBuddy 使用配套 Skill，并由 Skill 调用 npm CLI 完成任务，无需配置 MCP 连接器：
+WorkBuddy 用户可从 SkillHub 安装 [zlt-quant Skill](https://skillhub.cn/skills/org-gir79457/zlt-quant)，由 Skill 调用本包的 CLI 完成量化任务，无需配置 MCP 连接器。CLI 调用示例：
 
 ```powershell
 npx -y @zltquant/zlt-mcp list --json
 npx -y @zltquant/zlt-mcp call zlt-runtime-doctor --args-json '{}'
 ```
 
+使用 `--help` 和 `call --help` 获取当前调用契约；`list --tool mcp-wait --json`
+只查询一个工具的完整 schema，未知名字返回非零退出码。简单查询直接输出，无参数可省略参数选项；
+复杂配置用 `--args-file`，大结果或下游证据才使用结果文件。保留独立 stderr 和 CLI 原始退出码，
+调用成功后再解析结果，不通过管道隐藏失败。Skill 负责工作流，不维护第二份接口契约。
+
 业务调用支持 `call --output-json <新文件路径>`：完整 JSON 写入文件，stdout 返回含
 `ok`、`tool`、`resultFile`、`cliProvenance`、精简 `data` 的回执。
 输出目录须已存在，已有文件会在执行工具前报错；每次使用新文件名。完整参数与大段数据从结果文件读取。
 stderr 保留诊断，失败返回非零退出码。工具执行后若写文件失败，完整结果会输出到 stdout；先核对结果，不要自动重复执行。
 不传该参数时保持原有完整 stdout。
 
+回测可按当前工具 schema 传基线路径与覆盖：新建用 `strategyPath`（策略根 localPath），
+重跑用 `codePath`（所选 runId 的运行目录）。MCP 先读配置并校验身份，再合并覆盖、补默认值，
+沿原有 IPC 链提交完整参数。策略根是工作区/调试配置，正式 RUN 不保证更新根目录；运行目录用于该次结果对账。
+无覆盖时省略 runParams，由 ZLTAF 读取库中参数；部分覆盖需合并完整基线。版本管理开启时已执行的正式 RUN 必须新建记录，不自动绕过拒绝。
+`configurationEvidence` 标明基线来源/哈希与 `persistenceVerified=false`；提交回显不代表文件和数据库已回读一致。
+
 其他支持原生 MCP 的客户端（Trae / Claude Code / Cursor 等）可以使用下面的配置：
 
 ```json
@@ -48,6 +59,8 @@ npm i @zltquant/zlt-mcp --prefix "$env:USERPROFILE\.zlt-quant" --registry https:
 
 ## 配套技能
 
+推荐从 SkillHub 安装 [zlt-quant Skill](https://skillhub.cn/skills/org-gir79457/zlt-quant)，用于策略生成、回测执行与验收、结果分析和环境准备。
+
 量化技能（策略生成、回测执行与验收、结果分析、装机引导）见 gitee 组合仓，
 克隆后运行 `install.ps1`：
 

package/config.json

@@ -507,7 +507,7 @@
     },
     {
       "name": "mcp-create-and-run-backtest",
-      "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。",
+      "description": "创建并启动回测。strategyId 必须来自 mcp-create-strategy 返回的策略ID；runType 固定为 2；推荐传 strategyPath（策略 localPath）和 runParams 中本次要改的字段；MCP 读取策略根目录当前配置，合并覆盖后形成完整提交参数，再走原有 run/create → run/run 同步链，不由 Agent 直接改文件或写库。策略根目录是工作区/调试配置，正式 RUN 模式不会保证更新它；只有 DEBUG 路径显式双写根目录和运行目录。不要称根目录为最近正式回测参数，运行身份以返回 runId 为准。没有 strategyPath 时保持旧式完整参数调用；仅真正缺失的字段补默认值。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、runParams 和 evidence.effectiveRunParams 是 MCP 补全后的提交参数，不是文件/数据库回读确认。configurationEvidence 标明提交证据及基线来源/哈希，persistenceVerified=false；运行目录 tradesetting.json 和库中对应运行记录是落盘对账依据。evidence 同时给出 backtestId、runDir 和代码快照 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": "回测参数。有 tradesetting.json 配置基线时显式传入 schema 支持的已有字段（日期、资金、账户、频率、市场、预加载、参数/费率模板），用户本次要求覆盖对应字段；账户现金与初始资金保持一致。仅无用户要求且无配置基线的字段采用 MCP 默认值。",
+            "description": "本次参数覆盖。提供 strategyPath 时先读策略当前配置，再递归合并对象覆盖（数组整体替换），最后补系统默认值；不需要复述整套费率。只改 initial_capital 时同步单账户现金；多账户须明确分配。未提供 strategyPath 时必须自行携带已有配置基线，省略值会使用系统默认值。",
             "properties": {
               "account_list": {
                 "type": "array",
@@ -651,6 +651,10 @@
               }
             },
             "additionalProperties": false
+          },
+          "strategyPath": {
+            "type": "string",
+            "description": "策略根目录绝对路径，使用策略创建/详情返回的 localPath；不是 backtest 下的运行副本。提供时 MCP 读取该目录 .vscode/tradesetting.json 作为当前配置基线，runParams 只传本次覆盖；路径或 strategy_id 不匹配时在执行前拒绝。不提供时保持完整参数/系统默认值的兼容调用，不自动定位磁盘配置。"
           }
         },
         "required": [
@@ -742,7 +746,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* 是本次实际生效的区间、资金与基准，向用户报告时以它为准。\n\n重跑启动后同样立即调用 mcp-wait（kind=backtest，id=runId）阻塞等待结束，不要轮询状态；隐藏 guardian 会自行携带 attemptFence；任何后续显式 CLI call 或 MCP 重启后的调用，还要复用最初创建结果的 codePath，并传回本次重跑响应里的 attemptFence。",
+      "description": "运行指定 runId 的代码副本，不会把你在策略源工程里刚改过的 main.py 拷进去。ZLTAF 启用回测版本管理时，正式 RUN 记录一旦执行过就不能同 runId 重跑，会返回“请先创建新的回测记录”；这时报告限制，不自动重试、改 DEBUG 或绕过版本管理。需要新一轮实验时按用户授权使用 mcp-create-and-run-backtest。\n\n不改变参数时省略 runParams 或传空对象，MCP 不补旧缓存参数，由 ZLTAF 读取数据库 run_params。改变部分参数时传所选 runId 的 codePath，MCP 校验运行配置并递归合并覆盖，形成完整参数；无路径时只兼容有缓存基线或完整参数的调用。ZLTAF 对非空参数整体采用，不自行合并。返回 configurationEvidence 区分 mcp_submission 与 zltaf_stored_parameters；两者均不证明文件/数据库已回读一致。后者不回显猜测的 effectiveRunParams。\n\n成功启动后按 runId、codePath、attemptFence 调用 mcp-wait，再由收尾读取该次运行文件和终态。根目录不作为历史配置，策略实际基准也不由请求值证明。",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -760,7 +764,7 @@
           },
           "codePath": {
             "type": "string",
-            "description": "可选的回测运行目录。CLI 独立命令或 MCP 重启后必须传最初创建回测返回的绝对 codePath；仅用于 result.json 新旧轮次对账，不发送给 IPC。"
+            "description": "所选 runId 的运行目录绝对路径，用于身份校验、部分覆盖的配置基线和后续等待定位，不发送给 IPC。无参数覆盖时不把文件内容作为 runParams 重发；数据库配置由 ZLTAF 读取。"
           },
           "runType": {
             "type": "integer",
@@ -772,7 +776,7 @@
           },
           "runParams": {
             "type": "object",
-            "description": "回测参数，与 mcp-create-and-run-backtest 的 runParams 同构，字段说明见该工具。默认沿用最近一次创建回测的条件，用户只需要说明想修改的字段，没传的字段（含基准、撮合模式、滑点、费率模板）都按上一次原样继承；MCP 重启会丢掉这份上下文，之后必须传完整参数，否则会以「缺少必填字段」失败。改用期货市场（marketIds 含 zj/zs/ds/sq/gq）时，account_list 的 account_type 要一并改为 2（期货）。",
+            "description": "省略或空对象表示使用 ZLTAF 数据库存储参数，不依赖 MCP 缓存。非空对象表示本次覆盖：提供 codePath 时读取所选运行配置并递归合并；数组整体替换，多账户资金须明确分配。无 codePath 时需要缓存基线或完整参数，禁止把部分参数直接发送给会整体替换的后端。",
             "properties": {
               "marketIds": {
                 "type": "array",
@@ -795,10 +799,7 @@
         },
         "required": [
           "strategyId",
-          "strategyName",
-          "runId",
-          "runType",
-          "runParams"
+          "runId"
         ],
         "additionalProperties": false
       },

package/package.json

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