写社区插件并上架

字数

2460 字

阅读时间

11 分钟

目标：把仓库整理成商店可识别的形态，自检通过后上架到社区插件商店
准备：已完成插件开发；了解 Golden Plugin 代码合同
完成之后：向 community-plugin-index 提 PR，收录后用户可安装

用户安装见 社区插件商店。

你要完成什么

阶段	产出
开发	符合 NoneBot 包结构的独立仓库
自检	community_plugin_author.py check 通过（可选 L2 画像）
收录	向 community-plugin-index 追加 index.json 条目并提 PR

三种接入方式（落点相同）

| 方式 | 适用 | 做法 | | --- | --- | | 索引收录 | 希望公开展示、被商店发现 | 向 community-plugin-index 提 PR | | Git 直装 | 运维自行安装，不进公共索引 | WebUI 插件商店 → 社区插件 → 从 Git 安装 | | 手工投放 | 内网或本地调试 | 复制目录到 local/plugins/<id>/ |

同名冲突时 local/plugins 优先于官方插件。

步骤 1：整理插件目录

最小结构（与 NoneBot 一致）：

my_plugin/
├── __init__.py          # 含 __plugin_meta__（PluginMetadata）
├── README.md            # 商店详情页会尝试展示
└── assets/
    └── icon.png         # 推荐 256×256，商店卡片图标

项	规则
插件 ID	小写字母开头，仅 a-z / 0-9 / _，最长 64；与 local/plugins/<id>/ 目录名一致
PLUGIN_ID	可在 __init__.py 定义，便于与目录名对齐
最低版本	依赖 Pallas-Bot 内核时在 README 注明（如 4.0.0）
权限	接入 cmd_perm 的 command_permissions 后，帮助图自动展示「何人可用」

步骤 2：维护版本与更新日志

1. 版本号：遵循语义化版本（如 0.1.0）。index.json 可选字段 version 应与 git tag、CHANGELOG.md 对应。
2. git tag：发布时打 vX.Y.Z（如 v0.1.0），便于按 ref 安装。
3. CHANGELOG.md：仓库根目录维护，推荐 Keep a Changelog：日常记到 ## [Unreleased]，发布时按版本归档。
4. 已收录插件：发版后还须更新索引里自己那条的 version（见 步骤 6）；商店分别展示索引版本与本地安装版本。

本地安装版本优先读取插件根目录 pyproject.toml 的 [project].version；没有有效声明时读取 __plugin_meta__.extra['version'] 字面量。没有声明时返回空版本，界面显示提交或未知；不会用索引版本冒充。

控制台 插件商店 → 详情 → 更新日志 取值顺序：

1. 仓库根目录 CHANGELOG.md（首选）
2. 缺失时，对已装到 local/plugins/<id>/ 的副本按本地 git 提交标题兜底生成

提醒

建议维护 CHANGELOG.md。缺失时用户只能看到原始提交记录；README 中可写当前版本号（如「当前版本：v0.1.0」），不要依赖徽章组件。

示范仓库：pallas-community-plugin-interact（含 community-index.entry.json，发版时同步其 version）。

社区插件画像（L1 / L2）

公开收录与 WebUI「指令与能力」看 metadata 完整度：

档位	要点
L1（索引默认门槛）	command_permissions + menu_data + 规范 usage
L2（优选）	L1 + command_limits + 鉴权 ID 一致；命令推荐 plugin_sdk

check --profile L1|L2 校验 metadata 与命令 ID 一致性；目录、图标、README 仍是基础结构检查。

步骤 3：准备图标与索引元数据

商店卡片与插件列表视觉资源优先级（resolve_catalog_visuals()）：

1. 已安装插件包内 assets/（/pallas/plugin-assets/<plugin_id>/…）
2. 商店资源快照缓存（/pallas/store-assets/…）
3. 索引 / 官方插件条目中的 cover、icon、avatar（完整 URL）
4. 自动推断远程：https://raw.githubusercontent.com/<owner>/<repo>/<ref>/assets/icon.png（Gitee 同理）
5. 作者 GitHub 头像（author 或仓库 owner）

