smartmoney-cub-harness

smartmoney-cub-harness is a local-first, read-only, agent-agnostic control plane for trading review and evidence governance. It turns an external caller's offline run into portable, reviewable artifacts without taking trading authority.

External Agent or CLI caller → Run Envelope → frozen Benchmark/Evidence Pack → deterministic replay → explicit human promotion gate.

It has no embedded LLM, no broker connection, and no automatic trading. It does not place, cancel, or execute trades; select stocks; mutate accounts; run a background autonomous trading Agent; or automatically mutate core rules.

简体中文

Bilingual System Flow

Read-only inputs feed the SmartMoney-Cub control plane. Optional, user-selected open-source tools are kept outside the trusted core and enter only as review evidence. The control plane freezes manifests and evidence packs, and delayed D1/D3 outcomes flow through deterministic replay, evaluation, memory, challenger rules, and an explicit human promotion gate before any rule candidate can return to the next plan.

See docs/architecture.md for the text and Mermaid representation of the same flow.

Toy/offline control-plane workflow

Install the package, then capture one deterministic toy run with external-Agent metadata:

git clone https://github.com/myc0576/smartmoney-cub-harness.git
cd smartmoney-cub-harness
python -m pip install -e ".[dev]"
smcub capture-run --mode after-close --preset toy --sandbox --decision-time "2026-06-01T15:31:00+08:00" --agent-name "toy-doc-agent" --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 examples/toy_strategy/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 this sequence in a clean checkout; if you reuse the fixed decision time, capture-run adds a numeric suffix to avoid overwriting the earlier run. All inputs are toy/offline. The machine contracts are Run Envelope and Evidence Pack.

The workflow states are review states, never trading actions: a Run Envelope is completed, pending_review, or blocked; an Evidence Pack is challenger, ready_for_review, pending_review, or blocked; a replay report is verified, pending_review, or blocked. Only action_label describes a recorded observation such as SILENT or ALERT.

Run Envelope permissions are a declarative, unverified policy record (enforcement: declarative, verified: false), not a subprocess sandbox or proof that an external command obeyed the policy. The CLI's --sandbox flag only selects the disposable tmp/sandbox output namespace; it does not isolate the process. Run untrusted commands inside an OS/container sandbox. evidence_pack.sha256 seals the exact pack manifest for local tamper detection; it is not an authenticated signature. Replay rejects a missing, malformed, mismatched, or structurally invalid seal/manifest as pending_review.

Optional ecosystem integrations remain outside the trusted core. See docs/integrations.md, including the recommended companion wbh604/UZI-Skill, and the TradingAgents adapter boundary. External LLM/network credentials stay outside this repository, and imported reports remain review evidence rather than trading authority.

Isolated installation and upgrades

Keep the CLI in an isolated environment and verify the executable you are using:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\smcub.exe --version

python -m venv .venv
./.venv/bin/python -m pip install -e ".[dev]"
./.venv/bin/smcub --version
pipx install smartmoney-cub-harness
pipx upgrade smartmoney-cub-harness

Existing installations do not update automatically. See docs/versioning.md for Git, pip, pipx, tags, and GitHub Release update paths.

The existing toy Agent Loop remains supported:

smcub loop --preset toy --agent-trigger "自进化"

Example loop output:

{
  "status": "ok",
  "loop_name": "observe_candidate_plan_position_outcome_review_rule_update",
  "preset": "toy",
  "safety": "READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE",
  "champion_mutated": false
}

AI decision harness for subjective A-share traders.
Read-only. Human-in-the-loop. Built for review, discipline, and rule evolution.

聪明资金幼年体 / 游资幼年体：陪你复盘，不替你下单。
把“小资金做大的神话”，拆成每天可记录、可验证、可进化的交易系统。

Not a stock-picking bot. A semi-quant AI decision harness where human traders and agents evolve through evidence.

Safety & Disclaimer

This project is for research, journaling, review, and educational workflow design only. It is not financial advice, not a stock recommendation service, not price prediction, and not a trading execution system. Any account, screenshot, or trading-record input is used only for local review and structured analysis.

Every manifest, decision, outcome, evaluation, registry, and doctor output carries:

READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE

The Story

很多人都听过 A 股江湖里“小资金做大”的神话。

有人记住了龙头，有人记住了情绪，有人记住了分歧转一致，有人记住了“高手买入龙头，超级高手卖出龙头”。但真正难的不是背下这些语录，而是在自己的账户里，把每一次冲动、犹豫、误判、错过、格局和撤退，变成可以复盘的证据链。

smartmoney-cub-harness 想做的不是一个告诉你明天买什么的机器人。它是一只还在长大的“聪明资金幼年体”：它只读你的账户导出、截图、日志或 toy data，只记录你的计划和证据，只在结果出来之后和你一起复盘。

It does not ask "what is tomorrow's winner?" It asks:

• Why did you act at that time?
• Where was the invalidation point?
• Was this a repeatable pattern, or luck?
• Did the cycle offer opportunity, or did emotion take over?
• After D1/D3 review, should this rule be promoted, downgraded, or deleted?

In the AI era, good review does not have to depend on randomly meeting a mentor. A large model can become a sparring partner, challenger, reviewer, archivist, and systems-engineering assistant. But your pattern still has to grow out of your own feedback loop.

