## 游资复盘引擎 · 让每一次决策都变成系统的进化
*"散户靠感觉，高手靠系统。把你的感觉，变成可复盘、可验证、可进化的规则。"*
[](https://www.python.org/)
[](LICENSE)
[](tests/)
[](docs/safety.md)
[](docs/privacy.md)
[](docs/agent-loop.md)
[](docs/integrations.md)
[](docs/tradingagents-adapter.md)
[](https://alphatech.net.cn/)
只读 AI 复盘与规则进化 harness · 决策记录 · D1/D3 结果验证 · 本地 Markdown 记忆 · challenger -> champion 治理
[30 秒上手](#30-秒上手) · [5 秒体验闭环](#5-秒体验复盘闭环) · [核心理念](#核心理念系统--感觉) · [AI 助手接入](#给-ai-助手只读复盘协作) · [开源生态矩阵](#优秀开源项目集成矩阵) · [安全边界](#安全边界你的系统只属于你) · [CLI](#cli-commands)
`READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE`
[](https://alphatech.net.cn/)
### Jev 审查推理层与四轨金融评测基准
SmartMoney-Cub 原生支持 Jev（[TypeSafe 官方主页](https://typesafe.ai/) | [OpenRouter 托管主页](https://openrouter.ai/typesafe/jev)）作为可选的类型化语义判断层，提供 TypeSafe 原生直连与 OpenRouter 路由两种可插拔后端。Jev 仅用于回答结构化的 `noul`、`choice` 与 `score` 语义审查问题，所有数值运算、日期比较以及严格的时效边界门禁（`available_at <= decision_time`）始终由确定性 Python 代码执行与强制校验。
仓库内置 `finance-jev-v1` 离线评测基准套件，包含涵盖四大赛道（`trading-review`、`financial-filings`、`industry-events`、`macro-policy`）的 240 例冻结离线案例。在完成全赛道可回答性审计并彻底移除输入中的答案泄漏后，案例采用真实的证据叙述（交易执行日志、财报披露节选、行业电讯简报与央行公报原文）供模型进行结构化审方。在官方发布的参考运行产物（[assets/benchmark/run.json](assets/benchmark/run.json)）中，确定性规则基线实现了 **83.33%** 的综合准确率（95% Wilson 置信区间 [80.92%, 85.49%]）与 **0.7792** 的宏平均 F1（共 1,020 项评测问题）。TypeSafe Jev 在线评测系统（`typesafe_direct`，通过真实 API 评测，服务端解析为 `jev-1.13.0` 模型）实现了 **78.43%** 的综合准确率（95% Wilson 置信区间 [75.80%, 80.85%]）、**0.7319** 的宏平均 F1 以及 1034 ms 的 P50 延迟，并在概率校准上表现更优（ECE 为 0.1464 对比基线的 0.1667）。在财务财报赛道上，Jev 准确率达到 **77.00%**（F1: 0.6990）优于规则基线（73.33%），在行业事件赛道达到 **93.33%**（F1: 0.9215），在宏观政策赛道达到 **74.44%**（F1: 0.7148）。该指标如实反映在当前去泄漏冻结玩具案例集上的真实表现，不代表能泛化至真实实盘环境。OpenRouter 后端（`openrouter_jev`）因未配置密钥继续如实标注为 `not_run`。
### 30 秒极速上手
```bash
# 1. 安装核心库与开发依赖
pip install -e ".[dev]"
# 2. 环境健康检查与确定性安全声明验证
smcub doctor
# 3. 最短离线复盘体验闭环 (捕获决策并执行回放)
smcub capture-run --mode after-close --preset toy --sandbox --decision-time "2026-06-01T15:31:00+08:00"
smcub replay-evidence-pack tmp/sandbox/20260601/*-after-close
```
[English](README.md)
只读输入 → 核心控制平面（捕获 → 反未来函数 → 决策与风险契约 → 冻结证据）→ 延迟复盘（D1/D3 结果 → 确定性回放 → 评估与反方证据 → 记忆与案例库 → 挑战者规则 → 人工显式晋级门禁）→ 下一次计划。可选开源工具始终在可信核心外部，仅作为复盘证据加入。
对应文本与可维护 Mermaid 流程见 [docs/architecture.md](docs/architecture.md)。
---
游资和散户最大的区别是什么？不是信息差，不是资金量，而是系统。
高手每一次决策都有计划、有证据、有复盘、有规则迭代。普通人最容易掉进的坑，是复盘时翻聊天记录、翻交易软件、翻截图，折腾半天还是说不清当时为什么买、错在什么地方、下一次该怎么改。
`smartmoney-cub-harness` 是一个本地优先的 AI 复盘引擎。它帮你记录每一次决策的完整逻辑，追踪 D1/D3 的结果，把教训变成规则，把规则沉淀成系统。
它不是个股建议软件，不是自动交易系统，不是券商连接器，也不是财务建议系统。它是你的私人交易日志与复盘伙伴：对市场和执行只读，对你自己的日志可写。
更准确地说，`smartmoney-cub-harness` 是一个**本地优先、对市场与执行只读、不绑定任何 Agent 的交易日志与复盘 harness**：外部 Agent 或 CLI 调用方 → Run Envelope → 冻结的 Benchmark/Evidence Pack → 确定性回放 → 人工显式晋级门禁。它的核心**不内置 LLM**、**不连接券商**、**不自动交易**，控制平面完全离线运行；复盘助手是一个独立的、需要显式配置的入口，它只调用你自己配置的 Provider，并且只发送脱敏后的结构化字段。它不替用户选股、不运行后台自主交易 Agent、不自动修改核心规则。
```bash
smcub capture-run --mode after-close --preset toy --sandbox --decision-time "2026-06-01T15:31:00+08:00" --agent-name "toy-doc-agent-zh" --agent-version "1.0" --agent-interface "cli"
smcub validate-envelope tmp/sandbox/20260601/20260601_153100-after-close/run_envelope.json
smcub build-outcome tmp/sandbox/20260601/20260601_153100-after-close --horizon d1 --price-source smartmoney_cub_harness:data/sample_prices.json
smcub build-evidence-pack tmp/toy-evidence-pack --sample tmp/sandbox/20260601/20260601_153100-after-close --rule-candidate examples/toy_strategy/sample_rule_candidate.json --horizon d1
smcub replay-evidence-pack tmp/toy-evidence-pack
```
Run Envelope 的权限范围是**声明式、未经验证的策略记录**（`enforcement: declarative`、`verified: false`），不是子进程沙箱。CLI 的 `--sandbox` 只选择一次性的 `tmp/sandbox` 输出目录，并不隔离进程；不可信命令必须放在操作系统或容器沙箱中运行。`evidence_pack.sha256` 用于本地篡改检测，不是经过身份认证的数字签名；任何不一致只会进入 `pending_review` 或 `blocked`，绝不会自动晋级。
## 官方 API 网关
[alphatech.net.cn](https://alphatech.net.cn/) 是本项目自建的官方网关，提供 OpenAI 兼容的模型访问入口。若希望使用托管中转而不是自行配置上游，可把 Provider 指向它的端点：
```text
https://alphatech.net.cn/v1
```
该网关是可选的。核心 harness 完全离线只读运行，也可以指向任何你自己配置的 Provider；使用网关不授予交易权限，也不改变执行禁令。Provider 与自定义网关的设置见 [docs/review-agent.md](docs/review-agent.md)。
## 🧭 复盘工作台（1.0 · 本地优先）
工作台是三栏布局：左侧导航，中间业务页，右侧常驻复盘助手。导入券商交割文件或截图，
校对本地识别结果，然后让助手基于脱敏字段做复盘。
```bash
npx smartmoney-cub # 用户端不需要手工配置 Python
npx smartmoney-cub install --with-ocr # 识别截图与扫描 PDF 所需的本地 OCR
smcub workbench # 也可以直接用 Python 包启动
smcub skill install --target codex # 安装 Agent Skill
```
页面：总览（权益曲线、月历热力图、待复盘清单）、交易日志（表格 + 详情抽屉 + 成交版本历史）、
复盘日历、绩效分析（按标的／市场状态／星期／持有周期／标签归因，并显示样本量）、规则库、
数据导入、插件、设置（Provider、隐私与诊断）。
### 对话驱动的规则进化
复盘助手可以从已确认的证据里提出候选（challenger）规则，并且这条候选会和规则库页面读的是
同一个库：门禁缺口会被记录，同时在 workspace 数据库旁追加一条 `evolution_ledger.jsonl`
记录和一段可读的 `memory.md` 片段。
晋升是单独的一步，也是唯一能产生 champion 的写入：
```bash
smcub workspace rules
smcub workspace promote-rule RULE-1 --note "样本 24 笔，误报率 0.12，确认纳入"
```
那条确认说明就是门禁本身：说明为空或缺失时一律拒绝，且不写入任何东西——命令行与界面的
晋升接口行为一致。两道门禁刻意分开：样本与风险阈值只决定是否给出晋升建议，人写下的确认
说明才是规则变成 champion 的依据。助手、插件、导入的报告都不能替代它。
### 🔒 默认脱敏
助手默认走脱敏路径，界面不提供关闭开关：
- 券商截图、PDF、CSV 原文**只在本机解析**，**从不上传**到 AlphaTech 或任何其他模型 API。
- 账号、姓名与直接身份标识会被移除，或替换为设备内稳定的假名。
- 证券代码、组合名、精确数量、精确金额与精确时间会被替换为假名、区间或 15 分钟时段。
- 收益率、持有周期、执行偏差与统计特征会被保留，否则复盘没有意义。
- 每次外发都会在本机写入审计记录，说明发送了哪些字段、替换了多少处。
- 未配置 Provider 密钥时，助手只使用本地数据，不发出任何请求。
- Provider 来自目录：可添加内置 Provider、添加自定义网关（需指定协议）、从端点拉取模型目录，
并在输入框旁的选择器里切换模型与推理强度。详见 [docs/review-agent.md](docs/review-agent.md)。
详见 [docs/review-agent.md](docs/review-agent.md) 与 [docs/convergence.md](docs/convergence.md)。
---
## 🏢 Trader 产品（托管模式）
同一个包还带有托管版 Trader 产品：一套多租户的交易日志与复盘界面，作为 alphatech 平台
（[alphatech.net.cn/trader](https://alphatech.net.cn/trader)）的一个平级入口，与 Alpha Canvas、
Commerce Workbench 并列。它导入你自己的成交、计算绩效分析、为 Playbook 打分、
回测一套 JSON 策略 DSL，并回放历史 K 线。
托管产品的模型访问由官方网关提供：[alphatech.net.cn](https://alphatech.net.cn/)。
一条命令用同一个进程、同一个端口同时提供两个产品：
```bash
pip install "smartmoney-cub-harness[hosted]" # hosted 额外依赖：psycopg，用于 Postgres
smcub trader serve --mode local # 单个离线用户，SQLite
smcub trader serve --mode hosted \
--database-url "postgresql://user:pass@host:5432/smcub" \
--host 0.0.0.0 --token "$TRADER_ACCESS_TOKEN" --no-browser
```
`smcub trader serve` 把 trader API 挂在 `/api/trader/*`，
并与复盘工作台共用同一个 socket。`smcub workbench` 是本地单用户正门，
为单个离线用户挂载同一套 `/api/trader/*` 接口；
`smcub trader serve --mode hosted` 才是那个按请求解析平台身份的入口。
托管模式必须提供 `postgresql://` 地址，绝不回退到本地文件；
绑定到非回环地址必须提供 `--token`。
本产品不下单、不撤单、不修改券商账户、不自动化执行，也不是投资建议。
v1 覆盖了什么、明确的非目标、以及推迟到 v1 之后的功能，都写在
[Trader 产品说明](docs/trader-product.md)；HTTP 接口见 [docs/trader-api.md](docs/trader-api.md)，
三条部署路径见 [deploy/README.md](deploy/README.md)。
---
## 🧩 Everything is a Plugin（插件协议）
仓库自带插件协议、示例插件与精选目录。外部交易项目不进入核心发布包，用户安装插件后，
Harness 会自动发现、校验、注入并挂载能力，无需修改核心代码。详见 [docs/plugins.md](docs/plugins.md) 与 [docs/plugin-development.md](docs/plugin-development.md)。
```bash
smcub plugin inspect examples/toy_plugin/plugin.json
smcub plugin doctor --plugin-dir examples/toy_plugin
smcub plugin run toy.review-tagger \
--request request.json \
--decision-time 2026-09-10T15:00:00+08:00 \
--available-at 2026-09-10T14:00:00+08:00
smcub plugin catalog
smcub profile show a-share-review
```
自动的部分：发现、校验、依赖注入、激活、证据封装。
不自动的部分：安装、联网、外部模型、凭证——一律需要用户主动触发。工作台可代用户在专用虚拟环境执行安装，需逐项确认，且高风险项目永不安装；网络访问与外部模型调用亦永不静默自动开启。
每个插件输出都会封装为 Evidence Envelope，记录插件版本、源码引用、输入/输出哈希、时间语义与数据质量。
若 available_at 晚于 decision_time，直接判定为未来数据泄漏并拒绝执行。
## 收录的开源项目
> 该表格与工作台「插件市场」同源，安装由用户在工作台逐项确认后触发。
> 工作台可代用户在专用虚拟环境中执行安装，需逐项确认，且高风险项目永不安装；网络访问与模型调用亦永不静默自动开启。
### 数据
| 项目 | 上游 | 安装方式 | 许可证 | 安全边界 |
| --- | --- | --- | --- | --- |
| AKShare | [https://github.com/akfamily/akshare](https://github.com/akfamily/akshare) | `pip install akshare` | MIT | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| TuShare Pro | [https://tushare.pro](https://tushare.pro) | `pip install tushare` | BSD-3-Clause | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| BaoStock | [http://www.baostock.com](http://www.baostock.com) | `pip install baostock` | Apache-2.0 | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| 东方财富行情 | [https://github.com/Micro-sheep/efinance](https://github.com/Micro-sheep/efinance) | `pip install efinance` | MIT | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| Yahoo Finance | [https://github.com/ranaroussi/yfinance](https://github.com/ranaroussi/yfinance) | `pip install yfinance` | Apache-2.0 | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| Stooq 行情 | [https://github.com/pydata/pandas-datareader](https://github.com/pydata/pandas-datareader) | `pip install pandas-datareader` | BSD-3-Clause | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| FRED 宏观数据 | [https://github.com/mortada/fredapi](https://github.com/mortada/fredapi) | `pip install fredapi` | Apache-2.0 | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| 腾讯行情快照 | [https://gu.qq.com/](https://gu.qq.com/) | 内置 | builtin | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
### 绩效与风险
| 项目 | 上游 | 安装方式 | 许可证 | 安全边界 |
| --- | --- | --- | --- | --- |
| QuantStats | [https://github.com/ranaroussi/quantstats](https://github.com/ranaroussi/quantstats) | `pip install quantstats` | Apache-2.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| Empyrical Reloaded | [https://github.com/stefan-jansen/empyrical-reloaded](https://github.com/stefan-jansen/empyrical-reloaded) | `pip install empyrical-reloaded` | Apache-2.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| Pyfolio Reloaded | [https://github.com/stefan-jansen/pyfolio-reloaded](https://github.com/stefan-jansen/pyfolio-reloaded) | `pip install pyfolio-reloaded` | Apache-2.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| Riskfolio-Lib | [https://github.com/dcajasn/Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib) | `pip install riskfolio-lib` | BSD-3-Clause | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| PyPortfolioOpt | [https://github.com/pyportfolio/pyportfolioopt](https://github.com/pyportfolio/pyportfolioopt) | `pip install pyportfolioopt` | MIT | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| skfolio | [https://github.com/skfolio/skfolio](https://github.com/skfolio/skfolio) | `pip install skfolio` | BSD-3-Clause | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
### 研究与评估
| 项目 | 上游 | 安装方式 | 许可证 | 安全边界 |
| --- | --- | --- | --- | --- |
| pandas-ta-classic | [https://github.com/xgboosted/pandas-ta-classic](https://github.com/xgboosted/pandas-ta-classic) | `pip install pandas-ta-classic` | MIT | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| pandas-market-calendars | [https://github.com/rsheftel/pandas_market_calendars](https://github.com/rsheftel/pandas_market_calendars) | `pip install pandas-market-calendars` | MIT | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| Qlib 因子评估 | [https://github.com/microsoft/qlib](https://github.com/microsoft/qlib) | `pip install pyqlib` | MIT | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| vectorbt 证据检查 | [https://github.com/polakowo/vectorbt](https://github.com/polakowo/vectorbt) | `pip install vectorbt` | Apache-2.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| backtesting.py | [https://github.com/kernc/backtesting.py](https://github.com/kernc/backtesting.py) | `pip install backtesting` | AGPL-3.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| Backtrader | [https://github.com/mementum/backtrader](https://github.com/mementum/backtrader) | `pip install backtrader` | GPL-3.0 | 只读计算结果与报表；不产生买卖指令，不写入账户与订单。 |
| ZVT | [https://github.com/zvtvz/zvt](https://github.com/zvtvz/zvt) | `pip install zvt` | MIT | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
### Agent
| 项目 | 上游 | 安装方式 | 许可证 | 安全边界 |
| --- | --- | --- | --- | --- |
| 多 Agent 复盘 | harness 内置 | 内置 | builtin | 只生成 challenger 候选与复盘观察；champion 变更必须人工确认。 |
| 反方规则质询 | harness 内置 | 内置 | builtin | 只提出候选与反例；不自动晋级 champion，不改写规则库。 |
| TradingAgents | [https://github.com/TauricResearch/TradingAgents](https://github.com/TauricResearch/TradingAgents) | `git clone --depth 1 https://github.com/TauricResearch/TradingAgents` | Apache-2.0 | 用户自备 LLM/API key 并在本仓库之外配置；harness 不保存、不收集、不上传密钥；其输出只能作为复盘证据，不得转成订单意图或执行计划。 |
| UZI-Skill | [https://github.com/wbh604/UZI-Skill](https://github.com/wbh604/UZI-Skill) | `git clone --depth 1 https://github.com/wbh604/UZI-Skill` | unverified | 只能描述为推荐搭配与生态接入位；不得称为内置依赖，不得把结论变成买卖指令。 |
| tick-stock-panel | [https://github.com/shy3130/tick-stock-panel](https://github.com/shy3130/tick-stock-panel) | `git clone --depth 1 https://github.com/shy3130/tick-stock-panel` | unverified | 只读行情/财务数据，输出仅作为复盘证据；不连接券商、不下单、不改账户。 |
| vn.py | [https://github.com/vnpy/vnpy](https://github.com/vnpy/vnpy) | `git clone --depth 1 https://github.com/vnpy/vnpy` | MIT | 本项目自带下单与账户能力，因此 harness 绝不安装、挂载或调用它；仅作为对照参考记录在册。执行禁令绝对不变。 |
## 📓 复盘工作区与分享包
```bash
smcub workspace import-csv exports/fills.csv
smcub workspace list-cases --action AVOID
smcub workspace summary
smcub share-pack --csv exports/fills.csv --output tmp/share-pack --write
```
工作区用 SQLite 保存复盘用例、D1/D3 结果、插件证据与规则状态。
分享包是离线静态 HTML，证券代码、名称、金额与盘中时间会按策略降精度，并经过隐私审计；
系统不会自动上传。详见 [docs/share-pack.md](docs/share-pack.md) 与 [docs/review-workspace.md](docs/review-workspace.md)。
---
## 30 秒上手
任何 agent 里丢一句话，让它按本仓库的安全合同跑 toy 离线闭环。公开仓库只使用 toy offline data。
| 你用的 agent | 直接丢这句 |
| --- | --- |
| Claude Code | `阅读 AGENTS.md 和 docs/harness-contract.md，运行 smcub loop --preset toy --agent-trigger "自进化"，只做只读复盘，不连接券商，不下单。` |
| Codex / OpenAI CLI | `在这个仓库里按 README 跑 smartmoney-cub-harness toy loop：smcub loop --preset toy --agent-trigger "自进化"，然后阅读 loop_report.md 和 trace.jsonl。` |
| Cursor | `请按 docs/agent-loop.md 使用本项目，跑 toy loop 并总结复盘产物；所有规则更新只能保持 challenger 状态。` |
| Gemini CLI | `请阅读 docs/harness-contract.md，执行 toy offline loop，确认输出包含 READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE。` |
| OpenCode / OpenClaw | `帮我用这个仓库做一次只读复盘演示：运行 smcub doctor，再运行 smcub loop --preset toy --agent-trigger "自进化"。` |
| CLI 直用 | `git clone https://github.com/myc0576/SmartMoney-Cub.git && cd SmartMoney-Cub && pip install -e ".[dev]" && smcub loop --preset toy --agent-trigger "自进化"` |
### 隔离安装与版本确认
不要把开发版本直接装进全局 Python。Windows 推荐使用项目内虚拟环境：
```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\smcub.exe --version
.\.venv\Scripts\smcub.exe doctor
```
macOS / Linux：
```bash
python -m venv .venv
./.venv/bin/python -m pip install -e ".[dev]"
./.venv/bin/smcub --version
./.venv/bin/smcub doctor
```
如果电脑里安装过多个 Python，直接输入 `smcub` 可能命中另一个环境中的旧版本。安装后请运行 `smcub --version` 和 `smcub doctor`；`doctor` 会以不暴露本地路径的方式提示启动器冲突。
当前发行渠道是 GitHub Releases。普通 CLI 用户可用 pipx 从最新修复 tag 安装，让命令拥有独立环境：
```bash
pipx install "git+https://github.com/myc0576/SmartMoney-Cub.git@v1.0.0"
```
未来正式发布到 PyPI 后，可改用更短的安装和升级命令：
```bash
pipx install smartmoney-cub-harness
pipx upgrade smartmoney-cub-harness
```
现有安装不会自动同步。Git editable、pip、pipx 和源码压缩包用户的升级方式，以及 SemVer、Git tag、GitHub Release、PyPI 发布顺序，见 [版本与升级政策](docs/versioning.md)。
装好后最常用的安全命令：
```bash
smcub doctor
smcub privacy-audit
smcub loop --preset toy --agent-trigger "自进化"
smcub inspect-artifacts