TRA

TRA

具备确定性执行能力的自主交易 Agent。Agent 提出建议，系统做出决定。

TRA（trading research agents，交易研究 Agent）以 bitra 的名称发布在 PyPI 上，并以 tra 运行。在 0.10.1 之前，该包名为 trading-research-agents，目前仍以该名称发布同一个包。

大模型擅长解读市场并表达观点，但不擅长算术，不了解交易成本，还会轻易推翻你设定的限制。本项目只让它们负责前一部分。系统本身采用不涉及模型的固定规则来获取数据并计算所有数值。Agent 读取这些数据并给出意见。随后，系统为交易定价、应用你的限制、确定交易规模，然后将其记录下来，或发送一笔附带止损单的订单。每项决策和每次拒绝都会连同原因保存在磁盘上，方便你事后核查发生了什么以及原因。 这是一个早期版本，因此不同版本之间的设置可能会发生变化。目前支持的功能：通过同一订单路径交易线性永续合约、现货交易对（包括股票永续合约和代币化股票）以及预测市场结果；系统会发现并评估永续合约品种；筛选器会选出值得关注的标的；完整的自主周期基于实时数据运行；四位分析师和最多三位验证者；分析师命名的止损位和目标价须在你设定的范围内；由你设定的门槛决定是否通过；按照你自己的规则确定仓位大小；在你签署的授权约束下，通过交易场所的模拟环境下达真实订单；风险经理只能让交易台变得更加谨慎；还有两位审计员负责查阅记录。

---

目录

• 解决什么问题
• 快速开始
• 你会依次看到什么
• 单个周期如何做出决定
• 交易场所
• 模型和提供商
• 迈向真实订单
• 你的资金、订单和持仓
• 查看交易台及记录保存内容
• 命令行
• 保证的内容以及尚未构建的功能
• 发展方向
• 文档

解决什么问题

交易 Agent 常见的问题	这里的处理方式
模型编造或算错数字	模型从不进行计算。所有数值都由系统得出，模型引用的数值也会根据其简报进行核验，包括数值本身。
交易完成后才知道成本是多少	订单生成前会计算往返交易成本（手续费、价差、冲击成本、资金费率、滑点）；如果交易声称的优势不足以覆盖成本，就会被拒绝。
Agent 自行决定仓位大小	仓位大小由你的信心阶梯和风险限额决定。任何模型都不能扩大交易规模。
模型“决定”无视你的设置	是否通过由你设定的阈值决定。模型的意见会与阈值一并记录，绝不会取代阈值。
出了问题却没有记录可查	每个周期都会保留快照、简报、回答、交易意图以及交易场所的反馈。记录不会被改写。
崩溃后留下没有止损的持仓	止损和止盈会与入场订单一同提交到交易场所；如果交易场所不支持，也会在成交后立即提交，因此即使此进程崩溃，这些订单仍然有效。
信息流中的文本告诉模型该做什么	提出方向建议的模型只读取代码计算出的数值；外部文本只会交给不做任何决策的角色，任何模型都不能发送订单或访问密钥。

这些都不是假设情境。为何采用这种设计列出了每个问题背后有文档记录的故障案例及其来源。

开始使用

只需几分钟和一个模型密钥。每项设置都有可用的默认值，因此新建的交易工作区无需任何更改即可运行；第 6 步下方的表格列出了这些默认值。

1. 安装。 你需要 Python 3.11 或更高版本。uv 是最快捷的方式：

uv tool install 'bitra[ccxt,openai,anthropic,google,data]'

这会安装所有模型提供商和所有交易所支持。若不使用 uv，请在虚拟环境中运行 pip install 'bitra[ccxt,openai,anthropic,google,data]'。之后若要升级到最新版本：

uv tool upgrade bitra      # or: pip install -U 'bitra[ccxt,openai,anthropic,google,data]'
tra --version

这是正式发布的版本，也是应该运行的版本。GitHub 上的 develop 分支用于开发下一个版本；其中的提交并非正式发布版本（参见未来规划）。

2. 创建交易工作区。 交易工作区是一个文件夹，用于存放你的设置以及 Agent 做出的所有决策。指定你持有密钥的提供商：

tra init my-desk --profile autonomous --agent groq
cd my-desk

--agent	.env 中的密钥	未指定模型时使用的模型
groq	GROQ_API_KEY（免费套餐）	openai/gpt-oss-120b
google	GEMINI_API_KEY	gemini-flash-latest
anthropic	ANTHROPIC_API_KEY	claude-opus-5-5
openai、deepseek、xai、openrouter 等	参见模型和提供商	使用 --model 指定模型；tra models <provider> 会列出可用模型

