⚡ spr

spr — Strategic Portfolio Report

原名	fof-portfolio-report（已改名 spr）
类别	用户安装
来源	`https://git.atibm.com/at/skill-portfolio-report.git`
安装路径	`/opt/data/home/skill-portfolio-report/`
Skill 文件	`/opt/data/skills/financial-services/spr/SKILL.md`
分支模型	`main`（稳定） + `dev`（长期开发） + `fix/xxx`/`feature/xxx`（短生命分支）
CLI 入口	`spr`（`~/skill-portfolio-report/scripts/spr`）
当前版本	v1.1（2026-06-01）

功能概述

AI-powered 投资组合对比报告生成器。从 FOF/SPR 回测数据自动生成面向投资人的 ECharts 可视化 HTML 报告。

核心能力

CSV 适配器系统：自动识别 6 种 CSV 数据类型，可插拔扩展，无需改管线
管理人策略顺序：通过 管理人.json 自定义报告中 4 个管理人策略的排列顺序
数据输入：支持标准命名目录、业务命名目录、FOF2026 命名格式、zip 压缩包自动检测
回测评价指标：年化收益率、最大回撤、波动率、卡玛比率、夏普比率
净值曲线：从资金结算 CSV 提取日频净值，归一化（起点=1）绘制收益曲线
标的数据：从资产 CSV 提取每个标的的累计收益率，全量计算回撤/夏普/卡玛
全市场基金池：N×T 大宽表日净值矩阵，支持 100+ 基金产品
基金产品画像：产品元信息+聚类分组，含收益率/风险指标/分级聚类
分组详情：逐场景表格，标的+管理人=行，累计收益率+评价指标=列
可视化：ECharts 5.x 深色金融风，含分组柱状图、散点图（等比例+45°基准线）、净值曲线
叙事分析：4 种策略对比 + 分组对比分析
分组对比：稳定性/相关性子分类，FOF2026 四维业务字段（滤日期/评估期/夏普筛选/筛选类型）

CLI 用法

spr /path/to/data          → 生成报告（自动检测目录/zip/URL）
spr update                 → 安装远端最新 tag（含本地保护）
spr update <commit>       → 安装指定 commit（本地优先，无则拉远端）
spr version                → 显示版本、安装日期、git 仓库信息

保护机制：所有 spr update 操作自动保存当前 git 状态（分支+暂存），安装完成后还原。

管理人策略顺序

在回测场景目录中放置 管理人.json，可控制报告中 4 个管理人策略的排列顺序。两种格式均可：

// 格式 A：dict 含 strategy_order 字段
{"strategy_order": ["只用风筹", "满仓等权", "只用组合算法", "管理人003_FOF"]}

// 格式 B：直接数组
["只用风筹", "满仓等权", "只用组合算法", "管理人003_FOF"]

无 管理人.json 时按 CSV 动态发现顺序排列，向后兼容。

核心指标对比图

使用单图多指标+场景下拉切换设计，替代了原有的 4 个独立柱状图：

X 轴：年化收益率、最大回撤（标注"越低越好"）、夏普比率、卡玛比率
每组 4 色柱 = 4 个管理人策略
场景下拉切换，tooltip 显示各策略值
风险-收益散点图 XY 轴等比例，带 45°（收益=波动）虚线基准线

CSV 适配器系统（v1.1）

从 v1.1 开始，CSV 解析不再依赖硬编码文件名匹配，改为可插拔的适配器管线：

架构

input_dir → Registry.scan_directory()
  → 递归发现所有 CSV
  → 逐文件调用各适配器的 detect()
  → 取置信度最高的匹配（≥0.6）
  → parse() → model() → 统一 ModelData
  → _convert_models_to_reports()
    → 按 source_dir 分组，合并到同一 report
    → 补全 net_data / asset_net_data 的 _dates

模型合并机制

适配器管线以 CSV 文件为单位扫描——每个 CSV 产生一个独立 model。对于非 FOF2026 的场景目录（含 metrics + settlement × N + asset 多个 CSV），_convert_models_to_reports 按 source_dir 分组合并：

主模型= metrics（策略评价指标最全）
补充合并：settlement 模型的 net_values 合并入 net_data，asset 模型的 net_values 写入 asset_net_data
_dates 补全：适配器模型中 dates 字段不内嵌到 net_values 中，转换时从 dates 字段取回
SettlementAdapter 列数保护：列数 > 4 时不匹配结算类型，防止误认 asset CSV

6 个内置适配器

