桌面智能体 (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