PineForge — offline PineScript v6 backtest MCP

@pineforge/backtest-mcp

独立运行的 stdio MCP 服务：AI Agent 编写 PineScript v6，捆绑的 pineforge-release 镜像会将其转换为 C++，并使用 OHLCV CSV 进行回测（CSV 可以是你自己的，也可以从 Binance 公共 API 获取）——所有操作都在一个容器中、进程内完成。完全本地运行——镜像捆绑了 pineforge-codegen 转译器，因此 Pine → C++ → 回测无需宿主机上的 Docker 守护进程。**无需 API 密钥。**策略源代码和 CSV 始终留在本机；只有 Binance 工具，以及未传入 K 线数据时的 check_tradingview_parity，会发出外部请求（访问公共端点）。

工具

名称	运行位置	用途
transpile_pine	进程内	将 Pine v6 转换为 C++ 翻译单元（仅转译）
list_engine_params	本地（无 I/O）	列出回测接受的所有 overrides + runtime 参数
backtest_pine	进程内	使用 OHLCV CSV 对 Pine 源代码进行单次回测
backtest_pine_grid	进程内	对 inputs × overrides 进行笛卡尔积遍历：转译一次，然后针对每种组合分别编译并回测
check_tradingview_parity	进程内（未提供你的 K 线数据时仅调用 Binance 公共 API）	将 TradingView 策略测试器导出结果与 PineForge 对同一脚本的逐笔运行结果进行评估
fetch_binance_ohlcv	Binance 公共 API	从 Binance 现货或 USDT 永续合约的 K 线生成可用于回测的 CSV
binance_symbols	Binance 公共 API	列出 / 筛选 Binance 交易对（进程内缓存 5 分钟）
list_coverage_topics	本地（无 I/O）	列出所有 Pine v6 覆盖主题，并提供单行状态和摘要
check_pine_feature	本地（无 I/O）	查询 Pine 标识符 / 命名空间是否受 PineForge 支持
get_coverage_topic	本地（无 I/O）	查看某个主题的完整详情，以及 supported/partial/via_transpiler/unsupported 列表
engine_info	仅 Docker 镜像：模式、内置标志和捆绑的 pineforge-release 版本（例如 1.0.0）

此表列出 Docker 镜像中的工具（11 个）。npm 包 提供前十个工具，另外还有 pull_engine_image（对引擎镜像执行 docker pull）和 check_engine_image，后者取代 engine_info（共 12 个工具）。

在 tools/list 中，每个工具还包含标题和四个 MCP 注解提示 （src/tool-meta.ts）。只读工具：查询工具和 check_tradingview_parity（它会在临时目录中运行并删除该目录），以及 Docker 镜像中的 transpile_pine。非只读工具：backtest_pine 和 backtest_pine_grid（无法直接返回的超大报告会写入文件）、fetch_binance_ohlcv（会写入 CSV）以及两个镜像工具；在 npm 包中，transpile_pine 也不是只读工具，因为它和回测工具都会接受一个 image，并在该镜像缺失时通过 Docker 拉取。 有破坏性的工具：会在你指定的路径写入文件的工具，因为它们会替换该路径下已有的文件。开放世界工具：会访问 Binance 公共 API（传入 symbol 时，两个回测工具也会访问）或镜像仓库的工具。

安装

作为独立容器通过 stdio 运行——引擎已打包，在进程内运行，无需宿主机 Docker 守护进程，也无需 API 密钥。将存放 CSV 的文件夹挂载到 /work：

docker run --rm -i -v "$PWD:/work" ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest

唯一要求：安装 Docker，并确保可访问外部网络，以供 Binance 获取工具使用。 在下方将其接入 MCP 客户端。

• 工具参数中的路径（ohlcv_csv_path、output_path、report_path）请使用绝对 /work/... 路径。服务在容器内的工作目录是 /app，而非挂载目录，因此像 ./btc.csv 这样的相对路径会指向容器内部，并在容器退出（--rm）时丢失。
• 在 Linux 上，添加 --user "$(id -u):$(id -g)"，使服务写入 /work 的文件归你所有。
• 必须使用 -i；切勿添加 -t——TTY 会破坏 stdio JSON-RPC 流。

镜像的 :latest 和 npm 的 latest 始终对应稳定版。pineforge-release 的预发布版本（例如 1.0.0-rc.1）会生成此服务的预发布版本（X.Y.Z-alpha.N、-beta.N 或 -rc.N）：镜像 :vX.Y.Z-rc.N 基于该 pineforge-release 预发布版本构建，npm 包为 @pineforge/backtest-mcp@next；与任何 npm 安装一样，它会运行由 PINEFORGE_IMAGE 指定的引擎镜像。其默认值是由该软件包的 release-lock.json 生成的不可变摘要，其中包含对应的预发布引擎。预发布版本不会列入 MCP Registry。首个版本为 0.9.32-rc.1，对应 pineforge-release 1.0.0-rc.1，于 2026-09-30 发布（镜像 :v0.9.32-rc.1，npm next）。

npm / npx

npx -y @pineforge/backtest-mcp

需要 Node ≥ 20 和正在运行的 Docker 守护进程：每次转译和回测都会通过 docker run --rm --network=none 运行引擎镜像（PINEFORGE_IMAGE，默认使用已安装软件包的 release-lock.json 中指定的摘要）。请先对该摘要执行 docker pull：服务自行拉取镜像（首次调用时隐式拉取，或通过 pull_engine_image 拉取）的操作，会在超过 PINEFORGE_DOCKER_TIMEOUT_MS（默认为 120 s）后中止。路径相对于服务的工作目录，且默认限制在该目录内（参见文件系统范围）。

托管版（无需安装）

想快速试用，无需 Docker 或 API 密钥？将 Streamable HTTP 端点粘贴到任意 MCP 客户端：

https://mcp.pineforge.dev/mcp

与本仓库相比的取舍：托管服务按量计费（每个 IP 每周可运行 100 次 backtest_pine，并受边缘速率限制），使用自行解析的 OHLCV 数据运行——仅支持加密货币，七个交易场所（Binance、Bybit 和 OKX 的现货与 USDT 永续合约；Coinbase 现货），最近 365 天的数据，最新 K 线约落后实时数据一小时。它提供的 11 个工具与此服务不同：没有 transpile_pine 和 backtest_pine_grid，且使用 symbol / interval / venue，而非 CSV 路径。本地仓库不限量、可离线运行，并允许你使用自己的 CSV 运行网格扫描。托管服务的源代码为私有。