添加 --venue okx（或任意 ccxt id），即可在 Bybit 以外的交易所进行交易。

3. 添加密钥。 复制示例文件并填入你的密钥。每条命令都会自动读取与 strategy.toml 同一目录中的 .env。

cp .env.example .env        # then set GROQ_API_KEY=... in .env

4. 检查。 tra check 会逐项检查设置之间是否匹配，并指出接下来需要修复的一项内容。准备就绪的交易工作区会以以下内容结尾：

ok    provider groq: ready
ready to run `tra run`

5. 运行。 tra run 会使用实时市场数据，在沙盒中做出一次决策：任何内容都不会离开你的计算机。tra run --every 15m 会按时钟每 15 分钟运行一次决策。也可以单独输入 tra 打开控制台，使用相同的命令。

tra run
tra run --every 15m

6. 准备下真实订单时。 从交易所的模拟或测试网 API 开始。从一开始就为该交易所创建交易工作区，之后只需运行三条命令：

tra init my-desk --profile autonomous --agent groq --venue bitget
cd my-desk                       # put the exchange's keys in .env beside your model key
tra keys --probe --prepare       # reads the account; on a demo or testnet sets one-way mode
tra mandate --sign "Your Name" --venue-mode
tra check

--venue 会将该交易所所需的设置写入 [execution]：其模拟或测试网 API、3 倍逐仓杠杆、每笔订单最多 200，以及止损和止盈的下单方式。你可以更改其中任何一项。各交易所创建密钥的方法见交易所账户和密钥，迈向真实订单则介绍了完整流程。

新建的交易工作区在你进行任何更改之前会如何运行

	默认值	修改位置
订单	无：沙盒会记录每项决策，不会发送任何订单	[execution].mode
交易标的	Bybit 上的 BTCUSDT，以吃单方式交易	[run].instrument、[universe]、--venue
时间周期	根据 15 分钟 K 线做出决策，并读取 1 小时和 4 小时数据作为背景	[run].bar_interval_s、context_intervals
策略	没有固定策略：分析师会选择符合测得市场状态的交易方案，或保持空仓	[agents].mechanism
止损和目标	由分析师设定；止损幅度限制在 0.2% 至 3% 之间，且不得小于一个 ATR；目标为止损幅度的 1.5 至 4 倍	[exit]
每笔交易风险	无论止损距离多远，触及止损时的损失为权益的 0.5%	[controls].max_risk_per_trade_bps
不利交易日	当日亏损达到 3% 或从峰值回撤 10% 后，不再开新仓	[controls]
持仓时限	持仓 4 小时后平仓	[exit].timeout_bars
值得进行的交易	预期优势至少为往返交易成本的 2 倍，至少一半交易持平或盈利，每天最多 6 笔	[targets]
监督	一名只能削减风险、暂停或停止交易的风险经理；两名负责报告的审计员	[audit]

要参与代码开发？请参见开发。

依次呈现的内容

1. 控制台。 在工作台中运行 tra，即可打开控制台：显示哪些内容已就绪、哪些尚未就绪，以及下一条要运行的命令。下方是命令提示符，每条命令都会在这里显示。按方向键可回看输入过的内容，按 Tab 可自动补全，help 会列出命令，exit 则会退出。对于脚本和 cron，tra -c "run --now" 会运行一条命令后退出。

2. 检查你的交易标的。 输入 run --every 15m，工作台会先刷新所有到期的数据序列，每个序列占一行。然后，它会逐一检查列表中的所有交易标的，每个标的拉取一次数据并进行评估。屏幕会实时逐步显示整个过程：

3. 对选中的每个交易标的执行一个周期。 系统找出候选标的并完成评估；筛选器从中做出选择，引用每个交易标的自身的数据；系统自己的订单则与选择并列保留。选中的交易标的会执行完整周期。终端会从一开始就显示整个处理流程，并在每个步骤开始和结束时更新。并行运行的步骤会同时转动，各自显示计时器；下方一行则会说明当前正在处理的内容：

4. 结果。 周期结束后，表格会切换为整个标的范围的检查结果：筛选器选中了什么、哪些标的在等待、哪些被持有，以及原因。接着是周期本身：分析员提出了什么建议、依据哪些数据，以及每项拒绝背后的数字。这里，一笔在区间震荡市场中的 ETH 空头交易在退出阶段被拦下：即使设置了自己的止损和目标，计入往返交易成本后，同类交易中仍有一半以上必须获胜才能打平：

然后会显示周期使用的数据及其时效、读取分析员查看的序列、设置的止损和止盈，以及哪些 Agent 作出了回应。若周期继续推进，还会显示每位验证员的论据、信心值如何衡量分析员的意见，以及止损位的风险和目标位：