推荐：仓库放 assets/icon.png（可选 cover.webp、avatar.png），索引只写 repository；装到 local/plugins 后控制台直接读包内文件。

包内路径规则：Golden Plugin · 包内视觉资源。

索引单条示例（追加到 index.json 的 plugins）：

{
  "id": "my_plugin",
  "name": "我的插件",
  "description": "一句话说明功能。",
  "repository": "https://github.com/you/my_plugin.git",
  "ref": "main",
  "version": "0.1.0",
  "author": "your_github_id",
  "tags": ["工具"],
  "min_pallas_version": "4.0.0"
}

提 PR 前更新根级 updated_at（ISO 日期），便于客户端刷新图标缓存。

索引条目声明 min_pallas_version 后，Bot 的社区 Git 安装和更新（包括自动更新）会在改动本地插件前校验当前版本；低于下限或当前版本 / 非空下限无法解析时拒绝。缺少声明、插件未收录或索引暂不可用时仍可操作，但成功结果会提示兼容性未验证。

步骤 4：用作者工具 CLI 自检

在 Pallas-Bot 仓库根目录执行。

校验插件目录

uv run python tools/community_plugin_author.py check path/to/my_plugin
uv run python tools/community_plugin_author.py check path/to/my_plugin --profile L2

检查 __init__.py、ID 规范、推荐 assets/icon.png 与 README，并输出画像摘要 JSON。

生成索引条目

从插件目录读 PluginMetadata 草稿：

uv run python tools/community_plugin_author.py index-entry ./my_plugin \
  --repository https://github.com/you/my_plugin.git \
  --author your_github_id \
  --tags "工具,示例"

无本地目录时也可只按仓库生成：

uv run python tools/community_plugin_author.py index-entry \
  --repository https://github.com/you/my_plugin.git \
  --id my_plugin \
  --name "我的插件" \
  --description "简介"

把 stdout 里的 JSON 追加到 community-plugin-index 的 index.json。

README 插件列表（索引仓 CI 自动）

不用手改 README 表格。 索引仓 CI 在 PR / push main 时跑 tools/sync_readme.py，更新 <!-- PLUGIN_LIST_START --> … <!-- PLUGIN_LIST_END -->。

本地预览（在 community-plugin-index 仓库根目录）：

python tools/sync_readme.py --write
python tools/sync_readme.py --check

校验 index.json

uv run python tools/community_plugin_author.py validate-index
# 或指定路径
uv run python tools/community_plugin_author.py validate-index /path/to/index.json

索引仓另有 python tools/validate_index.py（与 CI 一致）。

步骤 5：提交收录 PR

合并前对照：

• 开源仓库，HTTPS clone 可访问（GitHub / Gitee / GitLab / Codeberg）
• 插件 ID 全局唯一，符合命名规范
• 仓库根即为 NoneBot 插件包（含 __init__.py），或 README 说明 clone 后路径
• assets/icon.png 或索引中提供 icon
• description 一句说清功能；min_pallas_version 如实填写
• 建议维护 CHANGELOG.md（Keep a Changelog），发布打 vX.Y.Z tag，条目可填 version
• 更新 index.json 的 updated_at

合并后 CI 同步 README 插件列表；Bot 拉远程 index.json 即可在商店展示。

步骤 6：发版后同步索引

插件已经收录后，每次正式发版（归档 CHANGELOG、打 vX.Y.Z tag）应同步更新公共索引，否则商店卡片上的 version 会落后于仓库。

1. 在插件仓完成发版：CHANGELOG.md 归档、vX.Y.Z tag、（若有）community-index.entry.json 的 version 一并改掉。
2. Fork / 检出 community-plugin-index，找到 index.json → plugins 里 同 id 的那一条。
3. 至少更新：
   • version → 与本次 tag 一致（不要带 v 前缀，如 0.1.3）
   • 根级 updated_at → 当天 ISO 日期或时间
   • 若说明、图标、min_pallas_version、ref 等有变，一并改
4. 本地校验：python tools/validate_index.py（或主仓 uv run python tools/community_plugin_author.py validate-index path/to/index.json）。
5. 向索引仓提 PR，标题建议：chore(index): <id> 升至 vX.Y.Z。