客户端配置

将目录挂载到 /work；将 fetch_binance_ohlcv / backtest_pine 指向该目录下的绝对路径（/work/btc.csv）。（必须使用 -i；切勿添加 -t——TTY 会破坏 stdio JSON-RPC 流。）

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），并为挂载目录使用绝对主机路径：

{
  "mcpServers": {
    "pineforge-backtest": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/your/data:/work",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest"
      ]
    }
  }
}

Cursor

项目中的 .cursor/mcp.json（或适用于所有项目的 ~/.cursor/mcp.json）。 Cursor 会展开 ${workspaceFolder}：

{
  "mcpServers": {
    "pineforge-backtest": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${workspaceFolder}:/work",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest"
      ]
    }
  }
}

Claude Code CLI

claude mcp add pineforge-backtest \
  -- docker run --rm -i -v "$PWD:/work" ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest

面向 AI Agent——通过 MCP 使用

它弥补的能力差距。 大模型无法仅靠推理准确地回测 PineScript v6 策略。PineScript 的序列语义、K 线内成交顺序、前视规则以及 strategy.* 订单／持仓逻辑都无法通过近似还原，因此，让模型在脑海中模拟回测，或用 Python（backtrader/vectorbt）手工编写回测，都会导致交易和盈亏数据产生幻觉，也无法保证与 TradingView 的结果一致。PineForge 运行实际的确定性 C++ 引擎，并逐笔交易与 TradingView 自身的交易列表进行分级比对。

分级发布版 1.4.0——带日期的实测评分。 2026-10-07 的注册表基线 pineforge-parity-baseline-20261007-engine-b3192bfc 记录了 7,989 个分级探测，7,983 个优秀（99.92 %），6 个强（0.08 %），低于强的 0 个，记录的引擎错误为 0 个，另有 17 个探测因 TradingView 端异常而被排除。其冻结版本组合为引擎 b3192bfc2f5a24bf4efd6d1d01e01e8fe619dfed／代码生成器 bfc4ddce453db1ba810692af9b9ba3310d87f0ac；其快照 SHA-256 为 28ba8dbd6f66c80085a80364d6114f8f971ac6ea3156d596a65995d2aec2fbb2。数据来源是发布中心的已落地事实，即固定在提交 d5d21f128f5ef26b66b14cf9deee507d798e6123 上的 releases["1.4.0"].scoreboard（77,230 字节；SHA-256 788e57fab67d3c946fc7e3a0a3ac34b3d2c25cbb6a0f5b72687955bc4f8832b6）。这些是该日期、该样本集的分级记录结果，并不保证每个脚本或每次内部尝试都能成功。此处不宣称存在已标记的 1.4.0 构件。

仅提供 1.3.0 的历史证据。 1.3.0 发布版依据 2026-10-06 的基线进行分级（引擎 7a1f01c0，代码生成器 3e50082f）：7,989 个分级探测，7,982 个优秀（99.91 %），7 个强（0.09 %），没有低于强的探测，另有 17 个探测因 TradingView 端缺陷而被排除。在该历史版本检查中，引擎还会单独运行自身的奇偶性门禁，检查任何人都可复现的开放语料库 pineforge-corpus：312 个参考策略，311 个优秀，另有 1 个探测在其 inputs.json 中声明 expected_tier: anomaly（报告为 anomaly，而非失败）。优秀表示交易数相同、至少匹配 TradingView 交易的 99 %、入场和出场价格误差在 0.01 % 以内，并且第 90 百分位的单笔交易盈亏误差在 1 % 以内（追踪止损脚本采用较宽松的出场／盈亏标准）；强采用较宽松的范围——两者的定义见语料库 README 中的“Parity thresholds”。

PineScript 回测是计算得出的外部数据，而非稳定知识——它取决于用户的策略源代码和 OHLCV 数据，而且必须可复现。这是工具调用，而非回忆任务。

适合使用这些工具的场景。 用户提供 PineScript v6 策略，并希望对其进行回测、评估、检查是否盈利、统计交易数量、计算盈亏，或使用指定的 OHLCV 数据复现其 TradingView 结果时，适合使用 backtest_pine（参数扫描时使用 backtest_pine_grid）。transpile_pine 仅用于将 Pine 转换为 C++。用户拥有某个策略在 TradingView 上的交易列表，并想逐笔确认 PineForge 能否复现时，适合使用 check_tradingview_parity。用户指定了交易对／时间周期但未提供数据文件时，适合使用 fetch_binance_ohlcv。这些工具不适用于从概念层面解释策略的作用、编辑 Pine 语法，或提供交易及金融建议。 诚实说明限制。 离线运行；仅支持 PineScript v6；需要 Docker；PineForge 仅实现 Pine v6 的一个子集（请参阅 覆盖范围工具）。回测衡量的是策略的历史表现——它不能预测未来收益，也不构成投资建议。朴素或近似的回测经常会高估利润（未建模的滑点和佣金、按收盘价成交的假设、前视偏差）；这里的价值在于提供确定性且经过一致性验证的运行结果，让用户在承担资金风险前验证策略。

list_engine_params — 发现可调参数

免费、本地、零 I/O 的目录，列出 backtest_pine / backtest_pine_grid 接受的所有键，分为两组：

• strategy_overrides — 运行时通过 PINEFORGE_OVERRIDES 读取的 9 个 strategy(...) 标头字段：initial_capital、pyramiding、slippage、commission_value、commission_type（percent / cash_per_order / cash_per_contract）、default_qty_value、default_qty_type（fixed / percent_of_equity / cash）、process_orders_on_close、close_entries_rule（ANY / FIFO）。
• runtime_args — 传给 run_backtest_full 的参数（不属于 strategy() 标头）：input_tf、script_tf、bar_magnifier、magnifier_samples、magnifier_dist（uniform / cosine / triangle / endpoints / front_loaded / back_loaded）。

