guanlan-regime-factor
huyukun662-crypto/guanlan-regime-factor
观澜 · 量化研究助手:Claude Code agent + 自定义 skills,把「研报检索 → 风险 regime → 大势研判 → 因子研究」全链路自动化,用真实 A 股 ETF/指数数据驱动可演示仪表板(HMM 大势研判 + 12 风格因子看板 + regime 门控风险平价 FOF 研究证据链)。
Instalação
npx convez-ai huyukun662-crypto/guanlan-regime-factor1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
观澜 · 大势研判 + 因子研究助手
一个自包含的量化研究作业:用一个 Claude Code agent(guanlan-analyst)+ 5 个自定义 skills,把"研报检索 → 风险 regime → 大势研判 → 因子研究"整条链路自动化,并用真实 A 股 ETF / 指数数据驱动可演示的仪表板。
仪表板现状(两页):① 大势研判(
index.html)—— HMM 4 态隐马尔可夫 × Kaufman 效率比 × 基本面的综合市场状态研判 + 风险仪表盘 + 顶/底指标 + 风险走势 + AI 顾问;② 因子看板(factors.html)—— 12 个真实风格指数代理因子的累积收益/轮动排行/全样本统计。两页侧栏互导。不做组合 / 不回测:项目交付物是「研判 + 配置建议」(read-only 解读),不构建组合、不出权重、不计回测指标。早期 ETF-FOF 回测脚手架
fof/{engine,selection,weights,sleeves}.py留在仓库仅作历史代码参考,未作为主交付,不在文档与仪表板呈现。
它解决什么
| 痛点(手工研究) | 本助手 |
|---|---|
| 翻几十篇研报、无引用链 | quant-research-retriever 秒级检索 vault 金工研报,带路径引用 |
| notebook 对数据、改一个参数就重写 | regime-radar + regime-verdict + factor-research 把指标/HMM大势/因子固化,一行命令全链路复跑 |
| 单策略心电图、回撤吓人 | 大势 verdict + 因子配置建议给「进攻/中性/防御」姿态 + 风格倾斜,研究判断而非组合 |
| 结果难以审阅 | GuanLan 风格风险仪表盘 + 内嵌实时 Claude 顾问可质询 |
三份核心交付文档:① 使用说明 docs/usage.pdf(+ agent 调用 docs/agent-使用说明.pdf); ② 提升对比(agent/skills 对策略研究的实际帮助,八维实测:耗时 / 可溯源 / 防前视 / 可复现 / 可验证 …) docs/before-after.pdf + docs/投研流程提升报告.pdf; ③ 网页使用展示(两页仪表板真实截图 + 当前真实读数)docs/网页使用展示.pdf。
架构
📑 所有文档均提供 PDF(
docs/*.pdf,中文 reportlab 渲染,无外部字体依赖),.md为源、python scripts/md_to_pdf.py --all可重生成: 上手用法 usage.pdf | 分层逻辑 architecture.pdf | skill 触发 skills-triggers.pdf | 跨工具用法 portable-agent.pdf | agent 调用说明 agent-使用说明.pdf | 网页使用展示(含截图)网页使用展示.pdf | 前后效果对比 before-after.pdf | 投研流程提升报告 投研流程提升报告.pdf。 (Markdown 源同名.md同目录可读。)
Tushare Pro ──▶ fof/ (Python 包) ──▶ outputs/*.json ──▶ web/ 仪表盘
真实ETF+宏观 data→regime→selection→weights→engine→report (vanilla JS + Chart.js)
▲
.claude/agents/guanlan-analyst ──────────────────────┤ 串起 5 skills
.claude/skills/{regime-radar, regime-verdict, factor-research, factor-allocation, quant-research-retriever}
▼
server/ (FastAPI) ──▶ /api/chat 实时 Claude 顾问
Agent
.claude/agents/guanlan-analyst.md —— 固定 4 阶段(研报锚定 → 风险 regime → 大势研判 → 因子研究),绝不编造数字、至少引用 2 个研报路径、本身无需 API key。
5 个 Skills
| skill | 作用 | 产出 |
|---|---|---|
regime-radar | 12 个真实指标的顶/底双评分(RSRS/MA20/宽度/波动率 + Tushare 宏观金铜比/期限利差/ERP + 情绪融资余额Z/全市场成交Z/Shibor + IF期货净多比/IO期权PCR)→ 0-100 综合风险分 + 顶/底部分 + 风险走势序列 | outputs/regime.json |
regime-verdict | 大势研判:HMM 4 态后验 × Kaufman 效率比 × 基本面三轴融合 → 走强/震荡/走弱 + 转移矩阵 + 状态统计 | outputs/master.json |
factor-research | 因子看板:12 风格因子的累积/轮动排行/月度IC·ICIR/滚动Sharpe/全样本统计/相关性 | outputs/factors.json |
factor-allocation | 因子配置建议(集成上两者):读 master + factors → 总仓位姿态(进攻/中性/防御)+ 该超配/低配哪些风格(方向由因子 IC 符号定)。纯解读、不建组合、不回测、不出权重 | outputs/factor_allocation.json |
quant-research-retriever | 检索 vault 金工研报(+可选 WebSearch),带引用 | 引用 JSON |
factor-allocation诚实口径:总仓位姿态优先于风格 tilt;因子动量很弱(IC≈0.04 → tilt 只是弱倾斜别重押);防御期 tilt 意义小;这是研究建议、不是组合(无权重/未回测/未计成本)。详见.claude/skills/factor-allocation/references/reading-allocation-advice.md。旧的 FOF tooling(
fof-research-orchestratoragent +fof-builderskill)已退役;ETF-FOF 回测代码fof/{engine,selection,weights,sleeves}.py仍在仓库仅作历史参考,未作主交付。
怎么触发(说什么话)
在 Claude Code 里打开本仓库目录后,直接用自然语言说出意图即可——Claude 把你的话语义匹配到各 SKILL.md 的 description(触发面),命中就自动加载执行。
| 你说(中文 / English) | 触发 |
|---|---|
| 「更新风险评分」「现在什么市场状态」/ "read the current regime" | regime-radar → 0-100 风险分 + 顶/底 |
| 「现在是走强还是走弱」「大势研判」「该进攻还是防御」/ "judge the regime" | regime-verdict → 走强/震荡/走弱 |
| 「看因子」「因子轮动 IC」「哪个风格在风口」/ "factor board / rotation IC" | factor-research → 因子排行/IC/Sharpe |
| 「该超配/低配哪些风格」「按大势和因子给配置建议」/ "factor allocation / tilt advice" | factor-allocation → 姿态 + 超配/低配 |
| 「查研报」/ "find research on X" | quant-research-retriever → 带引用 |
| 「跑一遍大势研判」「重建市场仪表板」/ "what's the market verdict" | agent guanlan-analyst → 整条链路 + 末尾问「要打开仪表盘吗?」 |
要点:① 是语义匹配,不必逐字照搬,意思相近即可;② 不确定就直接点名——「用 factor-allocation 给配置建议」;③ 也可命令行直跑脚本(见 docs/usage.md 方式③),不依赖触发。完整触发语对照与易混点见 docs/skills-triggers.md。
快速开始(跨平台,git clone 即用)
仓库自包含:vault/(236 篇金工研报/概念)、outputs/*.json(demo 数据)、.claude/(agent + 5 skills)全部随仓库分发,不依赖任何本机环境。
# 1. 建虚拟环境 + 装依赖(Python ≥ 3.10)
python -m venv venv
# Windows: venv\Scripts\Activate.ps1
# macOS / Linux: source venv/bin/activate
python -m pip install -r requirements.txt
# 2. 看 demo —— 无需任何 token:仓库已带 outputs/*.json
python scripts/open_dashboard.py # 一键:起服务(后台)+自动开浏览器到 127.0.0.1:8000
# 或手动: python -m uvicorn server.app:app --port 8000 然后开 http://127.0.0.1:8000 / /factors.html
# 3. 要刷新到最新数据,再配自己的 token
cp .env.example .env # Windows: Copy-Item .env.example .env
# .env 填 TUSHARE_TOKEN(必填,去 https://tushare.pro/register 免费领);ANTHROPIC_API_KEY(可选)
python scripts/run_pipeline.py --asof 2026-06-05 --start 2020-01-01
# 4. 单测(防前视等)
python -m pytest tests/test_factor_allocation.py -q # 纯映射、无网络,秒过
python -m pytest tests -q # 全量(需 TUSHARE_TOKEN + 网络)
- 无
TUSHARE_TOKEN:仪表板用仓库内置的outputs/*.json正常渲染(demo);只有「刷新数据 / 重跑 pipeline」才需要 token。 - AI 顾问(可换厂商):默认走 Anthropic(
ANTHROPIC_API_KEY),也支持 OpenAI / DeepSeek / Moonshot Kimi / Zhipu / 通义千问 / Ollama 等任何 OpenAI 兼容接口——在.env设LLM_PROVIDER=openai+LLM_API_KEY+LLM_BASE_URL+LLM_MODEL即可(见.env.example示例)。无 key 则降级为确定性基线建议,pipeline 与仪表板全部可用。 - 研报库:
quant-research-retriever默认读仓库内置vault/;想换成自己的 Obsidian 库,设环境变量QUANT_VAULT_PATH或传--vault。库缺失时优雅返回空引用(不崩)。 - 🔐 密钥安全:
.env已 gitignore,绝不入库。clone 者各自填自己的 token;任何曾在别处明文出现过的 token 请在 tushare.pro 及时轮换。
调用 agent:在 Claude Code 里打开本仓库 → 项目级 .claude/agents/guanlan-analyst 自动可用;说「跑一遍大势研判,该进攻还是防御?」即触发整条链路。完整调用说明(三种方式 + 常用问法 + 边界 + 故障排查)见 docs/agent-使用说明.pdf。
仪表板内容
- 大势研判页
index.html—— 沪深300价量日频上 walk-forward 重拟合 4 态高斯 HMM(稳态/平静/履冰/危机,依据 Yang 2026 SSRN 6823998)× Kaufman 效率比 ER × 基本面 → 走强/震荡/走弱 verdict + 风险仪表盘 + 顶/底指标 + 风险走势 + AI 顾问。12 个 regime 指标拆成 技术面/基本面/情绪资金 三栏(基本面含 IF 期货净多比 + IO 期权 PCR 两个衍生品仓位指标),大势栏 6 个可视化(进攻↔防御仪表盘、HMM 4 态概率演化 stacked-area、状态色带时间轴+持续天数、4×4 转移矩阵热力图、三轴罗盘、价格×状态×ER)。 - 因子看板页
factors.html—— 12 个真实风格指数代理因子(动量/反转/小市值/微盘/大盘/价值/成长/科技成长/红利/低波/质量/市场)的累积收益多线图 + 近期轮动排行 + 全样本统计 + 月度 IC/ICIR + 因子相关性。
目录
fof/ 数据 / regime / 大势研判 / 因子 / 配置建议(核心 Python 包)
.claude/agents/ guanlan-analyst.md
.claude/skills/ regime-radar, regime-verdict, factor-research, factor-allocation, quant-research-retriever
server/ FastAPI(仪表盘 JSON + 静态站点 + 流式 /api/chat)
web/ GuanLan 风格仪表盘(index.html, factors.html, app.js, chat.js, styles.css)
scripts/ run_pipeline.py, open_dashboard.py
outputs/ 仪表盘读取的 JSON(入库以保证可移植)
docs/ usage.md, architecture.md, skills-triggers.md, portable-agent.md, before-after.md
tests/ 防前视 / 指标 / 配置建议映射 单测
vault/ 内置研报库(236 篇金工研报+概念,retriever 默认读它)
工程纪律
- 防前视:指标/选择只用
series.loc[:asof];HMM 每月 walk-forward 只用[:m]重拟合,tests/test_regime.py断言追加未来 bar 不改变 asof。 - 密钥安全:
TUSHARE_TOKEN/ANTHROPIC_API_KEY仅在 gitignored 的.env,不入库、不打日志。 - 诚实交付:项目不构建组合、不回测、不出权重;
factor-allocation给的是研究建议,姿态优先于风格 tilt,因子动量历史很弱(IC≈0.04)→ tilt 只是弱倾斜别重押。
⚠️ 本仓库仅供量化研究参考,不构成任何投资建议。股市有风险,盈亏自负。