StockSharp Odysseus

Odysseus

一个 MCP 服务，可将任何 AI Agent 变成量化研究员，并让它遵守严谨的研究规范，让研究结果真正有意义。

C# 命名空间以 StockSharp.Odysseus 为根。MCP 服务将 StockSharp.Odysseus 作为名称，将 StockSharp Odysseus 作为显示标题；下面的客户端配置使用 odysseus。

有关 MCP Registry 发布和 Claude Desktop 扩展，请参阅 MCP 分发。

你可以在本地运行它，让它与你自己的 Agent 并肩工作。它会将真实市场历史数据下载到 StockSharp 存储中，供所有项目共享；测量存储中的实际数据；将形式化假设转换为真实的 StockSharp Strategy 类；编译并计入成本进行回测；搜索参数；并报告每次运行的结果。

它负责测量，不负责评判。 它没有评分、阈值，也不会接受或拒绝。回撤是否可以承受、收益是否值得获得，取决于你的研究内容；这是你的决定，而不是服务的决定。

---

为什么选择 MCP 服务

因为 Agent 就是研究员，而且它已经存在。

带有聊天窗口的回测产品必须提供模型、对话、界面，以及对何为良好策略的判断。本项目不提供其中任何一项。你的 Agent 负责推理；本项目则提供 Agent 单独使用时不擅长的部分：不会在结果出现后悄然变化的真实数据、每次都能将假设转换成相同代码的转换器、会计算点差成本的模拟器，以及一段在最后之前禁止查看的历史数据。

最后这一点才是关键。让 Agent 寻找盈利策略，它就会找到一个。区分发现与搜索的唯一因素，是搜索无法触及的数据。

---

它能做什么

create_project
  → import_history          real bars, into the shared storage
  → analyze_market          what the instrument does, before you propose anything for it
  → propose_spec            the hypothesis, as a formal document
  → build_candidate         translated to C#, compiled, hashed
  → evaluate_candidate      six fixed runs, reported in full
  → measure_on_closed_data  once, against data nobody was allowed to see
  → complete_strategy       you decide; the server keeps the code and every number behind it

总共 48 个工具：项目、连接器、数据、标的查询、假设、候选策略及其结果能否复现的检查、回测、评估、带种子的遗传搜索及其上的滚动前向分析、封闭数据测量、对接经纪商模拟账户的模拟交易、已完成事项的记录，以及——默认关闭，只有操作员启用后才可用——在服务运行的机器上安装 StockSharp 产品。

analyze_market 用于测量项目的数据集，包括标的的波动幅度、其价格变动是延续还是回归，以及策略可能交易的事件之后出现了什么。在提出任何方案之前先阅读分析结果：如果某个标的的突破后续毫无进展，那么针对它的突破假设就需要耗费一代候选策略才能证伪，而这些数据能提前说明这一点。

数据纪律

所有项目共用一个 StockSharp 市场数据存储库中的 K 线，存储在专属文件夹 ODYSSEUS_MARKET_DATA 中（默认为 ./market-data）。项目不会复制 K 线：其数据集由标的列表、K 线周期和时间范围组成，运行时会从共享存储库读取该范围的数据。运行记录会注明读取的内容——标的、K 线周期、起始时间和结束时间——因此再次导入相同范围时，可以找到所有已在该范围上执行的运行。

数据集按时间分为三部分：前 60% 用于形成假设，接下来的 20% 用于衡量假设，最后 20% 保持封存。describe_split 会说明各部分所在的位置；封存部分之所以保持封存，是因为没有工具会提供其中的 K 线，而且它只会被衡量 一次——不是每个项目一次，而是每段历史数据一次。衡量记录保存在项目旁的台账中，因为启动第二个项目并导入相同日期，并不会让结果变得不可见。台账会在一个步骤中检查并记录衡量结果，因此两个项目即使同时请求，也不可能都通过。

衡量结果是什么样的

六次运行，始终是相同的六次：开发切片、验证切片、成本提高 50% 后再次运行验证切片，以及将开发切片分成三个连续窗口并用相同参数运行。利润、回撤、交易数量、胜率、风险敞口、结果中有多少依赖单笔交易、各窗口之间的差异，以及在更高成本下保留下来的表现。不作结论——这部分由你决定。