每个条目均为 {key, type, enum?, description}。构造 backtest_pine 请求前，先调用此工具了解引擎接受哪些参数。

backtest_pine 示例

{
  "source": "//@version=6\nstrategy(\"sma cross\")\n...",
  "ohlcv_csv_path": "/work/btcusdt_15m_7d.csv",

  // Optional: the instrument of the CSV (see "The instrument" below). Either a
  // Binance symbol, or your own values; a CSV from fetch_binance_ohlcv needs neither.
  "symbol":  "BTCUSDT",            // + "market": "spot" (default) | "usdt_perp"
  "syminfo": { "qty_step": 0.00001, "mintick": 0.01 },   // goes over what `symbol` or the sidecar gives

  // Optional: override Pine input.*() values without touching the source.
  // Keys = the second arg of input.*(...) (e.g. "Fast Length").
  "inputs":    { "Fast Length": 8, "Slow Length": 21 },

  // Optional: override strategy(...) header fields. Each key is typed —
  // call list_engine_params for the catalog.
  "overrides": {
    "initial_capital":    100000,
    "default_qty_type":   "percent_of_equity",
    "default_qty_value":  10,
    "commission_type":    "percent",
    "commission_value":   0.04,
    "slippage":           2,
    "pyramiding":         0,
    "process_orders_on_close": true,
    "close_entries_rule": "ANY"
  },

  // Optional: engine runtime args (NOT strategy() header). Use script_tf
  // to aggregate the input CSV into a coarser strategy timeframe — the
  // engine REJECTS script_tf finer than input_tf, and the tool call then
  // fails (isError; "engine backtest failure (exit 4)" in the Docker image).
  "runtime": {
    "input_tf":          "15",
    "script_tf":         "60",
    "bar_magnifier":     true,
    "magnifier_samples": 8,
    "magnifier_dist":    "endpoints"
  },

  // Optional: where to write the full JSON report if it is too large to
  // return inline (see below). In Docker use an absolute path under /work.
  "report_path": "/work/report.json"
}

inputs 会作为 PINEFORGE_INPUTS 环境变量传递给引擎，overrides 会作为 PINEFORGE_OVERRIDES 环境变量传递，每个 runtime 字段则分别作为 PINEFORGE_INPUT_TF / PINEFORGE_SCRIPT_TF / PINEFORGE_BAR_MAGNIFIER / PINEFORGE_MAGNIFIER_SAMPLES / PINEFORGE_MAGNIFIER_DIST 环境变量传递。为空或未设置时 → 使用 strategy.pine 中的默认值，input_tf 则根据 CSV 前两行之间的间隔自动检测。

交易品种

引擎会根据交易品种的最小交易量（qty_step）和最小跳动单位（mintick）运行策略。若未设置最小交易量，100% 权益的订单可能会略微超出保证金限制，引擎还会记录一条极小的、低于最小交易量的追加保证金行（例如 2.6e-08 BTC，入场价等于出场价），而 TradingView 不会记录该行。因此，backtest_pine（以及 backtest_pine_grid 和 check_tradingview_parity）会在运行前通过 C ABI 将交易品种参数应用到引擎：qty_step 和 mincontract（最小交易量）、mintick、pointvalue、type、currency、basecurrency。ticker、tickerid、时区和交易时段不会应用（引擎会保留默认值）。参数来源如下：

1. symbol（以及 market：spot 或 usdt_perp；默认值：如果 CSV 的 sidecar 中记录的市场与其符号相同，则使用该市场，因此获取的永续合约仍为永续合约；否则使用 spot，结果会说明这一点：market not given: spot assumed for <SYMBOL> (pass market "usdt_perp" for a USD-M perpetual)；如果 market 与 sidecar 不一致，则使用 market，结果会说明 CSV 是按哪个市场获取的）。一句话概括：手数来自 TradingView 对该符号的实际读数，取自随此服务提供的实测表（仅当 TradingView 未列出某符号时才使用 Binance 的 LOT_SIZE.stepSize；对于上表较新的上架符号，则使用 TradingView 常见的 0.001）；跳动单位和货币来自 Binance 的公开 exchangeInfo（或来自 fetch_binance_ohlcv 获取 CSV 时放在其旁边的 sidecar）。手数分为三档，取决于表格（见下文）对该符号的记录：

   1. 表格中有读数（通常如此）：使用 TradingView 的实际读数，不附带来源警告；
   2. 表格标记为未在 TradingView 上架的符号（not_on_tv）：使用 Binance 的 LOT_SIZE.stepSize，这是该处唯一的数值，并显示警告 lot size for <label> is the exchange's lot step, not a TradingView reading: order quantities may differ from TradingView's；
   3. Binance 列出的其他符号（上架时间晚于表格）：使用 TradingView 常见的 0.001，并显示警告 lot size for <label> is TradingView's usual default (0.001), not a reading for this symbol (a listing newer than the readings): order quantities may differ from TradingView's（<label> 例如 Binance spot BTCUSDT）。对于表格中没有常见手数的市场，使用 Binance 的步长，与第 2 种情况相同。

   如果 Binance 没有该符号的记录（未列出该符号或无法连接 Binance），且表格中也没有读数，则没有手数：该交易品种无法解析（见下文），绝不会凭空编造步长网格。跳动单位是该符号的 PRICE_FILTER.tickSize，货币则是从 Binance 公开 exchangeInfo 中读取的 quoteAsset 和 baseAsset（请求一次，缓存 5 分钟）；点值为 1，类型为 crypto。

2. 如果没有 symbol，则使用 fetch_binance_ohlcv 在其获取的每个 CSV 旁写入的 sidecar <csv path>.instrument.json（其 instrument 结果会显示此文件）。如果 CSV 自创建以来有变化（第一根或最后一根 K 线变化，或内容变化），则忽略该文件，并在结果中说明原因。

