publish-moviepilot-plugin

发布 MoviePilot 插件

使用此技能，通过 GitHub 发布和维护 MoviePilot 本地插件仓库，同时保护本地机密和无关插件。

范围

• 将一个本地插件发布到 GitHub 仓库，插件目录为 plugins.v3/<plugin_id_lower>/、 plugins.v2/<plugin_id_lower>/ 或 plugins/<plugin_id_lower>/。
• 仅将该插件的条目合并到 package.v3.json、package.v2.json 或 package.json。
• 写入前预览本地与远程的差异。
• 将远程插件文件拉回本地插件源目录。
• 仅当用户明确选择自动创建时，才创建目标 GitHub 仓库；除非用户要求设为私有，否则仓库默认为公开。
• 在可用时复用 MoviePilot 设置 GITHUB_TOKEN、REPO_GITHUB_TOKEN 和 PLUGIN_LOCAL_REPO_PATHS。

事实依据

• 本地插件开发规则：skills/create-moviepilot-plugin/SKILL.md。
• 本地插件源发现方式：app/adapters/external/market.py、 PluginHelper.get_local_repo_paths()。
• GitHub 令牌设置：app/runtime/config.py，尤其是 GITHUB_TOKEN 和 REPO_GITHUB_TOKEN。
• 插件包目录结构：
  • V3：package.v3.json 和 plugins.v3/<plugin_id_lower>/
  • V2：package.v2.json 和 plugins.v2/<plugin_id_lower>/
  • 旧版：package.json 和 plugins/<plugin_id_lower>/

准备工作

1. 确定目标插件 ID 和本地源仓库。
   • 如果用户提供了路径，则使用该路径。
   • 否则查询 PLUGIN_LOCAL_REPO_PATHS；如果恰有一个已配置仓库包含该插件，则使用它。
   • 如果有多个已配置仓库包含该插件，则询问用户要使用哪一个。
2. 将 GitHub 仓库确定为 owner/repo。
   • 优先使用用户明确指定的仓库。
   • 如果用户未指定，只有在本地源有明显的 Git 远程地址时才进行推断。
   • 如果两者都不可用，询问用户是使用现有仓库还是自动创建新的公开仓库。
   • 如果用户选择现有仓库，则询问 owner/repo。
   • 如果用户选择自动创建，则询问目标 owner/repo，并说明仓库默认公开。
   • 除非用户明确要求，否则不要创建私有仓库。
3. 选择软件包版本目录结构。
   • 如果插件位于 plugins.v3/<plugin_id_lower>/ 下，或仓库提供 package.v3.json（当前 MoviePilot V3 主机），则优先使用 v3。
   • 如果存在 package.v2.json 或 plugins.v2/<plugin_id_lower>/，则优先使用 v2。
   • 仅当本地插件位于 plugins/ 下时才使用旧版结构。
4. 确认令牌是否可用。
   • 如果已配置，优先使用目标仓库对应的 REPO_GITHUB_TOKEN。
   • 否则使用 GITHUB_TOKEN。
   • 如果未配置令牌，则要求用户先进行配置，再推送。对于公开仓库，仍可在没有令牌的情况下运行只读预览。

脚本

使用 scripts/publish_plugin.py 执行确定性的 GitHub 操作。

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py preview \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py push \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2 \
  --message "Publish MyPlugin v1.0.0"

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py pull \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2

# V3 插件仓库（package.v3.json + plugins.v3/）
python skills/publish-moviepilot-plugin/scripts/publish_plugin.py push \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v3 \
  --message "Publish MyPlugin v1.0.0"

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py create-repo \
  --repo owner/repo

选项：

• --package-version v3|v2|legacy|auto：布局选择器。auto 会根据插件目录的实际位置 （plugins.v3 → plugins.v2 → plugins）确定布局，然后再检查清单文件作为后备， 因此仍同时保留两份清单的仓库也能保持正确。对于当前的 MoviePilot V3 插件仓库，请显式传入 v3。
• create-repo：创建目标 GitHub 仓库。默认可见性为公开；仅在用户明确要求设为私有时使用 --private。
• preview：比较本地筛选后的文件与远程文件，并打印 JSON。
• push：上传已更改的文件并合并插件 package 条目。
• pull：将远程插件文件和 package 条目写入本地源码。
• --create-repo-if-missing：执行 push 时，如果 GitHub 报告目标仓库不存在，则创建公开仓库。
• --delete-remote：执行 push 时，删除远程存在但本地已不存在的插件文件（排除规则生效后）。
• --force：执行 pull 时，允许覆盖与远程文件不同的本地文件。
• --include PATTERN：添加默认排除的文件。
• --exclude PATTERN：添加额外的忽略模式。
• --dry-run：打印计划进行的更改，但不写入。
• --proxy URL：为 GitHub API 请求使用显式的 HTTP/HTTPS 代理。

