tenko-api 0.1.0__py3-none-any.whl

tenko_api/__init__.py

@@ -0,0 +1,16 @@
+"""Tenko 第三方插件的稳定宿主接口。
+
+本包没有运行时依赖，只是一层薄转发：各子模块在导入时才转发到正在运行的
+Tenko 宿主（``tenko.*``），所以 ``import tenko_api`` 本身不要求宿主已安装。
+插件只应从 ``tenko_api.*`` 导入宿主能力，不要导入 ``tenko.*`` 内部模块。
+
+版本遵循语义化版本，且 1.0 之前（预览期）接口可能调整：
+
+- 新增能力：次版本号 +1；
+- 删除或改变语义：主版本号 +1，废弃的接口至少保留一个次版本并给出
+  ``DeprecationWarning``。
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

tenko_api/accounts.py

@@ -0,0 +1,23 @@
+"""稳定插件 API：只读账号信息。"""
+
+from satori.client import Account
+
+from tenko.host.accounts import account_registry
+
+__all__ = ["Account", "accounts_for_group", "online_accounts"]
+
+
+def online_accounts() -> tuple[Account, ...]:
+    """返回当前在线（已连接且未被停用）的全部账号。"""
+
+    return tuple(
+        account
+        for account in account_registry.accounts.values()
+        if account_registry.is_available(account)
+    )
+
+
+def accounts_for_group(group_id: str | int) -> tuple[Account, ...]:
+    """返回在该群可响应的账号：在线、未停用、未被该群禁言。"""
+
+    return account_registry.accounts_for_group(group_id)

tenko_api/actions.py

@@ -0,0 +1,48 @@
+"""稳定插件 API：宿主平台动作。
+
+动作经过宿主的权限检查、账号可用性判断和能力探测；失败时抛出
+:class:`ActionServiceError` 的子类。首个参数 ``account_or_id`` 接受 Satori
+账号对象或账号 ID，``ctx`` 为触发动作的消息上下文。
+"""
+
+from tenko.host.actions import (
+    ActionAccountUnavailable,
+    ActionCapabilityUnavailable,
+    ActionExecutionError,
+    ActionFailure,
+    ActionPermissionDenied,
+    ActionReceipt,
+    ActionServiceError,
+    ActionTargetUnavailable,
+    action_service,
+)
+
+send_group_message = action_service.send_group_message
+send_private_message = action_service.send_private_message
+mute_member = action_service.mute_member
+unmute_member = action_service.unmute_member
+kick_member = action_service.kick_member
+delete_message = action_service.delete_message
+get_group_member = action_service.get_group_member
+list_group_members = action_service.list_group_members
+list_groups = action_service.list_groups
+
+__all__ = [
+    "ActionAccountUnavailable",
+    "ActionCapabilityUnavailable",
+    "ActionExecutionError",
+    "ActionFailure",
+    "ActionPermissionDenied",
+    "ActionReceipt",
+    "ActionServiceError",
+    "ActionTargetUnavailable",
+    "delete_message",
+    "get_group_member",
+    "kick_member",
+    "list_group_members",
+    "list_groups",
+    "mute_member",
+    "send_group_message",
+    "send_private_message",
+    "unmute_member",
+]

tenko_api/context.py

@@ -0,0 +1,6 @@
+"""稳定插件 API：消息上下文。"""
+
+from tenko.context import MessageContext
+from tenko.plugins._common import context_from_session
+
+__all__ = ["MessageContext", "context_from_session"]

tenko_api/features.py

@@ -0,0 +1,41 @@
+"""稳定插件 API：功能开关查询与 Tenko 专有元数据声明。"""
+
+from typing import Literal
+
+from tenko.host import features as _features
+from tenko.host.guards import feature_required
+from tenko.host.perm import Permission
+
+__all__ = ["declare", "feature_enabled", "feature_required"]
+
+
+def feature_enabled(plugin_id: str, group_id: str | int | None = None) -> bool:
+    """只读查询插件在某群是否开启（全局开关、维护状态和默认值已合并）。"""
+
+    return _features.feature_service.is_enabled(plugin_id, group_id)
+
+
+def declare(
+    *,
+    scope: Literal["group", "global"] = "group",
+    default_enabled: bool = True,
+    rate_weight: int = 1,
+    level: Permission = Permission.ActiveGroup,
+) -> None:
+    """在插件模块导入期间声明 Tenko 元数据，须与 ``plugin.metadata(...)`` 一起调用。
+
+    - ``scope``：``"group"`` 按群开关；``"global"`` 只有一个全局开关。
+    - ``default_enabled``：为 ``False`` 时，没有显式设置的群默认关闭该插件。
+    - ``rate_weight``：每次调用该插件命令计入限流窗口的权重（正整数）。
+    - ``level``：插件要求的群等级（``Permission.InactiveGroup`` 到 ``TestGroup``），
+      默认 ``ActiveGroup``。群等级低于它时，该插件的命令在群里被静默忽略。
+
+    插件不能借此声明自己是受保护的宿主插件。
+    """
+
+    _features.declare_feature(
+        scope=scope,
+        default_enabled=default_enabled,
+        rate_weight=rate_weight,
+        level=level,
+    )

tenko_api/messages.py

@@ -0,0 +1,12 @@
+"""稳定插件 API：消息构造与错误上报。"""
+
+from tenko.plugins._common import (
+    action_error_message,
+    report_action_error,
+    text_message,
+)
+
+# 把异常连同消息来源报告给 Master；投递失败只记日志，不会再抛出。
+report_error = report_action_error
+
+__all__ = ["action_error_message", "report_error", "text_message"]

tenko_api/perm.py

@@ -0,0 +1,51 @@
+"""稳定插件 API：权限等级、权限检查和声明式权限装饰器。
+
+装饰器（``require`` / ``require_group`` / ``private_only`` / ``group_only``）
+是限定命令权限的默认写法，放在 ``@command.on(...)`` 之上或之下均可；要求会登记
+在处理函数上，``/帮助 <编号>`` 据此显示命令所需权限。只有权限取决于运行时数据
+（例如按参数区分的权限）时才在函数体里用 :func:`require_perm`。
+"""
+
+from tenko.context import MessageContext
+from tenko.host import perm as _perm
+from tenko.host.guards import group_only, private_only, require_group
+from tenko.host.guards import require as _require
+from tenko.host.perm import Permission
+
+__all__ = [
+    "Permission",
+    "get_group_perm",
+    "get_user_perm",
+    "group_only",
+    "private_only",
+    "require",
+    "require_group",
+    "require_perm",
+]
+
+
+async def get_user_perm(ctx: MessageContext) -> int:
+    """返回消息发送者在当前群（私聊为全局）的权限数值。"""
+
+    return await _perm.get_user_perm(ctx)
+
+
+async def get_group_perm(ctx: MessageContext) -> int:
+    """返回当前群的群等级数值。"""
+
+    return await _perm.get_group_perm(ctx)
+
+
+async def require_perm(ctx: MessageContext, level: int) -> bool:
+    """发送者权限不低于 ``level``（可用 :class:`Permission`）时返回 ``True``。"""
+
+    return await _perm.require_perm(ctx, level)
+
+
+def require(level: Permission):
+    """要求发送者的成员权限不低于 ``level``，否则回复权限不足并停止处理。
+
+    用法见模块说明；权限数值沿用 :class:`Permission`（含 DB 里的 BotAdmin 和黑名单）。
+    """
+
+    return _require(level)

tenko_api/render.py

@@ -0,0 +1,9 @@
+"""稳定插件 API：离线渲染。
+
+``RenderService`` 由 Entari 按类型注入到命令处理函数；调用
+:func:`render_or_none` 渲染，浏览器不可用时得到 ``None``，请回退到文本。
+"""
+
+from tenko.render import RenderService, render_or_none
+
+__all__ = ["RenderService", "render_or_none"]

tenko_api/storage.py

@@ -0,0 +1,17 @@
+"""稳定插件 API：插件独立存储。
+
+两种存储都以调用方插件的 ID 为键，且只能在插件自己的模块里使用（包必须在
+``pyproject.toml`` 的 ``tenko.plugins`` 入口中声明，子模块同样适用）：
+
+- :func:`data_dir`：数据目录 ``.tenko/plugin-data/<id>/``；
+- :class:`Store`：带版本号的 JSON 文件，旧版本迁移前自动备份。
+"""
+
+from tenko.host.plugin_storage import (
+    PluginStorageError,
+    Store,
+    StoreVersionError,
+    data_dir,
+)
+
+__all__ = ["PluginStorageError", "Store", "StoreVersionError", "data_dir"]

tenko_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: tenko-api
+Version: 0.1.0
+Summary: Tenko 第三方插件的稳定宿主接口（运行时转发到 Tenko 宿主）
+Project-URL: Homepage, https://github.com/g1331/tenko
+Project-URL: Issues, https://github.com/g1331/tenko/issues
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+
+# tenko-api
+
+[Tenko](https://github.com/g1331/tenko) 第三方插件使用的稳定宿主接口。
+
+插件依赖它，而不是依赖 `tenko` 本体：`tenko-api` 没有任何运行时依赖，
+只是转发到正在运行的 Tenko 宿主，因此不会影响插件自己的依赖解析。插件声明
+`tenko-api>=0.1,<0.2` 这样的范围，安装时由 pip / uv 的解析器拒绝不兼容的宿主，
+不需要另写兼容检查。
+
+> 当前为预览版（0.x）。1.0 之前接口可能调整，请把上限写到次版本。
+
+## 最小示例
+
+插件是标准 Python 包，写法与 Entari 原生插件相同，宿主能力一律从
+`tenko_api` 导入：
+
+```toml
+# pyproject.toml
+[project]
+name = "tenko-plugin-hello"
+version = "0.1.0"
+dependencies = ["tenko-api>=0.1,<0.2"]
+
+[project.entry-points."tenko.plugins"]
+hello = "tenko_plugin_hello"   # 入口名 = 插件 ID
+```
+
+```python
+# src/tenko_plugin_hello/__init__.py
+from arclet.alconna import Alconna
+from arclet.entari import Session, command, plugin
+
+from tenko_api.features import declare
+from tenko_api.messages import text_message
+from tenko_api.perm import Permission, require
+
+plugin.metadata("你好", author=["you"], version="0.1.0", description="打招呼")
+declare(
+    scope="group", default_enabled=True, rate_weight=1, level=Permission.ActiveGroup
+)
+
+
+@command.on(Alconna("你好"))
+@require(Permission.User)
+async def hello(session: Session):
+    return text_message("你好！")
+```
+
+## 权限与功能开关
+
+限制命令的默认写法是装饰器，不要在函数体里重复写检查（漏写就等于没有权限控制）：
+
+| 装饰器 | 作用 |
+|---|---|
+| `@require(Permission.X)` | 发送者的成员权限不低于 X（含 Master、BotAdmin 和数据库里的黑名单）；不足时回复“权限不足（当前权限：… / 需要权限：…）” |
+| `@require_group(Permission.X)` | 当前群等级不低于 X，不足时**静默忽略**；私聊不受限 |
+| `@group_only()` / `@private_only()` | 只允许群聊 / 私聊，否则回复“该指令只能在群聊/私聊中使用” |
+
+- 装饰器放在 `@command.on(...)` 之下，放在之上也同样生效；同一种装饰器在一个函数上只能用一次。
+  它们在命令匹配之后执行，所以只有命中命令的消息才会收到拒绝回复。
+- 声明的要求登记在处理函数上，`/帮助 <编号>` 会显示每条命令的“权限”。
+- 只有权限取决于运行时数据时（例如按参数区分的权限）才在函数体里调用 `require_perm`。
+- `declare(level=Permission.X)` 声明整个插件要求的群等级，默认 `ActiveGroup`：群等级更低的群里，
+  该插件的所有命令都被宿主静默忽略。
+- 不走命令的监听器（例如响应 @bot 的消息监听）没有宿主的命令策略保护，用
+  `@feature_required()` 检查所属插件的功能开关和维护模式（只在群聊生效，默认静默，
+  `notify=True` 时回复提示）。所属插件按被装饰函数的模块确定，规则与 `data_dir()` 相同。
+
+```python
+from arclet.entari import MessageCreatedEvent, plugin
+
+from tenko_api.features import feature_required
+
+
+@plugin.listen(MessageCreatedEvent)
+@feature_required()
+async def on_message(event: MessageCreatedEvent): ...
+```
+
+## 接口一览
+
+| 模块 | 内容 |
+|---|---|
+| `tenko_api.context` | `MessageContext`、`context_from_session` |
+| `tenko_api.perm` | `Permission`；装饰器 `require`、`require_group`、`group_only`、`private_only`；函数体内的 `require_perm`、`get_user_perm`、`get_group_perm` |
+| `tenko_api.actions` | 发消息、禁言、踢人、撤回、查询群成员等宿主动作，以及 `ActionServiceError` 系列异常 |
+| `tenko_api.accounts` | 只读账号信息：在线账号、某群可响应的账号 |
+| `tenko_api.features` | `feature_enabled` 只读查询；`declare` 声明范围、默认开关、限流权重和群等级；`feature_required` 装饰非命令监听器 |
+| `tenko_api.render` | `render_or_none`（浏览器不可用时回退文本） |
+| `tenko_api.messages` | `text_message`、`report_error` |
+| `tenko_api.storage` | 插件独立数据目录 `data_dir()`、带版本号并自动备份迁移的 JSON `Store` |
+
+完整的开发、测试和发布流程见仓库中的示例插件
+[`examples/tenko-plugin-example`](https://github.com/g1331/tenko/tree/main/examples/tenko-plugin-example)。
+
+## 版本承诺
+
+版本号独立于 Tenko 本体，遵循语义化版本（1.0 起生效）：
+
+| 变更 | 版本号 |
+|---|---|
+| 新增能力 | 次版本号 +1 |
+| 删除或改变语义 | 主版本号 +1 |
+
+被废弃的接口至少保留一个次版本，并抛出 `DeprecationWarning`。
+
+## 运行环境
+
+需要在 Tenko 宿主进程中使用：开发和测试时把 `tenko` 作为开发依赖安装即可。
+Python `>=3.11,<3.14`。

tenko_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tenko_api/__init__.py,sha256=ZqG-QHnUjrZTCVRyE8Tx1cqJ881c-VuY_rUvwHojY9Y,641
+tenko_api/accounts.py,sha256=02RL-nlzVhW6RVDpvemfaV7O_z7gO9UHodhXzeMKeLI,687
+tenko_api/actions.py,sha256=ETJu-pF2sVFr9nTRq1-8mlguIAYrzCEr0sBJi-6iVag,1440
+tenko_api/context.py,sha256=buVuQuLmv8CAs7FrQXRCc_2wZ0ggj-l9gFFwd7j1O5w,195
+tenko_api/features.py,sha256=WRyECyDeZtkIqI7GXKeJ9VxH1JMBoNgcGyRr1zNPxI4,1564
+tenko_api/messages.py,sha256=qLJEOxb0D3jROkwZWU9f3hwXdeMs-1Dtac9W8_I-cqg,362
+tenko_api/perm.py,sha256=JIde31FDPn4G-hU9vZqJ9Dxs8E_yrkVUaZuQHqTkQBQ,1706
+tenko_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tenko_api/render.py,sha256=kcwQwLyzEOhAZ1OgcBAcelSrqiwCiZiqzC3Y58fp0gM,314
+tenko_api/storage.py,sha256=ZOXxlhENzSirC7GUBunxuHSy9mSLrNMKfm4omVjh-5E,584
+tenko_api-0.1.0.dist-info/METADATA,sha256=SyMP2wC9bnxqXCiAEvizVKaiUNL9ovTyFcxrTDIRdfY,5505
+tenko_api-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+tenko_api-0.1.0.dist-info/RECORD,,

tenko_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any