3. syminfo：对于其他任何交易品种的 CSV，使用你提供的值：qty_step、mincontract、mintick、pointvalue、type、currency、basecurrency。这些值会覆盖 symbol 或 sidecar 提供的值；如果两者都没有，则这些值构成完整的交易品种信息。请提供 qty_step（或 mincontract；两者默认使用对方的值）；由于引擎默认跳动单位为 0.01，也请提供 mintick（缺失时结果会发出警告）。 已应用的内容记录在报告的 applied_runtime.syminfo 中，因此也会记录在 fingerprint.provenance.runtime 中：无网格运行和有网格运行的指纹永远不会相同。source.kind 表示手数大小的来源：tradingview（表格中的读数）、exchange（对于 TradingView 未列出的交易对，取自 Binance）、default（对于比表格中更新的交易对，采用 TradingView 通常使用的 0.001）或 user（syminfo，source.base 会注明它覆盖的内容）；exchange 和 default 都会附带上述来源警告。未解析表示未找到手数大小（没有 symbol、syminfo 或 sidecar；对于表格中没有读数的交易对，没有 Binance 记录；或者两者都没有该交易对）：运行仍会使用引擎默认值继续执行（没有手数网格；除非 syminfo 提供跳动单位，否则跳动单位为 0.01），结果开头会包含一条 warnings 条目（instrument grid unavailable for ... : order quantity is not floored to a lot size, so the run can contain sub-lot margin-call rows that TradingView does not book）。如果未解析的交易品种也没有其他可提供给引擎的信息（没有跳动单位，也没有货币），则不会应用任何内容：运行采用镜像自身的配置，报告中没有 applied_runtime.syminfo，而 warnings 会显示 no instrument was applied: the engine ran with its defaults；否则，applied_runtime.syminfo 会在已应用的信息旁显示 {"resolved": false, "reason": ...}。

不会因为缺少交易品种而拒绝或导致运行失败。交易品种通过引擎前缀的逐次运行覆盖层传入引擎（通过指向该前缀的符号链接实现）。如果无法构建覆盖层（例如 Windows 等不支持链接前缀的主机，或构建过程中发生任何错误），或者容器运行失败，且错误消息提及该覆盖层（覆盖层无法镜像的前缀布局、Docker 无法挂载的文件夹），运行会在不应用交易品种的情况下继续（第二种情况也会再次在不应用交易品种的情况下继续），并且 warnings 会显示 the instrument could not be applied (<reason>); the engine ran with its defaults。

引擎报告的内容，以及交易记录显示的内容。 如果镜像中的 run_json.py 不包含 apply_syminfo，则会按原样运行：报告中没有 applied_runtime.syminfo，结果也会说明这一点。如果镜像中的引擎库版本早于手数网格功能，则运行时会忽略该功能，而 applied_runtime.syminfo 会报告已应用（该库接受了调用）：如果交易数量不是报告所列手数大小的整数倍，结果会显示 the engine reported the lot size applied, but N of M trade quantities are not multiples of it (an older engine ignores it)（单独的区间末端标记不计入）。该检查只查看数量：无法区分旧版引擎与未将部分平仓数量向下取整至手数大小的策略；此处未检查这一点。

TradingView 的手数大小，而非交易所的。 TradingView 的 syminfo.mincontract 是 TradingView 自有的数据，并非 Binance 的字段；TradingView 会按它对订单数量向下取整。针对 TradingView 列出的每个 Binance 交易对进行测量（2026-10-03：1,366 个现货交易对和 523 个 USD-M 交易对）后发现，1,188 个现货交易对和 510 个 USD-M 交易对的该值与 LOT_SIZE.stepSize 不同（Binance 的步长仅分别与 13% 的现货交易对和 2.5% 的 USD-M 交易对相同）。TradingView 通常使用的 0.001，是其读取的 90.6% 的现货交易对（1,237 个，共 1,366 个）和 97.5% 的 USD-M 交易对（510 个，共 523 个）的手数大小；而 Binance 的步长往往是 1 或 0.1：USD-M 的 BTCUSDT 在 TradingView 上为 0.000001，在 Binance 上为 0.001，因此按 Binance 的步长向下取整，可能会使 10,000 USDT 的仓位最多缩小约 1.2%。在测量的所有交易对中，跳动单位都与 TradingView 的 syminfo.mintick 一致。 表格外的符号分为两种情况，表格会说明是哪一种。表格还会按市场列出 Binance 支持但 TradingView 不支持的符号（现货市场有 18 个，USD-M 市场有 1 个：not_on_tv），以及当某个市场至少 80% 的读数都是同一值时，TradingView 在该市场通常使用的步长（今天两个市场均为：defaults）。not_on_tv 列表中的符号使用 Binance 的步长（第 2 级）；表格外的其他符号均为比读数更新的上架符号，使用 0.001（第 3 级），因为这是比 Binance 步长更可能的值；warnings 会说明这两种情况。如果表格不含这两个列表（例如旧表格，或 PINEFORGE_TV_GRID 指向的表格），则两者都没有，因此表格外的符号使用 Binance 的步长，并带有 exchange 警告。无论哪种情况，你都可以传入 syminfo.qty_step（从图表读取 syminfo.mincontract）来自行设置步长：你提供的步长由你决定，即使它与默认值或 Binance 的步长相同，也会使用你提供的值，并且不会显示警告。

返回独立 pineforge-release 镜像的报告 JSON（engine、input、summary、trades、metrics、equity_curve、fingerprint、applied_inputs、applied_overrides、applied_runtime、diagnostics、elapsed_seconds），另附 _meta 块；当序列化后的大小不超过 200,000 字节时，结果会直接内联返回：

{
  "engine": "pineforge",
  "summary": { "total_trades": 49, "net_pnl": -190.85, ... },
  "applied_inputs":    { "Fast Length": "8", "Slow Length": "21" },
  "applied_overrides": { "default_qty_value": "5" },
  "applied_runtime":   { "input_tf": "15", ..., "syminfo": { "resolved": true, "qty_step": 0.00001, ... } },
  "trades": [ ... ],
  "equity_curve": [ ... ],
  "elapsed_seconds": 0.0042,
  "_meta": { "strategy_cpp_bytes": 5079, "image": "local" }   // npm/npx: the engine image name
}

长时间运行（3,000 根小时 K 线就足够）产生的结果无法放入 MCP 工具结果中。这时，完整报告会写入 report_path——默认路径为服务工作目录中的 pineforge-backtest-<timestamp>.json——而工具会返回精简结果：

