RiskGuard v1.4.0 — 每日体检 + 压力测试:AI 帮你盯盘的那一层

回应"AI 帮你 24 小时盯盘,普通人也能用上机构级风控武器"这个刚需场景。

🧭 先说清楚:逐层比对之后的判断

机构级风控拆开是四层:实时监控 → 异常检测 → 硬编码熔断线 → 压力测试。逐层核实 RiskGuard 现状:

• 硬编码熔断线——RiskGuard 自 v1.0 起就在做的事,且是唯一的立库使命(五轮对抗审查验证过)。
• 实时监控——核心机制(RiskMonitor)已有,这版补上它的交付形态:每日体检。
• 压力测试——原语已在(backtest 模块),这版补上一键推演当前持仓的顺手入口。
• 异常检测——明确排除。统计/AI 判定"这次不一样"是数据科学能力,和本库"确定性、fail-closed、绝不模糊判断"的设计哲学是两种不同的产品。这一层交给外部 AI agent:agent 负责观察、判断、叙述,RiskGuard 只保证它拿到的事实是真的、以及在规则被触发时毫不犹豫地执行——这条线不能由 AI 决定。

🌙 新增:riskguard.reporting

from riskguard.reporting import build_digest, render_digest_text, run_stress_test, render_stress_text

# 每日体检:结构化摘要,交给 AI agent 去叙述、去推送提醒
report = build_digest(engine, portfolio)
report.to_dict()

# 压力测试:"如果集体跌 20%,我扛得住吗"——绝对只读,零副作用
result = run_stress_test(engine, portfolio, shock_pct=-0.20)

CLI 同步支持多持仓输入:

$ riskguard digest --equity 95000 --position AAPL:80:190 --position TSLA:-40:250 --state-db risk.db
$ riskguard stress --equity 95000 --shock -0.20 --position AAPL:80:190 --position TSLA:-40:250

压力测试的只读承诺很硬:不触发熔断、不写审计、不碰持久化——即便 --state-db 指向一个还不存在的文件,也不会在磁盘上留下任何新文件。

🛡️ 发布前对抗审查(1 critical + 1 high + 2 low)

新模块经一轮聚焦审查,逮到一个 critical:账户被冲击打穿仓(权益 ≤ 0,恰恰是压力测试最该报警的场景)时,position_breaches 会因为 Portfolio.weight() 的除零防御性默认值而漏报所有超限仓位——同一份结果里总敞口比例却正确显示 inf,两个字段自相矛盾,CLI 的退出码可能因此静默显示"一切正常"。已用新增的 weight_or_inf() 统一修复(不改动已被多轮验证过的 Portfolio.weight() 核心方法)。详见 CHANGELOG。

774 项测试全绿。

⚡ 升级

pip install -U "riskguard @ git+https://github.com/SilentFleetKK/riskguard.git"

RiskGuard v1.3.0 — 状态持久化:堵住重启绕过熔断的后门

第三方独立体检(架构 + 领域 + 竞品 + 唱衰四路评审)发现的必修项修复:名实不符的文档主张,以及一个与产品使命直接矛盾的结构性缺陷——重启可以绕过熔断。

🔒 核心修复:状态持久化

RiskState 此前纯内存,进程一重启,高水位和熔断标记全部归零,等于给亏红眼的操作者留了一条"重启一下继续交易"的隐藏后路。现在接一个 state_store,熔断真的扛得住重启:

from riskguard import RiskEngine, SqliteStateStore
engine = RiskEngine(config, broker=broker, state_store=SqliteStateStore("risk_state.db"))

• 加载失败在构造期硬失败(拒绝以"一切正常"假象启动)
• 乐观锁(版本号 CAS):两个引擎共用同一存档不会静默互相覆盖,而是响亮报错
• reset_breaker() 先落盘、成功后才切内存(fail-closed)
• 拒绝写入/读回非有限权益(NaN/inf 会让回撤熔断永久失效)
• CLI riskguard check 新增 --state-db / --state-key,脚本化重复调用(cron 定时验单)也能跨调用持久化

