smartmoney-cub-harness

游资和散户最大的区别是什么？不是信息差，不是资金量，而是系统。

高手每一次决策都有计划、有证据、有复盘、有规则迭代。普通人最容易掉进的坑，是复盘时翻聊天记录、翻交易软件、翻截图，折腾半天还是说不清当时为什么买、错在什么地方、下一次该怎么改。

smartmoney-cub-harness 是一个本地优先的 AI 复盘引擎。它帮你记录每一次决策的完整逻辑，追踪 D1/D3 的结果，把教训变成规则，把规则沉淀成系统。

它不是个股建议软件，不是自动交易系统，不是券商连接器，也不是财务建议系统。它是你的私人只读交易系统训练器。

30 秒上手

任何 agent 里丢一句话，让它按本仓库的安全合同跑 toy 离线闭环。公开仓库只使用 toy offline data。

装好后最常用的安全命令：

smcub doctor
smcub privacy-audit
smcub loop --preset toy --agent-trigger "自进化"
smcub inspect-artifacts <run_dir>

本地私有 CSV 复盘可以使用自进化流程，但 champion 规则变更仍然必须人工确认：

smcub self-evolve --input-csv path/to/private_cases.csv --max-iterations 20 --time-budget-min 10 --horizon d1
smcub confirm-promotion state/self_evolve/<loop_id>/promotion_packet.json --decision promote --note "manual approval"

5 秒体验复盘闭环

真正有价值的复盘，不是看一眼盈亏就完事，而是把每一次判断拆成：计划是什么、证据是什么、结果是什么、下次怎么改。

一条命令跑完整个 toy 闭环：

git clone https://github.com/myc0576/smartmoney-cub-harness.git
cd smartmoney-cub-harness
pip install -e ".[dev]"
smcub loop --preset toy --agent-trigger "自进化"

运行后会在本地生成：

• loop_report.md
• trace.jsonl
• case_record.json
• memory.md
• evolution_ledger.jsonl

输出摘要会保持这个形状：

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

核心理念：系统 > 感觉

单次判断会忘，系统会进化。

smartmoney-cub-harness 把一次复盘拆成一条可审计链路：

Plan -> Observe -> Record -> Outcome -> Evaluate -> Memory -> Rule Candidate

这条链路对应的是：

每一次错误都应该被拆解，每一条规则都应该被验证或淘汰。这个项目做的不是预测，而是帮你把主观判断训练成可复盘的系统。

给普通用户

你不需要券商 API，不需要量化背景，也不需要把私有资料放进公开仓库。你可以在本地整理这些只读输入：

• 交易计划文本。
• 交易日志 CSV。
• 同花顺或券商截图。
• 只读导出文件。
• 手写复盘笔记。
• toy offline 示例，用来先学习流程。

Harness 帮你结构化这些问题：

• 当时的 thesis 是什么？
• invalidation、time stop、give-up conditions 是否写清楚？
• 数据源、available time、data quality 是否可靠？
• D1/D3 之后结果如何？
• 这次失败是执行问题、证据问题，还是规则问题？
• 有没有值得进入 challenger 状态的规则候选？

给 AI 助手：只读复盘协作

AI 助手在这个仓库里只能扮演 reviewer、challenger、archivist、drift detector 或 systems assistant。它们帮助你复盘，不替你承担交易动作。

安全 agent workflow：

1. 读 AGENTS.md 和 docs/harness-contract.md。
2. 运行 smcub doctor。
3. 运行 smcub loop --preset toy --agent-trigger "自进化"。
4. 打开 loop_report.md 和 trace.jsonl。
5. 提出复盘、安全、redaction、schema 或 workflow 改进。
6. 规则更新保持 challenger 状态。
7. champion 变更只通过显式人工确认路径发生。

详见 docs/agent-loop.md 和 docs/agent-integration.md。

优秀开源项目集成矩阵

这个 harness 会持续预留优秀开源项目的接入位。集成的目标不是制造更激进的交易信号，而是把外部工具的输出纳入只读复盘、证据整理和规则治理。

