jaychouu/see_the_screen

桌面智能体 (Desktop Agent)

基于 DeepSeek Harness 架构设计的 Windows 本地桌面自动化控制软件。无需 GPU，通过视觉感知屏幕内容，结合 LLM 智能决策，自动操控鼠标键盘，并支持人类随时干预。

🚀 v2 架构（推荐）：决策由 DSH 智能体接管

v1 由 deepseek-provider 调用 DeepSeek API 完成决策（需要 API Key）。

v2 决策层已移交 DeepSeek Harness 的智能体本身——软件被做成一个
DSH 插件（harness-plugin/screen-ctrl.host.js），你在 DSH 会话里直接下达
任务，智能体自主调用桌面工具（截图 → 定位 → 点击 → 输入 → 验证）完成任务，
全程不再调用任何 LLM API，无需 API Key。

安装插件并开始使用：
1. 在 DSH 会话中运行 screen-ctrl 插件（cordis_define + cordis_run，
代码见 harness-plugin/screen-ctrl.host.js）
2. 插件注册 12 个桌面工具（screen_capture / desktop_click / desktop_type / ...）
3. 直接说任务，例如："打开记事本输入 Hello"、"帮我看看桌面有什么"

独立模式（脱离 DSH 运行，需 API Key）仍可用：编辑 config/bundle.yml，
将 plugins 列表改为加载 deepseek-provider 并配置 API Key。

✨ 核心特性

- 👁️ 视觉感知：实时截图 + OCR 文字识别，自动检测 UI 元素（按钮、输入框、菜单等）
- 🖱️ 桌面操控：虚拟鼠标点击/移动/拖拽/滚轮，键盘输入/快捷键，程序启动
- 🧠 智能决策：集成 DeepSeek API，通过 ReAct 循环（Thought → Action → Observation）自主推理
- 👤 人类协作：控制台/WebUI 实时输入、指令注入、随时中断
- 🛡️ 安全控制：全局急停热键、操作审批、步骤限制、自动超时保护
- 🌐 Web UI：内置 HTTP + WebSocket 服务，浏览器可视化控制台
- 🧩 插件架构：参考 DSH "一切皆插件" 设计，模块清晰可扩展

📋 系统要求

| 项目 | 最低要求 | 推荐配置 |
|------|---------|---------|
| 操作系统 | Windows 10/11 | Windows 11 |
| Node.js | ^22.19 或 >=24 | v22 LTS |
| 内存 | 8 GB | 16 GB |
| 硬盘 | 2 GB 空闲空间 | 10 GB SSD |
| 网络 | 需要（调用DeepSeek API） | 稳定宽带 |

🚀 快速开始

1. 安装依赖

cd "d:\AI工具\TRAE SOLO CN\屏幕控制软件"
npm install

2. 配置 DeepSeek API Key

方式 A：配置文件（推荐）
- 编辑 config/bundle.yml，将 deepseek-provider.apiKey 改为你的 key

方式 B：环境变量
- 复制 .env.example 为 .env，填入你的 key
- 或 PowerShell 执行：$env:DEEPSEEK_API_KEY="sk-你的key"

方式 C：命令行参数
npm start -- --api-key sk-你的key

💡 免费获取 API Key：https://platform.deepseek.com/

3. 启动运行

交互控制台模式（推荐）：
npm run dev

Web UI 模式（浏览器界面）：
npm run web
浏览器会自动打开 http://127.0.0.1:3000

直接执行单任务：
npm run dev -- "打开Chrome浏览器并访问百度"

🎮 使用方式

控制台命令

启动后输入以下命令与Agent交互：

| 命令 | 说明 | 示例 |
|------|------|------|
| help | 显示帮助 | help |
| status | 查看Agent状态 | status |
| tools | 列出所有工具 | tools |
| history [N] | 查看最近N条历史 | history 20 |
| run  | 执行新任务 | run 打开记事本写Hello |
| inject  | 注入紧急指令 | inject 先保存，不要关闭 |
| stop | 优雅停止任务 | stop |
| interrupt | 紧急中断 | interrupt |
| approval on/off | 开关操作审批 | approval on |
| safety | 查看安全状态 | safety |
| approve / reject | 审批/拒绝操作 | approve |
| clear | 清除历史记录 | clear |

直接输入文字 = 直接作为任务执行 Agent

Web UI 功能

- 📊 实时状态面板：运行状态、步骤数、插件列表
- 🎯 任务输入框：发送新任务（带快捷 chip 提示）
- 📜 运行日志区：彩色角色标记区分 user/assistant/tool/system
- ⚙️ 快捷命令面板：一键执行常用命令
- 🛠️ 工具列表面板：查看所有可用工具说明
- 🔌 WebSocket 实时推送：事件实时同步

🧩 架构设计

