SPR — Strategic Portfolio Report

FOF 投资组合报告生成器 · 自动下载 + AI 分析 + ECharts 可视化

---

一、快速开始

对话触发

在 Hermes 聊天中输入 spr <input> 即可触发全自动流程：

spr /path/to/data                         # 本地数据目录
spr http://git.atibm.com/attachments/...   # Forgejo 附件 URL（自动认证下载）
spr version                                # 查看版本
spr update                                 # 更新 Skill

全自动流程（Agent 执行）：

你: spr http://...
    │
    ▼
Step A — CLI 下载数据
    │  检测 ai-analysis.html 不存在 → 打印数据目录路径 + 操作指南
    │  （不渲染，等 Agent 完成分析）
    ▼
Step B — Agent terminal() 读取所有 CSV/JSON
    │
    ▼
Step C — Agent 推理模型生成
    │     · 数据归纳（指标矩阵 + 相关性 + 信号汇总）
    │     · 分析建议（边际收益表 + MTC参数 + 分层配置）
    │     · 技术信息（算法链 + 数据量 + 参数值）
    ▼
Step D — write_file $DATA_DIR/ai-analysis.html
    │
    ▼
Step E — bin/spr $DATA_DIR --style 1
    │   自动发现 ai-analysis.html → 注入 Tab6
    ▼
Step F — 交付含深度AI分析的 HTML + ZIP

一句话：你只需要说 spr <数据>，Agent 自动完成 下载→分析→写文件→渲染→交付。

CLI 命令

# 生成报告
spr /path/to/data           # 本地目录
spr /path/to/data.zip       # 本地压缩包
spr https://...              # URL / Forgejo 附件

# 参数
spr /path/to/data --style 2  # 输出风格 1/2/3
spr /path/to/data --style 1  # （默认）

# 管理
spr version                  # 版本号
spr update                   # 从 Git 更新分支
spr update <commit>          # 指定 commit 更新
spr list                     # 列出历史任务
spr rm                       # 删除所有任务
spr rm <ts>                  # 删除指定任务

注意：spr <URL> 调用时，CLI 会检测数据目录中是否有 ai-analysis.html。
缺失 → 打印数据目录路径 + 操作指南 并退出（不渲染），等待 Agent 完成分析后 bin/spr $DATA_DIR 重跑。

---

二、CLI 命令

# 生成报告
spr /path/to/data           # 本地目录
spr /path/to/data.zip       # 本地压缩包
spr https://...              # URL / Forgejo 附件

# 参数
spr /path/to/data --style 2  # 输出风格 1/2/3
spr /path/to/data --style 1  # （默认）

# 管理
spr version                  # 版本号
spr update                   # 从 Git 更新分支
# 输出风格
--style 1     # 纵向滚动（窄长布局，默认）
--style 2     # 宽多Tab
--style 3     # 全局筛选面板 + HSL

---

四、项目结构

skill-portfolio-report/
├── SKILL.md                 ← Hermes Skill 工作流入口
├── README.md                ← 本文档
├── VERSION.json             ← 自动版本号
├── generate_report.py       ← 核心渲染脚本（5628行）
├── scripts/
│   └── spr                  ← CLI 入口（bin/spr 为其符号链接）
├── adapters/                ← CSV 适配器系统
├── references/              ← 代码模式 / 数据格式参考
│   ├── data-patterns.md     ← ECharts / DOM / 主题模式
│   ├── data-preparation.md  ← 测试数据准备
│   ├── fof2026-data-patterns.md
│   └── style1-manager-card.md
├── specs/                   ← STDD 规范文档
├── changes/                 ← STDD 变更
├── archive/                 ← 已完成变更
├── tests/                   ← 测试
├── input/                   ← 测试数据（gitignored）
├── output/                  ← 生成报告（gitignored）
└── design/                  ← 设计方案

---

五、生成报告脚本

用法

# 完整生成
python generate_report.py --input-dir /path/to/data

# 输出风格
python generate_report.py --input-dir ./data/ --style 1

# 仅提取数据 JSON
python generate_report.py --input-dir ./data/ --data-only

# 自动扫描
python generate_report.py --auto-detect

输出

• .html — 单文件自包含（ECharts 5.x CDN，深色金融风）
• .zip — 同级自动打包（Telegram 不接收裸 .html，必须发 zip）
• 文件名格式：{timestamp}_hermes-spr.html

适配器

脚本内置 6 种 CSV 适配器，按列名签名自动识别：

适配器	自动检测特征
委托回测指标	列名含年化收益率/回撤/波动率/卡玛/夏普 ≥3 个
委托净值	首列日期 + net/净值列
标的净值	首列日期，列数 2~50
全市场基金净值	首列日期，列数 >50
基金产品画像	列名含产品名称/管理人/一级分组
FOF2026 回测	目录名匹配 HHMMSS_滤XXX_评XXX_N只_选XXX_类型

---

七、开发

分支策略

分支	用途
main	稳定版
dev	长期开发分支
iter/*	功能迭代分支
tag vX.Y.Z	发布版本

安装（Hermes 环境）

# 从 Git 更新
spr update

# 本地安装
cp -r SKILL.md generate_report.py adapters/ /opt/data/skills/financial-services/spr/
cp scripts/spr /opt/data/home/bin/spr

STDD 研发流程

详见 AGENTS.md。

---

八、输入数据格式

目录结构

input/
├── {场景名}/
│   ├── *评价指标.csv           ← 核心：4策略 × 5指标
│   ├── *资金结算_{策略}.csv    ← 核心：日频净值（6列+）
│   ├── *资产.csv               ← 可选：子标日频净值
│   ├── *资产信息.csv           ← 可选
│   ├── *产品要素.json          ← 可选：回测参数
│   └── *管理人.json            ← 可选：算法参数
└── ...

4 种策略

策略	算法链	特征
只用组合算法	Select→Cluster→Predict→Weight(voting)→Risk(CMPI)	夏普稳定3.07，场景不敏感
只用风筹	EqualWeight(window=60)→Risk(MTC+SecurityCapper)	收益/回撤随阈值单调
满仓等权	EqualWeight(window=60)→Risk(CMPI+SecurityCapper)	基准39.7%/夏普3.13，场景不敏感
管理人051T	Weight(voting,245d)→Risk(MTC+SecurityCapper)	风控优先，回撤15是关键点

FOF2026 命名格式

{HHMMSS}_滤{日期}_评{期间}_{N只}_选{参数}_{类型}

例：155058_滤20220101_评20220101-20231231_10只_选-1.3-0.0_相关性

字段	示例	说明
滤20220101	筛选起始日	存活过滤时点
评20220101-20231231	评价期间	指标统计窗口
10只	标的数	抽样结果
选-1.3-0.0	夏普范围	分组筛选
相关性	类型	相关性/稳定性分群

版本

版本	日期	变更
v1.0	2026-06-01	初始版本
v1.1	2026-06-15	FOF2026 支持 + 6 tab
v1.2	2026-06-30	AI 分析自动发现 + CLI 守卫 + 无模板回退 + 深度分析规范