# CompanionGuard-RL — 项目宪法

> **目标期刊**：SCI Q1/Q2（Information Processing & Management / Expert Systems with Applications）
> 这份文件是所有 AI 助手会话的首要参考，优先级高于任何对话中的临时指令。

---

## 项目目标

为 AI 情感陪伴场景构建**检测 + 干预**一体化安全流水线，解决两个核心缺口：
1. 现有 guard 模型（Llama Guard、WildGuard）只检测、不干预——不知道该对高风险输出做什么
2. 通用安全模型对伴侣特有风险（依赖强化、孤立强化、浪漫化、危机不响应）系统性漏检

---

## 架构

```
输入 X = (Persona P, History H, User u_t, AI Response r_t)
              ↓
   [Module B: Context-aware Risk Detector]
   backbone: hfl/chinese-macbert-large + CrossAttention
              ↓
   D = (y_risk, l_risk 0-4, c_primary R1-R10, c_fine 14标签)
              ↓
   s_t = StateEncoder(D, e_H_pool, e_P_pool, t_norm)  ← obs_dim = 2065
              ↓
   [Module C: RL Intervention Policy π (BC + PPO)]
              ↓
   a_t ∈ {PASS, WARN, REWRITE, REJECT, CRISIS}
```

---

## 模块状态

| 模块 | 状态 | 关键指标 |
|------|------|---------|
| 数据集 CompanionRisk-Bench v4 | ✅ | 9,896 样本，14 标签全覆盖（train 6,926 / dev 1,484 / test 1,486） |
| Module B 检测器 v4 | ✅ | binary_f1=**0.9995**, FNR=0.00%, level_weighted_f1=0.559 |
| Module B 泛化验证 | ✅ | human subset binary_f1=0.9848，无同源过拟合 |
| Module C v3（当前） | ⚠️ | safety_recall=1.0 ✅，over_refusal=0.004 ✅，action_accuracy=**0.575** ❌，crisis_precision=**0.421** ❌ |
| Module C v5（下一步） | 🔄 | reward 重写 + 环境修复，**见 `change.md` 完整路线** |
| 论文写作 | 🔄 | LaTeX 框架已搭建（`paper/`），方法节完整，结果节等 v5 + SOTA baseline |

> **Module C 尚未完成**。v3 的 action_accuracy 和 crisis_precision 均未达标，需要按 `change.md` 执行 v5。
> **投稿前必补实验**：① Llama Guard v2 / WildGuard 评估（Module B SOTA 对标）；② LLM-as-judge baseline（Module C）；③ 消融实验（BC-only / 无 CrossAttention）。

---

## Red Lines（关键规则，违反必出 bug）

| # | 规则 | 违反后果 |
|---|------|---------|
| 1 | **PyYAML 陷阱**：配置文件 lr 必须写 `0.001`，禁止写 `1e-3` | PyYAML 6.x 将 `1e-3` 解析为字符串，训练静默失败 |
| 2 | **NCCL 环境变量**：RTX 5090 训练必须加 `NCCL_SHM_DISABLE=1 NCCL_P2P_DISABLE=1` | NCCL 通信报错崩溃 |
| 3 | **Module C 只能单 GPU**：PPO 阶段禁止多卡 | `torch.distributed.barrier()` 在 RTX 5090 引发 CUDA illegal memory access |
| 4 | **状态向量用 `det_l_risk`**：preprocessing.py 和 evaluate.py 必须用检测器预测的风险等级，不能用 ground truth `l_risk` | train/eval 不一致，指标虚高 |
| 5 | **obs_dim = 2065 固定**：`[d_score(1) + l_risk_onehot(5) + c_primary_probs(10) + e_H_pool(1024) + e_P_pool(1024) + t_norm(1)]` | 维度不匹配崩溃 |
| 6 | **BC 阶段用 CPU tensor 再构建 DataLoader**：`pin_memory=True` 要求 CPU tensor | RuntimeError: cannot pin cuda tensor |

---

## 文件地图

### 项目级（根目录）
| 文件 | 用途 |
|------|------|
| `state.md` | 当前进度快照（最新） |
| `change.md` | **Module C v5 完整技术路线**（待执行，含 13 项任务） |
| `exp.md` | 踩坑经验库（12 类，排查问题先查这里） |
| `experiments/eval_intervention_v3.json` | Module C 当前最佳结果（论文参考基准） |
| `experiments/eval_intervention_v4.json` | v3 重跑确认（数字相同，验证可复现） |
| `docs/` | 研究文档（研究框架、数据集设计、前期报告） |
| `paper/` | **论文 LaTeX 源码**（主框架已就绪，见 state.md §八） |

### 代码级（code/）
| 路径 | 用途 |
|------|------|
| `code/src/models/detector.py` | Module B 主模型 |
| `code/src/models/intervention_agent.py` | Module C Actor-Critic（obs_dim=2065→256→5） |
| `code/src/rl/reward.py` | 多目标奖励（**v5 需重写**） |
| `code/src/rl/companion_env.py` | 离线 RL 环境（**v5 需修复类别信号**） |
| `code/src/utils/preprocessing.py` | build_obs_vector（**必须用 det_l_risk**） |
| `code/configs/intervention_config.yaml` | Module C 训练配置 |
| `code/checkpoints/detector/best.pt` | Module B 最优权重（1.35GB，**frozen**） |
| `code/checkpoints/intervention/final_v2.pt` | Module C v3 权重（5MB，当前最佳） |

---

## 服务器速查

| | 服务器 1（主训练） | 服务器 2（当前使用） |
|--|--|--|
| SSH | `ssh -p 20083 root@10.82.3.180` | `ssh -p 20060 root@10.82.3.180` |
| 密码 | `m2dGcwyrhI` | `zwfn65xjTY` |
| Python 环境 | `/opt/conda/envs/dlapo-py310-cu128/bin` | `$PROJ/../env/dlapo-py310-cu128/bin` |
| GPU | 4 × RTX 5090 32GB | 2 × RTX 5090 32GB |

**服务器 1 $PROJ**：`/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL`
**服务器 2 $PROJ**：`/root/siton-data-740d234e02d749f08fe5347b0c74c49f/zsy/my-reasearch/companionguard-rl`
**MacBERT（两台）**：`$PROJ/../macbert-large`（服务器 2 在 `../zsy/macbert-large`）

### 上传代码（本地 → 服务器）
```powershell
scp -P 20083 -r `
  D:\Myresearch\CompanionGuard-RL\code\src `
  D:\Myresearch\CompanionGuard-RL\code\scripts `
  D:\Myresearch\CompanionGuard-RL\code\configs `
  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/
```

### 取回结果（服务器 → 本地）
```powershell
scp -P 20083 -r `
  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/experiments `
  D:\Myresearch\CompanionGuard-RL\

scp -P 20083 -r `
  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/checkpoints `
  D:\Myresearch\CompanionGuard-RL\code\
```