發布與模組商店指南

將你開發的模組或適配器發布到 ErisPulse 模組商店，讓其他使用者可以輕鬆地發現和安裝。

模組商店概述

ErisPulse 模組商店是一個集中式的模組註冊表，使用者可以透過 CLI 工具瀏覽、搜尋和安裝社群貢獻的模組與適配器。

瀏覽與發現

# 列出遠端可用的所有套件
epsdk list-remote

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

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

# 強制刷新遠端套件列表
epsdk list-remote -r

你也可以造訪 ErisPulse 官網 在線瀏覽模組商店。

支援的提交類型

快速發布

整個過程只需要三步：配置項目 → 發布到 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 模組商店，點擊「提交模組」，登入後填寫模組資訊即可。

支援的登入方式：GitHub、Codeberg、雲湖，任選其一即可。

填寫要點：

• 模組名稱、描述、倉庫位址
• 最低 SDK 版本：如果不確定，填寫 ErisPulse 最新發行版 版本號即可

提交後立即生效，使用者可透過模組來源安裝。模組會被標記為「未驗證」，維護者審核通過後改為「已驗證」。

關於驗證狀態：

• 「未驗證」僅表示尚未經過官方審核，不代表模組有問題
• 使用者透過 epsdk install 安裝未驗證模組時會收到風險提示，需確認後才可繼續安裝

4. 管理已發布的模組

在模組商店點擊「提交模組」並登入後，切換到「我的模組」標籤頁，可以：

• 編輯 — 修改模組描述、倉庫位址、標籤等資訊，版本號會自動從 PyPI 同步
• 刪除 — 從模組商店移除模組（不可撤銷）

剛提交的模組可能需要幾分鐘才會顯示在「我的模組」列表中。

更新已發佈模組

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 發布

兩種方式不衝突——你可以同時透過 PyPI 發布模組到模組商店，又透過 GHCR 提供開箱即用的 Docker 鏡像。