5. 周期之间。 工作台会显示下一次检查的时间以及剩余分钟数，例如 next pass at 14:30:00 UTC, in 10m 57s，并倒计时。被警报唤醒的审计员也有自己的转动指示器。

同一周期的纯文本输出（--plain、管道或日志），来自一次使用实时数据的真实运行，经缩短处理：

cycle 2026-09-29T02-59-16Z BTCUSDT: 5.344s of agents, 15.042s of validators
  funding        ccxt:bybit         age 4.267s
  ohlcv          ccxt:bybit         age 32.746s
  orderbook      ccxt:bybit         age 7.544s
macro      risk-off: the operator declared a bullish state for US10Y; measured correlation is
           neutral (0.0) on a modest sample, weak evidence that does not overturn the declaration
sentiment  positive: declared state is bullish, and the measured figures both support it
technical: long on range_reversion at 0.65 over 5 bars: the close is stretched low in the window
read: zscore=-0.587, vwap_gap_bps=-3.99, ret_1_bps=1.59
validator contra   oppose on 2 cited figure(s)
validator pro      support on 3 cited figure(s)
conviction: 0.800 of 1.0 (macro 1.0, sentiment 0.5, technical 1.300)
risk: 8.29 bps of equity at the stop against the declared 50 bps, size 0.010
cost: 12.87 bps round trip, 2.00 of it estimated
gate: 25.0000 bps claimed clears 12.8723 bps cost plus 0.0000 bps margin
  refused targets: the claimed edge is 1.94x the round trip and the desk declared 2.0x;
                   the cost is certain and the edge is not

这笔交易遭到拒绝。它通过了成本门槛，却仍然失败，因为该工作台要求优势达到成本的两倍，而它只有 1.94 倍。每次拒绝都会指出背后的数据。

一个周期如何做出决策

flowchart TD
    find[["the system finds the universe and measures each instrument<br/>one data pull each; every value carries its source and age"]] --> wake
    wake{"trigger<br/>has anything moved since the last look?"}
    wake -- "no" --> held["held: one data pull, no tokens spent"]
    wake -- "yes" --> pick["the screener picks among what the system admitted<br/>citing each instrument's own figures"]
    pick -- "none taken" --> held
    pick -- "taken" --> briefs
    briefs["the system writes the briefs<br/>each role sees only the figures its job needs"] --> round1
    subgraph round1["asked at the same time"]
        direction LR
        tech["technical analyst<br/>a direction, a confidence, a horizon"]
        macro["macro analyst"]
        chain["on-chain analyst"]
        mood["sentiment analyst"]
    end
    round1 --> price["the system prices the round trip<br/>fee, spread, impact, funding, slippage"]
    price --> exits{"the stop and the target<br/>the analyst's levels, held inside your bounds<br/>does the trade break even at half its kind winning?"}
    exits -- "no" --> refused
    exits -- "yes" --> round2["validators, as many as you declare<br/>a claim that cites no figure is thrown away"]
    round2 --> matrix{"confluence<br/>do your declared states agree with the direction?"}
    matrix -- "no" --> refused["a refusal that names its figure"]
    matrix -- "yes" --> size["conviction<br/>how much, from your ladder"]
    size --> risk{"risk per trade<br/>what does it lose at the stop?"}
    risk --> gate{"cost gate and targets<br/>does the edge clear the cost, by your margin?"}
    gate -- "no" --> refused
    gate -- "yes" --> intent["the intent, written into the cycle"]
    intent --> venue["venue mode only<br/>one order, the stop and take profit attached"]

各司其职：

角色	读取内容	回答内容	绝不能做的事
技术分析师	K 线、点差、资金费率、盘口失衡、未平仓量变化，以及其时间周期和你指定的更高时间周期上的市场状态	方向、固定列表中的一种策略、置信度、时间范围，以及止损和目标价位	确定交易规模、将价位设在你的 [exit] 范围之外、在区间震荡行情中执行趋势策略，或在市场并非经测量确认的区间行情时逆势交易
宏观分析师	带日期的利率和价位、带日期的文本	风险偏好、规避风险或中性	提出方向
链上分析师	链上数据和衍生品数据	吸筹、派发或中性	提出方向
情绪分析师	你整理的带日期评分和备注	负面、中性、正面或未声明	虚构任何数据都不支持的情绪
市场筛选器	系统针对每个获准交易的标的所测量的数据：波动、点差、市场状态、成交量、与 BTC 的相关性	按顺序列出应交易的标的，并引用相应数据	添加系统未获准的标的
验证者：正方和反方	提案及其背后的数据；双方各自无法看到对方的论据	各自提出有数据依据的最有力支持或反对理由	查看另一方的论据，或引用未提供给自己的数据
验证者：中立方，担任裁决者	相同的提案和数据，以及代码检查完所有主张后提供的双方论据	支持、反对或弃权；这是唯一有效的裁决	查看倡导者的裁决，或只计算主张数量而不权衡利弊
风险经理	本次运行记录的数据：往返交易、连亏次数、你的限额、触发警报的原因	继续、缩小新开仓规模、暂停交易某些标的或停止交易；每项都须注明小时数	放宽你设定的限额，或增加规模
技术和量化审计员	本交易台记录的周期	发现的问题和拟议的更改	更改任何内容