🛡️ 其它必修项

• README 安装指引名实不符:pip install riskguard 在 PyPI 未发布前是装不上的坏指令,改为诚实的 git 安装方式
• GitHub Actions CI:pytest 矩阵(3.10–3.13)+ ruff,徽章从手写静态数字换成真实 CI 状态
• 纪律的代价:新增 examples/09,诚实展示同一配置在 +200% 单边牛市里只吃到 20% 收益——不只展示风控救命的一面

🔬 发布前对抗审查

新模块经一轮聚焦审查,修复 1 critical + 4 high + 2 medium:两引擎共享存档静默覆盖对方熔断状态(critical)、NaN 权益毒化存档、reset_breaker() 崩溃窗口、RiskMonitor 重启后重复拉响 kill-switch 等(详见 CHANGELOG)。

730 项测试全绿。建议所有用户升级。

⚡ 升级

pip install -U "riskguard @ git+https://github.com/SilentFleetKK/riskguard.git"

RiskGuard v1.2.0 — 配置预设 + 命令行工具

配置预设 + 零依赖命令行——不想逐个调参?挑一档起步,或直接在终端一键验单。

🎚️ 三档预设

from riskguard import get_preset, RiskEngine
engine = RiskEngine(get_preset("conservative"))   # 或 "balanced" / "aggressive"

三档在每个风险维度上单调不减,且激进档仍收敛在库自身认可的稳健范围内(Kelly ≤ 0.5)。净敞口三档均设上限——最激进档不再是唯一"净敞口不设限"的一档。

⌨️ 命令行(riskguard / python -m riskguard,纯标准库)

$ riskguard check --preset balanced --equity 100000 --side buy --qty 1000 --price 200
裁决:  RESIZE
放行:  BUY 50 ASSET  (占权益 10.0%)

$ riskguard presets                               # 三档参数对照
$ riskguard replay --prices 100,96,90,82,75,70    # 套风控 vs 不套 的回撤对比
$ riskguard replay --csv prices.csv --csv-column close

退出码:0 原样放行 · 3 放行但缩量 · 1 拒单 · 2 用法/输入/IO 错误。

🛡️ 发布前对抗式审查已修

经一轮多智能体审查,修复 1 critical + 3 high + 3 medium/low:CSV 静默篡改价格(千分位 1,250 被读成 250,已改用标准库 csv + 坏行告警)、文件错误崩栈、nan/inf 输入、激进档杠杆/净敞口口径不自洽等。698 项测试全绿。

⚡ 升级

pip install -U riskguard

RiskGuard v1.1.0 — 回测接线:把风控接进 backtesting.py / vectorbt

回测接线 —— 把 RiskGuard 作为"风险叠加层"接进你已经在用的回测框架,让策略研究和爆仓防护第一次在同一条流水线上。连通量化五层积木的「回测 → 风控」两层。

🔌 新增

• RiskOverlay —— 框架无关的核心:目标持仓/权重 → 风控批准(或缩量)的下一步订单;approved_weight 供按权重再平衡的框架直接用;累计缩单/拒单/熔断/拦截统计。
• replay / compare —— 轻量价格重放器,一键跑"套风控 vs 不套风控"对比(非通用回测框架,只为看见/测试风控行为)。
• backtesting.py 适配器 make_riskguard_strategy —— 子类只写 signal() 返回目标权重,建平仓自动过风控(可选依赖 riskguard[backtesting])。
• vectorbt 辅助 risk_capped_weights / kelly_weights(纯函数,不装 vectorbt 也能用)+ from_signals_with_risk。
• examples/07 —— 双均线策略 + 风控叠加,展示同一段崩盘中缩单 2 次 + 熔断 1 次 + 拦下 1 次追高再入场三道防线齐出手(裸奔 −24% 回撤 vs 风控 −15.4%)。

