Metadata-Version: 2.4
Name: tiffany-hook-runtime
Version: 0.1.0
Summary: A raw-first, synchronous-lazy hook runtime
License-Expression: MIT
Project-URL: Repository, https://github.com/CyanReef/Tiffany
Project-URL: Issues, https://github.com/CyanReef/Tiffany/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets<17,>=16
Provides-Extra: benchmark
Requires-Dist: matplotlib<4,>=3.9; extra == "benchmark"
Provides-Extra: qqofficial
Requires-Dist: aiohttp<4,>=3.11; extra == "qqofficial"
Provides-Extra: openmetrics
Requires-Dist: aiohttp<4,>=3.11; extra == "openmetrics"
Requires-Dist: prometheus-client<1,>=0.22; extra == "openmetrics"
Provides-Extra: server
Requires-Dist: aiohttp<4,>=3.11; extra == "server"
Requires-Dist: prometheus-client<1,>=0.22; extra == "server"
Requires-Dist: qqbot-agent-sdk[qrcode]==1.2.2; extra == "server"
Dynamic: license-file

# Tiffany

**保留原始事件，按需读取字段，用 Hook 编写业务。**

Tiffany 是一个用 Python 编写的异步机器人运行时。接入层保存平台原始事件，核心负责路由、调度和资源生命周期；业务从一个异步函数开始，按需要组合字段、服务与扩展。

Python **3.11+** · **MIT** · 当前版本 **0.1.0**

