# TraderHarness full documentation

Canonical source: https://github.com/HephaestLab/TraderHarness

This file is generated from the public README and documentation pages.

---

<!-- source: README.md -->

# TraderHarness

<p align="center">
  <strong>面向 LLM 交易 Agent 的抗污染回测环境——同时也是一个构建在每次运行之上的训练数据合成器。</strong><br>
  真实 A 股数据 · 严格时点掩码 · 指纹回放 → 轨迹导出
</p>

<p align="center">
  <a href="README_en.md">English</a> ·
  <a href="https://github.com/HephaestLab/TraderHarness/actions/workflows/ci.yml">CI</a> ·
  <a href="https://pypi.org/project/traderharness/">PyPI</a> ·
  <a href="CHANGELOG.md">Research Beta</a> ·
  <a href="https://hephaestlab.github.io/TraderHarness/">文档站</a> ·
  Apache-2.0
</p>

LLM Agent 正在走进真实交易：研究、决策、下单，越来越多地由模型端到端完成，而不是人工编写的策略。

但"给 Agent 做回测"至今没有规范化的框架。通用模型可能认得被测的日期、公司，甚至那段历史走势本身——这种数据泄漏会悄悄让评测失效。成交口径五花八门，跑出来的结果无法复现，结论自然难以采信。

TraderHarness 就是这套规范：一个抗污染的 LLM 交易 Agent 回测执行环境——同时，由于每次模型调用都被全保真记录，它也是一个把这些运行一键变成轨迹训练数据的数据合成器。

<p align="center">
  <img src="docs/assets/traderharness-demo.gif" alt="TraderHarness 流式历史回放控制台" width="920">
</p>

<p align="center"><sub>该 GIF 由本地研究控制台截图生成（<code>webui/scripts/capture-demo.mjs</code>）。UI 有变化时执行 <code>npm run capture:demo</code> 重新生成；将随 v1.0 验收跑一并更新。</sub></p>

## 规范化回测框架

TraderHarness 交给模型一个严格对齐历史时点的市场、一套研究工具和一个账户。模型可以自主检索、写分析代码、修正判断，并通过唯一受控入口下单——环境里没有实盘市场，也没有券商接口。首个生产数据集覆盖中国 A 股：五年全市场日线与 5 分钟线、公告、政策快讯、基本面、估值、分红以及沪深 300 基准。

- **构造上抗污染。** 每个数据出口强制执行时点掩码，外加确定性的日期与公司匿名化——Agent 无法认出被测的时间段和股票。
- **公平成交。** 5 分钟行情渐进可见、分钟级撮合；每一笔成交都经过唯一路径 `TradingBus.place_order()`，按不复权的历史真实价格结算。
- **确定性。** 预载完成后零数据 I/O——相同的可见数据与动作序列，必然得到相同的环境结果。

## LLM 交易数据合成器

每一次回测同时就是一次数据生产，链路分三步：

1. **全保真轨迹。** 每一次 LLM 调用都会持久化完整消息列表、完整工具 schema、模型回答与推理内容、每次工具调用及其参数，以及阶段/子窗口元数据。
2. **指纹回放。** 生成的 cassette 可以在没有 API Key 的情况下确定性重放；分享之前，`traderharness audit` 会扫描序列化产物中泄漏的实体与日期。
3. **轨迹（trajectory）导出。** `traderharness export sft` 输出 OpenAI 风格 JSONL，并由掩码与泄漏检查把关。

```bash
traderharness audit result.json replay.jsonl
traderharness export sft result.json --output training.jsonl
```

研究控制台会把同一份证据渲染成逐笔复盘档案：成交时刻的 5 分钟 K 线、Agent 当时的推理陈述，以及产生这笔成交的具体工具调用。

<p align="center">
  <img src="docs/assets/results-workbench.png" alt="TraderHarness 回测结果研究工作台：基准、回撤、K 线、成交与决策证据" width="920">
</p>