这三个窗口用于判断结果是分布在整个历史数据中，还是仅由其中一段时间产生。它们不会为每个窗口选择参数；run_walk_forward 会负责这件事——它在一个时间段上搜索已声明的参数，在其后的时间段上测试所选参数，并逐个窗口向前推进。

信号在其 K 线收盘时执行，订单以当时的市场价格成交。若入场晚一根 K 线，结果是否依然成立——也就是不依赖信号被观察到时的价格，结果会如何——会单独进行测试：在 baseline 和 costsX15 场景之外，使用 entryOneBarLater 场景运行 run_backtest。

---

运行

通过 NuGet

使用 .NET 10 SDK，从 NuGet 安装任一工具：

包	命令	功能
StockSharp.Odysseus.Mcp	odysseus-mcp	面向 AI Agent 的 MCP 服务
StockSharp.Odysseus.Cli	odysseus	在终端中使用相同的研究工具

dotnet tool install --global StockSharp.Odysseus.Mcp
dotnet tool install --global StockSharp.Odysseus.Cli

每个包都在各自的文件夹中包含 worker 和 runner，因此可以独立安装任一工具。下方的 MCP 连接配置可以使用 "command": "odysseus-mcp"，而不必填写服务器可执行文件的路径。

通过发行版

你需要 .NET 10 运行时。从发行版页面下载适用于你系统的存档——Windows x64、Linux x64 或搭载 Apple silicon 的 macOS——并解压。文件夹中包含服务器 Odysseus.Server 和命令行工具 odysseus，以及它们启动的 worker 和 runner，这些文件夹都与相应程序并列，因此可以一起移动和删除。在 macOS 上，首次启动前请清除浏览器为下载文件添加的标记：xattr -dr com.apple.quarantine odysseus。

从源代码构建

你需要 .NET 10 SDK。

git clone https://github.com/StockSharp/StockSharp.git "StockSharp (GitHub)"
git clone https://github.com/StockSharp/Odysseus.git
cd Odysseus
dotnet build -c Release

交易平台需要从源代码构建，因此要将其存储库克隆到本项目旁边、构建系统会查找它的文件夹中。若要将其存放在其他位置，请在与 Directory.Build.props 相邻的 Directory.Build.local.props 中，将该位置命名为 StockSharpSource。

构建会生成 src/Odysseus.Server/bin/Release/net10.0/Odysseus.Server.exe，并在其旁生成命令行工具 src/Odysseus.Cli/bin/Release/net10.0/odysseus.exe。

连接 Agent

通过 stdio 将 Agent 指向服务：

{
  "mcpServers": {
    "odysseus": {
      "command": "path/to/Odysseus.Server.exe",
      "env": {
        "ODYSSEUS_PROJECTS_ROOT": "path/to/where/projects/should/live",
        "ODYSSEUS_MARKET_DATA": "path/to/the/shared/market-data/storage"
      }
    }
  }
}

然后让它调用 import_demo_dataset，并围绕一个假设开展工作。捆绑的数据集是生成的，因此基于它得出的任何测量结果都不能说明任何市场的情况——它的作用是证明这套机制无需账户也能运行。

工作区文件

一个 MCP 进程管理一个工作区，由 ODYSSEUS_PROJECTS_ROOT 指定。使用 CLI 在同一文件夹中运行研究命令前，请先停止该进程。不同工作区可以独立运行。同一进程中的请求在更新元数据时会串行执行。

项目、预算、候选项、运行记录、测量结果和审计事件均为可读的 JSON 文件。记录文件名包含其插入顺序；更新时文件名保持不变。作用域操作键存储在项目文件夹旁的 operations.json 中，已用额度的封存历史则存储在 closed-history.json 中。这些日志在重启后仍会保留，因此重启服务或创建另一个项目都不会重置研究限额，也不会让已封存的额度再次可用。无需数据库服务或原生 SQLite 库。

规格、生成的源代码、程序集和已完成的策略都会作为文件保留在各自的项目中。市场历史数据保存在 StockSharp 的 ODYSSEUS_MARKET_DATA 文件存储中，不会复制到项目元数据中。每个交易运行器都有自己的文件，其生命周期可以超过 MCP 进程。