宏观、链上和情绪分析师会读取你在 sources/ 下声明的带日期序列。每个序列要么是你保留的文件，要么是交易台自动刷新的数据源（FRED、Crypto Fear & Greed Index，或任何通过 https 返回 JSON 的付费供应商）。tra sources show 会列出每个序列的来源及其最新值的时间；超过其 max_age 的值会标记为过期，且绝不会计入。详情请参阅数据源。

由你决定运行哪些验证者。投票本身绝不会决定结果：它会根据你赋予的权重改变信念度（[conviction].validator_weight），而某种立场所代表的含义也会超出其指定角色；例如，支持方理应表示支持。

分析师之间可以意见不一。每位分析师的观点都会根据其自身数据与您设定的界线计算为 -1 到 1 之间的分数。因此，宏观读数仅略微越过界线时，分量较小；远远越过界线时，分量较大。信念度会将这些分量相加：意见一致会提高仓位规模，意见相左会按比例缩小规模，只有反对意见的权重超过支持理由时才会阻止交易。面对略微看涨的宏观环境和 0.56 的情绪评分，置信度为 0.70 的做空交易会以半仓执行；面对强烈看涨的环境时，评分则为 0，不会交易。

技术分析师在做出判断前，会先了解当前所处的市场类型。系统会测量其时间周期上的市场状态（上涨趋势、下跌趋势、区间震荡或混合状态），以及你在 [run].context_intervals 中列出的更高时间周期上的市场状态，并一并提供本周期宏观阈值所反映的信息。与市场状态不符的策略（例如在横盘市场中进行趋势交易）会被明确拒绝；相关界线由 [regime] 设定。 分析器之后的所有操作，都是对你声明的数字进行算术运算。模型无法下单、撤单或调整订单大小，无法读取项目之外的文件，也无法修改你的配置。Agent 列出了 Agent 可以访问的所有内容，运行周期则逐步讲解了每个环节。

交易平台

一个运行周期通过 ccxt 接入交易平台，因此 ccxt 支持的所有交易所都已集成：采用相同的订单路径、相同的关卡和相同的检查，核心代码中没有任何特定交易平台的名称。不同交易平台之间的区别在于 ccxt 报告其支持的功能（第二列），以及测试覆盖的程度（最后一列）：

交易平台	一个运行周期可在该平台执行的操作	实践环境	我们是否已完成端到端运行
Bybit（默认）	所有操作：下单时附带止损和止盈	demo、testnet	是，在 demo API 上：下达真实订单、附带退出订单，并取消一笔挂单
OKX	所有操作	demo（ccxt 的 testnet 开关）	是，在 demo API 上：下达真实订单、附带退出订单，并由交易平台自身的退出订单平仓
Bitget	所有操作，支持经典或统一交易账户	demo	是，在 demo API 上使用统一账户
BingX	所有操作	demo（VST，ccxt 的 testnet 开关）	是，在 demo API 上
Binance、Gate	下单，成交后立即挂出止损和止盈（exits = "separate"）	demo（Binance）、testnet（Gate）	是，在各自的实践 API 上
WEEX、BloFin、WOO X	所有操作	testnet	已可进行测试
Hyperliquid、Pacifica、WOOFi Pro、ModeTrade（去中心化）	所有操作	testnet	已可进行测试；欢迎提交 Hyperliquid 报告
KuCoin Futures、Deepcoin	所有操作	无	已集成；没有实践环境
dYdX、Paradex、Extended、Lighter（去中心化）；Deribit、Crypto.com、Coinbase International	可以下单，但 ccxt 无法在交易平台挂出退出订单，且有些平台无法设置杠杆	testnet	不适合需要在交易平台挂出退出订单的交易台
Kraken、Kraken Futures、Phemex	目前仅支持数据：ccxt 不会报告这些平台的持仓，因此不会向一个无法查看的持仓下单