完整契约见[训练数据](docs/training-data.md)；经过筛选的导出数据发布在 Hugging Face 的 [traderharness-ashare-5y 数据集](https://huggingface.co/datasets/ANTICH/traderharness-ashare-5y)。

## 研究控制台

内置的本地控制台（FastAPI + React）让回测变成可以围观的现场：像素风办公区实时直播回放过程，绩效、逐笔档案和跨 run 对比在同一个窗口里联动更新。它是本地研究工具——请保持只监听 localhost，不要暴露到公网。

<p align="center">
  <img src="docs/assets/live-control-room.png" alt="TraderHarness 实时控制室正在直播历史回放" width="920">
</p>

<table>
  <tr>
    <td width="50%"><img src="docs/assets/office-live.png" alt="像素办公区特写"></td>
    <td width="50%"><img src="docs/assets/live-performance.png" alt="运行中的实时绩效面板"></td>
  </tr>
  <tr>
    <td><sub><strong>像素办公区。</strong>每个 Agent 是工位上的一个角色；回放时钟、阶段和工具活动实时流动。</sub></td>
    <td><sub><strong>实时绩效。</strong>净值曲线、基准、回撤和持仓随交易日推进同步更新。</sub></td>
  </tr>
  <tr>
    <td width="50%"><img src="docs/assets/trade-review.png" alt="逐笔复盘：成交 K 线与 Agent 推理"></td>
    <td width="50%"><img src="docs/assets/run-compare.png" alt="跨 run 对比视图"></td>
  </tr>
  <tr>
    <td><sub><strong>逐笔复盘。</strong>每笔成交都能回溯到对应的 5 分钟 K 线、Agent 当时的推理和触发它的工具调用。</sub></td>
    <td><sub><strong>跨 run 对比。</strong>在同一份掩码数据上给不同 Agent 或不同检查点排名。</sub></td>
  </tr>
</table>

## 为什么不是普通 Agent Demo

| 能力 | 常见 Demo | TraderHarness |
|---|---:|---:|
| 基本面与新闻时点对齐 | 局部 | 每个数据出口强制执行 |
| 日期与公司匿名化 | 无 | 确定性实体/日期遮罩 |
| 盘中公平成交 | 常用收盘价 | 5 分钟可见性 + 分钟级撮合 |
| LLM 结果复现 | 仅日志 | 请求指纹校验的 replay |
| 训练轨迹 | 经常截断 | 请求、推理、工具、结果全保真 |
| 多 Agent | 共享聊天模拟 | 隔离组合对比 + 单执行者委员会 |
| 回测期间数据 I/O | 常见 | 启动预载后零 I/O |
| 历史回放 | 临时脚本拼接 | 流式、按阶段渐进披露的历史回放——绝非实时行情 |

TraderHarness 负责历史环境、信息边界、公平撮合和证据产物，不限定交易方法论。与 TradingAgents、StockBench、Qlib 等项目的完整边界对比见[项目对比](docs/comparison.md)。

## 四智能体展示阵容

TraderHarness 在 `traderharness/agents/builtin/` 下内置四个人设清晰、互不重复的参考 Agent 卡片：

| Agent id | 风格 | 风险画像 | 持仓周期 |
|---|---|---|---|
| `trend-breakout` | 量价突破、相对强度、成交量确认、机械止损 | 进取 | 3–10 个交易日 |
| `quality-compounder` | 盈利质量、资产负债表与估值纪律，低换手 | 保守 | 20–60 个交易日 |
| `event-hawk` | 公告/政策/新闻催化，重视时间戳与来源核验 | 进取 | 1–5 个交易日 |
| `quant-researcher` | 沙箱内可复现的横截面因子检验 | 均衡 | 2–20 个交易日 |

验收参考跑是这四个 Agent 在 **2024-03-04 → 2024-03-29** 区间的正面对比，执行模型为 `deepseek-v4-pro` 的 thinking（深度推理）模式，全程开启实体遮罩：

```powershell
$env:DEEPSEEK_API_KEY="..."
traderharness compare `
  --agent trend-breakout `
  --agent quality-compounder `
  --agent event-hawk `
  --agent quant-researcher `
  --start 2024-03-04 `
  --end 2024-03-29 `
  --mask-entities `
  --entity-mask-seed 42 `
  --record-replay showcase_mar2024 `
  --output showcase_mar2024/comparison.html
```

`--record-replay` 会保存一份带指纹校验的 cassette，可以在没有 API Key 的情况下确定性重放、审计和分享。参考[快速开始](#快速开始)和[训练数据](docs/training-data.md)。

**验收结果**（2024-03-04 → 2024-03-29，实体遮罩 seed `42`，`deepseek-v4-pro` thinking high）。
按夏普排序；该跑已通过 `traderharness audit`（零发现），可用 `--replay showcase_mar2024` 无 Key 复现：

| Agent | 累计收益 | 年化收益 | 夏普比率 | 最大回撤 | 胜率 | 成交次数 |
|---|---:|---:|---:|---:|---:|---:|
| `quality-compounder` | +0.52% | +7.92% | 1.09 | 0.76% | 33% | 9 |
| `trend-breakout` | +0.09% | +1.32% | −0.20 | 1.07% | 38% | 16 |
| `event-hawk` | −0.70% | −9.74% | −3.22 | 0.93% | 0% | 5 |
| `quant-researcher` | −1.33% | −17.75% | −4.19 | 1.73% | 40% | 19 |
| 沪深 300（基准） | −0.10% | — | — | — | — | — |

## 双重遮罩

数据泄漏是系统问题，不能只靠 prompt 约束。

- **时序遮罩**：日线严格满足 `date < current_date`；分钟线只暴露已发生子窗口；基本面严格满足 `pub_date <= current_date`。
- **日历遮罩**：Agent 看到的日历日期变为 `D-1`、`D+0` 等相对偏移。
- **实体遮罩**：股票代码和公司别名映射为确定性中性实体，同时保留创业板/科创板等交易规则（如 20% 涨跌停）。
- **输出清洗**：模型回答、推理、工具参数、委员会备忘、轨迹和 replay 全部经过同一套遮罩。
- **泄漏审计**：发布或导出轨迹前，可对 JSON、JSONL、Parquet 进行扫描。

<p align="center">
  <img src="docs/assets/dual-mask.svg" alt="历史公告经过日期与实体双重遮罩后的 Agent 视图" width="920">
</p>

v1.0 发布验收已对完整的一月 DeepSeek 轨迹做序列化后出口审计，未检出真实公司别名或绝对日历日期。这里指自动化出口审计结果，不代表语义再识别风险为零——参见[抗污染机制](docs/contamination.md)。

## 快速开始

支持 Python 3.10–3.12。六十秒上手，无需 API Key：

```bash
pip install "traderharness[llm,data,ui]"
traderharness data download --full
traderharness demo
```

`traderharness demo` 使用真实市场数据回放一段已经遮罩的单日轨迹，不需要 API Key。这是对真实本机行情的**流式历史回放**，按阶段渐进披露——不是实时行情，也不会用模拟价格替代真实数据。

启动本地研究控制台：

```bash
traderharness ui
# 打开 http://127.0.0.1:8000
```

运行真实模型回测：

```powershell
$env:DEEPSEEK_API_KEY="..."
traderharness run `
  --agent trend-breakout `
  --start 2024-03-04 `
  --end 2024-03-29 `
  --mask-entities `
  --record-replay run.jsonl
```

也可以用容器启动：

```bash
docker compose up --build
```

Compose 会把本机 `~/.traderharness` 挂载到 `/data`，不会把完整数据集烘焙进镜像。打开 `http://127.0.0.1:8000`，内置回放不需要 API Key。

### 每个交易日

每个交易日分三个有边界的阶段：

1. **盘前研究**：账户、昨日市场宽度、板块、自选股、公告和政策；禁止下单。
2. **开盘窗口**：09:30–10:00 的 5 分钟线按子窗口逐步可见；允许下单。
3. **尾盘窗口**：14:30–15:00 的数据逐步可见；允许下单并结束当天。

Agent 可查询历史 K 线、基本面、估值、公告和新闻，进行全市场筛选，在沙箱里自由使用 `numpy/pandas/scipy`，并查看只读账户。所有成交都必须经过 `TradingBus.place_order()`。

## 独立赛马 vs 单执行者委员会

`compare` 和委员会是建立在同一个遮罩市场和同一条下单路径上的两种不同产品。

### 独立组合对比

`compare` 让每个 Agent 拥有独立账户，在相同市场时钟和初始资金下并行运行，再按收益、风险和行为指标排名。[四智能体展示阵容](#四智能体展示阵容)就是用这个命令跑的。

```bash
traderharness compare \
  --agent trend-breakout \
  --agent quality-compounder \
  --start 2024-03-04 \
  --end 2024-03-29 \
  --mask-entities \
  --output comparison
```

<p align="center">
  <img src="docs/assets/compare-workbench.png" alt="TraderHarness 对比工作台：独立账户 Agent 排名" width="920">
</p>

### TradingAgents 风格委员会

委员会是"一个交易 Agent + 多个只读顾问 + 一个 Trader 执行者"。顾问并发研究，但只有 Trader 能获得下单工具，保证一个账户只有一条可追责的订单路径。

```yaml
id: research-committee
name: Research Committee
model: deepseek-v4-pro
persona: |
  你是委员会的唯一交易执行者。顾问意见只是证据输入；你必须独立核验，
  遵守仓位与交易窗口约束，并且只有你可以调用 place_order。
advisors:
  - role: fundamentals
    model: deepseek-v4-pro
    prompt: 关注盈利质量、估值、资产负债表和公告中的基本面变化。
  - role: technicals
    model: deepseek-v4-pro
    prompt: 关注趋势、量价、波动、支撑阻力和信号失效条件。
  - role: risk
    model: deepseek-v4-pro
    prompt: 从组合暴露、仓位集中、成交约束和尾部风险提出否决意见。
```

这份示例严格对应加载器真实的顶层 `advisors:` schema，没有嵌套的 `committee:` 结构，也没有虚构字段。完整六角色参考见 [`examples/tradingagents_committee.yaml`](examples/tradingagents_committee.yaml) 和[设计文档](docs/design/multi-role-agent.md)。

## 数据与架构

<p align="center">
  <img src="docs/assets/architecture.svg" alt="TraderHarness 数据、引擎、Agent、轨迹和评估架构" width="920">
</p>

核心不变量：回测期间零 I/O、单一下单路径（`TradingBus.place_order()`）、环境确定性、Agent 不持有 Portfolio、使用不复权真实价格。

全量数据下载会校验文件大小和 SHA-256，再原子安装到：

```text
~/.traderharness/dataset/
├── daily.parquet
├── 5min_clean/
├── announcements.parquet
├── news_cls.parquet
├── fundamentals.parquet
├── valuation.parquet
├── dividends.parquet
├── index_300.parquet
└── metadata.json
```

增量更新幂等：

```bash
traderharness data update
```

公开新闻数据保留模板化标题，去除有版权的正文。数据再分发和商业使用前请确认上游许可。详见[数据与许可](docs/data.md)和[核心架构](docs/architecture.md)。

## 面向 AI 的入口

TraderHarness 提供机器可读的操作指南，让编程助手不用猜测上面这些不变量：

- [`llms.txt`](llms.txt) —— 官方文档的精简索引。
- [`llms-full.txt`](llms-full.txt) —— 同一份文档集合合并成一个文件，由 `scripts/build_llms_full.py` 生成。
- [`AGENTS.md`](AGENTS.md) —— 公开操作指南：项目地图、不可协商的不变量与工作流程。

推荐先给 Cursor、Claude Code 等工具以下指令：

```text
先阅读 AGENTS.md 和 docs/architecture.md。新增 Agent 时不得绕过
TradingBus、时点遮罩和单一下单路径；先写失败测试，再运行相关测试和 replay demo。
```

## 和我们一起建设

TraderHarness 最值得扩展的几个接缝是：数据源适配器、工具、沙箱后端、评测指标、实盘 Broker adapter，以及研究控制台前端。每一个都在[扩展指南](docs/extensions.md)里有简短契约；流程和必跑检查见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。

```bash
.venv\Scripts\python.exe -m pip install -e ".[all]"
.venv\Scripts\python.exe -m pytest tests/ --no-header -q
.venv\Scripts\python.exe -m ruff check traderharness
cd webui
npm ci
npm test
npm run build
npm run test:e2e
```

## 路线图

完整版本（含明确的非目标）见 [`docs/roadmap.md`](docs/roadmap.md)：

| 状态 | 事项 |
|---|---|
| ✅ v1.0 已交付 | 回测引擎、遮罩、replay/轨迹导出、多 Agent 对比、委员会、研究控制台 |
| 🚧 下一阶段 | 模拟盘（Paper Trading，复用同一引擎和遮罩契约的前向仿真模式） |
| 📋 规划中 | 实盘 Broker adapter |
| 📋 规划中 | 面向不可信/第三方 Agent 卡片的强化沙盒 |
| ❌ 非目标 | 公开排行榜、多租户托管服务、市场冲击建模 |

## 边界与限制

- 目前维护的生产数据集覆盖中国 A 股；欢迎为其他市场提供适配器。
- 目前没有模拟盘或实盘接口，参见[路线图](docs/roadmap.md)。历史仿真不模拟市场冲击，也不保证实盘表现。
- 部分上游字段的再分发可能受供应商条款限制。
- TraderHarness 是研究基础设施，不是投资建议，也不是券商系统。

## Star 历史

<a href="https://star-history.com/#HephaestLab/TraderHarness&Date">
  <img src="https://img.shields.io/github/stars/HephaestLab/TraderHarness?style=for-the-badge&logo=github" alt="GitHub stars — 点击查看 Star History" width="220">
</a>

## 引用

如果 TraderHarness 对你的研究有帮助，请引用。机器可读记录见 [`CITATION.cff`](CITATION.cff)——GitHub 的 "Cite this repository" 按钮会直接读取它：

```bibtex
@software{traderharness2026,
  title  = {TraderHarness: A Contamination-Resistant Environment for Autonomous Trading Agents},
  author = {{HephaestLab}},
  year   = {2026},
  url    = {https://github.com/HephaestLab/TraderHarness},
  version = {1.0.0}
}
```

## 许可证

Apache-2.0 © HephaestLab。详见 [`LICENSE`](LICENSE)。

---

<!-- source: docs/quickstart.md -->

---
description: TraderHarness 快速上手：pip/Docker 安装、五年 A 股数据下载、免密回放演示、本地研究控制台与多 Agent 对比。
---

# 快速上手

## 安装

=== "pip"

    ```bash
    pip install "traderharness[llm,data,ui]"
    ```

=== "源码 / Windows"

    ```powershell
    git clone https://github.com/HephaestLab/TraderHarness
    cd TraderHarness
    python -m venv .venv
    .venv\Scripts\python.exe -m pip install -e ".[all]"
    ```

=== "Docker"

    ```bash
    docker compose up --build
    ```

## 安装行情数据

```bash
traderharness data download --full
```

下载完成后会按发布清单逐项校验文件大小与 SHA-256，再原子安装到 `~/.traderharness/dataset`。

## 跑免密回放演示

```bash
traderharness demo
```

盒带里是一段真实、经过掩码的模型轨迹，不需要 API key；引擎仍然会用本地真实行情对它进行评测。

## 打开 Web 控制台

```bash
traderharness ui
```

浏览器打开 [http://127.0.0.1:8000](http://127.0.0.1:8000)。服务默认只绑定回环地址，除非显式开启，否则拒绝意外的公网暴露。

![回测控制室：像素办公室、实时净值与决策事件流](assets/live-control-room.png)

*回测控制室：左侧像素办公室里每个 Agent 各司其职，右侧实时净值曲线与决策事件流同步滚动。*

## 跑一个真实的模型 Agent

```powershell
$env:DEEPSEEK_API_KEY="..."
traderharness run `
  --agent trend-breakout `
  --start 2024-03-04 `
  --end 2024-03-29 `
  --mask-entities
```

`trend-breakout` 是内置的参考 Agent 卡片之一——与 `quality-compounder`、`event-hawk`、`quant-researcher` 并列，各自拥有独立人设，默认执行模型为 `deepseek-v4-pro`（thinking 深度推理模式）。把四位选手放进同一市场时钟正面对决：

```powershell
traderharness compare `
  --agent trend-breakout `
  --agent quality-compounder `
  --agent event-hawk `
  --agent quant-researcher `
  --start 2024-03-04 `
  --end 2024-03-29 `
  --mask-entities `
  --output showcase
```

加 `--record-replay cassette.jsonl` 可以把整段运行录成确定性的、可过泄漏审计的回放盒带。

![多 Agent 对比工作台](assets/compare-workbench.png)

*对比工作台：同一市场时钟下多个 Agent 的权益曲线、风险与行为指标横向排名。*

---

<!-- source: docs/contamination.md -->

---
description: TraderHarness 如何在每个数据出口执行时点掩码、日期相对化与公司实体匿名化，防止 LLM 回测中的记忆污染与执行层泄漏。
---

# 无数据泄漏的 LLM 交易回测

TraderHarness 把历史污染当作环境边界来处理，而不是提示词层面的口头约定。

## 基本概念

**时点掩码（Point-in-time masking）**：任何暴露给 Agent 的数值，在离开环境之前都要先过模拟时钟的过滤。日线严格早于当前交易日，5 分钟线截断到当前子窗口，基本面记录的发布日期不得晚于当前日期。

**日期匿名化**：把 Agent 看到的绝对日历日期替换为相对模拟当前的偏移量。今天是 `D+0`，前一个自然日是 `D-1`。一天内的时刻保持可见。

**实体掩码**：真实 A 股代码与已知公司别名到中性假名之间的确定性、全运行范围双射。代码在兼容的板块分组内打散，使涨跌停规则在匿名化后依然成立。

**三阶段交易循环**：一个有边界的交易日——禁止下单的盘前研究、渐进揭示的 09:30–10:00 开盘窗口、渐进揭示的 14:30–15:00 尾盘窗口。

## 掩码覆盖范围 {#egress-coverage}

掩码作用于：

- 日线与盘中 K 线；
- 选股筛查、基本面、估值、公告与政策新闻；
- 账户与自选股视图；
- Python 沙箱中 `traderharness_api` 返回的 DataFrame；
- 模型回复、推理字段、工具参数与委员会备忘录；
- 跨日记忆、落盘轨迹、回放盒带、对比结果与轨迹导出。

Agent 通过工具回传的伪代码会在内部解析还原后再撮合；账户视图再经同一正向映射渲染，Agent 全程无需接触真实代码。

![日期与实体双重掩码的变换过程](assets/dual-mask.svg)

*同一条历史公告，两种身份：左侧是仅限环境的原始记录（真实日期 + 真实公司），右侧是 Agent 可见的视图（相对日期 `D-9` + 伪身份 `公司-600731`）。*

## 工件审计

```bash
traderharness audit result.json replay.jsonl export.parquet
```

审计器检查已知真实公司别名、六位 A 股代码泄漏、绝对 ISO/中文日期以及月-日形式。v1.0 发布验收中对一段序列化的一个月期 DeepSeek 轨迹做了审计，在最终出口修复之后未检出任何真实实体别名或绝对日期。

这个结论的含义是窄的：它验证的是已知的词法与日历出口契约。它无法证明模型不能从独特的财务模式、产品、高管或事件推断出某家知名公司。要发布可公开的评测结果，请报告掩码配置与种子、保留审计输出，并在语义重识别影响重大时对比遮罩与未遮罩运行。

## 执行层泄漏

如果撮合引擎允许模型先看完整个盘中窗口、再回头选择更早的优惠价格，信息掩码就失去了意义。TraderHarness 先揭示每个开盘/尾盘子窗口、再给出该窗口的合格成交，并让每一笔订单都经过 `TradingBus.place_order()`。因此动作序列不可能选中决策时刻不可见的价格。

---

<!-- source: docs/architecture.md -->

# 核心架构

![TraderHarness 数据、引擎、Agent、轨迹与评估架构](assets/architecture.svg)

```mermaid
flowchart TD
    D[(规范全市场数据)] -->|启动时预加载| E[BacktestEngine]
    E --> B[TradingBus（每 Agent）]
    B --> T[掩码工具]
    B --> V[PortfolioView]
    B --> X[Python 沙箱]
    T --> A[Agent 循环]
    V --> A
    X --> A
    A -->|place_order| B
    E --> C[轨迹采集器]
    C --> R[回放 / 轨迹导出 / 报告]
```

## 不可妥协的不变量

### 运行期零 I/O

引擎在第一个交易日之前预加载所需的全部行情切片。Agent 的工具调用只做内存查询，绝不回源拉取供应商数据，也不直接读取规范数据集。

### 严格的历史可见性

日线使用 `date < current_date`；基本面使用 `pub_date <= current_date`；5 分钟线截断到当前阶段与子窗口；面向 Agent 的绝对日期一律变为相对偏移。

### 唯一下单路径

`TradingBus.place_order()` 统一施加整手、停牌、现金、持仓、涨跌停、费用与可见价格校验。不存在供 Agent、委员会或沙箱绕行的第二条快速通道。

### 环境托管账户

账户由环境所有。Agent 只获得只读视图，只能通过校验过的订单改变状态。分红、送转与每日净值是确定性的引擎操作。

## 回放契约

每条记录的 LLM 请求都有规范的 SHA-256 指纹。回放会拒绝被改动的请求与耗尽的盒带，也绝不回退到联网模型——这让回归失败显式暴露，而不是悄无声息地变得不确定。

---

<!-- source: docs/comparison.md -->

# 与相邻项目的对比

TraderHarness 是一套环境与证据基础设施。它可以承载不同的 Agent 架构，但不规定它们的投资方法论。

| 项目 | 主要职责 | 原生决策单元 | 集成后还需要什么 |
|---|---|---|---|
| **TraderHarness** | 历史有效的市场、执行、账户、评估、回放与训练轨迹 | 自主 Agent、隔离对比或单执行者委员会 | 一个 Agent 人设或外部框架 |
| **TradingAgents** | 多角色分析师、辩论、风控与交易员工作流 | 规定的角色图 | 可用于基准测试的严格市场模拟器与下单契约 |
| **StockBench** | 标准化的股票推理基准任务 | 基准任务/预测 | 支持自主工具调用的持久账户环境 |
| **Qlib** | 量化数据、模型、实验与策略研究 | ML 模型或代码策略 | LLM 原生的工具循环与抗污染语言出口 |
| **Backtrader / vn.py** | 策略执行与交易基础设施 | 代码策略 | 自主 LLM 研究循环、掩码与轨迹契约 |

## 独立 Agent 与委员会的区别

`traderharness compare` 是一场赛跑：每个 Agent 拥有自己的现金、持仓、记忆与账户。所有 Agent 共享同一市场时钟，各自独立计分。

委员会则是一个选手：只读顾问可以并发研究，但只有 Trader 这一个角色持有下单工具。这保证了一条可问责的动作路径和一个账户。详见[多角色委员会](design/multi-role-agent.md)。

![跨回测权益曲线叠加与关键指标对比](assets/run-compare.png)

*跨回测对比：把多次已完成回测的权益曲线叠加在一起，横向比较累计收益、夏普、最大回撤、胜率与成交次数。*

## 接入你自己的框架

外部 LangGraph、TradingAgents 或自定义编排器应通过公开的 Agent 协议返回最终决策。行情读取与下单仍然经过 `TradingBus`，因此框架天然继承同样的时点掩码、实体/日期匿名化、盘中渐进可见性与撮合规则。

---

<!-- source: docs/design/multi-role-agent.md -->

# 多角色 Agent 适配器

## 目标

在不改变 TraderHarness 的市场、账户、撮合、掩码与回放语义的前提下，支持 TradingAgents 风格的委员会。委员会是被评估的一个 Agent、一个账户。专家角色只提供建议；唯一执行者才能调用
`place_order`。

这与 `traderharness compare` 不同：后者中独立 Agent 各自持有账户并相互排名。

## 模型

```text
BacktestEngine（共享不可变市场快照）
  └─ CommitteeAgent（一个 Portfolio + 一个 TradingBus）
       ├─ 基本面顾问 ───────┐
       ├─ 技术面顾问 ───────┼─> 阶段备忘录
       ├─ 新闻顾问 ─────────┤
       ├─ 多头研究员 ───────┤
       ├─ 空头研究员 ───────┘
       └─ trader/执行者 -> 现有 AgentLoop -> TradingBus.place_order()
```

多个独立委员会之间仍可由引擎并行：

```text
委员会 A + 账户 A ────┐
委员会 B + 账户 B ────┼─ 每个交易日 asyncio.gather
单 Agent + 账户 C ────┘
```

## 不变量

1. 顾问只收到已经掩码的 Agent 可见消息。
2. 顾问没有下单工具。只读工具访问是后续扩展。
3. 执行者使用现有 `ToolRegistry`；`TradingBus.place_order()` 仍是唯一撮合路径。
4. 委员会调用对回放是确定的：角色、阶段、提示词、响应、模型与顺序都是轨迹记录。
5. 一个运行级的 `EntityMasker` 由所有顾问与执行者共享。
6. 顾问失败在备忘录与轨迹中显式可见；不做静默兜底。

## 扩展面

```python
class Advisor(Protocol):
    role: str
    async def advise(self, messages: list[dict], phase: str) -> str: ...

class CommitteeCoordinator:
    async def build_memo(
        self,
        messages: list[dict],
        phase: str,
        sub_window: str | None,
    ) -> CommitteeMemo: ...
```

`AgentLoop._run_phase()` 在每个 `(day, phase, sub_window)` 的首次执行者调用前请求一份备忘录。顾问通过
`asyncio.gather` 并发执行；产出作为带标签的系统消息注入。执行者可以接受或否决每一条建议。

## TradingAgents 适配器

适配器把外部图节点映射为 `Advisor` 实现：

- 市场/新闻/基本面分析师 -> 专家顾问
- 多/空研究员 -> 对抗顾问
- 研究经理/风险经理 -> 综合顾问
- Trader -> TraderHarness 执行者

外部工具与账户对象不会被引入，取而代之的是 TraderHarness 的掩码观测与单一账户/下单路径。这样既保留外部推理拓扑，又保证回测公平性。

## 配置

加载器（`PromptAgent`）通过顶层 `advisors:` 列表识别委员会——不存在嵌套的 `committee:`
或 `executor:` 块。`id`、`name` 与执行者自己的 `model`/`persona` 都在顶层，与单 Agent 卡片完全一致：

```yaml
id: tradingagents-reference
name: TradingAgents Reference Committee
model: deepseek-chat
persona: ...
advisors:
  - role: fundamentals
    model: deepseek-chat
    prompt: ...
  - role: technical
    model: deepseek-chat
    prompt: ...
  - role: bull
    model: deepseek-chat
    prompt: ...
  - role: bear
    model: deepseek-chat
    prompt: ...
```

完整可加载的参考委员会见
[`examples/tradingagents_committee.yaml`](https://github.com/HephaestLab/TraderHarness/blob/main/examples/tradingagents_committee.yaml)。

## 验收标准

- 单元测试证明顾问永远不会拿到 `place_order`。
- 单元测试证明所有顾问被并发调度。
- 集成测试证明恰好只有一个执行者能下单。
- 回放能复现同样的备忘录与执行者动作序列。
- 真实一日、三日与一个月运行通过泄漏审计。
- `compare` 能在相同数据、现金、掩码种子与基准下，把委员会与普通 Agent 一起排名。

## 暂缓项

- 按顾问划分的只读工具预算。
- 任意环形图与 Agent 间消息总线。
- 多执行者共享账户（有意排除——它会让订单归属与回放变得含糊）。

---

<!-- source: docs/training-data.md -->

---
description: TraderHarness 全保真轨迹采集与轨迹导出：完整消息、工具 schema、推理内容逐次落盘，导出 OpenAI 风格 SFT JSONL。
---

# 全保真轨迹与轨迹导出

TraderHarness 可以持久化每一次执行者 LLM 调用的完整掩码请求/响应对。它的用途是可复现研究与下游监督微调（SFT），并不代表每一条生成的决策都是高质量训练目标。

![逐笔复盘：K 线上下文、下单理由与执行证据](assets/trade-review.png)

*每一次决策都可回放审计：成交时 K 线、已记录的下单理由、工具调用参数与执行结果完整留档。*

## 采集轨迹

开启实体掩码运行回测：

```bash
traderharness run \
  --agent trend-breakout \
  --start 2024-03-04 \
  --end 2024-03-29 \
  --mask-entities
```

每个 `llm_exchange` 轨迹步骤包含：

- 发给执行者的完整消息列表；
- 该次调用可用的完整工具 schema；
- assistant 内容与可选的推理内容；
- 完整的工具调用与参数；
- 阶段与子窗口元数据。

兼容性的 `assistant` 与 `tool_call` 步骤也会保留。新生成的结果中 assistant 文本不再截断。

## 导出 OpenAI 风格 JSONL

```bash
traderharness export sft \
  ~/.traderharness/results/<run>_result.json \
  --output ./training.jsonl
```

每次 LLM 调用输出一行：

```json
{
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "...", "tool_calls": []}
  ],
  "tools": [],
  "metadata": {
    "agent_id": "trend-breakout",
    "phase": "pre_market",
    "sub_window": null,
    "day_index": 1,
    "call_index": 1
  }
}
```

绝对交易日期不会进入导出元数据；Agent 可见日期保持相对形式（`D+0`、`D-1` 等）。

## 安全闸口

默认情况下，导出会：

1. 拒绝未开启实体掩码的运行；
2. 拒绝缺少全保真 `llm_exchange` 记录的旧轨迹；
3. 对输出运行实体/日期泄漏检测；
4. 只要仍有检出就以非零码退出。

`--allow-unmasked` 是面向私有研究的显式逃生门，这类输出不得作为抗污染训练数据发布。

## 筛选仍然必要

全保真意味着错误决策与好决策都会被保留。训练前请按结果、回撤、规则合规、工具错误与人工复核过滤轨迹，并确认所选模型供应商的条款允许将生成的推理与回复用于训练。

---

<!-- source: docs/data.md -->

# 数据与许可

规范 A 股发布版包含五年全市场日线与 5 分钟线，以及公告、政策新闻、基本面、估值、分红和沪深 300 基准。

## 完整性

`traderharness data download --full` 会按发布清单逐项校验后才原子替换本地数据集；`traderharness data update` 使用水位线、确定性去重与原子写入。

仓库自带的数据医生（data doctor）检查：

- 必需 schema 与日期范围
- 自然键重复
- 5 分钟线年度覆盖率
- 过期标的与数据集对齐
- 非 A 股公告代码非法值
- 元数据一致性

v1.0 规范构建包含 284,219,844 条去重后的 5 分钟记录。发布审计中，活跃日线股票池的年度标的覆盖率达到 100%，最终 5 分钟水位线处无滞后标的，验证样本中自然键零重复。

## 公开发布策略

公开新闻表只保留模板化标题，移除有授权限制的正文。公司模板只在运行时解析为中性身份。这在保护评测完整性的同时，让源数据集依然可用于时点过滤。

## 存储结构

```text
~/.traderharness/dataset/
├── daily.parquet
├── 5min_clean/
├── announcements.parquet
├── news_cls.parquet
├── fundamentals.parquet
├── valuation.parquet
├── dividends.parquet
├── index_300.parquet
└── metadata.json
```

行情数据许可因供应商与司法辖区而异。再分发或商用部署前请核实上游条款。

---

<!-- source: docs/api.md -->

# CLI 与本地 API 参考

## 核心 CLI

```text
traderharness run       运行单个 Agent
traderharness compare   在同一市场时钟下隔离运行多个 Agent
traderharness demo      免密回放内置的掩码运行
traderharness ui        启动本地 FastAPI + React 控制台
traderharness audit     扫描工件中的实体与日历泄漏
traderharness export    把轨迹转换为 SFT JSONL
traderharness data      下载、更新与检查数据集
```

各命令的具体参数以 `traderharness <command> --help` 为准。

## Agent 协议

自定义 Agent 实现 `traderharness.agents.protocol` 中的公开协议，分别在盘前、开盘窗口与尾盘窗口收到环境控制的上下文。只读顾问可以组合在单一执行者之后，详见[多角色委员会](design/multi-role-agent.md)。

## 本地 HTTP API

`traderharness ui` 提供：

- `GET /api/status` — 数据集、供应商与本地安全状态；
- `GET/POST /api/agents` — Agent 卡片集合；
- `GET/PUT/DELETE /api/agents/{id}` — 单张 Agent 卡片；
- `POST /api/runs` — 启动回测；
- `GET/DELETE /api/runs/{id}` — 查看或取消运行；
- `WS /api/runs/{id}/events` — 可重连的序号化事件日志；
- `GET /api/results` — 已落盘结果摘要；
- `GET /api/results/{file}` — 完整工件；
- `GET /api/results/{file}/analysis` — 归一化的 UI 研究档案；
- `POST /api/demo` — 启动内置回放；
- `GET /api/health` — 进程健康检查。

HTTP API 是本地工具，不是带鉴权的公共服务。请保持默认的 localhost 绑定。

---

<!-- source: docs/extensions.md -->

# 扩展 TraderHarness

TraderHarness 的设计允许在不削弱核心不变量的前提下扩展：回测期零 I/O、唯一下单路径、严格时点可见性、确定性执行、环境托管账户（见[核心架构](architecture.md)与
[`AGENTS.md`](https://github.com/HephaestLab/TraderHarness/blob/main/AGENTS.md)）。本页是几个常见扩展点的简要契约。大型改动前请先开 issue；流程见
[`CONTRIBUTING.md`](https://github.com/HephaestLab/TraderHarness/blob/main/CONTRIBUTING.md)。

## 数据源适配器

新市场，或现有 A 股数据集的新供应商，都应产出符合[数据与许可](data.md)中规范 schema 的数据。

契约：

- 在 `traderharness/data/providers/` 下实现 provider；不得绕过 `traderharness/data/datasets.py`，也不得直接写入正在运行的回测的内存表。
- 保持时点完整性：每条记录需要稳定的自然键；非价格类记录还需要可供掩码层过滤的发布时间戳（`pub_date` 式列）。
- 为新表添加或扩展数据医生检查（`scripts/data_doctor.py`）：必需列、日期覆盖与重复键不变量。
- 在 `tests/fixtures/` 提供小体量真实数据夹具与加载测试；验收验证不得用合成价格顶替（见真实数据工作区规则）。

## 工具

面向 Agent 的工具位于 `traderharness/tools/`，通过 `traderharness/tools/registry.py` 注册。

契约：

- 工具处理器接收本次运行的掩码上下文；它绝不能越过上下文读取规范数据集或其他 Agent 的状态。
- 每条失败路径都返回结构化、可行动的错误，区分"代码不存在""该日期前无数据""停牌""参数被忽略"——笼统异常不可接受。
- 新工具需要 JSON-schema 参数校验、每种失败模式一个单元测试；若内置 Agent 应使用它，还要加入相应 Agent 卡片的 `allowed_tools`。
- 工具不得新增第二条下单路径。交易始终走 `TradingBus.place_order()`。

## 沙箱后端

`execute_code` 工具与 `traderharness_api` 模块是 Agent 对掩码数据运行任意分析代码的受认可方式（见[防数据泄漏](contamination.md#egress-coverage)）。

契约：

- 沙箱后端必须执行同样的路径防护，阻断直接读取数据集（`sandbox/guard.py`），并使用同样的 wall-clock 超时。
- `traderharness_api` 的新增能力必须经由现有掩码访问器解析；不得添加返回未掩码 DataFrame 或真实实体代码的代码路径。
- 任何沙箱后端都不得启动嵌套回测，也不得回调引擎的下单路径。
- 沙箱隔离的演进方向见[路线图](roadmap.md#hardened-sandbox)；缩小可信面的贡献尤其受欢迎。

## 评估指标

绩效与行为指标位于 `traderharness/metrics/`。

契约：

- 新指标是对已完成运行的每日净值、成交与决策的纯函数——不得要求重跑回测或调用供应商 API。
- 在 docstring 中写清公式与边界情况（空成交历史、单交易日、缺基准数据），并添加报告/JSON 导出测试。
- Agent 间比较类指标（如排名）属于 `traderharness/metrics/comparison.py`，不属于单 Agent 报告。

## 券商适配器

v1.0 没有实盘券商适配器，见[路线图](roadmap.md#live-broker-adapter)。欢迎以 issue 形式讨论设计与原型，但券商集成不应接进回测用
`TradingBus`——历史模拟与实盘下单是不同的信任边界，必须保持分离。

## 前端（webui）

研究控制台是 `webui/` 下的纯本地 React 应用。

契约：

- 新视图从现有 REST/WebSocket API（`traderharness/server/app.py`）取数；不得在客户端用原始字段重新推导掩码数据。
- 中文文案统一走 `webui/src/locale.ts`，不要在组件里硬编码字面量。
- 新组件配 Vitest 单元测试；新页面或新流程配 `webui/tests/e2e` 下的 Playwright 场景（若应出现在 README GIF 中，同步扩展 `webui/scripts/capture-demo.mjs`）。

## 提交 PR 之前

1. 先写一个能证明新契约的失败测试。
2. 实现时不得削弱
   [`AGENTS.md`](https://github.com/HephaestLab/TraderHarness/blob/main/AGENTS.md#non-negotiable-invariants) 中任何不变量。
3. 跑聚焦测试套件，再跑全量（`pytest tests/ --no-header -q`、`ruff check`；涉及引擎/掩码/工具/数据/沙箱的改动还需一次真实回放或回测并检查轨迹）。
4. 如实声明做过哪些真实数据运行、哪些没做。

---

<!-- source: docs/roadmap.md -->

# 路线图

本页记录 TraderHarness 已经交付了什么、计划做什么，方便集成方做"自建还是等待"的决策，而不必从 issue 列表里猜。以下内容均不构成日期承诺。

## ✅ v1.0 已交付

- 五年全市场 A 股数据集（日线、5 分钟、公告、政策新闻、基本面、估值、分红、沪深 300），带原子增量更新与完整性检查。
- 预加载后回测期零行情 I/O；`TradingBus.place_order()` 唯一下单路径。
- 日线、盘中、新闻、公告、基本面与沙箱出口的严格时点掩码。
- 确定性日历（`D+0`、`D-1`……）与保留板块语义的公司实体匿名化。
- 盘前 / 开盘窗口 / 尾盘窗口三阶段 Agent 循环，盘中渐进可见。
- 独立多 Agent 对比（`traderharness compare`），以及单执行者多角色委员会参考实现（顾问只读；唯一 Trader 持有下单工具）。
- 全保真 LLM 交互轨迹、失败即报错的指纹回放、OpenAI 风格轨迹导出。
- 序列化工件泄漏审计（`traderharness audit`）。
- 本地 FastAPI + React 研究控制台、非特权 Docker 镜像、PyPI 打包与 CI。

逐项发布说明见 [`CHANGELOG.md`](https://github.com/HephaestLab/TraderHarness/blob/main/CHANGELOG.md)。

## 🚧 下一步：模拟实盘（paper trading）

一种模拟的实时前推模式：复用现有引擎、掩码与工具契约，但数据源从全量预加载改为流式推送，从而无需改动代码就能对一张 Agent 卡片做面向未来的评估。该功能在设计中，**目前不可用**，仓库中任何内容都不应被解读为相反 claim。

从回测引擎继承的约束：

- 同样的 `TradingBus.place_order()` 路径与风控检查；
- 任何面向 Agent 的出口都遵守同样的掩码契约；
- 不存在让沙箱或工具看到模拟时钟之后数据的捷径。

## 📋 规划：实盘券商适配器 {#live-broker-adapter}

一个适配器边界，让模拟实盘或研究 Agent 可以对接真实券商 API。它依赖模拟实盘先落地，并需要与项目整体安全姿态相匹配的凭据与下单授权威胁模型（见
[`SECURITY.md`](https://github.com/HephaestLab/TraderHarness/blob/main/SECURITY.md)）。目前没有任何券商集成。

## 📋 规划：沙箱加固 {#hardened-sandbox}

当前 Python 沙箱（`execute_code` + `traderharness_api`）的定位是防止单一可信研究者意外读取规范数据集或启动嵌套回测——见
[本地服务器安全](https://github.com/HephaestLab/TraderHarness/blob/main/AGENTS.md#local-server-security)。未来版本计划的加固：

- 适合运行不可信或第三方 Agent 卡片的资源与 wall-clock 隔离；
- 更窄的默认 `traderharness_api` 面，按工具做能力域划分；
- 与现有轨迹记录并列的结构化沙箱审计日志。

## ❌ 非目标

- **公开排行榜或托管多租户服务。** TraderHarness 是本地研究基础设施；见[本地服务器安全](https://github.com/HephaestLab/TraderHarness/blob/main/AGENTS.md#local-server-security)。
- **市场冲击建模。** 历史成交使用不复权价格，不模拟 Agent 自己的订单对市场的推动。
- **规定交易方法论。** 环境保持 Agent 架构中立；见[项目对比](comparison.md)。
- **Agent 之间实时互动、互相影响成交。** 每个 Agent（或委员会）都在自己的隔离账户中对同一历史时钟交易。

## 如何参与

上述路线图条目是最可能被快速接受的贡献方向。贡献契约见[扩展开发](extensions.md)，流程见
[`CONTRIBUTING.md`](https://github.com/HephaestLab/TraderHarness/blob/main/CONTRIBUTING.md)。

---

<!-- source: docs/faq.md -->

# 常见问题

## 为什么要在模型可能见过的历史上评测新 LLM？

知识截止日不是信息屏障。TraderHarness 在每一个面向 Agent 的边界移除绝对日期与公司身份，盘中分钟线渐进揭示，并对序列化工件做词法泄漏审计。著名事件仍可能被语义推断出来，因此严谨的工作应报告掩码设置，并在合适时加入遮罩/未遮罩对照。

## 实体掩码会改变交易规则吗？

不会。真实代码在兼容的 A 股板块分组内打散。创业板或科创板的伪代码保留其历史板块的涨跌停行为。撮合始终使用内部解析还原后的真实标的。

## 完整数据集是合成的吗？

不是。验收测试与公开运行都使用历史全市场真实数据。免密演示是一段真实掩码运行的确定性回放，不用生成的价格顶替。

## `compare` 是共享账户的多 Agent 吗？

不是。`compare` 给每个 Agent 一个隔离账户。想要 TradingAgents 式的结构，请用委员会：顾问只读，唯一 Trader 管理一个账户。

## 回放会偷偷调用模型供应商吗？

不会。请求带指纹。指纹不匹配或盒带耗尽都会直接失败（fail-closed）。

## 控制台能暴露成托管服务吗？

以当前形态不安全。Agent 编写的 Python 在本地 HTTP 服务后可执行。沙箱防护保护的是回测数据边界，而不是敌意多租户部署。请保持 localhost 绑定。

## 回测盈利等于可上线策略吗？

不等于。TraderHarness 不建模市场冲击，历史表现不保证未来收益。它是研究基础设施，不是投资建议，也不是券商。

## README 展示用哪些 Agent 和模型？

四 Agent 展示对比内置的 `trend-breakout`、`quality-compounder`、`event-hawk`、`quant-researcher` 四张卡片，区间为 2024-03-04 至 2024-03-29，开启实体掩码，执行模型为 thinking 模式的
`deepseek-v4-pro`。绩效数字只在该次运行真实完成并通过 `traderharness audit` 后发布——README 不会把估算或占位数字当作真实结果发布。

## `traderharness demo` 等于模拟实盘吗？

不等于。`demo` 回放一段已录制的掩码历史运行，全程无网络调用。模拟实盘——面向流式行情的前推模拟模式——尚不存在，见[路线图](roadmap.md)。