如需了解如何处理由旧版 SQLite 创建的工作区，请参阅一次性迁移。

使用真实数据

真实数据通过 StockSharp 连接器 获取，服务器不会针对某个连接器进行编译。 这是不可行的：正在运行的服务器无法编译自己，因此连接器会作为已发布的 NuGet 包提供，由服务器下载并加载到自己的上下文中。 由你决定使用哪个连接器。

将该连接器所需的凭据放入一个文件：

key: ...
secret: ...

并将 ODYSSEUS_BROKER_KEYS 指向该文件。这里使用文件路径而非凭据值本身，因为环境变量中的值会被每个子进程继承——包括运行候选方案的工作进程——并显示在进程列表中。

然后指定要使用的连接器，可以写入 ODYSSEUS_BROKER_CONNECTOR 所指向的文件：

{ "packageId": "StockSharp.Binance", "settings": {} }

也可以在服务器运行期间使用 list_connectors、describe_connector 和 select_connector。 describe_connector 会报告软件包接受的所有设置及各设置允许的值，因此可以根据连接器对自身的说明来填写选项，而不必依赖文档。

另外两个变量用于限定允许下载的内容，因为这三个工具都会运行下载的代码——连接器的用途，以及能否告知它当前使用的是模拟账户，都是其实例的属性；因此，读取软件包会在其中构建适配器：ODYSSEUS_CONNECTOR_SOURCES（软件源，默认值为 https://api.nuget.org/v3/index.json）和 ODYSSEUS_CONNECTOR_ALLOW（软件包名称前缀，默认值为 StockSharp.）。这两项都必须在启动时决定，工具无法更改。设置后为空的允许列表表示不允许任何内容，而非允许所有内容。使用 --hosted 启动的服务器会拒绝这三个工具：它的连接器在进程启动时就已选定。

没有连接器，其余功能仍可正常使用：演示数据集、analyze_market、所有回测、闭合数据测量和 complete_strategy 都会读取已导入的历史数据。 describe_server 会说明你使用的是产品的哪一部分。

历史数据也可以来自 远程 StockSharp 存储服务器（Hydra），而非经纪商。将其名称写入 ODYSSEUS_REMOTE_STORAGE 所指向的文件：

{ "address": "10.0.0.5:5002", "login": "...", "password": "..." }

import_history 随后会从该服务器读取 K 线数据并写入共享本地存储，所有运行任务都会从本地读取数据。服务器通过 StockSharp.Fix 软件包访问；该软件包会像连接器一样下载并加载，因此 ODYSSEUS_CONNECTOR_ALLOW 必须允许它。如果指定了经纪商，它仍会负责模拟交易。

仅限模拟账户，并且会进行检查，而非仅作声明。每个连接器都会先切换到模拟模式，再进行配置，配置后还会再次检查。没有模拟模式或无法保持模拟模式的连接器会被拒绝，而不会冒险使用。

部署的生命周期会超出启动它的会话

deploy_candidate 会启动独立进程——一次部署对应一个进程——即使 Agent 断开连接、MCP 服务退出，该进程仍会继续交易，直到有人将其停止。这是产品行为中最重要的变化，它有利也有弊：连接断开不再会中断任何事情，而除非有人停止策略，否则它就不会停下来。

会保留下来的是项目根目录下的一个目录：

projects/runners/<deploymentId>/
    launch.json      what to run and how to reach the broker
    runner.json      how to find the process, and how to tell it from a reused process number
    strategy.dll     the exact assembly being traded
    journal.jsonl    one line per state change, including what it was holding
    runner.log       what the runner has to say to a person

之后的会话——不同的 Agent、不同的进程，甚至是下周——读取的都是这个目录，而不是内存中保存的任何内容。list_deployments 会同时报告记录的内容，以及查找进程时发现的情况；这四种状态不能互换：

runner	含义
attached	已连接且能响应。数据是最新的。
gone	进程已不存在。它在经纪商处持有的任何头寸都原样保留。
unresponsive	进程仍在运行，但没有响应。它可能仍持有头寸，也可能仍在交易。
unknown	没有任何记录，或此版本无法与之通信。

