ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

发布与模块商店指南

Tip

什么时候需要读这篇:将作品发布到 PyPI / 模块商店时。不需要则跳过,不影响其它功能的使用。

将你开发的模块或适配器发布到 ErisPulse 模块商店,让其他用户可以方便地发现和安装。

模块商店概述

ErisPulse 模块商店是一个集中式的模块注册表,用户可以通过 CLI 工具浏览、搜索和安装社区贡献的模块、适配器。

浏览与发现

# 列出远程可用的所有包
epsdk list-remote

# 只查看模块
epsdk list-remote -t modules

# 只查看适配器
epsdk list-remote -t adapters

# 强制刷新远程包列表
epsdk list-remote -r

你也可以访问 ErisPulse 官网 或 ErisPulse Workbench 的「模块列表」在线浏览模块商店。

支持的提交类型

类型 说明 Entry-point 组
模块 (Module) 扩展机器人功能、实现业务逻辑 erispulse.module
适配器 (Adapter) 连接新的消息平台 erispulse.adapter

快速发布

整个过程只需要三步:配置项目 → 发布到 PyPI → 提交到模块商店。

1. 配置 pyproject.toml

确保项目目录包含 pyproject.toml、README.md,并根据类型配置 entry-points:

模块

[project]
name = "ErisPulse-MyModule"
version = "1.0.0"
description = "模块功能描述"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [ { name = "yourname" } ]
dependencies = [
    "ErisPulse>=2.0.0",
]

[project.entry-points."erispulse.module"]
"MyModule" = "MyModule:Main"

适配器

[project]
name = "ErisPulse-MyAdapter"
version = "1.0.0"
description = "适配器功能描述"
requires-python = ">=3.10"

[project.entry-points."erispulse.adapter"]
"myplatform" = "MyAdapter:MyAdapter"

注意:包名建议以 ErisPulse- 开头,便于用户识别。Entry-point 的键名(如 "MyModule")将作为模块在 SDK 中的访问名称。

2. 发布到 PyPI