push 通过 Git Data API（blob → tree → commit → 移动分支引用）提交：无论一次更改 多少文件，都只产生一个 commit，CI 只会触发一次、diff 完整，package 版本与源码 版本不会出现中间状态；返回的 JSON 中包含 commit_sha。空仓库会自动创建根提交并建立分支。

GitHub Release 与 README

push 只同步插件源码与 package 条目，不会创建 GitHub Release，也不会修改 README。如果目标仓库使用 GitHub Actions 打包（例如 .github/workflows/plugins-release.yml，产物为 Plugin_vX.Y.Z tag 和 zip/tar.gz + sha256 资产）：

• package 条目必须显式设置 "release": true，否则即使工作流运行也不会发布版本。
• 自动触发依赖同一次 push 中 package 文件的 version 发生变化。逐文件提交时， package.v3.json 的更改可能落在另一个提交中，导致 diff 中看不到它，从而静默跳过； 遇到这种情况，请改用 workflow_dispatch（source_directory + plugin_id）手动触发。
• README 中的插件表格与说明需要单独编辑并推送（Contents API 或 git），不属于 push 的职责范围。

安全规则

• 除非用户明确要求直接 push 且已审阅 diff，否则始终先运行 preview。
• 如果尚未确定仓库，请让用户选择： 使用已有 GitHub 仓库 或 自动创建 GitHub 仓库（默认 public）。
• 只有在用户明确选择自动创建后，才运行 create-repo 或 push --create-repo-if-missing。
• 除非明确包含以下文件，否则绝不上传： .env、.env.*、config/、data/、cache/、logs/、tmp/、 __pycache__/、.pytest_cache/、.mypy_cache/、.ruff_cache/、 .DS_Store、*.pyc、*.pyo、*.db、*.sqlite、*.sqlite3、*.log、 *.bak、*.tmp、*.secret、*.key、*.pem、*.crt、*.p12、*.pfx、 node_modules/。
• 对于 Vue federation 插件，如果存在构建后的运行时资产，请将其发布到 dist/assets/ 下；不要将其作为生成文件排除。
• 不要覆盖或删除其他插件的 package 条目。
• 读取 package 或插件文件之前，先固定远程 commit。基于同一棵树和父提交构建单个发布 commit。如果目标分支在此期间前进，则因 non-fast-forward 冲突而停止，然后针对新的快照重新运行 preview；绝不要强制推送或复用过时的合并内容。
• 不要记录或打印 GitHub token 值。
• 对于 push 操作，分别报告已创建、已更新、已删除、已跳过和被拒绝的文件。
• 对于 pull 操作，即使使用 --force，也要保留本地排除文件。 如果本地 package JSON 无效，则在写入任何本地文件之前停止 pull，包括 --force 模式。 如果本地插件文件或 package 元数据存在差异，则停止整个 pull，除非使用 --force。 其他插件的 package 条目保持不变。
• 使用 auto 布局时，分别检查每个已配置的本地仓库；工作目录不会决定其他仓库的布局。

示例

用户要求：把本地 MyPlugin 发布到我的 GitHub 插件仓库

1. 在配置的 PLUGIN_LOCAL_REPO_PATHS 下查找 MyPlugin。
2. 如果无法推断出 owner/repo，询问是使用现有仓库还是创建新的公开仓库。
3. 运行 preview 并总结差异。
4. 只有在用户确认或要求立即发布后，才运行 push。

用户要求：发布插件，没有 GitHub 仓库

1. 询问目标 owner/repo，并确认是否自动创建。
2. 运行 create-repo，或使用 push --create-repo-if-missing。
3. 仓库创建成功后，继续运行 preview 和 push。

用户要求：同步 GitHub 上 MyPlugin 的最新代码到本地

1. 运行 pull，不使用 --force。
2. 如果报告存在本地冲突，列出冲突路径，并询问是强制覆盖还是手动解决。

最终检查清单

• 插件 ID 与 package 对象键一致。
• package 文件和插件目录布局与所选版本一致。
• 已拒绝或跳过敏感文件和运行时本地文件。
• 已在推送前展示预览，除非用户明确要求跳过。
• 仅当此内置技能本身发生更改时，最终回复才提及是否需要重启本地 Agent。