Metadata-Version: 2.4
Name: astrbot-proactive-core
Version: 0.1.0
Summary: Shared queue and safety primitives for AstrBot proactive chat plugins.
Project-URL: Repository, https://github.com/yurisachan16-creator/astrbot_proactive_core
Project-URL: Issues, https://github.com/yurisachan16-creator/astrbot_proactive_core/issues
Author: aitwo
License: MIT
License-File: LICENSE
Keywords: AstrBot,plugin core,proactive chat,queue
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.15.13; extra == 'dev'
Description-Content-Type: text/markdown

# astrbot_proactive_core

AstrBot 主动消息插件的共享核心库。

这个仓库只放稳定、可复用、跨插件共享的底层能力，不绑定 QQ、Discord、Telegram，也不直接依赖 `yurisa-Hermes`。

当前 v0 能力：

- SQLite 持久化任务队列。
- 全局并发、按任务类型并发、按会话串行处理。
- 任务状态和投递状态分离。
- 对外安全的失败码和错误脱敏工具。

设计边界：

- 插件只能通过公开 facade 使用队列。
- storage、worker、payload 细节先保持内部实现。
- 后续 `astrbot_plugin_proactive_chat`、TTS/STT 插件和其他主动行为插件都可以复用这里的协议。

## 安装

本地开发：

```bash
cd /path/to/astrbot_proactive_core
uv sync --extra dev
uv run python scripts/smoke_check.py
uv run --extra dev pytest -q
uv run --extra dev ruff check .
```

作为依赖安装：

```bash
pip install 'astrbot-proactive-core>=0.1.0,<0.2.0'
```

如果还没有发布到 PyPI，可以先用 Git URL 或本地路径安装，再安装依赖它的 AstrBot 插件。

## 公共 API

当前对外稳定 API：

- `SQLiteQueue`
- `JobState`
- `DeliveryState`
- `JobRecord`
- `safe_failure_code`
- `redact_public_detail`

`SQLiteQueue.status_counts()` 可用于管理命令或 WebUI 展示队列状态。
