# CompanionGuard-RL

为 AI 情感陪伴场景构建**检测 + 干预**一体化安全流水线，目标期刊 SCI Q1/Q2（IP&M / ESWA）。

---

## 系统架构

```
输入 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}
```

**Module B frozen**：已达 binary_f1=0.9995，不再迭代。

---

## 不变量

违反这些规则会导致训练崩溃或结果在概念上错误，**不得绕过**。

| 规则 | 原因 |
|------|------|
| `obs_dim = 2065` 固定 | `1+5+10+1024+1024+1`，改动导致维度不匹配崩溃 |
| 状态向量用 `det_l_risk`，不用 GT `l_risk` | GT 在部署时不可得；用 GT 导致 train/eval 不一致，指标虚高 |
| Module C 训练只能单 GPU（`--num_processes=1`） | RTX 5090 上 `torch.distributed.barrier()` 触发 CUDA illegal memory access |
| BC 阶段 tensor 保持 CPU 直到 `accelerator.prepare()` | `DataLoader(pin_memory=True)` 不支持 CUDA tensor |
| Module B 权重 frozen，不参与 Module C 训练 | 检测器是 offline 预处理阶段，不是可微组件 |

---

## 行为准则

### 结果异常：立即暂停并报告
- 任何运行结果与预期明显不符（指标异常高/低、loss 不收敛、输出格式错误）→ 立即停止后续步骤，说明异常现象，不得假设"可能正常"后继续
- eval 数字在两次运行间出现差异 → 先找原因，不得直接取较好的那次结果
- 代码修改后指标反而大幅提升 → 优先怀疑 data leakage 或 bug，而非庆祝

### 不可逆操作：执行前明确确认
- 删除或覆盖任何文件（checkpoints、experiments/*.json、data/processed/）→ 必须先告知用户将要做什么，得到确认后再执行
- 服务器上的写入 / 覆盖操作 → 操作前说明目标路径和影响范围
- 重新训练 Module B → 需明确讨论（权重 1.35GB、GPU 数十小时，论文结果依赖 frozen 权重）

### 范围纪律：只做被要求的
- 修复 bug 时不顺手重构周边代码
- 改一处配置时不改动其他超参数
- 不引入未被要求的功能、抽象或依赖

### 研究诚信
- 论文中的数字必须可追溯到具体实验文件（experiments/*.json）和 checkpoint，不得凭记忆或估算填写
- `experiments/` 下的历史结果文件只读；需更新结果时生成新文件（如 `eval_intervention_v5.json`），不覆盖旧文件
- 数据集 v4（`data/processed/CompanionRisk-Bench/`）已冻结，不得修改任何样本
- 报告结果时不选择性省略不利指标（当前 action_accuracy、crisis_precision 未达标，必须如实陈述）

### 基础设施变动：立即记录
服务器修复、重置、存储重挂载等事件发生后，必须同步更新以下内容，**不得拖到下次出问题才修**：
- `state.md` 服务器速查表（SSH 命令、认证方式、存储 UUID、代理端口）
- `record.md` 补变更条目（变了什么、影响哪些文件、教训）
- 所有含绝对路径的 config 文件（`configs/intervention_config.yaml`、`configs/detector_config_server.yaml`）——先在服务器上确认新路径，再同步本地

典型触发场景：存储 UUID 变更、SSH 密钥更换、代理端口变化、Python 环境路径变化。

### 歧义：询问而非假设
- 当操作会影响实验结果或论文内容，且需求存在歧义时，先问清楚再动手

---

## 论文论点

**核心主张**：现有 guard 模型（Llama Guard、WildGuard）只检测不干预，且对 companion-specific 风险系统性漏检。CompanionGuard-RL 在检测基础上学习分级干预动作。

**三个贡献**：
1. CompanionRisk-Bench（9,896 样本）+ 10 类风险分类体系
2. Module B：上下文感知检测器，binary_f1=0.9995，FNR=0
3. Module C：RL 自适应干预策略，safety_recall=1.0（rule baseline 0.908）

**当前 limitation**（不能回避，在 discussion 节正面陈述）：
- action_accuracy=0.575（目标 ≥0.70），L1 过激主因
- crisis_precision=0.421（目标 ≥0.80），R1 样本稀少主因

---

## 文档导航

| 文件 | 内容 | 何时查阅 |
|------|------|---------|
| `state.md` | 当前模块状态、v5 执行计划、训练命令 | 每次开始工作前 |
| `record.md` | 历史变更、bug 修复记录、完整实验结果 | 需要了解某个决策来龙去脉时 |
| `exp.md` | 环境问题与解决方案（NCCL、PyYAML、依赖等） | 遇到运行时错误时 |

**更新规则**：代码改动 → `state.md` + `record.md`；环境/崩溃问题 → `exp.md`；架构或不变量变化 → `CLAUDE.md`；**服务器基础设施变动**（UUID、认证、代理）→ `state.md` + `record.md` + `CLAUDE.md` 服务器节。

---

## 代码结构

```
code/
├── src/
│   ├── models/detector.py            # Module B（frozen）
│   ├── models/intervention_agent.py  # Module C Actor-Critic
│   ├── rl/reward.py                  # v5 label-aligned constrained reward
│   ├── rl/companion_env.py           # 单步 MDP 离线环境
│   ├── rl/ppo_trainer.py             # PPO 训练器
│   └── utils/preprocessing.py       # build_obs_vector（用 det_l_risk）
├── scripts/
│   ├── train_intervention.py         # BC + PPO 主训练脚本
│   └── evaluate.py                   # 多基线评估（支持 --bc-ckpt ablation）
├── configs/
│   └── intervention_config.yaml      # 训练配置（use_wandb: false）
└── tests/
    ├── test_reward_v5.py
    └── test_intervention_metrics.py
```

---

## 服务器

```
# 连接（别名或完整命令）
ssh server5090
ssh -p 20083 -i C:/Users/张思远/.ssh/ai_tunnel_key root@10.82.3.180

# 路径
$PROJ   = /root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL
MacBERT = $PROJ/../macbert-large
Python  = /opt/conda/envs/dlapo-py310-cu128/bin/
GPU     = 4 × RTX 5090 32GB

# 认证
密钥文件: C:\Users\张思远\.ssh\ai_tunnel_key  (ED25519，2026-05-19 配置)
SSH config 别名: ~/.ssh/config → Host server5090

# 代理（服务器无外网，使用本地隧道转发）
服务器内 http_proxy=http://127.0.0.1:7890  用于 pip/curl
验证隧道: netstat -tlnp | grep 7890  → 应有 127.0.0.1:7890 LISTEN

# 存储 UUID（服务器修复/重置后可能变更，需同步更新 configs/ 绝对路径）
当前 UUID: siton-data-2849d4ce327c4ccfb233ce33868fe7fe  (2026-05-19 起)
旧 UUID:   siton-data-740d234e02d749f08fe5347b0c74c49f  (已失效)
```