“所有操作”表示 ccxt 报告支持安全下单所需的五项功能：下单、附加退出订单、读取持仓、读取未成交订单、撤单。“端到端运行”是更严格的说法，指在交易平台的 demo 或 testnet API 上完整运行，并下达真实订单。目前，Bybit、OKX、Bitget、BingX、Binance 和 Gate 已完成此类运行。有关如何在各平台创建密钥，请参阅交易账户和密钥。其他任何支持下单的交易平台都可以随时进行此类运行：先使用其实践环境，观察几个运行周期，再查看它发送的内容。每份报告都会让一个交易平台进入最后一列。

接入你所交易的平台只需四个步骤，一个命令就能完成其中大部分工作：

tra venues okx            # what it can do, and which keys it signs with
tra venues okx --setup    # the blocks to paste into envelope.toml, data.toml, strategy.toml and .env

平台报告账户费率时，系统会从你的账户中读取费率；在此之前，则会使用该平台的标准等级费率，并明确标注为标准费率。你手动填写的费率会被保留，并与账户费率进行核对。交易平台列出了完整的交易平台表格、各平台所需的密钥以及四个步骤。

模型和提供商

由你选择提供商和模型；没有任何内容是硬编码的。每个提供商都从环境变量（或配置文件旁边的 .env）读取密钥，不会从其他位置读取。

提供商	.env 中的密钥	安装依赖	结构化输出	此处实测情况
groq	GROQ_API_KEY	openai	JSON Schema，不支持时回退到 JSON 模式；由系统检查	是：openai/gpt-oss-120b 和 openai/gpt-oss-20b，在我们的记录中，每个实测周期都使用了它们
google	GEMINI_API_KEY 或 GOOGLE_API_KEY	google-genai	JSON Schema	是：gemini-flash-latest，作为备用模型
anthropic	ANTHROPIC_API_KEY	anthropic	JSON Schema	已通过单元测试；默认模型为 claude-opus-5-5
openai	OPENAI_API_KEY	openai	严格 JSON Schema	已通过单元测试
deepseek	DEEPSEEK_API_KEY	openai	JSON 模式	仅预设
mistral	MISTRAL_API_KEY	openai	JSON Schema	仅预设
xai	XAI_API_KEY	openai	JSON 模式	仅预设
openrouter	OPENROUTER_API_KEY	openai	JSON 模式	仅预设
qwen	DASHSCOPE_API_KEY	openai	JSON 模式	仅预设；请为所在区域传入 --base-url
ollama	无	openai	JSON 模式	仅预设；本地服务
local	无	openai	JSON 模式	任何兼容 OpenAI 的服务；请传入 --base-url
9router	9ROUTER_API_KEY	openai	JSON Schema	仅预设；本地路由器

无论使用哪个提供商，每个答案都会先由系统按照封闭式 Schema 解析，然后才会有人阅读。因此，仅支持 JSON 模式的模型也会受到与支持严格 Schema 的模型相同的格式约束。

[agents]
provider = "groq"
model = "openai/gpt-oss-120b"
effort = "medium"                    # minimal | low | medium | high | xhigh | max, where the
                                     # vendor takes it; left out, the vendor's default applies
fallback = ["google:gemini-flash-latest", "anthropic:claude-opus-5-5"]

[agents.roles.sentiment_analyst]     # a role that only labels can run on a cheaper model
model = "a-cheaper-model"
effort = "low"

当提供商受到速率限制或服务不可用时，系统会按顺序尝试 fallback，并使用相同的简要说明。供应商的免费额度会分别计算每个模型的用量，因此，不同角色可以共用一个提供商下的两个模型，而每个模型都保留自己的额度；tra check 会按模型评估负载，并指出何时负载过高。每次调用都会连同 token 数和延迟记录在 usage.jsonl 中；除非你设置上限，否则不会限制支出。tra keys --probe 可以验证每个密钥是否有效，而不会发送提示词。你也可以自行接入供应商，代码大约只需 30 行（模型提供商）。

迈向真实订单

目前可交易的标的都通过同一条订单路径，并经过相同的检查：

• 线性永续合约（USDT 或 USDC 保证金互换合约），可交易 ccxt 支持的任何交易场所，可做多也可做空， 并使用你声明的杠杆和保证金模式。默认配置已在六家交易所端到端运行。
• 现货交易对，仅做多且全额支付，适用于在 [execution].markets 中列出 spot 的交易台。
• 股票永续合约和代币化股票，对交易场所而言，它们分别是永续合约和现货交易对，并遵守底层交易所的交易时段。
• 预测市场结果，适用于列出 prediction 的交易台，由其分析师自行判断概率，并按结算结果定价。