What It Is

• A subjective trading decision harness.
• A read-only account/screenshot review companion.
• A trading journal with provenance and invalidation discipline.
• A D1/D3 outcome review engine.
• A rule evolution loop.
• An agent-ready review framework.
• A personal pattern discovery system.
• A semi-quantitative bridge between human discretion and machine-audited review.

What It Is Not

• Not a quantitative alpha factory.
• Not a single trading strategy.
• Not a stock-picking bot.
• Not a signal-selling system.
• Not a broker or execution bot.
• Not an automated trading system.
• Not financial advice.
• Not a promise that small capital will grow large.

Account & Screenshot Input

smartmoney-cub-harness can work with different levels of input:

• Read-only broker/account export.
• Read-only QMT or adapter integration if configured locally.
• Trading journal CSV.
• Watchlist files.
• TongHuaShun or broker screenshots of positions, orders, and daily review.
• Manually written trading notes.

All inputs are for review and journal generation only. The public core does not connect to live execution by default. It does not place orders, cancel orders, or modify accounts.

Screenshots are often the safer path for ordinary users: lower setup cost, smaller permission surface, and less chance of confusing review with execution. Even without an API, you can provide position screenshots, broker fill screenshots, and trading-plan text; the harness can still act as an AI review partner that structures the plan, risk, invalidation, and later outcome.

哪怕你没有 API，也可以把同花顺持仓截图、券商成交截图、交易计划文本丢给它，它依然可以作为 AI 复盘陪练，帮你整理当时的计划、风险、失效位和后续结果。

Core Loop

The bilingual system flow above summarizes the control-plane pipeline. The maintainable text and Mermaid source for this loop live in Architecture.

Where the 易经 Thinking Lives

This project does not use 易经 as fortune telling, symbol prediction, or price forecasting. The useful engineering translation is a review language for cycle, timing, position, change, restraint, and opposing evidence.

The retreat phase matters. In a cooldown or drawdown state, the goal is not offense; it is preserving the right to act next time.

Where Systems Engineering Lives

Qian Xuesen-style systems engineering appears here as modules and loops, not decorative philosophy.

Not Quant Trading. Not Pure Discretion. A Semi-Quant AI Decision Harness.

Traditional quant systems usually define a strategy first, backtest historical data, seek repeatable signals, and may automate execution. smartmoney-cub-harness starts from subjective trading experience and makes that experience auditable.

It is not the strategy itself. It is the container where a strategy grows up. It does not replace the trader; it trains the trader. It does not remove human experience; it makes that experience recordable, reviewable, and iterable.

Human × Agent Co-Evolution

AI is not an oracle. In this harness, an agent is a training partner that helps you ask the opposing question, review delayed outcomes, archive evidence, notice rule drift, and extract patterns from logs.

The human remains responsible for final judgment.

The edge is not inside the model. The edge emerges from the feedback loop between the trader, the market, and the memory of past decisions.

Quick Start

git clone https://github.com/myc0576/smartmoney-cub-harness.git
cd smartmoney-cub-harness
python -m pip install -e .
smcub doctor
smcub capture-run --mode after-close --sandbox --decision-time "2026-06-01T15:30:00+08:00" --command "python examples/toy_strategy/leader_pullback_demo.py"
smcub build-outcome tmp/sandbox/20260601/20260601_153000-after-close --horizon d1 --price-source examples/toy_strategy/sample_prices.json
smcub evaluate-run tmp/sandbox/20260601/20260601_153000-after-close --horizon d1

The fixed decision time above creates the shown sandbox path in a clean checkout. Local absolute paths are redacted from CLI JSON output, so choose another decision time before repeating the exact sequence.

Demo Output

Toy decision:

{
  "schema": "smartmoney_cub_decision.v1",
  "action_label": "ALERT",
  "symbol": "TOY.CUB",
  "invalidation_price": 9.4,
  "time_stop": "D1/D3 review",
  "give_up_conditions": [
    "observation thesis is no longer supported by recorded evidence",
    "price below invalidation_price 9.4000"
  ],
  "data_source": "toy_strategy",
  "available_at": "2026-06-01T15:30:00+08:00",
  "data_quality_flag": "ok",
  "safety": "READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE"
}

Toy evaluation:

{
  "grade": "useful_alert",
  "failure_tags": [],
  "scores": {
    "valid_contract": 1,
    "false_alert": 0,
    "missed_opportunity": 0,
    "risk_contract_violation": 0
  },
  "safety": "READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE"
}

Development Checks

python -m pip install -e ".[dev]"
pytest -q
python -m smartmoney_cub_harness.cli doctor
python -m smartmoney_cub_harness.cli --help

Contributing

Contributions are welcome when they preserve the safety contract. Keep examples offline and toy-only. Do not add live trading execution, broker automation, order placement, order cancellation, account modification, private watchlists, credentials, cookies, local absolute paths, or personal trading records.

License

MIT. See LICENSE.

Safety & Disclaimer

This project is for research, journaling, review, and educational workflow design only. It is not financial advice, not a stock recommendation service, not price prediction, and not a trading execution system. Any account, screenshot, or trading-record input is used only for local review and structured analysis.