tg-bot-plugin-buildkit 0.1.0__tar.gz

tg_bot_plugin_buildkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout buildkit
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]" build
+
+      - name: Run unit tests
+        run: |
+          python -m pytest -q
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Docker build smoke test
+        run: |
+          docker build -t tg-bot-plugin-buildkit:ci .

tg_bot_plugin_buildkit-0.1.0/.github/workflows/release-plugin.yml

@@ -0,0 +1,170 @@
+name: release-plugin
+
+on:
+  workflow_call:
+    inputs:
+      allow_unsigned_dev:
+        required: false
+        type: boolean
+        default: false
+      create_github_release:
+        required: false
+        type: boolean
+        default: true
+      python_version:
+        required: false
+        type: string
+        default: "3.13"
+      runtime_profile_id:
+        required: true
+        type: string
+      source_dir:
+        required: false
+        type: string
+        default: "."
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ inputs.python_version }}"
+
+      - name: Install buildkit
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tg-bot-plugin-buildkit tg-bot-plugin-contract-core
+
+      - name: Validate manifest version against tag
+        if: github.ref_type == 'tag'
+        env:
+          SOURCE_DIR: ${{ inputs.source_dir }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          source_dir = Path(os.environ["SOURCE_DIR"]).expanduser().resolve()
+          manifest_path = source_dir / "manifest.json"
+          if not manifest_path.is_file():
+              raise SystemExit(f"missing manifest.json: {manifest_path}")
+          manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+          plugin_version = str(manifest.get("plugin_version", "")).strip()
+          if plugin_version == "":
+              raise SystemExit("manifest.plugin_version must not be empty")
+          tag_name = str(os.environ.get("GITHUB_REF_NAME", "")).strip()
+          expected_tag = f"v{plugin_version}"
+          if tag_name != expected_tag:
+              raise SystemExit(
+                  f"release tag mismatch: tag={tag_name}, manifest.plugin_version={plugin_version}",
+              )
+          print(f"release tag matches manifest.plugin_version: {plugin_version}")
+          PY
+
+      - name: Build bundle
+        id: build_bundle
+        run: |
+          build_json="$(mktemp)"
+          tg-bot-plugin-buildkit build \
+            --source-dir "${{ inputs.source_dir }}" \
+            --runtime-profile-id "${{ inputs.runtime_profile_id }}" \
+            > "${build_json}"
+          cat "${build_json}"
+          python - "${build_json}" <<'PY' >> "$GITHUB_OUTPUT"
+          import json
+          from pathlib import Path
+          import sys
+
+          payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+          bundle_path = Path(payload["bundle_path"]).resolve()
+          print(f"bundle_path={bundle_path}")
+          print(f"bundle_name={bundle_path.name}")
+          print(f"package_sha256={payload['package_sha256']}")
+          print(f"plugin_version={payload['plugin_version']}")
+          PY
+
+      - name: Inspect bundle
+        run: |
+          tg-bot-plugin-buildkit inspect --bundle "${{ steps.build_bundle.outputs.bundle_path }}"
+
+      - name: Verify bundle
+        run: |
+          args=()
+          if [ "${{ inputs.allow_unsigned_dev }}" = "true" ]; then
+            args+=(--allow-unsigned-dev)
+          fi
+          tg-bot-plugin-buildkit verify \
+            --bundle "${{ steps.build_bundle.outputs.bundle_path }}" \
+            "${args[@]}"
+
+      - name: Validate same-profile bundle
+        run: |
+          args=()
+          if [ "${{ inputs.allow_unsigned_dev }}" = "true" ]; then
+            args+=(--allow-unsigned-dev)
+          fi
+          tg-bot-plugin-buildkit validate \
+            --mode same-profile \
+            --bundle "${{ steps.build_bundle.outputs.bundle_path }}" \
+            "${args[@]}"
+
+      - name: Validate target-profile bundle
+        run: |
+          args=()
+          if [ "${{ inputs.allow_unsigned_dev }}" = "true" ]; then
+            args+=(--allow-unsigned-dev)
+          fi
+          tg-bot-plugin-buildkit validate \
+            --mode target-profile \
+            --bundle "${{ steps.build_bundle.outputs.bundle_path }}" \
+            --target-runtime-profile-id "${{ inputs.runtime_profile_id }}" \
+            "${args[@]}"
+
+      - name: Reproducibility smoke check
+        run: |
+          repro_root="$(mktemp -d)"
+          tg-bot-plugin-buildkit build \
+            --source-dir "${{ inputs.source_dir }}" \
+            --output-dir "${repro_root}/first" \
+            --runtime-profile-id "${{ inputs.runtime_profile_id }}" \
+            > "${repro_root}/first.json"
+          tg-bot-plugin-buildkit build \
+            --source-dir "${{ inputs.source_dir }}" \
+            --output-dir "${repro_root}/second" \
+            --runtime-profile-id "${{ inputs.runtime_profile_id }}" \
+            > "${repro_root}/second.json"
+          python - "${repro_root}/first.json" "${repro_root}/second.json" <<'PY'
+          import json
+          from pathlib import Path
+          import sys
+
+          first = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+          second = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
+          if first["package_sha256"] != second["package_sha256"]:
+              raise SystemExit(
+                  "reproducibility smoke check failed: package_sha256 mismatch "
+                  f"{first['package_sha256']} != {second['package_sha256']}",
+              )
+          print(f"reproducibility smoke check passed: {first['package_sha256']}")
+          PY
+
+      - name: Upload bundle artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: plugin-bundle-${{ inputs.runtime_profile_id }}
+          path: ${{ steps.build_bundle.outputs.bundle_path }}
+
+      - name: Publish GitHub Release asset
+        if: github.ref_type == 'tag' && inputs.create_github_release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ steps.build_bundle.outputs.bundle_path }}