🛡️ 发布前对抗式审查已修

回测模块经一轮多智能体对抗式审查,修复 1 critical + 3 high + 3 medium/low:适配器每 bar 叠单导致失控杠杆(最严重,已改为方向制建平仓)、坏 tick 崩溃、approved_target_weight 副作用双计、回撤/收益基线不一致、适配器现金双算等。675 项测试全绿。

⚡ 升级

pip install -U riskguard
pip install "riskguard[backtesting]"   # 用 backtesting.py 适配器时

RiskGuard v1.0.1 — 修复第二轮审查的 fail-open 边界

第二轮独立对抗式审查发现并修复的 fail-open 边界——对一个"防爆仓"的库,这些正是最不能留的坑。

🔧 本版修复

• [高] NaN/inf 权益污染熔断:一次坏的权益读数(feed 抖动/除零)曾让 drawdown 恒算成 NaN、回撤熔断从此永不触发。现在非有限权益被直接忽略,熔断继续按最后有效权益工作。
• [高] 爆仓时误拒减仓:equity<=0 曾无条件拒单,连手动平仓的 reduce_only 单也被拦——违反"减仓永远放行"。现已把减仓放行提到 equity 判断之前。
• [中] max_net_exposure_pct 死配置:新增并接入 NetExposureLimit,净敞口(方向性风险)上限真正生效。
• [中] 审计异常中断风控:磁盘满等审计 IO 异常曾在锁内抛出、带崩 allow/deny 主判决。现统一 _safe_audit 兜底 + 可选 on_audit_error 回调。

reduce_only 现由 Broker 契约兜底执行(只减不增),风控规则据此统一放行减仓。

661 项测试全绿(新增 6 项针对本轮修复的回归测试)。建议所有用户升级。

RiskGuard v1.0.0 — 给交易系统配一个永不情绪化的风控官

给你的交易系统,配一个 7×24、永不情绪化的风控官。

量化五层积木(数据→研究→回测→风控→执行)里,唯独风控层没有开源标准件。RiskGuard 来补这块空白——把"提前写死的纪律"做成券商无关、核心零依赖的库,让系统在你情绪失控时替你踩刹车。

🔥 一句话说明它的价值

同一段 −45% 的崩盘、同一个满仓信号:裸奔账户最大回撤 −45%,套上 RiskGuard(10% 上限 + 15% 熔断)只有 −5.6%。数字来自可复现的 examples/06_with_vs_without.py,是仓位纪律的机械结果,不是收益承诺。

🧱 本版能力

• 四道风控闸门:单笔仓位上限 · 回撤熔断(减仓永远放行)· 新策略隔离 · 组合总敞口
• 动态下注:固定比例 / 分数 Kelly / 波动率目标(无正期望自动不下注)
• 券商抽象:内置纸面模拟盘(带滑点+手续费)· Alpaca 适配器
• 防篡改审计:JSONL/SQLite 哈希链,可选 HMAC 防伪 + expected_count 防尾部截断
• 实时哨兵:RiskMonitor 触线自动熔断并平仓(kill-switch)

🛡️ 工程质量

• 核心零第三方依赖,数据模型全部不可变
• 654 项测试全绿;经一轮多智能体对抗式审查,修复 3 个 critical + 4 个 high 缺陷(反手绕过熔断、reduce_only 未执行、审计防篡改边界、并发竞态等)并加回归测试钉死

⚡ 安装

pip install riskguard              # 核心零依赖
pip install "riskguard[alpaca]"    # 需要 Alpaca 适配器时

⚠️ 免责

风险控制工具,非投资建议,不保证盈利或防止亏损。任何策略先在模拟盘养满三个月,真钱只用亏光也不影响生活的闲钱。本项目不附带、也不宣称任何实盘战绩。