Metadata-Version: 2.4
Name: tg-bot-plugin-buildkit
Version: 0.2.0
Summary: 基于共享合同核心构建并校验 TG-BOT 插件 bundle。
Author: Fire Dragons
License: MIT
Requires-Python: >=3.11
Requires-Dist: cython==3.1.6
Requires-Dist: setuptools>=61.0
Requires-Dist: tg-bot-plugin-contract-core==0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# tg-bot-plugin-buildkit

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

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

完整正文：

- [编译打包与验收实战指南](./docs/编译打包与验收实战指南.md)
- [构建、签名、校验与发布指南](./docs/构建签名校验与发布指南.md)
- `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 与回滚结论漂移。

## 使用方式

```bash
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 校验口径与模板真源一致。
