• AI 插件
• AI 技能
• 插件系统
• 人工智能
• 开发工具

本文以 openJiuwen/agent-plugin（JiuwenSwarm 官方插件集合仓）为例，完整梳理agent-plugin 插件发布的全流程：打包阶段的文件黑名单规则、一条命令上传 Hub 市场、版本递增的硬性要求，以及出问题后的版本回滚策略，帮助新手把第一个插件包顺利送上货架。

发布前的两个准备条件

发布插件包前，你需要先确认两件事，否则会卡在第一步：

1. Hub 发布令牌：将令牌设置为环境变量JIUWENSWARM_HUB_TOKEN。注意令牌不写入任何文件、不进 git——这是发布脚本的硬约束，脚本启动时若发现令牌缺失或非法会直接报错退出（见 scripts/publish.py）。
2. jiuwenswarm 运行环境：三层校验中的热加载（L2）需要openjiuwen可导入，例如使用主仓的.venv。缺少环境时热加载校验会以 PARTIAL 状态跳过。

如果还没有本地仓库，可先克隆：

git clone https://gitcode.com/openJiuwen/agent-plugin

⚠️ 发布目标地址（Hub 地址）可通过JIUWENSWARM_HUB_BASE_URL环境变量覆盖，默认指向官方 swarmskills Hub，详见 docs/hub-publish.md。

打包黑名单：哪些文件不会进入发布包

这是很多新手容易踩坑的环节：plugins/<name>/目录里的内容就是用户最终拿到的全部内容。打包脚本 scripts/build.py 内置了一套强制排除规则，确保开发态产物和敏感文件绝不混进发布包。

黑名单目录与密钥文件

以下目录整目录排除，打包时自动跳过：

• .git、.archive、__pycache__、.pytest_cache、node_modules、out、.venv、tests、.idea

（规则见 scripts/build.py）

以下密钥与凭据类文件被单独拉黑：

• 文件名：id_rsa、id_ed25519、credentials.json、token.json、tokens.json、.DS_Store
• 文件后缀：.key、.p12、.pfx、.pyc
• 所有.env*文件（.env.example和.env.template除外）

其中.env.example/.env.template虽然允许进包，但脚本还会逐行检查内容：敏感键（token / key / password / secret 等）只允许空值或${VAR}占位符，发现疑似真实凭据会直接报错中止打包（见 scripts/build.py）。

四条硬性体积限制

除黑名单外，打包还受四重上限约束（scripts/build.py）：

此外，打包会拒绝 symlink（软链接）与非普通文件，防止通过链接绕过黑名单把包外内容"偷运"进发布包。

✅ 一个实用原则：测试、CI 配置、文档等开发态文件一律放在仓库层（如tests/plugins/<name>/），而不是塞进插件包目录。

一键发布：校验 → 打包 → 上传三步走

准备工作就绪后，发布只需一条命令：

python scripts/publish.py <插件名>

脚本会依次执行三个阶段（scripts/publish.py）：

1. 校验：自动运行 scripts/validate.py 完成 L0 规范 / L1 静态 / L2 热加载三层检查；
2. 打包：调用 scripts/build.py 按黑名单规则生成dist/<id>-<version>.zip（产物不进 git）；
3. 上传：以 multipart + Bearer token 方式 POST 到 Hub，请求头携带X-Checksum-SHA256校验和，Hub 端会核对返回的资产名、版本号与可见性是否一致，不一致立即报错。

上传成功后，脚本会打印 Hub 确认的asset_id；若资产进入人工审核，会提示pending_moderation（等待审核）状态。

常用参数速查

另外，publish.py会自动从 manifest.json 映射字段：asset_name取id、plugin_version取version、display_name取display_name.zh、标签取中文标签逗号拼接——也就是说，manifest 写什么，Hub 页面就展示什么。

版本递增规则：为什么必须升级版本号

Hub 以(package_name, version)二元组定位资产，由此衍生出几条发布纪律（docs/hub-publish.md）：

• 重发布必须递增 version：改了包内容就必须升级manifest.json中的version字段。patch 版本由发布流程管理，minor / major 需手动递增；
• 同版本覆盖需显式--force：因为用户端可能已缓存旧包，原地覆盖会导致"版本号没变但内容变了"的诡异状态，生产环境应避免；
• 合并到 main 不自动发布：正式发版按release/<插件名>-<版本>tag 触发发布流水线，与日常代码合并不耦合；
• 发布后记得对账：运行python scripts/catalog.py生成并提交更新后的 catalog/catalog.json，用于发布一致性核对；--check模式可校验清单是否漂移。

一句话记忆："内容变 → 版本号必变"。

版本回滚策略：发错了怎么办

发现问题版本时，按以下三步处理（docs/hub-publish.md）：

1. Hub 侧下架：联系 Hub 管理员或使用 Hub 控制台，下架/隐藏对应资产版本，先止血；
2. 仓内回退 + 递增重发：将包内容回退到正确 commit，递增 version 后重新发布——切记不要对已被用户安装的版本做原地--force覆盖；
3. 改名场景的特殊处理：插件id一经发布不可变。确需改名时，给旧 id 发最后一个版本、README 指向新插件，并在 renames.json 登记old-id → new-id映射，发布流程会据此在 Hub 侧维护资产别名。

新手发布清单（Quick Checklist）

发布前对照检查，一步不落：

• manifest.json无残留[TODO]，version已递增
• python scripts/validate.py --only <插件名> --require-hot-load校验全绿
• 包内无tests/、.venv等开发态目录，无密钥文件
• zip 产物 ≤ 50 MB
• JIUWENSWARM_HUB_TOKEN环境变量已设置
• 发布后运行python scripts/catalog.py并提交catalog/catalog.json

📎延伸阅读

• 发布流程权威文档：docs/hub-publish.md
• 插件包规范（manifest / skill / tool / rail）：docs/plugin-spec.md
• PR 安全审查清单：docs/review-checklist.md
• 仓库结构设计：docs/design/repo-structure-design.md
• 工具链脚本目录：scripts/
• 参考插件示例：plugins/example-plugin/

掌握"黑名单打包 → 一键上传 → 版本递增 → 规范回滚"这条主线，你的插件包就能安全、可追溯地上架 Hub 市场了。

• AI 插件
• AI 技能
• 插件系统
• 人工智能
• 开发工具