Metadata-Version: 2.4
Name: tg-bot-plugin-sdk
Version: 0.2.0
Summary: TG-BOT 插件作者侧 SDK 与 capability 真源模型。
Author: Fire Dragons
License: MIT
Requires-Python: >=3.11
Requires-Dist: apscheduler==3.11.2
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# tg-bot-plugin-sdk

`tg-bot-plugin-sdk` 是 TG-BOT 插件作者侧 Python API 的新真源。

当前阶段提供：

- `BasePlugin` 与 `PluginContext`
- `CapabilityResult` 与 `RuntimeCapabilityInvocation`
- `concurrency_class` 常量与 `PluginCapabilitySpec`
- `BackgroundTaskHandle` / `BackgroundTaskObserver`
- `invoke_capability` / `event_capability` 装饰器
- `CapabilityDeclarationError` / `PluginError`
- capability 真源投影与 externalize 输出脚本

作者侧 ABI 约束：

- `PluginCapabilitySpec.concurrency_class` 固定为 `sync_session / async_sidecar / async_terminal`，默认 `sync_session`
- `RuntimeCapabilityInvocation` 固定提供 `message_thread_id`、`session_key`、`session_kind`
- `PluginContext` 不默认暴露 `shard_id`、`worker_id`、`host_id` 这类内部调度字段

`packages/sdk/scripts/externalize_capabilities.py` 会生成
`build/capabilities.externalize.json`，后续由 `packages/buildkit` 消费并把 capability
投影刷新回 `manifest.json`。

## 本地验证

- 独立安装与导入验证：`bash packages/sdk/scripts/check_package_install.sh`
- 单元测试：`pytest -q packages/sdk/tests`
