tenko-plugin-example 0.1.0__tar.gz

tenko_plugin_example-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# 推送与 pyproject.toml 版本一致的标签（如 v0.1.0）时发布到 PyPI。
+# 使用 PyPI Trusted Publishing，不需要保存 token：先在 PyPI 上为该项目建立
+# （pending）publisher，工作流填 publish.yml，环境填 pypi。
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify the tag matches the project version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::标签 $GITHUB_REF_NAME 与 pyproject.toml 版本 v$version 不一致"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build --out-dir dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

tenko_plugin_example-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # 开发依赖里包含从 Git 安装的 Tenko 宿主，测试会加载真实的宿主。
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -q

tenko_plugin_example-0.1.0/.gitignore

@@ -0,0 +1,223 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Python binary files
+*/__pycache__
+*.pyc
+
+# VS Code
+.vscode/
+
+# 配置文件、日志
+/config/config.yaml
+/config/tenko.toml
+/log
+
+# 测试文件
+/modules/test_modules/
+auto_get_server.py
+test.py
+drafts/
+
+# 数据库
+data.db
+
+# Alembic files
+/alembic/
+alembic.ini
+
+# 数据文件
+/data/
+/.entari/
+/.tenko/
+/modules/self_contained/bilibili_dynamic/dynamic_list.json
+/modules/self_contained/emoji_mix/assets/update.json
+/modules/self_contained/chat_gpt/gpt_mode.json
+/modules/self_contained/claude/config.json
+/utils/bf1/default_account.json
+/utils/bf1/ap_info.json
+
+# 第三方插件
+/modules/third_party/
+/modules/self_contained/bf1_warm_server/
+
+#文件修改记录
+.history/
+
+# Claude Code 本地配置
+.claude/settings.local.json
+.claude/*.local.*
+.claude/local/
+.claude/plugins.json
+
+# Sigma 本地检查点(含嵌套 .git，禁止提交以免产生误判的子模块)
+.sigmadev/
+
+# 临时交接文档
+HANDOFF_BF_MANAGER.md
+
+.serena/
+
+# WebUI 前端依赖（构建产物 tenko/webui/static 需要提交）
+webui/node_modules

tenko_plugin_example-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: tenko-plugin-example
+Version: 0.1.0
+Summary: Tenko 第三方插件示例与模板
+Project-URL: Homepage, https://github.com/g1331/tenko/tree/main/examples/tenko-plugin-example
+Project-URL: Repository, https://github.com/g1331/tenko
+License-Expression: GPL-3.0-only
+Requires-Python: <3.14,>=3.11
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: tenko-api<0.3,>=0.2
+Description-Content-Type: text/markdown
+
+# tenko-plugin-example
+
+[Tenko](https://github.com/g1331/tenko) 第三方插件的示例与起步模板。它演示：
+
+- 用 `tenko_api.features.declare` 声明按群开关、默认状态、限流权重和群等级；
+- 用 `[plugin_config.example]` 配置插件（Entari 的 `BasicConfModel`）；
+- 用 `tenko_api.storage.Store` 保存带版本号的 JSON 数据，用 `Model` 和 `get_session()` 使用插件自己的 SQLite 库；
+- 用 `tenko_api.perm` 的装饰器（`@require` 等）声明命令权限，用 Entari 原生的 `command.on` 注册命令。
+
+插件命令 `/示例 [备注]` 记录你使用命令的次数（JSON）和备注历史（SQLite）。
+
+## 从模板开始
+
+1. 复制本目录作为新项目（在 GitHub 上可以把它放进自己的仓库）。
+2. 改名：分发名用 `tenko-plugin-xxx`，模块名用 `tenko_plugin_xxx`。同步修改
+   `pyproject.toml` 的 `name`、`[tool.hatch.build.targets.wheel]`、`src/` 目录名，以及
+   入口 `[project.entry-points."tenko.plugins"]` 里的 `<插件 ID> = "<模块>"`。
+   插件 ID 匹配 `[a-z][a-z0-9_]*`，全局唯一，不能和内置插件同名；它是功能开关、
+   配置节和数据目录的键。
+3. 换成你自己的信息：`plugin.metadata` 的 `author`、`description`，以及 `pyproject.toml`
+   的 `[project.urls]`（插件目录靠这里的 GitHub 地址确认仓库归你所有）。示例本身作为真实
+   插件发布在 PyPI 上，这些地方写的是 Tenko 维护者的信息。
+4. **不要声明 `entari.plugin` 入口**：Entari 会无视 Tenko 的启用状态自动加载它。
+5. 依赖只写 `tenko-api` 的兼容范围（预览期为 `>=0.2,<0.3`）和插件自己的依赖，
+   不要依赖 `tenko` 本体，也不要用 `==` 锁死依赖版本。
+
+## 开发与测试
+
+```text
+uv sync          # 创建环境，开发依赖里包含从 Git 安装的 Tenko 宿主（发布后请固定到版本标签）
+uv run pytest -q
+uv run ruff check .
+```
+
+`tests/conftest.py` 用真实的宿主加载插件：按 `tenko.plugins` 入口发现、启用、传入配置，
+然后直接调用命令处理函数。不需要启动 Tenko，也不需要连接聊天平台。
+
+写法要点：
+
+- 宿主能力一律从 `tenko_api` 导入，不要导入 `tenko.*` 内部模块。
+- `declare(...)` 必须在插件模块导入期间调用（与 `plugin.metadata(...)` 放在一起）。
+- `data_dir()` 和 `Store` 只能在插件自己的模块里使用，数据位于 `.tenko/plugin-data/<插件 ID>/`。
+  数据结构变化时提高 `Store` 的版本号并提供 `migrate`，宿主会先把旧文件备份为
+  `<名称>.json.bak-v<旧版本>`；插件被降级、读到更新版本的文件时会报错而不是覆盖。
+- `Model` 子类在插件模块导入期间定义，表建在 `data.db`；启动时自动建表和增加可空列，
+  删除或修改列会被拒绝，需要时写官方的 `register_custom_migration` 脚本。测试里要像宿主
+  那样先加载数据库插件、再加载插件、最后初始化并迁移（见 `tests/conftest.py`）。
+  版本变化后宿主会先备份库到 `backups/`。
+- 命令权限用 `tenko_api.perm` 的装饰器声明，不要在函数体里重复检查；装饰器在
+  `@command.on(...)` 之上或之下都生效。因为装饰器由 Entari 调度，测试里直接调用
+  `callable_target` 不会经过它们，应检查登记的要求（见 `tests/test_plugin.py`），
+  或像 `tests/tenko` 里那样走真实分发。
+- Entari 对标准 dataclass 配置模型不做类型校验，需要时在 `__post_init__` 里检查。
+
+## 在 Tenko 里启用
+
+1. 在运行 Tenko 的环境里安装插件：`uv pip install tenko-plugin-xxx`（本地调试用
+   `uv pip install -e /path/to/plugin`）。
+2. 打开 WebUI 的插件页，启用该插件（带“第三方”标记）。第三方插件默认关闭，启用后
+   写入 `.tenko/plugins/state.json`。
+3. 如有配置，在 `config/tenko.toml` 里添加 `[plugin_config.<插件 ID>]`，见仓库中
+   `config/tenko.toml.example` 末尾的说明。
+4. 重启 Tenko（聊天里的 `/重启` 或重新运行进程），插件才会被加载。
+
+之后可以在 WebUI 开关页或用 `/开启`、`/关闭` 按群控制，插件命令与内置命令走同一套
+维护模式、功能开关和限流。
+
+## 发布
+
+**发布到 PyPI（推荐，使用 Trusted Publishing，不保存 token）**
+
+1. 在 PyPI 上添加 pending publisher：项目名填你的分发名，所有者和仓库填你的 GitHub
+   仓库，工作流填 `publish.yml`，环境填 `pypi`。
+2. 在 GitHub 仓库设置里创建名为 `pypi` 的 Environment。
+3. 把 `pyproject.toml` 的版本改为 `X.Y.Z`，提交后打标签并推送：
+
+   ```text
+   git tag vX.Y.Z && git push origin vX.Y.Z
+   ```
+
+   `.github/workflows/publish.yml` 会检查标签与版本一致、构建并发布。
+
+**只用 GitHub**：不发布到 PyPI 时，使用者可以直接
+`uv pip install "tenko-plugin-xxx @ git+https://github.com/<你>/<仓库>@<标签或提交>"`，
+请固定到标签或提交哈希。
+
+## 收录到插件目录
+
+发布到 PyPI（或打好 Git 标签）后，在 [tenko-registry](https://github.com/g1331/tenko-registry)
+用投稿表单填写来源即可。插件 ID、名称、简介、作者、许可证和兼容范围都由目录的 CI 从
+`pyproject.toml` 和 `plugin.metadata(...)` 读取，之后的新版本也会自动追加。
+
+图标可选：在 `plugin.metadata(icon="https://…")` 里给出图片地址，或在投稿表单里上传。要求
+透明背景的单色图形（PNG 或 WebP，不接受 JPEG、SVG 和动图），短边至少 64 px；目录会裁成
+正方形、缩放到 128×128 PNG 并自行托管，Tenko 只显示目录托管的图标。
+
+## 兼容性
+
+`tenko-api` 遵循语义化版本（1.0 之前为预览，接口可能调整）。插件声明的范围由宿主在
+加载前检查：宿主提供的 `tenko-api` 不在范围内时，插件不加载，日志说明原因。注意 `uv pip install`
+遇到不兼容的范围不会报错，而是把环境里的 `tenko-api` 换成插件要的版本，所以不能靠安装结果判断兼容性。

tenko_plugin_example-0.1.0/README.md

@@ -0,0 +1,101 @@
+# tenko-plugin-example
+
+[Tenko](https://github.com/g1331/tenko) 第三方插件的示例与起步模板。它演示：
+
+- 用 `tenko_api.features.declare` 声明按群开关、默认状态、限流权重和群等级；
+- 用 `[plugin_config.example]` 配置插件（Entari 的 `BasicConfModel`）；
+- 用 `tenko_api.storage.Store` 保存带版本号的 JSON 数据，用 `Model` 和 `get_session()` 使用插件自己的 SQLite 库；
+- 用 `tenko_api.perm` 的装饰器（`@require` 等）声明命令权限，用 Entari 原生的 `command.on` 注册命令。
+
+插件命令 `/示例 [备注]` 记录你使用命令的次数（JSON）和备注历史（SQLite）。
+
+## 从模板开始
+
+1. 复制本目录作为新项目（在 GitHub 上可以把它放进自己的仓库）。
+2. 改名：分发名用 `tenko-plugin-xxx`，模块名用 `tenko_plugin_xxx`。同步修改
+   `pyproject.toml` 的 `name`、`[tool.hatch.build.targets.wheel]`、`src/` 目录名，以及
+   入口 `[project.entry-points."tenko.plugins"]` 里的 `<插件 ID> = "<模块>"`。
+   插件 ID 匹配 `[a-z][a-z0-9_]*`，全局唯一，不能和内置插件同名；它是功能开关、
+   配置节和数据目录的键。
+3. 换成你自己的信息：`plugin.metadata` 的 `author`、`description`，以及 `pyproject.toml`
+   的 `[project.urls]`（插件目录靠这里的 GitHub 地址确认仓库归你所有）。示例本身作为真实
+   插件发布在 PyPI 上，这些地方写的是 Tenko 维护者的信息。
+4. **不要声明 `entari.plugin` 入口**：Entari 会无视 Tenko 的启用状态自动加载它。
+5. 依赖只写 `tenko-api` 的兼容范围（预览期为 `>=0.2,<0.3`）和插件自己的依赖，
+   不要依赖 `tenko` 本体，也不要用 `==` 锁死依赖版本。
+
+## 开发与测试
+
+```text
+uv sync          # 创建环境，开发依赖里包含从 Git 安装的 Tenko 宿主（发布后请固定到版本标签）
+uv run pytest -q
+uv run ruff check .
+```
+
+`tests/conftest.py` 用真实的宿主加载插件：按 `tenko.plugins` 入口发现、启用、传入配置，
+然后直接调用命令处理函数。不需要启动 Tenko，也不需要连接聊天平台。
+
+写法要点：
+
+- 宿主能力一律从 `tenko_api` 导入，不要导入 `tenko.*` 内部模块。
+- `declare(...)` 必须在插件模块导入期间调用（与 `plugin.metadata(...)` 放在一起）。
+- `data_dir()` 和 `Store` 只能在插件自己的模块里使用，数据位于 `.tenko/plugin-data/<插件 ID>/`。
+  数据结构变化时提高 `Store` 的版本号并提供 `migrate`，宿主会先把旧文件备份为
+  `<名称>.json.bak-v<旧版本>`；插件被降级、读到更新版本的文件时会报错而不是覆盖。
+- `Model` 子类在插件模块导入期间定义，表建在 `data.db`；启动时自动建表和增加可空列，
+  删除或修改列会被拒绝，需要时写官方的 `register_custom_migration` 脚本。测试里要像宿主
+  那样先加载数据库插件、再加载插件、最后初始化并迁移（见 `tests/conftest.py`）。
+  版本变化后宿主会先备份库到 `backups/`。
+- 命令权限用 `tenko_api.perm` 的装饰器声明，不要在函数体里重复检查；装饰器在
+  `@command.on(...)` 之上或之下都生效。因为装饰器由 Entari 调度，测试里直接调用
+  `callable_target` 不会经过它们，应检查登记的要求（见 `tests/test_plugin.py`），
+  或像 `tests/tenko` 里那样走真实分发。
+- Entari 对标准 dataclass 配置模型不做类型校验，需要时在 `__post_init__` 里检查。
+
+## 在 Tenko 里启用
+
+1. 在运行 Tenko 的环境里安装插件：`uv pip install tenko-plugin-xxx`（本地调试用
+   `uv pip install -e /path/to/plugin`）。
+2. 打开 WebUI 的插件页，启用该插件（带“第三方”标记）。第三方插件默认关闭，启用后
+   写入 `.tenko/plugins/state.json`。
+3. 如有配置，在 `config/tenko.toml` 里添加 `[plugin_config.<插件 ID>]`，见仓库中
+   `config/tenko.toml.example` 末尾的说明。
+4. 重启 Tenko（聊天里的 `/重启` 或重新运行进程），插件才会被加载。
+
+之后可以在 WebUI 开关页或用 `/开启`、`/关闭` 按群控制，插件命令与内置命令走同一套
+维护模式、功能开关和限流。
+
+## 发布
+
+**发布到 PyPI（推荐，使用 Trusted Publishing，不保存 token）**
+
+1. 在 PyPI 上添加 pending publisher：项目名填你的分发名，所有者和仓库填你的 GitHub
+   仓库，工作流填 `publish.yml`，环境填 `pypi`。
+2. 在 GitHub 仓库设置里创建名为 `pypi` 的 Environment。
+3. 把 `pyproject.toml` 的版本改为 `X.Y.Z`，提交后打标签并推送：
+
+   ```text
+   git tag vX.Y.Z && git push origin vX.Y.Z
+   ```
+
+   `.github/workflows/publish.yml` 会检查标签与版本一致、构建并发布。
+
+**只用 GitHub**：不发布到 PyPI 时，使用者可以直接
+`uv pip install "tenko-plugin-xxx @ git+https://github.com/<你>/<仓库>@<标签或提交>"`，
+请固定到标签或提交哈希。
+
+## 收录到插件目录
+
+发布到 PyPI（或打好 Git 标签）后，在 [tenko-registry](https://github.com/g1331/tenko-registry)
+用投稿表单填写来源即可。插件 ID、名称、简介、作者、许可证和兼容范围都由目录的 CI 从
+`pyproject.toml` 和 `plugin.metadata(...)` 读取，之后的新版本也会自动追加。
+
+图标可选：在 `plugin.metadata(icon="https://…")` 里给出图片地址，或在投稿表单里上传。要求
+透明背景的单色图形（PNG 或 WebP，不接受 JPEG、SVG 和动图），短边至少 64 px；目录会裁成
+正方形、缩放到 128×128 PNG 并自行托管，Tenko 只显示目录托管的图标。
+
+## 兼容性
+
+`tenko-api` 遵循语义化版本（1.0 之前为预览，接口可能调整）。插件声明的范围由宿主在
+加载前检查：宿主提供的 `tenko-api` 不在范围内时，插件不加载，日志说明原因。注意 `uv pip install`
+遇到不兼容的范围不会报错，而是把环境里的 `tenko-api` 换成插件要的版本，所以不能靠安装结果判断兼容性。

tenko_plugin_example-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "tenko-plugin-example"
+version = "0.1.0"
+description = "Tenko 第三方插件示例与模板"
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    # 兼容声明：解析器据此拒绝不兼容的宿主。上限写到下一个次版本（1.0 之后写到主版本）。
+    "tenko-api>=0.2,<0.3",
+    # 插件自己的依赖写在这里：只写下限，不要用 == 锁死，以免与宿主冲突。
+    # Model 基于宿主已有的 SQLAlchemy，声明下限即可。
+    "sqlalchemy>=2.0",
+]
+
+# 插件目录用这些链接确认提交者对仓库的归属，并取 Homepage 作为主页。
+[project.urls]
+Homepage = "https://github.com/g1331/tenko/tree/main/examples/tenko-plugin-example"
+Repository = "https://github.com/g1331/tenko"
+
+# 入口名就是插件 ID（小写字母、数字、下划线，全局唯一）；值是纯模块路径。
+# 不要声明 entari.plugin 入口，Entari 会无视 Tenko 的启用状态自动加载它。
+[project.entry-points."tenko.plugins"]
+example = "tenko_plugin_example"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tenko_plugin_example"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=1",
+    "ruff",
+    # 测试要加载真实的宿主。发布后请把 main 换成固定的 Tenko 版本标签。
+    "tenko @ git+https://github.com/g1331/tenko@main",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

tenko_plugin_example-0.1.0/src/tenko_plugin_example/__init__.py

@@ -0,0 +1,98 @@
+"""Tenko 第三方插件示例：问候计数。
+
+演示 tenko_api 的主要能力：声明元数据（含群等级）、读取配置、带版本的 JSON
+存储、插件自己的 SQLite 库（``Model``），以及声明式权限装饰器。写法与内置插件一样，
+都是 Entari 原生的 ``plugin.metadata``、``command.on``。
+"""
+
+from sqlalchemy import String, select
+from sqlalchemy.orm import Mapped, mapped_column
+
+from arclet.alconna import Alconna, Args, CommandMeta
+from arclet.entari import BasicConfModel, Session, command, plugin
+from arclet.entari.command import Query
+
+from tenko_api.context import context_from_session
+from tenko_api.features import declare
+from tenko_api.perm import Permission, require
+from tenko_api.storage import Model, Store, get_session
+
+
+class ExampleConfig(BasicConfModel):
+    """对应 config/tenko.toml 中的 ``[plugin_config.example]``。"""
+
+    greeting: str = "你好"
+    """回复使用的问候语。"""
+
+
+plugin.metadata(
+    "示例插件",
+    author=["13"],
+    version="0.1.0",
+    description="记录每位用户使用示例命令的次数，并保存备注。",
+    config=ExampleConfig,
+    # 可选：插件目录会下载这张图，处理成 128×128 PNG 后自行托管。
+    # icon="https://raw.githubusercontent.com/you/tenko-plugin-example/main/icon.png",
+)
+# Tenko 专有元数据：按群开关、新群默认开启、每次调用计入限流窗口的权重，以及
+# 插件要求的群等级（低于它的群里命令被静默忽略，ActiveGroup 即默认值）。
+declare(
+    scope="group",
+    default_enabled=True,
+    rate_weight=1,
+    level=Permission.ActiveGroup,
+)
+
+config = plugin.get_config(ExampleConfig)
+# .tenko/plugin-data/example/visits.json；以后改数据结构时提高 version，并提供 migrate。
+visits = Store("visits", version=1)
+
+
+class Note(Model):
+    """备注历史。表建在 .tenko/plugin-data/example/data.db，表名默认为 example_note。
+
+    宿主启动时自动建表，并自动执行新增表、新增可空列、新增索引；删除或修改列需要
+    显式迁移脚本，否则会被拒绝。
+    """
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[str] = mapped_column(String(32), index=True)
+    text: Mapped[str] = mapped_column(String(200))
+
+
+example_command = Alconna(
+    "示例",
+    Args["note?", str],
+    meta=CommandMeta(
+        "统计你使用示例命令的次数，可附带一条备注",
+        usage="示例 [备注]",
+        example="/示例 今天也要加油",
+    ),
+)
+
+
+# 权限用装饰器声明（放在 command.on 之下）：不足时宿主统一回复，/帮助 <编号> 也会显示。
+@command.on(example_command)
+@require(Permission.User)
+async def example(session: Session, note: Query[str] = Query("note", "")):
+    ctx = context_from_session(session)
+    # Store 是同步读写：读改写之间没有 await，协程不会交错，所以不需要加锁。
+    records = visits.load(default={})
+    record = records.setdefault(ctx.user_id, {"count": 0})
+    record["count"] += 1
+    visits.save(records)
+
+    # 会话按模型自动路由到插件自己的库；事务由 commit 显式提交。
+    async with get_session() as db:
+        previous = await db.scalar(
+            select(Note.text)
+            .where(Note.user_id == ctx.user_id)
+            .order_by(Note.id.desc())
+            .limit(1)
+        )
+        if note.result:
+            db.add(Note(user_id=ctx.user_id, text=note.result))
+            await db.commit()
+
+    reply = f"{config.greeting}，这是你第 {record['count']} 次使用示例命令"
+    return f"{reply}（上次备注：{previous}）" if previous else reply

tenko_plugin_example-0.1.0/tests/conftest.py

@@ -0,0 +1,81 @@
+"""用真实的 Tenko 宿主加载插件，不启动网络服务。
+
+插件依赖的宿主能力都从 ``tenko_api`` 取得，所以这里只需要：Entari 运行环境、
+插件启用状态和配置。
+"""
+
+import json
+import os
+from datetime import datetime
+from types import SimpleNamespace
+
+import pytest
+import pytest_asyncio
+from arclet.entari import Entari
+from arclet.entari.config import EntariConfig
+from satori import Channel, ChannelType, EventType, Guild, Login, MessageObject, User
+from satori.model import Event, Member
+
+from tenko.config import DatabaseConfig
+from tenko.db.bootstrap import load_database_plugin
+from tenko.db.migration import run_database_migrations
+from tenko.host.plugins import PluginRuntime
+
+
+@pytest.fixture(scope="session")
+def host(tmp_path_factory):
+    """会话级宿主：工作目录切到临时目录，数据目录 ``.tenko/plugin-data`` 落在其中。"""
+
+    root = tmp_path_factory.mktemp("tenko-host")
+    previous = os.getcwd()
+    os.chdir(root)
+    EntariConfig(root / "entari.yml")
+    Entari(ignore_self_message=True)
+    (root / "state.json").write_text(json.dumps({"enabled": ["example"]}))
+    yield SimpleNamespace(root=root)
+    os.chdir(previous)
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session")
+async def runtime(host):
+    """按真实的入口发现机制加载 example 插件，并传入 ``[plugin_config.example]``。
+
+    和宿主启动一样：先加载数据库插件，加载插件时登记它的库，再初始化服务并迁移。
+    """
+
+    service = load_database_plugin(
+        DatabaseConfig(url=f"sqlite+aiosqlite:///{host.root / 'main.db'}")
+    )
+    runtime = PluginRuntime(
+        host.root / "no-builtin", state_file=host.root / "state.json"
+    )
+    await runtime.load_all(external_configs={"example": {"greeting": "测试问候"}})
+    await service.initialize()
+    await run_database_migrations(service)
+    yield runtime
+    runtime.unload("example")
+    for engine in service.engines.values():
+        await engine.dispose()
+
+
+@pytest.fixture(scope="session")
+def module(runtime):
+    """已加载的插件模块。"""
+
+    return runtime.loaded_plugins["example"].module
+
+
+def make_session(user_id: str, text: str = ""):
+    """构造 context_from_session 能解析的最小群聊 Session。"""
+
+    event = Event(
+        type=EventType.MESSAGE_CREATED,
+        timestamp=datetime.now(),
+        login=Login(platform="onebot", user=User("10001")),
+        channel=Channel("40001", ChannelType.TEXT),
+        guild=Guild("40001", "Tenko"),
+        member=Member(user=User(user_id)),
+        user=User(user_id),
+        message=MessageObject.from_elements("50001", []),
+    )
+    return SimpleNamespace(event=SimpleNamespace(_origin=event))

tenko_plugin_example-0.1.0/tests/test_plugin.py

@@ -0,0 +1,46 @@
+import sqlite3
+
+from arclet.entari.command import Query
+from conftest import make_session
+
+from tenko.host.guards import command_requirements
+from tenko.host.perm import Permission
+from tenko.host.plugins import PluginRuntime
+
+
+def test_entry_point_is_discovered_but_disabled_by_default(tmp_path):
+    """第三方插件默认关闭：没有状态文件时只被发现，不被加载。"""
+
+    runtime = PluginRuntime(tmp_path / "no-builtin", state_file=tmp_path / "none.json")
+    info = next(item for item in runtime.discover() if item.name == "example")
+    assert info.source == "external"
+    assert not runtime.is_enabled(info)
+
+
+async def test_plugin_loads_with_config_and_declared_metadata(runtime, module):
+    assert runtime.is_loaded("example")
+    assert module.config.greeting == "测试问候"
+    metadata = runtime.loaded_plugins["example"].metadata
+    assert (metadata.feature_scope, metadata.rate_weight) == ("group", 1)
+    assert metadata.group_level == Permission.ActiveGroup
+    # 装饰器声明的权限登记在命令上，/帮助 <编号> 据此显示。
+    requires = command_requirements(runtime.loaded_plugins["example"])
+    assert requires["示例"] == {"user": Permission.User}
+    # 命令归属于 example，所以功能开关和限流会按插件 ID 生效。
+    assert runtime.command_owner("示例").name == "example"
+
+
+async def test_command_counts_visits_and_remembers_the_last_note(module, host):
+    session = make_session("20001")
+
+    first = await module.example.callable_target(session, Query("note", "备忘"))
+    second = await module.example.callable_target(session, Query("note", ""))
+
+    assert str(first) == "测试问候，这是你第 1 次使用示例命令"
+    assert "第 2 次" in str(second) and "上次备注：备忘" in str(second)
+    assert module.visits.load()["20001"] == {"count": 2}
+    # 备注在插件自己的库里，不在宿主主库。
+    with sqlite3.connect(host.root / ".tenko/plugin-data/example/data.db") as db:
+        assert db.execute("SELECT user_id, text FROM example_note").fetchall() == [
+            ("20001", "备忘")
+        ]