gone 和 unresponsive 的区别在于是否有人仍持有头寸，因此状态有四种，而不是两种。停止 gone 状态的运行器会将其记录为已中断，并附上日志的最后一行；停止 unresponsive 状态的运行器会被拒绝，且不会记录任何内容，因为把一个可能仍在交易的进程标记为“已停止”，正是本产品竭力避免的谎言。

停止是一项关于头寸的决策，并会同时给出处理结果。进程终止则不是：崩溃、信号、机器重启和授权到期都会让头寸保持原样，而且都不会平仓。重启后也不会自动恢复任何内容——恢复的是记录，而不是交易。

两项实际影响：

• 部署需要指定连接器名称，而不必绑定连接器。 运行器会在自己的进程中加载自己的连接器，因此 MCP 服务即使尚未加载连接器也可以部署；但如果 select_connector 和 ODYSSEUS_BROKER_CONNECTOR 都没有指定连接器，部署就会被拒绝。
• 两个根目录就是两个注册表。 如果 shell 和 MCP 服务使用不同的 ODYSSEUS_PROJECTS_ROOT 值，它们看到的运行器也会不同。describe_server 会报告当前使用的根目录。

没有任何工具能终止运行器，这是有意为之：能够终止运行器的工具可能会让头寸无人看管。终止操作只能由人在终端中执行——odysseus runner kill <deploymentId> 会显示即将处于未平仓状态的内容，并要求再次输入标识符；也可以使用任务管理器。

面向操作员的实盘交易

以上所有内容都在模拟账户上交易，MCP 服务无法做其他任何事情。实盘交易是进程从启动之初就具备的一种属性，由操作员指定给即将进行交易的进程的文件决定；从设计上讲，Agent 通道无法触及它：

• 没有任何工具接受模式参数，而且不改变设计就无法添加这样的工具。
• MCP 服务会在唯一一个本可以另作选择的调用点，将模拟交易授权作为字面值传入。
• 它会从自己启动的每个子进程的环境中移除 ODYSSEUS_LIVE_MANDATE 和 ODYSSEUS_LIVE_PHRASE，并且只会从调用方明确传入的路径设置前一个变量——而服务总是将该路径留空；后一个变量则始终不设置。即使操作员在启动服务的 shell 中导出了其中任一变量，服务启动的仍是模拟交易运行器。
• 运行器会按照自己的时钟，从文件中自行重新检查所有内容：到期时间、它实际加载的连接器构建版本、交易品种、按最新价格计算的持仓，以及经纪商报告的账户。任何一项不匹配，它都不会启动任何内容。
• 持有文件并不等于获得许可。 文件中写明的短语必须通过文件无法提供的通道传回，策略才能启动。

授权文件采用 JSON 格式，而且本产品中的任何部分都不会写入这类文件——odysseus mandate template 会将示例打印到标准输出，供人保存，并将使用说明打印到标准错误，因此 odysseus mandate template > mandate.json 仍然会生成一个可解析的文件：

{
  "schema": 1,
  "phrase": "trade real money on U1234567 until the thirtieth",
  "account": "U1234567",
  "connector": {
    "packageId": "StockSharp.Example",
    "packageVersion": "1.2.3",
    "adapter": "StockSharp.Example.ExampleMessageAdapter"
  },
  "symbols": ["AAPL"],
  "maxPositionNotional": 5000,
  "expiresAt": "2026-09-30T00:00:00Z"
}

每个字段都是必填项，而且每个字段都会缩小许可范围：一个账户、一个连接器构建版本、少数几个交易品种、持仓上限，以及一个到期时间，这样一来，没人记得撤销的许可就会自动失效。

因此，要让运行器进入实盘模式，需要完成以下所有步骤，而且每一步都需要有人作出决定：

