TradeCat Public

Sponsors / 赞助商

Sponsor	Link
CA（交易猫 tradecat 社区）	`0x8a99b8d53eff6bc331af529af74ad267f3167777`
OPENAI	OpenAI

TradeCat Public 是一个面向 Agent/Hermes 的自主纸面交易运行时。公开在线表格只作为信号源；Agent/Hermes 根据仓库内自包含的 Binance skill/API 快照和公开只读工具补齐行情上下文与交易 thesis；TradeCat 负责 schema 审计、信号对齐、paper/watch 执行、账本、风控拒绝、报告和可复现审计。

本仓库的核心目标是：Agent 交易员同步在线表格作为信号源的自主纸面交易系统。旧的本地交互式 TUI、安装器、watchdog、缓存浏览器和 project/ 根目录已经退役。

仓库身份以 tradecat-public 为准；GitHub remote 为 tukuaiai/tradecat-public。本仓库不代表旧私有 TradeCat 运行态，也不包含实盘 executor。

功能特性

读取公开在线表格 signal_flow 和 anomaly_panel，不依赖私有 TradeCat 服务端。
使用 contracts/ 中的 JSON Schema 约束在线表格 source payload、Agent market context、trade thesis、paper report、audit journal 等 I/O。
保留 Binance public-readonly skill/API 快照与 provenance，供 Agent/Hermes 研究行情上下文。
执行本地 paper/watch，不读取 Binance key，不签名，不访问账户/订单私有端点，不真实下单。
缺少 Agent 明确 sizing、leverage、stop loss、take profit 或 max holding plan 时 fail-closed。
默认不常驻运行；paper loop 和 Web monitor 都必须由操作员显式启动。
运行态隔离在 ignored .runtime/，可生成 paper ledger、cycle archive、SQLite audit journal、health/daily/replay/alert 报告。
内嵌 skills/tradecat-public/，Agent/Hermes 可按 manifest 和 Skill references 使用本仓库。

安全边界

只允许 public/read-only market data 与本地 paper/watch。
禁止读取 Binance key/secret、.env、listen key、账户、余额、真实持仓或订单。
禁止签名请求，禁止调用下单、撤单、改杠杆、改保证金等私有端点。
禁止真实下单；实盘 executor 必须是未来独立私有仓库。
本地运行态只能写入 ignored .runtime/、.tradecat/、.venv/、.tools/、.hermes/。
交易 sizing、leverage、止损、止盈、持仓时长必须来自 Agent thesis 或 ignored runtime paper autonomy profile；TradeCat 不写入真实交易参数。

快速开始

环境要求来自 pyproject.toml 和 CI：

Python >=3.12；CI 覆盖 Python 3.12 和 3.13。
pip。
可选：make、Docker 或本地 gitleaks，用于部分开发入口或安全扫描加速。

安装开发依赖：

python3 -m pip install -c constraints.txt -e ".[dev]"

最短只读检查：

python3 scripts/request.py --datasets --format json
python3 scripts/request.py signal_flow --format json --limit 5
python3 scripts/request.py anomaly_panel --format json --limit 0
bash scripts/run-tradecat.sh soft-layer --json
bash scripts/start-auto-paper.sh status --json

如需代理读取公开在线表格，使用标准环境变量：

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

目录结构

tradecat-public/
|-- README.md
|-- AGENTS.md
|-- CONTRIBUTING.md
|-- CHANGELOG.md
|-- LICENSE
|-- pyproject.toml
|-- constraints.txt
|-- Makefile
|-- .env.example
|-- .github/
|   |-- CODEOWNERS
|   |-- dependabot.yml
|   |-- pull_request_template.md
|   `-- workflows/ci.yml
|-- contracts/                 # JSON Schema 机器契约
|-- docs/                      # 架构、配置、部署、发布说明
|-- resources/
|   |-- agent_market_context/  # Binance skill/API 只读快照与 provenance
|   `-- agent_soft_layer/      # Agent 角色与软策略资源
|-- scripts/                   # request、paper runtime、验证、监控入口
|-- src/
|   |-- tradecat_sources/      # 在线表格公开信号源读取与 dataset contract
|   `-- tradecat_auto/         # Agent context、paper/watch、ledger、风控、报告
|-- tests/
`-- skills/tradecat-public/    # Hermes/Codex Skill 包

