feat: contracts portfolio CLI

[XucroYuri]

新增 contracts portfolio，从合约 CSV 直接运行批量持仓高层汇总。

[Copilot]

🟡 Changes recommended

contracts portfolio 对 direction/lots 等用户输入缺少显式校验，结合下游吞掉 ValueError 的行为会导致无效参数被静默当作“正常运行但 episode_count=0”。

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

该 PR 为 goratio contracts CLI 新增 portfolio 子命令，使用户可以直接从合约级 CSV 运行批量持仓模拟的资金/保证金高层汇总（复用 margin.summarize_batch_portfolio()），并补充对应的测试与文档入口说明。

Changes:

• 新增 goratio contracts portfolio --csv ... CLI 子命令，读取合约 CSV、构造 episode，并输出批量持仓汇总（支持 --json）。
• 增加覆盖该新命令的单元测试用例。
• README / CHANGELOG / ROADMAP 增补该命令的使用与版本记录。

File summaries

File	Description
src/goratio/cli.py	增加 contracts portfolio 子命令解析与执行路径，调用批量持仓汇总并输出 JSON/文本结果。
tests/test_cli.py	新增 contracts portfolio 的集成式 CLI 测试（从临时合约 CSV 运行并断言 JSON 结构关键字段）。
README.md	补充 contracts portfolio 的 CLI 示例。
CHANGELOG.md	记录新增的 CLI 能力。
.planning/ROADMAP.md	路线图打勾并更新测试总数。

Review details

Suppressed comments (2)

src/goratio/cli.py:420

• 这里同一个 CSV 会被解析两次：先 read_contract_csv(args.csv)，随后 contract_csv_to_raw_market_data(args.csv) 内部又会 read_contract_csv(path)。对大文件会带来不必要的 IO/解析开销，并且如果文件在两次读取之间被修改，还可能出现 records 与 raw 不一致的边界情况。建议在 contracts.py 增加一个可复用的 helper（例如 contract_records_to_raw_market_data(records, ...)），或让 contract_csv_to_raw_market_data 支持接收已解析 records，从而在 CLI 里只读一次。

            records = read_contract_csv(args.csv)
            raw = contract_csv_to_raw_market_data(args.csv)

src/goratio/cli.py:421

• 这里建议在进入 portfolio 流程前显式校验 direction/lots/initial_capital。因为 run_position_simulation() 会捕获 position_pnl_estimate() 的 ValueError 并 continue；如果用户传入无效 direction/lots，会导致所有 episode 被静默跳过并最终 exit_code 仍为 0，误导为“正常运行但 episode_count=0”。main() 已统一捕获 ValueError 并返回 2，所以在 CLI 层提前 raise 更符合用户预期。

        if args.command == "contracts" and args.contracts_command == "portfolio":
            records = read_contract_csv(args.csv)
            raw = contract_csv_to_raw_market_data(args.csv)
            prepared = prepare_market_data(

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.