# GLW-VIS-000 · 光湖桌面视觉见证器 · 架构规范

> HLDP://world-architecture/projects/guanghu-visual-witness
> 固定编号: GLW-VIS-000
> 父系统: SYS-GLW-RD-0001
> 配套技能: SK-DEV-001
> 日期: 2026-07-02
> 状态: 语言架构完成 · 实体程序待开发
> 模型策略: 全部API调用 · 本地不安装大模型

---

## 1. 定义

光湖视觉见证器是安装在用户电脑上的轻量本地桥梁。

它让获得授权的人格体能够:

- 看见指定桌面软件的真实窗口
- 获取截图或短录屏
- 获取应用、窗口、版本和构建信息
- 调用云端视觉API
- 形成绑定研发步骤的证据包

它不负责模型推理，不保存模型权重。

---

## 2. 为什么不能只用编程AI自带视觉

不同Agent能力不同:

- 有的能读用户上传图片
- 有的只能读文件
- 有的能控制浏览器但不能看桌面
- 有的没有视觉模型
- 有的会话结束后失去截图上下文

视觉见证器把桌面观察能力放在用户自己的节点上，
使多个Agent共享同一套真实证据，而不是各自猜测。

---

## 3. 本地组件

```text
GLW-VIS-000
├── Capture Service
│   ├── 指定窗口截图
│   ├── 指定区域截图
│   └── 短时录屏
├── Window Inspector
│   ├── 应用名称
│   ├── 窗口标题
│   ├── 进程/版本
│   └── 可访问性控件树（授权后）
├── Privacy Guard
│   ├── 窗口白名单
│   ├── 截图前预览
│   ├── 敏感区域遮罩
│   └── 明显录制指示
├── HLDP Local Gateway
│   ├── 请求
│   ├── 临时令牌
│   └── 多Agent适配
├── Vision Router
│   ├── SC-004 Qwen-VL
│   └── 未来其他视觉API
└── Evidence Writer
    ├── RD-EVD
    ├── 内容哈希
    └── Git/研发仓库回执
```

---

## 4. API视觉策略

现有仓库:

```text
SC-004 = ALIYUN_QWEN_VL_KEY · 视觉理解
SC-005 = ALIYUN_WANXIANG_KEY · 当前登记为万相视频生成
```

因此V1默认使用Qwen-VL。

禁止:

- 把视频生成API当视觉理解API
- 下载本地视觉模型
- 要求用户配置GPU
- 把API密钥交给外部Agent

视觉见证器只通过个人节点密钥代理调用API。

---

## 5. 跨Agent请求

请求示例:

```hldp
@visual_request:
  request_id: VIS-REQ-...
  persona_id: RD-P-...
  visible_step_id: RD-VSTEP-...
  capture_scope: selected-window
  application: Guanghu Desktop Dev
  purpose: 验证第二个文本块已经出现并可编辑
  expires_at: ...
```

响应:

```hldp
@visual_result:
  evidence_id: RD-EVD-...
  image_hash: ...
  window_metadata: ...
  model_result: PASS|FAIL|UNCERTAIN
  findings: []
```

---

## 6. 权限

默认:

- 不允许全桌面持续捕获
- 不允许后台静默录屏
- 不允许读取未授权窗口
- 不允许保存与当前RD-VSTEP无关的画面
- 不允许外部Agent直接获取长期密钥

用户可以授权:

- 单次截图
- 当前窗口会话
- 指定应用在本次研发任务期间

任何授权都可以立即撤销。

---

## 7. 证据真实性

RD-EVD至少绑定:

- screenshot/video内容哈希
- captured_at
- application/window
- application_version
- build_id
- commit
- RD-VSTEP
- 视觉API结果
- 人格体复核
- 人类决定

截图与构建不一致时证据无效。

---

## 8. 本地资源目标

因为不运行大模型，V1目标:

```text
安装包: 约30~100MB
待机内存: 约50~150MB
独立显卡: 不需要
持续录屏: 默认关闭
网络: 仅验收时调用用户配置的视觉API
```

这些是设计目标，不是已完成产品实测数据。

---

## 9. 平台路线

### macOS

- ScreenCaptureKit或系统截图能力
- Accessibility API（可选）
- 屏幕录制权限

### Windows

- Windows Graphics Capture
- UI Automation（可选）
- 明确的捕获状态提示

先做一个平台MVP，再抽象统一接口。

---

## 10. MVP范围

只实现:

1. 用户选择一个应用窗口。
2. Agent通过HLDP请求单次截图。
3. 本地显示授权提示。
4. 截图后调用SC-004 Qwen-VL。
5. 绑定build/commit/RD-VSTEP。
6. 生成RD-EVD。
7. 人类在研发主控台选择“符合预期/需要修改”。

不做:

- 全自动桌面控制
- 长时间录屏
- 任意鼠标键盘操作
- 本地模型
- 无边界Shell权限

---

## 11. 与研发主控台的关系

```text
GLW-RD-000 研发主控系统
→ SK-DEV-001 定义人类可见步骤
→ GLW-VIS-000采集现实证据
→ RD-EVD写回
→ 主控台更新进度
→ 解锁或打回下一步
```

---

> ⊢ 视觉见证器不是监控软件。
> ⊢ 它是用户主动授权、人格体按任务取证、模型走API的研发验收桥梁。