适配器	检测特征	文件名加分	解析产出
委托回测指标 `metrics`	列名含 {年化收益率, 回撤, 波动率, 卡玛比率, 夏普比率} ≥3 个	"评价指标" +0.15	策略名 × 5 指标
委托净值 `settlement`	首列日期 + 含 net 列或首列日期 + 第2列数值列数 ≤4（排除 asset 宽表）	"资金结算" +0.15	日频净值/单位序列
标的净值 `asset`	首列日期 + 列数 2~50 + 不含业务关键词	"asset" +0.15	多标的日频净值
全市场基金净值 `fund_universe`	首列日期 + 列数 >50	—	100+ 基金×T日净值矩阵
基金产品画像 `product_profile`	列名含 {产品名称, 管理人, 一级分组} ≥2 个	"sample"/"group" +0.05	产品元信息+聚类分组
FOF2026 `fof2026`	目录名匹配 HMMSS_滤XXX_评XXX_N只_选XXX_类型	—	四维参数 + 子适配器递归

检测策略（三级）

列名签名（主）：CSV header 集合与适配器签名模板匹配，是核心检测手段
文件名启发（辅）：文件名含特定关键词 → 置信度 +0.05~0.15
值域确认（辅）：首列日期检查、数值列比例 → 置信度 +0.05~0.1

置信度 ≥0.6 为匹配。多个适配器匹配时取最高分。

更新流程

spr update 内部由 CLI 脚本处理完整 git 生命周期：

save_git_state()：保存当前分支 + stash 未提交变更
spr update → git fetch --tags origin → 找到最新 tag → checkout → 安装
spr update <commit> → 先本地 git cat-file -t 检查 → 存在则直接 checkout → 无则 fetch 后 checkout → 安装
install_to_hermes()：同步到 Hermes skill 目录（含 SKILL.md, generate_report.py, manual.md, adapters/, scripts/, references/）
write_version_meta()：更新 VERSION.json
restore_git_state()：切回原分支 + pop stash

AI 仅需执行 spr update 或 spr update <commit> 并转发 CLI 输出，不做额外 git 操作。

分支模型

main        ← stable, production-ready
dev         ← 长期开发分支
fix/xxx     ← 短期修复分支，基于 dev，合并至 main，然后 dev 同步 main
feature/xxx ← 短期功能分支（同 fix 模式）
tag         ← 在 main 上标记版本（v1.0.0、v1.1 等）

合并回填模式：fix/feature 分支合并入 main 后，dev 必须 merge main 保持同步。

策略配色

■ 只用组合算法	■ 只用风筹
■ 满仓等权（基准）	■ 管理人003_FOF

v1.1 变更（2026-06-01）

spr update 重构：仅支持 spr update（最新 tag）和 spr update <commit>（本地优先远端回退），删除 local 子命令
统一保护机制：所有 update 操作 save_git_state + restore_git_state
install 新增：复制 adapters/ 目录和 manual.md
核心指标单图化：4 个独立柱状图合并为一个场景下拉切换的分组柱状图
净值曲线归一化：所有策略从起点=1 出发，Y轴标注"累计收益 (起点=1)"
散点图等比例+45°线：XY 轴同步范围，虚线 y=x 基准线
分组详情表全填充：标的评价新增最大回撤/夏普/卡玛计算
管理人策略顺序：新增 管理人.json 支持
CSV 适配器系统：6 个内置适配器自动识别 CSV 类型
分组详情说明文字：追加年化天数=245 天 / 无风险利率=0% 信息
适配器模型合并：_convert_models_to_reports 按 source_dir 分组合并 settlement/asset 模型到主 metrics 模型，修复非 FOF2026 场景缺少标的的问题
_dates 补全：net_data / asset_net_data 从适配器 dates 字段取回，修复净值曲线缺失时间轴的问题
SettlementAdapter 列数保护：列数 >4 不匹配，防止 asset 宽表被误判为资金结算

v1.0.0 变更（2026-06-01）

STDD 可视化增强：回测周期智能格式化、筛选分组方法提取、场景名用目录短名、净值曲线高度+75°日期轴、标的曲线默认隐藏/单元素legend切换、夏普/卡玛拆为独立柱状图、散点图tooltip修复、所有数字保留3位小数
分支模型重构：从 iter 分支 → main + dev + fix/feature 分支模型
SKILL.md 重构：新增 AI 执行流程章节（spr update / spr version），指引 AI 调用 CLI 而非手动 git
CLI 更新：update 子命令从 local → tag 安装，增加 save_git_state/restore_git_state 保护

版本历史

版本	日期	说明
v1.1	2026-06-01	spr update 重构 + 单图多指标 + 净值归一化 + 散点图等比例+45°线 + 适配器系统 + 模型合并修复
v1.0.0	2026-06-01	可视化增强 + 分支模型重构 + SKILL.md AI执行流程修正
v0.1.0	2026-05-28	首个正式发布版本（含全部迭代修复）