skills/tradecat-public/agents/manifest.json 是 Agent/Hermes 的唯一机器主契约。文档只解释它，不复制第二份机器契约。

project/ 已退役；tasks/ 是本地任务拆解/草稿目录，和 .runtime/ 一样不进入公开 GitHub 仓库。

配置说明

配置示例见 .env.example。允许的本地配置：

HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=127.0.0.1,localhost
TRADECAT_AUTO_PAPER_RUNTIME_DIR=.runtime/auto-paper
TRADECAT_AUTO_PAPER_CYCLE_TIMEOUT_SECONDS=6000
TRADECAT_AUTO_PAPER_FEE_BPS=4
TRADECAT_AUTO_PAPER_SLIPPAGE_BPS=0
TRADECAT_AUTO_PAPER_AGENT_TRADE_THESIS_PATH=
TRADECAT_AUTO_PAPER_AUTONOMY_ENABLED=0
TRADECAT_AUTO_PAPER_AUTONOMY_PROFILE_PATH=
TRADECAT_AUTO_PAPER_AUTONOMY_MARGIN_USDT=10
TRADECAT_AUTO_PAPER_AUTONOMY_LEVERAGE=1
TRADECAT_AUTO_PAPER_AUTONOMY_STOP_LOSS_BPS=150
TRADECAT_AUTO_PAPER_AUTONOMY_TAKE_PROFIT_BPS=300
TRADECAT_AUTO_PAPER_AUTONOMY_MAX_HOLDING_MINUTES=90
TRADECAT_AUTO_PAPER_AUTONOMY_DIRECTION_POLICY=sheet_signal_or_taker_flow
TRADECAT_AUTO_PAPER_MONITOR_HOST=127.0.0.1
TRADECAT_AUTO_PAPER_MONITOR_PORT=8765

默认本地 Web 监控地址来自 scripts/serve-auto-paper-monitor.py：http://127.0.0.1:8765/。

start-auto-paper.sh 默认是手动运行 + 外部 Agent thesis 模式，不会自动生成 .runtime/auto-paper/paper_autonomy_profile.json，缺少明确 sizing/exits 时继续 agent_sizing_required fail-closed。只有显式设置 TRADECAT_AUTO_PAPER_AUTONOMY_ENABLED=1 或传入 TRADECAT_AUTO_PAPER_AUTONOMY_PROFILE_PATH 时，才会使用 paper-only runtime profile。

start-auto-paper.sh 也会默认维护 ignored .runtime/auto-paper/strategy_state.json。该状态由 strategy-review 基于本地 paper ledger / cycle archive 生成，用于把亏损 symbol、亏损信号类型、亏损方向、最大持仓数和单币并发上限反馈到下一轮 paper 风控。这是本地 paper/watch 自我迭代过滤，不读取 Binance 凭证，也不会触发真实订单。

纸面成本模型默认使用 Binance USDⓈ-M 官方 commission-rate 文档示例中的 taker 费率 4 bps 作为 public fallback；实际开仓滑点优先用公开 /fapi/v1/depth 盘口按 Agent notional 估算成交均价。精确账户/VIP/symbol 费率需要签名 USER_DATA，不属于本公开仓库边界。

TODO: GitHub 仓库 Settings 中的 main 分支保护、必需 review 和必需 status checks 无法从仓库文件确认；需要仓库管理员在 GitHub UI/API 中核查。

Agent 纸面交易流

signal_flow / anomaly_panel
-> Agent/Hermes 读取 Binance public/read-only K线、盘口、资金费率、OI 等上下文
-> agent_market_context.v1 + agent_trade_thesis.v1
-> context-audit
-> run-context / run-loop
-> paper risk gate
-> paper ledger + cycle archive + audit journal
-> health / daily / alert / replay report

常用 paper/watch 命令：