提醒

ref 若指向 main，用户重装会拉到最新代码；索引版本以索引 version 为准，本地版本以安装目录中的声明为准。不要新增第二条同 id 条目，只改已有那条。

本仓可放一份与索引对齐的 community-index.entry.json（见示范仓），发版时先改它，再复制字段到索引 PR，减少漏改。

可选接入方式：发布后自动创建索引 PR

这是可选接入方式，不替代上文的手工索引 PR 流程，也不是官方 PyPI 发版通道。目前只有 TogetsuDo/pallas-plugin-memes 完成集成，并非全部 9 个仓库均已接入。默认关闭；要使用时，插件仓与索引仓都须各自部署工作流并配置所需 token、变量和 environment，本说明不代为启用或配置。

启用步骤：

1. 在插件仓与索引仓分别部署并配置各自的工作流。
2. 在索引仓创建 community-index-release environment，仅允许 main 分支部署；将 INDEX_PR_TOKEN 配置为 environment secret。该凭据仅需索引仓 Contents: read/write 与 Pull requests: read/write 权限，不可使用默认 GITHUB_TOKEN 替代。
3. 在每个采用该接入方式的插件仓配置 COMMUNITY_INDEX_DISPATCH_TOKEN，其 fine-grained PAT 仅授予目标索引仓 Actions: write 权限。当前 workflow 直接使用 secret，不负责签发或刷新 GitHub App 安装 token；若使用 App，须另行实现即时签发/刷新，本试点不包含该能力，不要将短期 App token 长期存为 secret。
4. 在两仓分别设置 COMMUNITY_INDEX_SYNC_ENABLED=true。

触发 tag、插件元数据版本与 CHANGELOG 版本须一致，格式为正式 vX.Y.Z。自动流程只更新索引版本并创建 PR；CI 通过后仍须人工审核并合并，不会自动合并。条目的 ref=main 仍指向主分支，不会因发布自动固定到 tag。失败时可能留下自动 PR 分支，可重试，不会强推覆盖；未启用或未接入时继续按上文手工同步。

成功信号

• community_plugin_author.py check（及可选 L2）通过。
• 索引 PR 合并后，商店能看到该插件；发版后索引 version 与 tag 一致。

私有 / 公会索引

站点可在 config/pallas.toml 用自建索引，不必进公共策展仓：

[env]
COMMUNITY_PLUGIN_INDEX_URL = "https://example.com/my-guild-index.json"

或落盘 data/pallas_config/community_plugin_index.json 覆盖远程。

接下来做什么

项	位置
商店使用	community-plugin-store.md
站点 local/plugins	站点定制
索引加载	src/console/webui/community_plugin_index.py
Git 安装	src/console/webui/community_plugin_install.py
作者工具	tools/community_plugin_author.py

最后编辑于 1 分钟前

查看完整历史

de4a6a8-docs: 同步主仓 Pallas-Bot@26eaadc (main)

bbc5adb-docs: 同步主仓 Pallas-Bot@47d5f93 (main)

d69e09f-docs: 同步主仓 Pallas-Bot@b761eb0 (main)

72f3ada-docs: 同步跨平台安装与主线收敛

a63b73a-docs: 同步主仓 Pallas-Bot@9e51d85 (main)

e261a3b-docs: 同步全站信息架构与社区投稿墙

0779fa4-docs: 同步主仓 Pallas-Bot@63d8b5c (main)

93b1e80-docs: 同步主仓 Pallas-Bot@5901a94 (main)

1746ca4-docs: 全站文风重校准与导航断链修复

8b3949d-docs: 同步 4.0 迁移与官方插件文档

7fc0ae1-docs: 同步下架 architecture 素材层

3bbc64f-docs: 同步去掉「站长」称呼

4b696d9-docs: 同步去掉元叙述开场

83356fd-docs: 同步用户向正文全文打磨

6858fe1-docs: 同步用户向续润色与侧栏标题

576ddc0-docs: 上站社区插件与 LLM guide，更新侧栏