# 风险控制原理与风险代理设计

本文档梳理项目中的风险控制理念，覆盖风险代理的职责、数据需求、决策流程、日志策略与实施里程碑，为风控改造提供统一依据。

## 目标与定位

- 将 `RiskAgent` 从占位角色升级为具备实质决策能力的安全阀，保障所有交易建议在执行前通过风险复核。
- 提供回测与实盘一致的风险上下文，使补数、验证、告警等环节共享信息。
- 支持“风险否决 → 重新议程或减仓”的闭环，并将决策记录到数据库和可视化界面。

## 数据与信号

- **基础字段**：`risk_penalty`、`position_limit`、`is_suspended`、涨跌停状态等。
- **高级指标**：日内波动、VaR、行业集中度、黑名单或外部告警标签。
- **实时事件**：补数异常、执行失败、仓位越界等，需要通过 `DataBroker` 回调或交易执行层回传。
- **上下文结构**：在 `AgentContext.raw` 携带 `risk_flags`、`compliance_notes`，并在 UI 中展示。

## 决策流程

1. **风险评估阶段**  
   - 部门共识形成后触发 `risk_round`，由 `RiskAgent` 调整 `Decision.requires_review`、`target_weight` 等字段。  
   - 输出 `RiskAssessment` 数据（风险来源、建议动作、置信度），序列化进 `Decision.rounds`。

2. **执行协调阶段**  
   - 若风险建议为“冻结”或“减仓”，执行模块需遵循风险指令。  
   - 风险事件写入 `risk_events`（或同类表），供监控与审计使用。

3. **日志与监控**  
   - `risk_round` 应附加 `annotations`：违规指标、处置动作、证据引用。  
   - UI 与监控面板展示复核触发率、回滚成功率、风险热点等指标。

## 实施里程碑

1. **原型阶段（已完成）**  
   - 重构 `RiskAgent` 以返回策略建议。  
   - 扩展 `Decision` 结构新增 `risk_assessment`。  
   - `ProtocolHost` 将风险建议写入 `risk_round.notes`。

2. **集成验证（进行中）**  
   - 在回测环境构造停牌、仓位超限、黑名单等样例，验证闭环。  
   - 补充单元/集成测试覆盖典型风险场景。

3. **实盘准备（待启动）**  
   - 对接外部告警渠道（风控系统、合规接口等）。  
   - 统计复核频率、回滚动作、失败告警，形成运营指标。

4. **上线与迭代（待启动）**  
   - 影子运行对比建议与执行差异，收集风控策略表现。  
   - 依据反馈迭代规则、阈值与风险指标库。

## 后续关注

- 风险代理与执行模块的数据同步方式（数据库/消息队列）需明确。  
- 与合规团队协作确定阈值、回滚条件与审核流程。  
- UI 需支持展示风险建议原文、引用证据与执行结果。  
- 随业务扩展及时更新本原理文档，保持风险策略可解释、可追踪。