这就是项目的起点，而不是终点。对于现货，交易场所 说明了如何设置交易台。现货、股票永续合约和代币化股票已在 Bybit 和 OKX 的演示环境中运行；预测市场结果已在沙盒中使用实时数据运行，其订单路径也已针对 ccxt 的数据结构完成测试，待接入模拟交易场所。定期货、反向合约和期权正在开发中，每种都有自己的成本模型、退出规则和测试。在某种市场类型具备这些条件之前，交易场所模式会在每笔订单上检查类型并拒绝不支持的类型，因为系统尚无法为其定价和提供保护的市场，不应发送订单。边界说明了每种类型的适用范围。

Agent 交易台分为三个步骤，你可以按自己的节奏停留在任意一步：

步骤	方式	会发生什么	需要
1. 沙盒	tra run	使用实时数据运行完整周期；记录每个决策，不发送订单	模型密钥
2. 演示环境或测试网 API	tra run，并设置 [execution].mode = "venue" 和 environment = "demo" 或 "testnet"	在交易所的演示环境或测试网 API 上发送真实订单，附带退出指令，并管理持仓	已签署的授权书、杠杆、max_notional、练习用密钥
3. 真实资金	相同方式，但使用 environment = "mainnet"	使用真实资金发送真实订单	以上全部要求，外加达到试运行级别的阶梯（使用证据运行 tra ladder promote）

步骤 1 和 2 已在 Bybit、OKX、Bitget、BingX、 Binance 和 Gate 的演示环境或测试网 API 上端到端运行。我们尚未运行过步骤 3； 请先用少量资金自行验证。

如果你使用自己的脚本策略，而不是这些 Agent，那么在此之前也有独立的研究流程：tra data get BTCUSDT 2025-01-01 和 tra backtest 会回放交易所一天的历史数据，并扣除所有成本；tra paper --minutes 30 会使用实时数据流运行，不发送任何内容；tra live 则是在严格上限保护下进行的小规模试运行。示例核心用于展示流程，而非保证盈利；回放会在结果产生时打印净收益，无论盈亏。 实时级别提供了详细信息。

交易场所模式是唯一可能造成资金损失的模式，因此启用前设有一道关卡。使用 tra mandate 阅读授权书；接受后，运行 tra mandate --sign "Your Name"，即可将授权书保存到项目中的 MANDATE.md，并一步为 [execution] 签署你的姓名和当天日期。仅签署不会启用任何功能；--venue-mode 会同时签署授权并启用订单。tra check 会列出其他所有缺失项。

你的资金、订单和持仓

订单开始流转后，有三件事会保护资金，全部遵循系统自身规则，不受模型影响：

下单前	发送订单时	持仓期间
读取账户的实际权益和可用保证金	在交易场所应用你的杠杆并读取确认	每轮开始时，逐一根据交易场所的信息检查持仓
仓位大小取实际权益与您允许交易台使用的金额两者中的较小值	如果订单的强平价格会落在止损价以内，则拒绝该订单	超过持仓时限的仓位会通过仅减仓订单平仓
订单只能使用部分可用保证金	吃单入场会使用滑点范围内的限价 IOC，绝不会直接提交裸市价单	被交易场所的止损或止盈平仓的仓位会记录实际手续费和资金费用
当日亏损超过你的限额后，停止新开仓	止损和止盈随入场订单一起提交，因此即使此进程退出，它们仍然有效	交易台停止前，熔断开关会平掉所有仓位

谁决定什么，一句话说明：分析师提出方向，你的风险规则设定仓位大小，你选择杠杆，而最后两项都不由任何模型决定。 杠杆永远不会让交易规模变大。它只决定交易占用多少保证金，以及强平价距离有多远。

[execution]
mode = "venue"
environment = "demo"             # demo | testnet | mainnet
leverage = 3                     # yours to choose; it never makes a trade bigger
max_notional = 400               # the most one order may be worth, in quote currency
margin_mode = "isolated"         # isolated | cross
hold_limit = "timeout"           # close by time after [exit].timeout_bars; or horizon, or none

在底层，每个交易场所都遵循以下规则：订单只会发送到你声明的环境（demo、testnet 或 mainnet）；已有持仓或未成交订单时，拒绝第二次入场；如果订单规模不符合交易场所的步进要求，则直接拒绝，不会四舍五入；如果时钟与交易场所的时间相差超过一秒，则在签名任何内容之前拒绝；收到 Ctrl-C 或服务停止信号时，会先取消尚未成交的订单，再退出进程。每次平仓都会写入 positions.jsonl，每笔完结的交易都会写入 round_trips.jsonl。资金、订单和持仓列出了每项设置、每种拒绝情形以及背后的计算方式。

使用前需要了解一点：持仓检查会在每轮 tra run --every 开始时执行。如果没有交易台运行，未平仓的持仓只有交易场所端的止损和止盈保护，因此，打算无人值守运行的交易台应由监督程序托管。