接入规则见 docs/integrations.md。

可选接入 TradingAgents

TradingAgents 适合已经会配置 LLM provider、并希望把外部多智能体金融分析能力接入本地复盘系统的用户。默认 toy loop 不需要 TradingAgents，也不需要任何 LLM/API key；smartmoney-cub-harness 本身不托管、不读取明文、不提交、不上传 TradingAgents 的 key。

推荐两种模式：

1. report-only mode：用户独立运行 TradingAgents，把本地报告导入 harness，生成只读 review packet。
2. optional local bridge mode：用户已经在本地安装并配置 TradingAgents 后，显式传入 --allow-network 和 --ack-external-llm，由 adapter 包装外部分析结果为 review packet。

# report-only：用户先在 TradingAgents 中生成报告，然后导入本 harness
smcub tradingagents-ingest \
  --report path/to/tradingagents_report.md \
  --ticker 600519.SS \
  --analysis-date 2026-07-06 \
  --output artifacts/tradingagents_review_packet.json

# optional local bridge：仅当用户本地已经安装并配置 TradingAgents 后使用
smcub tradingagents-doctor
smcub tradingagents-run \
  --ticker 600519.SS \
  --analysis-date 2026-07-06 \
  --output artifacts/tradingagents_review_packet.json \
  --allow-network \
  --ack-external-llm

TradingAgents 的输出只会进入 reviewer / challenger / evidence / case-review 流程。它不能成为买入、卖出、下单、撤单、自动执行或账户操作的指令；任何 rule candidate 进入 champion 仍然必须由人显式确认。

安全边界：你的系统，只属于你

交易逻辑和复盘记忆是私有资产。smartmoney-cub-harness 的设计原则是：你的交易系统只在你本地进化。

每个 manifest、decision、outcome、evaluation、registry、doctor output 和 loop output 都必须携带：

READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE

项目默认：

• Local-first。
• Offline by default。
• No telemetry。
• No upload。
• No trading execution。
• No broker automation。
• CLI 输出前先 redaction。
• 公开仓库只使用 toy examples。

它明确不做：

• 不下单。
• 不撤单。
• 不修改账户。
• 不自动化券商。
• 不连接真实交易执行。
• 发布真实交易记录、真实 watchlist、账户数据、私有策略 prompt、私有路径、credentials 或 cookies。

运行：

smcub privacy-audit
smcub doctor

Privacy

This project does not collect, upload, sell, or learn your trading logic. By default it has no server, no telemetry, no remote database, and no real account connection.

Your private trading logic should remain in local artifacts on your machine. It must not be copied into the public repository. Public examples must stay toy-only.

See docs/privacy.md and docs/public-vs-private-quantkb.md.

CLI Commands

smcub loop --preset toy --agent-trigger "自进化"
smcub privacy-audit
smcub self-evolve --input-csv path/to/private_cases.csv --max-iterations 20 --time-budget-min 10 --horizon d1
smcub confirm-promotion state/self_evolve/<loop_id>/promotion_packet.json --decision promote --note "manual approval"
smcub inspect-artifacts <run_dir>
smcub collect-case <run_dir>
smcub append-ledger --event EVENT --payload-json FILE
smcub save-memory --case-record FILE
smcub tradingagents-doctor
smcub tradingagents-ingest --report path/to/tradingagents_report.md --ticker 600519.SS --analysis-date 2026-07-06
smcub tradingagents-run --ticker 600519.SS --analysis-date 2026-07-06 --allow-network --ack-external-llm
smcub doctor
smcub validate-manifest examples/sample_run/run_manifest.json

Development Checks

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

Public Boundary

The public repo can include schemas, loop runtime, toy examples, redaction, case bank, local Markdown memory format, evolution ledger, challenger/champion governance, integration guidance, and agent runbooks.

The public repo must not include real trades, real watchlists, account data, private QMT paths, private strategy prompts, key stock-picking logic, secret scoring weights, credentials, cookies, or local private workspace paths.

READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE remains the public boundary and runtime safety declaration.

License

MIT. See LICENSE.