Metadata-Version: 2.4
Name: dracoocr-proactive
Version: 0.1.0
Summary: DracoOCR 主动对话插件 — 联动桌面感知 SQLite 数据源，后台双系统引擎自动触发自然搭话
Author: Beichen890
License: MIT
Keywords: dracohub,agent,proactive-conversation,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
Provides-Extra: perception
Requires-Dist: dracoocr-perception>=0.1.0; extra == "perception"

---
name: dracoocr.proactive
description: 主动对话插件 — 联动桌面感知 SQLite 数据源，后台双系统引擎自动触发自然搭话
metadata:
  dracoocr:
    requires:
      bins: []
      env:
        - "DRACO_LLM_API_BASE"
        - "DRACO_LLM_API_KEY"
    always: false
    tools:
      - "tools.py"
---

# DracoOCR 主动对话插件

## 设计思路

本插件实现一套「双系统」主动对话引擎：

- **System1（即时）**：用户消息进来时做反馈检测（accept/reject/ignore），
  由 `ProactiveEngine.on_user_message()` 处理。
- **System2（后台巡检）**：daemon 线程每 120s 读一次桌面感知插件的
  SQLite 数据源，跑触发检测 → 思路缓冲 → 门控 → 策略选择 → LLM 生成 →
  回调投递。

只有 LLM 生成那一步消耗 token，其余判断全在本地完成。

## 联动桌面感知

通过 `_get_perception_store()` 在 `sys.modules` 里动态查找桌面感知插件
暴露的 `get_perception_store()`，拿到 `PerceptionStore` 句柄后调用
`store.get_activity_stats(hours=2)` 读取活动统计。桌面感知插件未安装时
返回 `None`，引擎进入「无数据源」空转，不会报错。

## 触发类型

| 触发 | 条件 | 策略映射 |
|------|------|----------|
| `long_work` | 连续工作 ≥ 120 分钟 | REMIND, CARE |
| `slacking` | 娱乐占比 ≥ 40% | TEASE, REMIND |
| `idle` | 无活动 ≥ 30 分钟 | CARE, CHAT |
| `late_night` | 23:00 后仍活跃 | CARE, REMIND |
| `morning_greet` | 07:00–10:00，每日一次 | GREET |
| `evening_greet` | 18:00–21:00，每日一次 | GREET |
| `periodic_chat` | 6 小时无互动 | CHAT, SHARE |

## 门控（5 条硬规则）

`GateKeeper.allow()` 依次检查，任一不通过即抑制：

1. 静默模式（`enter_silent_mode`）
2. 静默时段（`quiet_hours`，默认关闭）
3. 全局冷却（默认 600s）
4. 每日上限（默认 20 条）
5. 紧急度阈值（默认 0.15）

`ThoughtBuffer` 维护 60 秒合并窗口，短时间内的多个触发合并成一条消息，
按最高紧急度选策略。

## LLM 生成

`POST {api_base}/v1/chat/completions`，httpx 优先、urllib 回退。硬性约束：
1–3 句话、不超过 50 字、不用「检测到/监测显示」等监控感强的开头。

## 提供工具

| 工具 | 作用 |
|------|------|
| `check_triggers` | 检测当前触发条件，返回命中列表（不发消息） |
| `get_proactive_status` | 查询引擎运行状态与经验统计 |
| `start_proactive` | 启动后台巡检线程 |
| `stop_proactive` | 停止后台引擎 |
| `enter_silent_mode` | 进入静默模式（默认 2 小时） |
| `record_proactive_feedback` | 记录反馈用于经验学习 |
| `set_proactive_callback` | 按名称绑定消息回调 |

## 何时使用

当 DracoHub 需要让数字伙伴「主动开口」而非被动应答时启用本插件。
先 `start_proactive` 启动后台，再用 `set_proactive_callback` 绑定投递回调；
引擎会在合适时机自动生成一句话并通过回调投递。