默认情况下，订单会穿过订单簿（taker-taker）：订单总会成交，这也是大多数交易台的交易方式。将 [run].venue_key 指向 maker-taker 通道后，入场订单会改为以仅挂单方式留在订单簿上——手续费更低，但成交更少，因为市场可能会在订单成交前离开。无论采用哪种方式，成本门槛都会根据你所选通道的手续费进行定价。

观察一个桌面，以及保留的内容

控制台会在自己的进程中运行命令，因此关闭控制台会结束它正在运行的内容。需要持续运行的桌面应交由监管程序（systemd、服务管理器、tmux）管理，然后你可以随时随地查看：

tra watch --every 5s       # a read-only view built from the records the desk writes

tra watch 不会建立连接、持有密钥或加锁，因此打开或关闭它都不会影响桌面。

保留的内容及其位置：

内容	位置	说明
一个周期执行的所有操作	runs/cycles/<id>/	快照、简报、答案、意图、placed.json、cycle.json，以及包含原始输入的 inputs.json.gz；cycle.json 保存每个文件的 sha256
对整个市场的筛选过程	runs/screens/	每个测量过的标的、筛选器的选择及原因
每次模型调用	runs/cycles/usage.jsonl	token 数、延迟、价格
桌面何时运行，以及什么使其停止	runs/cycles/scheduler.jsonl	每次启动和停止各占一行
每个平仓的仓位，按时间、交易场所或熔断开关记录	runs/cycles/positions.jsonl	交易场所模式
每笔已完成交易的入场、出场、费用和资金费	runs/cycles/round_trips.jsonl	交易场所模式；量化审计员读取的内容
每天首次读取的权益	runs/cycles/equity.jsonl	每日亏损限额的计算基准
你在提示符处输入的内容	.tra-history	仅为便利功能；tra -c 不会保留任何内容

命令行

每条命令都会说明它执行了什么。退出码为 0 表示通过，1 表示某个门禁未通过，2 表示用法错误。--json 输出机器可读内容，--plain 输出文本而非面板。

快速开始

命令	作用
tra	打开控制台
tra init my-desk --profile autonomous	创建为各个 Agent 配置好的项目，并为每个文件添加注释
tra check	检查所有设置之间是否一致，并说明需要修复的内容
tra keys --probe	验证每个密钥是否可用；不会打印任何密钥，也不会发送提示词或订单
tra models groq	从供应商读取你的密钥可用的模型；不会发送提示词
tra init my-desk --profile autonomous --venue okx	创建针对单个交易所配置好的交易台：数据、订单、演示或测试网 API、密钥
tra venues	文档介绍的所有交易场所，以及各自支持的功能
tra venues okx --setup	某个交易场所支持的功能，以及可粘贴以便在该场所交易的配置块
tra mandate	交易场所模式要求的文本；使用 --sign "Your Name" 可将其保存为 MANDATE.md，并一步签署 [execution]

运行

命令	作用
tra run	执行一个自主周期
tra run --every 15m --cycles 12	按计划运行十二轮：第一轮立即开始，之后每隔一个十五分钟时段运行一轮
tra run --now	即使触发条件原本会让市场平静时段保持静默，也要求 Agent 名单中的 Agent 运行
tra watch --every 5s	只读查看正在运行的交易台
tra audit	两个审计器检查记录；不会应用任何内容
tra backtest、tra paper、tra live	回放、影子运行、金丝雀运行

数据

命令	作用
tra data get BTCUSDT 2025-01-01	下载一天的数据，验证校验和，对数据进行审计，并写入 Parquet 和资金费率
tra data audit export.csv --mapping mapping.toml	将你自己的 CSV 或 Parquet 数据交由同一套审计流程处理
tra data pull BTCUSDT	通过 data.toml 中的链获取一个实时快照
tra sources show、tra sources pull	查看研究分析师读取的序列来自何处以及数据有多旧；立即刷新这些序列
tra sources add macro us10y --from fred --id DGS10 --high bearish	一步将序列添加到数据架上：立即拉取数据，并根据其自身历史数据绘制界线
tra universe	查看当前交易场所上的发现功能找到哪些永续合约，以及每个筛选条件排除了哪些合约
tra runs verify	使用哈希验证每个周期的文件，并根据原始输入验证简报
tra runs prune --keep 90d	查看将要删除的旧周期目录；添加 --yes（和 --archive）即可执行

阶梯、研究与主机