bash scripts/binance-public-bundle.sh --symbols BTCUSDT,ETHUSDT --json
bash scripts/run-tradecat.sh agent-market-context --symbol BTCUSDT --json
bash scripts/run-tradecat.sh context-audit --input context.json --json
bash scripts/run-tradecat.sh run-context --input context.json --mode paper --json
bash scripts/run-tradecat.sh run-once --agent-trade-thesis-path thesis.json --mode paper --json
bash scripts/run-tradecat.sh paper-report --json
bash scripts/run-tradecat.sh strategy-review --ledger-path .runtime/auto-paper/paper_ledger.json --archive-path .runtime/auto-paper/cycles.jsonl --json
bash scripts/run-tradecat.sh latest-cycle --json
bash scripts/run-tradecat.sh latest-decision --json
bash scripts/run-tradecat.sh audit-journal --json
bash scripts/run-tradecat.sh health-report --json
bash scripts/run-tradecat.sh daily-report --json

缺少 Agent sizing/exits 时，TradeCat 必须 fail-closed，并返回结构化 error_code，不得自动填金额、杠杆、止损或止盈。

常驻 paper/watch

默认不要常驻运行。启动 loop 会持续读取在线表格、public Binance 数据和本地 Agent/thesis 上下文，可能带来网络/API/token 成本；启动前先确认预算、代理和运行目的。

bash scripts/start-auto-paper.sh ops-check --json
bash scripts/start-auto-paper.sh start --json
bash scripts/start-auto-paper.sh status --json
bash scripts/start-auto-paper.sh stop --json

长期常驻用 user systemd service 作为唯一生命周期 owner：

bash scripts/start-auto-paper.sh systemd-install --json
systemctl --user status tradecat-auto-paper.service

systemd-install 会禁用旧版 tradecat-auto-paper.timer，停止已有手动 _run，再启用长驻 tradecat-auto-paper.service；不要让 timer _cycle 和手动 _run 同时写 .runtime/auto-paper/。

本地 Web 监控页面：

python3 scripts/serve-auto-paper-monitor.py --host 127.0.0.1 --port 8765

页面只读展示本地 paper/watch、审计日志、账本、输入信号、Agent decision text 和依赖链健康，不会启动 auto-paper loop，不接触真实账户。

常用命令

# 安装
python3 -m pip install -c constraints.txt -e ".[dev]"
make install-dev

# 只读数据源
python3 scripts/request.py --datasets --format json
python3 scripts/request.py signal_flow --format json --limit 5
python3 scripts/request.py anomaly_panel --format json --limit 0
bash scripts/binance-public-snapshot.sh --symbols BTCUSDT,ETHUSDT --json

# 测试、lint、format
PYTHONPATH=src python3 -m pytest -q
PYTHONPATH=src ruff check src tests
PYTHONPATH=src ruff format --check src tests scripts

# 完整本地门禁
bash scripts/agent-smoke.sh
bash scripts/verify.sh
bash scripts/validate-skill.sh --strict
bash scripts/security-scan.sh
bash scripts/supply-chain-audit.sh
python3 scripts/validate_dependency_policy.py
python3 scripts/validate_testing_ci_contract.py
python3 scripts/ops-audit.py --json
git diff --check

# 构建 wheel，来源于 CI
python3 -m pip wheel . --no-deps -w /tmp/tradecat-wheel

Makefile 还提供 make test、make lint、make format、make format-check、make test-ci-contract、make security、make supply-chain、make agent-smoke、make verify、make ops-audit、make paper-status、make paper-start、make paper-stop、make monitor。

CI/CD

CI 文件为 .github/workflows/ci.yml，触发条件包括 push、pull_request、workflow_dispatch 和每日定时任务。CI 执行：

最小权限 permissions: contents: read、同 ref 并发取消、job timeout、checkout 不持久化凭证。
Skill strict validation。
secret scan。
安装 python -m pip install -c constraints.txt -e ".[dev]"。
public boundary guard。
dependency policy。
testing/CI contract validation，机器清单位于 resources/test_ci_matrix.json，设计说明见 docs/testing-ci-strategy.md。
ruff check src tests。
ruff format --check src tests scripts。
PYTHONPATH=src pytest -q。
data contract validators。
supply-chain audit。
shell/Python syntax check。
wheel package data check。
agent readiness smoke。