1. 自行编写授权文件，并将其保存在只有你能写入的位置。没有任何工具、Agent 或本产品的任何部分会写入该文件：软件能够创建的文件，也可能被说服创建出来。
2. 在即将用于启动运行器的 shell 中，将 ODYSSEUS_LIVE_MANDATE 指向该文件。如果变量已设置但文件不可读，运行器会拒绝启动，而不会退回模拟交易——设置该变量的操作员意在使用真实账户，用模拟账户运行其策略既安全又不诚实。
3. 亲自启动 Odysseus.Runner，并为它指定运行器的工作目录。MCP 服务启动的运行器不具备这两个变量，因此这就是唯一的进入方式。
4. 输入该短语以确认。 从终端启动时，运行器会打印账户、交易品种、上限和到期时间，并要求输入授权文件中写明的短语。系统会精确比较该短语——空格和大小写必须与原文一致，不会去除空白、统一大小写，也不会按任何语言环境的规则判断相等——而且绝不会打印出来供你复制。如果没有可供询问的终端，则必须将同一短语设置在 ODYSSEUS_LIVE_PHRASE 中。
5. 运行器会根据响应的经纪商重新检查所有内容，只有全部一致时才会启动策略。

短语不匹配，或启动时既没有人可供询问、ODYSSEUS_LIVE_PHRASE 也未设置，两种情况的处理结果都与其他任何不可用的授权文件相同：不会启动任何内容，日志会针对零持仓记录拒绝操作，也不会悄悄降级为模拟交易。

实盘运行器会在所有位置明确标示实盘状态，而且总是首先标示：在问候信息、每份状态报告、runner.json 中——因此，即使会话无法连接到运行器，也仍会报告“实盘，无法连接”；这是最需要有人介入的状态——以及在部署行和审计日志中。

安装 StockSharp 产品

六个工具用于在服务器运行所在的机器上安装、更新、移除和列出 StockSharp 自有应用——Designer、Terminal、Hydra 等。这些工具默认关闭，而且大多数机器根本无法使用它们；这是正常状态，并非故障。以下三项条件必须全部满足，且 get_installer_state 无需安装任何内容，就能报告这三项条件的状态：

• 安装程序控制台位于这台机器上。 Odysseus 将 StockSharp.Installer.Console 作为进程运行；它不会链接供应商的安装程序库，也 不会下载该程序。链接该库会把跨仓库依赖、StockSharp 账户、许可证和私有源引入一个匿名获取公共程序包的 服务器中。将 ODYSSEUS_INSTALLER 指向该可执行文件，或将它放在服务器旁边的 installer 文件夹中。
• 操作员已指定允许操作哪些产品。 ODYSSEUS_PRODUCT_ALLOW 是 由分号分隔的数字产品 ID 列表——9;10;1137 分别对应 Designer、Terminal 和 Runner。 未设置时表示不允许操作任何产品。这与 ODYSSEUS_CONNECTOR_ALLOW 的默认设置相反，而且这是有意为之： 产品功能有一半需要连接器，而研究工作流的任何部分都不需要 StockSharp 产品。
• 这台机器已登录 StockSharp 账户。 安装程序会从 %USERPROFILE%\Documents\StockSharp\credentials.json 读取账户信息。该文件对整台机器生效，且没有切换选项—— 无法在此处传入账户。如果没有账户，安装程序就会停下，等待有人在键盘上输入电子邮件地址，因此这些工具会拒绝执行，而不是一直挂起。

产品会安装在项目根目录下的 products/<id> 中，任何工具都不接受目录参数：作为参数传入的路径，就意味着可以向任意位置写入。 每次调用的完整输出都会保存到 products/invocations/ 中，响应则会附带输出末尾内容——该程序没有 机器可读的输出，因此无法解析的内容会以文本形式返回，而不会被丢弃。以 --hosted 启动的服务器会拒绝所有六个工具。

两种列表查询都需要网络，尽管听起来像是本地操作：安装程序每次调用时都会重新加载完整产品目录，且没有离线模式。

使用终端

同样的研究内容，以表格而非 JSON 呈现——相同的服务、相同的数字，只是面向人而非解析器：

dotnet run --project src/Odysseus.Cli -- new "my study"
dotnet run --project src/Odysseus.Cli -- demo
dotnet run --project src/Odysseus.Cli -- propose samples/hypothesis.json
dotnet run --project src/Odysseus.Cli -- build
dotnet run --project src/Odysseus.Cli -- backtest
dotnet run --project src/Odysseus.Cli -- measure
dotnet run --project src/Odysseus.Cli -- closed
dotnet run --project src/Odysseus.Cli -- complete "why you believe it"

