为什么值得关注

它将对话式界面与确定性风险检查和透明会计相结合，且无需任何第三方 Python 包。

适合谁使用

希望进行模拟交易练习的个人投资者
寻求投资组合自动化的 Hermes 平台用户
学习投资组合管理系统的开发者
教授市场机制与风险管理的教育工作者

典型使用场景

基于证据决策的回测投资策略
通过自动化研究和风险控制管理虚拟投资组合
在不投入真实资金的情况下学习市场动态
运行纸面交易竞赛或教育模拟

项目优势

零第三方 Python 依赖（仅标准库）
可审计的 SQLite 账本，记录完整交易历史
严格的安全模型：无杠杆、做空或真实资金执行
每项决策需至少两个来源的证据支持

使用前须知

需要已配置 Web Search & Extract 的 Hermes Agent 才能全面研究
无券商集成或真实订单执行
仅限于做多头寸，不支持做空、衍生品或保证金
可选的 Convex 仪表板需要单独部署，未随技能捆绑

README 快速开始

Virtual Investor — Harper

Harper is a long-only virtual portfolio engine and conversational investing skill for Hermes. It combines sourced market research with deterministic risk checks, virtual execution, marked-to-market accounting, forecast calibration, and an auditable SQLite ledger.

Harper can research and simulate intraday or longer-held positions across markets through versioned market adapters. It never places real orders, connects to a broker, uses leverage, or opens short positions.

Highlights

Evidence-backed BUY, SELL, and NO_TRADE decisions
Long-only risk controls enforced by the portfolio engine
Intraday and position-style theses with explicit invalidation rules
Sourced quotes, market sessions, catalysts, and corporate actions
Candidate screening, research memory, and forecast scoring
Market adapters with transparent fallbacks for newly configured markets
Optional Convex dashboard sync and timezone-aware Hermes automation with a user-selected configured messaging destination or local-only reports
Python standard-library runtime with local SQLite storage

Requirements

Python 3
Hermes Agent with Web Search & Extract configured for full research use
pytest only for running the development test suite

The runtime does not require third-party Python packages. Portfolio data, credentials, Hermes configuration, schedules, and virtual environments are not included in this repository.

Install

Install Harper directly from GitHub with Hermes:

hermes skills install balsimpson/virtual-investor/skills/harper

Start a new Hermes conversation, or run /reset in the current conversation, then invoke /harper. Harper will ask for one onboarding detail at a time, including the virtual starting cash after the reporting currency is known. It offers a sensible currency-aware default that the user can confirm or replace, verifies live research access, and initializes the local ledger idempotently.

Verify or update the installation with:

hermes skills list
hermes skills check
hermes skills update harper

For local development, copy the skill directory instead:

mkdir -p ~/.hermes/skills/finance/harper
rsync -a skills/harper/ ~/.hermes/skills/finance/harper/

To configure research access, run:

hermes tools

Choose Web Search & Extract and configure working provid

virtual-investor