CI 只证明代码、契约、测试和安全门禁通过；它不证明本机 auto-paper loop 正在运行。

本仓库没有 Dockerfile、docker-compose、K8s manifest 或 Helm chart；当前部署形态只有本地 public-readonly + paper/watch。TODO: 如未来新增容器或平台部署，需要同步更新 docs/deployment.md、README 和 AGENTS。

Troubleshooting / FAQ

ModuleNotFoundError: tradecat_auto：先安装 python3 -m pip install -c constraints.txt -e ".[dev]"，或运行命令时设置 PYTHONPATH=src。
ruff 或 pytest 不存在：运行 bash scripts/bootstrap-dev.sh 或安装开发依赖。
在线表格读取失败或 HTTP 404：先运行 python3 scripts/request.py --datasets --format json 确认 dataset；如网络受限，设置 HTTP_PROXY / HTTPS_PROXY。
paper_service_not_running：运行 bash scripts/start-auto-paper.sh status --json 查看状态，需要常驻时运行 bash scripts/start-auto-paper.sh start --json。
heartbeat_stale 但 pid 仍在：说明单轮 public-readonly/paper cycle 可能卡住；TRADECAT_AUTO_PAPER_CYCLE_TIMEOUT_SECONDS 会限制单轮最长时间，必要时运行 bash scripts/start-auto-paper.sh heal --json。
paper-report 显示 0 仓但服务在交易：默认账本应为 .runtime/auto-paper/paper_ledger.json；用 bash scripts/run-tradecat.sh latest-decision --json 和 bash scripts/run-tradecat.sh health-report --json 核对常驻服务事实源。
agent_sizing_required 在重启后出现：这是默认 fail-closed 手动模式；需要 Agent/Hermes 显式写入 thesis，或明确设置 TRADECAT_AUTO_PAPER_AUTONOMY_ENABLED=1 / TRADECAT_AUTO_PAPER_AUTONOMY_PROFILE_PATH。
想审计是否有旧服务、进程、端口或 cron 残留：运行 python3 scripts/ops-audit.py --json。
想完全改 paper 自治参数：设置 TRADECAT_AUTO_PAPER_AUTONOMY_*，并显式打开 TRADECAT_AUTO_PAPER_AUTONOMY_ENABLED=1，或显式传入 TRADECAT_AUTO_PAPER_AGENT_TRADE_THESIS_PATH / TRADECAT_AUTO_PAPER_AUTONOMY_PROFILE_PATH。
监控端口冲突：使用 python3 scripts/serve-auto-paper-monitor.py --host 127.0.0.1 --port <free-port>。

贡献指南

贡献流程：CONTRIBUTING.md
变更记录：CHANGELOG.md
架构说明：docs/ARCHITECTURE.md
配置说明：docs/configuration.md
部署与运维：docs/deployment.md
运维 runbook：docs/operations-runbook.md
发布流程：docs/release.md

.github/pull_request_template.md、.github/CODEOWNERS 和 .github/dependabot.yml 提供 PR、review owner 与依赖更新入口。平台级分支保护需要在 GitHub 仓库设置中启用。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

TradeCat Public

Sponsors / 赞助商

功能特性

安全边界

快速开始

目录结构

配置说明

Agent 纸面交易流

常驻 paper/watch

常用命令

CI/CD

Troubleshooting / FAQ

贡献指南

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 88 Commits
.github		.github
contracts		contracts
docs		docs
resources		resources
scripts		scripts
skills/tradecat-public		skills/tradecat-public
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEBUG.archive.md		DEBUG.archive.md
DEBUG.md		DEBUG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
constraints.txt		constraints.txt
lessons.md		lessons.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

TradeCat Public

Sponsors / 赞助商

功能特性

安全边界

快速开始

目录结构

配置说明

Agent 纸面交易流

常驻 paper/watch

常用命令

CI/CD

Troubleshooting / FAQ

贡献指南

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages