tg-bot-plugin-buildkit 0.2.0

基于共享合同核心构建并校验 TG-BOT 插件 bundle。

tg-bot-plugin-buildkit

tg-bot-plugin-buildkit 是面向 TG-BOT 单插件仓库的可复用构建与校验 CLI。

新建单插件仓库时，推荐直接从 tg-bot-plugin-template 起步；buildkit 负责承载底层 CLI、可复用 release workflow 与构建/验签合同，不承担模板脚手架职责。 插件作者侧的开发、编译、打包与正式发布说明应由模板仓库和本仓库承载；TG-BOT 主仓只保留平台运行时契约与验收语义。

完整正文：

• 编译打包与验收实战指南
• 构建、签名、校验与发布指南
• tg-bot-plugin-template 仓库中的 docs/作者侧开发与发布指南.md

它封装共享 tg-bot-plugin-contract-core 包，并提供：

• 消费 build/capabilities.externalize.json 的 schema_version/plugin_id/entrypoint/capabilities 合同，并回写 manifest capability 字段
• build
• embed-signature
• inspect
• verify
• validate --mode same-profile
• validate --mode target-profile
• benchmark
• install-local --dev-unsigned

本地开发

该包的正式发布形态固定依赖已发布的 tg-bot-plugin-contract-core。 README 只说明包名与职责边界，不写死补丁版本；具体已验证版本以 pyproject.toml、锁文件和发布工作流中的锁定值为准。

如果需要在未发布改动上进行本地多仓联调，CLI 仍可通过以下环境变量解析兄弟仓源码：

• TG_BOT_PLUGIN_CONTRACT_CORE_SRC=/path/to/tg-bot-plugin-contract-core/src

这条桥接路径只作为开发态回退，不再是正式 CI / release 的 canonical 依赖方式。

CI / 发布

• 仓库 CI 会执行：
  • pytest
  • wheel-only 构建
  • Docker builder 镜像构建 smoke test
• tag push v* 会额外执行：
  • tag == project.version 校验
  • PyPI 发布
  • GHCR builder 镜像发布
  • GitHub Release 附件上传
• 可复用 workflow release-plugin.yml 用于单插件仓库正式发版，固定执行：
  • tag == manifest.plugin_version 校验
  • build
  • sigstore sign 并把 META-INF/sigstore.bundle.json 回填到正式 bundle
  • inspect
  • verify
  • validate --mode target-profile
  • 可复现性 smoke check
  • bundle 产物上传 / Release asset 发布

说明：

• validate --mode same-profile 只用于“当前执行环境必须与 bundle runtime profile 一致”的场景，例如单插件仓库 PR/分支校验。
• 正式 release matrix 允许在单一 runner 上构建多个目标 profile，因此可复用 release workflow 只执行 validate --mode target-profile。
• Linux 环境的本机 runtime profile 归一化为 ...-gnu，避免 glibc / gnu 命名差异导致 same-profile 误报。
• 升级 contract-core 时，应通过显式 bump 提交和 CI / release 验证完成，不在安装或发布时解析 latest，避免可复现 bundle 与回滚结论漂移。

使用方式

python -m tg_bot_plugin_buildkit.cli build --source-dir ./plugin
python -m tg_bot_plugin_buildkit.cli embed-signature --bundle ./dist/plugins/demo/demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg --signature-bundle ./sigstore.bundle.json
python -m tg_bot_plugin_buildkit.cli inspect --bundle ./dist/plugins/demo/demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg
python -m tg_bot_plugin_buildkit.cli verify --bundle ./dist/plugins/demo/demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg
python -m tg_bot_plugin_buildkit.cli validate --mode same-profile --bundle ./dist/plugins/demo/demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg
python -m tg_bot_plugin_buildkit.cli install-local --bundle ./dist/plugins/demo/demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg --plugin-root ./plugins --dev-unsigned

build 默认会排除 Git/CI/测试/虚拟环境与 dist 等仓库控制或生成目录，避免把仓库元数据和旧 bundle 再次打进新的 .tgpkg。当 externalize 文件存在时，buildkit 会先校验 plugin_id 与 entrypoint 是否和 manifest.json 一致，再把 capabilities[] 投影到 interaction_schema.capabilities 与 declared_capabilities。

inspect / verify 现在会额外输出两组摘要，方便作者直接核对 Gate A 合同链而不是手工解压 bundle：

• capability_summary
  • 汇总 allowed_surfaces
  • 汇总 telegram_private_menu_button 的 commands_bridge / web_app_bridge
  • 汇总 requires_managed_webapp_auth_context=true 的 capability
• manifest_contract_summary
  • 汇总 declared_default_scope_matrix 的 scope 与 access
  • 汇总 feature_catalog 的 feature id / surface ref
  • 汇总 user_web_entries 的 entry id / landing entry / required_features
  • 汇总 platform_contract 的 resource slot / dependency / lifecycle 摘要

同时，inspect / verify 的 JSON 还会直接回显 declared_default_scope_matrix、feature_catalog、user_web_entries、platform_contract 这四个正式 manifest 字段，便于作者确认 bundle 校验口径与模板真源一致。