# 构建 + 发布(需要 PyPI 账号)
pip install build twine
python -m build
python -m twine upload dist/*

发布成功后验证安装:

pip install ErisPulse-MyModule

3. 提交到模块商店(ErisPulse Workbench)

模块收录与认证统一由 ErisPulse Workbench 承载:**https://workbench.erisdev.com/**。提交后经 repository_dispatch 下发到模块索引仓库,workflow 完成即入商店(通常数分钟)。

方式一:网页提交(推荐首次使用)

  1. 打开工作台,用 GitHub / Codeberg 账号登录(历史时期的模块可在模块详情页走「认领此模块」找回归属)
  2. 左侧「提交新模块」→ 按表单填写:名称 / 类型(module · adapter)/ PyPI 包名 / 描述(≥10 字符)/ 作者 / 仓库地址(github.com 或 codeberg.org)/ 分类(1 工具 · 2 娱乐 · 3 管理 · 4 通知 · 5 AI · 6 平台 · 7 分析)/ 标签 / 最低 SDK 版本
  3. 提交即生效并标记「未验证」(仅表示尚未官方审核,用户安装时会收到风险提示需确认);「认证审核」通过后转为「已验证」

方式二:API 自主提交(CLI / CI 场景)

① 生成访问令牌:工作台「开放接口 → 访问令牌」页 → 填写名称 →「生成令牌」。格式为 epat_ + 40 位十六进制,仅生成时显示一次;开启两步验证的账户可勾选「免动态码」,之后敏感接口不再要求 totp_code。

② 调用约定:

Authorization: Bearer epat_…
Content-Type: application/json

请求体必须为 UTF-8 编码的 JSON。Windows 终端默认 GBK,中文会被写成非 UTF-8 字节,服务端直接拒绝(报错 415 ENCODING_INVALID 并指出问题字段)——先执行 chcp 65001,或把请求体存成 UTF-8 文件后用 curl --data-binary @body.json 提交。

③ 提交模块:

curl -X POST https://workbench.erisdev.com/api/modules/submit \
  -H "Authorization: Bearer epat_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyModule",
    "type": "module",
    "package": "ErisPulse-MyModule",
    "description": "模块描述,至少 10 字符",
    "author": "Your Name",
    "repository": "https://github.com/you/MyModule",
    "category": 1,
    "tags": ["工具"],
    "i18n": ["zh", "en"],
    "min_sdk_version": ">=2.7.0"
  }'

④ 查询与管理:GET /api/modules/ops?name=MyModule&type=module 查提交/审核进度;POST /api/modules/manage 编辑 / 转正 / 删除;POST /api/modules/batch 批量操作。完整端点表见工作台内置「使用文档」(令牌 / 归属认领 / 模块管理 / FAQ)。

4. 管理已发布的模块

登录工作台「模块列表」→ 自己的模块详情页,可编辑描述、仓库、标签等(版本号自动从 PyPI 同步)、删除模块、发起归属认领;API 侧走 manage / batch 端点。

刚提交的模块可能需要几分钟才会出现在列表中。

更新已发布模块

  1. 更新 pyproject.toml 中的 version
  2. 重新构建并上传:python -m build && python -m twine upload dist/*
  3. 模块商店会自动同步 PyPI 上的最新版本

用户通过 epsdk upgrade MyModule 即可升级。

发布前检查清单

在推送到 PyPI 之前,请逐项确认以下内容:

代码质量

  • 所有公开 API 有类型注解(函数签名和返回值)
  • 所有公开方法有文档字符串("""...""" 格式,包含 :param / :return / :raises)
  • 通过 ruff check(无警告)
  • 测试覆盖率 ≥ 80%
  • 通过 pytest 全部用例

兼容性

  • pyproject.toml 声明了最低 SDK 版本:dependencies = ["ErisPulse>=x.y.z"]
  • 模块在 get_meta() 的 ModuleMeta(min_sdk_version="x.y.z") 声明了运行时最低 SDK 版本(适配器用类属性 min_sdk_version)——用户环境 SDK 过低时框架在加载期明确报错并跳过,而非报出难以定位的运行时异常
  • 测试了 Python 3.10 / 3.11 / 3.12 / 3.13
  • 测试了目标操作系统(Windows / Linux / macOS,如适用)
  • 无循环导入依赖

配置

  • 如果使用声明式配置(ConfigClass + BaseConfig / BotAccountConfig),配置字段有 description(推荐 i18n 格式)和 ui 元数据
  • 如果注册了 i18n 翻译键,已覆盖所有 5 种语言(zh-CN / zh-TW / en / ja / ru)
  • 敏感字段标记了 secret=True

文档

  • README.md 有安装说明和基本使用示例
  • README.md 说明了配置方式(配置文件示例 + 环境变量)
  • CHANGELOG.md 记录了所有变更
  • 适配器更新了平台特性文档(支持的 Send 类型、事件类型等)

发布

  • pyproject.toml 版本号已更新
  • 构建通过:python -m build
  • 已推送到 PyPI:python -m twine upload dist/*
  • 安装验证通过:pip install ErisPulse-xxx && epsdk run

开发模式测试

在正式发布前,可以使用可编辑模式在本地测试:

epsdk install -e /path/to/MyModule
# 或
pip install -e /path/to/MyModule

常见问题

包名必须以 ErisPulse- 开头吗?

不强制,但强烈推荐。这有助于用户在 PyPI 上识别 ErisPulse 生态的包。

一个包可以注册多个模块吗?

可以。在 entry-points 中配置多个键值对即可:

[project.entry-points."erispulse.module"]
"ModuleA" = "MyPackage:ModuleA"
"ModuleB" = "MyPackage:ModuleB"

审核需要多长时间?

通常在 1-3 个工作日内完成。你可以在模块商店「我的模块」中查看验证状态。

通过 Docker 镜像分发应用

如果你的应用不适合发布到 PyPI(如包含私有依赖、需要预配置环境),可以通过 GitHub Container Registry (GHCR) 发布 Docker 镜像,让其他用户 docker pull 一键启动。

适用场景

  • 你有一个完整的机器人应用(模块 + 配置 + 入口脚本),想一键分发
  • 模块/适配器依赖私有包或有特殊安装流程,不适合 PyPI
  • 想提供开箱即用的部署方案,降低用户使用门槛

1. 创建 Dockerfile

基于 ErisPulse 官方镜像构建,只需添加你的模块即可:

FROM erispulse/erispulse:latest

LABEL org.opencontainers.image.title="ErisPulse-MyModule" \
      org.opencontainers.image.description="模块描述" \
      org.opencontainers.image.url="https://github.com/yourname/ErisPulse-MyModule" \
      org.opencontainers.image.source="https://github.com/yourname/ErisPulse-MyModule"

COPY pyproject.toml README.md ./
COPY MyModule/ ./MyModule/

RUN uv pip install --system -e .

如果模块需要额外的系统依赖(如 SSH 客户端等),在 RUN uv pip install 之后添加:

RUN apt-get update && apt-get install -y --no-install-recommends \
    openssh-client \
    && rm -rf /var/lib/apt/lists/*

erispulse/erispulse:latest 已包含 ErisPulse、ErisPulse-Dashboard、Python 运行时和 uv,无需重复安装。

2. 创建 GitHub Actions 工作流

在 .github/workflows/docker-publish.yml 中创建:

name: 发布 Docker 镜像

on:
  workflow_dispatch:
  push:
    branches:
      - main
    tags:
      - "v*"

permissions:
  contents: read
  packages: write

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository_owner }}/my-bot

jobs:
  docker-publish:
    runs-on: ubuntu-latest

    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 QEMU (多架构支持)
        uses: docker/setup-qemu-action@v3

      - name: 设置 Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 登录 GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 提取 Docker 元数据
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=raw,value=latest

      - name: 构建并推送 Docker 镜像
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

GITHUB_TOKEN 由 GitHub Actions 自动提供,无需手动创建密钥。

3. 触发构建

推送代码或打 Tag 即可自动构建:

# 推送到 main 分支触发
git push origin main

# 或打 Tag 触发
git tag v1.0.0
git push origin v1.0.0

也可在 GitHub 仓库的 Actions 页面手动触发。

4. 设置镜像为公开

GHCR 镜像默认为 private,需要在 GitHub 设置为 Public 后其他用户才能免登录拉取:

  1. 进入仓库 → Packages → 点击对应 Package
  2. Package settings → Danger Zone → Change visibility → Public

5. 用户使用

构建完成后,用户可以用 docker run 一行启动:

docker run -d \
  --name my-bot \
  -p 8000:8000 \
  -v $(pwd)/config:/app/config \
  -e TZ=Asia/Shanghai \
  -e ERISPULSE_DASHBOARD_TOKEN=your-token \
  --restart unless-stopped \
  ghcr.io/<your-username>/my-bot:latest

或使用 docker-compose.yml:

services:
  my-bot:
    image: ghcr.io/<your-username>/my-bot:latest
    container_name: my-bot
    ports:
      - "8000:8000"
    volumes:
      - ./config:/app/config
    environment:
      - TZ=Asia/Shanghai
      - ERISPULSE_DASHBOARD_TOKEN=${ERISPULSE_DASHBOARD_TOKEN:-}
    restart: unless-stopped

同时发布到 Docker Hub

扩展工作流,在登录步骤前添加 Docker Hub 登录,并在 images 中增加 Docker Hub 地址:

      - name: 登录 Docker Hub
        uses: docker/login-action@v3
        with:
          registry: docker.io
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: 提取 Docker 元数据
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: |
            docker.io/<your-dockerhub-username>/my-bot
            ghcr.io/${{ github.repository_owner }}/my-bot

需要在仓库 Settings → Secrets 中添加 DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN。

Docker 镜像 vs PyPI 发布

特性 Docker 镜像 (GHCR) PyPI 发布
分发方式 docker pull 一键运行 pip install + 手动配置
适用范围 完整应用/解决方案 单个模块/适配器
私有依赖 天然支持 需要私有 PyPI 源
模块商店 不适用 可提交到模块商店
多架构 支持 amd64/arm64 与架构无关

两种方式不冲突——你可以同时通过 PyPI 发布模块到模块商店,又通过 GHCR 提供开箱即用的 Docker 镜像。

下一步

发布前把质量关

发布后让用户用起来