Files

T

qiuruiandClaude Opus 4.6 5b50a6b1d3 feat: enhance testing discipline, security model, and multi-UI state support

- Add testing methodology and mouse-first architecture docs to CLAUDE.md
- Harden safety.py with Unicode NFKC normalization, newline injection
  detection, and 10K character length limit
- Create screen_state.py for detecting BIOS, lock screen, desktop, sleep
  states via screenshot hash analysis and OCR keyword matching
- Integrate ScreenStateDetector into agent.py run_task() loop
- Centralize desktop/app keyword constants in screen_state.py
- Add 47 new unit tests (test_screen_state, test_mouse_ops, test_safety
  edge cases)
- Migrate test_integration.py cleanup code from combo keys to mouse_ops
- Fix pre-existing test_shortcut_action test to match blocked behavior
- Add project evaluation table to CLAUDE.md known limitations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-03 02:54:10 +00:00

4.7 KiB

Raw Permalink Blame History

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 测试必须遵循：

执行操作 — 调用 mouse_ops/kvm 方法
等待 — await asyncio.sleep() (0.5s-3s)
截图 — await kvm.screenshot()
OCR 验证 — ocr_snapshot_raw() + check_text()
记录证据 — collector.save_screenshot() + collector.record()
下一操作 — 仅验证通过后继续

禁止推理替代验证

不得基于 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("保存")

常用命令

# 运行 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，测试目标仍用原始组合键

4.7 KiB Raw Permalink Blame History Unescape Escape