# KVM-Privacy 项目配置

## 语言规则
- 所有交互使用中文（代码注释、变量名、类名保持英文）
- 技术术语可使用英文原文
- Git commit 消息使用英文

## 项目概述
KVM-Privacy 是一个基于 KVM-over-IP 的三层隐私保护系统，运行在 NanoPC-T6 (RK3588) 上。

### 核心服务

| 服务 | 端口 | 说明 |
|------|------|------|
| KVM Server (Go) | 8080 | KVM 控制 + React WebUI |
| info-privacy-rs (Rust) | 8001 | RKNN PII 检测 |
| mem-bridge router | 8002 | AI 路由服务 |
| mem-bridge memory | 8003 | 会话存储 + FAISS 向量搜索 |
| Privacy Gateway (Python) | 8888 | mitmproxy 网络拦截 |

### 架构

```
用户 → KVM WebUI → KVM Server (Go)
                      ├── 视频流（隐私遮蔽）
                      ├── HID 控制（键盘/鼠标）
                      ├── OCR 扫描（RKNN）
                      └── KVM Agent（自主操作）
                            ├── 本地感知（OCR + logodetect）
                            ├── LLM 规划（gpt-4o / 本地模型）
                            ├── 操作验证（前后截屏对比）
                            └── 记忆系统（mem-bridge）
```

## 目录结构

```
services/
  kvm_agent/          # Python - KVM AI Agent
  privacy_gateway/    # Python - mitmproxy 隐私网关
KVM/                  # Git submodule - Go KVM 服务端
deps/                 # Git submodules - 依赖项目
deploy/systemd/       # systemd 服务文件
```

## 编码规范
- Python：asyncio + httpx，类型注解，dataclass 优先
- 异步优先：所有 I/O 操作使用 async/await
- 错误处理：finally 块中释放资源（HID 控制、隐私模式）
- 测试：pytest + pytest-asyncio，mock 外部依赖
- 配置：YAML 文件 + 环境变量，dataclass 承载

## 测试方法论

### 严格的 action→screenshot→verify 工作流

所有 KVM HID 测试必须遵循：
1. **执行操作** — 调用 mouse_ops/kvm 方法
2. **等待** — `await asyncio.sleep()` (0.5s-3s)
3. **截图** — `await kvm.screenshot()`
4. **OCR 验证** — `ocr_snapshot_raw()` + `check_text()`
5. **记录证据** — `collector.save_screenshot()` + `collector.record()`
6. **下一操作** — 仅验证通过后继续

### 禁止推理替代验证

- 不得基于 Claude 对 Windows 界面的知识判断操作结果
- 不得跳过截图/OCR 步骤
- 每个 assert 必须基于 `ocr_result`、`pixel_diff` 或 `screenshot` 的实际数据
- 测试修复必须基于 verify_live.py 的实际运行输出

### 优先使用 StepVerifier

StepVerifier.verify_action() 封装完整循环：
action → sleep → screenshot → OCR → semantic assert

### pixel_diff 的局限

- 时钟变化 ~24% diff — 不能用于判断"操作成功"
- 仅用于判断"屏幕是否变化"
- OCR 语义验证 > 像素对比

## 架构决策：鼠标优先

### 背景
实机测试暴露组合键系统性风险：Alt+F4 触发关机、Win+D 二次触发恢复窗口、IME 拦截 Enter/Space。

### 规则
- **safety.py 白名单**：只允许 20 个单键，所有组合键一律禁止
- **mouse_ops.py**：所有操作通过鼠标+OCR 完成
- **LLM 提示词**：不提供 shortcut action type
- **翻译层**：agent._shortcut_to_mouse() 将 Alt+F4→close_window 等

### 安全键 (允许)
escape, enter, tab, backspace, delete, space, up/down/left/right, shift, f1-f5, f11, f12

### 鼠标等价操作
| 组合键 | 鼠标替代 |
|--------|---------|
| Alt+F4 | mouse_ops.close_window() |
| Win+D | mouse_ops.show_desktop() |
| Win+R | mouse_ops.launch_from_taskbar() |
| Ctrl+S | mouse_ops.click_element("保存") |

## 常用命令

```bash
# 运行 KVM Agent 单次任务
python -m kvm_agent --task "打开记事本" --kvm-url http://localhost:8080

# 运行测试
cd services/kvm_agent && python -m pytest tests/ -v

# 查看服务状态
systemctl status kvm-agent mem-bridge-memory mem-bridge-router info-privacy privacy-gateway

# 设备连接
ssh pi@192.168.123.181
```

## 目标设备
- 硬件：NanoPC-T6 (RK3588, 8核 ARM64, 6 TOPS NPU)
- 系统：Debian/Ubuntu ARM64
- Python：3.12.3
- Go：1.22+
- NPU：rknn-toolkit-lite2 2.3.2

## 已知限制

| 类别 | 状态 | 说明 |
|------|------|------|
| 安全模型 | ✅ 良好 | 三层防护，白名单模式，Unicode NFKC 归一化 |
| 鼠标优先 | ✅ 完成 | mouse_ops + LLM 提示词 + agent 翻译层 |
| 多 UI 状态 | ✅ 完成 | screen_state.py 检测 BIOS/锁屏/睡眠/桌面 |
| 测试覆盖 | ✅ 良好 | safety/screen_state/mouse_ops 单元测试 + integration |
| 隐私截图 | ❌ 未实现 | Go 端 privacy mode 不影响截图内容 |
| test_integration 一致性 | ⚠️ 部分 | 清理代码已迁移到 mouse_ops，测试目标仍用原始组合键 |