命令	作用
tra ladder show、promote、demote	查看交易台所处的层级；有证据时上升一级，或下降一级
tra chain floor、observe、check、validate	逐层查看研究链（证伪链）
tra ledger show	查看所有夭折的想法，以及它们夭折的原因
tra agent session、eval、trace	查看研究会话、模型比较结果，以及回读一次运行记录
tra mcp serve	将只读门禁作为工具提供给任意 MCP 主机

它能保证什么，以及尚未构建的内容

有些规则由系统和测试强制执行，是必须始终遵守的保证；每次更改都必须保留这些规则：

• 模型不会接触订单或密钥。 模型读取数据并作答；系统负责确定规模、定价、限制并发送。
• 模型不能放宽控制。 模型可以收紧限制、降低梯级或启用紧急停止开关；绝不能扩大、提升或解除控制。
• 每次决策最多对应一个订单。 交易平台出错时，系统会记录错误，并在下一个周期重新决策；不会围绕真实资金重试。
• **数据过时或缺失时会被拒绝，**绝不会将其视为零或当前数据。

其他内容只是尚未构建，欢迎贡献：反向合约、定期期货和期权；ccxt 之外的链上交易平台；多个账户；转账和资金管理；路由和执行算法；投资组合记账。边界逐项列出了当前实现的功能，以及贡献者需要完成的工作。示例策略核心仅供参考：由你来定义自己的优势。

责任说明明确说明了涉及真实资金时责任归属何处。

项目未来方向

项目正在积极开发中，本页面描述的是项目目前的状态，而非终点。

• 支持更多市场类型。 现货、股票永续合约、代币化股票和预测市场已构建完成；之后将支持反向合约、定期期货和期权，且每种类型在交易平台模式接受之前，都会配备自己的成本模型、退出规则、规模设定和测试。
• 端到端接入更多交易平台。 ccxt 支持的每个交易平台都已通过相同的订单路径和关卡。每个平台在自己的演示或测试网 API 上完成一次完整运行（使用我们的或你的 API）后，便会加入交易平台表格最后一列中已有的六个平台。
• **逐项实现尚未构建的其他内容，**同时不削弱任何保证。

使用发行版。 PyPI 安装的是最新发行版，也是应该运行的版本。发行版来自 master。develop 分支用于构建下一个发行版：它经常变动，其中的提交不代表发行版，可能包含尚未完成或发布前再次修改的工作。一组更改合并到 master、打上标签并发布后，才会成为发行版；CHANGELOG.md说明了每个发行版包含的内容。

文档

完整文档位于 docs.bijectivelabs.dev。文档源码在 docs/ 中，因此行为变更及其说明页面会放在同一个拉取请求中。

阅读内容	适用对象
为何如此构建	本项目旨在应对的、已有文档记录的失败案例及其来源，以及我们的构建经验
周期	周期的逐步说明，以及影响周期的所有设置
Agent	各个角色、它们读取的内容，以及 Agent 可以和不可以访问的内容
数据源	宏观、链上和情绪数据的来源、获取方式及新鲜度
资金、订单和持仓	权益、保证金、杠杆、强平、每日亏损、时间退出、紧急停止开关，以及这些操作留下的记录
交易场所	支持哪些交易场所，以及如何添加自己的交易场所
使用语言模型，模型提供商	模型的使用方式：回退、支出和添加提供商
实盘层级，交易 Agent	从回放到实盘会话的逐级流程
使用自己的数据，数据关卡	你提供的交易历史、序列和供应商数据源（CSV、JSON 或 Parquet 格式），以及每个文件必须通过的检查
边界，责任	哪些内容有保证、哪些功能尚未实现，以及由谁负责
Agent，MCP 服务	研究 Agent 和 MCP 服务
架构	软件包、导入规则和文件格式
证伪链，执行真实性，终止账本	研究链、执行真实性和判定结果
命令行	所有 tra 命令
CHANGELOG.md	变更内容

开发

git clone https://github.com/BijectiveLabs/bitra && cd bitra
uv sync --all-extras
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest

CONTRIBUTING.md 介绍了分支流程以及代码必须遵循的标准。

项目起源

本仓库于 2026 年 10 月向公众开放。其历史始于 2026 年 9 月 12 日，当时代码从 Bijective 的内部工作中分离出来；此后的每次提交、每个标签和每位贡献者都记录在这里。项目所依据的理念则更早：证伪链、成本模型以及每笔订单前的控制措施，都源自 Bijective 的研究，以及本仓库创建之前正在开发的交易平台。语言模型 Agent 是后来加入的，位于这些关卡之上，因此它们可以提出建议，却绝不能确定规模、定价或发送订单。

许可证

MIT。请参阅 LICENSE；NOTICE 列出了本软件包所依赖的第三方软件。

由 Bijective Labs 构建。