Metadata-Version: 2.4
Name: dracoocr-perception
Version: 0.1.0
Summary: DracoOCR 桌面感知插件 — 后台守护进程采集桌面状态写入 SQLite，通过 AgentHook 自动注入上下文到主 Agent
Author: Beichen890
License: MIT
Keywords: dracohub,agent,desktop-perception,dracoocr,sub-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

---
name: dracoocr.perception
description: 桌面感知插件 — 后台守护进程采集桌面状态写入 SQLite，通过 AgentHook 自动注入上下文到主 Agent
metadata:
  dracoocr:
    requires:
      bins:
        - "xdotool"
        - "xprintidle"
      env: []
    always: false
    tools:
      - "tools.py"
---

# DracoOCR 桌面感知插件

## 设计思路

本插件把桌面感知从「工具调用模式」改为「后台守护进程 + SQLite 存储 +
AgentHook 自动注入」架构，让主 Agent 无需手动调用工具即可感知桌面状态。

- **后台守护进程**（`PerceptionDaemon`）：daemon 线程默认每 30 秒采集一次
  桌面状态（窗口标题、进程名、空闲秒数、活跃状态），分类后写入 SQLite
  时间序列。跨平台降级：Linux（xdotool/xprintidle）、macOS（osascript/ioreg）、
  Windows（ctypes user32）。无可用工具时返回空值，不抛错。
- **SQLite 存储**（`PerceptionStore`）：时间序列表 `activities`，每条记录
  含 timestamp/window_title/process_name/category/idle_seconds/is_active。
  提供 `get_activity_stats(hours)` 查询近 N 小时统计。
- **AgentHook 自动注入**（`PerceptionHook`）：作为 AgentHook 注册到主
  Agent 的 hook 链，在 `before_iteration` 把当前桌面摘要注入 messages
  （默认每 5 次迭代注入一次，避免 token 浪费）。

## 跨平台采集

| 平台 | 窗口标题 | 进程名 | 空闲时间 |
|------|----------|--------|----------|
| Linux | `xdotool getwindowname` | `ps -p <pid> -o comm=` | `xprintidle` |
| macOS | `osascript` | `osascript` | `ioreg IOHIDSystem` |
| Windows | `GetWindowTextW` | `GetWindowThreadProcessId` | `GetLastInputInfo` |

## 分类规则

关键词匹配，三类：
- **entertainment**：bilibili、youtube、netflix、游戏、音乐、直播、抖音、微博等
- **work**：vscode、pycharm、terminal、git、office、docker、draco 等
- **other**：其余

## 提供工具

| 工具 | 作用 |
|------|------|
| `start_perception` | 启动后台守护进程（可配置间隔、空闲阈值、db 路径） |
| `stop_perception` | 停止守护进程 |
| `get_desktop_status` | 即时采集一次当前桌面状态（不写库） |
| `get_activity_stats` | 查询近 N 小时活动统计（供 proactive 读取） |
| `get_recent_activities` | 查询最近 N 条活动记录 |
| `get_perception_status` | 查询守护进程运行状态 |
| `clear_perception_data` | 清理历史数据（restricted） |

## 联动主动对话

主动对话插件 `dracoocr_proactive` 通过 `sys.modules` 软查找本模块的
`get_perception_store()`，拿到 `PerceptionStore` 后调用
`get_activity_stats(hours=2)` 读取活动统计用于触发检测。本插件未安装时
proactive 进入「无数据源」空转，不报错。

## AgentHook 注入

`PerceptionHook` 注入的 system 消息形如：

```
[桌面感知] 窗口「main.py - vscode」，进程 code，分类 work，已连续工作 30 分钟
```

默认每 5 次迭代注入一次，避免每次迭代都注入重复信息。可通过构造参数
`inject_every` 调整。

## 何时使用

当 DracoHub 需要让数字伙伴「看见」用户桌面状态时启用本插件。先
`start_perception` 启动守护进程，再把 `get_perception_hook()` 注册到
主 Agent 的 hook 链即可。