Desktop Agent (DSH Plugin Style)
├── Core (核心框架)
│   ├── Context              插件容器 + 服务注册 + 状态管理
│   ├── PluginLoader         从bundle.yml加载所有插件
│   └── ReActLoop            Thought-Action-Obs 循环调度
│
├── Plugins (插件 - 各司其职)
│   ├── desktop-vision       视觉感知
│   │   ├── screenshot()     截图 + 变化检测
│   │   └── find_element()   查找文字/类型UI元素
│   │
│   ├── desktop-control      操控执行
│   │   ├── click()          鼠标点击/双击/左中右
│   │   ├── move_mouse()     移动光标
│   │   ├── drag_mouse()     拖拽
│   │   ├── scroll()         滚轮
│   │   ├── type_text()      输入文字（含中文剪贴板方式）
│   │   ├── press_key()      按键/快捷键 (ctrl+c, alt+f4...)
│   │   ├── launch_app()     启动程序/打开URL
│   │   ├── run_command()    执行cmd命令
│   │   └── wait()           等待延迟
│   │
│   ├── harness-agent        LLM决策（v2：移交 DSH 智能体）
│   │   └── chat()           不再调用 LLM API，返回 DSH 接管指引
│   │
│   ├── (deepseek-provider)  LLM决策（v1 独立模式，可选，需 API Key）
│   │   └── chat()           DeepSeek API + 流式 + Function Calling
│   │
│   ├── human-intervention   人类协作
│   │   ├── 控制台命令       stop/inject/run/...
│   │   └── 指令注入机制     打断当前推理链
│   │
│   └── safety-guard         安全控制
│       ├── 信号监听         Ctrl+C → 优雅停止
│       ├── 操作审批         高风险操作需确认
│       ├── 步骤限制         防止死循环
│       └── 超时保护         自动停止长任务
│
└── Interfaces (交互界面)
├── CLI (readline)       命令行交互
└── Web UI (Express+WS)  浏览器控制台

ReAct 循环流程

┌─────────────────────────────────────────────────────┐
│  ① 检查中断  →  ② 截图+变化检测  →  ③ OCR+UI检测    │
│         ↓                                            │
│  ⑦ 等待UI反馈 ←  ⑥ 执行动作 ←  ⑤ LLM推理决策        │
│         ↓                                            │
└─────────────→  ④ 构建文字状态描述（给LLM） ←─────────┘

🛠️ 所有工具一览

Agent 可自动调用以下工具：

| 工具 | 说明 |
|------|------|
| screenshot | 截取屏幕，返回检测到的UI元素列表（文字+坐标+类型） |
| find_element | 按文字/类型查找屏幕元素 |
| click | 在指定坐标点击鼠标（支持左中右、双击） |
| move_mouse | 移动鼠标到指定位置 |
| drag_mouse | 从A点拖拽到B点 |
| scroll | 滚动鼠标滚轮（上下左右） |
| type_text | 在当前焦点输入文字 |
| press_key | 按单个键或组合键 |
| press_hotkey | 按下指定组合键数组 |
| launch_app | 启动程序或打开URL |
| run_command | 执行Windows命令（需审批） |
| wait | 等待指定毫秒数 |

👁️ 可视化操作反馈

Agent 真实操控电脑时，可通过以下方式直观看到它的鼠标动作（config/bundle.yml → desktop-control 配置）：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| animateMouse | true | 鼠标移动动画：光标沿路径平滑滑动（false = 瞬移） |
| mouseMoveSteps | 30 | 移动动画步数（越大越平滑） |
| mouseMoveDelayMs | 10 | 每步间隔毫秒（越大移动越慢、路径越清晰） |
| clickPreviewDelayMs | 350 | 点击前在目标位置悬停预览毫秒数 |
| showClickRing | true | 点击后显示红色反馈圆环 |
| showDragLine | true | 拖拽时显示橙色路径连线 + 起终点圆点 |

如需全速执行（不看动画），将 animateMouse: false 并调低 clickPreviewDelayMs: 0 即可。

🚨 安全说明

⚠️ 此软件可控制你的电脑，操作前请注意：

1. 首次使用建议在虚拟机/沙箱中测试，确认行为符合预期
2. 开启 操作审批：输入 approval on 让高风险操作先确认再执行
3. 急停方法：
- Ctrl + C → 优雅停止（推荐）
- 控制台输入 interrupt → 立即中断
- 任务管理器 taskkill /PID  /F → 强制结束
4. 本软件默认不操作真实物理鼠标光标（使用虚拟SendInput API），但部分版本robotjs会移动光标
5. 切勿在包含重要未保存数据的环境中长时间无人值守运行

📚 参考资源

- DeepSeek Harness 官方仓库: https://github.com/deepseek-ai/deepseek-harness
- DSH 中文教程: https://github.com/ht426/deepseek-harness-tutorial
- Qwen Function Calling 模型: https://huggingface.co/amgustav/toolchain-qwen2.5-3b-function-calling
- AutoGUI 桌面Agent: https://www.billmongan.com/software/autogui/

📁 项目结构

屏幕控制软件/
├── config/
│   └── bundle.yml          # 插件组合配置（v2 默认 harness-agent）
├── harness-plugin/
│   ├── screen-ctrl.host.js # ★ DSH 插件源码：桌面工具集（决策由 DSH 智能体接管）
│   └── README.md           # 插件安装/使用说明
├── src/
│   ├── core/               # 核心框架
│   │   ├── types.ts        # 类型定义
│   │   ├── plugin-loader.ts
│   │   └── react-loop.ts   # ReAct循环
│   ├── plugins/            # 插件（harness-agent / desktop-vision / desktop-control / ...）
│   │   ├── harness-agent/      # v2 决策层（移交 DSH 智能体）
│   │   ├── desktop-vision/
│   │   ├── desktop-control/
│   │   ├── deepseek-provider/  # v1 独立模式（可选）
│   │   ├── human-intervention/
│   │   └── safety-guard/
│   ├── index.ts            # CLI入口
│   └── server.ts           # Web UI入口
├── package.json
├── tsconfig.json
└── 技术文档.docx           # 原始技术方案

🧪 开发与调试

安装依赖
npm install

编译TypeScript
npm run build

CLI 开发模式（tsx热运行）
npm run dev

编译后运行CLI
npm start

Web UI开发模式
npm run web

构建 + 运行
npm run build ; npm start -- "打开记事本"

📝 许可证

参考 DeepSeek Harness：MIT License