tradecatlabs

tradecat-public

# TradeCat Public ## Sponsors / 赞助商 | Sponsor | Link | |---|---| | CA（交易猫 tradecat 社区） | [`0x8a99b8d53eff6bc331af529af74ad267f3167777`](https://dexscreener.com/bsc/0x8a99b8d53eff6bc331af529af74ad267f3167777) | | OPENAI | [OpenAI](https://openai.com/) | 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`，用于部分开发入口或安全扫描加速。 安装开发依赖： ```bash python3 -m pip install -c constraints.txt -e ".[dev]" ``` 最短只读检查： ```bash 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 ``` 如需代理读取公开在线表格，使用标准环境变量： ```bash export HTTPS_PROXY=http://127.0.0.1:7890 export HTTP_PROXY=http://127.0.0.1:7890 ``` ## 目录结构 ```text 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`。允许的本地配置： ```text 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 纸面交易流 ```text 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 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 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 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 监控页面： ```bash python3 scripts/serve-auto-paper-monitor.py --host 127.0.0.1 --port 8765 ``` 页面只读展示本地 paper/watch、审计日志、账本、输入信号、Agent decision text 和依赖链健康， 不会启动 auto-paper loop，不接触真实账户。 ## 常用命令 ```bash # 安装 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 仓库设置中启用。