[快速开始](#快速开始) · [核心设计](#核心设计) · [进阶扩展](#进阶扩展) · [性能复测](#性能复测) · [学习与开发](#学习与开发) · [文档导航](docs/README.md)

## 项目能做什么

| 接入方式 | 当前支持 | 启动入口 |
| --- | --- | --- |
| OneBot 反向 WebSocket | 接收事件、调用 API、回复消息；默认配置适配 NapCat | `bash start.sh` 首次选择 OneBot |
| QQ 官 Bot WebSocket | 群聊/C2C/频道消息；Markdown、按钮、富媒体上传、撤回和 C2C 流式接口；终端扫码配置 | `bash start.sh` 首次选择 QQ |
| 自定义事件源 | 构造 `Envelope`，经统一运行时分发给 Hook | `await bot.emit(envelope)` |

内置 `ping` 回复 `pong`，OneBot 与 QQ 官 Bot 共用业务 Hook。核心也可以独立使用，用于学习或构建自己的事件处理应用。

项目处于早期开发阶段，API 可能调整。QQ 官 Bot 已有本地假网关和 HTTP 服务测试，真实账号的权限、网关可用性和平台限制仍需实际联调；详见 [QQ 接入设计](docs/guides/qqofficial.md)。

## 快速开始

支持独立安装包和源码启动。Python 3.11+；长期后台运行可使用 screen。

### 1. 安装

已有 uv 时，下载或构建 wheel 后，无需克隆仓库即可安装：

```bash
uv tool install ./tiffany_hook_runtime-0.1.0-py3-none-any.whl --python 3.11
mkdir tiffany-instance
cd tiffany-instance
tiffany init
tiffany run
```

首次 `init` 选择 OneBot 或 QQ，并准备独立环境和插件；之后复用当前实例目录的 `data/`。也可用 `--home` 固定位置，重复 `init` 不重写配置和凭据。没有 uv 时可在虚拟环境用 `python -m pip install ./tiffany_hook_runtime-0.1.0-py3-none-any.whl`。发行名为 `tiffany-hook-runtime`；正式发布 PyPI 后可直接按发行名安装，目前不将公开索引安装视为已验证。构建与更新见 [部署指南](docs/guides/deployment.md#独立安装包与更新)。

需要开发源码，或继续使用现有脚本时：

```bash
git clone https://github.com/CyanReef/Tiffany.git
cd Tiffany
bash start.sh
```

启动器首次安装带哈希锁定的服务器依赖，终端向导选择一种接入。配置、凭据、日志、业务数据和环境在项目的 `data/` 下生成；后续启动复用，不重写配置。也可执行 `screen -S tiffany bash /opt/Tiffany/start.sh`。

Windows 测试机安装 Python 3.11+ 后，在项目目录的 PowerShell 或 CMD 中执行：

```powershell
.\start.bat
```

首次同样进入配置向导；之后一行命令复用 `data/`。也可在 PowerShell 使用 `.\start.ps1`。两个入口支持 `configure`、`login`、`check-config`、`--home` 等相同参数，并自动寻找 Python；指定解释器和迁移到 Linux 的方法见 [部署文档](docs/guides/deployment.md#windows-本机测试)。仅开发核心时仍可用 `python -m pip install -e .`；独立 Hook 示例无需服务器配置。

也可以在已激活的 Python 环境中，从项目根目录安装命令行入口：

```bash
python -m pip install -e .
tiffany run
```

`tiffany` 复用同一个启动器，支持 `init`、`configure`、`login`、`check-config`、`plugins`、`--version` 和 `--home`；不写子命令也会启动。源码可编辑安装需保留源码目录，默认复用该项目的 `data/`；独立安装使用当前实例的 `data/`。安装环境的 Scripts/bin 目录需在 PATH 中，完整说明见 [命令行入口](docs/guides/deployment.md#命令行入口)。

### 2. 连接 OneBot / NapCat

```bash
bash start.sh configure
bash start.sh check-config
bash start.sh
```

程序默认监听 `127.0.0.1:6199`。在 NapCat 或其他 OneBot 实现中启用**反向 WebSocket 客户端**，连接到 `ws://127.0.0.1:6199`，再向机器人发送 `ping`。

地址、端口、并发和共享缓冲预算在 `data/config/Tiffany.toml` 中设置，参考 [OneBot 示例](examples/Tiffany.onebot.toml)。Token 可在向导中隐藏输入；非本地绑定要求 Token。当前适配器支持一个活动连接。同一 `(adapter_id, session_id)` 内按接纳顺序执行；`workers = 1` 限制为单并发，跨会话仍按公平调度轮流执行，不保证整个连接的全局接收顺序。

### 3. 连接 QQ 官 Bot

```bash
# 在 configure 中选择 QQ 官 Bot，然后扫码或手动输入
bash start.sh configure
bash start.sh
# 需要重新绑定时
bash start.sh login
```

凭据与配置分离，默认保存到 `data/secrets/credentials.json`；配置指定的环境变量优先。使用一个账号、一个 WebSocket 连接；拿到 `READY` 后，测试群内 @机器人 `ping` 与私聊 `ping`。可用 `intents` 订阅获准的频道或互动事件。配置示例见 [Tiffany.qqofficial.toml](examples/Tiffany.qqofficial.toml)，消息 JSON 接口、上传和协议边界见 [接入说明](docs/guides/qqofficial.md)。

更新时 Ctrl+C 并等待清理结束，覆盖程序文件后再启动，保留 `data/`。发布包通过 `python -B tools/build_release.py` 生成并验证不含数据目录。环境按锁文件隔离以支持回滚；故障限次重启、日志轮转、健康检查和完整操作见 [服务器部署文档](docs/guides/deployment.md)。

实机验收步骤见 [部署说明](docs/guides/deployment.md#实机验收)，尚未完成的工作见 [路线图](docs/planning/roadmap.md)。

### 4. 选择业务扩展

在 `data/config/Tiffany.toml` 末尾添加以下配置，重启后启用裸文本 `ping`、`/ping` 和 `/help`：

```toml
[extensions]
enabled = ["commands", "ping", "help"]
```

未配置 `[extensions]` 时保留旧业务；`enabled = []` 显式停用全部业务。权限、限流和 SQLite 笔记需要显式启用，配置与命令见 [业务扩展指南](docs/guides/extensions.md)。无账号体验可运行 `python -B -m examples.extensions`；其他示例见 [示例导航](examples/README.md)。

第三方源码插件放入 `<home>/plugins/` 后默认启用，正常启动自动准备共享环境。使用 `start.bat plugins list` 或 `bash start.sh plugins list` 查看，`plugins disable ID` 停用；模板、pyproject 声明及修复命令见 [插件指南](docs/guides/plugins.md)。

## 写第一个 Hook

这个例子可独立运行，不需要机器人账号或外部服务。

```python
import asyncio

from core import Bot, Context, Envelope, Field

TEXT = Field[str]("demo.text")


async def main():
    bot = Bot()
    bot.provide(TEXT, lambda ctx: ctx.raw["text"].strip())

    @bot.hook(on="message", needs=(TEXT,))
    async def greet(ctx: Context):
        print(ctx.resolve(TEXT))

    async with bot:
        await bot.emit(Envelope("demo", {"text": " hello "}, kind="message"))


asyncio.run(main())  # 输出 hello
```

`needs` 声明依赖以便校验；真正调用 `ctx.resolve(TEXT)` 时才计算字段。同一事件的所有 Hook 共用缓存。接入真实平台后，可以在 Hook 中使用 `await ctx.reply("你好")` 回复，或直接读取 `ctx.raw` 中的平台特有数据。

`Field` 按对象身份区分，名称仅用于诊断。应在一个公共模块定义字段并导入同一实例；项目已有共享字段见 [fields.py](fields.py)。Provider 是同步计算函数；网络、数据库等异步调用放在 Hook 或 Service 中。

## 核心设计

```mermaid
flowchart LR
    A[Adapter 接收事件] --> E[Envelope 保存原始数据]
    E --> R[Runtime / Scheduler 有界调度]
    R --> H[Hook 业务处理]
    H --> P[Provider 按需解析字段]
    H --> S[Service 共享能力]
    H --> C[Client 回复 / 调用 API]
```

| 设计选择 | 如何工作 |
| --- | --- |
| 保留原始数据 | `Envelope.raw` 保存平台事件；协议状态与控制帧由 Adapter 管理 |
| 按需计算 | `Context.resolve()` 在本事件内缓存字段，未读取的字段无需解析 |
| 先路由，再执行业务 | 按 `platform`、`kind` 筛选 Hook，缓存当前注册快照的路由 |
| 有界接纳 | Scheduler 共享事件数与估算占用预算，按需创建执行任务，过载时明确拒绝 |
| 按资源归属清理 | Scope 管理一组注册与资源，Runtime 监督任务并负责关闭 |

同一个会话键的事件串行处理，不同会话可以并行；实际顺序取决于 Adapter 提供的会话键。默认共享 **8192** 个在途事件、**64 MiB 估算占用预算**、最多 **64** 个执行任务；适配器继承全局并发，显式 `workers` 可降低上限。会话没有固定积压上限，单会话突发按共享余量接纳；总预算的 1/8 为低占用会话保留。估算预算不等于进程 RSS 上限，实际吞吐量取决于 Hook 工作量和外部 I/O。配置与接纳契约见 [弹性调度说明](docs/design/scheduling.md)。

## 进阶扩展

可选业务通过 TOML 选择，命令按启动时编译的查找表执行，笔记在数据库提交成功后确认。

从一个 Hook 继续增加能力，无需改变基础事件模型。

| 想做什么 | 使用什么 |
| --- | --- |
| 提前执行过滤或权限判断 | `priority` 数值越大越先执行；`when` 支持同步或异步判断 |
| 组合派生字段 | `provide(..., requires=(...))` 声明依赖，Provider 内调用 `resolve()` |
| 为后续 Hook 共享本事件结果 | `ctx.put(field, value)`；`ctx.stop()` 停止后续 Hook |
| 复用数据库连接或 API 客户端 | 注册 `ServiceKey` 与 Service，通过 `ctx.service(key)` 获取 |
| 管理一组可卸载的业务 | `bot.scope("my.extension")` 注册 Hook、Provider、Service 和生命周期资源 |
| 控制错误与耗时 | `on_error="continue"` 或默认 `"abort"`，配合 `timeout`、`on_timeout` |
| 观察运行情况 | `bot.metrics`、可选 Trace 和 OpenMetrics 导出 |
| 使用平台独有能力 | 读取原始事件、自定义 Provider，或通过 Client 直接调用协议 API |

默认 `abort` 错误策略终止当前事件。Scope 卸载会处理其在途工作并撤销注册；共享依赖存在时会阻止错误卸载。资源生命周期、任务监督与完整示例见 [学习与开发路线](docs/development/learning-guide.md)。

## 性能复测

基准工具覆盖核心分发与字段缓存、调度负载、四框架离线消息路径。测量边界、依赖和结果解读见 [基准指南](docs/development/benchmarks.md)，工具入口见 [基准导航](benchmarks/README.md)。

```powershell
python -m pip install -e ".[benchmark]"
python -B -m benchmarks.run --output .build-cache/benchmarks/local.json
python -B -m benchmarks.plot --input .build-cache/benchmarks/local.json --output .build-cache/benchmarks/plots
```

历史报告、原始数据和源码快照已清理。新测量保存在 `.build-cache/`，性能结论需注明对应源码、环境与计时边界；当前版本的性能保证需要重新采样和实机验证。

## 学习与开发

| 从哪里开始 | 文档 |
| --- | --- |
| 了解目录职责，跟踪一条消息 | [源码地图](docs/development/code-map.md) |
| 按阶段读代码，动手制作扩展 | [学习与开发路线](docs/development/learning-guide.md) |
| 找到单元测试、集成测试与辅助对象 | [测试目录导航](tests/README.md) |
| 配置扩展、学习命令与笔记的资源归属 | [业务扩展指南](docs/guides/extensions.md) |
| 运行独立演示与查看配置示例 | [示例导航](examples/README.md) |
| 理解 QQ 接入与协议边界 | [QQ 官 Bot 接入设计](docs/guides/qqofficial.md) |
| 首次配置、screen、更新与回滚 | [服务器部署文档](docs/guides/deployment.md) |
| 理解性能测试及其限制 | [基准说明](docs/development/benchmarks.md) |
| 理解架构约束 | [架构说明](docs/design/architecture.md) |
| 查看后续开发与实机验收事项 | [路线图](docs/planning/roadmap.md) |
| 配置共享预算、同步接纳与公平调度 | [弹性调度说明](docs/design/scheduling.md) |

目录按职责组织：`hooks/` 编写业务，`adapters/` 接收事件，`clients/` 执行平台动作，`core/` 提供平台无关的运行机制；`application.py` 负责将它们组装起来。`deployment/` 管理环境和应用进程，`shared/` 保存标准库路径约定。核心的大模块内部按 `core/dispatch/` 与 `core/runtime/` 分工，原有 `from core import ...` 入口保持可用。

### 运行测试

```powershell
# 安装完整测试使用的服务器依赖
python -m pip install --require-hashes --only-binary=:all: -r requirements-server.lock
python -m unittest discover -s tests -t . -q
```

测试使用标准库 `unittest`，按 `unit`、`integration` 和协议分类。QQ 自动集成测试启动本地假 HTTP 服务与 WebSocket 网关，无需真实账号。

### 参与贡献

欢迎提交 [Issue](https://github.com/CyanReef/Tiffany/issues) 和 Pull Request。问题反馈请附复现步骤、Python 版本与必要日志；改动请说明目的、行为变化和验证方式。业务扩展优先放在 Hook / Provider / Service 层；修改核心机制时补充对应行为测试，并更新相关文档。

## 开源许可

Tiffany 使用单份标准英文 [MIT License](LICENSE)。允许商用、修改和再分发，分发时保留版权与许可声明；软件按原样提供，不附带担保。第三方依赖遵循各自的许可。

许可条款对应 [SPDX 收录的 MIT 条款](https://spdx.org/licenses/MIT.html)。