tg_bot_plugin_buildkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout buildkit
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]" build
+
+      - name: Validate tag and version
+        run: |
+          python scripts/check_release_tag.py --tag "${{ github.ref_name }}"
+
+      - name: Run unit tests
+        run: |
+          python -m pytest -q
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: tg-bot-plugin-buildkit-dist
+          path: dist/*
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: docker_meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/tg-bot-plugin-buildkit
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest
+
+      - name: Publish builder image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.docker_meta.outputs.tags }}
+          labels: ${{ steps.docker_meta.outputs.labels }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tg_bot_plugin_buildkit-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+.pytest_cache/
+__pycache__/
+dist/
+*.pyc

tg_bot_plugin_buildkit-0.1.0/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.13-slim
+
+WORKDIR /workspace
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN python -m pip install --upgrade pip && \
+    python -m pip install .
+
+ENTRYPOINT ["tg-bot-plugin-buildkit"]

tg_bot_plugin_buildkit-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: tg-bot-plugin-buildkit
+Version: 0.1.0
+Summary: 基于共享合同核心构建并校验 TG-BOT 插件 bundle。
+Author: Fire Dragons
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: tg-bot-plugin-contract-core==0.1.1
+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-contract-core` 包，并提供：
+
+- `build`
+- `inspect`
+- `verify`
+- `validate --mode same-profile`
+- `validate --mode target-profile`
+- `benchmark`
+- `install-local --dev-unsigned`
+
+## 本地开发
+
+该包的正式发布形态固定依赖已发布的 `tg-bot-plugin-contract-core==0.1.1`。
+
+如果需要在未发布改动上进行本地多仓联调，CLI 仍可通过以下环境变量解析兄弟仓源码：
+
+- `TG_BOT_PLUGIN_CONTRACT_CORE_SRC=/path/to/tg-bot-plugin-contract-core/src`
+
+这条桥接路径只作为开发态回退，不再是正式 CI / release 的 canonical 依赖方式。
+
+## CI / 发布
+
+- 仓库 CI 会执行：
+  - `pytest`
+  - wheel / sdist 构建
+  - Docker builder 镜像构建 smoke test
+- `tag push v*` 会额外执行：
+  - `tag == project.version` 校验
+  - PyPI 发布
+  - GHCR builder 镜像发布
+  - GitHub Release 附件上传
+- 可复用 workflow `release-plugin.yml` 用于单插件仓库正式发版，固定执行：
+  - `tag == manifest.plugin_version` 校验
+  - `build`
+  - `inspect`
+  - `verify`
+  - `validate --mode same-profile`
+  - `validate --mode target-profile`
+  - 可复现性 smoke check
+  - bundle 产物上传 / Release asset 发布
+
+## 使用方式
+
+```bash
+python -m tg_bot_plugin_buildkit.cli build --source-dir ./plugin
+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`。

tg_bot_plugin_buildkit-0.1.0/README.md

@@ -0,0 +1,56 @@
+# tg-bot-plugin-buildkit
+
+`tg-bot-plugin-buildkit` 是面向 TG-BOT 单插件仓库的可复用构建与校验 CLI。
+
+它封装共享 `tg-bot-plugin-contract-core` 包，并提供：
+
+- `build`
+- `inspect`
+- `verify`
+- `validate --mode same-profile`
+- `validate --mode target-profile`
+- `benchmark`
+- `install-local --dev-unsigned`
+
+## 本地开发
+
+该包的正式发布形态固定依赖已发布的 `tg-bot-plugin-contract-core==0.1.1`。
+
+如果需要在未发布改动上进行本地多仓联调，CLI 仍可通过以下环境变量解析兄弟仓源码：
+
+- `TG_BOT_PLUGIN_CONTRACT_CORE_SRC=/path/to/tg-bot-plugin-contract-core/src`
+
+这条桥接路径只作为开发态回退，不再是正式 CI / release 的 canonical 依赖方式。
+
+## CI / 发布
+
+- 仓库 CI 会执行：
+  - `pytest`
+  - wheel / sdist 构建
+  - Docker builder 镜像构建 smoke test
+- `tag push v*` 会额外执行：
+  - `tag == project.version` 校验
+  - PyPI 发布
+  - GHCR builder 镜像发布
+  - GitHub Release 附件上传
+- 可复用 workflow `release-plugin.yml` 用于单插件仓库正式发版，固定执行：
+  - `tag == manifest.plugin_version` 校验
+  - `build`
+  - `inspect`
+  - `verify`
+  - `validate --mode same-profile`
+  - `validate --mode target-profile`
+  - 可复现性 smoke check
+  - bundle 产物上传 / Release asset 发布
+
+## 使用方式
+
+```bash
+python -m tg_bot_plugin_buildkit.cli build --source-dir ./plugin
+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`。

tg_bot_plugin_buildkit-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tg-bot-plugin-buildkit"
+version = "0.1.0"
+description = "基于共享合同核心构建并校验 TG-BOT 插件 bundle。"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Fire Dragons" },
+]
+dependencies = [
+  "tg-bot-plugin-contract-core==0.1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0",
+]
+
+[project.scripts]
+tg-bot-plugin-buildkit = "tg_bot_plugin_buildkit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tg_bot_plugin_buildkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tg_bot_plugin_buildkit-0.1.0/scripts/check_release_tag.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""校验 Git tag 与 pyproject 中的项目版本一致。"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+import tomllib
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="校验 release tag 与项目版本是否一致。")
+    parser.add_argument("--tag", required=True, help="例如 v0.1.0")
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="包含 pyproject.toml 的项目根目录。",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = _parse_args()
+    project_root = Path(args.project_root).expanduser().resolve()
+    pyproject_path = project_root / "pyproject.toml"
+    tag = str(args.tag or "").strip()
+    if not pyproject_path.is_file():
+        print(f"missing pyproject.toml: {pyproject_path}", file=sys.stderr)
+        return 1
+    if not tag.startswith("v"):
+        print(f"release tag must start with 'v': {tag}", file=sys.stderr)
+        return 1
+
+    payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    project_version = str(payload.get("project", {}).get("version", "")).strip()
+    tag_version = tag[1:]
+    if project_version == "":
+        print("project.version is missing in pyproject.toml", file=sys.stderr)
+        return 1
+    if project_version != tag_version:
+        print(
+            f"release tag mismatch: tag={tag_version}, project.version={project_version}",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"release tag matches project version: {project_version}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tg_bot_plugin_buildkit-0.1.0/src/tg_bot_plugin_buildkit/__init__.py

@@ -0,0 +1,19 @@
+"""TG-BOT 插件 bundle 的可复用构建工具集。"""
+
+from .buildkit import (
+    benchmark_bundle,
+    build_bundle,
+    inspect_bundle,
+    install_local_bundle,
+    validate_bundle,
+    verify_bundle,
+)
+
+__all__ = [
+    "benchmark_bundle",
+    "build_bundle",
+    "inspect_bundle",
+    "install_local_bundle",
+    "validate_bundle",
+    "verify_bundle",
+]

tg_bot_plugin_buildkit-0.1.0/src/tg_bot_plugin_buildkit/buildkit.py

@@ -0,0 +1,307 @@
+"""构建在共享合同核心之上的高层 buildkit 操作。"""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from .core_adapter import (
+    compute_artifact_digest,
+    compute_package_sha256,
+    inspect_bundle as shared_inspect_bundle,
+    normalize_manifest_payload,
+    validate_bundle_same_profile,
+    validate_bundle_target_profile,
+    verify_bundle as shared_verify_bundle,
+    write_reproducible_bundle,
+)
+
+MANIFEST_FILE_NAME = "manifest.json"
+SUPPORTED_BUNDLE_SUFFIX = ".tgpkg"
+_BUNDLE_EXCLUDED_DIRECTORY_NAMES = {
+    ".git",
+    ".hg",
+    ".idea",
+    ".mypy_cache",
+    ".nox",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pycache__",
+    "node_modules",
+}
+_BUNDLE_EXCLUDED_TOP_LEVEL_NAMES = {
+    "build",
+    "dist",
+    "docs",
+    "scripts",
+    "tests",
+}
+_BUNDLE_EXCLUDED_TOP_LEVEL_FILE_NAMES = {
+    ".gitignore",
+    ".python-version",
+    "Makefile",
+    "README",
+    "README.md",
+    "poetry.lock",
+    "pyproject.toml",
+    "uv.lock",
+}
+_BUNDLE_EXCLUDED_FILE_SUFFIXES = {
+    ".pyc",
+    SUPPORTED_BUNDLE_SUFFIX,
+}
+
+
+def _stable_json(payload: Any) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
+def build_runtime_profile_id() -> str:
+    implementation = platform.python_implementation().lower()
+    version = f"{platform.python_version_tuple()[0]}.{platform.python_version_tuple()[1]}"
+    system_name = platform.system().lower()
+    machine_name = platform.machine().lower().replace("/", "_")
+    libc_name, _libc_version = platform.libc_ver()
+    abi = libc_name.lower() if libc_name else ("darwin" if system_name == "darwin" else "unknown")
+    return "-".join((implementation, version, system_name, machine_name, abi))
+
+
+def _read_manifest_payload(source_dir: Path) -> dict[str, Any]:
+    manifest_path = source_dir / MANIFEST_FILE_NAME
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("manifest root must be an object")
+    return payload
+
+
+def _write_manifest_payload(source_dir: Path, payload: dict[str, Any]) -> None:
+    (source_dir / MANIFEST_FILE_NAME).write_text(_stable_json(payload), encoding="utf-8")
+
+
+def _output_bundle_path(output_dir: Path, *, plugin_id: str, plugin_version: str, runtime_profile_id: str) -> Path:
+    return output_dir / plugin_id / f"{plugin_id}-{plugin_version}-{runtime_profile_id}{SUPPORTED_BUNDLE_SUFFIX}"
+
+
+def _output_roots_to_ignore(source_dir: Path, output_dir: Path) -> set[str]:
+    try:
+        relpath = output_dir.relative_to(source_dir)
+    except ValueError:
+        return set()
+    if not relpath.parts:
+        return set()
+    return {relpath.parts[0]}
+
+
+def _should_exclude_bundle_source(path: Path, source_dir: Path, extra_top_level_names: set[str]) -> bool:
+    relpath = path.relative_to(source_dir)
+    if not relpath.parts:
+        return False
+
+    first_part = relpath.parts[0]
+    if first_part in extra_top_level_names:
+        return True
+    if first_part.startswith(".") and first_part != "META-INF":
+        return True
+    if any(part in _BUNDLE_EXCLUDED_DIRECTORY_NAMES for part in relpath.parts):
+        return True
+    if first_part in _BUNDLE_EXCLUDED_TOP_LEVEL_NAMES:
+        return True
+    if len(relpath.parts) == 1 and path.name in _BUNDLE_EXCLUDED_TOP_LEVEL_FILE_NAMES:
+        return True
+    if path.is_file() and path.suffix in _BUNDLE_EXCLUDED_FILE_SUFFIXES:
+        return True
+    return False
+
+
+def _build_copy_ignore(source_dir: Path, output_dir: Path):
+    extra_top_level_names = _output_roots_to_ignore(source_dir, output_dir)
+
+    def _ignore(current_dir: str, names: list[str]) -> list[str]:
+        current_path = Path(current_dir)
+        ignored: list[str] = []
+        for name in names:
+            candidate = current_path / name
+            if _should_exclude_bundle_source(candidate, source_dir, extra_top_level_names):
+                ignored.append(name)
+        return ignored
+
+    return _ignore
+
+
+def build_bundle(
+    *,
+    source_dir: str | Path,
+    output_dir: str | Path | None = None,
+    runtime_profile_id: str = "",
+) -> dict[str, Any]:
+    resolved_source_dir = Path(source_dir).expanduser().resolve()
+    resolved_output_dir = (
+        Path(output_dir).expanduser().resolve()
+        if output_dir
+        else (resolved_source_dir / "dist" / "plugins").resolve()
+    )
+    manifest_payload = _read_manifest_payload(resolved_source_dir)
+    effective_runtime_profile_id = str(runtime_profile_id or "").strip() or build_runtime_profile_id()
+    manifest_payload["runtime_profile_id"] = effective_runtime_profile_id
+    manifest_payload["artifact_digest"] = ""
+    manifest = normalize_manifest_payload(manifest_payload, require_artifact_digest=False)
+
+    with tempfile.TemporaryDirectory(prefix=f"tg-bot-buildkit-{manifest.plugin_id}-") as temp_dir_str:
+        staging_dir = Path(temp_dir_str) / manifest.plugin_id
+        shutil.copytree(
+            resolved_source_dir,
+            staging_dir,
+            ignore=_build_copy_ignore(resolved_source_dir, resolved_output_dir),
+        )
+        _write_manifest_payload(staging_dir, manifest.raw)
+        artifact_digest = compute_artifact_digest(staging_dir, manifest.raw)
+        manifest_payload = dict(manifest.raw)
+        manifest_payload["artifact_digest"] = artifact_digest
+        _write_manifest_payload(staging_dir, manifest_payload)
+        bundle_path = _output_bundle_path(
+            resolved_output_dir,
+            plugin_id=manifest.plugin_id,
+            plugin_version=manifest.plugin_version,
+            runtime_profile_id=effective_runtime_profile_id,
+        )
+        bundle_path.parent.mkdir(parents=True, exist_ok=True)
+        write_reproducible_bundle(staging_dir, bundle_path)
+
+    return {
+        "build_status": "ok",
+        "plugin_id": manifest.plugin_id,
+        "plugin_version": manifest.plugin_version,
+        "runtime_profile_id": effective_runtime_profile_id,
+        "artifact_digest": artifact_digest,
+        "package_sha256": compute_package_sha256(bundle_path),
+        "bundle_path": str(bundle_path),
+    }
+
+
+def inspect_bundle(bundle_path: str | Path) -> dict[str, Any]:
+    inspection = shared_inspect_bundle(bundle_path)
+    return {
+        "inspect_status": "ok",
+        "plugin_id": inspection.plugin_id,
+        "plugin_version": inspection.plugin_version,
+        "runtime_profile_id": inspection.runtime_profile_id,
+        "artifact_digest": inspection.artifact_digest,
+        "package_sha256": inspection.package_sha256,
+        "entrypoint": inspection.manifest.entrypoint,
+        "bundle_path": str(inspection.bundle_path),
+    }
+
+
+def verify_bundle(bundle_path: str | Path, *, allow_unsigned_dev: bool = False) -> dict[str, Any]:
+    verification = shared_verify_bundle(bundle_path, allow_unsigned_dev=allow_unsigned_dev)
+    signer_identity = ""
+    if verification.signer_identity is not None:
+        signer_identity = verification.signer_identity.persistent_value()
+    return {
+        "verify_status": "ok",
+        "plugin_id": verification.plugin_id,
+        "plugin_version": verification.plugin_version,
+        "runtime_profile_id": verification.runtime_profile_id,
+        "artifact_digest": verification.artifact_digest,
+        "package_sha256": verification.package_sha256,
+        "signature_verification_status": verification.signature_verification_status,
+        "signer_identity": signer_identity,
+        "bundle_path": str(Path(bundle_path).expanduser().resolve()),
+    }
+
+
+def validate_bundle(
+    bundle_path: str | Path,
+    *,
+    mode: str,
+    target_runtime_profile_id: str = "",
+    allow_unsigned_dev: bool = False,
+) -> dict[str, Any]:
+    resolved_bundle_path = Path(bundle_path).expanduser().resolve()
+    if mode == "same-profile":
+        verification = validate_bundle_same_profile(
+            resolved_bundle_path,
+            runtime_profile_id=build_runtime_profile_id(),
+            allow_unsigned_dev=allow_unsigned_dev,
+        )
+    elif mode == "target-profile":
+        verification = validate_bundle_target_profile(
+            resolved_bundle_path,
+            target_runtime_profile_id=str(target_runtime_profile_id or "").strip(),
+            allow_unsigned_dev=allow_unsigned_dev,
+        )
+    else:
+        raise ValueError(f"unsupported validate mode: {mode}")
+    return {
+        "validate_status": "ok",
+        "mode": mode,
+        "plugin_id": verification.plugin_id,
+        "plugin_version": verification.plugin_version,
+        "runtime_profile_id": verification.runtime_profile_id,
+        "artifact_digest": verification.artifact_digest,
+        "package_sha256": verification.package_sha256,
+        "signature_verification_status": verification.signature_verification_status,
+        "bundle_path": str(resolved_bundle_path),
+    }
+
+
+def install_local_bundle(
+    *,
+    bundle_path: str | Path,
+    plugin_root: str | Path,
+    dev_unsigned: bool,
+) -> dict[str, Any]:
+    resolved_bundle_path = Path(bundle_path).expanduser().resolve()
+    resolved_plugin_root = Path(plugin_root).expanduser().resolve()
+    verification = shared_verify_bundle(resolved_bundle_path, allow_unsigned_dev=dev_unsigned)
+    target_dir = resolved_plugin_root / verification.plugin_id
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target_bundle_path = target_dir / f"{verification.plugin_id}{SUPPORTED_BUNDLE_SUFFIX}"
+    temp_bundle_path = target_bundle_path.with_suffix(f"{target_bundle_path.suffix}.tmp")
+    shutil.copy2(resolved_bundle_path, temp_bundle_path)
+    temp_bundle_path.replace(target_bundle_path)
+    return {
+        "install_status": "ok",
+        "plugin_id": verification.plugin_id,
+        "plugin_version": verification.plugin_version,
+        "package_sha256": verification.package_sha256,
+        "signature_verification_status": verification.signature_verification_status,
+        "installed_bundle": str(target_bundle_path),
+    }
+
+
+def benchmark_bundle(
+    *,
+    source_dir: str | Path,
+    output_dir: str | Path | None = None,
+    runtime_profile_id: str = "",
+) -> dict[str, Any]:
+    started_at = time.perf_counter()
+    build_result = build_bundle(
+        source_dir=source_dir,
+        output_dir=output_dir,
+        runtime_profile_id=runtime_profile_id,
+    )
+    build_duration_ms = round((time.perf_counter() - started_at) * 1000, 3)
+    bundle_path = Path(build_result["bundle_path"])
+    inspect_result = inspect_bundle(bundle_path)
+    return {
+        "benchmark_status": "ok",
+        "build_duration_ms": build_duration_ms,
+        "bundle_size_bytes": bundle_path.stat().st_size,
+        "plugin_id": build_result["plugin_id"],
+        "plugin_version": build_result["plugin_version"],
+        "runtime_profile_id": build_result["runtime_profile_id"],
+        "artifact_digest": inspect_result["artifact_digest"],
+        "package_sha256": inspect_result["package_sha256"],
+        "bundle_path": str(bundle_path),
+    }

tg_bot_plugin_buildkit-0.1.0/src/tg_bot_plugin_buildkit/cli.py

@@ -0,0 +1,104 @@
+"""tg-bot-plugin-buildkit 的命令行入口。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .buildkit import (
+    benchmark_bundle,
+    build_bundle,
+    inspect_bundle,
+    install_local_bundle,
+    validate_bundle,
+    verify_bundle,
+)
+
+
+def _stable_json(payload: dict[str, object]) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="构建并校验 TG-BOT 插件 bundle。")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    build_parser = subparsers.add_parser("build", help="构建可复现的 .tgpkg bundle。")
+    build_parser.add_argument("--source-dir", required=True, help="插件源码目录。")
+    build_parser.add_argument("--output-dir", default="", help="生成 bundle 的输出根目录。")
+    build_parser.add_argument("--runtime-profile-id", default="", help="覆盖 runtime profile id。")
+
+    inspect_parser = subparsers.add_parser("inspect", help="检查 bundle 合同完整性。")
+    inspect_parser.add_argument("--bundle", required=True, help=".tgpkg bundle 路径。")
+
+    verify_parser = subparsers.add_parser("verify", help="校验 bundle 签名材料。")
+    verify_parser.add_argument("--bundle", required=True, help=".tgpkg bundle 路径。")
+    verify_parser.add_argument(
+        "--allow-unsigned-dev",
+        action="store_true",
+        help="允许未签名的开发态 bundle。",
+    )
+
+    validate_parser = subparsers.add_parser("validate", help="按 runtime profile 校验 bundle。")
+    validate_parser.add_argument("--bundle", required=True, help=".tgpkg bundle 路径。")
+    validate_parser.add_argument("--mode", required=True, choices=("same-profile", "target-profile"))
+    validate_parser.add_argument("--target-runtime-profile-id", default="", help="target-profile 模式必填。")
+    validate_parser.add_argument("--allow-unsigned-dev", action="store_true")
+
+    benchmark_parser = subparsers.add_parser("benchmark", help="执行一次本地构建基准测试。")
+    benchmark_parser.add_argument("--source-dir", required=True, help="插件源码目录。")
+    benchmark_parser.add_argument("--output-dir", default="", help="生成 bundle 的输出根目录。")
+    benchmark_parser.add_argument("--runtime-profile-id", default="", help="覆盖 runtime profile id。")
+
+    install_parser = subparsers.add_parser("install-local", help="将 bundle 复制到本地插件根目录。")
+    install_parser.add_argument("--bundle", required=True, help=".tgpkg bundle 路径。")
+    install_parser.add_argument("--plugin-root", required=True, help="目标 TG_BOT_PLUGIN_ROOT 风格目录。")
+    install_parser.add_argument("--dev-unsigned", action="store_true", help="允许未签名的开发态 bundle。")
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = _parse_args()
+    try:
+        if args.command == "build":
+            payload = build_bundle(
+                source_dir=args.source_dir,
+                output_dir=args.output_dir,
+                runtime_profile_id=args.runtime_profile_id,
+            )
+        elif args.command == "inspect":
+            payload = inspect_bundle(args.bundle)
+        elif args.command == "verify":
+            payload = verify_bundle(args.bundle, allow_unsigned_dev=bool(args.allow_unsigned_dev))
+        elif args.command == "validate":
+            payload = validate_bundle(
+                args.bundle,
+                mode=args.mode,
+                target_runtime_profile_id=args.target_runtime_profile_id,
+                allow_unsigned_dev=bool(args.allow_unsigned_dev),
+            )
+        elif args.command == "benchmark":
+            payload = benchmark_bundle(
+                source_dir=args.source_dir,
+                output_dir=args.output_dir,
+                runtime_profile_id=args.runtime_profile_id,
+            )
+        elif args.command == "install-local":
+            payload = install_local_bundle(
+                bundle_path=args.bundle,
+                plugin_root=args.plugin_root,
+                dev_unsigned=bool(args.dev_unsigned),
+            )
+        else:
+            raise ValueError(f"unsupported command: {args.command}")
+    except Exception as exc:
+        print(_stable_json({"status": "error", "message": str(exc)}), end="")
+        return 1
+    print(_stable_json({"status": "ok", **payload}), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tg_bot_plugin_buildkit-0.1.0/src/tg_bot_plugin_buildkit/core_adapter.py

@@ -0,0 +1,60 @@
+"""面向 tg-bot-plugin-contract-core 的本地适配层。"""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib import import_module
+from pathlib import Path
+
+
+def _candidate_src_paths() -> list[Path]:
+    candidates: list[Path] = []
+    env_path = str(os.getenv("TG_BOT_PLUGIN_CONTRACT_CORE_SRC") or "").strip()
+    if env_path:
+        candidates.append(Path(env_path).expanduser())
+    sibling = Path(__file__).resolve().parents[3] / "tg-bot-plugin-contract-core" / "src"
+    candidates.append(sibling)
+    deduped: list[Path] = []
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved not in deduped:
+            deduped.append(resolved)
+    return deduped
+
+
+def _load_contract_core():
+    try:
+        public_module = import_module("tg_bot_plugin_contract_core")
+        core_module = import_module("tg_bot_plugin_contract_core.core")
+        return public_module, core_module
+    except ImportError:
+        for candidate in _candidate_src_paths():
+            if not candidate.is_dir():
+                continue
+            candidate_str = str(candidate)
+            if candidate_str not in sys.path:
+                sys.path.insert(0, candidate_str)
+            try:
+                public_module = import_module("tg_bot_plugin_contract_core")
+                core_module = import_module("tg_bot_plugin_contract_core.core")
+                return public_module, core_module
+            except ImportError:
+                continue
+    raise ImportError(
+        "tg_bot_plugin_contract_core is not importable; install the package or set "
+        "TG_BOT_PLUGIN_CONTRACT_CORE_SRC to the package src directory",
+    )
+
+
+_PUBLIC_MODULE, _CORE_MODULE = _load_contract_core()
+
+ContractCoreError = _PUBLIC_MODULE.ContractCoreError
+compute_artifact_digest = _PUBLIC_MODULE.compute_artifact_digest
+compute_package_sha256 = _PUBLIC_MODULE.compute_package_sha256
+inspect_bundle = _PUBLIC_MODULE.inspect_bundle
+validate_bundle_same_profile = _PUBLIC_MODULE.validate_bundle_same_profile
+validate_bundle_target_profile = _PUBLIC_MODULE.validate_bundle_target_profile
+verify_bundle = _PUBLIC_MODULE.verify_bundle
+write_reproducible_bundle = _PUBLIC_MODULE.write_reproducible_bundle
+normalize_manifest_payload = _CORE_MODULE._normalize_manifest_payload

tg_bot_plugin_buildkit-0.1.0/tests/test_buildkit.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import zipfile
+
+from tg_bot_plugin_buildkit.buildkit import (
+    benchmark_bundle,
+    build_bundle,
+    inspect_bundle,
+    install_local_bundle,
+)
+
+
+def _write_manifest(source_dir: Path, *, runtime_profile_id: str = "") -> None:
+    payload = {
+        "plugin_id": "demo",
+        "plugin_version": "1.2.3",
+        "name": "demo",
+        "description": "demo plugin",
+        "category": "utility",
+        "runtime_profile_id": runtime_profile_id,
+        "artifact_digest": "",
+        "entrypoint": {"module_path": "__init__", "symbol": "DemoPlugin"},
+        "config_schema": {},
+        "interaction_schema": {},
+        "declared_scopes": [],
+        "declared_capabilities": [],
+    }
+    (source_dir / "manifest.json").write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _make_plugin_source(tmp_path: Path) -> Path:
+    source_dir = tmp_path / "plugin"
+    source_dir.mkdir(parents=True, exist_ok=True)
+    _write_manifest(source_dir)
+    (source_dir / "__init__.py").write_text("class DemoPlugin:\n    pass\n", encoding="utf-8")
+    (source_dir / "META-INF").mkdir(parents=True, exist_ok=True)
+    return source_dir
+
+
+def test_build_bundle_writes_canonical_filename(tmp_path: Path):
+    source_dir = _make_plugin_source(tmp_path)
+
+    result = build_bundle(
+        source_dir=source_dir,
+        output_dir=tmp_path / "dist" / "plugins",
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+
+    bundle_path = Path(result["bundle_path"])
+    assert bundle_path.name == "demo-1.2.3-cpython-3.13-linux-x86_64-gnu.tgpkg"
+    assert bundle_path.is_file()
+    assert result["package_sha256"]
+
+
+def test_inspect_bundle_round_trips_build_output(tmp_path: Path):
+    source_dir = _make_plugin_source(tmp_path)
+    build_result = build_bundle(
+        source_dir=source_dir,
+        output_dir=tmp_path / "dist" / "plugins",
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+
+    inspect_result = inspect_bundle(build_result["bundle_path"])
+
+    assert inspect_result["plugin_id"] == "demo"
+    assert inspect_result["plugin_version"] == "1.2.3"
+    assert inspect_result["package_sha256"] == build_result["package_sha256"]
+
+
+def test_install_local_bundle_supports_dev_unsigned(tmp_path: Path):
+    source_dir = _make_plugin_source(tmp_path)
+    build_result = build_bundle(
+        source_dir=source_dir,
+        output_dir=tmp_path / "dist" / "plugins",
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+    plugin_root = tmp_path / "plugins"
+
+    install_result = install_local_bundle(
+        bundle_path=build_result["bundle_path"],
+        plugin_root=plugin_root,
+        dev_unsigned=True,
+    )
+
+    assert install_result["install_status"] == "ok"
+    assert (plugin_root / "demo" / "demo.tgpkg").is_file()
+
+
+def test_benchmark_bundle_reports_size_and_duration(tmp_path: Path):
+    source_dir = _make_plugin_source(tmp_path)
+
+    result = benchmark_bundle(
+        source_dir=source_dir,
+        output_dir=tmp_path / "dist" / "plugins",
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+
+    assert result["benchmark_status"] == "ok"
+    assert result["bundle_size_bytes"] > 0
+    assert result["build_duration_ms"] >= 0
+
+
+def test_build_bundle_excludes_repo_metadata_and_default_dist(tmp_path: Path):
+    source_dir = _make_plugin_source(tmp_path)
+    (source_dir / ".git").mkdir(parents=True, exist_ok=True)
+    (source_dir / ".git" / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
+    (source_dir / ".github" / "workflows").mkdir(parents=True, exist_ok=True)
+    (source_dir / ".github" / "workflows" / "ci.yml").write_text("name: ci\n", encoding="utf-8")
+    (source_dir / ".venv" / "bin").mkdir(parents=True, exist_ok=True)
+    (source_dir / ".venv" / "bin" / "python").write_text("#!/usr/bin/env python3\n", encoding="utf-8")
+    (source_dir / "tests").mkdir(parents=True, exist_ok=True)
+    (source_dir / "tests" / "test_demo.py").write_text("def test_demo():\n    assert True\n", encoding="utf-8")
+    (source_dir / "scripts").mkdir(parents=True, exist_ok=True)
+    (source_dir / "scripts" / "helper.py").write_text("print('helper')\n", encoding="utf-8")
+    (source_dir / "README.md").write_text("# demo\n", encoding="utf-8")
+    (source_dir / "pyproject.toml").write_text("[project]\nname = 'demo'\n", encoding="utf-8")
+
+    first = build_bundle(
+        source_dir=source_dir,
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+    second = build_bundle(
+        source_dir=source_dir,
+        runtime_profile_id="cpython-3.13-linux-x86_64-gnu",
+    )
+
+    assert first["package_sha256"] == second["package_sha256"]
+    with zipfile.ZipFile(first["bundle_path"]) as archive:
+        members = set(archive.namelist())
+
+    assert "manifest.json" in members
+    assert "__init__.py" in members
+    assert all(not member.startswith(".git/") for member in members)
+    assert all(not member.startswith(".github/") for member in members)
+    assert all(not member.startswith(".venv/") for member in members)
+    assert all(not member.startswith("dist/") for member in members)
+    assert all(not member.startswith("scripts/") for member in members)
+    assert all(not member.startswith("tests/") for member in members)
+    assert "README.md" not in members
+    assert "pyproject.toml" not in members