{
  "summary": { ... }, "applied_inputs": { ... }, "applied_overrides": { ... }, "applied_runtime": { ... },
  "elapsed_seconds": 0.0008, "total_trades": 73,
  "report_path": "...", "report_path_in_container": "/work/report.json",
  "truncated": true, "note": "...", "_meta": { ... }
}

在 Docker 镜像中，始终将绝对路径（位于 /work 下）传给 report_path：这样文件会出现在你挂载的文件夹中。如果不指定，报告会写入容器内的 /app 下，并随容器一同消失。（report_path 和 note 文本是相对于容器的工作目录计算的，因此请以你在挂载文件夹中找到的文件为准，而不要依赖这些字符串。）内联大小上限由 PINEFORGE_MAX_INLINE_BYTES 设置。

若要在 report_path 中获得正确的绝对主机路径，请将服务的工作目录设为 /work，并在 PINEFORGE_HOST_WORKDIR 中提供挂载的主机端路径。镜像的入口点是相对于 /app 的路径，因此需要显式指定 --entrypoint；工具中的相对路径也会解析到挂载目录中：

docker run --rm -i -v "$PWD:/work" -w /work -e PINEFORGE_HOST_WORKDIR="$PWD" \
  --entrypoint node ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest /app/dist/index.local.js

使用 Install 中普通的 docker run 命令（工作目录为 /app）时，PINEFORGE_HOST_WORKDIR 仍会让 report_path 变成绝对路径，但路径有误：它会与报告相对于 /app 的路径拼接。

backtest_pine_grid — 参数扫描

仅转译一次 Pine 源码（在本地、容器内），然后针对 inputs × overrides 的笛卡尔积中的每种组合编译并运行这段 C++：每种组合都会对同一个翻译单元进行一次全新的 g++ 构建，然后运行回测。返回按排名排列的列表，并在 best 下给出排名第一的条目。

{
  "source": "//@version=6\nstrategy(\"macd\")\n...",
  "ohlcv_csv_path": "/work/btcusdt_15m_7d.csv",

  // Each axis is {key: list-of-values}. All combinations are tried.
  "inputs": {
    "Fast Length": [8, 12, 19],
    "Slow Length": [21, 26, 39]
  },
  "overrides": {
    "default_qty_value": [1, 5],
    "commission_value":  [0.04]
  },

  // Optional knobs:
  "fixed_inputs":     { "Source": "close" },   // applied to every combo
  "fixed_overrides":  {},                      // typed strategy() overrides
  "runtime":          { "input_tf": "15",      // engine runtime args, fixed
                        "script_tf": "60" },   // across the sweep
  "max_combinations": 64,                      // default 64, at most 1024; a bigger grid is an error
  "concurrency":      2,                       // parallel runs: default 1, at most 8
  "include_trades":   false,                   // default false: omit per-trade lists
  "sort_by":          "net_pnl",               // net_pnl (default) | win_rate_pct | max_drawdown | total_trades
  "report_path":      "/work/grid.json"        // where an oversized sweep is written
}

结果包含 total_combinations、succeeded、failed、sort_by、best 和 results（按 sort_by 降序排列的成功运行结果，随后是失败项）。若扫描结果过大，无法内联返回，则会写入 report_path，工具会返回 best、top_results 中排名前 10 的结果、results_truncated 和 report_path。

check_tradingview_parity — 为 TradingView 结果评分

提供一个 Pine v6 脚本以及 TradingView 为其导出的 Strategy Tester 结果。该工具会在相同的市场和时间范围内运行脚本，并使用 pineforge-engine v1.2.0 中的 scripts/verify_corpus.py（sha256 431452ecddc8184937951ddf9a4c5f29029731237301967b5b480800be6fd1a6）逐笔比较两组交易记录并评分。该脚本与 v1.3.0 以及冻结的 1.4.0 候选版本逐字节一致。评分器版本锁定和评分方式均未更改。 单独随仓库提供的 scripts/run_strategy.py 执行框架现已逐字节复制自冻结的 1.4.0 引擎候选版本（SHA-256 36f7cf77e0b6355ce03f5d251c7c414f22be7da81ae4743a769f0527f06904d0）。 与旧版 v1.2.0/v1.3.0 随仓库提供的版本相比，它新增了稳定的失败代码/参数处理、对错误文本为空时失败状态的检测，以及 Docker 覆盖项的字符串序列化。评分器和馈送数据推导部分的字节内容保持不变，详见随仓库提供文件的哈希值。文件完全相同以及针对性的替代实现回归验证，并不能证明已对原生引擎语料库重新进行一致性验证。

框架 CLI 会输出引擎失败代码，但一致性工具目前尚未返回该代码；这是 1.4.0 中已知的限制。

历史接口证据，并非在 1.4.0 上重新运行语料库： 已对照开源 pineforge-corpus 的 a35c7c4 版本，并使用引擎 v1.1.0 和 codegen c5d97ee5 进行检查：评分核心会为语料库门禁评测的全部 309 个探测返回已发布的层级；而工具本身通过 stdio 调用、仅传入以下输入时，会为分层抽样的 30 个探测返回该层级。

{
  "pine": "//@version=6\nstrategy(\"my strategy\")\n...",
  // The "List of trades" CSV as TradingView exports it, or the Strategy Tester
  // XLSX report base64-encoded (it starts with UEsDB).
  "tradingview_trades": "Trade number,Type,Date and time,Signal,Price USDT,...",
  "symbol": "BINANCE:ETHUSDT.P",          // TradingView ticker
  "timeframe": "15",                      // TradingView resolution: 1, 5, 15, 60, 240, 1D, ...
  "range_start": "2025-04-01T00:00:00Z",  // first bar TradingView computed (UTC unless an offset is given)
  "chart_timezone": "Asia/Taipei",        // the timezone TradingView printed the trade times in

  // Optional:
  "range_end": "2025-10-01T00:00:00Z",    // default: the export's last row
  "inputs": { "Fast Length": 8 },         // TradingView's Inputs tab, as in backtest_pine
  "strategy_overrides": { "commission_value": 0.04 },  // TradingView's Properties tab (list_engine_params)
  "runtime": { "bar_magnifier": true },   // list_engine_params runtime args
  "max_mismatches": 10,                   // mismatching trades to list: default 10, at most 50
  "ohlcv_csv_path": "/work/eth_15m.csv",  // or "ohlcv_csv": "<CSV text>": your own bars
  "syminfo": { "qty_step": 0.001 }        // the instrument's own values, as in backtest_pine
}