从发布包解压后，在解压目录中运行 odysseus new "my study" 等相同命令即可。

samples/hypothesis.json 是一份真实的规范：一个经成交量确认的突破策略，带有 ATR 止损，并在交易时段结束时平仓。它就是上方演示提出的策略，且有一项测试会同时用服务器自身的检查和已发布的架构对它进行验证。

回测报告会同时列出运行成本和收益，因为只有两项费用中的一项可以通过交易方式降低：持仓时间越长，支付价差的次数越少；而手续费无论持仓多久，都会随成交量变化。

而且，任何一次运行都可以拆分分析——按月份、按交易时段、按持仓时长或按方向。每种拆分都基于相同的交易，因此各部分相加后仍会得到该次运行的总结果。如果结果集中在某一个月，或集中在当天最后半小时，这里就会明确显示，而不是等到六周的模拟交易之后才发现。

---

它不会做什么

• 它不会告诉你某个策略是好是坏。 它会报告发生了什么，解读留给你。
• 它不会通过 Agent 通道交易真实资金。 MCP 服务启动的每个部署都使用模拟账户，而且没有任何参数、规格字段或存储值可以改变这一点：实盘交易由一个进程在启动时读取的文件决定，而该进程无法由服务创建。操作员可以自行启动这样的进程；任何工具都无法触及它。
• 它不会因为某个进程终止就平仓。 止损单承载着对仓位的决策。崩溃、信号、重启和授权过期都不承载这样的决策，也不会默认获得这项决策。
• 它不会让你对同一段已平仓区间重复测量。 这就是它全部的价值。
• 它不会把回测冒充成结果。 模拟器会根据 K 线成交；回测与账户之间最常见的差异，就是永远没有发生的成交。

---

契约

工具返回的内容不会在任何地方写下来，这是有意为之。 工具会自我描述：每个工具都带有一段说明，供必须在尝试之前选择它的 Agent 阅读；每个参数也都说明了自身含义，并配有测试，若有任何参数缺少说明，测试套件就会失败。连接并调用 tools/list——这就是契约，而且它不会过时。静态保存的输出结构副本只会逐渐偏离生成它的代码。

工具列表本身受本页面约束：测试会将 tools/list 的响应与上文按原样分组的明确列表进行比较，因此，新增、移除或重命名工具都会导致测试套件失败，直到此处的列表和数量得到相应更新。

需要写下来的内容是你要发送的内容，因为在服务看到它之前，必须先确保这些内容正确：

• strategy-spec.schema.json — 假设文档，包含词汇表中的每一种表达式类型。测试会验证随附示例、同时使用所有类型的规格，以及服务写回的内容；其他测试会检查服务拒绝的规格是否也会被该架构拒绝，并确认其中的枚举值与代码声明一致。
• error.schema.json — 每种失败返回的结构；测试会确保其类别词汇与服务分支逻辑所依据的枚举保持一致。

如果这些检查只有在有人记得运行时才会执行，就毫无价值，因此 build.yml 会自动运行：每次推送和每个拉取请求都会还原依赖项，并以 Release 配置构建整个解决方案——该配置会将警告视为错误，因此这一步是所有测试开始前的关卡——然后运行所有测试，并为每个测试程序集保留一份 JUnit 报告。测试失败就会导致构建失败。它还会打包 MCP 和 CLI 工具，从这些包中安装工具，通过生成的数据运行 CLI 回测，并检查 MCP 握手。通过这些检查无需进行任何配置：少数需要经纪商账户的测试会查找凭据，找不到时便会跳过。

发布工作流 会在上传到 NuGet.org 和 GitHub 之前验证软件包和归档文件。发布设置与验证介绍了可信发布策略和试运行模式。

---

许可证

与所有 StockSharp 仓库一样，适用 StockSharp 自定义许可证声明——请参阅 LICENSE 及其指向的 EULA。连接器会在运行时作为 NuGet 包获取，并受其自身条款约束；任何 StockSharp 内容——源代码、二进制文件或密钥——都不属于本仓库。

没有遥测。全新安装不会发起任何网络调用，除非收到请求，否则不会连接经纪商。