输入	说明
pine	Pine v6 源码，最多 256 KiB
tradingview_trades	“List of trades”CSV 文本（列为 Trade number、Type、Date and time 及一个 Price 列），或以 base64 编码的 XLSX 报告
symbol	TradingView 代码；除非 XLSX 中已注明或你传入了 K 线数据，否则为必填
timeframe	TradingView 周期；除非 XLSX 中已注明，否则为必填
range_start	回测第一根 K 线的 ISO 8601 日期或日期时间；除非 XLSX 中已注明，否则为必填
range_end	可选；默认值：导出数据的最后一行（结果会说明）
chart_timezone	打印交易时间所使用时区的 IANA 名称（接受 UTC+8 样式的偏移量）；除非导出数据中已注明，否则为必填；不会猜测 TradingView 的“Exchange”设置
inputs、strategy_overrides、runtime	可选，与 backtest_pine 使用相同的键
max_mismatches	可选，默认值为 10，最多 50
syminfo	可选：该交易品种自身的值（qty_step、mintick 等），与 backtest_pine 中相同；这些值会覆盖根据代码解析出的值；对于 Binance 以外的市场，它们就是完整的交易品种信息
ohlcv_csv / ohlcv_csv_path	你提供的 K 线数据，因此适用于任何市场：timestamp,open,high,low,close,volume（epoch 毫秒）或 TradingView 图表导出格式 time,open,high,low,close,Volume（epoch 秒或 ISO 8601）；路径遵循 backtest_pine 规则
magnifier_ohlcv_csv / magnifier_ohlcv_csv_path	可选；为已声明的 K 线放大器提供 1 分钟 K 线数据，涵盖第一根图表 K 线的开盘至最后一根图表 K 线的收盘；格式、限制和路径规则与 ohlcv_csv / ohlcv_csv_path 相同

限制（超出限制时会在错误上方拒绝处理）：

项目	限制
pine	UTF-8 编码下 262,144 字节（256 KiB）
tradingview_trades	传入内容最多 33,554,432 个字符（32 × 1024²）；评分器读取的交易列表（CSV，或从 XLSX 重建的列表）最多 32 MiB UTF-8，且最多 400,000 行
XLSX 报告	每个解压后的部分最多 64 MiB，所有部分合计最多 128 MiB；每个工作表最多 400,000 行、256 列；读取的工作表（List of trades 和 Properties）合计最多 8,000,000 个单元格，每行内的空单元格也计入；共享字符串最多 2,000,000 个
ohlcv_csv	最多 67,108,864 个字符（64 × 1024²）
ohlcv_csv_path	无大小限制（TradingView 图表导出文件会在内存中转换）
Binance 获取数据	图表和放大器 K 线合计最多 100,000 根
运行时间	PINEFORGE_PARITY_TIMEOUT_MS，默认 600,000 毫秒，用于转译、编译、回测和评分的总耗时
这里没有配额限制，也没有历史窗口：范围仅由您传入的柱线决定，或受 Binance 获取的 100,000 根柱线限制。

柱线。 如果提供了 ohlcv_csv / ohlcv_csv_path，则使用它们。否则，BINANCE:<SYMBOL> 会从公共 API 获取 Binance 现货 K 线，BINANCE:<SYMBOL>.P 则获取 USDT-M 永续合约 K 线，最多 100,000 根。对于没有柱线的其他任何交易品种，都会报错并提示提供柱线。声明了 use_bar_magnifier = true 的脚本，在图表属于运行环境支持放大的类型（周期大于 1 分钟且不超过 1 天）且 runtime.bar_magnifier 不为 false 时，也会获取截至最后一根图表柱线收盘时刻的 1 分钟柱线，且计入同一数量上限。如果使用您自己的柱线，也可以选择传入 magnifier_ohlcv_csv / magnifier_ohlcv_csv_path；如果脚本声明了柱线放大器却未提供相应数据，结果会警告，柱线内部的成交可能与 TradingView 不同。

交易品种。 此次运行会应用交易品种的最小下单量和最小价格变动单位，方式与 backtest_pine 相同：对于 BINANCE:<SYMBOL> 和 BINANCE:<SYMBOL>.P，使用随附表格中的 TradingView 自有最小下单量（对于 TradingView 未列出的交易品种，使用 Binance 的 LOT_SIZE.stepSize；对于上市时间晚于表格的交易品种，使用 TradingView 通常采用的 0.001；两种情况都会发出警告），并从 Binance 的 exchangeInfo 获取最小价格变动单位；如果使用您自己的柱线且未提供 ticker，则使用柱线文件旁边的 sidecar 文件；其他交易所则需要 syminfo。如果没有最小下单量，引擎不会对订单进行向下取整，可能会记录 TradingView 不会记录的低于最小下单量的保证金追缴行，因此交易列表的配对效果会变差；结果会发出警告。结果会在 applied_instrument 下显示实际应用的设置（并在一行文本中显示 Instrument: ...）；同一交易品种也会作为请求键 instrument 传给评分核心。

XLSX 报告。 系统会像读取 CSV 一样读取「List of trades」工作表（Excel 日期会转换为 YYYY-MM-DD HH:MM）。「Properties」工作表提供交易品种、时间周期、日期范围、初始资金、订单规模、金字塔加仓、手续费、滑点及其中注明的成交选项；您也可以显式传入相同设置，但如果某个值与导出内容不一致，就会报错并指出两者。如果导出内容列出了策略输入项，系统只会报告这些输入项，不会应用它们；对于您更改过的任何输入项，请传入 inputs。TradingView 没有公开说明此布局，因此工作表名称和键名会采用宽松匹配，未知键会被忽略。

结果。 结果包含纯文本块及相同数据的 JSON（structuredContent）：等级及其含义、每项检查的数值和阈值、匹配的交易数量，以及仅存在于 TradingView 或 PineForge 的交易数量、并排列出的首批差异及数据所显示的可能原因提示（窗口边缘、范围结束时持仓仍未平仓、规模、手续费或滑点、时区）、时区检查、窗口，以及引擎、代码生成器和评分器的版本。交易的配对条件是方向相同、入场时间相差不超过一小时且入场价格相差不超过 $3。如果大多数匹配交易都存在相同的非零时间偏差，或另一个时区明显能匹配更多交易，结果会指出这一点；等级仍按您提供的时区确定。

等级按 verify_corpus.py v1.2.0 的评分规则确定。数量 Δ 为 |TradingView − PineForge| / max(TradingView, PineForge)；p90 数值是匹配交易中每笔交易相对差异的第 90 百分位数；覆盖率是匹配交易数占 TradingView 所有已平仓交易的比例。

等级	规则
excellent	交易数量相同；覆盖率 ≥ 99 % 或未匹配交易不超过 1 笔；入场价格 p90 < 0.01 %；出场价格 p90 < 0.01 %（生产配置：< 0.05 %）；盈亏 p90 < 1 %（生产配置：< 100 %）；如果 TradingView 显示同一时间和价格有多笔入场，PineForge 的入场数量也相同
strong	覆盖率 ≥ 95 % 或未匹配交易不超过 1 笔；数量 Δ < 6 %；入场价格 p90 < 0.1 %；出场价格 p90 < 0.5 %；盈亏 p90 < 100 %
moderate	覆盖率 ≥ 75 %，且匹配了 TradingView 交易的至少 90 %
weak	至少匹配 1 笔交易
minimal	未匹配任何交易
当脚本在 strategy.exit 上设置 trail_points、trail_offset 或
trail_price 时，适用生产配置文件；其他所有脚本均按严格配置文件评分。
方法：https://pineforge.dev/en/methodology/.

数据保留。 所有操作都在你的机器上运行；只有在你未传入 K 线数据时，才会从 Binance 获取市场数据。脚本和交易列表，以及必须转换或获取的 K 线数据，都会存入临时文件夹，并在检查结束后删除。使用 npm/npx 时，检查会在引擎镜像中运行（docker run --network=none，评分核心和你的 K 线数据以只读方式挂载）。

fetch_binance_ohlcv — 获取市场数据

从 Binance 公共接口生成可用于回测的 CSV（表头为 timestamp,open,high,low,close,volume， 其中 timestamp = UTC 的 UNIX 毫秒开盘时间）。无需身份验证。超过 1000 根 K 线的请求会自动分页。output_path 遵循与 ohlcv_csv_path 相同的规则：在 Docker 中使用 /work 下的绝对路径；使用 npx 时，路径必须位于工作目录内，除非设置了 PINEFORGE_ALLOW_ANYWHERE=1。

{
  "symbol":      "BTCUSDT",
  "interval":    "15m",          // 1s (spot only), 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
  "market":      "spot",         // default; or "usdt_perp" for USDT-margined perpetual futures
  "limit":       672,            // total bars: default 1000, at most 100000; > 1000 paginates
  "output_path": "/work/btcusdt_15m_7d.csv"
  // Optional: "start_time" / "end_time" in UNIX ms UTC.
}

此外还会写入 <output_path>.instrument.json：其中包含该交易对的交易品种信息（来自随附表格的 TradingView 手数；对于 TradingView 未列出的交易对，使用 Binance 的手数；对于表格中较新上线的交易对，使用 TradingView 通常采用的 0.001；以及来自 Binance 公共 exchangeInfo 的最小价格变动单位和货币）。backtest_pine 和 check_tradingview_parity 会读取此信息（参见交易品种）；结果中的 instrument 和 instrument_path 会显示该信息。如果无法读取 exchangeInfo，仍会写入 CSV，instrument 会说明原因，且 warnings 条目会指出应向 backtest_pine 传入什么。

binance_symbols — 发现 / 验证交易对

返回 Binance 公共 API 上可用于获取 OHLCV 数据的交易对列表。结果会在进程内缓存 5 分钟。调用 fetch_binance_ohlcv 前，可用此工具验证交易对。

{
  "market":        "usdt_perp",   // required: "spot" or "usdt_perp"
  "query":         "BTC",         // case-insensitive substring match
  "quote_asset":   "USDT",
  "base_asset":    "BTC",
  "status":        "TRADING",
  "contract_type": "PERPETUAL",   // futures-only filter
  "limit":         50             // default 200, at most 2000
}

覆盖范围工具

PineForge 实现了 Pine v6 的子集，因此在编写或移植策略前，请先检查：

• list_coverage_topics — 返回所有覆盖主题及其状态（supported、 partial、unsupported、via_transpiler）和摘要，并附带状态说明。
• get_coverage_topic { "topic": "ta" } — 返回一个主题 ID（例如 ta、 strategy_orders、request_security）下完整的 supported / partial / via_transpiler / unsupported 列表。
• check_pine_feature { "feature": "ta.supertrend" } — 查询一个标识符或命名空间： 返回 supported / partial / unsupported / via_transpiler / not_found 状态，以及引用目录条目的说明。图表、表格和警报（plot、bgcolor、table、 alert）均可接受且不会产生效果；line、box 和 label 对象则是策略可以读取的数据。

每种状态都说明了通过此服务进行回测时可以实现的功能。该服务不会安装其他代码的 K 线数据、已记录的请求数据或 Pine 库源码，因此，如果引擎支持更多功能，条目会对此作出说明：例如，request.security 支持在引擎上查询其他代码，但在此处，如果请求的值可能影响交易，运行就会停止。

嵌入式目录在 coverage_version 中标记为 engine v1.4.0 + codegen 1.4.0 (2026-10-08)。这是针对冻结版本组合、面向发行版且范围有限的审计，并非对目录中每个条目的全新测试。历史清单和未解决的限制仍然存在；此服务仍不提供其他代码的 K 线数据、已记录的请求或库源码。

直接受影响的断言会引用候选源码证据：

• 数值浮点型 matrix.sum 的矩阵/矩阵和矩阵/标量形式、方法及 id1/id2 关键字均由 矩阵重载见证 覆盖；这并不代表布尔值/字符串/颜色/UDT 矩阵支持算术运算。
• 已测试的本地缺失历史数组及浮点型/整型矩阵绑定会保留 na；缺失历史见证和有界关键字/可调用项见证明确列出了可调用项空副本、函数局部/参数历史和映射历史的限制。
• pineforge.h 包含 81 个 PF_API 声明：64 个运行时实现和 17 个生成的声明，此外还有 4 个不在该头文件中的生成回执导出项。新增的两个运行时 getter 会公开失败代码/参数；PF_ABI_VERSION 仍为 4。
• 输入清单会发布 supported 和由描述符支持的默认值、选项及边界（清单见证、回执一致性与已知限制）。 空选项列表不代表该标志不受支持；计算表达式、颜色编码和依赖时区的默认值不保证与原生回执值相同。发布镜像回测在库公开完整协议时会使用经过检查的 setter；旧版一致性测试框架和旧版库回退方案并不能保证执行相同的检查。UI 布局元数据仍不起作用。

历史运行时目录仍是通用参考；历史清单总数不会被改写。

文件系统范围

使用 npx 时，OHLCV、输出和报告路径默认必须位于 MCP 服务进程的当前工作目录中。检查针对解析后的路径进行：先解析 .. 段和符号链接，因此两者都不能指向目录外；目标不存在的符号链接也会被拒绝。因此，从目录外链接到工作目录中的数据文件或文件夹同样会被拒绝。可通过以下方式覆盖：

export PINEFORGE_ALLOW_ANYWHERE=1

Docker 镜像会自行设置 PINEFORGE_ALLOW_ANYWHERE=1（容器就是沙箱），因此其中接受任何路径——请使用绝对路径 /work/...。

其他环境变量

变量	默认值	用途
PINEFORGE_IMAGE	从已安装的 release-lock.json 获取的不可变摘要	仅限 npm/npx：用于转译和回测的引擎镜像（运行时 + 捆绑的代码生成器）
PINEFORGE_ALLOW_ANYWHERE	0（Docker 镜像中为 1）	允许 OHLCV / 输出 / 报告路径位于 cwd 之外
PINEFORGE_DOCKER_TIMEOUT_MS	120000	每次引擎运行和 docker pull 的强制终止超时时间
PINEFORGE_MAX_INLINE_BYTES	200000	内联返回的报告最大大小；更大的报告会写入 report_path
PINEFORGE_PARITY_TIMEOUT_MS	600000	单次 check_tradingview_parity 运行（转译、编译、回测、评分）的时限
PINEFORGE_BINANCE_TIMEOUT_MS	20000	每次向 Binance 发出的请求（K 线页、exchangeInfo）的时限；即使回测使用的 symbol 无法连接 Binance，仍会运行，但不会生成批量网格，并会说明这一点
PINEFORGE_BINANCE_SPOT_URL / PINEFORGE_BINANCE_FAPI_URL	https://api.binance.com / https://fapi.binance.com	Binance 现货和 USD-M 公共 API（K 线、exchangeInfo）的基础 URL：当无法连接 api.binance.com 时，可使用镜像或代理
PINEFORGE_TV_GRID	未设置	由 scripts/sync-tv-grid.mjs 生成的批量大小表路径，用于替代随程序附带的表（src/tv-grid.generated.json）
PINEFORGE_HOST_WORKDIR	未设置	Docker：挂载到 /work 的主机目录；设置后，report_path 是主机上的绝对路径——仅当服务以 /work 为工作目录运行时才正确（参见 backtest_pine 示例末尾）

使用 Docker 时，通过 -e NAME=value 传入这些变量。

开发

npm ci
npm run build     # tsc; also writes the gitignored src/version.ts
npm test

TradingView 批量大小表（src/tv-grid.generated.json）由程序生成，不应手动编辑。当 TradingView 的测量数据更新后（包含 TradingView 自有 mincontract、模式为 pineforge-tv-syminfo-receipts/v1 的表），运行一条命令重新生成并提交结果：

node scripts/sync-tv-grid.mjs <path to tv-grid-table.json>

它只保留两个 Binance 交易场所：每个交易品种的 mincontract、交易场所的 not_on_tv 列表，以及每个市场中 TradingView 常见的批量大小（0.001；仅当其读数占比至少为 0.80 时，记录该占比和读数数量）。它会按排序结果逐行写入交易品种，记录表格的 generated_utc、sha256 及其自身的内容哈希（涵盖读数、列表和默认值）；若表格不完整、任一 Binance 交易场所缺少 not_on_tv 列表（空列表也可以），或数值超出 1e-12..1e12 范围，则会拒绝处理。同一张表会生成完全相同的字节；PF_TV_GRID_SOURCE=<path to the table> npm test 也会检查已提交文件是否由该表生成。

构建镜像时，请同时使用已提交的镜像摘要和版本：

docker build -f docker/Dockerfile \
  --build-arg "PINEFORGE_RELEASE_IMAGE=$(node -p "const l=require('./release-lock.json'); l.image.repository+'@'+l.image.digest")" \
  --build-arg "PINEFORGE_RELEASE_VERSION=$(node -p "require('./release-lock.json').release_version")" \
  --build-arg "PINEFORGE_SOURCE_SHA=$(git rev-parse HEAD)" \
  -t pineforge-backtest-mcp .

自动分发使用基于清单的更新 PR 和必需的 release/ready 检查。有关 CI 测试夹具、仓库设置、收据和渠道恢复，请参阅离线发布链运行手册。

许可证

此服务采用 MIT 许可证（LICENSE）。该镜像还打包了 pineforge-engine（Apache-2.0）和 pineforge-codegen 转译器 （自 codegen 1.3.0 起，根据 PineForge Source License 1.2 提供源代码：可免费用于 非商业用途和个人交易；除个人交易之外的投资管理，以及其他商业用途，均需商业许可证。交易由自营 交易公司或资助交易计划提供或分配的账户，包括挑战、评估或模拟账户，不属于个人交易；该账户中的资金， 无论是真实资金还是模拟资金，均属于投资资金）。早期版本继续遵循其发布时适用的许可证：codegen 1.2.0 采用 PineForge Source License 1.1，1.1.0 及更早版本采用随附的 PolyForm Noncommercial 条款。codegen 的 LICENSE 是具约束力的文本。请参阅 LEGAL.md。